agent-trellis 0.6.3 → 0.8.0

package/dist/commands/migrate.js

@@ -4,25 +4,53 @@
  * Pure `collectMigratePlan` / effectful `applyMigratePlan`, same
  * plan-then-apply split every adapter already uses.
  */
-import { cpSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { cpSync, existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
-import { join } from "node:path";
+import { dirname, join } from "node:path";
 import * as claudeCodeProbe from "../probes/claude-code.js";
 import * as codexProbe from "../probes/codex.js";
 import * as kiroProbe from "../probes/kiro.js";
 import * as piProbe from "../probes/pi.js";
+import * as kimiCodeProbe from "../probes/kimi-code.js";
 import { AGENTS_MD_TEMPLATE } from "./init.js";
 import { decideDirImport } from "../lib/dirEquals.js";
 import { deepEqual } from "../lib/deepEqual.js";
-import { readClaudeCodeMcpDefs, readCodexMcpDefs, readKiroMcpDefs, resolvedEnvTextMap } from "../lib/mcpMigrateRead.js";
+import { readClaudeCodeMcpDefs, readCodexMcpDefs, readKiroMcpDefs, readKimiCodeMcpDefs, resolvedEnvTextMap } from "../lib/mcpMigrateRead.js";
+import { parseDotenv, writeLocalSecretValue } from "../lib/secretEnv.js";
 import { findLiteralSecret } from "../adapters/mcpPlan.js";
-import { loadCanonicalSource, upsertServerYaml } from "../core/canonical.js";
+import { ensureGitignoreEntry, ensureShellEnvSource, loadCanonicalSource, upsertServerYaml, writeSecretsPolicyExtraction } from "../core/canonical.js";
 import { ALL_AGENTS } from "../core/types.js";
+import { discoverNativeMemory, MAX_NATIVE_MEMORY_BYTES, renderNativeMemory } from "../lib/nativeMemory.js";
+/** Where a `staticEnv` literal secret's real value goes when
+ * `secrets.policy.yaml` doesn't already have its own `env_file`
+ * (trellis-migrate-extract-static-env-secrets design.md D3) — a sibling
+ * of `servers.yaml`, so "the mcp stuff" stays one directory rather than
+ * a second, disconnected location. `~`-form for what gets written into
+ * `secrets.policy.yaml` itself (portable across machines); resolved form
+ * for real file I/O. */
+const DEFAULT_LOCAL_SECRETS_ENV_FILE_TILDE = "~/.trellis/mcp/servers.local.env";
+function defaultLocalSecretsEnvFilePath(homeDir) {
+    return join(homeDir, ".trellis", "mcp", "servers.local.env");
+}
+/** Picks the rc file `ensureShellEnvSource` writes its one pointer block
+ * into, from `$SHELL` — zsh and bash are the only shells Trellis's own
+ * dev/CI machines and this feature's real-machine dogfooding have ever
+ * exercised; anything else falls back to `.profile`, the POSIX-sh default
+ * every shell still sources one way or another. */
+function defaultShellRcPath(homeDir) {
+    const shell = process.env.SHELL ?? "";
+    if (shell.includes("zsh"))
+        return join(homeDir, ".zshrc");
+    if (shell.includes("bash"))
+        return join(homeDir, ".bash_profile");
+    return join(homeDir, ".profile");
+}
 const PROBES = {
     "claude-code": (homeDir) => claudeCodeProbe.probe(homeDir),
     codex: (homeDir) => codexProbe.probe(homeDir),
     kiro: (homeDir) => kiroProbe.probe(homeDir),
     pi: (homeDir) => piProbe.probe(homeDir),
+    "kimi-code": (homeDir) => kimiCodeProbe.probe(homeDir),
 };
 /** pi has no static MCP config to read at all (roadmap.md P14/
  * trellis-migrate-mcp-servers) — deliberately absent, not an oversight;
@@ -31,6 +59,7 @@ const MCP_READERS = {
     "claude-code": readClaudeCodeMcpDefs,
     kiro: readKiroMcpDefs,
     codex: readCodexMcpDefs,
+    "kimi-code": readKimiCodeMcpDefs,
 };
 function planSkill(name, sourceDir, isSymlink, caseCorrect, canonicalDir) {
     if (isSymlink) {
@@ -91,6 +120,32 @@ function planInstructions(snapshot, canonicalAgentsMd) {
         remediation: `compare \`~/.trellis/agents.md\` against ${snapshot.instructionsFile.path} and either merge by hand or delete whichever copy you don't want to keep`,
     };
 }
+function planNativeMemoryCandidate(candidate, homeDir) {
+    const targetPath = join(homeDir, ".trellis", "memories", `${candidate.targetName}.md`);
+    const rendered = renderNativeMemory(candidate);
+    if (!existsSync(targetPath)) {
+        return {
+            kind: "memory",
+            name: candidate.targetName,
+            action: "create",
+            detail: `will import ${candidate.displayName} from ${candidate.sourceAgent} native memory`,
+            memorySourcePath: candidate.sourcePath,
+            memorySourceId: candidate.sourceId,
+            memoryTargetPath: targetPath,
+        };
+    }
+    const current = readFileSync(targetPath, "utf8");
+    if (current === rendered) {
+        return { kind: "memory", name: candidate.targetName, action: "already-migrated", detail: "canonical memory is byte-identical" };
+    }
+    return {
+        kind: "memory",
+        name: candidate.targetName,
+        action: "conflict",
+        detail: `canonical memories/${candidate.targetName}.md already has different content — resolve by hand`,
+        remediation: `compare the canonical file with ${candidate.sourcePath} and decide which memory to keep before re-running migration`,
+    };
+}
 /**
  * True when `existing` and `def` differ ONLY in which of `env`/
  * `envAliases`/`staticEnv` an env value is filed under, while every
@@ -110,24 +165,119 @@ export function isSafeReclassification(existing, def) {
         return false;
     return deepEqual(resolvedEnvTextMap(existing), resolvedEnvTextMap(def));
 }
-function planMcpServer(name, def, existing) {
-    // Checked first, before any comparison against `existing`: a source
-    // agent's real config holding a literal credential must never reach
-    // canonical at all, regardless of whether canonical already has
-    // something for this name. `resolveMcpPlan`'s own guard only protects
-    // the sync-OUT boundary (canonical -> agent) — this is the matching
-    // guard for the migrate-IN boundary (agent -> canonical), the gap a
-    // real `mcp-router` token in a real `kiro` config exposed.
-    const secretLabel = findLiteralSecret(def);
-    if (secretLabel) {
+/** Moves `sourceKey` out of `staticEnv` into a name-only `env` reference
+ * under `varName` — the def this produces never holds the literal that
+ * triggered extraction (trellis-migrate-extract-static-env-secrets
+ * design.md D7), safe to upsert into canonical or appear in any output.
+ * `sourceKey` and `varName` differ under D11's `TRELLIS_<SERVER>_<KEY>`
+ * naming scheme — the source dict key is not, in general, the name the
+ * value ends up referenced by. */
+function extractedMcpDef(def, sourceKey, varName) {
+    const remainingStaticEnv = { ...(def.staticEnv ?? {}) };
+    delete remainingStaticEnv[sourceKey];
+    const result = { ...def, env: [...(def.env ?? []), varName] };
+    if (Object.keys(remainingStaticEnv).length > 0) {
+        result.staticEnv = remainingStaticEnv;
+    }
+    else {
+        delete result.staticEnv;
+    }
+    return result;
+}
+/** Uppercase, non-alphanumeric runs collapsed to a single `_`, no leading
+ * or trailing `_` — the one sanitization every synthesized name piece
+ * shares (design.md D11), so `mcp-router` becomes `MCP_ROUTER` and a
+ * header key like `X-Api-Key` becomes `X_API_KEY`. */
+function sanitizeEnvNamePart(s) {
+    return s.toUpperCase().replace(/[^A-Z0-9]+/g, "_").replace(/^_+|_+$/g, "") || "X";
+}
+/** `TRELLIS_<SERVER>_<KEY>` — the project-wide prefix rules out a
+ * collision with anything already in the user's own environment or
+ * another tool's convention; the server-name segment rules out two
+ * Trellis-managed servers colliding with each other over the same key
+ * (design.md D11). Deliberately never the bare source key alone (what
+ * the code shipped with initially, and what an already-extracted server
+ * predating this scheme still uses — `planStaticEnvExtraction`'s own
+ * value-based lookup is what keeps recognizing those, not this
+ * function). */
+function synthesizeVarName(serverName, key) {
+    return `TRELLIS_${sanitizeEnvNamePart(serverName)}_${sanitizeEnvNamePart(key)}`;
+}
+/**
+ * Only reached when `findLiteralSecret` matched inside `staticEnv` —
+ * `key` is that field's own dict key (design.md D1). Reads the target
+ * local-secrets file read-only to decide the outcome; never writes
+ * anything itself (planning stays dry-run-safe) and never puts the real
+ * value on the returned item (design.md D9) — only used here, in memory,
+ * to compare against what's already on disk.
+ *
+ * The variable name a *new* extraction is filed under is synthesized
+ * (design.md D11's `TRELLIS_<SERVER>_<KEY>`, not the bare `key`) — but an
+ * already-extracted server may have been extracted before this scheme
+ * existed, under the bare key or any other name. Rather than hardcoding
+ * "the old scheme was the bare key", this looks up `existing.env` by
+ * VALUE: any name already in canonical's `env` list whose local-secrets
+ * value already matches `realValue` means this server was already
+ * extracted, under whatever name that was, and must keep using it — not
+ * get a second, newly-synthesized reference alongside the first.
+ */
+function planStaticEnvExtraction(name, def, existing, homeDir, policy, key) {
+    const realValue = def.staticEnv[key];
+    const targetPath = policy.envFile ?? defaultLocalSecretsEnvFilePath(homeDir);
+    const localSecrets = existsSync(targetPath) ? parseDotenv(readFileSync(targetPath, "utf-8")) : {};
+    const priorName = existing?.env?.find((n) => Object.hasOwn(localSecrets, n) && localSecrets[n] === realValue);
+    const varName = priorName ?? synthesizeVarName(name, key);
+    const safeDef = extractedMcpDef(def, key, varName);
+    const alreadyInSecretsFile = Object.hasOwn(localSecrets, varName);
+    if (priorName === undefined && alreadyInSecretsFile && localSecrets[varName] !== realValue) {
+        return {
+            kind: "mcp",
+            name,
+            action: "conflict",
+            detail: `refusing to extract MCP server "${name}"'s "${varName}": ${targetPath} already has a different value for this name — resolve by hand`,
+            remediation: `compare the source agent's current value for "${varName}" against the value already in ${targetPath} and update whichever one is stale, then re-run migrate`,
+        };
+    }
+    if (alreadyInSecretsFile && existing !== undefined && deepEqual(existing, safeDef)) {
+        return { kind: "mcp", name, action: "already-migrated", detail: `already extracted — "${varName}" is referenced from servers.yaml and its real value is already in ${targetPath}` };
+    }
+    if (existing !== undefined && !deepEqual(existing, safeDef) && !isSafeReclassification(existing, safeDef)) {
         return {
             kind: "mcp",
             name,
             action: "conflict",
-            detail: `refusing to import MCP server "${name}": a value matches a known-dangerous literal pattern (${secretLabel}) — canonical must hold variable NAMES only, never real values (docs/research.md "Secrets")`,
-            remediation: `move the real value in the source agent's own config to an environment variable (or your secrets manager), leaving only a name behind, then re-run migrate — canonical never accepts a literal credential, even briefly`,
+            detail: `canonical mcp/servers.yaml already has a different definition for "${name}" — resolve by hand`,
+            remediation: `compare the source agent's own definition for "${name}" against \`~/.trellis/mcp/servers.yaml\` and update canonical by hand if the source's is the one to keep`,
         };
     }
+    return {
+        kind: "mcp",
+        name,
+        action: "extract-secret",
+        detail: `will extract "${key}" to ${targetPath} as "${varName}", referencing it from servers.yaml instead of holding the literal value`,
+        mcpDef: safeDef,
+        extractVarName: varName,
+        extractTargetPath: targetPath,
+        extractSourceKey: key,
+    };
+}
+function planMcpServer(name, def, existing, homeDir, policy) {
+    // A `staticEnv` match is extracted (trellis-migrate-extract-static-env-secrets):
+    // its own dict key is a natural variable name, and `env`/`env_vars` is
+    // the one shape proven to resolve back to a real value for every
+    // consumer (pi-bridge, claude-code, codex, kiro). A literal anywhere
+    // else (`command`/`url`/`args`/`headers`) has either no natural name to
+    // extract to, or no `${VAR}` resolution mechanism proven across every
+    // consumer — a fake reference there would be strictly worse than the
+    // literal it replaced (an agent silently failing to connect instead of
+    // the source agent's own working config). Accepted as ordinary literal
+    // config instead (design.md D11), same as if no match were found at
+    // all; `secrets audit` keeps flagging canonical itself so this isn't
+    // silent.
+    const secretMatch = findLiteralSecret(def);
+    if (secretMatch?.field === "staticEnv") {
+        return planStaticEnvExtraction(name, def, existing, homeDir, policy, secretMatch.key);
+    }
     if (existing === undefined) {
         return { kind: "mcp", name, action: "create", detail: "will add to servers.yaml", mcpDef: def };
     }
@@ -153,13 +303,14 @@ function planMcpServer(name, def, existing) {
  * conflict. Omitting `only` (or passing both kinds) is exactly today's
  * behavior.
  */
-export async function collectMigratePlan(agent, homeDir = homedir(), only) {
+export async function collectMigratePlan(agent, homeDir = homedir(), only, workspaceDir = process.cwd()) {
     const snapshot = await PROBES[agent](homeDir);
     if (!snapshot.present) {
         return { agent, present: false, items: [] };
     }
     const canonicalRoot = join(homeDir, ".trellis");
     const items = [];
+    let memoryDiscovery;
     const wants = (kind) => !only || only.includes(kind);
     if (wants("skill")) {
         for (const root of snapshot.skillRoots) {
@@ -176,38 +327,108 @@ export async function collectMigratePlan(agent, homeDir = homedir(), only) {
     if (wants("mcp")) {
         const reader = MCP_READERS[agent];
         if (reader) {
-            const canonicalServers = loadCanonicalSource(homeDir).mcp.servers;
+            const canonical = loadCanonicalSource(homeDir);
             const { entries, unsupported } = reader(homeDir);
             for (const { name, def } of entries) {
-                items.push(planMcpServer(name, def, canonicalServers[name]));
+                items.push(planMcpServer(name, def, canonical.mcp.servers[name], homeDir, canonical.secretsPolicy));
             }
             for (const { name, reason } of unsupported) {
                 items.push({ kind: "mcp", name, action: "skip-unsupported", detail: reason });
             }
         }
     }
-    return { agent, present: true, items };
+    if (wants("memory")) {
+        const discovery = discoverNativeMemory(agent, homeDir, workspaceDir);
+        memoryDiscovery = { ...discovery, candidates: discovery.candidates.map(({ content: _content, ...safe }) => safe) };
+        for (const candidate of discovery.candidates) {
+            items.push(planNativeMemoryCandidate(candidate, homeDir));
+        }
+    }
+    return { agent, present: true, items, ...(memoryDiscovery ? { memoryDiscovery } : {}) };
 }
-export function applyMigratePlan(plan, homeDir = homedir()) {
+/**
+ * Re-reads the source agent's real MCP entries at apply time to recover
+ * `sourceKey`'s current value — deliberately not carried on the plan item
+ * itself (design.md D9), so it never rides through a `--json`/`--dry-run`
+ * plan object a caller might log or serialize. A cheap, synchronous
+ * re-read (the same `MCP_READERS` function `collectMigratePlan` already
+ * called), not a second network/probe round-trip. `sourceKey` (the
+ * source's own dict key) and `varName` (the synthesized name it's
+ * written under, design.md D11) are looked up and written under
+ * separately — they are not, in general, the same string.
+ */
+function applyStaticEnvExtraction(agent, serverName, sourceKey, varName, targetPath, homeDir, backup) {
+    const reader = MCP_READERS[agent];
+    const realValue = reader?.(homeDir).entries.find((e) => e.name === serverName)?.def.staticEnv?.[sourceKey];
+    if (realValue === undefined)
+        return; // source changed between plan and apply; nothing left to extract
+    if (targetPath === defaultLocalSecretsEnvFilePath(homeDir)) {
+        ensureGitignoreEntry(join(homeDir, ".trellis", ".gitignore"), "mcp/servers.local.env", backup);
+    }
+    writeLocalSecretValue(targetPath, varName, realValue, backup);
+    writeSecretsPolicyExtraction(join(homeDir, ".trellis", "secrets.policy.yaml"), { varName, envFilePath: DEFAULT_LOCAL_SECRETS_ENV_FILE_TILDE }, backup);
+}
+function copyDirectoryThroughBackup(sourceDir, destDir, backup) {
+    for (const entry of readdirSync(sourceDir)) {
+        const source = join(sourceDir, entry);
+        const dest = join(destDir, entry);
+        if (statSync(source).isDirectory()) {
+            mkdirSync(dest, { recursive: true });
+            copyDirectoryThroughBackup(source, dest, backup);
+        }
+        else {
+            backup.writeFile(dest, readFileSync(source, "utf-8"));
+        }
+    }
+}
+export function applyMigratePlan(plan, homeDir = homedir(), backup) {
     const canonicalRoot = join(homeDir, ".trellis");
     for (const item of plan.items) {
-        if (item.action !== "create" && item.action !== "reclassify")
+        if (item.action !== "create" && item.action !== "reclassify" && item.action !== "extract-secret")
             continue;
         if (item.kind === "skill" && item.sourceDir) {
             const dest = join(canonicalRoot, "skills", item.name);
             mkdirSync(dest, { recursive: true });
-            cpSync(item.sourceDir, dest, { recursive: true });
+            if (backup)
+                copyDirectoryThroughBackup(item.sourceDir, dest, backup);
+            else
+                cpSync(item.sourceDir, dest, { recursive: true });
         }
         else if (item.kind === "instructions" && item.sourceContent !== undefined) {
             mkdirSync(canonicalRoot, { recursive: true });
-            writeFileSync(join(canonicalRoot, "agents.md"), item.sourceContent);
+            if (backup)
+                backup.writeFile(join(canonicalRoot, "agents.md"), item.sourceContent);
+            else
+                writeFileSync(join(canonicalRoot, "agents.md"), item.sourceContent);
         }
         else if (item.kind === "mcp" && item.mcpDef) {
-            upsertServerYaml(join(canonicalRoot, "mcp", "servers.yaml"), item.name, item.mcpDef);
+            upsertServerYaml(join(canonicalRoot, "mcp", "servers.yaml"), item.name, item.mcpDef, backup);
+            if (item.action === "extract-secret" && item.extractVarName && item.extractTargetPath && item.extractSourceKey) {
+                applyStaticEnvExtraction(plan.agent, item.name, item.extractSourceKey, item.extractVarName, item.extractTargetPath, homeDir, backup);
+            }
+        }
+        else if (item.kind === "memory" && item.memorySourcePath && item.memorySourceId && item.memoryTargetPath) {
+            if (statSync(item.memorySourcePath).size > MAX_NATIVE_MEMORY_BYTES)
+                throw new Error(`native memory source exceeds the ${MAX_NATIVE_MEMORY_BYTES}-byte limit: ${item.memorySourcePath}`);
+            const content = readFileSync(item.memorySourcePath, "utf8");
+            const imported = renderNativeMemory({ sourceAgent: plan.agent, sourceId: item.memorySourceId, content });
+            mkdirSync(dirname(item.memoryTargetPath), { recursive: true });
+            if (backup)
+                backup.writeFile(item.memoryTargetPath, imported);
+            else
+                writeFileSync(item.memoryTargetPath, imported);
         }
     }
+    // Runs every real (non-dry-run) migrate invocation, not just the one that
+    // performed a fresh extraction — a machine that already extracted a
+    // secret before this shell-wiring existed gets fixed the next time
+    // migrate runs at all, not only on its next brand-new extraction.
+    const envFile = loadCanonicalSource(homeDir).secretsPolicy.envFile;
+    if (envFile) {
+        ensureShellEnvSource(defaultShellRcPath(homeDir), envFile, backup);
+    }
 }
-const ONLY_VALUES = ["skills", "instructions", "mcp"];
+const ONLY_VALUES = ["skills", "instructions", "mcp", "memory"];
 function isMigrateOnlyValue(value) {
     return ONLY_VALUES.includes(value);
 }
@@ -216,6 +437,8 @@ function toMigrateKinds(only) {
         return ["skill"];
     if (only === "instructions")
         return ["instructions"];
+    if (only === "memory")
+        return ["memory"];
     return ["mcp"];
 }
 export async function runMigrate(opts = {}) {
@@ -252,12 +475,15 @@ export async function runMigrate(opts = {}) {
  * this formatting (including the empty-plan "nothing to migrate" case). */
 export function printPlan(plan, dryRun) {
     console.log(`${dryRun ? "[dry run] " : ""}migrate --from ${plan.agent}`);
+    if (plan.memoryDiscovery && plan.memoryDiscovery.status !== "supported") {
+        console.log(`  memory source — [${plan.memoryDiscovery.status}] ${plan.memoryDiscovery.detail}`);
+    }
     if (plan.items.length === 0) {
         console.log("  nothing to migrate");
         return;
     }
     for (const item of plan.items) {
-        const label = item.kind === "skill" ? `skill "${item.name}"` : item.kind === "mcp" ? `mcp server "${item.name}"` : "instructions";
+        const label = item.kind === "skill" ? `skill "${item.name}"` : item.kind === "mcp" ? `mcp server "${item.name}"` : item.kind === "memory" ? `memory "${item.name}"` : "instructions";
         console.log(`  [${item.action}] ${label} — ${item.detail}`);
     }
 }

package/dist/commands/onboard.d.ts

@@ -12,15 +12,39 @@
  * new skill-copy, symlink, conflict-detection, or secrets-scanning
  * judgment is made here.
  */
-import type { AgentId } from "../core/types.js";
+import type { AgentId, McpConfig, McpRouteMode } from "../core/types.js";
+import { type CapabilityInventory } from "../core/capabilitySelection.js";
+import { type NativeMemoryStatus } from "../lib/nativeMemory.js";
 import type { MigrateKind, MigratePlan } from "./migrate.js";
 import type { SyncReport } from "./sync.js";
 import type { McpSyncReport } from "./mcp.js";
 import type { SecretsAuditReport } from "./secretsAudit.js";
 import type { MemorySyncResult } from "./memory.js";
 import type { DoctorReport } from "./doctor.js";
+import type { RollbackReport } from "./rollback.js";
 import type { ConfirmAndInstallOptions } from "../lib/installAgent.js";
 import type { VerdictItem } from "./onboardVerdict.js";
+/**
+ * Scores only real source-side content. The recommendation is a hint for a
+ * first-time user, never a filter: every candidate remains selectable.
+ */
+export declare function migrationSourceScore(summary: Pick<OnboardAgentSummary, "skillCount" | "mcpServerCount" | "hasRealInstructions">): number;
+export declare function recommendedMigrationSource(summaries: readonly (Pick<OnboardAgentSummary, "agent" | "skillCount" | "mcpServerCount" | "hasRealInstructions">)[]): AgentId | undefined;
+export declare const MCP_ROUTE_OPTIONS: ({
+    mode: "gateway";
+    label: string;
+} | {
+    mode: "direct";
+    label: string;
+} | {
+    mode: "hub";
+    label: string;
+})[];
+export declare function interactiveMcpRouteOptions(hubConfigured: boolean): Array<{
+    mode: McpRouteMode;
+    label: string;
+    disabled?: boolean;
+}>;
 export interface OnboardAgentSummary {
     agent: AgentId;
     present: boolean;
@@ -37,8 +61,13 @@ export interface OnboardAgentSummary {
      * memory). 0 for pi, which has no MCP reader at all — not a gap here,
      * the same fact `migrate.ts` already establishes. */
     mcpServerCount: number;
+    mcpServerNames: string[];
+    nativeMemoryStatus: NativeMemoryStatus;
+    nativeMemoryCount: number;
+    nativeMemoryNames: string[];
+    nativeMemoryDetail: string;
 }
-export declare function collectOnboardSummary(homeDir?: string): Promise<OnboardAgentSummary[]>;
+export declare function collectOnboardSummary(homeDir?: string, workspaceDir?: string): Promise<OnboardAgentSummary[]>;
 export interface RunOnboardOptions {
     /** Non-interactive migration-source choice. */
     agent?: string;
@@ -60,10 +89,19 @@ export interface RunOnboardOptions {
      * Omitted leaves whatever's already configured untouched — same
      * no-prompt posture as `mcpMode` (design.md D12). */
     memory?: string;
+    /** Non-interactive native-source memory migration toggle: `"on"` or
+     * `"off"`. Omitted preserves the current state and prompts only when
+     * supported source candidates are available in a real terminal. */
+    memoryMigrate?: string;
+    /** Optional YAML/JSON item-level capability selection for automation. */
+    selectionFile?: string;
     dryRun?: boolean;
     json?: boolean;
     /** Defaults to the real `~`; overridable for tests only. */
     homeDir?: string;
+    /** Defaults to the current working directory; controls project-scoped
+     * native-memory discovery and is overridable for tests. */
+    workspaceDir?: string;
     /** Test-only: overrides the real `process.stdin.isTTY` check so the
      * interactive-vs-refuse branch is exercisable without a real terminal. */
     isTTY?: boolean;
@@ -84,6 +122,13 @@ export interface RunOnboardOptions {
      * (design.md D9). `true` means "apply for real", matching what
      * accepting the real picker's "Yes, apply now" option means. */
     promptToApply?: () => Promise<boolean>;
+    /** Test-only: replaces the real mode-transition confirmation. */
+    promptForModeChange?: (previous: "direct" | "hub" | "gateway", next: "direct" | "hub" | "gateway", agents: readonly AgentId[]) => Promise<boolean>;
+    /** Test-only: replaces the interactive shared-Memory choice. `keep` leaves
+     * the existing state untouched; the real picker puts that choice first. */
+    promptForMemory?: (current: "on" | "off") => Promise<"keep" | "on" | "off">;
+    /** Test-only: replaces the interactive native-memory migration choice. */
+    promptForMemoryMigration?: (source: AgentId, count: number) => Promise<"keep" | "on" | "off">;
     /** Test-only: injected into every `confirmAndInstall` call for a
      * selected, not-yet-present agent. Never a real terminal prompt or a
      * real `npm install` in a unit test. */
@@ -96,6 +141,23 @@ export interface OnboardInstallResult {
 }
 export interface OnboardResult {
     summary: OnboardAgentSummary[];
+    inventory?: CapabilityInventory;
+    capabilitySummary?: {
+        awarenessSkill: boolean;
+        globalInstructions: {
+            available: boolean;
+            native: boolean;
+            runtimeReadable: boolean;
+        };
+        skills: number;
+        memories: number;
+        mcpServers: number;
+    };
+    managedAgentRuntime?: Array<{
+        agent: AgentId;
+        delivery: "native" | "mcp" | "both";
+        route: "direct" | "gateway" | "hub";
+    }>;
     source?: AgentId;
     sourceReason?: "auto-selected" | "flag" | "prompt";
     /** The full managed set this run acted against — the union of whatever
@@ -131,6 +193,8 @@ export interface OnboardResult {
      * inconsistent across agents independent of this run.
      */
     doctorReport?: DoctorReport;
+    /** Present when a blocking real run was automatically restored. */
+    rollback?: RollbackReport;
     /**
      * The resolved MCP mode after this run (trellis-onboard-mcp-mode
      * design.md D7) — `current` reflects canonical's state whether or not
@@ -165,6 +229,14 @@ export interface OnboardResult {
      */
     verdict: VerdictItem[];
 }
+/** Converges explicit per-Agent route lists with the shared Memory toggle.
+ * Legacy/top-level routes without a `servers` list already expose every
+ * eligible server and need no rewrite. Hub routes are intentionally opaque:
+ * the external hub owns its upstream set. */
+export declare function mergeMemoryIntoExplicitRoutes(mcp: McpConfig, managedAgents: readonly AgentId[], memoryEnabled: boolean): {
+    mcp: McpConfig;
+    changed: boolean;
+};
 export declare function collectOnboardPlan(opts?: RunOnboardOptions): Promise<OnboardResult>;
 export declare function runOnboard(opts?: RunOnboardOptions): Promise<{
     exitCode: number;