@nurix/etna 0.19.13 → 0.19.15

package/data/harnesses/kb-agi/codex/agents/kb-init.toml

@@ -0,0 +1,314 @@
+# dropped Claude tools: Read, Glob, Grep, Write, Bash
+name = "kb-init"
+description = "Initializes a kb-agi vault by scaffolding the meta/ control plane — the contract, genre templates and intent lanes generated from the identity-interview answers in the dispatch prompt, the gap ledger, sessions and proposals scaffolds — plus a skeleton Readme.md in every content folder lacking one. Use on a fresh vault, or when the router reports meta/contract.md missing. Re-run to check contract drift. Triggers on \"initialize the vault\", \"init kb-agi\", \"scaffold meta\", \"set up the control plane\"."
+developer_instructions = '''
+You are the **kb-init** agent. One job: stand up the `meta/` control plane a kb-agi vault needs, generate its reader-specific parts from the identity interview, then get out of the way. Every template you need is carried inline below — fully self-contained.
+
+## Inputs
+
+The router conducts the identity interview (you cannot ask the user questions) and dispatches you with:
+
+1. **Vault name and domain** — what this vault is about, in a sentence.
+2. **Reader types** — for each: a short name, what they come for, and a default answer depth (crisp / working / deep).
+3. **Primary intents** — 3–6 "I want to…" lanes for the intent index.
+
+If any of these are missing from your dispatch prompt, stop and report exactly what the router must collect first. Do not invent an identity.
+
+## Boundaries
+
+- You write `meta/` and skeleton folder `Readme.md` files only. **Never** `CLAUDE.md` (ships with the harness; if absent, stop — the harness isn't installed), **never** `meta/_derived/` (built by `kb-export`), **never** content notes.
+- **Never overwrite an existing file.** Create only what's missing; report every file created vs skipped.
+- Every write ends in a git commit.
+
+## Procedure
+
+1. **Installed?** If `CLAUDE.md` is missing at the vault root, stop: the kb-agi harness isn't installed here.
+2. **Already initialized?** If `meta/contract.md` exists, do not re-scaffold. Compare its `contract-version` against the template's below: same → report "initialized, current" and stop; older → report the drift and summarize what changed between the shapes, so a human can fold it in; never overwrite.
+3. **Write the control plane** from the Templates section, filling every `{placeholder}` from your inputs: `meta/contract.md`, one `meta/genres/<type>.md` per reader type, `meta/index.md` (one lane per primary intent + the standing "add knowledge" lane), `meta/gaps.md`, `meta/sessions/README.md`, `meta/proposals/README.md`.
+4. **Scaffold folder self-descriptions.** For every content folder (any folder outside `meta/` and dot-folders that holds `.md` notes) lacking a `Readme.md`: generate one in the skeleton shape below **from the folder's actual contents** — list what's really there, infer the About line, pick the most-linked note(s) as entry notes. Keep the review flag line; the audit's descriptions goal re-surfaces it until a human edits.
+5. **Commit** the scaffold (one commit, message `kb-init: scaffold meta/ control plane`).
+6. **Build the graph:** run `node .claude/scripts/kb-export.mjs` from the vault root.
+7. **Hand off.** Point the user at what they own: `meta/contract.md` (read it), `meta/genres/*.md` (tune the generated framings), and every generated folder `Readme.md` (review the skeletons). Then: ask the vault a question, or run `kb-audit`.
+
+---
+
+# Templates
+
+Fences are 4-backtick so inner 3-backtick blocks survive — strip the outer fence when writing each file. Fill `{placeholders}`; leave everything else byte-exact.
+
+## `meta/contract.md`
+
+````markdown
+---
+contract-version: 1.0.0
+---
+
+<!-- contract-version is the contract-SCHEMA version: it changes only when the shape of this
+     contract changes (new field, new section semantics), never in step with the kb-agi plugin
+     version, which bumps automatically on any payload edit. Do not sync the two. -->
+
+# {Vault name} — the contract
+
+This vault is about: {domain, one sentence}.
+
+This file is the single contract the router (`CLAUDE.md`) and the agents (`kb-audit`, `kb-apply`, `kb-init`) all read first. It defines what a note is, what the frontmatter hints mean, how links resolve, how a folder describes itself, and who may write what. Everything here is a **hint or a convention, not a schema enforced by code** — a note that omits a hint still works; the system degrades gracefully.
+
+## The note model
+
+The vault is one flat Obsidian vault. Every note is the same kind of thing — a markdown note linked to others by `[[wikilinks]]`. No document-type labels, no audience altitude. Folders exist for human convenience and describe themselves via a `Readme.md`.
+
+- **One idea per note.** Push depth into a _linked_ note instead of bloating one; the links carry the depth.
+- **Links are the structure.** The wikilink graph is the one graph, derived from the notes into `meta/_derived/graph.json` by `kb-export` — never hand-maintained.
+- **Notes are the only canon.** Everything under `meta/` is control plane; the derived graph and every index are regenerable.
+
+## Frontmatter hints
+
+All fields optional; a missing field means its default.
+
+```yaml
+---
+title: Human-readable title # default: the H1, else the filename
+maturity: synthesized # raw | captured | synthesized | published — default: captured
+canonical: true # THE current note on its topic? default: true
+visibility: public # public | hidden — default: public
+---
+```
+
+| maturity | meaning |
+| --- | --- |
+| `raw` | dumped in, unprocessed — a capture, a transcript, a paste |
+| `captured` | cleaned up and readable, not yet reconciled with neighbours |
+| `synthesized` | reconciled into the vault's point of view, linked to its neighbours |
+| `published` | load-bearing, citeable as the vault's current position |
+
+`canonical: false` marks a superseded-but-kept note — still reachable, treated as background. When a note supersedes another, the demotion lands **in the same commit** as the successor.
+
+`visibility: hidden` keeps a note in the vault and the graph but marks it for exclusion from any servable corpus (see Handover). An answer may draw on a hidden note only with explicit disclosure — never presented as the vault's position to an external-facing reader.
+
+## Wikilink dialect
+
+Four forms, resolved against the note set (code blocks are never links):
+
+| form | example | resolves to |
+| --- | --- | --- |
+| link | `[[note]]` | the note |
+| alias | `[[note\|shown text]]` | the note; alias is display-only |
+| anchor | `[[note#Heading]]` | the note (heading is a hint) |
+| embed | `![[note]]` | the note, transcluded |
+
+Resolution: an exact path (`[[specs/sso]]`) wins; else a unique basename; a basename shared by several notes is **ambiguous** — an error the shape goal surfaces. Keep titles and basenames unique.
+
+## Folder self-description — `Readme.md`
+
+Every content folder carries a `Readme.md`: the folder's landing page for humans **and** the checklist the coverage goal audits. Fixed shape:
+
+```markdown
+# <folder name>
+
+**About.** One or two sentences: what this folder holds and why.
+
+**Should contain.** The kinds of notes that belong here — the coverage checklist.
+
+**Entry notes.** The 1–3 notes to start from. (`[[wikilinks]]`)
+
+**Neighbours.** Folders this one links to most.
+```
+
+It describes the folder rather than holding an idea; losing one costs orientation, not knowledge.
+
+## Note shape
+
+- One idea per note; a note pushing past ~150 lines is a split candidate (depth moves to linked notes).
+- Unique titles and basenames — collisions break resolution and retrieval; `kb-export` reports them.
+- Frontmatter must parse (plain `key: value` scalars).
+
+## Who writes what
+
+| actor | reads | writes |
+| --- | --- | --- |
+| router, ask path | everything | `meta/sessions/` only |
+| router, contribute path | everything | content notes — a human steering every write |
+| `kb-audit` | everything | `meta/proposals/`, `meta/gaps.md`, session `processed` flags — never canon |
+| `kb-apply` | one open proposal | exactly that proposal's items (canon + entry points), then the proposal's status |
+| `kb-init` | — | the `meta/` scaffold + skeleton folder `Readme.md`s, once |
+| `kb-export` | every note | `meta/_derived/graph.json` only |
+
+Every agent mutation of canon flows **audit → proposal → human review → apply → git commit**. Every write, by anyone, is a git commit.
+
+## Deployment model
+
+The vault is a git repository; **one writer per clone**, sharing via push/pull. Session logs, proposals, and gap-ledger updates are commits like everything else. Session files carry a collision-safe suffix (see `meta/sessions/README.md`). This model is declared, not enforced — if you need concurrent writers in one checkout, you need a different harness.
+
+## Genre — the reader, not the document
+
+`genre` labels **who is asking** — never a note. Its only effect is the default depth and framing of answers, per `meta/genres/`. It never changes which notes exist or are reachable.
+
+## The control plane
+
+| path | what it is |
+| --- | --- |
+| `meta/contract.md` | this file |
+| `meta/genres/` | reader-type templates — default depth + entry points |
+| `meta/index.md` | "Read by need" — intent-keyed entry lanes |
+| `meta/gaps.md` | the gap ledger — the living content roadmap (owned by `kb-audit`) |
+| `meta/sessions/` | query logs — every ask, and whether it could be answered |
+| `meta/proposals/` | upkeep findings awaiting review, and the applied record |
+| `meta/_derived/` | the derived graph — regenerate with `node .claude/scripts/kb-export.mjs`, never edit |
+
+## Handover — this vault as a RAG corpus
+
+The repo is the index package; an ingesting system should read it as:
+
+| artifact | RAG role |
+| --- | --- |
+| content notes | the chunks — atomic, titled, author-bounded |
+| note frontmatter | metadata filters (`canonical`, `maturity`); `visibility: hidden` → exclude from the servable corpus |
+| `meta/_derived/graph.json` (`schema: kb-graph/1`, additive-only evolution) | graph expansion and re-ranking |
+| folder `Readme.md` files | curated cluster summaries |
+| `meta/index.md` | intent → entry-point routing hints |
+| `meta/gaps.md` | known-unanswerable list — answer "recorded gap" instead of hallucinating |
+| this file | the ingestion spec |
+
+A downstream system may write its own misses into `meta/sessions/` in the standard format — the coverage goal ingests them exactly like the router's, and the vault grows in response.
+````
+
+## `meta/genres/<type>.md` — one per reader type, generated
+
+Generate one file per reader type from the interview, following this shape exactly; write real content from what the reader wants, never placeholder text:
+
+````markdown
+# genre — {Reader type}
+
+{Who this reader is and what they come to the vault for — one or two sentences, from the interview.}
+
+**Default depth.** {crisp | working | deep} — {how an answer should open for this reader, one sentence.}
+
+**Framing.** {What to lead with and what to cite for this reader, one or two sentences.}
+
+**Start from.**
+
+- `meta/index.md` → {the lanes matching this reader's intents}
+- {the kinds of notes to lead with, e.g. "canonical, published positioning notes"}
+
+**Adjust.** {When to go deeper or compress; when to hand off toward another genre's depth.}
+````
+
+## `meta/index.md`
+
+Create one `##` lane per primary intent from the interview (replacing the example lane), each with the italic empty-marker line, then the standing final lane verbatim:
+
+````markdown
+# index — Read by need
+
+The front door, keyed on **what you're trying to do**, not who you are. Each lane lists entry notes; the links carry you from there. Kept current by the entrances goal of `kb-audit`. An empty lane is a known gap, not an error.
+
+## "{I want to …}"
+
+_{one-line description of the intent}_
+
+- _empty — populated as content lands_
+
+## "I want to add knowledge"
+
+_You have something the vault doesn't hold yet._
+
+- `meta/gaps.md` — what the vault is missing and wants next
+- `meta/contract.md` — the note model and where things belong
+````
+
+## `meta/gaps.md`
+
+````markdown
+# gaps — the content roadmap
+
+The living ledger of what the vault should hold but doesn't. **Written only by `kb-audit`'s coverage goal**, which folds in verified session gaps and folder-promise diffs, deduplicates, ranks (reader-hit above folder-promise), and checks off entries reality now covers. Readers and contributors: read this, don't edit it — landing a note that closes a gap is how an entry gets checked off.
+
+Entry format: `- [ ] {what's missing} — {folder it belongs in} — {why: session | promise | both}`
+
+## Content gaps
+
+_none recorded yet_
+
+## Navigation gaps
+
+_Knowledge that exists but can't be reached from the entry lanes — link work, not writing work._
+
+_none recorded yet_
+````
+
+## `meta/sessions/README.md`
+
+````markdown
+# sessions — query logs
+
+Every ask the router handles is logged here: it lets a reader resume later, and a question the vault **couldn't** answer feeds the gap ledger. This is the only thing the read-only ask path writes. A downstream system (e.g. a RAG service over this vault) may write its misses here in the same format — they're ingested identically.
+
+One file per session, named `YYYY-MM-DD-<slug>-<hhmm>.md` (the time suffix keeps clones collision-safe):
+
+```markdown
+---
+date: 2026-07-10
+genre: pm # or unknown
+answered: partial # yes | partial | no
+processed: false # flipped by kb-audit's coverage goal once folded into the ledger
+---
+
+## Q: <the question, in the asker's words>
+
+**Depth taken.** <crisp | working | deep>
+
+**Notes used.** [[note-a]], [[note-b]]
+
+**Gap.** <only if answered is partial/no, and only after searching the whole vault: what's truly
+missing (content gap) — or, if the answer existed but wasn't reachable from the entry lanes,
+say so (navigation gap).>
+```
+
+`processed: true` sessions have been folded into `meta/gaps.md` and may be pruned by a human.
+````
+
+## `meta/proposals/README.md`
+
+````markdown
+# proposals — upkeep findings awaiting review
+
+Every `kb-audit` run writes its findings as one proposal file here; nothing changes in the vault until a human reviews it and `kb-apply` executes it. This folder is both the review queue (`status: open`) and the applied record (`status: applied`).
+
+One file per audit run, named `YYYY-MM-DD-<goals>-<hhmm>.md`:
+
+```markdown
+---
+status: open # open | applied
+date: 2026-07-10
+goals: [coverage, graph]
+---
+
+## Health
+
+answered (last 10 sessions): 7 yes / 2 partial / 1 no · open gaps: 4 (2 new) · dead links: 3 · orphans: 1 · collisions: 0
+
+## Items
+
+- [ ] coverage · write missing note — `product/`: "pricing-tiers" (reader-hit ×2 + folder promise; link from [[positioning]])
+- [ ] graph · fix dead link — [[roadmap]] in `product/positioning.md` → renamed to [[product-roadmap]]
+```
+
+**Review = edit this file.** Delete any line you veto; what remains is the mandate. `kb-apply` executes the surviving unchecked items exactly, checks them off, flips `status: applied`, and commits with this file referenced. Items an agent couldn't complete stay unchecked with a note appended.
+```` 
+
+## `<content folder>/Readme.md` — skeleton, per folder lacking one
+
+````markdown
+# {folder name}
+
+> review: generated skeleton — a human should edit this description. (`kb-audit` re-surfaces this flag until edited.)
+
+**About.** {inferred from the notes actually present}
+
+**Should contain.** {the kinds of notes observed here — this is the coverage checklist; extend it with what SHOULD be here}
+
+**Entry notes.** {the 1–3 most-linked or most central notes, as [[wikilinks]]}
+
+**Neighbours.** {folders these notes link to most}
+````
+'''

package/data/harnesses/kb-agi/harness.json

@@ -7,5 +7,5 @@
     ".prettierignore",
     ".vscode/settings.json"
   ],
-  "digest": "2132e273abb1"
+  "digest": "11b127dd4a61"
 }

package/lib/codex/README.md

@@ -0,0 +1,31 @@
+# `lib/codex` — Claude→Codex projection
+
+Turns a harness's already-materialized Claude artifacts into their OpenAI Codex counterparts, so one harnessed repo works under **both** Claude Code and Codex. Consumed by both shippers — the installer (`bin/etna.js`) and the marketplace publisher (`.github/scripts/publish.mjs`) — through one module, so the two channels can't drift (the same "keep in agreement" rule as the `evals/`/`fixtures/` ship-filter).
+
+Owning doc: [`docs/features/codex-support.md`](../../../../docs/features/codex-support.md).
+
+## What it emits
+
+| Source | Target | File |
+| --- | --- | --- |
+| `CLAUDE.md` | `AGENTS.md` (exact copy) | `agents-md.mjs` |
+| `.claude/skills/` | `.agents/skills/` (mirror) | `skills.mjs` |
+| bundle `codex/agents/*.toml` | `.codex/agents/*.toml` (copy) | `subagents.mjs` |
+| `hooks.json` | `.codex/hooks.json` (`type:"command"` only) | `hooks.mjs` |
+| `.claude-plugin/*` | `.codex-plugin/plugin.json` + `.agents/plugins/marketplace.json` | `plugin-manifest.mjs` |
+
+`index.mjs` orchestrates the install-time projectors and returns `{installed, notices, warnings, owned}`; `owned` is recorded in `.claude/harness.json` → `owned.codex` for prune-on-refresh.
+
+**Out of scope (owner decision 2026-07-13):** MCP projection and any Codex `settings.json`/`config.toml` equivalent. There is no user-editable Codex file the harness co-owns, so every Codex path is a clean full-overwrite — no managed-block merge.
+
+## Subagents are authored, not derived at install
+
+`.claude/agents/*.md → .codex/agents/*.toml` is lossy/semantic, so it is done by the **real Codex CLI** at authoring time, not a parser at install:
+
+```bash
+node packages/cli/lib/codex/gen-agents.mjs                 # shared catalog (agents/*.md), stale/missing only
+node packages/cli/lib/codex/gen-agents.mjs --force          # regenerate all shared agents
+node packages/cli/lib/codex/gen-agents.mjs --include-plugins # + plugins/*/agents/*.md
+```
+
+`gen-agents.mjs` runs `codex exec` per agent and writes a committed `agents/<name>.codex.toml` sibling. It runs **only on a laptop with `codex` installed + authenticated — never in CI**. `build-data.js` and `publish.mjs` then ship those committed TOML; the installer copies them, so **consumers need no Codex CLI**. Regenerate an agent's TOML in the same change that edits its `.md` (source↔generated parity).

package/lib/codex/agents-md.mjs

@@ -0,0 +1,35 @@
+// packages/cli/lib/codex/agents-md.mjs
+// CLAUDE.md → AGENTS.md — an exact copy (Codex's confirmed CLAUDE.md analog).
+// Mirrors the installer's CLAUDE.md safety net: overwrite in place when git can
+// recover it, otherwise back up the existing file and warn.
+
+import { existsSync, lstatSync, renameSync, cpSync } from 'node:fs';
+import { join } from 'node:path';
+
+function isSymlink(path) {
+    try {
+        return lstatSync(path).isSymbolicLink();
+    } catch {
+        return false;
+    }
+}
+
+export function projectAgentsMd({ targetDir, bundledClaudeMd, projectHasGit }) {
+    if (!existsSync(bundledClaudeMd)) return null;
+    const dest = join(targetDir, 'AGENTS.md');
+    const existed = existsSync(dest) || isSymlink(dest);
+    let notice = null;
+    let warning = null;
+    if (existed) {
+        if (projectHasGit) {
+            notice = 'Overwrote existing AGENTS.md (tracked by git — `git checkout AGENTS.md` to restore).';
+        } else {
+            const ts = new Date().toISOString().replace(/[:.]/g, '-');
+            const backup = `${dest}.bak.${ts}`;
+            renameSync(dest, backup);
+            warning = `No .git here, so no version-control safety net — backed up existing AGENTS.md → ${backup}`;
+        }
+    }
+    cpSync(bundledClaudeMd, dest, { force: true });
+    return { installed: 'AGENTS.md → ./', notice, warning };
+}

package/lib/codex/gen-agents.mjs

@@ -0,0 +1,156 @@
+// packages/cli/lib/codex/gen-agents.mjs
+// AUTHORING-TIME generator — runs ON A LAPTOP with the Codex CLI installed and
+// authenticated, NEVER in CI. For each Claude subagent (agents/<name>.md in the
+// shared catalog, plus plugins/*/agents/*.md with --include-plugins) it runs
+// `codex exec` to translate the markdown into an OpenAI Codex subagent TOML and
+// writes a committed sibling agents/<name>.codex.toml. The shippers (build-data.js,
+// publish.mjs) then carry those committed files; the installer copies them into a
+// consumer's .codex/agents/ with no Codex CLI required downstream.
+//
+// Usage:
+//   node packages/cli/lib/codex/gen-agents.mjs            # shared catalog, only stale/missing
+//   node packages/cli/lib/codex/gen-agents.mjs --force    # regenerate all shared agents
+//   node packages/cli/lib/codex/gen-agents.mjs --include-plugins  # + plugins/*/agents/*.md
+
+import {
+    existsSync,
+    readdirSync,
+    readFileSync,
+    writeFileSync,
+    statSync,
+} from 'node:fs';
+import { dirname, join, resolve, basename } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { spawnSync } from 'node:child_process';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const repoRoot = resolve(__dirname, '..', '..', '..', '..');
+
+// Pinned conversion prompt — deterministic instructions so re-runs stay stable.
+// Codex does the semantic md→toml; the body is copied verbatim, tools are dropped
+// (no Codex equivalent) and recorded in a leading comment.
+const CONVERSION_PROMPT = [
+    'Convert the Claude Code subagent definition provided on stdin into an OpenAI Codex subagent TOML document.',
+    'Output ONLY the raw TOML — no prose, no markdown code fences, nothing before or after.',
+    'Set `name` from the frontmatter `name`.',
+    'Set `description` as a TOML basic string (double quotes) from the frontmatter `description`, escaping any interior double-quote as \\".',
+    'Put the ENTIRE markdown body (everything after the closing frontmatter ---) VERBATIM into a TOML multi-line',
+    "LITERAL string delimited by triple SINGLE quotes: developer_instructions = '''<body>'''.",
+    'A literal string is verbatim — do NOT escape anything inside it, and do NOT use triple double-quotes (backslashes like \\s in the body must survive unchanged).',
+    'If frontmatter `model` is a real model id, set `model`; if it is `inherit`, omit `model`.',
+    'If frontmatter has a `tools:` line, do NOT translate it — instead put a single comment line',
+    '`# dropped Claude tools: <the list>` as the first line of the file.',
+    'Emit no keys other than name, description, model (optional), developer_instructions.',
+].join(' ');
+
+const args = process.argv.slice(2);
+const force = args.includes('--force');
+const includePlugins = args.includes('--include-plugins');
+
+function die(msg) {
+    console.error(`gen-codex-agents: ${msg}`);
+    process.exit(1);
+}
+
+// Codex must be present + authenticated — this step cannot run in CI.
+function assertCodexReady() {
+    const which = spawnSync('codex', ['--version'], { encoding: 'utf8' });
+    if (which.status !== 0) {
+        die('the `codex` CLI is not installed / not on PATH. This generator runs only on an authoring laptop.');
+    }
+}
+
+// Every agents/<name>.md to convert: the shared catalog, plus plugin-owned agents on request.
+function collectAgentFiles() {
+    const files = [];
+    const shared = join(repoRoot, 'agents');
+    if (existsSync(shared)) {
+        for (const f of readdirSync(shared)) {
+            if (f.endsWith('.md')) files.push(join(shared, f));
+        }
+    }
+    if (includePlugins) {
+        const pluginsDir = join(repoRoot, 'plugins');
+        if (existsSync(pluginsDir)) {
+            for (const plugin of readdirSync(pluginsDir)) {
+                const agentsDir = join(pluginsDir, plugin, 'agents');
+                if (!existsSync(agentsDir)) continue;
+                for (const f of readdirSync(agentsDir)) {
+                    if (f.endsWith('.md')) files.push(join(agentsDir, f));
+                }
+            }
+        }
+    }
+    return files.sort();
+}
+
+// A regen is due when forced, the toml is missing, or the md is newer than the toml.
+function needsRegen(mdPath, tomlPath) {
+    if (force || !existsSync(tomlPath)) return true;
+    return statSync(mdPath).mtimeMs > statSync(tomlPath).mtimeMs;
+}
+
+// Strip an accidental ```toml fence if the model wrapped its output despite the prompt.
+function stripFences(text) {
+    const trimmed = text.trim();
+    const fence = trimmed.match(/^```(?:toml)?\n([\s\S]*?)\n```$/);
+    return (fence ? fence[1] : trimmed) + '\n';
+}
+
+// Validate that the produced TOML parses. Uses python3's tomllib when present
+// (returns true/error string); returns null when python3 is unavailable so the
+// caller proceeds best-effort rather than hard-failing on a missing dev tool.
+function tomlError(toml) {
+    const res = spawnSync('python3', ['-c', 'import tomllib,sys; tomllib.loads(sys.stdin.read())'], {
+        input: toml,
+        encoding: 'utf8',
+    });
+    if (res.error && res.error.code === 'ENOENT') return null;
+    return res.status === 0 ? '' : (res.stderr || 'invalid TOML').trim();
+}
+
+function convert(mdPath) {
+    const md = readFileSync(mdPath, 'utf8');
+    const res = spawnSync('codex', ['exec', '--sandbox', 'read-only', CONVERSION_PROMPT], {
+        input: md,
+        encoding: 'utf8',
+        maxBuffer: 32 * 1024 * 1024,
+    });
+    if (res.status !== 0) {
+        throw new Error(`codex exec failed for ${mdPath}: ${(res.stderr || '').slice(-400)}`);
+    }
+    const toml = stripFences(res.stdout || '');
+    if (!/^\s*name\s*=/m.test(toml)) {
+        throw new Error(`codex output for ${mdPath} has no \`name =\` key — refusing to write. Got:\n${toml.slice(0, 200)}`);
+    }
+    const err = tomlError(toml);
+    if (err) {
+        throw new Error(`codex output for ${mdPath} is not valid TOML — refusing to write:\n${err.slice(0, 300)}`);
+    }
+    return toml;
+}
+
+assertCodexReady();
+const files = collectAgentFiles();
+if (!files.length) die('no agents/*.md found to convert.');
+
+let wrote = 0;
+let skipped = 0;
+for (const mdPath of files) {
+    const name = basename(mdPath, '.md');
+    const tomlPath = join(dirname(mdPath), `${name}.codex.toml`);
+    if (!needsRegen(mdPath, tomlPath)) {
+        skipped += 1;
+        continue;
+    }
+    process.stdout.write(`converting ${name} … `);
+    try {
+        writeFileSync(tomlPath, convert(mdPath));
+        wrote += 1;
+        console.log('ok');
+    } catch (e) {
+        console.log('FAILED');
+        console.error(`  ${e.message}`);
+    }
+}
+console.log(`\ngen-codex-agents: wrote ${wrote}, skipped ${skipped} (up-to-date) of ${files.length} agent(s).`);

package/lib/codex/hooks.mjs

@@ -0,0 +1,33 @@
+// packages/cli/lib/codex/hooks.mjs
+// .claude/hooks/hooks.json → .codex/hooks.json. Same JSON shape Codex documents;
+// filtered to type:"command" (the only hook type Codex executes — "prompt"/"agent"
+// entries are parsed but skipped). A standalone file, not a config.toml [hooks]
+// table, since the settings/config surface is out of scope for Codex here.
+
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+
+export function projectHooks({ targetDir, bundledHarnessDir }) {
+    const srcJson = join(bundledHarnessDir, 'hooks', 'hooks.json');
+    if (!existsSync(srcJson)) return null;
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(srcJson, 'utf8'));
+    } catch {
+        return null;
+    }
+    const out = {};
+    for (const [event, groups] of Object.entries(parsed.hooks || {})) {
+        const kept = [];
+        for (const group of groups) {
+            const hooks = (group.hooks || []).filter((h) => h.type === 'command');
+            if (hooks.length) kept.push({ ...group, hooks });
+        }
+        if (kept.length) out[event] = kept;
+    }
+    if (!Object.keys(out).length) return null;
+    const dest = join(targetDir, '.codex', 'hooks.json');
+    mkdirSync(dirname(dest), { recursive: true });
+    writeFileSync(dest, JSON.stringify({ hooks: out }, null, 2) + '\n');
+    return { installed: '.codex/hooks.json' };
+}

package/lib/codex/index.mjs

@@ -0,0 +1,62 @@
+// packages/cli/lib/codex/index.mjs
+// Claude→Codex projection entry. Derives a repo's Codex-native artifacts
+// (AGENTS.md, .agents/skills/, .codex/agents/, .codex/hooks.json) from the
+// just-installed Claude tree + the harness bundle. Consumed by BOTH shippers —
+// the installer (bin/etna.js) and the marketplace publisher (publish.mjs) — so
+// the two distribution channels can never diverge (the same "keep in agreement"
+// discipline as the evals/fixtures ship-filter). MCP and a settings/config.toml
+// equivalent are deliberately OUT of scope (owner decision 2026-07-13); see
+// docs/features/codex-support.md.
+
+import { existsSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { projectAgentsMd } from './agents-md.mjs';
+import { projectSkills } from './skills.mjs';
+import { copyCodexAgents } from './subagents.mjs';
+import { projectHooks } from './hooks.mjs';
+
+// Project every Codex artifact into targetDir. Returns the same {installed,
+// notices, warnings} accounting shape the installer already collects, plus
+// `owned` — the top-level Codex targets, recorded in harness.json's
+// `owned.codex` so a later version can prune one it stops shipping.
+export function projectCodexArtifacts({
+    targetDir,
+    bundledHarnessDir,
+    bundledClaudeMd,
+    projectHasGit,
+    priorCodexOwned = [],
+}) {
+    const installed = [];
+    const notices = [];
+    const warnings = [];
+    const owned = [];
+
+    const collect = (result, ownedPath) => {
+        if (!result) return;
+        if (result.installed) installed.push(result.installed);
+        if (result.notice) notices.push(result.notice);
+        if (result.warning) warnings.push(result.warning);
+        owned.push(ownedPath);
+    };
+
+    // AGENTS.md — exact copy of CLAUDE.md, with the CLAUDE.md backup-if-no-git rule.
+    collect(projectAgentsMd({ targetDir, bundledClaudeMd, projectHasGit }), 'AGENTS.md');
+    // .agents/skills — full-rebuilt mirror of the installed (already ship-filtered) .claude/skills.
+    collect(projectSkills({ targetDir, projectHasGit }), '.agents/skills');
+    // .codex/agents — copy the shipped, pre-generated *.toml (see gen-agents.mjs).
+    collect(copyCodexAgents({ targetDir, bundledHarnessDir, projectHasGit }), '.codex/agents');
+    // .codex/hooks.json — Claude hooks.json filtered to type:"command".
+    collect(projectHooks({ targetDir, bundledHarnessDir }), '.codex/hooks.json');
+
+    // Prune a Codex target a prior version owned but this bundle no longer emits.
+    for (const rel of priorCodexOwned) {
+        if (owned.includes(rel)) continue;
+        const target = join(targetDir, rel);
+        if (existsSync(target)) {
+            rmSync(target, { recursive: true, force: true });
+            notices.push(`removed orphaned codex ${rel}`);
+        }
+    }
+
+    return { installed, notices, warnings, owned };
+}