dotmd-cli 0.88.1 → 0.89.1

package/README.md

@@ -37,13 +37,28 @@ integration for whichever host you run:
 ```bash
 runlist install             # what's installed for each host
 runlist install claude      # Claude Code plugin (marketplace + plugin)
+runlist install codex       # Codex skill and hooks (personal marketplace)
 runlist install opencode    # OpenCode plugin (one auto-discovered file)
 runlist doctor --session    # what identity runlist sees here, and from where
 ```
 
-Both are one-time and global; `runlist update` keeps them in step with the CLI.
-Codex needs no install for identity: it exports `CODEX_THREAD_ID` to every tool
-shell, and runlist reads it as a per-session identity automatically.
+The integrations are one-time and global. Codex exports `CODEX_THREAD_ID` to
+every tool shell, so its identity works without the plugin; the plugin adds a
+workflow skill, session orientation, and the tool guard.
+
+### Codex Plugin
+
+`runlist install codex` copies the plugin included in the npm package into the
+personal Codex marketplace and runs `codex plugin add runlist-codex@personal`.
+Codex asks you to review and trust plugin hooks separately. Start a new thread
+after installation so the skill and SessionStart primer load. The hooks use
+the globally installed `runlist` CLI; a missing CLI produces one install hint
+and otherwise leaves tool calls alone. `CODEX_THREAD_ID` stays the ownership
+source. The CLI refuses to overwrite a plugin directory it did not generate.
+
+Direct prompt reads warn by default in Codex and Claude. A repository can set
+`export const guard = { promptReads: 'deny' };` to block reads of existing
+pending prompts; `runlist prompts show` remains the read-only inspection verb.
 
 ### Claude Code Plugin
 
@@ -72,6 +87,9 @@ supplies the two things the CLI cannot get on its own:
 - **A session-start briefing**, the equivalent of Claude Code's SessionStart
   hook. OpenCode's Claude Code compatibility covers skills and the system
   prompt, not hooks, so nothing else runs `runlist hud`.
+- **Prompt-read guardrails.** Recognized reads are checked before execution so
+  the opt-in strict policy can stop them. Default warnings are attached to the
+  result because OpenCode's before hook cannot return model context.
 
 Restart OpenCode after installing. The file is version-stamped (`runlist-generated:`, or
 `dotmd-generated:` from older releases); a `dotmd.js` without either stamp is

package/assets/opencode/plugin.js

@@ -11,10 +11,8 @@
 //     that isn't one — so an exported helper wouldn't just be untidy, it would
 //     be *called* as a second plugin. Helpers stay module-local.
 //
-//  2. NO HOOK MAY THROW. OpenCode awaits hook callbacks inside the request it
-//     is serving; a rejected promise fails the user's chat turn. Every hook
-//     body is wrapped, and a failure degrades to "runlist does nothing here"
-//     rather than to a broken session.
+//  2. Only a deliberate guard denial may throw. OpenCode awaits hooks inside
+//     the chat request, so every other failure degrades to a no-op.
 //
 // Runs under Bun inside the OpenCode process. Node builtins only, no deps.
 
@@ -64,12 +62,9 @@ function runCli(directory, args, input = null) {
   });
 }
 
-// OpenCode runs no Claude Code hooks, so `runlist guard` never sees its tool
-// calls, and sessions opened pending prompts with the read tool, which prints a
-// prompt without archiving it. The guard's answer for a prompt read is a
-// warning, not a block, so it is applied after the call: the teaching text is
-// appended to what the agent sees. Only calls that name a prompt file reach
-// the CLI; everything else costs a regex.
+// OpenCode runs no Claude Code hooks. Evaluate recognized prompt reads before
+// the tool so opt-in strict mode can block them. Its V1 before hook cannot
+// return model context, so ordinary warnings are appended to the result.
 const PROMPT_FILE = /(^|[\\/])prompts[\\/]\S*\.md\b/;
 
 function guardPayload(tool, args) {
@@ -86,6 +81,14 @@ export default async function dotmdOpencodePlugin({ directory }) {
   // Keyed by session so a subagent session primes independently, the way
   // SubagentStart does under Claude Code.
   const primers = new Map();
+  const guardDecisions = new Map();
+
+  async function guardFor(tool, args) {
+    const payload = guardPayload(tool, args);
+    if (!payload) return null;
+    const raw = await runCli(directory, ['guard'], JSON.stringify(payload));
+    return raw ? JSON.parse(raw)?.hookSpecificOutput ?? null : null;
+  }
 
   async function primerFor(sessionId) {
     const key = sessionId ?? '';
@@ -101,6 +104,18 @@ export default async function dotmdOpencodePlugin({ directory }) {
   }
 
   return {
+    'tool.execute.before': async (input, output) => {
+      let refusal = null;
+      try {
+        const decision = await guardFor(input?.tool, output?.args);
+        if (input?.callID && decision) guardDecisions.set(input.callID, decision);
+        if (decision?.permissionDecision === 'deny') {
+          if (input?.callID) guardDecisions.delete(input.callID);
+          refusal = decision.permissionDecisionReason;
+        }
+      } catch { /* a missing/broken guard must not fail the chat turn */ }
+      if (refusal) throw new Error(`[runlist] ${refusal}`);
+    },
     // Ownership identity. OpenCode sets no session-id variable of its own, and
     // `OPENCODE_PID` — what runlist falls back to without this plugin — names the
     // OpenCode *process*, so every session in one TUI shares it and can release
@@ -126,10 +141,10 @@ export default async function dotmdOpencodePlugin({ directory }) {
     // nothing left to refuse.
     'tool.execute.after': async (input, output) => {
       try {
-        const payload = guardPayload(input?.tool, input?.args);
-        if (!payload || typeof output?.output !== 'string') return;
-        const raw = await runCli(directory, ['guard'], JSON.stringify(payload));
-        const note = raw ? JSON.parse(raw)?.hookSpecificOutput?.additionalContext : null;
+        if (typeof output?.output !== 'string') return;
+        const decision = input?.callID ? guardDecisions.get(input.callID) : null;
+        if (input?.callID) guardDecisions.delete(input.callID);
+        const note = (decision ?? await guardFor(input?.tool, input?.args))?.additionalContext;
         if (typeof note === 'string' && note) output.output += `\n\n${note}`;
       } catch { /* a guard failure never touches the tool result */ }
     },

package/bin/dotmd.mjs

@@ -147,8 +147,9 @@ with a one-line recap naming the habit to break.`,
 
   runlist install                report what is installed for each known host
   runlist install claude         install the Claude Code plugin (marketplace + plugin)
+  runlist install codex          install/refresh the Codex plugin (personal marketplace)
   runlist install opencode       install/refresh the OpenCode plugin (global config dir)
-  runlist install <host> --remove
+  runlist install opencode --remove
   runlist install opencode --path <dir>   write to a specific plugin directory
   runlist install opencode --force        overwrite a runlist.js runlist did not write
 
@@ -168,6 +169,12 @@ host gets that a different way:
             under extraKnownMarketplaces with a source that no longer matches;
             runlist names the field but never edits that file.
 
+  codex     Copies the npm-packaged runlist-codex plugin into the personal
+            marketplace and invokes \`codex plugin add\`. It supplies a compact
+            skill, SessionStart orientation, and a PreToolUse guard. Codex
+            requires a separate hook trust review; start a new thread after
+            installing. CODEX_THREAD_ID remains the ownership identity.
+
   opencode  Writes one auto-discovered plugin file. OpenCode has no plugin
             registry but globs \`{plugin,plugins}/*.{ts,js}\` under its global
             config dir, so no opencode.json edit is needed. It supplies two
@@ -302,7 +309,7 @@ Create & Export:
 
 Setup:
   init                              Create starter config + docs directory
-  install [opencode]                Install the agent-host integration (no arg = status)
+  install [claude|codex|opencode]  Install the agent-host integration (no arg = status)
   update [--check|--cli-only|--plugin-only]  Update the CLI + Claude Code plugin (--check reports skew, no network)
   statuses [list|add|set|remove|migrate]  Manage per-project status taxonomy
   help statuses                     Full status vocabulary + unstuck-actions + transitions
@@ -849,7 +856,7 @@ Modes:
   --migrate-prompts      Retrofit pre-existing markdown files under any docs
                          root's prompts/ subdirectory with proper prompt
                          frontmatter (type, status, created from git
-                         history, dotmd_version, context, related_plans).
+                         history, runlist_version, context, related_plans).
                          Skips files that already have frontmatter.
   --migrate-template <file>  Migrate just one plan.
   --migrate-template --include-archived

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dotmd-cli",
-  "version": "0.88.1",
+  "version": "0.89.1",
   "description": "CLI for managing markdown documents with YAML frontmatter — index, query, validate, graph, export, lifecycle, and AI summaries.",
   "type": "module",
   "license": "MIT",
@@ -16,6 +16,7 @@
     "bin/",
     "src/",
     "assets/",
+    "plugins/runlist-codex/",
     "scripts/postinstall.mjs",
     "runlist.config.example.mjs"
   ],

package/plugins/runlist-codex/.codex-plugin/plugin.json

@@ -0,0 +1,18 @@
+{
+  "name": "runlist-codex",
+  "version": "0.89.1",
+  "description": "Runlist workflow skill, session orientation, and tool guard for Codex",
+  "author": {
+    "name": "Reo Owens"
+  },
+  "skills": "./skills/",
+  "interface": {
+    "displayName": "Runlist Codex",
+    "shortDescription": "Plan, handoff, and document workflow for Codex.",
+    "longDescription": "Adds a concise runlist skill, session primer, and prompt/status guard hooks for managed Markdown repositories.",
+    "developerName": "Reo Owens",
+    "category": "Productivity",
+    "capabilities": [],
+    "defaultPrompt": "Show my runlist plans and pending handoffs."
+  }
+}

package/plugins/runlist-codex/bin/runlist-hook

@@ -0,0 +1,86 @@
+#!/bin/sh
+# runlist Codex plugin hook wrapper.
+#
+# The plugin's hooks drive the whole workflow through the PATH `runlist` binary
+# (`runlist hud`, `runlist guard`), falling back to the legacy `dotmd` alias. If a user enables the plugin but hasn't run
+# `npm i -g dotmd-cli`, the binary is missing, the hook errors `command not
+# found`, and the session is primed with *silent nothing* — no signal that the
+# whole workflow is one install away. runlist can't warn about its own absence
+# (it's the thing that's missing), so the check lives here, outside the binary.
+#
+# Usage: runlist-hook [--hint] <runlist-subcommand> [args...]
+#   --hint  emit a one-line install hint to stdout when no CLI is on PATH.
+#           Only SessionStart passes this, so the hint surfaces once per hook
+#           invocation (stdout becomes session context), never on a tool call.
+#
+# When the CLI is missing we always exit 0 with no further output: hooks must
+# stay non-blocking, and the PreToolUse guard in particular must never deny a
+# tool just because the optional CLI isn't installed.
+hint=0
+if [ "$1" = "--hint" ]; then
+  hint=1
+  shift
+fi
+
+if command -v runlist >/dev/null 2>&1; then
+  CLI=runlist
+elif command -v dotmd >/dev/null 2>&1; then
+  CLI=dotmd
+else
+  if [ "$hint" = "1" ]; then
+    echo "runlist plugin: neither \`runlist\` nor \`dotmd\` is on PATH, so its hooks are no-ops. Enable the workflow with: npm i -g dotmd-cli"
+  fi
+  exit 0
+fi
+
+# PreToolUse fast path: the guard fires on matched Bash, apply_patch, and MCP
+# read calls, and
+# a full Node boot (~100ms: CLI startup + config discovery) is pure overhead for
+# the vast majority of payloads no guard rule can possibly match. Every rule
+# needs a `.md` path AND either a prompts/ path (commit/cat/read-prompt) or the
+# word `status` (edit-status) somewhere in the payload — a cheap shell glob
+# decides that without leaving sh. Anything else gets the no-opinion reply
+# (`{}`) directly. False positives here just pay the old cost (Node runs and
+# returns {}); false negatives are impossible because the globs are strictly
+# weaker than the rules they gate.
+if [ "$1" = "guard" ]; then
+  payload=$(cat)
+  # Broad Git forms do not name a .md file in the payload; Node inspects the
+  # actual eligible/staged path set before deciding whether a live prompt is
+  # included. Always route those forms through the guard.
+  case "$payload" in
+    *git*add*|*git*stage*|*git*commit*)
+      printf '%s' "$payload" | "$CLI" "$@"
+      exit $?
+      ;;
+  esac
+  case "$payload" in
+    *.md*)
+      case "$payload" in
+        *prompts/*|*prompts\\*|*status*)
+          printf '%s' "$payload" | "$CLI" "$@"
+          exit $?
+          ;;
+      esac
+      ;;
+  esac
+  printf '{}\n'
+  exit 0
+fi
+
+# UserPromptSubmit fast path is retained for compatibility with the Claude
+# wrapper; Codex does not register that hook here. It would fire on every
+# message that asks for a handoff gets an answer. The glob is strictly weaker
+# than the Node-side match, so a skipped payload could never have matched.
+if [ "$1" = "hud" ] && [ "$2" = "--prompt-submit" ]; then
+  payload=$(cat)
+  case "$payload" in
+    *[Bb][Aa][Tt][Oo][Nn]*|*[Hh][Aa][Nn][Dd]*[Oo][Ff][Ff]*|*[Rr][Ee][Ss][Uu][Mm][Ee]*|*[Pp][Ii][Cc][Kk]*[Uu][Pp]*)
+      printf '%s' "$payload" | "$CLI" "$@"
+      exit 0
+      ;;
+  esac
+  exit 0
+fi
+
+exec "$CLI" "$@"

package/plugins/runlist-codex/hooks/hooks.json

@@ -0,0 +1,16 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "startup|resume|clear|compact",
+        "hooks": [{ "type": "command", "command": "sh \"${PLUGIN_ROOT}/bin/runlist-hook\" --hint hud", "timeout": 5 }]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Bash|apply_patch|mcp__.*__(read_file|read_text_file|read_media_file|read_multiple_files)",
+        "hooks": [{ "type": "command", "command": "sh \"${PLUGIN_ROOT}/bin/runlist-hook\" guard", "timeout": 5 }]
+      }
+    ]
+  }
+}

package/plugins/runlist-codex/skills/runlist/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: runlist
+description: Manage a repository's plans, docs, decisions, and saved prompts with the runlist CLI. Use when starting or closing plan work, checking the plan queue, or creating or consuming a handoff.
+---
+
+# Runlist workflow
+
+Use this skill in repositories with `runlist.config.mjs` or `dotmd.config.mjs`. The CLI is `runlist` (from `dotmd-cli`; `dotmd` remains an alias). The session hook prints a short live orientation. `CODEX_THREAD_ID` is the session identity used for plan claims; do not replace it with a process ID.
+
+- Orient with `runlist plans`. Use `runlist agent-context` for structured state; `runlist briefing` is the comprehensive view and can be large.
+- Start plan work with `runlist use <plan-file>`. It claims the plan, marks it `in-session`, and prints the card.
+- Change status with `runlist set <status> <file> [--note "why"]`; this runs validation, lifecycle hooks, ref repairs, and index updates. Never hand-edit a `status:` field.
+- Close a shipped plan with `runlist archive <file>`; use `partial`, `active`, `awaiting`, or `blocked` when those match the actual state. Valid statuses are repository and type specific: `runlist statuses list --type plan`.
+- For a handoff, write a concrete resume draft, then run `runlist baton [<plan-or-slug>] @<draft-file>`. An owned plan is released in the same operation. If a handoff for that work is pending, inspect it with `runlist prompts show <file>`; keep it if current or pass `--replace` with the new draft. Replacement archives the old text and refreshes exactly one pending prompt.
+- Consume a saved prompt with `runlist use <prompt-file>` (or bare `runlist use` for the oldest). This archives and claims before printing the body. For read-only triage, use `runlist prompts show <file>` or `runlist prompts show --all`; never open pending prompts with a file reader or `cat`.
+- Pending prompts are session-local. Commit the tracked plan or source files named by baton, not `docs/prompts/*.md`.
+- Create a document with `runlist new <type> <name> @<draft-file>`. A draft starting with frontmatter can supply scaffold fields; `type` is fixed by the command.
+- Record a decision with `runlist new decision <plan> --question "…" @<record-file>`; configured registers may also require `--answers`.
+- If a lifecycle mutation reports an abandoned transaction, inspect `runlist doctor --transactions` before retrying. Use `--apply` only for cases the doctor identifies as recoverable.
+
+The `PreToolUse` hook warns on direct pending-prompt reads and denies hand-edited status transitions or Git operations that would include a live prompt. A repo can opt into blocking direct reads of existing pending prompts with `guard: { promptReads: 'deny' }`. Archived prompts and `runlist prompts show` remain readable. Codex requires explicit trust of a plugin's hooks before they run.

package/runlist.config.example.mjs

@@ -13,6 +13,11 @@ export const archiveDir = 'archived';
 // Directories to skip when scanning
 export const excludeDirs = ['evidence'];
 
+// Agent-host tool guard: direct reads of existing pending prompts warn by
+// default. Set promptReads to 'deny' to block those reads before execution;
+// `runlist prompts show` and archived prompt reads remain available.
+// export const guard = { promptReads: 'deny' };
+
 // Floor under the scan surface. `runlist check` fails when it scans fewer docs than
 // this, so a broken root or an over-eager exclude can't read as a clean estate —
 // zero errors and zero docs look identical otherwise. Off when unset. Set it well

package/src/atomic-mutation.mjs

@@ -1159,7 +1159,7 @@ function reserveExclusive(filePath, mode, content, testHooks = {}) {
     fd = openSync(filePath, 'wx', mode);
     const opened = fstatSync(fd, { bigint: true });
     openedIdentity = { dev: opened.dev, ino: opened.ino };
-    const reservationContent = content ?? JSON.stringify({ dotmdReservation: true, pid: process.pid, createdAt: new Date().toISOString() }) + '\n';
+    const reservationContent = content ?? JSON.stringify({ runlistReservation: true, pid: process.pid, createdAt: new Date().toISOString() }) + '\n';
     writeFileSync(fd, reservationContent, 'utf8');
     testHooks.afterReserveWrite?.(filePath);
     testHooks.beforeReserveFsync?.(filePath);
@@ -1357,7 +1357,7 @@ export function moveFileAtomic(sourcePath, targetPath, render, options) {
       for (const item of creations) ensureTransactionDirectory(path.dirname(item.path), transaction, options, item.path);
       try {
         reservation = reserveExclusive(targetPath, source.identity.mode, JSON.stringify({
-          dotmdReservation: true,
+          runlistReservation: true,
           transactionId,
           sourcePath,
           backup,

package/src/codex-integration.mjs

@@ -0,0 +1,81 @@
+// Codex's default personal marketplace is discovered without a CLI registration.
+// The npm package carries this plugin so installation does not need a Git checkout.
+import { cpSync, existsSync, mkdirSync, mkdtempSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const SOURCE = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', 'plugins', 'runlist-codex');
+const NAME = 'runlist-codex';
+const MARKER = '.runlist-generated.json';
+
+export function codexPaths(homedir = os.homedir()) {
+  const root = path.join(homedir, '.agents', 'plugins');
+  // The implicit personal marketplace file lives under ~/.agents/plugins,
+  // but Codex resolves its `./plugins/...` sources relative to the home dir.
+  return { root, marketplace: path.join(root, 'marketplace.json'), plugin: path.join(homedir, 'plugins', NAME) };
+}
+
+function marketplaceAt(file) {
+  if (!existsSync(file)) return { name: 'personal', interface: { displayName: 'Personal' }, plugins: [] };
+  const data = JSON.parse(readFileSync(file, 'utf8'));
+  if (!data || typeof data.name !== 'string' || !Array.isArray(data.plugins)) {
+    throw new Error(`${file} is not a valid personal marketplace`);
+  }
+  return data;
+}
+
+export function codexStatus({ version, homedir = os.homedir() } = {}) {
+  const paths = codexPaths(homedir);
+  let installed = null;
+  try { installed = JSON.parse(readFileSync(path.join(paths.plugin, MARKER), 'utf8')).version; } catch { /* absent or foreign */ }
+  const exists = existsSync(paths.plugin);
+  return { ...paths, exists, foreign: exists && !installed, version: installed, stale: Boolean(installed && version && installed !== version) };
+}
+
+export function installCodexPlugin({ version, homedir = os.homedir(), dryRun = false } = {}) {
+  const sourceVersion = JSON.parse(readFileSync(path.join(SOURCE, '.codex-plugin', 'plugin.json'), 'utf8')).version;
+  if (sourceVersion !== version) throw new Error(`Codex plugin source is ${sourceVersion}, CLI is ${version}`);
+  const status = codexStatus({ version, homedir });
+  if (status.foreign) return { ...status, action: 'refused', reason: 'plugin directory exists without a runlist marker' };
+  let market;
+  try { market = marketplaceAt(status.marketplace); }
+  catch (err) { return { ...status, action: 'refused', reason: err.message }; }
+  const expected = `./plugins/${NAME}`;
+  const entry = market.plugins.find(p => p.name === NAME);
+  if (entry && (entry.source?.source !== 'local' || entry.source?.path !== expected)) {
+    return { ...status, action: 'refused', reason: 'marketplace entry points to a different plugin source' };
+  }
+  if (!entry) market.plugins.push({
+    name: NAME, source: { source: 'local', path: expected },
+    policy: { installation: 'AVAILABLE', authentication: 'ON_INSTALL' }, category: 'Productivity',
+  });
+  if (status.exists && !status.stale && entry) return { ...status, action: 'current', marketplaceName: market.name };
+  if (dryRun) return { ...status, action: status.exists ? 'updated' : 'installed', marketplaceName: market.name, dryRun: true };
+
+  const parent = path.dirname(status.plugin);
+  mkdirSync(parent, { recursive: true });
+  mkdirSync(path.dirname(status.marketplace), { recursive: true });
+  const stage = mkdtempSync(path.join(parent, '.runlist-codex-stage-'));
+  const backup = `${stage}-previous`;
+  const marketStage = `${status.marketplace}.runlist-stage-${process.pid}`;
+  let movedOld = false;
+  let published = false;
+  try {
+    cpSync(SOURCE, stage, { recursive: true });
+    writeFileSync(path.join(stage, MARKER), JSON.stringify({ version }) + '\n');
+    writeFileSync(marketStage, JSON.stringify(market, null, 2) + '\n');
+    if (status.exists) { renameSync(status.plugin, backup); movedOld = true; }
+    renameSync(stage, status.plugin);
+    published = true;
+    renameSync(marketStage, status.marketplace);
+    if (movedOld) rmSync(backup, { recursive: true, force: true });
+  } catch (err) {
+    if (published) rmSync(status.plugin, { recursive: true, force: true });
+    if (movedOld) renameSync(backup, status.plugin);
+    rmSync(stage, { recursive: true, force: true });
+    rmSync(marketStage, { force: true });
+    throw err;
+  }
+  return { ...codexStatus({ version, homedir }), action: status.exists ? 'updated' : 'installed', marketplaceName: market.name };
+}

package/src/config.mjs

@@ -147,9 +147,9 @@ const DEFAULTS = {
   // and users who want usage observability flip this on (or set RUNLIST_JOURNAL=1).
   journal: false,
 
-  // PreToolUse guard behavior. `deny: false` drops the status-edit rules from
-  // deny (block the tool call) back to warn-only teaching context.
-  guard: { deny: true },
+  // PreToolUse guard behavior. `deny: false` drops status edits to warnings;
+  // `promptReads: 'deny'` blocks direct reads of existing pending prompts.
+  guard: { deny: true, promptReads: 'warn' },
 
   presets: {
     stale: ['--status', 'active,ready,planned,blocked,scoping', '--stale', '--sort', 'updated', '--all'],
@@ -667,8 +667,8 @@ export async function resolveConfig(cwd, explicitConfigPath) {
     moduleRequiredStatuses,
 
     indexPath,
-    indexStartMarker: config.index?.startMarker ?? '<!-- GENERATED:dotmd:start -->',
-    indexEndMarker: config.index?.endMarker ?? '<!-- GENERATED:dotmd:end -->',
+    indexStartMarker: config.index?.startMarker ?? '<!-- GENERATED:runlist:start -->',
+    indexEndMarker: config.index?.endMarker ?? '<!-- GENERATED:runlist:end -->',
     indexSnapshot: config.index?.snapshot ?? 'status',
     archivedHighlightLimit: config.index?.archivedLimit ?? 8,
 
@@ -678,7 +678,10 @@ export async function resolveConfig(cwd, explicitConfigPath) {
     presets: config.presets,
     configuredPresetNames: new Set(Object.keys(userConfig.presets ?? {})),
     journal: config.journal === true,
-    guard: { deny: config.guard?.deny !== false },
+    guard: {
+      deny: config.guard?.deny !== false,
+      promptReads: config.guard?.promptReads === 'deny' ? 'deny' : 'warn',
+    },
     hooks,
     configWarnings,
   };

package/src/export.mjs

@@ -99,7 +99,7 @@ export function runExport(argv, config, opts = {}) {
       }
     }
   } else if (format === 'html') {
-    const outDir = output ?? 'dotmd-export';
+    const outDir = output ?? (existsSync('dotmd-export') ? 'dotmd-export' : 'runlist-export');
     const identities = allocateOutputIdentities(index.docs);
     exportHtml(docsWithBody, config, outDir, identities, { dryRun });
     if (dryRun) {

package/src/guard.mjs

@@ -1,7 +1,8 @@
-import { readFileSync } from 'node:fs';
+import { readFileSync, realpathSync } from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { inspectGitCommandPaths } from './git.mjs';
+import { extractFrontmatter, parseSimpleFrontmatter } from './frontmatter.mjs';
 import { recordGuardEvent } from './journal.mjs';
 import { readEnv } from './naming.mjs';
 
@@ -241,7 +242,26 @@ const STREAM_EDITOR_INPLACE = [
   /\bg?awk\b[^|;&<>]*\binplace\b/,
 ];
 
-function evalBash(command, config, inspectGitPaths, baseCwd) {
+function promptReadDecision(filePath, config, deps = {}) {
+  if (config?.guard?.promptReads !== 'deny') return 'warn';
+  if (!isManagedDoc(filePath, config)) return 'warn';
+  const readFile = deps.readFile ?? ((p) => readFileSync(p, 'utf8'));
+  try {
+    const absolute = path.resolve(deps.gitCwd ?? process.cwd(), filePath);
+    const real = p => { try { return realpathSync(p); } catch { return p; } };
+    const roots = config.docsRoots || (config.docsRoot ? [config.docsRoot] : ['docs']);
+    const insideRoot = roots.some(root => {
+      const base = real(path.resolve(config.repoRoot ?? process.cwd(), root));
+      const relative = path.relative(base, real(absolute));
+      return relative && relative !== '..' && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative);
+    });
+    if (!insideRoot) return 'warn';
+    const fm = parseSimpleFrontmatter(extractFrontmatter(readFile(absolute)).frontmatter);
+    return fm.type === 'prompt' && fm.status === 'pending' ? 'deny' : 'warn';
+  } catch { return 'warn'; }
+}
+
+function evalBash(command, config, inspectGitPaths, baseCwd, deps = {}) {
   const segments = shellSegments(command);
   let cwd = baseCwd;
 
@@ -279,7 +299,7 @@ function evalBash(command, config, inspectGitPaths, baseCwd) {
     // Rule B — reading a prompt through the shell instead of consuming it.
     if (SHELL_READERS.has(cmd0) && promptTokens.length) {
       return {
-        decision: 'warn',
+        decision: promptReadDecision(promptTokens[0], config, { ...deps, gitCwd: cwd }),
         rule: 'cat-prompt',
         detail: `${cmd0} ${promptTokens.join(' ')}`,
         reason:
@@ -301,10 +321,10 @@ function evalBash(command, config, inspectGitPaths, baseCwd) {
   return null;
 }
 
-function evalRead(filePath, config) {
+function evalRead(filePath, config, deps = {}) {
   if (!isPromptPath(filePath, config)) return null;
   return {
-    decision: 'warn',
+    decision: promptReadDecision(filePath, config, deps),
     rule: 'read-prompt',
     detail: filePath,
     reason:
@@ -314,6 +334,31 @@ function evalRead(filePath, config) {
   };
 }
 
+// Codex and OpenCode expose patch edits as one string. Only +/- hunk lines
+// count: context mentioning status is an anchor, not an edit. New files are
+// creation, and status on a deleted file is not a hand-edited transition.
+function evalPatch(command, config) {
+  if (typeof command !== 'string') return null;
+  let target = null;
+  let removed = [];
+  let added = [];
+  const changed = () => target && statusLines(removed.join('\n')).join('\n') !== statusLines(added.join('\n')).join('\n');
+  for (const line of command.split('\n')) {
+    const update = line.match(/^\*\*\* Update File: (.+)$/);
+    if (update || /^\*\*\* (?:Add|Delete) File: /.test(line) || line === '*** End Patch') {
+      if (changed()) return editStatusResult(target, config, target);
+      target = update && isManagedDoc(update[1], config) ? update[1] : null;
+      removed = [];
+      added = [];
+      continue;
+    }
+    if (!target || line.startsWith('***')) continue;
+    if (line.startsWith('+')) added.push(line.slice(1));
+    else if (line.startsWith('-')) removed.push(line.slice(1));
+  }
+  return changed() ? editStatusResult(target, config, target) : null;
+}
+
 // Every `status:` line in a snippet, normalized for comparison.
 function statusLines(s) {
   if (typeof s !== 'string') return [];
@@ -359,8 +404,16 @@ export function evaluateGuard(payload, config, deps = {}) {
   const inspectGitPaths = deps.inspectGitPaths
     || ((subcommand, args, cwd) => inspectGitCommandPaths(subcommand, args, cwd ?? deps.gitCwd ?? process.cwd()));
 
-  if (tool === 'Bash') return evalBash(input.command || '', config, inspectGitPaths, deps.gitCwd ?? process.cwd());
-  if (tool === 'Read') return evalRead(input.file_path || '', config);
+  if (tool === 'Bash') return evalBash(input.command || input.cmd || '', config, inspectGitPaths, input.workdir ?? deps.gitCwd ?? process.cwd(), deps);
+  if (tool === 'Read') return evalRead(input.file_path || '', config, deps);
+  if (tool === 'apply_patch') return evalPatch(input.command || input.patchText || '', config);
+  if (/^mcp__.*__(?:read_file|read_text_file|read_media_file|read_multiple_files)$/.test(tool ?? '')) {
+    const paths = Array.isArray(input.paths) ? input.paths : [input.path ?? input.file_path];
+    for (const p of paths) {
+      const result = evalRead(p, config, deps);
+      if (result) return result;
+    }
+  }
   if (tool === 'Edit' || tool === 'Write' || tool === 'MultiEdit') return evalEdit(input, config, deps);
   return null;
 }

package/src/hub-membership.mjs

@@ -273,7 +273,7 @@ export function checkHubMembershipDrift(docs, config) {
     warnings.push({
       path: child.path,
       level: 'warning',
-      message: `is ranked in the body order of \`${hub.path}\` (the list \`runlist runlist next\` walks) but has no \`parent_plan:\`. Add \`parent_plan: ${hub.path}\` so reverse-link tooling (pickup-card Related:, graph) stays consistent.`,
+      message: `is ranked in the body order of \`${hub.path}\` (used by \`runlist runlist next\`) but has no \`parent_plan:\`. Add \`parent_plan: ${hub.path}\` so reverse-link tooling (pickup-card Related:, graph) stays consistent.`,
       meta: { kind: BACKREF_KIND, hub: hub.path, source: 'body-order' },
     });
   }

package/src/index-file.mjs

@@ -5,15 +5,29 @@ import { formatSnapshot } from './render.mjs';
 import { authorizeRepoGeneratedPath } from './managed-path.mjs';
 import { mutateFile } from './atomic-mutation.mjs';
 
+function indexMarkers(current, config) {
+  const start = config.indexStartMarker;
+  const end = config.indexEndMarker;
+  if (current.includes(start) && current.includes(end)) return { start, end };
+  // A config that omitted markers may point at an index from an older release.
+  // Keep updating that block in place; newly initialized indexes use runlist.
+  if (start === '<!-- GENERATED:runlist:start -->' && end === '<!-- GENERATED:runlist:end -->'
+    && current.includes('<!-- GENERATED:dotmd:start -->') && current.includes('<!-- GENERATED:dotmd:end -->')) {
+    return { start: '<!-- GENERATED:dotmd:start -->', end: '<!-- GENERATED:dotmd:end -->' };
+  }
+  return { start, end };
+}
+
 export function renderIndexFile(index, config, current = readFileSync(config.indexPath, 'utf8')) {
-  const start = current.indexOf(config.indexStartMarker);
-  const end = current.indexOf(config.indexEndMarker);
+  const markers = indexMarkers(current, config);
+  const start = current.indexOf(markers.start);
+  const end = current.indexOf(markers.end);
 
   if (start === -1 || end === -1 || end < start) {
     throw new Error(`${config.indexPath} is missing generated block markers.`);
   }
 
-  const before = current.slice(0, start + config.indexStartMarker.length);
+  const before = current.slice(0, start + markers.start.length);
   const after = current.slice(end);
   const generated = `\n\n${renderGeneratedBlock(index, config)}\n`;
   return `${before}${generated}${after}`;
@@ -130,8 +144,9 @@ export function checkIndex(docs, config, opts = {}) {
   }
 
   const current = readFileSync(config.indexPath, 'utf8');
-  const start = current.indexOf(config.indexStartMarker);
-  const end = current.indexOf(config.indexEndMarker);
+  const markers = indexMarkers(current, config);
+  const start = current.indexOf(markers.start);
+  const end = current.indexOf(markers.end);
 
   if (start === -1 || end === -1 || end < start) {
     errors.push({ path: config.indexPath, level: 'error', message: 'Missing generated index block markers.' });

package/src/init.mjs

@@ -53,8 +53,8 @@ export const root = 'docs';
 
 export const index = {
   path: 'docs/docs.md',
-  startMarker: '<!-- GENERATED:dotmd:start -->',
-  endMarker: '<!-- GENERATED:dotmd:end -->',
+  startMarker: '<!-- GENERATED:runlist:start -->',
+  endMarker: '<!-- GENERATED:runlist:end -->',
   archivedLimit: 8,
 };
 
@@ -118,11 +118,11 @@ against the type, and runs the lifecycle hooks.
 
 const STARTER_INDEX = `# Docs
 
-<!-- GENERATED:dotmd:start -->
+<!-- GENERATED:runlist:start -->
 
 _No docs yet. Run \`runlist list\` after creating your first document._
 
-<!-- GENERATED:dotmd:end -->
+<!-- GENERATED:runlist:end -->
 `;
 
 function scanExistingDocs(dir) {
@@ -263,8 +263,8 @@ function generateDetectedConfig(scan, rootPath) {
 
   lines.push('export const index = {');
   lines.push(`  path: '${rootPath}/docs.md',`);
-  lines.push(`  startMarker: '<!-- GENERATED:dotmd:start -->',`);
-  lines.push(`  endMarker: '<!-- GENERATED:dotmd:end -->',`);
+  lines.push(`  startMarker: '<!-- GENERATED:runlist:start -->',`);
+  lines.push(`  endMarker: '<!-- GENERATED:runlist:end -->',`);
   lines.push(`  snapshot: 'status',`);
   lines.push('};');
   lines.push('');

package/src/install.mjs

@@ -9,11 +9,12 @@ import {
 } from './host-integration.mjs';
 import { readInstalledPlugin } from './update.mjs';
 import { executableName, which } from './util.mjs';
+import { codexStatus, installCodexPlugin } from './codex-integration.mjs';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(readFileSync(path.join(__dirname, '..', 'package.json'), 'utf8'));
 
-const HOSTS = ['claude', 'opencode'];
+const HOSTS = ['claude', 'codex', 'opencode'];
 const ALIASES = { 'claude-code': 'claude', claudecode: 'claude' };
 
 function flagValue(argv, name) {
@@ -33,6 +34,7 @@ function hostStates() {
       marketplaceRegistered: plugin ? plugin.marketplaceRegistered : null,
     },
     opencode: { ...opencodeStatus({ version: pkg.version }), detected: opencodeDetected() },
+    codex: codexStatus({ version: pkg.version }),
   };
 }
 
@@ -42,7 +44,7 @@ function reportStatus(json) {
     process.stdout.write(JSON.stringify({ cli: pkg.version, hosts: states }, null, 2) + '\n');
     return;
   }
-  const { claude, opencode } = states;
+  const { claude, codex, opencode } = states;
   process.stdout.write(`${bold('runlist host integrations')}  ${dim(`CLI ${pkg.version}`)}\n\n`);
 
   const claudeBroken = claude.installed && claude.marketplaceRegistered === false;
@@ -52,6 +54,13 @@ function reportStatus(json) {
   process.stdout.write(`  claude    ${claudeState}\n`);
   process.stdout.write(`            ${dim(claude.installed ? claude.id : 'plugin: SessionStart primer, PreToolUse guard, workflow skill')}\n`);
 
+  const codexState = codex.foreign ? yellow('unmanaged directory present')
+    : !codex.exists ? yellow('not installed')
+    : codex.stale ? yellow(`${codex.version} — behind CLI ${pkg.version}`)
+    : green(codex.version);
+  process.stdout.write(`  codex     ${codexState}\n`);
+  process.stdout.write(`            ${dim(codex.plugin)}\n`);
+
   const ocState = opencode.foreign ? yellow('unmanaged file present')
     : !opencode.exists ? yellow('not installed')
     : opencode.stale ? yellow(`${opencode.version} — behind CLI ${pkg.version}`)
@@ -61,6 +70,7 @@ function reportStatus(json) {
 
   const todo = [];
   if (!claude.installed || claudeBroken) todo.push('runlist install claude');
+  if (!codex.exists || codex.stale) todo.push('runlist install codex');
   if (!opencode.exists || opencode.stale) todo.push('runlist install opencode');
   if (todo.length) {
     process.stdout.write('\n');
@@ -73,6 +83,43 @@ function reportStatus(json) {
   }
 }
 
+function installCodex(argv, dryRun, json) {
+  if (argv.includes('--remove')) {
+    process.stderr.write('Codex removal is managed by `codex plugin remove`; the personal marketplace source is left available.\n');
+    process.exitCode = 1;
+    return;
+  }
+  const result = installCodexPlugin({ version: pkg.version, dryRun });
+  if (result.action === 'refused') {
+    if (json) process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+    else process.stderr.write(`refused: ${result.reason}\n`);
+    process.exitCode = 1;
+    return;
+  }
+  if (!json) process.stdout.write(`${dryRun ? '[dry-run] ' : ''}${result.action} codex integration (${pkg.version}) at ${result.plugin}\n`);
+  if (dryRun) {
+    if (json) process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+    return;
+  }
+  const selector = `runlist-codex@${result.marketplaceName}`;
+  if (!which('codex')) {
+    if (json) process.stdout.write(JSON.stringify({ ...result, pluginAdd: 'codex-cli-unavailable' }, null, 2) + '\n');
+    else process.stdout.write(`Install in Codex with: codex plugin add ${selector}\n`);
+    return;
+  }
+  const added = spawnSync(executableName('codex'), ['plugin', 'add', selector], {
+    stdio: json ? 'pipe' : 'inherit', encoding: json ? 'utf8' : undefined,
+    shell: process.platform === 'win32',
+  });
+  if (json) process.stdout.write(JSON.stringify({ ...result, pluginAdd: added.status === 0 ? 'installed' : 'failed', pluginAddExit: added.status }, null, 2) + '\n');
+  if (added.status !== 0) {
+    process.stderr.write(`Codex plugin source is ready; finish installation with: codex plugin add ${selector}\n`);
+    process.exitCode = 1;
+  } else if (!json) {
+    process.stdout.write('Start a new Codex thread and review/trust the plugin hooks to enable the primer and guard.\n');
+  }
+}
+
 function installClaude(argv, dryRun, json) {
   const remove = argv.includes('--remove');
   const steps = planClaudeInstall({ installed: readInstalledPlugin(), hasClaude: which('claude'), remove });
@@ -164,5 +211,6 @@ export function runInstall(argv, _config, opts = {}) {
 
   const dryRun = Boolean(opts.dryRun);
   if (host === 'claude') { installClaude(argv, dryRun, json); return; }
+  if (host === 'codex') { installCodex(argv, dryRun, json); return; }
   installOpencode(argv, dryRun, json);
 }

package/src/migrate-prompts.mjs

@@ -64,7 +64,7 @@ export function migrateOnePrompt(raw, opts = {}) {
       'type: prompt',
       'status: pending',
       `created: ${created}`,
-      `dotmd_version: ${pkg.version}`,
+      `runlist_version: ${pkg.version}`,
       `context: "${context.replace(/"/g, '\\"')}"`,
       'related_plans: []',
     ].join('\n');
@@ -86,7 +86,7 @@ export function migrateOnePrompt(raw, opts = {}) {
   if (!parsed.type) needed.push(['type', 'prompt']);
   if (!parsed.status) needed.push(['status', 'pending']);
   if (!parsed.created) needed.push(['created', created]);
-  if (!parsed.dotmd_version) needed.push(['dotmd_version', pkg.version]);
+  if (!parsed.runlist_version && !parsed.dotmd_version) needed.push(['runlist_version', pkg.version]);
   if (!parsed.context) {
     // Prefer existing `title:` if present, else derive from body/filename.
     const ctx = typeof parsed.title === 'string' ? parsed.title : deriveContext(rawBody || raw, opts.filePath || 'unknown');

package/src/new.mjs

@@ -237,7 +237,7 @@ Status markers (put in heading text):
       `status: ${s}`,
       `created: ${d}`,
       `updated: ${d}`,
-      `dotmd_version: ${pkg.version}`,
+      `runlist_version: ${pkg.version}`,
       `context: ${ctx?.title ? `"${ctx.title.replace(/"/g, '\\"')}"` : ''}`,
       'related_plans:',
     ].join('\n'),

package/src/update.mjs

@@ -6,6 +6,7 @@ import { fileURLToPath } from 'node:url';
 import { green, dim, yellow } from './color.mjs';
 import { executableName, which } from './util.mjs';
 import { CLAUDE_MARKETPLACE, claudeMarketplaceRefusalHint, installOpencodePlugin, opencodeStatus } from './host-integration.mjs';
+import { codexStatus } from './codex-integration.mjs';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(readFileSync(path.join(__dirname, '..', 'package.json'), 'utf8'));
@@ -129,6 +130,11 @@ export function planUpdate(opts, ctx) {
     } else if (ctx.opencode?.foreign) {
       steps.push({ kind: 'skip', reason: `${ctx.opencode.path} was not written by runlist — leaving it alone` });
     }
+    if (ctx.codex?.foreign) {
+      steps.push({ kind: 'skip', reason: `${ctx.codex.plugin} was not written by runlist — leaving it alone` });
+    } else if (ctx.codex?.exists && (ctx.codex.stale || (!opts.pluginOnly && ctx.hasNpm))) {
+      steps.push({ kind: 'codex', cmd: ['runlist', 'install', 'codex'] });
+    }
   }
   return steps;
 }
@@ -158,11 +164,16 @@ export function runUpdate(argv, _config, opts = {}) {
     if (!oc.exists) process.stdout.write(dim('runlist opencode: not installed\n'));
     else if (oc.foreign) process.stdout.write(`runlist opencode: ${yellow('unmanaged file — not written by runlist')}\n`);
     else process.stdout.write(`runlist opencode: ${oc.version} ${oc.stale ? yellow('behind — run `runlist update`') : green('in sync')}\n`);
+    const cx = codexStatus({ version: pkg.version });
+    if (!cx.exists) process.stdout.write(dim('runlist codex: not installed\n'));
+    else if (cx.foreign) process.stdout.write(`runlist codex: ${yellow('unmanaged plugin directory')}\n`);
+    else process.stdout.write(`runlist codex: ${cx.version} ${cx.stale ? yellow('behind — run `runlist update`') : green('in sync')}\n`);
     return;
   }
 
   const opencode = opencodeStatus({ version: pkg.version });
-  const steps = planUpdate({ cliOnly, pluginOnly }, { plugin, opencode, hasClaude: which('claude'), hasNpm: which('npm') });
+  const codex = codexStatus({ version: pkg.version });
+  const steps = planUpdate({ cliOnly, pluginOnly }, { plugin, opencode, codex, hasClaude: which('claude'), hasNpm: which('npm') });
   if (opts.dryRun) {
     for (const step of steps) {
       if (step.kind === 'skip') process.stdout.write(dim(`[dry-run] skip: ${step.reason}\n`));