@sleepy_panda_srl/portulan 0.1.0

package/cli/init.mjs

@@ -0,0 +1,1729 @@
+#!/usr/bin/env node
+// `init` — the subcommand that drafts a workspace for a repository that has none.
+//
+// `docs/plan.md` row 7: *"`init` asks where this repository's workspace resides — in the repository,
+// or in a workspace that names it — and writes a full workspace or a pointer accordingly."* That verb
+// is the design. This tool has **no default residence**: the one thing the row says it asks is the one
+// thing it may not decide, and the wrong guess is the dual-management shape
+// `../.portulan/proposals/0017-one-repository-one-governing-workspace.md` exists to refuse.
+//
+// ## What it writes, and what it refuses to write
+//
+// It drafts. `docs/vision.md` carries *"No auto-generated curated context. `init` drafts; humans
+// accept"* as a binding non-goal, so every file here is a starting point with the questions left
+// visible in it — never a filled-in workspace that reads as finished. The two hard refusals:
+//
+// **It never overwrites a residence.** A repository already carrying a workspace or a pointer is
+// governed, and replacing that is not onboarding — it is the switch, which `cli/vendor.mjs` carries as
+// of 2026-08-03, when the maintainer widened `vendor`'s gloss and settled the verb he had deliberately
+// left unassigned on 2026-07-31. So `init` stops, says which residence it found, and names the tool
+// whose job the switch is.
+//
+// **It refuses rather than emitting a manifest a validator would misread.** A governor or a name that
+// is not a slug is caught here, at the boundary, because `doctor`'s cross-repository check still
+// mis-reports an empty governor as a *conflicting* one
+// ([#141](https://github.com/sleepy-panda-srl/portulan/issues/141)). That bug is `doctor`'s to fix;
+// what this tool owes is that it can never be the thing that produced the input.
+//
+// ## Two capabilities this draft deliberately does not claim
+//
+// **The session-end gate is drafted as a binding, not as a wire — and the reason has CHANGED, so the
+// paragraph is rewritten rather than left standing.** It used to be that `cli/compile.mjs` emitted a
+// `Stop` hook naming `.portulan/compile/stop.mjs`, which was customer zero's own file and shipped in no
+// published artifact, so a drafted workspace's compiled hook would have pointed at a file the adopter
+// does not have — a gate existing only as a sentence, since a missing hook **fails open** (measured,
+// CLI 2.1.220). That was the state the maintainer's 2026-07-31 ruling waited on: decide the runner's
+// residence when there is a concrete mechanism to point at.
+//
+// **The mechanism now exists.** Both runners live in `cli/`, ship in the published package, and
+// `compile` emits a path that resolves from a checkout and from a project-local install. What `init`
+// still does not do is *run* `compile` over what it drafts — so a drafted workspace has the binding and
+// no compiled hooks until its human runs `compile` themselves, which is the honest remaining gap and is
+// what `cli/init.test.mjs` asserts.
+//
+// **The drafted README said the opposite for one pull request.** It told every adopter the runner "is not
+// shipped in any artifact you have received" and that "nothing here compiles to a working Stop hook" —
+// true before the runners moved, false the moment they did, and it survived a fourteen-carrier sweep
+// because it describes the mechanism without naming the files the sweep was grepping for. The worst
+// shape available: a false claim emitted into somebody else's tree, telling them a rail they now have is
+// one they do not.
+//
+// **The interview asks where somebody is there to answer — milestone 7 session 7.** `docs/vision.md`
+// glosses `init` as *interview + codebase scan*, and until this session the second half shipped and the
+// first did not: the substrate — every question modelled as an answer, with a validator each — was
+// built first precisely because a prompt loop cannot be run by CI, by a test, or by a headless host.
+// It now drives a loop, under two conditions that keep both halves honest: the interview runs only
+// where **stdin and stdout are both TTYs**, so every non-interactive invocation is byte-for-byte what
+// it was before; and it decides nothing the flags path could not decide, so the two are one tool with
+// two front doors rather than two tools. `--no-interview` is the escape for a terminal that wants the
+// refusals. _(This paragraph read "there is no interactive interview yet" and left whether flags
+// satisfy the gloss to the maintainer at milestone 7's close. The question is retired rather than
+// answered: the loop exists, so nobody has to rule on whether its absence was acceptable.)_
+//
+// ## Exit codes
+//
+// `0` it wrote · `2` it wrote nothing. There is deliberately **no 1**: this tool renders no verdict
+// about anybody's workspace, so it has no red to report. `compile` documents the same asymmetry from
+// the other side — writing never returns 1, because a run that rewrites an artifact has nothing to
+// disagree with.
+//
+// _The second code read "it could not run" until the interview arrived, and the interview introduced a
+// way to write nothing that is not a failure at all: a human declining at the confirmation, or ending
+// the input. Widening the sentence is the honest repair — `0` must keep meaning *it wrote*, since
+// callers chain on it, and a decline is nobody's verdict. So the code is the same and the gloss now
+// covers every way of reaching it._
+
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+// Host plugin-cache discovery (#123). `init` composes a checkpoints pack by default — row 7 clause (a)
+// — so it is the tool that most needed a root it did not have to be told.
+import { AUTO, discoverPackRoots, namedWithAuto } from "./discover.mjs";
+
+// The handoff index is GENERATED, and this is the generator — the same one `index --check` compares
+// against. Imported rather than approximated: a draft that wrote its own version of this file would be
+// a second renderer of one artifact, and the drafted rail would go red on the adopter's first run
+// against a difference this tool invented. `cli/index.mjs` imports nothing from here, so the direction
+// is one-way.
+import { renderHandoffIndex } from "./index.mjs";
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+
+/** Every refusal in this file. Carrying a class rather than a string lets `run` map all of them to 2. */
+export class InitError extends Error {}
+
+// ONE definition of a slug, read from the contract that publishes it rather than written out again.
+//
+// A second copy here would be free to drift from `spec/workspace.schema.json`, and this tool's whole
+// job at the boundary is to refuse exactly what that schema refuses. The read works in both layouts —
+// from a checkout `spec/` is one level up from `cli/`, and the published package keeps that shape
+// because `files` ships both under the package root.
+//
+// Unreadable is not fatal at import time, because a module that throws while loading gives the entry
+// point nothing better than a stack trace. It becomes a could-not-run inside `run`, which is where a
+// user can be told what is missing.
+let SCHEMA_ERROR = null;
+export const SLUG = (() => {
+    try {
+        const file = path.join(HERE, "..", "spec", "workspace.schema.json");
+        return new RegExp(JSON.parse(fs.readFileSync(file, "utf8")).$defs.slug.pattern);
+    } catch (error) {
+        SCHEMA_ERROR = error;
+        return null;
+    }
+})();
+
+/** The Workspace Definition this tool writes against. A pointer needs 2.7 — the version that added it. */
+const SPEC = "2.7";
+
+/** The gate-policy spec `cli/compile.mjs` reads. Checked by its own suite, not guessed at here. */
+const GATE_POLICY_SPEC = "2.2";
+
+const RESIDENCES = new Set(["in-repo", "pointer"]);
+
+/** The pack composed by default when the cycle is scaffolded. The workspace names it; core names none. */
+const DEFAULT_CHECKPOINTS = "rituals/checkpoints";
+
+// Every key an answers file may carry, and the flag each corresponds to. Declared as data because the
+// file reader and the flag parser must agree about what an answer IS — two lists is how a `residnce`
+// gets silently dropped and the tool then asks for something the adopter believes they supplied.
+const ANSWER_KEYS = new Set(["residence", "name", "summary", "governed-by", "feed", "checkpoints", "cycle", "pack-root"]);
+
+/**
+ * A directory name, or any string, reduced to the schema's slug shape.
+ *
+ * Returns `null` rather than a fallback when nothing survives: a workspace called `workspace` because
+ * the directory was `---` is a name nobody chose, and `init` asks instead.
+ */
+export function slugify(text) {
+    const slug = String(text ?? "")
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "");
+    return slug === "" ? null : slug;
+}
+
+// ------------------------------------------------------------------------- the command line
+
+/**
+ * Splits argv into flags and the single target directory.
+ *
+ * Throws rather than returning a half-parsed shape: a flag whose value is missing must not silently
+ * consume the next flag, which is the parsing bug that turns `--name --residence in-repo` into a
+ * workspace named `--residence`.
+ */
+export function parseArgs(argv) {
+    const flags = {};
+    const targets = [];
+    let help = false;
+
+    const VALUED = new Set(["--residence", "--name", "--summary", "--governed-by", "--feed", "--checkpoints", "--answers", "--pack-root"]);
+
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg === "--help" || arg === "-h") {
+            help = true;
+        } else if (arg === "--no-cycle") {
+            flags.cycle = false;
+        } else if (arg === "--no-interview") {
+            // Not an answer, so it is deliberately outside ANSWER_KEYS and cannot arrive in an answers
+            // file: it governs how the answers are collected, and a file of answers has already
+            // collected them.
+            flags.noInterview = true;
+        } else if (VALUED.has(arg)) {
+            const value = argv[i + 1];
+            // ANY leading `-` is a missing value, not `--` only. `cli/doctor.mjs` already guards this
+            // way and `init` was the outlier: `init --residence -h <dir>` consumed `-h` as the
+            // residence and then complained that `-h` is not one, which blames the user for a token
+            // they typed as a flag. A help request is the likeliest thing to land here, and it was
+            // the likeliest thing to be eaten. Found by review on the pull request.
+            //
+            // A value that genuinely begins with `-` is not lost: `--answers` carries it, where the
+            // shape is a JSON string and nothing has to guess where a flag ends.
+            if (value === undefined || value.startsWith("-")) {
+                throw new InitError(
+                    `\`${arg}\` needs a value and the next argument is \`${value ?? "(nothing)"}\` — refusing to read a ` +
+                        `flag as one. If the value really does start with \`-\`, pass it through \`--answers\`, where it ` +
+                        `is a JSON string and nothing has to guess.`,
+                );
+            }
+            // An EMPTY value is given-but-invalid, and it is refused here for every flag rather than
+            // per-field. `--summary ""` used to pass straight through `??` into the manifest, where
+            // the schema's `minLength: 1` made `doctor` red on a workspace `init` had just reported
+            // writing successfully — the one outcome this tool exists to make impossible. No flag
+            // here has a meaningful empty value, so one rule covers all of them.
+            if (value.trim() === "") {
+                throw new InitError(
+                    `\`${arg}\` was given an empty value. Every answer this tool writes into a manifest has to be ` +
+                        `non-empty — an empty one validates nowhere — so it is refused rather than treated as unasked.`,
+                );
+            }
+            const key = arg.slice(2);
+            if (key === "pack-root") (flags["pack-root"] ??= []).push(value);
+            else flags[key] = value;
+            i++;
+        } else if (arg.startsWith("-")) {
+            // #155: this said "run `init --help`", which is not a command anybody can run. The tool is
+            // genuinely reachable two ways and the honest string differs per invocation, so both are
+            // named rather than one being derived — deriving it would mean the entry point telling the
+            // subcommand what name it was invoked under, and that entry point deliberately passes argv
+            // and nothing else, so the tool behaves identically either way. A better sentence is not
+            // worth trading that property for. The same fix is applied to `usage()` below.
+            throw new InitError(
+                `unknown option \`${arg}\` — run \`portulan init --help\` for the ones this understands, ` +
+                    `or \`node cli/init.mjs --help\` from a checkout`,
+            );
+        } else {
+            targets.push(arg);
+        }
+    }
+
+    if (targets.length > 1) {
+        throw new InitError(
+            `${targets.length} target directories given (${targets.join(", ")}) — \`init\` drafts one workspace for one ` +
+                `repository, and picking one of two would be choosing which repository gets governed`,
+        );
+    }
+
+    return { help, flags, target: targets[0] ?? null };
+}
+
+/**
+ * Merges an `--answers` file under the flags, and refuses anything it does not recognise.
+ *
+ * The nearer answer wins: a flag typed on the command line overrides the same key in the file, which
+ * is the resolution cascade's own direction — more specific beats more general.
+ */
+export function resolveAnswers(flags) {
+    let fromFile = {};
+    if (flags.answers) {
+        let raw;
+        try {
+            raw = fs.readFileSync(flags.answers, "utf8");
+        } catch (error) {
+            throw new InitError(`could not read the answers file \`${flags.answers}\` — ${error.message}`);
+        }
+        try {
+            fromFile = JSON.parse(raw);
+        } catch (error) {
+            throw new InitError(`the answers file \`${flags.answers}\` is not valid JSON — ${error.message}`);
+        }
+        if (!fromFile || typeof fromFile !== "object" || Array.isArray(fromFile)) {
+            throw new InitError(`the answers file \`${flags.answers}\` must hold a JSON object of answers`);
+        }
+        // Refused rather than ignored, on the schema's own `additionalProperties: false` reasoning: the
+        // common case is a typo, and a silently-dropped answer leaves the tool asking for something the
+        // adopter believes they gave.
+        const unknown = Object.keys(fromFile).filter((key) => !ANSWER_KEYS.has(key));
+        if (unknown.length) {
+            throw new InitError(
+                `the answers file carries ${unknown.map((k) => `\`${k}\``).join(", ")}, which is not an answer this tool asks for ` +
+                    `(it asks: ${[...ANSWER_KEYS].join(", ")}). A misspelt key is an answer nobody receives.`,
+            );
+        }
+        // The VALUES are checked too, not only the keys. Lecturing about a misspelt key while
+        // accepting `"cycle": "false"` — a truthy string that composes the pack the adopter was
+        // trying to switch off — checks the half that is easy to check and lets the half that
+        // changes behaviour through.
+        for (const [key, value] of Object.entries(fromFile)) {
+            const expected = key === "cycle" ? "boolean" : "string";
+            const actual = Array.isArray(value) ? "array" : typeof value;
+            const arrayOk = key === "pack-root" && Array.isArray(value) && value.every((v) => typeof v === "string" && v.trim() !== "");
+            if (arrayOk) continue;
+            if (actual !== expected) {
+                throw new InitError(
+                    `the answers file gives \`${key}\` as ${actual === "array" ? "an array" : `a ${actual}`} (${JSON.stringify(value)}), ` +
+                        `and this tool reads it as ${expected === "boolean" ? "a boolean" : "a string"}. \`"cycle": "false"\` is a ` +
+                        `non-empty string, which is true — the answer would do the opposite of what it reads as.`,
+                );
+            }
+            if (expected === "string" && value.trim() === "") {
+                throw new InitError(`the answers file gives \`${key}\` as an empty string, which validates nowhere — refused rather than read as unasked`);
+            }
+        }
+    }
+
+    const merged = { ...fromFile };
+    for (const [key, value] of Object.entries(flags)) {
+        // Neither is an answer. `--answers` names where answers come from and `--no-interview` says
+        // how they are collected, and letting either into `given` would put a flag nobody answered
+        // into the set the misplaced-option refusal reads.
+        if (key === "answers" || key === "noInterview") continue;
+        merged[key] = value;
+    }
+
+    // WHICH keys were actually supplied, kept apart from what they resolved to. `cycle` and
+    // `checkpoints` have defaults, so their values cannot tell a caller who typed them from a caller
+    // who did not — and the residence check below must refuse only what somebody asked for. A
+    // default that triggered a refusal would be the tool objecting to its own choice.
+    const given = new Set(Object.keys(merged));
+
+    return {
+        given,
+        residence: merged.residence ?? null,
+        name: merged.name ?? null,
+        summary: merged.summary ?? null,
+        governedBy: merged["governed-by"] ?? null,
+        feed: merged.feed ?? null,
+        checkpoints: merged.checkpoints ?? DEFAULT_CHECKPOINTS,
+        cycle: merged.cycle !== false,
+        // NORMALISED to an array, because the two sources disagree about shape. The flag is
+        // repeatable and accumulates into one; an answers file may reasonably give a single string,
+        // which the value check above accepts as a string like every other key. Everything
+        // downstream — `.length`, `.map`, `packResolves`'s `.some` — is array-shaped, so a string
+        // reaching here turned a perfectly valid answers file into `roots.some is not a function`:
+        // a real answer, refused with a message about somebody else's bug. Found by review on the
+        // pull request. Normalising here rather than at each use keeps one shape after this line.
+        packRoots: [merged["pack-root"] ?? []].flat(),
+    };
+}
+
+/** Everything that must be true before a single byte is written. Each refusal names what to type. */
+export function validateAnswers(answers) {
+    // The named+auto pair, refused for EVERY path rather than inside the one branch that resolves a
+    // pack. It lived in the `residence === "in-repo" && cycle && packRoots.length` arm until Copilot's
+    // round 3, so `--no-cycle` with both flags was accepted and one of them silently ignored —
+    // breaking the *refused in all five tools* claim that change made, in the fifth tool. _(Five was the
+    // set on #233; it is seven since `recipe-set` and this file joined. Kept as the round's own words
+    // rather than re-typed, and dated so it does not read as a present count.)_
+    //
+    // Third time this session that a correct refusal was placed where something could skip it: below a
+    // workspace read in `compile`, below a manifest read in `skills-set`, and inside a conditional
+    // here. The rule the three share is that a judgement about the COMMAND LINE belongs where the
+    // command line is assembled, not where its subject is used.
+    const bothAsked = namedWithAuto(
+        (answers.packRoots ?? []).filter((r) => r !== AUTO),
+        (answers.packRoots ?? []).includes(AUTO),
+    );
+    if (bothAsked) throw new InitError(bothAsked);
+    if (!answers.residence) {
+        throw new InitError(
+            "no residence given — `init` asks where this repository's workspace lives and will not choose for you. " +
+                "Pass `--residence in-repo` to write a full workspace into this repository, or `--residence pointer` " +
+                "with `--governed-by <workspace>` to record that another workspace governs it. A repository is " +
+                "governed by exactly one workspace, so this answer is the one that cannot be defaulted.",
+        );
+    }
+    if (!RESIDENCES.has(answers.residence)) {
+        throw new InitError(`\`${answers.residence}\` is not a residence — the two are \`in-repo\` and \`pointer\``);
+    }
+    if (answers.name !== null && !SLUG.test(answers.name)) {
+        throw new InitError(
+            `the workspace name \`${answers.name}\` is not a slug — lowercase letters, digits and single hyphens ` +
+                `(${SLUG.source}). A workspace ships as a plugin through a feed, so its name is an identifier rather than a title.`,
+        );
+    }
+    // ACCEPTED-BUT-IGNORED is refused, because this file's header claims it refuses what it cannot
+    // act on and that claim has to be true. `--feed` and `--governed-by` mean nothing to a full
+    // workspace; `--pack-root`, `--checkpoints` and `--no-cycle` mean nothing to a pointer, which
+    // composes nothing. Silently dropping them lets a caller — or an answers file nobody re-reads —
+    // believe an option had an effect it never had, which is the same defect as `--summary ""`
+    // reaching a manifest: an answer accepted and then not honoured. Found by review on the pull
+    // request. Keyed on what was GIVEN, never on the resolved value, so a default never trips it.
+    const misplaced = {
+        "in-repo": ["feed", "governed-by"],
+        pointer: ["pack-root", "checkpoints", "cycle"],
+    }[answers.residence].filter((key) => answers.given.has(key));
+    if (misplaced.length) {
+        const spelling = (key) => (key === "cycle" ? "`--no-cycle`" : `\`--${key}\``);
+        throw new InitError(
+            `${misplaced.map(spelling).join(" and ")} ${misplaced.length > 1 ? "do" : "does"} nothing with ` +
+                `\`--residence ${answers.residence}\` — ${
+                    answers.residence === "pointer"
+                        ? "a pointer holds no policy of its own, so it composes no packs"
+                        : "a workspace that lives here has no governor and no feed to be delivered from"
+                }. Refused rather than ignored: an option accepted and then dropped is one you will believe had an effect.`,
+        );
+    }
+
+    if (answers.residence === "pointer") {
+        // Absent and invalid are different answers and take different refusals: telling an adopter
+        // who typed a malformed governor to pass the flag they just passed sends them to the wrong
+        // place. The EMPTY spelling never reaches here — the command line refuses it earlier, where
+        // the clearer sentence lives — so this branch is the omission and the one below is the
+        // malformation. Both matter because an empty or non-string governor is exactly the value
+        // `doctor` still mis-reports as a *conflicting* one (#141).
+        if (answers.governedBy === null) {
+            throw new InitError(
+                "a pointer must name the workspace that governs this repository — pass `--governed-by <workspace>`. " +
+                    "A pointer that names nothing governs nothing, and is indistinguishable from a repository that " +
+                    "never adopted Portulan.",
+            );
+        }
+        if (!SLUG.test(answers.governedBy)) {
+            throw new InitError(
+                `the governing workspace \`${answers.governedBy}\` is not a slug — lowercase letters, digits and single ` +
+                    `hyphens (${SLUG.source}). It must be spelled exactly as that workspace's own \`name\`, or the pointer ` +
+                    `and its target have drifted into two identifiers.`,
+            );
+        }
+    }
+    if (answers.residence === "in-repo" && answers.cycle) {
+        const parts = String(answers.checkpoints).split("/");
+        if (parts.length !== 2 || !parts.every((part) => SLUG.test(part))) {
+            throw new InitError(
+                `\`${answers.checkpoints}\` is not a pack id — a pack is \`<category>/<name>\`, each a slug, as ` +
+                    `\`spec/pack.schema.json\` defines it. Composing an id nothing can resolve would put a red in the ` +
+                    `adopter's first run for a reason they did not cause.`,
+            );
+        }
+    }
+}
+
+// ------------------------------------------------------------------------- the codebase scan
+
+/**
+ * Reads what the repository actually says about itself. **Observations only.**
+ *
+ * The failure an onboarding tool is most likely to commit is the confident default: emitting
+ * `make test` because most repositories have one. `doctor` lints repo-card build and test claims
+ * against the tree, so an invented claim is a red the adopter did not cause — and, worse, a workspace
+ * that lies about them on the day it was created. Every field here is either read out of a file that
+ * exists or left `null`, and `null` is written into the draft as *not determined* rather than dropped.
+ */
+export function scan(dir) {
+    const observed = { stack: [], build: null, test: null, run: null, name: null, vcs: null, evidence: [] };
+    const has = (rel) => fs.existsSync(path.join(dir, rel));
+    const read = (rel) => {
+        try {
+            return fs.readFileSync(path.join(dir, rel), "utf8");
+        } catch {
+            return null;
+        }
+    };
+
+    if (has(".git")) {
+        observed.vcs = "git";
+        observed.evidence.push(".git/");
+    }
+
+    if (has("package.json")) {
+        observed.stack.push("node");
+        observed.evidence.push("package.json");
+        let manifest = null;
+        try {
+            manifest = JSON.parse(read("package.json"));
+        } catch {
+            // A package.json that does not parse is evidence of node and evidence of nothing else. It
+            // is not this tool's business to fix it, and reading scripts out of a guess would be the
+            // invented claim this whole function exists to avoid.
+        }
+        if (manifest && typeof manifest === "object") {
+            if (typeof manifest.name === "string") observed.name = manifest.name;
+            const scripts = manifest.scripts ?? {};
+            if (typeof scripts.test === "string") observed.test = scripts.test;
+            if (typeof scripts.build === "string") observed.build = scripts.build;
+            if (typeof scripts.start === "string") observed.run = scripts.start;
+        }
+    }
+
+    const makefile = read("Makefile") ?? read("makefile");
+    if (makefile !== null) {
+        observed.stack.push("make");
+        observed.evidence.push("Makefile");
+        // A target that exists is an observation; `make test` on a Makefile with no `test:` target is
+        // a guess, and would fail for the adopter the first time they ran it.
+        for (const [target, key] of [["test", "test"], ["build", "build"], ["run", "run"]]) {
+            if (observed[key] === null && new RegExp(`^${target}\\s*:`, "m").test(makefile)) observed[key] = `make ${target}`;
+        }
+    }
+
+    for (const [file, stack] of [["pyproject.toml", "python"], ["Cargo.toml", "rust"], ["go.mod", "go"]]) {
+        if (has(file)) {
+            observed.stack.push(stack);
+            observed.evidence.push(file);
+        }
+    }
+
+    return observed;
+}
+
+// ------------------------------------------------------------------------- the draft
+
+/**
+ * Decides the whole file set and returns it. **Writes nothing.**
+ *
+ * The split from writing is what keeps every refusal ahead of the first byte on disk: a tool that
+ * decides while writing has no state left in which it can still refuse. It also makes the shape
+ * testable without a filesystem, which is why almost every assertion in the suite is cheap.
+ *
+ * @returns {Map<string, {contents: string, mode?: number}>} keyed by path relative to the target
+ */
+export function draft(answers, observed) {
+    return answers.residence === "pointer" ? draftPointer(answers) : draftWorkspace(answers, observed);
+}
+
+function json(value) {
+    return `${JSON.stringify(value, null, 2)}\n`;
+}
+
+function draftPointer(answers) {
+    const files = new Map();
+
+    // Exactly the five keys `doctor` permits a pointer, and no others. Anything more is not a
+    // cosmetic defect here — it is the dual-management refusal, and the adopter's first run is red.
+    const manifest = {
+        portulan: { spec: SPEC },
+        name: answers.name ?? "workspace",
+        summary: answers.summary ?? `This repository is governed by the \`${answers.governedBy}\` workspace.`,
+        kind: "pointer",
+        governed_by: answers.feed ? { workspace: answers.governedBy, feed: answers.feed } : { workspace: answers.governedBy },
+    };
+    files.set(".portulan/workspace.json", { contents: json(manifest) });
+
+    files.set(".portulan/README.md", {
+        contents: `# This repository's workspace lives elsewhere
+
+This directory holds a **pointer**, not a workspace. It records one fact: the \`${answers.governedBy}\`
+workspace governs this repository${answers.feed ? `, and ships through the \`${answers.feed}\` feed` : ""}.
+
+A repository is governed by **exactly one** workspace — it carries its own full workspace, or a pointer
+to the workspace that names it, never both. Two policy layers for one repository is not redundancy; it
+is an agent booting on the wrong gates and looking exactly like success.
+
+## What you get here, and what you do not
+
+Every Portulan feature keys to a workspace **slot**, never to a residence, so nothing is lost by
+governing this repository from elsewhere. One step is real and is named rather than claimed away:
+**the governing workspace has to be installed before anything boots against it**, and no tool here
+fetches it. What *is* built is the step after that — a host's installed-plugin record is read from
+disk and this pointer's \`governed_by\` is resolved against it, so once the workspace is installed
+the boot loads it and reports it exactly as it would an in-repo one. Run
+\`node <portulan>/cli/discover.mjs --json .portulan\` to see which of the four answers this machine
+gives: resolved, not installed here, ambiguous, or could not look.
+
+## Moving back
+
+If this repository should carry its own workspace instead, that is a **switch**, not a re-run of
+\`init\`: the workspace is materialised in the new residence, a pointer or nothing is left in the old
+one, and validation is green at both ends *before* the old residence is retired.
+
+From this repository's root, with the \`${answers.governedBy}\` workspace checked out somewhere you can
+name — nothing here fetches it:
+
+\`\`\`
+portulan vendor <path to the ${answers.governedBy} workspace> --into .portulan --residence in-repo --switch
+\`\`\`
+
+Run that rather than deleting this file and writing a workspace by hand — the window between those two
+acts is a repository governed by nothing, which looks identical to a repository that never adopted
+Portulan.
+
+## Curate this
+
+\`init\` drafted this file. The \`summary\` in \`workspace.json\` is a placeholder; make it say what
+this repository is, in the one line an agent reads before loading anything else.
+`,
+    });
+
+    return files;
+}
+
+function draftWorkspace(answers, observed) {
+    const files = new Map();
+    const name = answers.name ?? "workspace";
+
+    const manifest = {
+        portulan: { spec: SPEC },
+        name,
+        summary: answers.summary ?? `The ${name} workspace — drafted by \`init\`, and not yet curated.`,
+        kind: "repository",
+        // A `repository` workspace must declare `tree`: it is the policy layer of a repository that is
+        // present, so it has an answer, and without one every repo-card and gate-map claim silently
+        // degrades from checked to unverifiable. The constraint is `doctor`'s rather than the schema's,
+        // which makes it exactly the kind a generator forgets.
+        tree: "../",
+        gates: "gates.json",
+        slots: {
+            identity: "identity.md",
+            principles: "principles.md",
+            gates: "gate-map.md",
+            dod: "dod.md",
+            handoffs: "handoffs/",
+        },
+        verify: {
+            default: "workspace",
+            recipes: [
+                {
+                    id: "workspace",
+                    run: "./.portulan/verify/workspace.sh",
+                    requires: ["bash"],
+                    doc: "verify/README.md",
+                },
+                // The records rail — row 7 clause (a)'s third record convention, beside the handoffs
+                // directory and the session-end binding. A generated index nothing compares is a file
+                // that is current until the first person forgets, which is the reminder this project
+                // trades for a rail wherever it can. It is NOT the default: the default is what the
+                // Stop-gate runs at every session end, and that slot belongs to the recipe saying
+                // whether the repository works.
+                {
+                    id: "index",
+                    run: "./.portulan/verify/index.sh",
+                    requires: ["bash", "node"],
+                    doc: "verify/README.md",
+                },
+            ],
+        },
+        // Sited OUTSIDE the series it indexes: an index living in `handoffs/` would be counted as a
+        // handoff by everything that walks the directory.
+        handoffs: { index: { path: "handoffs-index.md" } },
+    };
+    if (answers.cycle) manifest.packs = [answers.checkpoints];
+
+    files.set(".portulan/workspace.json", { contents: json(manifest) });
+    files.set(".portulan/gates.json", { contents: json(draftPolicy()) });
+    files.set(".portulan/README.md", { contents: draftReadme(answers, observed, name) });
+    files.set(".portulan/identity.md", { contents: draftIdentity(observed, name) });
+    files.set(".portulan/principles.md", { contents: draftPrinciples(name) });
+    files.set(".portulan/gate-map.md", { contents: draftGateMap() });
+    files.set(".portulan/dod.md", { contents: draftDod() });
+    files.set(".portulan/verify/README.md", { contents: draftVerifyReadme() });
+    files.set(".portulan/verify/workspace.sh", { contents: draftRecipe(), mode: 0o755 });
+    files.set(".portulan/verify/index.sh", { contents: draftIndexRecipe(), mode: 0o755 });
+    // Written by the generator, not by this file, and written NOW rather than left for the adopter's
+    // first `index` run — a rail whose subject does not exist yet is a red on day one for a file
+    // nobody was asked to write. An empty series renders an index with a zero count, which is the
+    // honest state of a workspace drafted five seconds ago.
+    files.set(`.portulan/${manifest.handoffs.index.path}`, {
+        contents: renderHandoffIndex(manifest, { records: [], bytes: 0 }),
+    });
+    // A Map of files cannot express an empty directory and git does not track one, so the slot's
+    // directory is created by a file that says why it is there.
+    files.set(".portulan/handoffs/.gitkeep", {
+        contents: "# The handoff series. One dated record per session; filenames lead with YYYY-MM-DD.\n",
+    });
+
+    return files;
+}
+
+function draftPolicy() {
+    return {
+        portulan: { spec: GATE_POLICY_SPEC },
+        why: "gate-map.md",
+        // A floor is drafted with no required checks, deliberately. `doctor` FAILS a floor requiring a
+        // status check no workflow job in the tree reports — so a draft naming the checks this
+        // repository has not written yet would put a red in the adopter's first run and teach them the
+        // tool guesses. The branch is the answer nearly every repository shares; the checks are theirs.
+        floor: {
+            branch: "main",
+            checks: [],
+            reviews: 0,
+            resolve_conversations: true,
+        },
+        rules: [
+            // The two rules below are the ones the FLOOR backend can actually compile — a policy
+            // whose floor no rule reaches is refused outright, so a starter policy that declared a
+            // floor and gated only `gh pr merge` would put a hard red in the adopter's very first
+            // run. Found by running the real validator against a real draft rather than by reading
+            // the compiler. They are also the right two to start with: both destroy a ref rather
+            // than adding one, which is the property that puts them above the line.
+            {
+                id: "force-push-without-a-lease",
+                tier: "gated",
+                action: { shell: "git push --force" },
+                reason: "A bare force-push to a shared remote can silently discard commits that arrived since you last fetched, and that is the one part of pushing which is not recoverable in a working copy. Use `--force-with-lease`, which refuses the push if the remote moved.",
+            },
+            {
+                id: "delete-a-remote-branch",
+                tier: "gated",
+                action: { shell: "git push --delete" },
+                reason: "Deleting a branch on a shared remote destroys a ref rather than adding one. It is the single push spelling whose damage outlives the working copy. SHARED is the operative word. Two conditions, both required: you created the branch, AND deleting the ref destroys no work that exists nowhere else. A branch somebody else pushed stays gated however the second comes out — they may be relying on it. Test the second against the REMOTE ref and fail closed: `git fetch origin <branch>:refs/remotes/origin/<branch> && git cherry origin/<default-branch> origin/<branch>` must exit 0 and show zero `+` lines, because an unknown ref exits 128 and prints nothing, which reads as zero. The base is the branch the work was destined for — your default branch, whatever it is named — and NOT any branch you happen to pick: a wrong base answers no-unique-work about a question nobody asked. `git branch --merged` lies wherever you rebase-merge. Any `+` line, any error, or any doubt about either condition: gated.",
+            },
+            {
+                id: "merge-a-pull-request",
+                tier: "gated",
+                action: { shell: "gh pr merge" },
+                reason: "An agent never decides for itself that a change is ready to land. A commit enters the repository's record here, and that decision is a human's.",
+            },
+            {
+                id: "edit-the-workspace",
+                tier: "propose",
+                action: { write: ".portulan/" },
+                reason: "This workspace is the layer that decides gates, lanes and the bar for done. Changing it by pull request is what keeps an agent from widening its own permissions in the same change it uses them.",
+            },
+            {
+                id: "edit-on-a-working-branch",
+                tier: "auto",
+                action: { write: "./" },
+                reason: "Creating and editing files on a working branch is unattended. What makes it safe is the gate on landing, not the edit.",
+            },
+        ],
+    };
+}
+
+function draftReadme(answers, observed, name) {
+    const bound = answers.cycle
+        ? `This workspace composes the \`${answers.checkpoints}\` pack, which carries the three checkpoint
+skills — session-open, pre-commit, milestone-close — and the supervisor persona that staffs them.`
+        : `This workspace composes no packs: \`init\` was run with \`--no-cycle\`. The checkpoint ritual is
+the one most teams want first; add it to \`packs\` in \`workspace.json\` when you do.`;
+
+    return `# ${name} — a drafted workspace
+
+\`init\` wrote every file in this directory. **None of it is finished**, and that is deliberate: agents
+may draft this layer and may never own it. Read each file, delete what does not describe your team, and
+replace the placeholders. A workspace you have not curated is a workspace that makes an agent work
+*generically* — which is the one thing it exists to prevent.
+
+## Where to start
+
+1. **\`identity.md\`** — who you are, your stack, your glossary. It is the first thing an agent reads
+   after the kernel, and the scan below could only observe so much.
+2. **\`principles.md\`** — the handful of rules that are yours rather than everyone's. Placeholders
+   until you write them.
+3. **\`verify/workspace.sh\`** — **this exits 2 (could not run) until you edit it.** It cannot report
+   green, because nobody has told it what green means for this repository. That is the honest state, not
+   a bug: "nothing looked" must never read as "nothing wrong."
+4. **\`gate-map.md\` and \`gates.json\`** — ${draftPolicy().rules.length} starter rules and a platform
+   floor with no required checks. Add your checks once your CI reports them; a floor requiring a check
+   no job reports blocks every pull request.
+
+## The cycle this drafts
+
+${bound}
+
+**What is bound and what is not, stated plainly** — because a workspace that overstates its own rails
+is worse than one with fewer of them.
+
+- **The pack is named; resolving it is a separate step.** Naming a pack and finding it on this machine
+  are different things. **Until the root resolves, validation is RED**, not merely unverified:
+  \`doctor\` fails a declared pack it cannot resolve rather than passing over it. Three ways out —
+  \`doctor --pack-root auto .portulan\`, which finds it in this host's installed plugins;
+  \`doctor --pack-root <dir> .portulan\` if you would rather name the location; or \`init --no-cycle\`
+  to compose the pack later, once you know where it lives.
+- **The records conventions are drafted, and the freshness rail is one of them** — a \`handoffs/\`
+  directory in the \`handoffs\` slot, a generated \`handoffs-index.md\` **written by the same generator
+  that will check it**, and \`verify/index.sh\` declared beside \`workspace\` to hold the two in
+  agreement. The index starts at zero handoffs, which is what this repository has, so the rail is green
+  today rather than red about a file nobody wrote. Edit that index by hand and the rail goes red; add a
+  handoff without regenerating and it goes red the same way. It is **not** the default recipe: the
+  default is what runs at every session end, and that slot belongs to the one that says whether this
+  repository works.
+- **The rail needs the CLI, and may not find it here.** It looks at \`$PORTULAN_CLI\`, then
+  \`portulan\` on your \`PATH\`, then the bundle this workspace was drafted from — an absolute path on
+  the machine that ran \`init\`, which git cannot carry to anybody else. Where none answers it exits
+  **2 — could not run**, never 0. On CI that is the state to expect until the CLI is installed there,
+  and it is said here rather than left to be met as an amber pipeline.
+- **The session-end gate is wired by \`compile\`, and this draft has not run it.** The runner that
+  enforces "a handoff dated today exists" before a session ends **does** ship in the package you have —
+  it is \`cli/stop-gate.mjs\` — and \`portulan compile\` emits a \`Stop\` hook naming it. What this
+  draft does is bind the ritual and the records conventions; running \`compile\` is the step that turns
+  them into enforcement, and it is yours to run because compiling writes host settings and that is not
+  a thing a scaffold should do to your machine unasked. **Until you run it**, treat the session-end
+  handoff as a practice your team holds rather than a rail — a rule nothing checks is worth exactly
+  what you can remember about it.
+
+## What the scan observed
+
+${observed.evidence.length ? observed.evidence.map((e) => `- \`${e}\``).join("\n") : "- Nothing it recognised. Every claim in `identity.md` is yours to write."}
+
+Only what is listed above was read. Anything \`identity.md\` marks *not determined* was left blank
+rather than guessed at — an invented build command is worse than an absent one, because the workspace
+then disagrees with the repository on the day it was created.
+`;
+}
+
+function draftIdentity(observed, name) {
+    const unknown = "_Not determined by the scan — fill this in._";
+    const row = (label, value) => `| ${label} | ${value ? `\`${value}\`` : unknown} |`;
+
+    return `# Identity — ${name}
+
+> Who this team is, what it builds with, and what its words mean. The first thing an agent reads after
+> the kernel, so keep it short and keep it true. \`init\` drafted this from what it could observe; every
+> line marked *not determined* was left blank rather than guessed at.
+
+## The team
+
+${unknown} — how many people, what they own, how they work.
+
+## The stack
+
+${observed.stack.length ? observed.stack.map((s) => `- \`${s}\``).join("\n") : unknown}
+
+## Commands
+
+| What | Command |
+|---|---|
+${row("Build", observed.build)}
+${row("Test", observed.test)}
+${row("Run", observed.run)}
+
+${
+    observed.build || observed.test || observed.run
+        ? "These were read out of files in this repository, not inferred. Correct them if they are stale."
+        : "The scan found no command written down anywhere it looked. Write them here; anything else would be a guess."
+}
+
+## Glossary
+
+${unknown} — the words your team uses that a newcomer would misread. This section earns its place the
+first time an agent gets one wrong.
+
+## Write the limit, not the aspiration
+
+Where something is not true yet, say so here rather than describing the intended state. A document that
+claims a capability the tree does not have is the defect this section exists to prevent.
+`;
+}
+
+function draftPrinciples(name) {
+    return `# Principles — ${name}
+
+> The rules that are **yours** rather than everyone's. Core already carries the universal ones; this
+> file is what makes an agent work *this* team's way. \`init\` cannot draft these — they are the part
+> no scan can observe and no generator should invent.
+
+Three questions worth answering here, in your own words:
+
+1. **What do you refuse to trade away?** Every team has one — a latency budget, a review depth, a
+   dependency policy, an accessibility floor. Name it, and say what it costs, because a principle with
+   no cost is a preference.
+2. **What has gone wrong more than once?** The rule that would have caught it belongs here, with a link
+   to the incident. A rule with no provenance cannot be retired later, because nobody can tell whether
+   the thing it guards against can still happen.
+3. **Where does this team differ from the obvious default?** That difference is the whole reason this
+   file exists rather than a link to someone's style guide.
+
+_Delete this list once you have replaced it. A workspace whose principles slot still holds the prompt
+is a workspace nobody has curated._
+`;
+}
+
+function draftGateMap() {
+    return `# Gate map
+
+> The **policy** half of the engine's autonomy model. Core defines the tiers — Auto, Propose, Gated,
+> Prohibited — as universal mechanism; this file binds *your* concrete actions to them, because which
+> action is dangerous is a property of a team, not of an engine.
+>
+> **\`gates.json\` is the policy; this file is the rationale.** Where they disagree, the JSON wins — it
+> is the one that compiles.
+
+## The tiers, bound
+
+### Auto — the agent acts unattended
+
+Recoverable, reversible, and it puts nothing in front of anyone.
+
+- \`edit-on-a-working-branch\` — create and edit files on a working branch.
+
+### Propose — the agent drafts; a human decides
+
+- \`edit-the-workspace\` — anything under \`.portulan/\`, including this file and the policy beside it.
+
+### Gated — the agent asks first, every time
+
+- \`force-push-without-a-lease\` — a bare \`--force\` can discard commits that arrived since you fetched.
+  \`--force-with-lease\` is the spelling that refuses when the remote moved.
+- \`delete-a-remote-branch\` — destroys a ref rather than adding one.
+- \`merge-a-pull-request\` — a change enters the record here, and that decision is a human's.
+
+### Prohibited — no role acts here
+
+Nothing yet. Add what must never happen regardless of who asks.
+
+## The platform floor
+
+Branch protection on \`main\`, with conversation resolution required and **no required status checks
+declared yet**. Add your checks to \`floor.checks\` in \`gates.json\` once your CI reports them — a floor
+requiring a check no job reports blocks every pull request, which is why \`init\` declared none.
+
+The two Gated ref rules above are what this floor compiles from: they become \`non_fast_forward\` and
+\`deletion\` on \`refs/heads/main\`. Note the coarseness in the honest direction — \`non_fast_forward\`
+blocks **every** force-push, including \`--force-with-lease\`, which the policy above classifies Auto. A
+ref rule gates a ref and cannot read a command's flags.
+
+Until \`floor.checks\` is declared, \`edit-the-workspace\` and every other Propose rule compiles to
+nothing in this backend: requiring a pull request while requiring nothing green of it reads as a floor
+and is not one.
+
+The floor is the layer indifferent to how a command was spelled. Everything above depends on a host
+honouring a permission rule; this does not.
+
+## The triage threshold
+
+${"_Not set._"} Where does small work stop needing ceremony? Answer it here, in a sentence a person can
+apply without asking. Left unset, every rule above applies to a one-line fix, and a ritual that cannot
+scale down gets switched off wholesale rather than tuned.
+`;
+}
+
+function draftDod() {
+    return `# Definition of done
+
+> Core supplies the floor: green verify, and never report done on what you could not explain. A
+> workspace may **extend** that floor and may never lower it. These are the additional conditions for
+> work here — each one you add should carry the reason it exists, or nobody can tell later whether it
+> still earns its place.
+
+A change is done when **all** of the following hold.
+
+1. **The verify recipe ran green in this working copy.** Not "should pass" — run it and read the
+   output. _Why: this is the only condition whose evidence is a machine's rather than a person's._
+2. **You could walk a reviewer through every line.** _Why: core's bar, and the one most often skipped
+   when a diff is mostly prose — prose reviews as "fine" far more easily than code does._
+
+_Add yours below. Two are enough to start; a list nobody can hold in their head is a list that gets
+skimmed. Each condition should be checkable by someone who was not in the room._
+`;
+}
+
+function draftVerifyReadme() {
+    return `# verify/
+
+The executable half of *done*. \`workspace.json\` declares the recipes and names the default.
+
+**Nothing runs them for you yet, and that is worth knowing before you trust a green.** In this
+repository there is no Stop-gate wired — see \`../README.md\` — and \`init\` writes no CI workflow, so
+these recipes run when a person runs them. The design is that the default recipe is what a session-end
+gate and a pull-request check both call; both of those are things you wire, and until you do, a recipe
+is a command in a file.
+
+| Recipe | What it checks |
+|---|---|
+| \`workspace\` | **Nothing yet — it exits 2.** Replace it with the command that tells you this repository is healthy. This one is the **default**: it is what runs at a session end. |
+| \`index\` | The generated \`handoffs-index.md\` against the series it indexes, byte for byte. Finished as drafted — it checks a real thing today. |
+
+## The three exit codes, and why the middle one is not enough
+
+- **0 — green.** Everything this recipe checks passed.
+- **1 — red.** Something it checks failed. A verdict about the repository.
+- **2 — could not run.** A precondition was missing: a tool absent, a file unreadable, nothing to
+  check. **This is not a pass.** A recipe that returns 0 because it found nothing to look at reports
+  "nothing wrong" when the truth is "nothing looked", and every gate downstream believes it.
+
+\`workspace\` exits 2 for exactly that reason. It is not broken; it is honest about not yet knowing
+what green means here.
+
+**\`index\` has an expected 2 of its own, and it is worth knowing before you meet it.** The recipe needs
+the Portulan CLI, and looks for it in three places: \`$PORTULAN_CLI\`, then \`portulan\` on \`PATH\`,
+then the bundle this workspace was drafted from — the last being an absolute path on the machine that
+ran \`init\`, which git cannot carry to a clone or to a CI runner. Where none of the three answers, and
+where \`node\` itself is absent, the recipe exits **2** and names what it looked for. That is the state
+to expect on CI until the CLI is installed there; it is not a red, and it is not a pass either.
+
+**Regenerating is yours, and the rail deliberately does not do it.** A check that repaired what it
+found would report green on a repository nobody had corrected, and the index is only worth having
+because it is derived — run the index tool yourself and commit the result.
+
+**One thing the three locations cannot establish, said rather than left implicit.** The second of them
+is *whatever \`portulan\` is on your \`PATH\`* — and nothing here can tell that it is this tool rather
+than another program of the same name. Where that matters to you, set \`$PORTULAN_CLI\` to a checkout
+you chose: an explicit path is the one location that answers a question about identity rather than about
+availability, and a location that holds no \`index.mjs\` exits **2** rather than being read as a drifted
+index.
+`;
+}
+
+function draftRecipe() {
+    return `#!/usr/bin/env bash
+# Workspace verify recipe — REPLACE THIS.
+#
+# This is a draft. It runs nothing and exits 2 (could not run), because nobody has yet told it what
+# "green" means for this repository. That is deliberate and it is not a placeholder to be deleted: a
+# stub exiting 0 would report "nothing wrong" when the truth is "nothing looked", and the Stop-gate,
+# CI, and every human reading a green check would believe it.
+#
+# Replace the body with the command that actually verifies this repository — the test suite, the
+# linter, the build, whatever your team already trusts — and keep the three codes:
+#
+#   exit 0   green: everything this checks passed
+#   exit 1   red: something it checks failed
+#   exit 2   could not run: a precondition was missing. Never a pass.
+
+set -uo pipefail
+
+printf 'verify: this workspace has not declared what green means yet.\\n' >&2
+printf 'verify: edit .portulan/verify/workspace.sh — see .portulan/verify/README.md\\n' >&2
+exit 2
+`;
+}
+
+/**
+ * The records rail, drafted with its own honest first state.
+ *
+ * Unlike `workspace.sh` this one is **finished** — it checks a real thing on the day it is written,
+ * because the index it holds current is written beside it. What it cannot promise is that the tool is
+ * reachable: this package is not published, so on an adopter's CI none of the three locations may
+ * answer and the recipe's expected first state there is **exit 2**. That is the honest code and it is
+ * said in `verify/README.md` as well, rather than discovered when a pipeline goes amber.
+ *
+ * The third location is the bundle this workspace was drafted from, and it is written in as a
+ * MACHINE-LOCAL convenience for the person who ran `init` — an absolute path on one machine, which
+ * git cannot carry anywhere (`.portulan/memory/a-generated-file-must-not-point-at-what-git-cannot-carry.md`).
+ * The script says so where a reader meets it, so nobody reads it as a portable location.
+ *
+ * **Both lines carrying it are marked `# portulan:bundle-fallback`, and the marker is the point.** A
+ * workspace is not fixed where it was drafted: `vendor --switch` copies these files byte for byte into
+ * another residence — so this path travels to machines it was never true on, and it does so silently,
+ * because a stale absolute path exits 2 rather than failing loudly. A comment asking the next
+ * implementer to notice is the reminder this project trades away wherever it can; a fixed token is
+ * something a rewriter can **find**.
+ *
+ * **The rewriter arrived at milestone 7 session 9**, and this sentence read "`upgrade` *will* rewrite
+ * them" until it did: `spec/migrations/0002-bundle-fallback-path.mjs`, run by `portulan upgrade`,
+ * re-derives every marked line for the bundle it is running from — wherever the line is, since the
+ * marker rather than the filename is the contract. `cli/vendor.mjs` and that step both cite the token
+ * and `init.test.mjs` asserts they do, so the marker cannot be dropped by an edit to this recipe that
+ * forgets why it was there.
+ */
+function draftIndexRecipe() {
+    const bundle = path.resolve(HERE, "..");
+    return `#!/usr/bin/env bash
+# Records rail — the generated index is compared against the series it indexes.
+#
+# \`handoffs-index.md\` is GENERATED. This recipe regenerates it in memory and compares byte for byte,
+# so an index edited by hand, or one left behind when a handoff was added, is a RED rather than a file
+# that quietly stopped being true. Nothing here writes: run the index tool yourself to repair it.
+#
+#   exit 0   green: the index matches the series
+#   exit 1   red: it does not — regenerate it
+#   exit 2   could not run: the Portulan CLI is not reachable from here. NEVER a pass.
+
+set -uo pipefail
+cd "\$(dirname "\$0")/../.." || exit 2
+
+# Three locations, in order. An explicit path wins, then an installed CLI, then the bundle this
+# workspace was drafted from — which is an absolute path on the machine that ran \`init\` and is NOT
+# portable: a clone of this repository elsewhere will not find it, and should set PORTULAN_CLI or
+# install the CLI instead.
+# Two of the three locations are node scripts, so node is their precondition and not their business.
+# An absent interpreter must exit 2 like any other missing tool: unchecked, \`node …\` dies **127**,
+# which is the shell's code for "not found" and reads to every reader downstream as a recipe that ran
+# and rendered a verdict. A recipe's own contract is the three codes, and it owes them even when what
+# is missing is the thing that would have run it.
+need_node() {
+    command -v node >/dev/null 2>&1 && return 0
+    printf 'verify: node is needed to run the index tool and is not on PATH, so the index was NOT checked.\\n' >&2
+    exit 2
+}
+
+if [ -n "\${PORTULAN_CLI:-}" ]; then
+    # An explicit location that does not hold the tool is COULD NOT RUN, not red. Without this test
+    # \`node .../index.mjs\` dies 1, and 1 is this recipe's code for "the index drifted — regenerate
+    # it": a pointer typed wrongly would send somebody to repair a file that was never wrong.
+    if [ ! -f "\${PORTULAN_CLI}/index.mjs" ]; then
+        printf 'verify: PORTULAN_CLI is set to %s, which holds no index.mjs — the index was NOT checked.\\n' "\${PORTULAN_CLI}" >&2
+        exit 2
+    fi
+    need_node
+    set -- node "\${PORTULAN_CLI}/index.mjs"
+elif command -v portulan >/dev/null 2>&1; then
+    set -- portulan index
+elif [ -f ${JSON.stringify(`${bundle}/cli/index.mjs`)} ]; then # portulan:bundle-fallback
+    need_node
+    set -- node ${JSON.stringify(`${bundle}/cli/index.mjs`)} # portulan:bundle-fallback
+else
+    printf 'verify: the Portulan CLI is not reachable, so the index was NOT checked.\\n' >&2
+    printf 'verify: looked at \$PORTULAN_CLI/index.mjs, portulan on PATH, and the bundle this\\n' >&2
+    printf 'verify: workspace was drafted from. Set PORTULAN_CLI to a checkout, or install the CLI.\\n' >&2
+    exit 2
+fi
+
+"\$@" --check .portulan
+code=\$?
+
+# 126 and 127 are the shell's two ways of saying it never ran the program — "found but not
+# executable" and "not found" — and both can arrive here even though \`command -v portulan\` answered:
+# a Node-based entry point whose interpreter is gone dies on exec, before any of this tool's own
+# codes exist. Left unmapped, either reads downstream as this recipe having RUN and rendered a
+# verdict about the index, which is the laundering \`need_node\` prevents on the branches it guards.
+# The index tool itself only ever exits 0, 1 or 2, so neither code is ambiguous here.
+#
+# Raised by Copilot, round 1 on #227, naming 127 alone; measured while pinning it, a bad interpreter
+# is **126** on this platform and the fix would have missed the case that prompted it.
+if [ "\$code" -eq 126 ] || [ "\$code" -eq 127 ]; then
+    printf 'verify: the index tool could not be executed (%s) — the index was NOT checked.\\n' "\$code" >&2
+    exit 2
+fi
+exit "\$code"
+`;
+}
+
+// ------------------------------------------------------------------------- writing
+
+/**
+ * The residence already present in a target, if any.
+ *
+ * An unreadable manifest returns `unreadable` rather than `none`, and the distinction is the whole
+ * point: reading a parse failure as "no workspace here" would make a corrupt manifest the one case
+ * where this tool overwrites — the case where it knows least and where overwriting costs most.
+ */
+export function residenceAt(target) {
+    // The path to the manifest is walked with `lstatSync` BEFORE anything is read, and that order is
+    // the whole of it. This function used `existsSync`/`readFileSync`, which follow symlinks — so a
+    // repository with a `.portulan` symlink pointing at somebody else's workspace made `init` read a
+    // manifest OUTSIDE the target and announce *"this repository already carries a `repository`
+    // workspace"*, naming a workspace that is not in this repository at all. Two failures in one
+    // sentence: an out-of-repo read, and a refusal that misdescribed what it found.
+    //
+    // It also ran ahead of the symlink-aware collision check, so the containment guarantee that check
+    // exists to give was reachable only when this function happened not to fire first. A guarantee
+    // that depends on which check runs first is not a guarantee. Found by review on the pull request,
+    // as the follow-up to the escape it is the other half of.
+    let here = target;
+    for (const segment of [".portulan", "workspace.json"]) {
+        here = path.join(here, segment);
+        let stat;
+        try {
+            stat = fs.lstatSync(here);
+        } catch (error) {
+            // ONLY `ENOENT` means "nothing here". Every other error — EACCES above all — means the
+            // question could not be answered, and answering "no residence" to a question that could
+            // not be answered is the fail-open that `a-checker-must-refuse-what-it-cannot-check.md` governs:
+            // "nothing looked" reported as "nothing wrong". A permission error here would have let
+            // `init` proceed to write into a directory it could not even stat.
+            if (error.code === "ENOENT") return { state: "none" };
+            // `kind` is carried because the two ways of being unreadable need DIFFERENT sentences.
+            // Telling somebody with a permissions problem to "repair the JSON" is a refusal that
+            // misdescribes what it found — the defect the read-side symlink fix was about, arriving
+            // one round later in the message rather than in the check.
+            return { state: "unreadable", kind: "io", why: error.message };
+        }
+        if (stat.isSymbolicLink()) return { state: "symlink", where: path.relative(target, here) };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(fs.readFileSync(here, "utf8"));
+    } catch (error) {
+        return { state: "unreadable", kind: "parse", why: error.message };
+    }
+    return { state: "present", kind: parsed?.kind ?? "unknown", name: parsed?.name ?? null };
+}
+
+/**
+ * The FIRST root that carries the pack, or null.
+ *
+ * It returned a boolean until 2026-08-13, and the root is needed now rather than merely convenient: the
+ * unasked path resolves from **either** the host's plugin cache or the workspace's own `<target>/packs`,
+ * and the closing advice was written claiming the cache for both. A sentence naming the wrong residence
+ * is worse than one naming none — it sends an adopter to uninstall a plugin that had nothing to do with
+ * it. Found by trying to write the test for the degrade, which is the half reading never catches.
+ *
+ * First-match-wins, matching `resolvePack`, so the order `expandRoots` returns is the order that decides.
+ */
+function packResolvedAt(roots, packId) {
+    return roots.find((root) => fs.existsSync(path.join(root, packId, "pack.json"))) ?? null;
+}
+
+/**
+ * The roots `init` checks a composed pack against, resolving `auto` the way the other four tools do.
+ *
+ * `auto` is kept VERBATIM in the answers file rather than expanded into the path it resolved to today:
+ * a persisted answer naming a machine-specific cache path is exactly what an answers file exists to
+ * avoid, and `auto` replays correctly on another machine while a path does not.
+ *
+ * **Two unions, and only one of them is law — do not collapse them.**
+ *
+ * - **Named ∪ discovered is still REFUSED.** The first version of this appended discovered roots
+ *   beside named ones, which made `init` the odd tool out with union semantics: the divergence
+ *   `../cli/compile.mjs`'s `namedRootsOption` records, re-committed inside the change that cites it.
+ *   Since 2026-08-12 asking for both is a refusal rather than a silent drop, which is stricter than
+ *   what that incident produced and in the same direction. _(This said "the only tool of **five**",
+ *   a figure that was seven by the time `recipe-set` and `init` joined the refusal — see
+ *   `NAMED_WITH_AUTO`, which derives nothing and has now been wrong twice. The count is dropped rather
+ *   than corrected, because nothing in the sentence needs it.)_
+ * - **Discovered ∪ derived IS law**, as of the same date, in `discover.mjs`'s `resolutionRoots`. A
+ *   later reader must not "fix" this arm by citing the incident above: that incident is about the
+ *   first pair, and this arm implements the second.
+ *
+ * The derived root here is the one the workspace **being drafted** would have — `<target>/packs` —
+ * because this check exists to predict the `doctor` run that follows the draft. Mirroring the shared
+ * rule is what stops `init` refusing a composition that `doctor` then resolves happily: a false red
+ * against the very tool it is predicting. _(That read "`doctor --pack-root auto`" until 2026-08-13,
+ * when the bare invocation started resolving the same way — which is precisely why this arm had to
+ * gain its own unasked branch below rather than staying a named-roots check.)_
+ *
+ * ## The UNASKED arm, added 2026-08-13 with the disposal, and its one hard rule
+ *
+ * `doctor` consults discovery unasked as of that date, so this check must too or it stops predicting
+ * the run it exists to predict — and the prediction is the whole reason it is here. But `init` **WRITES
+ * FILES**, and that makes one arm of the disposal non-negotiable here:
+ *
+ * **On the unasked path, a pack that does not resolve is ADVICE and never a refusal.** A refusal would
+ * mean `init` drafts a workspace on a host where the pack is installed and refuses to draft one where
+ * it is not — host-dependence deciding whether files exist, which is worse than any verdict moving.
+ * `--pack-root <dir>` and `--pack-root auto` keep their refusals: a caller who said where to look and
+ * was wrong is owed one. Nobody who said nothing is.
+ *
+ * **And the DRAFT ITSELF is byte-identical on every host.** Discovery reaches the advice and the
+ * resolvability answer, never `draft()`. That is `../docs/vision.md`'s *no auto-generated curated
+ * context* at the one tool that could break it, and `init.test.mjs` hashes the drafted files on a host
+ * with a record and on one without to keep it that way.
+ *
+ * Returns `{ roots, why, refusal, asked }`. `why` is non-null only when discovery **could not look**,
+ * which a caller must be able to tell from *looked and found nothing*; `asked` is what lets the caller
+ * choose between a refusal and a sentence for the same answer.
+ */
+function expandRoots(roots, target, env) {
+    const named = roots.filter((root) => root !== AUTO);
+    const forced = roots.includes(AUTO);
+    const derived = path.join(target, "packs");
+    const refusal = namedWithAuto(named, forced);
+    if (refusal) return { roots: [], why: null, refusal, asked: true };
+    if (named.length) return { roots: named, why: null, refusal: null, asked: true };
+    // `env` is the injection seam — see `index.mjs`'s `readScopes`.
+    const found = discoverPackRoots({ env });
+    // Could not look. Asked, that is a refusal at the call site; unasked, the derived root carries on
+    // alone and the sentence says why the other half is missing — the same degrade
+    // `../cli/discover.mjs`'s `resolutionRoots` makes, for the same reason.
+    if (!found.ok) return { roots: forced ? [] : [derived], why: found.why, refusal: null, asked: forced };
+    return { roots: [...found.roots, derived], why: null, refusal: null, asked: forced };
+}
+
+/**
+ * Every path in the draft that cannot be written without destroying or being blocked by something.
+ *
+ * The residence check above keys on the MANIFEST, which is right for "is this repository governed?"
+ * and wrong for "is it safe to write here?". A `.portulan/` holding a hand-written `gate-map.md` and
+ * no manifest is not a residence — and the first version of this tool silently replaced that file.
+ * The two questions are separate and both have to be asked.
+ *
+ * Blocked ancestors are the same check from the other side: a `verify` that is a *file* makes
+ * `verify/README.md` unwritable, and finding that out halfway through the write loop is how a run
+ * leaves a torso behind.
+ */
+export function collisions(target, files) {
+    const found = [];
+    for (const rel of files.keys()) {
+        // Walked from the target DOWN, one segment at a time, with `lstatSync` — never `statSync`,
+        // and never `existsSync`. Both of those FOLLOW symlinks, which is how the first version of
+        // this check let a `.portulan` symlink carry the whole drafted workspace out of the
+        // repository: `init` wrote nine files somewhere else entirely and reported success.
+        // Demonstrated on the pull request. `doctor` and `plugin-lint` already treat a symlink escape
+        // as significant; this is the same rule arriving at the tool that WRITES, where it matters
+        // more than at the tools that read.
+        //
+        // A symlink anywhere on the chain is a collision rather than something to resolve and permit.
+        // Resolving it would mean deciding whether the destination is "really" inside the repository,
+        // which is a containment judgement with a bad failure mode; refusing is a judgement with none.
+        const segments = rel.split("/");
+        let here = target;
+        for (let i = 0; i < segments.length; i++) {
+            here = path.join(here, segments[i]);
+            let stat;
+            try {
+                stat = fs.lstatSync(here);
+            } catch (error) {
+                if (error.code === "ENOENT") {
+                    // Absent — and nothing below an absent directory can exist either, so this path
+                    // is clear and the walk stops.
+                    break;
+                }
+                // Anything else — EACCES above all — means this path's state is UNKNOWN, and an
+                // unknown is not a clear. Declaring it clear would let the write loop start on the
+                // strength of a question nobody could answer, which is precisely the guarantee this
+                // function exists to give. Reported as a collision so the run refuses.
+                found.push({ rel, why: `\`${path.relative(target, here)}\` could not be examined (${error.code})` });
+                break;
+            }
+            const where = path.relative(target, here);
+            if (stat.isSymbolicLink()) {
+                found.push({ rel, why: `\`${where}\` is a symlink, and writing through it would leave the repository` });
+                break;
+            }
+            if (i === segments.length - 1) {
+                found.push({ rel, why: "already exists" });
+                break;
+            }
+            if (!stat.isDirectory()) {
+                found.push({ rel, why: `\`${where}\` is in the way and is not a directory` });
+                break;
+            }
+        }
+    }
+    return found;
+}
+
+// ------------------------------------------------------------------------- the interview
+
+/**
+ * Every refusal owed to a repository that is already governed, in one place.
+ *
+ * Extracted from `run` when the interview arrived, because it is now asked at two moments — before a
+ * human is made to answer five questions, and at the point in the sequence it has always occupied —
+ * and a second spelling of three refusals is three chances for them to drift apart.
+ */
+export function refuseIfGoverned(existing, spelling) {
+    if (existing.state === "symlink") {
+        // Handled here rather than left to the collision check, so the containment refusal does not
+        // depend on which check happens to run first — and so nothing outside the repository was read
+        // in order to produce it.
+        throw new InitError(
+            `\`${existing.where}\` is a symlink, and \`init\` will not follow one out of the repository — not to write ` +
+                `through it, and not to read a workspace manifest through it either. A manifest reached that way ` +
+                `describes some other directory, so any verdict about "this repository" drawn from it would be about ` +
+                `somewhere else. Replace the link with a real directory, or draft into a repository that has none.`,
+        );
+    }
+    if (existing.state === "unreadable") {
+        const at = path.join(spelling, ".portulan");
+        throw new InitError(
+            existing.kind === "io"
+                ? `could not examine \`${at}\` — ${existing.why}. Refusing rather than treating it as empty: ` +
+                  `a directory this tool cannot look into is a question it could not answer, and "nothing looked" ` +
+                  `must never be recorded as "nothing there". Fix the permissions and run this again.`
+                : `could not read the workspace manifest already at \`${path.join(at, "workspace.json")}\` — ` +
+                  `${existing.why}. Refusing to write over a manifest it cannot understand: a corrupt policy layer ` +
+                  `is the case where overwriting costs the most and this tool knows the least. Repair the JSON and ` +
+                  `run \`doctor\` on it, or — if it was never a workspace you meant to keep — move it aside and run ` +
+                  `this again.`,
+        );
+    }
+    if (existing.state === "present") {
+        const what = existing.kind === "pointer" ? "a pointer to another workspace" : `a \`${existing.kind}\` workspace`;
+        throw new InitError(
+            `this repository already carries ${what}${existing.name ? ` (\`${existing.name}\`)` : ""} — a repository is ` +
+                `governed by exactly one workspace, and \`init\` will not replace one. Moving between residences is a ` +
+                `switch, not a re-run: the workspace is materialised in the new residence, a pointer or nothing is left ` +
+                `in the old, and validation is green at both ends before the old one is retired. \`vendor\` is the ` +
+                `subcommand that does it — \`portulan vendor <the workspace> --into <where it should live> --residence ` +
+                `<in-repo|feed-side> --switch\` — and it holds that ordering so you do not have to. Doing it by hand the ` +
+                `other way round leaves a window in which this repository is governed by nothing, which looks exactly ` +
+                `like one that never adopted Portulan.`,
+        );
+    }
+}
+
+/**
+ * The default reader: a real terminal, and only where there is one at BOTH ends.
+ *
+ * `interactive` is the whole gate on the interview, and it is two questions rather than one. A pipe
+ * on stdin is a script; a redirected stdout is a log — and prompting into either produces a run that
+ * hangs waiting for an answer nobody is there to give, which on CI is a job that burns its timeout
+ * instead of printing the refusal that names the flag to pass.
+ */
+function terminal() {
+    return {
+        interactive: Boolean(process.stdin.isTTY && process.stdout.isTTY),
+        async ask(question) {
+            const readline = await import("node:readline/promises");
+            const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+            try {
+                return await rl.question(question);
+            } catch {
+                // A closed stdin rejects rather than returning. Both are "no answer is coming", and
+                // the caller's EOF handling is where that becomes a refusal.
+                return null;
+            } finally {
+                rl.close();
+            }
+        },
+        say(line) {
+            process.stdout.write(`${line}\n`);
+        },
+    };
+}
+
+/**
+ * Ask for what the flags did not supply, and fill `answers` in place.
+ *
+ * **What the gloss asked for and what this closes.** `docs/vision.md` glosses `init` as *interview +
+ * codebase scan → drafted workspace, human curates*. The scan has shipped since session 1 and the
+ * substrate — every question modelled as an answer, with one validator each — since then; the prompt
+ * loop was the open half, and this is it. Nothing here decides anything the flags path could not
+ * decide, which is the property that keeps the two paths one tool.
+ *
+ * **A question is re-asked, never fatal.** The flags path refuses a bad value because there is nobody
+ * to ask again; here there is, and aborting an interview on a typo would make the interactive path the
+ * unforgiving one. The validators are the same functions, so the two paths cannot drift into
+ * disagreeing about what a valid answer is.
+ *
+ * Every answer supplied by a flag or an answers file is skipped: being asked to confirm something you
+ * just typed on the command line reads as the tool not having listened.
+ */
+export async function interview(answers, { io, target, derivedName }) {
+    const ask = async (prompt, { fallback = null, validate = () => null } = {}) => {
+        for (;;) {
+            const raw = await io.ask(fallback === null ? `${prompt}: ` : `${prompt} [${fallback}]: `);
+            // EOF — Ctrl-D, or a stream that closed — is not an empty answer. An empty LINE accepts
+            // the offered default; end-of-input means no answer is coming, and the run stops with
+            // nothing written rather than proceeding on defaults nobody confirmed.
+            if (raw === null) throw new InitError("no answer — the interview ended before it finished, and nothing was written");
+            const value = raw.trim() === "" ? fallback : raw.trim();
+            if (value === null || value === "") {
+                io.say("  that one has no default, so it needs an answer.");
+                continue;
+            }
+            const why = validate(value);
+            if (why === null) return value;
+            io.say(`  ${why}`);
+        }
+    };
+
+    io.say("");
+    io.say(`init: drafting a workspace for ${target}`);
+    io.say("init: every answer becomes a DRAFT you curate afterwards. Nothing is written until you say so.");
+    io.say("");
+
+    if (!answers.residence) {
+        io.say("Where does this repository's workspace live?");
+        io.say("  in-repo   a full workspace in this repository");
+        io.say("  pointer   this repository is governed by a workspace that names it");
+        answers.residence = await ask("residence", {
+            validate: (v) => (RESIDENCES.has(v) ? null : `\`${v}\` is not a residence — the two are \`in-repo\` and \`pointer\`.`),
+        });
+        answers.given.add("residence");
+    }
+
+    if (answers.name === null) {
+        answers.name = await ask("workspace name", {
+            fallback: derivedName,
+            validate: (v) => (SLUG.test(v) ? null : `\`${v}\` is not a slug — lowercase letters, digits and single hyphens (${SLUG.source}).`),
+        });
+        answers.given.add("name");
+    }
+
+    if (answers.summary === null) {
+        answers.summary = await ask("one-line summary", { fallback: `The ${answers.name} workspace — drafted by \`init\`, and not yet curated.` });
+        answers.given.add("summary");
+    }
+
+    if (answers.residence === "pointer") {
+        if (answers.governedBy === null) {
+            answers.governedBy = await ask("the governing workspace's name", {
+                validate: (v) => (SLUG.test(v) ? null : `\`${v}\` is not a slug — it must be spelled exactly as that workspace's own \`name\`.`),
+            });
+            answers.given.add("governed-by");
+        }
+        if (answers.feed === null) {
+            // `none` rather than an empty line, because an empty line means *take the default* at
+            // every other prompt and a second meaning for it here is how an answer gets misread.
+            const feed = await ask("the feed it ships through", { fallback: "none" });
+            if (feed !== "none") {
+                answers.feed = feed;
+                answers.given.add("feed");
+            }
+        }
+    } else if (!answers.given.has("checkpoints") && !answers.given.has("cycle")) {
+        io.say("");
+        io.say("The supervised cycle composes a checkpoints pack, so full-lane work gets a fresh-context");
+        io.say("verdict at session-open, pre-commit and milestone-close. It is opt-out.");
+        const pack = await ask("checkpoints pack (`none` to compose nothing)", { fallback: DEFAULT_CHECKPOINTS });
+        if (pack === "none") {
+            answers.cycle = false;
+        } else {
+            answers.checkpoints = pack;
+            answers.given.add("checkpoints");
+        }
+    }
+
+    // The last question, and the one that makes every answer above reversible: everything is echoed
+    // and nothing has been written. A confirmation printed AFTER the write would be a receipt.
+    io.say("");
+    io.say("init: about to draft");
+    io.say(`  residence   ${answers.residence}`);
+    io.say(`  name        ${answers.name}`);
+    io.say(`  summary     ${answers.summary}`);
+    if (answers.residence === "pointer") {
+        io.say(`  governed by ${answers.governedBy}`);
+        io.say(`  feed        ${answers.feed ?? "(none)"}`);
+    } else {
+        io.say(`  cycle       ${answers.cycle ? answers.checkpoints : "(none — composing no packs)"}`);
+    }
+    io.say("");
+    const confirm = await io.ask("Write these files? [y/N]: ");
+    if (confirm === null || !/^y(es)?$/i.test(confirm.trim())) {
+        // Exit 2, because this file has exactly two codes and 0 means *it wrote*. A decline is not a
+        // verdict about anybody's workspace either, so 1 stays as absent as it has always been.
+        throw new InitError("nothing written — you declined at the confirmation. Run this again when the answers are right.");
+    }
+}
+
+// ------------------------------------------------------------------------- the entry point
+
+export function usage() {
+    return [
+        "portulan init — draft a workspace for a repository that has none",
+        "",
+        // Both spellings, for #155's reason: the tool is reachable through the entry point and from a
+        // checkout, and a usage line naming only one of them is wrong for whoever arrived the other way.
+        "  portulan init [options] <repository-directory>",
+        "  node cli/init.mjs [options] <repository-directory>      (from a checkout)",
+        "",
+        "  --residence <in-repo|pointer>  REQUIRED. Where this repository's workspace lives:",
+        "                                 in the repository, or in a workspace that names it.",
+        "                                 There is no default — this is the question init asks.",
+        "  --governed-by <workspace>      Required with `pointer`: the governing workspace's name.",
+        "  --feed <name>                  Optional, pointer only: the feed it ships through.",
+        "  --name <slug>                  The workspace's name. Defaults to the directory's.",
+        "  --summary <text>               One line an agent reads before loading anything else.",
+        "  --checkpoints <category/name>  The checkpoint pack to compose. Default: " + DEFAULT_CHECKPOINTS + ".",
+        "  --no-cycle                     Compose no packs. The binding is opt-out, not opt-in.",
+        "  --pack-root <dir>              Where packs are looked up, so the composed one can be",
+        "                                 confirmed to exist. Repeatable. `auto` discovers it from",
+        "                                 the host's plugin cache; `./auto` names a directory.",
+        "  --answers <file>               A JSON object of answers. Flags override its keys.",
+        "  --no-interview                 Never ask, even at a terminal: refuse instead, naming the flag.",
+        "",
+        "Exit codes: 0 it wrote · 2 it wrote nothing. There is no 1: init renders no verdict.",
+        "",
+        "At a terminal, anything you have not answered is asked, and nothing is written until you",
+        "confirm. Where stdin or stdout is not a TTY nothing is asked — the answers arrive as flags",
+        "or as `--answers`, and a missing one is refused with the flag that supplies it.",
+    ].join("\n");
+}
+
+export async function run(argv, options = {}) {
+    const say = options.say ?? ((line) => process.stdout.write(`${line}\n`));
+    const warn = options.warn ?? ((line) => process.stderr.write(`${line}\n`));
+
+    try {
+        if (SLUG === null) {
+            throw new InitError(
+                `could not read spec/workspace.schema.json, which defines what a valid name is — ${SCHEMA_ERROR?.message}. ` +
+                    `Refusing to write a manifest it cannot check.`,
+            );
+        }
+
+        const parsed = parseArgs(argv);
+        if (parsed.help) {
+            say(usage());
+            return 0;
+        }
+
+        if (!parsed.target) {
+            throw new InitError("no target directory given — `init <repository-directory>` drafts a workspace into a repository");
+        }
+
+        const target = path.resolve(parsed.target);
+        let stat;
+        try {
+            stat = fs.statSync(target);
+        } catch (error) {
+            throw new InitError(
+                `\`${parsed.target}\` does not exist — ${error.message}. \`init\` drafts a workspace INTO a repository; ` +
+                    `it does not create the repository.`,
+            );
+        }
+        if (!stat.isDirectory()) throw new InitError(`\`${parsed.target}\` is not a directory`);
+
+        const answers = resolveAnswers(parsed.flags);
+        const derivedName = slugify(path.basename(target));
+
+        // The interview, and the two conditions on it. A prompt loop cannot be run by CI, by a test or
+        // by a headless host, so **everything below happens only where somebody is at both ends** —
+        // stdin and stdout are both TTYs — and a non-interactive run is byte-for-byte what it was
+        // before this existed. `--no-interview` is the escape for a TTY that wants the old refusals.
+        //
+        // The governance question is asked FIRST and by the machine, not the human: being made to
+        // answer five questions and then told this repository already has a workspace is the shape of
+        // a tool that asks before it looks. The same refusal stands where it always did, for callers
+        // that never reach this branch — running it twice is two reads and no writes.
+        const io = options.io ?? terminal();
+        const interviewing = io.interactive && !parsed.flags.noInterview;
+        if (interviewing) {
+            refuseIfGoverned(residenceAt(target), parsed.target);
+            await interview(answers, { io, target, derivedName });
+        }
+
+        if (answers.name === null) answers.name = derivedName;
+        if (answers.name === null) {
+            throw new InitError(
+                `the directory name \`${path.basename(target)}\` yields no usable workspace name — pass \`--name <slug>\`. ` +
+                    `A workspace called something nobody chose is worse than being asked.`,
+            );
+        }
+        validateAnswers(answers);
+
+        // Before a byte: is this repository already governed? A repository is governed by exactly one
+        // workspace, so finding one here is a refusal rather than a prompt to replace it.
+        refuseIfGoverned(residenceAt(target), parsed.target);
+
+        // **`answers.packRoots.length` was the gate, and dropping it is what makes the unasked arm
+        // live.** With it, `expandRoots`' new branch was unreachable from the command line — the exact
+        // shape of dead plumbing `skills-set` and `recipe-set` were each caught with, a capability that
+        // reads as wired and is none. Every `in-repo` run that composes a pack now asks the question;
+        // what differs is whether the answer can refuse.
+        let packAdvice = null;
+        if (answers.residence === "in-repo" && answers.cycle) {
+            const expanded = expandRoots(answers.packRoots, target, options.env);
+            // Belt and braces: `validateAnswers` has already refused this pair on every path. Kept
+            // because `expandRoots` is reachable on its own and must not answer with an empty set.
+            if (expanded.refusal) throw new InitError(expanded.refusal);
+            const resolvedAt = packResolvedAt(expanded.roots, answers.checkpoints);
+            const resolved = resolvedAt !== null;
+            if (expanded.asked) {
+                if (expanded.why) {
+                    throw new InitError(
+                        `\`--pack-root auto\` could not read this host's plugin record, so whether \`${answers.checkpoints}\` ` +
+                            `is installed is unknown rather than no — ${expanded.why}. Name a root explicitly, or run with ` +
+                            `\`--no-cycle\` and compose the pack later.`,
+                    );
+                }
+                if (!resolved) {
+                    throw new InitError(
+                        `the pack \`${answers.checkpoints}\` does not resolve under ${answers.packRoots.map((r) => `\`${r}\``).join(", ")} ` +
+                            `— refusing to compose a pack that is not there. Pass a root that carries it, name a different pack ` +
+                            `with \`--checkpoints\`, or run with \`--no-cycle\` and compose it later.`,
+                    );
+                }
+            }
+            // **Unasked: an answer, never a refusal.** Carried to the closing advice rather than thrown,
+            // because a run that refuses to draft on one host and drafts on another has made the
+            // existence of files a function of the machine. The three answers are kept apart — resolved,
+            // looked-and-absent, could-not-look — because "the pack is not here" and "I could not tell"
+            // send a reader to different places.
+            // `inTree` is what keeps the advice from naming the wrong residence: the unasked path
+            // searches the host cache AND `<target>/packs`, and only the second is the repository's own.
+            packAdvice = { resolved, why: expanded.why, inTree: resolvedAt !== null && resolvedAt === path.join(target, "packs") };
+        }
+
+        const files = draft(answers, scan(target));
+
+        // The second safety question, and it is not the one above. "Is this repository governed?"
+        // keys on the manifest; "may I write here?" keys on every path the draft touches. A
+        // `.portulan/` with a hand-written file and no manifest answers no to the first and must
+        // still stop the second.
+        const clash = collisions(target, files);
+        if (clash.length) {
+            // Grouped by CAUSE, not listed per path. One symlinked `.portulan` blocks every drafted
+            // file, and naming it ten times buries the single fact the reader needs under nine
+            // copies of it — a refusal nobody finishes reading is a refusal that failed to explain.
+            const byCause = new Map();
+            for (const { rel, why } of clash) (byCause.get(why) ?? byCause.set(why, []).get(why)).push(rel);
+            const summary = [...byCause]
+                .map(([why, rels]) =>
+                    rels.length > 2
+                        ? `${why} — blocking ${rels.length} drafted files, including \`${rels[0]}\``
+                        : `${why} — ${rels.map((r) => `\`${r}\``).join(", ")}`,
+                )
+                .join("; ");
+            throw new InitError(
+                `refusing to write into \`${path.join(parsed.target, ".portulan")}\`: ${summary}. \`init\` drafts a ` +
+                    `workspace where there is none; it does not merge into one somebody has started, and it does not ` +
+                    `follow a link out of the repository. Move or remove what is in the way, or draft into a clean ` +
+                    `directory and copy across what you want to keep.`,
+            );
+        }
+
+        // Every refusal is ahead of this line, so a run that reaches here has nothing left to
+        // discover — but I/O can still fail for reasons no check can see, and the ORDER decides what
+        // a failure leaves behind. `workspace.json` is written LAST: written first, a half-completed
+        // run leaves a torso that the residence check above then reads as a governed repository,
+        // and the retry is refused with a sentence that is false. Last, the same failure leaves
+        // files and no manifest — which the collision check reports plainly and a person can clear.
+        const manifest = ".portulan/workspace.json";
+        for (const [rel, file] of [...files].filter(([rel]) => rel !== manifest).concat([[manifest, files.get(manifest)]])) {
+            const full = path.join(target, rel);
+            fs.mkdirSync(path.dirname(full), { recursive: true });
+            fs.writeFileSync(full, file.contents);
+            if (file.mode !== undefined) fs.chmodSync(full, file.mode);
+        }
+
+        say(`init: drafted ${files.size} file(s) into ${path.join(parsed.target, ".portulan")}`);
+        if (answers.residence === "pointer") {
+            say(`init: this repository is recorded as governed by \`${answers.governedBy}\`. Nothing was fetched.`);
+        } else {
+            say("init: every file is a DRAFT. Read .portulan/README.md before trusting any of it.");
+            say("init: the verify recipe exits 2 until you say what green means here — that is deliberate.");
+            if (answers.cycle) {
+                // Said at the surface rather than only in a file, because the alternative is that the
+                // adopter's very next command is `doctor`, it is RED on a pack nothing can find, and
+                // the tool that put it there said nothing about it.
+                //
+                // **It used to say that unconditionally**, in the words "nothing resolves a pack for
+                // you … name where it lives" — which stopped being true when `--pack-root auto`
+                // landed at milestone 7 session 4, and read as advice to go and find a cache path by
+                // hand immediately after `auto` had found one. Worse than merely stale: this tool has
+                // ALREADY checked resolvability above, so it knew. Found by running `init` on a real
+                // never-seen repository for D1, which is the half of this class no reading catches.
+                // **The invocation printed is the one that WORKS, and since 2026-08-13 that is usually
+                // the bare one.** `doctor` consults discovery unasked, so a host carrying the pack needs
+                // no flag at all — and printing `--pack-root auto` there would be the same defect this
+                // branch was already fixed for once, advice to type something the tool no longer needs.
+                const workspaceArg = path.join(parsed.target, ".portulan");
+                if (answers.packRoots.length) {
+                    const rootArgs = answers.packRoots.map((r) => `--pack-root ${r}`).join(" ");
+                    say(`init: this workspace composes \`${answers.checkpoints}\`, and it resolved — validate with:`);
+                    say(`init:   doctor ${rootArgs} ${workspaceArg}`);
+                } else if (packAdvice?.resolved) {
+                    const where = packAdvice.inTree ? "from `packs/` in this repository" : "from this host's plugin cache";
+                    say(`init: this workspace composes \`${answers.checkpoints}\`, and it resolved ${where} — validate with:`);
+                    say(`init:   doctor ${workspaceArg}`);
+                    // Said out loud because it is the one thing the green does not certify — and only
+                    // where it is TRUE. A pack found on this machine is not in the repository, so a CI
+                    // runner with nothing installed derives `<repo>/packs` alone and reports it
+                    // unresolved; a pack found in the tree travels with the tree and needs no warning.
+                    if (!packAdvice.inTree) {
+                        say("init: that root is this machine's, not the repository's — pin `--pack-root <dir>` in CI.");
+                    }
+                } else if (packAdvice?.why) {
+                    say(
+                        `init: this workspace composes \`${answers.checkpoints}\` and this host's plugin record ` +
+                            `could not be read, so whether it is installed is unknown rather than no:`,
+                    );
+                    say(`init:   ${packAdvice.why}`);
+                    say(`init:   doctor --pack-root <dir> ${workspaceArg}     (naming where the pack lives)`);
+                } else {
+                    say(
+                        `init: this workspace composes \`${answers.checkpoints}\` and nothing here resolves it — ` +
+                            `not the host's plugin cache, and not \`packs/\` in the repository — so validation is RED until you say where to look:`,
+                    );
+                    say(`init:   doctor --pack-root <dir> ${workspaceArg}`);
+                    say("init: or re-draft with --no-cycle and compose it once you know.");
+                }
+            }
+        }
+        return 0;
+    } catch (error) {
+        if (error instanceof InitError) {
+            warn(`init: ${error.message}`);
+            return 2;
+        }
+        warn(`init: could not run — ${error.message}`);
+        return 2;
+    }
+}
+
+// The `?? ""` is not decoration and every sibling tool here carries it: `process.argv[1]` is absent
+// when this module is imported by something that is not a script — `node -e "import('./init.mjs')"`,
+// which is how a suite or a REPL reaches it — and `pathToFileURL(undefined)` throws at module load.
+// This file argued two hundred lines up that an unreadable schema must not throw while loading,
+// because the entry point can only turn that into a stack trace; it then omitted the guard that makes
+// the same promise here. Found at the pre-commit checkpoint.
+if (import.meta.url === pathToFileURL(process.argv[1] ?? "").href) {
+    process.exitCode = await run(process.argv.slice(2));
+}