@bike4mind/cli 0.18.4 → 0.20.0

package/LICENSE

@@ -9,7 +9,7 @@ Parameters
 
 Licensor:             Bike4Mind, Inc.
 
-Licensed Work:        Bike4Mind (the lumina5 repository and the components
+Licensed Work:        Bike4Mind (this repository and the components
                       distributed under this License).
                       The Licensed Work is (c) 2026 Bike4Mind, Inc.
 
@@ -33,7 +33,21 @@ Additional Use Grant: You may make production use of the Licensed Work,
                       provider — is expressly permitted and is not a Bike4Mind
                       Service.
 
-Change Date:          Four years from the date a given version of the Licensed
+                      Nominative name use (an additional grant): notwithstanding
+                      the trademark reservation in the Terms below, you may use
+                      the name "Bike4Mind" solely to state accurately that your
+                      product or service is built on, forked from, or derived
+                      from the Licensed Work. This permission does not extend to
+                      using "Bike4Mind" as the name of your own product or
+                      service, or in any manner that implies sponsorship or
+                      endorsement by Bike4Mind, Inc. Retaining the NOTICE file
+                      provided with the Licensed Work is encouraged; and when you
+                      distribute a version on or after its Change Date, retaining
+                      it is required by the Change License (Apache-2.0, Section
+                      4(d)). That obligation attaches to distribution, not to
+                      hosted use.
+
+Change Date:          Two years from the date a given version of the Licensed
                       Work is first made publicly available. Each version
                       carries its own Change Date (see Terms). Bike4Mind, Inc.
                       may, at its discretion, designate an earlier Change Date
@@ -57,7 +71,7 @@ works, redistribute, and make non-production use of the Licensed Work. The
 Licensor may make an Additional Use Grant, above, permitting limited production
 use.
 
-Effective on the Change Date, or the fourth anniversary of the first publicly
+Effective on the Change Date, or the second anniversary of the first publicly
 available distribution of a specific version of the Licensed Work under this
 License, whichever comes first, the Licensor hereby grants you rights under
 the terms of the Change License, and the rights granted in the paragraph

package/README.md

@@ -70,26 +70,74 @@ The CLI will prompt you to authenticate with your Bike4Mind account on first run
 ### CLI Flags
 
 ```bash
-b4m [options]
+b4m [options] ["initial prompt"]
 ```
 
-**Available flags:**
-- `--dev` - Point the CLI at the local dev server (`http://localhost:3001`) and remember it
-- `--prod` - Point the CLI at Bike4Mind production and remember it
-- `--verbose`, `-v` - Show debug logs in console (useful for troubleshooting)
-- `--help`, `-h` - Show help information
-- `--version`, `-V` - Show CLI version
+A bare positional argument seeds **and** submits the first turn while keeping the interactive UI open (e.g. `b4m "summarize the git log"`).
+
+**Environment / API** (see [API Configuration](#api-configuration)):
+
+| Flag | Effect |
+| --- | --- |
+| `--dev` | Point the CLI at the local dev server (`http://localhost:3001`) and remember it. Aliases: `--local`, single-dash forms. |
+| `--prod` | Point the CLI at Bike4Mind production and remember it. Alias: `--production`. |
+| `--api-url <url>` | Point the CLI at **any** instance — a self-hosted stack, an AWS deployment, `http://localhost:3000`, etc. Clears cached auth (bound to the old origin) and exits; run `b4m` again to sign in. |
+| `--reset-api` | Reset the API URL to the built-in default and clear auth, then exit. |
+
+**Session / behavior:**
+
+| Flag | Effect |
+| --- | --- |
+| `--verbose`, `-v` | Show debug logs in the console (also always written to file — see [Debug Logs](#debug-logs)). |
+| `--debug-stream` | Ultra-verbose: log every SSE event (stream-parser debugging). Implies `--verbose`. |
+| `--no-project-config` | Skip loading project-specific config (`.bike4mind/`). |
+| `--add-dir <dir>` | Grant file access to an additional directory. Repeatable. |
+| `--ollama-host <url>` | Add a local Ollama endpoint's models to the picker (e.g. `http://localhost:11434`). |
+| `--no-remote-skills` | Skip fetching remote B4M-web skills for this run (local files only). |
+
+**Headless / non-interactive** (for scripts and CI):
+
+| Flag | Effect |
+| --- | --- |
+| `-p`, `--prompt <query>` | Run a single query non-interactively and exit. |
+| `--output-format <fmt>` | Output when using `-p`: `text` (default), `json`, or `stream-json` (NDJSON of thoughts/actions/observations). |
+| `--dangerously-skip-permissions` | With `-p`, auto-allow all tool permission prompts. Use with caution in CI/CD. |
+
+**Info:**
+
+| Flag | Effect |
+| --- | --- |
+| `--help`, `-h` | Show help. |
+| `--version`, `-V` | Show CLI version. |
+
+> **Host / `claude`-drop-in flags** (`--mcp-config`, `--strict-mcp-config`, `--append-system-prompt`, `--allowedTools`, `--settings`, `--session-id`, `--resume`) are documented under [Running as a `claude` engine inside a host app](#running-as-a-claude-engine-inside-a-host-app).
 
 **Examples:**
 ```bash
+# Point at a self-hosted stack, then sign in
+b4m --api-url http://localhost:3000
+b4m
+
+# One-shot headless query, JSON output
+b4m -p "What is 2+2?" --output-format json
+
 # Run with debug logs visible
 b4m --verbose
 
-# Check version
-b4m --version
+# Seed and submit the first turn, stay interactive
+b4m "review the recent changes"
+```
 
-# Show help
-b4m --help
+### Subcommands
+
+```bash
+b4m mcp list                              # List configured MCP servers
+b4m mcp add <name> -- <command...>        # Add an MCP server
+b4m mcp remove <name>                     # Remove an MCP server
+b4m mcp enable <name> | disable <name>    # Toggle a server on/off
+b4m mcp serve [--http] [--port <n>]       # Expose Bike4Mind itself as an MCP server
+b4m update                                # Check for and install CLI updates
+b4m doctor                                # Diagnose the CLI installation (Node, registry, ripgrep, native modules)
 ```
 
 ### Switching environments (`--dev` / `--prod`)
@@ -116,31 +164,64 @@ shown in the startup banner (`🌍 API Environment: …`).
 
 ## Commands
 
-While in interactive mode:
+While in interactive mode. This mirrors the registry in `src/config/commands.ts` — run `/help` in a session for the live list (which also includes any custom and project commands).
 
 **Authentication:**
 - `/login` - Authenticate with your B4M account
 - `/logout` - Clear authentication and sign out
 - `/whoami` - Show current authenticated user
 
-**Session Management:**
+**Session management:**
 - `/save <name>` - Save current session
-- `/resume` - List and resume saved sessions
-
-**API Configuration:**
-- `/set-api <url>` - Connect to self-hosted Bike4Mind instance
-- `/reset-api` - Reset to Bike4Mind main service
+- `/resume` (alias `/sessions`) - List and resume saved sessions
+- `/clear` (alias `/new`) - Start a new session
+- `/compact [instructions]` - Compact the conversation into a new session
+- `/context` - Show context-window usage
+- `/usage` - Show credit usage and balance
+
+**API configuration:**
+- `/set-api <url>` - Connect to a self-hosted / custom Bike4Mind instance
+- `/reset-api` - Reset to the Bike4Mind main service
 - `/api-info` - Show current API configuration
 
-**Tool Permissions:**
-- `/trust <tool-name>` - Trust a tool (won't ask permission again)
-- `/untrust <tool-name>` - Remove tool from trusted list
-- `/trusted` - List all trusted tools
+**Files & checkpoints:**
+- `/add-dir <path>` / `/remove-dir <path>` / `/dirs` - Manage accessible directories
+- `/undo` - Undo the last file change
+- `/checkpoints` - List file restore points
+- `/restore <number>` - Restore files to a checkpoint
+- `/diff [number]` - Diff current state against a checkpoint
+- `/rewind` - Rewind the conversation to a previous point
+
+**Tool permissions:**
+- `/trust <tool-name>` / `/untrust <tool-name>` / `/trusted` - Manage auto-approved tools
+
+**Sandbox** (OS-level isolation for `bash`):
+- `/sandbox` - Show sandbox status and configuration
+- `/sandbox:enable` / `/sandbox:disable` - Toggle the sandbox
+- `/sandbox:mode <auto-allow|permissions>` - Set enforcement mode
+- `/sandbox:trust-domain <domain> [...]` / `/sandbox:domains` - Manage the network allowlist
+- `/sandbox:violations [count]` / `/sandbox:violations:clear` - Inspect / clear violations
+
+**MCP & agents:**
+- `/mcp` (alias `/mcp:list`) - Show MCP server status and connected tools
+- `/agents` (alias `/agents:list`) - List available agents
+- `/agents:new <name>` / `/agents:reload` - Create / reload agent definitions
+
+**Custom commands:**
+- `/commands` - List all custom commands
+- `/commands:new <name>` / `/commands:reload` - Create / reload custom commands
+
+**Durable workflow** (cross-session continuity):
+- `/workflow [decisions|blockers|handoff|review-gates]` - Workflow overview or a section
+- `/decisions` / `/blockers` / `/review-gates` - Shortcuts for the sections above
+- `/handoff [generate|--local]` - Show or generate a session handoff (`--local` = LLM-free snapshot)
 
 **General:**
 - `/help` - Show help
-- `/exit` - Exit CLI
-- `/config` - Show configuration
+- `/config` - Open the interactive configuration editor
+- `/project-config` - Show merged project configuration
+- `/terminal-setup` - Configure Shift+Enter for multi-line input
+- `/exit` (alias `/quit`) - Exit the CLI
 
 ## Configuration
 
@@ -164,31 +245,43 @@ The default is baked in at build time from the hosted build environment — ther
 fallback in source** (open-core, #9306/#9392), so a fresh clone ships empty. A fork publishes its
 own CLI by setting `B4M_DEFAULT_API_URL` when building — see `tsdown.config.ts`.
 
+Because that default is injected only at build time, the endpoint is resolved like this:
+
+1. A **custom URL** you set (`--api-url` / `--dev` / `--prod` / `/set-api`) always wins.
+2. Otherwise, the **build-time default** baked into a published binary.
+3. Otherwise, when running **from source** (a `pnpm link --global` checkout, `pnpm dev` — no
+   `dist/` built), the CLI defaults to the local dev server `http://localhost:3001`. Use
+   `--prod` / `--api-url` to point it elsewhere.
+4. Otherwise (a published, unbranded fork with no baked default), the first `b4m` **prompts you
+   to choose a backend**.
+
 **Quick switch between local dev and production:** use the `b4m --dev` / `b4m --prod`
 launch flags (see [Switching environments](#switching-environments---dev----prod)).
 They persist your choice and cache auth per-environment. The `/set-api`, `/reset-api`,
 and `/api-info` commands below operate on the same setting from inside a session.
 
-**For Self-Hosted Instances:**
-
-If your organization runs a self-hosted Bike4Mind instance, connect to it using:
+**For self-hosted / custom instances:**
 
-```bash
-/set-api https://app.your-instance.example.com
-```
+The CLI can point at **any** Bike4Mind deployment — a self-hosted Docker stack, an AWS deployment, or `http://localhost:3000` — because auth (the OAuth device flow) and the chat API ship in the open core and are served by that instance directly.
 
-To return to the main Bike4Mind service:
+From the launch line (clears auth, then exit — run `b4m` again to sign in):
 
 ```bash
-/reset-api
+b4m --api-url http://localhost:3000              # local self-host Docker stack
+b4m --api-url https://app.your-instance.example.com
+b4m --reset-api                                  # back to the built-in default
 ```
 
-Check your current API configuration:
+Or from inside a session:
 
 ```bash
-/api-info
+/set-api https://app.your-instance.example.com
+/reset-api    # return to the default service
+/api-info     # show the current API configuration
 ```
 
+Auth tokens are cached **per environment**, so switching between hosted and self-host does not force a re-login. For an end-to-end walkthrough (hosted **and** self-host, sign-in, credits, troubleshooting), see the top-level [**BIKE4MIND_CLI.md**](../../BIKE4MIND_CLI.md).
+
 ### Tool API Keys
 
 Some built-in tools require API keys to function. Add them to `~/.bike4mind/config.json`:
@@ -297,6 +390,77 @@ You can also run any MCP server via npx or custom executables:
 
 **Note:** Internal MCP servers must be built and available in the `b4m-core/packages/mcp/dist/src/` directory. The CLI will automatically find them if you're running from the monorepo. For Docker-based servers, ensure Docker is installed and the image is accessible.
 
+#### Serve Bike4Mind itself as an MCP server (`b4m mcp serve`)
+
+The reverse of adding a server: `b4m mcp serve` exposes your Bike4Mind backend to any MCP client (Claude Desktop, editors, other agents). It advertises eight tools (`list_notebooks`, `get_notebook`, `create_notebook`, `send_message`, `search_knowledge_base`, `list_files`, `get_file`, `generate_sound_effect`) plus four resource templates (`b4m://notebook/{id}`, `b4m://file/{id}`, `b4m://project/{id}`, `b4m://artifact/{id}`), each listable and readable as JSON, and `b4m://agent-quest` - the credential-free manifest for The Open Door, the onboarding quest for agents.
+
+```bash
+b4m mcp serve                        # stdio (default) - for local clients that spawn the process
+b4m mcp serve --http --port 7000     # stateless streamable HTTP at http://127.0.0.1:7000/mcp
+```
+
+Auth precedence is `--api-key` > `B4M_API_KEY` > the stored login; the endpoint is `B4M_API_URL` > `--api-url` > the configured backend. Tool *listing* needs no credentials; tool *calls* authenticate. Prefer `B4M_API_KEY` over `--api-key` (a flag value shows up in process listings). HTTP mode binds loopback only (`127.0.0.1`, `/mcp` path) and has no per-request auth, so do not expose it off-host. The advertised scopes are the recommended key configuration, not per-route hard gates. See [Serve Bike4Mind as an MCP server](../../BIKE4MIND_CLI.md#serve-bike4mind-as-an-mcp-server-b4m-mcp-serve) for the Claude Desktop config and details.
+
+## Plugins
+
+The CLI can load external feature modules at runtime. A plugin is an npm package that adds tools, a system-prompt section, slash commands, and (optionally) WebSocket handlers to the interactive session, without any change to the CLI itself.
+
+```bash
+b4m plugin add @someone/b4m-plugin-foo     # install from npm
+b4m plugin add github:user/b4m-plugin-foo  # install from GitHub
+b4m plugin add file:/path/to/local/plugin  # install a local directory (development/QA)
+b4m plugin list                            # show installed plugins and their state
+b4m plugin remove foo                      # uninstall and disable
+```
+
+Plugins install to `~/.bike4mind/plugins/` and are gated by a `features` toggle in your config: `add` enables it for you, and every installed plugin also shows up automatically in the `/config` editor. A newly installed plugin loads the next time you start `b4m`; toggling an already-installed plugin in `/config` hot-reloads it in place.
+
+### Writing a plugin
+
+A plugin declares itself with a `b4m-plugin` field in its `package.json`:
+
+```json
+{
+  "name": "@someone/b4m-plugin-foo",
+  "type": "module",
+  "b4m-plugin": { "entry": "./dist/index.js", "configKey": "foo" }
+}
+```
+
+`entry` (required) is the module the CLI imports, resolved inside the package. `configKey` (optional, defaults to the package name) is the `features` key that gates the plugin.
+
+The entry default-exports a factory. It receives a context (currently `{ logger }`, with `debug/info/warn/error` methods that write to the CLI debug log) and returns the module object:
+
+```js
+export default ctx => ({
+  name: 'foo',                       // unique module name
+  description: 'What this plugin does',
+  getTools: () => [
+    {
+      toolFn: async args => 'result',   // invoked when the agent calls the tool
+      toolSchema: {
+        name: 'foo_tool',
+        description: 'What the tool does',
+        parameters: { type: 'object', properties: {} },  // JSON Schema
+      },
+    },
+  ],
+  getSystemPromptSection: () => 'Extra system-prompt text (or an empty string)',
+  getCommands: () => [{ name: 'foo', description: '...', execute: args => {} }],  // optional
+  registerWsHandlers: wsManager => {},  // optional
+  dispose: () => {},                    // optional, runs on exit/disable
+});
+```
+
+Tool objects are written out structurally as shown - plugin packages cannot import `@bike4mind/*` packages at runtime (those are bundled into the CLI binary and are not on npm in a compatible form). See `test/fixtures/b4m-plugin-example/` in this package for a complete working plugin.
+
+### Limitations and trust
+
+- **Plugins run in-process with your privileges.** Installing one runs its npm install scripts, and enabling it executes its code inside the CLI, same as configuring an MCP server command. Only install plugins you trust.
+- **Interactive mode only.** Headless (`b4m -p`) and ACP sessions do not load feature modules or plugins today.
+- **Downgrade caveat:** CLI versions without plugin support strip plugin keys from the config `features` map on their next save; re-enable after upgrading again.
+- A plugin that fails to load (bad manifest, import error, malformed tools) is skipped with a warning at startup - it never blocks the CLI. `b4m plugin list` shows the reason.
+
 ## Git-Aware Code Search
 
 The CLI includes a `recent_changes` tool that uses git history to find recently modified files. This significantly speeds up debugging by narrowing the search space to recently changed code.
@@ -459,6 +623,11 @@ b4m --version
 
 After step 4, running `b4m` anywhere on your system executes this working tree. Re-run `pnpm link --global` if you move or rename the repo.
 
+> **Which backend does a linked checkout talk to?** A source/linked run has no build-time
+> default baked in, so `b4m` defaults to the local dev server (`http://localhost:3001`) — start
+> your local stack, or point it elsewhere with `b4m --prod` / `b4m --api-url <url>`. See
+> [API Configuration](#api-configuration) for the full resolution order.
+
 ### Editing CLI source (`packages/cli/src/`)
 
 Just run `b4m`. The bin's `tsx` fallback picks up your edits on the next invocation — no build step needed.
@@ -547,7 +716,7 @@ packages/cli/
 │   │   └── ConfigStore.ts
 │   └── index.tsx         # Main entry point
 └── bin/
-    └── bike4mind-cli.js  # Executable
+    └── bike4mind-cli.mjs  # Executable (source/dist auto-detect + flag parsing)
 ```
 
 ## Dependencies

package/bin/bike4mind-cli.mjs

@@ -1,19 +1,15 @@
 #!/usr/bin/env node
  
 
-// This is the executable entry point for the CLI
-// In development, it will use tsx to run the TypeScript directly
-// In production, it will run the compiled JavaScript
+// Executable entry point for the CLI: tsx runs the TypeScript source in dev,
+// the compiled JavaScript in production.
 
-// Suppress punycode deprecation warning from dependencies
-// This is a known issue with older npm packages using Node's built-in punycode
+// Suppress punycode deprecation warning from older deps using Node's built-in punycode.
 process.removeAllListeners('warning');
 process.on('warning', (warning) => {
-  // Only suppress punycode deprecation warnings
   if (warning.name === 'DeprecationWarning' && warning.message.includes('punycode')) {
     return;
   }
-  // Show all other warnings
   console.warn(warning);
 });
 
@@ -37,7 +33,7 @@ const { version: cliVersion } = require('../package.json');
 // Intercept these BEFORE yargs parses argv. They're accepted with either a
 // single or double dash (e.g. `b4m -prod` and `b4m --prod` both work), but
 // single-dash multi-char tokens would otherwise be split into clustered short
-// flags by yargs (`-prod` → `-p -r -o -d`, colliding with -p/--prompt). We pull
+// flags by yargs (`-prod` -> `-p -r -o -d`, colliding with -p/--prompt). We pull
 // them out here, record the target, and strip them so yargs sees a clean argv.
 const ENV_FLAG_MAP = {
   '--dev': 'dev', '-dev': 'dev', '--local': 'dev', '-local': 'dev',
@@ -57,14 +53,13 @@ let envTarget = null;
   process.argv = [process.argv[0], process.argv[1], ...cleaned];
 }
 
-// Parse CLI arguments
 const argv = await yargs(hideBin(process.argv))
   // --dev / --prod are declared here ONLY so they appear in `--help`. The actual
-  // handling is the pre-yargs argv interception above — these yargs-side values
+  // handling is the pre-yargs argv interception above - these yargs-side values
   // (`argv.dev` / `argv.prod`) are never read.
   .option('dev', {
     type: 'boolean',
-    description: 'Point the CLI at the local dev server (http://localhost:3001) and remember it',
+    description: 'Point the CLI at the local dev server (http://localhost:3000) and remember it',
   })
   .option('prod', {
     type: 'boolean',
@@ -107,13 +102,17 @@ const argv = await yargs(hideBin(process.argv))
     description: 'When using -p, auto-allow all tool permission prompts (use with caution in CI/CD)',
     default: false,
   })
+  .option('permission-policy', {
+    type: 'string',
+    description: 'When using -p, path to a JSON permission policy for unattended runs (allow/deny/risk rules)',
+  })
   .option('ollama-host', {
     type: 'string',
     description: 'Add local Ollama models to the model picker (e.g. http://localhost:11434)',
   })
-  // ─── claude-compatible flags (host drop-in masquerade) ──────────────────────
-  // Declared so a host's claude launch flags parse into named options instead of
-  // leaking into the positional `argv._` task. See packages/cli README "host app".
+  // claude-compatible flags (host drop-in masquerade). Declared so a host's
+  // claude launch flags parse into named options instead of leaking into the
+  // positional `argv._` task. See packages/cli README "host app".
   .option('mcp-config', {
     type: 'string',
     description: 'Path to a JSON file of MCP servers to inject ({ "mcpServers": {...} })',
@@ -198,10 +197,62 @@ const argv = await yargs(hideBin(process.argv))
       }, async () => {
         // Handled by external command handler
       })
-      .demandCommand(1, 'You must provide a subcommand (list, add, remove, enable, disable)');
+      .command('serve', 'Run Bike4Mind as an MCP server (stdio by default, or --http)', (yargs) => {
+        return yargs
+          .option('http', {
+            type: 'boolean',
+            description: 'Serve over streamable HTTP instead of stdio',
+            default: false,
+          })
+          .option('port', {
+            type: 'number',
+            description: 'Port for --http mode',
+            default: 7000,
+          })
+          .option('api-key', {
+            type: 'string',
+            description: 'Bike4Mind API key (overrides B4M_API_KEY and the stored login). Visible in process listings; prefer B4M_API_KEY',
+          })
+          .option('api-url', {
+            type: 'string',
+            description: 'Bike4Mind API URL (overrides B4M_API_URL and the configured backend)',
+          })
+          .example('b4m mcp serve', 'Serve over stdio for Claude Desktop and other local clients')
+          .example('b4m mcp serve --http --port 7000', 'Serve over streamable HTTP on port 7000');
+      }, async () => {
+        // Handled by external command handler
+      })
+      .demandCommand(1, 'You must provide a subcommand (list, add, remove, enable, disable, serve)');
+  })
+  .command('plugin', 'Manage B4M feature-module plugins', (yargs) => {
+    return yargs
+      .command('list', 'List installed plugins', {}, async () => {
+        // Handled by external command handler
+      })
+      .command('add <spec>', 'Install a plugin package', (yargs) => {
+        return yargs
+          .positional('spec', {
+            type: 'string',
+            describe: 'npm package, @scope/package, github:user/repo, or file:<path>',
+          })
+          .example('b4m plugin add @someone/b4m-plugin-foo', 'Install from npm')
+          .example('b4m plugin add github:user/b4m-plugin-foo', 'Install from GitHub');
+      }, async () => {
+        // Handled by external command handler
+      })
+      .command('remove <name>', 'Uninstall a plugin', (yargs) => {
+        return yargs.positional('name', {
+          type: 'string',
+          describe: 'Plugin name (config key, package name, or short name)',
+        });
+      }, async () => {
+        // Handled by external command handler
+      })
+      .demandCommand(1, 'You must provide a subcommand (list, add, remove)');
   })
   .command('update', 'Check for and install CLI updates')
   .command('doctor', 'Run diagnostic checks on CLI installation')
+  .command('acp', 'Run as an Agent Client Protocol (ACP) stdio server for editors like Zed')
   .help()
   .alias('help', 'h')
   .version(cliVersion)
@@ -238,8 +289,8 @@ if (argv['no-remote-skills']) {
   process.env.B4M_NO_REMOTE_SKILLS = '1';
 }
 
-// ─── claude-compatible flags → B4M_* env (read by src/index.tsx init) ─────────
-// Mirrors the established bin→env→init channel (cf. --add-dir → B4M_ADDITIONAL_DIRS).
+// claude-compatible flags -> B4M_* env (read by src/index.tsx init).
+// Mirrors the established bin->env->init channel (cf. --add-dir -> B4M_ADDITIONAL_DIRS).
 if (argv['mcp-config']) {
   process.env.B4M_MCP_CONFIG_FILE = resolve(argv['mcp-config']);
 }
@@ -266,7 +317,7 @@ if (argv.resume) {
 }
 // Positional task (claude `<prompt>` form): seeds AND submits turn 1, stays interactive.
 // Only when it's not a known subcommand and headless -p wasn't used.
-const KNOWN_SUBCOMMANDS = new Set(['mcp', 'update', 'doctor']);
+const KNOWN_SUBCOMMANDS = new Set(['mcp', 'plugin', 'update', 'doctor', 'acp']);
 if (argv.prompt === undefined && argv._.length > 0 && !KNOWN_SUBCOMMANDS.has(String(argv._[0]))) {
   process.env.B4M_INITIAL_PROMPT = String(argv._[0]);
 }
@@ -284,10 +335,21 @@ const hasDist = existsSync(distPath);
 const isDev = process.env.NODE_ENV === 'development' ||
               (!hasDist && hasSource);
 
+// Signal source mode to the app so endpoint resolution can default an
+// otherwise-unconfigured run to the local dev server (build-time brand
+// defaults are never injected into a source run). Set before any command
+// dispatch below so --reset-api messaging and the app both observe it.
+// See resolveApiEndpoint() / isSourceMode() in src/utils/apiUrl.ts.
+if (isDev) {
+  process.env.B4M_SOURCE_MODE = '1';
+}
+
 // Handle --api-url / --reset-api flags
 // These mutate ~/.bike4mind/config.json and exit before any auth flow runs,
 // so devs can recover from a misconfigured customUrl without editing JSON.
-if (argv['reset-api'] || argv['api-url'] !== undefined) {
+// `mcp serve` has its own ephemeral --api-url (points that one server at a
+// backend without touching config), so skip the mutate-and-exit path for it.
+if ((argv['reset-api'] || argv['api-url'] !== undefined) && argv._[0] !== 'mcp') {
   try {
     let handleApiCommand;
 
@@ -360,6 +422,7 @@ if (argv.prompt !== undefined) {
       dangerouslySkipPermissions: argv['dangerously-skip-permissions'] || false,
       verbose: argv.verbose || false,
       addDirs: rawAddDirs.map(d => resolve(d)),
+      permissionPolicyPath: argv['permission-policy'] ? resolve(argv['permission-policy']) : undefined,
     });
     // handleHeadlessCommand calls process.exit internally, but handle the case it doesn't
     process.exit(0);
@@ -397,6 +460,31 @@ if (argv._[0] === 'mcp') {
   }
 }
 
+// Handle plugin subcommands (external commands)
+if (argv._[0] === 'plugin') {
+  const pluginSubcommand = argv._[1];
+
+  try {
+    let handlePluginCommand;
+
+    if (isDev) {
+      const { register } = require('tsx/esm/api');
+      register();
+      const module = await import('../src/commands/pluginCommand.ts');
+      handlePluginCommand = module.handlePluginCommand;
+    } else {
+      const module = await import('../dist/commands/pluginCommand.mjs');
+      handlePluginCommand = module.handlePluginCommand;
+    }
+
+    await handlePluginCommand(pluginSubcommand, argv);
+    process.exit(0);
+  } catch (error) {
+    console.error('Error:', error.message);
+    process.exit(1);
+  }
+}
+
 // Handle update command (external command)
 if (argv._[0] === 'update') {
   try {
@@ -420,6 +508,31 @@ if (argv._[0] === 'update') {
   }
 }
 
+// Handle ACP server command (external command)
+// stdio is the JSON-RPC transport, so this never returns until the client
+// disconnects. Errors go to stderr to keep stdout as a clean protocol stream.
+if (argv._[0] === 'acp') {
+  try {
+    let handleAcpCommand;
+
+    if (isDev) {
+      const { register } = require('tsx/esm/api');
+      register();
+      const module = await import('../src/commands/acpCommand.ts');
+      handleAcpCommand = module.handleAcpCommand;
+    } else {
+      const module = await import('../dist/commands/acpCommand.mjs');
+      handleAcpCommand = module.handleAcpCommand;
+    }
+
+    await handleAcpCommand({ verbose: argv.verbose || false, version: cliVersion });
+    process.exit(0);
+  } catch (error) {
+    process.stderr.write(`Error: ${error.message}\n`);
+    process.exit(1);
+  }
+}
+
 // Handle doctor command (external command)
 if (argv._[0] === 'doctor') {
   try {
@@ -444,14 +557,14 @@ if (argv._[0] === 'doctor') {
 }
 
 if (isDev) {
-  // Show dev mode indicator for developers
-  console.log('🔧 Running in development mode (using TypeScript source)\n');
+  // Note: this is about *how the CLI runs* (unbuilt TypeScript source), which is
+  // distinct from the `--dev` flag (which selects the local dev *backend*).
+  console.log('🔧 Running from TypeScript source (no dist build)\n');
   // Development: use tsx to run TypeScript
   try {
     const { register } = require('tsx/esm/api');
     register();
 
-    // Import and run the main app
     await import(join(__dirname, '../src/index.tsx'));
   } catch (error) {
     console.error('Failed to start CLI in development mode:', error);
@@ -463,7 +576,7 @@ if (isDev) {
   try {
     // Auto-update on launch (consent-first): when a newer version is available
     // on a writable global prefix, install + re-exec into it BEFORE importing
-    // the code-split app — running an install while dist/index.mjs is loaded
+    // the code-split app - running an install while dist/index.mjs is loaded
     // would crash it. On the default 'ask' preference this prompts the user
     // (Update once / Always / Skip / Never); 'auto' installs silently, 'never'
     // does nothing. Wrapped so the updater can never block launching the CLI.
@@ -471,7 +584,7 @@ if (isDev) {
       const { maybeAutoUpdateOnLaunch } = await import('../dist/commands/updateCommand.mjs');
       await maybeAutoUpdateOnLaunch();
     } catch {
-      // Updater is best-effort — fall through to the current version.
+      // Updater is best-effort - fall through to the current version.
     }
 
     await import(join(__dirname, '../dist/index.mjs'));