@venizia/vulcan 0.1.0-1 → 0.2.0-0

package/README.md

@@ -17,7 +17,7 @@ flag `bun x` fetches it when `@venizia/vulcan` is not installed yet.
 | Command | What it does |
 |---|---|
 | `init [--config ts\|mts\|mjs\|js]` | Scaffold the project layer: `AGENTS.md`, `.configs/vulcan.config.*`, the three lint configs, `.agents/rules.md`, `.agents/knowledge/index.md`, a Makefile `-include`. Never overwrites; prints what to add to existing files, and the atlas `.mcp.json` entry for projects with a wiki |
-| `sync [--dry-run]` | Write the gitignored agent adapters: `CLAUDE.md` (`@AGENTS.md`), `.claude/settings.json` (shipped + slot + project hooks + `claude.settings` over your personal keys; what it applied is recorded in `.claude/vulcan-managed.json`, so a removed choice is removed), `.claude/skills/` links. Idempotent |
+| `sync [--dry-run] [--prune]` | Write the gitignored agent adapters: `CLAUDE.md` (`@AGENTS.md`), `.claude/settings.json` (shipped + slot + project hooks + `claude.settings` over your personal keys; what it applied is recorded in `.claude/vulcan-managed.json`, so a removed choice is removed), `.claude/skills/` links, and the committed `.agents/vulcan.manifest.json`. Prints each base rule added, changed or removed since the manifest last recorded it, with its new text, then records the new hashes. `--prune` also removes what sync proves stale and did not write: an old VULCAN or plugin-era hook command (a shipped hook in an old form, or a `.agents/` hook whose file is gone) and a dead `.claude/skills` link - never a developer's own hook or a real directory. Idempotent |
 | `doctor` | Check the project follows VULCAN; exit 1 on any violation |
 | `upgrade [<version\|tag>]` | Install the target `@venizia/vulcan` (default: the `next` dist-tag), then run `sync` from the newly installed CLI |
 | `x <tool> [args...]` | Run a shipped tool at the pinned version: `okf`, `atlas` |
@@ -39,6 +39,7 @@ export default {
   knowledge: { bundle: '.agents/knowledge' },
   hooks: [{ event: 'Stop', command: 'echo done' }],
   claude: { settings: { permissions: { allow: ['Bash(make test)'] } } }, // team-shared, committed
+  digest: { oftenDropped: ['V-B-03', 'W-00'] },  // repeated at every session start; base or own IDs
 } satisfies VulcanConfig;
 ```
 
@@ -46,7 +47,7 @@ An unknown key is an error; every error names the file and the field.
 
 ## What ships (`base/`)
 
-- `rules.md` - the base rules: write boundaries, security, process, build, and the IGNIS coding style V-C-01..V-C-18 (37 rules; V-W-05, V-C-03 and V-C-05 are retired).
+- `rules.md` - the base rules: write boundaries, security, process, build, and the IGNIS coding style V-C-01..V-C-18 (37 rules; it lists V-W-05, V-C-03 and V-C-05 as retired).
 - `slots.json` - rules a project picks a wording for (V-W-01 today).
 - `skills/` - `knowledge-sync`, `docs-writing` (project-neutral; a project-specific skill stays in its project).
 - `hooks/` - `session-start.ts` (prints the rules digest) and `guard-writes.ts` (asks before a database write, a migration, a deploy or a mutating HTTP call).
@@ -57,10 +58,13 @@ or shadows a shipped one.
 
 ## `doctor` checks
 
-`config` (exactly one valid config) · `layout` (AGENTS.md, rules, knowledge bundle) · `rule-ids` (no
-project rule in the base `V-` namespace) · `rule-slots` (every slot chosen, valid option) · `skills` (no shipped skill
+`config` (exactly one valid config) · `layout` (AGENTS.md, rules, knowledge bundle) · `rule-ids` (every
+`V-` ID a project rule points at - an `Extends` list or a first cell - is a base rule, not a retired one) · `rule-slots` (every slot chosen, valid option) · `skills` (no shipped skill
 shadowed) · `make` (includes `vulcan.mk`, no shipped target redefined) · `hooks` (shipped hooks are
 not re-registered) · `adapters` (sync is current, no hand-written `CLAUDE.md`, valid settings) ·
-`style` (`@venizia/dev-configs` installed, every lint config builds on it).
+`prune` (no stale hook command or dead skill link - `sync --prune` removes them) ·
+`style` (`@venizia/dev-configs` declared by the package holding the lint config or the root, every lint config builds on it).
+
+The session-start digest prints the base write boundaries, the slot choices, the project's own rules (bold `| **W-00** |` rows and `| V-W-02, V-W-03 |` rows that elaborate base rules), the project's `<!-- minimap-shape:start -->` ... `<!-- minimap-shape:end -->` block from `.agents/rules.md` verbatim, and the `digest.oftenDropped` rules.
 
 MIT licensed - see [LICENSE.md](LICENSE.md).

package/base/claude/settings.json

@@ -7,7 +7,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "bun \"${CLAUDE_PROJECT_DIR}\"/node_modules/@venizia/vulcan/base/hooks/session-start.ts"
+            "command": "f=\"${CLAUDE_PROJECT_DIR}/node_modules/@venizia/vulcan/base/hooks/session-start.ts\"; if [ -f \"$f\" ] && command -v bun >/dev/null 2>&1; then bun \"$f\"; s=$?; [ \"$s\" -eq 0 ] && exit 0; exit 2; fi; echo \"vulcan: the session-start hook cannot run (node_modules/@venizia/vulcan or bun is missing) - run bun install\" >&2; exit 2"
           }
         ]
       }
@@ -18,7 +18,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "bun \"${CLAUDE_PROJECT_DIR}\"/node_modules/@venizia/vulcan/base/hooks/guard-writes.ts"
+            "command": "f=\"${CLAUDE_PROJECT_DIR}/node_modules/@venizia/vulcan/base/hooks/guard-writes.ts\"; if [ -f \"$f\" ] && command -v bun >/dev/null 2>&1; then bun \"$f\"; s=$?; [ \"$s\" -eq 0 ] && exit 0; exit 2; fi; if grep -Eq '\"command\" *: *\"bun (install|i)( --?[a-z][a-z0-9-]*(=[A-Za-z0-9._-]+)?)*\"'; then exit 0; fi; echo \"vulcan: the guard-writes hook cannot run (node_modules/@venizia/vulcan or bun is missing) - run bun install (the one command that passes until then)\" >&2; exit 2"
           }
         ]
       }

package/base/hooks/guard-writes.ts

@@ -1,14 +1,29 @@
 /**
  * PreToolUse hook on Bash: catches the writes V-W-02 and V-W-03 reserve for a human, reading the
  * command and any local script it runs. It asks rather than denies (src/hooks/common/constants.ts).
+ *
+ * It fails closed: Claude Code blocks a PreToolUse call only on exit 2, so a hook that throws - a
+ * partial install, say, where its own modules are missing - would let every command through. The
+ * modules load inside the try for that reason.
  */
-import { buildGuardDecision, inspectCommand, parseHookCommand } from '../../src/hooks/index.ts';
 
-const hookCommand = parseHookCommand({ text: await Bun.stdin.text() });
-const hits = hookCommand
-  ? inspectCommand({ command: hookCommand.command, cwd: hookCommand.cwd ?? process.cwd() })
-  : [];
+// A module, so the awaits below are top-level; it has no static import, by design.
+export {};
 
-if (hits.length > 0) {
-  console.log(JSON.stringify(buildGuardDecision({ hits })));
+try {
+  const { buildGuardDecision, inspectCommand, parseHookCommand } =
+    await import('../../src/hooks/index.ts');
+  const hookCommand = parseHookCommand({ text: await Bun.stdin.text() });
+  const hits = hookCommand
+    ? inspectCommand({ command: hookCommand.command, cwd: hookCommand.cwd ?? process.cwd() })
+    : [];
+
+  if (hits.length > 0) {
+    console.log(JSON.stringify(buildGuardDecision({ hits })));
+  }
+} catch (error) {
+  console.error(
+    `vulcan: the guard-writes hook failed (${error instanceof Error ? error.message : String(error)}) - blocked; run bun install`,
+  );
+  process.exit(2);
 }

package/base/make/vulcan.mk

@@ -5,48 +5,57 @@
 VULCAN ?= bun x --no-install vulcan
 
 .PHONY: vulcan-sync vulcan-doctor agent-setup okf-check okf-check-strict okf-gen okf-coverage okf-viz \
-        surface-gen surface-check symbols-gen symbols-check releases-gen releases-check
+        surface-gen surface-check atlas-symbols atlas-releases changelogs-migrate \
+        knowledge-symbols-check
 
-vulcan-sync:
+vulcan-sync: ## Write the agent adapters, settings, skill links and manifest from the config
 	@$(VULCAN) sync
 
-vulcan-doctor:
+vulcan-doctor: ## Check the project against the VULCAN contract
 	@$(VULCAN) doctor
 
-# The IGNIS name for the same job, kept for muscle memory.
-agent-setup: vulcan-sync
+# The older name for the same job, kept for muscle memory.
+agent-setup: vulcan-sync ## The older name for vulcan-sync
 
 # OKF v0.2 conformance only; okf-check-strict adds the house rules (links, style, coverage, freshness).
-okf-check:
+okf-check: ## Check the knowledge bundle against OKF v0.2
 	@$(VULCAN) x okf check
 
-okf-check-strict:
+okf-check-strict: ## okf-check plus the house rules: links, style, coverage, freshness
 	@$(VULCAN) x okf check --strict
 
-okf-gen:
+okf-gen: ## Regenerate the generated pages and regions of the knowledge bundle
 	@$(VULCAN) x okf gen
 
-okf-coverage:
+okf-coverage: ## Report how much of the code the knowledge bundle covers
 	@$(VULCAN) x okf coverage
 
-okf-viz:
+okf-viz: ## Build the knowledge graph view
 	@$(VULCAN) x okf viz
 
-# The Atlas tables. surface and symbols read the built .d.ts - build first.
-surface-gen:
+# The public surface: an optional API gate a project commits and checks. It reads the built .d.ts -
+# build first.
+surface-gen: ## Write the public API surface from the built .d.ts
 	@$(VULCAN) x atlas surface gen
 
-surface-check:
+surface-check: ## Fail when the public API surface differs from the committed one
 	@$(VULCAN) x atlas surface check
 
-symbols-gen:
-	@$(VULCAN) x atlas symbols gen
+# Symbols are read from the built or installed .d.ts when atlas is asked - nothing to commit.
+# atlas-symbols prints what atlas reads, to see what symbol answers from. Build first.
+atlas-symbols: ## Print the symbols atlas reads from the built or installed .d.ts
+	@$(VULCAN) x atlas symbols
 
-symbols-check:
-	@$(VULCAN) x atlas symbols check
+# Releases are computed from tags when atlas reads the project - nothing to generate or commit.
+# atlas-releases prints the computed table, to see what version and changes answer from.
+atlas-releases: ## Print the release table atlas computes from the tags
+	@$(VULCAN) x atlas releases
 
-releases-gen:
-	@$(VULCAN) x atlas releases gen
+# Writes the packages: list into every changelog entry that declares none - once, then review it.
+changelogs-migrate: ## Write the packages: list into changelog entries that declare none
+	@$(VULCAN) x atlas changelogs migrate
 
-releases-check:
-	@$(VULCAN) x atlas releases check
+# A concept may name code (`symbols:` in its frontmatter); this fails when a named symbol is gone or its
+# signature changed since `vulcan x atlas concepts stamp`. It reads the built .d.ts - run it after build.
+knowledge-symbols-check: ## Fail when a symbol a concept names is gone or its signature changed
+	@$(VULCAN) x atlas concepts check

package/base/rules.md

@@ -1,16 +1,20 @@
 # Rules - VULCAN base
 
 <!-- Shipped by @venizia/vulcan. Never edit in a project: add extensions in .agents/rules.md.
-     W, S, P, B are INTERIM until the base-rules work reconciles the rules IGNIS, ARDOR and BANA share.
-     C is IGNIS's coding style, shipped to every project; the rules that bind IGNIS's own stack live in IGNIS. -->
+     W, S, P, B are INTERIM until the base-rules work reconciles the rules the projects share.
+     C is the shared coding style, shipped to every project; a rule that binds one project's own stack
+     lives in that project. -->
 
 Cite by ID. Every rule has "Enforced by". Base IDs carry the `V-` namespace (`V-W-01`, `V-C-04`).
 A project extends this set in its own `.agents/rules.md` with bare IDs (`W-06`, `C-19`), which can
-never collide with a base ID; it never claims the `V-` namespace (`vulcan doctor` enforces it).
+never collide with a base ID. A `V-` ID there points at a base rule (`Extends V-W-01`); `vulcan doctor`
+fails one the base does not carry or has retired.
 
-Retired IDs are never reused: `V-W-05` (task-manager loop), `V-C-03` (`@inject` on container-built
-classes) and `V-C-05` (`getError` / `ApplicationError`) - the last two, with the hard stack once in
-`V-C-18`, are IGNIS rules now (2026-10-17).
+Retired IDs are never reused (2026-10-17):
+
+- `V-W-05` - the task-manager loop
+- `V-C-03` - `@inject` on container-built classes, moved to the project whose stack it binds
+- `V-C-05` - `getError` / `ApplicationError`, moved to the project whose stack it binds, with the hard stack once in `V-C-18`
 
 ## W - Write boundaries
 
@@ -58,8 +62,8 @@ classes) and `V-C-05` (`getError` / `ApplicationError`) - the last two, with the
 | ID | Rule | Enforced by |
 |----|------|-------------|
 | V-C-01 | **English only in code** - identifiers, comments, commit messages, logs, docs. Vietnamese belongs in chat. | SOFT |
-| V-C-02 | **Options objects everywhere:** `fn({ key, value })`, never `fn(key, value)`. **One parameter is not an exception** - `isValidName({ name })`, not `isValidName(name)`. A single positional parameter reads fine until the second one arrives, and by then the method is published and every call site pays. The cost is highest on an interface others implement: `IStorageHelper` carried three positional methods for exactly this reason and the migration touched 72 call sites. Mixing the two styles in one interface is itself the defect - a reader cannot tell which shape a method takes without opening it. | SOFT |
-| V-C-04 | **Never abbreviate identifiers:** `ProductRepository` not `ProductRepo`, `ProductDocument` not `ProductDoc`; type parameters too (`TDocument`, not `TDoc`). A project lists its own exceptions in its rules (IGNIS: `tz` for a time zone). | SOFT |
+| V-C-02 | **One options object first, at most 5 parameters.** Fold every argument you can into a single options object in the first position: `fn({ key, value })`, not `fn(key, value)`, and one parameter is not an exception - `isValidName({ name })`, not `isValidName(name)`. A second parameter is allowed only where the first object cannot carry it, for example a repository method that takes its data and its query options separately. Never more than 5 parameters. A single positional parameter reads fine until the second one arrives, and by then the method is published and every call site pays. The cost is highest on an interface others implement: `IStorageHelper` carried three positional methods for exactly this reason and the migration touched 72 call sites. Mixing the two styles in one interface is itself the defect - a reader cannot tell which shape a method takes without opening it. | SOFT - lint (`venizia/max-params-own`, 5) once `@venizia/dev-configs` ships `houseConfigs` |
+| V-C-04 | **Never abbreviate identifiers:** `ProductRepository` not `ProductRepo`, `ProductDocument` not `ProductDoc`; type parameters too (`TDocument`, not `TDoc`). A project lists its own exceptions in its rules (for example `tz` for a time zone). | SOFT |
 | V-C-06 | **Never a silent catch - log it.** Always braces. Early return. `switch` with `default` over a long if-else chain. Strict TypeScript; no `any` where a type exists. | LINT (braces, floating promises) + SOFT |
 | V-C-07 | **A function name opens with its verb** - `generate` `build` `to` `is` `has` `assert` `extract` `enrich` `get` `resolve`. `is*` returns a boolean and leaves the branch to the caller; `assert*` throws and returns `void`, so the code after it needs none - reach for `assert*` when every caller would throw on `false` anyway. `has*` is the ownership question (`hasBucket`, never `isBucketExists`). That list is for UTILITY functions; service methods lean on a wider set. **Arrow functions, not `function` declarations** (do not churn existing ones). State plus the operations on it live in a class with static members - the `LoggerFactory` shape - never module-level `let` plus exported arrows. | SOFT |
 | V-C-08 | **Enumerable strings are a const class plus `TConstValue`,** never a raw string-literal union. Every such class carries `static readonly SCHEME_SET = new Set([...])` over its values and `static isValid(value: string): boolean` reading it, so a runtime check exists wherever a value crosses a boundary (`IsolationLevels` in connectors is the model; a subclass redeclares `SCHEME_SET` with `...Parent.SCHEME_SET` first). The `T`/`I` prefix follows the declaration keyword: `type` gets `T`, `interface` gets `I`; an interface turned into a type alias is renamed, and no tool catches it - grep both directions. | SOFT |
@@ -67,7 +71,7 @@ classes) and `V-C-05` (`getError` / `ApplicationError`) - the last two, with the
 | V-C-10 | **No explicit cast in new code.** `as X`, `as any`, `as unknown as X` and `as never` assert nothing; they silence the compiler where the type is wrong. Fix the type instead: a generic on the setter, a narrower parameter, a typed helper, `satisfies`. A pre-existing cast is removed when the line is touched, never copied. Generic parameters are full words (`ApplicationType`, `TDocument`), never `App` or `TDoc` (V-C-04). | SOFT |
 | V-C-11 | **SIMPLE FIRST, in code and in prose.** Fewest concepts, plainest words, smallest surface. Complexity must buy correctness, speed or safety the simple version cannot, and the artifact says what it bought. Something a reader cannot follow in one pass is a defect even when it works. Fix the root cause with the smallest change; never layer an abstraction on a misdiagnosed problem. | SOFT |
 | V-C-12 | **Consistent, never self-invented.** Before writing anything new - a constant, file, binding key, error shape - find the nearest precedent in this repo and copy its shape. Binding keys are namespaced (`controllers.X`, `services.X`, `repositories.X`, `datasources.X`). Every scope is one folder with nested `common/{types,constants}.ts` and an index barrel (`inversion` is the model). A second style for something that already has one is a defect. | SOFT |
-| V-C-13 | **Docs style: hyphen `-`, never an em-dash or en-dash. A brand is spelled the way its owner spells it (IGNIS, ARDOR, VULCAN), never "Ignis".** English prose. The human-facing docs site stays native to its generator (IGNIS: plain VitePress, no custom components or theme CSS). The knowledge bundle is agent-facing; never conflate the two. | SOFT - `okf check --strict` (bundle) |
+| V-C-13 | **Docs style: hyphen `-`, never an em-dash or en-dash. A brand is spelled the way its owner spells it (VULCAN, never "Vulcan").** English prose. The human-facing docs site stays native to its generator (for example plain VitePress, no custom components or theme CSS). The knowledge bundle is agent-facing; never conflate the two. | SOFT - `okf check --strict` (bundle) |
 | V-C-14 | **Our types are camelCase.** A snake_case wire name exists only at the mapper boundary, through a string-literal key - never through an eslint-disable. | LINT (naming convention) + SOFT |
 | V-C-15 | **One method with a mode option, not several specialized methods.** Payload variants are zod-per-variant with `z.infer`, discriminated. | SOFT |
 | V-C-16 | **One concept, one implementation.** When the same question is answered in several places, the bug lives at the seam and no tool catches it. Consolidate to one home before building on top. | SOFT |

package/base/skills/docs-writing/references/before-after.md

@@ -1,4 +1,4 @@
-# Worked example - a real IGNIS changelog bullet, before and after
+# Worked example - a real changelog bullet, before and after
 
 From the 2026-07-18 Repository Read Retry changelog. Every fact survives; the reading effort does not.
 

package/base/skills/docs-writing/references/page-anatomy.md

@@ -15,7 +15,7 @@ If a page's sections resolve to different quadrants, it is two pages wearing one
 
 ## Skeleton 1 - Tutorial (getting started)
 
-1. **Title** - an achievement: "Build your first IGNIS API", never "Learn IGNIS".
+1. **Title** - an achievement: "Build your first API", never "Learn the framework".
 2. **Goal + outcome preview** - 1-3 sentences: "In this tutorial we build a working X." Never "you will learn".
 3. **Prerequisites** - exact versions and tools, once.
 4. **Numbered steps** - ONE path, zero choices. Every step ends in a visible result with the expected output shown ("After a few seconds you'll see...").
@@ -52,7 +52,7 @@ Governing rule: describe and only describe. Structure mirrors the code. You cons
 1. **Title** - accepts an implicit "About...": "Understanding the DI container".
 2. **The question** - what "why" this page answers. It is also the page's boundary.
 3. **The picture** - the mental model, a diagram if code and words fail.
-4. **Design decisions** - why IGNIS chose this (prior art: LoopBack, NestJS, Spring), constraints, trade-offs.
+4. **Design decisions** - why the project chose this (prior art: LoopBack, NestJS, Spring), constraints, trade-offs.
 5. **Alternatives and objections** - weigh them honestly (Tailwind's "Why not just use inline styles?" move).
 6. **Boundaries + links** - where the topic ends; link the reference and how-tos.
 

package/base/skills/knowledge-sync/SKILL.md

@@ -1,146 +1,80 @@
 ---
 name: knowledge-sync
-description: Re-sync the .agents/knowledge OKF bundle against the source code. Use when the user asks to sync knowledge, refresh the knowledge bundle, audit concepts against code, or run a periodic/monthly knowledge audit.
+description: Re-syncs a project's OKF knowledge bundle against its source code - verifies the curated concepts whose code changed since the last sync (delta) or every concept (full), applies the confirmed fixes and logs the sync. Use when the user asks to sync knowledge, refresh the knowledge bundle, audit concepts against code, or run a periodic knowledge audit.
 user-invocable: true
 allowed-tools: Read, Write, Edit, Grep, Glob, Bash, Agent, Workflow
 ---
 
-# Knowledge Sync - re-sync `.agents/knowledge` against source code
-
-Keep the OKF knowledge bundle true to the code. The generated reference layer self-heals via
-`make okf-gen`; this skill covers the **curated** concepts, which only stay honest when someone
-re-reads the source.
-
-This is deliberately **not** a commit gate. A per-commit check cannot tell whether prose is still
-true - only re-reading the code can. So the bundle is verified periodically, here.
-
-## Core principles
-
-1. **Code is ground truth.** Never fix a concept from `docs/wiki`, `AGENTS.md`, a `CLAUDE.md`, or
-   memory - those drift too. This bundle exists because they did. Every finding needs a `file:line`
-   witness; every fix is applied faithfully to that witness.
-2. **Curate, do not dump.** Concepts stay tight: fix wrong/stale, fold in only durable high-value
-   missing facts, skip volatile detail (dependency lists, config keys, version numbers).
-3. **Cheap by default.** Delta mode only verifies concepts whose code areas changed since the last
-   sync. Full mode (everything + critics) is for monthly/quarterly.
-4. **Nothing is committed.** The agent edits the bundle + `log.md`; the user reviews and commits.
-5. **Subagents never run state-changing git commands.** Read-only `git log`/`diff`/`show` only.
-
-## Mode selection
-
-| What the user asked for | Mode |
-|---|---|
-| daily / weekly / bi-weekly / "sync knowledge" (no qualifier) | `delta` |
-| monthly / quarterly / "full" / "toàn bộ" / last **full** sync > 30 days ago (check `log.md`) | `full` |
-
-`full` = delta verifiers **plus** 6 directory spot-auditors over every other concept **plus**
-completeness + usability critics.
-
-## Step 0 - Baseline
-
-1. `make okf-gen` then `make okf-check` - refresh the generated layer first so verifiers never chase
-   facts `gen` already fixes. `check` must be clean before proceeding.
-2. **Anchor the last sync by COMMIT, not by date:**
-   ```bash
-   LAST_SYNC=$(git log -1 --format=%H -G '^## [0-9-]+ - knowledge-sync' -- .agents/knowledge/log.md)
-   ```
-   The scan range is `$LAST_SYNC..HEAD`. Anchor on the sync's own log heading, never on the last
-   edit of `log.md`: every ordinary change appends to it (OKF §9), so the last edit is almost never
-   the last sync and the range would come out empty. The date in the heading is only a display label.
-
-   **If `LAST_SYNC` is empty** no entry carries the `knowledge-sync` heading yet (or `log.md` was renamed). Do not
-   build a `..HEAD` range from it - that silently means "everything". Either anchor on the commit
-   that introduced the bundle (`git log --diff-filter=A --format=%H -- .agents/knowledge/index.md`)
-   or run `full` mode, which does not depend on the range for its spot-auditors.
-   Never use a bare `--since=YYYY-MM-DD`: git's approxidate reads a date equal to *today* as "since
-   the current wall-clock time" and silently returns empty, and same-day commits made before the
-   last sync get double-counted. A hash range has neither problem.
-3. Changed-area scan:
-   ```bash
-   git log $LAST_SYNC..HEAD --no-merges --name-only --format= -- packages/ examples/ Makefile make/ .github/ .githooks/ scripts/ \
-     | sort -u | awk -F/ '{print $1"/"$2}' | sort | uniq -c | sort -rn
-   git log $LAST_SYNC..HEAD --no-merges --oneline
-   git diff HEAD --stat -- packages/ examples/ Makefile make/ .github/ .githooks/ scripts/ package.json
-   ```
-   The last line is uncommitted code. `okf gen` regenerates from the working tree and the verifiers
-   read the working tree, so uncommitted changes count as changed areas too - say which are
-   uncommitted in the target hint. Commit subjects become verifier hints. Ignore commits touching
-   only `.agents/knowledge/` or `docs/` - that is knowledge maintenance, not code drift.
-4. **Early exit (delta mode):** if no code areas changed, report "bundle already in sync", run the
-   gates (Step 3), stop. No workflow, no log entry - unless `gen` changed generated files, then a
-   one-line entry.
-
-## Step 1 - Build delta targets
-
-One target per changed area, from this map. Extend it when a new area appears, and keep it in sync
-as concepts are added.
-
-| Changed area | Concepts to verify (under `.agents/knowledge/`) |
-|---|---|
-| `packages/core-server/src/base/applications` | architecture/application-lifecycle, packages/core-server |
-| `packages/core-server/src/components` | architecture/component-model, architecture/controller-system, architecture/authentication, architecture/authorization-casbin, process/adding-a-component |
-| `packages/kernel/src/base/repositories`, `packages/kernel/src/base/datasources` | architecture/repository-hierarchy, architecture/datasource-hierarchy, architecture/transactions, packages/kernel |
-| `packages/kernel/src/common/bindings.ts` | conventions/binding-key-namespaces |
-| `packages/kernel` (broad/other) | packages/kernel, architecture/di-container, architecture/controller-system, architecture/error-handling-flow |
-| `packages/connectors` | packages/connectors, architecture/relational-connector, architecture/sqlite-connector, architecture/search-typesense, architecture/transactions |
-| `packages/filter` | packages/filter, architecture/filter-system |
-| `packages/core-worker` | packages/core-worker |
-| `packages/atlas` | packages/atlas |
-| `packages/core-server` (broad/other) | packages/core-server, architecture/error-handling-flow, conventions/gotchas |
-| `packages/boot` | packages/boot, architecture/boot-lifecycle |
-| `packages/inversion` | packages/inversion, architecture/di-container, conventions/gotchas |
-| `packages/helpers` | packages/helpers, conventions/error-handling, process/adding-a-helper |
-| `packages/dev-configs` | packages/dev-configs, conventions/coding-style, conventions/testing-conventions |
-| `examples/<x>` | examples/&lt;x&gt; |
-| `Makefile`, `make/`, `scripts/`, `.githooks/`, root `package.json` | process/build-system, process/testing, process/git-workflow, overview/build-run-test, conventions/gotchas |
-| `.github/workflows/` | process/release-publish, process/updating-the-wiki |
-| `docs/wiki` | process/updating-the-wiki |
-
-Per-target fields: `key`, `area` (git pathspec), `concepts`, `hint` (summarize the commit subjects -
-the verifier is told to verify, not trust), `model` - `opus` for heavy or architecture-critical areas
-(core, inversion, big diffs), `sonnet` for small ones. Ignore noise-only areas (formatting,
-lockfiles, generated files). Merge tiny areas (<=3 files each) into one combined target.
-
-## Step 2 - Run the workflow
-
-Invoke the Workflow tool with the saved script. Do not rewrite the orchestration inline:
+# Knowledge sync
+
+The generated layer (`vulcan x okf gen`) heals itself; curated concepts stay true only when someone
+re-reads the code. Code is ground truth - never fix a concept from docs, `AGENTS.md` or memory. Every
+finding cites a `file:line` witness. Nothing is committed: the user reviews the diff.
+
+## Requirements
+
+- Bun, git, and `@venizia/vulcan` installed in the project (`bun x --no-install vulcan`).
+- The Workflow tool, for the fan-out in Step 3.
+
+## Checklist
+
+Copy it into your reply and tick it off:
 
 ```
-Workflow({
-  scriptPath: '.claude/skills/knowledge-sync/knowledge-sync.workflow.js',
-  args: {
-    repo: '<git rev-parse --show-toplevel>',
-    mode: '<delta|full>',
-    since: '<YYYY-MM-DD>',              // display label for prompts/log
-    gitRange: '<LAST_SYNC hash>..HEAD', // what verifiers actually diff
-    deltaTargets: [...],
-  },
-})
+- [ ] 1. Prerequisites hold
+- [ ] 2. Baseline: gen, check, last sync, changed areas
+- [ ] 3. Targets built, workflow run
+- [ ] 4. Gaps decided
+- [ ] 5. Gates green (loop until they are)
+- [ ] 6. Log entry written; reported
 ```
 
-It fans out verifiers (+ spot-auditors and critics in full mode), groups findings per concept file,
-and runs one Opus applier per file under strict curation rules. Returns
-`{ stats, findingsByFile, applySummaries, gaps, notes }`.
-
-## Step 3 - Post-workflow
-
-1. **Gaps** (usually full mode): for each, decide like a curator - durable, load-bearing, no existing
-   home? If yes, spawn one Opus agent per gap to create the concept: copy frontmatter/voice/length
-   from 2-3 sibling concepts, verify every claim against source, cross-link, add a line to `index.md`
-   in the right section. If a gap is really consolidation (same fact in N files), make ONE file the
-   canonical home and reduce the others to pointers - never lose unique facts.
-2. **Gates:** `make okf-gen`, then `make okf-check` (must be OK), then
-   `bun .agents/knowledge-tools/okf.ts coverage --min 100` (structural must stay 100% - every
-   `packages/*` and `examples/*` needs a concept; the number grows as the repo does).
-3. **Log:** prepend an entry to `.agents/knowledge/log.md` headed `## YYYY-MM-DD - knowledge-sync (<mode>): <summary>` (the `knowledge-sync` word is what Step 0 anchors on), then a
-   method one-liner (N verifiers / findings / confirmed / files touched), bullets for the notable
-   corrections (the ones that change how someone works), creations, dedups, gate status. **This entry
-   is the anchor the next sync reads** - its commit is what `LAST_SYNC` resolves to.
-4. **Do not commit.** Leave the diff for the user.
-
-## Report (to the user, Vietnamese)
-
-Lead with the outcome: gate status + scale (`X findings áp vào Y files, Z claims xác nhận đúng`).
-Then the notable corrections as short bullets (what was wrong -> what is true now, with the source
-witness), new/merged concepts, and anything an applier skipped, with the reason. If delta mode
-early-exited: one line - nothing changed since `<since>`, gates green.
+## 1. Prerequisites
+
+1. `bun x --no-install vulcan doctor` passes - the manifest is fresh. Fix what it names first.
+2. Read `.agents/vulcan.manifest.json`: `knowledge.bundle` (the bundle), `packages[].path` (the code
+   areas), `knowledge.syncAreas` (the area map, optional), `name` (the brand, upper case).
+
+## 2. Baseline
+
+1. `bun x --no-install vulcan x okf gen`, then `vulcan x okf check --strict` - it must pass before
+   anything else, so no verifier chases a fact `gen` fixes.
+2. Anchor the last sync by commit, never by date:
+   `LAST_SYNC=$(git log -1 --format=%H -G '^## [0-9-]+ - knowledge-sync' -- <bundle>/log.md)`.
+   Empty: no sync yet - run `full`, or anchor on the commit that added `<bundle>/index.md`. A bare
+   `--since=<date>` is wrong: git reads today's date as "now" and returns nothing.
+3. Changed areas: `git log $LAST_SYNC..HEAD --no-merges --name-only --format= -- <package paths> Makefile make/ scripts/ .github/`,
+   plus `git diff HEAD --stat` for uncommitted code. Commits that touch only the bundle or `docs/` are
+   knowledge maintenance, not drift.
+4. Delta mode, nothing changed: report "already in sync", run Step 5's gates, stop.
+
+## 3. Targets and the workflow
+
+Mode: `delta` by default; `full` when asked (monthly, quarterly, "full") or when the last full sync
+in `log.md` is over 30 days old. Build the targets and run the workflow as
+[references/workflow.md](references/workflow.md) describes - one target per changed area, from the
+area map when the project has one, else from each concept's `resource`.
+
+## 4. Gaps
+
+For each gap the critics propose: durable, load-bearing, and no existing home? Create the concept -
+copy frontmatter, voice and length from 2-3 siblings, verify every claim in source, link it from
+`index.md`. A gap that is really one fact in several files: make one file its home, the rest point
+to it. Never lose a unique fact.
+
+## 5. Gates - validate, fix, repeat
+
+1. `vulcan x okf gen`
+2. `vulcan x okf check --strict`
+3. `vulcan x okf coverage --min 100` - structural coverage stays at 100%.
+
+A gate that fails: fix what it names, run all three again. Stop only when all three pass.
+
+## 6. Log and report
+
+1. Prepend to `<bundle>/log.md`: `## YYYY-MM-DD - knowledge-sync (<mode>): <summary>` - the
+   `knowledge-sync` word is what the next sync anchors on - then one line of method (verifiers,
+   findings, confirmed, files touched) and bullets for the corrections that change how someone works.
+2. Report in the user's language: gate status and scale first (findings applied, files, claims
+   confirmed), then each notable correction (was -> is, with its witness), new or merged concepts,
+   and anything an applier skipped, with the reason. Do not commit.