agent-trellis 0.14.1 → 0.15.1

package/docs/architecture.md

@@ -10,8 +10,8 @@ required reading for that.
 
 ```
 ┌─────────────────────────────────────────────────────────┐
-│  Trellis canonical source  (~/.trellis — global only, see  │
-│  "Global vs. workspace scope" below)                        │
+│  Trellis canonical source  (~/.trellis global + <repo>/.agents,     │
+│  see "Global vs. workspace scope" below)                            │
 │  instructions · skills · agents · mcp/servers.yaml ·      │
 │  memories · secrets policy                                 │
 └───────────────┬─────────────────────────────────────────┘
@@ -19,8 +19,8 @@ required reading for that.
         ┌───────┼────────┬─────────────┬──────────────┐
         ▼                ▼             ▼              ▼
    Claude Code         Codex          Kiro            pi          Kimi Code       ZCode
-  (symlink adapter) (incremental   (symlink adapter) (bridge
-                     TOML writer)                    extension)
+  (symlink adapter) (incremental   (symlink adapter) (native
+                     TOML writer)                    mcp.json)
 ```
 
 Trellis owns exactly one thing: **the canonical source, and the generators
@@ -56,19 +56,77 @@ Aligned to the `.agents Protocol` draft, extended where the draft is silent:
 
 ## Global vs. workspace scope
 
-**Global only, for now.** Trellis manages `~/.trellis` — one canonical
-source per machine, applied to that machine's six supported agents. It does not yet
-read or merge a project-local `.trellis/` in a specific repo.
+Two layers, both canonical: `~/.trellis` per machine (global) and
+`<repo>/.agents/` per project (workspace). A repo opts in by containing
+`.agents/`; `trellis sync` discovers the nearest ancestor `.agents/`
+walking up from the cwd (`findWorkspaceRoot` in `src/lib/workspace.ts` —
+`~/` itself is never picked up as a workspace root) and merges the two
+layers. Outside any workspace the plan is byte-identical to the old
+global-only behavior; `--global-only` opts out explicitly.
 
-The `.agents Protocol` draft (see `research.md`) describes a two-layer
-merge — global defaults, workspace overrides on top, closest wins. That
-model is a reasonable target eventually, but it's explicitly **out of
-scope until a later phase**: it adds real complexity (merge precedence,
-per-project drift, a second place secrets policy has to be checked) that
-isn't justified before the single-layer global case is solid. Don't build
-workspace resolution ahead of that decision — if you find yourself adding
-a `root?: string` parameter or precedence logic to `loadCanonicalSource`,
-that's scope creep against this section, not a natural extension.
+```
+.agents/
+├── config.json             # { "version": 1, mcp.servers } — the same
+│                           # snake_case schema and validator as
+│                           # mcp/servers.yaml; one schema, one validator
+├── AGENTS.md               # workspace instructions
+├── skills/<name>/SKILL.md
+└── .trellis-rendered.json  # Trellis's ownership manifest — committable;
+                            # what a fresh clone re-attaches through
+```
+
+Merge semantics (`src/lib/workspaceMerge.ts`): workspace wins by ID for
+MCP servers and skills; `enabled: false` tombstones a global entry for
+this project only; instructions are not content-merged (a workspace
+`AGENTS.md` stands on its own layer). Provenance and the
+shadowed/tombstoned lists ride on the canonical source so `trellis
+doctor` can attribute every entry to its layer.
+
+Delivery is layer-preserving — Trellis never re-renders global content
+into project files. Global entries go to the agents' user-level paths as
+before; workspace entries go to project-level native paths (`.mcp.json`,
+`.codex/config.toml`, `.kiro/settings/mcp.json`, `.pi/mcp.json`,
+`.kimi-code/mcp.json`, `zcode.json`/`.zcode/config.json`). The agents
+then layer natively: five of six resolve project-over-user; zcode
+resolves same-name MCP conflicts user-first, so a shadowing workspace
+server gets an explicit sync warning instead of a silent no-op. Skills
+are *copied* (not symlinked — rendered artifacts must be committable and
+work without symlink support) into `.claude/skills/` and `.kiro/skills/`
+with digest-based drift detection, while Codex/pi/Kimi read
+`.agents/skills/` natively. Instructions render as marker-headed copies:
+root `AGENTS.md` for Codex/pi/Kimi and `.kiro/steering/
+trellis-workspace.md` for Kiro; Claude's `CLAUDE.md` is never written
+(v1 limitation — `migrate --workspace` is the path for absorbing a
+hand-written one).
+
+Two invariants make the workspace layer safe to commit:
+
+- **No secrets in the repo.** Workspace `config.json` rejects
+  credential-shaped literals at load (the same `reject_patterns` as the
+  global secrets policy) and accepts only `${VAR}` references; rendered
+  artifacts likewise carry references, never resolved values. Secret
+  values live in the machine-local store (`secrets.policy.yaml`'s
+  `env_file`) and are re-established per machine —
+  `migrate --workspace` extracts any literal it finds in a hand-written
+  project file into that store (and flags git-tracked plaintext with a
+  rotation advisory).
+- **Ownership travels with the repo.** `.agents/.trellis-rendered.json`
+  records what Trellis rendered per agent per server; an entry present
+  in an agent's file but absent from the manifest is user-authored and
+  never overwritten. Because the manifest is committed, a fresh clone —
+  or a copied directory — re-attaches cleanly instead of
+  conflict-guarding on its own committed artifacts.
+
+`trellis sync --check` computes the identical plan with zero writes and
+exits non-zero on drift — the CI freshness gate for committed artifacts.
+Existing hand-written project config is adopted with
+`trellis migrate --workspace`: it scans all six agents' project-level
+paths plus the root `AGENTS.md`, classifies every find (create /
+already-managed / identical-to-global / skip-local / skip-unsupported /
+conflict / extract-secret), refuses the whole run on unresolved
+conflicts, then imports and re-renders inside a single backup session so
+one `trellis rollback` restores originals and removes generated
+`.agents/` content.
 
 ## Private / agent-specific capabilities
 
@@ -163,17 +221,19 @@ populates `~/.pi/agent/skills` on its own. (This corrects an earlier,
 pre-P0 assumption that pi needed "no adapter" for skills/instructions;
 that was written before pi's actual global discovery directory was
 confirmed, when it wasn't yet known whether canonical skills would ever
-reach it without one.) MCP is the one place pi is genuinely different: it
-needs a real bridge either way, but which shape depends on `mcp.hub`:
-without it, the bridge extension opens N `@modelcontextprotocol/sdk` stdio
-clients (one per server) and registers each one's tools through pi's
-`registerTool` API; with `mcp.hub` set, it opens exactly one HTTP client to
-the hub instead — meaningfully less code and one fewer class of failure
-(N processes to keep alive vs. one connection). This is the one piece of
-the project that is an agent runtime extension, not a config generator,
-regardless of hub mode.
-
-The pi bridge symlink follows the currently executing Trellis installation.
+reach it without one.) MCP on pi ≥ 1.1.0 is native: the adapter merges
+entries into `~/.pi/agent/mcp.json` — a `trellis mcp-gateway --agent pi`
+stdio entry under gateway mode (or `mcp-runtime` under runtime delivery),
+a single hub-URL entry under hub mode, direct entries otherwise — with
+agent-owned OAuth servers written as bare `{url}` entries that
+`pi mcp login` authorizes (an optional canonical `auth.client_name`
+renders as `oauth.clientName` for providers that gate dynamic client
+registration by name, e.g. Figma). On pi < 1.1.0 the legacy bridge
+extension (`src/pi-bridge/`, symlinked into `~/.pi/agent/extensions/`) is
+still planned instead; it is deprecated and scheduled for removal.
+
+The legacy bridge symlink follows the currently executing Trellis
+installation.
 When switching from a checkout to a global package (or between installation
 roots), sync can repair an outside-root link only if its target ends in
 `dist/pi-bridge/bundle.js` and its bytes match the current bridge bundle.
@@ -211,12 +271,14 @@ to the code writing one entry that points at it.
 - Every adapter writes ONE entry instead of N. This is most of the value:
   adding a new backend server means editing wherever the hub's own config
   lives (this project doesn't prescribe that either) and never touching
-  any of the five agents' configs or restarting them, if the hub supports
+  any of the six agents' configs or restarting them, if the hub supports
   live reload (mcp-hub does, via SSE).
 - The collision check against `known_host_injected` (docs/research.md
   §"Codex — three hard constraints") shrinks to checking one name instead
   of N, since there's nothing else locally defined to collide with.
-- pi's bridge (P4) becomes one HTTP client instead of N stdio clients.
+- pi gets one hub-URL entry in its native mcp.json instead of N direct
+  entries (pre-1.1.0: the legacy bridge opens one HTTP client instead of N
+  stdio clients).
 
 **What doesn't change:** the boundary with mirasim (docs/research.md §3)
 is unaffected — `mcp.hub`, self-hosted or not, only ever carries the
@@ -253,11 +315,11 @@ there (not silently dropped) while still reaching every other agent.
 
 **Real OAuth** (browser redirect, short-lived access token, refresh
 token) was, for most of this project's life, deliberately not built:
-all three native-config agents already have their own working flow —
+all the native-config agents already have their own working flow —
 Claude Code's `claude mcp add --client-id/--client-secret/--callback-port`,
 Codex's `codex mcp login`/`logout` pair, Kiro's `oauth`/`oauthScopes`
-fields — and pi, whose bridge is Trellis's own code, simply couldn't
-reach such a server at all.
+fields, pi's `pi mcp login` (native since pi 1.1.0; the legacy bridge
+could not reach such a server at all).
 
 Gateway mode does not automatically take ownership of OAuth servers. Mark a
 server explicitly with `auth: oauth` (or `trellis mcp set <name> --auth oauth`)
@@ -400,7 +462,7 @@ Trellis MCP Runtime
   │   ├─ SkillProvider   (read/search canonical skills)
   │   ├─ RuntimeMemoryProvider
   │   │   └─ CanonicalMemoryProvider (read-only canonical Markdown)
-  │   └─ StatusProvider  (future read-only diagnostics)
+  │   └─ StatusProvider  (read-only diagnostics)
   └─ UpstreamProvider
       └─ existing GatewayBackend / future RemoteBackend
 ```
@@ -542,26 +604,26 @@ development, not in CI, not for a "quick manual check." A bug in an adapter
 that patches TOML in place is exactly the kind of thing that corrupts a
 real config file if it's tested against one.
 
-**Exception: pi.** This rule protects real state a person depends on — the
-other three agents' adapters patch that state in place (symlinks over real
-directories, in-place TOML/JSON edits). pi's adapter never does: skills/
-instructions are the same symlink-or-noop regardless of machine, and the
-MCP bridge (P4) is a single already-symlinked extension file that reads a
-separate, Trellis-owned `servers.yaml` rather than writing into anything pi
-itself depends on. A temporary, narrowly-scoped `~/.trellis/mcp/servers.yaml`
-(deleted afterward) plus a real `pi -p` run therefore carries none of the
-corruption risk this section exists to prevent, and it's the only way to
-observe pi's actual extension-loading behavior on *this* installed pi/jiti
-version — `docker/pi-sandbox.Dockerfile` verifies the same jiti-tolerance in
-general (P4's own acceptance criteria), but doesn't stand in for a
-spot-check against a specific real installation. Real-machine verification
-of pi specifically is therefore permitted, not a hard-rule violation — the
-other three agents are not exempted.
+**Exception: pi (bridge era, kept as history).** This rule protects real
+state a person depends on — the other agents' adapters patch that state in
+place (symlinks over real directories, in-place TOML/JSON edits). In the
+bridge era pi's adapter never did: skills/instructions were the same
+symlink-or-noop regardless of machine, and the MCP bridge (P4) was a
+single already-symlinked extension file that read a separate,
+Trellis-owned `servers.yaml` rather than writing into anything pi itself
+depended on, so a temporary, narrowly-scoped `~/.trellis/mcp/servers.yaml`
+plus a real `pi -p` run carried none of the corruption risk this section
+exists to prevent. Since pi 1.1.0 the adapter merges
+`~/.pi/agent/mcp.json` in place like every other adapter, so **this
+exception no longer applies to MCP config** — real-machine pi verification
+(the v0.14.0 managed migration, for example) follows the standard
+discipline: backup, dry-run, then a scoped apply. The paragraph is kept
+because the bridge extension still exists as the pre-1.1.0 fallback.
 
 Verification happens against an isolated environment instead: a scratch
 `$HOME` (or a container with one mounted) populated with synthetic
 per-agent config that looks like the real thing but is expendable — created
-fresh, asserted against, thrown away. `docs/implementation-plan.md`'s P1
+fresh, asserted against, thrown away. `docs/archive/implementation-plan.md`'s P1
 acceptance criteria already describes this shape ("point at a scratch
 `$HOME`... run `trellis sync skills`... confirm zero findings"); this
 section exists to make it a project-wide rule that every later phase's

package/docs/getting-started.md

@@ -496,8 +496,8 @@ Trellis resolves `CODEX_HOME` when set, otherwise `~/.codex`, and reads only
 the Memory directory. `AGENTS.md`, `session_index.jsonl`, sessions,
 credentials, and plugin state are never treated as memory.
 
-**MCP servers** (claude-code, kiro, codex — not pi, which has no static
-MCP config to read at all) migrate the same way, into
+**MCP servers** (claude-code, kiro, codex, kimi-code, zcode — not pi, whose
+mcp.json migrate-in is not implemented) migrate the same way, into
 `~/.trellis/mcp/servers.yaml`:
 
 ```
@@ -821,6 +821,69 @@ automatically, so `trellis rollback` can undo the whole run later — see
 [`trellis rollback`](#trellis-rollback--undoing-a-syncmcp-synconboard-run)
 below.
 
+## Workspace scope — per-project config in the repo
+
+Everything above manages `~/.trellis`, one canonical source per machine.
+A project can carry its own layer in the repo itself, under `.agents/` —
+committable by design, shared with every teammate and agent that checks
+it out:
+
+```
+$ cd your-repo
+$ trellis init --workspace     # scaffold .agents/ (fill-missing-only)
+```
+
+```
+.agents/
+├── config.json             # { "version": 1, mcp.servers } — same schema
+│                           # as ~/.trellis/mcp/servers.yaml
+├── AGENTS.md               # workspace instructions
+├── skills/<name>/SKILL.md
+└── .trellis-rendered.json  # Trellis's ownership manifest — commit it too
+```
+
+Edit those files directly, or use the CLI with `--workspace`
+(`trellis mcp add <name> --workspace`, `trellis skill add <name> --from ... --workspace`).
+Then, from anywhere inside the repo:
+
+```
+$ trellis sync               # global layer + workspace layer together
+$ trellis sync --global-only # global only, even inside a workspace
+```
+
+The workspace layer wins on ID conflicts with the global one (and
+`enabled: false` in `config.json` tombstones a global server for this
+project). Rendered artifacts — `.mcp.json`, `.codex/config.toml`,
+`.pi/mcp.json`, skill copies under `.claude/skills/`, the marker-headed
+root `AGENTS.md`, … — are meant to be **committed** alongside `.agents/`.
+They contain only `${VAR}` references, never secret values, and
+`.agents/config.json` itself refuses credential-shaped literals at load;
+actual values live in each machine's local secret store and are
+re-established per machine. CI keeps the committed artifacts honest:
+
+```
+$ trellis sync --check       # zero writes; exit 1 naming any stale file
+```
+
+Already have hand-written project config (a `.mcp.json`, a
+`.codex/config.toml`, a root `AGENTS.md`)? Absorb it instead of
+rewriting by hand:
+
+```
+$ trellis migrate --workspace --dry-run   # preview the classified plan
+$ trellis migrate --workspace             # import + re-render, one
+                                          # backup session — `trellis
+                                          # rollback` undoes the whole thing
+```
+
+The scanner inventories all six agents' project-level paths, skips
+`*.local.*` files unread, extracts plaintext secrets into the global
+secret store as `${VAR}` references (with a rotation advisory when the
+literal was git-tracked), and refuses the run on unresolved conflicts —
+pick a side with `--choose name=agentId`, or import an
+identical-to-global entry as an intentional shadow with
+`--dedup override`.
+
 ## `trellis mcp sync`
 
 Distributes `~/.trellis/mcp/servers.yaml` to every **managed** agent's
@@ -915,9 +978,13 @@ stay direct while ordinary remote servers remain shared through the gateway.
 
 ### `trellis mcp auth <server-name>`
 
-For a remote (`http`/`sse`) server marked `auth: oauth`, native Agents should
-use their own login command. Pi's direct bridge path can be authorized once
-through Trellis:
+Authorization ownership is explicit per server (the full model is
+[`mcp-authorization-ownership.md`](mcp-authorization-ownership.md)):
+**agent-owned** OAuth servers (plain `auth: oauth`) are authorized by the
+Agent's own login command — `claude mcp` / `codex mcp login` /
+`pi mcp login <name>` — and Trellis never touches their tokens. **Trellis-owned**
+servers (`auth: { kind: oauth, owner: trellis }`) connect through the
+gateway/runtime on a credential Trellis holds, authorized once through:
 
 ```
 $ trellis mcp auth notion-remote
@@ -929,17 +996,19 @@ This opens your browser, completes the flow, and stores the result 0600
 under `~/.trellis/mcp/oauth/` — never in `servers.yaml`, so canonical
 stays safe to read, diff, and commit.
 
-Run it once per server when Pi's direct bridge owns the OAuth connection.
-After that the bridge refreshes the token silently whenever it expires; it
-never opens a browser and never prompts, because it is spawned by an agent
-with no terminal attached. Re-running
+Run it once per Trellis-owned server. After that the gateway refreshes the
+token silently whenever it expires; it never opens a browser and never
+prompts, because it is spawned by an agent with no terminal attached.
+Re-running
 this command when the stored token is still valid does nothing (`--force`
 overrides); when it has expired but is renewable, it refreshes without a
-browser.
+browser. `trellis mcp renew` does the same non-interactively for every
+Trellis-owned server that can be renewed without a browser.
 
-If a Pi direct OAuth server has no stored credential, the bridge skips that
-one server and keeps serving every other — it does not fail to start. Native
-Agents report the same direct entry as requiring their own authorization.
+If a Trellis-owned OAuth server has no stored credential, the gateway skips
+that one server and keeps serving every other — it does not fail to start.
+Agent-owned servers in the same route are unaffected: the Agent's own client
+reports them as requiring its own authorization.
 
 An Agent can call the read-only `trellis.mcp.status` Runtime tool to explain
 this partial state to the user. It reports unavailable or authorization-
@@ -1083,7 +1152,10 @@ $ trellis doctor
 ```
 
 Read-only. Scans all six agents' current state and reports drift —
-mismatched skill content across agents, wrong-case skill files, and (with
+mismatched skill content across agents, wrong-case skill files, OAuth
+credential health for Trellis-owned servers (the same read-only
+classification as `trellis mcp renew` and the `trellis.mcp.status` Runtime
+tool, so the three never disagree), and (with
 `--probe-mcp`) whether each configured MCP server actually handshakes.
 Safe to run any time; nothing here writes anything.
 

package/docs/mcp-oauth-matrix.md

@@ -41,7 +41,18 @@ per-provider list, is what Trellis commits to.
 | Notion | DCR-open | `client_id` from DCR | Same | Medium |
 | Linear | DCR-open | `client_id` from DCR | Same | Medium |
 | Cloudflare | DCR-open | `client_id` from DCR | Same | Medium |
-| Figma | Allowlist | Provider-published `client_id`, supplied by the user | Registration refused with `unauthorized_client` — observed directly, and the reason this change exists | High |
+| Figma | DCR gated by client_name | `client_id` from DCR, issued only when the self-asserted `client_name` is on Figma's beta allowlist | Registration with an unknown name (e.g. `pi`, `Trellis`) refused with a bare 403; `Claude Code` succeeds — observed directly 2026-10-11 (oauth-client-name) | High |
+
+**Figma, updated.** The row above supersedes an earlier classification of
+Figma as plain Allowlist ("no self-service path"). What Figma actually gates
+is the `client_name` a client asserts at registration, not possession of a
+pre-issued `client_id`: the same registration endpoint answers 403 for
+`pi`/`Trellis` and 200 for an allowlisted name, independent of User-Agent.
+The working path is therefore agent-owned auth plus a declared canonical
+`auth.client_name` (rendered into the agent's own registration, e.g. pi's
+`oauth.clientName`). Trellis-hosted DCR hardcodes `client_name: "Trellis"`
+(`src/lib/oauth/flow.ts`) and would be refused for Figma until Trellis's own
+name is allowlisted or the field is wired through there too.
 
 **On confidence.** "High" means the behavior was observed directly against the
 live provider and the failure (or success) is reproducible from this

package/docs/overview.zh-CN.md

@@ -71,6 +71,22 @@ Trellis Runtime / Gateway
         └── MCP Runtime ────── Kimi Code / ZCode / 其他 Runtime-first Agent
 ```
 
+### 所有权边界（Ownership boundary）
+
+- `~/.trellis/` 是 canonical source 和策略边界。
+- 各 Agent 的原生目录是投影，不是独立的事实源。
+- Gateway/Runtime 负责连接路由和 Provider 暴露，不接管 Agent 的私有会话。
+- 凭证不进入 canonical YAML，在运行时解析。
+- Runtime Provider 将 Memory、MCP 输出和任务记录视为不可信上下文。
+
+## 投递模式（Delivery modes）
+
+| 模式 | 含义 | 典型场景 |
+|---|---|---|
+| `native` | 将能力投影到 Agent 的原生配置 | 最大化原生兼容性 |
+| `mcp` | 通过 Runtime MCP 边界消费 Trellis 能力 | Kimi Code 等 Runtime-first Agent |
+| `both` | 过渡期同时保留 native 和 Runtime 投递 | 兼容性迁移 |
+
 ## 与相似产品的关系
 
 | 产品/类别 | 主要解决的问题 | Trellis 的区别 |
@@ -79,6 +95,7 @@ Trellis Runtime / Gateway
 | [MCP Router](https://github.com/mcp-router/mcp-router) | 桌面 MCP 管理、Workspace、Provider 和日志 | 可作为 Trellis 的导入源或上游；Trellis 自己维护 canonical MCP 状态 |
 | [MetaMCP](https://github.com/metatool-ai/metamcp) / [mcp-hub](https://github.com/ravitemer/mcp-hub) | MCP 聚合和统一入口 | Trellis 额外负责不同 Agent 的 native 适配、生命周期和安全同步 |
 | [OpenViking](https://github.com/volcengine/OpenViking) | Memory、资源和 Skill 的上下文数据库 | Trellis 可将其接入 Memory/Context Provider，作为底层上下文服务 |
+| Agent 编排平台 | 启动 worker、调度任务、协调执行 | Trellis 目前只提供持久化任务交接记录和租约，不隐式远程执行 Agent；执行层是明确的未来方向 |
 
 ## 术语约定
 

package/docs/research.md

@@ -3,6 +3,13 @@
 Surveyed 2026-09-11. This is why Trellis is a thin orchestration layer, not a
 from-scratch rebuild of anything below.
 
+> **Currency note (2026-10-11, doc governance):** this is a research/history
+> document — sections are dated snapshots of what was true when surveyed, and
+> some "decided not to build" / "future direction" passages have since been
+> implemented (gateway/runtime, skills-over-MCP, pi native MCP). Where a
+> section conflicts with [`architecture.md`](architecture.md), architecture.md
+> is current. Inline markers flag the known-superseded spots.
+
 ## Rules / skills sync (crowded — don't rebuild)
 
 | Project | Covers | Kiro | pi | MCP | Memory | Secrets |
@@ -50,7 +57,11 @@ specifies).
 | [mcp-router](https://github.com/mcp-router/mcp-router) | — | Desktop app + CLI, Sustainable Use License | Already deployed in this environment; token-based, has a GUI. **First-hand incident**: its `MCPR_TOKEN` existed in three different values across `secrets.env`/`config.toml`/`kiro/mcp.json` simultaneously, one silently invalid — see below |
 
 Decision: Trellis still does not implement aggregation/routing logic
-itself. It generates native MCP config for each agent directly — that's
+itself. *(Superseded 2026-10: gateway mode and the Trellis MCP Runtime now
+do exactly this in-process — see architecture.md "Gateway mode" and the
+BuiltinRegistry/UpstreamProvider diagram; the hub-mode support described
+below remains as the external-endpoint option.)* It generates native MCP
+config for each agent directly — that's
 what actually needed solving, since none of the above touch Kiro/pi/Codex's
 TOML format. But it now natively *supports* routing every agent through a
 single external endpoint instead of N direct definitions ("hub mode," see
@@ -68,6 +79,10 @@ before hub mode existed as a documented option.
 
 ### MCP Runtime / built-in capability direction — confirmed architecture
 
+*(Implemented: SkillProvider, RuntimeMemoryProvider and StatusProvider ship
+in v0.12–v0.14 exactly in this shape — this section is the pre-implementation
+confirmation, kept as the design's origin.)*
+
 The next abstraction is broader than a skill-only MCP server. MCP defines
 tools, resources, and prompts with different control models, so a Trellis
 runtime should host a registry of providers rather than make every new
@@ -93,6 +108,11 @@ scripts by default.
 
 ### Local Claude Code / pi dogfood — 2026-09-18
 
+*(Bridge-era snapshot: "the packaged MCP bridge" below refers to the pi
+bridge extension, retired as the default delivery by pi 1.1.0 native MCP in
+v0.14.0. The findings about tool-surface size and route granularity are
+still valid.)*
+
 After an external, credential-minimized host snapshot, the managed set was
 narrowed from all four agents to Claude Code and pi through `trellis manage
 set`. Hashes of Codex and Kiro's relevant native state were identical before
@@ -245,12 +265,14 @@ Reverse-engineered directly from the installed binary
   not supported"` — that era is why the bridge extension below exists.
 - pi's capability surface is **extensions**: JS modules loaded via
   `--extension`/discovery, with a real API (`createExtension`,
-  `registerTool`). Giving pi access to the same MCP servers every other agent
-  uses means writing a bridge extension that spins up
+  `registerTool`). *(Superseded as the default path: since pi 1.1.0, Trellis
+  writes pi's native `mcp.json` directly — trellis-pi-native-mcp-migration,
+  v0.14.0. The bridge extension remains only as the pre-1.1.0 fallback and
+  is scheduled for removal.)* Giving pi access to the same MCP servers
+  every other agent uses meant writing a bridge extension that spins up
   `@modelcontextprotocol/sdk` stdio clients from `mcp.json` and registers
-  their tools through this API. This is the one adapter in Trellis that is
-  genuine code, not config templating — see
-  [`src/adapters/pi/`](../src/adapters/pi).
+  their tools through this API — the one adapter in Trellis that is genuine
+  code, not config templating.
 
 ## Cross-machine / cloud sharing — surveyed 2026-09-15, future direction confirmed
 

package/docs/roadmap.md

@@ -1,10 +1,13 @@
 # Roadmap
 
+*Current release: v0.14.1 (2026-10-11). This file tracks phase-level scope;
+per-release detail lives in [`releases/`](releases/).*
+
 Each phase must ship with a `trellis doctor` check that verifies its own
 claim — no phase is "done" on the strength of a config file existing, only
 on the strength of a passing verification against the real running agent.
 
-See [`implementation-plan.md`](implementation-plan.md) for P1–P4 broken down
+See [`archive/implementation-plan.md`](archive/implementation-plan.md) for P1–P4 broken down
 to file/function level.
 
 **P0 is done and archived** (`openspec/changes/archive/2026-09-12-trellis-doctor-p0/`;
@@ -21,7 +24,7 @@ had a much larger blast radius than "read-only" should mean.
 
 This is the format every later phase uses: one `openspec/changes/<phase>/`
 directory per phase, `openspec new change <name>` → tasks implemented →
-`openspec archive <name>`. `implementation-plan.md`'s P0/P1 sections are
+`openspec archive <name>`. `archive/implementation-plan.md`'s P0/P1 sections are
 kept only as historical notes; don't edit them further.
 
 **P1 is done and archived** (`openspec/changes/archive/2026-09-12-trellis-sync-p1/`;
@@ -933,7 +936,7 @@ tests passing.
 | P1 | ✅ `trellis sync skills` / `trellis sync instructions` — symlink-based distribution to Claude Code, Codex, Kiro, and pi | P0 |
 | P2 | ✅ `trellis mcp sync` — incremental, in-place adapters for Claude Code (JSON merge), Codex (TOML section patch), Kiro (JSON merge); collision check against known host-injected server names | P1 |
 | P3 | ✅ `trellis secrets audit` — scans every adapter's output for literal credential patterns and unexpected env var names, fails non-zero on any hit | P2 |
-| P4 | ✅ pi bridge extension — MCP tool registration via `registerTool`, sourced from the same `mcp/servers.yaml` | P2 |
+| P4 | ✅ pi bridge extension — MCP tool registration via `registerTool`, sourced from the same `mcp/servers.yaml`. **Superseded as the default by v0.14.0** (pi ≥ 1.1.0 native MCP, trellis-pi-native-mcp-migration): the bridge is now the pre-1.1.0 fallback only, and `src/pi-bridge/` is scheduled for removal one release later | P2 |
 | P5 | ✅ `@trellis/sdk` — read-only API over the canonical source, for third-party agents to consume without depending on the CLI | P1–P4 stable |
 | P6 | ✅ Memory: document and wire the `server-memory` default; write the mem0/OpenMemory upgrade guide | P2 |
 | P7 | ✅ Secrets/env management: shared `resolveSecretEnv` + `secrets.policy.yaml`'s `env_file`, pi bridge stops reading raw ambient env, `secrets audit` gains a `missing-env-value` check | P3, P4 |
@@ -957,9 +960,18 @@ tests passing.
 
 | P25 | ✅ Onboard prompt TUI: replaces Trellis's hand-written raw-mode picker and ANSI redraw logic with `@clack/prompts`, preserving non-TTY fallbacks, `--json`, stream-injected tests, stderr-only interactive chrome, and compact agent summaries that show counts instead of enumerating skills. Full-screen TUI runtimes remain out of scope; onboarding stays visible in terminal scrollback | P22 |
 | P26 | ✅ Fine-grained capability selection: item-level skill/MCP/memory selection from a serializable selection file or searchable TUI, per-agent MCP route overrides with direct/gateway/hub precedence, selected-memory sync without implicit native-memory import, and explicit unsupported-reader diagnostics | P17, P21, P22, P25 |
-| P27 | 🚧 Trellis MCP Runtime phase 1 ✅: one provider registry and agent-facing MCP edge; SkillProvider and the read-only CanonicalMemoryProvider expose scoped progressive-disclosure tools/resources, runtime delivery supports native/mcp/both per agent, selected upstream tools mount through the existing GatewayBackend, and doctor checks runtime drift. Remaining: upstream resource/prompt backend, real pi/Kiro model smoke, and real Claude model smoke (Claude remains intentionally deferred) | P21, P25, P26 |
-| P28 | 🚧 Kimi Code Runtime-first adapter: Kimi is recognized as a managed Agent, receives one deferred `trellis` Runtime entry in `~/.kimi-code/mcp.json`, and `trellis kimi` isolates native Skill discovery for Runtime-only delivery. The Runtime Skill is available through SkillProvider; remaining: real Kimi model-session smoke and upstream resource/prompt consumption | P27 |
+| P27 | 🚧 Trellis MCP Runtime phase 1 ✅: one provider registry and agent-facing MCP edge; SkillProvider and the read-only CanonicalMemoryProvider expose scoped progressive-disclosure tools/resources, runtime delivery supports native/mcp/both per agent, selected upstream tools mount through the existing GatewayBackend, upstream **resources** ship (v0.12.0), and doctor checks runtime drift. Remaining: upstream **prompts** backend, real pi/Kiro model smoke, and real Claude model smoke (Claude remains intentionally deferred) | P21, P25, P26 |
+| P28 | 🚧 Kimi Code Runtime-first adapter: Kimi is recognized as a managed Agent, receives one deferred `trellis` Runtime entry in `~/.kimi-code/mcp.json`, and `trellis kimi` isolates native Skill discovery for Runtime-only delivery. The Runtime Skill is available through SkillProvider; upstream resources ship (v0.12.0). Remaining: real Kimi model-session smoke and upstream prompt consumption | P27 |
 | P29 | ✅ ZCode Runtime-first adapter: `zcode` is a managed Agent with profile-aware static configuration (`~/.zcode/cli/config.json` for official profiles and `setting.json` for the local community CLI), a single owned Runtime MCP entry, scoped-Skill isolation, safe instruction/MCP migration, doctor/onboarding coverage, and public-CLI chat/delegation parsing for ZCode's `response`/`sessionId` stream envelope. Desktop-private runtime paths are never process-host entry points. | P27, P28 |
+| P30 | ✅ Workspace scope: a second canonical layer in the repo itself, `<repo>/.agents/` (`config.json` reusing `servers.yaml`'s exact snake_case schema + validator, `AGENTS.md`, `skills/`), discovered by walking up from the cwd (`~/` never counts) and merged workspace-wins-by-ID with `enabled: false` tombstones. Delivery is layer-preserving — global content never re-renders into project files; workspace entries go to all six agents' project-level native paths, with skills *copied* (digest-drift-detected) for Claude/Kiro, native `.agents/skills/` reads for Codex/pi/Kimi, marker-headed root `AGENTS.md` for Codex/pi/Kimi + Kiro steering, and a zcode reverse-precedence warning (its MCP resolves user-first). Committable by design: `config.json` refuses credential-shaped literals at load, rendered artifacts carry only `${VAR}` references, and the committed `.agents/.trellis-rendered.json` ownership manifest is what lets a fresh clone or copied directory re-attach instead of conflict-guarding on its own artifacts. CLI: `init --workspace`, `sync` auto-include with `--check` as the CI freshness gate and `--global-only` as the escape hatch, `mcp add`/`skill add --workspace`, and `migrate --workspace` — a six-path scanner + seven-way classifier (create / already-managed / identical-to-global / skip-local / skip-unsupported / conflict / extract-secret) that refuses wholesale on unresolved conflicts, extracts plaintext secrets into the global store (git-tracked literals get a rotation advisory), seeds manifest ownership so the cascade render adopts rather than conflicts, and runs inside one backup session so a single `rollback` restores every original | P2, P24 |
+
+**Shipped since P29 without a phase number** (detail in `docs/releases/`):
+v0.13.0 — OAuth credential operability (`trellis mcp renew`, doctor OAuth
+health, honest credential status in `trellis.mcp.status`, browser callback
+page). v0.14.0 — pi native MCP delivery (pi ≥ 1.1.0 `mcp.json` writes,
+bridge retirement in the same sync; supersedes P4's default path).
+v0.14.1 — canonical `auth.client_name` for providers that gate OAuth dynamic
+client registration by client name (Figma).
 
 **Cross-machine / cloud sharing — confirmed future direction, not yet
 scoped as a phase.** Surveyed 2026-09-15 (`docs/research.md`'s "Cross-

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-trellis",
-  "version": "0.14.1",
+  "version": "0.15.1",
   "description": "A unified Code Agent Runtime for Skills, MCP, Memory, and shared instructions across Claude Code, Codex, Kiro, pi, Kimi Code, and ZCode.",
   "license": "MIT",
   "author": "Paul Leo",