novahiz 0.2.2 → 0.2.3

package/adapters/opencode/commands/novahiz-init.md

@@ -0,0 +1,10 @@
+---
+description: Initialize Novahiz in this project (memory, docs, analysis, reviewed cleanup)
+---
+
+Load the `novahiz-init` skill and follow its pipeline from the current working directory.
+
+1. Run `novahiz init --dry-run --json` and show the plan.
+2. Unless the user only wanted a preview, run `novahiz init --json`.
+3. Deep-read the project (`novahiz-analyse`), fill `novahiz-docs/`, seed memory.
+4. Offer cleanup only after listing candidates; apply solely on explicit consent.

package/adapters/opencode/novahiz.ts

@@ -1,10 +1,11 @@
 import type { Plugin } from "@opencode-ai/plugin";
-import { spawnSync } from "node:child_process";
+import { spawn, spawnSync } from "node:child_process";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
-import { join } from "node:path";
+import { join, relative, resolve } from "node:path";
 
-// Inlined from src/prompt-rewriter.ts to avoid broken relative path in installed plugin
+// Inlined from src/prompt-rewriter.ts — the installed plugin lives in
+// ~/.config/opencode/plugins/ and cannot resolve ../../src/*.
 type RewriteResult = { original: string; rewritten: string; sourceLanguage: string; wasRewritten: boolean };
 
 function detectLanguage(prompt: string): string {
@@ -50,6 +51,138 @@ function rewritePrompt(prompt: string): RewriteResult {
   return { original: prompt, rewritten: r, sourceLanguage, wasRewritten: true };
 }
 
+// Inlined from src/autodocs.ts — same reason as prompt-rewriter: relative
+// imports to ../../src break once the plugin is copied into opencode's plugins/.
+const NOVAHIZ_DIR = ".novahiz";
+const STATE_NAME = "state.json";
+const CONFIG_NAME = "config.json";
+
+type AutoDocsState = {
+  dirty: boolean;
+  pending: string[];
+  lastSync: string | null;
+  sessions: number;
+};
+
+const EMPTY_STATE: AutoDocsState = { dirty: false, pending: [], lastSync: null, sessions: 0 };
+const MAJOR_DIRS = /^(src|lib|app|routes|pages|api|server|internal|pkg|cmd)\//;
+const MAJOR_FILES = new Set([
+  "package.json",
+  "pyproject.toml",
+  "Cargo.toml",
+  "go.mod",
+  "composer.json",
+  "Gemfile"
+]);
+const MAJOR_EXT = new Set([
+  ".ts",
+  ".tsx",
+  ".js",
+  ".jsx",
+  ".mjs",
+  ".cjs",
+  ".py",
+  ".rs",
+  ".go",
+  ".php",
+  ".rb",
+  ".java",
+  ".kt",
+  ".swift",
+  ".dart",
+  ".sql"
+]);
+const SKIP_DIRS = new Set([
+  "node_modules",
+  ".git",
+  "project-memory",
+  "novahiz-docs",
+  ".novahiz",
+  "dist",
+  "build",
+  "coverage",
+  ".next"
+]);
+
+function projectDir(cwd: string): string {
+  return join(cwd, NOVAHIZ_DIR);
+}
+
+function configPath(cwd: string): string {
+  return join(projectDir(cwd), CONFIG_NAME);
+}
+
+function statePath(cwd: string): string {
+  return join(projectDir(cwd), STATE_NAME);
+}
+
+function ensureNovahizDir(path: string): void {
+  if (!existsSync(path)) mkdirSync(path, { recursive: true });
+}
+
+function autoDocsEnabled(cwd: string): boolean {
+  const escape = (process.env.NOVAHIZ_AUTODOCS ?? "").toLowerCase();
+  if (["off", "0", "false", "no", "disabled"].includes(escape)) return false;
+  try {
+    const parsed = JSON.parse(readFileSync(configPath(cwd), "utf8")) as { autoDocs?: unknown };
+    return parsed !== null && typeof parsed === "object" && parsed.autoDocs === true;
+  } catch {
+    return false;
+  }
+}
+
+function readState(cwd: string): AutoDocsState {
+  try {
+    const parsed = JSON.parse(readFileSync(statePath(cwd), "utf8")) as Partial<AutoDocsState>;
+    if (!parsed || typeof parsed !== "object") return { ...EMPTY_STATE };
+    return {
+      dirty: parsed.dirty === true,
+      pending: Array.isArray(parsed.pending)
+        ? parsed.pending.filter((entry): entry is string => typeof entry === "string").slice(0, 64)
+        : [],
+      lastSync: typeof parsed.lastSync === "string" ? parsed.lastSync : null,
+      sessions: typeof parsed.sessions === "number" && Number.isFinite(parsed.sessions) ? parsed.sessions : 0
+    };
+  } catch {
+    return { ...EMPTY_STATE };
+  }
+}
+
+function writeState(cwd: string, state: AutoDocsState): void {
+  ensureNovahizDir(projectDir(cwd));
+  writeFileSync(statePath(cwd), `${JSON.stringify(state, null, 2)}\n`, "utf8");
+}
+
+function normalizePath(filePath: string): string {
+  return filePath.replace(/\\/g, "/").replace(/^\.\//, "").replace(/^\/+/, "");
+}
+
+function isMajorPath(filePath: string): boolean {
+  const path = normalizePath(filePath);
+  const parts = path.split("/");
+  if (parts.some((part) => SKIP_DIRS.has(part))) return false;
+  const base = parts[parts.length - 1] ?? "";
+  if (MAJOR_FILES.has(base)) return true;
+  const dot = base.lastIndexOf(".");
+  const ext = dot >= 0 ? base.slice(dot).toLowerCase() : "";
+  if (MAJOR_EXT.has(ext)) return true;
+  return MAJOR_DIRS.test(path);
+}
+
+function markDirty(cwd: string, filePath: string): AutoDocsState {
+  const path = normalizePath(filePath);
+  const state = readState(cwd);
+  const pending = state.pending.includes(path) ? state.pending : [...state.pending, path].slice(-64);
+  const next: AutoDocsState = {
+    ...state,
+    dirty: true,
+    pending,
+    sessions: state.sessions + 1
+  };
+  writeState(cwd, next);
+  return next;
+}
+
 function ensureProjectMemory(cwd: string): boolean {
   try {
     const root = join(cwd, "project-memory");
@@ -219,6 +352,28 @@ export const NovahizPlugin: Plugin = async ({ client }) => {
 
     event: async ({ event }) => {
       const type = (event as { type?: string }).type ?? "";
+      if (type === "session.idle") {
+        // Fail-open: never block idle; skip when disabled or nothing pending.
+        try {
+          const cwd = process.cwd();
+          if (autoDocsEnabled(cwd)) {
+            const state = readState(cwd);
+            if (state.dirty || state.pending.length > 0) {
+              const child = spawn(NODE, [CLI, "autodocs", "--flush"], {
+                cwd,
+                stdio: "ignore",
+                timeout: RUN_TIMEOUT_MS,
+                windowsHide: true
+              });
+              child.on("error", () => undefined);
+              child.unref();
+            }
+          }
+        } catch {
+          // fail-open
+        }
+        return;
+      }
       if (type !== "session.deleted") return;
       const properties = (event as { properties?: { info?: { id?: string }; sessionID?: string } }).properties ?? {};
       const sessionID = properties.info?.id ?? properties.sessionID;
@@ -395,6 +550,29 @@ export const NovahizPlugin: Plugin = async ({ client }) => {
         await log("warn", `Gate error, denying the tool call as precaution: ${String(error)}`);
         throw new Error(`Novahiz gate blocked ${input.tool}: internal gate error. Set NOVAHIZ_GATE=off to disable.`);
       }
+    },
+
+    "tool.execute.after": async (input) => {
+      // Fail-open: mark major paths only; never break the tool result.
+      try {
+        const tool = input.tool.toLowerCase();
+        if (!["edit", "write", "patch", "apply_patch"].includes(tool)) return;
+        const args = (input.args ?? {}) as Record<string, unknown>;
+        const raw =
+          (typeof args.filePath === "string" && args.filePath) ||
+          (typeof args.file_path === "string" && args.file_path) ||
+          (typeof args.path === "string" && args.path) ||
+          "";
+        if (!raw) return;
+        const cwd = process.cwd();
+        const abs = resolve(cwd, raw);
+        const rel = relative(cwd, abs).replace(/\\/g, "/");
+        if (!rel || rel.startsWith("..")) return;
+        if (!isMajorPath(rel)) return;
+        markDirty(cwd, rel);
+      } catch {
+        // fail-open
+      }
     }
   };
 };

package/docs/CONFIGURATION.md

@@ -61,7 +61,7 @@ These files live in `catalog/` and are part of the git repository:
 | `skillRoots` | `["./skills", "./bundled-skills"]` | Directories to scan for skills |
 | `gate.enabled` | `true` | Enable/disable the gate |
 | `gate.mode` | `block` | `block`, `warn`, or `audit` |
-| `gate.envEscape` | `NOVAHIZ_GATE` | Env var to disable the gate |
+| `gate.envEscape` | `NOVAHIZ_GATE` | Schema field only. The kill-switch name is hardcoded to `NOVAHIZ_GATE` in the CLI, MCP gate, and plugin; a config value cannot redirect it. |
 | `gate.tools` | `[edit, write, patch, ...]` | Tools to intercept |
 | `gate.placeholders` | `true` | Block edits with placeholder markers |
 | `classify.minScore` | `1` | Minimum score to match a category |
@@ -79,7 +79,7 @@ These files live in `catalog/` and are part of the git repository:
 | Variable | Purpose |
 |----------|---------|
 | `NOVAHIZ_HOME` | Override Novahiz home directory |
-| `NOVAHIZ_GATE` | Set to `off` to disable the gate |
+| `NOVAHIZ_GATE` | Set to `off` to disable the gate (hardcoded name; not configurable) |
 | `NOVAHIZ_NODE` | Override node executable path |
 | `NOVAHIZ_DB` | Override database path |
 | `OPENCODE_CONFIG_DIR` | Override opencode config directory |

package/docs/PLUGIN.md

@@ -13,13 +13,17 @@ The opencode adapter is a thin plugin that bridges the Novahiz core with the ope
 │  3. Check DISABLED flag (env escape or config)              │
 │  4. Register hooks:                                         │
 │     • config → inject MCP server + providers                │
-│     • event → clean up session state on session.deleted     │
+│     • event → session.deleted cleanup;                      │
+│               session.idle → flush autodocs (fail-open)     │
 │     • chat.message → classify prompt, build enforcement     │
 │     • experimental.chat.system.transform → inject into prompt│
 │     • tool.execute.before → gate check on edits             │
+│     • tool.execute.after → mark major path dirty (autodocs)  │
 └─────────────────────────────────────────────────────────────┘
 ```
 
+The plugin is self-contained: prompt rewriting and autodocs helpers are inlined so the installed copy under `~/.config/opencode/plugins/` does not depend on `../../src/*` (that path does not resolve after install).
+
 ## Hooks
 
 ### `config`
@@ -28,8 +32,8 @@ Registers the Novahiz MCP server and any additional providers from `catalog/prov
 
 ```typescript
 config: async (input) => {
-  // Register Novahiz MCP server
-  config.mcp.Novahiz = {
+  // Register Novahiz MCP server (key is lowercase: config.mcp.novahiz)
+  config.mcp.novahiz = {
     type: "local",
     command: [NODE, join(HOME, "mcp", "novahiz-tools", "index.mjs")],
     enabled: true
@@ -108,10 +112,23 @@ The core enforcement hook. Intercepts tool calls and runs the gate:
 │  Gate output:                                               │
 │  • exit 0 → allow                                           │
 │  • exit 2 → BLOCK (throw error with missing skills list)    │
-│  • exit != 0 → allow with warning (gate unavailable)        │
+│  • exit != 0 → BLOCK (fail-closed, same as spawn error)      │
 └─────────────────────────────────────────────────────────────┘
 ```
 
+### `event`
+
+Two event types:
+
+| Event | Behavior |
+|-------|----------|
+| `session.deleted` | Forget in-memory session state |
+| `session.idle` | If autodocs is enabled and state is dirty, spawn `novahiz autodocs --flush` (fail-open, unref'd child) |
+
+### `tool.execute.after`
+
+After an edit-like tool succeeds, if the path is a major source file (`src/…`, `package.json`, `.ts`, …), call the inlined `markDirty` so the next `session.idle` can flush docs. Non-edit tools and non-major paths are ignored. Never throws.
+
 ## Session state
 
 The plugin maintains per-session state in memory:
@@ -145,6 +162,7 @@ When disabled, all hooks return early without doing anything.
 ## Error handling
 
 - If `classify` fails → warning logged, no enforcement injected
-- If `gate` fails with spawn error → tool call allowed (gate unavailable)
-- If `gate` exits non-zero non-two → tool call allowed with warning
+- If `gate` fails with spawn error → tool call **blocked** (fail-closed)
+- If `gate` exits non-zero non-two → tool call **blocked** (fail-closed)
 - If `gate` exits 2 → error thrown, tool call blocked
+- Autodocs flush on `session.idle` and `tool.execute.after` are fail-open

package/docs/RULES.md

@@ -75,7 +75,7 @@ The `gate` block in `novahiz.config.json` controls behavior:
 
 - `enabled`: disable the whole gate.
 - `mode`: `block`, `warn`, or `audit`.
-- `envEscape`: the variable that disables the gate for one session. Defaults to `novahiz_GATE`; values `off`, `0`, `false`, `no`, `disabled` disable it. Read by the CLI, the hook mode, the MCP gate tool, and the opencode plugin.
+- `envEscape`: schema field only. The kill-switch variable is hardcoded to `NOVAHIZ_GATE` (not configurable); values `off`, `0`, `false`, `no`, `disabled` disable the gate. Read by the CLI, the hook mode, the MCP gate tool, and the opencode plugin.
 - `tools`: the tool names the gate intercepts.
 - `ignoreFiles`: globs skipped by the gate.
 

package/install/install.mjs

@@ -46,6 +46,8 @@ function defaultConfig(skillsDir) {
     gate: {
       enabled: true,
       mode: "block",
+      // Kept for schema compatibility only — the kill-switch name is hardcoded
+      // to NOVAHIZ_GATE in the CLI, MCP gate, and plugin (see src/spec.ts).
       envEscape: "NOVAHIZ_GATE",
       tools: ["edit", "write", "patch", "apply_patch", "bash", "shell"]
     },

package/mcp/novahiz-tools/index.mjs

@@ -11,7 +11,7 @@ import { rankSkills } from "../../src/relevance.ts";
 import { openDb } from "../../src/db.ts";
 import { enabledProviders } from "../../src/providers.ts";
 import { checkDependencies } from "../../src/deps.ts";
-import { activeTask, addTodos, amendTodo, blockTodo, buildWorkPackets, completeTodo, createTask, dropTodo, getTask, getTodo, insertTodo, ledgerSummary, listTodos, recordTodoDone, reorderTodos, resume, reviewDue, reviewTask, revisionSignals, startTodo } from "../../src/ledger.ts";
+import { activeTask, addTodos, amendTodo, blockTodo, buildWorkPackets, completeTodo, createTask, dropTask, dropTodo, getTask, getTodo, insertTodo, ledgerSummary, listTodos, recordTodoDone, reorderTodos, resume, reviewDue, reviewTask, revisionSignals, startTodo } from "../../src/ledger.ts";
 import { DEFAULT_LIMIT_CHARS, DEFAULT_LIMIT_LINES, ensureMemoryRoot, getSlot, listSlots, memoryRoot, parseSlotInput, rebuildIndex, writeEntry } from "../../src/memory.ts";
 
 const SUPPORTED_PROTOCOLS = ["2024-11-05", "2025-06-18"];
@@ -63,7 +63,8 @@ const TOOLS = [
         filePath: { type: "string", description: "Alias of file. Some harnesses rename the parameter when they surface the tool." },
         tool: { type: "string", description: "edit, write or patch." },
         content: { type: "string", description: "The edited content, used for content-aware rules." },
-        categories: { type: "array", items: { type: "string" } },
+        prompt: { type: "string", description: "Optional prompt used to auto-classify when categories is omitted or empty." },
+        categories: { type: "array", items: { type: "string" }, description: "Category ids. When omitted or empty, inferred from prompt, content, or file path." },
         loaded: { type: "array", items: { type: "string" } }
       }
     }
@@ -118,7 +119,7 @@ const TOOLS = [
           description: "What to do with the ledger."
         },
         title: { type: "string", description: "Task title for action new." },
-        id: { type: "string", description: "Task id (new) or todo id (start, done, block)." },
+        id: { type: "string", description: "Task id (new) or todo/task id (start, done, block, drop)." },
         task: { type: "string", description: "Task id. Defaults to the active task." },
         session: { type: "string", description: "Session id used to scope the active task." },
         label: { type: "string", description: "Todo label for action todo." },
@@ -329,12 +330,34 @@ function callTool(name, args) {
     if (args?.tool !== undefined && typeof args.tool !== "string") {
       throw new Error("Invalid params: tool must be a string");
     }
+    if (args?.prompt !== undefined && typeof args.prompt !== "string") {
+      throw new Error("Invalid params: prompt must be a string");
+    }
+    if (typeof args?.prompt === "string" && args.prompt.length > MAX_PROMPT_LEN) {
+      throw new Error(`Invalid params: prompt exceeds ${MAX_PROMPT_LEN} characters`);
+    }
+    // Auto-classify when categories is omitted or empty: seed from prompt,
+    // fall back to content, then file path. Explicit categories always win.
+    let categories = args?.categories ? args.categories.map(String) : [];
+    if (categories.length === 0) {
+      const seed =
+        (typeof args?.prompt === "string" && args.prompt.length > 0 ? args.prompt : "") ||
+        (typeof args?.content === "string" && args.content.length > 0 ? args.content : "") ||
+        file;
+      try {
+        categories = classify(spec, seed).categories.map((entry) => entry.id);
+      } catch {
+        // Fail closed on classify errors: keep empty categories so
+        // evaluateGate still runs path/content rules instead of crashing.
+        categories = [];
+      }
+    }
     const index = loadInstalledSkills(spec);
     const result = evaluateGate({
       tool: String(args?.tool ?? "edit"),
       filePath: file,
       content: typeof args?.content === "string" ? args.content : "",
-      categories: args?.categories ? args.categories.map(String) : [],
+      categories,
       loadedSkills: args?.loaded ? args.loaded.map(String) : [],
       installedSkills: index.skills,
       installedIndexAvailable: index.available,
@@ -472,8 +495,14 @@ function callTool(name, args) {
         const position = raw === undefined || raw === "" ? "end" : /^\d+$/.test(String(raw)) ? Number(raw) : String(raw);
         return toolResult(insertTodo(db, taskId, normalizeTodo(args), position));
       }
-      if (action === "drop") return toolResult(dropTodo(db, String(args?.id ?? ""), args?.reason ? String(args.reason) : ""));
-      if (action === "reorder") {
+        if (action === "drop") {
+          const dropId = String(args?.id ?? "");
+          const reason = args?.reason ? String(args.reason) : "";
+          if (getTask(db, dropId)) return toolResult({ task: dropTask(db, dropId, reason) });
+          if (getTodo(db, dropId)) return toolResult({ todo: dropTodo(db, dropId, reason) });
+          throw new Error(`unknown id: ${dropId} (expected a task id or todo id)`);
+        }
+        if (action === "reorder") {
         const taskId = args?.task ? String(args.task) : activeTask(db, session)?.id;
         if (!taskId) return toolResult("no active task", true);
         const order = Array.isArray(args?.order) ? args.order.map(String) : [];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "novahiz",
-  "version": "0.2.2",
+  "version": "0.2.3",
   "description": "Enforce AI agent skills before every file edit: prompt classifier, skill catalog, and pre-edit gate.",
   "type": "module",
   "license": "Apache-2.0",
@@ -27,11 +27,11 @@
     "access": "public"
   },
   "bin": {
-    "novahiz": "./bin/novahiz.mjs",
-    "novahiz-bootstrap": "./install/bootstrap.mjs",
-    "novahiz-install": "./install/install.mjs",
-    "novahiz-uninstall": "./install/uninstall.mjs",
-    "novahiz-mcp": "./mcp/novahiz-tools/index.mjs"
+    "novahiz": "bin/novahiz.mjs",
+    "novahiz-bootstrap": "install/bootstrap.mjs",
+    "novahiz-install": "install/install.mjs",
+    "novahiz-uninstall": "install/uninstall.mjs",
+    "novahiz-mcp": "mcp/novahiz-tools/index.mjs"
   },
   "engines": {
     "node": ">=22.18.0"

package/skills/novahiz-gate/SKILL.md

@@ -67,7 +67,7 @@ Charger chaque skill manquante avec `skill({name})`. Le chargement est enregistr
 
 ## Contournement
 
-Le seul prévu par le code : `novahiz_GATE=off` (ou `0`, `false`, `no`, `disabled`) dans l'environnement, lu via `gate.envEscape`. L'utilisateur peut aussi demander explicitement de passer outre. Dans les deux cas, la dérogation se dit à voix haute et se rattrape après coup. Le jugement de l'agent n'est pas un contournement valide.
+Le seul prévu par le code : `NOVAHIZ_GATE=off` (ou `0`, `false`, `no`, `disabled`) dans l'environnement. Le nom de la variable est codé en dur (le champ `gate.envEscape` de la config ne le redirige pas). L'utilisateur peut aussi demander explicitement de passer outre. Dans les deux cas, la dérogation se dit à voix haute et se rattrape après coup. Le jugement de l'agent n'est pas un contournement valide.
 
 ## Anti-patterns
 

package/skills/novahiz-init/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: novahiz-init
+description: |
+  novahiz-init bootstraps Novahiz inside a project: memory skeleton, novahiz-docs/,
+  deep read of the codebase, documentation fill-in, and a reviewed cleanup list.
+  Use when the user says "/novahiz init", "init novahiz", "initialize novahiz in this project",
+  "set up project docs and memory", or wants a one-shot project onboarding.
+license: Apache-2.0
+compatibility: opencode
+metadata:
+  author: Novahiz
+  organization: Novahiz
+  version: "1.0.0"
+---
+
+# novahiz-init
+
+One entry point to bring Novahiz into the current project: scaffold first, then deepen with an agent read.
+
+## When to run
+
+- `/novahiz init` or `novahiz init` in the project root
+- A new repo needs docs + `project-memory/`
+- Docs or memory are missing after a clone
+
+Do **not** use this to install Novahiz on the machine. That stays `novahiz setup` / `install.mjs`.
+
+## Pipeline
+
+```
+1. CLI scaffold     novahiz init [--dry-run] [--docs-only|--memory-only]
+2. Deep read        novahiz-analyse on the real code
+3. Fill docs        novahiz-docs templates already created by CLI
+4. Seed memory      memory_write a baseline slot from findings
+5. Cleanup review   confirm list, then novahiz init --apply --json
+```
+
+### 1. Scaffold (CLI, deterministic)
+
+From the project root:
+
+```
+novahiz init --dry-run --json
+```
+
+Review the plan, then run without `--dry-run` unless the user only wanted a preview.
+
+Flags:
+
+| Flag | Effect |
+|---|---|
+| `--dry-run` | Print steps and cleanup candidates, write nothing |
+| `--docs-only` | Only `novahiz-docs/` |
+| `--memory-only` | Only `project-memory/` |
+| `--no-seed` | Create memory root without the baseline slot |
+| `--apply` | Delete the listed cleanup candidates (never without review) |
+| `--json` | Machine-readable result |
+
+The CLI creates:
+
+- `project-memory/index.json` + `slots/` (plus one baseline slot unless `--no-seed`)
+- `novahiz-docs/{ARCHITECTURE,CONVENTIONS,DECISIONS,STANDARDS}.md` from the `novahiz-docs` templates when the folder is absent
+- A cleanup candidate list (logs, `*.orig`, `*.novahiz-bak`, …). Nothing is deleted without `--apply`.
+
+### 2. Deep read
+
+Load `novahiz-analyse` and walk manifests, entry points, and data flow. Every claim cites a path. This step is agent work; the CLI does not invent architecture.
+
+### 3. Fill documentation
+
+Edit only the four files under `novahiz-docs/`:
+
+- Replace HTML comment placeholders with observed facts
+- Keep DECISIONS.md empty until a real decision exists
+- If older docs live in `README.md` or `docs/`, migrate unique facts into the right file, then leave a pointer in the README. Do not delete the README.
+
+Load `novahiz-humanizer` before writing prose.
+
+### 4. Seed memory
+
+After docs are filled, append one slot via MCP `memory_write` or `novahiz init` baseline (already written by CLI):
+
+- stack and markers
+- entry points
+- where docs live
+- open unknowns
+
+### 5. Cleanup (optional, reviewed)
+
+1. Show the CLI cleanup list to the user.
+2. Use the `question` tool: apply all, apply none, or hand-pick.
+3. Only after an explicit choice:
+
+```
+novahiz init --apply --json
+```
+
+`--yes` alone is never enough to delete files the user has not seen.
+
+## Exit criteria
+
+- `novahiz init --json` has `failed: []`
+- `novahiz-docs/` has four files with no remaining fill-in comments on architecture/conventions/standards
+- `project-memory/` has at least one slot
+- Cleanup either applied with consent or left unapplied on purpose
+
+## Pitfalls
+
+- Running `novahiz init` thinking it installs the global tool (`setup` does that).
+- Filling templates with guessed architecture instead of a real read.
+- Deleting cleanup candidates without showing the list.
+- Duplicating content that already belongs in `novahiz-docs` update / converge.