@opum-ai/lore 0.1.0

package/src/commands/init.ts

@@ -0,0 +1,583 @@
+/**
+ * commands/init.ts — `lore init`: scaffold an empty, conformant OKF bundle, and fold the rest of
+ * onboarding into the SAME one command (LORE-260): the Claude Code agent bridge, downstream
+ * doc-site scaffolds (mkdocs/docusaurus/obsidian), and a backlog-coupling capability check —
+ * replacing the old `init` → `agents` → external `lore-setup.sh` → manual Obsidian sequence.
+ *
+ * ## The locked design decision (2026-07-24)
+ *
+ * A **bare** `lore init` on an interactive terminal runs a guided wizard that asks about each
+ * configurable consumer; it is **TTY-gated** — when stdin OR stderr is not a TTY (CI, pipes, a
+ * test, or a caller that redirects only one stream), `--json` was requested, or ANY of this
+ * command's own flags is passed, it runs fully **non-interactively** with defaults and no prompt
+ * can ever block it (the npm-init pattern: interactive on a bare TTY invocation, `-y`/non-TTY skips
+ * prompts). **Both stdin and stderr must be real terminals** — every wizard question is written to
+ * stderr (cli-contract §4: stdout stays exclusively `init`'s own envelope), so gating on stdin alone
+ * would leave the wizard blocked-but-invisible behind a redirected stderr (review round 2,
+ * BLOCKING-1 — confirmed live: `lore init >/dev/null 2>&1` under a pty hung forever with zero
+ * output). `--json` is a third, independent veto: a machine-readable run must never prompt even at a
+ * genuinely interactive terminal. Every wizard question maps 1:1 to a flag (`--agents`,
+ * `--scaffold <target>`, `--obsidian`, `--no-backlog`/`--check-backlog`), so a script gets the exact
+ * same outcome as answering the wizard, with zero prompts. This is documented in
+ * [ADR-0017](../../docs/adr/0017-interactive-init-wizard-tty-gated.md) (an amendment to ADR-0004/
+ * ADR-0005's non-interactive CLI contract).
+ *
+ * **EOF (Ctrl-D) mid-wizard is a `usage` error, not a silent exit 0** (review round 2, BLOCKING-2):
+ * `readline/promises`' `rl.question()` never settles on stdin EOF, so a naive implementation left the
+ * wizard's promise abandoned forever — the process would exit 0 with `process.exitCode` never set,
+ * zero stdout bytes even under `--json` (a parse error for a `| jq` consumer expecting either a valid
+ * envelope or a classified failure), and a half-applied run (the base scaffold already written,
+ * nothing else). {@link createRealPrompter} now races every question against the readline
+ * interface's own `close` event and throws a `usage` {@link LoreError} on an early close, so the run
+ * exits non-zero with a rendered diagnostic instead — chosen over silently falling back to each
+ * question's default because BLOCKING-1's lesson applies here too: never silently do something the
+ * user couldn't see coming.
+ *
+ * **The non-interactive default is UNCHANGED from before this task**: with no flags and a non-TTY
+ * stdin (the automatic case for every existing caller — CI, `lore-setup.sh`, this file's own
+ * pre-LORE-260 tests), `lore init` does exactly what it always did — scaffold `docs/`/`.lore/` and
+ * nothing else. The agent bridge, scaffolds, and the backlog check are strictly opt-in via flags (or
+ * the wizard); this is what keeps the docker e2e harness's existing bare `lore init` calls, and
+ * every pre-existing unit test, byte-for-byte compatible with the prior behavior.
+ *
+ * The base bundle scaffold (this file's original, sole responsibility) is the thin command layer
+ * over the pure {@link buildScaffold} (lore-design §2.2, §3.1): it resolves the repo root and a
+ * clock, asks core for the intended bytes, and applies them to the filesystem **idempotently**.
+ * The load-bearing behavior is idempotency (AC#2/AC#3): every file is created only when **absent**
+ * (an atomic `wx` write, so there is no time-of-check/time-of-use race and no clobber of a user's
+ * edits), and directories are `mkdir -p` (already-exists is not an error). The agent bridge and
+ * scaffold steps reuse the SAME idempotent primitives `lore agents`/`lore scaffold` ship
+ * ({@link applyAgentsBridge}/{@link applyScaffold}) rather than duplicating their logic, so a second
+ * run of any combination of flags is a no-op wherever the first run already finished.
+ *
+ * The interactive wizard's TTY gate and its I/O are both **injectable** ({@link InitOptions.stdinIsTTY}
+ * / {@link InitOptions.prompter}), never read from `process.stdin` at this call site — a test drives
+ * the wizard path by passing `stdinIsTTY: true` plus a scripted {@link InitPrompter}, never a real
+ * terminal. `runInit` itself stays a plain (non-`async`) function returning `number | Promise<number>`
+ * (mirroring `commands/check.ts`'s own `runCheck`): the common, fully-synchronous path (no flags, no
+ * backlog check) returns a plain number exactly as before LORE-260, and only the wizard or an
+ * actually-requested backlog check return a `Promise`.
+ */
+
+import { join } from "node:path";
+import * as readline from "node:readline/promises";
+import type { BacklogAdapter } from "../adapters/backlog";
+import { loadProfile } from "../core/profile";
+import { buildScaffold } from "../core/scaffold";
+import { ANSI, EXIT_OK, LoreError, paint, WarningCollector, type Writer } from "../errors";
+import { emit, type OutputContext, type Renderable } from "../output";
+import { type AgentsResult, applyAgentsBridge, bridgeActionColor, renderTrailer } from "./agents";
+import { optionValues, parseCommandArgs, usage } from "./args";
+import { applyCodexBridge, type CodexBridgeResult } from "./codex-bridge";
+import { assertNoSymlinkInPath, createIfAbsent, ensureDir } from "./fswrite";
+import { defaultAdapter } from "./link";
+import { applyScaffold, TARGETS as SCAFFOLD_TARGETS, type ScaffoldResult } from "./scaffold";
+
+/** The backlog-coupling capability check's outcome, folded into {@link InitResult} when it ran. */
+export interface InitBacklogCheck {
+  /** Always `true` when this field is present at all — kept explicit (vs. field presence alone) so a `--json` consumer can branch without an `in` check. */
+  readonly checked: true;
+  /** Whether a `--json`-capable `backlog` was found on PATH. */
+  readonly capable: boolean;
+  /** The reported `backlog --version`, when capable. */
+  readonly version?: string;
+  /** The advisory message (also written to stderr) when NOT capable. */
+  readonly warning?: string;
+}
+
+/** The result of a `lore init` run: the base scaffold, plus whichever optional consumers ran. */
+export interface InitResult {
+  /** The repo root the bundle was initialized in. */
+  root: string;
+  /** Repo-relative POSIX paths created this run, in scaffold order (base OKF bundle only). */
+  created: string[];
+  /** Repo-relative POSIX paths that already existed and were left untouched (base OKF bundle only). */
+  skipped: string[];
+  /** Whether the interactive wizard ran this invocation. */
+  interactive: boolean;
+  /** The agent bridge's result, present iff this run set it up (wizard "yes", or `--agents`). */
+  agents?: AgentsResult;
+  /** Codex bridge result, present iff Codex setup was selected or explicitly requested. */
+  codex?: CodexBridgeResult;
+  /** One entry per downstream doc-site/vault actually scaffolded this run (wizard picks, `--scaffold`, `--obsidian`); empty when none were requested. */
+  scaffolds: ScaffoldResult[];
+  /** The backlog-coupling capability check's outcome, present iff it ran this invocation. */
+  backlog?: InitBacklogCheck;
+}
+
+/** The interactive wizard's minimal prompt vocabulary — confirm (yes/no) and choose (one of a fixed list). Injected so the wizard is unit-testable without a real terminal. */
+export interface InitPrompter {
+  /** Ask a yes/no question; an empty answer (bare Enter) resolves to `defaultValue`. */
+  confirm(question: string, defaultValue: boolean): Promise<boolean>;
+  /** Ask the user to pick one of `choices`; an empty or unrecognized answer resolves to `defaultValue`. */
+  choose(question: string, choices: readonly string[], defaultValue: string): Promise<string>;
+  /** Release the prompter's I/O resources (the real implementation's `readline` interface). */
+  close(): void;
+}
+
+/** Options for {@link runInit}; `root`, `clock`, the streams, the TTY gate, the prompter, and the backlog adapter are all injectable for tests. */
+export interface InitOptions {
+  /** The repo root to initialize. */
+  root: string;
+  /** The resolved output mode/color (from `output.ts`). */
+  output: OutputContext;
+  /** The command's normalized tokens from Commander. */
+  args?: readonly string[];
+  /** Clock seam for the root index timestamp (and a fresh scaffold's timestamp); defaults to the real wall clock. */
+  clock?: () => Date;
+  /** stdout sink; defaults to `process.stdout`. */
+  stdout?: Writer;
+  /** stderr sink for the backlog-check advisory; defaults to `process.stderr`. */
+  stderr?: Writer;
+  /**
+   * Whether STDIN is an interactive terminal — one half of the wizard's TTY gate (AC#2). Resolved
+   * once at the CLI boundary (`cli.ts`'s `run`, mirroring its own `isTTY`/`stderrIsTTY` handling) and
+   * handed in here as a plain boolean; this module never reads `process.stdin.isTTY` itself. Defaults
+   * to `false` (non-interactive) so an omitted value can never accidentally enable a blocking prompt —
+   * the safe default for every existing caller (tests, `lore-setup.sh`, CI) that predates this flag.
+   */
+  stdinIsTTY?: boolean;
+  /**
+   * Whether STDERR is an interactive terminal — the wizard's OTHER required condition (review
+   * round 2, BLOCKING-1). Every wizard question is written to stderr (cli-contract §4: stdout stays
+   * exclusively `init`'s own envelope), so `stdinIsTTY` alone is not sufficient — a caller that
+   * redirects only stderr (`lore init >out 2>/dev/null`, or the universal shell idiom
+   * `cmd >/dev/null 2>&1` that `lore-setup.sh` itself uses) still has a readable stdin, and would
+   * otherwise block forever on a prompt nobody can see. Resolved once at the CLI boundary exactly
+   * like {@link stdinIsTTY} (`cli.ts` already computes this for the error-color gate; LORE-260 round
+   * 2 threads the SAME resolved value here instead of leaving it unset). Defaults to `false` for the
+   * same "never accidentally enable a blocking prompt" reason.
+   */
+  stderrIsTTY?: boolean;
+  /**
+   * Whether `--json` was requested for this run. A machine-readable invocation must never prompt —
+   * even sitting at a real, fully-interactive terminal (review round 2, BLOCKING-1's sibling
+   * finding) — since a script piping `--json` output can never answer a wizard question. Kept as its
+   * own explicit boolean rather than derived from {@link InitOptions.output}'s `mode` (which governs
+   * rendering only, per `output.ts`'s documented single-responsibility split): `output.mode` is
+   * always `"json"` in exactly this case for a real `cli.ts` invocation (`resolveMode` maps `--json`
+   * to `mode: "json"` unconditionally), but a unit test may also hand-build a `mode: "json"`
+   * `OutputContext` purely so it can `JSON.parse` the result for assertions while still wanting the
+   * wizard to run (see `test/init.test.ts`'s wizard-path tests) — a separate flag lets that stay
+   * possible without conflating "how do we render" with "was `--json` actually on the command line".
+   * Defaults to `false` (not requested) when omitted.
+   */
+  jsonRequested?: boolean;
+  /** The interactive wizard's I/O seam; defaults to a real `node:readline/promises` session over stdin/stderr. Injected in tests so the wizard never touches a real terminal. */
+  prompter?: InitPrompter;
+  /** The Backlog adapter for the coupling capability check; defaults to the real `backlog` binary on PATH. */
+  adapter?: BacklogAdapter;
+  /** Injectable executable discovery for the interactive agent choices. */
+  agentAvailability?: () => AgentAvailability;
+}
+
+export interface AgentAvailability {
+  readonly claude: boolean;
+  readonly codex: boolean;
+}
+
+/** The parsed, validated `lore init` arguments. */
+interface InitArgs {
+  /** `--yes` (or its `--non-interactive` alias, NIT-2): force the non-interactive path (with defaults) even on a TTY — the npm-init `-y` equivalent. */
+  yes: boolean;
+  /** `--agents`: also set up the Claude Code agent bridge. */
+  agents: boolean;
+  /** `--codex`: set up the Codex bridge. */
+  codex: boolean;
+  /** `--scaffold <target>` (repeatable) and/or `--obsidian`, deduped; targets from {@link SCAFFOLD_TARGETS}. */
+  scaffolds: string[];
+  /** `--no-backlog`: skip the backlog-coupling capability check entirely. */
+  noBacklog: boolean;
+  /** `--check-backlog`: run the backlog-coupling capability check even with no other flag requesting it. */
+  checkBacklog: boolean;
+}
+
+/**
+ * Run `lore init` against `options.root`: scaffold the base bundle idempotently (unchanged from
+ * before LORE-260), then resolve the optional consumers — via the interactive wizard on a bare TTY
+ * invocation, or from flags otherwise — apply whichever were chosen (also idempotently), render the
+ * result, and return the exit code. A filesystem permission failure throws a `denied` {@link
+ * LoreError}; a scaffold collision throws `conflict`; a bad flag throws `usage`; any other
+ * unexpected IO error propagates to the CLI's top-level handler.
+ *
+ * Stays a plain (non-`async`) function, like `commands/check.ts`'s `runCheck`: the common path (no
+ * flags, no implied backlog check) returns a plain `number`, so every pre-LORE-260 synchronous
+ * caller — this file's own original tests, and the router's `--bogus`/positional usage-error paths —
+ * is untouched. Only the wizard, or a backlog check actually requested/implied, return a `Promise`.
+ */
+export function runInit(options: InitOptions): number | Promise<number> {
+  const parsed = parseInitArgs(options.args ?? []);
+  const stdinIsTTY = options.stdinIsTTY ?? false;
+  // BLOCKING-1 (review round 2): BOTH streams must be a real terminal — every wizard question is
+  // written to stderr, so a redirected stderr with a still-TTY stdin must never engage the wizard
+  // (the reader can't see the prompt to answer it). `--json` is an independent third veto: a
+  // machine-readable run must never prompt even at a genuinely interactive terminal.
+  const stderrIsTTY = options.stderrIsTTY ?? false;
+  const jsonRequested = options.jsonRequested ?? false;
+  const interactive = stdinIsTTY && stderrIsTTY && !jsonRequested && !anyFlagGiven(parsed);
+
+  const clock = options.clock ?? (() => new Date());
+  // Honor a pre-existing `.lore/profile.toml` so `init` scaffolds schemas for a project's custom
+  // types; with none present this is the built-in story-convention profile (zero-config).
+  const profile = loadProfile({ root: options.root });
+  const plan = buildScaffold({ timestamp: clock().toISOString(), profile });
+
+  for (const dir of plan.dirs) {
+    // LORE-77/LORE-93: ensureDir itself refuses a pre-existing symlink at (or above) this
+    // directory before its mkdirSync gets a chance to transparently walk through it.
+    ensureDir(options.root, dir);
+  }
+
+  const created: string[] = [];
+  const skipped: string[] = [];
+  for (const file of plan.files) {
+    assertNoSymlinkInPath(options.root, file.path);
+    if (createIfAbsent(join(options.root, file.path), file.contents, file.path)) {
+      created.push(file.path);
+    } else {
+      skipped.push(file.path);
+    }
+  }
+  const base = { root: options.root, created, skipped };
+
+  if (interactive) {
+    return runInteractiveWizard(options, base);
+  }
+
+  const scaffoldTargets = [...new Set(parsed.scaffolds)];
+  const agents = parsed.agents ? applyAgentsBridge({ root: options.root, force: false, check: false }) : undefined;
+  const codex = parsed.codex ? applyCodexBridge({ root: options.root, force: false, check: false }) : undefined;
+  const scaffolds = scaffoldTargets.map((target) => applyScaffold({ root: options.root, target, force: false, clock }));
+
+  // The backlog check is advisory-only (never fails the run) and, off-TTY/via-flags, runs only when
+  // it's actually relevant: explicitly requested (`--check-backlog`), or implied by onboarding a
+  // consumer that depends on the coupling (`--agents`/`--scaffold`/`--obsidian`) — unless the user
+  // opted all the way out with `--no-backlog`. A completely bare `lore init` therefore never spawns
+  // a `backlog` subprocess, exactly as before this task.
+  const shouldCheckBacklog =
+    parsed.checkBacklog || (!parsed.noBacklog && (parsed.agents || parsed.codex || scaffoldTargets.length > 0));
+  if (!shouldCheckBacklog) {
+    const result: InitResult = { ...base, interactive: false, agents, codex, scaffolds, backlog: undefined };
+    emit(initRenderable(result), options.output, options.stdout);
+    return EXIT_OK;
+  }
+
+  const warnings = new WarningCollector();
+  return probeBacklogCapability(options, warnings).then((backlog) => {
+    warnings.flush({ color: options.output.color, stderr: options.stderr ?? process.stderr });
+    const result: InitResult = { ...base, interactive: false, agents, codex, scaffolds, backlog };
+    emit(initRenderable(result), options.output, options.stdout);
+    return EXIT_OK;
+  });
+}
+
+/**
+ * The interactive wizard (AC#1): ask the three fold-in questions over the injected {@link
+ * InitPrompter} (or a real `readline` session over stdin/stderr — prompts and the whole UI live on
+ * **stderr**, per cli-contract §4: stdout must stay exclusively `init`'s own envelope), apply
+ * whichever were chosen (idempotently, via the exact same core primitives the flag path uses), then
+ * ALWAYS run the backlog-coupling detection (a fact-check, not a choice — mirrors AC#1's "detection"
+ * wording, not a fourth question) before rendering the combined result.
+ */
+async function runInteractiveWizard(
+  options: InitOptions,
+  base: { root: string; created: string[]; skipped: string[] },
+): Promise<number> {
+  const prompter = options.prompter ?? createRealPrompter();
+  const scaffoldTargets: string[] = [];
+  let wantAgents = false;
+  let wantCodex = false;
+  try {
+    const available = detectAgentAvailability(options);
+    if (available.claude) {
+      wantAgents = await prompter.confirm("Set up the Claude Code agent bridge (SKILL.md + CLAUDE.md nudge)?", true);
+    }
+    if (available.codex) {
+      wantCodex = await prompter.confirm("Set up the Codex agent bridge (SKILL.md + AGENTS.md nudge)?", true);
+    }
+    const site = await prompter.choose("Scaffold a downstream docs site?", ["none", "mkdocs", "docusaurus"], "none");
+    if (site !== "none") {
+      scaffoldTargets.push(site);
+    }
+    const wantObsidian = await prompter.confirm("Also scaffold an Obsidian vault config (docs/.obsidian)?", false);
+    if (wantObsidian) {
+      scaffoldTargets.push("obsidian");
+    }
+  } finally {
+    prompter.close();
+  }
+
+  const clock = options.clock ?? (() => new Date());
+  const agents = wantAgents ? applyAgentsBridge({ root: options.root, force: false, check: false }) : undefined;
+  const codex = wantCodex ? applyCodexBridge({ root: options.root, force: false, check: false }) : undefined;
+  const scaffolds = scaffoldTargets.map((target) => applyScaffold({ root: options.root, target, force: false, clock }));
+
+  const warnings = new WarningCollector();
+  const backlog = await probeBacklogCapability(options, warnings);
+  warnings.flush({ color: options.output.color, stderr: options.stderr ?? process.stderr });
+
+  const result: InitResult = { ...base, interactive: true, agents, codex, scaffolds, backlog };
+  emit(initRenderable(result), options.output, options.stdout);
+  return EXIT_OK;
+}
+
+/**
+ * A real, interactive {@link InitPrompter} over the given streams (defaulting to
+ * `process.stdin`/`process.stderr`) — constructed only when the wizard actually runs and no
+ * test-injected prompter was given. `streams` is a parameter (not hard-coded) purely so a unit test
+ * can exercise this function's own EOF handling over a fake stream pair, never a real terminal.
+ *
+ * **BLOCKING-2 (review round 2):** `readline/promises`' `rl.question()` never settles when its input
+ * stream hits EOF (Ctrl-D, or stdin simply closing) — confirmed live: a pending `question()` call
+ * neither resolves nor rejects, so a naive implementation left the wizard's promise abandoned
+ * forever, `finally { prompter.close() }` never ran, and the process fell through to exit `0` with
+ * `process.exitCode` unset and zero stdout bytes (a broken `--json | jq` contract on top of a
+ * half-applied run). Every `question()` call is now raced against the readline interface's own
+ * `close` event via {@link ask}: the interface closes on EOF regardless of whether `question()`
+ * itself ever settles, so the race always resolves. **Disposition: error out, not silently default**
+ * (documented in ADR-0017 and this task's Implementation Notes) — an early close throws a `usage`
+ * {@link LoreError} rather than silently resolving to each question's default value, for the same
+ * reason as BLOCKING-1: a user who hits Ctrl-D gets no visual confirmation of what happened, so
+ * guessing an answer on their behalf and proceeding is exactly the kind of invisible side effect
+ * BLOCKING-1 already ruled out. The rejection propagates out of `confirm`/`choose`, unwinds
+ * `runInteractiveWizard`'s `try`/`finally` (which still calls `prompter.close()` — safe here since
+ * `rl.close()` is idempotent and the interface is already closing), and reaches `cli.ts`'s async
+ * error path, which renders the diagnostic and maps `usage` to exit `2`.
+ *
+ * The `closedEarly` promise is given a standalone `.catch(() => {})` in addition to being raced,
+ * because the *normal* (non-EOF) completion path also ends in `prompter.close()` — every question
+ * answered, `runInteractiveWizard`'s `finally` calls `close()` intentionally, which emits `close` for
+ * the FIRST time in that path and would otherwise reject an unobserved promise (an unhandled
+ * rejection) after every race has already settled successfully.
+ */
+export function createRealPrompter(
+  streams: { input: NodeJS.ReadableStream; output: NodeJS.WritableStream } = {
+    input: process.stdin,
+    output: process.stderr,
+  },
+): InitPrompter {
+  const rl = readline.createInterface({ input: streams.input, output: streams.output });
+  const closedEarly = new Promise<never>((_resolve, reject) => {
+    rl.once("close", () => {
+      reject(
+        new LoreError(
+          "usage",
+          "stdin closed or the wizard was interrupted before it finished (EOF/Ctrl-D or Ctrl-C)",
+          "answer every prompt, or run prompt-free with `lore init --yes` (or --claude/--codex/--scaffold <target>/--obsidian/--no-backlog/--check-backlog)",
+        ),
+      );
+    });
+  });
+  // Prevents an "unhandled promise rejection" once the wizard finishes normally and its own
+  // `prompter.close()` call fires `close` for the first time, after every `ask()` race is already
+  // settled and nothing is awaiting `closedEarly` anymore — see the doc comment above.
+  closedEarly.catch(() => {});
+
+  /** Race one `rl.question()` call against the interface's own `close` event (see the doc above). */
+  function ask(promptText: string): Promise<string> {
+    return Promise.race([rl.question(promptText), closedEarly]);
+  }
+
+  return {
+    async confirm(question, defaultValue) {
+      const suffix = defaultValue ? "Y/n" : "y/N";
+      const raw = (await ask(`${question} [${suffix}] `)).trim().toLowerCase();
+      if (raw === "") {
+        return defaultValue;
+      }
+      return raw === "y" || raw === "yes";
+    },
+    async choose(question, choices, defaultValue) {
+      const raw = (await ask(`${question} (${choices.join("/")}) [${defaultValue}] `)).trim().toLowerCase();
+      return choices.includes(raw) ? raw : defaultValue;
+    },
+    close() {
+      rl.close();
+    },
+  };
+}
+
+/**
+ * Run the backlog-coupling capability check (AC#1/AC#4): probe the injected {@link
+ * InitOptions.adapter} (defaulting to the real `backlog` binary on PATH). Never throws — a
+ * missing/incapable binary is recorded as `warnings` advisory (stderr) plus the returned {@link
+ * InitBacklogCheck}, never a failed `lore init` run, since the base scaffold (and any agent
+ * bridge/doc-site scaffold already applied) succeeded regardless of whether Backlog.md coupling is
+ * available yet.
+ */
+async function probeBacklogCapability(options: InitOptions, warnings: WarningCollector): Promise<InitBacklogCheck> {
+  const adapter = options.adapter ?? defaultAdapter(options.root);
+  try {
+    const capability = await adapter.probe();
+    return { checked: true, capable: true, version: capability.version };
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    const hint = err instanceof LoreError ? err.hint : undefined;
+    warnings.add(`backlog coupling unavailable: ${message}${hint ? ` — ${hint}` : ""}`);
+    return { checked: true, capable: false, warning: message };
+  }
+}
+
+/** Whether any of `lore init`'s own flags was passed — the signal that overrides a bare-TTY invocation into the non-interactive path (AC#2). */
+function anyFlagGiven(parsed: InitArgs): boolean {
+  return (
+    parsed.yes ||
+    parsed.agents ||
+    parsed.codex ||
+    parsed.scaffolds.length > 0 ||
+    parsed.noBacklog ||
+    parsed.checkBacklog
+  );
+}
+
+/**
+ * Parse `init`'s tokens: no positionals (unchanged from before LORE-260 — a bare/`--`-terminated
+ * positional is still a `usage` error, byte-identical wording to the router's old blanket
+ * `rejectCommandArgs` guard so every pre-existing regression test keeps passing), plus the boolean
+ * `--yes` (alias `--non-interactive`, NIT-2)/`--agents`/`--obsidian`/`--no-backlog`/`--check-backlog`
+ * and the repeatable value flag `--scaffold <target>`. An unknown flag, an invalid `--scaffold`
+ * target, a stray positional, or the mutually-exclusive `--no-backlog`+`--check-backlog` pair all
+ * throw a `usage` {@link LoreError} (exit `2`) before any scaffold work runs.
+ */
+function parseInitArgs(args: readonly string[]): InitArgs {
+  const parsed = parseCommandArgs(args, "init");
+  const yes = parsed.flags.has("yes") || parsed.flags.has("non-interactive");
+  const agents = parsed.flags.has("agents") || parsed.flags.has("claude");
+  const codex = parsed.flags.has("codex");
+  const noBacklog = parsed.flags.has("no-backlog");
+  const checkBacklog = parsed.flags.has("check-backlog");
+  const scaffolds: string[] = [];
+  for (const value of optionValues(parsed, "scaffold")) {
+    if (value === "") {
+      throw usage("--scaffold needs a value", "pass a value, e.g. `--scaffold mkdocs`");
+    }
+    if (!SCAFFOLD_TARGETS.has(value)) {
+      throw usage(`unknown scaffold target "${value}"`, `valid targets are ${[...SCAFFOLD_TARGETS].join(", ")}`);
+    }
+    if (!scaffolds.includes(value)) scaffolds.push(value);
+  }
+  if (parsed.flags.has("obsidian") && !scaffolds.includes("obsidian")) scaffolds.push("obsidian");
+  if (parsed.positionals.length > 0) {
+    // Byte-identical wording to the router's pre-LORE-260 `rejectCommandArgs` guard (cli.ts), which
+    // used to reject EVERY token this command received — `lore init` still takes no positionals.
+    throw usage(
+      `\`lore init\` takes no arguments, got "${parsed.positionals[0]}"`,
+      "run `lore init` with no positional arguments",
+      { command: "init", unexpected: [...parsed.positionals] },
+    );
+  }
+  if (noBacklog && checkBacklog) {
+    throw usage(
+      "--no-backlog and --check-backlog are mutually exclusive",
+      "pass at most one of --no-backlog / --check-backlog",
+    );
+  }
+  return { yes, agents, codex, scaffolds, noBacklog, checkBacklog };
+}
+
+/** Detect installed agents without making absence or a broken PATH fatal to onboarding. */
+function detectAgentAvailability(options: InitOptions): AgentAvailability {
+  if (options.agentAvailability) return options.agentAvailability();
+  try {
+    return { claude: Bun.which("claude") !== null, codex: Bun.which("codex") !== null };
+  } catch {
+    return { claude: false, codex: false };
+  }
+}
+
+/** The per-result-type rendering bundle for `init` (output.ts dispatches on the mode). */
+function initRenderable(data: InitResult): Renderable<InitResult> {
+  return { kind: "init", data, pretty: renderPretty, plain: renderPlain };
+}
+
+/** Human view: the base scaffold summary, then a section per optional consumer that ran this run. */
+function renderPretty(data: InitResult, opts: { color: boolean }): string {
+  const head = data.created.length
+    ? `Initialized lore bundle at ${data.root}`
+    : `lore bundle already initialized at ${data.root} (nothing to create)`;
+  const lines = [head];
+  for (const path of data.created) {
+    lines.push(`  ${paint("+", ANSI.green, opts.color)} ${path}`);
+  }
+  for (const path of data.skipped) {
+    lines.push(`  ${paint(`· ${path} (exists)`, ANSI.dim, opts.color)}`);
+  }
+  if (data.agents) {
+    lines.push("Claude Code bridge:");
+    for (const file of data.agents.files) {
+      // "protected" is a warning, not a success (LORE-260 review round 2, MINOR-4): a hand-edited
+      // file was left untouched, which is meaningfully different from "unchanged" (nothing to do)
+      // and must not be painted the same green as an actual write. Shared with `lore agents`' own
+      // renderer (LORE-267) so the two commands cannot diverge on this mapping again.
+      lines.push(`  ${paint(file.action, bridgeActionColor(file.action), opts.color)} ${file.path}`);
+    }
+    // Reuse `lore agents`' own trailer verbatim (MINOR-4) rather than dropping it: a `protected`
+    // file with no visible remedy reads as silent success (LORE-129 established this line as
+    // load-bearing).
+    const agentsTrailer = renderTrailer(data.agents);
+    if (agentsTrailer !== undefined) {
+      lines.push(paint(agentsTrailer, ANSI.yellow, opts.color));
+    }
+  }
+  if (data.codex) {
+    lines.push("Codex bridge:");
+    for (const file of data.codex.files) {
+      lines.push(`  ${paint(file.action, bridgeActionColor(file.action), opts.color)} ${file.path}`);
+    }
+  }
+  for (const scaffold of data.scaffolds) {
+    lines.push(`Scaffold (${scaffold.target}):`);
+    if (scaffold.files.length === 0) {
+      lines.push(`  ${paint("already up to date", ANSI.dim, opts.color)}`);
+    }
+    for (const file of scaffold.files) {
+      lines.push(`  ${paint(file.action, ANSI.green, opts.color)} ${file.path}`);
+    }
+  }
+  if (data.backlog) {
+    lines.push(
+      data.backlog.capable
+        ? `backlog: --json-capable${data.backlog.version ? ` (v${data.backlog.version})` : ""}`
+        : paint("backlog: not --json-capable — see the warning above (coupling unavailable)", ANSI.yellow, opts.color),
+    );
+  }
+  if (data.interactive) {
+    lines.push("Run `lore instructions` for the canonical agent loop.");
+  }
+  return lines.join("\n");
+}
+
+/** ANSI-free, diff-stable view: one line per base-scaffold path, then one line per optional-consumer action. */
+function renderPlain(data: InitResult): string {
+  const lines = [...data.created.map((path) => `created ${path}`), ...data.skipped.map((path) => `exists ${path}`)];
+  if (data.agents) {
+    for (const file of data.agents.files) {
+      lines.push(`agents-${file.action} ${file.path}`);
+    }
+    const agentsTrailer = renderTrailer(data.agents);
+    if (agentsTrailer !== undefined) {
+      lines.push(agentsTrailer);
+    }
+  }
+  if (data.codex) {
+    for (const file of data.codex.files) {
+      lines.push(`codex-${file.action} ${file.path}`);
+    }
+  }
+  for (const scaffold of data.scaffolds) {
+    // NIT-1 (review round 2): an already-up-to-date scaffold produced NO line at all in plain mode
+    // (renderPretty said "already up to date"; renderPlain said nothing), so a --plain consumer
+    // couldn't tell the step ran versus never having been requested.
+    if (scaffold.files.length === 0) {
+      lines.push(`scaffold-${scaffold.target} up-to-date`);
+      continue;
+    }
+    for (const file of scaffold.files) {
+      lines.push(`scaffold-${scaffold.target}-${file.action} ${file.path}`);
+    }
+  }
+  if (data.backlog) {
+    lines.push(data.backlog.capable ? "backlog capable" : "backlog incapable");
+  }
+  return lines.join("\n");
+}

package/src/commands/instructions.ts

@@ -0,0 +1,91 @@
+/**
+ * commands/instructions.ts — `lore instructions [<topic>]` (cli-surface §instructions).
+ *
+ * The thin, read-only layer over the static topic registry in
+ * `core/instructions.ts`: it parses the one optional positional, looks up the
+ * topic, and emits it. There is no bundle to load and no config to read, so
+ * unlike most commands this one needs neither `root` nor a `WarningCollector`.
+ *
+ * With no `<topic>` it prints `overview` (the canonical loop + a topic index);
+ * an unrecognized `<topic>` is a `not_found` error (exit 3) whose hint lists
+ * the valid keys. Argument parsing goes through `args.ts`'s shared Commander parser
+ * with no known flags, so any `-`-prefixed token or a second positional is a
+ * `usage` error (exit 2), matching every other command's strict parsing.
+ */
+
+import { findInstructionTopic, INSTRUCTION_TOPICS, type InstructionTopic } from "../core/instructions";
+import { ANSI, EXIT_OK, LoreError, paint, type Writer } from "../errors";
+import { emit, type OutputContext, type Renderable } from "../output";
+import { parseCommandArgs, usage } from "./args";
+
+/** Options for {@link runInstructions}; the streams are injectable for tests. */
+export interface InstructionsOptions {
+  /** The resolved output mode/color (from `output.ts`). */
+  output: OutputContext;
+  /** The command's normalized positional tokens from Commander. */
+  args: readonly string[];
+  /** stdout sink; defaults to `process.stdout`. */
+  stdout?: Writer;
+}
+
+/** The `instructions.text` payload: the requested topic plus the full topic index, so a `--json` caller can discover the other keys without a second request. */
+export interface InstructionsData {
+  /** The topic actually served (`overview` when no `<topic>` was given). */
+  topic: string;
+  /** The topic's one-line heading. */
+  title: string;
+  /** The topic's full guidance body. */
+  body: string;
+  /** Every topic `lore instructions` can serve, in index order. */
+  topics: ReadonlyArray<{ key: string; title: string }>;
+}
+
+/** Run `lore instructions`: parse the optional `<topic>`, look it up, emit it, and return `0`. */
+export function runInstructions(options: InstructionsOptions): number {
+  const key = parseInstructionsArgs(options.args);
+  const topic = findInstructionTopic(key);
+  if (topic === undefined) {
+    const validKeys = INSTRUCTION_TOPICS.map((t) => t.key).join(", ");
+    throw new LoreError(
+      "not_found",
+      `unknown instructions topic "${key}"`,
+      `valid topics: ${validKeys}; run \`lore instructions\` for the overview`,
+      { topic: key },
+    );
+  }
+  emit(instructionsRenderable(topic), options.output, options.stdout);
+  return EXIT_OK;
+}
+
+/** Parse `instructions`' tokens via the shared parser (no known flags): at most one positional (the topic key, defaulting to `overview`); any flag or second positional is a `usage` error. */
+function parseInstructionsArgs(args: readonly string[]): string {
+  const { positionals } = parseCommandArgs(args, "instructions");
+  if (positionals.length > 1) {
+    throw usage(`unexpected argument "${positionals[1]}"`, "run `lore instructions [<topic>]`");
+  }
+  return positionals[0] ?? "overview";
+}
+
+/** Build the `instructions.text` {@link Renderable} for one topic. */
+function instructionsRenderable(topic: InstructionTopic): Renderable<InstructionsData> {
+  const data: InstructionsData = {
+    topic: topic.key,
+    title: topic.title,
+    body: topic.body,
+    topics: INSTRUCTION_TOPICS.map(({ key, title }) => ({ key, title })),
+  };
+  return { kind: "instructions.text", data, pretty: renderPretty, plain: renderPlain };
+}
+
+/** `<title>` heading (painted when `color`) + a blank line + the body. Shared by pretty/plain so the two differ only in color. */
+function render(data: InstructionsData, color: boolean): string {
+  return `${paint(data.title, ANSI.green, color)}\n\n${data.body}`;
+}
+
+function renderPretty(data: InstructionsData, opts: { color: boolean }): string {
+  return render(data, opts.color);
+}
+
+function renderPlain(data: InstructionsData): string {
+  return render(data, false);
+}