novahiz 0.9.6 → 0.9.8

package/CHANGELOG.md

@@ -5,6 +5,58 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.9.8] - 2026-10-15
+
+### Removed
+
+- **The 7 `eas-*` skills from the catalogue** - `test` and `devops` listed them
+  as `defaultSkills` (`eas-app-stores`, `eas-hosting`, `eas-observe`,
+  `eas-simulator`, `eas-update`, `eas-update-insights`, `eas-workflows`) while
+  the expo pack deliberately excludes them: `providers.json` says so in the
+  provider's own purpose. No provider could install a single one, so `doctor`
+  named them and `novahiz deps --install` returned `install: []`. 0.9.5 made
+  that row tell the truth instead of blaming the reader; the references
+  themselves stayed, and the row reports without blocking, which is why nothing
+  had failed since. `referencedSkills` now spans 51 ids and none of them is
+  undeliverable, so `doctor` reports `51 present` with no caveat. The seven
+  inert `overrides.json` entries went with them; the `devops` keywords `eas`,
+  `eas build` and `eas update` stay, since they route a deployment question to
+  a roadmap that still applies.
+
+### Added
+
+- **A test holding the catalogue to that invariant** -
+  `undeliverableReferences(spec, packageRootDir)` is exported from
+  `doctor.ts`, and `tests/doctor-referenced-skills.test.ts` runs it against the
+  shipped catalogue: it must return `[]`, no `defaultSkills` may carry an
+  `eas-*`, and a reintroduced one must be named. Checked by injection: putting
+  `eas-simulator` back into `test.defaultSkills` turns both assertions red.
+
+## [0.9.7] - 2026-10-15
+
+### Added
+
+- **Project docs mirrored into the vault** - `novahiz init` now fills the
+  `<Domain>/<Branch>/docs/<slug>/` folder it creates instead of leaving it
+  empty: a new `Obsidian project docs` step copies `ARCHITECTURE.md`,
+  `CONVENTIONS.md`, `DECISIONS.md` and `STANDARDS.md` verbatim from
+  `novahiz-docs/`, and `novahiz autodocs --flush` re-mirrors them on every
+  flush, reported as a `Vault` row. The folder previously appeared holding only
+  a `_MOC.md` - the `docs` leaf of the catalogue existed and nothing ever wrote
+  into it. The copy is a **mirror, never the source**: every note reflects a
+  file that still lives in the project, which is what makes an overwriting flush
+  safe instead of a second history to maintain. Guards, none silent: no
+  `vault.json` binding, a binding outside the catalogue, or a target folder
+  `project-init` never created all skip with advice and invent nothing (contract
+  1); a doc file absent from the project is reported as `absent`, never
+  manufactured; a dry-run writes neither note nor log entry. Each real write
+  appends one `- HH:MM -` line under the day's heading of `log.md` through
+  `appendLogLine` - contract 8's "log the operation" was an instruction for the
+  agent and not code, so it only happened when someone remembered it. The
+  project name now resolves through a single `readProjectName` helper shared by
+  `init` and `flush`, so the seed and the refresh cannot slugify to different
+  folders.
+
 ## [0.9.6] - 2026-10-15
 
 ### Added

package/catalog/categories.json

@@ -554,8 +554,7 @@
     "defaultSkills": [
       "flutter-add-widget-test",
       "dart-add-unit-test",
-      "expo-skill-eval",
-      "eas-simulator"
+      "expo-skill-eval"
     ],
     "roadmap": {
       "id": "testing",
@@ -1329,14 +1328,7 @@
       "tag a version",
       "changelog"
     ],
-    "defaultSkills": [
-      "eas-workflows",
-      "eas-app-stores",
-      "eas-hosting",
-      "eas-observe",
-      "eas-update",
-      "eas-update-insights"
-    ],
+    "defaultSkills": [],
     "roadmap": {
       "id": "devops",
       "steps": [

package/catalog/overrides.json

@@ -634,83 +634,6 @@
         "docs-writing"
       ]
     },
-    "eas-app-stores": {
-      "power": 4,
-      "stars": null,
-      "tags": [
-        "eas",
-        "expo"
-      ],
-      "categories": [
-        "expo"
-      ]
-    },
-    "eas-hosting": {
-      "power": 4,
-      "stars": null,
-      "tags": [
-        "eas",
-        "expo"
-      ],
-      "categories": [
-        "expo"
-      ]
-    },
-    "eas-observe": {
-      "power": 4,
-      "stars": null,
-      "tags": [
-        "eas",
-        "expo"
-      ],
-      "categories": [
-        "expo"
-      ]
-    },
-    "eas-simulator": {
-      "power": 4,
-      "stars": null,
-      "tags": [
-        "eas",
-        "expo"
-      ],
-      "categories": [
-        "expo"
-      ]
-    },
-    "eas-update": {
-      "power": 4,
-      "stars": null,
-      "tags": [
-        "eas",
-        "expo"
-      ],
-      "categories": [
-        "expo"
-      ]
-    },
-    "eas-update-insights": {
-      "power": 4,
-      "stars": null,
-      "tags": [
-        "eas",
-        "expo"
-      ],
-      "categories": [
-        "expo"
-      ]
-    },
-    "eas-workflows": {
-      "power": 4,
-      "stars": null,
-      "tags": [
-        "eas",
-        "expo"
-      ],
-      "categories": [
-        "expo"
-      ]
-    },
     "expo-animation": {
       "power": 4,
       "stars": null,

package/dist/autodocs.js

@@ -56,6 +56,22 @@ export function configPath(cwd) {
 export function statePath(cwd) {
     return join(projectDir(cwd), STATE_NAME);
 }
+/** Nom du projet côté module pur, sans dépendre de `commands/init.ts` (qui
+ *  importe déjà ce fichier : importer `detectProject` créerait un cycle).
+ *  package.json `name`, sinon le dernier segment du cwd — la même chute que
+ *  `detectProject`, volontairement unique : l'init et le flush doivent produire
+ *  le même slug, sans quoi la copie vault partirait dans un autre dossier. */
+export function readProjectName(cwd) {
+    try {
+        const pkg = JSON.parse(readFileSync(join(cwd, "package.json"), "utf8"));
+        if (typeof pkg.name === "string" && pkg.name.trim().length > 0)
+            return pkg.name;
+    }
+    catch {
+        // name falls back to the folder below, exactly as detectProject does
+    }
+    return cwd.split(/[\\/]/).filter(Boolean).pop() ?? "project";
+}
 function ensureDir(path) {
     if (!existsSync(path))
         mkdirSync(path, { recursive: true });

package/dist/commands/autodocs.js

@@ -1,8 +1,9 @@
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
-import { autoDocsEnabled, clearDirty, dateStamp, isMajorPath, markDirty, readProjectConfig, readState, upsertChangesSection, writeProjectConfig } from "../autodocs.js";
+import { autoDocsEnabled, clearDirty, dateStamp, isMajorPath, markDirty, readProjectConfig, readProjectName, readState, upsertChangesSection, writeProjectConfig } from "../autodocs.js";
 import { emit, flagOn } from "./context.js";
 import { memoryRoot, writeEntry } from "../memory.js";
+import { syncProjectDocsToVault } from "./second-memory.js";
 import * as ui from "../render.js";
 const MAX_DOC_PATHS = 12;
 const ARCHITECTURE = "novahiz-docs/ARCHITECTURE.md";
@@ -26,6 +27,7 @@ function skipResult(reason, paths = []) {
         docsPath: null,
         docsUpdated: false,
         memorySlot: null,
+        vaultDocs: null,
         paths,
         pending: state.pending.length,
         lastSync: state.lastSync
@@ -76,6 +78,20 @@ export function flushAutoDocs(cwd) {
         const paths = state.pending;
         const docs = flushDocs(cwd, paths);
         const memorySlot = flushMemory(cwd, paths);
+        // Volet « miroir » : la doc fraîchement écrite est répercutée dans
+        // <Domaine>/<Branche>/docs/<slug>/. Volontairement encapsulé plutôt que
+        // laissé dans le try du flush : docs et slot sont déjà écrits à ce point,
+        // et faire échouer le flush ici laisserait un état sale et un slot
+        // dupliqué à la prochaine exécution. Le vault est un miroir dérivé, la
+        // source de vérité reste le projet — il n'a pas le droit de le casser.
+        let vaultTarget = null;
+        try {
+            const vault = syncProjectDocsToVault(readProjectName(cwd), join(cwd, "novahiz-docs"), true);
+            vaultTarget = vault.target.length > 0 && vault.copied.length > 0 ? vault.target : null;
+        }
+        catch {
+            vaultTarget = null;
+        }
         const next = clearDirty(cwd);
         return {
             status: "flushed",
@@ -83,6 +99,7 @@ export function flushAutoDocs(cwd) {
             docsPath: docs.path,
             docsUpdated: docs.updated,
             memorySlot,
+            vaultDocs: vaultTarget,
             paths,
             pending: next.pending.length,
             lastSync: next.lastSync
@@ -95,6 +112,7 @@ export function flushAutoDocs(cwd) {
             docsPath: null,
             docsUpdated: false,
             memorySlot: null,
+            vaultDocs: null,
             paths: state.pending,
             pending: state.pending.length,
             lastSync: state.lastSync
@@ -116,6 +134,7 @@ function markFromArgs(cwd, mark, positionals) {
             docsPath: null,
             docsUpdated: false,
             memorySlot: null,
+            vaultDocs: null,
             paths: [],
             pending: readState(cwd).pending.length,
             lastSync: readState(cwd).lastSync
@@ -140,6 +159,7 @@ function markFromArgs(cwd, mark, positionals) {
             docsPath: null,
             docsUpdated: false,
             memorySlot: null,
+            vaultDocs: null,
             paths: rejected,
             pending: state.pending.length,
             lastSync: state.lastSync
@@ -153,6 +173,7 @@ function markFromArgs(cwd, mark, positionals) {
         docsPath: null,
         docsUpdated: false,
         memorySlot: null,
+        vaultDocs: null,
         paths: accepted,
         pending: state.pending.length,
         lastSync: state.lastSync
@@ -204,7 +225,8 @@ export function commandAutodocs(parsed) {
                 ["Action", outcome.status],
                 ["Reason", outcome.reason],
                 ["Docs", outcome.docsPath ? `${outcome.docsPath}${outcome.docsUpdated ? " updated" : " unchanged"}` : "n/a"],
-                ["Memory", outcome.memorySlot ?? "n/a"]
+                ["Memory", outcome.memorySlot ?? "n/a"],
+                ["Vault", outcome.vaultDocs ?? "n/a"]
             ]));
             lines.push("", outcome.status === "failed" ? ui.style("red", outcome.reason) : ui.style("green", outcome.reason));
         }

package/dist/commands/doctor.js

@@ -443,22 +443,15 @@ function referencedSkills(spec) {
  *  `indexSkills` is null when the index is unreadable — the index check already
  *  reports that, so the row stays quiet instead of double-failing.
  *  Only skills the package ships (packageRoot/skills) can make a fresh install
- *  broken. The remaining references — the dart/eas/expo/flutter packs and
- *  impeccable — are optional delivery downloaded on request and are simply not
+ *  broken. The remaining references, the dart/expo/flutter packs and
+ *  impeccable, are optional delivery downloaded on request and are simply not
  *  present on a machine that never asked for them; the gate already degrades
  *  them to "not enforced". Blocking on them turned every healthy fresh install
  *  red (`missing from index: dart-...` right after novahiz-install --yes). */
 export function referencedSkillsCheck(spec, indexSkills, packageRootDir) {
     const referenced = referencedSkills(spec);
     const absent = indexSkills ? referenced.filter((id) => !indexSkills.has(id)) : [];
-    const shipped = new Set();
-    const shippedDir = join(packageRootDir, "skills");
-    if (existsSync(shippedDir)) {
-        for (const entry of readdirSync(shippedDir, { withFileTypes: true })) {
-            if (entry.isDirectory())
-                shipped.add(entry.name);
-        }
-    }
+    const shipped = shippedSkills(packageRootDir);
     const absentShipped = absent.filter((id) => shipped.has(id));
     const absentPack = absent.filter((id) => !shipped.has(id));
     // Only promise the update command when a pack can actually deliver what is
@@ -493,11 +486,14 @@ export function referencedSkillsCheck(spec, indexSkills, packageRootDir) {
  *  argv: an explicit `--skill a b c` names them, and `--skill *` delivers the
  *  whole repo, whose ids start with the repo's leading segment with any hyphen
  *  suffix dropped (`flutter/skills` -> `flutter-`, `dart-lang/skills` ->
- *  `dart-`). Measured 2026-10-15: the 7 skills doctor reported as "pack skills
- *  not installed" are `eas-*`, referenced as `defaultSkills` by the `test` and
- *  `devops` categories while no provider ships them, so
- *  "run /novahiz-skills-update, or novahiz deps --install" could not have
- *  installed a single one. Advice no command can honour is a defect. */
+ *  `dart-`). Measured 2026-10-15 on the 0.9.5 install: the 7 skills doctor
+ *  reported as "pack skills not installed" were `eas-*`, referenced as
+ *  `defaultSkills` by `test` and `devops` while the expo pack deliberately
+ *  excludes them, so "run /novahiz-skills-update, or novahiz deps --install"
+ *  could not have installed a single one. Advice no command can honour is a
+ *  defect. Those references are gone from the catalog; the guard stays, since
+ *  the same situation reappears whenever a pack is disabled or its `--skill`
+ *  list stops naming an id the catalog still asks for. */
 function packDelivery(spec) {
     const exact = new Set();
     const prefixes = [];
@@ -526,6 +522,27 @@ function packDelivery(spec) {
     }
     return { exact, prefixes };
 }
+/** Skill ids the package itself carries in `packageRootDir/skills`. */
+function shippedSkills(packageRootDir) {
+    const shipped = new Set();
+    const shippedDir = join(packageRootDir, "skills");
+    if (existsSync(shippedDir)) {
+        for (const entry of readdirSync(shippedDir, { withFileTypes: true })) {
+            if (entry.isDirectory())
+                shipped.add(entry.name);
+        }
+    }
+    return shipped;
+}
+/** Referenced skill ids nothing in the system can supply: the package ships
+ *  none of them and no enabled pack can install them. Exported so the catalog
+ *  is held to this invariant in tests, since the row above reports it without
+ *  blocking and therefore never failed on it. */
+export function undeliverableReferences(spec, packageRootDir) {
+    const shipped = shippedSkills(packageRootDir);
+    const { exact, prefixes } = packDelivery(spec);
+    return referencedSkills(spec).filter((id) => !shipped.has(id) && !exact.has(id) && !prefixes.some((prefix) => id.startsWith(prefix)));
+}
 /** Impeccable design-context checks: PRODUCT.md and DESIGN.md resolution
  *  (root -> .agents/context -> docs/). Rows appear only when the impeccable
  *  skill is installed (opt-in) and are never blocking: a missing record is a

package/dist/commands/init.js

@@ -5,8 +5,9 @@ import { loadSpec, NovahizHome } from "../spec.js";
 import { loadInstalledSkills } from "../catalog.js";
 import { findContextFile } from "../impeccable.js";
 import { ensureMemoryRoot, memoryRoot, writeEntry } from "../memory.js";
+import { readProjectName } from "../autodocs.js";
 import { ensureProjectAutoDocsConfig } from "./autodocs.js";
-import { projectInit } from "./second-memory.js";
+import { projectInit, syncProjectDocsToVault } from "./second-memory.js";
 import * as ui from "../render.js";
 const DOC_FILES = ["ARCHITECTURE.md", "CONVENTIONS.md", "DECISIONS.md", "STANDARDS.md"];
 const CLEANUP_PATTERNS = [
@@ -56,7 +57,7 @@ function detectProject(cwd) {
     if (existsSync(join(cwd, "README.md")))
         markers.push("README.md");
     if (!name) {
-        name = cwd.split(/[\\/]/).filter(Boolean).pop() ?? "project";
+        name = readProjectName(cwd);
     }
     return { kind, name, version, markers };
 }
@@ -297,6 +298,53 @@ function obsidianProject(dryRun, project) {
         detail: created > 0 ? `${where}: ${created} folder(s) + binding` : `${where}: already initialized`
     };
 }
+/** Étape de suite : la place existe-t-elle, on la remplit.
+ *  Recopie `<projet>/novahiz-docs/` dans le `<docs>/<slug>/` du vault. Elle
+ *  hérite du verdict d'`obsidianProject` au lieu d'en dériver un second : si le
+ *  dossier projet n'a pas pu être posé, il n'y a aucune cible légitime et cette
+ *  étape se tait plutôt que d'en tenter une. Sans vault, sans binding ou sans
+ *  dossier cible, elle saute avec le conseil exact ; aucun dossier n'est
+ *  inventé (contrainte 1) et aucune copie ne part dans le vide. */
+function obsidianDocs(cwd, dryRun, project, folder) {
+    const label = "Obsidian project docs";
+    if (folder.status !== "created" && folder.status !== "skipped") {
+        return { id: "obsidian-docs", label, status: "skipped", detail: `project folder not ready — see "${folder.label}"` };
+    }
+    const name = project.name.trim();
+    if (name.length === 0) {
+        return { id: "obsidian-docs", label, status: "skipped", detail: "no project name detected (package.json)" };
+    }
+    let result;
+    try {
+        result = syncProjectDocsToVault(name, join(cwd, "novahiz-docs"), !dryRun);
+    }
+    catch (error) {
+        return { id: "obsidian-docs", label, status: "failed", detail: String(error).slice(0, 160) };
+    }
+    const where = result.target.length > 0 ? result.target : `${result.domain}/${result.branch}/${result.slug}`;
+    if (result.warnings.length > 0 && result.copied.length === 0) {
+        return {
+            id: "obsidian-docs",
+            label,
+            status: "skipped",
+            detail: `${where}: ${result.warnings.join("; ").slice(0, 160)}`,
+            advice: result.target.length > 0 ? undefined : `Link it: novahiz second-memory project-init --name <project> --branch Domain/Branch --apply`
+        };
+    }
+    const counts = `${result.copied.length} file(s)${result.absent.length > 0 ? `, ${result.absent.length} absent` : ""}`;
+    if (dryRun) {
+        return { id: "obsidian-docs", label, status: "dry-run", detail: `${where}: ${counts} would be copied` };
+    }
+    if (result.warnings.length > 0) {
+        return { id: "obsidian-docs", label, status: "failed", detail: `${where}: ${result.warnings.join("; ").slice(0, 160)}` };
+    }
+    return {
+        id: "obsidian-docs",
+        label,
+        status: result.copied.length > 0 ? "created" : "skipped",
+        detail: result.copied.length > 0 ? `${where}: ${counts} mirrored` : `${where}: nothing to copy`
+    };
+}
 export function commandInit(parsed) {
     const cwd = process.cwd();
     const home = NovahizHome();
@@ -336,7 +384,9 @@ export function commandInit(parsed) {
             });
         }
         steps.push(impeccableContext(home, cwd, dryRun));
-        steps.push(obsidianProject(dryRun, project));
+        const folder = obsidianProject(dryRun, project);
+        steps.push(folder);
+        steps.push(obsidianDocs(cwd, dryRun, project, folder));
     }
     let cleanup = [];
     let cleanupApplied = 0;

package/dist/commands/second-memory.js

@@ -2159,6 +2159,123 @@ export function projectInit(name, branchFlag, apply) {
     }
     return result;
 }
+// --- project docs sync ---------------------------------------------------------
+/** Les quatre fichiers que `novahiz init` pose dans `<projet>/novahiz-docs/` et
+ *  que la copie vault reflète. Liste fermée, même ordre canonique que le
+ *  template : on ne recopie pas n'importe quel fichier trouvé dans le dossier. */
+export const PROJECT_DOC_FILES = ["ARCHITECTURE.md", "CONVENTIONS.md", "DECISIONS.md", "STANDARDS.md"];
+/** Append-only, une entrée par jour : `- HH:MM - message` sous `## YYYY-MM-DD`.
+ *  Même forme que l'entrée posée à l'initialisation du vault (L1036), pour que
+ *  le journal reste lisible comme un seul flux. Une entrée est posée uniquement
+ *  en mode apply : la trace d'un dry-run est un non-événement. */
+function appendLogLine(vault, message) {
+    const now = new Date();
+    const date = now.toISOString().slice(0, 10);
+    const time = now.toTimeString().slice(0, 5);
+    const entry = `- ${time} - ${message}`;
+    const path = join(vault, LOG_FILE);
+    if (!existsSync(path)) {
+        writeFileSync(path, `# Second Memory Log\n\nAppend-only. Never delete entries.\n\n## ${date}\n${entry}\n`, "utf8");
+        return;
+    }
+    const body = readFileSync(path, "utf8").replace(/\s*$/, "");
+    // log.md est chronologique : la section du jour, si elle existe, est la dernière.
+    const marker = "## " + date;
+    const lastHeading = body.slice(body.lastIndexOf("\n## ") + 1);
+    const todayIsLast = lastHeading.startsWith(marker);
+    const head = todayIsLast ? body + "\n" : body + "\n\n" + marker + "\n";
+    writeFileSync(path, head + entry + "\n", "utf8");
+}
+/** Copie la documentation d'un projet vers `<Domaine>/<Branche>/docs/<slug>/`.
+ *
+ *  Volet « écriture automatique dans le vault » de `novahiz init` et de
+ *  `autodocs flush`. La copie est **un miroir, jamais la source** : chaque note
+ *  reflète un fichier qui existe toujours dans `<projet>/novahiz-docs/`, donc un
+ *  écrasement ne détruit rien qu'on ne puisse régénérer — c'est ce qui rend
+ *  l'absence de backup défendable ici, contrairement à une note écrite à la main.
+ *
+ *  Garde-fous, tous explicites et non silencieux :
+ *  - aucun binding → on ne devine pas de branche, on renvoie le conseil ;
+ *  - branche absente du catalogue → le vault a bougé, on ne crée rien ;
+ *  - dossier cible absent → `project-init` crée la chaîne, on ne l'invente pas
+ *    (contrainte 1) ;
+ *  - fichier absent du projet → reporté dans `absent`, pas d'étublage.
+ *
+ *  En dry-run (`apply: false`), rien n'est écrit — ni note, ni entrée de log ;
+ *  `copied` liste alors ce qui *serait* copié. */
+export function syncProjectDocsToVault(name, docsDir, apply) {
+    const trimmed = (name ?? "").trim();
+    const slug = projectFolder(trimmed, "");
+    const result = { apply, project: trimmed, slug, domain: "", branch: "", target: "", copied: [], absent: [], warnings: [] };
+    if (slug.length === 0) {
+        result.warnings.push("empty project name after slugify — pass a real project name");
+        return result;
+    }
+    const vault = vaultPath();
+    if (!existsSync(vault)) {
+        result.warnings.push("vault not found — run `novahiz second-memory init` first");
+        return result;
+    }
+    if (!existsSync(docsDir)) {
+        result.warnings.push(`no project docs at ${docsDir} — run \`novahiz init\` to create them`);
+        return result;
+    }
+    const binding = readBinding(slug);
+    if (!binding) {
+        result.warnings.push(`no vault binding for "${slug}" — run \`novahiz second-memory project-init --name ${slug} --branch Domain/Branch\``);
+        return result;
+    }
+    const domainNode = findDomain(binding.domain);
+    const branchNode = domainNode?.children?.find((node) => node.name === binding.branch) ?? null;
+    if (!domainNode || !branchNode) {
+        result.warnings.push(`binding points to an unknown branch ${binding.domain}/${binding.branch} — re-run project-init`);
+        return result;
+    }
+    result.domain = domainNode.name;
+    result.branch = branchNode.name;
+    const leaf = (branchNode.children ?? []).find((node) => node.kind === "docs");
+    if (!leaf) {
+        result.warnings.push(`branch ${domainNode.name}/${branchNode.name} carries no docs leaf`);
+        return result;
+    }
+    const target = `${domainNode.name}/${branchNode.name}/${leaf.name}/${slug}`;
+    if (!existsSync(join(vault, target))) {
+        result.warnings.push(`target folder missing: ${target} — run \`novahiz second-memory project-init --name ${slug}\``);
+        return result;
+    }
+    result.target = target;
+    for (const file of PROJECT_DOC_FILES) {
+        const source = join(docsDir, file);
+        let content;
+        try {
+            content = readFileSync(source, "utf8");
+        }
+        catch {
+            result.absent.push(file);
+            continue;
+        }
+        if (!apply) {
+            result.copied.push(file);
+            continue;
+        }
+        try {
+            writeFileSync(join(vault, target, file), content, "utf8");
+            result.copied.push(file);
+        }
+        catch (error) {
+            result.warnings.push(`${file}: ${String(error).slice(0, 200)}`);
+        }
+    }
+    if (apply && result.copied.length > 0) {
+        try {
+            appendLogLine(vault, `project docs synced: ${target} (${result.copied.length} file(s))`);
+        }
+        catch (error) {
+            result.warnings.push(`log: ${String(error).slice(0, 160)}`);
+        }
+    }
+    return result;
+}
 function secondMemoryProjectInit(parsed) {
     const apply = flagOn(parsed, "apply");
     const name = String(parsed.flags.name ?? "").trim();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "novahiz",
-  "version": "0.9.6",
+  "version": "0.9.8",
   "description": "Enforce AI agent skills before every file edit: prompt classifier, skill catalog, and pre-edit gate.",
   "type": "module",
   "license": "Apache-2.0",

package/skills/novahiz-second-memory/SKILL.md

@@ -5,7 +5,9 @@ description: |
   FIXED, predefined arborescence: root INDEX.md, a _MOC.md per folder, 11 domains with
   predefined branches and memory/docs/journal/decisions leaves. `second-memory project-init`
   gives a new project its docs/journal/decisions folders (never memory: it stays local) and
-  binds it to a branch; other folders appear on first write, never speculatively.
+  binds it to a branch; `novahiz init` seeds that docs folder and `autodocs --flush`
+  re-mirrors the project's four novahiz-docs files into it. Other folders appear on first
+  write, never speculatively.
   `second-memory doctor` audits and repairs the vault, installs the 10 mandatory plugins.
   Use when the user writes to, organizes, audits, repairs or syncs the second-memory vault,
   or needs past context: search the vault first (`novahiz second-memory search "<terms>"`)
@@ -29,11 +31,16 @@ is predefined, and every write lands in a predefined spot.
 
 ## The contract (non-negotiable)
 
-1. **Fixed arborescence** — content lives only inside the tree below. Nothing is ever
-   written at the vault root, and no top-level folder is invented.
+1. **Fixed arborescence** — content lives only inside the tree below. No note is ever
+   written at the vault root: only the three system files live there (`INDEX.md`,
+   `STRUCTURE.md`, `log.md`). No top-level folder is invented.
 2. **`INDEX.md` is the single entry point** — categories → index, subcategories →
-   category, subfolders → parent. It links exactly the active domains, nothing else.
-3. **Every folder owns a `_MOC.md`** — it indexes its children; children link back to it.
+   category, subfolders → parent. Its `## Categories` section carries exactly the active
+   domains — never more, never fewer. The `## System` section below it is fixed and lists
+   the system folders; the audit reads `## Categories` only.
+3. **Every content folder owns a `_MOC.md`** — it indexes its children; children link back
+   to it. The four system folders (`Inbox/`, `Archive/`, `Templates/`, `Excalidraw/`) sit
+   outside the graph: they carry no `_MOC.md`, and `doctor` never asks for one.
 4. **Auto-create** — a write never fails on a missing folder: the whole path is created
    (folder → `_MOC.md` → parent link → `INDEX.md` link) before the note is written.
 5. **A domain activates whole** — the first write that routes to a domain materializes its
@@ -79,6 +86,11 @@ second-memory/
 
 Full per-domain detail (MOC titles, leaves, what belongs where): `references/arborescence.md`.
 
+The four system folders sit outside the graph: they carry no `_MOC.md` and `doctor` never
+audits them. Routing reaches only `Inbox/`, as the parking spot for a note with no domain
+signal; `Archive/`, `Templates/` and `Excalidraw/` are never routing targets — the last one
+holds the plugin's own drawing data.
+
 Leaves mean:
 
 - **`memory/`** — evergreen personal notes, split into one subfolder per project
@@ -122,6 +134,19 @@ memory stays local. Dry-run is the default; `novahiz init` runs the same logic a
 `Obsidian project folder` step. Nothing else creates folders speculatively: without a
 write, a folder does not exist.
 
+`docs/<project>/` is not left empty: `novahiz init` fills it in an `Obsidian project docs`
+step, and `novahiz autodocs --flush` re-mirrors on every flush. Copied verbatim from the
+project's `novahiz-docs/`: `ARCHITECTURE.md`, `CONVENTIONS.md`, `DECISIONS.md`,
+`STANDARDS.md`. Those notes are **a mirror, never the source** — each one reflects a file
+that still lives in the project, which is why the flush overwrites in place and takes no
+backup: the content is regenerated, not preserved. Two consequences worth stating. A hand
+edit to a mirrored note is lost on the next flush — edit the project file, not the copy.
+And the seed refuses to guess: no `vault.json` binding, a binding whose branch has left
+the catalogue, a branch carrying no `docs` leaf, or a folder `project-init` never created
+each skip with its advice printed, and a document missing from the project is reported
+absent rather than manufactured. Every real write appends one `- HH:MM -` line to
+`log.md` under the day's heading; a dry-run leaves no trace at all.
+
 ## INDEX.md format
 
 ```markdown
@@ -142,6 +167,7 @@ Personal knowledge vault. Start here.
 - [[Inbox]]
 - [[Archive]]
 - [[Templates]]
+- [[Excalidraw]]
 ```
 
 `## Categories` is machine-managed: exactly the active domains, in catalog order.
@@ -198,6 +224,7 @@ Novahiz home. Dry-run is the default on every mutating subcommand.
 | `project-init` | give a project its folders (`docs/journal/decisions/<project>/`) and bind it to a branch — dry-run default |
 | `sync` | retire the old memory mirror: list/archive the vault notes that were slot copies (memory stays local) |
 | `status` | note counts, categories, open issues, resolved memory root |
+| `search` | full-text search across the vault notes (`second-memory search "<terms>"`) |
 
 `doctor` checks, in order: `vault`, `skeleton`, `arborescence`, `outside-tree folders`,
 `links`, `plugins`, `memory`. It exits **1 while issues remain** and 0 when the vault is
@@ -277,5 +304,8 @@ the `log.md` format.
 - **Memory**: project memory stays local — `memory_search` / `memory_get` read the slots,
   `memory_write` appends them; nothing is mirrored into the vault. A legacy note carrying
   `novahiz_slot_id` is a mirror copy; `sync --apply` archives it (§3).
-- **Docs**: vault notes can cite novahiz-docs as `novahiz-docs/<library>@<version>`.
+- **Docs**: unlike memory, project *documentation* is mirrored — `novahiz init` seeds
+  `<Domain>/<Branch>/docs/<slug>/` from the project's `novahiz-docs/`, and
+  `novahiz autodocs --flush` refreshes it (a `Vault` row reports the target). Vault notes
+  can also cite novahiz-docs as `novahiz-docs/<library>@<version>`.
 - **Ledger**: structural changes to the vault are logged in the novahiz ledger (task todos).

package/src/autodocs.ts

@@ -74,6 +74,21 @@ export function statePath(cwd: string): string {
   return join(projectDir(cwd), STATE_NAME);
 }
 
+/** Nom du projet côté module pur, sans dépendre de `commands/init.ts` (qui
+ *  importe déjà ce fichier : importer `detectProject` créerait un cycle).
+ *  package.json `name`, sinon le dernier segment du cwd — la même chute que
+ *  `detectProject`, volontairement unique : l'init et le flush doivent produire
+ *  le même slug, sans quoi la copie vault partirait dans un autre dossier. */
+export function readProjectName(cwd: string): string {
+  try {
+    const pkg = JSON.parse(readFileSync(join(cwd, "package.json"), "utf8")) as { name?: unknown };
+    if (typeof pkg.name === "string" && pkg.name.trim().length > 0) return pkg.name;
+  } catch {
+    // name falls back to the folder below, exactly as detectProject does
+  }
+  return cwd.split(/[\\/]/).filter(Boolean).pop() ?? "project";
+}
+
 function ensureDir(path: string): void {
   if (!existsSync(path)) mkdirSync(path, { recursive: true });
 }

package/src/commands/autodocs.ts

@@ -7,12 +7,14 @@ import {
   isMajorPath,
   markDirty,
   readProjectConfig,
+  readProjectName,
   readState,
   upsertChangesSection,
   writeProjectConfig
 } from "../autodocs.ts";
 import { emit, flagOn, type Parsed } from "./context.ts";
 import { memoryRoot, writeEntry } from "../memory.ts";
+import { syncProjectDocsToVault } from "./second-memory.ts";
 import * as ui from "../render.ts";
 
 const MAX_DOC_PATHS = 12;
@@ -26,6 +28,9 @@ export type FlushOutcome = {
   docsPath: string | null;
   docsUpdated: boolean;
   memorySlot: string | null;
+  /** Rel de la copie vault du projet, ou null quand rien n'a été répercuté :
+   *  aucun binding, dossier cible absent, ou aucun fichier à recopier. */
+  vaultDocs: string | null;
   paths: string[];
   pending: number;
   lastSync: string | null;
@@ -50,6 +55,7 @@ function skipResult(reason: string, paths: string[] = []): FlushOutcome {
     docsPath: null,
     docsUpdated: false,
     memorySlot: null,
+    vaultDocs: null,
     paths,
     pending: state.pending.length,
     lastSync: state.lastSync
@@ -98,6 +104,19 @@ export function flushAutoDocs(cwd: string): FlushOutcome {
     const paths = state.pending;
     const docs = flushDocs(cwd, paths);
     const memorySlot = flushMemory(cwd, paths);
+    // Volet « miroir » : la doc fraîchement écrite est répercutée dans
+    // <Domaine>/<Branche>/docs/<slug>/. Volontairement encapsulé plutôt que
+    // laissé dans le try du flush : docs et slot sont déjà écrits à ce point,
+    // et faire échouer le flush ici laisserait un état sale et un slot
+    // dupliqué à la prochaine exécution. Le vault est un miroir dérivé, la
+    // source de vérité reste le projet — il n'a pas le droit de le casser.
+    let vaultTarget: string | null = null;
+    try {
+      const vault = syncProjectDocsToVault(readProjectName(cwd), join(cwd, "novahiz-docs"), true);
+      vaultTarget = vault.target.length > 0 && vault.copied.length > 0 ? vault.target : null;
+    } catch {
+      vaultTarget = null;
+    }
     const next = clearDirty(cwd);
     return {
       status: "flushed",
@@ -105,6 +124,7 @@ export function flushAutoDocs(cwd: string): FlushOutcome {
       docsPath: docs.path,
       docsUpdated: docs.updated,
       memorySlot,
+      vaultDocs: vaultTarget,
       paths,
       pending: next.pending.length,
       lastSync: next.lastSync
@@ -116,6 +136,7 @@ export function flushAutoDocs(cwd: string): FlushOutcome {
       docsPath: null,
       docsUpdated: false,
       memorySlot: null,
+      vaultDocs: null,
       paths: state.pending,
       pending: state.pending.length,
       lastSync: state.lastSync
@@ -139,6 +160,7 @@ function markFromArgs(cwd: string, mark: string | boolean, positionals: string[]
       docsPath: null,
       docsUpdated: false,
       memorySlot: null,
+      vaultDocs: null,
       paths: [],
       pending: readState(cwd).pending.length,
       lastSync: readState(cwd).lastSync
@@ -162,6 +184,7 @@ function markFromArgs(cwd: string, mark: string | boolean, positionals: string[]
       docsPath: null,
       docsUpdated: false,
       memorySlot: null,
+      vaultDocs: null,
       paths: rejected,
       pending: state.pending.length,
       lastSync: state.lastSync
@@ -176,6 +199,7 @@ function markFromArgs(cwd: string, mark: string | boolean, positionals: string[]
     docsPath: null,
     docsUpdated: false,
     memorySlot: null,
+    vaultDocs: null,
     paths: accepted,
     pending: state.pending.length,
     lastSync: state.lastSync
@@ -233,7 +257,8 @@ export function commandAutodocs(parsed: Parsed): void {
           ["Action", outcome.status],
           ["Reason", outcome.reason],
           ["Docs", outcome.docsPath ? `${outcome.docsPath}${outcome.docsUpdated ? " updated" : " unchanged"}` : "n/a"],
-          ["Memory", outcome.memorySlot ?? "n/a"]
+          ["Memory", outcome.memorySlot ?? "n/a"],
+          ["Vault", outcome.vaultDocs ?? "n/a"]
         ])
       );
       lines.push(

package/src/commands/doctor.ts

@@ -439,8 +439,8 @@ function referencedSkills(spec: ReturnType<typeof loadSpec>): string[] {
  *  `indexSkills` is null when the index is unreadable — the index check already
  *  reports that, so the row stays quiet instead of double-failing.
  *  Only skills the package ships (packageRoot/skills) can make a fresh install
- *  broken. The remaining references — the dart/eas/expo/flutter packs and
- *  impeccable — are optional delivery downloaded on request and are simply not
+ *  broken. The remaining references, the dart/expo/flutter packs and
+ *  impeccable, are optional delivery downloaded on request and are simply not
  *  present on a machine that never asked for them; the gate already degrades
  *  them to "not enforced". Blocking on them turned every healthy fresh install
  *  red (`missing from index: dart-...` right after novahiz-install --yes). */
@@ -451,13 +451,7 @@ export function referencedSkillsCheck(
 ): DoctorCheck {
   const referenced = referencedSkills(spec);
   const absent = indexSkills ? referenced.filter((id) => !indexSkills.has(id)) : [];
-  const shipped = new Set<string>();
-  const shippedDir = join(packageRootDir, "skills");
-  if (existsSync(shippedDir)) {
-    for (const entry of readdirSync(shippedDir, { withFileTypes: true })) {
-      if (entry.isDirectory()) shipped.add(entry.name);
-    }
-  }
+  const shipped = shippedSkills(packageRootDir);
   const absentShipped = absent.filter((id) => shipped.has(id));
   const absentPack = absent.filter((id) => !shipped.has(id));
   // Only promise the update command when a pack can actually deliver what is
@@ -491,11 +485,14 @@ export function referencedSkillsCheck(
  *  argv: an explicit `--skill a b c` names them, and `--skill *` delivers the
  *  whole repo, whose ids start with the repo's leading segment with any hyphen
  *  suffix dropped (`flutter/skills` -> `flutter-`, `dart-lang/skills` ->
- *  `dart-`). Measured 2026-10-15: the 7 skills doctor reported as "pack skills
- *  not installed" are `eas-*`, referenced as `defaultSkills` by the `test` and
- *  `devops` categories while no provider ships them, so
- *  "run /novahiz-skills-update, or novahiz deps --install" could not have
- *  installed a single one. Advice no command can honour is a defect. */
+ *  `dart-`). Measured 2026-10-15 on the 0.9.5 install: the 7 skills doctor
+ *  reported as "pack skills not installed" were `eas-*`, referenced as
+ *  `defaultSkills` by `test` and `devops` while the expo pack deliberately
+ *  excludes them, so "run /novahiz-skills-update, or novahiz deps --install"
+ *  could not have installed a single one. Advice no command can honour is a
+ *  defect. Those references are gone from the catalog; the guard stays, since
+ *  the same situation reappears whenever a pack is disabled or its `--skill`
+ *  list stops naming an id the catalog still asks for. */
 function packDelivery(spec: ReturnType<typeof loadSpec>): { exact: Set<string>; prefixes: string[] } {
   const exact = new Set<string>();
   const prefixes: string[] = [];
@@ -518,6 +515,33 @@ function packDelivery(spec: ReturnType<typeof loadSpec>): { exact: Set<string>;
   return { exact, prefixes };
 }
 
+/** Skill ids the package itself carries in `packageRootDir/skills`. */
+function shippedSkills(packageRootDir: string): Set<string> {
+  const shipped = new Set<string>();
+  const shippedDir = join(packageRootDir, "skills");
+  if (existsSync(shippedDir)) {
+    for (const entry of readdirSync(shippedDir, { withFileTypes: true })) {
+      if (entry.isDirectory()) shipped.add(entry.name);
+    }
+  }
+  return shipped;
+}
+
+/** Referenced skill ids nothing in the system can supply: the package ships
+ *  none of them and no enabled pack can install them. Exported so the catalog
+ *  is held to this invariant in tests, since the row above reports it without
+ *  blocking and therefore never failed on it. */
+export function undeliverableReferences(
+  spec: ReturnType<typeof loadSpec>,
+  packageRootDir: string
+): string[] {
+  const shipped = shippedSkills(packageRootDir);
+  const { exact, prefixes } = packDelivery(spec);
+  return referencedSkills(spec).filter(
+    (id) => !shipped.has(id) && !exact.has(id) && !prefixes.some((prefix) => id.startsWith(prefix))
+  );
+}
+
 /** Impeccable design-context checks: PRODUCT.md and DESIGN.md resolution
  *  (root -> .agents/context -> docs/). Rows appear only when the impeccable
  *  skill is installed (opt-in) and are never blocking: a missing record is a

package/src/commands/init.ts

@@ -5,8 +5,9 @@ import { loadSpec, NovahizHome } from "../spec.ts";
 import { loadInstalledSkills } from "../catalog.ts";
 import { findContextFile } from "../impeccable.ts";
 import { ensureMemoryRoot, memoryRoot, writeEntry } from "../memory.ts";
+import { readProjectName } from "../autodocs.ts";
 import { ensureProjectAutoDocsConfig } from "./autodocs.ts";
-import { projectInit } from "./second-memory.ts";
+import { projectInit, syncProjectDocsToVault } from "./second-memory.ts";
 import * as ui from "../render.ts";
 
 type StepStatus = "created" | "skipped" | "dry-run" | "failed";
@@ -78,7 +79,7 @@ function detectProject(cwd: string): ProjectInfo {
   if (existsSync(join(cwd, "README.md"))) markers.push("README.md");
 
   if (!name) {
-    name = cwd.split(/[\\/]/).filter(Boolean).pop() ?? "project";
+    name = readProjectName(cwd);
   }
   return { kind, name, version, markers };
 }
@@ -320,6 +321,53 @@ function obsidianProject(dryRun: boolean, project: ProjectInfo): InitStep {
   };
 }
 
+/** Étape de suite : la place existe-t-elle, on la remplit.
+ *  Recopie `<projet>/novahiz-docs/` dans le `<docs>/<slug>/` du vault. Elle
+ *  hérite du verdict d'`obsidianProject` au lieu d'en dériver un second : si le
+ *  dossier projet n'a pas pu être posé, il n'y a aucune cible légitime et cette
+ *  étape se tait plutôt que d'en tenter une. Sans vault, sans binding ou sans
+ *  dossier cible, elle saute avec le conseil exact ; aucun dossier n'est
+ *  inventé (contrainte 1) et aucune copie ne part dans le vide. */
+function obsidianDocs(cwd: string, dryRun: boolean, project: ProjectInfo, folder: InitStep): InitStep {
+  const label = "Obsidian project docs";
+  if (folder.status !== "created" && folder.status !== "skipped") {
+    return { id: "obsidian-docs", label, status: "skipped", detail: `project folder not ready — see "${folder.label}"` };
+  }
+  const name = project.name.trim();
+  if (name.length === 0) {
+    return { id: "obsidian-docs", label, status: "skipped", detail: "no project name detected (package.json)" };
+  }
+  let result;
+  try {
+    result = syncProjectDocsToVault(name, join(cwd, "novahiz-docs"), !dryRun);
+  } catch (error) {
+    return { id: "obsidian-docs", label, status: "failed", detail: String(error).slice(0, 160) };
+  }
+  const where = result.target.length > 0 ? result.target : `${result.domain}/${result.branch}/${result.slug}`;
+  if (result.warnings.length > 0 && result.copied.length === 0) {
+    return {
+      id: "obsidian-docs",
+      label,
+      status: "skipped",
+      detail: `${where}: ${result.warnings.join("; ").slice(0, 160)}`,
+      advice: result.target.length > 0 ? undefined : `Link it: novahiz second-memory project-init --name <project> --branch Domain/Branch --apply`
+    };
+  }
+  const counts = `${result.copied.length} file(s)${result.absent.length > 0 ? `, ${result.absent.length} absent` : ""}`;
+  if (dryRun) {
+    return { id: "obsidian-docs", label, status: "dry-run", detail: `${where}: ${counts} would be copied` };
+  }
+  if (result.warnings.length > 0) {
+    return { id: "obsidian-docs", label, status: "failed", detail: `${where}: ${result.warnings.join("; ").slice(0, 160)}` };
+  }
+  return {
+    id: "obsidian-docs",
+    label,
+    status: result.copied.length > 0 ? "created" : "skipped",
+    detail: result.copied.length > 0 ? `${where}: ${counts} mirrored` : `${where}: nothing to copy`
+  };
+}
+
 export function commandInit(parsed: Parsed): void {
   const cwd = process.cwd();
   const home = NovahizHome();
@@ -362,7 +410,9 @@ export function commandInit(parsed: Parsed): void {
       });
     }
     steps.push(impeccableContext(home, cwd, dryRun));
-    steps.push(obsidianProject(dryRun, project));
+    const folder = obsidianProject(dryRun, project);
+    steps.push(folder);
+    steps.push(obsidianDocs(cwd, dryRun, project, folder));
   }
 
   let cleanup: CleanupCandidate[] = [];

package/src/commands/second-memory.ts

@@ -2260,6 +2260,141 @@ export function projectInit(name: string, branchFlag: string | undefined, apply:
   return result;
 }
 
+// --- project docs sync ---------------------------------------------------------
+
+/** Les quatre fichiers que `novahiz init` pose dans `<projet>/novahiz-docs/` et
+ *  que la copie vault reflète. Liste fermée, même ordre canonique que le
+ *  template : on ne recopie pas n'importe quel fichier trouvé dans le dossier. */
+export const PROJECT_DOC_FILES = ["ARCHITECTURE.md", "CONVENTIONS.md", "DECISIONS.md", "STANDARDS.md"] as const;
+
+export type DocsSyncResult = {
+  apply: boolean;
+  project: string;
+  slug: string;
+  /** Rel `<Domaine>/<Branche>/docs/<slug>` ; chaîne vide tant que la cible
+   *  n'est pas confirmée sur le disque. */
+  target: string;
+  /** Confiés uniquement quand la cible est établie : un domaine dont la branche
+   *  manque n'est pas un chemin valide, et son nom reste dans `warnings`. */
+  domain: string;
+  branch: string;
+  copied: string[];
+  absent: string[];
+  warnings: string[];
+};
+
+/** Append-only, une entrée par jour : `- HH:MM - message` sous `## YYYY-MM-DD`.
+ *  Même forme que l'entrée posée à l'initialisation du vault (L1036), pour que
+ *  le journal reste lisible comme un seul flux. Une entrée est posée uniquement
+ *  en mode apply : la trace d'un dry-run est un non-événement. */
+function appendLogLine(vault: string, message: string): void {
+  const now = new Date();
+  const date = now.toISOString().slice(0, 10);
+  const time = now.toTimeString().slice(0, 5);
+  const entry = `- ${time} - ${message}`;
+  const path = join(vault, LOG_FILE);
+  if (!existsSync(path)) {
+    writeFileSync(path, `# Second Memory Log\n\nAppend-only. Never delete entries.\n\n## ${date}\n${entry}\n`, "utf8");
+    return;
+  }
+  const body = readFileSync(path, "utf8").replace(/\s*$/, "");
+  // log.md est chronologique : la section du jour, si elle existe, est la dernière.
+  const marker = "## " + date;
+  const lastHeading = body.slice(body.lastIndexOf("\n## ") + 1);
+  const todayIsLast = lastHeading.startsWith(marker);
+  const head = todayIsLast ? body + "\n" : body + "\n\n" + marker + "\n";
+  writeFileSync(path, head + entry + "\n", "utf8");
+}
+
+/** Copie la documentation d'un projet vers `<Domaine>/<Branche>/docs/<slug>/`.
+ *
+ *  Volet « écriture automatique dans le vault » de `novahiz init` et de
+ *  `autodocs flush`. La copie est **un miroir, jamais la source** : chaque note
+ *  reflète un fichier qui existe toujours dans `<projet>/novahiz-docs/`, donc un
+ *  écrasement ne détruit rien qu'on ne puisse régénérer — c'est ce qui rend
+ *  l'absence de backup défendable ici, contrairement à une note écrite à la main.
+ *
+ *  Garde-fous, tous explicites et non silencieux :
+ *  - aucun binding → on ne devine pas de branche, on renvoie le conseil ;
+ *  - branche absente du catalogue → le vault a bougé, on ne crée rien ;
+ *  - dossier cible absent → `project-init` crée la chaîne, on ne l'invente pas
+ *    (contrainte 1) ;
+ *  - fichier absent du projet → reporté dans `absent`, pas d'étublage.
+ *
+ *  En dry-run (`apply: false`), rien n'est écrit — ni note, ni entrée de log ;
+ *  `copied` liste alors ce qui *serait* copié. */
+export function syncProjectDocsToVault(name: string, docsDir: string, apply: boolean): DocsSyncResult {
+  const trimmed = (name ?? "").trim();
+  const slug = projectFolder(trimmed, "");
+  const result: DocsSyncResult = { apply, project: trimmed, slug, domain: "", branch: "", target: "", copied: [], absent: [], warnings: [] };
+  if (slug.length === 0) {
+    result.warnings.push("empty project name after slugify — pass a real project name");
+    return result;
+  }
+  const vault = vaultPath();
+  if (!existsSync(vault)) {
+    result.warnings.push("vault not found — run `novahiz second-memory init` first");
+    return result;
+  }
+  if (!existsSync(docsDir)) {
+    result.warnings.push(`no project docs at ${docsDir} — run \`novahiz init\` to create them`);
+    return result;
+  }
+  const binding = readBinding(slug);
+  if (!binding) {
+    result.warnings.push(`no vault binding for "${slug}" — run \`novahiz second-memory project-init --name ${slug} --branch Domain/Branch\``);
+    return result;
+  }
+  const domainNode = findDomain(binding.domain);
+  const branchNode = domainNode?.children?.find((node) => node.name === binding.branch) ?? null;
+  if (!domainNode || !branchNode) {
+    result.warnings.push(`binding points to an unknown branch ${binding.domain}/${binding.branch} — re-run project-init`);
+    return result;
+  }
+  result.domain = domainNode.name;
+  result.branch = branchNode.name;
+  const leaf = (branchNode.children ?? []).find((node) => node.kind === "docs");
+  if (!leaf) {
+    result.warnings.push(`branch ${domainNode.name}/${branchNode.name} carries no docs leaf`);
+    return result;
+  }
+  const target = `${domainNode.name}/${branchNode.name}/${leaf.name}/${slug}`;
+  if (!existsSync(join(vault, target))) {
+    result.warnings.push(`target folder missing: ${target} — run \`novahiz second-memory project-init --name ${slug}\``);
+    return result;
+  }
+  result.target = target;
+
+  for (const file of PROJECT_DOC_FILES) {
+    const source = join(docsDir, file);
+    let content: string;
+    try {
+      content = readFileSync(source, "utf8");
+    } catch {
+      result.absent.push(file);
+      continue;
+    }
+    if (!apply) {
+      result.copied.push(file);
+      continue;
+    }
+    try {
+      writeFileSync(join(vault, target, file), content, "utf8");
+      result.copied.push(file);
+    } catch (error) {
+      result.warnings.push(`${file}: ${String(error).slice(0, 200)}`);
+    }
+  }
+  if (apply && result.copied.length > 0) {
+    try {
+      appendLogLine(vault, `project docs synced: ${target} (${result.copied.length} file(s))`);
+    } catch (error) {
+      result.warnings.push(`log: ${String(error).slice(0, 160)}`);
+    }
+  }
+  return result;
+}
+
 function secondMemoryProjectInit(parsed: Parsed): void {
   const apply = flagOn(parsed, "apply");
   const name = String(parsed.flags.name ?? "").trim();