doc: plugin development guide

.gitmodules

@@ -28,3 +28,6 @@
 [submodule "code-repos/zenstackhq/v3-doc-tanstack-query"]
 	path = code-repos/zenstackhq/v3-doc-tanstack-query
 	url = https://github.com/zenstackhq/v3-doc-tanstack-query
+[submodule "code-repos/zenstackhq/v3-doc-plugin"]
+	path = code-repos/zenstackhq/v3-doc-plugin
+	url = https://github.com/zenstackhq/v3-doc-plugin

versioned_docs/version-3.x/modeling/plugin.md

@@ -48,4 +48,6 @@ A plugin can have the following effects to ZModel:
 - It can contribute custom attributes that you can use to annotate models and fields.
 - It can contribute code generation logic that's executed when you run the `zenstack generate` command.
 
-Plugins can also contribute to the ORM runtime behavior, and we'll leave it to the [ORM](../orm/plugins/) part to explain it in detail.
+:::info
+Plugins can also extend ZenStack's CLI and ORM runtime behavior. Please refer to the [Plugin Development](../recipe/plugin-dev.md) documentation for a comprehensive guide.
+:::

versioned_docs/version-3.x/orm/cli.md

@@ -16,3 +16,7 @@ You can try running the `npx zen generate` command in the following playground a
 <StackBlitzGithub repoPath="zenstackhq/v3-doc-quick-start" openFile="zenstack/schema.zmodel" />
 
 The `generate` command generates several TypeScript files from the ZModel schema that support both development-time typing and runtime access to the schema. For more details of the generated code, please refer to the [@core/typescript plugin](../reference/plugins/typescript.md) documentation.
+
+:::info
+The CLI's code generation is extensible via plugins. Please refer to the [Plugin Development](../recipe/plugin-dev.md) documentation for a comprehensive guide.
+:::

versioned_docs/version-3.x/orm/plugins/index.md

@@ -40,3 +40,7 @@ const db = new ZenStackClient({ ... });
 const withPlugin = $db.use({ ... });
 const noPlugin = withPlugin.$unuseAll();
 ```
+
+:::info
+Plugins can also extend the ZModel language and ZenStack's CLI. Please refer to the [Plugin Development](../../recipe/plugin-dev.md) documentation for a comprehensive guide.
+:::

versioned_docs/version-3.x/recipe/plugin-dev.md

@@ -0,0 +1,107 @@
+---
+sidebar_position: 5
+description: Plugin development guide
+---
+
+import StackBlitzGithub from '@site/src/components/StackBlitzGithub';
+import PackageInstall from '../_components/PackageInstall';
+
+# Plugin Development
+
+This guide provides a comprehensive introduction to developing ZenStack plugins, demonstrating how to extend ZenStack’s functionality at the schema, CLI, and runtime levels.
+
+## Extending the schema language
+
+Plugins can contribute new ZModel attributes and functions, and use them to extend the data modeling semantics. To do that, create a folder in your source tree with a `plugin.zmodel` file in it, and define your custom attributes and/or functions in it.
+
+:::tip
+You can also package a plugin as an npm package. Make sure to export the "plugin.zmodel" file in the package's `package.json` file.
+:::
+
+The following example shows a sample plugin that allows you to mark fields as "password" and specify hashing algorithms to use.
+
+<StackBlitzGithub repoPath="zenstackhq/v3-doc-plugin" openFile="zenstack/password-plugin/plugin.zmodel" />
+
+:::info
+Model-level attributes must be prefixed with `@@`, and field-level ones with `@`.
+:::
+
+You need to enable the plugin in your ZModel to use the attributes and functions defined in it:
+
+```zmodel title="schema.zmodel"
+plugin password {
+    provider = './password-plugin'
+}
+
+model User {
+    id Int @id @default(autoincrement())
+    password String @password(hasher: bcryptHasher(10))
+}
+```
+
+## Generating custom artifacts
+
+The `zen` CLI is extensible via plugins and allows you to generate custom artifacts from the ZModel schema. To continue the previous example, let's create a very simple CLI plugin that generates a markdown document listing all model fields marked as passwords.
+
+To implement a plugin, first install the "@zenstackhq/sdk" package that contains type definitions and utilities for working with ZModel AST:
+
+<PackageInstall devDependencies={["@zenstackhq/sdk@next"]} />
+
+A CLI plugin is an ESM module that default-exports an object that contains the following fields:
+
+- `name`: the name of the plugin.
+- `generate`: an async function that's invoked during the `zen generate` command run.
+- `statusText` (optional): text displayed in the CLI during the plugin run.
+
+The implementation looks like the following:
+
+<StackBlitzGithub repoPath="zenstackhq/v3-doc-plugin" openFile="zenstack/password-plugin/index.ts" />
+
+Then, enable the reporting in ZModel with the "report" option:
+
+```zmodel title="schema.zmodel"
+plugin password {
+    provider = './password-plugin'
+    report = true
+}
+```
+
+Finally, run the `zen generate` command to generate the report:
+
+```bash
+npx zen generate
+```
+
+You should see that the custom plugin is run during the generation process, and the markdown file is created in the output folder.
+
+```plain
+% npx zen generate
+✔ Generating TypeScript schema
+✔ Running plugin Password Report
+Generation completed successfully in 116ms.
+```
+
+:::info How does the CLI load plugin modules?
+The CLI attempts to load the plugin module following these steps:
+1. If `provider` is resolvable as a file path (with ".js", ".mjs", ".ts", or ".mts" extensions), load it as a local file.
+2. If `provider` is resolvable as a folder containing an index file (with ".js", ".mjs", ".ts", or ".mts" extensions), load the index file.
+3. Otherwise, load it as an npm package.
+
+Please note that only ESM modules are supported. TypeScript files are loaded via [jiti](https://gi.thub.com/unjs/jiti).
+:::
+
+## Extending the ORM runtime
+
+The most powerful aspect of the plugin system is the ability to extend the ORM runtime behavior. ZenStack's ORM client provides a plugin system that allows you to intercept the ORM query lifecycle at different stages and abstraction levels. Please see the [ORM plugins](../orm/plugins/) documentation for detailed information.
+
+In this section, we'll see how to implement automatic password hashing functionality at runtime using the [Kysely](https://kysely.dev/) query hooks mechanism. The implementation requires an understanding of Kysely's [Operation Node](https://kysely-org.github.io/kysely-apidoc/interfaces/OperationNode.html) concept (which is the SQL AST used by Kysely internally).
+
+:::warning
+The implementation is mostly vibe-coded with Claude Code. Please review carefully before using it in production.
+:::
+
+<StackBlitzGithub repoPath="zenstackhq/v3-doc-plugin" openFile="password-hasher-plugin.ts" />
+
+With the plugin installed on the ORM client, any time you create or update a User record, the password field will be automatically hashed before being stored in the database.
+
+<StackBlitzGithub repoPath="zenstackhq/v3-doc-plugin" openFile="main.ts" />