@azure-id/orc 0.55.0

package/bin/webui/serve.js

@@ -0,0 +1,557 @@
+"use strict";
+/**
+ * serve.js — the `orc ui` http server.
+ *
+ * NOTE THE NAME: this is `bin/webui/`, not `bin/ui/`. `bin/ui.js` is the
+ * TERMINAL styling kit (colors, glyphs, boxes) the CLI prints through. Two
+ * different things; the user-facing command is still `orc ui`.
+ *
+ * The server can write config, so it is treated as a write surface throughout:
+ * loopback bind only, a per-launch token on every /api call, a Host-header
+ * check against DNS rebinding, no CORS headers at all, POST-only mutations,
+ * and a token that is never logged.
+ *
+ * It never runs a lane, never spawns `claude`, never calls a model API. Every
+ * byte it serves or writes comes from `bin/cli.js`.
+ */
+
+const http = require("http");
+const fs = require("fs");
+const path = require("path");
+const crypto = require("crypto");
+const { spawn } = require("child_process");
+const { handleApi } = require("./api.js");
+
+const DEFAULT_PORT = 9921;
+const PORT_WALK_MAX = 9930;
+// No heartbeat from ANY client for this long → exit. Closing the tab shuts the
+// server down within about a minute.
+const HEARTBEAT_GRACE_MS = 60_000;
+// Backstop for a client that died without a beacon (laptop sleep, browser
+// crash, killed tab process) — it never sent a heartbeat OR a bye.
+const DEFAULT_IDLE_MIN = 30;
+const LOCK_REL = path.join("orc", "ui.lock");
+
+// ── the static map ──────────────────────────────────────────────────────────
+// The panel is ~55 files (v0.48.1), so the old hand-written table became a
+// maintenance trap: a new stylesheet that nobody added to it 401s, and the
+// symptom is an unstyled page rather than an error anyone can read.
+//
+// It is built by a ONE-TIME walk at server start, never per request. A request
+// path is therefore still a KEY LOOKUP in a frozen table and never a path join
+// — directory traversal stays structurally impossible, which is a STRONGER
+// guarantee than the hand-written table gave, not a weaker one.
+//
+// The string tables are static assets rather than an API route on purpose:
+// they are shipped data with no CLI behind them, so adding a language is
+// dropping JSON into i18n/ and naming it in LANGS — no server change.
+const TYPES = {
+  ".html": "text/html; charset=utf-8",
+  ".css": "text/css; charset=utf-8",
+  ".js": "text/javascript; charset=utf-8",
+  ".json": "application/json; charset=utf-8",
+};
+
+// Server-side code is NEVER served. These are required by node, not fetched by
+// the browser, and shipping them would hand a reader the API surface map.
+const NEVER_SERVE = new Set(["serve.js", "api.js", "fixtures.js"]);
+
+function buildStatic(rootDir) {
+  const map = Object.create(null);
+  const walk = (dir, prefix) => {
+    for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+      const rel = prefix ? prefix + "/" + e.name : e.name;
+      // fixtures/ is canned data for `--fixtures`; api.js reads it in-process.
+      if (e.isDirectory()) {
+        if (e.name === "fixtures") continue;
+        walk(path.join(dir, e.name), rel);
+        continue;
+      }
+      if (NEVER_SERVE.has(rel)) continue;
+      const type = TYPES[path.extname(e.name)];
+      if (!type) continue;
+      // The key is the POSIX-normalised path relative to bin/webui/, so Windows
+      // and macOS agree on it — the /api/fs/list precedent.
+      map["/" + rel] = { file: path.join(...rel.split("/")), type };
+    }
+  };
+  walk(rootDir, "");
+  map["/"] = map["/app.html"];
+  return map;
+}
+
+const STATIC = buildStatic(__dirname);
+
+// ── the lock file ───────────────────────────────────────────────────────────
+// `.claude/orc/ui.lock` — project-scoped like everything else, and the thing
+// that makes re-running `orc ui` idempotent, `--stop` possible, and a forgotten
+// server findable. It lives under .claude/orc/, which `isPrunable` in cli.js
+// can never match, so `orc update --prune` will not delete it.
+
+function lockPath(claudeDir) {
+  return path.join(claudeDir, LOCK_REL);
+}
+
+function readLock(claudeDir) {
+  try {
+    const raw = JSON.parse(fs.readFileSync(lockPath(claudeDir), "utf8"));
+    if (raw && raw.pid && raw.port && raw.token) return raw;
+  } catch (_) {}
+  return null;
+}
+
+function writeLock(claudeDir, data) {
+  const p = lockPath(claudeDir);
+  fs.mkdirSync(path.dirname(p), { recursive: true });
+  fs.writeFileSync(p, JSON.stringify(data, null, 2) + "\n");
+}
+
+function removeLock(claudeDir) {
+  try {
+    fs.rmSync(lockPath(claudeDir));
+  } catch (_) {}
+}
+
+function pidAlive(pid) {
+  try {
+    // Signal 0 tests for existence without touching the process.
+    process.kill(pid, 0);
+    return true;
+  } catch (e) {
+    // EPERM means it exists and belongs to someone else — still alive.
+    return e.code === "EPERM";
+  }
+}
+
+// A lock whose pid is dead is stale: delete it and start fresh.
+function liveLock(claudeDir) {
+  const lock = readLock(claudeDir);
+  if (!lock) return null;
+  if (pidAlive(lock.pid)) return lock;
+  removeLock(claudeDir);
+  return null;
+}
+
+function urlFor(port, token) {
+  return `http://127.0.0.1:${port}/?t=${token}`;
+}
+
+// ── restarting in place ─────────────────────────────────────────────────────
+//
+// `orc upgrade` replaces the package this process is RUNNING FROM. Node read
+// bin/webui into memory at require time, and `STATIC` is a one-time walk at
+// boot, so an upgraded panel keeps serving the old bytes until something
+// restarts it. Until now that something was the user: stop the server, re-run
+// `orc ui`, find the new URL, open it. Three manual steps to see the release
+// they just installed.
+//
+// So the server hands itself over. The successor is spawned DETACHED with the
+// SAME port and the SAME token, which is the whole trick — the URL in the
+// user's address bar stays valid, so the open tab only has to reload.
+//
+// THE TOKEN TRAVELS IN THE ENVIRONMENT, NEVER IN ARGV. It authenticates a write
+// surface, which puts it in the same class as the credentials `orc extra`
+// refuses to accept on a command line: argv is world-readable in a process
+// list and lands in shell history, while a child's environment is readable by
+// its owner. It is read ONCE at boot and deleted from process.env immediately,
+// so the CLI subprocesses this server shells out to never inherit it.
+const RESTART_ENV_TOKEN = "ORC_UI_TOKEN";
+const RESTART_ENV_FLAG = "ORC_UI_RESTART";
+// The successor binds the port its predecessor has only just released. A few
+// hundred milliseconds of EADDRINUSE is normal and is not an error worth
+// showing anybody.
+const RESTART_BIND_RETRIES = 20;
+const RESTART_BIND_WAIT_MS = 250;
+
+function spawnSuccessor({ claudeDir, projectRoot, port, token, idleMinutes }) {
+  const cli = path.join(__dirname, "..", "cli.js");
+  const argv = [cli, "ui", "--port", String(port), "--no-open", "--idle", String(idleMinutes)];
+  if (projectRoot) argv.push("--dir", projectRoot);
+  const env = Object.assign({}, process.env);
+  env[RESTART_ENV_TOKEN] = token;
+  env[RESTART_ENV_FLAG] = "1";
+  const child = spawn(process.execPath, argv, {
+    detached: true,
+    stdio: "ignore",
+    windowsHide: true,
+    cwd: projectRoot || undefined,
+    env,
+  });
+  child.unref();
+  return child.pid;
+}
+
+// ── open a browser ──────────────────────────────────────────────────────────
+// Best-effort and never fatal: the URL is always printed, so a failed open is
+// an inconvenience, not an error.
+function openBrowser(url) {
+  try {
+    const [cmd, args] =
+      process.platform === "win32"
+        ? ["cmd", ["/c", "start", "", url]]
+        : process.platform === "darwin"
+        ? ["open", [url]]
+        : ["xdg-open", [url]];
+    const child = spawn(cmd, args, { detached: true, stdio: "ignore", windowsHide: true });
+    child.unref();
+    return true;
+  } catch (_) {
+    return false;
+  }
+}
+
+// ── `orc ui --stop` ─────────────────────────────────────────────────────────
+// Exit 0 if something was stopped, 1 if nothing was running — the same
+// exit-code convention as `orc resume` and `orc pattern status`.
+function stop(claudeDir) {
+  const lock = liveLock(claudeDir);
+  if (!lock) {
+    removeLock(claudeDir);
+    console.log("No orc ui server is running for this project.");
+    return 1;
+  }
+  try {
+    process.kill(lock.pid);
+  } catch (_) {}
+  removeLock(claudeDir);
+  console.log(`Stopped the orc ui server (pid ${lock.pid}, port ${lock.port}).`);
+  return 0;
+}
+
+// ── binding ─────────────────────────────────────────────────────────────────
+// Port free → bind it. Port held by anything else → walk 9922…9930 — but ONLY
+// when the port was the default. An EXPLICIT --port never auto-increments: if
+// you asked for a specific port and it is taken, that is an error, not a silent
+// move to somewhere you are not looking.
+function listen(server, port, explicit, retries = 0) {
+  return new Promise((resolve, reject) => {
+    let left = retries;
+    const tryPort = (p) => {
+      const onError = (err) => {
+        server.removeListener("listening", onOk);
+        if (err.code !== "EADDRINUSE") return reject(err);
+        // A SUCCESSOR waits for the port rather than moving or failing. Its
+        // predecessor released it moments ago and the whole point of the
+        // handover is that the URL already in the user's address bar keeps
+        // working — walking to another port would break exactly what this is
+        // trying to preserve.
+        if (left > 0) {
+          left--;
+          setTimeout(() => tryPort(p), RESTART_BIND_WAIT_MS);
+          return;
+        }
+        if (explicit)
+          return reject(
+            Object.assign(new Error(`port ${p} is already in use`), { code: "EADDRINUSE", port: p })
+          );
+        if (p >= PORT_WALK_MAX)
+          return reject(
+            Object.assign(new Error(`ports ${DEFAULT_PORT}-${PORT_WALK_MAX} are all in use`), {
+              code: "ENOPORT",
+            })
+          );
+        tryPort(p + 1);
+      };
+      const onOk = () => {
+        server.removeListener("error", onError);
+        resolve(p);
+      };
+      server.once("error", onError);
+      server.once("listening", onOk);
+      // 127.0.0.1 ONLY — never 0.0.0.0. This is a write surface.
+      server.listen(p, "127.0.0.1");
+    };
+    tryPort(port);
+  });
+}
+
+// ── security ────────────────────────────────────────────────────────────────
+
+// DNS-rebinding guard. A page on evil.example can make a browser resolve a
+// hostname to 127.0.0.1 and reach this server; the Host header it sends is that
+// attacker hostname, never a loopback literal. Anything but a loopback Host is
+// refused before routing.
+function loopbackHost(hostHeader, port) {
+  if (!hostHeader) return false;
+  const h = String(hostHeader).trim().toLowerCase();
+  return (
+    h === `127.0.0.1:${port}` ||
+    h === `localhost:${port}` ||
+    h === `[::1]:${port}` ||
+    h === "127.0.0.1" ||
+    h === "localhost"
+  );
+}
+
+// Constant-time compare so a token cannot be recovered by timing the reply.
+function tokenOk(given, expected) {
+  if (typeof given !== "string" || given.length !== expected.length) return false;
+  return crypto.timingSafeEqual(Buffer.from(given), Buffer.from(expected));
+}
+
+// ── the server ──────────────────────────────────────────────────────────────
+
+async function serve(opts) {
+  const {
+    claudeDir,
+    projectRoot,
+    port: wantPort,
+    explicitPort,
+    open = true,
+    idleMinutes = DEFAULT_IDLE_MIN,
+    fixtures = false,
+    version = "",
+  } = opts;
+
+  // The handoff from a predecessor that is on its way out, read ONCE and then
+  // removed from the environment so no CLI subprocess ever inherits the token.
+  const inheritedToken = process.env[RESTART_ENV_TOKEN] || null;
+  const isSuccessor = process.env[RESTART_ENV_FLAG] === "1" && !!inheritedToken;
+  delete process.env[RESTART_ENV_TOKEN];
+  delete process.env[RESTART_ENV_FLAG];
+
+  // Idempotent relaunch: a live server for THIS project is not replaced by a
+  // second one — read its lock, verify the pid, and just open the browser at
+  // the recorded port and token.
+  //
+  // A SUCCESSOR SKIPS THIS. The lock it would find names its own predecessor,
+  // which is either dying or already gone; treating that as "already running"
+  // would make the restart a silent no-op and leave the user on the old build
+  // with no way to tell.
+  if (!fixtures && !isSuccessor) {
+    const existing = liveLock(claudeDir);
+    if (existing) {
+      const url = urlFor(existing.port, existing.token);
+      console.log(`orc ui is already running for this project (pid ${existing.pid}).`);
+      console.log(`  ${url}`);
+      if (open) openBrowser(url);
+      console.log("  Stop it with: orc ui --stop");
+      return 0;
+    }
+  }
+
+  const token = inheritedToken || crypto.randomBytes(32).toString("hex");
+  const startedMs = Date.now();
+  let lastContact = Date.now();
+  let boundPort = wantPort;
+  // Has a browser ever talked to us? Until one has, only the idle timeout
+  // applies — otherwise a `--no-open` launch would shut itself down in 60s.
+  let sawClient = false;
+  // One handover per process. A second request while the successor is starting
+  // is answered with the same "yes, it is happening" rather than spawning two.
+  let restarting = false;
+
+  const ctx = {
+    claudeDir,
+    projectRoot,
+    fixtures,
+    version,
+    startedMs,
+    idleMinutes,
+    get port() {
+      return boundPort;
+    },
+    onHeartbeat() {
+      lastContact = Date.now();
+      sawClient = true;
+    },
+    onBye() {
+      // A beacon is a hint, not a command: another tab may still be open, so
+      // the heartbeat window — not this call — decides the actual shutdown.
+      lastContact = Date.now() - HEARTBEAT_GRACE_MS + 3000;
+    },
+    // Hand this project's panel over to a fresh process on the same port and
+    // token. CLIENT-TRIGGERED, always: the server never restarts itself the
+    // moment a job finishes, because the job's output lives in memory and a
+    // restart the user did not ask for would take the record of what just ran
+    // with it. It also means a tab that is already closed leaves the old
+    // process running the old code, which is the safe resting state.
+    restart() {
+      if (fixtures) return { ok: false, reason: "fixtures" };
+      if (restarting) return { ok: true, already: true, port: boundPort };
+      restarting = true;
+      // The lock is deliberately NOT removed. The successor overwrites it with
+      // the same port and token under its own pid; if the spawn fails instead,
+      // the lock names a dead pid and `liveLock` cleans it up on the next
+      // launch. Removing it here would open a window where `orc ui` sees no
+      // server and starts a second one somewhere else.
+      let pid = null;
+      try {
+        pid = spawnSuccessor({ claudeDir, projectRoot, port: boundPort, token, idleMinutes });
+      } catch (e) {
+        restarting = false;
+        return { ok: false, reason: "spawn-failed", error: String(e && e.message) };
+      }
+      // Stop listening FIRST so the successor can take the port, then leave.
+      // The delay is only long enough for this response to reach the browser
+      // that asked for it.
+      setTimeout(() => {
+        console.log("\norc ui — handing over to a fresh process on port " + boundPort + " (pid " + pid + ")");
+        try {
+          server.close();
+        } catch (_) {}
+        process.exit(0);
+      }, 250);
+      return { ok: true, pid, port: boundPort, url: urlFor(boundPort, token) };
+    },
+  };
+
+  const server = http.createServer((req, res) => {
+    lastContact = Date.now();
+    let url;
+    try {
+      url = new URL(req.url, `http://127.0.0.1:${boundPort}`);
+    } catch (_) {
+      res.writeHead(400).end();
+      return;
+    }
+
+    if (!loopbackHost(req.headers.host, boundPort)) {
+      // Deliberately terse: an attacker learns nothing, and this can only be
+      // hit by something that is not the local browser we opened.
+      res.writeHead(403, { "content-type": "text/plain" }).end("forbidden\n");
+      return;
+    }
+
+    // No CORS headers at ALL — no Access-Control-Allow-*, ever. A cross-origin
+    // page must not be able to read a single byte of this.
+    const given = url.searchParams.get("t") || req.headers["x-orc-token"];
+    const authed = tokenOk(given, token);
+
+    const stat = STATIC[url.pathname];
+    if (stat) {
+      if (!authed) {
+        res
+          .writeHead(401, { "content-type": "text/html; charset=utf-8" })
+          .end(
+            "<h1>orc ui</h1><p>This link is missing its session token. Re-run <code>orc ui</code> " +
+              "in your project to get a fresh URL.</p>"
+          );
+        return;
+      }
+      let body;
+      try {
+        body = fs.readFileSync(path.join(__dirname, stat.file));
+      } catch (_) {
+        res.writeHead(500, { "content-type": "text/plain" }).end("missing asset\n");
+        return;
+      }
+      // The token is required on EVERY request, and a <link>/<script> in the
+      // HTML carries no query string of its own — so every asset would 401 and
+      // the page would render as unstyled, scriptless markup. Stamp the live
+      // token onto EVERY asset reference as the shell goes out. Doing it here
+      // (rather than with a cookie) keeps the token explicit per request: there
+      // is no ambient credential a cross-origin page could ever ride on.
+      //
+      // Generic since v0.48.1: naming the two files was fine when there were
+      // two. With ~55 the pattern has to be the rule, or the next <script> tag
+      // someone adds 401s silently. A test parses app.html and asserts every
+      // href/src comes back stamped AND resolves to a real entry in STATIC.
+      if (stat.file === "app.html") {
+        body = Buffer.from(
+          body
+            .toString("utf8")
+            .replace(
+              /(href|src)="([\w./-]+\.(?:css|js))"/g,
+              (m, attr, ref) => `${attr}="${ref}?t=${token}"`
+            ),
+          "utf8"
+        );
+      }
+      res.writeHead(200, {
+        "content-type": stat.type,
+        "cache-control": "no-store",
+        "x-content-type-options": "nosniff",
+        // The page loads only its own inline-free assets and talks only to
+        // itself; nothing external is ever fetched.
+        "content-security-policy":
+          "default-src 'none'; script-src 'self'; style-src 'self'; img-src 'self' data:; connect-src 'self'; base-uri 'none'; form-action 'none'",
+        "referrer-policy": "no-referrer",
+      });
+      res.end(body);
+      return;
+    }
+
+    if (!url.pathname.startsWith("/api/")) {
+      res.writeHead(404, { "content-type": "text/plain" }).end("not found\n");
+      return;
+    }
+    if (!authed) {
+      res
+        .writeHead(401, { "content-type": "application/json" })
+        .end(JSON.stringify({ error: "bad or missing token" }));
+      return;
+    }
+    // Mutations are POST-only, enforced here as well as in the router, so a GET
+    // can never reach a write path however the table is later edited.
+    if (req.method !== "GET" && req.method !== "POST") {
+      res.writeHead(405, { "content-type": "application/json" }).end(JSON.stringify({ error: "method not allowed" }));
+      return;
+    }
+    Promise.resolve(handleApi(req, res, url, ctx)).catch((e) => {
+      if (res.headersSent) return;
+      res.writeHead(500, { "content-type": "application/json" }).end(JSON.stringify({ error: String(e && e.message) }));
+    });
+  });
+
+  try {
+    boundPort = await listen(server, wantPort, explicitPort, isSuccessor ? RESTART_BIND_RETRIES : 0);
+  } catch (e) {
+    if (e.code === "EADDRINUSE")
+      console.error(
+        `❌ port ${e.port} is already in use.\n` +
+          "   You asked for that port explicitly, so orc ui will not move to another one.\n" +
+          "   Pick a different one with --port <n>, or stop whatever holds it."
+      );
+    else if (e.code === "ENOPORT")
+      console.error(
+        `❌ ports ${DEFAULT_PORT}-${PORT_WALK_MAX} are all in use.\n` +
+          "   Choose one yourself with: orc ui --port <n>"
+      );
+    else console.error("❌ could not start the orc ui server: " + e.message);
+    return 1;
+  }
+
+  const url = urlFor(boundPort, token);
+  if (!fixtures) writeLock(claudeDir, { pid: process.pid, port: boundPort, token, started_ms: startedMs });
+
+  // The token is part of the URL the user needs; it is never written to a log
+  // line of its own, and never echoed by any /api response.
+  console.log(`\norc ui — ${fixtures ? "FIXTURE MODE (canned data, nothing real is read)" : projectRoot}`);
+  console.log(`  ${url}`);
+  console.log(
+    "  " +
+      (idleMinutes > 0
+        ? `Shuts down ~1 min after the last tab closes, or after ${idleMinutes} idle minutes.`
+        : "Idle timeout disabled (--idle 0) — stop it with `orc ui --stop`.")
+  );
+  console.log("  Stop it now with: orc ui --stop  (or Ctrl-C here)\n");
+  if (open) openBrowser(url);
+
+  // A shutdown is never mysterious: the reason is printed to the terminal this
+  // was launched from.
+  const shutdown = (reason, code = 0) => {
+    console.log(`\norc ui stopped — ${reason}`);
+    if (!fixtures) removeLock(claudeDir);
+    try {
+      server.close();
+    } catch (_) {}
+    process.exit(code);
+  };
+
+  const idleMs = idleMinutes > 0 ? idleMinutes * 60_000 : 0;
+  const timer = setInterval(() => {
+    const quiet = Date.now() - lastContact;
+    // 1) Heartbeat: a client WAS here and has stopped pinging → the tab closed.
+    if (sawClient && quiet > HEARTBEAT_GRACE_MS) shutdown("the browser tab closed");
+    // 2) Idle: nothing at all for the whole window → nobody is using this.
+    if (idleMs && quiet > idleMs) shutdown(`idle for ${idleMinutes} minutes`);
+  }, 5000);
+  timer.unref();
+
+  for (const sig of ["SIGINT", "SIGTERM"]) process.on(sig, () => shutdown(`received ${sig}`));
+
+  return new Promise(() => {}); // run until a shutdown path exits
+}
+
+module.exports = { serve, stop, readLock, liveLock, lockPath, removeLock, loopbackHost, buildStatic, DEFAULT_PORT, PORT_WALK_MAX, HEARTBEAT_GRACE_MS, DEFAULT_IDLE_MIN };

package/mock-run/INDEX.md

@@ -0,0 +1,106 @@
+# Mocked runs — what each ORC lane looks like when it runs
+
+New to ORC? Start here. Every file below is a **mocked run**: the screen you
+would see, the questions you would be asked, and the files that would land on
+disk — written the way the real lane writes them.
+
+Nothing here was executed. It is documentation, and it is here because you
+should not have to spend tokens to find out what a command does.
+
+All of it uses **easy English**, short sentences, and the same fake project.
+
+> **Read it in the panel instead:** `orc ui` ▸ **Mocked Skill Use** — the same
+> documents, searchable, with a reading pane. From the terminal:
+> `orc mock-run list` and `orc mock-run show <slug>`.
+
+---
+
+## Start here
+
+| Doc | What it shows |
+|---|---|
+| [The example project](the-example-project.md) | `shopcart`, the fake project every mock uses, and how to read these files |
+| [A normal day](a-normal-day.md) | `/orc-pact`, `/orc-boundary`, `/orc-budget`, `/orc-aftermath` and the rest, all inside one ordinary run |
+
+## Build a change
+
+| Doc | Lane | One line |
+|---|---|---|
+| [orc](orc.md) | `/orc` | The full pipeline: intake → plan → score → parallel waves → review → verify → ship |
+| [orc-ultra](orc-ultra.md) | `/orc-ultra` | The same, plus an advisor and three judgment gates. Costs the most |
+| [orc-mini](../templates/skills/orc-mini/examples/mini-run-mock.md) | `/orc-mini` | One executor, a smoke gate, ship |
+| [orc-fast](orc-fast.md) | `/orc-fast` | No analyst, no planner — the wiki and the pattern already did that work |
+| [orc-quick](orc-quick.md) | `/orc-quick` | Ask for anything. Look → ask once → do, and it always asks which agent |
+| [orc-diy](orc-diy.md) | `/orc-diy` | Your own lane, composed in the terminal and compiled |
+
+## Decide what to build
+
+| Doc | Lane | One line |
+|---|---|---|
+| [orc-brainstorm](orc-brainstorm.md) | `/orc-brainstorm` | No idea yet: it generates the options and **you** pick |
+| [orc-grill](orc-grill.md) | `/orc-grill` | One vague idea, sharpened by questions — it never answers its own |
+| [orc-doc](orc-doc.md) | `/orc-doc` | A PRD, TSD, agreement, report or runbook — written in parts, so nothing holds it all |
+| [orc-plan](orc-plan.md) | `/orc-plan` | A real task plan: grounded files, dependencies, facets, test dispositions |
+| [orc-route](orc-route.md) | `/orc-route` | You have a plan — which lane should build it, and which cannot |
+| [orc-explain](orc-explain.md) | `/orc-explain` | "Wait, what?" — it says the last message again, properly |
+| [orc-analyze](../templates/skills/orc-analyze/examples/analyze-mock.md) | `/orc-analyze` | A document turned into code-grounded requirements |
+| [orc-analyze-mini](../templates/skills/orc-analyze-mini/examples/quick-analysis-mock.md) | *(inside `/orc-mini`)* | The same, single pass, much cheaper |
+| [context-combiner](context-combiner.md) | — | Two related analyses merged into one spec, with a 100% conservation gate |
+| [orc-poly](../templates/skills/orc-poly/examples/poly-run-mock.md) | `/orc-poly` | One change across two or more repos, without drift |
+
+## Teach ORC your project
+
+| Doc | Lane | One line |
+|---|---|---|
+| [orc-wiki](../templates/skills/orc-wiki/examples/wiki-run-mock.md) | `/orc-wiki` | Scan the codebase into an evidence-anchored knowledge base |
+| [orc-pattern](orc-pattern.md) | `/orc-pattern` | Learn your real conventions so executors match your house style |
+| [orc-learn](../templates/skills/orc-learn/examples/learn-run-mock.md) | `/orc-learn` | Onboarding docs for a human, per feature |
+| [orc-claude](../templates/skills/orc-claude/examples/claude-run-mock.md) | `/orc-claude` | Build or refresh this repo's `CLAUDE.md` from verified facts |
+| [orc-export](orc-export.md) | `/orc-export` | Compile it all into a portable `AGENTS.md` so ORC is not a trap |
+
+## Check what happened
+
+| Doc | Lane | One line |
+|---|---|---|
+| [orc-verify](../templates/skills/orc-verify/examples/verify-mock.md) | `/orc-verify` | Verify only your git-modified changes. Read-only |
+| [orc-challenge](orc-challenge.md) | `/orc-challenge` | Grade a finished document, then stop and make you fix it in another session |
+| [orc-challenge-council](orc-challenge-council.md) | `/orc-challenge` | Six more ways of looking at the same document — and you choose which ones run |
+| [orc-pact](orc-pact.md) | `/orc-pact` | The promises your system makes, and which are in doubt right now |
+| [orc-boundary](orc-boundary.md) | `/orc-boundary` | What the agent should **not** try here, and what would change that |
+| [orc-aftermath](orc-aftermath.md) | `/orc-aftermath` | Did what we shipped hold up. Churn is a signal, never a verdict |
+| [orc-budget](orc-budget.md) | `/orc-budget` | What a run costs, in the unit you are billed in |
+| [orc-retro](../templates/skills/orc-retro/examples/retro-mock.md) | `/orc-retro` | Mine the behavior traces into a calibration report |
+
+## Ship and hand over
+
+| Doc | Lane | One line |
+|---|---|---|
+| [orc-pr-setup / orc-pr-driver](orc-pr-setup.md) | `/orc-pr-setup`, `/orc-pr-driver` | Split a big change into a stack of PRs, then build and merge them |
+| [orc-handoff](orc-handoff.md) | `/orc-handoff` | What a non-developer can safely change, graded by whether a check exists |
+
+## Panel and terminal
+
+| Doc | One line |
+|---|---|
+| [orc-ui](orc-ui.md) | The local control panel for everything that is not ai (**video placeholder here**) |
+| [orc-cli](orc-cli.md) | The terminal commands: install, config, probes, run state, stats |
+| [orc-extra](orc-extra.md) | Run some of ORC's work on a different AI model, and still know what left your machine |
+| [extra-recovery](extra-recovery.md) | When that other model stops half-way: what it left on disk, whose fault it was, and how to continue |
+| [extra-slots](extra-slots.md) | The four lanes that never score a task: giving one JOB to a cheaper model, and what ORC says before it does |
+
+---
+
+## Two kinds of document
+
+- **Walkthroughs** (this folder) — written for a person, in easy English.
+- **Annotated examples** (`templates/skills/<skill>/examples/`) — dense, written
+  for the model, and shipped inside your `.claude/` install. Both appear in
+  `orc mock-run list` and in the **Mocked Skill Use** panel.
+
+## Adding one
+
+Drop a `.md` file in this folder with a `# Title` heading and a `> one line`
+summary under it. It appears in `orc mock-run`, in the panel, and here — no list
+to update anywhere else. Reading order comes from `GROUP_OF` in
+[`bin/mockrun-catalog.js`](../bin/mockrun-catalog.js); a file nobody placed
+there still shows, under **More**.