@venizia/vulcan 0.1.0-2 → 0.2.0-1

package/base/skills/knowledge-sync/knowledge-sync.workflow.js

@@ -1,17 +1,21 @@
 // Reusable Workflow script for /knowledge-sync.
-// See .agents/plugin/skills/knowledge-sync/SKILL.md for the procedure that drives it.
+// See SKILL.md and references/workflow.md beside it for the procedure that drives it.
 //
 // Invoke via: Workflow({ scriptPath: '.claude/skills/knowledge-sync/knowledge-sync.workflow.js', args: {...} })
 //
 // args = {
-//   repo: '/abs/path/to/ignis',       // repo root - `git rev-parse --show-toplevel`
+//   repo: '/abs/path/to/project',     // repo root - `git rev-parse --show-toplevel`
 //   mode: 'delta' | 'full',
 //   since: 'YYYY-MM-DD',              // last sync date (display label only), read from log.md
 //   gitRange: '<hash>..HEAD',         // commit range since the last sync - what verifiers actually diff
+//   bundle: '.agents/knowledge',      // the manifest's knowledge.bundle
+//   brand: 'ACME',                    // the manifest's name, upper case - the spelling prose keeps
+//   packagePaths: ['packages/core'],  // the manifest's packages[].path
+//   sections: ['overview', 'packages'], // the bundle's top-level directories, for full mode
 //   deltaTargets: [{
 //     key: 'core',                    // short label
-//     area: 'packages/core-server',          // git pathspec(s), space-separated
-//     concepts: ['packages/core-server.md'], // bundle-relative concept files to verify
+//     area: 'packages/core',          // git pathspec(s), space-separated
+//     concepts: ['packages/core.md'], // bundle-relative concept files to verify
 //     hint: 'what changed (from commit subjects) - verify, do not trust',
 //     model: 'opus' | 'sonnet',       // opus for heavy/critical areas, sonnet for small ones
 //   }],
@@ -19,7 +23,7 @@
 export const meta = {
   name: 'knowledge-sync',
   description:
-    'Re-sync .agents/knowledge curated concepts against source: delta-verify changed areas (and in full mode spot-audit everything + critics), then apply fixes per concept file',
+    "Re-sync the knowledge bundle's curated concepts against source: delta-verify changed areas (and in full mode spot-audit everything + critics), then apply fixes per concept file",
   phases: [
     {
       title: 'Verify',
@@ -51,7 +55,11 @@ if (!gitRange) {
   );
 }
 
-const KB = REPO + '/.agents/knowledge';
+const BUNDLE = (input.bundle ?? '.agents/knowledge').replace(/\/+$/, '');
+const KB = REPO + '/' + BUNDLE;
+const BRAND = input.brand ?? 'the project';
+const PACKAGE_PATHS = input.packagePaths ?? [];
+const SECTIONS = input.sections ?? [];
 
 const FINDINGS_SCHEMA = {
   type: 'object',
@@ -66,7 +74,7 @@ const FINDINGS_SCHEMA = {
           concept: {
             type: 'string',
             description:
-              'repo-relative path of the knowledge file, e.g. .agents/knowledge/packages/core-server.md',
+              'repo-relative path of the knowledge file, e.g. .agents/knowledge/packages/core.md',
           },
           kind: { type: 'string', enum: ['wrong', 'stale', 'missing'] },
           claim: {
@@ -120,46 +128,37 @@ const APPLY_SCHEMA = {
   },
 };
 
-const COMMON = `You are a knowledge-bundle verifier for the IGNIS framework monorepo at ${REPO} (branch develop).
-IGNIS is a TypeScript server framework: LoopBack 4's architecture (decorator DI, repository pattern, boot system, components) on Hono's speed.
+const COMMON = `You are a knowledge-bundle verifier for the ${BRAND} repository at ${REPO}. Read ${KB}/index.md first: it says what the project is.
 The knowledge bundle lives at ${KB} - markdown concepts with YAML frontmatter (OKF format).
 Your job: verify the ASSIGNED concept files against the ACTUAL CURRENT SOURCE CODE (ground truth is code, never other docs).
 Method: read each assigned concept file fully; for every load-bearing claim (class names, file paths, lifecycle order, binding keys, routes, hierarchies, enum values, flows, seams), open the real source and confirm it. Use Grep/Read/Bash freely.
 Rules:
 - Ground truth = source code on the current working tree. docs/wiki, AGENTS.md and any CLAUDE.md may themselves be stale - this bundle was created precisely because they were.
 - NEVER run a git command that changes state (no commit/stash/checkout/reset/add). Read-only git (log, diff, show) is fine.
-- Generated files are OUT OF SCOPE - \`okf gen\` and \`vulcan x atlas surface|symbols|releases gen\` own them. Do not report findings on: ${KB}/reference/source-map.md, reference/components.md, reference/helpers.md, reference/binding-keys.md, reference/makefile-targets.md, reference/public-surface.md, any reference/*.json, and the \`<!-- okf:generated:packages-table -->\` region inside overview/monorepo-layout.md. (Exception: note it if you spot an extractor BUG.)
+- Generated content is OUT OF SCOPE - \`vulcan x okf gen\` and \`vulcan x atlas\` own it. Do not report findings on: a file whose frontmatter has a \`generated:\` key, any \`<!-- okf:generated:\` region, and any ${KB}/reference/*.json. (Exception: note it if you spot an extractor BUG.)
 - Report only ACTIONABLE findings: wrong (contradicts code), stale (was true, code moved on), missing (a durable, high-value fact an engineer/agent needs that the concept omits). Skip volatile implementation detail (dependency lists, exhaustive config keys, version numbers).
 - Each finding MUST cite evidence (source path:line or a command you ran + output).
-- Style the bundle follows: hyphen not em-dash, the brand is always written IGNIS, English prose, no version numbers.
+- Style the bundle follows: hyphen not em-dash, the brand is always written ${BRAND}, English prose, no version numbers.
 - Do NOT edit any files. Return findings via structured output only.`;
 
 const DELTA = `\nFocus mode DELTA: first run \`git log ${gitRange} --no-merges --oneline -- <area>\` and \`git diff\` for the interesting commits to learn exactly what changed since the bundle's last sync (${since}). Uncommitted working-tree changes are code too: also run \`git diff HEAD --stat -- <area>\` and read the diff of everything it lists. Then check whether the assigned concepts reflect the NEW reality. Also verify a sample of older claims while you are in the code.`;
 
-// Full-mode spot groups are directory-based so they stay valid as concepts are added.
-const spotGroups = [
-  {
-    key: 'overview-ref',
-    dirs: 'overview/ + the CURATED files under reference/ (glossary.md, key-source-files.md, external-links.md) - the other reference/ files are generated, skip them',
-  },
-  { key: 'architecture', dirs: 'architecture/' },
-  {
-    key: 'packages',
-    dirs: 'packages/ - verify each package concept against its real src/ and package.json exports map',
-  },
-  {
-    key: 'conventions',
-    dirs: 'conventions/ - every rule must still hold in the code; gotchas.md especially, it decays fastest',
-  },
-  {
-    key: 'process',
-    dirs: 'process/ - verify every command, path, Makefile target and step actually exists and works as written (read Makefile, package.json scripts, scripts/, .githooks/, .github/workflows/)',
-  },
-  {
-    key: 'examples',
-    dirs: 'examples/ - verify each concept against the real examples/<dir>: what it demos, how it runs, what it exercises',
-  },
-];
+// Full-mode spot groups: one per bundle section, so they stay valid as sections are added. A few
+// sections that decay in known ways carry a sharper instruction.
+const SECTION_HINTS = {
+  packages: 'verify each package concept against its real src/ and package.json exports map',
+  conventions: 'every rule must still hold in the code; gotchas decay fastest',
+  process:
+    'verify every command, path, make target and step actually exists and works as written (read the Makefile, package.json scripts, scripts/, .github/workflows/)',
+  examples:
+    'verify each concept against the real example: what it demos, how it runs, what it exercises',
+  reference:
+    'audit only the CURATED files - a file with a generated: frontmatter key is generated, skip it',
+};
+const spotGroups = SECTIONS.map(section => ({
+  key: section,
+  dirs: SECTION_HINTS[section] ? `${section}/ - ${SECTION_HINTS[section]}` : `${section}/`,
+}));
 
 phase('Verify');
 const deltaConceptList = deltaTargets.flatMap(t => t.concepts).join(', ');
@@ -189,7 +188,7 @@ if (mode === 'full') {
     ),
     () =>
       agent(
-        `${COMMON}\nRole: COMPLETENESS CRITIC. Do not verify individual claims. Instead ask: what does this repo contain that the bundle does NOT cover? Compare ${KB}/index.md + the file tree under ${KB}/ against reality: ls packages/ examples/, scan major changes since the last sync (\`git log ${gitRange} --oneline\` and uncommitted \`git diff HEAD --stat\`), new components under packages/core-server/src/components/, new helper modules under packages/helpers/src/modules/, new connectors under packages/core-server/src/connectors/. Report (a) findings = missing durable facts in EXISTING concepts, (b) gaps = whole missing concepts worth creating (title + rationale + suggestedPath under ${KB}). A gap must be durable, load-bearing knowledge - not volatile detail. Note: every packages/* and examples/* dir MUST have a concept or \`okf coverage\` fails at under 100% structural.`,
+        `${COMMON}\nRole: COMPLETENESS CRITIC. Do not verify individual claims. Instead ask: what does this repo contain that the bundle does NOT cover? Compare ${KB}/index.md + the file tree under ${KB}/ against reality: the package paths (${PACKAGE_PATHS.length > 0 ? PACKAGE_PATHS.join(', ') : 'see the manifest'}) and their src/ trees, and the major changes since the last sync (\`git log ${gitRange} --oneline\` and uncommitted \`git diff HEAD --stat\`). Report (a) findings = missing durable facts in EXISTING concepts, (b) gaps = whole missing concepts worth creating (title + rationale + suggestedPath under ${KB}). A gap must be durable, load-bearing knowledge - not volatile detail. Note: every directory a coverage axis covers MUST have a concept or \`okf coverage\` fails at under 100% structural.`,
         { label: 'critic:completeness', phase: 'Verify', model: 'opus', schema: GAPS_SCHEMA },
       ),
     () =>
@@ -209,14 +208,15 @@ log(
   `Verify done (${mode}): ${allFindings.length} findings, ${gaps.length} gap proposals, ${confirmedTotal} claims confirmed`,
 );
 
-const GENERATED =
-  /reference\/(source-map|components|helpers|binding-keys|makefile-targets|public-surface)\.md$|reference\/[a-z-]+\.json$/;
+// Generated files never reach an applier: `okf gen` owns them, and a verifier is told so. The JSON
+// tables are the only ones a path alone identifies; the rest are refused by the applier's rules.
+const GENERATED = /reference\/[a-z-]+\.json$/;
 
 const byFile = {};
 for (const finding of allFindings) {
   let path = finding.concept.trim().replace(/^\/+/, '');
-  if (!path.startsWith('.agents/knowledge/')) {
-    path = '.agents/knowledge/' + path.replace(/^\.agents\/knowledge\//, '');
+  if (!path.startsWith(BUNDLE + '/')) {
+    path = BUNDLE + '/' + path;
   }
   path = path.replace(/ \(.*\)$/, '');
   if (GENERATED.test(path)) {
@@ -236,13 +236,13 @@ const applyResults = await parallel(
   files.map(
     path => () =>
       agent(
-        `You are a careful knowledge curator for the IGNIS monorepo at ${REPO}.
+        `You are a careful knowledge curator for the ${BRAND} repository at ${REPO}.
 Target file: ${REPO}/${path}
 Apply the verified findings below to this ONE file. Curation rules:
 - Fix 'wrong' and 'stale' faithfully to the cited evidence - re-check the evidence in source first if it looks off; if a finding does not hold up against the code, SKIP it and say why.
 - For 'missing', fold in only durable, high-value facts; keep the concept TIGHT - this is a curated concept, not a dump. Skip volatile detail.
-- Preserve the file's existing voice, structure, frontmatter (update the description only if now inaccurate), and links. Do not touch any '<!-- okf:generated:' regions.
-- Style: hyphen not em-dash, brand always written IGNIS, English, no version numbers. Never abbreviate identifiers (ProductRepository not ProductRepo).
+- Preserve the file's existing voice, structure, frontmatter (update the description only if now inaccurate), and links. Do not touch any '<!-- okf:generated:' regions. If the file's frontmatter has a generated: key, change nothing and say so.
+- Style: hyphen not em-dash, brand always written ${BRAND}, English, no version numbers. Never abbreviate identifiers (ProductRepository not ProductRepo).
 - Do not edit any other file. NEVER run a state-changing git command.
 Findings (JSON):
 ${JSON.stringify(byFile[path], null, 2)}

package/base/skills/knowledge-sync/references/workflow.md

@@ -0,0 +1,44 @@
+# The knowledge-sync workflow - targets and arguments
+
+## Delta targets
+
+One target per changed area:
+
+- **With an area map** (`knowledge.syncAreas` in the manifest): the file holds a table
+  `| Changed area | Concepts to verify |`. Each changed path that falls under a row's area becomes a
+  target with that row's concepts.
+- **Without one:** each changed package path becomes a target; its concepts are the bundle files
+  whose frontmatter `resource` points into that path. An area no concept names: verify every concept
+  under `packages/` and `architecture/` that mentions it (`grep -l`).
+
+Per target: `key` (short label), `area` (git pathspecs), `concepts` (bundle-relative files), `hint`
+(the commit subjects, summarised - verifiers check it, never trust it), `model` (`opus` for large or
+central areas, `sonnet` for small ones). Merge areas of 3 files or fewer into one target; skip
+formatting-only or lockfile-only changes.
+
+## Running it
+
+Invoke the saved script - never re-write the orchestration inline:
+
+```
+Workflow({
+  scriptPath: '.claude/skills/knowledge-sync/knowledge-sync.workflow.js',
+  args: {
+    repo: '<git rev-parse --show-toplevel>',
+    mode: '<delta|full>',
+    since: '<YYYY-MM-DD of the last sync>',     // a label in prompts and the log
+    gitRange: '<LAST_SYNC hash>..HEAD',         // what the verifiers diff
+    bundle: '<manifest knowledge.bundle>',
+    brand: '<manifest name, upper case>',
+    packagePaths: ['<manifest packages[].path>', ...],
+    sections: ['<each top-level directory of the bundle>', ...],
+    deltaTargets: [...],
+  },
+})
+```
+
+It fans out verifiers (plus one spot-auditor per bundle section and two critics in full mode), groups
+the findings per concept file, and runs one applier per file. It returns
+`{ stats, findingsByFile, applySummaries, gaps, notes }`. Files whose frontmatter carries
+`generated:`, every `<!-- okf:generated:` region, and `reference/*.json` are out of scope: `gen` owns
+them.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@venizia/vulcan",
-  "version": "0.1.0-2",
+  "version": "0.2.0-1",
   "description": "VULCAN - one setup, one workflow for every project: init, sync, doctor, upgrade, and `vulcan x` for the shipped tools. Bun-only.",
   "homepage": "https://github.com/VENIZIA-AI/vulcan/tree/main/packages/cli",
   "repository": {
@@ -26,6 +26,7 @@
   },
   "exports": {
     ".": "./src/index.ts",
+    "./okf": "./src/okf.ts",
     "./package.json": "./package.json"
   },
   "files": [
@@ -43,8 +44,8 @@
     "test": "NODE_ENV=test bun test --env-file=.env.test"
   },
   "dependencies": {
-    "@venizia/vulcan-atlas": "0.1.0-2",
-    "@venizia/vulcan-okf": "0.1.0-2",
+    "@venizia/vulcan-atlas": "0.2.0-1",
+    "@venizia/vulcan-okf": "0.2.0-1",
     "zod": "^4.5.4"
   },
   "devDependencies": {

package/src/commands/help.command.ts

@@ -5,7 +5,8 @@ const HELP = `vulcan ${VULCAN_VERSION} - one setup, one workflow for every proje
 Usage: bun x vulcan <command>
 
   init [--config ts|mts|mjs|js]   Scaffold the project layer (never overwrites)
-  sync [--dry-run]                Write the gitignored agent adapters (CLAUDE.md, .claude/)
+  sync [--dry-run] [--prune]      Write the gitignored agent adapters (CLAUDE.md, .claude/);
+                                  --prune also removes stale hooks and dead skill links
   doctor                          Check the project follows VULCAN; exit 1 on any violation
   upgrade [<version|tag>]         Bump the pinned @venizia/vulcan, then sync
   x <tool> [args...]              Run a shipped tool at the pinned version: okf, atlas

package/src/commands/sync.command.ts

@@ -2,9 +2,19 @@ import { relative } from 'node:path';
 import { ExitCodes } from '../common/index.ts';
 import type { ICommandContext } from '../common/index.ts';
 import { loadConfig } from '../config/index.ts';
-import { planSync, SyncConstants, SyncStatuses } from '../sync/index.ts';
+import { diffBaseRules, planPrune, planSync, SyncConstants, SyncStatuses } from '../sync/index.ts';
 
 const DRY_RUN_FLAG = '--dry-run';
+const PRUNE_FLAG = '--prune';
+const LABEL_WIDTH = 9;
+
+/** Under --dry-run nothing is written, so a write is labelled as what it would do. */
+const DRY_RUN_LABELS: Record<string, string> = {
+  [SyncStatuses.CREATED]: 'would create',
+  [SyncStatuses.REPLACED]: 'would replace',
+  [SyncStatuses.REMOVED]: 'would remove',
+};
+const DRY_RUN_LABEL_WIDTH = Math.max(...Object.values(DRY_RUN_LABELS).map(label => label.length));
 
 export const runSyncCommand = async (opts: ICommandContext): Promise<number> => {
   const loaded = await loadConfig({ root: opts.cwd });
@@ -16,7 +26,12 @@ export const runSyncCommand = async (opts: ICommandContext): Promise<number> =>
   }
 
   const dryRun = opts.args.includes(DRY_RUN_FLAG);
-  const actions = planSync({ root: opts.cwd, config: loaded.config });
+  // Planned before anything is written: prune reads the managed record of the previous sync.
+  const pruned = opts.args.includes(PRUNE_FLAG) ? planPrune({ root: opts.cwd }) : [];
+  const actions = [...planSync({ root: opts.cwd, config: loaded.config }), ...pruned];
+  // Read before the manifest action rewrites the hashes it compares against.
+  const changes = diffBaseRules({ root: opts.cwd });
+  const width = dryRun ? DRY_RUN_LABEL_WIDTH : LABEL_WIDTH;
 
   for (const action of actions) {
     if (!dryRun) {
@@ -24,10 +39,13 @@ export const runSyncCommand = async (opts: ICommandContext): Promise<number> =>
     }
 
     const note = action.note === undefined ? '' : ` (${action.note})`;
+    const label = (dryRun ? DRY_RUN_LABELS[action.status] : undefined) ?? action.status;
+
+    process.stderr.write(`  ${label.padEnd(width)} ${relative(opts.cwd, action.path)}${note}\n`);
+  }
 
-    process.stderr.write(
-      `  ${action.status.padEnd(9)} ${relative(opts.cwd, action.path)}${note}\n`,
-    );
+  for (const { id, change, text } of changes) {
+    process.stderr.write(`  ${change.padEnd(width)} ${[id, text].filter(Boolean).join(' ')}\n`);
   }
 
   const settingsBroken = actions.some(

package/src/commands/upgrade.command.ts

@@ -1,11 +1,10 @@
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
-import { ExitCodes } from '../common/index.ts';
+import { ExitCodes, PACKAGE_NAME } from '../common/index.ts';
 import type { ICommandContext } from '../common/index.ts';
 
 /** Every VULCAN release is a prerelease on the `next` dist-tag until a stable channel exists. */
 const DEFAULT_TARGET = 'next';
-const PACKAGE_NAME = '@venizia/vulcan';
 
 export const buildUpgradeArgs = (opts: { target?: string }): string[] => [
   'add',

package/src/commands/x.command.ts

@@ -1,6 +1,8 @@
 import { readFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
-import { ExitCodes, PACKAGE_ROOT, VulcanTools } from '../common/index.ts';
+import { ExitCodes, PACKAGE_ROOT, ProjectLayout, VulcanTools } from '../common/index.ts';
+import { findConfigFiles, loadConfig, resolvePackages } from '../config/index.ts';
+import { ManifestConstants, renderManifest } from '../manifest/index.ts';
 import type { ICommandContext, IToolPackage } from '../common/index.ts';
 
 const TOOL_PACKAGES: Record<string, IToolPackage> = {
@@ -40,6 +42,36 @@ export const resolveToolBin = (opts: { name: string }): string | undefined => {
   return bin === undefined ? undefined : join(dirname(manifestPath), bin);
 };
 
+/**
+ * The environment a tool runs with: the project's resolved config, validated once here, when the
+ * project has one. No config is fine (atlas serves sources without one); an invalid one is an error.
+ */
+export const buildToolEnvironment = async (opts: {
+  root: string;
+}): Promise<{ ok: true; env: Record<string, string> } | { ok: false; error: string }> => {
+  if (findConfigFiles({ root: opts.root }).length === 0) {
+    return { ok: true, env: {} };
+  }
+
+  const loaded = await loadConfig({ root: opts.root });
+
+  if (!loaded.ok) {
+    return { ok: false, error: loaded.error };
+  }
+
+  const config = { ...loaded.config, packages: resolvePackages({ config: loaded.config }) };
+
+  return {
+    ok: true,
+    env: {
+      [ProjectLayout.CONFIG_ENV]: JSON.stringify(config),
+      [ProjectLayout.ROOT_ENV]: opts.root,
+      // Atlas reads the manifest only; rendered fresh, so a run never sees a stale committed one.
+      [ManifestConstants.ENV]: renderManifest({ root: opts.root, config: loaded.config }),
+    },
+  };
+};
+
 /** Runs the tool as a child on the inherited stdio: vulcan writes nothing to stdout, so MCP stays clean. */
 export const runXCommand = async (opts: ICommandContext): Promise<number> => {
   const [name, ...toolArgs] = opts.args;
@@ -62,8 +94,17 @@ export const runXCommand = async (opts: ICommandContext): Promise<number> => {
     return ExitCodes.FAILURE;
   }
 
+  const environment = await buildToolEnvironment({ root: opts.cwd });
+
+  if (!environment.ok) {
+    process.stderr.write(`vulcan x: ${environment.error}\n`);
+
+    return ExitCodes.FAILURE;
+  }
+
   const child = Bun.spawn([process.execPath, bin, ...toolArgs], {
     cwd: opts.cwd,
+    env: { ...process.env, ...environment.env },
     stdio: ['inherit', 'inherit', 'inherit'],
   });
 

package/src/common/constants.ts

@@ -39,6 +39,10 @@ export class VulcanTools {
 export class ProjectLayout {
   /** How everything unattended runs vulcan: `--no-install` never fetches the unrelated npm package named `vulcan`. */
   static readonly VULCAN_COMMAND = 'bun x --no-install vulcan';
+
+  /** `vulcan x` hands the resolved project config to the tool in these variables; the tools read nothing else. */
+  static readonly CONFIG_ENV = 'VULCAN_CONFIG';
+  static readonly ROOT_ENV = 'VULCAN_PROJECT_ROOT';
   /** `-include`: a fresh clone runs `make install` before node_modules exists. */
   static readonly MAKE_INCLUDE_LINE = '-include node_modules/@venizia/vulcan/base/make/vulcan.mk';
   static readonly STYLE_PACKAGE = '@venizia/dev-configs';

package/src/common/paths.ts

@@ -1,4 +1,4 @@
-import { readFileSync } from 'node:fs';
+import { existsSync, readFileSync, realpathSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 
 /** The installed `@venizia/vulcan` directory, in a workspace or a project's node_modules. */
@@ -7,6 +7,22 @@ export const PACKAGE_ROOT = resolve(import.meta.dir, '..', '..');
 /** The shipped base: rules, slots, skills, settings, hooks, make module, templates. */
 export const BASE_DIRECTORY = join(PACKAGE_ROOT, 'base');
 
+export const PACKAGE_NAME = '@venizia/vulcan';
+
+/**
+ * The base as a project reaches it: through `node_modules/@venizia/vulcan` when that resolves to this
+ * package. bun's isolated install keeps the files in a hashed store directory that every upgrade
+ * replaces, so a link to the real path dies with the next upgrade; the stable path does not.
+ * Anywhere else - no install, or another copy installed - the real directory.
+ */
+export const stableBaseDirectoryOf = (opts: { root: string }): string => {
+  const installed = join(opts.root, 'node_modules', PACKAGE_NAME, 'base');
+
+  return existsSync(installed) && realpathSync(installed) === realpathSync(BASE_DIRECTORY)
+    ? installed
+    : BASE_DIRECTORY;
+};
+
 export const VULCAN_VERSION: string = JSON.parse(
   readFileSync(join(PACKAGE_ROOT, 'package.json'), 'utf8'),
 ).version;

package/src/config/common/constants.ts

@@ -51,4 +51,14 @@ export class ConfigConstants {
   static readonly BASENAME = 'vulcan.config';
   static readonly DEFAULT_KNOWLEDGE_BUNDLE = '.agents/knowledge';
   static readonly RULE_ID_PATTERN = /^(?:[A-Z]+-)?[A-Z]-\d{2}$/;
+  /** The rules a session drops most, printed at every session start unless the project lists its own. */
+  static readonly DEFAULT_OFTEN_DROPPED = [
+    'V-B-03',
+    'V-P-05',
+    'V-P-06',
+    'V-B-04',
+    'V-W-04',
+    'V-C-02',
+    'V-C-10',
+  ];
 }

package/src/config/index.ts

@@ -1,3 +1,4 @@
 export * from './common/index.ts';
 export * from './loader.ts';
 export * from './schema.ts';
+export * from './packages.ts';

package/src/config/packages.ts

@@ -0,0 +1,33 @@
+import type { TResolvedConfig } from './schema.ts';
+
+const DEFAULT_PACKAGES_DIRECTORY = 'packages';
+
+export interface IProjectPackage {
+  dir: string;
+  name: string;
+  /** From the root, resolved: `packages/<dir>` unless the config says otherwise. */
+  path: string;
+  aliases: string[];
+  retired: boolean;
+}
+
+/** The project's packages in release order: `packages`, or the `atlas.packages` alias for one release. */
+export const resolvePackages = (opts: { config: TResolvedConfig }): IProjectPackage[] => {
+  if (opts.config.packages.length > 0) {
+    return opts.config.packages.map(entry => ({
+      dir: entry.dir,
+      name: entry.name,
+      path: entry.path ?? `${DEFAULT_PACKAGES_DIRECTORY}/${entry.dir}`,
+      aliases: entry.aliases,
+      retired: entry.retired,
+    }));
+  }
+
+  return Object.entries(opts.config.atlas.packages ?? {}).map(([dir, name]) => ({
+    dir,
+    name,
+    path: `${DEFAULT_PACKAGES_DIRECTORY}/${dir}`,
+    aliases: [],
+    retired: false,
+  }));
+};

package/src/config/schema.ts

@@ -8,33 +8,118 @@ const HOOK_EVENT = z.string().refine(value => HookEvents.isValid(value), {
   message: `one of: ${[...HookEvents.SCHEME_SET].join(', ')}`,
 });
 
+const PROJECT_PACKAGE = z.strictObject({
+  dir: z.string().regex(/^[a-z0-9][a-z0-9.-]*$/),
+  name: z.string(),
+  /** Where the package lives, from the root; default `packages/<dir>`. */
+  path: z.string().optional(),
+  aliases: z.array(z.string()).default([]),
+  retired: z.boolean().default(false),
+});
+
+/**
+ * A release template: `<dir>` (synonym `<package>`) is the package DIRECTORY - the `packages` key,
+ * never the npm name (`packages/core-server` published as `@acme/server` tags `core-server-v1.2.0`); `<version>` is the
+ * version; `<issue>` an issue number. Every other character is literal. When matching a commit, a
+ * leading `[#<issue>] ` is optional and a trailing ` [<mode>]` is tolerated. A release train that
+ * tags once leaves `<dir>` out (`v<version>`).
+ */
+const RELEASE_TEMPLATE = z.string().refine(value => value.includes('<version>'), {
+  message: 'a template with <version> (and <dir> or <package> for per-package releases)',
+});
+
+/** A renderer by id: a built-in, or a project module (`module`); a bare string is the id alone. */
+const OKF_RENDERER = z.union([
+  z.string().transform(id => ({ id, options: {} })),
+  z.strictObject({
+    id: z.string(),
+    module: z.string().optional(),
+    options: z.record(z.string(), z.unknown()).default({}),
+  }),
+]);
+
+const VIZ_OUTPUT = '.agents/knowledge/viz.html';
+
 /** `.configs/vulcan.config.*` - strict: an unknown key is a typo, and a typo is an error. */
 export const VULCAN_CONFIG_SCHEMA = z.strictObject({
+  /** The project's name in the manifest and in every atlas result; default: the root package name, unscoped. */
+  name: z
+    .string()
+    .regex(/^[a-z0-9][a-z0-9-]*$/)
+    .optional(),
   agents: z.array(CODING_AGENT).default([CodingAgents.CLAUDE]),
   rules: z.record(z.string().regex(ConfigConstants.RULE_ID_PATTERN), z.string()).default({}),
+  /** The project's packages in release order; okf, atlas, make and release read this one list. */
+  packages: z.array(PROJECT_PACKAGE).default([]),
   knowledge: z
     .strictObject({
       bundle: z.string().default(ConfigConstants.DEFAULT_KNOWLEDGE_BUNDLE),
       wiki: z.string().optional(),
       changelogs: z.string().optional(),
+      /** The knowledge-sync skill's map of code areas to concepts. */
+      syncAreas: z.string().optional(),
     })
     .default({ bundle: ConfigConstants.DEFAULT_KNOWLEDGE_BUNDLE }),
-  /** Validated now; consumed once okf reads project config (plan: known gaps). */
   okf: z
     .strictObject({
-      renderers: z.array(z.string()).optional(),
-      coverage: z.array(z.strictObject({ name: z.string(), path: z.string() })).optional(),
+      renderers: z.array(OKF_RENDERER).default([]),
+      regions: z
+        .array(z.strictObject({ id: z.string(), file: z.string(), renderer: z.string() }))
+        .default([]),
+      sections: z
+        .strictObject({
+          order: z.array(z.string()).default([]),
+          labels: z.record(z.string(), z.string()).default({}),
+        })
+        .default({ order: [], labels: {} }),
+      coverage: z.array(z.strictObject({ name: z.string(), path: z.string() })).default([]),
+      denylist: z.array(z.string()).default([]),
+      /** Agent-read files outside the bundle that get a generated contents list when they pass 100 lines. */
+      contents: z
+        .strictObject({ files: z.array(z.string()).default(['AGENTS.md', '.agents/rules.md']) })
+        .default({ files: ['AGENTS.md', '.agents/rules.md'] }),
+      viz: z
+        .strictObject({
+          outputs: z.array(z.string()).default([VIZ_OUTPUT]),
+          brand: z.string().optional(),
+          copy: z.record(z.string(), z.unknown()).optional(),
+        })
+        .default({ outputs: [VIZ_OUTPUT] }),
     })
-    .optional(),
-  /** Validated now; consumed by atlas v1. */
+    .default({
+      renderers: [],
+      regions: [],
+      sections: { order: [], labels: {} },
+      coverage: [],
+      denylist: [],
+      contents: { files: ['AGENTS.md', '.agents/rules.md'] },
+      viz: { outputs: [VIZ_OUTPUT] },
+    }),
   atlas: z
     .strictObject({
+      /** The `packages` alias for one release: directory to npm name, in release order. */
       packages: z.record(z.string(), z.string()).optional(),
-      tagPattern: z.string().optional(),
+      releaseCommit: RELEASE_TEMPLATE.default('[#<issue>] chore(<dir>): release v<version>'),
+      tagPattern: RELEASE_TEMPLATE.default('<dir>-v<version>'),
+      sources: z
+        .array(
+          z.strictObject({
+            name: z.string(),
+            repo: z.string(),
+            ref: z.string().default('develop'),
+          }),
+        )
+        .default([]),
       legacyTagPrefixes: z.array(z.string()).optional(),
-      releaseCommit: z.string().optional(),
+      /** Tags neither read nor checked (globs) - an old layout's tags. */
+      ignoreTags: z.array(z.string()).optional(),
+      typescriptFrom: z.string().optional(),
     })
-    .optional(),
+    .default({
+      releaseCommit: '[#<issue>] chore(<dir>): release v<version>',
+      tagPattern: '<dir>-v<version>',
+      sources: [],
+    }),
   /** Team-shared Claude settings (permissions, env, enabledPlugins...), merged by sync over personal keys. */
   claude: z
     .strictObject({ settings: z.record(z.string(), z.unknown()).default({}) })
@@ -44,6 +129,14 @@ export const VULCAN_CONFIG_SCHEMA = z.strictObject({
       z.strictObject({ event: HOOK_EVENT, matcher: z.string().optional(), command: z.string() }),
     )
     .default([]),
+  /** The session-start digest: the rule IDs it repeats as "the rules sessions drop most" - base or the project's own. */
+  digest: z
+    .strictObject({
+      oftenDropped: z
+        .array(z.string().regex(ConfigConstants.RULE_ID_PATTERN))
+        .default(ConfigConstants.DEFAULT_OFTEN_DROPPED),
+    })
+    .default({ oftenDropped: ConfigConstants.DEFAULT_OFTEN_DROPPED }),
 });
 
 export type VulcanConfig = z.input<typeof VULCAN_CONFIG_SCHEMA>;