@alpacakit/channels 0.1.0-beta.36 → 0.1.0-beta.39

package/README.md

@@ -1,772 +1,253 @@
 # @alpacakit/channels
 
-Define an entry once, bind it to CLI and MCP, and use the same typed endpoint
-for argument parsing, help, MCP schemas, input decoding, and projection.
+`@alpacakit/channels` defines shared operations and derives registration views
+for application-owned CLI, HTTP, and MCP hosts. It does not own argv parsing,
+network servers, SDK transports, handler registries, response formatting, or
+resource lifetime.
 
-HTTP routing is not currently provided. The supported entry-tree channels are
-CLI and MCP.
+## Public entry points
 
-## The mental model
+- `@alpacakit/channels`: Entry, Parameter, codec, Endpoint, Node/Tree,
+  introspection, input errors, and optional output verification.
+- `@alpacakit/channels/cli`: CLI bindings and `collectCliCommands`.
+- `@alpacakit/channels/http`: HTTP bindings and `collectHttpRoutes`.
+- `@alpacakit/channels/mcp`: MCP bindings and `collectMcpTools`.
 
-You only need four concepts:
+The package has no MCP SDK, Hono, Express, or Commander dependency. Hosts use
+the neutral registration views with the framework version they own.
 
-```text
-Entry    = what the command accepts and what it projects
-Binding  = how one channel supplies that input
-Endpoint = the Entry and its Bindings bundled together
-Tree     = where the Endpoint lives in the command hierarchy
-```
-
-A useful shorthand is:
-
-```text
-What?        -> Entry
-How?         -> Binding
-Where?       -> Tree
-Bundle them  -> Endpoint
-```
-
-Suppose an application exposes this CLI command:
-
-```console
-my-app hint "entry tree" --limit 5
-```
-
-The same operation is exposed to MCP with this JSON input:
-
-```json
-{
-  "query": "entry tree",
-  "limit": 5
-}
-```
+## Quick start: one handler, three channels
 
-The definitions have this structure:
-
-```text
-┌────────────────────────────────────────┐
-│ Entry: HintEntry                       │
-│                                        │
-│ query: required string                 │
-│ limit: optional integer, default 20    │
-│                                        │
-│ project the values into a HintRequest  │
-└───────────────────┬────────────────────┘
-                    │
-                    │ attach channel input mappings
-                    ▼
-┌────────────────────────────────────────┐
-│ Endpoint: HintEndpoint                 │
-│                                        │
-│ ┌────────────────────────────────────┐ │
-│ │ CLI Binding                        │ │
-│ │ query -> positional argument       │ │
-│ │ limit -> --limit / -n              │ │
-│ └────────────────────────────────────┘ │
-│                                        │
-│ ┌────────────────────────────────────┐ │
-│ │ MCP Binding                        │ │
-│ │ query -> JSON property "query"     │ │
-│ │ limit -> JSON property "limit"     │ │
-│ └────────────────────────────────────┘ │
-└───────────────────┬────────────────────┘
-                    │
-                    │ place the endpoint at an address
-                    ▼
-┌────────────────────────────────────────┐
-│ Tree                                   │
-│                                        │
-│ my-app                                 │
-│ └── hint                               │
-│     └── HintEndpoint                   │
-└────────────────────────────────────────┘
-```
-
-The important rule is that value types, validation, requiredness, defaults, and
-projection are declared only on the Entry. A Binding only says how a channel
-supplies a parameter. A Tree only says where an Endpoint lives.
-
-The following sections build that example from top to bottom.
-
-## 1. Define what the command does: Entry
-
-An Entry answers four questions:
-
-```text
-What values does this operation accept?
-                ↓
-How are those values validated?
-                ↓
-Which defaults are applied?
-                ↓
-What application value is produced?
-```
+Define the input once, attach the shared operation as the Endpoint's `handler`,
+and collect the Tree in the application that owns each host. The following
+sections use the same `AppTree`; each host is independent.
 
 ```ts
 import {
-  codecs,
-  defineEntry,
-  defineParameter,
-  optional,
-  required,
+  codecs, defineEntry, defineEntryEndpoint, defineEntryNode,
+  defineEntryTree, defineParameter, optional,
 } from "@alpacakit/channels";
+import { bindCliEntry, collectCliCommands } from "@alpacakit/channels/cli";
+import { bindHttpEntry, collectHttpRoutes } from "@alpacakit/channels/http";
+import { bindMcpEntry, collectMcpTools } from "@alpacakit/channels/mcp";
 
-const HintEntry = defineEntry({
-  name: "hint",
-
+export const GreetEntry = defineEntry({
+  name: "greet",
   parameters: [
     defineParameter({
-      name: "query",
+      name: "name",
       codec: codecs.string(),
-      requirement: required(),
-      description: "Text to search for",
-    }),
-
-    defineParameter({
-      name: "limit",
-      codec: codecs.positiveInteger({ max: 100 }),
-      requirement: optional({ default: 20 }),
-      description: "Maximum number of hints",
+      requirement: optional({ default: "world" }),
+      description: "Person to greet",
     }),
   ],
-
-  project: ({ values }) => ({
-    query: values.query,
-    limit: values.limit,
-  }),
+  project: ({ values }) => ({ name: values.name }),
 });
-```
-
-In plain English, this Entry means:
-
-```text
-hint
-
-Input:
-  query
-    - string
-    - required
-
-  limit
-    - positive integer
-    - at most 100
-    - defaults to 20
-
-Projection:
-  {
-    query: string,
-    limit: number
-  }
-```
-
-There is no CLI or MCP logic here. The Entry describes the operation itself.
-
-Because `limit` has a default, `values.limit` is typed as `number`, not
-`number | undefined`. Only optional parameters without a default remain
-optional in `values`.
 
-## 2. Define how each channel supplies input: Bindings
+export type GreetingContext = {
+  readonly greeting: string;
+};
 
-A CLI Binding maps the Entry parameters to argv syntax:
-
-```ts
-import { bindCliEntry } from "@alpacakit/channels/cli";
+export function greet(
+  input: ReturnType<typeof GreetEntry.project>,
+  context: GreetingContext,
+) {
+  return { message: `${context.greeting}, ${input.name}!` };
+}
 
-const HintCliBinding = bindCliEntry({
-  parameters: [
-    { kind: "positional", parameterName: "query" },
-    { kind: "option", parameterName: "limit", flags: ["--limit", "-n"] },
+export const GreetEndpoint = defineEntryEndpoint(GreetEntry, {
+  handler: greet,
+  channels: [
+    bindHttpEntry({ method: "GET" }),
+    bindMcpEntry({ name: "greet" }),
+    bindCliEntry({
+      parameters: [{ kind: "option", parameterName: "name" }],
+    }),
   ],
 });
-```
-
-A binding row only needs `kind` and `parameterName`. The rest is derived from
-the parameter name and only stated when you want to override it:
-
-- `query` needs no `valueName` (help shows `QUERY`) and no `variadic` (defaults
-  to `false`).
-- `limit` would default to the single flag `--limit`; here `flags` is given
-  only to add the `-n` alias.
 
-The mapping is:
-
-```text
-my-app hint "entry tree" --limit 5
-             └────┬────┘ └───┬───┘
-                  │            │
-                  ▼            ▼
-                query        limit
-```
-
-Do not repeat `query`'s string codec or `limit`'s default in the Binding. Those
-facts already belong to the Entry.
-
-An MCP Binding selects the Entry parameters exposed as tool input:
-
-```ts
-import { bindMcpEntry } from "@alpacakit/channels/mcp";
-
-const HintMcpBinding = bindMcpEntry("query", "limit");
-```
-
-The mapping is:
-
-```text
-{
-  "query": "entry tree",
-  "limit": 5
-}
-     │            │
-     ▼            ▼
-   query        limit
-```
-
-## 3. Bundle the Entry and Bindings: Endpoint
-
-An Endpoint is the public execution identity for the operation:
-
-```ts
-import { defineEntryEndpoint } from "@alpacakit/channels";
-
-const HintEndpoint = defineEntryEndpoint(
-  HintEntry,
-  HintCliBinding,
-  HintMcpBinding,
-);
-```
-
-Its structure is:
-
-```text
-HintEndpoint
-│
-├── operation
-│   └── HintEntry
-│
-├── CLI input mapping
-│   ├── query is positional
-│   └── limit is --limit / -n
-│
-└── MCP input mapping
-    ├── expose query
-    └── expose limit
-```
-
-Keep the object returned by `defineEntryEndpoint()`. CLI result narrowing and
-all MCP runtime APIs use endpoint identity. Do not reconstruct an equivalent
-Endpoint later.
-
-## 4. Give the Endpoint an address: Tree
-
-Place the Endpoint under the `hint` command:
-
-```ts
-import {
-  defineEntryNode,
-  defineEntryTree,
-} from "@alpacakit/channels";
-
-const CommandTree = defineEntryTree(
+export const AppTree = defineEntryTree(
   defineEntryNode({
-    name: "my-app",
-    description: "My application",
-
+    name: "demo",
+    description: "Greeting example",
     children: [
       defineEntryNode({
-        name: "hint",
-        description: "Find implementation hints",
-        endpoints: [HintEndpoint],
+        name: "greet",
+        description: "Greet someone",
+        endpoints: [GreetEndpoint],
       }),
     ],
   }),
 );
 ```
 
-The resulting hierarchy is:
-
-```text
-CommandTree
+`GreetEndpoint.handler === greet`. The first argument to `defineEntryEndpoint`
+is the Entry definition; `handler` is the function the host callback calls.
+Bindings describe how to expose the operation and do not contain another
+handler. Definition and collection never invoke it or create its context.
 
-my-app                    <- root surface name
-│
-└── hint                  <- token that appears in argv
-    │
-    └── HintEndpoint      <- operation executed here
-```
+The second handler argument is your own context: here it contains `greeting`,
+but it can contain a service, authenticated user, or cancellation signal. Create
+it inside the host callback when its dependencies are available. A handler that
+needs no context can accept only the projected input. Handlers may take zero,
+one, or two parameters; rest and three-or-more-parameter signatures are rejected
+by TypeScript.
 
-The root name is the program or surface name. It is not included in the argv
-passed to the router.
+### HTTP with Hono
 
-Independent modules can contribute canonical nodes and merge them without an
-intermediate route model:
+Install Hono in the consuming application. Register each route on an existing
+Hono app, use its request API, and choose its response format yourself:
 
 ```ts
-const children = mergeEntryTreeNodes([
-  ...configCommandNodes,
-  ...integrationCommandNodes,
-]);
-```
-
-Nodes with the same name are merged recursively. Their descriptions and
-channel segment overrides must agree; identical endpoint objects are
-deduplicated by identity.
+import { Hono } from "hono";
 
-An endpoint placed directly on the root is the default command:
-
-```text
-my-app
-├── DefaultEndpoint       <- runs for []
-└── hint
-    └── HintEndpoint      <- runs for ["hint", ...]
-```
-
-## 5. Execute it from CLI
-
-```ts
-import {
-  createCliRouter,
-  isCliResolvedEndpoint,
-} from "@alpacakit/channels/cli";
-
-const router = createCliRouter(CommandTree);
-
-const result = router.resolve([
-  "hint",
-  "entry tree",
-  "--limit",
-  "5",
-]);
-
-if (isCliResolvedEndpoint(result, HintEndpoint)) {
-  console.log(result.projection);
-}
-```
-
-The typed projection is:
-
-```ts
-{
-  query: "entry tree",
-  limit: 5,
-}
-```
-
-At runtime the data flows through these stages:
-
-```text
-CLI argv
-  │
-  │ ["hint", "entry tree", "--limit", "5"]
-  ▼
-CLI Router
-  │
-  │ find HintEndpoint from the Tree
-  ▼
-CLI Binding
-  │
-  │ query = "entry tree"
-  │ limit = "5"
-  ▼
-Shared Decoder
-  │
-  │ validate query as a string
-  │ coerce and validate limit as an integer
-  ▼
-HintEntry.project()
-  │
-  ▼
-{
-  query: "entry tree",
-  limit: 5
-}
-```
-
-A stored Tree may contain many differently typed entries, so its endpoints are
-deliberately type-erased. `isCliResolvedEndpoint()` checks endpoint identity and
-restores the exact projection type for the selected Endpoint.
-
-The same router also exposes a channel-derived help surface:
-
-```ts
-const help = router.help;
-```
-
-For applications with many endpoints, an optional typed registry replaces a
-manual identity-check chain:
-
-```ts
-const executor = createCliExecutor(router, [
-  handleCliEndpoint(HintEndpoint, ({ projection }) => runHint(projection)),
-]);
-```
-
-The registry rejects duplicate, missing, and out-of-router endpoints when it is
-created. Handlers, output policy, and process exit behavior remain outside the
-Entry definition.
-
-## 6. Execute the same Endpoint from MCP
-
-Compile the Endpoint once, then reuse the handle for both registration and
-per-invocation decoding:
-
-```ts
-import {
-  createMcpEndpoint,
-  isMcpResolved,
-} from "@alpacakit/channels/mcp";
-
-const HintMcpEndpoint = createMcpEndpoint(HintEndpoint);
-```
-
-`createMcpEndpoint()` validates the MCP binding once and returns a handle:
-
-```text
-HintMcpEndpoint
-│
-├── inputSchema   <- raw Zod object shape for tool registration
-│
-└── parse(raw)    <- decode + project one invocation
-```
-
-`inputSchema` is a raw Zod object shape suitable for MCP tool registration. It
-contains descriptions, validation, and requiredness derived from `HintEntry`.
-
-Decode and project an MCP invocation through the same handle:
-
-```ts
-const result = HintMcpEndpoint.parse({
-  query: "entry tree",
-  limit: 5,
-});
-
-if (isMcpResolved(result)) {
-  console.log(result.projection);
-}
-```
-
-Create the handle once (typically at startup) and reuse it for every request.
-The binding is compiled a single time, so `parse()` does no per-invocation
-recompilation, and an invalid binding throws `EntryTreeDefinitionError`
-eagerly — exactly like `createCliRouter()`.
-
-The MCP runtime path is:
-
-```text
-MCP JSON
-  │
-  │ { query: "entry tree", limit: 5 }
-  ▼
-HintEndpoint
-  │
-  ▼
-MCP Binding
-  │
-  │ select query and limit
-  ▼
-Shared Decoder
-  │
-  │ validate both values
-  ▼
-HintEntry.project()
-  │
-  ▼
-{
-  query: "entry tree",
-  limit: 5
-}
-```
-
-CLI and MCP have different inputs, but they converge on the same decoder,
-defaults, and projection:
-
-```text
-CLI argv ──> CLI Binding ──┐
-                           │
-                           ▼
-                     HintEndpoint
-                           │
-                           ▼
-                     Shared Decoder
-                           │
-                           ▼
-                   HintEntry.project()
-                           │
-                           ▼
-                    same projection
-                           ▲
-                           │
-MCP JSON ──> MCP Binding ──┘
-```
-
-If `limit` is omitted from either channel, both produce the Entry default:
-
-```ts
-{
-  query: "entry tree",
-  limit: 20,
-}
-```
-
-## Where each decision belongs
-
-When adding a command, ask these questions in order:
-
-| Question | Definition |
-| --- | --- |
-| What values does the operation need? | Entry parameters |
-| How are they validated and defaulted? | Entry codecs and requirements |
-| What application value should be produced? | Entry `project()` |
-| How does CLI supply each value? | CLI Binding |
-| Which values does MCP expose? | MCP Binding |
-| What object ties the operation and channels together? | Endpoint |
-| Under which command path does it live? | Tree |
-
-Do not put CLI flags, MCP property selection, or command-tree placement on the
-Entry. Do not repeat codecs, requiredness, or defaults in Bindings.
-
-## Suggested application file layout
-
-For a larger application, separating these responsibilities keeps the model
-easy to navigate:
-
-```text
-src/
-├── hint-entry.ts
-│   └── HintEntry
-│       parameters, codecs, defaults, projection
-│
-├── hint-endpoint.ts
-│   └── HintEndpoint
-│       CLI and MCP Bindings
-│
-├── command-tree.ts
-│   └── CommandTree
-│       command hierarchy
-│
-├── cli.ts
-│   └── createCliRouter(CommandTree)
-│
-└── mcp.ts
-    └── createMcpEndpoint(HintEndpoint)
-```
-
-## Package entries
-
-The neutral model and channel adapters are intentionally separate imports:
-
-| Import | Purpose |
-| --- | --- |
-| `@alpacakit/channels` | Parameters, codecs, entries, output contracts, and entry-tree builders |
-| `@alpacakit/channels/cli` | CLI bindings/coercion, router, typed executor, help traversal, and text renderers |
-| `@alpacakit/channels/mcp` | MCP binding, the compiled endpoint handle, output schema projection, and the resolved-result guard |
-
-`zod` is a peer dependency. In this workspace, depend on the package with
-`workspace:*` and use the workspace Zod version.
-
-## Parameter and codec reference
-
-Built-in codecs are:
-
-- `codecs.string()`
-- `codecs.stringList()`
-- `codecs.boolean()`
-- `codecs.positiveInteger({ max })`
-- `codecs.stringEnum(values)`
-- `codecs.stringEnumList(values)`
-
-Use `required()` for required input, `optional()` for an optional value without
-a default, and `optional({ default })` for a materialized default.
-
-Defaults belong to the Entry, not a channel. They are applied even when an
-optional parameter is not exposed by the selected channel. A required parameter
-must be reachable through every channel binding on that Endpoint.
-
-`codecs.define({ schema, shape })` is available for advanced codecs. Its shape
-is the CLI representation contract and must match the schema's value type.
-Arrays are limited to supported scalar element shapes.
-
-## CLI reference
-
-Use `overrideCliSegment()` when the CLI spelling differs from the logical node
-name:
-
-```ts
-import { overrideCliSegment } from "@alpacakit/channels/cli";
-
-defineEntryNode({
-  name: "hint",
-  description: "Find implementation hints",
-  segments: [overrideCliSegment({ token: "h", aliases: ["hi"] })],
-  endpoints: [HintEndpoint],
+const app = new Hono();
+collectHttpRoutes(AppTree).forEach((route) => {
+  app.on(route.method, route.path, async (context) => {
+    const input = route.input.parseQuery(context.req.queries());
+    const result = await route.handler(input, { greeting: "Hello" });
+    return context.json(result);
+  });
 });
 ```
 
-CLI binding and routing rules:
-
-- An option with no `flags` defaults to a single `--<kebab-case parameter
-  name>` long flag. Provide `flags` only to add aliases or a short flag.
-- A value-taking option's `valueName` defaults to the upper snake-cased
-  parameter name. Boolean flags reject `valueName` because they take no value.
-- A positional's `valueName` defaults to the upper snake-cased parameter name,
-  and `variadic` defaults to `false`. State either only to override it.
-- Options use reachable `-x` or `--long` flags. Requiredness comes from the
-  Entry parameter, not the Binding.
-- A defaulted boolean option is a flag by default. `negated: true` adds its
-  generated `--no-...` long flags.
-- A boolean without a default accepts an explicit value unless `booleanMode`
-  selects another supported behavior.
-- Array options may be repeated. `repeatMode: "comma_or_repeat"` also accepts
-  comma-separated values.
-- A variadic positional requires an array codec and must be the final
-  positional.
-- An executable node cannot have both positional arguments and child commands.
-- `--` forces all remaining tokens to be parsed as positionals.
-- A matching child command wins over an executable parent.
-- `coercion: "json"` parses strict JSON before Entry validation.
-  `coercion: "json_or_string"` preserves malformed JSON as text. Final value
-  validation always belongs to the Entry codec.
-
-`createCliRouter()` compiles and validates the complete CLI surface. Invalid
-definitions throw `EntryTreeDefinitionError` at construction time.
-
-The router's `help` property contains the compiled hierarchy, aliases,
-render-ready option groups, positionals, requiredness, defaults, repeat modes,
-and generated negative flags. Authored option-section names are resolved during
-projection, so renderers consume `optionGroups` without performing a join.
-`findCliHelpSurface()`, `listCliHelpSurfaces()`, `renderCliHelp()`, and
-`formatCliRouterError()` provide standard lookup, traversal, one-surface text
-rendering, and diagnostics without writing output or choosing an exit code.
-`renderCliHelp()` implements `CliHelpRender`; its context carries the full
-selected `programName`, root `executableName`, path, and description preference.
-The renderer path uses canonical CLI segment tokens; a directly invoked alias
-may still be preserved in `programName` for user-facing usage text.
-`--help`, complete-reference framing, and `--version` remain application policy.
-
-The router returns a discriminated union:
-
-- `resolved`
-- `unknown_command`
-- `incomplete_command`
-- `invalid_input`
-- `internal_error`
-
-`path` is preserved for diagnostics. Consumers may use the standard formatter
-or supply their own wording. Process exit codes remain consumer policy.
-
-## MCP reference
-
-`createMcpEndpoint()` compiles the Endpoint once and returns the handle used for
-both schema generation and runtime parsing. Do not keep a second runtime copy of
-the MCP Binding.
-
-```ts
-declare const toolArguments: Record<string, unknown>;
-
-const mcpEndpoint = createMcpEndpoint(HintEndpoint);
-const inputShape = mcpEndpoint.inputSchema;
-const result = mcpEndpoint.parse(toolArguments);
-```
-
-`inputSchema` is a raw Zod object shape. It includes only MCP-bound parameters
-and projects their schemas, descriptions, and requiredness.
-
-`parse()` applies Entry defaults to all parameters, validates bound input, and
-runs the Entry projection. It returns:
-
-- `resolved` with the typed projection
-- `invalid_input` for missing input, codec failures, or an `EntryInputError`
-  deliberately thrown by `project()`
-- `internal_error` with the original error for an unexpected `project()` throw
-
-`isMcpResolved(result)` narrows a parse result to its `resolved` variant, the
-MCP counterpart of `isCliResolvedEndpoint()`.
-
-An invalid Endpoint binding throws `EntryTreeDefinitionError` from
-`createMcpEndpoint()` itself, so definition errors surface at construction rather
-than on the first invocation.
-
-MCP tool naming and registration stay with the consumer. Hierarchical MCP tool
-names are not currently derived from the Tree.
+`GET /greet?name=Ada` produces `{ "message": "Hello, Ada!" }`.
+For JSON bodies, pass the object from your framework to `route.input.parse`
+instead. Authentication, middleware, server startup, and response handling stay
+in the application; the same registration views also work with Express or
+another router.
 
-## Output contracts
+### MCP with the MCP SDK
 
-An output contract is optional. Add one when the same successful result schema
-must drive runtime verification and MCP structured output:
+Install the MCP SDK in the consuming application and use your own server and
+transport:
 
 ```ts
-import {
-  createOutputContract,
-  defineEntry,
-  defineEntryEndpoint,
-  verifyEntryOutput,
-} from "@alpacakit/channels";
-import {
-  bindMcpEntry,
-  createMcpOutputSchema,
-} from "@alpacakit/channels/mcp";
-import { z } from "zod";
-
-const HintOutputSchema = z
-  .object({
-    hints: z.array(z.string()).readonly(),
-  })
-  .strict()
-  .readonly();
-
-const EntryWithOutput = defineEntry({
-  name: "hint",
-  parameters: [],
-  project: () => null,
-  output: createOutputContract(HintOutputSchema),
-});
-
-const EndpointWithOutput = defineEntryEndpoint(
-  EntryWithOutput,
-  bindMcpEntry(),
-);
-
-const outputSchema = createMcpOutputSchema(EndpointWithOutput);
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 
-const verified = verifyEntryOutput(EntryWithOutput, {
-  hints: ["A validated result"],
+const server = new McpServer({ name: "demo", version: "1.0.0" });
+collectMcpTools(AppTree).forEach((tool) => {
+  server.registerTool(
+    tool.name,
+    { inputSchema: tool.input.schema },
+    async (values) => {
+      // The SDK has already validated and transformed the public values.
+      const input = tool.input.project(values);
+      const result = await tool.handler(input, { greeting: "Hello" });
+      return { content: [{ type: "text", text: result.message }] };
+    },
+  );
 });
+// Connect `server` to the transport chosen by your application.
+```
+
+Calling tool `greet` with `{ "name": "Ada" }` returns the greeting as MCP text.
+Use `project`, not `parse`, after SDK validation so defaults and transforms are
+not applied twice. The SDK's callback also lets the application use MCP request
+metadata or cancellation when constructing the shared handler's context.
+
+### CLI with your own parser
+
+The collected view is a tree of nodes, so a CLI host walks it once to learn
+which paths are executable and what each command accepts. Argv parsing stays in
+the application. Use the input plan to convert and validate supplied values,
+then call the shared handler in your host callback:
+
+```ts
+const view = collectCliCommands(AppTree);
+const commands = new Map<
+  string,
+  (supplied: Record<string, unknown>) => Promise<string>
+>();
+
+function register(node: typeof view.root): void {
+  node.commands.forEach((spec) => {
+    // `spec.parameters` describes the flags and positionals your parser must
+    // accept for this command.
+    commands.set(spec.path.join(" "), async (supplied) => {
+      const input = spec.input.parseOptions(supplied);
+      // Build the handler context here, where its dependencies are available.
+      const result = await spec.handler(input, { greeting: "Hello" });
+      return result.message;
+    });
+  });
+  node.children.forEach(register);
+}
 
-void outputSchema;
-void verified;
-```
-
-`createMcpOutputSchema()` requires an object output contract. Invalid output
-passed to `verifyEntryOutput()` throws `EntryOutputContractError`.
-
-## Error boundaries
-
-- `EntryTreeDefinitionError` means the Tree or a channel Binding is invalid.
-  Treat it as a startup or programmer error.
-- `EntryInputError` may be thrown inside `project()` for an expected semantic
-  input rejection. It becomes `invalid_input`. Pass
-  `{ parameterName: "name" }` to associate all issues with one Entry parameter;
-  an unknown parameter name is an `internal_error` programmer failure.
-- Codec and required-input failures become `invalid_input`.
-- Any other projection exception becomes `internal_error` and retains the
-  original error. It is never reported as caller input failure.
-- `EntryOutputContractError` means a handler returned a value outside its
-  declared success contract.
-
-## Scope
-
-The package currently provides the neutral entry tree, CLI router, optional CLI
-executor and text renderers, and MCP endpoint adapter. It does not provide an
-HTTP router, process exit policy, automatic `--help`/`--version` handling, MCP
-tool registration, authentication, or a network listener.
-
-Every command surface uses `defineEntryEndpoint()` with `bindCliEntry()` and
-`bindMcpEntry()`. There is no separate legacy option-descriptor API.
-
-## Zod peer and source linking
-
-Packed consumers are type-checked against the declared `zod: ^4.3.6` peer. A
-packed channels build was verified with both Zod 4.3.6 and 4.4.3. Source-linking
-the package is different: if channels resolves its development Zod 4.3.6 while
-the consumer resolves 4.4.3, TypeScript can expand the two distinct Zod type
-graphs until it reports excessive depth or exhausts memory. When linking source,
-use exactly one shared Zod installation/version, or consume a packed tarball.
+register(view.root);
+
+// Your parser selects the path and supplies only the options the user typed.
+const greetCommand = commands.get("greet");
+if (!greetCommand) throw new Error("Missing greet command");
+console.log(await greetCommand({ name: "Ada" })); // Hello, Ada!
+```
+
+This demonstrates the handoff after parsing `demo greet --name Ada`; it does
+not parse argv. Supplying no `name` key applies the authored default `world`.
+Pass `parseOptions` only the canonical parameter names the user explicitly
+supplied — defaults inserted by your parser would override the authored ones.
+The walk visits commands in nested groups and executable parents with children;
+the tree also retains group-only nodes for your host's help and registration.
+
+`collectCliCommands` accepts a Node or a Tree. A collection requires a context
+satisfying all its handlers. Collect modules with incompatible contexts
+separately, and create each module's context inside its invocation callback.
+The host owns output formatting and resource cleanup.
+
+The complete [greeting example](./examples/greeting.ts) turns the same view into
+a Commander program, including flag registration, `getOptionValueSource`
+filtering so only user-supplied options reach `parseOptions`, and process error
+handling. Its adapter handles value-taking options only, which is all the
+greeting tree uses; register boolean flags and positionals from
+`spec.parameters` with your parser's corresponding APIs. That file is shipped
+with the package and is compiled and invoked from its packed artifact. The
+[book-search example](./examples/book-search.ts) also demonstrates a typed
+output contract and domain outcome union.
+
+## Input and failure handling
+
+| Host input | Method | Work performed |
+| --- | --- | --- |
+| CLI values explicitly supplied by the user | `input.parseOptions(raw)` | String coercion, validation/defaults, then Entry projection |
+| HTTP query strings or string arrays | `input.parseQuery(raw)` | Query coercion, validation/defaults, then Entry projection |
+| Unvalidated JSON object | `input.parse(raw)` | Validation/defaults, then Entry projection |
+| Values already validated by `input.schema` | `input.project(values)` | Entry projection and hidden defaults, without revalidating public values |
+
+The host decides how to report invalid input and operation failures. Catch
+`EntryInputError` around the input-processing call when mapping it to HTTP 400,
+a CLI usage error, or an MCP error result. Keep the handler call outside that
+catch: an exception from the operation or its dependencies is a separate
+failure, even if it has the same error class. Response envelopes, logging,
+resource cleanup, and process exit remain application responsibilities.
+
+`parseOptions` must receive only canonical parameter names explicitly supplied
+by the user. Do not pass defaults inserted by the external parser.
+`parseQuery` accepts a scalar string or one-element string array, rejects
+duplicate scalar values, and treats a scalar value for an array parameter as a
+one-element array. `input.parse` is the JSON-value path and performs no CLI or
+query string coercion.
+
+`input.schema` performs public parameter validation, authored raw defaults, and
+codec transforms. It never performs Entry projection. After an SDK validates
+with that schema, call `input.project` once; otherwise call `input.parse` once.
+Authored defaults are represented by the public schema (including input-mode
+JSON Schema conversion) before codec transforms, and are copied for each
+invocation, including object and array defaults. Non-object JSON containers are
+rejected as `EntryInputError` by every parse path.
+
+## Tree placement
+
+A Tree root is a container: its CLI path is `[]`, its HTTP path is `/`, and its
+CLI token is the program display name. Collecting a Node directly creates a
+virtual CLI root and includes the Node's own segment (`[token]` and
+`/segment`). Empty and group-only nodes remain visible in the CLI view.
+
+Use `mergeEntryTreeNodes` to explicitly merge compatible same-name nodes.
+Collectors deduplicate the same Endpoint at the same placement, retain the same
+Endpoint at different CLI/HTTP paths, and emit one MCP tool per Endpoint.
+Cycles, conflicting paths, invalid segments, duplicate channel bindings,
+unreachable required parameters, and HTTP/MCP/CLI ownership collisions throw
+`EntryTreeDefinitionError` before a host registers anything.
+
+See the shipped [examples guide](./examples/README.md) for the two examples and
+the division of responsibility between channels and the host.