@geraldmaron/construct 1.0.0 → 1.0.2

package/lib/init-docs.mjs

@@ -1,191 +1,328 @@
 #!/usr/bin/env node
 /**
- * lib/init-docs.mjs — AI-powered doc structure scaffolding
+ * lib/init-docs.mjs — stand up a documentation system for a project.
  *
- * Uses a fast model (Haiku) to analyze the project, ask 2-3 clarifying
- * questions, then generate a tailored documentation structure.
- * Falls back to a minimal static scaffold if no API key is available.
+ * Intentionally separate from `construct init`. Creates the docs surface only:
+ * docs/README.md plus selected lane directories such as docs/adr/, docs/intake/,
+ * docs/memos/, docs/notes/, docs/prds/, and docs/rfcs/ with starter templates
+ * copied into per-lane templates/ directories from Construct's template library.
  *
  * Usage:
- *   node lib/init-docs.mjs [target-path] [--yes]
- *   construct init-docs [path] [--yes]
+ *   node lib/init-docs.mjs [target-path] [--yes] [--docs=prds,rfcs,adrs] [--with-architecture] [--suggest-org] [--organize]
+ *   construct init-docs [path] [--yes] [--docs=prds,rfcs,adrs] [--with-architecture] [--suggest-org] [--organize]
+ *
+ * Flags:
+ *   --yes          Skip interactive prompts and use defaults.
+ *   --docs         Comma-separated list of lanes to initialize (default: adrs,intake,memos,notes,prds).
+ *   --with-architecture  Also create docs/architecture.md.
+ *   --suggest-org  Scan existing .md files and suggest where they might belong (no changes made).
+ *   --organize     Actually move files to suggested locations (implies --suggest-org, requires --yes to avoid prompts).
  */
 
 import fs from "node:fs";
 import path from "node:path";
-import readline from "node:readline";
-import { execSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
-import { defaultWorkflow } from "./workflow-state.mjs";
-import { readOpenRouterApiKeyFromOpenCodeConfig } from "./model-router.mjs";
+
+import { suggestDocsLaneForFile } from './docs-routing.mjs';
+import { stampFrontmatter } from "./doc-stamp.mjs";
+import readline from "node:readline";
 
 const __dirname = fileURLToPath(new URL(".", import.meta.url));
 const ROOT_DIR = path.join(__dirname, "..");
+const TEMPLATE_DIR = path.join(ROOT_DIR, "templates", "docs");
 
 const args = process.argv.slice(2);
 const skipInteractive = args.includes("--yes") || !process.stdin.isTTY;
-const targetArg = args.find((a) => !a.startsWith("--"));
+const docsArg = args.find((arg) => arg.startsWith("--docs="));
+const extrasArg = args.find((arg) => arg.startsWith("--extras="));
+const withArchitectureFlag = args.includes("--with-architecture");
+const suggestOrg = args.includes("--suggest-org");
+const organize = args.includes("--organize");
+const targetArg = args.find((arg) => !arg.startsWith("--"));
 const target = path.resolve(targetArg ?? process.cwd());
 
-const FAST_MODEL = "claude-haiku-4-5-20251001";
+const docsRootArg = args.find((arg) => arg.startsWith('--docs-root='));
+const docsRootRelative = docsRootArg ? docsRootArg.split('=')[1] : 'docs';
+const docsDir = path.join(target, docsRootRelative);
 
-// ─── .env loader ──────────────────────────────────────────────────────────────
+const created = [];
+const skipped = [];
 
-function loadEnv(envPath) {
-  if (!fs.existsSync(envPath)) return;
-  for (const line of fs.readFileSync(envPath, "utf8").split("\n")) {
-    const trimmed = line.trim();
-    if (!trimmed || trimmed.startsWith("#")) continue;
-    const eq = trimmed.indexOf("=");
-    if (eq === -1) continue;
-    const key = trimmed.slice(0, eq).trim();
-    const val = trimmed.slice(eq + 1).trim().replace(/^["']|["']$/g, "");
-    if (!process.env[key]) process.env[key] = val;
+const DOC_LANES = {
+  adrs: {
+    title: "ADRs",
+    dir: "adr",
+    description: "Architecture decision records for decisions that have already been made.",
+    templates: ["adr.md"],
+  },
+  briefs: {
+    title: "Briefs",
+    dir: "briefs",
+    description: "Research, evidence, signal, and one-pager style documents.",
+    templates: [
+      "research-brief.md",
+      "evidence-brief.md",
+      "signal-brief.md",
+      "one-pager.md",
+      "customer-profile.md",
+      "product-intelligence-report.md",
+      "backlog-proposal.md",
+    ],
+  },
+  changelogs: {
+    title: "Changelogs",
+    dir: "changelogs",
+    description: "User-facing release notes and version history entries.",
+    templates: ["changelog-entry.md"],
+  },
+  intake: {
+    title: "Intake",
+    dir: "intake",
+    description: "Intake batch records that explain what arrived, why it matters, and how it should be ingested.",
+    templates: ["__intake-template__"],
+  },
+  memos: {
+    title: "Memos",
+    dir: "memos",
+    description: "Decision memos and internal arguments for alignment and approval.",
+    templates: ["memo.md"],
+  },
+  meetings: {
+    title: 'Meetings',
+    dir: 'meetings',
+    description: 'Meeting notes, minutes, retros, standups, planning sessions, and agendas.',
+    templates: ['__meeting-notes-template__'],
+  },
+  notes: {
+    title: "Notes",
+    dir: "notes",
+    description: "Working notes and lightweight durable context outside formal docs or meetings.",
+    templates: ["__notes-template__"],
+  },
+  onboarding: {
+    title: "Onboarding",
+    dir: "onboarding",
+    description: "Runnable setup guides and first-day workflows for engineers, product, or ops.",
+    templates: ["onboarding.md"],
+  },
+  postmortems: {
+    title: "Postmortems",
+    dir: "postmortems",
+    description: "Blameless incident reports: timeline, root cause, contributing factors, and corrective actions.",
+    templates: ["incident-report.md"],
+  },
+  prds: {
+    title: "PRDs",
+    dir: "prds",
+    description: "Product and capability requirement documents.",
+    templates: ["prd.md", "meta-prd.md", "prd-business.md", "prd-platform.md", "prfaq.md"],
+  },
+  rfcs: {
+    title: "RFCs",
+    dir: "rfcs",
+    description: "Architecture and implementation proposals that need review before a decision.",
+    templates: ["rfc.md", "rfc-platform.md"],
+  },
+  runbooks: {
+    title: "Runbooks",
+    dir: "runbooks",
+    description: "Operational procedures, diagnostics, remediation, and escalation paths.",
+    templates: ["runbook.md"],
+  },
+};
+
+const DOC_PRESETS = {
+  lean: ["adrs", "intake", "memos", "meetings", "notes", "prds"],
+  product: ["adrs", "intake", "memos", "meetings", "notes", "prds", "rfcs"],
+  full: ["adrs", "briefs", "changelogs", "intake", "memos", "meetings", "notes", "onboarding", "postmortems", "prds", "rfcs", "runbooks"],
+};
+
+const DEFAULT_LANES = DOC_PRESETS.lean;
+const LANE_ORDER = ["adrs", "briefs", "changelogs", "intake", "memos", "meetings", "notes", "onboarding", "postmortems", "prds", "rfcs", "runbooks"];
+const LANE_ALIASES = {
+  adr: "adrs",
+  adrs: "adrs",
+  brief: "briefs",
+  briefs: "briefs",
+  changelog: "changelogs",
+  changelogs: "changelogs",
+  releases: "changelogs",
+  release: "changelogs",
+  intake: "intake",
+  memo: "memos",
+  memos: "memos",
+  meeting: 'meetings',
+  meetings: 'meetings',
+  minutes: 'meetings',
+  retro: 'meetings',
+  note: "notes",
+  notes: "notes",
+  onboard: "onboarding",
+  onboarding: "onboarding",
+  postmortem: "postmortems",
+  postmortems: "postmortems",
+  incident: "postmortems",
+  incidents: "postmortems",
+  prd: "prds",
+  prds: "prds",
+  rfc: "rfcs",
+  rfcs: "rfcs",
+  runbook: "runbooks",
+  runbooks: "runbooks",
+};
+
+function inferProjectName(targetPath) {
+  const packageJsonPath = path.join(targetPath, "package.json");
+  if (fs.existsSync(packageJsonPath)) {
+    try {
+      const pkg = JSON.parse(fs.readFileSync(packageJsonPath, "utf8"));
+      return pkg.name || path.basename(targetPath);
+    } catch {}
   }
+  return path.basename(targetPath);
 }
 
-loadEnv(path.join(ROOT_DIR, ".env"));
-
-// ─── API caller ───────────────────────────────────────────────────────────────
-
-async function callModel(messages, system) {
-  const anthropicKey = process.env.ANTHROPIC_API_KEY;
-  if (anthropicKey) {
-    const res = await fetch("https://api.anthropic.com/v1/messages", {
-      method: "POST",
-      headers: {
-        "x-api-key": anthropicKey,
-        "anthropic-version": "2023-06-01",
-        "content-type": "application/json",
-      },
-      body: JSON.stringify({ model: FAST_MODEL, max_tokens: 4096, system, messages }),
-    });
-    if (!res.ok) throw new Error(`Anthropic API ${res.status}: ${await res.text()}`);
-    const data = await res.json();
-    return data.content[0].text;
-  }
+function parseCsvList(value) {
+  return value
+    .split(",")
+    .map((entry) => entry.trim())
+    .filter(Boolean);
+}
 
-  const orKey = process.env.OPENROUTER_API_KEY || readOpenRouterApiKeyFromOpenCodeConfig();
-  if (orKey) {
-    const res = await fetch("https://openrouter.ai/api/v1/chat/completions", {
-      method: "POST",
-      headers: {
-        Authorization: `Bearer ${orKey}`,
-        "content-type": "application/json",
-        "HTTP-Referer": "https://github.com/construct",
-      },
-      body: JSON.stringify({
-        model: `anthropic/${FAST_MODEL}`,
-        max_tokens: 4096,
-        messages: [{ role: "system", content: system }, ...messages],
-      }),
-    });
-    if (!res.ok) throw new Error(`OpenRouter API ${res.status}: ${await res.text()}`);
-    const data = await res.json();
-    return data.choices[0].message.content;
-  }
+const NO_ANSWER_PATTERNS = new Set([
+  "",
+  "n",
+  "no",
+  "none",
+  "nope",
+  "nah",
+  "nothing",
+  "blank",
+  "skip",
+  "no thanks",
+]);
+
+const ALL_ANSWER_PATTERNS = new Set([
+  "all",
+  "all of them",
+  "everything",
+  "default",
+  "defaults",
+]);
+
+function normalizeAnswer(value) {
+  return value.trim().toLowerCase().replace(/\s+/g, " ");
+}
 
-  return null;
-}
-
-// ─── Project context ──────────────────────────────────────────────────────────
-
-function dirTree(dir, depth = 0, maxDepth = 2) {
-  if (depth > maxDepth) return [];
-  const skip = new Set(["node_modules", ".git", ".next", "dist", "build", "out",
-    "__pycache__", ".venv", "vendor", "target", ".turbo", "coverage"]);
-  let items;
-  try { items = fs.readdirSync(dir); } catch { return []; }
-  const entries = [];
-  for (const item of items.sort()) {
-    if (skip.has(item) || (item.startsWith(".") && depth === 0 && item !== ".cx")) continue;
-    const full = path.join(dir, item);
-    let stat;
-    try { stat = fs.statSync(full); } catch { continue; }
-    if (stat.isDirectory()) {
-      entries.push(`${"  ".repeat(depth)}${item}/`);
-      entries.push(...dirTree(full, depth + 1, maxDepth));
-    } else {
-      entries.push(`${"  ".repeat(depth)}${item}`);
-    }
-  }
-  return entries;
-}
-
-function gatherContext(targetPath) {
-  const ctx = { name: path.basename(targetPath) };
-
-  for (const name of ["package.json", "pyproject.toml", "Cargo.toml", "go.mod", "build.gradle", "composer.json"]) {
-    const p = path.join(targetPath, name);
-    if (!fs.existsSync(p)) continue;
-    if (name === "package.json") {
-      try {
-        const pkg = JSON.parse(fs.readFileSync(p, "utf8"));
-        ctx.name = pkg.name ?? ctx.name;
-        ctx.description = pkg.description;
-        const deps = Object.keys({ ...(pkg.dependencies ?? {}), ...(pkg.devDependencies ?? {}) });
-        ctx.dependencies = deps.slice(0, 40);
-        ctx.scripts = Object.keys(pkg.scripts ?? {});
-      } catch {}
-    } else {
-      ctx.manifest = fs.readFileSync(p, "utf8").slice(0, 600);
-    }
-    ctx.manifestFile = name;
-    break;
-  }
+function isNegativeAnswer(value) {
+  return NO_ANSWER_PATTERNS.has(normalizeAnswer(value));
+}
 
-  for (const name of ["README.md", "readme.md", "README.txt"]) {
-    const p = path.join(targetPath, name);
-    if (fs.existsSync(p)) {
-      ctx.readme = fs.readFileSync(p, "utf8").slice(0, 2000);
-      break;
-    }
-  }
+function isAllAnswer(value) {
+  return ALL_ANSWER_PATTERNS.has(normalizeAnswer(value));
+}
 
-  ctx.structure = dirTree(targetPath).join("\n");
+function parseLaneSelection(value) {
+  const normalized = normalizeAnswer(value);
+  if (!value.trim() || isAllAnswer(value)) return DEFAULT_LANES;
+  if (isNegativeAnswer(value)) return [];
+  if (DOC_PRESETS[normalized]) return DOC_PRESETS[normalized];
+  return parseSelectableLanes(value);
+}
 
-  const docsPath = path.join(targetPath, "docs");
-  if (fs.existsSync(docsPath)) {
-    ctx.existingDocs = fs.readdirSync(docsPath).slice(0, 20).join(", ");
-  }
+function parseExtraLaneSelection(value) {
+  if (!value.trim() || isNegativeAnswer(value)) return [];
+  return parseCsvList(value)
+    .map(normalizeCustomLaneName)
+    .filter(Boolean);
+}
 
-  try {
-    ctx.gitRemote = execSync("git remote get-url origin", { cwd: targetPath, timeout: 3000, stdio: ["pipe", "pipe", "pipe"] })
-      .toString().trim();
-  } catch {}
+function parseSelectableLanes(value) {
+  return value
+    .split(/[,\n]/)
+    .map((entry) => entry.trim())
+    .filter(Boolean)
+    .map((entry) => {
+      if (/^\d+$/.test(entry)) {
+        const lane = LANE_ORDER[Number(entry) - 1];
+        return lane ?? "";
+      }
+      return normalizeLaneKey(entry);
+    })
+    .filter((lane) => lane in DOC_LANES);
+}
 
-  return ctx;
+function parseBooleanAnswer(value, defaultValue = false) {
+  if (!value.trim()) return defaultValue;
+  const normalized = normalizeAnswer(value);
+  if (["y", "yes", "true"].includes(normalized)) return true;
+  if (["n", "no", "false", "nope", "nah"].includes(normalized)) return false;
+  return defaultValue;
 }
 
-function contextToText(ctx) {
-  const parts = [`Project: ${ctx.name}`];
-  if (ctx.description) parts.push(`Description: ${ctx.description}`);
-  if (ctx.gitRemote) parts.push(`Git remote: ${ctx.gitRemote}`);
-  if (ctx.manifestFile) parts.push(`Manifest: ${ctx.manifestFile}`);
-  if (ctx.dependencies?.length) parts.push(`Dependencies: ${ctx.dependencies.join(", ")}`);
-  if (ctx.scripts?.length) parts.push(`npm scripts: ${ctx.scripts.join(", ")}`);
-  if (ctx.manifest) parts.push(`\nManifest content:\n${ctx.manifest}`);
-  if (ctx.readme) parts.push(`\nREADME:\n${ctx.readme}`);
-  if (ctx.structure) parts.push(`\nDirectory structure:\n${ctx.structure}`);
-  if (ctx.existingDocs) parts.push(`\nExisting docs/: ${ctx.existingDocs}`);
-  return parts.join("\n");
+function normalizeCustomLaneName(name) {
+  return name
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
 }
 
-// ─── JSON extraction ──────────────────────────────────────────────────────────
+function normalizeLaneKey(name) {
+  return LANE_ALIASES[name.trim().toLowerCase()] ?? name.trim().toLowerCase();
+}
 
-function extractJson(text) {
-  const fence = text.match(/```(?:json)?\s*([\s\S]*?)```/);
-  const raw = (fence ? fence[1] : text).trim();
-  const start = raw.indexOf("{");
-  const end = raw.lastIndexOf("}");
-  if (start === -1 || end === -1) throw new Error("No JSON object found in response");
-  return JSON.parse(raw.slice(start, end + 1));
+function repoHasAny(targetDir, candidates) {
+  return candidates.some((candidate) => fs.existsSync(path.join(targetDir, candidate)));
 }
 
-// ─── File writing ─────────────────────────────────────────────────────────────
+function scanNames(targetDir, maxDepth = 2) {
+  const ignored = new Set(['.git', 'node_modules', '.next', 'dist', 'build', 'coverage', '.cx', 'docs']);
+  const names = [];
+
+  function walk(dir, depth) {
+    if (depth > maxDepth) return;
+    const entries = fs.readdirSync(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (ignored.has(entry.name)) continue;
+      names.push(entry.name.toLowerCase());
+      if (entry.isDirectory()) walk(path.join(dir, entry.name), depth + 1);
+    }
+  }
 
-const created = [];
-const skipped = [];
+  walk(targetDir, 0);
+  return names;
+}
+
+function suggestContextualLanes(targetDir) {
+  const suggestions = [];
+  const names = scanNames(targetDir);
+  const hasKeyword = (keywords) => keywords.some((keyword) => names.some((name) => name.includes(keyword)));
+
+  if (repoHasAny(targetDir, ['package.json', 'src', 'lib', 'apps', 'services', 'api']) || hasKeyword(['proposal', 'interface', 'contract', 'schema', 'openapi'])) {
+    suggestions.push({ lane: 'rfcs', reason: 'codebase and interface changes usually benefit from proposal docs' });
+  }
+  if (repoHasAny(targetDir, ['Dockerfile', 'deploy', 'infra', '.github', 'ops', 'terraform']) || hasKeyword(['incident', 'deploy', 'runbook', 'oncall'])) {
+    suggestions.push({ lane: 'runbooks', reason: 'deployment and operations files suggest an ops lane is useful' });
+  }
+  if (repoHasAny(targetDir, ['Dockerfile', 'deploy', 'infra', '.github']) || hasKeyword(['incident', 'postmortem', 'oncall', 'sev', 'pagerduty'])) {
+    suggestions.push({ lane: 'postmortems', reason: 'ops setup suggests an incident post-mortem lane is useful' });
+  }
+  if (repoHasAny(targetDir, ['CHANGELOG.md', 'CHANGELOG', 'RELEASES.md']) || hasKeyword(['changelog', 'release', 'version'])) {
+    suggestions.push({ lane: 'changelogs', reason: 'existing changelog or release files suggest a changelogs lane' });
+  }
+  if (repoHasAny(targetDir, ['onboarding', 'setup', 'getting-started']) || hasKeyword(['onboarding', 'setup', 'getting-started', 'local-dev'])) {
+    suggestions.push({ lane: 'onboarding', reason: 'setup or onboarding files suggest an onboarding lane' });
+  }
+  if (hasKeyword(['research', 'brief', 'customer', 'interview', 'market', 'competitive', 'signal'])) {
+    suggestions.push({ lane: 'briefs', reason: 'research-style source material suggests a briefs lane' });
+  }
+  if (hasKeyword(['meeting', 'minutes', 'standup', 'retro', 'agenda', 'sync', '1:1'])) {
+    suggestions.push({ lane: 'meetings', reason: 'meeting artifacts suggest a dedicated meetings lane' });
+  }
+
+  return suggestions.filter((suggestion, index, arr) => arr.findIndex((item) => item.lane === suggestion.lane) === index);
+}
 
 function writeIfMissing(filePath, content) {
   if (fs.existsSync(filePath)) {
@@ -193,190 +330,493 @@ function writeIfMissing(filePath, content) {
     return;
   }
   fs.mkdirSync(path.dirname(filePath), { recursive: true });
-  fs.writeFileSync(filePath, content, "utf8");
+  const stamped = filePath.endsWith(".md")
+    ? stampFrontmatter(content, { generator: "construct/init-docs" })
+    : content;
+  fs.writeFileSync(filePath, stamped, "utf8");
   created.push(path.relative(target, filePath));
 }
 
-// ─── Static fallback ──────────────────────────────────────────────────────────
+function sortLaneKeys(lanes) {
+  return [...lanes].sort((a, b) => {
+    const left = DOC_LANES[a]?.title ?? titleCase(a);
+    const right = DOC_LANES[b]?.title ?? titleCase(b);
+    return left.localeCompare(right);
+  });
+}
+
+function buildDocsReadme(projectName, selectedLanes) {
+  const laneLines = sortLaneKeys(selectedLanes).map((lane) => {
+    const label = DOC_LANES[lane]?.title ?? titleCase(lane);
+    const laneDir = DOC_LANES[lane]?.dir ?? lane;
+    const desc = DOC_LANES[lane]?.description ?? "Custom documentation lane.";
+    return `- [${label}](./${laneDir}/) — ${desc}`;
+  });
+
+  return `<!--
+docs/README.md — documentation index and maintenance contract.
+
+Generated by \`construct init-docs\`. Keep this file aligned with the actual doc
+lanes in the repo. Update it when lanes are added, removed, or repurposed, and
+prune stale links instead of letting the doc surface drift.
+-->
 
-function scaffoldStatic(projectName, workflowJson) {
-  writeIfMissing(path.join(target, ".cx", "context.json"),
-    `${JSON.stringify({ format: "json", savedAt: new Date().toISOString(), source: "init-docs", projectName, activeWork: [], recentDecisions: [], architectureNotes: [], openQuestions: [] }, null, 2)}\n`);
-  writeIfMissing(path.join(target, ".cx", "context.md"),
-    `# Project Context\n\n> Required project state. Keep this file updated. All LLMs working in this repo, including Construct, read it at session start and must keep it current. Keep under 100 lines.\n\n## Active Work\n\n## Recent Decisions\n\n## Architecture Notes\n\n## Open Questions\n`);
-  writeIfMissing(path.join(target, ".cx", "workflow.json"), workflowJson);
-  writeIfMissing(path.join(target, ".cx", "decisions", "_template.md"),
-    `# ADR-{NNN}: {title}\n\nDate: {YYYY-MM-DD}\nStatus: proposed | accepted | deprecated\n\n## Context\n\n## Decision\n\n## Consequences\n`);
-  writeIfMissing(path.join(target, "docs", "README.md"),
-    `# ${projectName} — Documentation
+# ${projectName} Documentation
 
-> Required project state. All LLMs working in this repo, including Construct, must keep the core documents below current.
+> This docs surface is the canonical home for long-lived project documents such as ADRs, briefs, intake material, memos, notes, PRDs, RFCs, and runbooks.
 
-## Required core documents
+## Operating model
 
-| File | Purpose | Update when |
-|---|---|---|
-| .cx/context.md | Session-resumable human summary | Active work, decisions, architecture assumptions, or open questions change |
-| .cx/context.json | Machine-readable resumable context | Context state needs to stay in sync with .cx/context.md |
-| .cx/workflow.json | Canonical workflow/task state | Non-trivial work starts, changes phase, or completes |
-| docs/README.md | Docs index and documentation contract | Core docs set or maintenance expectations change |
-| docs/architecture.md | Canonical architecture and invariants | Runtime shape, contracts, boundaries, or major dependencies change |
+- Use Beads or the project's external tracker for durable task tracking.
+- Use \`plan.md\` for the current implementation plan.
+- Use this \`docs/\` tree for durable narrative artifacts and decision records.
+- If multiple agent or harness sessions are active, use a single writer per file and coordinate handoffs in the tracker or \`plan.md\`.
+- Prune stale sections and directories when they stop matching how the repo is actually run.
 
-## Contents
+## Lanes
 
-- [Architecture](./architecture.md)
-- [Runbooks](./runbooks/)
-- [ADRs](../.cx/decisions/)
+${laneLines.join("\n")}
 
 ## Maintenance rule
 
-If work changes project reality, update the affected core document before calling it done.
-`);
-  writeIfMissing(path.join(target, "docs", "architecture.md"),
-    `# ${projectName} Architecture\n\n> Required project state. Keep this file updated when system shape, contracts, boundaries, or dependencies materially change. All LLMs working in this repo should treat it as canonical architecture context.\n\n## System overview\n\nDescribe the main runtime shape, primary modules, and external dependencies.\n\n## Core layers\n\n- CLI / entrypoints\n- Application/runtime modules\n- State, data, and storage\n- External integrations\n\n## Key invariants\n\n- Public surface and ownership boundaries\n- Data/contract expectations\n- Safety or review gates\n`);
-  writeIfMissing(path.join(target, "docs", "runbooks", "README.md"),
-    `# Runbooks\n\n## Contents\n\n- Local development startup\n- Verification / health checks\n- Incident recovery\n- Release checklist\n`);
+If a document lane stops serving a real purpose, remove it or archive it intentionally. This tree should stay opinionated and current, not become a graveyard of stale templates.
+`;
 }
 
-// ─── Prompts ──────────────────────────────────────────────────────────────────
+function buildArchitectureDoc(projectName, selectedLanes) {
+  const laneLines = sortLaneKeys(selectedLanes).map((lane) => {
+    const label = DOC_LANES[lane]?.title ?? titleCase(lane);
+    const desc = DOC_LANES[lane]?.description ?? "Custom documentation lane.";
+    return `- **${label}** — ${desc}`;
+  });
 
-const SYSTEM_QUESTIONS = `You are a documentation architect. You've been given context about a software project.
+  return `<!--
+docs/architecture.md — canonical architecture context and documentation-system contract.
 
-Ask 2–3 targeted clarifying questions to fill gaps that will materially affect the doc structure.
-Good questions cover things like: team collaboration style, external consumers, operational complexity,
-compliance needs, or release cadence — only when these aren't clear from the context.
+Generated by \`construct init-docs\`. Update this file when the system shape,
+ownership boundaries, or documentation operating model changes. Remove stale
+assumptions as soon as they stop matching the codebase.
+-->
 
-Do NOT ask about things already obvious from the code. Do NOT ask open-ended questions.
-Each question should have a short, specific answer (a few words or a sentence).
+# ${projectName} Architecture
 
-Output ONLY valid JSON:
-{
-  "questions": [
-    { "id": "q1", "question": "..." },
-    { "id": "q2", "question": "..." }
-  ]
-}`;
+## System overview
 
-const SYSTEM_GENERATE = `You are a documentation architect generating a tailored doc structure.
+Describe the runtime shape, major modules, external dependencies, and key data boundaries.
 
-Generate complete, project-specific files — not generic templates. Use real section headings,
-meaningful placeholder content, and examples that match the actual tech stack and project type.
+## Project-state hierarchy
 
-Rules:
-- Always include .cx/context.md, .cx/context.json, .cx/workflow.json, docs/README.md, and docs/architecture.md
-- Treat these files as required, maintained project state for all LLMs working in the repo, including Construct
-- .cx/context.md should stay under 100 lines and contain real project sections
-- Use the provided .cx/workflow.json verbatim
-- Only include docs that make sense for THIS project — skip what doesn't apply
-- Prefer fewer, higher-quality files over many hollow ones
-- For template files (e.g. ADR template), use the filename _template.md inside the relevant folder
+1. External tracker, preferably Beads, owns the durable backlog and issue status.
+2. \`plan.md\` owns the current human-readable implementation plan.
+3. cass-memory through MCP \`memory\` stores cross-session observations and preferences.
+4. \`docs/\` stores durable narrative artifacts such as ADRs, briefs, intake notes, memos, notes, PRDs, RFCs, and runbooks.
 
-Output ONLY valid JSON:
-{
-  "summary": "One sentence: what was generated and why",
-  "files": [
-    { "path": "relative/path/file.md", "content": "complete file content" }
-  ]
-}`;
+## Documentation lanes
 
-// ─── Main ─────────────────────────────────────────────────────────────────────
+${laneLines.join("\n")}
 
-async function main() {
-  console.log(`\nConstruct init-docs → ${target}\n`);
-
-  const ctx = gatherContext(target);
-  const contextText = contextToText(ctx);
-  const workflowJson = JSON.stringify(defaultWorkflow(target, ctx.name), null, 2) + "\n";
-
-  // Attempt AI path
-  let questionsResponse = null;
-  try {
-    process.stdout.write("  Analyzing project...");
-    questionsResponse = await callModel([{ role: "user", content: contextText }], SYSTEM_QUESTIONS);
-    process.stdout.write(" done\n\n");
-  } catch (err) {
-    process.stdout.write(` failed (${err.message})\n`);
-  }
+## Key invariants
 
-  if (!questionsResponse) {
-    console.log("  No API key found — using static scaffold.\n");
-    console.log("  Set ANTHROPIC_API_KEY or OPENROUTER_API_KEY in .env for AI-tailored output.\n");
-    scaffoldStatic(ctx.name, workflowJson);
-    printSummary();
-    return;
+- Keep one source of truth per concern instead of parallel trackers.
+- When multiple agent or harness sessions run in parallel, use a single writer per file.
+- Update or prune stale docs when work changes project reality.
+- Prefer adding a lane only when it has a distinct audience and decision rhythm.
+`;
+}
+
+function buildLaneReadme(laneKey) {
+  const lane = DOC_LANES[laneKey];
+  const title = lane?.title ?? titleCase(laneKey);
+  const description = lane?.description ?? "Custom documentation lane.";
+  const dirName = lane?.dir ?? laneKey;
+  const templateLines = (lane?.templates ?? []).map((templateName, index) => {
+    const filename = index === 0 ? "_template.md" : templateName.replace(/\.md$/, ".template.md");
+    return `- [${filename}](./templates/${filename})`;
+  });
+  const usageSection = laneKey === "intake"
+    ? `
+## Intake flow
+
+- Drop source files into either [\`.cx/inbox/\`](../../.cx/inbox/) or this lane's directory when you want Construct to ingest them.
+- Run \`construct ingest ./docs/intake --sync\` or \`construct ingest ./.cx/inbox --sync\` to convert supported files into retrieval-ready markdown, or let the embed daemon watch those drop zones automatically.
+- Durable ingested knowledge lands under \`.cx/knowledge/internal/\` by default, which is where Construct's learning and search paths already operate.
+`
+    : "";
+
+  return `<!--
+docs/${dirName}/README.md — lane guide for ${title}.
+
+Generated by \`construct init-docs\`. Keep this lane focused on one document
+family. If it no longer has a distinct purpose, prune it or merge it elsewhere.
+-->
+
+# ${title}
+
+${description}
+
+## Starter templates
+
+${templateLines.join("\n")}
+${usageSection}
+`;
+}
+
+function buildCustomLaneReadme(laneDir) {
+  return `<!--
+docs/${laneDir}/README.md — custom documentation lane.
+
+Generated by \`construct init-docs\`. Rename, refine, or remove this lane once
+its real purpose is clear. Do not keep placeholder structures around indefinitely.
+-->
+
+# ${titleCase(laneDir)}
+
+Custom documentation lane for this project.
+
+## Starter templates
+
+- [\`_template.md\`](./templates/_template.md)
+`;
+}
+
+function buildCustomLaneTemplate(laneDir) {
+  return `<!--
+docs/${laneDir}/_template.md — starter template for a custom documentation lane.
+
+Replace this with a real template once the lane's purpose is clear. If the lane
+never becomes meaningful, delete the lane instead of keeping placeholder docs.
+-->
+
+# ${titleCase(laneDir)}: {title}
+
+- **Date**: {YYYY-MM-DD}
+- **Author**: {name}
+- **Status**: draft | active | superseded
+
+## Summary
+
+<!-- What this document exists to explain or decide. -->
+
+## Context
+
+<!-- Why this matters now and what the reader needs to know first. -->
+
+## Details
+
+<!-- The actual content for this lane. -->
+
+## Decisions or next steps
+
+<!-- What changes because of this document. -->
+
+## References
+
+<!-- Links to related docs, code, or evidence. -->
+`;
+}
+
+function buildNotesTemplate() {
+  return `<!--
+docs/notes/templates/_template.md — starter template for durable project notes.
+
+Keep notes concise, dated, and easy to skim. Promote major decisions into ADRs,
+PRDs, or RFCs when they stop being just notes.
+-->
+
+# Note: {title}
+
+- **Date**: {YYYY-MM-DD}
+- **Author**: {name}
+- **Topic**: {topic}
+
+## Summary
+
+<!-- One-paragraph summary. -->
+
+## Details
+
+<!-- Main notes. -->
+
+## Follow-ups
+
+<!-- Next actions, questions, or references. -->
+`;
+}
+
+function buildMeetingNotesTemplate() {
+  return `<!--
+docs/notes/meetings/_template.md — starter template for meeting notes.
+
+Use this for meeting minutes, standups, reviews, planning, retros, and working sessions.
+Promote durable decisions into ADRs, memos, or PRDs when needed.
+-->
+
+# Meeting: {title}
+
+- **Date**: {YYYY-MM-DD}
+- **Attendees**: {names}
+- **Type**: standup | planning | retro | review | 1:1 | working-session
+
+## Summary
+
+<!-- What happened and why it mattered. -->
+
+## Decisions
+
+<!-- Decisions made in the meeting. -->
+
+## Action items
+
+<!-- Follow-ups, owners, and due dates. -->
+
+## References
+
+<!-- Relevant docs, tickets, links, or recordings. -->
+`;
+}
+
+function buildIntakeTemplate() {
+  return `<!--
+docs/intake/templates/_template.md — starter template for logging an intake batch.
+
+Use this when you want a durable record of what was dropped into intake and why.
+Raw source files belong in .cx/inbox/ until they are ingested.
+-->
+
+# Intake Batch: {title}
+
+- **Date**: {YYYY-MM-DD}
+- **Owner**: {name}
+- **Source**: {vendor, teammate, export, upload}
+
+## What arrived
+
+<!-- Files, folders, or links dropped into .cx/inbox/. -->
+
+## Why it matters
+
+<!-- Why Construct should ingest this material. -->
+
+## Ingest plan
+
+- Run: \`construct ingest ./.cx/inbox --sync\`
+- Target: \`.cx/knowledge/internal/\` unless a different knowledge target is more appropriate
+
+## Notes
+
+<!-- Caveats, access concerns, or cleanup notes. -->
+`;
+}
+
+function titleCase(value) {
+  return value
+    .split(/[-_\s]+/)
+    .filter(Boolean)
+    .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+    .join(" ");
+}
+
+/**
+ * Scan for markdown files in the target directory, excluding common ignored directories.
+ * Returns array of objects: { filePath: absolute path, relPath: path relative to target, content: file content }
+ */
+function scanMarkdownFiles(targetDir) {
+   const ignoredDirs = new Set([
+     'node_modules', '.git', '.next', 'dist', 'build', 'coverage',
+     '.claude', '.cx', 'templates', 'scripts', 'platforms',
+     'docs', // exclude existing docs lane files from reorganization suggestions
+   ]);
+
+  const results = [];
+
+  function walk(dir) {
+    const entries = fs.readdirSync(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      const fullPath = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        if (!ignoredDirs.has(entry.name)) {
+          walk(fullPath);
+        }
+      } else if (entry.isFile() && entry.name.endsWith('.md')) {
+        // Skip files that are already in a docs lane directory (we don't want to suggest moving them)
+        const relPath = path.relative(targetDir, fullPath);
+        if (!relPath.startsWith('docs/') || !relPath.includes('/')) {
+          // Only suggest files at the repo root or in non-docs top-level dirs
+          try {
+            const content = fs.readFileSync(fullPath, 'utf8');
+            results.push({ filePath: fullPath, relPath, content });
+          } catch (err) {
+            // If we can't read, skip
+          }
+        }
+      }
+    }
   }
 
-  // Parse and ask questions
-  let questions = [];
-  try {
-    questions = extractJson(questionsResponse).questions ?? [];
-  } catch {
-    // skip questions if parse fails, go straight to generation
+  walk(targetDir);
+  return results;
+}
+
+/**
+ * Suggest a documentation lane for a given file based on its content and filename.
+ * Returns the canonical lane key (e.g., 'prds', 'rfcs', 'adrs') or null if no clear suggestion.
+ */
+function suggestLocationForFile(filePath, content) {
+  return suggestDocsLaneForFile(filePath, content);
+}
+
+function copyLaneTemplates(laneKey) {
+  const lane = DOC_LANES[laneKey];
+  if (!lane) return;
+  const laneRoot = path.join(docsDir, lane.dir);
+  writeIfMissing(path.join(laneRoot, "README.md"), buildLaneReadme(laneKey));
+  for (const [index, templateName] of lane.templates.entries()) {
+    const outputName = index === 0 ? "_template.md" : templateName.replace(/\.md$/, ".template.md");
+    const content =
+      templateName === "__notes-template__" ? buildNotesTemplate()
+      : templateName === '__meeting-notes-template__' ? buildMeetingNotesTemplate()
+      : templateName === "__intake-template__" ? buildIntakeTemplate()
+      : fs.readFileSync(path.join(TEMPLATE_DIR, templateName), "utf8");
+    writeIfMissing(path.join(laneRoot, "templates", outputName), content);
   }
+}
 
-  const answers = {};
-  if (questions.length && !skipInteractive) {
-    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
-    console.log("A few questions to tailor the structure:\n");
-    for (const q of questions) {
-      const answer = await new Promise((resolve) => rl.question(`  ${q.question}\n  > `, resolve));
-      answers[q.id] = answer.trim();
-      console.log();
-    }
-    rl.close();
+function createCustomLane(laneDir) {
+  const laneRoot = path.join(docsDir, laneDir);
+  writeIfMissing(path.join(laneRoot, "README.md"), buildCustomLaneReadme(laneDir));
+  writeIfMissing(path.join(laneRoot, "templates", "_template.md"), buildCustomLaneTemplate(laneDir));
+}
+
+/* ─── askQuestions ───────────────────────────────────────────────────────── */
+async function askQuestions() {
+  if (skipInteractive) {
+    return {
+      lanes: docsArg ? parseLaneSelection(docsArg.split("=")[1]) : DEFAULT_LANES,
+      extraLanes: extrasArg ? parseExtraLaneSelection(extrasArg.split("=")[1]) : [],
+      withArchitecture: withArchitectureFlag,
+    };
   }
 
-  // Build generation prompt
-  const qaText = questions.length && Object.keys(answers).length
-    ? "\n\nAnswers to clarifying questions:\n" +
-      questions.filter((q) => answers[q.id]).map((q) => `Q: ${q.question}\nA: ${answers[q.id]}`).join("\n\n")
-    : "";
+  const contextualSuggestions = suggestContextualLanes(target);
+  const suggestedKeys     = new Set(contextualSuggestions.map((s) => s.lane));
+  const suggestedReasons  = Object.fromEntries(contextualSuggestions.map((s) => [s.lane, s.reason]));
+
+  const defaultSet = new Set(DEFAULT_LANES);
+  const items = LANE_ORDER.map((key) => ({
+    value: key,
+    label: DOC_LANES[key].title,
+    description: DOC_LANES[key].description,
+    checked: defaultSet.has(key) || suggestedKeys.has(key),
+    suggestion: suggestedKeys.has(key) ? suggestedReasons[key] : null,
+    meta: `docs/${DOC_LANES[key].dir}/`,
+  }));
+
+  const selectedKeys = await multiSelect({
+    title: 'Select doc lanes',
+    instructions: 'Use arrows to move, Space to toggle, a to toggle all, i to invert, Enter to confirm.',
+    options: items,
+  });
+  const lanes = selectedKeys.length ? selectedKeys : DEFAULT_LANES;
+
+  const withArchitecture = await selectOption({
+    title: 'Create docs/architecture.md?',
+    instructions: 'Pick whether to scaffold the architecture document now.',
+    options: [
+      { value: true, label: 'Yes', description: 'Create docs/architecture.md with the project-state hierarchy and lane summary.' },
+      { value: false, label: 'No', description: 'Skip docs/architecture.md for now. You can add it later.' },
+    ],
+  });
+  process.stdout.write("\n");
+
+  return { lanes, extraLanes: [], withArchitecture };
+}
 
-  const genPrompt = `${contextText}${qaText}\n\n---\n.cx/workflow.json (use verbatim):\n${workflowJson}`;
-
-  let genResponse = null;
-  try {
-    process.stdout.write("  Generating doc structure...");
-    genResponse = await callModel([{ role: "user", content: genPrompt }], SYSTEM_GENERATE);
-    process.stdout.write(" done\n\n");
-  } catch (err) {
-    process.stdout.write(` failed (${err.message})\n`);
-    console.log("  Falling back to static scaffold.\n");
-    scaffoldStatic(ctx.name, workflowJson);
-    printSummary();
-    return;
+async function main() {
+  const projectName = inferProjectName(target);
+  const { lanes, extraLanes, withArchitecture } = await askQuestions();
+  const normalizedLanes = Array.from(new Set(
+    lanes
+      .map((lane) => normalizeLaneKey(lane))
+      .filter((lane) => lane in DOC_LANES),
+  ));
+  const selectedLanes = normalizedLanes.length ? normalizedLanes : DEFAULT_LANES;
+  const selectedCustomLanes = Array.from(new Set(
+    extraLanes
+      .map(normalizeCustomLaneName)
+      .filter(Boolean)
+      .filter((lane) => !(lane in DOC_LANES)),
+  ));
+  const allLaneKeys = sortLaneKeys([...selectedLanes, ...selectedCustomLanes]);
+
+  process.stdout.write(`\nConstruct init-docs → ${target}\n\n`);
+
+  writeIfMissing(path.join(docsDir, "README.md"), buildDocsReadme(projectName, allLaneKeys));
+if (withArchitecture) {
+  writeIfMissing(path.join(docsDir, "architecture.md"), buildArchitectureDoc(projectName, allLaneKeys));
+}
+  if (selectedLanes.includes('intake')) {
+    writeIfMissing(path.join(target, '.cx', 'inbox', '.gitkeep'), '');
   }
 
-  try {
-    const plan = extractJson(genResponse);
-    if (plan.summary) console.log(`  ${plan.summary}\n`);
-    for (const file of plan.files ?? []) {
-      if (file.path && file.content) {
-        writeIfMissing(path.join(target, file.path), file.content);
+  for (const laneKey of selectedLanes) copyLaneTemplates(laneKey);
+  for (const laneKey of selectedCustomLanes) createCustomLane(laneKey);
+
+  // Handle suggestion and organization of existing markdown files
+  if (suggestOrg || organize) {
+    if (organize && !skipInteractive) {
+      process.stdout.write("Error: --organize requires --yes to avoid interactive prompts.\n");
+      process.exit(1);
+    }
+
+    const markdownFiles = scanMarkdownFiles(target);
+    const suggestions = [];
+
+    for (const file of markdownFiles) {
+      const suggestedLane = suggestLocationForFile(file.filePath, file.content);
+      if (suggestedLane) {
+        suggestions.push({ file: file, lane: suggestedLane });
       }
     }
-  } catch (err) {
-    console.warn(`  Could not parse model output (${err.message}). Falling back to static scaffold.\n`);
-    scaffoldStatic(ctx.name, workflowJson);
-  }
 
-  printSummary();
-}
+    if (suggestions.length === 0) {
+      process.stdout.write("No files found that could be organized into documentation lanes.\n");
+    } else {
+      process.stdout.write(`Found ${suggestions.length} file(s) that could be organized:\n\n`);
+      for (const { file, lane } of suggestions) {
+        process.stdout.write(`  ${file.relPath} → docs/${DOC_LANES[lane]?.dir ?? lane}/\n`);
+      }
+      process.stdout.write("\n");
+
+      if (organize) {
+        // Actually move the files
+        process.stdout.write("Moving files to suggested locations...\n");
+        for (const { file, lane } of suggestions) {
+          const targetDir = path.join(target, "docs", DOC_LANES[lane]?.dir ?? lane);
+          const targetPath = path.join(targetDir, path.basename(file.filePath));
+          try {
+            fs.renameSync(file.filePath, targetPath);
+            process.stdout.write(`  Moved: ${file.relPath} → docs/${DOC_LANES[lane]?.dir ?? lane}/${path.basename(file.filePath)}\n`);
+          } catch (err) {
+            process.stdout.write(`  Failed to move ${file.relPath}: ${err.message}\n`);
+          }
+        }
+        process.stdout.write("Organization complete.\n");
+      }
+    }
+  }
 
-function printSummary() {
-  console.log(`Doc structure initialized at: ${target}\n`);
   if (created.length) {
-    console.log("Created:");
-    for (const f of created) console.log(`  + ${f}`);
+    process.stdout.write("Created:\n");
+    for (const file of created) process.stdout.write(`  + ${file}\n`);
   }
   if (skipped.length) {
-    console.log("\nSkipped (already exist):");
-    for (const f of skipped) console.log(`  ~ ${f}`);
+    process.stdout.write("\nSkipped (already exist):\n");
+    for (const file of skipped) process.stdout.write(`  ~ ${file}\n`);
   }
-  console.log(`\n${created.length} created, ${skipped.length} skipped.`);
+  process.stdout.write(`\n${created.length} created, ${skipped.length} skipped.\n`);
 }
 
-main().catch((err) => {
-  console.error("Error:", err.message);
+main().catch((error) => {
+  process.stderr.write(`Error: ${error.message}\n`);
   process.exit(1);
 });