@synergenius/flow-weaver 0.33.2 → 0.44.0

package/docs/reference/marketplace.md

@@ -1,44 +1,34 @@
 ---
 name: Marketplace
-description: Create, publish, install, and manage Flow Weaver marketplace packages and external plugins
-keywords: [marketplace, market, package, publish, install, search, npm, flow-weaver-pack, plugin, init, manifest, node types, patterns, workflows, component, area, sandbox]
+description: Create, publish, install, and manage Flow Weaver marketplace packages
+keywords: [marketplace, market, package, pack, publish, install, search, npm, flow-weaver-pack, manifest, manifestVersion, node types, workflows, cliEntrypoint, cliCommands, mcpEntrypoint, mcpTools, exportTargets, tagHandlers, serializerExport, validationRuleSets, initContributions, docs, engineVersion, authoring, extend, grammar, custom tags, deploy namespace]
 ---
 
 # Marketplace
 
-The Flow Weaver marketplace is an npm-based ecosystem for sharing reusable node types, workflows, and patterns. Packages follow the `flow-weaver-pack-*` naming convention and are discoverable via npm search.
+The Flow Weaver marketplace is an npm-based ecosystem for sharing reusable node types and workflows. A pack is an npm package that carries a `flowweaver.manifest.json` and the `flow-weaver-marketplace-pack` keyword — that is how one is recognised, installed or on a registry. By convention packs are named `flow-weaver-pack-*` (or `@scope/flow-weaver-pack-*`), which makes them easy to find; a pack named otherwise, as an organisation's policy may require, works the same and is found the same way.
 
 ## Overview
 
-| What | Purpose |
-|------|---------|
-| **Node types** | Reusable `@flowWeaver nodeType` functions |
-| **Workflows** | Complete `@flowWeaver workflow` exports |
-| **Patterns** | Reusable `@flowWeaver pattern` fragments |
-| **Export targets** | Deployment targets for `fw export` |
+| What | Purpose | Declared |
+|------|---------|----------|
+| **Node types** | Reusable `@flowWeaver nodeType` functions | Generated from source |
+| **Workflows** | Complete `@flowWeaver workflow` exports | Generated from source |
+| **Export targets** | Deployment targets for `fw export` | `exportTargets` in the manifest |
+| **Tag handlers** | New JSDoc tags, parsed into a namespace of the workflow's deploy data — see [Extending the grammar](#extending-the-grammar-with-a-pack) | `tagHandlers` |
+| **CLI commands** | `fw <pack> <command>` | `cliEntrypoint` + `cliCommands` |
+| **MCP tools** | Tools added to `fw mcp-server` | `mcpEntrypoint` + `mcpTools` |
+| **Validation rules, docs, init templates** | See [Pack Contributions](#pack-contributions) | `validationRuleSets`, `docs`, `initContributions` |
 
 A single package can contain any combination of these.
 
-## Official Export Target Packs
+`fw console` shows the packs installed in a project and everything each one contributes, exports a workflow through a pack's target, searches the marketplace, and — when the open project is itself a pack — runs the `market pack` validation and shows the manifest it would write. See [Console](console.md).
 
-Flow Weaver provides 6 official export target packs:
+## Export Target Packs
 
-| Package | Target name | Description |
-|---------|-------------|-------------|
-| `@synergenius/flow-weaver-pack-lambda` | `lambda` | AWS Lambda + API Gateway |
-| `@synergenius/flow-weaver-pack-vercel` | `vercel` | Vercel serverless functions |
-| `@synergenius/flow-weaver-pack-cloudflare` | `cloudflare` | Cloudflare Workers |
-| `@synergenius/flow-weaver-pack-inngest` | `inngest` | Inngest durable functions |
-| `@synergenius/flow-weaver-pack-github-actions` | `github-actions` | GitHub Actions CI/CD pipelines |
-| `@synergenius/flow-weaver-pack-gitlab-ci` | `gitlab-ci` | GitLab CI/CD pipelines |
+Flow Weaver core ships no export target. Every target comes from a pack's `exportTargets` manifest field, resolved from `node_modules` each time `fw export` or `fw_export` runs. Find target packs with `fw market search`, install one, and its target name becomes valid for `--target`. What a target generates, and any annotations it reads, is documented by the pack itself — once installed, its topics appear in `fw docs`.
 
-Install with:
-
-```bash
-npm install @synergenius/flow-weaver-pack-lambda
-```
-
-See [Deployment](deployment) for target-specific usage details.
+Without a target pack installed, `fw export` and `fw_export` return `INVALID_TARGET` for every name.
 
 ---
 
@@ -46,7 +36,7 @@ See [Deployment](deployment) for target-specific usage details.
 
 ### Search
 
-Find packages on npm:
+Find packs on every registry your npm uses:
 
 ```bash
 fw market search openai
@@ -54,10 +44,14 @@ fw market search            # Browse all packages
 fw market search llm --limit 5
 ```
 
-For private registries:
+The search reads `.npmrc` the way `npm install` does — the user's file, then the project's — and asks the default registry and every scoped one (`@acme:registry=https://npm.internal.com/`), each with its own token (`//npm.internal.com/:_authToken=…`). A private pack is found wherever an install would find it; the output names each registry searched and whether it answered. `fw_market_search` and the console's marketplace page do the same.
+
+A result marked **official** is published under the maintainers' `@synergenius/` npm scope. Every other scope is a third-party pack: review it as you would any npm dependency before installing, since a pack's code runs in your project.
+
+A registry that is not in `.npmrc` can be asked directly, by its search URL:
 
 ```bash
-fw market search openai --registry https://npm.internal.com
+fw market search openai --registry https://npm.internal.com/-/v1/search
 ```
 
 ### Install
@@ -69,7 +63,7 @@ fw market install flow-weaver-pack-openai
 fw market install flow-weaver-pack-openai@1.0.0
 ```
 
-After installation, the package's node types, workflows, and patterns are available for use in your workflows via `@fwImport`.
+After installation, the package's node types and workflows are available for use in your workflows via `@fwImport`.
 
 ### List Installed
 
@@ -77,65 +71,93 @@ After installation, the package's node types, workflows, and patterns are availa
 fw market list
 ```
 
-Shows all installed `flow-weaver-pack-*` packages with their available node types, workflows, and patterns.
+Shows every installed pack — any package under `node_modules` with a `flowweaver.manifest.json` — with its node types and workflows.
 
 ---
 
 ## Creating Packages
 
-### Scaffold
+A pack is written like any project that uses Flow Weaver, plus a manifest. The loop is: scaffold, write node types, build, `fw market pack`, try it from a project, publish.
 
-Create a new marketplace package:
+### Scaffold
 
 ```bash
 fw market init openai
-```
-
-This creates a `flow-weaver-pack-openai/` directory with:
-- `package.json` — Configured with `flow-weaver-marketplace-pack` keyword
-- `src/` — Source directory for node types, workflows, and patterns
-- `tsconfig.json` — TypeScript configuration
-
-Options:
-
-```bash
 fw market init openai --description "OpenAI nodes for Flow Weaver" --author "Your Name"
 fw market init openai -y  # Skip prompts
 ```
 
-### Package Structure
+This creates `flow-weaver-pack-openai/` (the prefix is added when missing):
 
 ```
 flow-weaver-pack-openai/
   src/
-    nodes/
-      chat-completion.ts    # @flowWeaver nodeType functions
-      embeddings.ts
-    workflows/
-      rag-pipeline.ts       # @flowWeaver workflow functions
-    patterns/
-      retry-with-backoff.ts # @flowWeaver pattern functions
-  package.json
-  tsconfig.json
+    index.ts                # barrel: re-exports node-types, workflows
+    node-types/
+      index.ts
+      sample.ts             # one @flowWeaver nodeType to start from
+    workflows/index.ts
+  package.json              # keyword flow-weaver-marketplace-pack, flowWeaver.engineVersion,
+                            # peerDependency on @synergenius/flow-weaver, scripts build / pack / prepublishOnly
+  tsconfig.json             # ESM, declarations, src → dist
+  README.md
+  .gitignore
 ```
 
-### Validate & Pack
+Everything the manifest points at is a **compiled** file under `dist/`, so `npm run build` (`tsc`) comes before `fw market pack`; `prepublishOnly` runs both.
+
+### Write node types
 
-Validate your package and generate the manifest:
+A node type in a pack is exactly a node type anywhere else — see [Concepts](concepts.md). Two things matter more in a pack:
+
+- Every `@flowWeaver nodeType` function under `src/` becomes an entry in the manifest, named after its function. Helpers a node calls must not carry the annotation, and two node types may not share a name (`UNIT-002`).
+- Give each one `@description`, and a `@color`, `@icon` or `@tag`; a workflow author sees these in the console and in `fw market list`, and `fw market pack` warns when they are missing (`PKG-008`, `PKG-009`).
+
+```typescript
+/**
+ * @flowWeaver nodeType
+ * @expression
+ * @label Chat Completion
+ * @description One turn against a chat model
+ * @color purple
+ * @icon smartToy
+ * @tag openai
+ */
+export async function chatCompletion(prompt: string, model: string): Promise<{ text: string }> {
+  // ...
+}
+```
+
+A workflow uses it with `@fwImport chatCompletion chatCompletion from "flow-weaver-pack-openai"` and then `@node ask chatCompletion`; ports come from the function's signature, read from the pack's `.d.ts`.
+
+### Validate & Pack
 
 ```bash
+npm run build
 fw market pack
 fw market pack --verbose  # Show parse warnings
 ```
 
-This:
-1. Scans all TypeScript files for `@flowWeaver` annotations
-2. Validates against 12 marketplace-specific rules
-3. Generates `flowweaver.manifest.json` with metadata about all exports
+This scans `src/**/*.ts` for `@flowWeaver` annotations, validates the package against the [marketplace rules](#marketplace-validation-rules), and writes `flowweaver.manifest.json`.
 
-### Publish
+Only `nodeTypes` and `workflows` are derived from source. Every other manifest field is hand-written and carried over unchanged from the existing `flowweaver.manifest.json` each time `market pack` runs; `name`, `version` and `description` come from `package.json`, and `engineVersion` and `categories` from its `flowWeaver` block.
+
+`fw console` opened on the pack's directory does the same without writing: the *This pack* page shows the manifest it would produce, the rules over it, and what writing it would change.
 
-Publish to npm:
+### Try it from a project
+
+Before publishing, install the pack into a project the way a user will, and use it:
+
+```bash
+cd ../my-project
+npm install ../flow-weaver-pack-openai     # or: npm link flow-weaver-pack-openai
+fw market list                             # the pack, its node types and what it contributes
+fw console                                 # Packs shows the pack's page, with its node types in the Step pane
+```
+
+The manifest's `file` paths are resolved inside `node_modules/<pack>/`, so a handler, rule set or target only loads when `dist/` was built and is in `files`.
+
+### Publish
 
 ```bash
 fw market publish
@@ -143,37 +165,181 @@ fw market publish --dry-run  # Preview without publishing
 fw market publish --tag beta # Publish with dist-tag
 ```
 
+`fw market publish` runs the pack validation first and refuses on an error-level issue. A private registry works as it does for `npm publish`: `publishConfig.registry` in `package.json`, or the scope's registry in `.npmrc`.
+
 ---
 
 ## Marketplace Validation Rules
 
-The `market pack` command validates packages against additional rules beyond standard workflow validation:
+`fw market pack` and `fw market publish` check the package beyond ordinary workflow validation. An error blocks publishing; a warning is reported.
+
+| Code | Severity | Says |
+|------|----------|------|
+| `PKG-001` | error | `package.json` keywords must include `flow-weaver-marketplace-pack` — this is what identifies a pack on a registry |
+| `PKG-002` | error | `flowWeaver.engineVersion` must be set in `package.json` |
+| `PKG-003` | error | `peerDependencies` must include `@synergenius/flow-weaver` |
+| `PKG-004` | error | The package must not be `private` |
+| `PKG-005` | warning | The name should follow `flow-weaver-pack-*` — the convention that makes a pack easy to find; a pack named otherwise still packs, installs and loads |
+| `PKG-006` | error | At least one node type, workflow or export target |
+| `PKG-007` | warning | `README.md` should exist |
+| `PKG-008` | warning | A node type should have a description |
+| `PKG-009` | warning | A node type should have visuals (`@color`, `@icon` or `@tag`) |
+| `UNIT-001` | error | Every workflow in the pack must validate |
+| `UNIT-002` | error | Node type names must be unique within the pack |
+| `TGT-001` / `TGT-002` | error | An export target needs `name` and `file`; names are unique |
+| `HND-001` | warning | A tag handler has no `serializerExport`: its tags are dropped whenever annotations are regenerated — see [Extending the grammar](#extending-the-grammar-with-a-pack) |
+| `HND-002` | error | A tag handler must declare `tags`, `namespace` and `file` |
 
-- Package name must start with `flow-weaver-pack-`
-- Must include `flow-weaver-marketplace-pack` keyword in `package.json`
-- All exported node types must have proper annotations
-- All exported workflows must validate successfully
-- No conflicting node type names
-- Proper TypeScript compilation
-- Manifest generation succeeds
+---
+
+## Pack Contributions
+
+Beyond node types, a pack extends Flow Weaver through hand-written fields in `flowweaver.manifest.json` (`manifestVersion: 2`). Installed packs are found by scanning `node_modules` for a `flowweaver.manifest.json`; each field below is read by a specific loader at a specific moment.
+
+| Field | Loaded by | When |
+|-------|-----------|------|
+| `tagHandlers` | The parser | Every parse with a `projectDir`; see [Custom Tag Handlers](#custom-tag-handlers) |
+| `validationRuleSets` | The parser | Every parse with a `projectDir`; each set's `detect` decides whether its rules apply |
+| `exportTargets` | `fw export` / `fw_export` | Per call; an unknown target name lists the installed ones |
+| `cliEntrypoint` + `cliCommands` | The CLI | At startup; commands appear as `fw <namespace> <command>` |
+| `mcpEntrypoint` + `mcpTools` | `fw mcp-server` | At server start, after the core tools |
+| `initContributions` | `fw init` | Use cases and templates offered during project setup; see [Init contributions](#init-contributions) |
+| `docs` | `fw docs`, `fw_docs`, `fw context`, `fw_context` | At command or server start; topics list, read and search like core topics |
+| `engineVersion` | CLI and MCP loaders | A pack requiring a newer Flow Weaver still loads, with a warning on stderr |
+
+### CLI commands
+
+Both fields are required; a pack with `cliEntrypoint` but an empty `cliCommands` is skipped.
+
+```json
+{
+  "cliEntrypoint": "dist/cli.js",
+  "cliCommands": [
+    {
+      "name": "replay",
+      "description": "Replay a recording",
+      "arguments": [{ "syntax": "<recording>", "description": "Recording file" }],
+      "options": [{ "flags": "--speed <n>", "description": "Playback speed", "default": 1 }]
+    }
+  ]
+}
+```
+
+- The namespace is the npm name without its scope and the `flow-weaver-pack-` prefix: `@acme/flow-weaver-pack-audio` → `fw audio replay`
+- The entrypoint is imported lazily, only when one of its commands runs
+- It exports `handleCommandV2(name, context)` where `context` is `{ args, options, cwd }` — Flow Weaver owns the parsing, so a pack never reads `process.argv`. The older `handleCommand(name, args)` is still accepted; `printHelp()` is optional
+
+### MCP tools
+
+Both fields are required; `mcpTools` is the list the server uses to decide whether to import the entrypoint at all, so declare every tool the entrypoint registers.
+
+```json
+{
+  "mcpEntrypoint": "dist/mcp.js",
+  "mcpTools": [{ "name": "fw_audio_replay", "description": "Replay a recording" }]
+}
+```
+
+```typescript
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+
+export async function registerMcpTools(mcp: McpServer): Promise<void> {
+  mcp.tool('fw_audio_replay', 'Replay a recording', { recording: z.string() }, async (args) => {
+    // …
+  });
+}
+```
+
+- Pack tools are registered after the core tools, so a name collision with a core tool is the pack's to avoid; prefix with the pack namespace
+- Every tool definition is sent to the assistant on every turn — keep descriptions short (see [MCP Tools](mcp-tools.md))
+- A failing import is reported on stderr and the server keeps running without that pack
+
+### Export targets
+
+```json
+{
+  "exportTargets": [{ "name": "audio-cloud", "description": "Deploy to Audio Cloud", "file": "dist/target.js", "exportName": "AudioCloudTarget" }]
+}
+```
+
+Targets are resolved per call from the current working directory's `node_modules`, so `fw_export` with no target packs installed returns `INVALID_TARGET` for every name. `file` is the compiled module; `exportName` names the class export (the default export when omitted). The class is instantiated lazily with no constructor arguments. What each target generates is described in [Deployment](deployment.md).
+
+#### Writing an export target
+
+A target is a class implementing `ExportTarget` from `@synergenius/flow-weaver/deployment`. Extending `BaseExportTarget` from the same module gives you `createFile`, `generatePackageJson`, `generateTsConfig`, the OpenAPI builders and `generateReadme`.
+
+| Member | Required | Called by |
+|--------|----------|-----------|
+| `name`, `description` | yes | Always |
+| `generate(options)` | yes | `fw export` for a single workflow; `fw_export` when the target has no `generateBundle` — targets that read the workflow AST rather than compiled code |
+| `generateBundle(workflows, nodeTypes, options)` | no | `fw export --multi`; `fw_export` whenever the target defines it. Receives the selected workflows and node types, each with an `expose` flag saying whether it gets an HTTP endpoint |
+| `getDeployInstructions(artifacts)` | yes | After generation; returns `{ title, steps, prerequisites, localTestSteps?, links? }` |
+| `deploySchema`, `nodeTypeDeploySchema` | no | Declare the `@deploy` keys the target accepts, for validation and editor autocomplete |
+| `generateMultiWorkflow`, `generateNodeTypeService` | no | Declared on the interface; neither `fw export` nor `fw_export` calls them |
+
+`options` is an `ExportOptions`: `sourceFile`, `workflowName`, `displayName`, `outputDir`, and optionally `description`, `production`, `includeDocs`, `multi`, `workflows`, and `targetOptions` — `{ durableSteps: true }` when requested; `fw_export` also passes the workflow's `@deploy` block as `deploy`.
+
+Both generators return artifacts of the shape `{ files, target, workflowName, entryPoint, warnings? }`, where each file is `{ relativePath, absolutePath, content, type }` and `type` is one of `handler`, `config`, `workflow`, `nodeType`, `package`, `other`. The caller writes the files unless `--dry-run` (CLI) or `preview` (MCP) was requested, then prints the deploy instructions.
+
+### Documentation topics
+
+```json
+{
+  "docs": [
+    {
+      "slug": "audio-recording",
+      "name": "Audio Recording",
+      "description": "Recording, trimming and replaying audio in a workflow",
+      "keywords": ["audio", "record", "replay"],
+      "presets": ["authoring"],
+      "file": "docs/recording.md"
+    }
+  ]
+}
+```
+
+- `file` is relative to the package root and is plain Markdown; frontmatter is optional — when the file has none, `name`, `description` and `keywords` come from the manifest
+- The topic appears in `fw docs`, `fw_docs list`/`read`/`search` and, for each preset named in `presets`, in `fw context` and `fw_context`
+- A slug that collides with a core topic is ignored; a `file` that does not exist is skipped with a note on stderr
+
+### Init contributions
+
+```json
+{
+  "initContributions": {
+    "useCase": { "id": "audio", "name": "Audio pipelines", "description": "Record, trim and publish audio" },
+    "templates": ["audio-record", "audio-publish"]
+  }
+}
+```
+
+`fw init` offers the use case among its prompts and, when it is picked, the listed templates. The templates themselves are read from a `templates.js` beside the manifest (`<pack>/templates.js`), which exports `workflowTemplates: WorkflowTemplate[]` — the same shape as the core templates listed in [Scaffold](scaffold.md); only the ids named in `templates` are taken.
 
 ---
 
-## Custom Tag Handlers
+## Extending the grammar with a pack
 
-Tag handlers let packs extend the parser with custom JSDoc annotations. When the parser encounters a tag it doesn't recognize natively, it delegates to registered pack handlers before emitting "Unknown annotation" warnings.
+A pack can teach the parser new JSDoc tags — for example `@secret`, `@runner`, `@matrix` — because the data a tag carries is meant for the pack's own consumers: its export target, its validation rules, its CLI. A pack can also read generic `[key: "value"]` bracket attributes on `@node`: core parses any bracket attribute it does not itself define into `nodeInstance.attributes` verbatim and gives it no meaning, so a pack reads that map and interprets its own keys (for example `[runner: "ubuntu-latest"]`). What a pack cannot add: new structural tags like `@path`, or new port syntax; those stay in core so every tool reads a workflow the same way.
 
-The CI/CD pack (`flow-weaver-pack-cicd`) is the primary example: it registers handlers for `@secret`, `@runner`, `@cache`, `@artifact`, and other CI/CD tags.
+The pieces, all declared under `tagHandlers` in the manifest and resolved from one compiled file:
 
-### Writing a handler
+| Piece | Direction | Required |
+|-------|-----------|----------|
+| handler (`TTagHandlerFn`) | tag line → data in `deploy.<namespace>` | yes |
+| serializer (`TTagSerializerFn`) | `deploy.<namespace>` → tag lines | in practice yes: without it, regeneration drops the tags (`HND-001`) |
+| validation rule set | rules that run when `detect(ast)` says the workflow uses the namespace | when the tags have rules |
+
+### Where the data goes
 
-A tag handler is a function matching the `TTagHandlerFn` signature:
+A handled tag writes into the deploy map under the handler's namespace. In the AST that is `workflow.options.deploy[namespace]` for a workflow block and `nodeType.deploy[namespace]` for a node type block; the parser also mirrors each namespace to `options.<namespace>` so a pack's own code can read it with a typed name. Everything else reads it from there: the console shows it on the step card as *pack tags*, an export target receives it as `deploy`, and the pack's rules see it in `ast`.
+
+### Writing a handler
 
 ```typescript
 import type { TTagHandlerFn } from '@synergenius/flow-weaver/api';
 
-export const myHandler: TTagHandlerFn = (tagName, comment, ctx) => {
-  // tagName: the tag without '@', e.g. "secret"
+export const audioTagHandler: TTagHandlerFn = (tagName, comment, ctx) => {
+  // tagName: the tag without '@', e.g. "region"
   // comment: everything after the tag on that line
   // ctx.deploy: the deploy map for your namespace (mutate it directly)
   // ctx.warnings: push parser warnings here
@@ -183,119 +349,102 @@ export const myHandler: TTagHandlerFn = (tagName, comment, ctx) => {
     ctx.warnings.push(`Empty @${tagName} tag`);
     return;
   }
+  if (tagName === 'region') ctx.deploy['region'] = value;
+  if (tagName === 'memory') ctx.deploy['memory'] = Number(value);
+};
+```
 
-  const items = (ctx.deploy['items'] as string[]) ?? [];
-  items.push(value);
-  ctx.deploy['items'] = items;
+The handler receives one call per tag occurrence, in source order, and may be called for several tags (`tags` in the manifest). Push a warning rather than throwing: a warning reaches `fw validate` and the console; a throw aborts the parse of that file.
+
+### Writing the serializer
+
+The compiler regenerates a workflow's JSDoc block from the AST on `fw compile` and after every `fw_modify`. Core knows how to write its own tags; for a namespace it does not know, it calls the pack's serializer with the namespace's data and writes whatever lines come back. A pack without one loses its tags the first time the block is regenerated — silently, until the export target notices its data is gone.
+
+```typescript
+import type { TTagSerializerFn } from '@synergenius/flow-weaver/api';
+
+// The inverse of the handler: every line the handler understands, emitted from the data it produced.
+export const audioSerializer: TTagSerializerFn = (deploy) => {
+  const lines: string[] = [];
+  if (typeof deploy.region === 'string') lines.push(` * @region ${deploy.region}`);
+  if (typeof deploy.memory === 'number') lines.push(` * @memory ${deploy.memory}`);
+  return lines;
 };
 ```
 
-The handler receives one call per tag occurrence. Parsed data goes into `ctx.deploy`, which maps to `workflow.deploy[namespace]` or `nodeType.deploy[namespace]` in the final AST.
+Each returned string is a whole comment line including the leading ` * `. Emit in a stable order so a regenerated file diffs cleanly. The round trip — parse, regenerate, parse again, equal — is worth a test in the pack.
 
 ### Declaring handlers in the manifest
 
-Add a `tagHandlers` entry to your `flowweaver.manifest.json`:
-
 ```json
 {
   "manifestVersion": 2,
   "tagHandlers": [
     {
-      "tags": ["secret", "runner", "cache"],
-      "namespace": "cicd",
+      "tags": ["region", "memory"],
+      "namespace": "audio",
       "scope": "both",
       "file": "dist/tag-handler.js",
-      "exportName": "cicdTagHandler"
+      "exportName": "audioTagHandler",
+      "serializerExport": "audioSerializer"
     }
   ]
 }
 ```
 
-Fields:
-
 | Field | Description |
 |-------|-------------|
 | `tags` | Tag names this handler processes (without the `@` prefix) |
-| `namespace` | Key in the deploy map where parsed data is stored |
+| `namespace` | Key in the deploy map where parsed data is stored; also the `options.<namespace>` mirror |
 | `scope` | `workflow` for workflow-level tags, `nodeType` for node type tags, `both` for either |
-| `file` | Relative path to the compiled JS file exporting the handler |
-| `exportName` | Named export from the file (omit for `default` export) |
-
-### Handler scope
-
-A handler scoped to `workflow` only runs for tags inside `@flowWeaver workflow` blocks. A handler scoped to `nodeType` only runs inside `@flowWeaver nodeType` blocks. Use `both` when your tags are valid in either context.
-
-If a tag appears in the wrong scope, the parser emits a warning and skips the handler call.
-
-### How discovery works
-
-When `parseWorkflow()` is called with a `projectDir` option (or when the CLI runs from a project directory), the parser scans `node_modules` for installed packs with a `flowweaver.manifest.json`. It reads the `tagHandlers` array from each manifest, dynamically imports the handler files, and registers them in the `TagHandlerRegistry`. This scan runs once per project directory and is cached for subsequent parse calls.
-
----
-
-## External Plugins
-
-Plugins extend the Flow Weaver Studio IDE with custom UI components, system logic, and integrations.
+| `file` | Relative path to the compiled JS file exporting the handler (and the serializer) |
+| `exportName` | Named export of the handler (omit for `default`) |
+| `serializerExport` | Named export of the serializer, from the same `file` |
 
-### Scaffold a Plugin
+A handler scoped to `workflow` only runs for tags inside `@flowWeaver workflow` blocks; `nodeType` only inside `@flowWeaver nodeType` blocks. A tag in the wrong scope is consumed with a warning and not handled.
 
-```bash
-fw plugin init my-plugin
-```
-
-Options:
-
-| Flag | Description | Default |
-|------|-------------|---------|
-| `-a, --area <area>` | Component area | `panel` |
-| `--no-system` | Skip system module | included |
-| `-p, --preview` | Preview without writing | `false` |
-| `--force` | Overwrite existing | `false` |
+### Validation rules for the tags
 
-### Component Areas
+Rules that only make sense when the namespace is in use — a declared secret nobody reads, a job name used twice — are a rule set: a `detect` predicate and a lazy `getRules`, from one compiled file.
 
-Plugins register React components in specific areas of the Studio IDE:
-
-| Area | Location |
-|------|----------|
-| `sidebar` | Left sidebar panel |
-| `main` | Main content area |
-| `toolbar` | Top toolbar |
-| `modal` | Modal dialog |
-| `panel` | Bottom or side panel |
+```typescript
+import type { TValidationRule, TWorkflowAST } from '@synergenius/flow-weaver/ast';
 
-### Plugin Structure
+export function detect(ast: TWorkflowAST): boolean {
+  return ast.options?.deploy?.audio !== undefined;
+}
 
-```bash
-fw plugin init my-plugin --area sidebar
+export function getRules(): TValidationRule[] {
+  return [{
+    name: 'AUDIO_REGION_UNKNOWN',
+    validate(ast) {
+      const region = ast.options?.deploy?.audio?.region;
+      return typeof region === 'string' && !['eu', 'us'].includes(region)
+        ? [{ type: 'error', code: 'AUDIO_REGION_UNKNOWN', message: `Unknown region "${region}"; use eu or us` }]
+        : [];
+    },
+  }];
+}
 ```
 
-Generates:
-```
-my-plugin/
-  src/
-    index.ts          # Plugin manifest and registration
-    component.tsx     # React component for the area
-    system.ts         # System module (event handlers, state)
-  package.json
+```json
+{
+  "validationRuleSets": [
+    { "name": "Audio rules", "namespace": "audio", "file": "dist/rules.js", "detectExport": "detect", "rulesExport": "getRules" }
+  ]
+}
 ```
 
-### Capability Sandboxing
+A rule returns `TValidationError`s: `type` (`error` | `warning`), a `code` prefixed with the pack's namespace so it never collides with core's, a `message` that says what to change, and optionally `node`. They run inside `fw validate`, `fw_validate` and the console's Issues pane exactly like core rules, and an `error` blocks `fw compile`. Document each code in one of the pack's [documentation topics](#documentation-topics) so `fw_docs` can explain it.
 
-Plugins declare required capabilities. The runtime enforces access controls:
+### How discovery works
 
-| Capability | Allows |
-|------------|--------|
-| `filesystem` | Read/write workflow files |
-| `network` | HTTP requests |
-| `process` | Spawn processes |
-| `interop` | Communicate with other plugins |
+When `parseWorkflow()` is called with a `projectDir` (the CLI and the console always pass one), the parser scans `node_modules` for packs with a `flowweaver.manifest.json`, imports each handler `file`, and registers the handler, the serializer and the rule sets. The scan runs once per project directory per process. A `file` that fails to import — most often because the pack was not built — is skipped without an error: if a pack's tags come back as `Unknown annotation` warnings, check that its `dist/` exists.
 
 ---
 
 ## Related Topics
 
-- [CLI Reference](cli-reference) — Full marketplace and plugin command flags
-- [Patterns](patterns) — Creating and sharing reusable patterns
-- [Scaffold](scaffold) — Template system for node types and workflows
-- [Concepts](concepts) — Core workflow fundamentals
+- [CLI Reference](cli-reference.md) — Full marketplace command flags
+- [Scaffold](scaffold.md) — Template system for node types and workflows
+- [Concepts](concepts.md) — Core workflow fundamentals