@nusoft/nuos-build-catalogue 0.12.0 → 0.14.1

package/dist/cli.js

@@ -10,8 +10,6 @@
  * Implementation note — uses minimist-free arg parsing to keep deps lean.
  * If we need richer parsing later, swap in commander/yargs.
  */
-import path from 'node:path';
-import { fileURLToPath } from 'node:url';
 // Static imports — these don't pull in NuVector / NuFlow transitively.
 // init / migrate / regenerate / summary / list / show / install-protocols all
 // work without those native deps being installed.
@@ -21,28 +19,7 @@ import { listRegister, showRecord, commandToRegister, listAcrossRegisters, } fro
 import { runRegenerate } from './regenerate/check.js';
 import { openPrompt } from './commands/prompt.js';
 import { cmdInit, cmdInstallProtocols } from './commands/init.js';
-// Dynamic imports below — index / search / write commands / create commands
-// load NuVector or NuFlow transitively. Loading them at module-parse time
-// would crash on platforms where the NuVector native binary isn't resolved
-// (e.g. fresh npx installs before @nusoft/nuvector ships its platform-specific
-// binaries as optionalDependencies). Lazy-load so the lightweight commands
-// (init, migrate, etc.) work universally; the heavyweight commands degrade
-// gracefully when their deps are missing.
-const __filename = fileURLToPath(import.meta.url);
-const PACKAGE_ROOT = path.resolve(path.dirname(__filename), '..');
-// Defaults resolve in this order: env var > flag-supplied > package-relative
-// fallback. The package-relative fallback only makes sense when running
-// against the nuos catalogue as a sibling (the original WU 110 use case);
-// for any other consumer (Sensight, NuTutor, etc.) the env vars or the
-// per-command flags are the right path. CLAUDE.md guidance for adopters:
-// set NUOS_CATALOGUE_BUILD_ROOT and NUOS_CATALOGUE_WORKFLOWS in your
-// shell profile.
-const DEFAULT_CATALOGUE_ROOT = process.env.NUOS_CATALOGUE_ROOT ?? path.resolve(PACKAGE_ROOT, '../nuos/docs');
-const DEFAULT_BUILD_ROOT = process.env.NUOS_CATALOGUE_BUILD_ROOT ?? path.resolve(PACKAGE_ROOT, '../nuos/docs/build');
-const DEFAULT_INDEX_DIR = process.env.NUOS_CATALOGUE_INDEX_DIR ?? path.resolve(PACKAGE_ROOT, '.nuos-catalogue');
-const DEFAULT_INDEX_PATH = path.join(DEFAULT_INDEX_DIR, 'index.nv');
-const DEFAULT_HASH_PATH = path.join(DEFAULT_INDEX_DIR, 'hashes.json');
-const DEFAULT_WORKFLOWS_PATH = process.env.NUOS_CATALOGUE_WORKFLOWS ?? path.join(DEFAULT_INDEX_DIR, 'workflows.json');
+import { resolveBuildRoot, resolveCatalogueRoot, resolveWorkflowsPath, resolveIndexPath, resolveHashPath, gitignoreCatalogueNote, } from './path-resolution.js';
 function parseArgs(argv) {
     const [command, ...rest] = argv;
     const positional = [];
@@ -64,9 +41,10 @@ function parseArgs(argv) {
     return { command: command ?? 'help', positional, flags };
 }
 async function cmdIndex(flags) {
-    const catalogueRoot = String(flags['catalogue'] ?? DEFAULT_CATALOGUE_ROOT);
-    const indexPath = String(flags['index'] ?? DEFAULT_INDEX_PATH);
-    const hashPath = String(flags['hash-file'] ?? DEFAULT_HASH_PATH);
+    const catalogueRoot = resolveCatalogueRoot(flags['catalogue']);
+    const buildRoot = resolveBuildRoot(flags['build-root']);
+    const indexPath = resolveIndexPath(buildRoot, flags['index']);
+    const hashPath = resolveHashPath(buildRoot, flags['hash-file']);
     const { selectEmbedderFromEnv } = await import('./embedder/select.js');
     const { openStore } = await import('./store/open.js');
     const { runIndex } = await import('./indexer/upsert.js');
@@ -99,7 +77,8 @@ async function cmdSearch(positional, flags) {
         console.error('Usage: nuos-catalogue search "<query>" [--kind=...] [--status=...] [--limit=N] [--json]');
         process.exit(2);
     }
-    const indexPath = String(flags['index'] ?? DEFAULT_INDEX_PATH);
+    const buildRoot = resolveBuildRoot(flags['build-root']);
+    const indexPath = resolveIndexPath(buildRoot, flags['index']);
     const { selectEmbedderFromEnv } = await import('./embedder/select.js');
     const { openStore } = await import('./store/open.js');
     const { runSearch } = await import('./search/query.js');
@@ -132,8 +111,8 @@ async function cmdSearch(positional, flags) {
     }
 }
 async function cmdMigrate(flags) {
-    const buildRoot = String(flags['build-root'] ?? DEFAULT_BUILD_ROOT);
-    const workflowsPath = String(flags['workflows'] ?? DEFAULT_WORKFLOWS_PATH);
+    const buildRoot = resolveBuildRoot(flags['build-root']);
+    const workflowsPath = resolveWorkflowsPath(buildRoot, flags['workflows']);
     const dryRun = Boolean(flags['dry-run']);
     console.log(`migrating ${buildRoot}`);
     console.log(`  workflows file: ${workflowsPath}`);
@@ -161,6 +140,17 @@ async function cmdMigrate(flags) {
         console.log('     Resolve by renaming the conflicting files (e.g. give them distinct number prefixes) then re-run migrate.');
     }
     console.log(`(${(report.durationMs / 1000).toFixed(2)}s)`);
+    // Surface a gitignore hint if the project's .gitignore is missing the
+    // `.nuos-catalogue/` entry. Silent if .gitignore is absent or correct.
+    // (We do this after the success block so the report is the first thing
+    // the operator reads; the note follows.)
+    if (!dryRun) {
+        const note = gitignoreCatalogueNote(buildRoot);
+        if (note) {
+            console.log('');
+            console.log(note);
+        }
+    }
 }
 async function cmdRegisterDispatch(command, positional, flags) {
     const register = commandToRegister(command);
@@ -169,8 +159,8 @@ async function cmdRegisterDispatch(command, positional, flags) {
         process.exit(2);
     }
     const action = positional[0];
-    const workflowsPath = String(flags['workflows'] ?? DEFAULT_WORKFLOWS_PATH);
-    const buildRoot = String(flags['build-root'] ?? DEFAULT_BUILD_ROOT);
+    const buildRoot = resolveBuildRoot(flags['build-root']);
+    const workflowsPath = resolveWorkflowsPath(buildRoot, flags['workflows']);
     const store = await openWorkflowStore(workflowsPath);
     const asJson = Boolean(flags['json']);
     switch (action) {
@@ -300,8 +290,8 @@ async function cmdRegisterDispatch(command, positional, flags) {
     }
 }
 async function cmdRegenerate(flags) {
-    const buildRoot = String(flags['build-root'] ?? DEFAULT_BUILD_ROOT);
-    const workflowsPath = String(flags['workflows'] ?? DEFAULT_WORKFLOWS_PATH);
+    const buildRoot = resolveBuildRoot(flags['build-root']);
+    const workflowsPath = resolveWorkflowsPath(buildRoot, flags['workflows']);
     const write = Boolean(flags['write']);
     const showDiffs = Boolean(flags['diff']);
     const registerFilter = flags['register'] ? String(flags['register']) : undefined;
@@ -353,7 +343,8 @@ async function cmdRegenerate(flags) {
     process.exit(report.differs > 0 || report.missing > 0 ? 1 : 0);
 }
 async function cmdSummary(flags) {
-    const workflowsPath = String(flags['workflows'] ?? DEFAULT_WORKFLOWS_PATH);
+    const buildRoot = resolveBuildRoot(flags['build-root']);
+    const workflowsPath = resolveWorkflowsPath(buildRoot, flags['workflows']);
     const store = await openWorkflowStore(workflowsPath);
     const { byRegister, total } = listAcrossRegisters(store);
     if (Boolean(flags['json'])) {
@@ -371,7 +362,7 @@ function cmdHelp() {
     console.log(`nuos-catalogue — NuOS build-catalogue tooling (WU 110, WU 111)
 
 Usage:
-  nuos-catalogue init     [--name=X --tagline="Y" --domain=Z --role=consumer --yes]
+  nuos-catalogue init     [--name=X --tagline="Y" --role=consumer --interactive]
                           (interactive bootstrap of docs/build/, methodfile.json, .claude/commands/<protocols>, CLAUDE.md, .gitignore overrides; refuses if docs/build/ already exists)
   nuos-catalogue install-protocols
                           (refresh .claude/commands/<protocols> from this CLI's bundled canonical bodies)
@@ -387,6 +378,7 @@ Usage:
   nuos-catalogue wu        create    (interactive — multi-step prompts)
   nuos-catalogue wu        advance   <handle> --to=<status> [--reason="..."]
   nuos-catalogue wu        tick      <handle> --index=N --evidence="..."
+                          (--index is 1-based: --index=1 ticks the first AC)
   nuos-catalogue decision  list      [--status=<s>] [--limit=N] [--json]
   nuos-catalogue decision  show      <handle> [--json]
   nuos-catalogue decision  create    (interactive)
@@ -399,17 +391,25 @@ Usage:
   nuos-catalogue persona   show      <handle> [--json]
   nuos-catalogue persona   create    (interactive — seven dimensions + acid-test per D046)
 
+  nuos-catalogue plan      status    show planning progress across the 5-phase arc
+
   nuos-catalogue help
 
 Handles accepted: canonical (wu-111, D046, Q009, P001) or friendly
 (WU 111, 111, D45, Q9). Unambiguous integers ("111" under "wu show")
 are normalised to the canonical form.
 
+Default locations: when --build-root / --workflows / --catalogue are
+omitted and the matching env vars are unset, the CLI walks up from the
+current working directory looking for a docs/build/ directory (the
+same way git finds its repo root). Invoke from anywhere inside the
+project. The workflow store lives at <project-root>/.nuos-catalogue/.
+
 Environment:
-  NUOS_CATALOGUE_BUILD_ROOT   default for --build-root (the catalogue's docs/build/ dir)
-  NUOS_CATALOGUE_WORKFLOWS    default for --workflows (the JSON workflow store path)
-  NUOS_CATALOGUE_ROOT         default for --catalogue (semantic-search index source)
-  NUOS_CATALOGUE_INDEX_DIR    default parent dir for index.nv + workflows.json
+  NUOS_CATALOGUE_BUILD_ROOT   override for --build-root (the catalogue's docs/build/ dir)
+  NUOS_CATALOGUE_WORKFLOWS    override for --workflows (the JSON workflow store path)
+  NUOS_CATALOGUE_ROOT         override for --catalogue (semantic-search index source)
+  NUOS_CATALOGUE_INDEX_DIR    override for parent dir of index.nv + workflows.json
   NUOS_CATALOGUE_EMBEDDER     vertex | openai | stub  (default: vertex)
   GOOGLE_CLOUD_PROJECT        required for vertex
   GOOGLE_CLOUD_LOCATION       optional (default: us-central1)
@@ -434,7 +434,7 @@ async function main() {
                     tagline: args.flags['tagline'] ? String(args.flags['tagline']) : undefined,
                     domain: args.flags['domain'] ? String(args.flags['domain']) : undefined,
                     role: args.flags['role'] ? String(args.flags['role']) : undefined,
-                    nonInteractive: Boolean(args.flags['yes']),
+                    interactive: Boolean(args.flags['interactive']),
                 });
                 if (result.output)
                     console.log(result.output);
@@ -473,6 +473,19 @@ async function main() {
         case 'persona':
             await cmdRegisterDispatch(args.command, args.positional, args.flags);
             break;
+        case 'plan': {
+            const sub = args.positional[0];
+            if (sub === 'status') {
+                const { cmdPlanStatus } = await import('./commands/plan.js');
+                const code = await cmdPlanStatus({ cwd: process.cwd() });
+                if (code !== 0)
+                    process.exit(code);
+                break;
+            }
+            console.error(`unknown plan subcommand: ${sub ?? '(none)'}`);
+            console.error('available: plan status');
+            process.exit(1);
+        }
         case 'help':
         case '--help':
         case '-h':

package/dist/commands/init.d.ts

@@ -30,12 +30,22 @@ import type { Prompt } from './prompt.js';
 export interface InitOptions {
     /** Target project root (default: cwd). */
     cwd?: string;
-    /** Pre-supplied values; if any are missing, the prompt fills them in. */
+    /** Pre-supplied values; if omitted, sensible defaults are used. */
     name?: string;
     tagline?: string;
     domain?: string;
     role?: string;
-    /** When true, runs all steps without prompts (uses defaults / supplied values). */
+    /**
+     * Opt into the prompt flow (project name, tagline, role, confirm).
+     * Default is non-interactive: scaffolds immediately with sensible
+     * defaults. The real configuration happens during Phase A of the
+     * planning arc, not at init time.
+     */
+    interactive?: boolean;
+    /**
+     * @deprecated kept only for backward compat with the older `--yes` flag;
+     * has no effect — init is always non-interactive unless `interactive` is set.
+     */
     nonInteractive?: boolean;
 }
 export interface InitResult {

package/dist/commands/init.js

@@ -30,7 +30,6 @@ import { mkdir, readFile, writeFile, readdir, access } from 'node:fs/promises';
 import { existsSync, constants } from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { askUntilValid, validate } from './prompt.js';
 const __filename = fileURLToPath(import.meta.url);
 const PACKAGE_ROOT = path.resolve(path.dirname(__filename), '..', '..');
 const TEMPLATES_ROOT = path.resolve(PACKAGE_ROOT, 'templates');
@@ -39,6 +38,7 @@ const PROTOCOL_FILES = [
     'end-of-session.md',
     'wu-new.md',
     'persona-new.md',
+    'plan-orientation.md',
 ];
 /**
  * One-line descriptions used in the frontmatter of installed protocol
@@ -46,10 +46,11 @@ const PROTOCOL_FILES = [
  * read as an imperative summary.
  */
 const PROTOCOL_DESCRIPTIONS = {
-    'start-of-session': 'Read STATE, last session log, active WU; surface next action',
-    'end-of-session': 'Write session log, update STATE + indices, move ✅ WUs to done/, commit',
-    'wu-new': 'Create a new work unit with the six-field outcome shape (per D046)',
-    'persona-new': 'Create a new P-NNN persona with the seven dimensions and acid-test (per D046)',
+    'start-of-session': 'Read where the project is and propose the next concrete action',
+    'end-of-session': 'Capture what happened, update state, write session log, commit',
+    'wu-new': 'File a new work unit through a guided plain-English conversation',
+    'persona-new': 'File a new persona by walking the seven dimensions conversationally',
+    'plan-orientation': 'Phase A of planning — project description, personas, the horizon map',
 };
 const TOOLS = {
     claude: {
@@ -93,44 +94,41 @@ export async function cmdInit(prompt, options = {}) {
         };
     }
     // Gather inputs.
+    //
+    // Init is **zero-prompt by default**. The user wants `npx ... init` to
+    // just work — sensible defaults fill in everything, the scaffold goes
+    // down, and the real planning happens in /start-of-session (Phase A of
+    // the planning arc), where the AI walks the user through the project
+    // description, personas, and the horizon map IN CONTEXT.
+    //
+    // Old behavior (4 prompts: name, tagline, domain, role) wasn't load-
+    // bearing — tagline gets produced during Phase A; domain is a relic;
+    // role is a planning-time annotation rarely used downstream. Users who
+    // want the prompts back can pass --interactive.
     const projectDefault = path.basename(cwd);
-    let name = options.name;
-    let tagline = options.tagline;
-    let domain = options.domain;
-    let role = options.role;
-    if (!options.nonInteractive) {
-        prompt.print('Initialising a NuOS Build Method catalogue.');
+    let name = options.name ?? projectDefault;
+    let tagline = options.tagline ?? '';
+    let domain = options.domain ?? '';
+    let role = options.role ?? 'consumer';
+    if (options.interactive) {
+        prompt.print('Setting up the catalogue.');
         prompt.print('');
-        if (!name) {
-            name = await askUntilValid(prompt, `Project name [${projectDefault}]: `, (v) => (v.trim().length === 0 ? null : null) // empty allowed; default applied below
-            );
-            if (!name.trim())
-                name = projectDefault;
+        if (!options.name) {
+            const answer = (await prompt.ask(`Project name [${projectDefault}]: `)).trim();
+            if (answer)
+                name = answer;
         }
-        if (!tagline) {
-            tagline = await askUntilValid(prompt, 'One-sentence tagline (what this project is): ', (v) => validate.nonEmpty(v, 'tagline'));
+        if (!options.tagline) {
+            tagline = (await prompt.ask('One-line description (or empty — Phase A will fill it in): ')).trim();
         }
-        if (!domain) {
-            domain = (await prompt.ask('Domain (e.g. example.com; empty for none): ')).trim() || 'n/a';
-        }
-        if (!role) {
+        if (!options.role) {
             role = await prompt.askChoice('Project role?', ['consumer', 'standalone', 'harness']);
         }
-        const confirm = await prompt.confirm(`About to create docs/build/, methodfile.json, .claude/commands/<protocols>, append to CLAUDE.md, update .gitignore, and run first migrate. Proceed?`, true);
+        const confirm = await prompt.confirm(`Create docs/build/, install protocols + hooks, set up the catalogue. Proceed?`, true);
         if (!confirm) {
-            return { output: 'init cancelled by operator.', exitCode: 1 };
+            return { output: 'init cancelled.', exitCode: 1 };
         }
     }
-    else {
-        if (!name)
-            name = projectDefault;
-        if (!tagline)
-            tagline = '';
-        if (!domain)
-            domain = 'n/a';
-        if (!role)
-            role = 'consumer';
-    }
     const subs = {
         '{{PROJECT_NAME}}': name,
         '{{PROJECT_TAGLINE}}': tagline,
@@ -138,10 +136,15 @@ export async function cmdInit(prompt, options = {}) {
         '{{PROJECT_ROLE}}': role,
         '{{TODAY}}': today,
     };
+    // Per-step "· created X" messages are kept as an in-memory audit trail
+    // but NOT printed by default. The end-user-facing output is just a
+    // single "Done. Type /start-of-session" at the close. Pass `interactive`
+    // to see the per-step lines (useful for debugging).
     const log = [];
     const log_line = (msg) => {
         log.push(msg);
-        prompt.print(msg);
+        if (options.interactive)
+            prompt.print(msg);
     };
     // Step 1: docs/build/ scaffold from starter-kit
     log_line('  · creating docs/build/ from bundled starter-kit');
@@ -165,6 +168,12 @@ export async function cmdInit(prompt, options = {}) {
             log_line(`  · ${existed ? 'overwrote' : 'installed'} ${tool.destPath(slug)} (${tool.label})`);
         }
     }
+    // Step 3b: install the git hooks (pre-commit enforcement + post-commit
+    // auto-reindex). Two source files land in scripts/hooks/ so the consumer
+    // has the version-controlled source-of-truth; copies are pushed into
+    // .git/hooks/ so they fire immediately without the user re-running an
+    // installer.
+    await installHooks(cwd, log_line);
     // Step 4: CLAUDE.md
     const claudeMdPath = path.join(cwd, 'CLAUDE.md');
     const catalogueSection = renderCatalogueSection(name);
@@ -188,16 +197,10 @@ export async function cmdInit(prompt, options = {}) {
     const gitignorePath = path.join(cwd, '.gitignore');
     await ensureGitignoreEntries(gitignorePath, log_line);
     prompt.print('');
-    prompt.print(`✅ Catalogue initialised at ${path.join(cwd, 'docs/build')}`);
+    prompt.print('✅ Done.');
     prompt.print('');
-    prompt.print('Next steps:');
-    prompt.print('  1. Set env vars in your shell profile so the CLI knows where this catalogue lives:');
-    prompt.print(`       export NUOS_CATALOGUE_BUILD_ROOT="${path.join(cwd, 'docs/build')}"`);
-    prompt.print(`       export NUOS_CATALOGUE_WORKFLOWS="${path.join(cwd, '.nuos-catalogue/workflows.json')}"`);
-    prompt.print('  2. Edit docs/build/STATE.md to describe the actual current state of this project.');
-    prompt.print('  3. File the first WU: `nuos-catalogue wu create`');
+    prompt.print('Now type  /start-of-session  into Claude Code to begin.');
     prompt.print('');
-    prompt.print('To refresh protocols only later (without re-running init): `nuos-catalogue install-protocols`');
     return { output: '', exitCode: 0 };
 }
 export async function cmdInstallProtocols(prompt, options = {}) {
@@ -230,9 +233,76 @@ export async function cmdInstallProtocols(prompt, options = {}) {
     prompt.print(`Refreshing protocols (Claude Code / OpenCode / Codex CLI):`);
     for (const l of lines)
         prompt.print(l);
+    // Refresh hooks too — same idempotent shape.
+    prompt.print('');
+    prompt.print(`Refreshing git hooks (pre-commit enforcement, post-commit auto-reindex):`);
+    await installHooks(cwd, (msg) => prompt.print(msg));
     return { output: '', exitCode: 0 };
 }
 // ---------------------------------------------------------------------------
+// installHooks — copy bundled hook sources into the consumer + activate them
+// ---------------------------------------------------------------------------
+/**
+ * Bundled hooks ship in templates/hooks/. Two source files (pre-commit,
+ * post-commit) land in the consumer's scripts/hooks/ so the maintainer
+ * has the version-controlled source. Copies also land in .git/hooks/ so
+ * they fire immediately. The bash install-hooks.sh script also lands in
+ * scripts/ so re-running it after a fresh clone reconstitutes .git/hooks/.
+ *
+ * Idempotent: byte-identical sources are skipped silently. Permissions
+ * are set executable on every install so a chmod isn't required.
+ */
+async function installHooks(cwd, log_line) {
+    const hooksTemplatesRoot = path.join(TEMPLATES_ROOT, 'hooks');
+    if (!existsSync(hooksTemplatesRoot)) {
+        log_line('  · (hooks bundle not present in this CLI install — skipping)');
+        return;
+    }
+    // 1) Source-of-truth files in <cwd>/scripts/
+    const scriptsDir = path.join(cwd, 'scripts');
+    const scriptsHooksDir = path.join(scriptsDir, 'hooks');
+    await mkdir(scriptsHooksDir, { recursive: true });
+    const hookFiles = ['pre-commit', 'post-commit'];
+    for (const name of hookFiles) {
+        const src = path.join(hooksTemplatesRoot, name);
+        const dest = path.join(scriptsHooksDir, name);
+        await writeHookFile(src, dest, log_line, `  · `, `scripts/hooks/${name}`);
+    }
+    // install-hooks.sh — convenience bash installer; sits next to scripts/hooks/
+    const installerSrc = path.join(hooksTemplatesRoot, 'install-hooks.sh');
+    const installerDest = path.join(scriptsDir, 'install-hooks.sh');
+    await writeHookFile(installerSrc, installerDest, log_line, `  · `, `scripts/install-hooks.sh`);
+    // 2) Active copies in <cwd>/.git/hooks/ — only if .git/ exists. Some
+    // tests run init in a non-git directory; that's fine, skip the active
+    // install and let the user run install-hooks.sh later.
+    const gitHooksDir = path.join(cwd, '.git', 'hooks');
+    if (!existsSync(path.join(cwd, '.git'))) {
+        log_line(`  · (no .git/ found at ${cwd} — skipping active hook install; run scripts/install-hooks.sh after \`git init\`)`);
+        return;
+    }
+    await mkdir(gitHooksDir, { recursive: true });
+    for (const name of hookFiles) {
+        const src = path.join(hooksTemplatesRoot, name);
+        const dest = path.join(gitHooksDir, name);
+        await writeHookFile(src, dest, log_line, `  · `, `.git/hooks/${name}`);
+    }
+}
+async function writeHookFile(src, dest, log_line, prefix, label) {
+    const srcContent = await readFile(src, 'utf8');
+    let action = 'created';
+    if (existsSync(dest)) {
+        const destContent = await readFile(dest, 'utf8');
+        action = destContent === srcContent ? 'unchanged' : 'updated';
+    }
+    if (action !== 'unchanged') {
+        await writeFile(dest, srcContent, 'utf8');
+    }
+    // chmod +x — required for git to actually run them
+    const { chmod } = await import('node:fs/promises');
+    await chmod(dest, 0o755);
+    log_line(`${prefix}${action} ${label}`);
+}
+// ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
 function substitute(content, subs) {
@@ -291,48 +361,40 @@ async function ensureGitignoreEntries(gitignorePath, log_line) {
 function renderCatalogueSection(projectName) {
     return `## Build catalogue (NuOS Build Method)
 
-This repo runs **the NuOS Build Method**. The catalogue lives at [docs/build/](docs/build/) and tracks work units, decisions, open questions, personas, sessions, and risks.
+This project uses the **NuOS Build Method catalogue** at [docs/build/](docs/build/). It is the project's memory — who it's for, what's been built, what's been decided, what's still unknown, what's at risk. Eleven registers in plain Markdown. The catalogue stays current through two protocols that bookend every session.
 
-### At the start of every session
+**Start here** if you're new:
 
-Run \`/start-of-session\` (or follow [docs/build/START-OF-SESSION.md](docs/build/START-OF-SESSION.md)).
+- [docs/build/WELCOME.md](docs/build/WELCOME.md) — what this catalogue is, in 5 minutes
+- [docs/build/GLOSSARY.md](docs/build/GLOSSARY.md) — every term defined once
 
-### At the end of every session
+### Three commands
 
-Run \`/end-of-session\`. **Without it, work is lost.**
+That's it. Everything else is automatic.
 
-### Daily use via the CLI
-
-Set these env vars in your shell profile so commands work without flags:
-
-\`\`\`bash
-export NUOS_CATALOGUE_BUILD_ROOT="$(pwd)/docs/build"
-export NUOS_CATALOGUE_WORKFLOWS="$(pwd)/.nuos-catalogue/workflows.json"
+\`\`\`text
+/start-of-session       — every time you begin working
+/end-of-session         — every time you stop
 \`\`\`
 
-Then:
+(\`init\` runs once at the start; you've already done that.)
 
-\`\`\`bash
-nuos-catalogue wu create                          # interactive — file a new WU
-nuos-catalogue wu list                            # what's in flight
-nuos-catalogue wu advance <handle> --to=in_progress
-nuos-catalogue wu tick <handle> --index=N --evidence="commit abc123"
-nuos-catalogue decision create
-nuos-catalogue question create
-nuos-catalogue regenerate                         # check store-vs-disk drift
-nuos-catalogue summary                            # totals by register
-\`\`\`
+If this is a brand-new project, \`/start-of-session\` will detect the empty catalogue and walk you through 5 short planning phases (Orientation, Architecture, UI/UX + Design System, Maps, Initial Work Units) before any building starts. Each phase is its own session. Take them in order; pause whenever you need to.
 
-To refresh the protocol bodies later (after a CLI upgrade):
+### The principle that makes it work
 
-\`\`\`bash
-nuos-catalogue install-protocols
-\`\`\`
+**Project memory never drifts from project reality.** Every decision made in conversation gets saved before the session ends. Every change to an existing piece flows through a protocol. The pre-commit hook blocks silent edits to accepted decisions; the post-commit hook auto-refreshes the search index after every commit. What the AI finds when you ask "what did we decide about X?" is always current.
 
 ### What never to do
 
-- Never make architectural decisions without recording them in \`docs/build/decisions/\`
-- Never start work outside the active work unit without recording why
-- Never skip end-of-session
-- Never modify a committed \`accepted\` decision file (use \`decision supersede\` instead)`;
+- **Never close a session without \`/end-of-session\`.** Work that isn't written down is work that's lost.
+- **Never edit an accepted decision file.** If something changes, file a new decision that supersedes the old one. The pre-commit hook will block silent edits.
+- **Never make an architectural decision in conversation without filing it.** If you and the AI agree on "let's go with X", file it as a decision *before moving on*. Drift is the failure mode that makes the catalogue worthless.
+
+### If you need more
+
+- All registers and their templates live under [docs/build/](docs/build/)
+- The full CLI surface (creating work units / decisions / personas / questions / contracts / surfaces from the command line) is documented at [docs/build/WELCOME.md](docs/build/WELCOME.md)
+- To refresh protocols and hooks later (after a CLI upgrade): \`npx @nusoft/nuos-build-catalogue install-protocols\`
+`;
 }

package/dist/commands/plan.d.ts

@@ -0,0 +1,12 @@
+/**
+ * `nuos-catalogue plan status` — read methodfile.json's planning tracker
+ * and print a 5-line summary of where the project is in the planning arc.
+ *
+ * Read-only; never mutates state. The actual phase advancement is done by
+ * the relevant plan-* protocol when it finishes its work and updates the
+ * methodfile + STATE.md as part of its end-of-session.
+ */
+export interface PlanStatusOptions {
+    cwd?: string;
+}
+export declare function cmdPlanStatus(options?: PlanStatusOptions): Promise<number>;

package/dist/commands/plan.js

@@ -0,0 +1,83 @@
+/**
+ * `nuos-catalogue plan status` — read methodfile.json's planning tracker
+ * and print a 5-line summary of where the project is in the planning arc.
+ *
+ * Read-only; never mutates state. The actual phase advancement is done by
+ * the relevant plan-* protocol when it finishes its work and updates the
+ * methodfile + STATE.md as part of its end-of-session.
+ */
+import { readFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+const PHASES = [
+    { key: 'phaseA_orientation', label: 'A. Orientation' },
+    { key: 'phaseB_architecture', label: 'B. Architecture & Contracts' },
+    { key: 'phaseC_uiUxDesignSystem', label: 'C. UI/UX + Design System' },
+    { key: 'phaseD_maps', label: 'D. Maps' },
+    { key: 'phaseE_initialWorkUnits', label: 'E. Initial Work Units' },
+];
+function statusIcon(s) {
+    switch (s) {
+        case 'complete':
+            return '✅';
+        case 'in_progress':
+            return '🟡';
+        default:
+            return '🔵';
+    }
+}
+function statusLabel(s) {
+    switch (s) {
+        case 'complete':
+            return 'complete';
+        case 'in_progress':
+            return 'in progress';
+        default:
+            return 'not started';
+    }
+}
+export async function cmdPlanStatus(options = {}) {
+    const cwd = options.cwd ?? process.cwd();
+    const methodfilePath = path.join(cwd, 'methodfile.json');
+    if (!existsSync(methodfilePath)) {
+        console.error(`No methodfile.json found at ${cwd}.`);
+        console.error('Run `nuos-catalogue init` first to set up a catalogue.');
+        return 1;
+    }
+    let mf;
+    try {
+        mf = JSON.parse(await readFile(methodfilePath, 'utf8'));
+    }
+    catch (err) {
+        console.error(`Couldn't read methodfile.json: ${err.message}`);
+        return 1;
+    }
+    const planning = mf.planning ?? {};
+    console.log('');
+    console.log('Planning progress for this project:');
+    console.log('');
+    for (const { key, label } of PHASES) {
+        const status = planning[key];
+        console.log(`  ${statusIcon(status)} ${label.padEnd(36)} ${statusLabel(status)}`);
+    }
+    console.log('');
+    const firstNotStarted = PHASES.find((p) => planning[p.key] !== 'complete');
+    if (!firstNotStarted) {
+        console.log('All five phases complete. The project is ready to build —');
+        console.log('use /start-of-session and /end-of-session for normal work from here.');
+        console.log('');
+        return 0;
+    }
+    if (planning[firstNotStarted.key] === 'in_progress') {
+        console.log(`Currently in: ${firstNotStarted.label} (in progress)`);
+        console.log('Resume by running /start-of-session — the AI reads the last session log');
+        console.log('and picks up at the right step.');
+    }
+    else {
+        console.log(`Next phase: ${firstNotStarted.label}`);
+        console.log('Begin by running /start-of-session — the AI detects the empty phase');
+        console.log('and routes to the right planning protocol.');
+    }
+    console.log('');
+    return 0;
+}