first commit

docs/devtools/tooling/README.md

@@ -0,0 +1,28 @@
+# `tooling`
+
+CLI frameworks, installers, and build tooling.
+
+<!-- begin:auto-docs -->
+## Packages in `tooling`
+
+16 packages.
+
+| Package | Description |
+|---|---|
+| [`@suaveplan/cli`](./cli/README.md) | Enterprise-grade CLI framework for Node.js. Composable fluent API with subcommand routing, option parsing, OTel tracing, and a full set of terminal UI primitiv… |
+| [`@suaveplan/electrobun`](./electrobun/README.md) | Electrobun desktop-app generator and orchestrator for the SuavePlan ecosystem. Scaffolds a fresh Electrobun project from a layered config + prompt flow, drives… |
+| [`@suaveplan/install-agent-skills`](./install-agent-skills/README.md) | Installer plugin that bundles every Suaveplan skill (`SKILL.md` + assets) and installs them into a target project via `@suaveplan/installer`. |
+| [`@suaveplan/installer`](./installer/README.md) | Plugin host for project boilerplating and asset installation. Pipelines plugins through `detect → prompts → plan → apply → postInstall` with transactional roll… |
+| [`@suaveplan/javy-cli-darwin-arm64`](./javy-cli-darwin-arm64/README.md) | Platform wrapper for **Javy v8.1.1** on `darwin-arm64`. |
+| [`@suaveplan/javy-cli-darwin-x64`](./javy-cli-darwin-x64/README.md) | Platform wrapper for **Javy v8.1.1** on `darwin-x64`. |
+| [`@suaveplan/javy-cli-linux-arm64`](./javy-cli-linux-arm64/README.md) | Platform wrapper for **Javy v8.1.1** on `linux-arm64`. |
+| [`@suaveplan/javy-cli-linux-x64`](./javy-cli-linux-x64/README.md) | Platform wrapper for **Javy v8.1.1** on `linux-x64`. |
+| [`@suaveplan/javy-cli-win32-x64`](./javy-cli-win32-x64/README.md) | Platform wrapper for **Javy v8.1.1** on `win32-x64`. |
+| [`@suaveplan/linter`](./linter/README.md) | Unified markdown + biome linting pipeline for Suaveplan: a remark-based markdown fixer covering MD012/022/025/029/031/032/035/036/040/044, an injectable `Comma… |
+| [`@suaveplan/mcp`](./mcp/README.md) | Universal Model Context Protocol (MCP) server + client with a pluggable transport stack, JSON-RPC dispatcher, AbortSignal cancellation, progress notifications,… |
+| [`@suaveplan/overview`](./overview/README.md) | Machine-readable Suaveplan project manifest: typed PackageRecord / SuavePlanManifest / WorkspaceGraph, Zod schemas, tier inference, filesystem discovery (server sub-path), graph utilities (topo, cycle detection, transitive closure, leaves, roots), plugin/category/tier roll-ups, six OVERVIEW.* error codes, three OTel counters + one histogram. |
+| [`@suaveplan/profiler`](./profiler/README.md) | Universal runtime performance profiler. |
+| [`@suaveplan/readline`](./readline/README.md) | AsyncGenerator line reader and interactive prompt interface for Node.js streams, file paths, and Web Streams. |
+| [`@suaveplan/sandbox`](./sandbox/README.md) | Server-tier sandboxed code execution for `@suaveplan` plugin hosts and agent runtimes. Ships four `SandboxEngine` implementations (a `node:vm` default, real `n… |
+| [`@suaveplan/test-vite`](./test-vite/README.md) | Vite + Vitest configuration factories and validators for Suaveplan: `createViteLibraryConfig`, `createViteAppConfig`, `createVitestConfig`, `createVitestBrowse… |
+<!-- end:auto-docs -->

docs/devtools/tooling/_intro.md

@@ -0,0 +1 @@
+CLI frameworks, installers, and build tooling.

docs/devtools/tooling/cli/src/app/app.md

@@ -0,0 +1,120 @@
+# app
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+## Purpose
+
+`App` is the top-level entry point for a `@suaveplan/cli` application. It wraps a root `Command` and adds application-level concerns: version printing, help generation, `onError` handling, OTel span instrumentation on `run()`, and `AbortSignal` support. The `cli()` factory function creates an `App` with a name and optional version string in a single expression.
+
+`App` delegates all routing and parsing to the underlying `Command` hierarchy. Its primary responsibility is to intercept `--version`, `--help`, and abort signals before dispatching, and to wrap any thrown error with `CliError(CLI_CODES.APP.RUN_FAILED)` when an `onError` handler is registered.
+
+## Features
+
+- Fluent builder: `.description()`, `.option()`, `.argument()`, `.action()`, `.command()`, `.example()`
+- `run(argv?, options?)` dispatches to the root command; defaults `argv` to `process.argv.slice(2)`
+- `--version` / `-V` prints the version string (if set) and exits cleanly
+- `--help` / `-h` prints `helpText()` and exits cleanly
+- `options.signal` (AbortSignal) — throws `CliError(CLI_CODES.APP.ABORTED)` immediately when already aborted
+- `onError` handler — catches thrown errors, wraps non-`CliError` in `CliError(CLI_CODES.APP.RUN_FAILED)`, and calls the handler instead of re-throwing
+- OTel span on every `run()` call: span name `cli.app.run`, attribute `cli.app` set to the app name; `SpanStatusCode.ERROR` set on failure
+- `cli(name, version?)` factory for single-expression app creation
+
+## Usage: Basic Example
+
+```ts
+import { cli } from "@suaveplan/cli/app/app";
+
+const app = cli("deploy", "1.0.0")
+  .description("Deployment toolkit");
+
+app.command("up")
+  .description("Bring services up")
+  .action(async () => {
+    console.log("Services are up");
+  });
+
+await app.run();
+```
+
+## Usage: Advanced Example
+
+```ts
+import { App } from "@suaveplan/cli/app/app";
+
+const app = new App({
+  name: "myapp",
+  version: "2.1.0",
+  description: "My enterprise CLI",
+  writer: (text) => process.stdout.write(text + "\n"),
+  onError: (err) => {
+    console.error(`Error [${err.code}]: ${err.message}`);
+    process.exit(1);
+  },
+});
+
+app
+  .option("--verbose", "Enable verbose output")
+  .action(async (ctx) => {
+    if (ctx.options.verbose) console.log("Verbose mode on");
+  });
+
+const controller = new AbortController();
+process.on("SIGINT", () => controller.abort());
+
+await app.run(process.argv.slice(2), { signal: controller.signal });
+```
+
+## API Reference
+
+### `new App(config: AppConfig)`
+
+Creates a new app. Config fields: `name` (required), `version`, `description`, `enableHelp` (default true), `enableVersion` (default true), `onError`, `writer`.
+
+### `app.name: string`
+
+The app's name as provided in config.
+
+### `app.version: string | undefined`
+
+The app's version string, or `undefined` if not set.
+
+### `app.description(text: string): this`
+
+Sets the app description shown in help text.
+
+### `app.option(flags, description?, defaultValue?): this`
+
+Registers a root-level option.
+
+### `app.argument(spec, description?): this`
+
+Registers a root-level positional argument.
+
+### `app.action(fn: ActionFn): this`
+
+Sets the root action handler.
+
+### `app.command(name: string): Command`
+
+Registers and returns a named sub-command.
+
+### `app.example(text: string): this`
+
+Adds an example to the help output.
+
+### `app.helpText(): string`
+
+Returns formatted multi-line help text for the root command.
+
+### `app.run(argv?: string[], options?: { signal?: AbortSignal }): Promise<void>`
+
+Executes the app. If `signal` is already aborted, throws `CliError(ABORTED)` immediately. Intercepts `--version` and `--help` before routing. Delegates to the root `Command.execute()`.
+
+### `cli(name: string, version?: string): App`
+
+Factory function. Creates an `App` with `name` and optional `version`.
+
+## Implementation Notes
+
+The `writer` config field injects the output sink, defaulting to `process.stdout.write`. This enables full testability without TTY or process coupling. The `onError` hook receives a `CliError` — if the thrown value was a plain `Error`, it is wrapped in `CliError(RUN_FAILED)` before being handed to the hook, so callers always receive a structured error with a stable code.

docs/devtools/tooling/cli/src/command/command.md

@@ -0,0 +1,122 @@
+# command
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+## Purpose
+
+`Command` is the core routing primitive for `@suaveplan/cli`. It models a single CLI command that can carry options, positional arguments, and an action handler, or act as a router that delegates to named sub-commands. Every `App` is backed by a root `Command`.
+
+The class exposes a fluent builder API: chain `.description()`, `.option()`, `.argument()`, `.command()`, and `.action()` calls before calling `.execute()` at runtime. Sub-commands are registered via `.command(name)` which returns the child `Command`, enabling identical fluent chaining for nested hierarchies.
+
+## Features
+
+- Fluent builder: `.description()`, `.option()`, `.argument()`, `.action()`, `.command()`, `.alias()`, `.hidden()`, `.example()`
+- Sub-command routing: first non-flag token in `argv` is matched against registered names and aliases
+- Option parsing delegated to `parseArgs` — inherits full flag semantics (boolean, string, number, `--no-*`, short flags, `=` syntax, `--` rest)
+- OTel span on every `execute()` call: span name `cli.command.execute`, attribute `cli.command` set to the full qualified name
+- `CliError(CLI_CODES.COMMAND.NO_ACTION)` when no action is registered and no sub-command is found
+- `CliError(CLI_CODES.COMMAND.UNKNOWN_SUBCOMMAND)` when an unknown first token is provided and sub-commands are registered
+- Automatic `--help` / `-h` handling: prints `helpText()` and returns without error
+- `helpText(parentName?)` generates a formatted usage block with options and sub-command listing
+
+## Usage: Basic Example
+
+```ts
+import { Command } from "@suaveplan/cli/command/command";
+
+const cmd = new Command("greet")
+  .description("Greet a user")
+  .option("--name <name>", "Name to greet", "World")
+  .action(async (ctx) => {
+    console.log(`Hello, ${ctx.options.name}!`);
+  });
+
+await cmd.execute(["--name", "Alice"]);
+// → Hello, Alice!
+```
+
+## Usage: Advanced Example
+
+```ts
+import { Command } from "@suaveplan/cli/command/command";
+
+const root = new Command("deploy")
+  .description("Deployment toolkit");
+
+root
+  .command("up")
+  .description("Bring services up")
+  .option("--env <env>", "Target environment", "staging")
+  .action(async (ctx) => {
+    console.log(`Deploying to ${ctx.options.env}`);
+  });
+
+root
+  .command("down")
+  .alias("d")
+  .description("Tear services down")
+  .action(async () => {
+    console.log("Tearing down...");
+  });
+
+// Route: "deploy up --env production"
+await root.execute(["up", "--env", "production"]);
+
+// Route by alias: "deploy d"
+await root.execute(["d"]);
+```
+
+## API Reference
+
+### `new Command(name: string)`
+
+Creates a new command with the given name.
+
+### `.description(text: string): this`
+
+Sets the human-readable description shown in help text.
+
+### `.option(flags: string, description?: string, defaultValue?: unknown): this`
+
+Registers an option. `flags` follows `parseOptionFlags` syntax: `"--name <value>"`, `"-v, --verbose"`.
+
+### `.argument(spec: string, description?: string): this`
+
+Registers a positional argument. `spec` follows `parseArgumentSpec` syntax: `"<file>"`, `"[file]"`, `"<files...>"`.
+
+### `.action(fn: ActionFn): this`
+
+Sets the action handler. `fn` receives an `ActionContext` with `options`, `args` (positionals), `rest`, and `command` info.
+
+### `.command(name: string): Command`
+
+Registers a named sub-command and returns it for further chaining.
+
+### `.alias(name: string): this`
+
+Adds an alias for this command, recognised during routing.
+
+### `.hidden(): this`
+
+Marks the command as hidden — it is excluded from help text listings.
+
+### `.example(text: string): this`
+
+Adds an example line shown in help text.
+
+### `.helpText(parentName?: string): string`
+
+Returns formatted multi-line help text including usage, options, sub-commands, and examples.
+
+### `.getParserConfig(): ParserConfig`
+
+Returns the `ParserConfig` derived from registered options and arguments. Used internally by `execute()`.
+
+### `.execute(argv: string[], parentName?: string): Promise<void>`
+
+Parses `argv`, routes to sub-commands or calls the action. Wraps the execution in an OTel span. Throws `CliError` on routing or parse failures.
+
+## Implementation Notes
+
+Sub-command alias resolution scans all registered sub-commands for an `_aliases` entry matching the first token. An OTel span covers the full `execute()` lifecycle including sub-command delegation — the span status is set to `ERROR` if any exception propagates. The `--help` / `-h` shortcut is handled before sub-command routing and before the action call, so it always works even if no action is registered.

docs/devtools/tooling/cli/src/errors/errors.md

@@ -0,0 +1,171 @@
+# errors
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+## Purpose
+
+The `errors` module defines the complete error taxonomy for `@suaveplan/cli`. It
+provides a stable, machine-readable code registry (`CLI_CODES`) and a strongly-typed
+error class (`CliError`) so that every failure surface in the CLI framework is
+discriminable at runtime without string-matching on messages. Callers can switch
+exhaustively on `err.code`, log structured records with stable identifiers, and
+forward typed errors across process boundaries without losing fidelity.
+
+## Features
+
+- **Three sub-namespaces** — `CLI.PARSE.*` covers argument/option parsing failures;
+  `CLI.COMMAND.*` covers command-dispatch failures; `CLI.APP.*` covers top-level
+  application lifecycle failures.
+- **Nine stable error codes** — each code is a dot-delimited string constant produced
+  by `defineCodes()` from `@suaveplan/error`, guaranteeing uniqueness and structural
+  consistency across the codebase.
+- **`CliCode` union type** — narrows the full set of valid codes for use in generic
+  `SuaveplanError<CliCode>` type parameters and exhaustive switch statements.
+- **`CliError` class** — extends `SuaveplanError` with a public constructor, cause
+  chaining, and structured `context` attachment for diagnostic metadata.
+- **Zero runtime overhead** — the `CLI_CODES` object is `as const`, so all string
+  values are inlined at the call site by the TypeScript compiler.
+
+## Usage: Basic Example
+
+```ts
+import { CliError, CLI_CODES } from "@suaveplan/cli/errors/errors";
+
+function assertKnownOption(flag: string, known: Set<string>): void {
+    if (!known.has(flag)) {
+        throw new CliError(
+            CLI_CODES.PARSE.UNKNOWN_OPTION,
+            "cli.parse.unknown_option"
+        );
+    }
+}
+```
+
+## Usage: Advanced Example
+
+```ts
+import { CliError, CLI_CODES } from "@suaveplan/cli/errors/errors";
+import { SuaveplanError } from "@suaveplan/error";
+
+async function runApp(signal: AbortSignal): Promise<void> {
+    try {
+        await doWork(signal);
+    } catch (err) {
+        if (signal.aborted) {
+            throw new CliError(CLI_CODES.APP.ABORTED, "cli.app.aborted", {
+                cause: err instanceof Error ? err : undefined,
+                context: { reason: signal.reason },
+            });
+        }
+        throw new CliError(CLI_CODES.APP.RUN_FAILED, "cli.app.run_failed", {
+            cause: err instanceof Error ? err : undefined,
+        });
+    }
+}
+
+function handleError(err: unknown): void {
+    if (err instanceof CliError) {
+        // Narrow on the stable code — no message-string matching needed.
+        switch (err.code) {
+            case CLI_CODES.APP.ABORTED:
+                process.exitCode = 130; // standard SIGINT exit code
+                break;
+            case CLI_CODES.PARSE.UNKNOWN_OPTION:
+                console.error(`Unknown option: ${String(err.context?.["option"])}`);
+                process.exitCode = 1;
+                break;
+            default:
+                console.error(err.message);
+                process.exitCode = 1;
+        }
+    }
+}
+```
+
+## API Reference
+
+### `CLI_CODES`
+
+```ts
+const CLI_CODES: {
+    PARSE: {
+        UNKNOWN_OPTION: "CLI.PARSE.UNKNOWN_OPTION";
+        MISSING_VALUE: "CLI.PARSE.MISSING_VALUE";
+        INVALID_VALUE: "CLI.PARSE.INVALID_VALUE";
+        MISSING_ARGUMENT: "CLI.PARSE.MISSING_ARGUMENT";
+        MISSING_REQUIRED_OPTION: "CLI.PARSE.MISSING_REQUIRED_OPTION";
+    };
+    COMMAND: {
+        NO_ACTION: "CLI.COMMAND.NO_ACTION";
+        UNKNOWN_SUBCOMMAND: "CLI.COMMAND.UNKNOWN_SUBCOMMAND";
+    };
+    APP: {
+        RUN_FAILED: "CLI.APP.RUN_FAILED";
+        ABORTED: "CLI.APP.ABORTED";
+    };
+}
+```
+
+Immutable registry of all error codes used by `@suaveplan/cli`. Each value is a
+dot-delimited string in the form `<NAMESPACE>.<SUBCATEGORY>.<NAME>`.
+
+### `CliCode`
+
+```ts
+type CliCode =
+    | "CLI.PARSE.UNKNOWN_OPTION"
+    | "CLI.PARSE.MISSING_VALUE"
+    | "CLI.PARSE.INVALID_VALUE"
+    | "CLI.PARSE.MISSING_ARGUMENT"
+    | "CLI.PARSE.MISSING_REQUIRED_OPTION"
+    | "CLI.COMMAND.NO_ACTION"
+    | "CLI.COMMAND.UNKNOWN_SUBCOMMAND"
+    | "CLI.APP.RUN_FAILED"
+    | "CLI.APP.ABORTED";
+```
+
+Union of all values in `CLI_CODES`. Use as the type parameter for
+`SuaveplanError<CliCode>` or in exhaustive switch statements.
+
+### `CliError`
+
+```ts
+class CliError extends SuaveplanError<CliCode> {
+    public constructor(
+        code: CliCode,
+        messageKey: string,
+        options?: SuaveplanErrorOptions
+    ): CliError;
+}
+```
+
+Typed error for all `@suaveplan/cli` failures.
+
+- **`code`** — one of the `CliCode` values; accessible as `err.code` via the base
+  class.
+- **`messageKey`** — i18n message key passed to the base class for message resolver
+  integration.
+- **`options.cause`** — optional upstream `Error` for cause chaining; accessible as
+  `err.cause`.
+- **`options.context`** — optional `Record<string, unknown>` with structured
+  diagnostic metadata; accessible as `err.context`.
+
+Throws: nothing — this is an Error constructor.
+
+## Implementation Notes
+
+`CLI_CODES` is built from three separate `defineCodes()` calls rather than one flat
+call so that each sub-namespace is isolated. This mirrors the pattern established in
+`@suaveplan/readline` and keeps future code-set additions within a namespace
+non-breaking for callers who already destructure `CLI_CODES.PARSE`.
+
+The `CliError` constructor comment (`biome-ignore`) documents why the constructor is
+not "useless" from Biome's perspective: the base `SuaveplanError` constructor is
+`protected`, so widening it to `public` here is a meaningful override even though
+the body only calls `super()`. This is the standard pattern across all
+`@suaveplan/*` packages.
+
+No runtime dependencies beyond `@suaveplan/error` are introduced. The `defineCodes`
+helper produces plain string literals, so the entire module tree-shakes to near
+zero bytes when errors are not thrown on a given code path.

docs/devtools/tooling/cli/src/output/format/format.md

@@ -0,0 +1,93 @@
+# output/format
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+## Purpose
+
+`format` provides a collection of pure string-formatting utilities for structured CLI output. All functions take plain data and return formatted strings — no side effects, no I/O. Callers are responsible for printing the result. This design makes every function trivially testable and composable.
+
+The module covers the most common CLI output patterns: key-value pairs, bulleted lists, directory-style trees, inline JSON, multi-column alignment, section headings, horizontal dividers, and indented blocks.
+
+## Features
+
+- `keyValue(obj, opts?)` — formats a record as aligned `key: value` pairs
+- `list(items, opts?)` — formats an array as a bulleted list
+- `tree(node, opts?)` — renders a recursive tree with `├─` / `└─` connectors
+- `json(value, opts?)` — `JSON.stringify` wrapper with configurable indent
+- `columns(rows, separator?)` — right-pads cells so columns align across rows
+- `heading(text, level?)` — box-style heading with `═` (level 1) or `─` (level 2) borders
+- `divider(char?, width?)` — repeated character line
+- `indent(text, spaces?)` — prefixes every line with spaces
+
+## Usage: Basic Example
+
+```ts
+import { keyValue, list, heading } from "@suaveplan/cli/output/format/format";
+
+console.log(heading("Build Report"));
+console.log(keyValue({ status: "success", files: 42, duration: "1.2s" }));
+console.log(list(["Compiled main.ts", "Emitted dist/", "Linked types"]));
+```
+
+## Usage: Advanced Example
+
+```ts
+import { tree, columns, json, indent } from "@suaveplan/cli/output/format/format";
+
+const structure = {
+  label: "src/",
+  children: [
+    { label: "app/", children: [{ label: "app.ts" }, { label: "app.test.ts" }] },
+    { label: "utils/", children: [{ label: "format.ts" }] },
+  ],
+};
+
+console.log(tree(structure));
+
+const rows = [
+  ["alice", "admin", "2024-01-01"],
+  ["bob", "user", "2024-03-15"],
+];
+console.log(columns([["Name", "Role", "Joined"], ...rows]));
+
+console.log(indent(json({ ok: true, count: 7 }), 4));
+```
+
+## API Reference
+
+### `keyValue(obj: Record<string, unknown>, opts?: KeyValueOptions): string`
+
+Formats each entry as `key: value`. Options: `separator` (default `": "`), `indent` (spaces before each line, default 0).
+
+### `list(items: string[], opts?: ListOptions): string`
+
+Formats each item with a bullet marker. Options: `bullet` (default `"•"`), `indent` (default 0).
+
+### `tree(node: TreeNode, opts?: TreeOptions, _prefix?: string): string`
+
+Renders a nested tree with connector lines. Options: `indent` (spaces per nesting level, default 2).
+
+### `json(value: unknown, opts?: JsonOptions): string`
+
+Returns `JSON.stringify(value, null, indent)`. Options: `indent` (default 2).
+
+### `columns(rows: string[][], separator?: string): string`
+
+Pads each cell in each column to the column's maximum width, then joins with `separator` (default `"  "`). Returns empty string for empty input.
+
+### `heading(text: string, level?: number): string`
+
+Returns a three-line block: border, centered text, border. Level 1 uses `═`, level 2 uses `─`, others use `-`.
+
+### `divider(char?: string, width?: number): string`
+
+Returns `char.repeat(width)`. Defaults: `"─"` and `40`.
+
+### `indent(text: string, spaces?: number): string`
+
+Prepends `spaces` (default 2) spaces to every line of `text`.
+
+## Implementation Notes
+
+All functions are stateless and have no dependencies. `tree` recurses depth-first, tracking a prefix string for connector characters at each level. `columns` computes widths in a single pass over all rows, then renders in a second pass. The `_prefix` parameter of `tree` is internal — external callers should omit it.

docs/devtools/tooling/cli/src/output/table/table.md

@@ -0,0 +1,81 @@
+# output/table
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+## Purpose
+
+`table` renders structured data as a formatted ASCII table with header row, optional borders, and configurable column alignment. It computes column widths from the full data set — header and all rows — ensuring that every column is at least as wide as its widest cell. The result is a plain multi-line string ready for console output or piping.
+
+The function is pure: it takes a `TableOptions` object and returns a `string`. No state, no I/O, no mutations.
+
+## Features
+
+- Automatic column width calculation: each column is as wide as its widest cell across all rows
+- Three alignment modes per column: `"left"` (default), `"right"`, `"center"`
+- Border mode (default on): header and data rows separated by `─┼─` divider
+- Border-off mode: columns joined with two spaces
+- Handles empty rows gracefully — returns header-only output
+- Property-tested: column widths always `>=` max cell content width
+
+## Usage: Basic Example
+
+```ts
+import { table } from "@suaveplan/cli/output/table/table";
+
+const out = table({
+  headers: ["Name", "Role", "Since"],
+  rows: [
+    ["Alice", "Admin", "2022"],
+    ["Bob", "User", "2023"],
+  ],
+});
+console.log(out);
+// Name  │ Role  │ Since
+// ──────┼───────┼──────
+// Alice │ Admin │ 2022
+// Bob   │ User  │ 2023
+```
+
+## Usage: Advanced Example
+
+```ts
+import { table } from "@suaveplan/cli/output/table/table";
+
+const out = table({
+  headers: ["Package", "Version", "Size"],
+  rows: [
+    ["@suaveplan/error", "0.1.0", "12 kB"],
+    ["@suaveplan/cli", "0.1.0", "48 kB"],
+  ],
+  alignment: ["left", "center", "right"],
+  border: true,
+});
+console.log(out);
+```
+
+## API Reference
+
+### `table(opts: TableOptions): string`
+
+Renders the table and returns the formatted string.
+
+**`opts.headers: string[]`** — column header labels. Determines the number of columns.
+
+**`opts.rows: string[][]`** — data rows. Each row is an array of string cells. Extra cells beyond `headers.length` are ignored; missing cells are treated as empty.
+
+**`opts.alignment?: Alignment[]`** — per-column alignment (`"left"` | `"right"` | `"center"`). Defaults to `"left"` for any column not specified.
+
+**`opts.border?: boolean`** — whether to render `│` column separators and `─┼─` divider line. Default `true`.
+
+### `Alignment`
+
+`"left" | "right" | "center"` — the alignment mode for a table column.
+
+### `TableOptions`
+
+The full options type. Corresponds to `TableOptionsSchema` for Zod validation.
+
+## Implementation Notes
+
+Column widths are computed with a single `Math.max` pass over `[headers, ...rows]`. Cells are padded with `String.prototype.padEnd` (left/center) or `String.prototype.padStart` (right via the `align` helper). The divider line joins `"─".repeat(width)` segments with `"─┼─"`. When `border` is false, the divider is omitted and segments are joined with `"  "` instead of `" │ "`. Trailing whitespace on each row is trimmed to keep output clean.

docs/devtools/tooling/cli/src/parser/parser.md

@@ -0,0 +1,92 @@
+# parser
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+## Purpose
+
+The `parser` module turns a raw `argv` token array into a structured `ParsedArgs` object with typed options, named positional arguments, and a `rest` passthrough channel. It is the low-level argument-parsing engine that higher-level command definitions build on, designed to model the behaviour CLI users expect from mature tools like `git`, `npm`, and `cargo`.
+
+The module is deliberately imperative and framework-free: no reflection, no decorators, no hidden state. Every behaviour — type coercion, `--no-*` negation, short-flag resolution, choice validation, required-option checking — is enforced in a single linear pass over `argv`, and every failure mode raises a `CliError` with a stable code drawn from `CLI_CODES.PARSE.*` so callers can branch on machine-readable codes instead of message strings.
+
+## Features
+
+- Boolean flags (`--verbose`) and negation (`--no-verbose`)
+- String/number/array options via `--key value`, `--key=value`, or short-flag (`-v`) forms
+- Short-flag mapping via `short: "v"` on the option config
+- Passthrough `rest` channel after `--`
+- Variadic positionals (`<files...>`) collected as arrays
+- Required positionals and required options with dedicated error codes
+- Choice validation with `INVALID_VALUE`
+- `allowUnknown: true` to silently ignore unrecognised flags
+- Defaults for options and positionals
+- Helper parsers for flag specs (`parseOptionFlags`) and positional specs (`parseArgumentSpec`)
+
+## Usage: Basic Example
+
+```ts
+import { parseArgs } from "@suaveplan/cli/parser";
+
+const result = parseArgs(["--verbose", "src/file.ts"], {
+    options: { verbose: { type: "boolean" } },
+    arguments: [{ name: "file", required: true, variadic: false }],
+});
+
+console.log(result.options.verbose); // true
+console.log(result.positionals.file); // "src/file.ts"
+```
+
+## Usage: Advanced Example
+
+```ts
+import { parseArgs, parseOptionFlags, parseArgumentSpec } from "@suaveplan/cli/parser";
+
+const flag = parseOptionFlags("-o, --output <file>", "Output file");
+const posArg = parseArgumentSpec("<sources...>", "Source files");
+
+const result = parseArgs(
+    ["-o", "out.txt", "--format=json", "a.ts", "b.ts", "--", "--not-a-flag"],
+    {
+        options: {
+            [flag.name]: flag.config,
+            format: { type: "string", choices: ["json", "text"], default: "text" },
+            retries: { type: "number", default: 3 },
+        },
+        arguments: [posArg],
+    }
+);
+
+// result.options.output === "out.txt"
+// result.options.format === "json"
+// result.positionals.sources === ["a.ts", "b.ts"]
+// result.rest === ["--not-a-flag"]
+```
+
+## API Reference
+
+### `parseArgs(argv, config?)`
+
+- `argv: string[]` — raw CLI tokens (without the node/bun prefix)
+- `config?: ParserConfig` — optional options/arguments definitions, `allowUnknown`, `stopEarly`
+- Returns `ParsedArgs` with `options`, `positionals`, and `rest`
+- Throws `CliError` with codes `UNKNOWN_OPTION`, `MISSING_VALUE`, `INVALID_VALUE`, `MISSING_ARGUMENT`, `MISSING_REQUIRED_OPTION`
+
+### `parseOptionFlags(flags, description?, defaultValue?)`
+
+- `flags: string` — commander-style spec, e.g. `"-v, --verbose"` or `"--output <file>"`
+- Returns `{ name, config }` where `name` is the camelCased long-flag name
+- Throws `CliError(UNKNOWN_OPTION)` if no long flag is provided
+
+### `parseArgumentSpec(spec, description?)`
+
+- `spec: string` — `"<name>"`, `"[name]"`, `"<name...>"`, or `"[name...]"`
+- Returns an `ArgumentConfig` with `required`, `variadic`, `name`, and optional `description`
+
+## Implementation Notes
+
+- Single-pass state machine: tokens are consumed left-to-right with a small `restMode` flag that flips when `--` is encountered. There are no lookaheads beyond peeking at `argv[i + 1]` to decide whether a flag's value is the next token.
+- `--no-*` handling strips the literal `--no-` prefix (not the camelCased form) and then camelCases the remainder, so `--no-dry-run` correctly maps to the `dryRun` option.
+- Values are only consumed as the next token when that token does not start with `-`, preventing `--foo --bar` from stealing `--bar` as the value of `--foo`.
+- `number` type uses `Number(raw)` and rejects `NaN` so strings like `"abc"` raise `INVALID_VALUE` rather than silently becoming `NaN`.
+- All errors are `CliError` instances carrying `context` metadata (option name, offending value, allowed choices) so UIs and logs can render actionable diagnostics without re-parsing message strings.
+- Schemas mirror the TypeScript types exactly and are exported separately so callers can validate untrusted `ParserConfig` inputs at the boundary without pulling Zod into hot paths.

docs/devtools/tooling/cli/src/progress/progress.md

@@ -0,0 +1,92 @@
+# progress
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+## Purpose
+
+`createProgress` renders a fixed-width ASCII progress bar for tracking long-running operations with a known total. It writes bar updates to any `WritableStreamLike` output — TTY or non-TTY — using in-place line clearing on TTY terminals and newline-separated lines on non-TTY streams (CI, pipes). The bar updates are driven by explicit `update(current)` calls from the caller; no internal timer is used.
+
+The instance is `AbortSignal`-aware: aborting the signal silently makes all subsequent `update()` calls no-ops, allowing calling code to cancel a long operation without crashing.
+
+## Features
+
+- Fixed-width block bar with configurable `width` (default 40 characters) using `█` fill and `░` empty characters
+- Percentage and `current/total` count displayed after the bar: `[████████████░░░░░░░░] 60% (60/100)`
+- TTY mode: clears the current line and re-renders in-place via `clearLine` / `cursorTo`
+- Non-TTY mode: writes each update on its own line for readable CI output
+- `render()` returns the bar string without writing to the stream — useful for embedding in larger output
+- `complete()` forces 100% and appends a newline; idempotent (safe to call multiple times)
+- `AbortSignal` support: abort event listener marks the instance done; pre-fired signal respected via guard check in `update()`
+
+## Usage: Basic Example
+
+```ts
+import { createProgress } from "@suaveplan/cli/progress/progress";
+
+const p = createProgress({ total: 100 });
+
+for (let i = 0; i <= 100; i++) {
+  p.update(i);
+  await sleep(20);
+}
+
+p.complete();
+```
+
+## Usage: Advanced Example
+
+```ts
+import { createProgress } from "@suaveplan/cli/progress/progress";
+import { Writable } from "node:stream";
+
+const controller = new AbortController();
+const p = createProgress({
+  total: files.length,
+  width: 60,
+  signal: controller.signal,
+});
+
+let processed = 0;
+for (const file of files) {
+  if (controller.signal.aborted) break;
+  await processFile(file);
+  p.update(++processed);
+}
+
+p.complete();
+```
+
+## API Reference
+
+### `createProgress(opts: ProgressOptions): ProgressInstance`
+
+Creates a progress bar instance. No output is written until `update()` or `complete()` is called.
+
+**`opts.total: number`** — the maximum value (100%). Must be positive.
+
+**`opts.width?: number`** — width of the bar in characters (default `40`).
+
+**`opts.stream?: WritableStreamLike`** — output target (default `process.stdout`). TTY in-place rendering requires `clearLine` and `cursorTo` methods plus `isTTY === true`.
+
+**`opts.signal?: AbortSignal`** — when aborted, future `update()` calls become no-ops and the bar stops advancing.
+
+### `ProgressInstance`
+
+**`update(current: number): void`** — updates the displayed progress to `current`. Values are clamped to `[0, total]`. No-op if `complete()` was already called or the signal was aborted.
+
+**`complete(): void`** — writes a 100% bar with a trailing newline and marks the instance done. Idempotent.
+
+**`render(): string`** — returns the current bar string without writing to the stream.
+
+### `ProgressOptionsSchema`
+
+Zod schema for `ProgressOptions` — validates `total` (positive number) and `width` (optional positive number). Excludes `stream` and `signal`.
+
+### `WritableStreamLike`
+
+Re-exported from `../spinner/spinner.types.js`. Any object with `write(text: string): void` satisfies this interface; `clearLine`, `cursorTo`, and `isTTY` are optional and enable TTY mode when present.
+
+## Implementation Notes
+
+Progress percentage is computed as `Math.min(1, current / total)` to handle over-total updates gracefully. The filled block count is `Math.round(pct * width)` — rounding avoids a full-bar display at 99% on small widths. The `complete()` guard (`done` flag) prevents double-writes when called multiple times. The `AbortSignal` listener uses `{ once: true }` so it self-removes after the first event.

docs/devtools/tooling/cli/src/prompt/prompt.md

@@ -0,0 +1,95 @@
+# prompt
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+## Purpose
+
+`prompt` provides a collection of pure, injectable interactive prompt functions for CLI applications: `text`, `password`, `confirm`, `select`, and `multiselect`. All five functions accept an `InputReader` as their last argument for testing and embedding — callers supply any object with `question(prompt): Promise<string>` and `close(): void`. In production, `createDefaultReader()` builds an `InputReader` backed by `@suaveplan/readline/interface`, which in turn reads from `process.stdin`.
+
+Prompt functions are asynchronous, loop-safe, and validation-aware. They re-prompt on invalid input rather than throwing, keeping the user experience coherent across all terminal types.
+
+## Features
+
+- `text(opts, reader?)` — free-form text input with optional default and validation callback
+- `password(opts, reader?)` — masked input (structurally identical to text; masking is delegated to the terminal emulator or TTY mode)
+- `confirm(opts, reader?)` — yes/no boolean with optional default; accepts `y`, `yes`, `n`, `no` (case-insensitive)
+- `select(opts, reader?)` — numbered single-choice list; re-prompts on out-of-range input
+- `multiselect(opts, reader?)` — comma-separated multi-choice with configurable `min`/`max` and deduplication
+- `createDefaultReader()` — async factory returning an `InputReader` wired to `process.stdin` via `@suaveplan/readline`
+- All functions accept both a plain `string` message or a full options object for brevity
+
+## Usage: Basic Example
+
+```ts
+import { confirm, select, text } from "@suaveplan/cli/prompt/prompt";
+
+const name = await text("Your name?");
+const confirmed = await confirm({ message: "Continue?", default: true });
+const role = await select({ message: "Pick a role:", choices: ["admin", "user", "guest"] });
+
+console.log(name, confirmed, role);
+```
+
+## Usage: Advanced Example
+
+```ts
+import { multiselect, text } from "@suaveplan/cli/prompt/prompt";
+import type { InputReader } from "@suaveplan/cli/prompt/prompt";
+
+// Inject a reader for testing
+function mockReader(lines: string[]): InputReader {
+  let i = 0;
+  return { question: async () => lines[i++] ?? "", close: () => {} };
+}
+
+const username = await text(
+  { message: "Username?", validate: (v) => v.length >= 3 || "at least 3 chars" },
+  mockReader(["ab", "alice"]),
+);
+
+const features = await multiselect(
+  { message: "Enable features:", choices: ["logging", "metrics", "tracing"], min: 1 },
+  mockReader(["1,2"]),
+);
+
+console.log(username, features);
+```
+
+## API Reference
+
+### `text(opts: TextPromptOptions | string, reader?: InputReader): Promise<string>`
+
+Prompts for free-form text. When `opts` is a string it is used as the `message`. Returns the user's input or `opts.default` if the input is empty and a default is set. Re-prompts if `opts.validate` returns an error string.
+
+### `password(opts: PasswordPromptOptions | string, reader?: InputReader): Promise<string>`
+
+Identical interface to `text` but semantically for secret input. The caller is responsible for disabling echo on the actual terminal if needed.
+
+### `confirm(opts: ConfirmPromptOptions | string, reader?: InputReader): Promise<boolean>`
+
+Prompts for a yes/no answer. Accepts `y`, `yes`, `n`, `no` (case-insensitive). Returns `opts.default` when the user submits an empty line and a default is configured. Re-prompts on unrecognized input.
+
+### `select<T>(opts: SelectPromptOptions<T>, reader?: InputReader): Promise<T>`
+
+Displays a numbered list of choices and returns the `value` of the selected entry. Choices may be plain strings (label = value) or `SelectChoice<T>` objects. Re-prompts when the entered number is out of range.
+
+### `multiselect<T>(opts: MultiSelectPromptOptions<T>, reader?: InputReader): Promise<T[]>`
+
+Displays a numbered list and accepts comma-separated indices. Deduplicates repeated indices. Enforces `opts.min` / `opts.max` bounds and re-prompts when any index is invalid or the count is out of bounds.
+
+### `createDefaultReader(): Promise<InputReader>`
+
+Async factory that lazily imports `@suaveplan/readline/interface` and wires it to `process.stdin` / `process.stdout`. Returns an `InputReader`. The caller is responsible for calling `close()` when done.
+
+### `InputReader`
+
+Injectable interface: `{ question(prompt: string): Promise<string>; close(): void; }`. Pass a mock for tests.
+
+### `TextPromptOptionsSchema`, `ConfirmPromptOptionsSchema`, `SelectChoiceSchema`
+
+Zod schemas for the corresponding option types — useful for config-file driven prompts.
+
+## Implementation Notes
+
+All prompt functions manage the reader lifecycle when no reader is injected: they call `createDefaultReader()` in a `try/finally` block that calls `close()` after the prompt resolves. When a reader is injected, the caller owns the lifecycle. Validation callbacks return either `true` (pass) or an error string (fail); the error is written to `process.stderr` before re-prompting. The `multiselect` function considers any out-of-range index a hard error and re-prompts rather than silently discarding it.

docs/devtools/tooling/cli/src/spinner/spinner.md

@@ -0,0 +1,99 @@
+# spinner
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+## Purpose
+
+`createSpinner` renders an animated terminal spinner for long-running operations. It writes a spinning frame animation to any `WritableStreamLike` output — TTY or non-TTY — and exposes a chainable API to start, stop, succeed, fail, or warn when the operation resolves. The spinner integrates with `AbortSignal` so it can be cancelled programmatically without leaking timers.
+
+The spinner is entirely synchronous after creation. No promises are used internally — the animation is driven by a `setInterval` timer that is always cancelled on `stop()`.
+
+## Features
+
+- Animated frame loop with configurable frames array and interval (default 80ms, 10-frame braille spinner)
+- Chainable API: `start().succeed()`, `start().fail()`, `start().warn()`, `start().stop()`
+- TTY mode: clears current line and re-renders in-place via `clearLine`/`cursorTo`
+- Non-TTY mode (CI/pipes): writes each frame on its own line — no escape codes
+- `AbortSignal` support: live abort event listener (`"abort"`) stops the spinner; pre-fired abort prevents `start()` entirely
+- `succeed` / `fail` / `warn` write a terminal symbol (`✔` / `✖` / `⚠`) followed by the text
+- `update(text)` changes the displayed text without restarting the animation
+
+## Usage: Basic Example
+
+```ts
+import { createSpinner } from "@suaveplan/cli/spinner/spinner";
+
+const sp = createSpinner({ text: "Fetching data…" });
+sp.start();
+await fetchData();
+sp.succeed("Done!");
+```
+
+## Usage: Advanced Example
+
+```ts
+import { createSpinner } from "@suaveplan/cli/spinner/spinner";
+
+const controller = new AbortController();
+const sp = createSpinner({
+  text: "Building…",
+  frames: ["-", "\\", "|", "/"],
+  interval: 120,
+  signal: controller.signal,
+});
+
+sp.start();
+setTimeout(() => controller.abort(), 5000); // cancel after 5 s
+
+try {
+  await runBuild();
+  sp.succeed("Build complete");
+} catch {
+  sp.fail("Build failed");
+}
+```
+
+## API Reference
+
+### `createSpinner(opts?: SpinnerOptions): SpinnerInstance`
+
+Creates and returns a spinner instance. No animation starts until `start()` is called.
+
+**`opts.text?: string`** — initial text displayed next to the spinner frame (default `""`).
+
+**`opts.frames?: string[]`** — animation frame sequence (default: 10-step braille pattern).
+
+**`opts.interval?: number`** — milliseconds between frame advances (default `80`).
+
+**`opts.stream?: WritableStreamLike`** — output target (default `process.stdout`). Any object with a `write()` method is accepted; TTY-specific methods (`clearLine`, `cursorTo`) are optional.
+
+**`opts.signal?: AbortSignal`** — when aborted, calls `stop()` immediately. If already aborted at construction time, `start()` becomes a no-op.
+
+### `SpinnerInstance`
+
+**`isSpinning: boolean`** — `true` between `start()` and `stop()`.
+
+**`start(text?: string): SpinnerInstance`** — begins animation. If a `text` argument is provided, updates the displayed text before starting. No-op if already spinning or if the signal is pre-aborted.
+
+**`stop(): SpinnerInstance`** — stops animation and clears the line (TTY only). No-op if not spinning.
+
+**`succeed(text?: string): SpinnerInstance`** — calls `stop()` then writes `✔ <text>` (falls back to current text).
+
+**`fail(text?: string): SpinnerInstance`** — calls `stop()` then writes `✖ <text>`.
+
+**`warn(text?: string): SpinnerInstance`** — calls `stop()` then writes `⚠ <text>`.
+
+**`update(text: string): SpinnerInstance`** — replaces the displayed text without interrupting animation.
+
+### `SpinnerOptionsSchema`
+
+Zod schema for `SpinnerOptions` — validates `text`, `frames`, and `interval` (excludes `stream` and `signal` which are not Zod-serialisable).
+
+### `WritableStreamLike`
+
+Minimal interface for the `stream` option: any object with `write(text: string): void`. The optional `clearLine`, `cursorTo`, and `isTTY` members enable TTY in-place rendering when present.
+
+## Implementation Notes
+
+The TTY branch detects `stream.isTTY === true` at construction time and uses `clearLine(0)` + `cursorTo(0)` + `write(frame + " " + text)` on each tick. The non-TTY branch appends a newline to each frame write so CI logs remain readable. The `setInterval` is stored and cleared in `stop()` to prevent timer leaks; calling `stop()` when not spinning is a safe no-op. The `AbortSignal` listener uses `{ once: true }` so it self-removes after the first abort event.

docs/devtools/tooling/cli/src/style/style.md

@@ -0,0 +1,82 @@
+# style
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+## Purpose
+
+`style` provides terminal ANSI colour and text-decoration utilities for `@suaveplan/cli`. It wraps text in ANSI escape sequences for modifiers (bold, dim, italic, underline, strikethrough) and colours (foreground and background). The module is colour-support-aware: when the terminal does not support colour, all styling is bypassed and plain text is returned unchanged.
+
+The design uses a `Proxy`-based fluent builder that allows infinite chaining of style codes — `style.bold.red.underline("text")` — without allocating intermediate strings until the final call.
+
+## Features
+
+- 24 style codes: 6 modifiers, 9 foreground colours, 1 gray, 8 background colours
+- `createStyler(enabled?)` — factory for a fresh styler instance, injectable colour flag for testing
+- `style` — singleton styler wired to `isColorSupported()` at module load time
+- `stripAnsi(text)` — removes all ANSI escape sequences from a string
+- `isColorSupported()` — returns `true` when stdout is a TTY or `FORCE_COLOR` is set
+- `getStyleNames()` — returns the list of all valid style code names
+- Proxy-based chaining: `style.bold.red.underline("x")` composes all codes in a single call
+- Disabled mode: `createStyler(false)` returns identity function — no allocation overhead
+- Zero runtime dependencies outside the package
+
+## Usage: Basic Example
+
+```ts
+import { style } from "@suaveplan/cli/style/style";
+
+console.log(style.bold("Build complete"));
+console.log(style.red("Error occurred"));
+console.log(style.green.bold("✓ Tests passed"));
+```
+
+## Usage: Advanced Example
+
+```ts
+import { createStyler, isColorSupported, stripAnsi } from "@suaveplan/cli/style/style";
+
+// Inject colour support for testing
+const s = createStyler(process.env.CI !== "true");
+
+function label(text: string, type: "info" | "warn" | "error"): string {
+  if (type === "error") return s.bold.red(`[ERROR] ${text}`);
+  if (type === "warn")  return s.yellow(`[WARN]  ${text}`);
+  return s.cyan(`[INFO]  ${text}`);
+}
+
+console.log(label("Connection timed out", "error"));
+
+// Strip for log files
+const plain = stripAnsi(label("hello", "info"));
+```
+
+## API Reference
+
+### `createStyler(enabled?: boolean): Styler`
+
+Creates a new styler instance. `enabled` defaults to `isColorSupported()`. Returns a `Styler` (Proxy) that composes ANSI codes on chained property access and applies them on call.
+
+### `style: Styler`
+
+Pre-built singleton styler bound to the current terminal's colour support. Use this for production output.
+
+### `stripAnsi(text: string): string`
+
+Strips all ANSI escape sequences from `text`. Safe for log files and length calculations.
+
+### `isColorSupported(): boolean`
+
+Returns `true` when `process.stdout.isTTY` is true or `FORCE_COLOR` env var is set.
+
+### `getStyleNames(): StyleCode[]`
+
+Returns the array of all known style code names in order.
+
+### `Styler`
+
+A callable type with all style codes as chainable properties. Calling it with a string applies all accumulated codes and returns the styled string.
+
+## Implementation Notes
+
+The `Proxy` trap intercepts property access on the styler function itself, returning a new `Proxy`-wrapped function with the accessed code appended to the accumulated stack. This avoids the class-per-style-combination explosion of naive implementations. Opening and closing ANSI codes are concatenated from the stack at call time. The `reset` code (`\x1b[0m`) is handled like any other code — callers can chain `.reset` to reset all styles.

docs/devtools/tooling/electrobun/README.md

@@ -0,0 +1,151 @@
+# @suaveplan/electrobun - Electrobun desktop-app generator + orchestrator: scaffolds projects, generates icons, drives dev/build/package/sign commands via an injectable runner. Typed ELECTROBUN_CODES, Zod-validated options, OTel self-telemetry.
+
+Electrobun desktop-app generator and orchestrator for the SuavePlan
+ecosystem. Scaffolds a fresh Electrobun project from a layered config +
+prompt flow, drives the upstream `electrobun` binary for dev / build /
+package / sign, and emits structured reports + OpenTelemetry metrics for
+every operation.
+
+<!-- begin:auto-docs -->
+## Documentation tree
+
+- [bin](./src/bin/suaveplan-electrobun.md) — Single-file binary that wires `process.argv` into the pure `runCli` dispatcher and translates the resolved exit code in…
+  - [suaveplan-electrobun](./src/bin/suaveplan-electrobun.md) — Single-file binary that wires `process.argv` into the pure `runCli` dispatcher and translates the resolved exit code in…
+- [cli](./src/cli/cli.md) — Owns the five command surfaces — `createCommand`, `devCommand`, `buildCommand`, `packageCommand`, `signCommand` — plus…
+  - [cli](./src/cli/cli.md) — Owns the five command surfaces — `createCommand`, `devCommand`, `buildCommand`, `packageCommand`, `signCommand` — plus…
+- [config](./src/config/config.md) — `loadConfig(cliArgs, deps?)` builds an `ElectrobunConfig` by layering hard-coded defaults, an optional on-disk `.suavep…
+  - [config](./src/config/config.md) — `loadConfig(cliArgs, deps?)` builds an `ElectrobunConfig` by layering hard-coded defaults, an optional on-disk `.suavep…
+- [error-codes](./src/error-codes/error-codes.md) — Owns the stable `ELECTROBUN.*` error-code namespace and the `ElectrobunError` class that every public entry point throw…
+  - [error-codes](./src/error-codes/error-codes.md) — Owns the stable `ELECTROBUN.*` error-code namespace and the `ElectrobunError` class that every public entry point throw…
+- [fs](./src/fs/fs.md) — Owns the `FsAdapter` seam and the synchronous `ConfigDiscoveryAdapter` used by the layered-config loader. Every IO-touc…
+  - [fs](./src/fs/fs.md) — Owns the `FsAdapter` seam and the synchronous `ConfigDiscoveryAdapter` used by the layered-config loader. Every IO-touc…
+- [generator](./src/generator/generator.md) — Owns the two-call surface that scaffolds an Electrobun project on disk. `collectFiles(options, overrides?)` is pure — i…
+  - [generator](./src/generator/generator.md) — Owns the two-call surface that scaffolds an Electrobun project on disk. `collectFiles(options, overrides?)` is pure — i…
+- [icons](./src/icons/icons.md) — Wraps the upstream `iconz` library behind an `IconRendererAdapter` seam so the generator can run the icon-generation pi…
+  - [icons](./src/icons/icons.md) — Wraps the upstream `iconz` library behind an `IconRendererAdapter` seam so the generator can run the icon-generation pi…
+- [prompts](./src/prompts/prompts.md) — Owns the interactive scaffolder that backs the CLI's `create` command. `runPrompts(config, outputDir, prompter)` walks…
+  - [prompts](./src/prompts/prompts.md) — Owns the interactive scaffolder that backs the CLI's `create` command. `runPrompts(config, outputDir, prompter)` walks…
+- [runner](./src/runner/runner.md) — Owns the `CommandRunner` seam that every electrobun shell-out flows through, plus the `probeElectrobun` and `invokeElec…
+  - [runner](./src/runner/runner.md) — Owns the `CommandRunner` seam that every electrobun shell-out flows through, plus the `probeElectrobun` and `invokeElec…
+- [schemas](./src/schemas/schemas.md) — Owns the Zod schemas that gate every public boundary of `@suaveplan/electrobun`. Each interface in `src/types/electrobu…
+  - [schemas](./src/schemas/schemas.md) — Owns the Zod schemas that gate every public boundary of `@suaveplan/electrobun`. Each interface in `src/types/electrobu…
+- [telemetry](./src/telemetry/telemetry.md) — Owns the OpenTelemetry surface for `@suaveplan/electrobun`. Every public entry point that does observable work (project…
+  - [telemetry](./src/telemetry/telemetry.md) — Owns the OpenTelemetry surface for `@suaveplan/electrobun`. Every public entry point that does observable work (project…
+- [templates](./src/templates/templates.md) — Owns every renderer that produces a project-level file in the scaffolded output: `electrobun.config.ts`, `package.json`…
+  - [features](./src/templates/features.md) — Owns every renderer that produces a per-feature file in the scaffolded output: `i18n`, `networking` (basic + full), `ap…
+  - [templates](./src/templates/templates.md) — Owns every renderer that produces a project-level file in the scaffolded output: `electrobun.config.ts`, `package.json`…
+<!-- end:auto-docs -->
+
+## Features
+
+- **Five-command CLI**: `create`, `dev`, `build`, `package`, `sign`.
+- **Layered config**: defaults + `.suaveplan-electrobun.json` + CLI args
+  via `@suaveplan/config`.
+- **Injectable seams**: `FsAdapter`, `CommandRunner`,
+  `IconRendererAdapter`, `Prompter` — every IO path is testable without
+  `vi.mock`.
+- **Zod-validated options** at every public boundary; bad input fails as
+  `ELECTROBUN.INVALID_OPTIONS`.
+- **Eleven typed error codes** under the `ELECTROBUN.*` namespace.
+- **OpenTelemetry**: five counters + two histograms on the
+  `@suaveplan/electrobun` meter.
+- **iconz integration** for `.icns` / `.ico` / `.png` icon generation.
+- **Auto-update bundling** via the `--update` flag on `build`.
+- **Code-signing pipeline** via `sign --identity --entitlements
+  --notarize` (the wrapper shapes argv; signing certificates remain in
+  the user's keychain).
+- **Eight feature renderers** (`i18n`, `networking` × basic/full, `api`,
+  `api-schemas`, `storage`, `auth`, `form-builder`, `r3f` with five
+  modules).
+
+## Installation
+
+```bash
+bun add @suaveplan/electrobun
+```
+
+The package ships a `suaveplan-electrobun` binary:
+
+```bash
+suaveplan-electrobun --help
+```
+
+## Usage
+
+### Scaffold a new project
+
+```bash
+suaveplan-electrobun create my-app --skip-prompts \
+    --name my-app --id com.example.my-app --icon ./assets/icon.png
+```
+
+### Interactive scaffold
+
+```bash
+suaveplan-electrobun create ./my-app
+```
+
+### Dev / build / package / sign
+
+```bash
+suaveplan-electrobun dev --cwd ./my-app
+suaveplan-electrobun build --cwd ./my-app --target mac --update
+suaveplan-electrobun package --cwd ./my-app --target mac
+suaveplan-electrobun sign --cwd ./my-app \
+    --identity "Developer ID Application: ..." \
+    --entitlements ./entitlements.plist --notarize
+```
+
+### Programmatic use
+
+```ts
+import {
+    buildCommand,
+    createCommand,
+    generate,
+    runCli,
+} from "@suaveplan/electrobun";
+
+const report = await generate({
+    name: "my-app",
+    identifier: "com.example.my-app",
+    description: "A demo",
+    version: "0.1.0",
+    outputDir: "./my-app",
+    features: ["i18n", "api"],
+    networkingComplexity: "basic",
+    r3fModules: [],
+});
+```
+
+## Subpath exports
+
+| Subpath | Surface |
+|---|---|
+| `@suaveplan/electrobun` | Full barrel |
+| `@suaveplan/electrobun/cli` | Five command functions + `runCli` |
+| `@suaveplan/electrobun/config` | `loadConfig`, defaults |
+| `@suaveplan/electrobun/error-codes` | `ELECTROBUN_CODES`, `ElectrobunError` |
+| `@suaveplan/electrobun/fs` | `FsAdapter`, `nodeFsAdapter`, file helpers |
+| `@suaveplan/electrobun/generator` | `collectFiles`, `generate` |
+| `@suaveplan/electrobun/icons` | `generateIcons`, `iconzRendererAdapter` |
+| `@suaveplan/electrobun/prompts` | `runPrompts` |
+| `@suaveplan/electrobun/runner` | `CommandRunner`, `probeElectrobun`, `invokeElectrobun` |
+| `@suaveplan/electrobun/schemas` | Zod schemas + `parseOrThrow` |
+| `@suaveplan/electrobun/telemetry` | OTel counters + histograms |
+| `@suaveplan/electrobun/templates` | Project + feature renderers |
+| `@suaveplan/electrobun/types` | Shared types + `FEATURE_ORDER` |
+
+## Error codes
+
+The full `ELECTROBUN.*` registry:
+
+`INVALID_OPTIONS`, `OUTPUT_NOT_EMPTY`, `CONFIG_PARSE_FAILED`,
+`ICON_SOURCE_MISSING`, `ICON_RENDER_FAILED`, `TEMPLATE_RENDER_FAILED`,
+`FS_WRITE_FAILED`, `BINARY_UNAVAILABLE`, `RUNNER_FAILED`,
+`PROMPT_ABORTED`, `UNKNOWN_FLAG`.
+
+## License
+
+MIT — see the repository root.
+

docs/devtools/tooling/electrobun/src/bin/suaveplan-electrobun.md

@@ -0,0 +1,65 @@
+# Binary entry — `suaveplan-electrobun.ts`
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+Single-file binary that wires `process.argv` into the pure `runCli`
+dispatcher and translates the resolved exit code into a real
+`process.exit` call. All business logic lives in `src/cli/cli.ts`; this
+file is the only place that talks to the process boundary, which makes
+the rest of the package fully unit-testable.
+
+The binary registers the `@suaveplan/cli` prompt primitives as the
+`Prompter` so the interactive `create` flow works against a real TTY
+when run by hand. Tests that exercise the CLI never load this file —
+they call `runCli` directly with a scripted prompter and a recording
+runner.
+
+## Features
+
+- One-line wiring from `process.argv` to `runCli`.
+- Real TTY prompts via `@suaveplan/cli/prompt/prompt`.
+- Exit code translation: `runCli` resolves `{ code }`, the binary calls
+  `process.exit(code)`.
+- Unexpected exceptions print to stderr and exit with `code: 2`.
+
+## Usage: Basic
+
+```bash
+suaveplan-electrobun create my-app --skip-prompts --name my-app
+suaveplan-electrobun dev --cwd ./my-app
+suaveplan-electrobun build --cwd ./my-app --target mac --update
+suaveplan-electrobun package --cwd ./my-app --target mac
+suaveplan-electrobun sign --cwd ./my-app --identity "Dev ID Application: …"
+```
+
+## Usage: Advanced
+
+```bash
+# Use the layered config file at $HOME/.suaveplan-electrobun.json
+# combined with project-level overrides
+suaveplan-electrobun create --name override-app --skip-prompts ./out
+```
+
+## API Reference
+
+- The binary takes no programmatic API. It accepts the argv shape
+  documented in `src/cli/cli.ts::HELP_TEXT`.
+
+## Implementation Notes
+
+The binary is excluded from the coverage thresholds in
+`vitest.config.ts` because its only logic is `runCli(...).then(...,
+...)` — the unit tests for `runCli` cover every reachable branch, and
+the only paths that are unique to the binary are the `process.exit`
+calls themselves. Excluding the file from coverage keeps the gate
+honest without forcing a contrived "spawn a subprocess and assert on
+exit code" test that would not catch anything the unit tests miss.
+
+The binary uses `process.argv.slice(2)` rather than `process.argv` so
+the node executable path and script path are stripped before the
+parser sees them. The dispatcher's parser treats every remaining token
+as a user-supplied flag, subcommand, or positional argument.

docs/devtools/tooling/electrobun/src/cli/cli.md

@@ -0,0 +1,100 @@
+# CLI — `cli.ts`
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+Owns the five command surfaces — `createCommand`, `devCommand`,
+`buildCommand`, `packageCommand`, `signCommand` — plus the
+`runCli(argv, deps?)` dispatcher that the published binary delegates to.
+Every command is a pure function: it validates its option struct against
+the matching Zod schema, runs the orchestrated work, and returns a typed
+report. `runCli` never calls `process.exit`; the only exit-call lives in
+`src/bin/suaveplan-electrobun.ts`, so the entire CLI is unit-testable
+without a child process.
+
+`createCommand` is the scaffolder entry: it loads the layered config,
+applies CLI overrides, optionally runs the prompt flow, then hands off
+to `generate`. The other four commands are runner-only — they probe the
+upstream `electrobun` binary, raise `ELECTROBUN.BINARY_UNAVAILABLE` when
+missing, spawn the binary with the canonical argv, and return a
+`CommandReport` carrying exit code, stdout, stderr, and duration.
+
+## Features
+
+- Five command functions, each with Zod-validated options and structured
+  reports.
+- Pure `runCli(argv)` dispatcher with `--help` / `-h` short-circuit and
+  closed-set flag parsing.
+- Long-flag `--key=value` and `--key value` forms supported uniformly.
+- Unknown flags / subcommands raise `ELECTROBUN.UNKNOWN_FLAG`.
+- Missing required values raise `ELECTROBUN.INVALID_OPTIONS`.
+- `timeRunner` wrapper increments invocation + duration histograms per
+  call and increments failure counters on `ElectrobunError` paths.
+
+## Usage: Basic
+
+```ts
+import { runCli } from "@suaveplan/electrobun/cli";
+
+const { code } = await runCli(process.argv.slice(2));
+process.exit(code);
+```
+
+## Usage: Advanced
+
+```ts
+import { buildCommand } from "@suaveplan/electrobun/cli";
+import type { CommandRunner } from "@suaveplan/electrobun/types";
+
+const customRunner: CommandRunner = async (input) => {
+    // ship the spawn to a remote CI worker
+    return await postToWorker(input);
+};
+const report = await buildCommand(
+    { cwd: "/proj", target: "linux", update: true },
+    { runner: customRunner }
+);
+```
+
+## API Reference
+
+- `createCommand(opts: CreateCommandOptions, deps: CommandDeps & {
+  prompter: Prompter }): Promise<GenerateReport>`.
+- `devCommand(opts: DevCommandOptions, deps?: { runner? }):
+  Promise<CommandReport>`.
+- `buildCommand(opts: BuildCommandOptions, deps?: { runner? }):
+  Promise<CommandReport>`.
+- `packageCommand(opts: PackageCommandOptions, deps?: { runner? }):
+  Promise<CommandReport>`.
+- `signCommand(opts: SignCommandOptions, deps?: { runner? }):
+  Promise<CommandReport>`.
+- `runCli(argv: readonly string[], deps?: RunCliOptions): Promise<{
+  code: number }>`.
+- `HELP_TEXT: string` — the full help banner.
+
+## Implementation Notes
+
+The arg parser uses a closed `ALL_KNOWN_FLAGS` set. New flags must be
+added to the set before the parser will accept them; an unknown flag
+fails the run with `ELECTROBUN.UNKNOWN_FLAG`, which keeps subtle typos
+from being silently swallowed. The `--help` and `-h` short forms are
+intercepted before subcommand dispatch so they work uniformly across
+every subcommand.
+
+`runCli` catches every `ElectrobunError` and folds it into `code: 1`
+with a one-line stderr message. Any other thrown value re-propagates,
+on the principle that the runtime should not eat unexpected exceptions
+— if something other than a typed error escapes the call, the bin
+wrapper surfaces it with `code: 2`.
+
+The `timeRunner` helper increments `electrobun_runner_invocations_total`
+on entry, records the duration histogram on every exit (success or
+failure), and records `electrobun_runner_failures_total` when the thrown
+`ElectrobunError` carries a numeric `details.exitCode`. The failure
+counter labels the exit code with `-1` when no numeric exit-code is
+available — for instance when the probe stage raises
+`BINARY_UNAVAILABLE` — so dashboards can still attribute the failure
+to the right command without inventing fake exit codes.

docs/devtools/tooling/electrobun/src/config/config.md

@@ -0,0 +1,82 @@
+# Config loader — `config.ts`
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+`loadConfig(cliArgs, deps?)` builds an `ElectrobunConfig` by layering
+hard-coded defaults, an optional on-disk `.suaveplan-electrobun.json`,
+and CLI argument overrides on top of one another. The loader sits on
+`@suaveplan/config`'s five-layer pipeline (defaults / file / object /
+env / CLI), wiring three of the five for the scaffolder's needs.
+
+The `--name`, `--id`, `--icon`, and `--version` CLI flags map to the
+`name`, `identifier`, `iconSource`, and `version` fields respectively.
+Defaults fill `version="0.0.1"`, `features=[]`,
+`networkingComplexity="basic"`, and `r3fModules=[]` so callers can rely
+on the final shape having those fields populated even when no file or
+flag supplies them.
+
+The `ConfigDiscoveryAdapter` seam (defined in `src/fs/fs.ts`) controls
+where the loader looks for the config file. Tests inject an in-memory
+adapter; production code uses the default `nodeConfigDiscoveryAdapter`
+that probes `process.cwd()` then `homedir()` via real `node:fs` calls.
+
+## Features
+
+- Three-layer build: defaults → file → CLI.
+- Synchronous (no async lift required by callers).
+- Wraps malformed JSON as `ELECTROBUN.CONFIG_PARSE_FAILED`.
+- Pluggable file discovery through `ConfigDiscoveryAdapter`.
+- Exported `CLI_MAPPING` constant so consumers can introspect the flag
+  set (used by the `--help` text builder).
+
+## Usage: Basic
+
+```ts
+import { loadConfig } from "@suaveplan/electrobun/config";
+
+const cfg = loadConfig(process.argv.slice(2));
+console.log(cfg.name ?? "(no name set)");
+```
+
+## Usage: Advanced
+
+```ts
+import { loadConfig } from "@suaveplan/electrobun/config";
+import type { ConfigDiscoveryAdapter } from "@suaveplan/electrobun/fs";
+
+const inMemory: ConfigDiscoveryAdapter = {
+    cwd: () => "/proj",
+    homedir: () => "/home/user",
+    exists: (p) => p === "/proj/.suaveplan-electrobun.json",
+    readFile: () => JSON.stringify({ name: "ci-app", features: ["api"] }),
+};
+const cfg = loadConfig(["--icon", "/icons/app.png"], {
+    discovery: inMemory,
+});
+// cfg.name === "ci-app"; cfg.iconSource === "/icons/app.png"
+```
+
+## API Reference
+
+- `loadConfig(cliArgs: readonly string[] = [], deps?: { discovery?:
+  ConfigDiscoveryAdapter }): ElectrobunConfig`.
+- `HARDCODED_DEFAULTS: ElectrobunConfig` — frozen defaults applied at
+  the bottom of the layer stack.
+- `CLI_MAPPING: Record<string, string>` — exact flag-to-field mapping
+  used by the CLI layer.
+
+## Implementation Notes
+
+`@suaveplan/config`'s `cliLayer` takes mapping keys without the leading
+`--`; the constants here mirror that contract verbatim. `coerceValue`
+inside the cli layer parses booleans, numbers, and JSON literals, so a
+caller can pass `--features '["api","i18n"]'` and have the array land
+on the right field without bespoke wiring.
+
+The file layer is skipped entirely when `findConfigFile` returns
+`undefined`. This keeps the layer stack short for the common "no config
+file" case and avoids a no-op fileLayer reload subscription.

docs/devtools/tooling/electrobun/src/error-codes/error-codes.md

@@ -0,0 +1,93 @@
+# Error codes — `error-codes.ts`
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+Owns the stable `ELECTROBUN.*` error-code namespace and the
+`ElectrobunError` class that every public entry point throws on failure.
+The registry is produced by `@suaveplan/error`'s `defineCodes("ELECTROBUN",
+[...])` so each code is a plain `ELECTROBUN.<REASON>` string that survives
+serialisation across worker / RPC / log-shipping boundaries — consumers
+discriminate on `error.code` instead of `instanceof`, which means
+incidents land in a single switch statement regardless of where the
+failure originated.
+
+The eleven codes cover every observable failure path in the package:
+boundary validation, output-directory collision, malformed config files,
+missing or unrenderable icon sources, template renderer crashes, fs
+write failures, an unavailable `electrobun` binary, a non-zero exit from
+the orchestrated runner, a user-aborted prompt, and an unknown CLI flag
+or subcommand. Each code is paired with at least one call site exercised
+by the package's tests; the conformance gate fails the build if
+any code becomes unreachable.
+
+## Features
+
+- `ELECTROBUN_CODES` frozen-string registry of eleven codes.
+- `ElectrobunError` extending `SuaveplanError<ElectrobunCode>`.
+- `details: Record<string, unknown>` payload preserved through
+  `SuaveplanError.context`.
+- `cause` chaining for native error wrappers without losing the original
+  stack.
+
+## Usage: Basic
+
+```ts
+import { ELECTROBUN_CODES, ElectrobunError } from "@suaveplan/electrobun/error-codes";
+
+throw new ElectrobunError(
+    ELECTROBUN_CODES.INVALID_OPTIONS,
+    "name must be a non-empty string"
+);
+```
+
+## Usage: Advanced
+
+```ts
+import { ELECTROBUN_CODES, ElectrobunError } from "@suaveplan/electrobun/error-codes";
+
+try {
+    await runSomething();
+} catch (cause) {
+    throw new ElectrobunError(
+        ELECTROBUN_CODES.RUNNER_FAILED,
+        "electrobun build exited 2",
+        {
+            cause,
+            details: {
+                command: "build",
+                exitCode: 2,
+                stderr: "missing entitlements",
+            },
+        }
+    );
+}
+```
+
+## API Reference
+
+- `ELECTROBUN_CODES: Readonly<{...}>` — frozen registry of code strings.
+  Every value is `"ELECTROBUN." + <REASON>`.
+- `ElectrobunCode = typeof ELECTROBUN_CODES[keyof typeof
+  ELECTROBUN_CODES]` — the literal-union code type.
+- `class ElectrobunError extends SuaveplanError<ElectrobunCode>` with
+  fields `code`, `message`, `details`, and `cause`.
+- `ElectrobunErrorOptions = { cause?: unknown; details?: Record<string,
+  unknown> }`.
+
+## Implementation Notes
+
+The constructor forwards `details` through `SuaveplanError.context` so the
+serialised wire format (the `error.toJSON()` shape produced by
+`@suaveplan/error`) carries the diagnostic payload alongside the code.
+Consumers reading the wire format pull `code` and `context` and never
+need to deserialise an `Error` subclass.
+
+`cause` is only set when the caller supplies it — passing `undefined`
+elides the field rather than leaving an explicit `cause: undefined` that
+would defeat downstream cause-chain walkers. The same pattern is used
+across `@suaveplan/linter` and `@suaveplan/installer`; keeping the shape
+identical reduces the cognitive load of moving between packages.

docs/devtools/tooling/electrobun/src/fs/fs.md

@@ -0,0 +1,104 @@
+# Filesystem adapters — `fs.ts`
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+Owns the `FsAdapter` seam and the synchronous `ConfigDiscoveryAdapter`
+used by the layered-config loader. Every IO-touching helper in the
+package routes through one of these contracts so tests can stand in a
+fake adapter without resorting to `vi.mock`, and so production code can
+swap in a real-fs adapter wired through a test container or a mounted
+overlay when the situation calls for it.
+
+The default `nodeFsAdapter` round-trips strings as UTF-8 through
+`node:fs/promises`. The default `nodeConfigDiscoveryAdapter` uses
+`node:fs`'s sync `existsSync` / `readFileSync` plus the `node:os`
+`homedir` and `process.cwd()` calls — sync paths are limited to the
+single one-off discovery pass during `loadConfig`, and every other write
+path is async through the adapter seam.
+
+## Features
+
+- `nodeFsAdapter` — full `FsAdapter` implementation backed by
+  `node:fs/promises`.
+- `ensureDirectory` / `directoryExists` / `directoryIsEmpty` — defensive
+  directory helpers that never throw on a missing parent.
+- `writeFiles(outputDir, files, fs?)` — writes a generated file list,
+  creating parents along the way; wraps adapter throws as
+  `ELECTROBUN.FS_WRITE_FAILED`.
+- `nodeConfigDiscoveryAdapter` + `findConfigFile(discovery?)` — synchronous
+  config-file discovery in `cwd` then `homedir`; wraps malformed JSON or
+  read failures as `ELECTROBUN.CONFIG_PARSE_FAILED`.
+
+## Usage: Basic
+
+```ts
+import {
+    ensureDirectory,
+    nodeFsAdapter,
+    writeFiles,
+} from "@suaveplan/electrobun/fs";
+
+await ensureDirectory("/tmp/my-app");
+await writeFiles(
+    "/tmp/my-app",
+    [{ path: "README.md", content: "# hi" }],
+    nodeFsAdapter
+);
+```
+
+## Usage: Advanced
+
+```ts
+import type { FsAdapter } from "@suaveplan/electrobun/types";
+import { writeFiles } from "@suaveplan/electrobun/fs";
+
+const recording: Array<{ path: string; content: string }> = [];
+const recorder: FsAdapter = {
+    readFile: async () => "",
+    writeFile: async (path, content) => {
+        recording.push({ path, content });
+    },
+    mkdir: async () => undefined,
+    stat: async () => ({ isDirectory: () => true }),
+    readdir: async () => [],
+};
+await writeFiles("/out", [{ path: "a.txt", content: "x" }], recorder);
+// recording carries the spawn-equivalent log of every write
+```
+
+## API Reference
+
+- `FsAdapter` — `readFile`, `writeFile`, `mkdir({ recursive })`, `stat`,
+  `readdir`.
+- `nodeFsAdapter: FsAdapter`.
+- `ensureDirectory(dir, fs?): Promise<void>`.
+- `directoryExists(dir, fs?): Promise<boolean>`.
+- `directoryIsEmpty(dir, fs?): Promise<boolean>` — `true` for missing
+  dirs as well.
+- `writeFiles(outputDir, files, fs?): Promise<void>` — throws
+  `ElectrobunError(ELECTROBUN.FS_WRITE_FAILED)` on adapter failure.
+- `ConfigDiscoveryAdapter` — `exists`, `readFile`, `cwd`, `homedir`.
+- `nodeConfigDiscoveryAdapter: ConfigDiscoveryAdapter`.
+- `findConfigFile(discovery?): ElectrobunConfig | undefined` — throws
+  `ElectrobunError(ELECTROBUN.CONFIG_PARSE_FAILED)` on malformed JSON or
+  unreadable file.
+- `CONFIG_FILENAME = ".suaveplan-electrobun.json"`.
+
+## Implementation Notes
+
+`directoryIsEmpty` deliberately returns `true` for a missing directory
+because the caller's intent is "can we scaffold into this path?" — a
+non-existent path is just as scaffold-friendly as an empty one. This
+mirrors the upstream behaviour and keeps the `create` command from
+spuriously refusing to scaffold into a fresh directory.
+
+`findConfigFile` is the only synchronous path in the package because it
+runs once before the asynchronous CLI command dispatch; making it async
+would force the entire CLI shim to be async without a benefit, and would
+move the test boundary deeper into the call chain. The
+`ConfigDiscoveryAdapter` seam keeps the test surface clean while
+preserving the synchronous default.

docs/devtools/tooling/electrobun/src/generator/generator.md

@@ -0,0 +1,96 @@
+# Generator — `generator.ts`
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+Owns the two-call surface that scaffolds an Electrobun project on disk.
+`collectFiles(options, overrides?)` is pure — it returns the
+`GeneratedFile[]` list for a given `ProjectOptions` without touching the
+filesystem. `generate(options, deps?)` writes the file list through the
+`FsAdapter` seam, snapshots the `.suaveplan-electrobun.json` config, and
+optionally runs the icon pipeline when `options.iconSource` is set.
+
+The generator is the only place that knows the canonical file order: the
+nine core files come first (`electrobun.config.ts`, `package.json`,
+`tsconfig.json`, the main-process Bun entry, three mainview files, the
+shared types module, the README), then one file per selected feature in
+the `FEATURE_ORDER` (`i18n`, `networking`, `api`, `api-schemas`,
+`storage`, `auth`, `form-builder`, `r3f`). Input order does not matter
+— the iterator walks `FEATURE_ORDER` and includes the feature only when
+it is present in the input set.
+
+The `overrides` argument lets tests substitute a faulty renderer to
+exercise the `ELECTROBUN.TEMPLATE_RENDER_FAILED` wrapper without forcing
+the production renderer table to throw. Production callers never set
+overrides.
+
+## Features
+
+- Deterministic file ordering across runs.
+- Zod-validated input via `ProjectOptionsSchema`.
+- Wraps every renderer throw as `ELECTROBUN.TEMPLATE_RENDER_FAILED`.
+- Optional icon pipeline gated by `options.iconSource`.
+- OTel: `recordProject(featuresCount)` increment +
+  `recordGenerateDuration(ms, featuresCount)` observation per call.
+- `CollectOverrides` seam for test-only renderer substitution.
+
+## Usage: Basic
+
+```ts
+import { generate } from "@suaveplan/electrobun/generator";
+
+const report = await generate({
+    name: "my-app",
+    identifier: "com.example.my-app",
+    description: "demo",
+    version: "0.1.0",
+    outputDir: "/tmp/my-app",
+    features: ["i18n", "api"],
+    networkingComplexity: "basic",
+    r3fModules: [],
+});
+console.log(`Wrote ${report.filesCreated.length} files in ${report.durationMs}ms`);
+```
+
+## Usage: Advanced
+
+```ts
+import { collectFiles } from "@suaveplan/electrobun/generator";
+import type { FsAdapter } from "@suaveplan/electrobun/types";
+import { writeFiles } from "@suaveplan/electrobun/fs";
+
+const fs: FsAdapter = /* in-memory adapter */;
+const files = collectFiles(opts);
+await writeFiles(opts.outputDir, files, fs);
+```
+
+## API Reference
+
+- `collectFiles(options: ProjectOptions, overrides?: CollectOverrides):
+  GeneratedFile[]`.
+- `generate(options: ProjectOptions, deps?: GenerateDeps):
+  Promise<GenerateReport>`.
+- `GenerateDeps = { fs?, renderer?, fileExists?, now?, overrides? }`.
+- `CollectOverrides = { renderProjectFile?, renderFeatureFile? }` — the
+  test seam.
+
+## Implementation Notes
+
+`collectFiles` validates with Zod first, then iterates the file list.
+Each renderer is wrapped in a try/catch that converts native errors into
+`ElectrobunError(ELECTROBUN.TEMPLATE_RENDER_FAILED)` carrying the
+faulty path (or feature name) in `details`. The wrap is essential
+because a renderer failure surfaces as a string-typed crash at the call
+site that consumed `collectFiles`; the typed code lets the caller branch
+on "template bug" vs "Zod bug" vs "fs bug" without parsing messages.
+
+The icon-pipeline integration is gated by a truthy
+`parsed.iconSource` rather than `!= undefined`, so an empty-string
+`iconSource` (a common prompt default) skips icon generation entirely.
+This matches the upstream behaviour: the prompt layer collapses an
+empty answer to `undefined` before passing it down, but the generator
+defends against the empty-string case too in case a config file
+materialises one.

docs/devtools/tooling/electrobun/src/icons/icons.md

@@ -0,0 +1,91 @@
+# Icon pipeline — `icons.ts`
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+Wraps the upstream `iconz` library behind an `IconRendererAdapter` seam
+so the generator can run the icon-generation pipeline with a real
+renderer in production and with a deterministic fake in tests. The
+adapter contract is intentionally narrow — `render(input)` takes a
+single descriptor and returns a `{ files }` payload — so swapping in a
+different implementation (for instance, a server-side image-magick
+worker) costs one struct.
+
+`generateIcons({ inputPath, outputDir }, deps?)` validates its input
+against the Zod schema, probes for the source file's existence, calls
+the renderer, and returns an `IconReport` carrying either the produced
+file list or the error message that the renderer threw. The function
+never throws on a renderer failure — it returns the report with
+`generated: false` and an `error` string so callers can surface the
+warning without aborting the rest of the scaffold. A missing source
+file IS a hard failure (raises `ELECTROBUN.ICON_SOURCE_MISSING`)
+because the caller's intent was specifically "generate icons from this
+path", not "skip icons silently."
+
+## Features
+
+- `iconzRendererAdapter` default backed by lazy `iconz` import.
+- Boundary validation against `GenerateIconsOptionsSchema`.
+- Hard `ELECTROBUN.ICON_SOURCE_MISSING` on a missing source path.
+- Soft `IconReport.error` wrapping for renderer throws.
+- Canonical icon descriptor (icns 16/32/.../1024, ico 16/.../256, png
+  16/.../1024) — pinned across runs.
+- OTel `recordIcons("generated"|"skipped"|"failed")` increments per
+  outcome.
+
+## Usage: Basic
+
+```ts
+import { generateIcons } from "@suaveplan/electrobun/icons";
+
+const report = await generateIcons({
+    inputPath: "./assets/source.png",
+    outputDir: "./out/my-app",
+});
+if (report.error) {
+    console.warn(report.error);
+}
+```
+
+## Usage: Advanced
+
+```ts
+import type { IconRendererAdapter } from "@suaveplan/electrobun/types";
+import { generateIcons } from "@suaveplan/electrobun/icons";
+
+const recording: IconRendererAdapter = {
+    async render(input) {
+        console.log("would emit:", input.icons);
+        return { files: ["app.icns", "app.ico"] };
+    },
+};
+await generateIcons(
+    { inputPath: "./a.png", outputDir: "./out" },
+    { renderer: recording, fileExists: () => true }
+);
+```
+
+## API Reference
+
+- `generateIcons(options, deps?): Promise<IconReport>`.
+- `GenerateIconsOptions = { inputPath, outputDir }`.
+- `GenerateIconsDeps = { renderer?, fileExists? }`.
+- `iconzRendererAdapter: IconRendererAdapter` — default `iconz`-backed
+  renderer.
+
+## Implementation Notes
+
+The renderer is loaded via dynamic `import("iconz")` rather than a
+top-level static import so the cost is paid only on the first real
+icon-render call. Test environments that always inject a fake adapter
+never trigger the import, which keeps the test suite fast and free of
+native-dependency side effects.
+
+The `IconReport.files` array is built from the renderer's reply rather
+than from a hard-coded list so an adapter that produces a different
+file set (for example, a stripped-down adapter for CI) reports honestly.
+The recorder fake in `icons.test.ts` returns a minimal list to keep the
+assertions tight.

docs/devtools/tooling/electrobun/src/prompts/prompts.md

@@ -0,0 +1,96 @@
+# Prompts — `prompts.ts`
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+Owns the interactive scaffolder that backs the CLI's `create` command.
+`runPrompts(config, outputDir, prompter)` walks the user through nine
+questions (name, identifier, description, version, icon source,
+features, networking complexity when networking is selected, R3F modules
+when R3F is selected, and a final confirm) and returns a fully-populated
+`ProjectOptions` ready to feed the generator.
+
+Every interaction flows through the injectable `Prompter` contract; tests
+drive the function with a scripted prompter that returns canned answers,
+production consumes the `@suaveplan/cli` prompt façade. The
+`Prompter.text`, `confirm`, `select<T>`, and `multiselect<T>` methods are
+the four primitives every prompt rests on — keeping the surface narrow
+means swapping in a non-TTY prompter (for example a GUI front-end)
+costs four methods.
+
+A negative `proceed` answer raises `ELECTROBUN.PROMPT_ABORTED` and bumps
+the `electrobun_prompts_total{outcome="aborted"}` counter; a completed
+run bumps the `outcome="completed"` slot.
+
+## Features
+
+- Closed `Prompter` contract for swapping front-ends.
+- Defaults pulled from the supplied `ElectrobunConfig` (lifted from
+  `loadConfig`).
+- `networkingComplexity` and `r3fModules` are conditional on the
+  matching feature being selected.
+- `deriveIdentifier` falls back to `com.example.<slug>` when the user
+  declines to set an explicit identifier.
+- OTel `recordPromptOutcome` per call.
+
+## Usage: Basic
+
+```ts
+import { runPrompts } from "@suaveplan/electrobun/prompts";
+import { confirm, multiselect, select, text } from "@suaveplan/cli/prompt/prompt";
+import type { Prompter } from "@suaveplan/electrobun/types";
+
+const cliPrompter: Prompter = {
+    text,
+    confirm,
+    select,
+    multiselect,
+};
+const opts = await runPrompts({}, undefined, cliPrompter);
+```
+
+## Usage: Advanced
+
+```ts
+import type { Prompter } from "@suaveplan/electrobun/types";
+
+const recorded: string[] = [];
+const dryPrompter: Prompter = {
+    async text({ message, default: d }) {
+        recorded.push(message);
+        return d ?? "";
+    },
+    async confirm({ default: d }) {
+        return d ?? true;
+    },
+    async select({ choices, default: d }) {
+        return (d ?? choices[0]!.value) as never;
+    },
+    async multiselect() {
+        return [] as never;
+    },
+};
+await runPrompts(cfg, "/tmp/x", dryPrompter);
+```
+
+## API Reference
+
+- `runPrompts(config: ElectrobunConfig, outputDir: string | undefined,
+  prompter: Prompter): Promise<ProjectOptions>`.
+
+## Implementation Notes
+
+The feature-list and R3F-module choices are derived from
+`FEATURE_LABELS` / `R3F_MODULE_LABELS` so the human-readable text stays
+in lockstep with the closed `FeatureModule` / `R3fModule` union types.
+A new feature joining the union appears automatically in the prompt
+choices once the labels constant is updated.
+
+`iconSource` is collapsed from an empty string to `undefined` before
+being returned. This matches the generator's expectation that an
+absent icon source means "skip the icon pipeline entirely"; without the
+collapse, the generator would call into the icon module with an empty
+path and then have to re-handle the empty case.

docs/devtools/tooling/electrobun/src/runner/runner.md

@@ -0,0 +1,97 @@
+# Command runner — `runner.ts`
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+Owns the `CommandRunner` seam that every electrobun shell-out flows
+through, plus the `probeElectrobun` and `invokeElectrobun` helpers that
+the four orchestration subcommands use. The seam exists so tests can
+substitute a recording fake without `vi.mock`, and so consumers running
+under sandboxed environments can plug in their own spawn primitive
+(for example a remote-runner that ships the spawn off to a CI worker).
+
+The default `nodeCommandRunner` wraps `node:child_process.spawn` directly;
+it buffers stdout / stderr as UTF-8 strings, records the wall-clock
+duration, and propagates an optional `AbortSignal` through a `SIGTERM`
+kill on abort. The wrapper does not pass the command through a shell, so
+argument-injection through unsanitised user input is structurally
+impossible.
+
+`probeElectrobun` runs `bunx electrobun --version` and reports
+`{ available, version? }`. `invokeElectrobun` probes first, raises
+`ELECTROBUN.BINARY_UNAVAILABLE` on miss, and otherwise spawns the
+subcommand with the supplied argv; a non-zero exit lands as
+`ELECTROBUN.RUNNER_FAILED` carrying `command`, `exitCode`, `stderr`, and
+the original argv on `details`.
+
+## Features
+
+- `nodeCommandRunner` — default async runner backed by
+  `node:child_process.spawn`.
+- `probeElectrobun(runner?, cwd?)` — boolean probe + optional version
+  string parsed from stdout / stderr.
+- `invokeElectrobun({ runner, cwd, args, command, signal? })` —
+  probe-then-spawn orchestrator with full error classification.
+
+## Usage: Basic
+
+```ts
+import { invokeElectrobun, nodeCommandRunner } from "@suaveplan/electrobun/runner";
+
+const result = await invokeElectrobun({
+    runner: nodeCommandRunner,
+    cwd: "/tmp/my-app",
+    args: ["build", "--target", "mac"],
+    command: "build",
+});
+console.log(`build exited ${result.exitCode} in ${result.durationMs}ms`);
+```
+
+## Usage: Advanced
+
+```ts
+import type { CommandRunner } from "@suaveplan/electrobun/types";
+import { invokeElectrobun } from "@suaveplan/electrobun/runner";
+
+const recording: Array<{ command: string; args: readonly string[] }> = [];
+const recorder: CommandRunner = async (input) => {
+    recording.push({ command: input.command, args: input.args });
+    return { exitCode: 0, stdout: "1.2.3", stderr: "", durationMs: 1 };
+};
+await invokeElectrobun({
+    runner: recorder,
+    cwd: "/tmp/x",
+    args: ["sign", "--identity", "Dev ID"],
+    command: "sign",
+});
+```
+
+## API Reference
+
+- `nodeCommandRunner: CommandRunner` — `spawn`-backed default.
+- `probeElectrobun(runner?: CommandRunner, cwd?: string):
+  Promise<{ available: boolean; version?: string }>`.
+- `invokeElectrobun(input: { runner, cwd, args, command, signal? }):
+  Promise<CommandResult>` — throws `ElectrobunError(BINARY_UNAVAILABLE
+  | RUNNER_FAILED)`.
+
+## Implementation Notes
+
+`spawn` is used rather than `exec` so the `command` and `args` arrays
+never pass through a shell. The wrapper sets `stdio: ["ignore", "pipe",
+"pipe"]` to detach stdin (the orchestrated commands run non-interactively)
+and to surface stdout / stderr buffers for diagnostics.
+
+The version regex `(\d+\.\d+\.\d+)` is intentionally permissive — it
+covers `1.2.3`, `v1.2.3`, and `electrobun 1.2.3 (some flag)` outputs.
+When the binary changes its `--version` format the probe still reports
+`available: true` without a version, which is enough to clear the
+`BINARY_UNAVAILABLE` gate.
+
+`AbortSignal` is forwarded via an `addEventListener("abort", …,
+{ once: true })` that issues `SIGTERM` to the child. The listener is
+removed on `close` / `error` to avoid leaking memory when many
+subprocesses share a single signal.

docs/devtools/tooling/electrobun/src/schemas/schemas.md

@@ -0,0 +1,104 @@
+# Schemas — `schemas.ts`
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+Owns the Zod schemas that gate every public boundary of
+`@suaveplan/electrobun`. Each interface in `src/types/electrobun.types.ts`
+has a matching schema here, and the `parseOrThrow` helper folds the
+parse + throw pattern into one call so every entry point reads the same
+way: validate, then operate on the inferred type. The schemas are the
+runtime contract — when a downstream library passes a stale
+`ProjectOptions` shape, the schema fails at the boundary rather than
+silently producing a broken project.
+
+The schemas use Zod 4's enum / object / readonly-array helpers to keep
+the TypeScript inference cheap, and `parseOrThrow` always raises
+`ElectrobunError(ELECTROBUN.INVALID_OPTIONS)` so consumers can branch on
+`error.code === "ELECTROBUN.INVALID_OPTIONS"` regardless of which entry
+point validated.
+
+## Features
+
+- Enum schemas (`FeatureModuleSchema`, `NetworkingComplexitySchema`,
+  `R3fModuleSchema`, `BuildTargetSchema`).
+- Composite schemas (`ProjectOptionsSchema`, `ElectrobunConfigSchema`,
+  `GenerateIconsOptionsSchema`, `DevCommandOptionsSchema`,
+  `BuildCommandOptionsSchema`, `PackageCommandOptionsSchema`,
+  `SignCommandOptionsSchema`).
+- `parseOrThrow(schema, value, context)` — single helper that converts a
+  Zod failure into an `ElectrobunError` carrying `details.issues`.
+
+## Usage: Basic
+
+```ts
+import { ProjectOptionsSchema } from "@suaveplan/electrobun/schemas";
+
+const parsed = ProjectOptionsSchema.safeParse(input);
+if (!parsed.success) {
+    console.error(parsed.error.issues);
+}
+```
+
+## Usage: Advanced
+
+```ts
+import {
+    ProjectOptionsSchema,
+    parseOrThrow,
+} from "@suaveplan/electrobun/schemas";
+import { ElectrobunError } from "@suaveplan/electrobun/error-codes";
+
+try {
+    const validated = parseOrThrow(
+        ProjectOptionsSchema,
+        input,
+        "ProjectOptions"
+    );
+    await generate(validated);
+} catch (err) {
+    if (err instanceof ElectrobunError) {
+        process.stderr.write(`${err.code}: ${err.message}\n`);
+        for (const issue of err.details["issues"] as Array<{
+            path: ReadonlyArray<string>;
+            message: string;
+        }>) {
+            process.stderr.write(`  - ${issue.path.join(".")}: ${issue.message}\n`);
+        }
+    }
+}
+```
+
+## API Reference
+
+- `FeatureModuleSchema`, `NetworkingComplexitySchema`, `R3fModuleSchema`,
+  `BuildTargetSchema` — closed Zod enums.
+- `ProjectOptionsSchema` — full `ProjectOptions` shape; rejects empty
+  `name`, `identifier`, `version`, `outputDir`.
+- `ElectrobunConfigSchema` — partial config; every field optional.
+- `GenerateIconsOptionsSchema` — `{ inputPath, outputDir }`.
+- `DevCommandOptionsSchema`, `BuildCommandOptionsSchema`,
+  `PackageCommandOptionsSchema`, `SignCommandOptionsSchema` — per-command
+  option shapes.
+- `parseOrThrow<T>(schema, value, context)` — returns the parsed value or
+  throws `ElectrobunError(ELECTROBUN.INVALID_OPTIONS, "${context}: invalid
+  options", { details: { context, issues } })`.
+
+## Implementation Notes
+
+`z.array(...).readonly()` produces a `readonly`-typed inference that
+matches the `readonly`-array fields on `ProjectOptions`, so the consumer
+gets a parsed object whose mutability matches the interface. This is
+important because the generator iterates the feature list and would
+otherwise need an explicit `Array.from(...)` to avoid a structural
+mismatch.
+
+`parseOrThrow` uses `safeParse` rather than `parse` so the Zod issue list
+lands on `details.issues`. The thrown error carries the original `cause`
+slot empty — the Zod issues are the cause, surfaced as structured data
+rather than a child `Error`. Consumers who want to log a single line
+should format `err.message`; consumers who want to drive remediation
+should walk `details.issues`.

docs/devtools/tooling/electrobun/src/telemetry/telemetry.md

@@ -0,0 +1,93 @@
+# Telemetry — `telemetry.ts`
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+Owns the OpenTelemetry surface for `@suaveplan/electrobun`. Every public
+entry point that does observable work (project scaffolding, icon
+rendering, command orchestration, prompt completion) ends with a call
+into one of the recorder helpers exported here. Tests register a real
+in-memory `MeterProvider` in `tests/setup/polyfills.ts` before any source
+module imports, so the global meter resolved on first use binds to it
+and every increment / observation is captured for assertion.
+
+When no provider is registered the OTel API returns no-op instruments,
+so the helpers are safe to call from production code that opts out of
+telemetry without a guard ladder. The instrument names follow the
+`electrobun_*` snake-case convention that the rest of the tooling
+family already uses, which keeps Prometheus / Loki dashboards consistent.
+
+## Features
+
+- Five counters (`projects_generated`, `icons_generated`,
+  `runner_invocations`, `runner_failures`, `prompts`).
+- Two histograms (`generate_duration_ms`, `runner_duration_ms`).
+- Eight recorder helpers, one per instrument plus the prompt outcome and
+  icon outcome convenience wrappers.
+- Lazy-bound meter that picks up whichever `MeterProvider` was registered
+  globally at first use — no boot order constraints on the consumer.
+
+## Usage: Basic
+
+```ts
+import { recordRunnerInvocation } from "@suaveplan/electrobun/telemetry";
+
+recordRunnerInvocation("build");
+```
+
+## Usage: Advanced
+
+```ts
+import {
+    recordGenerateDuration,
+    recordRunnerDuration,
+    recordRunnerFailure,
+} from "@suaveplan/electrobun/telemetry";
+
+const started = performance.now();
+try {
+    await runOrchestrator(opts);
+    recordRunnerDuration("build", performance.now() - started);
+} catch (err) {
+    recordRunnerFailure("build", err?.details?.exitCode ?? 1);
+    throw err;
+} finally {
+    recordGenerateDuration(performance.now() - started, opts.features.length);
+}
+```
+
+## API Reference
+
+- `recordProject(featuresCount: number): void` — `+1` on
+  `electrobun_projects_generated_total` with `features_count`.
+- `recordIcons(outcome: "generated"|"skipped"|"failed"): void` — `+1` on
+  `electrobun_icons_generated_total`.
+- `recordRunnerInvocation(command: RunnerCommand): void` — `+1` on
+  `electrobun_runner_invocations_total`.
+- `recordRunnerFailure(command: RunnerCommand, exitCode: number): void`
+  — `+1` on `electrobun_runner_failures_total` with `command` and
+  `exit_code` labels.
+- `recordPromptOutcome(outcome: "completed"|"aborted"): void` — `+1` on
+  `electrobun_prompts_total`.
+- `recordGenerateDuration(ms: number, featuresCount: number): void` —
+  observation on `electrobun_generate_duration_ms` with `features_count`.
+- `recordRunnerDuration(command: RunnerCommand, ms: number): void` —
+  observation on `electrobun_runner_duration_ms` with `command`.
+
+## Implementation Notes
+
+The label keys are pinned (`features_count`, `outcome`, `command`,
+`exit_code`) and intentionally use snake_case so they line up with the
+OpenTelemetry semantic-conventions style for tooling instruments. The
+recorder helpers stringify numeric labels because the `MeterProvider`
+attribute API accepts strings — letting callers pass numbers would force
+every call site to remember the coercion.
+
+The lazy `meter` binding means the package can be imported into a fresh
+process and used immediately; if the consumer later registers a
+`MeterProvider`, the next call picks up the new instruments without a
+re-import. This matches the lifecycle of the `@suaveplan/opentelemetry`
+SDK factory, which wires the provider once at process start.

docs/devtools/tooling/electrobun/src/templates/features.md

@@ -0,0 +1,85 @@
+# Feature templates — `features.ts`
+
+## Purpose
+
+Owns every renderer that produces a per-feature file in the scaffolded
+output: `i18n`, `networking` (basic + full), `api`, `api-schemas`,
+`storage`, `auth`, `form-builder`, and `r3f`. The renderers are pure
+functions over `ProjectOptions`; the `r3f` renderer additionally branches
+on `options.r3fModules` to wire camera / physics / particles / character
+/ pathfinding subsystems into the emitted scene.
+
+The companion `templates.ts` module covers the project-level renderers;
+the two together replace the upstream `src/templates/*.ts` and
+`src/templates/features/*.ts` blob set. `renderFeature(feature,
+options)` is the single dispatch entry the generator uses; individual
+`render*Feature` helpers are exported for tools that want to render a
+single feature in isolation (for example, a "show me the API skeleton"
+preview pane in an IDE extension).
+
+## Features
+
+- Eight per-feature renderers — every closed `FeatureModule` value has a
+  dedicated implementation.
+- `renderNetworkFeature` vs `renderNetworkFullFeature` selected by
+  `options.networkingComplexity`.
+- `renderR3fFeature` composes the camera / physics / particles imports
+  + scene fragments based on `options.r3fModules`.
+- `featurePath(feature)` returns the canonical output path for each
+  feature (the generator uses this to assemble the file list).
+
+## Usage: Basic
+
+```ts
+import { renderFeature, featurePath } from "@suaveplan/electrobun/templates";
+
+const content = renderFeature("i18n", opts);
+const path = featurePath("i18n");
+// path === "src/features/i18n.ts"
+```
+
+## Usage: Advanced
+
+```ts
+import {
+    featurePath,
+    renderFeature,
+} from "@suaveplan/electrobun/templates";
+
+const featureFiles = opts.features.map((f) => ({
+    path: featurePath(f),
+    content: renderFeature(f, opts),
+}));
+```
+
+## API Reference
+
+- `renderI18nFeature()`, `renderNetworkFeature()`,
+  `renderNetworkFullFeature()`, `renderApiFeature()`,
+  `renderApiSchemasFeature()`, `renderStorageFeature()`,
+  `renderAuthFeature()`, `renderFormBuilderFeature()`,
+  `renderR3fFeature(options)`.
+- `renderFeature(feature: FeatureModule, options: ProjectOptions):
+  string` — dispatch table.
+- `featurePath(feature: FeatureModule): string`.
+
+## Implementation Notes
+
+The `r3f` renderer is the only one whose output is materially shaped by
+`ProjectOptions` beyond the basic "the feature is enabled" toggle. The
+imports and scene fragments are assembled by joining arrays of strings,
+which makes the relative ordering deterministic and the diff-noise low
+when a new R3F module is added: the test for "r3f renderer emits the
+requested modules" pins the order so a refactor cannot silently
+re-shuffle imports.
+
+The `networking` renderer dispatches on `options.networkingComplexity`
+rather than `options.networking` because the upstream contract used
+`"basic"` / `"full"` to gate the full mesh layer. Keeping the same
+contract means downstream electrobun projects already on the
+`networkingComplexity` shape do not need to migrate.
+
+`featurePath` lives here rather than in the generator because the
+mapping is per-feature; the generator consumes it as a thin lookup. If
+a future feature lands with a non-default output path, the change is
+local to `features.ts`.

docs/devtools/tooling/electrobun/src/templates/templates.md

@@ -0,0 +1,107 @@
+# Project templates — `templates.ts`
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+Owns every renderer that produces a project-level file in the scaffolded
+output: `electrobun.config.ts`, `package.json`, `tsconfig.json`,
+`README.md`, the main-process Bun entry, the mainview HTML / CSS / TSX,
+and the shared types module. The renderers are pure functions over
+`ProjectOptions` — given the same input they return byte-identical
+strings, which is the property the generator's snapshot tests rely on.
+
+The companion `features.ts` module covers the per-feature renderers; the
+two files together replace the upstream `src/templates/*.ts` blob set.
+Splitting project files from features keeps the dispatch table for each
+small enough to inline at the call site, and keeps the test surface
+shallow.
+
+`renderProjectFile(kind, options)` is the single entry point the
+generator uses. Direct exports of each `render*` helper are preserved
+for consumers that want to drop a single template into a different
+toolchain (for example, a `--scaffold-only` CI script that emits
+`package.json` without the rest of the project).
+
+## Features
+
+- Nine project renderers covering every file the scaffolder writes.
+- `renderProjectFile(kind, options)` dispatch table for the generator.
+- `FEATURE_LABELS` / `R3F_MODULE_LABELS` constants used by the prompt
+  layer and by `renderReadme`.
+- Deterministic output for a given `ProjectOptions` (byte-stable across
+  runs).
+
+## Usage: Basic
+
+```ts
+import { renderPackageJson } from "@suaveplan/electrobun/templates";
+
+const pkgJson = renderPackageJson({
+    name: "my-app",
+    identifier: "com.example.my-app",
+    description: "demo",
+    version: "0.1.0",
+    outputDir: "/tmp/x",
+    features: ["api"],
+    networkingComplexity: "basic",
+    r3fModules: [],
+});
+```
+
+## Usage: Advanced
+
+```ts
+import { renderProjectFile } from "@suaveplan/electrobun/templates";
+import { writeFiles } from "@suaveplan/electrobun/fs";
+
+const kinds = [
+    "electrobun-config",
+    "package-json",
+    "tsconfig",
+    "main-process",
+    "mainview-html",
+    "mainview-css",
+    "mainview-entry",
+    "shared-types",
+    "readme",
+] as const;
+const opts = /* ... */;
+const files = kinds.map((kind) => ({
+    path: pathFor(kind),
+    content: renderProjectFile(kind, opts),
+}));
+await writeFiles(opts.outputDir, files);
+```
+
+## API Reference
+
+- `renderElectrobunConfig(options)`, `renderMainProcess(options)`,
+  `renderMainviewHtml(options)`, `renderMainviewCss()`,
+  `renderMainviewEntry(options)`, `renderSharedTypes(options)`,
+  `renderTsconfig()`, `renderReadme(options)`, `renderPackageJson(options)`.
+- `renderProjectFile(kind: ProjectFileKind, options)` — dispatch table.
+- `FEATURE_LABELS: Record<FeatureModule, string>`.
+- `R3F_MODULE_LABELS: Record<R3fModule, string>`.
+
+## Implementation Notes
+
+Every renderer is total over its input — there is no fallback branch
+that emits a placeholder. Bad `ProjectOptions` should be rejected by the
+Zod schema in `src/schemas/schemas.ts` before reaching a renderer; if
+the schema misses something the renderer will produce a string with
+unexpected `undefined` interpolations, which the unit tests catch.
+
+`renderPackageJson` keeps the dependency map in a per-feature table
+(`FEATURE_DEPS`) so the renderer body stays small and the table can
+diff cleanly when the suaveplan dep set evolves. R3F module dependencies
+live in a parallel `R3F_MODULE_DEPS` table for the same reason.
+
+`renderMainviewEntry` builds the i18n greeting via a literal template
+fragment rather than a string-interpolation `${...}` so the source
+emitted into the scaffolded project preserves the surrounding `${...}`
+braces. The build step never touches these strings — they are emitted
+verbatim — so the generated `.tsx` file compiles cleanly inside the
+downstream project.

docs/devtools/tooling/electrobun/src/types/electrobun.types.md

@@ -0,0 +1,115 @@
+# Types — `electrobun.types.ts`
+
+## Purpose
+
+Centralises every public interface used across the `@suaveplan/electrobun`
+surface. The file is type-only — no runtime emit beyond the
+`FEATURE_ORDER` `readonly` array that defines the canonical feature
+render order. Keeping every shape in a single module means downstream
+consumers (CI scripts, IDE extensions, the binary entry) only ever import
+one symbol per concept instead of chasing them across feature folders.
+
+The Zod schemas in `src/schemas/schemas.ts` mirror these shapes one-to-one
+so the type system and the runtime validator never drift. Every public
+function in the package parses its options against the schema and then
+operates on the inferred TypeScript type.
+
+## Features
+
+- `ProjectOptions` / `ElectrobunConfig` — the user-facing scaffolder shape.
+- `FeatureModule`, `NetworkingComplexity`, `R3fModule`, `BuildTarget` —
+  closed union types that mirror the upstream CLI choices.
+- `FsAdapter`, `CommandRunner`, `IconRendererAdapter`, `Prompter` — the four
+  seams every IO-touching helper accepts.
+- `*CommandOptions` (`Dev`, `Build`, `Package`, `Sign`) + `CommandReport`
+  for the four orchestration subcommands.
+- `IconReport`, `GenerateReport` — structured returns for the generator
+  and icon pipeline.
+- `CommandDeps` — the dependency bag accepted by `runCli` and every
+  subcommand.
+
+## Usage: Basic
+
+```ts
+import type { ProjectOptions } from "@suaveplan/electrobun/types";
+
+const opts: ProjectOptions = {
+    name: "my-app",
+    identifier: "com.example.my-app",
+    description: "A demo Electrobun app",
+    version: "0.1.0",
+    outputDir: "/tmp/my-app",
+    features: ["i18n", "api"],
+    networkingComplexity: "basic",
+    r3fModules: [],
+};
+```
+
+## Usage: Advanced
+
+```ts
+import type {
+    CommandRunner,
+    FsAdapter,
+    Prompter,
+} from "@suaveplan/electrobun/types";
+
+const recordingRunner: CommandRunner = async (input) => ({
+    exitCode: 0,
+    stdout: "",
+    stderr: "",
+    durationMs: 1,
+});
+const fakeFs: FsAdapter = {
+    readFile: async () => "",
+    writeFile: async () => undefined,
+    mkdir: async () => undefined,
+    stat: async () => ({ isDirectory: () => true }),
+    readdir: async () => [],
+};
+const promptScript: Prompter = {
+    text: async ({ default: d }) => d ?? "",
+    confirm: async () => true,
+    select: async ({ default: d, choices }) =>
+        (d ?? choices[0]!.value) as never,
+    multiselect: async () => [] as never,
+};
+```
+
+## API Reference
+
+- `ProjectOptions` — required fields: `name`, `identifier`, `description`,
+  `version`, `outputDir`, `features`, `networkingComplexity`, `r3fModules`.
+  Optional: `iconSource`.
+- `ElectrobunConfig` — every `ProjectOptions` field is optional; used as the
+  config-file shape.
+- `GeneratedFile = { path: string; content: string }`.
+- `FsAdapter` — `readFile`, `writeFile`, `mkdir({ recursive })`, `stat`,
+  `readdir` (all `Promise<…>`).
+- `CommandInput = { command, args, cwd?, env?, signal? }`.
+- `CommandResult = { exitCode, stdout, stderr, durationMs }`.
+- `CommandRunner = (input) => Promise<CommandResult>`.
+- `Prompter.text / confirm / select<T> / multiselect<T>`.
+- `IconRendererInput.icons` carries `{ icns, ico, png }` descriptors.
+- `IconReport = { generated, files, error? }`.
+- `GenerateReport = { outputDir, filesCreated, durationMs, icons }`.
+- `CommandReport = { command, exitCode, durationMs, stdout, stderr }`.
+- `FEATURE_ORDER` — the canonical eight-feature render order.
+
+## Implementation Notes
+
+`FEATURE_ORDER` is a `readonly` array tuple so the generator can iterate
+it without sorting on every call. The runtime contract is "if the consumer
+asks for `r3f` before `i18n`, we render `i18n` first regardless." Keeping
+the order in a single exported constant is the gate against drift between
+the upstream CLI and the renderer ordering.
+
+`FsAdapter.stat` returns `{ isDirectory(): boolean }` to match the
+`node:fs.Stats` shape without forcing the consumer to import the whole
+`Stats` class. The fakes used in tests return inline objects implementing
+just this method, which keeps tests free of `Stats` instantiation.
+
+Every option that the CLI exposes has both a `*Options` interface and a
+matching Zod schema in `src/schemas/schemas.ts`; consumers should prefer
+the schema for runtime validation and the interface for compile-time
+typing.

docs/devtools/tooling/install-agent-skills/README.md

@@ -0,0 +1,94 @@
+# @suaveplan/install-agent-skills - Suaveplan installer plugin: bundles the agent-skills set and installs them into a target project via @suaveplan/installer.
+
+## Summary
+
+Installer plugin that bundles every Suaveplan skill (`SKILL.md` + assets)
+and installs them into a target project via `@suaveplan/installer`.
+
+<!-- begin:auto-docs -->
+## Documentation tree
+
+- [apply](./src/apply/apply.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
+  - [apply](./src/apply/apply.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
+- [detect](./src/detect/detect.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
+  - [detect](./src/detect/detect.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
+- [plan](./src/plan/plan.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
+  - [plan](./src/plan/plan.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
+- [plugin](./src/plugin/plugin.md) — Composes the agent-skills installer plugin from its constituent stages (`detect`, `prompts`, `plan`, `apply`, `postInst…
+  - [plugin](./src/plugin/plugin.md) — Composes the agent-skills installer plugin from its constituent stages (`detect`, `prompts`, `plan`, `apply`, `postInst…
+- [post-install](./src/post-install/post-install.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
+  - [post-install](./src/post-install/post-install.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
+- [prompts](./src/prompts/prompts.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
+  - [prompts](./src/prompts/prompts.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
+- [error-codes](./src/error-codes.md) — Defines the canonical error-code registry for `@suaveplan/install-agent-skills`. Every plugin-side failure path (invali…
+- [manifest-loader](./src/manifest-loader.md) — Loads and validates the bundled `assets/skills/manifest.json` produced by `scripts/build-skills-bundle.ts`. The loader…
+<!-- end:auto-docs -->  - [apply](./src/apply/apply.md) — <!-- begin:auto-docs --> _(no submodules)_- [detect](./src/detect/detect.md) — <!-- begin:auto-docs --> _(no submodules)_- [detect](./src/detect/detect.md) — <!-- begin:auto-docs --> _(no submodules)_- [plan](./src/plan/plan.md) — <!-- begin:auto-docs --> _(no submodules)_- [plan](./src/plan/plan.md) — <!-- begin:auto-docs --> _(no submodules)_- [post-install](./src/post-install/post-install.md) — <!-- begin:auto-docs --> _(no submodules)_- [post-install](./src/post-install/post-install.md) — <!-- begin:auto-docs --> _(no submodules)_- [prompts](./src/prompts/prompts.md) — <!-- begin:auto-docs --> _(no submodules)_- [prompts](./src/prompts/prompts.md) — <!-- begin:auto-docs --> _(no submodules)_- [error-codes](./src/error-codes.md) — Defines the canonical error-code registry for `@suaveplan/install-agent-skills`. Every plugin-side failure path (invali…
+- [manifest-loader](./src/manifest-loader.md) — Loads and validates the bundled `assets/skills/manifest.json` produced by `scripts/build-skills-bundle.ts`. The loader…
+- [plugin](./src/plugin.md) — Composes the agent-skills installer plugin from its constituent stages (`detect`, `prompts`, `plan`, `apply`, `postInst…
+- [apply](./src/apply/apply.md) — <!-- begin:auto-docs --> _(no submodules)_- [detect](./src/detect/detect.md) — <!-- begin:auto-docs --> _(no submodules)_- [detect](./src/detect/detect.md) — <!-- begin:auto-docs --> _(no submodules)_- [plan](./src/plan/plan.md) — <!-- begin:auto-docs --> _(no submodules)_- [plan](./src/plan/plan.md) — <!-- begin:auto-docs --> _(no submodules)_- [post-install](./src/post-install/post-install.md) — <!-- begin:auto-docs --> _(no submodules)_- [post-install](./src/post-install/post-install.md) — <!-- begin:auto-docs --> _(no submodules)_- [prompts](./src/prompts/prompts.md) — <!-- begin:auto-docs --> _(no submodules)_- [prompts](./src/prompts/prompts.md) — <!-- begin:auto-docs --> _(no submodules)_- [error-codes](./src/error-codes.md) — Defines the canonical error-code registry for `@suaveplan/install-agent-skills`. Every plugin-side failure path (invali…
+- [manifest-loader](./src/manifest-loader.md) — Loads and validates the bundled `assets/skills/manifest.json` produced by `scripts/build-skills-bundle.ts`. The loader…
+- [plugin](./src/plugin.md) — Composes the agent-skills installer plugin from its constituent stages (`detect`, `prompts`, `plan`, `apply`, `postInst…
+- [apply](./src/apply/apply.md) — <!-- begin:auto-docs --> _(no submodules)_- [detect](./src/detect/detect.md) — <!-- begin:auto-docs --> _(no submodules)_- [detect](./src/detect/detect.md) — <!-- begin:auto-docs --> _(no submodules)_- [plan](./src/plan/plan.md) — <!-- begin:auto-docs --> _(no submodules)_- [plan](./src/plan/plan.md) — <!-- begin:auto-docs --> _(no submodules)_- [post-install](./src/post-install/post-install.md) — <!-- begin:auto-docs --> _(no submodules)_- [post-install](./src/post-install/post-install.md) — <!-- begin:auto-docs --> _(no submodules)_- [prompts](./src/prompts/prompts.md) — <!-- begin:auto-docs --> _(no submodules)_- [prompts](./src/prompts/prompts.md) — <!-- begin:auto-docs --> _(no submodules)_- [error-codes](./src/error-codes.md) — Defines the canonical error-code registry for `@suaveplan/install-agent-skills`. Every plugin-side failure path (invali…
+- [manifest-loader](./src/manifest-loader.md) — Loads and validates the bundled `assets/skills/manifest.json` produced by `scripts/build-skills-bundle.ts`. The loader…
+- [plugin](./src/plugin.md) — Composes the agent-skills installer plugin from its constituent stages (`detect`, `prompts`, `plan`, `apply`, `postInst…
+- [apply](./src/apply/apply.md) — <!-- begin:auto-docs --> _(no submodules)_- [detect](./src/detect/detect.md) — <!-- begin:auto-docs --> _(no submodules)_  - [detect](./src/detect/detect.md) — <!-- begin:auto-docs --> _(no submodules)_- [plan](./src/plan/plan.md) — <!-- begin:auto-docs --> _(no submodules)_  - [plan](./src/plan/plan.md) — <!-- begin:auto-docs --> _(no submodules)_- [post-install](./src/post-install/post-install.md) — <!-- begin:auto-docs --> _(no submodules)_  - [post-install](./src/post-install/post-install.md) — <!-- begin:auto-docs --> _(no submodules)_- [prompts](./src/prompts/prompts.md) — <!-- begin:auto-docs --> _(no submodules)_  - [prompts](./src/prompts/prompts.md) — <!-- begin:auto-docs --> _(no submodules)_- [error-codes](./src/error-codes.md) — Defines the canonical error-code registry for `@suaveplan/install-agent-skills`. Every plugin-side failure path (invali…
+- [manifest-loader](./src/manifest-loader.md) — Loads and validates the bundled `assets/skills/manifest.json` produced by `scripts/build-skills-bundle.ts`. The loader…
+- [plugin](./src/plugin.md) — Composes the agent-skills installer plugin from its constituent stages (`detect`, `prompts`, `plan`, `apply`, `postInst…
+
+## Quickstart
+
+```bash
+bun add -D @suaveplan/install-agent-skills
+npx @suaveplan/installer add agent-skills
+```
+
+## Filtered installs
+
+```bash
+# Only a curated subset
+npx @suaveplan/installer add agent-skills --only crypto,events,logger
+
+# Everything except legacy skills
+npx @suaveplan/installer add agent-skills --exclude legacy
+
+# Force overwrite, non-interactive
+npx @suaveplan/installer add agent-skills --force --no-interactive
+```
+
+## Programmatic use
+
+```ts
+import { agentSkillsPlugin } from "@suaveplan/install-agent-skills";
+import { Host, DiskFs } from "@suaveplan/installer";
+
+const fs = new DiskFs({ cwd: process.cwd() });
+const host = new Host(ctx, fs);
+const result = await host.run(agentSkillsPlugin, {
+    answers: { targetDir: ".suaveplan/skills" },
+});
+console.log(`installed ${result.handle?.installed} skills`);
+```
+
+## Bundle build
+
+The plugin ships its skill set inside `assets/skills/`. To rebuild the
+bundle from the upstream `suaveplan-skills` marketplace:
+
+```bash
+bun run build:bundle
+```
+
+By default the script reads from `../../../../suaveplan-skills/plugins`;
+override via `SUAVEPLAN_SKILLS_ROOT=/path/to/skills bun run build:bundle`.
+
+## Module documentation
+
+Every implementation file ships with a sibling `.md` covering Purpose,
+Features, Usage, API Reference, and Implementation Notes. See
+`src/plan/plan.md`, `src/manifest-loader.md`, `src/plugin.md` for the
+load-bearing modules.
+
+## License
+
+MIT
+

docs/devtools/tooling/install-agent-skills/assets/skills/ab-testing/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: ab-testing
+description: Use when implementing or debugging code that uses @suaveplan/ab-testing: Enterprise A/B testing and experimentation: deterministic FNV-1a bucketing, targeting rules, variant assignment, conversion tracking, and OTel instrumentation.
+---
+
+# @suaveplan/ab-testing
+
+Enterprise A/B testing and experimentation engine with deterministic FNV-1a bucketing, targeting rules, variant assignment, conversion tracking, result aggregation, and OpenTelemetry instrumentation.
+
+## When to use this skill
+
+- Implementing or debugging code that imports `@suaveplan/ab-testing`.
+- The task touches: see package README.
+- You need API guidance for this package's exports.
+
+## Quick reference
+
+```ts
+import { /* see API Reference below */ } from "@suaveplan/ab-testing";
+```
+
+## Dependencies
+
+Workspace dependencies: `@suaveplan/error`, `@suaveplan/events`, `@suaveplan/feature-flags`, `@suaveplan/logger`, `@suaveplan/types`
+
+## Where to read more
+
+This skill is intentionally short. The package's own documentation is the authoritative source — read these in order:
+
+1. **`packages/platform/ab-testing/README.md`** — overview, install, quick-start, module index
+2. **`packages/platform/ab-testing/src/**/*.md`** — co-located docs per implementation file (Purpose, Features, Basic + Advanced examples, full API reference, Implementation notes — all packages  ship ≥200 words per module)
+3. **`packages/platform/ab-testing/package.json`** `exports` map — every subpath you can import from
+
+When the user asks an API question, read the relevant co-located `.md` first; do not answer from training-data memory.
+
+## See also
+
+- `@suaveplan/error`
+- `@suaveplan/events`
+- `@suaveplan/feature-flags`
+- `@suaveplan/logger`
+- `@suaveplan/types`
+
+---
+
+_This SKILL.md is auto-generated by `suaveplan-skills/scripts/generate-skills.ts` from the package's README. Do not edit by hand — re-run the generator after the README changes._

docs/devtools/tooling/install-agent-skills/assets/skills/api-schemas/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: api-schemas
+description: Use when implementing or debugging code that uses @suaveplan/api-schemas: Shared Zod schemas describing Suaveplan API request/response shapes — single source of truth for server plugins, React data hooks, and generated OpenAPI documents.
+---
+
+# @suaveplan/api-schemas
+
+Shared Zod schemas describing Suaveplan API request/response shapes. The single source of truth for server plugins, React data hooks, and generated OpenAPI documents.
+
+## When to use this skill
+
+- Implementing or debugging code that imports `@suaveplan/api-schemas`.
+- The task touches: see package README.
+- You need API guidance for this package's exports.
+
+## Quick reference
+
+```ts
+import { /* see API Reference below */ } from "@suaveplan/api-schemas";
+```
+
+## Dependencies
+
+Workspace dependencies: _none_
+
+## Where to read more
+
+This skill is intentionally short. The package's own documentation is the authoritative source — read these in order:
+
+1. **`packages/api/api-schemas/README.md`** — overview, install, quick-start, module index
+2. **`packages/api/api-schemas/src/**/*.md`** — co-located docs per implementation file (Purpose, Features, Basic + Advanced examples, full API reference, Implementation notes — all packages  ship ≥200 words per module)
+3. **`packages/api/api-schemas/package.json`** `exports` map — every subpath you can import from
+
+When the user asks an API question, read the relevant co-located `.md` first; do not answer from training-data memory.
+
+## See also
+
+- The marketplace root: `../../../README.md`
+
+---
+
+_This SKILL.md is auto-generated by `suaveplan-skills/scripts/generate-skills.ts` from the package's README. Do not edit by hand — re-run the generator after the README changes._

docs/devtools/tooling/install-agent-skills/assets/skills/audit-logging/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: audit-logging
+description: Use when implementing or debugging code that uses @suaveplan/audit-logging: Tamper-proof, GDPR-compliant audit logging: cryptographic chain-integrity, pluggable storage, retention policy, GDPR export, and a rich event taxonomy.
+---
+
+# @suaveplan/audit-logging
+
+Tamper-proof, GDPR-compliant audit logging for Suaveplan. Provides a cryptographic chain-integrity engine, pluggable storage adapters, GDPR data export, configurable retention policies, and a rich event taxonomy spanning auth, authorization, data access, system, and GDPR events.
+
+## When to use this skill
+
+- Implementing or debugging code that imports `@suaveplan/audit-logging`.
+- The task touches: see package README.
+- You need API guidance for this package's exports.
+
+## Quick reference
+
+```ts
+import { /* see API Reference below */ } from "@suaveplan/audit-logging";
+```
+
+## Dependencies
+
+Workspace dependencies: `@suaveplan/crypto`, `@suaveplan/crypto-hash`, `@suaveplan/error`, `@suaveplan/events`, `@suaveplan/logger`, `@suaveplan/serialize`, `@suaveplan/types`
+
+## Where to read more
+
+This skill is intentionally short. The package's own documentation is the authoritative source — read these in order:
+
+1. **`packages/platform/audit-logging/README.md`** — overview, install, quick-start, module index
+2. **`packages/platform/audit-logging/src/**/*.md`** — co-located docs per implementation file (Purpose, Features, Basic + Advanced examples, full API reference, Implementation notes — all packages  ship ≥200 words per module)
+3. **`packages/platform/audit-logging/package.json`** `exports` map — every subpath you can import from
+
+When the user asks an API question, read the relevant co-located `.md` first; do not answer from training-data memory.
+
+## See also
+
+- `@suaveplan/crypto`
+- `@suaveplan/crypto-hash`
+- `@suaveplan/error`
+- `@suaveplan/events`
+- `@suaveplan/logger`
+- `@suaveplan/serialize`
+- `@suaveplan/types`
+
+---
+
+_This SKILL.md is auto-generated by `suaveplan-skills/scripts/generate-skills.ts` from the package's README. Do not edit by hand — re-run the generator after the README changes._

docs/devtools/tooling/install-agent-skills/assets/skills/auth/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: auth
+description: Use when implementing or debugging code that uses @suaveplan/auth: Provider-agnostic authentication: JWT lifecycle, API key management, session management, and request middleware with pluggable storage adapters.
+---
+
+# @suaveplan/auth
+
+Provider-agnostic authentication library for Suaveplan. Ships JWT token lifecycle, API key management, session management, and framework-agnostic middleware — all backed by a pluggable `AuthAdapter` interface.
+
+## When to use this skill
+
+- Implementing or debugging code that imports `@suaveplan/auth`.
+- The task touches: see package README.
+- You need API guidance for this package's exports.
+
+## Quick reference
+
+```ts
+import { /* see API Reference below */ } from "@suaveplan/auth";
+```
+
+## Dependencies
+
+Workspace dependencies: `@suaveplan/crypto`, `@suaveplan/crypto-keys`, `@suaveplan/error`, `@suaveplan/logger`, `@suaveplan/retry`, `@suaveplan/types`
+
+## Where to read more
+
+This skill is intentionally short. The package's own documentation is the authoritative source — read these in order:
+
+1. **`packages/auth/auth/README.md`** — overview, install, quick-start, module index
+2. **`packages/auth/auth/src/**/*.md`** — co-located docs per implementation file (Purpose, Features, Basic + Advanced examples, full API reference, Implementation notes — all packages  ship ≥200 words per module)
+3. **`packages/auth/auth/package.json`** `exports` map — every subpath you can import from
+
+When the user asks an API question, read the relevant co-located `.md` first; do not answer from training-data memory.
+
+## See also
+
+- `@suaveplan/crypto`
+- `@suaveplan/crypto-keys`
+- `@suaveplan/error`
+- `@suaveplan/logger`
+- `@suaveplan/retry`
+- `@suaveplan/types`
+
+---
+
+_This SKILL.md is auto-generated by `suaveplan-skills/scripts/generate-skills.ts` from the package's README. Do not edit by hand — re-run the generator after the README changes._

docs/devtools/tooling/install-agent-skills/assets/skills/barcode/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: barcode
+description: Use when implementing or debugging code that uses @suaveplan/barcode: Barcode generation and parsing for common 1D symbologies: Code 128, Code 39, EAN-13, EAN-8, UPC-A, UPC-E, ITF.
+---
+
+# @suaveplan/barcode
+
+Runtime-agnostic 1D barcode generation for seven symbologies — Code 128B, Code 39, EAN-13, EAN-8, UPC-A, UPC-E, and ITF. Outputs inline SVG strings and binary bar-pattern arrays with no canvas, no DOM, and no Node.js built-ins required, making it safe to use in Bun, Deno, edge runtimes, and browsers alike. Includes check-digit calculation, barcode validation, and human-readable text rendering. Use this package to generate product labels, shipping labels (ITF/GTIN-14), retail barcodes (EAN/UPC), and document barcodes (Code 128). For 2D barcodes (QR codes) use `@suaveplan/qrcode`. This package does not support barcode scanning/decoding from images — it is generation-only.
+
+## When to use this skill
+
+- Implementing or debugging code that imports `@suaveplan/barcode`.
+- The task touches: see package README.
+- You need API guidance for this package's exports.
+
+## Quick reference
+
+```ts
+import { /* see API Reference below */ } from "@suaveplan/barcode";
+```
+
+## Dependencies
+
+Workspace dependencies: _none_
+
+## Where to read more
+
+This skill is intentionally short. The package's own documentation is the authoritative source — read these in order:
+
+1. **`packages/foundation/barcode/README.md`** — overview, install, quick-start, module index
+2. **`packages/foundation/barcode/src/**/*.md`** — co-located docs per implementation file (Purpose, Features, Basic + Advanced examples, full API reference, Implementation notes — all packages  ship ≥200 words per module)
+3. **`packages/foundation/barcode/package.json`** `exports` map — every subpath you can import from
+
+When the user asks an API question, read the relevant co-located `.md` first; do not answer from training-data memory.
+
+## See also
+
+- The marketplace root: `../../../README.md`
+
+---
+
+_This SKILL.md is auto-generated by `suaveplan-skills/scripts/generate-skills.ts` from the package's README. Do not edit by hand — re-run the generator after the README changes._

docs/devtools/tooling/install-agent-skills/assets/skills/bitpacker/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: bitpacker
+description: Use when implementing or debugging code that uses @suaveplan/bitpacker: Bit-level binary packing and unpacking: arbitrary-width integers, booleans, fixed-point, bit-field schemas, and streaming read/write cursors.
+---
+
+# @suaveplan/bitpacker
+
+Bit-level binary packing and unpacking for TypeScript. Designed for network protocols, game-state serialisation, and compact binary formats. Pure TypeScript, zero runtime deps beyond `@suaveplan/error`.
+
+## When to use this skill
+
+- Implementing or debugging code that imports `@suaveplan/bitpacker`.
+- The task touches: see package README.
+- You need API guidance for this package's exports.
+
+## Quick reference
+
+```ts
+import { /* see API Reference below */ } from "@suaveplan/bitpacker";
+```
+
+## Dependencies
+
+Workspace dependencies: `@suaveplan/error`, `@suaveplan/types`
+
+## Where to read more
+
+This skill is intentionally short. The package's own documentation is the authoritative source — read these in order:
+
+1. **`packages/bitpacker/bitpacker/README.md`** — overview, install, quick-start, module index
+2. **`packages/bitpacker/bitpacker/src/**/*.md`** — co-located docs per implementation file (Purpose, Features, Basic + Advanced examples, full API reference, Implementation notes — all packages  ship ≥200 words per module)
+3. **`packages/bitpacker/bitpacker/package.json`** `exports` map — every subpath you can import from
+
+When the user asks an API question, read the relevant co-located `.md` first; do not answer from training-data memory.
+
+## See also
+
+- `@suaveplan/error`
+- `@suaveplan/types`
+
+---
+
+_This SKILL.md is auto-generated by `suaveplan-skills/scripts/generate-skills.ts` from the package's README. Do not edit by hand — re-run the generator after the README changes._

docs/devtools/tooling/install-agent-skills/assets/skills/bytes/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: bytes
+description: Use when implementing or debugging code that uses @suaveplan/bytes: Low-level byte utilities: hex/base64/utf8 encoding, Uint8Array helpers, UUID conversion.
+---
+
+# @suaveplan/bytes
+
+Low-level byte utilities for Suaveplan: lossless hex/base64/UTF-8 encoding, `Uint8Array` manipulation, and UUID conversion. No native addons; depends only on platform globals (`TextEncoder`, `atob`/`btoa`, `crypto.randomUUID`) and `@suaveplan/error` for typed errors.
+
+## When to use this skill
+
+- Implementing or debugging code that imports `@suaveplan/bytes`.
+- The task touches: see package README.
+- You need API guidance for this package's exports.
+
+## Quick reference
+
+```ts
+import { /* see API Reference below */ } from "@suaveplan/bytes";
+```
+
+## Dependencies
+
+Workspace dependencies: `@suaveplan/error`, `@suaveplan/types`
+
+## Where to read more
+
+This skill is intentionally short. The package's own documentation is the authoritative source — read these in order:
+
+1. **`packages/foundation/bytes/README.md`** — overview, install, quick-start, module index
+2. **`packages/foundation/bytes/src/**/*.md`** — co-located docs per implementation file (Purpose, Features, Basic + Advanced examples, full API reference, Implementation notes — all packages  ship ≥200 words per module)
+3. **`packages/foundation/bytes/package.json`** `exports` map — every subpath you can import from
+
+When the user asks an API question, read the relevant co-located `.md` first; do not answer from training-data memory.
+
+## See also
+
+- `@suaveplan/error`
+- `@suaveplan/types`
+
+---
+
+_This SKILL.md is auto-generated by `suaveplan-skills/scripts/generate-skills.ts` from the package's README. Do not edit by hand — re-run the generator after the README changes._

docs/devtools/tooling/install-agent-skills/assets/skills/cache/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: cache
+description: Use when implementing or debugging code that uses @suaveplan/cache: Type-safe caching abstraction: LRU/LFU/FIFO/TTL MemoryCache, NamespacedCache, CacheFactory, stale-while-revalidate, multi-get/set, lifecycle events, injectable clock, OTel instrumentation, and structured CACHE.
+---
+
+# @suaveplan/cache
+
+Type-safe caching abstraction for Suaveplan. Provides `MemoryCache` with LRU/LFU/FIFO/TTL eviction, `NamespacedCache` for shared-storage isolation, a `CacheFactory` with module-augmentation-based provider registry, stale-while-revalidate, multi-get/set, injectable clock and event bus, OTel instrumentation, and structured `CACHE.*` error codes.
+
+## When to use this skill
+
+- Implementing or debugging code that imports `@suaveplan/cache`.
+- The task touches: see package README.
+- You need API guidance for this package's exports.
+
+## Quick reference
+
+```ts
+import { /* see API Reference below */ } from "@suaveplan/cache";
+```
+
+## Dependencies
+
+Workspace dependencies: `@suaveplan/error`, `@suaveplan/events`, `@suaveplan/types`
+
+## Where to read more
+
+This skill is intentionally short. The package's own documentation is the authoritative source — read these in order:
+
+1. **`packages/database/cache/README.md`** — overview, install, quick-start, module index
+2. **`packages/database/cache/src/**/*.md`** — co-located docs per implementation file (Purpose, Features, Basic + Advanced examples, full API reference, Implementation notes — all packages  ship ≥200 words per module)
+3. **`packages/database/cache/package.json`** `exports` map — every subpath you can import from
+
+When the user asks an API question, read the relevant co-located `.md` first; do not answer from training-data memory.
+
+## See also
+
+- `@suaveplan/error`
+- `@suaveplan/events`
+- `@suaveplan/types`
+
+---
+
+_This SKILL.md is auto-generated by `suaveplan-skills/scripts/generate-skills.ts` from the package's README. Do not edit by hand — re-run the generator after the README changes._

docs/devtools/tooling/install-agent-skills/assets/skills/cli/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: cli
+description: Use when implementing or debugging code that uses @suaveplan/cli: Zero-dependency CLI toolkit: argument parser, command router, ANSI styling, output formatting, spinner, progress bar, interactive prompts.
+---
+
+# @suaveplan/cli
+
+Enterprise-grade CLI framework for Node.js. Composable fluent API with subcommand routing, option parsing, OTel tracing, and a full set of terminal UI primitives.
+
+## When to use this skill
+
+- Implementing or debugging code that imports `@suaveplan/cli`.
+- The task touches: see package README.
+- You need API guidance for this package's exports.
+
+## Quick reference
+
+```ts
+import { /* see API Reference below */ } from "@suaveplan/cli";
+```
+
+## Dependencies
+
+Workspace dependencies: `@suaveplan/error`, `@suaveplan/readline`, `@suaveplan/types`
+
+## Where to read more
+
+This skill is intentionally short. The package's own documentation is the authoritative source — read these in order:
+
+1. **`packages/tooling/cli/README.md`** — overview, install, quick-start, module index
+2. **`packages/tooling/cli/src/**/*.md`** — co-located docs per implementation file (Purpose, Features, Basic + Advanced examples, full API reference, Implementation notes — all packages  ship ≥200 words per module)
+3. **`packages/tooling/cli/package.json`** `exports` map — every subpath you can import from
+
+When the user asks an API question, read the relevant co-located `.md` first; do not answer from training-data memory.
+
+## See also
+
+- `@suaveplan/error`
+- `@suaveplan/readline`
+- `@suaveplan/types`
+
+---
+
+_This SKILL.md is auto-generated by `suaveplan-skills/scripts/generate-skills.ts` from the package's README. Do not edit by hand — re-run the generator after the README changes._

docs/devtools/tooling/install-agent-skills/assets/skills/compress-image/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: compress-image
+description: Use when implementing or debugging code that uses @suaveplan/compress-image: Runtime-agnostic image compression utilities: resize, quality reduction, format conversion, and metadata stripping via pluggable adapters.
+---
+
+# @suaveplan/compress-image
+
+Runtime-agnostic image compression utilities with pluggable adapters for Node.js (Sharp) and testing (MemoryAdapter). Supports resize, quality reduction, format conversion (JPEG, PNG, WebP, AVIF), and metadata stripping.
+
+## When to use this skill
+
+- Implementing or debugging code that imports `@suaveplan/compress-image`.
+- The task touches: see package README.
+- You need API guidance for this package's exports.
+
+## Quick reference
+
+```ts
+import { /* see API Reference below */ } from "@suaveplan/compress-image";
+```
+
+## Dependencies
+
+Workspace dependencies: `@suaveplan/error`, `@suaveplan/types`
+
+## Where to read more
+
+This skill is intentionally short. The package's own documentation is the authoritative source — read these in order:
+
+1. **`packages/image/compress-image/README.md`** — overview, install, quick-start, module index
+2. **`packages/image/compress-image/src/**/*.md`** — co-located docs per implementation file (Purpose, Features, Basic + Advanced examples, full API reference, Implementation notes — all packages  ship ≥200 words per module)
+3. **`packages/image/compress-image/package.json`** `exports` map — every subpath you can import from
+
+When the user asks an API question, read the relevant co-located `.md` first; do not answer from training-data memory.
+
+## See also
+
+- `@suaveplan/error`
+- `@suaveplan/types`
+
+---
+
+_This SKILL.md is auto-generated by `suaveplan-skills/scripts/generate-skills.ts` from the package's README. Do not edit by hand — re-run the generator after the README changes._

docs/devtools/tooling/install-agent-skills/assets/skills/compress-svg/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: compress-svg
+description: Use when implementing or debugging code that uses @suaveplan/compress-svg: SVG optimisation and minification: whitespace removal, redundant attribute stripping, path data precision reduction, element collapsing, ID mangling, and SVGO-compatible plugin pipeline.
+---
+
+# @suaveplan/compress-svg
+
+SVG optimisation and minification for TypeScript. Pure TypeScript — no DOMParser, no external SVG library. Runs in Bun, Node.js, browsers, and edge runtimes.
+
+## When to use this skill
+
+- Implementing or debugging code that imports `@suaveplan/compress-svg`.
+- The task touches: see package README.
+- You need API guidance for this package's exports.
+
+## Quick reference
+
+```ts
+import { /* see API Reference below */ } from "@suaveplan/compress-svg";
+```
+
+## Dependencies
+
+Workspace dependencies: `@suaveplan/error`, `@suaveplan/types`
+
+## Where to read more
+
+This skill is intentionally short. The package's own documentation is the authoritative source — read these in order:
+
+1. **`packages/docs/compress-svg/README.md`** — overview, install, quick-start, module index
+2. **`packages/docs/compress-svg/src/**/*.md`** — co-located docs per implementation file (Purpose, Features, Basic + Advanced examples, full API reference, Implementation notes — all packages  ship ≥200 words per module)
+3. **`packages/docs/compress-svg/package.json`** `exports` map — every subpath you can import from
+
+When the user asks an API question, read the relevant co-located `.md` first; do not answer from training-data memory.
+
+## See also
+
+- `@suaveplan/error`
+- `@suaveplan/types`
+
+---
+
+_This SKILL.md is auto-generated by `suaveplan-skills/scripts/generate-skills.ts` from the package's README. Do not edit by hand — re-run the generator after the README changes._

docs/devtools/tooling/install-agent-skills/assets/skills/config/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: config
+description: Use when implementing or debugging code that uses @suaveplan/config: Layered configuration management: defaults, file, object, env, CLI layers merged in priority order with deep-merge, Zod validation, OTel instrumentation, and event-bus watch support.
+---
+
+# @suaveplan/config
+
+Layered configuration management for Suaveplan. Resolves an ordered set of typed layers (defaults, file, object, env, CLI) in priority order, deep-merges the results, applies per-environment overrides, validates via a caller-supplied Zod schema or custom function, and exposes an immutable `ConfigStore` with live reload and event-bus change propagation.
+
+## When to use this skill
+
+- Implementing or debugging code that imports `@suaveplan/config`.
+- The task touches: see package README.
+- You need API guidance for this package's exports.
+
+## Quick reference
+
+```ts
+import { /* see API Reference below */ } from "@suaveplan/config";
+```
+
+## Dependencies
+
+Workspace dependencies: `@suaveplan/env`, `@suaveplan/error`, `@suaveplan/events`, `@suaveplan/types`
+
+## Where to read more
+
+This skill is intentionally short. The package's own documentation is the authoritative source — read these in order:
+
+1. **`packages/foundation/config/README.md`** — overview, install, quick-start, module index
+2. **`packages/foundation/config/src/**/*.md`** — co-located docs per implementation file (Purpose, Features, Basic + Advanced examples, full API reference, Implementation notes — all packages  ship ≥200 words per module)
+3. **`packages/foundation/config/package.json`** `exports` map — every subpath you can import from
+
+When the user asks an API question, read the relevant co-located `.md` first; do not answer from training-data memory.
+
+## See also
+
+- `@suaveplan/env`
+- `@suaveplan/error`
+- `@suaveplan/events`
+- `@suaveplan/types`
+
+---
+
+_This SKILL.md is auto-generated by `suaveplan-skills/scripts/generate-skills.ts` from the package's README. Do not edit by hand — re-run the generator after the README changes._

docs/devtools/tooling/install-agent-skills/assets/skills/crdt/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: crdt
+description: Use when implementing or debugging code that uses @suaveplan/crdt: Conflict-free replicated data types: G-Counter, PN-Counter, OR-Set, LWW-Register, MV-Register, 2P-Set, RGA, Vector Clock, and Sync Manager.
+---
+
+# @suaveplan/crdt
+
+Conflict-free Replicated Data Types (CRDTs) for distributed systems. Provides eight composable CRDT primitives plus a vector-clock and a sync manager that coordinate delta exchange across heterogeneous replicas.
+
+## When to use this skill
+
+- Implementing or debugging code that imports `@suaveplan/crdt`.
+- The task touches: see package README.
+- You need API guidance for this package's exports.
+
+## Quick reference
+
+```ts
+import { /* see API Reference below */ } from "@suaveplan/crdt";
+```
+
+## Dependencies
+
+Workspace dependencies: `@suaveplan/diff`, `@suaveplan/error`, `@suaveplan/events`, `@suaveplan/types`
+
+## Where to read more
+
+This skill is intentionally short. The package's own documentation is the authoritative source — read these in order:
+
+1. **`packages/foundation/crdt/README.md`** — overview, install, quick-start, module index
+2. **`packages/foundation/crdt/src/**/*.md`** — co-located docs per implementation file (Purpose, Features, Basic + Advanced examples, full API reference, Implementation notes — all packages  ship ≥200 words per module)
+3. **`packages/foundation/crdt/package.json`** `exports` map — every subpath you can import from
+
+When the user asks an API question, read the relevant co-located `.md` first; do not answer from training-data memory.
+
+## See also
+
+- `@suaveplan/diff`
+- `@suaveplan/error`
+- `@suaveplan/events`
+- `@suaveplan/types`
+
+---
+
+_This SKILL.md is auto-generated by `suaveplan-skills/scripts/generate-skills.ts` from the package's README. Do not edit by hand — re-run the generator after the README changes._

docs/devtools/tooling/install-agent-skills/assets/skills/crypto-browser/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: crypto-browser
+description: Use when implementing or debugging code that uses @suaveplan/crypto-browser: WebCrypto-backed engine implementations for @suaveplan/crypto — AES-256-GCM, Ed25519, ECDSA-P256/P384, X25519, ECDH, RSA, AES-KW, and non-extractable key support via crypto.
+---
+
+# @suaveplan/crypto-browser
+
+WebCrypto-backed engine implementations for `@suaveplan/crypto` — AES-256-GCM, Ed25519, ECDSA-P256/P384, X25519, ECDH-P256/P384, RSA, AES-KW, and non-extractable key support via `crypto.subtle`. Zero third-party cryptography dependencies.
+
+## When to use this skill
+
+- Implementing or debugging code that imports `@suaveplan/crypto-browser`.
+- The task touches: see package README.
+- You need API guidance for this package's exports.
+
+## Quick reference
+
+```ts
+import { /* see API Reference below */ } from "@suaveplan/crypto-browser";
+```
+
+## Dependencies
+
+Workspace dependencies: `@suaveplan/crypto`, `@suaveplan/error`
+
+## Where to read more
+
+This skill is intentionally short. The package's own documentation is the authoritative source — read these in order:
+
+1. **`packages/crypto/crypto-browser/README.md`** — overview, install, quick-start, module index
+2. **`packages/crypto/crypto-browser/src/**/*.md`** — co-located docs per implementation file (Purpose, Features, Basic + Advanced examples, full API reference, Implementation notes — all packages  ship ≥200 words per module)
+3. **`packages/crypto/crypto-browser/package.json`** `exports` map — every subpath you can import from
+
+When the user asks an API question, read the relevant co-located `.md` first; do not answer from training-data memory.
+
+## See also
+
+- `@suaveplan/crypto`
+- `@suaveplan/error`
+
+---
+
+_This SKILL.md is auto-generated by `suaveplan-skills/scripts/generate-skills.ts` from the package's README. Do not edit by hand — re-run the generator after the README changes._

docs/devtools/tooling/install-agent-skills/assets/skills/crypto-cipher/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: crypto-cipher
+description: Use when implementing or debugging code that uses @suaveplan/crypto-cipher: AEAD cipher primitives with per-primitive selector layout: aes-256-gcm, chacha20-poly1305, xchacha20-poly1305.
+---
+
+# @suaveplan/crypto-cipher
+
+Low-level AEAD (Authenticated Encryption with Associated Data) cipher primitives for the `@suaveplan/crypto` stack. Provides three algorithms — AES-256-GCM, ChaCha20-Poly1305, and XChaCha20-Poly1305 — each as a standalone subpath export for tree-shaking. Nonces are always caller-supplied: the package validates nonce length but never generates randomness internally, keeping the CSPRNG boundary in the caller's control. Implementation flavour (`'noble'` vs `'native'`) is selected at build time via `crypto.config.ts`; all Phase 0 implementations route to `@noble/ciphers`. Use `@suaveplan/crypto` for the high-level façade that combines nonce generation, engine selection, and structured error handling; use this package only when you need to supply your own cipher engine implementation.
+
+## When to use this skill
+
+- Implementing or debugging code that imports `@suaveplan/crypto-cipher`.
+- The task touches: see package README.
+- You need API guidance for this package's exports.
+
+## Quick reference
+
+```ts
+import { /* see API Reference below */ } from "@suaveplan/crypto-cipher";
+```
+
+## Dependencies
+
+Workspace dependencies: `@suaveplan/crypto-utils`, `@suaveplan/error`, `@suaveplan/types`
+
+## Where to read more
+
+This skill is intentionally short. The package's own documentation is the authoritative source — read these in order:
+
+1. **`packages/crypto/crypto-cipher/README.md`** — overview, install, quick-start, module index
+2. **`packages/crypto/crypto-cipher/src/**/*.md`** — co-located docs per implementation file (Purpose, Features, Basic + Advanced examples, full API reference, Implementation notes — all packages  ship ≥200 words per module)
+3. **`packages/crypto/crypto-cipher/package.json`** `exports` map — every subpath you can import from
+
+When the user asks an API question, read the relevant co-located `.md` first; do not answer from training-data memory.
+
+## See also
+
+- `@suaveplan/crypto-utils`
+- `@suaveplan/error`
+- `@suaveplan/types`
+
+---
+
+_This SKILL.md is auto-generated by `suaveplan-skills/scripts/generate-skills.ts` from the package's README. Do not edit by hand — re-run the generator after the README changes._

docs/devtools/tooling/install-agent-skills/assets/skills/crypto-curve/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: crypto-curve
+description: Use when implementing or debugging code that uses @suaveplan/crypto-curve: Elliptic-curve primitives with per-primitive selector layout: secp256k1, ed25519, x25519, p256.
+---
+
+# @suaveplan/crypto-curve
+
+Low-level elliptic-curve building blocks for the `@suaveplan/crypto` stack. Exposes four curves — secp256k1, Ed25519, X25519, and NIST P-256 — each as a standalone subpath export so bundlers only ship the primitives actually used. Every curve provides key generation, signing/verification (or key agreement), and raw byte operations. Implementation flavour (`'noble'` vs `'native'`) is selected at build time via the repo-root `crypto.config.ts`; all Phase 0 implementations route to `@noble/curves`. Use this package when you need raw curve operations; for high-level AEAD, signing, or sealed-box use `@suaveplan/crypto` instead.
+
+## When to use this skill
+
+- Implementing or debugging code that imports `@suaveplan/crypto-curve`.
+- The task touches: see package README.
+- You need API guidance for this package's exports.
+
+## Quick reference
+
+```ts
+import { /* see API Reference below */ } from "@suaveplan/crypto-curve";
+```
+
+## Dependencies
+
+Workspace dependencies: `@suaveplan/crypto-hash`, `@suaveplan/crypto-utils`, `@suaveplan/error`, `@suaveplan/types`
+
+## Where to read more
+
+This skill is intentionally short. The package's own documentation is the authoritative source — read these in order:
+
+1. **`packages/crypto/crypto-curve/README.md`** — overview, install, quick-start, module index
+2. **`packages/crypto/crypto-curve/src/**/*.md`** — co-located docs per implementation file (Purpose, Features, Basic + Advanced examples, full API reference, Implementation notes — all packages  ship ≥200 words per module)
+3. **`packages/crypto/crypto-curve/package.json`** `exports` map — every subpath you can import from
+
+When the user asks an API question, read the relevant co-located `.md` first; do not answer from training-data memory.
+
+## See also
+
+- `@suaveplan/crypto-hash`
+- `@suaveplan/crypto-utils`
+- `@suaveplan/error`
+- `@suaveplan/types`
+
+---
+
+_This SKILL.md is auto-generated by `suaveplan-skills/scripts/generate-skills.ts` from the package's README. Do not edit by hand — re-run the generator after the README changes._

docs/devtools/tooling/install-agent-skills/assets/skills/crypto-hash/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: crypto-hash
+description: Use when implementing or debugging code that uses @suaveplan/crypto-hash: Pure-TypeScript hashing substrate — SHA-2 digests, HMAC, HKDF, PBKDF2, Argon2id, hex/Base64 encoding.
+---
+
+# @suaveplan/crypto-hash
+
+Pure-TypeScript hashing substrate. SHA-2 digests, HMAC, HKDF, PBKDF2, Argon2id, and hex/Base64 encoding — no WASM, no browser globals, fully tree-shakeable.
+
+## When to use this skill
+
+- Implementing or debugging code that imports `@suaveplan/crypto-hash`.
+- The task touches: see package README.
+- You need API guidance for this package's exports.
+
+## Quick reference
+
+```ts
+import { /* see API Reference below */ } from "@suaveplan/crypto-hash";
+```
+
+## Dependencies
+
+Workspace dependencies: `@suaveplan/crypto-utils`, `@suaveplan/error`, `@suaveplan/types`
+
+## Where to read more
+
+This skill is intentionally short. The package's own documentation is the authoritative source — read these in order:
+
+1. **`packages/crypto/crypto-hash/README.md`** — overview, install, quick-start, module index
+2. **`packages/crypto/crypto-hash/src/**/*.md`** — co-located docs per implementation file (Purpose, Features, Basic + Advanced examples, full API reference, Implementation notes — all packages  ship ≥200 words per module)
+3. **`packages/crypto/crypto-hash/package.json`** `exports` map — every subpath you can import from
+
+When the user asks an API question, read the relevant co-located `.md` first; do not answer from training-data memory.
+
+## See also
+
+- `@suaveplan/crypto-utils`
+- `@suaveplan/error`
+- `@suaveplan/types`
+
+---
+
+_This SKILL.md is auto-generated by `suaveplan-skills/scripts/generate-skills.ts` from the package's README. Do not edit by hand — re-run the generator after the README changes._

docs/devtools/tooling/install-agent-skills/assets/skills/crypto-keys/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: crypto-keys
+description: Use when implementing or debugging code that uses @suaveplan/crypto-keys: Keypair generation, validation, and keychain store for @suaveplan/crypto — Ed25519, ECDSA-P256, X25519, pluggable adapters.
+---
+
+# @suaveplan/crypto-keys
+
+Keypair generation, validation, and keychain management for the `@suaveplan` stack. Delegates cryptographic operations to `@suaveplan/crypto` while adding key lifecycle utilities: tagging keypairs with their algorithm, validating structural and cryptographic correctness, and storing named keypairs with pluggable persistence adapters.
+
+## When to use this skill
+
+- Implementing or debugging code that imports `@suaveplan/crypto-keys`.
+- The task touches: see package README.
+- You need API guidance for this package's exports.
+
+## Quick reference
+
+```ts
+import { /* see API Reference below */ } from "@suaveplan/crypto-keys";
+```
+
+## Dependencies
+
+Workspace dependencies: `@suaveplan/crypto`, `@suaveplan/error`, `@suaveplan/types`
+
+## Where to read more
+
+This skill is intentionally short. The package's own documentation is the authoritative source — read these in order:
+
+1. **`packages/crypto/crypto-keys/README.md`** — overview, install, quick-start, module index
+2. **`packages/crypto/crypto-keys/src/**/*.md`** — co-located docs per implementation file (Purpose, Features, Basic + Advanced examples, full API reference, Implementation notes — all packages  ship ≥200 words per module)
+3. **`packages/crypto/crypto-keys/package.json`** `exports` map — every subpath you can import from
+
+When the user asks an API question, read the relevant co-located `.md` first; do not answer from training-data memory.
+
+## See also
+
+- `@suaveplan/crypto`
+- `@suaveplan/error`
+- `@suaveplan/types`
+
+---
+
+_This SKILL.md is auto-generated by `suaveplan-skills/scripts/generate-skills.ts` from the package's README. Do not edit by hand — re-run the generator after the README changes._

docs/devtools/tooling/install-agent-skills/assets/skills/crypto-sodium/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: crypto-sodium
+description: Use when implementing or debugging code that uses @suaveplan/crypto-sodium: libsodium-backed engine implementations for @suaveplan/crypto — AEAD (XChaCha20-Poly1305, ChaCha20-Poly1305, AES-256-GCM), Ed25519 sign, X25519 agree, sealed-box, auth-box, KDF, BLAKE2b auth, Argon2id pwhash, Ristretto255 group ops.
+---
+
+# @suaveplan/crypto-sodium
+
+libsodium-backed engine implementations for `@suaveplan/crypto`. Provides AEAD encryption, Ed25519 signing, X25519 key agreement, sealed-box, auth-box, deterministic KDF, BLAKE2b MAC, Argon2id password hashing, and Ristretto255 group operations — all via the `libsodium-wrappers-sumo` WASM module.
+
+## When to use this skill
+
+- Implementing or debugging code that imports `@suaveplan/crypto-sodium`.
+- The task touches: see package README.
+- You need API guidance for this package's exports.
+
+## Quick reference
+
+```ts
+import { /* see API Reference below */ } from "@suaveplan/crypto-sodium";
+```
+
+## Dependencies
+
+Workspace dependencies: `@suaveplan/crypto`, `@suaveplan/error`
+
+## Where to read more
+
+This skill is intentionally short. The package's own documentation is the authoritative source — read these in order:
+
+1. **`packages/crypto/crypto-sodium/README.md`** — overview, install, quick-start, module index
+2. **`packages/crypto/crypto-sodium/src/**/*.md`** — co-located docs per implementation file (Purpose, Features, Basic + Advanced examples, full API reference, Implementation notes — all packages  ship ≥200 words per module)
+3. **`packages/crypto/crypto-sodium/package.json`** `exports` map — every subpath you can import from
+
+When the user asks an API question, read the relevant co-located `.md` first; do not answer from training-data memory.
+
+## See also
+
+- `@suaveplan/crypto`
+- `@suaveplan/error`
+
+---
+
+_This SKILL.md is auto-generated by `suaveplan-skills/scripts/generate-skills.ts` from the package's README. Do not edit by hand — re-run the generator after the README changes._

docs/devtools/tooling/install-agent-skills/assets/skills/crypto-utils/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: crypto-utils
+description: Use when implementing or debugging code that uses @suaveplan/crypto-utils: Shared cryptographic utilities: encoding (hex/base64/base64url/base58), byte helpers (concat/xor/i2osp/os2ip), constant-time equality, random bytes, zeroize, Merkle tree helpers, KAT/differential-fuzz test harnesses, PrimitiveId registry, PrimitiveNotImplemented error.
+---
+
+# @suaveplan/crypto-utils
+
+Shared cryptographic utilities consumed internally by all other `@suaveplan/crypto-*` packages. Provides the low-level primitives that every crypto implementation needs but that belong in one place: multi-alphabet encoding (`toHex`/`fromHex`, `toBase64`/`fromBase64`, `toBase64Url`, `toBase58`/`fromBase58`); byte helpers (`concatBytes`, `xor`, `i2osp`/`os2ip` for integer-to-octet-string conversions); `constantTimeEqual` for timing-safe comparisons; `randomBytes` with an injectable `ByteSource`; `zeroize` for wiping key material; Merkle tree helpers (`merkleRoot`, `merkleProof`, `verifyMerkleProof`); a `PrimitiveId` registry and `PrimitiveNotImplemented` sentinel error; and KAT/differential-fuzz harnesses (`runVectors`, `diffFuzz`) used in every crypto primitive's test suite. Zero runtime crypto dependencies — this package provides helpers only, not cryptographic algorithms. Application code should generally import from `@suaveplan/crypto` or `@suaveplan/crypto-hash`; import from this package only when building a new cryptographic primitive or engine adapter.
+
+## When to use this skill
+
+- Implementing or debugging code that imports `@suaveplan/crypto-utils`.
+- The task touches: see package README.
+- You need API guidance for this package's exports.
+
+## Quick reference
+
+```ts
+import { /* see API Reference below */ } from "@suaveplan/crypto-utils";
+```
+
+## Dependencies
+
+Workspace dependencies: `@suaveplan/bytes`, `@suaveplan/error`, `@suaveplan/types`
+
+## Where to read more
+
+This skill is intentionally short. The package's own documentation is the authoritative source — read these in order:
+
+1. **`packages/crypto/crypto-utils/README.md`** — overview, install, quick-start, module index
+2. **`packages/crypto/crypto-utils/src/**/*.md`** — co-located docs per implementation file (Purpose, Features, Basic + Advanced examples, full API reference, Implementation notes — all packages  ship ≥200 words per module)
+3. **`packages/crypto/crypto-utils/package.json`** `exports` map — every subpath you can import from
+
+When the user asks an API question, read the relevant co-located `.md` first; do not answer from training-data memory.
+
+## See also
+
+- `@suaveplan/bytes`
+- `@suaveplan/error`
+- `@suaveplan/types`
+
+---
+
+_This SKILL.md is auto-generated by `suaveplan-skills/scripts/generate-skills.ts` from the package's README. Do not edit by hand — re-run the generator after the README changes._

docs/devtools/tooling/install-agent-skills/assets/skills/crypto-vault/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: crypto-vault
+description: Use when implementing or debugging code that uses @suaveplan/crypto-vault: BIP39 mnemonic, Argon2id-locked vault, and chain signer for @suaveplan/crypto — deterministic HD key derivation, zeroize-on-lock, typed events.
+---
+
+# @suaveplan/crypto-vault
+
+BIP39 mnemonic management, Argon2id-hardened hierarchical key derivation, and multi-algorithm signing registry for the Suaveplan platform. The `Vault` class generates or imports a 12/15/18/21/24-word BIP39 mnemonic, unlocks it into a locked/unlocked state machine, derives named signing keys from HD paths (`m/signing/0`, `m/auth/0`, etc.) using either Ed25519 or ECDSA-P256, and zeroizes all key material on `lock()`. The `ChainSigner` is a standalone multi-key registry that associates named keys with signing algorithms for multi-signature workflows. Events (unlock/lock/derive/sign) are emitted via `@suaveplan/events` for audit trails. This package sits above `@suaveplan/crypto-keys` (raw keypair generation) and `@suaveplan/crypto` (primitive operations) — use it when you need mnemonic-seeded key hierarchies, not just raw keypairs.
+
+## When to use this skill
+
+- Implementing or debugging code that imports `@suaveplan/crypto-vault`.
+- The task touches: see package README.
+- You need API guidance for this package's exports.
+
+## Quick reference
+
+```ts
+import { /* see API Reference below */ } from "@suaveplan/crypto-vault";
+```
+
+## Dependencies
+
+Workspace dependencies: `@suaveplan/crypto`, `@suaveplan/crypto-hash`, `@suaveplan/crypto-keys`, `@suaveplan/error`, `@suaveplan/events`, `@suaveplan/types`
+
+## Where to read more
+
+This skill is intentionally short. The package's own documentation is the authoritative source — read these in order:
+
+1. **`packages/crypto/crypto-vault/README.md`** — overview, install, quick-start, module index
+2. **`packages/crypto/crypto-vault/src/**/*.md`** — co-located docs per implementation file (Purpose, Features, Basic + Advanced examples, full API reference, Implementation notes — all packages  ship ≥200 words per module)
+3. **`packages/crypto/crypto-vault/package.json`** `exports` map — every subpath you can import from
+
+When the user asks an API question, read the relevant co-located `.md` first; do not answer from training-data memory.
+
+## See also
+
+- `@suaveplan/crypto`
+- `@suaveplan/crypto-hash`
+- `@suaveplan/crypto-keys`
+- `@suaveplan/error`
+- `@suaveplan/events`
+- `@suaveplan/types`
+
+---
+
+_This SKILL.md is auto-generated by `suaveplan-skills/scripts/generate-skills.ts` from the package's README. Do not edit by hand — re-run the generator after the README changes._

docs/devtools/tooling/install-agent-skills/assets/skills/crypto/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: crypto
+description: Use when implementing or debugging code that uses @suaveplan/crypto: Universal cryptographic primitives — AEAD (AES-256-GCM, ChaCha20-Poly1305, XChaCha20-Poly1305), Ed25519 / X25519 / ECDSA-P256, sealed-box, auth-box, constant-time compare, zeroize.
+---
+
+# @suaveplan/crypto
+
+Universal cryptographic primitives — engine-pluggable AEAD, Ed25519/ECDSA-P256 signing, X25519 key agreement, sealed-box, and auth-box. Built on audited [@noble/*](https://paulmillr.com/noble/) libraries with zero WASM.
+
+## When to use this skill
+
+- Implementing or debugging code that imports `@suaveplan/crypto`.
+- The task touches: see package README.
+- You need API guidance for this package's exports.
+
+## Quick reference
+
+```ts
+import { /* see API Reference below */ } from "@suaveplan/crypto";
+```
+
+## Dependencies
+
+Workspace dependencies: `@suaveplan/crypto-cipher`, `@suaveplan/crypto-curve`, `@suaveplan/crypto-hash`, `@suaveplan/crypto-utils`, `@suaveplan/error`, `@suaveplan/types`
+
+## Where to read more
+
+This skill is intentionally short. The package's own documentation is the authoritative source — read these in order:
+
+1. **`packages/crypto/crypto/README.md`** — overview, install, quick-start, module index
+2. **`packages/crypto/crypto/src/**/*.md`** — co-located docs per implementation file (Purpose, Features, Basic + Advanced examples, full API reference, Implementation notes — all packages  ship ≥200 words per module)
+3. **`packages/crypto/crypto/package.json`** `exports` map — every subpath you can import from
+
+When the user asks an API question, read the relevant co-located `.md` first; do not answer from training-data memory.
+
+## See also
+
+- `@suaveplan/crypto-cipher`
+- `@suaveplan/crypto-curve`
+- `@suaveplan/crypto-hash`
+- `@suaveplan/crypto-utils`
+- `@suaveplan/error`
+- `@suaveplan/types`
+
+---
+
+_This SKILL.md is auto-generated by `suaveplan-skills/scripts/generate-skills.ts` from the package's README. Do not edit by hand — re-run the generator after the README changes._

docs/devtools/tooling/install-agent-skills/assets/skills/data-masking/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: data-masking
+description: Use when implementing or debugging code that uses @suaveplan/data-masking: PII/sensitive data masking for objects and strings: field-level masking rules, nested object traversal, format-preserving masking, tokenization, and FNV-1a hashing.
+---
+
+# @suaveplan/data-masking
+
+PII/sensitive data masking for objects and strings with field-level rules, nested traversal, eight masking strategies, and OpenTelemetry instrumentation.
+
+## When to use this skill
+
+- Implementing or debugging code that imports `@suaveplan/data-masking`.
+- The task touches: see package README.
+- You need API guidance for this package's exports.
+
+## Quick reference
+
+```ts
+import { /* see API Reference below */ } from "@suaveplan/data-masking";
+```
+
+## Dependencies
+
+Workspace dependencies: _none_
+
+## Where to read more
+
+This skill is intentionally short. The package's own documentation is the authoritative source — read these in order:
+
+1. **`packages/platform/data-masking/README.md`** — overview, install, quick-start, module index
+2. **`packages/platform/data-masking/src/**/*.md`** — co-located docs per implementation file (Purpose, Features, Basic + Advanced examples, full API reference, Implementation notes — all packages  ship ≥200 words per module)
+3. **`packages/platform/data-masking/package.json`** `exports` map — every subpath you can import from
+
+When the user asks an API question, read the relevant co-located `.md` first; do not answer from training-data memory.
+
+## See also
+
+- The marketplace root: `../../../README.md`
+
+---
+
+_This SKILL.md is auto-generated by `suaveplan-skills/scripts/generate-skills.ts` from the package's README. Do not edit by hand — re-run the generator after the README changes._

docs/devtools/tooling/install-agent-skills/assets/skills/datetime/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: datetime
+description: Use when implementing or debugging code that uses @suaveplan/datetime: Timezone-aware date/time utilities with business-day arithmetic, recurrence rules, calendar math, and relative time formatting.
+---
+
+# @suaveplan/datetime
+
+Timezone-aware date/time utilities covering the most common application-layer date operations that the native `Date` API leaves unaddressed. The package provides calendar math (`addDuration`, `subtractDuration`, `startOf`, `endOf`, `getCalendarMonth`, leap-year detection), business-day arithmetic with configurable holiday calendars and custom weekend definitions, an RRULE-subset recurrence engine (DAILY/WEEKLY/MONTHLY/YEARLY with BYDAY/BYMONTH/COUNT/UNTIL), and human-readable relative time formatting (`"3 hours ago"`, `"in 2 days"`). All stateful entry points accept an injectable `Clock` for deterministic testing. Use this package for scheduling UIs, calendar components, invoice date calculations, and any domain where "next business day" or "every other Monday" has real meaning. For low-level stopwatches, throttle/debounce, or vector clocks use `@suaveplan/timing`.
+
+## When to use this skill
+
+- Implementing or debugging code that imports `@suaveplan/datetime`.
+- The task touches: see package README.
+- You need API guidance for this package's exports.
+
+## Quick reference
+
+```ts
+import { /* see API Reference below */ } from "@suaveplan/datetime";
+```
+
+## Dependencies
+
+Workspace dependencies: `@suaveplan/error`, `@suaveplan/types`
+
+## Where to read more
+
+This skill is intentionally short. The package's own documentation is the authoritative source — read these in order:
+
+1. **`packages/foundation/datetime/README.md`** — overview, install, quick-start, module index
+2. **`packages/foundation/datetime/src/**/*.md`** — co-located docs per implementation file (Purpose, Features, Basic + Advanced examples, full API reference, Implementation notes — all packages  ship ≥200 words per module)
+3. **`packages/foundation/datetime/package.json`** `exports` map — every subpath you can import from
+
+When the user asks an API question, read the relevant co-located `.md` first; do not answer from training-data memory.
+
+## See also
+
+- `@suaveplan/error`
+- `@suaveplan/types`
+
+---
+
+_This SKILL.md is auto-generated by `suaveplan-skills/scripts/generate-skills.ts` from the package's README. Do not edit by hand — re-run the generator after the README changes._

docs/devtools/tooling/install-agent-skills/assets/skills/db-sqlite/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: db-sqlite
+description: Use when implementing or debugging code that uses @suaveplan/db-sqlite: Universal SQLite adapter for Suaveplan: bun:sqlite on the Bun server, @sqlite.
+---
+
+# @suaveplan/db-sqlite
+
+Universal SQLite adapter for Suaveplan: bun:sqlite on the Bun server, @sqlite.org/sqlite-wasm in the browser, unified behind a Drizzle-ORM surface with LRU prepared-statement cache, forward-only migration runner, OTel instrumentation, and structured SQLITE.* error codes.
+
+## When to use this skill
+
+- Implementing or debugging code that imports `@suaveplan/db-sqlite`.
+- The task touches: see package README.
+- You need API guidance for this package's exports.
+
+## Quick reference
+
+```ts
+import { /* see API Reference below */ } from "@suaveplan/db-sqlite";
+```
+
+## Dependencies
+
+Workspace dependencies: `@suaveplan/db`, `@suaveplan/error`, `@suaveplan/types`
+
+## Where to read more
+
+This skill is intentionally short. The package's own documentation is the authoritative source — read these in order:
+
+1. **`packages/database/db-sqlite/README.md`** — overview, install, quick-start, module index
+2. **`packages/database/db-sqlite/src/**/*.md`** — co-located docs per implementation file (Purpose, Features, Basic + Advanced examples, full API reference, Implementation notes — all packages  ship ≥200 words per module)
+3. **`packages/database/db-sqlite/package.json`** `exports` map — every subpath you can import from
+
+When the user asks an API question, read the relevant co-located `.md` first; do not answer from training-data memory.
+
+## See also
+
+- `@suaveplan/db`
+- `@suaveplan/error`
+- `@suaveplan/types`
+
+---
+
+_This SKILL.md is auto-generated by `suaveplan-skills/scripts/generate-skills.ts` from the package's README. Do not edit by hand — re-run the generator after the README changes._

docs/devtools/tooling/install-agent-skills/assets/skills/db/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: db
+description: Use when implementing or debugging code that uses @suaveplan/db: Universal relational database adapter interface: DatabaseAdapter (extends DatabaseLike), structured DB.
+---
+
+# @suaveplan/db
+
+Universal relational database adapter interface for Suaveplan. Provides the `DatabaseAdapter` contract (extending `DatabaseLike` from `@suaveplan/types`), injectable connection singletons, structured `DB.*` error codes, Zod-validated config types, a `MigrationRunner` interface, and full OpenTelemetry instrumentation.
+
+## When to use this skill
+
+- Implementing or debugging code that imports `@suaveplan/db`.
+- The task touches: see package README.
+- You need API guidance for this package's exports.
+
+## Quick reference
+
+```ts
+import { /* see API Reference below */ } from "@suaveplan/db";
+```
+
+## Dependencies
+
+Workspace dependencies: `@suaveplan/error`, `@suaveplan/types`
+
+## Where to read more
+
+This skill is intentionally short. The package's own documentation is the authoritative source — read these in order:
+
+1. **`packages/database/db/README.md`** — overview, install, quick-start, module index
+2. **`packages/database/db/src/**/*.md`** — co-located docs per implementation file (Purpose, Features, Basic + Advanced examples, full API reference, Implementation notes — all packages  ship ≥200 words per module)
+3. **`packages/database/db/package.json`** `exports` map — every subpath you can import from
+
+When the user asks an API question, read the relevant co-located `.md` first; do not answer from training-data memory.
+
+## See also
+
+- `@suaveplan/error`
+- `@suaveplan/types`
+
+---
+
+_This SKILL.md is auto-generated by `suaveplan-skills/scripts/generate-skills.ts` from the package's README. Do not edit by hand — re-run the generator after the README changes._

docs/devtools/tooling/install-agent-skills/assets/skills/dedup/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: dedup
+description: Use when implementing or debugging code that uses @suaveplan/dedup: Entity deduplication engine with pluggable match keys, scoring rules, Jaro-Winkler/Levenshtein similarity, and merge strategies.
+---
+
+# @suaveplan/dedup
+
+Entity deduplication engine for detecting and merging duplicate records in any data set. Given a list of objects with varying representations of the same real-world entity (e.g. `"John Smith"` vs `"J. Smith"`, or the same email in different capitalisation), the `DedupEngine` scores pairs using a weighted combination of field-level similarity algorithms — Jaro-Winkler, Levenshtein, exact match, or phonetic — groups records into connected components via union-find, and merges each group with a pluggable strategy (`latestWins`, `manual`, or `scoredMerge`). Use this package for ETL pipelines, contact deduplication, and data cleansing. For domain-name-specific normalisation and alias resolution use `@suaveplan/domain-normalizer`; for string-similarity primitives only, the scoring module is exported as a standalone subpath.
+
+## When to use this skill
+
+- Implementing or debugging code that imports `@suaveplan/dedup`.
+- The task touches: see package README.
+- You need API guidance for this package's exports.
+
+## Quick reference
+
+```ts
+import { /* see API Reference below */ } from "@suaveplan/dedup";
+```
+
+## Dependencies
+
+Workspace dependencies: _none_
+
+## Where to read more
+
+This skill is intentionally short. The package's own documentation is the authoritative source — read these in order:
+
+1. **`packages/foundation/dedup/README.md`** — overview, install, quick-start, module index
+2. **`packages/foundation/dedup/src/**/*.md`** — co-located docs per implementation file (Purpose, Features, Basic + Advanced examples, full API reference, Implementation notes — all packages  ship ≥200 words per module)
+3. **`packages/foundation/dedup/package.json`** `exports` map — every subpath you can import from
+
+When the user asks an API question, read the relevant co-located `.md` first; do not answer from training-data memory.
+
+## See also
+
+- The marketplace root: `../../../README.md`
+
+---
+
+_This SKILL.md is auto-generated by `suaveplan-skills/scripts/generate-skills.ts` from the package's README. Do not edit by hand — re-run the generator after the README changes._

docs/devtools/tooling/install-agent-skills/assets/skills/diff/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: diff
+description: Use when implementing or debugging code that uses @suaveplan/diff: Zero-dependency RFC 6902 JSON Patch engine with structural diffing, patch application/inversion, linear history manager, sync manager, and rich path utilities.
+---
+
+# @suaveplan/diff
+
+Zero-dependency RFC 6902 JSON Patch engine for computing, applying, and inverting structural differences between JSON documents. The `diff(a, b)` function produces a minimal patch using index-based or LCS array strategies; `applyPatch` applies it; `revertPatch` undoes it; and `invertPatch` creates an inverse patch. A `HistoryManager` provides undo/redo with configurable depth and branch truncation on new edits. A `SyncManager` handles optimistic concurrency: apply local changes speculatively, then reconcile when the server responds. RFC 6901 JSON Pointer parsing and formatting is exposed as a standalone `path` module. Use this package for collaborative editing, undo/redo stacks, change-event streams, and any system where you need to track or transmit the delta between two object states rather than the full state itself.
+
+## When to use this skill
+
+- Implementing or debugging code that imports `@suaveplan/diff`.
+- The task touches: see package README.
+- You need API guidance for this package's exports.
+
+## Quick reference
+
+```ts
+import { /* see API Reference below */ } from "@suaveplan/diff";
+```
+
+## Dependencies
+
+Workspace dependencies: _none_
+
+## Where to read more
+
+This skill is intentionally short. The package's own documentation is the authoritative source — read these in order:
+
+1. **`packages/foundation/diff/README.md`** — overview, install, quick-start, module index
+2. **`packages/foundation/diff/src/**/*.md`** — co-located docs per implementation file (Purpose, Features, Basic + Advanced examples, full API reference, Implementation notes — all packages  ship ≥200 words per module)
+3. **`packages/foundation/diff/package.json`** `exports` map — every subpath you can import from
+
+When the user asks an API question, read the relevant co-located `.md` first; do not answer from training-data memory.
+
+## See also
+
+- The marketplace root: `../../../README.md`
+
+---
+
+_This SKILL.md is auto-generated by `suaveplan-skills/scripts/generate-skills.ts` from the package's README. Do not edit by hand — re-run the generator after the README changes._

docs/devtools/tooling/install-agent-skills/assets/skills/dmarc/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: dmarc
+description: Use when implementing or debugging code that uses @suaveplan/dmarc: DMARC report parser — parses aggregate (RUA) and forensic (RUF) DMARC XML reports into typed structures.
+---
+
+# @suaveplan/dmarc
+
+DMARC report parser for `@suaveplan` — parses aggregate (RUA) and forensic (RUF) DMARC XML reports into validated, strongly-typed structures. Accepts raw XML strings or gzip-compressed binary blobs.
+
+## When to use this skill
+
+- Implementing or debugging code that imports `@suaveplan/dmarc`.
+- The task touches: see package README.
+- You need API guidance for this package's exports.
+
+## Quick reference
+
+```ts
+import { /* see API Reference below */ } from "@suaveplan/dmarc";
+```
+
+## Dependencies
+
+Workspace dependencies: _none_
+
+## Where to read more
+
+This skill is intentionally short. The package's own documentation is the authoritative source — read these in order:
+
+1. **`packages/emails/dmarc/README.md`** — overview, install, quick-start, module index
+2. **`packages/emails/dmarc/src/**/*.md`** — co-located docs per implementation file (Purpose, Features, Basic + Advanced examples, full API reference, Implementation notes — all packages  ship ≥200 words per module)
+3. **`packages/emails/dmarc/package.json`** `exports` map — every subpath you can import from
+
+When the user asks an API question, read the relevant co-located `.md` first; do not answer from training-data memory.
+
+## See also
+
+- The marketplace root: `../../../README.md`
+
+---
+
+_This SKILL.md is auto-generated by `suaveplan-skills/scripts/generate-skills.ts` from the package's README. Do not edit by hand — re-run the generator after the README changes._

docs/devtools/tooling/install-agent-skills/assets/skills/domain-normalizer/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: domain-normalizer
+description: Use when implementing or debugging code that uses @suaveplan/domain-normalizer: Normalisation, matching, and alias-canonicalisation for internet domain names.
+---
+
+# @suaveplan/domain-normalizer
+
+Normalisation, matching, and alias-canonicalisation for internet domain names. Given heterogeneous URL or domain input — including common mobile/CDN subdomains and 31 built-in alias mappings (e.g. `m.youtube.com → youtube.com`, `old.reddit.com → reddit.com`) — this package produces a canonical registrable domain via `tldts`, strips `www`/`m`/`mobile` prefixes, resolves the alias map, and returns structured `NormalizedDomain` objects. It also provides Levenshtein-based similarity scoring (`computeSimilarity`), fuzzy matching (`matchDomains`), and a `groupDomains` function that clusters a mixed list by canonical root domain. Use this package for deduplicating contact email domains, canonicalising URLs before storage, and building domain-level blocklists. For full entity deduplication across arbitrary fields use `@suaveplan/dedup`; for MIME or URL content-type detection use `@suaveplan/mime`.
+
+## When to use this skill
+
+- Implementing or debugging code that imports `@suaveplan/domain-normalizer`.
+- The task touches: see package README.
+- You need API guidance for this package's exports.
+
+## Quick reference
+
+```ts
+import { /* see API Reference below */ } from "@suaveplan/domain-normalizer";
+```
+
+## Dependencies
+
+Workspace dependencies: _none_
+
+## Where to read more
+
+This skill is intentionally short. The package's own documentation is the authoritative source — read these in order:
+
+1. **`packages/foundation/domain-normalizer/README.md`** — overview, install, quick-start, module index
+2. **`packages/foundation/domain-normalizer/src/**/*.md`** — co-located docs per implementation file (Purpose, Features, Basic + Advanced examples, full API reference, Implementation notes — all packages  ship ≥200 words per module)
+3. **`packages/foundation/domain-normalizer/package.json`** `exports` map — every subpath you can import from
+
+When the user asks an API question, read the relevant co-located `.md` first; do not answer from training-data memory.
+
+## See also
+
+- The marketplace root: `../../../README.md`
+
+---
+
+_This SKILL.md is auto-generated by `suaveplan-skills/scripts/generate-skills.ts` from the package's README. Do not edit by hand — re-run the generator after the README changes._

docs/devtools/tooling/install-agent-skills/assets/skills/env/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: env
+description: Use when implementing or debugging code that uses @suaveplan/env: Type-safe environment variable loading: schema-first validation, field types, dotenv loader, presets, structured errors.
+---
+
+# @suaveplan/env
+
+Type-safe, schema-first environment variable loading for Node.js and edge runtimes. Define a schema of typed field builders, point it at your sources, and receive a frozen record with TypeScript types inferred at compile time — no manual type annotations required.
+
+## When to use this skill
+
+- Implementing or debugging code that imports `@suaveplan/env`.
+- The task touches: see package README.
+- You need API guidance for this package's exports.
+
+## Quick reference
+
+```ts
+import { /* see API Reference below */ } from "@suaveplan/env";
+```
+
+## Dependencies
+
+Workspace dependencies: `@suaveplan/error`, `@suaveplan/types`
+
+## Where to read more
+
+This skill is intentionally short. The package's own documentation is the authoritative source — read these in order:
+
+1. **`packages/foundation/env/README.md`** — overview, install, quick-start, module index
+2. **`packages/foundation/env/src/**/*.md`** — co-located docs per implementation file (Purpose, Features, Basic + Advanced examples, full API reference, Implementation notes — all packages  ship ≥200 words per module)
+3. **`packages/foundation/env/package.json`** `exports` map — every subpath you can import from
+
+When the user asks an API question, read the relevant co-located `.md` first; do not answer from training-data memory.
+
+## See also
+
+- `@suaveplan/error`
+- `@suaveplan/types`
+
+---
+
+_This SKILL.md is auto-generated by `suaveplan-skills/scripts/generate-skills.ts` from the package's README. Do not edit by hand — re-run the generator after the README changes._

docs/devtools/tooling/install-agent-skills/assets/skills/error/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: error
+description: Use when implementing or debugging code that uses @suaveplan/error: Foundation error substrate — SuaveplanError base class, stable code registry, cause-chain traversal, Zod-validated wire format (JSON + MessagePack), redaction, OTel span-event adapter, i18n resolver hook.
+---
+
+# @suaveplan/error
+
+Foundation error substrate for Suaveplan. Every non-testing `@suaveplan/*` package extends this library's `SuaveplanError` base class and uses its stable code registry. The package provides: `SuaveplanError<TCode>` — an abstract base with literal-typed discriminant codes, injectable clock, context bag, traceId, and cause chaining; `defineCodes(namespace, reasons)` — a frozen, literal-typed registry that makes error codes refactor-safe; `walkCauses(err)` — a cycle-safe, depth-bounded generator for traversing nested error causes; lossless JSON and binary wire formats (`toJSON`/`fromJSON`/`toBinary`/`fromBinary`) with Zod validation; `markSensitive`/`unwrapSensitive` for redaction at serialization boundaries; `toSpanEvent` for OpenTelemetry `exception` span events without an OTel SDK import; and a `setMessageResolver` hook for i18n. Zero `@suaveplan/*` runtime or peer dependencies — this is the lowest-level package in the stack.
+
+## When to use this skill
+
+- Implementing or debugging code that imports `@suaveplan/error`.
+- The task touches: see package README.
+- You need API guidance for this package's exports.
+
+## Quick reference
+
+```ts
+import { /* see API Reference below */ } from "@suaveplan/error";
+```
+
+## Dependencies
+
+Workspace dependencies: `@suaveplan/types`
+
+## Where to read more
+
+This skill is intentionally short. The package's own documentation is the authoritative source — read these in order:
+
+1. **`packages/foundation/error/README.md`** — overview, install, quick-start, module index
+2. **`packages/foundation/error/src/**/*.md`** — co-located docs per implementation file (Purpose, Features, Basic + Advanced examples, full API reference, Implementation notes — all packages  ship ≥200 words per module)
+3. **`packages/foundation/error/package.json`** `exports` map — every subpath you can import from
+
+When the user asks an API question, read the relevant co-located `.md` first; do not answer from training-data memory.
+
+## See also
+
+- `@suaveplan/types`
+
+---
+
+_This SKILL.md is auto-generated by `suaveplan-skills/scripts/generate-skills.ts` from the package's README. Do not edit by hand — re-run the generator after the README changes._

docs/devtools/tooling/install-agent-skills/assets/skills/etl/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: etl
+description: Use when implementing or debugging code that uses @suaveplan/etl: Extract-Transform-Load pipeline engine with typed stages, error handling, observable progress, and OTel instrumentation.
+---
+
+# @suaveplan/etl
+
+Extract-Transform-Load pipeline engine with typed stages, error handling, observable progress, and OTel instrumentation.
+
+## When to use this skill
+
+- Implementing or debugging code that imports `@suaveplan/etl`.
+- The task touches: see package README.
+- You need API guidance for this package's exports.
+
+## Quick reference
+
+```ts
+import { /* see API Reference below */ } from "@suaveplan/etl";
+```
+
+## Dependencies
+
+Workspace dependencies: `@suaveplan/error`, `@suaveplan/events`, `@suaveplan/serialize`, `@suaveplan/types`
+
+## Where to read more
+
+This skill is intentionally short. The package's own documentation is the authoritative source — read these in order:
+
+1. **`packages/platform/etl/README.md`** — overview, install, quick-start, module index
+2. **`packages/platform/etl/src/**/*.md`** — co-located docs per implementation file (Purpose, Features, Basic + Advanced examples, full API reference, Implementation notes — all packages  ship ≥200 words per module)
+3. **`packages/platform/etl/package.json`** `exports` map — every subpath you can import from
+
+When the user asks an API question, read the relevant co-located `.md` first; do not answer from training-data memory.
+
+## See also
+
+- `@suaveplan/error`
+- `@suaveplan/events`
+- `@suaveplan/serialize`
+- `@suaveplan/types`
+
+---
+
+_This SKILL.md is auto-generated by `suaveplan-skills/scripts/generate-skills.ts` from the package's README. Do not edit by hand — re-run the generator after the README changes._

docs/devtools/tooling/install-agent-skills/assets/skills/event-sourcing/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: event-sourcing
+description: Use when implementing or debugging code that uses @suaveplan/event-sourcing: Event sourcing patterns: aggregate root, typed event store, snapshot support, projections, upcasting, and OTel instrumentation.
+---
+
+# @suaveplan/event-sourcing
+
+Event sourcing patterns for Suaveplan: typed aggregate root, in-memory event store with optimistic concurrency, snapshot support, projections, upcasting, and OTel instrumentation.
+
+## When to use this skill
+
+- Implementing or debugging code that imports `@suaveplan/event-sourcing`.
+- The task touches: see package README.
+- You need API guidance for this package's exports.
+
+## Quick reference
+
+```ts
+import { /* see API Reference below */ } from "@suaveplan/event-sourcing";
+```
+
+## Dependencies
+
+Workspace dependencies: `@suaveplan/diff`, `@suaveplan/error`, `@suaveplan/events`, `@suaveplan/types`
+
+## Where to read more
+
+This skill is intentionally short. The package's own documentation is the authoritative source — read these in order:
+
+1. **`packages/events/event-sourcing/README.md`** — overview, install, quick-start, module index
+2. **`packages/events/event-sourcing/src/**/*.md`** — co-located docs per implementation file (Purpose, Features, Basic + Advanced examples, full API reference, Implementation notes — all packages  ship ≥200 words per module)
+3. **`packages/events/event-sourcing/package.json`** `exports` map — every subpath you can import from
+
+When the user asks an API question, read the relevant co-located `.md` first; do not answer from training-data memory.
+
+## See also
+
+- `@suaveplan/diff`
+- `@suaveplan/error`
+- `@suaveplan/events`
+- `@suaveplan/types`
+
+---
+
+_This SKILL.md is auto-generated by `suaveplan-skills/scripts/generate-skills.ts` from the package's README. Do not edit by hand — re-run the generator after the README changes._

docs/devtools/tooling/install-agent-skills/assets/skills/events-metrics/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: events-metrics
+description: Use when implementing or debugging code that uses @suaveplan/events-metrics: OTel metrics companion for @suaveplan/events: dispatch counters, latency histograms, queue-depth gauges, and active-subscriber counts via interceptor API.
+---
+
+# @suaveplan/events-metrics
+
+OTel metrics companion for `@suaveplan/events`. Attaches via the public interceptor API to record dispatch totals, listener error counts, and latency histograms per event name.
+
+## When to use this skill
+
+- Implementing or debugging code that imports `@suaveplan/events-metrics`.
+- The task touches: see package README.
+- You need API guidance for this package's exports.
+
+## Quick reference
+
+```ts
+import { /* see API Reference below */ } from "@suaveplan/events-metrics";
+```
+
+## Dependencies
+
+Workspace dependencies: `@suaveplan/error`, `@suaveplan/events`, `@suaveplan/opentelemetry`, `@suaveplan/types`
+
+## Where to read more
+
+This skill is intentionally short. The package's own documentation is the authoritative source — read these in order:
+
+1. **`packages/events/events-metrics/README.md`** — overview, install, quick-start, module index
+2. **`packages/events/events-metrics/src/**/*.md`** — co-located docs per implementation file (Purpose, Features, Basic + Advanced examples, full API reference, Implementation notes — all packages  ship ≥200 words per module)
+3. **`packages/events/events-metrics/package.json`** `exports` map — every subpath you can import from
+
+When the user asks an API question, read the relevant co-located `.md` first; do not answer from training-data memory.
+
+## See also
+
+- `@suaveplan/error`
+- `@suaveplan/events`
+- `@suaveplan/opentelemetry`
+- `@suaveplan/types`
+
+---
+
+_This SKILL.md is auto-generated by `suaveplan-skills/scripts/generate-skills.ts` from the package's README. Do not edit by hand — re-run the generator after the README changes._

docs/devtools/tooling/install-agent-skills/assets/skills/events-otel/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: events-otel
+description: Use when implementing or debugging code that uses @suaveplan/events-otel: OpenTelemetry tracing companion for @suaveplan/events: wraps each dispatch in a span, propagates W3C Trace Context, and records listener exceptions as span errors.
+---
+
+# @suaveplan/events-otel
+
+OpenTelemetry tracing companion for `@suaveplan/events`. Wraps each dispatch in a span, propagates W3C Trace Context, and records listener exceptions as span errors.
+
+## When to use this skill
+
+- Implementing or debugging code that imports `@suaveplan/events-otel`.
+- The task touches: see package README.
+- You need API guidance for this package's exports.
+
+## Quick reference
+
+```ts
+import { /* see API Reference below */ } from "@suaveplan/events-otel";
+```
+
+## Dependencies
+
+Workspace dependencies: `@suaveplan/error`, `@suaveplan/events`, `@suaveplan/types`
+
+## Where to read more
+
+This skill is intentionally short. The package's own documentation is the authoritative source — read these in order:
+
+1. **`packages/events/events-otel/README.md`** — overview, install, quick-start, module index
+2. **`packages/events/events-otel/src/**/*.md`** — co-located docs per implementation file (Purpose, Features, Basic + Advanced examples, full API reference, Implementation notes — all packages  ship ≥200 words per module)
+3. **`packages/events/events-otel/package.json`** `exports` map — every subpath you can import from
+
+When the user asks an API question, read the relevant co-located `.md` first; do not answer from training-data memory.
+
+## See also
+
+- `@suaveplan/error`
+- `@suaveplan/events`
+- `@suaveplan/types`
+
+---
+
+_This SKILL.md is auto-generated by `suaveplan-skills/scripts/generate-skills.ts` from the package's README. Do not edit by hand — re-run the generator after the README changes._

docs/devtools/tooling/install-agent-skills/assets/skills/events-schema/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: events-schema
+description: Use when implementing or debugging code that uses @suaveplan/events-schema: Runtime schema-validation companion for @suaveplan/events: validates event payloads at dispatch boundaries via Zod schemas with strict/warn/sample modes and sensitive field redaction.
+---
+
+# @suaveplan/events-schema
+
+Runtime schema-validation companion for `@suaveplan/events`. Validates event payloads at dispatch boundaries via Zod schemas with strict/warn/sample modes and sensitive field redaction.
+
+## When to use this skill
+
+- Implementing or debugging code that imports `@suaveplan/events-schema`.
+- The task touches: see package README.
+- You need API guidance for this package's exports.
+
+## Quick reference
+
+```ts
+import { /* see API Reference below */ } from "@suaveplan/events-schema";
+```
+
+## Dependencies
+
+Workspace dependencies: `@suaveplan/error`, `@suaveplan/events`, `@suaveplan/schema-registry`, `@suaveplan/types`
+
+## Where to read more
+
+This skill is intentionally short. The package's own documentation is the authoritative source — read these in order:
+
+1. **`packages/events/events-schema/README.md`** — overview, install, quick-start, module index
+2. **`packages/events/events-schema/src/**/*.md`** — co-located docs per implementation file (Purpose, Features, Basic + Advanced examples, full API reference, Implementation notes — all packages  ship ≥200 words per module)
+3. **`packages/events/events-schema/package.json`** `exports` map — every subpath you can import from
+
+When the user asks an API question, read the relevant co-located `.md` first; do not answer from training-data memory.
+
+## See also
+
+- `@suaveplan/error`
+- `@suaveplan/events`
+- `@suaveplan/schema-registry`
+- `@suaveplan/types`
+
+---
+
+_This SKILL.md is auto-generated by `suaveplan-skills/scripts/generate-skills.ts` from the package's README. Do not edit by hand — re-run the generator after the README changes._

docs/devtools/tooling/install-agent-skills/assets/skills/events-transport/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: events-transport
+description: Use when implementing or debugging code that uses @suaveplan/events-transport: Cross-context event bridges for @suaveplan/events: MessageChannel (at-least-once with ack) and BroadcastChannel (at-most-once) transports with nonce dedup, W3C trace context, and AbortSignal support.
+---
+
+# @suaveplan/events-transport
+
+Cross-context event bridges for `@suaveplan/events`: `MessageChannel` (at-least-once with ack/retry) and `BroadcastChannel` (at-most-once, fan-out) transports with nonce deduplication and AbortSignal support.
+
+## When to use this skill
+
+- Implementing or debugging code that imports `@suaveplan/events-transport`.
+- The task touches: see package README.
+- You need API guidance for this package's exports.
+
+## Quick reference
+
+```ts
+import { /* see API Reference below */ } from "@suaveplan/events-transport";
+```
+
+## Dependencies
+
+Workspace dependencies: `@suaveplan/error`, `@suaveplan/events`, `@suaveplan/types`
+
+## Where to read more
+
+This skill is intentionally short. The package's own documentation is the authoritative source — read these in order:
+
+1. **`packages/events/events-transport/README.md`** — overview, install, quick-start, module index
+2. **`packages/events/events-transport/src/**/*.md`** — co-located docs per implementation file (Purpose, Features, Basic + Advanced examples, full API reference, Implementation notes — all packages  ship ≥200 words per module)
+3. **`packages/events/events-transport/package.json`** `exports` map — every subpath you can import from
+
+When the user asks an API question, read the relevant co-located `.md` first; do not answer from training-data memory.
+
+## See also
+
+- `@suaveplan/error`
+- `@suaveplan/events`
+- `@suaveplan/types`
+
+---
+
+_This SKILL.md is auto-generated by `suaveplan-skills/scripts/generate-skills.ts` from the package's README. Do not edit by hand — re-run the generator after the README changes._

docs/devtools/tooling/install-agent-skills/assets/skills/events/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: events
+description: Use when implementing or debugging code that uses @suaveplan/events: Typed event-bus substrate: pub/sub with deterministic FIFO, interceptor API, bounded-queue backpressure, idempotent listeners, Zod-validated envelopes, passive observability adapter.
+---
+
+# @suaveplan/events
+
+Typed event-bus substrate for Suaveplan. Pub/sub with deterministic FIFO delivery, interceptor API, bounded-queue backpressure, idempotent listeners, Zod-validated envelopes, and a passive observability adapter.
+
+## When to use this skill
+
+- Implementing or debugging code that imports `@suaveplan/events`.
+- The task touches: see package README.
+- You need API guidance for this package's exports.
+
+## Quick reference
+
+```ts
+import { /* see API Reference below */ } from "@suaveplan/events";
+```
+
+## Dependencies
+
+Workspace dependencies: `@suaveplan/error`, `@suaveplan/types`
+
+## Where to read more
+
+This skill is intentionally short. The package's own documentation is the authoritative source — read these in order:
+
+1. **`packages/events/events/README.md`** — overview, install, quick-start, module index
+2. **`packages/events/events/src/**/*.md`** — co-located docs per implementation file (Purpose, Features, Basic + Advanced examples, full API reference, Implementation notes — all packages  ship ≥200 words per module)
+3. **`packages/events/events/package.json`** `exports` map — every subpath you can import from
+
+When the user asks an API question, read the relevant co-located `.md` first; do not answer from training-data memory.
+
+## See also
+
+- `@suaveplan/error`
+- `@suaveplan/types`
+
+---
+
+_This SKILL.md is auto-generated by `suaveplan-skills/scripts/generate-skills.ts` from the package's README. Do not edit by hand — re-run the generator after the README changes._

docs/devtools/tooling/install-agent-skills/assets/skills/exif/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: exif
+description: Use when implementing or debugging code that uses @suaveplan/exif: Dependency-free, runtime-agnostic EXIF/XMP/IPTC metadata reader, writer, and stripper for JPEG and PNG images.
+---
+
+# @suaveplan/exif
+
+Dependency-free, runtime-agnostic EXIF/XMP/IPTC metadata reader, writer, and stripper for JPEG and PNG images. Parses JPEG segment chains to locate and decode the EXIF IFD (TIFF byte-order aware, including GPS and SubIFD), IPTC IIM (caption, keywords, copyright), and XMP Dublin Core (raw XML string extraction). Writes back a revised EXIF IFD without re-encoding the image pixels, and strips all metadata segments for privacy-preserving image export. Includes a `ByteReader`/`ByteWriter` pair with rational arithmetic helpers and CRC-32 for PNG chunks. Use this package when you need to read camera metadata (make, model, GPS coordinates, orientation, focal length), watermark images with IPTC copyright fields, or scrub location data before publishing user-uploaded photos. For audio file metadata (ID3, MP4 atoms, FLAC Vorbis) use `@suaveplan/audio-metadata`.
+
+## When to use this skill
+
+- Implementing or debugging code that imports `@suaveplan/exif`.
+- The task touches: see package README.
+- You need API guidance for this package's exports.
+
+## Quick reference
+
+```ts
+import { /* see API Reference below */ } from "@suaveplan/exif";
+```
+
+## Dependencies
+
+Workspace dependencies: _none_
+
+## Where to read more
+
+This skill is intentionally short. The package's own documentation is the authoritative source — read these in order:
+
+1. **`packages/image/exif/README.md`** — overview, install, quick-start, module index
+2. **`packages/image/exif/src/**/*.md`** — co-located docs per implementation file (Purpose, Features, Basic + Advanced examples, full API reference, Implementation notes — all packages  ship ≥200 words per module)
+3. **`packages/image/exif/package.json`** `exports` map — every subpath you can import from
+
+When the user asks an API question, read the relevant co-located `.md` first; do not answer from training-data memory.
+
+## See also
+
+- The marketplace root: `../../../README.md`
+
+---
+
+_This SKILL.md is auto-generated by `suaveplan-skills/scripts/generate-skills.ts` from the package's README. Do not edit by hand — re-run the generator after the README changes._

docs/devtools/tooling/install-agent-skills/assets/skills/feature-flags/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: feature-flags
+description: Use when implementing or debugging code that uses @suaveplan/feature-flags: Provider-agnostic feature flag evaluation with typed flag values, strategy chains, and deterministic bucketing.
+---
+
+# @suaveplan/feature-flags
+
+Provider-agnostic feature flag evaluation engine for controlling feature rollout without code deploys. The package ships a `FlagManager` high-level façade, a `FlagRegistry` backed by any pluggable `FlagProvider`, and an `Evaluator` strategy chain. Five composable strategies cover the full rollout playbook: `PercentageStrategy` (deterministic FNV-1a bucketing for consistent user cohorts), `UserTargetStrategy` (allowlist), `AttributeStrategy` (10 comparison operators for segment targeting), `ScheduleStrategy` (time-window gating), and `CompositeStrategy` (AND/OR combinator). Built-in providers include `MemoryProvider` and `JsonProvider` for file-based flag definitions. Evaluation priority is: flag disabled → in-process override → first matching strategy → default value. This package is for runtime flag evaluation only — it is not a flag management UI or remote config service.
+
+## When to use this skill
+
+- Implementing or debugging code that imports `@suaveplan/feature-flags`.
+- The task touches: see package README.
+- You need API guidance for this package's exports.
+
+## Quick reference
+
+```ts
+import { /* see API Reference below */ } from "@suaveplan/feature-flags";
+```
+
+## Dependencies
+
+Workspace dependencies: `@suaveplan/error`, `@suaveplan/events`, `@suaveplan/logger`, `@suaveplan/types`
+
+## Where to read more
+
+This skill is intentionally short. The package's own documentation is the authoritative source — read these in order:
+
+1. **`packages/platform/feature-flags/README.md`** — overview, install, quick-start, module index
+2. **`packages/platform/feature-flags/src/**/*.md`** — co-located docs per implementation file (Purpose, Features, Basic + Advanced examples, full API reference, Implementation notes — all packages  ship ≥200 words per module)
+3. **`packages/platform/feature-flags/package.json`** `exports` map — every subpath you can import from
+
+When the user asks an API question, read the relevant co-located `.md` first; do not answer from training-data memory.
+
+## See also
+
+- `@suaveplan/error`
+- `@suaveplan/events`
+- `@suaveplan/logger`
+- `@suaveplan/types`
+
+---
+
+_This SKILL.md is auto-generated by `suaveplan-skills/scripts/generate-skills.ts` from the package's README. Do not edit by hand — re-run the generator after the README changes._

docs/devtools/tooling/install-agent-skills/assets/skills/font-compress/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: font-compress
+description: Use when implementing or debugging code that uses @suaveplan/font-compress: BTF (Binary TypeFace) binary packing and unpacking.
+---
+
+# @suaveplan/font-compress
+
+BTF (Binary TypeFace) binary packing and unpacking. Converts `TypefaceFont` (typeface.js JSON format) to a compact `Uint8Array` using dictionary-based integer compression, and reverses it.
+
+## When to use this skill
+
+- Implementing or debugging code that imports `@suaveplan/font-compress`.
+- The task touches: see package README.
+- You need API guidance for this package's exports.
+
+## Quick reference
+
+```ts
+import { /* see API Reference below */ } from "@suaveplan/font-compress";
+```
+
+## Dependencies
+
+Workspace dependencies: `@suaveplan/error`, `@suaveplan/font-convert`, `@suaveplan/types`
+
+## Where to read more
+
+This skill is intentionally short. The package's own documentation is the authoritative source — read these in order:
+
+1. **`packages/fonts/font-compress/README.md`** — overview, install, quick-start, module index
+2. **`packages/fonts/font-compress/src/**/*.md`** — co-located docs per implementation file (Purpose, Features, Basic + Advanced examples, full API reference, Implementation notes — all packages  ship ≥200 words per module)
+3. **`packages/fonts/font-compress/package.json`** `exports` map — every subpath you can import from
+
+When the user asks an API question, read the relevant co-located `.md` first; do not answer from training-data memory.
+
+## See also
+
+- `@suaveplan/error`
+- `@suaveplan/font-convert`
+- `@suaveplan/types`
+
+---
+
+_This SKILL.md is auto-generated by `suaveplan-skills/scripts/generate-skills.ts` from the package's README. Do not edit by hand — re-run the generator after the README changes._

docs/devtools/tooling/install-agent-skills/assets/skills/font-convert/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: font-convert
+description: Use when implementing or debugging code that uses @suaveplan/font-convert: Convert TTF/OTF/WOFF/WOFF2 font files to typeface.
+---
+
+# @suaveplan/font-convert
+
+Converts TTF/OTF/WOFF/WOFF2 font files to the [typeface.js](https://gero3.github.io/facetype.js/) JSON format used by [Three.js `FontLoader`](https://threejs.org/docs/#examples/en/loaders/FontLoader). Also defines the canonical `TypefaceFont`, `TypefaceGlyph`, and `PathCommand` types consumed by `@suaveplan/font-compress`.
+
+## When to use this skill
+
+- Implementing or debugging code that imports `@suaveplan/font-convert`.
+- The task touches: see package README.
+- You need API guidance for this package's exports.
+
+## Quick reference
+
+```ts
+import { /* see API Reference below */ } from "@suaveplan/font-convert";
+```
+
+## Dependencies
+
+Workspace dependencies: `@suaveplan/error`, `@suaveplan/types`
+
+## Where to read more
+
+This skill is intentionally short. The package's own documentation is the authoritative source — read these in order:
+
+1. **`packages/fonts/font-convert/README.md`** — overview, install, quick-start, module index
+2. **`packages/fonts/font-convert/src/**/*.md`** — co-located docs per implementation file (Purpose, Features, Basic + Advanced examples, full API reference, Implementation notes — all packages  ship ≥200 words per module)
+3. **`packages/fonts/font-convert/package.json`** `exports` map — every subpath you can import from
+
+When the user asks an API question, read the relevant co-located `.md` first; do not answer from training-data memory.
+
+## See also
+
+- `@suaveplan/error`
+- `@suaveplan/types`
+
+---
+
+_This SKILL.md is auto-generated by `suaveplan-skills/scripts/generate-skills.ts` from the package's README. Do not edit by hand — re-run the generator after the README changes._

docs/devtools/tooling/install-agent-skills/assets/skills/font-subset/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: font-subset
+description: Use when implementing or debugging code that uses @suaveplan/font-subset: Font subsetting pipeline: Unicode range subsetting, WOFF2/WOFF encoding, TTF-to-OTF normalisation, feature tag filtering, hinting strip, metadata strip.
+---
+
+# @suaveplan/font-subset
+
+Font subsetting and compression library with a codec-agnostic adapter interface. Supports Unicode range subsetting, WOFF2/WOFF/OTF/TTF output, OpenType feature filtering, hinting strip, and metadata strip. Adapter implementations supply the actual codec; this package provides the orchestration, validation, format detection, and OTel instrumentation.
+
+## When to use this skill
+
+- Implementing or debugging code that imports `@suaveplan/font-subset`.
+- The task touches: see package README.
+- You need API guidance for this package's exports.
+
+## Quick reference
+
+```ts
+import { /* see API Reference below */ } from "@suaveplan/font-subset";
+```
+
+## Dependencies
+
+Workspace dependencies: `@suaveplan/error`, `@suaveplan/mime`, `@suaveplan/types`
+
+## Where to read more
+
+This skill is intentionally short. The package's own documentation is the authoritative source — read these in order:
+
+1. **`packages/fonts/font-subset/README.md`** — overview, install, quick-start, module index
+2. **`packages/fonts/font-subset/src/**/*.md`** — co-located docs per implementation file (Purpose, Features, Basic + Advanced examples, full API reference, Implementation notes — all packages  ship ≥200 words per module)
+3. **`packages/fonts/font-subset/package.json`** `exports` map — every subpath you can import from
+
+When the user asks an API question, read the relevant co-located `.md` first; do not answer from training-data memory.
+
+## See also
+
+- `@suaveplan/error`
+- `@suaveplan/mime`
+- `@suaveplan/types`
+
+---
+
+_This SKILL.md is auto-generated by `suaveplan-skills/scripts/generate-skills.ts` from the package's README. Do not edit by hand — re-run the generator after the README changes._

docs/devtools/tooling/install-agent-skills/assets/skills/fsm/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: fsm
+description: Use when implementing or debugging code that uses @suaveplan/fsm: Typed finite state machine with guards, actions, history tracking, hierarchical states, parallel regions, deferred events, and OTel instrumentation.
+---
+
+# @suaveplan/fsm
+
+Typed, generic finite state machine (FSM) for TypeScript. Ships a synchronous-by-default interpreter with guard predicates, ordered transition actions, context threading, entry/exit lifecycle hooks, history recording, and OTel instrumentation. Zero peer dependencies beyond `@suaveplan/error`, `@suaveplan/events`, and `@suaveplan/types`.
+
+## When to use this skill
+
+- Implementing or debugging code that imports `@suaveplan/fsm`.
+- The task touches: see package README.
+- You need API guidance for this package's exports.
+
+## Quick reference
+
+```ts
+import { /* see API Reference below */ } from "@suaveplan/fsm";
+```
+
+## Dependencies
+
+Workspace dependencies: `@suaveplan/error`, `@suaveplan/events`, `@suaveplan/types`
+
+## Where to read more
+
+This skill is intentionally short. The package's own documentation is the authoritative source — read these in order:
+
+1. **`packages/foundation/fsm/README.md`** — overview, install, quick-start, module index
+2. **`packages/foundation/fsm/src/**/*.md`** — co-located docs per implementation file (Purpose, Features, Basic + Advanced examples, full API reference, Implementation notes — all packages  ship ≥200 words per module)
+3. **`packages/foundation/fsm/package.json`** `exports` map — every subpath you can import from
+
+When the user asks an API question, read the relevant co-located `.md` first; do not answer from training-data memory.
+
+## See also
+
+- `@suaveplan/error`
+- `@suaveplan/events`
+- `@suaveplan/types`
+
+---
+
+_This SKILL.md is auto-generated by `suaveplan-skills/scripts/generate-skills.ts` from the package's README. Do not edit by hand — re-run the generator after the README changes._

docs/devtools/tooling/install-agent-skills/assets/skills/i18n/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: i18n
+description: Use when implementing or debugging code that uses @suaveplan/i18n: Internationalization core: message catalog, ICU-like interpolation, pluralization, locale resolution, middleware, date/currency formatting.
+---
+
+# @suaveplan/i18n
+
+Enterprise-grade internationalization (i18n) core for Suaveplan. Works in Bun, Node.js, and modern browsers — zero DOM dependencies, tree-shakeable subpath exports. The package covers the full i18n surface: a namespaced `MessageCatalog` with lazy loaders and missing-key hooks; an `InterpolationEngine` with `{{ variable }}` and HTML-escape support; a `PluralizationEngine` with 14 language rules (including Arabic, Russian, and Celtic forms); an ICU-lite AST message parser for plural/select nodes; a `LocaleResolver` with BCP-47 normalisation, RTL detection, and fallback chains; server-side locale middleware; and `Intl`-backed date and currency formatters. Do not confuse with `@suaveplan/templates`, which handles string interpolation in non-i18n contexts — this package is specifically for locale-keyed message catalogs and locale-sensitive formatting.
+
+## When to use this skill
+
+- Implementing or debugging code that imports `@suaveplan/i18n`.
+- The task touches: see package README.
+- You need API guidance for this package's exports.
+
+## Quick reference
+
+```ts
+import { /* see API Reference below */ } from "@suaveplan/i18n";
+```
+
+## Dependencies
+
+Workspace dependencies: `@suaveplan/error`, `@suaveplan/types`
+
+## Where to read more
+
+This skill is intentionally short. The package's own documentation is the authoritative source — read these in order:
+
+1. **`packages/i18n/i18n/README.md`** — overview, install, quick-start, module index
+2. **`packages/i18n/i18n/src/**/*.md`** — co-located docs per implementation file (Purpose, Features, Basic + Advanced examples, full API reference, Implementation notes — all packages  ship ≥200 words per module)
+3. **`packages/i18n/i18n/package.json`** `exports` map — every subpath you can import from
+
+When the user asks an API question, read the relevant co-located `.md` first; do not answer from training-data memory.
+
+## See also
+
+- `@suaveplan/error`
+- `@suaveplan/types`
+
+---
+
+_This SKILL.md is auto-generated by `suaveplan-skills/scripts/generate-skills.ts` from the package's README. Do not edit by hand — re-run the generator after the README changes._

docs/devtools/tooling/install-agent-skills/assets/skills/idempotency/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: idempotency
+description: Use when implementing or debugging code that uses @suaveplan/idempotency: Idempotency key guard and dedup: store adapters (memory, database, redis), distributed locking, middleware, key generation, metrics, OTel instrumentation.
+---
+
+# @suaveplan/idempotency
+
+Idempotency key guard and deduplication for async operations. The package provides a complete `pending → completed | failed` state machine, three store backends (memory, database, Redis), distributed locking across multiple processes, request middleware, key generation with payload fingerprinting, version history management, and OTel metrics instrumentation. It is designed to protect any operation that must not execute more than once per request — payment charges, email sends, record creation — regardless of retries or race conditions.
+
+## When to use this skill
+
+- Implementing or debugging code that imports `@suaveplan/idempotency`.
+- The task touches: see package README.
+- You need API guidance for this package's exports.
+
+## Quick reference
+
+```ts
+import { /* see API Reference below */ } from "@suaveplan/idempotency";
+```
+
+## Dependencies
+
+Workspace dependencies: `@suaveplan/error`, `@suaveplan/events`, `@suaveplan/types`
+
+## Where to read more
+
+This skill is intentionally short. The package's own documentation is the authoritative source — read these in order:
+
+1. **`packages/foundation/idempotency/README.md`** — overview, install, quick-start, module index
+2. **`packages/foundation/idempotency/src/**/*.md`** — co-located docs per implementation file (Purpose, Features, Basic + Advanced examples, full API reference, Implementation notes — all packages  ship ≥200 words per module)
+3. **`packages/foundation/idempotency/package.json`** `exports` map — every subpath you can import from
+
+When the user asks an API question, read the relevant co-located `.md` first; do not answer from training-data memory.
+
+## See also
+
+- `@suaveplan/error`
+- `@suaveplan/events`
+- `@suaveplan/types`
+
+---
+
+_This SKILL.md is auto-generated by `suaveplan-skills/scripts/generate-skills.ts` from the package's README. Do not edit by hand — re-run the generator after the README changes._

docs/devtools/tooling/install-agent-skills/assets/skills/json/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: json
+description: Use when implementing or debugging code that uses @suaveplan/json: Safe JSON parse/stringify with prototype-pollution protection, circular-ref detection, and OTel instrumentation.
+---
+
+# @suaveplan/json
+
+Safe, enterprise-grade JSON utilities with prototype-pollution protection, circular-reference detection, and OpenTelemetry instrumentation.
+
+## When to use this skill
+
+- Implementing or debugging code that imports `@suaveplan/json`.
+- The task touches: see package README.
+- You need API guidance for this package's exports.
+
+## Quick reference
+
+```ts
+import { /* see API Reference below */ } from "@suaveplan/json";
+```
+
+## Dependencies
+
+Workspace dependencies: `@suaveplan/error`, `@suaveplan/types`
+
+## Where to read more
+
+This skill is intentionally short. The package's own documentation is the authoritative source — read these in order:
+
+1. **`packages/foundation/json/README.md`** — overview, install, quick-start, module index
+2. **`packages/foundation/json/src/**/*.md`** — co-located docs per implementation file (Purpose, Features, Basic + Advanced examples, full API reference, Implementation notes — all packages  ship ≥200 words per module)
+3. **`packages/foundation/json/package.json`** `exports` map — every subpath you can import from
+
+When the user asks an API question, read the relevant co-located `.md` first; do not answer from training-data memory.
+
+## See also
+
+- `@suaveplan/error`
+- `@suaveplan/types`
+
+---
+
+_This SKILL.md is auto-generated by `suaveplan-skills/scripts/generate-skills.ts` from the package's README. Do not edit by hand — re-run the generator after the README changes._

docs/devtools/tooling/install-agent-skills/assets/skills/jwt-tenant/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: jwt-tenant
+description: Use when implementing or debugging code that uses @suaveplan/jwt-tenant: JWT-based multi-tenant token issuance and verification with Ed25519/ECDSA signing, JWKS rotation, and injectable clock.
+---
+
+# @suaveplan/jwt-tenant
+
+JWT-based multi-tenant token issuance and verification with Ed25519/ECDSA signing, JWKS rotation, and injectable clock
+
+## When to use this skill
+
+- Implementing or debugging code that imports `@suaveplan/jwt-tenant`.
+- The task touches: see package README.
+- You need API guidance for this package's exports.
+
+## Quick reference
+
+```ts
+import { /* see API Reference below */ } from "@suaveplan/jwt-tenant";
+```
+
+## Dependencies
+
+Workspace dependencies: `@suaveplan/error`, `@suaveplan/retry`, `@suaveplan/types`
+
+## Where to read more
+
+This skill is intentionally short. The package's own documentation is the authoritative source — read these in order:
+
+1. **`packages/auth/jwt-tenant/README.md`** — overview, install, quick-start, module index
+2. **`packages/auth/jwt-tenant/src/**/*.md`** — co-located docs per implementation file (Purpose, Features, Basic + Advanced examples, full API reference, Implementation notes — all packages  ship ≥200 words per module)
+3. **`packages/auth/jwt-tenant/package.json`** `exports` map — every subpath you can import from
+
+When the user asks an API question, read the relevant co-located `.md` first; do not answer from training-data memory.
+
+## See also
+
+- `@suaveplan/error`
+- `@suaveplan/retry`
+- `@suaveplan/types`
+
+---
+
+_This SKILL.md is auto-generated by `suaveplan-skills/scripts/generate-skills.ts` from the package's README. Do not edit by hand — re-run the generator after the README changes._

docs/devtools/tooling/install-agent-skills/assets/skills/locale-data/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: locale-data
+description: Use when implementing or debugging code that uses @suaveplan/locale-data: Static ISO 3166-1 country data and ISO 639-1 language data with typed lookup functions, OTel instrumentation, and Zod schemas.
+---
+
+# @suaveplan/locale-data
+
+Static ISO 3166-1 country data and ISO 639-1 language data with typed lookup functions, OTel instrumentation, and Zod schemas.
+
+## When to use this skill
+
+- Implementing or debugging code that imports `@suaveplan/locale-data`.
+- The task touches: see package README.
+- You need API guidance for this package's exports.
+
+## Quick reference
+
+```ts
+import { /* see API Reference below */ } from "@suaveplan/locale-data";
+```
+
+## Dependencies
+
+Workspace dependencies: `@suaveplan/error`, `@suaveplan/types`
+
+## Where to read more
+
+This skill is intentionally short. The package's own documentation is the authoritative source — read these in order:
+
+1. **`packages/i18n/locale-data/README.md`** — overview, install, quick-start, module index
+2. **`packages/i18n/locale-data/src/**/*.md`** — co-located docs per implementation file (Purpose, Features, Basic + Advanced examples, full API reference, Implementation notes — all packages  ship ≥200 words per module)
+3. **`packages/i18n/locale-data/package.json`** `exports` map — every subpath you can import from
+
+When the user asks an API question, read the relevant co-located `.md` first; do not answer from training-data memory.
+
+## See also
+
+- `@suaveplan/error`
+- `@suaveplan/types`
+
+---
+
+_This SKILL.md is auto-generated by `suaveplan-skills/scripts/generate-skills.ts` from the package's README. Do not edit by hand — re-run the generator after the README changes._

docs/devtools/tooling/install-agent-skills/assets/skills/logger/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: logger
+description: Use when implementing or debugging code that uses @suaveplan/logger: Foundation logging package — structured JSON output, level filtering, redaction, sampling, OTel correlation, and pluggable sinks.
+---
+
+# @suaveplan/logger
+
+Enterprise-grade structured logger for Suaveplan. Provides a full pipeline: level filtering → OTel trace enrichment → sampling → redaction → sinks. Supports multiple output strategies (console, JSON/NDJSON, event bus, storage) with buffering and backpressure.
+
+## When to use this skill
+
+- Implementing or debugging code that imports `@suaveplan/logger`.
+- The task touches: see package README.
+- You need API guidance for this package's exports.
+
+## Quick reference
+
+```ts
+import { /* see API Reference below */ } from "@suaveplan/logger";
+```
+
+## Dependencies
+
+Workspace dependencies: `@suaveplan/error`, `@suaveplan/events`, `@suaveplan/types`
+
+## Where to read more
+
+This skill is intentionally short. The package's own documentation is the authoritative source — read these in order:
+
+1. **`packages/platform/logger/README.md`** — overview, install, quick-start, module index
+2. **`packages/platform/logger/src/**/*.md`** — co-located docs per implementation file (Purpose, Features, Basic + Advanced examples, full API reference, Implementation notes — all packages  ship ≥200 words per module)
+3. **`packages/platform/logger/package.json`** `exports` map — every subpath you can import from
+
+When the user asks an API question, read the relevant co-located `.md` first; do not answer from training-data memory.
+
+## See also
+
+- `@suaveplan/error`
+- `@suaveplan/events`
+- `@suaveplan/types`
+
+---
+
+_This SKILL.md is auto-generated by `suaveplan-skills/scripts/generate-skills.ts` from the package's README. Do not edit by hand — re-run the generator after the README changes._

docs/devtools/tooling/install-agent-skills/assets/skills/metadata/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: metadata
+description: Use when implementing or debugging code that uses @suaveplan/audio-metadata: Universal audio metadata extractor: parses ID3v1/v2, MP4/M4A atoms, FLAC Vorbis comments, Ogg, WAV, AIFF, and returns a normalised Track record.
+---
+
+# @suaveplan/audio-metadata
+
+Universal audio metadata extractor that parses ID3v1/v2, MP4/M4A atoms, FLAC Vorbis comments, Ogg Vorbis, WAV RIFF, and AIFF/AIFC containers, returning a normalised `Track` record. Works in both Node.js and browser environments — zero native dependencies.
+
+## When to use this skill
+
+- Implementing or debugging code that imports `@suaveplan/audio-metadata`.
+- The task touches: see package README.
+- You need API guidance for this package's exports.
+
+## Quick reference
+
+```ts
+import { /* see API Reference below */ } from "@suaveplan/audio-metadata";
+```
+
+## Dependencies
+
+Workspace dependencies: _none_
+
+## Where to read more
+
+This skill is intentionally short. The package's own documentation is the authoritative source — read these in order:
+
+1. **`packages/audio/metadata/README.md`** — overview, install, quick-start, module index
+2. **`packages/audio/metadata/src/**/*.md`** — co-located docs per implementation file (Purpose, Features, Basic + Advanced examples, full API reference, Implementation notes — all packages  ship ≥200 words per module)
+3. **`packages/audio/metadata/package.json`** `exports` map — every subpath you can import from
+
+When the user asks an API question, read the relevant co-located `.md` first; do not answer from training-data memory.
+
+## See also
+
+- The marketplace root: `../../../README.md`
+
+---
+
+_This SKILL.md is auto-generated by `suaveplan-skills/scripts/generate-skills.ts` from the package's README. Do not edit by hand — re-run the generator after the README changes._

docs/devtools/tooling/install-agent-skills/assets/skills/migration/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: migration
+description: Use when implementing or debugging code that uses @suaveplan/migration: Database-agnostic migration runner with ledger tracking, dry-run, checksums, lock adapters, and OTel instrumentation.
+---
+
+# @suaveplan/migration
+
+Database-agnostic schema migration runner with ledger tracking, checksum validation, dry-run reporting, distributed locking, event bus integration, and OTel instrumentation.
+
+## When to use this skill
+
+- Implementing or debugging code that imports `@suaveplan/migration`.
+- The task touches: see package README.
+- You need API guidance for this package's exports.
+
+## Quick reference
+
+```ts
+import { /* see API Reference below */ } from "@suaveplan/migration";
+```
+
+## Dependencies
+
+Workspace dependencies: `@suaveplan/db`, `@suaveplan/error`, `@suaveplan/events`, `@suaveplan/logger`, `@suaveplan/types`
+
+## Where to read more
+
+This skill is intentionally short. The package's own documentation is the authoritative source — read these in order:
+
+1. **`packages/database/migration/README.md`** — overview, install, quick-start, module index
+2. **`packages/database/migration/src/**/*.md`** — co-located docs per implementation file (Purpose, Features, Basic + Advanced examples, full API reference, Implementation notes — all packages  ship ≥200 words per module)
+3. **`packages/database/migration/package.json`** `exports` map — every subpath you can import from
+
+When the user asks an API question, read the relevant co-located `.md` first; do not answer from training-data memory.
+
+## See also
+
+- `@suaveplan/db`
+- `@suaveplan/error`
+- `@suaveplan/events`
+- `@suaveplan/logger`
+- `@suaveplan/types`
+
+---
+
+_This SKILL.md is auto-generated by `suaveplan-skills/scripts/generate-skills.ts` from the package's README. Do not edit by hand — re-run the generator after the README changes._

docs/devtools/tooling/install-agent-skills/assets/skills/mime/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: mime
+description: Use when implementing or debugging code that uses @suaveplan/mime: Structured MIME-type detection, parsing, and registry: magic-byte sniffing, RFC 7231 Content-Type parsing, IANA-sourced type database.
+---
+
+# @suaveplan/mime
+
+Structured MIME-type detection, parsing, and registry for the Suaveplan platform. Provides RFC 7231 Content-Type parsing, magic-byte file signature detection, charset sniffing, and a 150+ entry IANA-sourced type database — all in a zero-dependency, tree-shakeable package.
+
+## When to use this skill
+
+- Implementing or debugging code that imports `@suaveplan/mime`.
+- The task touches: see package README.
+- You need API guidance for this package's exports.
+
+## Quick reference
+
+```ts
+import { /* see API Reference below */ } from "@suaveplan/mime";
+```
+
+## Dependencies
+
+Workspace dependencies: `@suaveplan/error`, `@suaveplan/types`
+
+## Where to read more
+
+This skill is intentionally short. The package's own documentation is the authoritative source — read these in order:
+
+1. **`packages/foundation/mime/README.md`** — overview, install, quick-start, module index
+2. **`packages/foundation/mime/src/**/*.md`** — co-located docs per implementation file (Purpose, Features, Basic + Advanced examples, full API reference, Implementation notes — all packages  ship ≥200 words per module)
+3. **`packages/foundation/mime/package.json`** `exports` map — every subpath you can import from
+
+When the user asks an API question, read the relevant co-located `.md` first; do not answer from training-data memory.
+
+## See also
+
+- `@suaveplan/error`
+- `@suaveplan/types`
+
+---
+
+_This SKILL.md is auto-generated by `suaveplan-skills/scripts/generate-skills.ts` from the package's README. Do not edit by hand — re-run the generator after the README changes._

docs/devtools/tooling/install-agent-skills/assets/skills/noise/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: noise
+description: Use when implementing or debugging code that uses @suaveplan/noise: Seeded spatial noise fields: Perlin, Simplex, Value, Worley, fBm and Blue-noise sampling for procedural generation.
+---
+
+# @suaveplan/noise
+
+Seeded spatial noise fields for procedural content generation. Provides six field types — Perlin, Simplex (2D/3D/4D), Value, Worley/cellular (F1/F2/F2-F1 modes), fBm (fractal Brownian motion compositor), and Poisson-disk Blue noise sampling — all seeded with `Sfc32Rng` for byte-identical, reproducible output. Every generator is available as both a functional API and a stateful class. Use this package for terrain heightmaps, texture generation, cloud simulation, vegetation scattering, and any procedural system that needs spatially-coherent randomness. For non-spatial random values (UUIDs, shuffles, distributions) use `@suaveplan/random`; for seeded integer/float sequences use `@suaveplan/pseudo-random`.
+
+## When to use this skill
+
+- Implementing or debugging code that imports `@suaveplan/noise`.
+- The task touches: see package README.
+- You need API guidance for this package's exports.
+
+## Quick reference
+
+```ts
+import { /* see API Reference below */ } from "@suaveplan/noise";
+```
+
+## Dependencies
+
+Workspace dependencies: `@suaveplan/error`, `@suaveplan/pseudo-random`, `@suaveplan/types`
+
+## Where to read more
+
+This skill is intentionally short. The package's own documentation is the authoritative source — read these in order:
+
+1. **`packages/foundation/noise/README.md`** — overview, install, quick-start, module index
+2. **`packages/foundation/noise/src/**/*.md`** — co-located docs per implementation file (Purpose, Features, Basic + Advanced examples, full API reference, Implementation notes — all packages  ship ≥200 words per module)
+3. **`packages/foundation/noise/package.json`** `exports` map — every subpath you can import from
+
+When the user asks an API question, read the relevant co-located `.md` first; do not answer from training-data memory.
+
+## See also
+
+- `@suaveplan/error`
+- `@suaveplan/pseudo-random`
+- `@suaveplan/types`
+
+---
+
+_This SKILL.md is auto-generated by `suaveplan-skills/scripts/generate-skills.ts` from the package's README. Do not edit by hand — re-run the generator after the README changes._

docs/devtools/tooling/install-agent-skills/assets/skills/oauth-client/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: oauth-client
+description: Use when implementing or debugging code that uses @suaveplan/oauth-client: Universal OAuth 2.
+---
+
+# @suaveplan/oauth-client
+
+Universal OAuth 2.0 / OIDC client for Node.js, browsers, Bun, Deno, and edge runtimes.
+
+## When to use this skill
+
+- Implementing or debugging code that imports `@suaveplan/oauth-client`.
+- The task touches: see package README.
+- You need API guidance for this package's exports.
+
+## Quick reference
+
+```ts
+import { /* see API Reference below */ } from "@suaveplan/oauth-client";
+```
+
+## Dependencies
+
+Workspace dependencies: `@suaveplan/error`, `@suaveplan/types`
+
+## Where to read more
+
+This skill is intentionally short. The package's own documentation is the authoritative source — read these in order:
+
+1. **`packages/auth/oauth-client/README.md`** — overview, install, quick-start, module index
+2. **`packages/auth/oauth-client/src/**/*.md`** — co-located docs per implementation file (Purpose, Features, Basic + Advanced examples, full API reference, Implementation notes — all packages  ship ≥200 words per module)
+3. **`packages/auth/oauth-client/package.json`** `exports` map — every subpath you can import from
+
+When the user asks an API question, read the relevant co-located `.md` first; do not answer from training-data memory.
+
+## See also
+
+- `@suaveplan/error`
+- `@suaveplan/types`
+
+---
+
+_This SKILL.md is auto-generated by `suaveplan-skills/scripts/generate-skills.ts` from the package's README. Do not edit by hand — re-run the generator after the README changes._

docs/devtools/tooling/install-agent-skills/assets/skills/opentelemetry/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: opentelemetry
+description: Use when implementing or debugging code that uses @suaveplan/opentelemetry: OpenTelemetry SDK setup and configuration helpers: tracer/meter/logger providers, resource detection, exporter configuration, and sampling strategies.
+---
+
+# @suaveplan/opentelemetry
+
+OpenTelemetry SDK setup and configuration helpers for Suaveplan. Provides batteries-included OTel initialization helpers, resource detection, ergonomic span/metrics wrappers, W3C trace-context propagation utilities, and a no-op SDK façade that works without any heavyweight `@opentelemetry/sdk-*` packages.
+
+## When to use this skill
+
+- Implementing or debugging code that imports `@suaveplan/opentelemetry`.
+- The task touches: see package README.
+- You need API guidance for this package's exports.
+
+## Quick reference
+
+```ts
+import { /* see API Reference below */ } from "@suaveplan/opentelemetry";
+```
+
+## Dependencies
+
+Workspace dependencies: `@suaveplan/error`, `@suaveplan/types`
+
+## Where to read more
+
+This skill is intentionally short. The package's own documentation is the authoritative source — read these in order:
+
+1. **`packages/platform/opentelemetry/README.md`** — overview, install, quick-start, module index
+2. **`packages/platform/opentelemetry/src/**/*.md`** — co-located docs per implementation file (Purpose, Features, Basic + Advanced examples, full API reference, Implementation notes — all packages  ship ≥200 words per module)
+3. **`packages/platform/opentelemetry/package.json`** `exports` map — every subpath you can import from
+
+When the user asks an API question, read the relevant co-located `.md` first; do not answer from training-data memory.
+
+## See also
+
+- `@suaveplan/error`
+- `@suaveplan/types`
+
+---
+
+_This SKILL.md is auto-generated by `suaveplan-skills/scripts/generate-skills.ts` from the package's README. Do not edit by hand — re-run the generator after the README changes._

docs/devtools/tooling/install-agent-skills/assets/skills/pagination/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: pagination
+description: Use when implementing or debugging code that uses @suaveplan/pagination: Universal pagination primitives: cursor, offset, keyset strategies with adapters, iterators, and type-safe request/response shapes.
+---
+
+# @suaveplan/pagination
+
+Universal pagination primitives for cursor-based, offset-based, and keyset-based (seek) pagination strategies. The package covers the full pagination surface: request normalisation, response envelope construction, opaque cursor and page-token encoding, async iterators that drain pages automatically, a pluggable adapter interface for any data source, and optional OpenTelemetry instrumentation. All three strategies share the same error hierarchy and Zod schemas so they compose cleanly in multi-strategy APIs.
+
+## When to use this skill
+
+- Implementing or debugging code that imports `@suaveplan/pagination`.
+- The task touches: see package README.
+- You need API guidance for this package's exports.
+
+## Quick reference
+
+```ts
+import { /* see API Reference below */ } from "@suaveplan/pagination";
+```
+
+## Dependencies
+
+Workspace dependencies: `@suaveplan/error`, `@suaveplan/types`
+
+## Where to read more
+
+This skill is intentionally short. The package's own documentation is the authoritative source — read these in order:
+
+1. **`packages/foundation/pagination/README.md`** — overview, install, quick-start, module index
+2. **`packages/foundation/pagination/src/**/*.md`** — co-located docs per implementation file (Purpose, Features, Basic + Advanced examples, full API reference, Implementation notes — all packages  ship ≥200 words per module)
+3. **`packages/foundation/pagination/package.json`** `exports` map — every subpath you can import from
+
+When the user asks an API question, read the relevant co-located `.md` first; do not answer from training-data memory.
+
+## See also
+
+- `@suaveplan/error`
+- `@suaveplan/types`
+
+---
+
+_This SKILL.md is auto-generated by `suaveplan-skills/scripts/generate-skills.ts` from the package's README. Do not edit by hand — re-run the generator after the README changes._

docs/devtools/tooling/install-agent-skills/assets/skills/password-formats/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: password-formats
+description: Use when implementing or debugging code that uses @suaveplan/password-formats: Universal import/export layer for common password-manager export formats — Apple Passwords CSV, Bitwarden JSON, Chrome CSV, KeePass XML.
+---
+
+# @suaveplan/password-formats
+
+Universal import/export layer for common password-manager export formats. Parses Apple Passwords CSV, Bitwarden JSON, Chrome CSV, and KeePass XML into a normalized `PasswordEntry[]` array, and exports back to a universal CSV format.
+
+## When to use this skill
+
+- Implementing or debugging code that imports `@suaveplan/password-formats`.
+- The task touches: see package README.
+- You need API guidance for this package's exports.
+
+## Quick reference
+
+```ts
+import { /* see API Reference below */ } from "@suaveplan/password-formats";
+```
+
+## Dependencies
+
+Workspace dependencies: _none_
+
+## Where to read more
+
+This skill is intentionally short. The package's own documentation is the authoritative source — read these in order:
+
+1. **`packages/crypto/password-formats/README.md`** — overview, install, quick-start, module index
+2. **`packages/crypto/password-formats/src/**/*.md`** — co-located docs per implementation file (Purpose, Features, Basic + Advanced examples, full API reference, Implementation notes — all packages  ship ≥200 words per module)
+3. **`packages/crypto/password-formats/package.json`** `exports` map — every subpath you can import from
+
+When the user asks an API question, read the relevant co-located `.md` first; do not answer from training-data memory.
+
+## See also
+
+- The marketplace root: `../../../README.md`
+
+---
+
+_This SKILL.md is auto-generated by `suaveplan-skills/scripts/generate-skills.ts` from the package's README. Do not edit by hand — re-run the generator after the README changes._

docs/devtools/tooling/install-agent-skills/assets/skills/permissions/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: permissions
+description: Use when implementing or debugging code that uses @suaveplan/permissions: Full RBAC/ABAC permissions engine: Ability/AbilityBuilder, RoleManager, PolicyEngine, PermissionCache, conditions, and pluggable storage adapters.
+---
+
+# @suaveplan/permissions
+
+Full RBAC/ABAC permissions engine for Suaveplan. Ships role management, policy evaluation, CASL-inspired ability builder, TTL permission cache, condition evaluation, and framework-agnostic middleware.
+
+## When to use this skill
+
+- Implementing or debugging code that imports `@suaveplan/permissions`.
+- The task touches: see package README.
+- You need API guidance for this package's exports.
+
+## Quick reference
+
+```ts
+import { /* see API Reference below */ } from "@suaveplan/permissions";
+```
+
+## Dependencies
+
+Workspace dependencies: `@suaveplan/error`, `@suaveplan/events`, `@suaveplan/types`
+
+## Where to read more
+
+This skill is intentionally short. The package's own documentation is the authoritative source — read these in order:
+
+1. **`packages/auth/permissions/README.md`** — overview, install, quick-start, module index
+2. **`packages/auth/permissions/src/**/*.md`** — co-located docs per implementation file (Purpose, Features, Basic + Advanced examples, full API reference, Implementation notes — all packages  ship ≥200 words per module)
+3. **`packages/auth/permissions/package.json`** `exports` map — every subpath you can import from
+
+When the user asks an API question, read the relevant co-located `.md` first; do not answer from training-data memory.
+
+## See also
+
+- `@suaveplan/error`
+- `@suaveplan/events`
+- `@suaveplan/types`
+
+---
+
+_This SKILL.md is auto-generated by `suaveplan-skills/scripts/generate-skills.ts` from the package's README. Do not edit by hand — re-run the generator after the README changes._

docs/devtools/tooling/install-agent-skills/assets/skills/pick-plugins/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: pick-plugins
+description: Use when starting a new project, scaffolding a Suaveplan-based codebase, or asking "which plugins do I need". Interrogates the user's use case (password manager, multiplayer game, SaaS, logistics, P2P app, email platform, DMX, astronomy, API service, CLI), matches it to a project archetype, and outputs the recommended `suaveplan-*` plugin install commands plus a build-order hint.
+---
+
+# Pick the right Suaveplan plugins for your project
+
+The Suaveplan marketplace ships ~50 plugins covering everything from cryptographic primitives to 3D game physics. Most projects need 10–20 of them, not all 50. This skill asks what you're building, matches it against the archetype recipes in `data/archetypes.yml`, and produces a curated install list.
+
+## When to invoke
+
+- User says "I want to build X" and X involves the Suaveplan stack.
+- User asks "which plugins do I need for Y".
+- User is scaffolding a new app, service, or game.
+- After installing the marketplace and before installing individual plugins.
+
+## Fast path: deterministic CLI matcher
+
+If the marketplace repo is checked out locally, prefer running the matcher and presenting its output verbatim:
+
+```bash
+bun /path/to/suaveplan-skills/scripts/match-archetype.ts "<the user's description>"
+# JSON form (if you want to compose with other tools):
+bun /path/to/suaveplan-skills/scripts/match-archetype.ts --json "<...>"
+```
+
+The matcher implements the algorithm in this skill. If the user says "I'm building a password manager", running it returns the password-manager archetype with its install commands ready to paste. Use the output directly; do not re-derive.
+
+If the matcher is not available (the user hasn't cloned the marketplace repo, or only has the plugin installed), fall back to the manual procedure below.
+
+## Manual procedure
+
+1. **Read** `data/archetypes.yml` (sibling of this file via `${CLAUDE_PLUGIN_ROOT}/data/archetypes.yml`).
+2. **Ask the user** in one short turn: "What are you building?" Give them the archetype names from the YAML as a menu but accept free text.
+3. **Match** the user's answer to one or more archetypes:
+   - Free text matches via the `signals` field of each archetype (case-insensitive substring match on any signal phrase).
+   - Menu pick matches by archetype key directly.
+   - If multiple archetypes match (e.g. "SaaS with email marketing"), union the `core` lists.
+4. **Output** in this exact order:
+   - **Recommended plugins** — bulleted list of `suaveplan-<plugin>` for every plugin in `core`, with the plugin's marketplace description.
+   - **Optional extras** — bulleted list from `optional`, prefixed with "consider if:" hint where the YAML's `notes` field calls them out.
+   - **Install commands** — a copy-pastable block:
+
+```text
+     /plugin install suaveplan-<core-1>@suaveplan
+     /plugin install suaveplan-<core-2>@suaveplan
+     ...
+     ```
+
+   - **Notes** — verbatim from the archetype's `notes` field, if present.
+   - **Build order hint** — order the plugins by dependency layer (foundation → observability → primitives → domain plugins → UI/api → dev). The order in `core` lists is already roughly correct; preserve it.
+5. **Offer to refine**: "Anything in this list you don't need?" / "Anything missing? Tell me more about the project."
+
+## Matching rules
+
+- **Free text → archetype**: lowercase the user's answer, lowercase each signal, substring match. Sum match counts per archetype; pick the highest. Tie → ask the user to disambiguate.
+- **No match**: don't guess. Say "I don't have an archetype for that yet — tell me what categories your project touches (auth, data, network, UI, gaming, payment, comms, media, geo, dev) and I'll assemble a plugin set from those."
+- **Multi-archetype**: if signals from two archetypes both match strongly (≥2 each), confirm with the user before unioning.
+
+## What this skill does NOT do
+
+- It does not run `/plugin install` for the user. It produces the commands; the user executes them.
+- It does not read the user's existing codebase. If the user has an existing project, ask them to describe it rather than scanning files.
+- It does not modify `data/archetypes.yml`. New archetypes are added by editing the YAML in this plugin and committing.
+
+## Example interaction
+
+> **User:** I'm building a password manager
+>
+> **You:** That matches the **password-manager** archetype. You'll want these plugins:
+>
+> - `suaveplan-foundation` — error hierarchy, types, tsconfig
+> - `suaveplan-crypto` — hash, curve, cipher, AEAD, signing
+> - `suaveplan-vaulted` — SRP, OTP, WebAuthn, vault orchestration
+> - `suaveplan-drive` — encrypted file attachments
+> - … (full list)
+>
+> ```
+> /plugin install suaveplan-foundation@suaveplan
+> /plugin install suaveplan-crypto@suaveplan
+> /plugin install suaveplan-vaulted@suaveplan
+> ...
+> ```
+>
+> **Notes from the recipe:** `vaulted` depends on `crypto` — install both. `drive` carries encrypted file attachments and sharing.
+>
+> Anything you'd like to drop or add?
+
+## Reference
+
+- `data/archetypes.yml` — recipe data
+- `../../README.md` (marketplace root) — how to add the marketplace and install plugins
+- `docs/design/folder-reorg-by-domain/proposal.md` — full plugin → package mapping

docs/devtools/tooling/install-agent-skills/assets/skills/pseudo-random/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: pseudo-random
+description: Use when implementing or debugging code that uses @suaveplan/pseudo-random: Deterministic seeded PRNG implementations (Mulberry32, SFC32, Xoshiro256++, CounterRng) with offset/fork/checkpoint/restore semantics.
+---
+
+# @suaveplan/pseudo-random
+
+Deterministic, seeded pseudo-random number generators (PRNGs) conforming to the `Rng` interface from `@suaveplan/types`. Ships four algorithms — Mulberry32, SFC32, Xoshiro256++, and CounterRng — with a unified `SeededRng` surface that includes `nextUint32`, `nextFloat`, `skip`, `at`, `fork`, `checkpoint`, and `restore`. Use this package when you need reproducible randomness (procedural generation, game simulations, property tests) or seek O(1) access to arbitrary positions in the sequence. For cryptographically secure randomness use `@suaveplan/random` (CSPRNG-backed) or `@suaveplan/crypto` (raw bytes). Utility functions `shuffle`, `sample`, `choice`, and `weightedChoice` accept any `Rng` and work with both seeded and crypto-backed sources.
+
+## When to use this skill
+
+- Implementing or debugging code that imports `@suaveplan/pseudo-random`.
+- The task touches: see package README.
+- You need API guidance for this package's exports.
+
+## Quick reference
+
+```ts
+import { /* see API Reference below */ } from "@suaveplan/pseudo-random";
+```
+
+## Dependencies
+
+Workspace dependencies: `@suaveplan/error`, `@suaveplan/types`
+
+## Where to read more
+
+This skill is intentionally short. The package's own documentation is the authoritative source — read these in order:
+
+1. **`packages/foundation/pseudo-random/README.md`** — overview, install, quick-start, module index
+2. **`packages/foundation/pseudo-random/src/**/*.md`** — co-located docs per implementation file (Purpose, Features, Basic + Advanced examples, full API reference, Implementation notes — all packages  ship ≥200 words per module)
+3. **`packages/foundation/pseudo-random/package.json`** `exports` map — every subpath you can import from
+
+When the user asks an API question, read the relevant co-located `.md` first; do not answer from training-data memory.
+
+## See also
+
+- `@suaveplan/error`
+- `@suaveplan/types`
+
+---
+
+_This SKILL.md is auto-generated by `suaveplan-skills/scripts/generate-skills.ts` from the package's README. Do not edit by hand — re-run the generator after the README changes._

docs/devtools/tooling/install-agent-skills/assets/skills/qrcode/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: qrcode
+description: Use when implementing or debugging code that uses @suaveplan/qrcode: QR code generation producing SVG, pixel matrix, terminal (Unicode blocks), and data URL representations.
+---
+
+# @suaveplan/qrcode
+
+QR code generation producing SVG, pixel matrix, terminal (Unicode blocks), and data URL representations. Implements QR code versions 1-10, error correction levels L/M/Q/H, automatic version and mode selection.
+
+## When to use this skill
+
+- Implementing or debugging code that imports `@suaveplan/qrcode`.
+- The task touches: see package README.
+- You need API guidance for this package's exports.
+
+## Quick reference
+
+```ts
+import { /* see API Reference below */ } from "@suaveplan/qrcode";
+```
+
+## Dependencies
+
+Workspace dependencies: _none_
+
+## Where to read more
+
+This skill is intentionally short. The package's own documentation is the authoritative source — read these in order:
+
+1. **`packages/foundation/qrcode/README.md`** — overview, install, quick-start, module index
+2. **`packages/foundation/qrcode/src/**/*.md`** — co-located docs per implementation file (Purpose, Features, Basic + Advanced examples, full API reference, Implementation notes — all packages  ship ≥200 words per module)
+3. **`packages/foundation/qrcode/package.json`** `exports` map — every subpath you can import from
+
+When the user asks an API question, read the relevant co-located `.md` first; do not answer from training-data memory.
+
+## See also
+
+- The marketplace root: `../../../README.md`
+
+---
+
+_This SKILL.md is auto-generated by `suaveplan-skills/scripts/generate-skills.ts` from the package's README. Do not edit by hand — re-run the generator after the README changes._

docs/devtools/tooling/install-agent-skills/assets/skills/queue/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: queue
+description: Use when implementing or debugging code that uses @suaveplan/queue: Enterprise-grade queue management: memory/priority/delayed queues, concurrent workers with retry and dead-letter, job state machines, OTel instrumentation.
+---
+
+# @suaveplan/queue
+
+Enterprise-grade queue management: memory/priority/delayed queues, concurrent workers with retry and dead-letter forwarding, job state machines, and OTel instrumentation.
+
+## When to use this skill
+
+- Implementing or debugging code that imports `@suaveplan/queue`.
+- The task touches: see package README.
+- You need API guidance for this package's exports.
+
+## Quick reference
+
+```ts
+import { /* see API Reference below */ } from "@suaveplan/queue";
+```
+
+## Dependencies
+
+Workspace dependencies: `@suaveplan/error`, `@suaveplan/types`
+
+## Where to read more
+
+This skill is intentionally short. The package's own documentation is the authoritative source — read these in order:
+
+1. **`packages/jobs/queue/README.md`** — overview, install, quick-start, module index
+2. **`packages/jobs/queue/src/**/*.md`** — co-located docs per implementation file (Purpose, Features, Basic + Advanced examples, full API reference, Implementation notes — all packages  ship ≥200 words per module)
+3. **`packages/jobs/queue/package.json`** `exports` map — every subpath you can import from
+
+When the user asks an API question, read the relevant co-located `.md` first; do not answer from training-data memory.
+
+## See also
+
+- `@suaveplan/error`
+- `@suaveplan/types`
+
+---
+
+_This SKILL.md is auto-generated by `suaveplan-skills/scripts/generate-skills.ts` from the package's README. Do not edit by hand — re-run the generator after the README changes._

docs/devtools/tooling/install-agent-skills/assets/skills/random/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: random
+description: Use when implementing or debugging code that uses @suaveplan/random: High-level CSPRNG-backed randomness: strings, UUID/ULID/Nanoid, collections, objects, game primitives, and a full statistical-distribution suite.
+---
+
+# @suaveplan/random
+
+High-level cryptographically secure randomness for application use. This is the everyday random package — it wraps the CSPRNG with ergonomic helpers for every common randomness task: unique IDs (`randomUUID` v4, `randomUUIDv7`, `randomULID`, `randomNanoid`), random strings with eight charset presets, collection utilities (`shuffle`, `choice`, `sample`, `weightedChoice`), object utilities (`randomKey`, `randomEntry`, `randomSubset`), game primitives (`coin`, `dice`, `roll`), and a full suite of continuous and discrete statistical distributions (Normal, LogNormal, Binomial, Poisson, and eight more). Every function accepts an optional `rng?: Rng` — omit it for crypto-backed defaults, or pass a `SeededRng` from `@suaveplan/pseudo-random` for deterministic tests. Do not confuse with `@suaveplan/pseudo-random` (seeded, deterministic, for procedural generation) or `@suaveplan/crypto` (raw cryptographic byte generation).
+
+## When to use this skill
+
+- Implementing or debugging code that imports `@suaveplan/random`.
+- The task touches: see package README.
+- You need API guidance for this package's exports.
+
+## Quick reference
+
+```ts
+import { /* see API Reference below */ } from "@suaveplan/random";
+```
+
+## Dependencies
+
+Workspace dependencies: `@suaveplan/error`, `@suaveplan/pseudo-random`, `@suaveplan/types`
+
+## Where to read more
+
+This skill is intentionally short. The package's own documentation is the authoritative source — read these in order:
+
+1. **`packages/foundation/random/README.md`** — overview, install, quick-start, module index
+2. **`packages/foundation/random/src/**/*.md`** — co-located docs per implementation file (Purpose, Features, Basic + Advanced examples, full API reference, Implementation notes — all packages  ship ≥200 words per module)
+3. **`packages/foundation/random/package.json`** `exports` map — every subpath you can import from
+
+When the user asks an API question, read the relevant co-located `.md` first; do not answer from training-data memory.
+
+## See also
+
+- `@suaveplan/error`
+- `@suaveplan/pseudo-random`
+- `@suaveplan/types`
+
+---
+
+_This SKILL.md is auto-generated by `suaveplan-skills/scripts/generate-skills.ts` from the package's README. Do not edit by hand — re-run the generator after the README changes._

docs/devtools/tooling/install-agent-skills/assets/skills/rate-limiter/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: rate-limiter
+description: Use when implementing or debugging code that uses @suaveplan/rate-limiter: Enterprise rate limiter: TokenBucket, SlidingWindow, FixedWindow algorithms; tenant multipliers; rule-based routing; pluggable storage; OTel instrumentation.
+---
+
+# @suaveplan/rate-limiter
+
+Enterprise rate limiter with three algorithms, rule-based routing, tenant multipliers, pluggable storage, and OTel instrumentation.
+
+## When to use this skill
+
+- Implementing or debugging code that imports `@suaveplan/rate-limiter`.
+- The task touches: see package README.
+- You need API guidance for this package's exports.
+
+## Quick reference
+
+```ts
+import { /* see API Reference below */ } from "@suaveplan/rate-limiter";
+```
+
+## Dependencies
+
+Workspace dependencies: `@suaveplan/error`, `@suaveplan/events`, `@suaveplan/logger`, `@suaveplan/types`
+
+## Where to read more
+
+This skill is intentionally short. The package's own documentation is the authoritative source — read these in order:
+
+1. **`packages/platform/rate-limiter/README.md`** — overview, install, quick-start, module index
+2. **`packages/platform/rate-limiter/src/**/*.md`** — co-located docs per implementation file (Purpose, Features, Basic + Advanced examples, full API reference, Implementation notes — all packages  ship ≥200 words per module)
+3. **`packages/platform/rate-limiter/package.json`** `exports` map — every subpath you can import from
+
+When the user asks an API question, read the relevant co-located `.md` first; do not answer from training-data memory.
+
+## See also
+
+- `@suaveplan/error`
+- `@suaveplan/events`
+- `@suaveplan/logger`
+- `@suaveplan/types`
+
+---
+
+_This SKILL.md is auto-generated by `suaveplan-skills/scripts/generate-skills.ts` from the package's README. Do not edit by hand — re-run the generator after the README changes._

docs/devtools/tooling/install-agent-skills/assets/skills/readline/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: readline
+description: Use when implementing or debugging code that uses @suaveplan/readline: Terminal I/O primitive: AsyncGenerator line reader and interactive prompt interface.
+---
+
+# @suaveplan/readline
+
+AsyncGenerator line reader and interactive prompt interface for Node.js streams, file paths, and Web Streams.
+
+## When to use this skill
+
+- Implementing or debugging code that imports `@suaveplan/readline`.
+- The task touches: see package README.
+- You need API guidance for this package's exports.
+
+## Quick reference
+
+```ts
+import { /* see API Reference below */ } from "@suaveplan/readline";
+```
+
+## Dependencies
+
+Workspace dependencies: `@suaveplan/error`, `@suaveplan/types`
+
+## Where to read more
+
+This skill is intentionally short. The package's own documentation is the authoritative source — read these in order:
+
+1. **`packages/foundation/readline/README.md`** — overview, install, quick-start, module index
+2. **`packages/foundation/readline/src/**/*.md`** — co-located docs per implementation file (Purpose, Features, Basic + Advanced examples, full API reference, Implementation notes — all packages  ship ≥200 words per module)
+3. **`packages/foundation/readline/package.json`** `exports` map — every subpath you can import from
+
+When the user asks an API question, read the relevant co-located `.md` first; do not answer from training-data memory.
+
+## See also
+
+- `@suaveplan/error`
+- `@suaveplan/types`
+
+---
+
+_This SKILL.md is auto-generated by `suaveplan-skills/scripts/generate-skills.ts` from the package's README. Do not edit by hand — re-run the generator after the README changes._

docs/devtools/tooling/install-agent-skills/assets/skills/retry/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: retry
+description: Use when implementing or debugging code that uses @suaveplan/retry: Retry strategies with exponential/linear/constant backoff, jitter, circuit breaker with half-open probing, sleep and timeout helpers.
+---
+
+# @suaveplan/retry
+
+Retry strategies and circuit-breaker for async operations. The package provides constant, linear, and exponential backoff with four jitter modes (full, equal, decorrelated, none), a `sleep` helper with AbortSignal support, a per-attempt `withTimeout` wrapper, and a three-state circuit breaker (closed → open → half-open) with event emission and configurable failure/success thresholds. All entry points accept an injectable `Clock` and `AbortSignal` so they integrate cleanly with test harnesses and request cancellation.
+
+## When to use this skill
+
+- Implementing or debugging code that imports `@suaveplan/retry`.
+- The task touches: see package README.
+- You need API guidance for this package's exports.
+
+## Quick reference
+
+```ts
+import { /* see API Reference below */ } from "@suaveplan/retry";
+```
+
+## Dependencies
+
+Workspace dependencies: `@suaveplan/error`, `@suaveplan/events`, `@suaveplan/types`
+
+## Where to read more
+
+This skill is intentionally short. The package's own documentation is the authoritative source — read these in order:
+
+1. **`packages/foundation/retry/README.md`** — overview, install, quick-start, module index
+2. **`packages/foundation/retry/src/**/*.md`** — co-located docs per implementation file (Purpose, Features, Basic + Advanced examples, full API reference, Implementation notes — all packages  ship ≥200 words per module)
+3. **`packages/foundation/retry/package.json`** `exports` map — every subpath you can import from
+
+When the user asks an API question, read the relevant co-located `.md` first; do not answer from training-data memory.
+
+## See also
+
+- `@suaveplan/error`
+- `@suaveplan/events`
+- `@suaveplan/types`
+
+---
+
+_This SKILL.md is auto-generated by `suaveplan-skills/scripts/generate-skills.ts` from the package's README. Do not edit by hand — re-run the generator after the README changes._

docs/devtools/tooling/install-agent-skills/assets/skills/schema-registry/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: schema-registry
+description: Use when implementing or debugging code that uses @suaveplan/schema-registry: Versioned schema registry with forward/backward compatibility checking for evolving data contracts.
+---
+
+# @suaveplan/schema-registry
+
+Versioned schema registry with forward/backward/full compatibility checking for evolving data contracts. Register schemas by subject name, enforce evolution rules, and detect breaking changes before they reach production.
+
+## When to use this skill
+
+- Implementing or debugging code that imports `@suaveplan/schema-registry`.
+- The task touches: see package README.
+- You need API guidance for this package's exports.
+
+## Quick reference
+
+```ts
+import { /* see API Reference below */ } from "@suaveplan/schema-registry";
+```
+
+## Dependencies
+
+Workspace dependencies: `@suaveplan/error`, `@suaveplan/types`
+
+## Where to read more
+
+This skill is intentionally short. The package's own documentation is the authoritative source — read these in order:
+
+1. **`packages/foundation/schema-registry/README.md`** — overview, install, quick-start, module index
+2. **`packages/foundation/schema-registry/src/**/*.md`** — co-located docs per implementation file (Purpose, Features, Basic + Advanced examples, full API reference, Implementation notes — all packages  ship ≥200 words per module)
+3. **`packages/foundation/schema-registry/package.json`** `exports` map — every subpath you can import from
+
+When the user asks an API question, read the relevant co-located `.md` first; do not answer from training-data memory.
+
+## See also
+
+- `@suaveplan/error`
+- `@suaveplan/types`
+
+---
+
+_This SKILL.md is auto-generated by `suaveplan-skills/scripts/generate-skills.ts` from the package's README. Do not edit by hand — re-run the generator after the README changes._

docs/devtools/tooling/install-agent-skills/assets/skills/search/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: search
+description: Use when implementing or debugging code that uses @suaveplan/search: Full-text and fuzzy search primitives with in-memory BM25 engine, trigram fuzzy matching, faceted search, and pagination support.
+---
+
+# @suaveplan/search
+
+Full-text and fuzzy search primitives with in-memory BM25 engine, trigram fuzzy matching, faceted search, and pagination support.
+
+## When to use this skill
+
+- Implementing or debugging code that imports `@suaveplan/search`.
+- The task touches: see package README.
+- You need API guidance for this package's exports.
+
+## Quick reference
+
+```ts
+import { /* see API Reference below */ } from "@suaveplan/search";
+```
+
+## Dependencies
+
+Workspace dependencies: `@suaveplan/error`, `@suaveplan/pagination`, `@suaveplan/types`
+
+## Where to read more
+
+This skill is intentionally short. The package's own documentation is the authoritative source — read these in order:
+
+1. **`packages/platform/search/README.md`** — overview, install, quick-start, module index
+2. **`packages/platform/search/src/**/*.md`** — co-located docs per implementation file (Purpose, Features, Basic + Advanced examples, full API reference, Implementation notes — all packages  ship ≥200 words per module)
+3. **`packages/platform/search/package.json`** `exports` map — every subpath you can import from
+
+When the user asks an API question, read the relevant co-located `.md` first; do not answer from training-data memory.
+
+## See also
+
+- `@suaveplan/error`
+- `@suaveplan/pagination`
+- `@suaveplan/types`
+
+---
+
+_This SKILL.md is auto-generated by `suaveplan-skills/scripts/generate-skills.ts` from the package's README. Do not edit by hand — re-run the generator after the README changes._

docs/devtools/tooling/install-agent-skills/assets/skills/security-codes/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: security-codes
+description: Use when implementing or debugging code that uses @suaveplan/security-codes: Detect and sanitise sensitive security-code leakage in strings: API keys, JWTs, credit cards, GitHub tokens, Stripe keys, SSH keys, PEM blocks, AWS access keys, and more.
+---
+
+# @suaveplan/security-codes
+
+Detect and sanitise sensitive security-code leakage in strings. Handles API keys, JWTs, credit cards, GitHub tokens, Stripe keys, SSH keys, PEM blocks, AWS access keys, OpenAI keys, Google API keys, and high-entropy heuristics.
+
+## When to use this skill
+
+- Implementing or debugging code that imports `@suaveplan/security-codes`.
+- The task touches: see package README.
+- You need API guidance for this package's exports.
+
+## Quick reference
+
+```ts
+import { /* see API Reference below */ } from "@suaveplan/security-codes";
+```
+
+## Dependencies
+
+Workspace dependencies: _none_
+
+## Where to read more
+
+This skill is intentionally short. The package's own documentation is the authoritative source — read these in order:
+
+1. **`packages/platform/security-codes/README.md`** — overview, install, quick-start, module index
+2. **`packages/platform/security-codes/src/**/*.md`** — co-located docs per implementation file (Purpose, Features, Basic + Advanced examples, full API reference, Implementation notes — all packages  ship ≥200 words per module)
+3. **`packages/platform/security-codes/package.json`** `exports` map — every subpath you can import from
+
+When the user asks an API question, read the relevant co-located `.md` first; do not answer from training-data memory.
+
+## See also
+
+- The marketplace root: `../../../README.md`
+
+---
+
+_This SKILL.md is auto-generated by `suaveplan-skills/scripts/generate-skills.ts` from the package's README. Do not edit by hand — re-run the generator after the README changes._