argsbarg 6.1.2 → 6.1.3

package/docs/configure.md

@@ -1,5 +1,7 @@
 # Configure command
 
+> This feature is experimental.
+
 The `configure` built-in manages **agent artifacts** (skills, MCP config, app config). The **binary and shell completions** ship via Homebrew — see [distribution-homebrew.md](distribution-homebrew.md).
 
 Opt out with `configure: { enabled: false }` on the program root.

package/docs/decisions.md

@@ -0,0 +1,40 @@
+# Decisions
+
+This doc tracks big architectural decisions so that we can avoid re-hashing the same decisions over and over.
+
+## HTTP REST vs flat `/tools/:name`
+
+Decision: **nested `/api/...` REST** (7.0)
+
+### Context
+
+- v6 exposed tools as `POST /tools/:flat-name` with hyphen-joined paths
+- Nested resources (e.g. `workspaces/{id}`) and verb-specific methods need a route model aligned with the CLI tree
+
+### Rationale
+
+1. Command tree already encodes hierarchy — REST paths mirror `http.segment ?? key` plus `:param` routers
+2. Verb leaves (`get`, `post`, …) map to HTTP methods without duplicating path segments
+3. OpenAPI paths match real URLs clients call; query/body binding matches MCP flat args
+4. Hard break on `/tools/*` is acceptable pre-7.0-ship
+
+## Validation: JSON-SCHEMA vs Zod, etc
+
+Decision: JSON-SCHEMA
+
+### Context
+- JSON-SCHEMA is an open standard to capture a schema in json
+- Zod is the leading Typescript schema management library
+- Others are similar or less good than Zod
+
+### Rational
+Zod may actually cause more complexity and little/no gain for consumers. 
+
+Yes Zod implements some features we do custom for JSON-SCHEMA, but is opinionated, less flexible, and would actually explode complexity in some situations. Zod could be a win for consumers if they require substantial, complex validation -- but then that may not convert well to json-schema anyways and json-schema generation is a big win.
+
+1. Argsbarg does a lot of schema patching/manipulation to create different schemas per target (cli-schema.json, MCP contract, openapi.json). This would be harder with Zod
+2. Consumers can already use zod if they want by using Zod's to-json-schema features to convert when passing to Argsbarg. So we aren't actually alienating / thwarting consumers from using Zod anyways.
+3. For uses like API pass-through, proxy, dynamic schemas, Zod may actually explode complexity for consumers.
+4. Our TS->json-schema approach is actually easier and better in many cases
+  - Just write plain typescript, done.
+  - Better intellisense -- substantially less abstraction/inference, much better control

package/docs/developing.md

@@ -32,14 +32,28 @@ Sibling consumer repos (machine-specific paths in the root `justfile` `consumer_
 
 | Recipe | When | Effect |
 | --- | --- | --- |
-| `just consumers-dev` | Before publish; hacking on argsbarg locally | `bun add argsbarg@file:<relative>`; refresh `.cursor/rules/cli-program.mdc` from template (keeps app-specific suffix) |
-| `just consumers-sync` | After release | Sets `"argsbarg": "^<this package.json version>"`, `bun install`, merge **argsbarg Cursor rule**, `just build`, `just docgen`, `just install-local` (Homebrew dev formula + agent artifacts; `just install` is an alias) |
+| `just consumers-dev` | Before publish; hacking on argsbarg locally | `bun add argsbarg@file:<relative>`; refresh `.cursor/rules/cli-program.mdc` and `code.mdc` from template (keeps app-specific suffix) |
+| `just consumers-sync` | After release | Sets `"argsbarg": "^<this package.json version>"`, `bun install`, merge **cli-program** + **code** Cursor rules, `just build`, `just docgen`, `just install-local` (Homebrew dev formula + agent artifacts; `just install` is an alias) |
+| `just consumers-schemagen` | After `@sg` type changes in consumers | Runs `argsbarg schemagen` in each `consumer_apps` path (fails if missing) |
 
 `consumers-sync` reads the version from **this repo’s** `package.json` — not npm. Run it **after** `just release` so consumers pin a version that exists on the registry.
 
-**Argsbarg authoring rule** — `scripts/merge-cli-program-rule.ts` copies `examples/full-example/.cursor/rules/cli-program.mdc` into each consumer’s `.cursor/rules/cli-program.mdc`, preserving any existing `**… conventions:**` footer block.
+**Argsbarg authoring rules** — `scripts/merge-cli-program-rule.ts` and `scripts/merge-code-rule.ts` copy templates from `examples/full-example/.cursor/rules/` into each consumer, preserving any existing `**… conventions:**` footer block.
 
-**Recommended in each consumer:** replace the template placeholder with `**<app> conventions:**` bullets (paths to `read*Flags`, shared flags, Ink vs JSON-only). Commit that file; merges refresh the shared top, not your footer.
+**Recommended in each consumer:** replace template placeholders with `**<app> conventions:**` bullets. Commit those files; merges refresh the shared top, not your footer.
+
+## Upgrading consumer apps to 7.0
+
+Breaking changes (no backward compat). See [CHANGELOG.md](../CHANGELOG.md) `[Unreleased]`.
+
+1. **Schemagen:** replace `export type configType|inputType|outputType` with `/** @sg */` immediately above `export interface` / `export type` (no blank line).
+2. **Imports:** `configSchema` → `{AppConfig}Schema` (type name + `Schema`); same for leaf `inputSchema` / `outputSchema` imports (`StatusJsonOutputSchema`, etc.).
+3. **Run** `argsbarg schemagen` (or `just schemagen`) after every type change.
+4. **HTTP:** use `/api/...` REST routes only (`POST /tools/*` removed).
+5. **Hooks:** remove manual `ctx.locals.requestId` in `beforeInvoke` — framework seeds it.
+6. **Exports:** stop importing `loadLeafInputs` / `CliHttpResponseConfig` from `argsbarg` (use `ctx.inputs`, leaf `http.successContentType`).
+7. **Cursor rules:** `just consumers-dev` merges `cli-program.mdc` + `code.mdc` (includes **Abstractions** needless-extraction rule).
+8. **Verify:** `just test` and `just docgen` in each consumer repo.
 
 **Consumer app skill** — `just install-local` in each consumer (part of `consumers-sync`) runs Homebrew dev install then `myapp configure --sync --yes`, which updates `~/.cursor/skills/<app>/` from that app’s schema — not the argsbarg framework rule.
 
@@ -60,7 +74,31 @@ just full-example-schemagen
 just test
 ```
 
-See [`.cursor/rules/examples.mdc`](../.cursor/rules/examples.mdc) for maintainer guidance.
+See [docs/README.md](README.md) for the full documentation map.
+
+## Advanced imports
+
+Subpath exports (root barrel still re-exports everything):
+
+```typescript
+import { Cli, type CliProgram } from "argsbarg/cli";
+import { generateOpenApi, httpServeHttp } from "argsbarg/http";
+import { packMcpBundle } from "argsbarg/mcp"; // @experimental
+import { shouldRunHeadless } from "argsbarg/headless";
+import { runSchemagen } from "argsbarg/schemagen";
+```
+
+## Module boundaries
+
+| Layer | Role |
+| --- | --- |
+| `schema.ts`, `parse.ts`, `context.ts` | Transport-agnostic CLI core |
+| `http/` | HTTP tool server (`httpServer` capability) |
+| `mcp/` | MCP stdio server and bundle (`mcpServer` capability) |
+| `configure/artifacts/` | Agent artifact sync (`configure` capability) |
+| `docs/` | Built-in documentation generators |
+
+Capabilities are declared on `CliProgram`; builtins wire them in [`src/builtins/`](../src/builtins/).
 
 ## Docs
 

package/docs/http-server.md

@@ -0,0 +1,171 @@
+# HTTP API server
+
+ArgsBarg can expose your CLI as an HTTP REST server. Each **leaf command** becomes a route under `/api/...` — nested command paths, HTTP verbs, and `:param` routers are reflected in the URL. The server uses Bun's built-in HTTP stack and binds to **localhost by default**.
+
+The HTTP API is **opt-in**. Apps that do not set `httpServer` on the program root behave exactly as before.
+
+## Quick start
+
+1. Add `httpServer` to your program root:
+
+```typescript
+import pkg from "../package.json" with { type: "json" };
+
+const cli = {
+  key: "myapp",
+  version: pkg.version,
+  description: "My app.",
+  httpServer: { enabled: true },
+  commands: [/* ... */],
+} satisfies CliProgram;
+```
+
+`httpServer: { enabled: true }` opts in. Omit `httpServer` entirely to disable HTTP. Empty `httpServer: {}` is rejected at validation.
+
+2. Run the HTTP server:
+
+```bash
+myapp http
+```
+
+The process listens until interrupted. Startup prints the listen URL to stderr.
+
+Optional flags on `myapp http` (and `myapp http serve`): `--host`, `--port`, `--trust-proxy`, `--obscure-errors`, `--log-format`, `--log-file`, `--no-access-log`, `--dev`.
+
+## Configuration
+
+Set `httpServer` on the **program root only**. Validation rejects `httpServer` on nested nodes.
+
+| Field | Default | Purpose |
+| --- | --- | --- |
+| `enabled` | *(required)* | Must be `true` when `httpServer` is set |
+| `host` | `127.0.0.1` | Listen address |
+| `port` | `3000` | Listen port |
+| `trustProxy` | `false` | Honor `X-Forwarded-For` in hooks and access logs |
+| `errors.errorSchema` | `{ error: string }` | OpenAPI + default error body shape |
+| `errors.obscureUnexpected` | `false` | Client sees generic message on 500; ECS logs real stack |
+| `hooks` | — | Observe-only wire hooks (`onRequest`, `onResponse`, `onError`) |
+
+`httpServer` and `mcpServer` are independent — enable either or both.
+
+Program-level `program.log` controls ECS JSON vs human text on stderr (and optional file tee). See [docs/decisions.md](decisions.md).
+
+## REST routes
+
+Routes are derived from the command tree:
+
+| CLI path | HTTP | Notes |
+| --- | --- | --- |
+| `workspaces get` | `GET /api/workspaces` | Verb leaf (`get`) omitted from URL |
+| `workspaces post` | `POST /api/workspaces` | Default POST success **201** |
+| `workspaces :id get` | `GET /api/workspaces/{id}` | `:id` param router |
+| `stat owner lookup` | `POST /api/stat/owner/lookup` | Default method POST when key is not a verb |
+
+Method precedence: `leaf.http.method` → verb key (`get`/`post`/…) → **POST**.
+
+Query string binds to options (values starting with `{` or `[` are JSON-parsed). Body on POST/PUT/PATCH binds to options, positionals, and `inputSchema` fields.
+
+Per-surface exposure: `http.enabled: false` removes a leaf from the route table; `http.hidden: true` keeps it callable but omits it from OpenAPI.
+
+## Endpoints
+
+| Method | Path | Purpose |
+| --- | --- | --- |
+| `GET` | `/health` or `/health/live` | Liveness — 200 when server is listening |
+| `GET` | `/health/ready` | Readiness — config + optional `program.readiness` |
+| `GET` | `/openapi.json` | OpenAPI 3.1 REST paths |
+| `GET` | `/openapi-browser` | Interactive Scalar API reference (CDN) |
+| `*` | `/api/...` | Invoke user commands (method per route) |
+| `OPTIONS` | `*` | CORS preflight (`GET, POST, PUT, PATCH, DELETE`) |
+
+`POST /tools/*` was removed in 7.0 — use `/api/*` only.
+
+## Examples
+
+```bash
+curl -s http://127.0.0.1:3000/health
+curl -s http://127.0.0.1:3000/health/ready
+curl -s http://127.0.0.1:3000/openapi.json
+open http://127.0.0.1:3000/openapi-browser
+curl -s http://127.0.0.1:3000/api/workspaces
+curl -s -X POST http://127.0.0.1:3000/api/workspaces \
+  -H 'content-type: application/json' \
+  -d '{"name":"qa2"}'
+curl -s http://127.0.0.1:3000/api/workspaces/{id}
+```
+
+Discover paths and request shapes from `openapi.json` or `myapp docs openapi`.
+
+## Handler responses (`ctx.respond()`)
+
+API and MCP tool handlers must return machine-readable output via **`ctx.respond()`** or by **returning a value** (implicit JSON). `console.log` is not included in HTTP/MCP success payloads.
+
+```typescript
+handler: (ctx) => {
+  if (ctx.hasFlag("json")) {
+    return { user: "alice", path: "/tmp" };
+  }
+  ctx.respond({
+    body: pdfBytes,
+    contentType: "application/pdf",
+    headers: { "Content-Disposition": 'inline; filename="invoice.pdf"' },
+  });
+},
+```
+
+**CLI mode:** `ctx.respond()` prints to stdout. Handlers may still use `console.log` for human-only CLI output.
+
+### Leaf HTTP metadata
+
+```typescript
+http?: {
+  method?: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+  segment?: string;              // URL segment override
+  successStatus?: number;
+  successContentType?: string;   // OpenAPI + default Content-Type
+  contentDisposition?: string;
+};
+```
+
+## Responses
+
+**Success:** status from `ctx.respond({ status })` → `http.successStatus` → method default (GET 200, POST 201, DELETE 204 without body).
+
+| Body type | HTTP `Content-Type` |
+| --- | --- |
+| object / array | `application/json` |
+| string | handler `contentType` or `text/plain` |
+| `Uint8Array` | e.g. `application/pdf` (set explicitly) |
+
+**Errors:** JSON `{ "error": "..." }` by default (override with `httpServer.errors.errorSchema`).
+
+| Situation | Status |
+| --- | --- |
+| Validation / help | 400 |
+| Unknown route | 404 |
+| Thrown handler / missing `ctx.respond()` | 500 |
+| Missing required config | 503 |
+
+Tool invocations are **not** gated on `/health/ready`; readiness is for orchestrators only.
+
+## Hooks and runtime
+
+`program.hooks` (`beforeInvoke`, `afterInvoke`, `formatError`, `onError`) run for user commands on CLI, HTTP, and MCP — **not** for builtins.
+
+- `ctx.locals` — per-request bag (fresh each invoke); framework sets `requestId` before `beforeInvoke` (HTTP/MCP wire id when present, else a new UUID)
+- `ctx.runtime` — shared `ServerRuntime.state` on HTTP/MCP server sessions
+- `ctx.pathParams` — values from `:param` routers
+
+Error order: `formatError` → `onError` → ECS log → client response.
+
+## CORS
+
+All responses include wide-open CORS headers (`Access-Control-Allow-Origin: *`). Not configurable in v1.
+
+## OpenAPI
+
+Call `generateOpenApi(program)` from `argsbarg/http`, fetch `GET /openapi.json`, or run `myapp docs openapi --save`. Nested `$ref` in input/output schemas are dereferenced in the spec.
+
+## Complex tool inputs
+
+Set `inputSchema` on the leaf and read coerced values with `ctx.inputs` / `ctx.inputsAs<T>()`. HTTP query, body, and path params merge into inputs before validation.

package/docs/json-schema-subset.md

@@ -0,0 +1,51 @@
+# JSON Schema subset
+
+Argsbarg validates `program.appConfig`, leaf `inputSchema`, and related documents with a **custom Draft-07 subset** in [`src/config/validate.ts`](../src/config/validate.ts). There is no runtime dependency on a full JSON Schema validator.
+
+Use this page when authoring schemas for config files, `inputSchema` on leaves, or `@sg` schemagen output.
+
+## Supported constructs
+
+| Feature | Notes |
+| --- | --- |
+| `type` | `object`, `array`, `string`, `integer`, `number`, `boolean`, `null` |
+| `properties` / `required` | Object keys; `additionalProperties: false` enforced when set |
+| `items` | Homogeneous arrays; comma-separated CLI strings coerced when `items` is a primitive |
+| `enum` / `const` | Exact value checks |
+| `anyOf` / `oneOf` | First matching branch wins; errors surface when none match |
+| `$ref` | **Local only** — `#/definitions/Name` resolved within the same root document |
+| `definitions` | Companion to local `$ref` |
+| `format` | `date`, `date-time`, `duration`, `comma-list` (and related string coercions) |
+| `minimum` / `maximum` | Numbers and integers |
+| `minLength` / `maxLength` | Strings |
+| `pattern` | String regex (ECMAScript) |
+
+## Partial validation
+
+`validateConfigDocumentPartial` validates **present keys only** — root `required` is skipped. Used for `configure set` partial writes and bootstrap flows.
+
+Leaf `inputSchema` validation uses full validation (including `required`) before the handler runs.
+
+## Not supported (today)
+
+- Remote `$ref` (`http://…`, other files)
+- `allOf`, conditional (`if`/`then`/`else`), `not`
+- Unevaluated / dynamic references
+- `default` application at validation time (defaults come from CLI option `default` or config bindings)
+
+If schemagen emits an unsupported keyword, simplify the TypeScript type or post-process the generated JSON Schema.
+
+## Where validation runs
+
+| Surface | Validator | When |
+| --- | --- | --- |
+| App config file | `validateConfigDocument` / `Partial` | `configure set`, config load |
+| Leaf `inputSchema` | Same engine via leaf-inputs | Before handler (MCP/HTTP/CLI merged inputs) |
+| `outputSchema` | Structural checks at program validate time | Startup / `cliValidateProgram` |
+
+## Related docs
+
+- [cli-program.md](cli-program.md) — `inputSchema`, JSON leaves, `ctx.inputs` / `ctx.inputsAs`
+- [config-schema.md](config-schema.md) — `program.appConfig` and schemagen pipeline
+
+Implementation: [`src/config/validate.ts`](../src/config/validate.ts), [`src/core/leaf-inputs.ts`](../src/core/leaf-inputs.ts).

package/docs/mcp.md

@@ -1,5 +1,7 @@
 # MCP server
 
+> This feature is experimental.
+
 ArgsBarg can expose your CLI to AI agents through the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/). Each **leaf command** becomes an MCP tool; the full command tree is available as a schema resource. The server speaks JSON-RPC over stdio — one JSON object per line on stdin and stdout.
 
 MCP is **opt-in**. Apps that do not set `mcpServer` on the program root behave exactly as before.
@@ -246,7 +248,7 @@ The built-in schema resource (default URI `<sanitized-key>://schema`, e.g. `nest
 
 ### Auto docs topic resources
 
-When both **`docs.enabled`** and **`mcpServer.enabled`** are true, each user key in **`docs.topics`** is also exposed as an MCP resource:
+When docs is enabled (default) and **`mcpServer.enabled`** is true, each user key in **`docs.topics`** is also exposed as an MCP resource:
 
 | Property | Value |
 | --- | --- |
@@ -419,7 +421,7 @@ Bare **`myapp mcp`** still runs the stdio MCP server (unchanged for `configure`
 
 ## Hidden commands and options
 
-Set **`hidden: true`** on a command or option to omit it from help listings, `docs cli-schema` / `docs api`, shell completions, and MCP `tools/list` / tool `inputSchema`. Hidden commands remain invocable; **`myapp hidden-cmd -h`** still works.
+Set **`hidden: true`** on a command or option to omit it from help listings, `docs cli-schema` / `docs cli`, shell completions, and MCP `tools/list` / tool `inputSchema`. Hidden commands remain invocable; **`myapp hidden-cmd -h`** still works.
 
 ## Reserved names
 

package/docs/output-schema.md

@@ -7,12 +7,12 @@ How to describe JSON stdout on leaf commands — and the **argsbarg schemagen**
 On **leaf commands**, set `outputSchema` to a JSON Schema object when the handler emits JSON (typically with `--json`, always for JSON-only commands, or on the MCP headless path).
 
 ```typescript
-import { outputSchema } from "./__generated__/index.ts";
+import { StatusJsonOutputSchema } from "./__generated__";
 
 export const status = {
   key: "status",
   description: "Show environment status.",
-  outputSchema,
+  outputSchema: StatusJsonOutputSchema,
   handler: async (ctx) => { /* writes JSON to stdout */ },
 } satisfies CliLeaf;
 ```
@@ -20,14 +20,14 @@ export const status = {
 | Where argsbarg uses it | Purpose |
 | --- | --- |
 | `myapp docs cli-schema` | Full command tree JSON export |
-| `myapp docs api` | Markdown per-command **Output** section |
+| `myapp docs cli` | Markdown per-command **Output** section |
 | `myapp docs skill` | `reference.md` for agent skills |
 | MCP `tools/list` | Optional `outputSchema` on each tool |
 | HTTP `GET /openapi.json` | Response schema per tool |
 
 **Not validated at runtime** — argsbarg does not parse or reject handler stdout against the schema today. The schema is documentation and MCP/HTTP metadata.
 
-**Set on the leaf only** — not under `mcpTool` (legacy `mcpTool.outputSchema` still resolves but is deprecated).
+**Set on the leaf only** — not under `mcpTool`.
 
 **Draft version** — argsbarg accepts any JSON Schema object (`type`, `properties`, `definitions`, etc.). Generators may emit draft-07 or draft 2020-12; docgen embeds the object as-is.
 
@@ -38,7 +38,7 @@ See [cli-program.md — Structured stdout](cli-program.md#structured-stdout) for
 | Approach | When |
 | --- | --- |
 | **Inline object** on the leaf | One-off commands, spikes, very small shapes |
-| **Codegen from TypeScript** | Multiple commands share a shape, nested objects, or you want rich `description` fields in `docs api` / skills |
+| **Codegen from TypeScript** | Multiple commands share a shape, nested objects, or you want rich `description` fields in `docs cli` / skills |
 
 Production CLIs with several JSON commands tend to use **codegen** so types, handlers, and schemas stay aligned.
 
@@ -50,137 +50,129 @@ Reference implementations: **sqsp-qa-manager-poc**, **sqsp-workspaces**, **sqsp-
 
 ```mermaid
 flowchart LR
-  subgraph types [types.ts]
-    Config["export type configType = AppConfig"]
-    Output["export type outputType = StatusJsonOutput"]
-    Input["export type inputType = ToolInput (optional)"]
+  subgraph src [src/**/*.ts]
+    Sg["/** @sg */ export interface TypeName"]
   end
   subgraph gen [argsbarg schemagen]
-    Discover["discover types.ts roots"]
+    Walk["walk src/ minus tests and __generated__"]
     Gen["ts-json-schema-generator"]
   end
   subgraph artifacts [Gitignored __generated__]
-    Json["configSchema.json / inputSchema.json / outputSchema.json"]
+    Json["TypeNameSchema.json"]
     Index["index.ts re-exports"]
   end
   subgraph runtime [Runtime]
-    Leaves["import { outputSchema } from ./__generated__/index.ts"]
+    Leaves["import { TypeNameSchema } from ./__generated__"]
     Docgen["just docgen"]
   end
-  types --> Discover --> Gen --> Json
+  src --> Walk --> Gen --> Json
   Gen --> Index --> Leaves --> Docgen
 ```
 
 | Piece | Convention |
 | --- | --- |
 | Generator | [`ts-json-schema-generator`](https://github.com/vega/ts-json-schema-generator) (bundled as an argsbarg dependency) |
-| Discovery | Walk `src/**/types.ts` for `export type outputType` / `inputType` / `configType`; generate from the aliased type in the same file |
-| Artifacts | `src/**/__generated__/` — gitignored; run schemagen after clone or when `types.ts` changes |
+| Discovery | Walk `src/**/*.ts` (exclude `*.test.ts`, `__generated__/`); find `/** @sg */` JSDoc immediately followed by `export interface` or `export type` |
+| Artifacts | One `__generated__/` per source directory; `{TypeName}Schema.json` + `export const {TypeName}Schema` in `index.ts` |
 | Invocation | `just schemagen` — justfile exports `node_modules/.bin` on `PATH` for local `argsbarg` |
 | tsconfig | `"resolveJsonModule": true` |
 | CI | `just check`: `schemagen` → typecheck (no git diff on generated files) |
-| Cleanup | Schemagen removes orphan `__generated__/` dirs and stale JSON when roots or kinds are removed |
-| Docgen | `docgen` depends on `schemagen` so saved `./docs/api.md` and `./docs/cli-schema.json` are fresh |
+| Cleanup | Schemagen removes orphan `__generated__/` dirs and stale JSON when roots are removed |
+| Docgen | `docgen` depends on `schemagen` so saved `./docs/cli.md` and `./docs/cli-schema.json` are fresh |
 
 ### Declaring a schema root
 
-Put schema-facing interfaces and role exports in **`types.ts`** (or `core/types.ts` for shared shapes):
+Mark any exported interface or type with `/** @sg */` on the line immediately above the declaration (no blank line):
 
 ```typescript
 // src/commands/status/types.ts
-/** JSON stdout for `myapp status --json`. */
+/** @sg */
 export interface StatusJsonOutput {
-  workspaces: WorkspaceStatus[];
+  version: string;
 }
+```
+
+Handlers import types from the same module; leaves import schemas from `./__generated__`:
 
-/** Schemagen root for leaf outputSchema. */
-export type outputType = StatusJsonOutput;
+```typescript
+import { StatusJsonOutputSchema } from "./__generated__";
 ```
 
-Handlers and other modules import from the same **`types.ts`** module.
+Shared shapes in one directory share one `__generated__/index.ts`:
 
 ```typescript
-// src/ui/runHeadless/types.ts — shared by many mutating commands
+// src/ui/runHeadless/types.ts
+/** @sg */
 export interface HeadlessOpResult {
   command: string;
   exitCode: number;
   tasks: HeadlessTaskResult[];
 }
-
-export type outputType = HeadlessOpResult;
 ```
 
 ```typescript
-// src/commands/render-invoice/types.ts — custom HTTP/MCP body (pdf-gen)
+// src/commands/render-invoice/types.ts
+/** @sg */
 export interface RenderInvoiceInput {
   format: "pdf" | "html";
   invoice: InvoiceData;
 }
 
+/** @sg */
 export interface RenderInvoiceOutput {
   bytes: number;
 }
-
-export type inputType = RenderInvoiceInput;
-export type outputType = RenderInvoiceOutput;
 ```
 
-| Export | Role |
-| --- | --- |
-| `export type configType = AppConfig` | `program.appConfig.jsonSchema` (one per repo, typically `src/config/types.ts`) |
-| `export type outputType = …` | `leaf.outputSchema` |
-| `export type inputType = …` | `leaf.inputSchema` (only when the tool body is not flat CLI flags) |
+Wire on the leaf or `program.appConfig`:
 
-**Domain helpers** and **role exports** live in `types.ts`. Commands without structured JSON omit role exports. Shared shapes (e.g. `HeadlessOpResult`) are defined once in `types.ts` with a single `outputType`; other commands import `{ outputSchema }` from that module’s `__generated__/index.ts`.
+| Generated export | Typical use |
+| --- | --- |
+| `AppConfigSchema` | `program.appConfig.jsonSchema` (optional — `src/config/types.ts`) |
+| `StatusJsonOutputSchema` | `leaf.outputSchema` |
+| `RenderInvoiceInputSchema` | `leaf.inputSchema` |
 
-For nested MCP/HTTP bodies, add a `kind: Json` option (same name as the `inputType` property) and use `ctx.jsonOpt(...)` or `ctx.readLeafInputs()` — see [cli-program.md](cli-program.md#json-options-and-piped-stdin).
+For nested MCP/HTTP bodies, add a `kind: Json` option (same name as the schema property) and use `ctx.jsonOpt(...)`, `ctx.inputs`, or `ctx.inputsAs<T>()` — see [cli-program.md](cli-program.md#json-options-and-piped-stdin).
 
 When you do **not** set `inputSchema`, argsbarg builds tool input from CLI `options` + `positionals`.
 
 ### Generated artifacts
 
-Schemagen writes under `__generated__/` beside each `types.ts` with role exports:
+Schemagen writes under `__generated__/` beside the `@sg` source files in each directory:
 
-| Kind | Generated file | Exported const (from `__generated__/index.ts`) |
+| Type name | Generated file | Exported const |
 | --- | --- | --- |
-| config | `configSchema.json` | `configSchema` |
-| output | `outputSchema.json` | `outputSchema` |
-| input | `inputSchema.json` | `inputSchema` |
+| `StatusJsonOutput` | `StatusJsonOutputSchema.json` | `StatusJsonOutputSchema` |
+| `RenderInvoiceInput` | `RenderInvoiceInputSchema.json` | `RenderInvoiceInputSchema` |
 
 Wire on the leaf:
 
 ```typescript
-import { outputSchema } from "./__generated__/index.ts";
+import { StatusJsonOutputSchema } from "./__generated__";
 
 export const statusCommand = {
-  outputSchema,
+  outputSchema: StatusJsonOutputSchema,
   // …
 } satisfies CliLeaf;
 ```
 
-Shared mutators:
-
-```typescript
-import { outputSchema } from "../../../ui/runHeadless/__generated__/index.ts";
-```
-
-App config:
+App config (when used):
 
 ```typescript
-import { configSchema } from "./config/__generated__/index.ts";
+import { AppConfigSchema } from "./config/__generated__";
 
-appConfig: { jsonSchema: configSchema, entries: { … } },
+appConfig: { jsonSchema: AppConfigSchema, entries: { … } },
 ```
 
 ## Schema-facing types
 
-**Goal:** generated schemas match what handlers actually print, with descriptions agents can read in `docs api`.
+**Goal:** generated schemas match what handlers actually print, with descriptions agents can read in `docs cli`.
 
-1. **Schema roots** — `export interface` in `types.ts`, with `export type outputType = …` (or `inputType` / `configType`).
+1. **Schema roots** — `/** @sg */` immediately above `export interface` or `export type`, with per-field JSDoc.
 2. **Per property** — `/** … */` on every field that should appear in JSON Schema `properties` (including nested named types).
 3. **Unions / enums** — document the alias; generator emits `enum` / `anyOf` with type-level description.
 4. **Formats** — property JSDoc can include `@format date-time` for ISO timestamps; add a smoke test that the generated property has `format: "date-time"`.
-5. **Do not hand-edit** `__generated__/` — change types/JSDoc in `types.ts`, run `just schemagen`.
+5. **Do not hand-edit** `__generated__/` — change types/JSDoc in source files, run `just schemagen`.
 
 ### Narrowing when runtime ≠ stdout
 
@@ -193,7 +185,8 @@ export interface TranslationReadinessResult {
   evaluatedAt: string;
 }
 
-export type outputType = TranslationReadinessResult;
+/** @sg */
+export interface TranslationReadinessResult {
 ```
 
 Patterns:
@@ -213,15 +206,15 @@ Per consumer repo (optional):
 
 ## Contributor workflow
 
-1. Add or edit schema roots in `src/**/types.ts` with `outputType` / `inputType` / `configType` and per-field JSDoc.
+1. Add or edit `/** @sg */` roots in `src/**/*.ts` with per-field JSDoc.
 2. `just schemagen` — refresh `src/**/__generated__/`.
-3. Import `{ outputSchema }` / `{ inputSchema }` / `{ configSchema }` from the relevant `__generated__/index.ts`.
-4. `just docgen` / `myapp docs api --save` — refresh consumer docs.
+3. Import `{ TypeNameSchema }` from the relevant `./__generated__` barrel.
+4. `just docgen` / `myapp docs cli --save` — refresh consumer docs.
 5. Document which commands use which roots in **your** `docs/architecture.md` (argsbarg does not maintain per-app tables).
 
 Add a bullet under your app’s `**… conventions:**` block in `.cursor/rules/cli-program.mdc` pointing at `node_modules/argsbarg/docs/output-schema.md`.
 
-**Reference implementation:** [`examples/full-example/`](../examples/full-example/) in this repo — `types.ts` roots, `__generated__/`, and `status` leaf with `outputSchema`.
+**Reference implementation:** [`examples/full-example/`](../examples/full-example/) in this repo — `@sg` on command types, `__generated__/`, and `status` leaf with `StatusJsonOutputSchema`.
 
 ## Out of scope
 
@@ -233,5 +226,5 @@ Add a bullet under your app’s `**… conventions:**` block in `.cursor/rules/c
 - [config-schema.md](config-schema.md) — `configType` / `program.appConfig`
 - [cli-program.md](cli-program.md) — structured stdout, headless JSON, `read*Flags`
 - [mcp.md](mcp.md) — `tools/list`, `structuredContent`
-- [bundled-docs.md](bundled-docs.md) — `docs api` / `docs cli-schema` docgen
+- [bundled-docs.md](bundled-docs.md) — `docs cli` / `docs cli-schema` docgen
 - [docs/README.md](README.md) — documentation map