@aitne/daemon 0.1.6 → 0.1.8

package/dist/core/skills-compiler.js

@@ -1,10 +1,11 @@
 import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync, } from "node:fs";
 import { dirname, join, relative } from "node:path";
 import { APP_NAME, BACKEND_IDS, INTEGRATION_DESCRIPTORS, INTEGRATION_KEYS, applyIntegrationModeFilter, collectSessionDeniedTools, filterDeniedToolsForBackend, selectSkillVariantFile, selectTaskFlowVariantSuffix, substituteBrandTokens, } from "@aitne/shared";
-import { getProfileForEvent, getProfileForProcess, getSkillsForEvent, getSkillsForProcess } from "./skills-manifest.js";
+import { getProfileForEvent, getProfileForProcess, resolveSkillManifest, resolveSkillManifestForProcess, } from "./skills-manifest.js";
 import { applyCharacterBlockRewrite, buildCharacterBlock } from "./character-block.js";
 import { applyOutputLanguagePointerRewrite, renderOutputLanguagePolicyPointer, } from "./output-language-policy.js";
 import { createLogger } from "../logging.js";
+import { loadFetchWindowSystemPrompt } from "./fetch-window-prompt-loader.js";
 import { substituteIntegrationRoutingTables } from "./management-md.js";
 import { loadCurationDeclaration, } from "./skill-curation/declarations.js";
 import { listBuiltinSlugs, resolveBuiltinSkillDir, } from "./skill-source-paths.js";
@@ -13,6 +14,18 @@ import { hasCurationAnchors, spliceCurationAnchors, } from "./skill-curation/spl
 // Exported so tests can spy on `logger.warn` (e.g. the missing-reference
 // branch of `renderReferenceIncludes`). Production callers do not import it.
 export const logger = createLogger("skills-compiler");
+// docs/design/appendices/fetch-window-cost-reduction.md Phase 1.5 — single shared constant
+// for the pre-pass process key. Typed as `ProcessKey` (not the inferred
+// string literal) so a rename in `@aitne/shared/process-key.ts` lights up
+// here rather than silently dead-branching the slim materializer.
+const FETCH_WINDOW_PROCESS_KEY = "routine.fetch_window";
+// Single skill kept in the slim fetch_window CLI session: the
+// `observations` SKILL.md is the POST contract for
+// `/api/observations/batch` and the fetcher's only structural assertion.
+// The other skills the wide path inlines (`mail`, `notion`,
+// `external-services`, `attach`) are already restated by the integration
+// partial the runner inlines into the user prompt.
+const FETCH_WINDOW_SLIM_SKILL = "observations";
 /**
  * Check whether the skill AND task-flow variants a given integration would
  * require when delegated to `delegatedBackend` are all present on disk.
@@ -151,7 +164,7 @@ function missingVariantsForMode(workspaceDir, integrationKey, pinnedState) {
     // required.
     const sessionBackendsToCheck = pinnedState.mode === "native"
         ? [pinnedState.nativeBackend]
-        : BACKEND_IDS;
+        : BACKEND_IDS.filter((backend) => backend !== "opencode");
     // De-dup with sets — the same file path can come up under multiple
     // session backends when descriptors share a slug.
     const skills = new Set();
@@ -357,9 +370,20 @@ export class SkillsCompiler {
         const profileName = params.processKey
             ? getProfileForProcess(params.processKey)
             : getProfileForEvent(params.eventType);
+        // `evening-review-slimdown.md` §2.1 — route through the predicate-aware
+        // wrapper so the evening rulebook gate (and any future per-event
+        // predicate) is consulted exactly once per session, at materialization
+        // time. The wrapper passes non-conditional events through verbatim, so
+        // every other process key keeps its old behaviour.
+        const manifestOpts = {
+            ...(params.contextDir ? { contextDir: params.contextDir } : {}),
+            ...(params.db !== undefined ? { db: params.db } : {}),
+            ...(params.messageText !== undefined ? { messageText: params.messageText } : {}),
+        };
+        const hasManifestOpts = Object.keys(manifestOpts).length > 0;
         const manifestSkills = params.processKey
-            ? getSkillsForProcess(params.processKey)
-            : getSkillsForEvent(params.eventType);
+            ? resolveSkillManifestForProcess(params.processKey, hasManifestOpts ? manifestOpts : undefined)
+            : resolveSkillManifest(params.eventType, hasManifestOpts ? manifestOpts : undefined);
         // Custom bang command override: when the dispatcher passes a slug array
         // we use it verbatim, ignoring the manifest. Empty array is allowed and
         // means "no skills." `null` keeps manifest behavior — the override is a
@@ -378,13 +402,32 @@ export class SkillsCompiler {
         // adds their first account mid-session (0→N transition). Filtering
         // here would leave the skill dir absent forever since refresh only
         // writes into existing dirs.
+        // docs/design/appendices/opencode-backend.md §6.5 / Phase 4 — opencode discovers
+        // skills via cwd auto-discovery from `.claude/skills/` (V2) AND uses
+        // a per-process agent file at `.opencode/agent/<slug>.md` (V5,
+        // singular `agent/`). Routing through `materializeCliSession` would
+        // inline skill bodies into AGENTS.md, which we explicitly do NOT
+        // want for opencode (skills are auto-discovered by the `skill` tool).
         if (params.backendId === "claude") {
             this.materializeClaudeSession(params.sessionDir, profileName, skills, profileBodyOverride, params.processKey ?? params.eventType, params.wikiWorkspaceName);
         }
+        else if (params.backendId === "opencode") {
+            this.materializeOpencodeSession(params.sessionDir, profileName, skills, profileBodyOverride, params.processKey ?? params.eventType, params.wikiWorkspaceName);
+        }
         else {
             this.materializeCliSession(params.sessionDir, profileName, skills, params.backendId, params.processKey ?? params.eventType, profileBodyOverride, params.wikiWorkspaceName);
         }
-        return { profile: profileName, skills };
+        // docs/design/appendices/fetch-window-cost-reduction.md Phase 1.5 — the slim
+        // CLI materializer drops every manifest skill except `observations`.
+        // The Claude path is wide for fetch_window today (Phase 1 swaps only
+        // the system prompt, not the workdir layout). Report what was
+        // actually written so log lines / callers see truth, not the
+        // manifest's pre-narrow list.
+        const effectiveSkills = params.backendId !== "claude"
+            && (params.processKey ?? params.eventType) === FETCH_WINDOW_PROCESS_KEY
+            ? [FETCH_WINDOW_SLIM_SKILL]
+            : skills;
+        return { profile: profileName, skills: effectiveSkills };
     }
     /** Read raw profile .md without safety injection. */
     readProfile(profileName) {
@@ -492,8 +535,39 @@ export class SkillsCompiler {
             mkdirSync(dirname(join(sessionDir, "CLAUDE.md")), { recursive: true });
             writeFileSync(join(sessionDir, "CLAUDE.md"), profileContent, "utf-8");
         }
+        this.writeSkillsDir(sessionDir, join(".claude", "skills"), skillSlugs, "claude", processKey, wikiWorkspaceName);
+    }
+    /**
+     * docs/design/appendices/skills-unification.md Phase 1 — per-backend skill-dir writer.
+     *
+     * Writes `<sessionDir>/<destSkillsRootRelative>/<slug>/SKILL.md` for each
+     * slug, applying the full per-skill transformation pipeline:
+     * variant resolution → brand tokens → partial / reference inlining →
+     * service strip → mode filter → deny filter → curation splice → mail
+     * `accounts.md`. The destination directory is the only thing that varies
+     * across backends:
+     *
+     *   - Claude  → `.claude/skills`
+     *   - OpenCode → `.opencode/skills`
+     *   - Codex   → `.codex/skills`
+     *   - Gemini  → `.gemini/skills`
+     *
+     * For Codex sessions, this method ALSO prepends a one-line read-sensitive
+     * banner to each materialised SKILL.md whose body references a read-
+     * sensitive `/api/*` endpoint (those endpoints 401 on Codex because the
+     * Codex backend does not hold the read-sensitive token). The banner
+     * points the agent at the `## Read-sensitive endpoints are UNAVAILABLE`
+     * section already rendered into `AGENTS.md`.
+     *
+     * Returns the list of slugs that ended up on disk (slugs whose variant
+     * resolved to `null` for same-backend native MCP and slugs whose source
+     * SKILL.md was missing are excluded). Callers use this list to render
+     * the `<skill-index>` block from a stable, post-materialisation source.
+     */
+    writeSkillsDir(sessionDir, destSkillsRootRelative, skillSlugs, sessionBackend, processKey, wikiWorkspaceName) {
+        const materialised = [];
         const skillsRoot = this.getSourceSkillsRoot();
-        const destSkillsRoot = join(sessionDir, ".claude", "skills");
+        const destSkillsRoot = join(sessionDir, destSkillsRootRelative);
         mkdirSync(destSkillsRoot, { recursive: true });
         // Re-materialize cleanup: a previous turn (especially one with a wider
         // skill set or a different custom-command override) may have left
@@ -504,11 +578,19 @@ export class SkillsCompiler {
         // `syncAllUserSkills` is the authoritative writer for that subset.
         pruneStaleBuiltinSkillDirs(destSkillsRoot, skillsRoot, skillSlugs);
         for (const skillSlug of skillSlugs) {
+            // docs/design/appendices/opencode-backend.md §10 D6 / Phase 4 — slug must match
+            // opencode's skill-name lint regex `[a-z0-9-]{1,64}` because a
+            // future opencode release may reject names that fall outside it.
+            // Warn at materialisation; do not strip the skill (every Aitne
+            // built-in slug already conforms — see audit acceptance criterion).
+            if (!isValidSkillSlug(skillSlug)) {
+                logger.warn({ skillSlug, expected: "[a-z0-9-]{1,64}" }, "skills_compiler.skill_slug_invalid");
+            }
             const src = resolveBuiltinSkillDir(skillsRoot, skillSlug);
             if (!existsSync(join(src, "SKILL.md"))) {
                 continue;
             }
-            const variantFile = this.resolveSkillVariantFile(skillSlug, "claude");
+            const variantFile = this.resolveSkillVariantFile(skillSlug, sessionBackend);
             const destDir = join(destSkillsRoot, skillSlug);
             // DELEGATED-MODE-V2-DESIGN.md §4.1.2 — same-backend native MCP. The
             // agent already has the connector's tools in its inventory; a skill
@@ -545,10 +627,10 @@ export class SkillsCompiler {
             //
             // Order: refs BEFORE strip-services. The CLI paths
             // (`materializeCliSession` inline + directory copy) both run refs
-            // before strip; aligning Claude here preserves the byte-equivalence
+            // before strip; aligning here preserves the byte-equivalence
             // contract (plan §3.1) for the case where a reference file carries
             // `<!-- service:* -->` markers — strip-first would leak those on
-            // Claude while CLI scrubs them.
+            // Claude/OpenCode while CLI scrubs them.
             const destSkillMdForRefs = join(destDir, "SKILL.md");
             if (existsSync(destSkillMdForRefs)) {
                 const raw = readFileSync(destSkillMdForRefs, "utf-8");
@@ -578,18 +660,20 @@ export class SkillsCompiler {
             const destSkillMdForMode = join(destDir, "SKILL.md");
             if (existsSync(destSkillMdForMode)) {
                 const raw = readFileSync(destSkillMdForMode, "utf-8");
-                const filtered = applyIntegrationModeFilter(raw, this.integrations, "claude");
+                const filtered = applyIntegrationModeFilter(raw, this.integrations, sessionBackend);
                 if (filtered !== raw) {
                     writeFileSync(destSkillMdForMode, filtered, "utf-8");
                 }
             }
             // §7.7 — apply tool-deny policy AFTER partial includes and
-            // service-section stripping. For Claude this rewrites the
-            // `allowed-tools` frontmatter; the SDK enforces hard.
+            // service-section stripping. For the Claude SDK this rewrites the
+            // `allowed-tools` frontmatter (hard); for opencode the rewrite is
+            // a soft-enforcement prose body addition that the runtime config
+            // doubles up via `permission.bash.deny` rules.
             const destSkillMdForDeny = join(destDir, "SKILL.md");
             if (existsSync(destSkillMdForDeny)) {
                 const raw = readFileSync(destSkillMdForDeny, "utf-8");
-                const filtered = applyAllDeniedToolsForSkill(raw, skillSlug, "claude", this.integrations);
+                const filtered = applyAllDeniedToolsForSkill(raw, skillSlug, sessionBackend, this.integrations);
                 if (filtered !== raw) {
                     writeFileSync(destSkillMdForDeny, filtered, "utf-8");
                 }
@@ -608,7 +692,141 @@ export class SkillsCompiler {
                     ? renderMailAccountsMd(this.mailAccounts)
                     : EMPTY_MAIL_ACCOUNTS_MD, "utf-8");
             }
+            // Phase 1 §"Codex read-sensitive banner inheritance" — prepend the
+            // 3-line caveat banner to every Codex skill body that touches a
+            // read-sensitive `/api/*` endpoint. Skipped for the other three
+            // backends: Claude / Gemini hold the read-sensitive token; OpenCode
+            // surfaces those routes via its own credential flow.
+            if (sessionBackend === "codex") {
+                prependCodexReadSensitiveBanner(join(destDir, "SKILL.md"));
+            }
+            materialised.push(skillSlug);
         }
+        return materialised;
+    }
+    /**
+     * docs/design/appendices/opencode-backend.md §6.5 / Phase 4 — opencode-specific
+     * materialisation.
+     *
+     * Three on-disk artefacts are written per session:
+     *   1. `AGENTS.md` (cwd-auto-discovered by opencode per V1) — same
+     *      shape as `materializeCliSession` produces for Codex EXCEPT
+     *      skill bodies are NOT inlined (skills auto-discover from
+     *      `.claude/skills/` via opencode's `skill` tool — V2). Includes
+     *      safety, character, behavioral rules, daemon-API, integration
+     *      routing tables, and the runtime profile body.
+     *   2. `.opencode/agent/<profile-slug>.md` (singular `agent/` per V5)
+     *      — the per-process agent persona with V5-correct frontmatter
+     *      (`mode: primary`, `permission` block keyed only on
+     *      `edit/bash/webfetch/doom_loop/external_directory` — NO `read`
+     *      key per V5 contract). Body is the profile body; opencode
+     *      invokes this via `session.prompt({ body: { agent: <slug> } })`
+     *      so the per-agent permission overrides the server-level
+     *      defaults.
+     *   3. `.opencode/skills/<slug>/` via `writeSkillsDir` — every
+     *      manifest skill becomes a discoverable SKILL.md tree opencode
+     *      reads on `skill` tool activation. `.claude/skills/` is
+     *      intentionally NOT written: docs/design/appendices/skills-unification.md Phase 1
+     *      flipped opencode from V2 path (b) (`.claude/skills/`
+     *      redundancy-avoiding alias) to V2 path (c) (`.opencode/skills/`)
+     *      so each backend lives under its own brand-aligned namespace.
+     *
+     * The dispatcher passes `agent: <slug>` (where `<slug>` matches the
+     * profile filename without `.md`) on every `session.prompt` call so
+     * the right agent file is selected.
+     */
+    materializeOpencodeSession(sessionDir, profileName, skillSlugs, profileBodyOverride, processKey, wikiWorkspaceName) {
+        // ── 1. AGENTS.md — cwd context (no skill inlining) ──
+        let profileContent = profileBodyOverride !== null
+            ? profileBodyOverride.trim()
+            : (this.readProfile(profileName) ?? "");
+        profileContent = substituteWikiWorkspaceTokens(profileContent, processKey, wikiWorkspaceName);
+        const safetyContent = this.readSafetyPreamble();
+        const characterBlock = buildCharacterBlock(this.character);
+        // DELEGATED-MODE-V2-DESIGN.md §4.3.3-§4.3.4 — same-backend deny prose.
+        // Opencode's MCP-tool deny is server-level only (§5.6 v1: drop the
+        // server from config to deny). The prose duplicates intent so the
+        // agent doesn't waste tokens drafting calls that will be dropped.
+        const sameBackendDenyBlock = buildSameBackendDenyBlock(this.integrations, "opencode");
+        const rawInstruction = renderCliInstructionFile({
+            backendId: "opencode",
+            processKey,
+            profileName,
+            profileContent,
+            safetyContent,
+            characterBlock,
+            skillSlugs,
+            // R3 — OpenCode never gets a `<skill-index>` block. The cwd
+            // auto-discovery loader is the source of truth; emitting an index
+            // here would inject a second listing the runtime ignores and the
+            // agent could mistake for canonical. The `## Skills` slug manifest
+            // (no path, no inlined bodies) survives as a turn-scope hint.
+            skillPreamble: null,
+            skillIndexBlock: null,
+            sameBackendDenyBlock,
+        });
+        const instruction = substituteWikiWorkspaceTokens(substituteIntegrationRoutingTables(rawInstruction, this.integrations), processKey, wikiWorkspaceName);
+        writeFileSync(join(sessionDir, "AGENTS.md"), instruction, "utf-8");
+        // ── 2. .opencode/agent/<profileName>.md — V5 frontmatter wrapper ──
+        this.writeOpencodeAgentFile(sessionDir, profileName, profileContent, safetyContent, characterBlock);
+        // ── 3. .opencode/skills/ — auto-discovered by opencode 1.14+ ──
+        // docs/design/appendices/skills-unification.md Phase 1 — opencode 1.14+ auto-discovers
+        // skills from `.opencode/skills/<slug>/SKILL.md` (V2 path (c),
+        // empirically verified). The earlier path (b) (`.claude/skills/`)
+        // worked as a redundancy-avoiding alias; per-backend brand-aligned
+        // naming now picks (c) explicitly.
+        this.writeSkillsDir(sessionDir, join(".opencode", "skills"), skillSlugs, "opencode", processKey, wikiWorkspaceName);
+    }
+    /**
+     * docs/design/appendices/opencode-backend.md §6.5 / V5 — write the per-process agent
+     * profile to `.opencode/agent/<slug>.md` (singular `agent/`; the
+     * plural form does NOT register per V5).
+     *
+     * Frontmatter shape (V5-correct keys only):
+     *   - `mode: primary` — opencode's primary-agent mode; subagent is
+     *     reserved for the disabled `task` tool path.
+     *   - NO `permission` block here — the server-level
+     *     `OpencodeRuntimeConfig.permission` is the per-session truth and
+     *     is stricter for narrow agents (delegated runs use a separate
+     *     `delegated-<callId>` agent file with its own tight permission).
+     *     Emitting `permission: {}` here would NOT widen anything (the
+     *     server-level deny still wins), but the absence keeps the
+     *     frontmatter a manifest and avoids drift between two seats.
+     *   - NO `model` field — opencode falls back to `OPENCODE_CONFIG_CONTENT.model`
+     *     (set per-session by `OpencodeCore`'s runtime-config builder),
+     *     and the dispatcher additionally overrides per `session.prompt`
+     *     body. Pinning here would either drift from the per-call value
+     *     or duplicate it.
+     *
+     * Body composition mirrors AGENTS.md (safety + character + profile)
+     * so an `agent: <slug>` invocation that REPLACES opencode's default
+     * cwd context still gets safety/character rules — V5 confirmed the
+     * agent body becomes the system prompt for that turn.
+     */
+    writeOpencodeAgentFile(sessionDir, profileName, profileBody, safetyContent, characterBlock) {
+        const agentDir = join(sessionDir, ".opencode", "agent");
+        mkdirSync(agentDir, { recursive: true });
+        // Strip a description from the profile body's first paragraph for
+        // the frontmatter `description` field. Opencode displays this in
+        // its agent picker; we use a stable phrasing so re-renders produce
+        // identical bytes.
+        const description = `${APP_NAME} ${profileName} — per-process persona`;
+        const frontmatter = [
+            "---",
+            `description: ${description}`,
+            "mode: primary",
+            "---",
+            "",
+        ].join("\n");
+        const bodySections = [];
+        if (safetyContent)
+            bodySections.push(safetyContent);
+        if (characterBlock)
+            bodySections.push(characterBlock);
+        if (profileBody.trim())
+            bodySections.push(profileBody.trim());
+        const body = bodySections.join("\n\n");
+        writeFileSync(join(agentDir, `${profileName}.md`), `${frontmatter}${body}\n`, "utf-8");
     }
     /**
      * P22 §1.5 — splice CURATION anchors in a single skill's materialized
@@ -648,64 +866,121 @@ export class SkillsCompiler {
             writeFileSync(skillMdPath, result.body, "utf-8");
         }
     }
-    materializeCliSession(sessionDir, profileName, skillSlugs, backendId, processKey, profileBodyOverride, wikiWorkspaceName) {
-        // Skills are inlined in the instruction file (AGENTS.md / GEMINI.md) for
-        // guaranteed availability AND copied to the backend-specific skill
-        // directory for native CLI skill discovery. The directory copy only adds
-        // ~20 tokens per skill at session start (name + description); full body
-        // is lazy-loaded on activation. Belt-and-suspenders: inline ensures task
-        // flow prompts always have API references in context; directories let the
-        // CLI's native skill activation and tooling work.
+    /**
+     * docs/design/appendices/skills-unification.md Phase 1 item 15 — the slim path does NOT
+     * emit a `<skill-index>` block or the skill-discovery preamble. The
+     * fetch_window system prompt is a self-contained operational contract
+     * (one-window-one-curl, no sub-tasks, exactly-one JSON-on-stdout) and
+     * the only skill copied (`observations`) is referenced inline by the
+     * runner-emitted user prompt. Adding the index would mis-signal the
+     * fetcher to scan for skills before executing the acquisition plan.
+     *
+     * docs/design/appendices/fetch-window-cost-reduction.md Phase 1.5 — slim instruction-file
+     * materializer for `routine.fetch_window` on Codex / Gemini CLI.
+     *
+     * Mirrors the Claude SDK's Phase 1 systemPrompt swap (the same
+     * `agent-assets/system-prompts/routine-fetch-window.md` template is the
+     * single source of truth): write the slim body verbatim as AGENTS.md /
+     * GEMINI.md and copy only the `observations` skill — the
+     * `/api/observations/batch` POST contract is the fetcher's sole
+     * structural assertion. The integration partial inlined by the runner
+     * (`routine-fetch-window-runner.ts:reassemblePrompt`) covers the
+     * per-attempt call shape, so `mail` / `notion` / `external-services` /
+     * `attach` skill bodies are deliberately omitted.
+     *
+     * No safety preamble / character / behavioral-rules / daemon-API
+     * sections — the slim template restates the only rules the fetcher
+     * needs (localhost-only curl, no sub-tasks, no context writes, no
+     * notify, JSON-on-stdout-and-exit). The destructive-action policy layer
+     * (absolute-block list, Codex sandbox, Gemini admin TOML) still applies
+     * unchanged at runtime.
+     *
+     * The `<mcp-servers>` section is appended downstream by
+     * `services/mcp/session-materializer.ts:appendMcpSection` exactly as on
+     * the wide path — Phase 3's allowlist filter, when it lands, will scope
+     * that section without further changes here.
+     */
+    materializeFetchWindowCliSession(sessionDir, backendId) {
+        mkdirSync(sessionDir, { recursive: true });
+        const slim = loadFetchWindowSystemPrompt();
+        writeFileSync(join(sessionDir, cliInstructionFileName(backendId)), slim, "utf-8");
+        // Copy ONLY the `observations` skill dir. The wide path's prune step
+        // is replaced by an explicit single-slug list — `pruneStaleBuiltinSkillDirs`
+        // removes any other built-in skill dir that a prior re-materialization
+        // (e.g. a fallback-driven wide path on the same workdir) may have left.
+        const cliSkillsRoot = cliSkillsDirName(backendId);
+        if (cliSkillsRoot === null)
+            return; // Claude-only — fetch_window slim runs on Claude SDK natively.
         const skillsRoot = this.getSourceSkillsRoot();
-        const skillContents = {};
-        for (const skillSlug of skillSlugs) {
-            const src = resolveBuiltinSkillDir(skillsRoot, skillSlug);
-            const variantFile = this.resolveSkillVariantFile(skillSlug, backendId);
-            // DELEGATED-MODE-V2-DESIGN.md §4.1.2 — same-backend native MCP path:
-            // skip the inline. The connector's own tool descriptions, present in
-            // the CLI's tool inventory at session-init, are the authoritative
-            // surface for the agent.
-            if (variantFile === null)
-                continue;
-            const skillMdPath = join(src, variantFile);
-            if (!existsSync(skillMdPath)) {
-                continue;
-            }
-            let raw = substituteBrandTokens(readFileSync(skillMdPath, "utf-8"));
-            // Resolve {{> base }} partials before inlining. Wrap the result —
-            // SKILL.base.md is read directly from src and would slip past the
-            // single-point-of-change contract if it grew an `{APP_NAME}` token.
-            raw = substituteBrandTokens(renderPartialIncludes(raw, join(src, "SKILL.base.md")));
-            // Resolve `{{> ref:<name> }}` directives by inlining
-            // `references/<name>.md` from the source skill dir. Runs AFTER the
-            // base-partial resolver so a base-partial fragment can itself carry
-            // `{{> ref:* }}` markers (one-level nesting cap; references inside
-            // references are intentionally NOT resolved per §4.7 / NG5). Same
-            // src-bypass concern as above — wrap the result.
-            raw = substituteBrandTokens(renderReferenceIncludes(raw, src));
-            raw = substituteWikiWorkspaceTokens(raw, processKey, wikiWorkspaceName);
-            // Strip unconfigured service sections before inlining
-            if (skillSlug === "external-services" && this.configuredServices.size > 0) {
-                raw = stripUnconfiguredServices(raw, this.configuredServices);
-            }
-            // Mode-conditional sections — see materializeClaudeSession for the
-            // ordering rationale. Same filter, same ordering: service-strip
-            // then mode-filter then deny.
-            raw = applyIntegrationModeFilter(raw, this.integrations, backendId);
-            // §7.7 — apply tool-deny policy. For CLI backends this appends the
-            // soft-enforcement prose block; the inline-into-AGENTS.md path
-            // strips frontmatter below, so the deny block must already be in
-            // body content before that strip.
-            raw = applyAllDeniedToolsForSkill(raw, skillSlug, backendId, this.integrations);
-            // Inline content for instruction file — strip frontmatter (Claude-specific
-            // YAML metadata like allowed-tools has no meaning for CLI backends).
-            skillContents[skillSlug] = stripFrontmatter(raw);
+        const destSkillsRoot = join(sessionDir, cliSkillsRoot, "skills");
+        mkdirSync(destSkillsRoot, { recursive: true });
+        pruneStaleBuiltinSkillDirs(destSkillsRoot, skillsRoot, [FETCH_WINDOW_SLIM_SKILL]);
+        const src = resolveBuiltinSkillDir(skillsRoot, FETCH_WINDOW_SLIM_SKILL);
+        const skillMdPath = join(src, "SKILL.md");
+        if (!existsSync(skillMdPath))
+            return;
+        const destDir = join(destSkillsRoot, FETCH_WINDOW_SLIM_SKILL);
+        cpSync(src, destDir, { recursive: true });
+        substituteBrandTokensInDir(destDir);
+        // No `substituteWikiWorkspaceTokensInDir` — fetch_window never touches
+        // wiki workspace state, and the resolver is a no-op for non-wiki
+        // process keys anyway.
+        let adapted = substituteBrandTokens(readFileSync(skillMdPath, "utf-8"));
+        // observations/SKILL.md ships no `{{> base }}` or `{{> ref:* }}`
+        // directives today, but run the resolvers anyway so a future curation
+        // edit cannot silently drop content. Idempotent on plain content.
+        adapted = substituteBrandTokens(renderPartialIncludes(adapted, join(src, "SKILL.base.md")));
+        adapted = substituteBrandTokens(renderReferenceIncludes(adapted, src));
+        // Mode-conditional filter — observations/SKILL.md carries
+        // `<!-- mode:<predicate>:notion -->` markers (lines 273-345 today)
+        // because the source / consume contract differs across `direct` /
+        // `delegated-same` / `delegated-cross` / `native` / `disabled`. The
+        // wide path applies this filter at `materializeCliSession`; the
+        // slim path must match so the agent doesn't get every mode's prose
+        // for every integration. Idempotent on bodies that lack markers.
+        adapted = applyIntegrationModeFilter(adapted, this.integrations, backendId);
+        // Tool-deny policy stays in force — even though the fetcher is fed a
+        // narrow allowlist, the soft-enforcement prose lands in the body
+        // BEFORE the CLI frontmatter strip so it's not lost.
+        adapted = applyAllDeniedToolsForSkill(adapted, FETCH_WINDOW_SLIM_SKILL, backendId, this.integrations);
+        // docs/design/appendices/skills-unification.md Phase 1 §R6 — frontmatter stays intact
+        // across all backends. `adaptSkillForCli` is gone; the source body's
+        // YAML preamble flows through verbatim.
+        writeFileSync(join(destDir, "SKILL.md"), adapted, "utf-8");
+        this.spliceCurationAnchorsInSkill(destDir, FETCH_WINDOW_SLIM_SKILL);
+    }
+    materializeCliSession(sessionDir, profileName, skillSlugs, backendId, processKey, profileBodyOverride, wikiWorkspaceName) {
+        // docs/design/appendices/fetch-window-cost-reduction.md Phase 1.5 — divert
+        // `routine.fetch_window` to a slim materializer that mirrors the
+        // Claude SDK's Phase 1 systemPrompt swap. Custom bang commands cannot
+        // reach this branch (they bind to `messaging.custom_command`), so
+        // `profileBodyOverride` is intentionally NOT forwarded.
+        if (processKey === FETCH_WINDOW_PROCESS_KEY) {
+            this.materializeFetchWindowCliSession(sessionDir, backendId);
+            return;
         }
+        // docs/design/appendices/skills-unification.md Phase 1 — directory-based skill delivery.
+        // The Codex / Gemini CLIs have no native cwd auto-discovery today, so
+        // the instruction file (AGENTS.md / GEMINI.md) carries a compact
+        // `<skill-index>` block and the agent `Read`s each `SKILL.md` from the
+        // per-backend dir on demand. Skill bodies are NEVER inlined into the
+        // instruction file.
+        //
+        // OpenCode reaches `materializeOpencodeSession` instead, so this method
+        // only handles Codex and Gemini. The defensive `null` check below
+        // protects future backends that might temporarily route through here
+        // before getting their own materialiser.
+        const cliSkillsDir = cliSkillsDirName(backendId);
+        if (cliSkillsDir === null) {
+            throw new Error(`materializeCliSession: no skills directory mapped for backend "${backendId}"`);
+        }
+        const destSkillsRootRelative = join(cliSkillsDir, "skills");
+        const materialisedSlugs = this.writeSkillsDir(sessionDir, destSkillsRootRelative, skillSlugs, backendId, processKey, wikiWorkspaceName);
         // Read profile and safety separately so renderCliInstructionFile can
         // place safety at the top level for prominence (instead of burying it
         // inside the profile section). For custom bang commands the dispatcher
         // passes a `profileBodyOverride` that replaces the persona body; the
-        // safety + character + skills sections still wrap around it via
+        // safety + character + skill index sections still wrap around it via
         // `renderCliInstructionFile`.
         let profileContent = profileBodyOverride !== null
             ? profileBodyOverride.trim()
@@ -721,6 +996,18 @@ export class SkillsCompiler {
         // prose duplicates intent so the agent doesn't waste tokens drafting
         // calls that will be denied at the policy layer.
         const sameBackendDenyBlock = buildSameBackendDenyBlock(this.integrations, backendId);
+        // docs/design/appendices/skills-unification.md Phase 1 §"Skill preamble" — render the
+        // universal preamble + `<skill-index>` block. The index is derived
+        // from the **materialised** SKILL.md frontmatter on disk so curation /
+        // mode-filter / deny passes are reflected. Reading post-materialisation
+        // also keeps user-authored slugs synced by `syncAllUserSkills` (which
+        // runs LATER from the workdir layer) out of the index — those land in
+        // the same dir but are appended after this render. The
+        // `refreshSkillIndexBlock` helper (called by workdir.ts post-sync) is
+        // responsible for splicing user-authored slugs into the block.
+        const skillPreamble = loadSkillIndexPreamble(this.workspaceDir);
+        const destSkillsRootAbs = join(sessionDir, destSkillsRootRelative);
+        const skillIndexBlock = renderSkillIndexBlock(destSkillsRootAbs, destSkillsRootRelative);
         const rawInstruction = renderCliInstructionFile({
             backendId,
             processKey,
@@ -728,89 +1015,18 @@ export class SkillsCompiler {
             profileContent,
             safetyContent,
             characterBlock,
-            skillSlugs,
-            skillContents,
+            skillSlugs: materialisedSlugs,
+            skillPreamble,
+            skillIndexBlock,
             sameBackendDenyBlock,
         });
         // INTEGRATION_NATIVE_MODE_DESIGN.md §7.3 — substitute the
         // `<integration-routing-table>` placeholder in the rendered
         // instruction file. Runs after the whole document is assembled so
-        // placeholders anywhere (profile body, inlined skill bodies,
-        // safety preamble) all resolve in one pass. No-op when neither
-        // placeholder string is present.
+        // placeholders anywhere (profile body, preamble, index) all resolve
+        // in one pass.
         const instruction = substituteWikiWorkspaceTokens(substituteIntegrationRoutingTables(rawInstruction, this.integrations), processKey, wikiWorkspaceName);
-        writeFileSync(join(sessionDir, backendId === "codex" ? "AGENTS.md" : "GEMINI.md"), instruction, "utf-8");
-        // Copy skills to the backend-specific skill directory for native CLI
-        // discovery:  .codex/skills/<slug>/  or  .gemini/skills/<slug>/
-        const cliSkillsDir = cliSkillsDirName(backendId);
-        const destSkillsRoot = join(sessionDir, cliSkillsDir, "skills");
-        mkdirSync(destSkillsRoot, { recursive: true });
-        // See `materializeClaudeSession` — same prune contract for CLI workdirs.
-        pruneStaleBuiltinSkillDirs(destSkillsRoot, skillsRoot, skillSlugs);
-        for (const skillSlug of skillSlugs) {
-            const src = resolveBuiltinSkillDir(skillsRoot, skillSlug);
-            const variantFile = this.resolveSkillVariantFile(skillSlug, backendId);
-            const destDir = join(destSkillsRoot, skillSlug);
-            // §4.1.2 same-backend short-circuit: no SKILL.md / .codex/skills/<slug>
-            // / .gemini/skills/<slug> directory written. The connector ships its
-            // own descriptions; injecting prose only confuses the dispatch.
-            // Remove any prior-materialization leftovers so a mode flip doesn't
-            // leak stale prose into the workdir.
-            if (variantFile === null) {
-                if (existsSync(destDir)) {
-                    rmSync(destDir, { recursive: true, force: true });
-                }
-                continue;
-            }
-            const variantPath = join(src, variantFile);
-            if (!existsSync(variantPath)) {
-                continue;
-            }
-            // Copy the whole skill directory (scripts/, references/, etc.)
-            cpSync(src, destDir, { recursive: true });
-            // Resolve `{APP_NAME}` brand tokens in the verbatim copy before any
-            // downstream transform reads them. Source-of-truth: branding.ts.
-            substituteBrandTokensInDir(destDir);
-            substituteWikiWorkspaceTokensInDir(destDir, processKey, wikiWorkspaceName);
-            // Render variant (resolving partials), adapt frontmatter for CLI, and
-            // write as SKILL.md in the dest dir.
-            let adapted = substituteBrandTokens(readFileSync(variantPath, "utf-8"));
-            // SKILL.base.md and references/*.md are read directly from src by these
-            // inliners; wrap the results so future tokens added to those files still
-            // reach single-point-of-change. Idempotent.
-            adapted = substituteBrandTokens(renderPartialIncludes(adapted, join(src, "SKILL.base.md")));
-            // Resolve `{{> ref:<name> }}` directives — keeps the
-            // `.codex/skills/<slug>/SKILL.md` and `.gemini/skills/<slug>/SKILL.md`
-            // bodies byte-identical to the inline-into-AGENTS.md / GEMINI.md
-            // copy emitted above (modulo CLI frontmatter strip), preserving the
-            // "guaranteed availability" contract that motivated this resolver.
-            adapted = substituteBrandTokens(renderReferenceIncludes(adapted, src));
-            adapted = substituteWikiWorkspaceTokens(adapted, processKey, wikiWorkspaceName);
-            if (skillSlug === "external-services" && this.configuredServices.size > 0) {
-                adapted = stripUnconfiguredServices(adapted, this.configuredServices);
-            }
-            // Mode-conditional filter — keep this dest-dir copy byte-aligned with
-            // the inline copy emitted into AGENTS.md / GEMINI.md (modulo
-            // adaptSkillForCli's frontmatter strip). The filter is idempotent so
-            // running it on both copies independently is safe.
-            adapted = applyIntegrationModeFilter(adapted, this.integrations, backendId);
-            // §7.7 — apply tool-deny policy BEFORE adaptSkillForCli strips
-            // frontmatter so the soft-enforcement prose block lands in body
-            // content (CLI skills carry only `name` + `description` in
-            // frontmatter, no `allowed-tools` to filter).
-            adapted = applyAllDeniedToolsForSkill(adapted, skillSlug, backendId, this.integrations);
-            adapted = adaptSkillForCli(adapted);
-            writeFileSync(join(destDir, "SKILL.md"), adapted, "utf-8");
-            // P22 — splice CURATION anchors against overlay/seed JSON so the
-            // CLI-side .codex/.gemini skill copy stays byte-equivalent to the
-            // Claude-side copy after curation. No-op when no curation context.
-            this.spliceCurationAnchorsInSkill(destDir, skillSlug);
-            if (skillSlug === "mail") {
-                writeFileSync(join(destDir, "accounts.md"), this.mailAccounts.length > 0
-                    ? renderMailAccountsMd(this.mailAccounts)
-                    : EMPTY_MAIL_ACCOUNTS_MD, "utf-8");
-            }
-        }
+        writeFileSync(join(sessionDir, cliInstructionFileName(backendId)), instruction, "utf-8");
     }
 }
 export const EMPTY_MAIL_ACCOUNTS_MD = [
@@ -843,16 +1059,171 @@ export function renderMailAccountsMd(accounts) {
     ].join("\n");
 }
 /**
- * Return the backend-specific skills directory name for a given backend.
- * Returns null for Claude (which uses `.claude/skills/` managed separately).
+ * docs/design/appendices/opencode-backend.md §10 D6 — opencode 1.14.50 documents
+ * `[a-z0-9-]{1,64}` as the legal skill-slug pattern. Aitne's existing
+ * built-ins all conform; this helper is the predicate the build-time
+ * validator (`validateBuiltinSkillSourceTree`) and the user-skill PUT
+ * endpoint both gate on.
+ *
+ * docs/design/appendices/skills-unification.md Phase 1 §R5 / item 6 — promoted from a
+ * runtime warn to a build-time throw at SkillsCompiler construction so
+ * a malformed source tree refuses to boot the daemon.
+ *
+ * Exported for unit testing (`skills-compiler.test.ts` regression).
+ */
+export function isValidSkillSlug(slug) {
+    return /^[a-z0-9-]{1,64}$/.test(slug);
+}
+/**
+ * docs/design/appendices/skills-unification.md Phase 1 §R5 / item 6 — build-time invariant
+ * pass over `agent-assets/skills/`. Throws on:
+ *   - Any built-in slug that doesn't match `[a-z0-9-]{1,64}`.
+ *   - Any SKILL.md (incl. variants like `SKILL.delegated.<backend>.md`)
+ *     whose `description` exceeds `SKILL_DESCRIPTION_MAX_LENGTH`.
+ *   - Any SKILL.md missing `name` or `description`.
+ *
+ * No-op when the source tree is absent (test workspaces / partial-clone
+ * scenarios). Memoised per workspace dir + skill-tree fingerprint so
+ * repeated SkillsCompiler constructions in the same process don't pay
+ * the walk cost twice; tests that mutate source between constructions
+ * get fresh validation because the fingerprint shifts.
+ *
+ * Exported for tests that exercise the failure paths in isolation.
+ */
+export function validateBuiltinSkillSourceTree(skillsRoot) {
+    if (!existsSync(skillsRoot))
+        return;
+    const fingerprint = computeSkillTreeFingerprint(skillsRoot);
+    const cached = validatedTreeCache.get(skillsRoot);
+    if (cached === fingerprint)
+        return;
+    for (const slug of listBuiltinSlugs(skillsRoot)) {
+        if (!isValidSkillSlug(slug)) {
+            throw new Error(`skills_compiler.invalid_slug: ${slug} (expected [a-z0-9-]{1,64})`);
+        }
+        const skillDir = resolveBuiltinSkillDir(skillsRoot, slug);
+        const skillMdPath = join(skillDir, "SKILL.md");
+        if (!existsSync(skillMdPath))
+            continue; // skip slugs that ship only a variant
+        const primaryContent = readFileSync(skillMdPath, "utf-8");
+        const primaryFm = parseSkillFrontmatter(primaryContent);
+        // Stub primary (no frontmatter) — treat the whole skill as a test
+        // scaffold and skip its variants too. Production builds always have
+        // proper frontmatter; the fingerprint cache picks up any future
+        // primary-content fix automatically.
+        if (!primaryFm.name && !primaryFm.description)
+            continue;
+        if (!primaryFm.name) {
+            throw new Error(`skills_compiler.missing_frontmatter_name: ${slug}/SKILL.md`);
+        }
+        if (!primaryFm.description) {
+            throw new Error(`skills_compiler.missing_frontmatter_description: ${slug}/SKILL.md`);
+        }
+        if (primaryFm.description.length > SKILL_DESCRIPTION_MAX_LENGTH) {
+            throw new Error(`skills_compiler.description_too_long: ${slug}/SKILL.md `
+                + `(${primaryFm.description.length} > ${SKILL_DESCRIPTION_MAX_LENGTH})`);
+        }
+        // Variant validation — only run when the primary is well-formed. Each
+        // variant is shipped to the model the same way the primary is, so the
+        // same description-length cap applies. Variants that are stub
+        // sentinels in tests are caught by the primary-stub short-circuit
+        // above (this loop never runs for those).
+        const entries = readdirSync(skillDir, { withFileTypes: true });
+        for (const entry of entries) {
+            if (!entry.isFile())
+                continue;
+            const name = entry.name;
+            if (!name.startsWith("SKILL.") || !name.endsWith(".md"))
+                continue;
+            if (name === "SKILL.base.md")
+                continue; // base partial — frontmatter optional
+            const variantContent = readFileSync(join(skillDir, name), "utf-8");
+            const variantFm = parseSkillFrontmatter(variantContent);
+            if (!variantFm.name || !variantFm.description) {
+                throw new Error(`skills_compiler.variant_missing_frontmatter: ${slug}/${name}`);
+            }
+            if (variantFm.description.length > SKILL_DESCRIPTION_MAX_LENGTH) {
+                throw new Error(`skills_compiler.description_too_long: ${slug}/${name} `
+                    + `(${variantFm.description.length} > ${SKILL_DESCRIPTION_MAX_LENGTH})`);
+            }
+        }
+    }
+    validatedTreeCache.set(skillsRoot, fingerprint);
+}
+const validatedTreeCache = new Map();
+function computeSkillTreeFingerprint(skillsRoot) {
+    // mtime-only fingerprint over SKILL*.md files: enough to bust the
+    // cache on a source-tree edit between constructions without paying
+    // the cost of a full content hash. Tests that mutate files within
+    // the same millisecond should call SkillsCompiler.invalidateValidator()
+    // — but in practice the millisecond resolution suffices.
+    const parts = [];
+    for (const slug of listBuiltinSlugs(skillsRoot).sort()) {
+        const skillDir = resolveBuiltinSkillDir(skillsRoot, slug);
+        let entries;
+        try {
+            entries = readdirSync(skillDir, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const e of entries) {
+            if (!e.isFile())
+                continue;
+            const name = e.name;
+            if (!name.startsWith("SKILL") || !name.endsWith(".md"))
+                continue;
+            try {
+                const stat = statSync(join(skillDir, name));
+                parts.push(`${slug}/${name}:${stat.mtimeMs}:${stat.size}`);
+            }
+            catch { /* ignore */ }
+        }
+    }
+    return parts.join("|");
+}
+/**
+ * Return the backend-specific dotfile namespace name for a given backend's
+ * skill directory, **without** the trailing `skills` segment — callers
+ * join `skills` themselves. Returns `null` only for Claude (which is
+ * dispatched through `materializeClaudeSession` and writes
+ * `<sessionDir>/.claude/skills/` directly).
+ *
+ * docs/design/appendices/skills-unification.md Phase 1 — every non-Claude backend now writes
+ * to its own brand-aligned namespace:
+ *   - `codex`    → `.codex`
+ *   - `gemini`   → `.gemini`
+ *   - `opencode` → `.opencode` (V2 path (c); flipped from prior `.claude/`
+ *                  redundancy-avoiding alias).
  */
 export function cliSkillsDirName(backendId) {
     switch (backendId) {
         case "codex": return ".codex";
         case "gemini": return ".gemini";
+        case "opencode": return ".opencode";
         default: return null;
     }
 }
+/**
+ * Return the CLI instruction-file name for a given backend. Codex and
+ * OpenCode both auto-discover `AGENTS.md` from cwd; Gemini reads
+ * `GEMINI.md`. Throws for `claude` — the Claude SDK consumes a per-cwd
+ * `CLAUDE.md` written by `materializeClaudeSession`, not an instruction
+ * file from this helper.
+ *
+ * Single helper so the choice is consistent between the wide
+ * `materializeCliSession` and the slim `materializeFetchWindowCliSession`
+ * paths (docs/design/appendices/fetch-window-cost-reduction.md §4.5.7).
+ */
+export function cliInstructionFileName(backendId) {
+    switch (backendId) {
+        case "codex":
+        case "opencode":
+            return "AGENTS.md";
+        case "gemini":
+            return "GEMINI.md";
+    }
+}
 /**
  * Session instruction files the live-overwrite path (design §15.6.1 /
  * §15.9) walks when the owner PATCHes `character` mid-session. Each file
@@ -888,8 +1259,27 @@ const CHARACTER_INSTRUCTION_FILES = [
  */
 export function rewriteCharacterBlock(workdir, character) {
     const summary = { rewritten: 0, skipped: 0, failed: 0 };
-    for (const name of CHARACTER_INSTRUCTION_FILES) {
-        const target = join(workdir, name);
+    const targets = CHARACTER_INSTRUCTION_FILES.map((name) => join(workdir, name));
+    // docs/design/appendices/opencode-backend.md §6.5 — opencode also carries the character
+    // block inside `.opencode/agent/<slug>.md` (the per-process persona
+    // body). Walk the dir so a mid-session character PATCH lands on every
+    // active opencode agent file (typically one per workdir). Defensive
+    // existence check below — a non-opencode workdir simply has no
+    // `.opencode/agent/` dir and contributes zero rewrites.
+    const opencodeAgentDir = join(workdir, ".opencode", "agent");
+    if (existsSync(opencodeAgentDir)) {
+        try {
+            for (const entry of readdirSync(opencodeAgentDir, { withFileTypes: true })) {
+                if (entry.isFile() && entry.name.endsWith(".md")) {
+                    targets.push(join(opencodeAgentDir, entry.name));
+                }
+            }
+        }
+        catch (err) {
+            logger.warn({ err, opencodeAgentDir }, "rewriteCharacterBlock failed to enumerate opencode agent dir");
+        }
+    }
+    for (const target of targets) {
         if (!existsSync(target)) {
             summary.skipped++;
             continue;
@@ -919,7 +1309,7 @@ export function rewriteCharacterBlock(workdir, character) {
     return summary;
 }
 function renderCliInstructionFile(params) {
-    const toolName = params.backendId === "codex" ? "AGENTS.md" : "GEMINI.md";
+    const toolName = cliInstructionFileName(params.backendId);
     const parts = [
         `# ${APP_NAME} ${toolName}`,
         "",
@@ -964,22 +1354,40 @@ function renderCliInstructionFile(params) {
     // For Gemini / Claude the section is informational; the position is
     // kept consistent so the rendered file shape is uniform.
     parts.push(renderDaemonApiUsageSection(params.backendId !== "codex"), "");
-    parts.push("## Runtime profile", "", params.profileContent.trim(), "", "## Skills", "");
-    if (params.skillSlugs.length === 0) {
-        parts.push("No process-scoped built-in skills were selected for this turn.");
+    // docs/design/appendices/skills-unification.md Phase 1 §R2 — preamble + `<skill-index>`
+    // sit after Character (already emitted above) and **before** the
+    // Runtime profile (which carries the integration routing table
+    // substitution). Codex / Gemini only — `skillPreamble` and
+    // `skillIndexBlock` are `null` for OpenCode (R3) so the section is
+    // suppressed entirely and the `## Skills` slug manifest below holds.
+    if (params.skillPreamble) {
+        parts.push(params.skillPreamble.trim(), "");
     }
-    else {
-        for (const slug of params.skillSlugs) {
-            const content = params.skillContents[slug];
-            if (content) {
-                parts.push(`### ${slug}`, "", content.trim(), "");
-            }
-            else {
-                parts.push(`### ${slug}`, "", `See \`skills/${slug}/SKILL.md\` for details.`, "");
+    if (params.skillIndexBlock) {
+        parts.push(params.skillIndexBlock, "");
+    }
+    parts.push("## Runtime profile", "", params.profileContent.trim(), "");
+    // docs/design/appendices/skills-unification.md Phase 1 §R3 — the `## Skills` slug manifest
+    // only fires for OpenCode (no `<skill-index>` block; cwd auto-discovery
+    // already enumerates the skills, but the manifest pins the per-turn
+    // active set so the agent doesn't grab unrelated user skills). Codex /
+    // Gemini suppress this section since their `<skill-index>` above already
+    // serves as the canonical listing — duplicating it here would risk the
+    // agent mistaking the manifest for the authoritative path source.
+    if (!params.skillIndexBlock) {
+        parts.push("## Skills", "");
+        if (params.skillSlugs.length === 0) {
+            parts.push("No process-scoped built-in skills were selected for this turn.", "");
+        }
+        else {
+            parts.push("Active built-in skills for this turn (cwd auto-discovery loads them):", "");
+            for (const slug of params.skillSlugs) {
+                parts.push(`- \`${slug}\``);
             }
+            parts.push("");
         }
+        parts.push("User-authored skills may also be discovered from the same directory.");
     }
-    parts.push("", "User-authored skills may also exist under `skills/<name>/SKILL.md`.");
     return parts.join("\n");
 }
 function renderDaemonApiUsageSection(readSensitiveAvailable) {
@@ -993,7 +1401,7 @@ function renderDaemonApiUsageSection(readSensitiveAvailable) {
         lines.push("- The wrapper auto-attaches session auth for read-sensitive endpoints.");
     }
     else {
-        lines.push("", "### Read-sensitive endpoints are UNAVAILABLE on this backend", "", "Codex sessions do not receive the read-sensitive daemon token. The", "wrapper still prepends headers it can supply, but the daemon answers", "personal-data reads with `401 Unauthorized` regardless. Endpoints", "below are affected; the skill bodies in `## Skills` describe them", "as if they were available — treat the section as a contract you", "cannot satisfy on this backend.", "", "- Context vault: `GET /api/context/*`, `GET /api/context/list/*`", "- Mail (multi-provider): `GET /api/mail/*` (read), search, providers", "- Calendar (direct mode): `GET /api/calendar/*`", "- Notion (direct mode): `GET /api/notion/{query,search,pages}`", "- Obsidian: `GET /api/obsidian/*`", "- Observations: `GET /api/observations`", "- Reading list / receipts / travel bookings", "", "If a skill body directs you at one of these reads, stop and tell", "the user the task needs a different backend (Claude or Gemini).", "Do not hammer the endpoint — the 401 is permanent for this", "session, not transient. Writes and autonomous-tier endpoints", "stay reachable; the gate is read-sensitive scope only.");
+        lines.push("", "### Read-sensitive endpoints are UNAVAILABLE on this backend", "", "Codex sessions do not receive the read-sensitive daemon token. The", "wrapper still prepends headers it can supply, but the daemon answers", "personal-data reads with `401 Unauthorized` regardless. Endpoints", "below are affected; the per-skill `SKILL.md` files under", "`.codex/skills/<name>/` listed in `<skill-index>` describe them as if", "they were available — treat their `curl /api/*` examples as a", "contract you cannot satisfy on this backend.", "", "- Context vault: `GET /api/context/*`, `GET /api/context/list/*`", "- Mail (multi-provider): `GET /api/mail/*` (read), search, providers", "- Calendar (direct mode): `GET /api/calendar/*`", "- Notion (direct mode): `GET /api/notion/{query,search,pages}`", "- Obsidian: `GET /api/obsidian/*`", "- Observations: `GET /api/observations`", "- Reading list / receipts / travel bookings", "", "If a skill body directs you at one of these reads, stop and tell", "the user the task needs a different backend (Claude or Gemini).", "Do not hammer the endpoint — the 401 is permanent for this", "session, not transient. Writes and autonomous-tier endpoints", "stay reachable; the gate is read-sensitive scope only.");
     }
     return lines.join("\n");
 }
@@ -1022,53 +1430,283 @@ function stripFrontmatter(content) {
     return content.slice(endIdx + 4).replace(/^\n+/, "");
 }
 /**
- * Adapt a SKILL.md for CLI backends (Codex / Gemini): retain only `name`,
- * `description`, and `when_to_use` frontmatter fields, stripping
- * Claude-specific fields like `allowed-tools`. The body content is
- * preserved unchanged.
- *
- * `when_to_use` is the secondary trigger-shape clarification documented
- * in `SKILLS-PHASE-2-PLAN.md` §3.2 / §5; the Claude Agent SDK reads it
- * verbatim from `q.when_to_use` (verified against
- * `claude-agent-sdk@0.2.98/cli.js`). Preserving it on the CLI side keeps
- * the per-backend skill frontmatter aligned even though Codex / Gemini
- * do not currently consume the field — drift would surface as a missing
- * activation hint when they eventually do.
- *
- * Assumes `name`, `description`, and `when_to_use` are each single-line
- * YAML scalars (no `|` / `>` block forms). A multi-line `when_to_use:`
- * is matched only by its first line — the `.+` regex stops at the
- * newline — but since YAML block scalars start with the line that
- * contains only `|` or `>`, the captured value would be the empty
- * indicator and the inlined value would be useless. Phase 2 v1 keeps
- * this conservative: callers must use single-line scalars (NG5).
+ * docs/design/appendices/skills-unification.md Phase 1 — parse the `name` and `description`
+ * single-line YAML scalars out of a SKILL.md frontmatter block. Returns
+ * `{ name: null, description: null }` when no frontmatter is present or
+ * neither key is set. Multi-line block scalars (`description: |` /
+ * `description: >`) are rejected at the regex level — the schema enforces
+ * single-line scalars across all backends (R6).
  */
-export function adaptSkillForCli(content) {
+export function parseSkillFrontmatter(content) {
     if (!content.startsWith("---"))
-        return content;
+        return { name: null, description: null };
     const endIdx = content.indexOf("\n---", 3);
     if (endIdx < 0)
-        return content;
-    const frontmatter = content.slice(4, endIdx);
-    const body = content.slice(endIdx + 4);
-    const nameMatch = frontmatter.match(/^name:\s*(.+)$/m);
-    const descMatch = frontmatter.match(/^description:\s*(.+)$/m);
-    const whenMatch = frontmatter.match(/^when_to_use:\s*(.+)$/m);
-    // Reject multi-line block scalars (`when_to_use: |` / `when_to_use: >`):
-    // their first-line capture would just be the indicator. Falling through
-    // to "no when_to_use" matches the documented contract (§3.4.2 #9).
-    const whenIsBlockScalar = whenMatch !== null && /^[|>][-+]?\s*$/.test(whenMatch[1].trim());
-    const parts = ["---"];
-    if (nameMatch)
-        parts.push(`name: ${nameMatch[1].trim()}`);
-    if (descMatch)
-        parts.push(`description: ${descMatch[1].trim()}`);
-    if (whenMatch && !whenIsBlockScalar) {
-        parts.push(`when_to_use: ${whenMatch[1].trim()}`);
+        return { name: null, description: null };
+    const fm = content.slice(4, endIdx);
+    const nameMatch = fm.match(/^name:\s*(.+)$/m);
+    const descMatch = fm.match(/^description:\s*(.+)$/m);
+    return {
+        name: nameMatch ? nameMatch[1].trim() : null,
+        description: descMatch ? descMatch[1].trim() : null,
+    };
+}
+/**
+ * docs/design/appendices/skills-unification.md Phase 1 §R5 — hard upper bound on a
+ * SKILL.md `description` scalar. Enforced at SkillsCompiler construction
+ * for built-in skills (refuses to boot on violation) and at
+ * `PUT /api/skills/<slug>` for user-authored skills (HTTP 400). Sized to
+ * fit the model's selection decision without pinning enough prose to
+ * encode body content.
+ */
+export const SKILL_DESCRIPTION_MAX_LENGTH = 280;
+/**
+ * docs/design/appendices/skills-unification.md Phase 1 §"Codex read-sensitive banner
+ * inheritance" — endpoints flagged `RiskTier.ReadSensitive` by
+ * `safety/risk-classifier.ts` that a Codex session cannot satisfy (no
+ * read-sensitive token). Any SKILL.md whose body references one of these
+ * prefixes triggers a one-line banner prepend on the Codex copy. Listed
+ * literally (not derived from `API_RISK` at module-load time) so the
+ * core/skills-compiler module stays independent of safety/risk-classifier
+ * — a circular import would invert the bootstrap order.
+ *
+ * Drift guard: `skills-compiler.test.ts` pins this list against the
+ * RiskTier.ReadSensitive GET-prefix set in `risk-classifier.ts` so a new
+ * read-sensitive endpoint added to API_RISK surfaces here at test time
+ * instead of as silent 401 retries in a future Codex session.
+ *
+ * Exported for the drift-guard regression test only — production code
+ * MUST use {@link skillBodyTouchesReadSensitive} to keep the
+ * "literal prefix" decision encapsulated.
+ */
+export const READ_SENSITIVE_API_PREFIXES = [
+    "/api/apple-calendar",
+    "/api/books",
+    "/api/calendar",
+    "/api/context",
+    "/api/entities",
+    "/api/mail",
+    "/api/mcp/servers",
+    "/api/notion",
+    "/api/observations",
+    "/api/obsidian",
+    "/api/receipts",
+    "/api/travel-bookings",
+];
+function skillBodyTouchesReadSensitive(skillBody) {
+    return READ_SENSITIVE_API_PREFIXES.some((prefix) => skillBody.includes(prefix));
+}
+const CODEX_READ_SENSITIVE_BANNER_HEADER = "<!-- codex-read-sensitive-banner -->";
+const CODEX_READ_SENSITIVE_BANNER = [
+    CODEX_READ_SENSITIVE_BANNER_HEADER,
+    "> NOTE (Codex session): Some endpoints in this skill are read-sensitive and",
+    "> return 401 here. See `## Read-sensitive endpoints are UNAVAILABLE` in",
+    "> AGENTS.md before invoking. Do not retry on 401 — stop and notify the user.",
+    "",
+].join("\n");
+/**
+ * docs/design/appendices/skills-unification.md Phase 1 §"Codex read-sensitive banner
+ * inheritance" — prepend the 3-line caveat banner to a Codex skill body
+ * whose contents reference any read-sensitive `/api/*` endpoint. The
+ * banner sits immediately after the YAML frontmatter (so the frontmatter
+ * parser on the agent side still picks up `name`/`description`/
+ * `allowed-tools` first) and is idempotent — re-running on an already-
+ * banner-bearing file is a no-op (the HTML-comment sentinel lets us
+ * detect prior insertion without false positives from user prose).
+ *
+ * No-op when:
+ *  - The skill body references zero read-sensitive endpoints.
+ *  - The banner is already present (sentinel hit).
+ */
+function prependCodexReadSensitiveBanner(skillMdPath) {
+    if (!existsSync(skillMdPath))
+        return;
+    const content = readFileSync(skillMdPath, "utf-8");
+    if (!skillBodyTouchesReadSensitive(content))
+        return;
+    if (content.includes(CODEX_READ_SENSITIVE_BANNER_HEADER))
+        return;
+    if (!content.startsWith("---")) {
+        writeFileSync(skillMdPath, CODEX_READ_SENSITIVE_BANNER + content, "utf-8");
+        return;
+    }
+    const fmCloseIdx = content.indexOf("\n---", 3);
+    if (fmCloseIdx < 0) {
+        writeFileSync(skillMdPath, CODEX_READ_SENSITIVE_BANNER + content, "utf-8");
+        return;
     }
-    parts.push("---");
-    return parts.join("\n") + body;
+    const afterFm = fmCloseIdx + 4; // include `\n---`
+    // Skip a single trailing newline after `---` so the banner sits on its
+    // own line cleanly. If no newline follows, we still emit one before the
+    // banner so the prose split is unambiguous.
+    const head = content.slice(0, afterFm);
+    const tail = content.slice(afterFm).replace(/^\n+/, "");
+    writeFileSync(skillMdPath, `${head}\n\n${CODEX_READ_SENSITIVE_BANNER}${tail ? `\n${tail}` : ""}`, "utf-8");
 }
+/**
+ * docs/design/appendices/skills-unification.md Phase 1 §"Skill preamble" — load the static
+ * preamble shipped at
+ * `agent-assets/system-prompts/skill-index-instruction.md`. The preamble
+ * is constant per backend (Codex / Gemini) and explains the on-demand
+ * skill-load protocol. Returns a built-in minimal fallback when the asset
+ * is missing so tests that don't seed the system-prompts dir still
+ * produce deterministic output.
+ */
+function loadSkillIndexPreamble(workspaceDir) {
+    const path = join(workspaceDir, "agent-assets", "system-prompts", "skill-index-instruction.md");
+    if (existsSync(path)) {
+        return readFileSync(path, "utf-8").trim();
+    }
+    return [
+        "## Skills",
+        "",
+        "Skills are materialised on disk under the per-backend dotfile",
+        "directory. When your task matches an entry in `<skill-index>` below,",
+        "`Read` its `SKILL.md` and follow the contents.",
+    ].join("\n");
+}
+/**
+ * docs/design/appendices/skills-unification.md Phase 1 §"`<skill-index>` block" — render
+ * the per-slug index from the **materialised** SKILL.md frontmatter on
+ * disk. Walking the destination dir (instead of the source manifest)
+ * keeps the index in sync with what the agent will actually find when
+ * it reads:
+ *
+ *   - Same-backend native MCP slugs whose variant resolved to `null` are
+ *     correctly omitted (no SKILL.md was written).
+ *   - User-authored slugs synced AFTER `writeSkillsDir` (via
+ *     `syncAllUserSkills` from the workdir layer) appear automatically
+ *     when this is called from the post-sync refresh helper.
+ *   - Frontmatter that has gone through curation / mode filter / deny
+ *     pass / read-sensitive banner reflects the post-pipeline state.
+ *
+ * The block is emitted with a fixed XML-style envelope so tests can pin
+ * its placement and the splicer in `refreshSkillIndexBlock` can locate
+ * it for in-place rewrites between turns.
+ *
+ * `destSkillsRootRelative` is the on-disk path the agent should Read
+ * (`.codex/skills` or `.gemini/skills`); it gets embedded in the header
+ * sentence verbatim. Built-ins and user-authored slugs are not
+ * distinguished here — see R4.
+ */
+/**
+ * docs/design/appendices/skills-unification.md Phase 1 — splice sentinels.
+ *
+ * The visible `<skill-index>` / `</skill-index>` XML-style tags are the
+ * agent-facing contract; they MUST stay in the rendered output for the
+ * preamble's protocol to make sense. But using them as the splicer's
+ * region markers is fragile — any profile body, skill body, or user
+ * prose that quotes the tag verbatim would be misidentified as the
+ * splice region and silently corrupted on `refreshSkillIndexBlock`.
+ *
+ * The sentinels below are unique HTML comments emitted immediately
+ * outside the visible tags. The splicer keys on them instead, so even
+ * a profile that quotes `<skill-index>` cannot collide with the splice
+ * region. Comments render as low-signal tokens to the model and add
+ * ~50 bytes per session — negligible against the ~3 KB block.
+ */
+const SKILL_INDEX_START_SENTINEL = "<!-- skill-index:start -->";
+const SKILL_INDEX_END_SENTINEL = "<!-- skill-index:end -->";
+export function renderSkillIndexBlock(destSkillsRootAbs, destSkillsRootRelative) {
+    const lines = [
+        SKILL_INDEX_START_SENTINEL,
+        "<skill-index>",
+        `The following skills are materialized at \`${destSkillsRootRelative}/<name>/SKILL.md\`.`,
+        "When your task matches a skill's `description`, `Read` the `SKILL.md`",
+        "to load its guidance and follow it. Skill bodies are NOT inlined in",
+        "this prompt — read them on demand. Multiple skills may be loaded in",
+        "one turn.",
+        "",
+    ];
+    let entryCount = 0;
+    if (existsSync(destSkillsRootAbs)) {
+        const slugs = readdirSync(destSkillsRootAbs, { withFileTypes: true })
+            .filter((e) => e.isDirectory())
+            .map((e) => e.name)
+            .sort((a, b) => a.localeCompare(b));
+        for (const slug of slugs) {
+            const skillMdPath = join(destSkillsRootAbs, slug, "SKILL.md");
+            if (!existsSync(skillMdPath))
+                continue;
+            const fm = parseSkillFrontmatter(readFileSync(skillMdPath, "utf-8"));
+            if (!fm.name || !fm.description)
+                continue;
+            lines.push(`- name: ${fm.name}`);
+            lines.push(`  description: ${fm.description}`);
+            entryCount++;
+        }
+    }
+    if (entryCount === 0) {
+        lines.push("(No skills materialized this turn — proceed with the runtime profile only.)");
+    }
+    lines.push("</skill-index>", SKILL_INDEX_END_SENTINEL);
+    return lines.join("\n");
+}
+/**
+ * docs/design/appendices/skills-unification.md Phase 1 — re-render the `<skill-index>` block
+ * inside an existing instruction file. Called by the workdir layer AFTER
+ * `syncAllUserSkills` so user-authored slugs land in the index alongside
+ * the built-ins (`renderSkillIndexBlock` reads the dest dir on disk, so a
+ * post-sync re-render naturally picks them up).
+ *
+ * No-op when:
+ *  - The backend is Claude (no instruction file with `<skill-index>`).
+ *  - The instruction file is missing (the session has not been
+ *    materialised yet).
+ *  - The instruction file carries no `<skill-index>` block (slim
+ *    fetch_window sessions, or future backends that opt out).
+ *
+ * Idempotent — re-running with the same dest contents produces an
+ * identical instruction file.
+ */
+export function refreshSkillIndexBlock(sessionDir, backendId) {
+    // docs/design/appendices/skills-unification.md Phase 1 §R3 — OpenCode never gets a
+    // `<skill-index>` block. The cwd auto-discovery loader is the source
+    // of truth; emitting an index would inject a second listing the
+    // runtime ignores. Also matters in fallback workdirs where codex and
+    // opencode share AGENTS.md: a stray opencode refresh would clobber
+    // the codex-rendered sentinels with opencode's skill listing.
+    if (backendId === "claude" || backendId === "opencode")
+        return;
+    const cliRoot = cliSkillsDirName(backendId);
+    if (cliRoot === null)
+        return;
+    const destSkillsRootRelative = join(cliRoot, "skills");
+    const destSkillsRootAbs = join(sessionDir, destSkillsRootRelative);
+    const fileName = backendId === "gemini" ? "GEMINI.md" : "AGENTS.md";
+    const instructionPath = join(sessionDir, fileName);
+    if (!existsSync(instructionPath))
+        return;
+    const current = readFileSync(instructionPath, "utf-8");
+    // Splice on the HTML-comment sentinels, NOT on the visible
+    // `<skill-index>` tags — the sentinels are unique enough that a
+    // profile body or user-authored skill that quotes the visible tag
+    // cannot collide with the splice region.
+    const startIdx = current.indexOf(SKILL_INDEX_START_SENTINEL);
+    const endIdx = startIdx >= 0
+        ? current.indexOf(SKILL_INDEX_END_SENTINEL, startIdx + SKILL_INDEX_START_SENTINEL.length)
+        : -1;
+    if (startIdx < 0 || endIdx < 0)
+        return; // OpenCode (no index) or slim path
+    const replacement = renderSkillIndexBlock(destSkillsRootAbs, destSkillsRootRelative);
+    const next = current.slice(0, startIdx) +
+        replacement +
+        current.slice(endIdx + SKILL_INDEX_END_SENTINEL.length);
+    if (next !== current) {
+        writeFileSync(instructionPath, next, "utf-8");
+    }
+}
+/**
+ * docs/design/appendices/skills-unification.md Phase 1 §R6 — `adaptSkillForCli` (which used
+ * to retain only `name`/`description`/`when_to_use` and strip
+ * `allowed-tools` from CLI-bound copies) is deleted. The source
+ * SKILL.md frontmatter is byte-identical across all backends post-
+ * materialisation. Codex / Gemini tolerate unknown YAML keys; OpenCode's
+ * permissive frontmatter parser does too (verified against
+ * `docs/design/appendices/opencode-backend.md` §5.5). The `when_to_use:` field has been
+ * dropped from every built-in SKILL.md (Phase 0.1 of the sister doc) so
+ * there is no per-backend fork to maintain.
+ */
 /**
  * Resolve `{{> base }}` include directives in a skill/task-flow variant file.
  * Reads `SKILL.base.md` (or `<key>.base.md` for task flows) from `basePath`
@@ -1313,10 +1951,11 @@ function appendCliDenyBlock(content, namespacedDenied) {
  * own deny list.
  *
  * Hard enforcement of the same deny list for cross-backend delegated
- * calls lives at the `POST /api/integrations/:key/invoke` chokepoint
- * (DELEGATED-MODE-V2-DESIGN.md §4.3.2). For same-backend native MCP it
- * is enforced via SDK `disallowedTools` (Claude) / admin policy
- * (Gemini); see `collectSessionDeniedTools` (§4.3.3).
+ * calls lives at the `POST /api/integrations/:key/exec` task-mode
+ * chokepoint (DELEGATED-MODE-V2-DESIGN.md §4.3.2; the legacy `/invoke`
+ * RPC was retired 2026-05-01). For same-backend native MCP it is
+ * enforced via SDK `disallowedTools` (Claude) / admin policy (Gemini);
+ * see `collectSessionDeniedTools` (§4.3.3).
  */
 export function applyAllDeniedToolsForSkill(content, skillSlug, backendId, integrations) {
     let result = content;