@interactive-inc/claude-funnel 0.15.1 → 0.16.1

package/README.md

@@ -54,11 +54,21 @@ The MCP layer is a thin bridge into the agent. It subscribes to the bound channe
 
 ## Install
 
+Per-repo (recommended for getting started — no global install, version pinned by the repo's lock file):
+
+```bash
+bun add -D @interactive-inc/claude-funnel
+bunx funnel claude            # or `bunx funnel <any subcommand>`
+```
+
+Global (one CLI for every repo you touch):
+
 ```bash
 bun add -g @interactive-inc/claude-funnel
+funnel claude                 # or the `fnl` shorthand
 ```
 
-The published package ships the built `dist/`, so `bun add -g` makes `funnel` / `fnl` available immediately — no post-install step.
+The published package ships the built `dist/`, so either install makes `funnel` / `fnl` available immediately — no post-install step. The rest of the README uses `fnl` for brevity; swap in `bunx funnel` if you went the per-repo route.
 
 ## Quick start
 
@@ -85,34 +95,43 @@ Or drop a `funnel.json` in the repo and `fnl claude` (no args) inside the repo w
 
 ```json
 {
-  "$schema": "https://interactive-inc.github.io/open-claude-funnel/funnel.schema.json",
-  "channel": "ops",
-  "options": ["--brief", "--agent", "cto"],
+  "$schema": "./node_modules/@interactive-inc/claude-funnel/funnel.schema.json",
+  "options": ["--brief"],
   "env": {
     "ANTHROPIC_MODEL": "claude-sonnet-4-6"
   },
-  "connectors": [
+  "channels": [
+    {
+      "name": "ops",
+      "options": ["--agent", "pm"],
+      "connectors": [
+        {
+          "type": "slack",
+          "name": "my-slack",
+          "env": {
+            "botToken": "SLACK_BOT_TOKEN",
+            "appToken": "SLACK_APP_TOKEN"
+          }
+        }
+      ]
+    },
     {
-      "type": "slack",
-      "name": "my-slack",
-      "env": {
-        "botToken": "SLACK_BOT_TOKEN",
-        "appToken": "SLACK_APP_TOKEN"
-      }
+      "name": "review",
+      "options": ["--agent", "reviewer"]
     }
   ]
 }
 ```
 
-Only `channel` is required.
+`channels[]` is required and the first entry is the default. `fnl claude --channel review` picks one by name; `fnl claude` with no `--channel` uses the first.
 
-The optional `options` array is prepended to the claude argv on every launch, before any args the user types after `fnl claude`. Use it for repo-wide claude flags (e.g. `--brief`, `--agent <name>`, `--model <name>`). User-supplied CLI args appear later in the argv so they still win on collision.
+The optional top-level `options` array is shared by every channel and prepended to each channel's own `options` (and both appear before user-supplied CLI args, which still come last). Use it for flags that should apply repo-wide (e.g. `--brief`). Per-channel `options` add channel-specific flags (e.g. a different `--agent`).
 
-The optional top-level `env` is a `Record<string, string>` of environment variables to layer under the claude process. `process.env` from the launching shell wins on collision, so funnel.json sets defaults that the user can still override one-off via the shell.
+The optional top-level `env` is a `Record<string, string>` of environment variables shared by every channel; each channel's own `env` shallow-merges on top. `process.env` from the launching shell wins overall, so funnel.json sets defaults that the user can still override one-off via the shell.
 
 The optional `connectors` array is treated as the source of truth for the declared channel: missing connectors are created, an existing connector that the spec references by token (not by name) is renamed in place, and connectors not declared in the spec are removed on launch. An absent `connectors` field leaves `~/.funnel` alone.
 
-The optional top-level `$schema` points at the hosted JSON Schema (`https://interactive-inc.github.io/open-claude-funnel/funnel.schema.json`) so editors can validate and autocomplete the file. Local alternatives: the file ships in the npm package at `node_modules/@interactive-inc/claude-funnel/schemas/funnel.schema.json`, or generate one in-repo with `fnl schema > funnel.schema.json` and reference it via `./funnel.schema.json`.
+The optional top-level `$schema` points at the JSON Schema so editors can validate and autocomplete the file. The recommended reference for repos with a local install is `./node_modules/@interactive-inc/claude-funnel/funnel.schema.json` — it works without a network round-trip and editors do not need to prompt for trust. The same file is also published at `https://interactive-inc.github.io/open-claude-funnel/funnel.schema.json` (editors usually require explicit trust on first use), and `fnl schema > funnel.schema.json` regenerates a local copy on demand.
 
 Each token field resolves in this order:
 
@@ -178,9 +197,9 @@ fnl profiles <name> as-default               move to the front of the list
 fnl profiles rename <old> <new>
 fnl profiles remove <name>
 
-fnl claude                                   launch using ./funnel.json, or the default profile
-fnl claude --profile <name>                  launch a named profile
-fnl claude --channel <name>                  raw launch (no profile, cwd = current dir)
+fnl claude                                   launch the first channel from ./funnel.json, or the default profile
+fnl claude --channel <name>                  with funnel.json: pick that channel; without: raw launch
+fnl claude --profile <name>                  launch a named profile (ignores funnel.json)
 fnl claude [...]                             positionals and any flag other than -p / --profile / --channel
                                               (e.g. --agent, --resume, -c, --model) pass through to claude
 fnl mcp                                      run as an MCP server (invoked from .mcp.json)
@@ -240,12 +259,16 @@ Connector  =
 Profile    = { name, path, subAgent, channelId }
         named launch preset; the first profile in the list is the default
 
-LocalConfig = { channel, options?, env?, connectors? }
-        per-repo file (funnel.json) checked by `fnl claude` when no --profile / --channel is given
-        options[] is prepended to claude argv (user CLI args override); env merges under process.env;
-        connectors[] declares connectors to materialize on launch (each token field accepts a literal,
-        an env-var reference at `env.<field>` resolved from process.env and ./.env.local, or omission
-        for a TTY prompt persisted to ~/.funnel)
+LocalConfig = { options?, env?, channels: ChannelSpec[] }
+        per-repo file (funnel.json). channels[] required; first entry is default, --channel selects.
+        Top-level options/env are shared defaults merged into each channel.
+
+ChannelSpec = { name, options?, env?, connectors? }
+        options[] is appended to the shared options (user CLI args still come last); env shallow-merges
+        on top of the shared env (process.env wins overall); connectors[] declares connectors to
+        materialize on launch (each token field accepts a literal, an env-var reference at
+        `env.<field>` resolved from process.env and ./.env.local, or omission for a TTY prompt
+        persisted to ~/.funnel)
 
 Settings   = { channels[], profiles[] }                 → ~/.funnel/settings.json
 ```