@venizia/vulcan-atlas 0.1.0-2 → 0.2.0-0

package/README.md

@@ -1,9 +1,10 @@
 # @venizia/vulcan-atlas
 
 An MCP server that lets an AI agent search and read a project's documentation - the wiki, the
-changelogs and the knowledge bundle - and look up exported symbols and versions. Every hit carries
-an id the agent can read in full and cite. It also generates the symbol and release tables it
-serves. Part of VULCAN; today it serves IGNIS-shaped projects.
+changelogs and the knowledge bundle - and look up exported symbols, versions and changes. Every hit
+carries an id the agent can read in full and cite. It reads a project only through its committed
+manifest (`.agents/vulcan.manifest.json`, written by `vulcan sync`), and it serves other projects
+next to it as sources. Part of VULCAN.
 
 You do not import it. You register it with an MCP client (Claude Code, an IDE agent, ...), which
 starts it over stdio.
@@ -17,20 +18,20 @@ In a project set up with VULCAN, run it through the pinned `vulcan` CLI:
   "mcpServers": {
     "atlas": {
       "command": "bun",
-      "args": ["x", "vulcan", "x", "atlas", "mcp", "--root", "."]
+      "args": ["x", "--no-install", "vulcan", "x", "atlas", "mcp"]
     }
   }
 }
 ```
 
-Without VULCAN, `bun x` runs the published release directly:
+Without a VULCAN project, name the sources to serve:
 
 ```json
 {
   "mcpServers": {
     "atlas": {
       "command": "bun",
-      "args": ["x", "@venizia/vulcan-atlas", "mcp"]
+      "args": ["x", "@venizia/vulcan-atlas", "mcp", "--source", "VENIZIA-AI/ignis@develop"]
     }
   }
 }
@@ -41,25 +42,24 @@ dependency on an MCP SDK - it speaks JSON-RPC over stdio itself.
 
 ## What it serves
 
-The directory the server starts in decides what it reads.
-
-| Started in | Corpora | Freshness |
+| Source | Read from | Freshness |
 |---|---|---|
-| An IGNIS checkout | `wiki`, `changelog`, `knowledge` - read from `docs/wiki/content` and `.agents/knowledge` | Re-indexes before a tool call when a file changed |
-| Anywhere else | `wiki` and `changelog`, as packaged with the installed release | Fixed at the release |
+| The project it starts in | its manifest's bundle, wiki and changelogs; releases from its git tags; symbols from its built `.d.ts` | Re-indexes before a tool call when a file changed |
+| Each `atlas.sources` entry, or `--source <owner/repo>@<ref>` | a git partial clone and sparse checkout under `$XDG_CACHE_HOME/vulcan/atlas/v1/` (a GitHub tarball when git is missing) | The ref's commit (a branch, a tag or a SHA), checked at start; the newest cache when the remote does not answer within 10 s. The cache keeps the newest 3 SHAs |
+| `$XDG_CONFIG_HOME/vulcan/atlas.json` `{ "sources": [...] }` | the same, outside any project | Same |
 
-The knowledge bundle is not shipped in the npm package, so `corpus: "knowledge"` returns nothing
-outside a checkout. A checkout of a sibling framework built the same way (its root `package.json`
-named `@venizia/<family>-workspace`) is served too, under the name `<family>-atlas`.
+atlas ships code only - no packaged corpus. With no project, no `--source` and no user config it
+exits 2. Every hit names its source; `get` takes `source` only when two sources hold the same id.
+A private repository uses `GITHUB_TOKEN`, else `gh auth token`, sent in request headers only.
 
 ## Tools
 
 | Tool | Input | Returns |
 |---|---|---|
 | `search` | `query` (2+ characters), `corpus?` (`all`, `wiki`, `changelog`, `knowledge`), `limit?` (1-50, default 10), `offset?` | A ranked page of hits: `id`, `corpus`, `title`, `headingPath`, `anchor`, `snippet`, `score`; plus `total`, `returned`, and `nextOffset` when more remain |
-| `get` | `id` (from a hit), `maxChars?` (500-50000, default 8000), `cursor?` | The section's `body`, with `next` when it continues |
-| `symbol` | `name`, `package?` (`helpers` or `@venizia/ignis-helpers`) | Where an exported symbol is declared (`file`, `line`, `signature`, the import `specifier`) and the pages that document it; `matches` when several packages export it |
-| `version` | `cwd?` (a project directory) | The IGNIS versions installed there, the newest this release knows, and which are `behind` |
+| `get` | `id` (from a hit), `source?`, `maxChars?` (500-50000, default 8000), `cursor?` | The section's `body`, with `next` when it continues |
+| `symbol` | `name`, `package?` (an npm name, a directory or an alias) | Where an exported symbol is declared (`file`, `line`, `signature`, the import `specifier`) and the pages that document it; `matches` when several packages export it |
+| `version` | `cwd?` (a project directory) | The served packages installed there, the newest release atlas computed for each, and which are `behind` |
 | `changes` | `package?`, `from?`, `to?` (versions, or dates) | The changelog entries between two versions |
 
 Page `search` with `offset: nextOffset`, not `offset + limit`: the reply-size budget can return fewer
@@ -68,32 +68,32 @@ hits than `limit`. Pass a hit's `id` to `get` to read the whole section.
 ## Command line
 
 ```bash
-vulcan-atlas [mcp] [--root <dir>]
-vulcan-atlas surface|symbols|releases gen|check
+vulcan-atlas [mcp] [--root <dir>] [--source <owner/repo>@<ref>]...
+vulcan-atlas pull [--source <name>]
+vulcan-atlas surface gen|check
+vulcan-atlas symbols | releases
+vulcan-atlas changelogs migrate [--dry-run]
+vulcan-atlas concepts stamp|check
 ```
 
-`--root` names the checkout to serve. When you pass it, the directory must be a checkout - the
-server exits rather than falling back to the packaged corpus.
+| Command | What it does |
+|---|---|
+| `mcp` | Serves the project at `--root` (default: the working directory) and its sources over stdio |
+| `pull` | Fetches every source, or one, now |
+| `surface gen\|check` | Writes or checks `reference/public-surface.md` from the built `.d.ts`; `check` exits `1` when it is stale |
+| `symbols`, `releases` | Print what the `symbol`, `version` and `changes` tools read - nothing to commit |
+| `changelogs migrate` | Writes the `packages:` list into every changelog entry that declares none |
+| `concepts stamp\|check` | Locks the signature of each symbol a concept names in `symbols:`; `check` exits `1` when one is gone or changed |
 
 | Exit code | Meaning |
 |---|---|
-| `0` | The client closed the connection |
-| `1` | A failure at startup or while running |
-| `2` | Bad arguments, `--root` is not a checkout, or no corpus was found |
-
-The generators write and check the tables under the project's `.agents/knowledge/reference/`:
-`surface` → `public-surface.md`, `symbols` → `symbols.json` (the `symbol` tool), `releases` →
-`releases.json` (the `version` and `changes` tools). They read the project they run in (the working
-directory); `surface` and `symbols` use the project's own `typescript` and read its built
-`.d.ts`, so build first. `check` exits `1` when a table is stale.
-
-`surface` and `symbols` walk the packages listed in `atlas.packages` of the project's
-`.configs/vulcan.config.*` - directory under `packages/` to npm name, in release order - and stop
-with what to add when it is missing:
-
-```ts
-atlas: { packages: { inversion: '@venizia/ignis-inversion', helpers: '@venizia/ignis-helpers' } },
-```
+| `0` | The client closed the connection, or the command passed |
+| `1` | A failure, or a `check` that found something stale |
+| `2` | Bad arguments, or nothing to serve |
+
+The packages come from the manifest's `packages` - npm names, directories, aliases, retired ones.
+`surface` and the symbol reader use the project's own `typescript` and read its built `.d.ts`, so
+build first.
 
 ## Where it sits
 

package/dist/cjs/changelogs/command.d.ts

@@ -0,0 +1,6 @@
+/** `vulcan x atlas changelogs migrate [--dry-run]` - one pass, for a human to review the diff. */
+export declare const runChangelogsCommand: (opts: {
+    command?: string;
+    argv: string[];
+}) => number;
+//# sourceMappingURL=command.d.ts.map

package/dist/cjs/changelogs/command.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"command.d.ts","sourceRoot":"","sources":["../../../src/changelogs/command.ts"],"names":[],"mappings":"AAKA,kGAAkG;AAClG,eAAO,MAAM,oBAAoB,GAAI,MAAM;IAAE,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,EAAE,CAAA;CAAE,KAAG,MAwBjF,CAAC"}

package/dist/cjs/changelogs/command.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runChangelogsCommand = void 0;
+const project_config_1 = require("../common/project-config");
+const migrate_1 = require("./migrate");
+const DRY_RUN_FLAG = '--dry-run';
+/** `vulcan x atlas changelogs migrate [--dry-run]` - one pass, for a human to review the diff. */
+const runChangelogsCommand = (opts) => {
+    if (opts.command !== 'migrate') {
+        console.error('usage: vulcan x atlas changelogs migrate [--dry-run]');
+        return 2;
+    }
+    const write = !opts.argv.includes(DRY_RUN_FLAG);
+    const report = (0, migrate_1.migrateChangelogs)({ project: (0, project_config_1.readAtlasProject)(), write });
+    const verb = write ? 'wrote' : 'would write';
+    for (const file of report.written) {
+        console.log(`changelogs: ${verb} packages into ${file}`);
+    }
+    for (const file of report.unresolved) {
+        console.log(`changelogs: ${file} names no package - declare its packages by hand`);
+    }
+    console.log(`changelogs: ${report.written.length} ${verb}, ${report.unresolved.length} to declare by hand, ${report.declared} already declared`);
+    return 0;
+};
+exports.runChangelogsCommand = runChangelogsCommand;
+//# sourceMappingURL=command.js.map

package/dist/cjs/changelogs/command.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"command.js","sourceRoot":"","sources":["../../../src/changelogs/command.ts"],"names":[],"mappings":";;;AAAA,4DAA2D;AAC3D,uCAA8C;AAE9C,MAAM,YAAY,GAAG,WAAW,CAAC;AAEjC,kGAAkG;AAC3F,MAAM,oBAAoB,GAAG,CAAC,IAA0C,EAAU,EAAE;IACzF,IAAI,IAAI,CAAC,OAAO,KAAK,SAAS,EAAE,CAAC;QAC/B,OAAO,CAAC,KAAK,CAAC,sDAAsD,CAAC,CAAC;QAEtE,OAAO,CAAC,CAAC;IACX,CAAC;IAED,MAAM,KAAK,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,YAAY,CAAC,CAAC;IAChD,MAAM,MAAM,GAAG,IAAA,2BAAiB,EAAC,EAAE,OAAO,EAAE,IAAA,iCAAgB,GAAE,EAAE,KAAK,EAAE,CAAC,CAAC;IACzE,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,aAAa,CAAC;IAE7C,KAAK,MAAM,IAAI,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;QAClC,OAAO,CAAC,GAAG,CAAC,eAAe,IAAI,kBAAkB,IAAI,EAAE,CAAC,CAAC;IAC3D,CAAC;IAED,KAAK,MAAM,IAAI,IAAI,MAAM,CAAC,UAAU,EAAE,CAAC;QACrC,OAAO,CAAC,GAAG,CAAC,eAAe,IAAI,kDAAkD,CAAC,CAAC;IACrF,CAAC;IAED,OAAO,CAAC,GAAG,CACT,eAAe,MAAM,CAAC,OAAO,CAAC,MAAM,IAAI,IAAI,KAAK,MAAM,CAAC,UAAU,CAAC,MAAM,wBAAwB,MAAM,CAAC,QAAQ,mBAAmB,CACpI,CAAC;IAEF,OAAO,CAAC,CAAC;AACX,CAAC,CAAC;AAxBW,QAAA,oBAAoB,wBAwB/B"}

package/dist/cjs/changelogs/index.d.ts

@@ -0,0 +1,4 @@
+export * from './command';
+export * from './migrate';
+export * from './resolve';
+//# sourceMappingURL=index.d.ts.map

package/dist/cjs/changelogs/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/changelogs/index.ts"],"names":[],"mappings":"AAAA,cAAc,WAAW,CAAC;AAC1B,cAAc,WAAW,CAAC;AAC1B,cAAc,WAAW,CAAC"}

package/dist/cjs/changelogs/index.js

@@ -0,0 +1,20 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./command"), exports);
+__exportStar(require("./migrate"), exports);
+__exportStar(require("./resolve"), exports);
+//# sourceMappingURL=index.js.map

package/dist/cjs/changelogs/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/changelogs/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,4CAA0B;AAC1B,4CAA0B;AAC1B,4CAA0B"}

package/dist/cjs/changelogs/migrate.d.ts

@@ -0,0 +1,20 @@
+import type { IAtlasProject } from '../common/project-config';
+export interface IMigrateReport {
+    /** Entries given a `packages:` list (written, or would be on a dry run). */
+    written: string[];
+    /** Entries nothing resolved for: a human declares their packages. */
+    unresolved: string[];
+    /** Entries that already declared a list - never touched. */
+    declared: number;
+}
+/**
+ * Project Contract v1, C3: writes `packages: [<npm name>, ...]` into every dated changelog entry
+ * that declares none, from what today's resolution finds (frontmatter, a Package column, npm-name
+ * mentions, `packages/<dir>` paths). A declared list is never overwritten; what resolves to nothing
+ * is reported for a human. `write: false` reports without writing.
+ */
+export declare const migrateChangelogs: (opts: {
+    project: IAtlasProject;
+    write: boolean;
+}) => IMigrateReport;
+//# sourceMappingURL=migrate.d.ts.map

package/dist/cjs/changelogs/migrate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"migrate.d.ts","sourceRoot":"","sources":["../../../src/changelogs/migrate.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAM7D,MAAM,WAAW,cAAc;IAC7B,4EAA4E;IAC5E,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,qEAAqE;IACrE,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,4DAA4D;IAC5D,QAAQ,EAAE,MAAM,CAAC;CAClB;AAYD;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,GAAI,MAAM;IACtC,OAAO,EAAE,aAAa,CAAC;IACvB,KAAK,EAAE,OAAO,CAAC;CAChB,KAAG,cAwCH,CAAC"}

package/dist/cjs/changelogs/migrate.js

@@ -0,0 +1,54 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.migrateChangelogs = void 0;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const resolve_1 = require("./resolve");
+const DATED_ENTRY = /^\d{4}-\d{2}-\d{2}-.*\.md$/;
+const FRONTMATTER_BLOCK = /^---\r?\n([\s\S]*?)\r?\n---/;
+/** The entry with `line` added as the last frontmatter key, or a frontmatter of its own - in its own line endings. */
+const withFrontmatterLine = (opts) => {
+    const block = FRONTMATTER_BLOCK.exec(opts.text);
+    const eol = opts.text.includes('\r\n') ? '\r\n' : '\n';
+    return block === null
+        ? `---${eol}${opts.line}${eol}---${eol}${eol}${opts.text}`
+        : `---${eol}${block[1]}${eol}${opts.line}${eol}---${opts.text.slice(block[0].length)}`;
+};
+/**
+ * Project Contract v1, C3: writes `packages: [<npm name>, ...]` into every dated changelog entry
+ * that declares none, from what today's resolution finds (frontmatter, a Package column, npm-name
+ * mentions, `packages/<dir>` paths). A declared list is never overwritten; what resolves to nothing
+ * is reported for a human. `write: false` reports without writing.
+ */
+const migrateChangelogs = (opts) => {
+    const { project } = opts;
+    const directory = project.knowledge.changelogs;
+    const report = { written: [], unresolved: [], declared: 0 };
+    if (directory === undefined || !(0, node_fs_1.existsSync)(directory)) {
+        return report;
+    }
+    for (const file of (0, node_fs_1.readdirSync)(directory)
+        .filter(name => DATED_ENTRY.test(name))
+        .sort()) {
+        const path = (0, node_path_1.join)(directory, file);
+        const text = (0, node_fs_1.readFileSync)(path, 'utf8');
+        const shown = (0, node_path_1.relative)(project.root, path);
+        if ('packages' in (0, resolve_1.splitFrontmatter)(text).data) {
+            report.declared += 1;
+            continue;
+        }
+        const names = (0, resolve_1.resolveChangelogPackages)({ text, packages: project.packages }).map(dir => project.packages.find(entry => entry.dir === dir)?.name ?? dir);
+        if (names.length === 0) {
+            report.unresolved.push(shown);
+            continue;
+        }
+        if (opts.write) {
+            const line = `packages: [${names.map(name => `'${name}'`).join(', ')}]`;
+            (0, node_fs_1.writeFileSync)(path, withFrontmatterLine({ text, line }));
+        }
+        report.written.push(shown);
+    }
+    return report;
+};
+exports.migrateChangelogs = migrateChangelogs;
+//# sourceMappingURL=migrate.js.map

package/dist/cjs/changelogs/migrate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"migrate.js","sourceRoot":"","sources":["../../../src/changelogs/migrate.ts"],"names":[],"mappings":"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"}

package/dist/cjs/changelogs/resolve.d.ts

@@ -0,0 +1,21 @@
+import type { IAtlasPackage } from '../common/project-config';
+export declare const resolveAll: (opts: {
+    values: string[];
+    packages: IAtlasPackage[];
+}) => string[];
+export declare const splitFrontmatter: (text: string) => {
+    data: Record<string, unknown>;
+    body: string;
+};
+/**
+ * The packages one changelog file names, by the first rule that hits: a `packages:` frontmatter
+ * list, a Details table's `Package` column, npm-name mentions, then `packages/<dir>` paths. Only the
+ * configured packages count, retired ones included; a file none of the four answer for resolves to
+ * none - it never guesses. `changelogs migrate` writes what this finds, once, for a human to review;
+ * nothing else reads prose (Project Contract v1, C3).
+ */
+export declare const resolveChangelogPackages: (opts: {
+    text: string;
+    packages: IAtlasPackage[];
+}) => string[];
+//# sourceMappingURL=resolve.d.ts.map

package/dist/cjs/changelogs/resolve.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve.d.ts","sourceRoot":"","sources":["../../../src/changelogs/resolve.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAc7D,eAAO,MAAM,UAAU,GAAI,MAAM;IAAE,MAAM,EAAE,MAAM,EAAE,CAAC;IAAC,QAAQ,EAAE,aAAa,EAAE,CAAA;CAAE,KAAG,MAAM,EAMxF,CAAC;AAiFF,eAAO,MAAM,gBAAgB,GAAI,MAAM,MAAM,KAAG;IAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAU5F,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,wBAAwB,GAAI,MAAM;IAC7C,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,aAAa,EAAE,CAAC;CAC3B,KAAG,MAAM,EA2BT,CAAC"}

package/dist/cjs/changelogs/resolve.js

@@ -0,0 +1,114 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveChangelogPackages = exports.splitFrontmatter = exports.resolveAll = void 0;
+const package_map_1 = require("../common/package-map");
+const FRONTMATTER_PATTERN = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n)?/;
+const TABLE_ROW_PATTERN = /^\s*\|(.*)\|\s*$/;
+const TABLE_SEPARATOR_PATTERN = /^\s*\|[\s|:-]+\|\s*$/;
+const byText = (left, right) => {
+    if (left === right) {
+        return 0;
+    }
+    return left < right ? -1 : 1;
+};
+const resolveAll = (opts) => {
+    const resolved = opts.values
+        .map(value => (0, package_map_1.directoryOf)({ value, packages: opts.packages }))
+        .filter((name) => name !== undefined);
+    return [...new Set(resolved)].sort(byText);
+};
+exports.resolveAll = resolveAll;
+const cellsOf = (line) => {
+    const matched = line.match(TABLE_ROW_PATTERN);
+    return matched ? matched[1].split('|').map(cell => cell.trim()) : [];
+};
+/**
+ * Every value under a `Package` column, across every table in the body. A row whose cell count
+ * differs from its header's contributes nothing - a stray `|` shifts the column, it never renames it.
+ */
+const packageColumnValuesOf = (opts) => {
+    const lines = opts.body.split('\n');
+    const values = [];
+    let columnIndex = -1;
+    let columnCount = 0;
+    for (const line of lines) {
+        const cells = cellsOf(line);
+        if (cells.length === 0) {
+            columnIndex = -1;
+            continue;
+        }
+        if (TABLE_SEPARATOR_PATTERN.test(line)) {
+            continue;
+        }
+        const headerIndex = cells.findIndex(cell => cell.toLowerCase() === 'package');
+        if (columnIndex === -1 || headerIndex !== -1) {
+            columnIndex = headerIndex;
+            columnCount = cells.length;
+            continue;
+        }
+        if (cells.length === columnCount) {
+            values.push(cells[columnIndex]);
+        }
+    }
+    return values;
+};
+const escapeLiteral = (opts) => opts.text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+/**
+ * Every npm-name mention anywhere in the body, as the names themselves: each package's name, and
+ * each alias spelled as a npm name (an old or a misspelled one a changelog used). Longest first, and
+ * a name followed by more of a name (`@a/shop-other` for `@a/shop`) is no mention of it; a
+ * sub-path (`@a/shop/core`) is.
+ */
+const bodyMentionsOf = (opts) => {
+    const names = opts.packages
+        .flatMap(entry => [entry.name, ...entry.aliases.filter(alias => alias.startsWith('@'))])
+        .sort((left, right) => right.length - left.length);
+    if (names.length === 0) {
+        return [];
+    }
+    const pattern = new RegExp(`(?:${names.map(name => escapeLiteral({ text: name })).join('|')})(?![a-z0-9-])`, 'g');
+    return [...opts.body.matchAll(pattern)].map(match => match[0]);
+};
+/** `packages/<dir>`, the heading convention every changelog before 2026-09 used to name its package. */
+const PACKAGE_PATH_PATTERN = /packages\/([a-z0-9-]+)/g;
+const bodyPathsOf = (opts) => [...opts.body.matchAll(PACKAGE_PATH_PATTERN)].map(match => match[1]);
+const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+const splitFrontmatter = (text) => {
+    const matched = text.match(FRONTMATTER_PATTERN);
+    if (!matched) {
+        return { data: {}, body: text };
+    }
+    const parsed = Bun.YAML.parse(matched[1]);
+    return { data: isRecord(parsed) ? parsed : {}, body: text.slice(matched[0].length) };
+};
+exports.splitFrontmatter = splitFrontmatter;
+/**
+ * The packages one changelog file names, by the first rule that hits: a `packages:` frontmatter
+ * list, a Details table's `Package` column, npm-name mentions, then `packages/<dir>` paths. Only the
+ * configured packages count, retired ones included; a file none of the four answer for resolves to
+ * none - it never guesses. `changelogs migrate` writes what this finds, once, for a human to review;
+ * nothing else reads prose (Project Contract v1, C3).
+ */
+const resolveChangelogPackages = (opts) => {
+    const { data, body } = (0, exports.splitFrontmatter)(opts.text);
+    const { packages } = opts;
+    const listed = Array.isArray(data.packages) ? data.packages : [];
+    const declared = (0, exports.resolveAll)({
+        values: listed.filter((item) => typeof item === 'string'),
+        packages,
+    });
+    if (declared.length > 0) {
+        return declared;
+    }
+    const tabled = (0, exports.resolveAll)({ values: packageColumnValuesOf({ body }), packages });
+    if (tabled.length > 0) {
+        return tabled;
+    }
+    const mentioned = (0, exports.resolveAll)({ values: bodyMentionsOf({ body, packages }), packages });
+    if (mentioned.length > 0) {
+        return mentioned;
+    }
+    return (0, exports.resolveAll)({ values: bodyPathsOf({ body }), packages });
+};
+exports.resolveChangelogPackages = resolveChangelogPackages;
+//# sourceMappingURL=resolve.js.map

package/dist/cjs/changelogs/resolve.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve.js","sourceRoot":"","sources":["../../../src/changelogs/resolve.ts"],"names":[],"mappings":"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"}

package/dist/cjs/cli/index.d.ts

@@ -1,2 +1,3 @@
 export * from './modes';
+export * from './sources';
 //# sourceMappingURL=index.d.ts.map

package/dist/cjs/cli/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/cli/index.ts"],"names":[],"mappings":"AAAA,cAAc,SAAS,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/cli/index.ts"],"names":[],"mappings":"AAAA,cAAc,SAAS,CAAC;AACxB,cAAc,WAAW,CAAC"}

package/dist/cjs/cli/index.js

@@ -15,4 +15,5 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./modes"), exports);
+__exportStar(require("./sources"), exports);
 //# sourceMappingURL=index.js.map

package/dist/cjs/cli/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/cli/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,0CAAwB"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/cli/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,0CAAwB;AACxB,4CAA0B"}

package/dist/cjs/cli/modes.d.ts

@@ -1,11 +1,6 @@
-import type { TAtlasMode } from '../common';
 /** A `root`/`packageDirectory` pair that satisfies neither mode, or a malformed `--root` flag. */
 export declare class ModeUsageError extends Error {
 }
-export interface IResolvedMode {
-    mode: TAtlasMode;
-    root: string;
-}
 /** `--root`'s value from `argv`, and whether the caller passed it explicitly (cwd is the fallback). */
 export interface IRootArgument {
     value: string;
@@ -27,14 +22,4 @@ export declare const findPackageDirectory: (opts: {
 export declare const readRootArgument: (opts: {
     argv: string[];
 }) => IRootArgument;
-/**
- * Repo mode wins when `root` is a checkout; otherwise the packaged snapshot next to
- * `packageDirectory`; otherwise a `ModeUsageError` naming both paths it checked. An explicit
- * `--root` that is not a checkout never falls back to the snapshot - it named the wrong directory.
- */
-export declare const resolveMode: (opts: {
-    root: string;
-    packageDirectory: string;
-    explicitRoot?: boolean;
-}) => IResolvedMode;
 //# sourceMappingURL=modes.d.ts.map

package/dist/cjs/cli/modes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"modes.d.ts","sourceRoot":"","sources":["../../../src/cli/modes.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAgB3C,kGAAkG;AAClG,qBAAa,cAAe,SAAQ,KAAK;CAAG;AAE5C,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,UAAU,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;CACd;AAED,uGAAuG;AACvG,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,OAAO,CAAC;CACnB;AAoBD,+GAA+G;AAC/G,eAAO,MAAM,kBAAkB,GAAI,MAAM;IAAE,SAAS,EAAE,MAAM,CAAA;CAAE,KAAG,MAAM,GAAG,SAC7C,CAAC;AAc9B;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,GAAI,MAAM;IAAE,cAAc,EAAE,MAAM,CAAA;CAAE,KAAG,MAYvE,CAAC;AAEF,oGAAoG;AACpG,eAAO,MAAM,gBAAgB,GAAI,MAAM;IAAE,IAAI,EAAE,MAAM,EAAE,CAAA;CAAE,KAAG,aA0B3D,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,WAAW,GAAI,MAAM;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,gBAAgB,EAAE,MAAM,CAAC;IACzB,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB,KAAG,aAsBH,CAAC"}
+{"version":3,"file":"modes.d.ts","sourceRoot":"","sources":["../../../src/cli/modes.ts"],"names":[],"mappings":"AAOA,kGAAkG;AAClG,qBAAa,cAAe,SAAQ,KAAK;CAAG;AAE5C,uGAAuG;AACvG,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,OAAO,CAAC;CACnB;AAoBD,+GAA+G;AAC/G,eAAO,MAAM,kBAAkB,GAAI,MAAM;IAAE,SAAS,EAAE,MAAM,CAAA;CAAE,KAAG,MAAM,GAAG,SAC7C,CAAC;AAc9B;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,GAAI,MAAM;IAAE,cAAc,EAAE,MAAM,CAAA;CAAE,KAAG,MAYvE,CAAC;AAEF,oGAAoG;AACpG,eAAO,MAAM,gBAAgB,GAAI,MAAM;IAAE,IAAI,EAAE,MAAM,EAAE,CAAA;CAAE,KAAG,aA0B3D,CAAC"}

package/dist/cjs/cli/modes.js

@@ -1,8 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.resolveMode = exports.readRootArgument = exports.findPackageDirectory = exports.readPackageVersion = exports.ModeUsageError = void 0;
-const common_1 = require("../common");
-const layout_1 = require("../common/layout");
+exports.readRootArgument = exports.findPackageDirectory = exports.readPackageVersion = exports.ModeUsageError = void 0;
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
 // The npm package name, not `AtlasConstants.SERVER_NAME` (`vulcan-atlas`, the bin/MCP server name) -
@@ -66,24 +64,4 @@ const readRootArgument = (opts) => {
     return { value, explicit: true };
 };
 exports.readRootArgument = readRootArgument;
-/**
- * Repo mode wins when `root` is a checkout; otherwise the packaged snapshot next to
- * `packageDirectory`; otherwise a `ModeUsageError` naming both paths it checked. An explicit
- * `--root` that is not a checkout never falls back to the snapshot - it named the wrong directory.
- */
-const resolveMode = (opts) => {
-    const { root, packageDirectory, explicitRoot = false } = opts;
-    if ((0, layout_1.isRepositoryCheckout)({ root })) {
-        return { mode: common_1.AtlasModes.REPOSITORY, root };
-    }
-    if (explicitRoot) {
-        throw new ModeUsageError(`${root} is not a VENIZIA family checkout - a checkout needs ${layout_1.WIKI_DIRECTORY}, ${layout_1.CHANGELOG_DIRECTORY}, ${layout_1.KNOWLEDGE_DIRECTORY} and a root package.json named like ${layout_1.WORKSPACE_PACKAGE_NAME} (any @venizia/<family>-workspace)`);
-    }
-    const distDirectory = (0, node_path_1.join)(packageDirectory, 'dist');
-    if ((0, node_fs_1.existsSync)((0, node_path_1.join)(distDirectory, layout_1.SNAPSHOT_DIRECTORY))) {
-        return { mode: common_1.AtlasModes.SNAPSHOT, root: distDirectory };
-    }
-    throw new ModeUsageError(`no IGNIS checkout at ${root} and no packaged snapshot under ${packageDirectory} - pass --root <dir> pointing at a checkout`);
-};
-exports.resolveMode = resolveMode;
 //# sourceMappingURL=modes.js.map

package/dist/cjs/cli/modes.js.map

@@ -1 +1 @@
-{"version":3,"file":"modes.js","sourceRoot":"","sources":["../../../src/cli/modes.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"modes.js","sourceRoot":"","sources":["../../../src/cli/modes.ts"],"names":[],"mappings":"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"}

package/dist/cjs/cli/sources.d.ts

@@ -0,0 +1,14 @@
+import type { IAtlasSource } from '../sources/common';
+/** `owner/repo@ref`, `owner/repo` (on develop), or a git URL with `@ref` - the name is the repository's. */
+export declare const parseSourceArgument: (opts: {
+    value: string;
+}) => IAtlasSource;
+/** Every `--source <value>` and `--source=<value>`, in order. */
+export declare const readSourceArguments: (opts: {
+    argv: string[];
+}) => IAtlasSource[];
+/** `$XDG_CONFIG_HOME/vulcan/atlas.json` - \`{ "sources": [{ "name", "repo", "ref" }] }\`, for use outside any project. */
+export declare const readUserSources: (opts?: {
+    configHome?: string;
+}) => IAtlasSource[];
+//# sourceMappingURL=sources.d.ts.map

package/dist/cjs/cli/sources.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sources.d.ts","sourceRoot":"","sources":["../../../src/cli/sources.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAKrD,4GAA4G;AAC5G,eAAO,MAAM,mBAAmB,GAAI,MAAM;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,KAAG,YAO7D,CAAC;AAEF,iEAAiE;AACjE,eAAO,MAAM,mBAAmB,GAAI,MAAM;IAAE,IAAI,EAAE,MAAM,EAAE,CAAA;CAAE,KAAG,YAAY,EAWvE,CAAC;AAEL,0HAA0H;AAC1H,eAAO,MAAM,eAAe,GAAI,OAAM;IAAE,UAAU,CAAC,EAAE,MAAM,CAAA;CAAO,KAAG,YAAY,EAuBhF,CAAC"}

package/dist/cjs/cli/sources.js

@@ -0,0 +1,48 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readUserSources = exports.readSourceArguments = exports.parseSourceArgument = void 0;
+const node_fs_1 = require("node:fs");
+const node_os_1 = require("node:os");
+const node_path_1 = require("node:path");
+const DEFAULT_REF = 'develop';
+const SOURCE_FLAG = '--source';
+/** `owner/repo@ref`, `owner/repo` (on develop), or a git URL with `@ref` - the name is the repository's. */
+const parseSourceArgument = (opts) => {
+    const at = opts.value.lastIndexOf('@');
+    const hasRef = at > opts.value.lastIndexOf('/');
+    const repo = hasRef ? opts.value.slice(0, at) : opts.value;
+    const ref = hasRef ? opts.value.slice(at + 1) : DEFAULT_REF;
+    return { name: (0, node_path_1.basename)(repo).replace(/\.git$/, ''), repo, ref };
+};
+exports.parseSourceArgument = parseSourceArgument;
+/** Every `--source <value>` and `--source=<value>`, in order. */
+const readSourceArguments = (opts) => opts.argv.flatMap((argument, index) => {
+    if (argument.startsWith(`${SOURCE_FLAG}=`)) {
+        return [(0, exports.parseSourceArgument)({ value: argument.slice(SOURCE_FLAG.length + 1) })];
+    }
+    const value = opts.argv[index + 1];
+    return argument === SOURCE_FLAG && value !== undefined && !value.startsWith('--')
+        ? [(0, exports.parseSourceArgument)({ value })]
+        : [];
+});
+exports.readSourceArguments = readSourceArguments;
+/** `$XDG_CONFIG_HOME/vulcan/atlas.json` - \`{ "sources": [{ "name", "repo", "ref" }] }\`, for use outside any project. */
+const readUserSources = (opts = {}) => {
+    const home = opts.configHome ?? process.env.XDG_CONFIG_HOME ?? (0, node_path_1.join)((0, node_os_1.homedir)(), '.config');
+    const file = (0, node_path_1.join)(home, 'vulcan', 'atlas.json');
+    if (!(0, node_fs_1.existsSync)(file)) {
+        return [];
+    }
+    const config = JSON.parse((0, node_fs_1.readFileSync)(file, 'utf8'));
+    return (config.sources ?? []).flatMap(source => typeof source.name === 'string' && typeof source.repo === 'string'
+        ? [
+            {
+                name: source.name,
+                repo: source.repo,
+                ref: typeof source.ref === 'string' ? source.ref : DEFAULT_REF,
+            },
+        ]
+        : []);
+};
+exports.readUserSources = readUserSources;
+//# sourceMappingURL=sources.js.map