padrone 1.4.0 → 1.6.0

package/CHANGELOG.md

@@ -1,5 +1,120 @@
 # padrone
 
+## 1.6.0
+
+### Minor Changes
+
+- [`75066f9`](https://github.com/KurtGokhan/padrone/commit/75066f9e12c33a1f64c502e248fce4d4e455d0da) Thanks [@KurtGokhan](https://github.com/KurtGokhan)! - Improve "Did you mean?" suggestions for typos in commands and options. Return multiple matches (up to 3), add prefix/substring matching for inputs longer than 3 characters, and include `--` prefix in option suggestions. Suggestions are now included in soft-mode validation errors too.
+
+- [`93ab85c`](https://github.com/KurtGokhan/padrone/commit/93ab85c88441e9062b2402f7d97f3d337293f2e7) Thanks [@KurtGokhan](https://github.com/KurtGokhan)! - Add typed context support. Define context with `.context<T>()` or `.context(transform)`, provide it via `cli()`, `eval()`, `run()`, and access it in action handlers as `ctx.context` and in all plugin phase contexts. Subcommands inherit context from parents. `.mount()` accepts an optional `{ context }` transform. New `InferContext` type helper.
+
+- [`3b7fed0`](https://github.com/KurtGokhan/padrone/commit/3b7fed06d15cc2acad04df7d919ce0f6c9b66207) Thanks [@KurtGokhan](https://github.com/KurtGokhan)! - Add typed context injection for interceptors. Interceptors can declare provided context via `.provides<T>()` and required context via `.requires<T>()` on `defineInterceptor()`. Action handlers see the full merged context type. `.intercept()` rejects interceptors whose required context is not satisfied at compile time.
+
+- [`067b9f7`](https://github.com/KurtGokhan/padrone/commit/067b9f7d695a838f0c39204c563029f8a2527675) Thanks [@KurtGokhan](https://github.com/KurtGokhan)! - Add extension system with `.extend()` for build-time composition. Rename plugins to interceptors (`.use()` → `.intercept()`, `PadronePlugin` → `PadroneInterceptor`). Move built-in commands to composable extensions. Default builtins (help, version, repl, color, config, interactive) are applied automatically via `createPadrone()`. Advanced features (completion, man, mcp, serve, update-check) are opt-in extensions. Individual builtins can be disabled via `createPadrone('name', { builtins: { help: false } })`.
+
+- [`4e7f88b`](https://github.com/KurtGokhan/padrone/commit/4e7f88bdc68b7c97f36e3546142b6ebf5f87f76e) Thanks [@KurtGokhan](https://github.com/KurtGokhan)! - Respect terminal width in help output. Default and choices metadata now appear inline with descriptions when space allows, and long descriptions wrap aligned to the description column.
+
+- [`aa0b568`](https://github.com/KurtGokhan/padrone/commit/aa0b568f35c2fcb97a78abf077561a914606de6f) Thanks [@KurtGokhan](https://github.com/KurtGokhan)! - Add support for Ink apps. The `ink` interceptor renders an Ink app as part of a command's execution, and waits for it to unmount before proceeding.
+
+- [`91fd814`](https://github.com/KurtGokhan/padrone/commit/91fd8146c0fff0eb8c4e5f46191d1a6bf8203ecf) Thanks [@KurtGokhan](https://github.com/KurtGokhan)! - Add `padroneLogger()` and `padroneTiming()` extensions for structured logging and command execution timing.
+
+- [`99c8cfa`](https://github.com/KurtGokhan/padrone/commit/99c8cfa298194d9632b9c784858c1695e7782acf) Thanks [@KurtGokhan](https://github.com/KurtGokhan)! - Add `program.info` for read-only access to program metadata (name, version, description, commands, etc.). Add XDG config directory support via `xdg` option on `padroneConfig()`.
+
+- [`88c45af`](https://github.com/KurtGokhan/padrone/commit/88c45afeef123d4a3e5d5e4d359e080ddf60a154) Thanks [@KurtGokhan](https://github.com/KurtGokhan)! - Add elapsed time (`time: true`) and ETA (`eta: true`) to progress indicators. ETA is calculated from numeric progress updates and counts down between updates. Move progress messages into a `message` field (string or `{ validation, progress, success, error }` object) with runtime-level defaults via context.
+
+- [`8691694`](https://github.com/KurtGokhan/padrone/commit/86916947b189109e6647684d30dc06992a3909b5) Thanks [@KurtGokhan](https://github.com/KurtGokhan)! - Improve runtime agnosticism. Add `terminal` and `exit` fields to `PadroneRuntime`. Replace `Buffer` usage with `Uint8Array`/`TextEncoder`. Route scattered `process.*` reads through runtime abstraction. Replace all `require()` calls with dynamic `import()`. Use `runtime.onSignal` in serve/MCP instead of direct `process.on`.
+
+- [`4343f78`](https://github.com/KurtGokhan/padrone/commit/4343f7857b6685c8e1774b4d933846cd786fe828) Thanks [@KurtGokhan](https://github.com/KurtGokhan)! - Add signal handling support for graceful shutdown. Actions and plugins receive an `AbortSignal` via `ctx.signal` that aborts on SIGINT/SIGTERM/SIGHUP. Command results include `signal` and `exitCode` fields when interrupted. Double Ctrl+C within 2 seconds force-quits. Export new `SignalError` class and `PadroneSignal` type.
+
+- [`7464026`](https://github.com/KurtGokhan/padrone/commit/746402615e11262a0ff7257f41a4840c3a54143e) Thanks [@KurtGokhan](https://github.com/KurtGokhan)! - Reject unknown options for commands without `.arguments()`. Previously, commands without a schema accepted all options silently. Now they infer an empty object and error on unknown options.
+
+- [`be62401`](https://github.com/KurtGokhan/padrone/commit/be624016ee6e4852ab043b15b4d525431319a168) Thanks [@KurtGokhan](https://github.com/KurtGokhan)! - Add experimental `padroneTracing()` extension for OpenTelemetry tracing. Logger automatically bridges log calls to span events when tracing is active.
+
+### Patch Changes
+
+- [`dbac7ec`](https://github.com/KurtGokhan/padrone/commit/dbac7ec56a9f0c320550eef2f6b188a3741d1d4e) Thanks [@KurtGokhan](https://github.com/KurtGokhan)! - Add `runtime` to interceptor contexts. Interceptors can now access and override the runtime via `ctx.runtime` instead of calling `getCommandRuntime()`. Support `next()` overrides for passing modified context to downstream interceptors.
+
+- [`0dfae77`](https://github.com/KurtGokhan/padrone/commit/0dfae774d264d4cab092b90bb779dd3da46abaef) Thanks [@KurtGokhan](https://github.com/KurtGokhan)! - Collect repeated non-array options into an array for the validator. Enables schemas like `z.union([z.string(), z.array(z.string())])` to receive all values when an option is passed multiple times.
+
+## 1.5.0
+
+### Minor Changes
+
+- [`ef5e829`](https://github.com/KurtGokhan/padrone/commit/ef5e82931c06bbce70b6cdf3e34c179a48d04c66) Thanks [@KurtGokhan](https://github.com/KurtGokhan)! - Add `asyncStream` for streaming stdin as `AsyncIterable`. New `padrone/zod` entrypoint exports `zodAsyncStream` and `jsonCodec` for typed streams with per-item validation. Extract shared `JSON_SCHEMA_OPTS` constant across all `jsonSchema.input()` calls.
+
+- [`bbb05d9`](https://github.com/KurtGokhan/padrone/commit/bbb05d9dcf4b360d7f5ae85bdd4fa6e45b68b64d) Thanks [@KurtGokhan](https://github.com/KurtGokhan)! - Add `examples` configuration to options and commands for command-line usage examples.
+
+- [`7ff2738`](https://github.com/KurtGokhan/padrone/commit/7ff2738c146c419f4f03315ec8182af5be31d1b0) Thanks [@KurtGokhan](https://github.com/KurtGokhan)! - Collapse global commands in help output to a single summary line by default. Add `--all` flag to show full global commands section. Bare `--detail` flag now defaults to `full`. Rename "Built-in" section to "Global".
+
+- [`369ebba`](https://github.com/KurtGokhan/padrone/commit/369ebbab4dc14c1d8acfd2af01a9322f5d964e23) Thanks [@KurtGokhan](https://github.com/KurtGokhan)! - Add `group` configuration to options and commands for organized help output.
+
+  Options can be grouped via `fields: { myField: { group: 'Group Name' } }` in argument metadata. Commands can be grouped via `configure({ group: 'Group Name' })`. Grouped items are rendered under labeled `${group}:` sections in help output, while ungrouped items remain under the default `Options:` / `Commands:` headers.
+
+- [`3d7b282`](https://github.com/KurtGokhan/padrone/commit/3d7b28202890925e05357c9796218349b4a8410e) Thanks [@KurtGokhan](https://github.com/KurtGokhan)! - Add per-field validation during interactive prompts.
+
+  When a user provides an invalid value for an interactive field, the prompt now immediately validates it against the schema and re-prompts with a warning message instead of deferring all errors until after all prompts complete. This applies to both required and optional interactive fields.
+
+- [`1843f1f`](https://github.com/KurtGokhan/padrone/commit/1843f1f3a00714d11570c245361ab73c4049aa91) Thanks [@KurtGokhan](https://github.com/KurtGokhan)! - Lazily initialize commands defined with callbacks. Builder functions passed to `.command()` are now deferred until the command is routed to, avoiding upfront construction of unused commands. Features that need the full command tree (help, MCP, serve, docs, completion, REPL) resolve all commands eagerly. Added `getCommand()` and `isPadroneProgram()` helpers to replace direct `commandSymbol` usage.
+
+- [`45ba002`](https://github.com/KurtGokhan/padrone/commit/45ba002db474e34808b64b15ebce59b289f9115b) Thanks [@KurtGokhan](https://github.com/KurtGokhan)! - Add built-in Model Context Protocol (MCP) server. Expose CLI commands as AI tools via `mcp` command or `.mcp()` method. Supports Streamable HTTP and stdio transports per the 2025-11-25 MCP spec.
+
+- [`ab53491`](https://github.com/KurtGokhan/padrone/commit/ab534915e3bcb5cd1c3f563f4fde740d1b91fa50) Thanks [@KurtGokhan](https://github.com/KurtGokhan)! - **BREAKING:** `eval()`, `cli()`, and `run()` no longer throw errors. Instead, they return a discriminated union with an `error` field:
+
+  - Success: `{ command, args, argsResult, result, drain() }`
+  - Error: `{ error, command?, args?, argsResult?, drain() }`
+
+  Added `drain()` method to all command results. It flattens the result into a single `Promise<{ value } | { error }>` that never throws — resolving Promises, collecting iterables into arrays, and catching errors:
+
+  ```ts
+  const { value, error } = await program.cli().drain();
+  ```
+
+  New exported types: `PadroneDrainResult<T>`, `Drained<T>`.
+
+- [`dffc5cd`](https://github.com/KurtGokhan/padrone/commit/dffc5cd36250f94cc82edae850aa34ae9916d43a) Thanks [@KurtGokhan](https://github.com/KurtGokhan)! - Add progress indicator system for commands with auto-managed spinners and manual control.
+
+  **Auto-managed progress** via `.progress()` builder method:
+
+  - `true` or `string` for simple messages, or a full config object with per-state messages
+  - Starts before validation, auto-succeeds/fails after execution
+  - Validation-phase message transitions to execution-phase message
+  - `spinner` option: preset name (`dots`, `line`, `arc`, `bounce`), custom `{ frames, interval }`, or `false` to disable animation
+  - `success`/`error` fields accept static strings, `null` to suppress, callbacks `(result) => string | null`, or `{ message, indicator }` objects for per-call icon customization
+
+  **Manual progress** via `ctx.progress` in action handlers:
+
+  - Works even without `.progress()` config — lazily creates a real indicator on first use
+  - Auto-stopped when execution finishes (no leaked spinners)
+  - No-op when the runtime has no progress factory
+
+  **Built-in terminal spinner** (`createTerminalSpinner`):
+
+  - ANSI-based spinner with pause/resume for clean output interleaving
+  - Customizable success/error indicator icons via `PadroneProgressOptions`
+  - Empty string indicators hide the icon prefix entirely
+  - Graceful fallback in non-TTY/CI environments
+
+  **New types**: `PadroneProgressIndicator`, `PadroneProgressConfig`, `PadroneProgressMessage`, `PadroneProgressOptions`, `PadroneSpinnerConfig`, `PadroneSpinnerPreset`
+
+- [`6851b48`](https://github.com/KurtGokhan/padrone/commit/6851b4878ab0fc8d48f40e93c2f8924236a40165) Thanks [@KurtGokhan](https://github.com/KurtGokhan)! - Add REST server (`program.serve()`) and `mutation` command config.
+
+  - New `serve()` program method: exposes commands as HTTP endpoints with automatic OpenAPI docs (Scalar).
+  - New `serve` built-in CLI command: `myapp serve --port 3000`.
+  - Built-in endpoints: `/_health`, `/_help`, `/_schema`, `/_docs` (Scalar), `/_openapi`.
+  - New `mutation` option in `.configure()`: mutation commands are POST-only in serve, set `destructiveHint` in MCP, and default `needsApproval` to true in `tool()`.
+  - MCP: rename `endpoint` to `basePath` for consistency with serve.
+  - Shared utilities extracted from MCP (`collectEndpoints`, `buildInputSchema`, `serializeArgsToFlags`).
+
+### Patch Changes
+
+- [`7e8f14d`](https://github.com/KurtGokhan/padrone/commit/7e8f14ddb628620f94a7c9f2e88f9417577f2b04) Thanks [@KurtGokhan](https://github.com/KurtGokhan)! - Expand boolean auto-coercion to accept `yes`/`no`/`on`/`off` (case-insensitive).
+
+- [`a1c7072`](https://github.com/KurtGokhan/padrone/commit/a1c70724829f8cd4fb1632098f352498c87cbf2e) Thanks [@KurtGokhan](https://github.com/KurtGokhan)! - Improve help output formatting: options now display flags first, then names, type, and description in aligned columns. Metadata (deprecated, default, choices, examples, env, config) is shown on separate indented lines.
+
+- [`befc82e`](https://github.com/KurtGokhan/padrone/commit/befc82e39b4a1663c3ace74305dd48f9aded1a09) Thanks [@KurtGokhan](https://github.com/KurtGokhan)! - Add `.catch()` and `.finally()` methods to thenable sync results from `eval()`, `parse()`, and `cli()`
+
+- [`81f3bbc`](https://github.com/KurtGokhan/padrone/commit/81f3bbce54940953ff32d76c620eabd6cec7322f) Thanks [@KurtGokhan](https://github.com/KurtGokhan)! - Use `node:child_process` in wrap handler instead of `Bun.spawn` for Node.js compatibility.
+
 ## 1.4.0
 
 ### Minor Changes

package/README.md

@@ -2,10 +2,8 @@
   <img src="media/padrone.svg" alt="Padrone Logo" width="200" height="200" />
 </p>
 
-<!-- <h1 align="center">Padrone</h1> -->
-
 <p align="center">
-  <strong>Create type-safe, interactive CLI apps with Zod schemas</strong>
+  <strong>Type-safe CLI framework powered by Zod schemas</strong>
 </p>
 
 <p align="center">
@@ -16,33 +14,26 @@
 
 ---
 
-## ✨ Features
+Define your CLI with Zod schemas. Get type safety, validation, help generation, interactive prompts, shell completions, AI tool integration, and more — all from a single source of truth.
 
-- 🔒 **Type-safe** - Full TypeScript support with Zod schema validation
-- 🎯 **Fluent API** - Chain commands and arguments with a clean builder pattern
-- 🤖 **AI-Ready** - First-class support for Vercel AI SDK tool integration
-- 📚 **Auto Help** - Automatic help generation from your schema definitions
-- 🧩 **Nested Commands** - Support for deeply nested subcommands
-- 🔄 **Standard Schema** - Built on [Standard Schema](https://github.com/standard-schema/standard-schema) for maximum compatibility
-- 🚀 **Zero Config** - Works out of the box with sensible defaults
+Built on [Standard Schema](https://github.com/standard-schema/standard-schema), so it also works with Valibot, ArkType, and others.
 
-## 📦 Installation
+## Install
 
 ```bash
-# Using npm
 npm install padrone zod
+```
 
-# Using bun
-bun add padrone zod
+## Scaffold a New Project
 
-# Using pnpm
-pnpm add padrone zod
+The fastest way to get started is with `padrone init`:
 
-# Using yarn
-yarn add padrone zod
+```bash
+npx padrone init my-cli
+cd my-cli && bun i && bun dev
 ```
 
-## 🚀 Quick Start
+## Quick Start
 
 ```typescript
 import { createPadrone } from 'padrone';
@@ -54,320 +45,154 @@ const program = createPadrone('myapp')
       .arguments(
         z.object({
           names: z.array(z.string()).describe('Names to greet'),
-          prefix: z
-            .string()
-            .optional()
-            .describe('Prefix to use in greeting')
-            .meta({ alias: 'p' }),
+          prefix: z.string().optional().describe('Prefix').meta({ flags: 'p' }),
         }),
         { positional: ['...names'] },
       )
       .action((args) => {
-        const prefix = args?.prefix ? `${args.prefix} ` : '';
-        args.names.forEach((name) => {
-          console.log(`Hello, ${prefix}${name}!`);
-        });
+        for (const name of args.names) {
+          console.log(`Hello, ${args.prefix ?? ''} ${name}!`);
+        }
       }),
   );
 
-// Run from CLI arguments
 program.cli();
 ```
 
-### Running your CLI
-
 ```bash
-# Run with arguments
-myapp greet John Jane --prefix Mr.
-
-# Or with alias
 myapp greet John Jane -p Mr.
+# Hello, Mr. John!
+# Hello, Mr. Jane!
 ```
 
-Output:
-```
-Hello, Mr. John!
-Hello, Mr. Jane!
-```
-
-## 📖 Usage Examples
-
-### Programmatic Execution
-
-```typescript
-// Run a command directly with typed arguments
-program.run('greet', { names: ['John', 'Jane'], prefix: 'Dr.' });
-
-// Parse CLI input without executing
-const parsed = program.parse('greet John --prefix Mr.');
-console.log(parsed.args); // { names: ['John'], prefix: 'Mr.' }
-```
-
-### API Mode
-
-Generate a typed API from your CLI program:
-
-```typescript
-const api = program.api();
-
-// Call commands as functions with full type safety
-api.greet({ names: ['Alice', 'Bob'], prefix: 'Dr.' });
-```
-
-### Nested Commands
-
-```typescript
-const program = createPadrone('weather')
-  .command('forecast', (c) =>
-    c
-      .arguments(
-        z.object({
-          city: z.string().describe('City name'),
-          days: z.number().optional().default(3).describe('Number of days'),
-        }),
-        { positional: ['city'] },
-      )
-      .action((args) => {
-        console.log(`Forecast for ${args.city}: ${args.days} days`);
-      })
-      .command('extended', (c) =>
-        c
-          .arguments(
-            z.object({
-              city: z.string().describe('City name'),
-            }),
-            { positional: ['city'] },
-          )
-          .action((args) => {
-            console.log(`Extended forecast for ${args.city}`);
-          }),
-      ),
-  );
-
-// Run nested command
-program.eval('forecast extended London');
-```
-
-### Option Aliases and Metadata
+## What It Does
 
 ```typescript
-const program = createPadrone('app')
-  .command('serve', (c) =>
-    c
-      .arguments(
-        z.object({
-          port: z
-            .number()
-            .default(3000)
-            .describe('Port to listen on')
-            .meta({ alias: 'p', examples: ['3000', '8080'] }),
-          host: z
-            .string()
-            .default('localhost')
-            .describe('Host to bind to')
-            .meta({ alias: 'h' }),
-          verbose: z
-            .boolean()
-            .optional()
-            .describe('Enable verbose logging')
-            .meta({ alias: 'v', deprecated: 'Use --debug instead' }),
-        }),
-      )
-      .action((args) => {
-        console.log(`Server running at ${args.host}:${args.port}`);
-      }),
-  );
-```
+// Multiple ways to run commands
+program.cli();                                              // from process.argv
+program.eval('greet John --prefix Mr.');                    // from a string
+program.run('greet', { names: ['John'], prefix: 'Mr.' });  // typed args
+program.api().greet({ names: ['John'], prefix: 'Mr.' });   // as a function
 
-### Environment Variables and Config Files
-
-Padrone supports loading arguments from environment variables and config files using dedicated schema methods:
-
-```typescript
-const program = createPadrone('app')
-  .command('serve', (c) =>
-    c
-      .arguments(
-        z.object({
-          port: z.number().default(3000).describe('Port to listen on'),
-          apiKey: z.string().describe('API key for authentication'),
-        }),
-      )
-      // Map environment variables to arguments
-      .env(
-        z
-          .object({
-            APP_PORT: z.coerce.number().optional(),
-            API_KEY: z.string().optional(),
-          })
-          .transform((env) => ({
-            port: env.APP_PORT,
-            apiKey: env.API_KEY,
-          })),
-      )
-      // Load config from JSON file with matching schema
-      .configFile(
-        'app.config.json',
-        z.object({
-          port: z.number().optional(),
-          apiKey: z.string().optional(),
-        }),
-      )
-      .action((args) => {
-        console.log(`Server running on port ${args.port}`);
-      }),
-  );
-```
+// Parse without executing
+const { args } = program.parse('greet John --prefix Mr.');
 
-**Precedence order** (highest to lowest): CLI args > environment variables > config file
+// Interactive REPL
+for await (const result of program.repl()) { /* ... */ }
 
-### Async Validation
+// AI tool for Vercel AI SDK
+const tool = program.tool();
 
-If your schema uses async refinements (e.g. `z.check(async ...)`), mark the command as async so that `parse()` and `cli()` return Promises:
+// MCP server for AI assistants (Claude, Cursor, etc.) [experimental]
+await program.mcp();  // or: myapp mcp
 
-```typescript
-import { asyncSchema, createPadrone } from 'padrone';
+// REST server with OpenAPI docs [experimental]
+await program.serve();  // or: myapp serve
 
-const program = createPadrone('app')
-  .command('create', (c) =>
-    c
-      // Option 1: brand the schema with asyncSchema()
-      .arguments(asyncSchema(z.object({ name: z.string() }).check(async (ctx) => { /* ... */ })))
-      // Option 2: call .async() on the builder
-      .async()
-      .action((args) => args.name),
-  );
+// Shell completions
+const script = program.completion('zsh');
 
-// parse() and cli() now return Promises
-const result = await program.parse('create --name test');
+// Help in multiple formats
+program.help('greet');                        // text
+program.help('greet', { format: 'json' });   // json, markdown, html, ansi
 ```
 
-## 🤖 AI SDK Integration
-
-Padrone provides first-class support for the [Vercel AI SDK](https://ai-sdk.dev/), making it easy to expose your CLI as an AI tool:
-
-```typescript
-import { streamText } from 'ai';
-import { createPadrone } from 'padrone';
-import * as z from 'zod/v4';
-
-const weatherCli = createPadrone('weather')
-  .command('current', (c) =>
-    c
-      .arguments(
-        z.object({
-          city: z.string().describe('City name'),
-        }),
-        { positional: ['city'] },
-      )
-      .action((args) => {
-        return { city: args.city, temperature: 72, condition: 'Sunny' };
-      }),
-  );
-
-// Convert your CLI to an AI tool
-const result = await streamText({
-  model: yourModel,
-  prompt: "What's the weather in London?",
-  tools: {
-    weather: weatherCli.tool(),
-  },
-});
-```
+## Features at a Glance
 
-## 📋 Auto-Generated Help
+**Arguments** — positional args, variadic args, short flags (`-v`), long aliases (`--dry-run`), auto kebab-case aliases, negatable booleans (`--no-verbose`).
 
-Padrone automatically generates help text from your Zod schemas:
+**Env & Config** — load from environment variables with `.extend(padroneEnv(schema))` and config files with `.extend(padroneConfig({ files, schema }))`. Precedence: CLI > stdin > env > config > defaults.
 
-```typescript
-console.log(program.help());
-```
+**Interactive prompts** — auto-prompt for missing fields. Booleans become confirm, enums become select, arrays become multi-select.
 
-Example output:
-```
-Usage: myapp greet [names...] [arguments]
+**Progress indicators** — auto-managed spinners and progress bars with elapsed time and ETA. `.extend(padroneProgress({ message: 'Deploying...', bar: true, time: true, eta: true }))`.
 
-Positionals:
-  names...    Names to greet
+**Extension-first architecture** — most built-in features (help, version, REPL, color, signal handling, auto-output, stdin, config, interactive, suggestions) are implemented as extensions composed via `.extend()`. Any built-in can be disabled or replaced.
 
-Arguments:
-  -p, --prefix <string>   Prefix to use in greeting
-  -h, --help              Show help
-```
+**Interceptors** — middleware hooks for 6 phases (start, parse, validate, execute, error, shutdown). Onion model with `next()`. Extensions register interceptors under the hood. Create your own with `defineInterceptor()`.
 
-## 🔧 API Reference
+**Composition** — mount programs as subcommands with `.mount()`, override commands with merge semantics.
 
-### `createPadrone(name)`
+**Wrapping** *(experimental)* — wrap external CLI tools with `.wrap({ command: 'git', args: ['commit'] })`.
 
-Creates a new CLI program with the given name.
+## API
 
-### Program Methods
+### Builder (define commands)
 
-| Method | Description |
+| Method | What it does |
+|--------|-------------|
+| `.arguments(schema, meta?)` | Define args with Zod schema, positional config, field metadata |
+| `.action(handler)` | Set handler `(args, ctx, base?) => result` |
+| `.command(name, builder)` | Add subcommand (name or `[name, ...aliases]`) |
+| `.context(transform?)` | Define typed context or transform inherited context |
+| `.mount(name, program, options?)` | Mount another program as subcommand tree |
+| `.configure(config)` | Set title, description, version, etc. |
+| `.extend(padroneEnv(schema))` | Map env vars to args (composable extension) |
+| `.extend(padroneConfig({ files, schema }))` | Load args from config files (composable extension) |
+| `.wrap(config)` | Wrap an external CLI tool *(experimental)* |
+| `.extend(padroneProgress(config?))` | Auto-managed progress indicator (extension) |
+| `.intercept(interceptor)` | Register middleware interceptor (use `defineInterceptor()`) |
+| `.extend(extension)` | Apply a build-time extension (bundle of config, commands, interceptors) |
+| `.runtime(runtime)` | Custom I/O (for non-terminal use) |
+| `.updateCheck(config?)` | Background version check |
+| `.async()` | Mark as async validation |
+
+### Program (run commands)
+
+| Method | What it does |
 |--------|-------------|
-| `.configure(config)` | Configure program properties (title, description, version) |
-| `.command(name, builder)` | Add a command to the program |
-| `.arguments(schema, meta?)` | Define arguments schema with optional positional args |
-| `.async()` | Mark command as async (for schemas with async validation) |
-| `.env(schema)` | Define schema for parsing environment variables into arguments |
-| `.configFile(file, schema?)` | Configure config file path(s) and schema |
-| `.action(handler)` | Set the command handler function |
-| `.cli(input?)` | Run as CLI (parses `process.argv` or input string) |
-| `.run(command, args?)` | Run a command programmatically |
-| `.parse(input?)` | Parse input without executing |
-| `.stringify(command?, args?)` | Convert command and arguments back to CLI string |
-| `.api()` | Generate a typed API object |
-| `.help(command?)` | Generate help text |
-| `.tool()` | Generate a Vercel AI SDK tool |
-| `.find(command)` | Find a command by name |
-
-### Arguments Meta
-
-Use the second argument of `.arguments()` to configure positional arguments and per-argument metadata:
+| `.cli(prefs?)` | Entry point — parses `process.argv`, throws on errors. Pass `context` in prefs. |
+| `.eval(input, prefs?)` | Parse + validate + execute string, returns errors softly. Pass `context` in prefs. |
+| `.run(command, args, prefs?)` | Run by name with typed args (no validation). Pass `context` in prefs. |
+| `.parse(input?)` | Parse without executing |
+| `.api()` | Generate typed function API |
+| `.repl(options?)` | Interactive REPL session |
+| `.help(command?, prefs?)` | Generate help (text, ansi, markdown, html, json) |
+| `.tool()` | Vercel AI SDK tool definition |
+| `.mcp(prefs?)` | Start MCP server (HTTP or stdio) *(experimental)* |
+| `.serve(prefs?)` | Start REST server with OpenAPI docs *(experimental)* |
+| `.completion(shell?)` | Shell completion script |
+| `.find(command)` | Look up command by path |
+| `.stringify(command?, args?)` | Convert back to CLI string |
+
+### Zod `.meta()` fields
+
+| Field | Example | Purpose |
+|-------|---------|---------|
+| `flags` | `'v'` | Single-char short flag (`-v`) |
+| `alias` | `'dry-run'` | Multi-char long alias (`--dry-run`) |
+| `examples` | `['8080']` | Example values in help |
+| `deprecated` | `'Use --debug'` | Deprecation warning |
+| `hidden` | `true` | Hide from help |
+| `group` | `'Advanced'` | Group in help output |
+
+### Arguments meta (second param of `.arguments()`)
 
 ```typescript
 .arguments(schema, {
-  positional: ['source', '...files', 'dest'],  // '...files' is variadic
-  fields: {
-    verbose: { alias: 'v' },
-    format: { deprecated: 'Use --output instead' },
-  },
+  positional: ['source', '...files', 'dest'],
+  interactive: ['name', 'template'],
+  optionalInteractive: ['typescript'],
+  fields: { verbose: { flags: 'v' } },
+  stdin: 'data',
+  autoAlias: true,  // default
 })
 ```
 
-### Zod Metadata
+## Agent Skill
 
-Use `.meta()` on Zod schemas to provide additional CLI metadata:
-
-```typescript
-z.string().meta({
-  alias: 'p',            // Short alias (-p)
-  examples: ['value'],   // Example values for help text
-  deprecated: 'message', // Mark as deprecated
-  hidden: true,          // Hide from help output
-})
-```
-
-## 🤖 AI Coding Agent Skill
-
-Install the [Padrone skill](https://agentskills.io) to give your AI coding agent (Claude Code, etc.) knowledge of the Padrone API:
+Give your AI coding agent knowledge of the Padrone API:
 
 ```bash
 npx skills add KurtGokhan/padrone
 ```
 
-## 🛠️ Requirements
+## Requirements
 
 - Node.js 18+ or Bun
 - TypeScript 5.0+ (recommended)
-- Zod 3.25+ or 4.x
+- Zod (or any Standard Schema-compatible library)
 
-## 📄 License
+## License
 
-[MIT](LICENSE) © [Gokhan Kurt](https://gkurt.com)
-
----
-
-<p align="center">
-  Made with ❤️ by <a href="https://gkurt.com">Gokhan Kurt</a>
-</p>
+[MIT](LICENSE)