@aiwg/cli 2026.10.3 → 2026.10.5

package/dist/src/artifacts/relations-builder.js

@@ -0,0 +1,168 @@
+/** Framework build projection. Kept separate so lookup processes import only relations.ts. */
+import fs from 'node:fs';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+import { INDEX_EXTRACTOR_VERSION } from './types.js';
+import { recordTypeForEntry, stableRecordId } from './browser-export.js';
+import { resolveRuleBindingTarget } from './query-engine.js';
+import { Minimatch } from 'minimatch';
+import { FRAMEWORK_RELATIONS_REVISION } from './framework-source-digest.js';
+import { writeIndexFile } from './index-reader.js';
+import { RELATIONS_SCHEMA, RELATIONS_VERSION, RULE_TIERS, emptyRuleStats, } from './relations.js';
+const TARGET_TYPES = new Set(['skill', 'agent', 'flow', 'command']);
+const BINDING_TYPES = { skills: 'skill', agents: 'agent', flows: 'flow' };
+export function relationId(entry) {
+    return stableRecordId(recordTypeForEntry(entry, 'v2'), entry.path);
+}
+function slug(entry) {
+    const normalized = entry.path.replace(/\\/g, '/');
+    const file = path.posix.basename(normalized);
+    return /^(SKILL|AGENT|FLOW|COMMAND|RULE|BEHAVIOR)\.md$/i.test(file)
+        ? path.posix.basename(path.posix.dirname(normalized)) : file.replace(/\.[^.]+$/, '');
+}
+/** Same source bundle boundary as the framework graph (nested extensions retain their owner). */
+function owner(entry) {
+    const match = entry.path.replace(/\\/g, '/').match(/(?:^|\/)agentic\/code\/(frameworks|addons|extensions)\/([^/]+)\//);
+    if (!match)
+        return null; // Top-level behaviors are unowned, not fabricated bundles.
+    const kind = { frameworks: 'framework', addons: 'addon', extensions: 'extension' }[match[1]];
+    return { id: `${kind}:${match[2]}`, kind };
+}
+/** Only rule/action sources affect this projection; no full metadata serialization or file rereads. */
+export function relationsFingerprint(entries) {
+    const sources = entries.filter(entry => TARGET_TYPES.has(entry.type) || ['rule', 'behavior'].includes(entry.type))
+        .map(entry => [entry.path, entry.checksum]).sort((a, b) => a[0].localeCompare(b[0]));
+    return { version: RELATIONS_VERSION, sources: `sha256:${createHash('sha256').update(JSON.stringify({ projectionVersion: FRAMEWORK_RELATIONS_REVISION, extractorVersion: INDEX_EXTRACTOR_VERSION, sources })).digest('hex')}` };
+}
+function statsFor(ids, index) {
+    const stats = emptyRuleStats();
+    for (const id of ids) {
+        const rule = index.rules[id];
+        const enforcement = rule.enforcement ?? 'unknown';
+        const activation = rule.activation ?? 'unknown';
+        stats.by_enforcement[enforcement] = (stats.by_enforcement[enforcement] ?? 0) + 1;
+        stats.by_activation[activation] = (stats.by_activation[activation] ?? 0) + 1;
+        if (enforcement === 'critical' || enforcement === 'high')
+            stats.required_checks++;
+    }
+    return stats;
+}
+export function buildRelations(entries) {
+    const index = {
+        $schema: RELATIONS_SCHEMA, version: RELATIONS_VERSION, generatedAt: '1970-01-01T00:00:00.000Z',
+        fingerprint: relationsFingerprint(entries), artifacts: {}, rules: {}, targets: {}, capabilities: {}, aliases: { targets: {}, rules: {} },
+    };
+    for (const entry of [...entries].sort((a, b) => a.path.localeCompare(b.path))) {
+        if (!TARGET_TYPES.has(entry.type) && !['rule', 'behavior'].includes(entry.type))
+            continue;
+        const { path: sourcePath, type, name, title, kernel, script, governedPaths } = entry;
+        index.artifacts[relationId(entry)] = { path: sourcePath, type, title, ...(name ? { name } : {}), ...(kernel ? { kernel } : {}), ...(script ? { script } : {}), ...(governedPaths ? { governedPaths } : {}) };
+    }
+    const rules = entries.filter(entry => entry.type === 'rule' || entry.type === 'behavior')
+        .sort((a, b) => (a.name ?? a.path).localeCompare(b.name ?? b.path) || a.path.localeCompare(b.path));
+    const targets = entries.filter(entry => TARGET_TYPES.has(entry.type)).sort((a, b) => a.path.localeCompare(b.path));
+    for (const rule of rules) {
+        const id = relationId(rule);
+        const capability = owner(rule);
+        index.rules[id] = {
+            name: rule.name ?? slug(rule), path: rule.path, type: rule.type,
+            activation: rule.activation ?? null, enforcement: rule.ruleEnforcement ?? null,
+            summary: rule.ruleSummary ?? '', capability: capability?.id ?? null,
+            ...(rule.rulePaths ? { paths: rule.rulePaths } : {}),
+            ...(rule.triggers?.length ? { triggers: rule.triggers } : {}),
+            ...(rule.bound_to ? { bound_to: rule.bound_to } : {}), targets: [],
+        };
+        for (const alias of new Set([rule.name, slug(rule), rule.path].filter((value) => !!value))) {
+            (index.aliases.rules[alias] ??= []).push(id);
+        }
+        if (capability) {
+            const owned = index.capabilities[capability.id] ??= {
+                kind: capability.kind, rules_by_tier: { critical: [], high: [], medium: [], low: [] },
+            };
+            const tier = RULE_TIERS.find(tier => tier === rule.ruleEnforcement);
+            if (tier)
+                owned.rules_by_tier[tier].push(id);
+        }
+    }
+    const compiled = rules.map(rule => ({ rule, bindings: Object.fromEntries(Object.entries(rule.bound_to ?? {}).map(([key, patterns]) => [key, patterns.map(pattern => ({ pattern, matcher: new Minimatch(pattern, { nonegate: true, nocomment: true }) }))])) }));
+    const aliases = new Map();
+    for (const target of targets)
+        for (const alias of new Set([target.name, slug(target), relationId(target)].filter((value) => !!value))) {
+            const key = `${target.type}:${alias}`;
+            const group = aliases.get(key) ?? { type: target.type, alias, entries: [] };
+            group.entries.push(target);
+            aliases.set(key, group);
+        }
+    for (const target of targets) {
+        const key = `${target.type}:${relationId(target)}`;
+        // Preserve show's tolerant alias/glob matching, including behavior contracts.
+        const normalized = target.path.replace(/\\/g, '/');
+        const file = path.posix.basename(normalized);
+        const showAliases = [target.name, target.title, target.path, relationId(target),
+            file === 'SKILL.md' ? path.posix.basename(path.posix.dirname(normalized)) : file.replace(/\.[^.]+$/, '')]
+            .filter((value) => !!value);
+        const binding = Object.entries(BINDING_TYPES).find(([, type]) => type === target.type)?.[0];
+        const bound = binding ? compiled.filter(({ bindings }) => bindings[binding]?.some(({ pattern, matcher }) => showAliases.some(alias => alias === pattern || matcher.match(alias)))).map(({ rule }) => relationId(rule)) : [];
+        index.targets[key] = { name: target.name ?? slug(target), path: target.path,
+            rules: bound, rule_stats: emptyRuleStats() };
+    }
+    // Forward edges deliberately use deploy's strict canonical-ID resolver. Do not
+    // turn stale/misspelled/ambiguous bindings into silently missing contracts.
+    const resolved = new Map();
+    for (const rule of rules) {
+        const edges = new Map();
+        for (const [binding, type] of Object.entries(BINDING_TYPES)) {
+            for (const alias of rule.bound_to?.[binding] ?? []) {
+                const key = `${type}:${alias}`;
+                let target = resolved.get(key);
+                if (!target) {
+                    target = resolveRuleBindingTarget(aliases.get(key)?.entries ?? [], type, alias);
+                    resolved.set(key, target);
+                }
+                const id = relationId(target);
+                edges.set(`${type}:${id}`, { type, id });
+                if (type === 'flow') {
+                    // A provider may wrap this flow as a skill, or share an authored skill's
+                    // body. Keep a distinct projection identity so show parity is preserved.
+                    const projectedId = `projected:${id}`;
+                    const projectedKey = `skill:${projectedId}`;
+                    index.targets[projectedKey] ??= { ...index.targets[`flow:${id}`],
+                        rules: [...index.targets[`flow:${id}`].rules], projected_from: { type: 'flow', id } };
+                    edges.set(projectedKey, { type: 'skill', id: projectedId });
+                }
+            }
+        }
+        index.rules[relationId(rule)].targets = [...edges.values()].sort((a, b) => `${a.type}:${a.id}`.localeCompare(`${b.type}:${b.id}`));
+    }
+    // Resolve each accepted spelling once at build time, retaining ambiguities.
+    for (const [key, group] of aliases) {
+        let matches = group.entries;
+        if (group.type !== 'command') {
+            try {
+                matches = [resolveRuleBindingTarget(group.entries, group.type, group.alias)];
+            }
+            catch { /* Preserve all candidates for an explicit ambiguity diagnostic. */ }
+        }
+        index.aliases.targets[key] = matches.map(entry => `${entry.type}:${relationId(entry)}`);
+    }
+    for (const [key, target] of Object.entries(index.targets)) {
+        if (target.projected_from)
+            index.aliases.targets[`skill:projected:${target.name}`] = [key];
+        target.rule_stats = statsFor(target.rules, index);
+    }
+    return index;
+}
+export async function writeRelations(entries, cwd, indexDir, force = false) {
+    const values = Object.values(entries);
+    const fingerprint = relationsFingerprint(values);
+    try {
+        const existing = JSON.parse(fs.readFileSync(path.join(indexDir, 'relations.json'), 'utf8'));
+        if (!force && existing.version === RELATIONS_VERSION && existing.$schema === RELATIONS_SCHEMA
+            && existing.fingerprint.version === fingerprint.version && existing.fingerprint.sources === fingerprint.sources
+            && existing.artifacts && existing.rules && existing.targets && existing.capabilities && existing.aliases?.targets && existing.aliases.rules)
+            return;
+    }
+    catch { /* Missing, corrupt, and unsupported sidecars are regenerated. */ }
+    writeIndexFile(cwd, 'relations.json', buildRelations(values), indexDir);
+}
+//# sourceMappingURL=relations-builder.js.map

package/dist/src/artifacts/relations.js

@@ -0,0 +1,148 @@
+/** Small framework relationship reader. This module never reads metadata.json. */
+import fs from 'node:fs';
+import path from 'node:path';
+import { getGraphIndexDir } from './types.js';
+import { resolveFrameworkIndexRoot } from './framework-index-paths.js';
+import { frameworkSourceDigest } from './framework-source-digest.js';
+import { createHash } from 'node:crypto';
+import { loadRulePinConfigs, resolveRulePins } from '../rules/pins.mjs';
+export const RELATIONS_VERSION = 1;
+export const RELATIONS_SCHEMA = 'https://aiwg.io/schemas/artifacts/relations.v1.schema.json';
+export const RULE_TIERS = ['critical', 'high', 'medium', 'low'];
+export function emptyRuleStats() {
+    return { by_enforcement: {}, by_activation: {}, required_checks: 0 };
+}
+function lookupAlias(aliases, id) {
+    const matches = aliases[id];
+    if (matches?.length > 1)
+        throw new Error(`Ambiguous relationship ID: ${id}: ${matches.join(', ')}`);
+    return matches?.[0];
+}
+export class RelationsReader {
+    index;
+    pinnedRuleIds;
+    constructor(index, pinnedRuleIds = new Set()) {
+        this.index = index;
+        this.pinnedRuleIds = pinnedRuleIds;
+    }
+    rulesForTarget(type, id) {
+        const key = `${type}:${id}`;
+        const resolved = Object.hasOwn(this.index.targets, key) ? key : lookupAlias(this.index.aliases.targets, key);
+        return [...(resolved ? this.index.targets[resolved]?.rules ?? [] : [])];
+    }
+    targetsForRule(id) {
+        const resolved = Object.hasOwn(this.index.rules, id) ? id : lookupAlias(this.index.aliases.rules, id);
+        return resolved ? (this.index.rules[resolved]?.targets ?? []).map(target => ({ ...target })) : [];
+    }
+    rulesForCapability(id, tiers = RULE_TIERS) {
+        const capability = this.index.capabilities[id];
+        return [...new Set(tiers.flatMap(tier => capability?.rules_by_tier[tier] ?? []))];
+    }
+    ruleStats(type, id) {
+        const key = `${type}:${id}`;
+        const resolved = Object.hasOwn(this.index.targets, key) ? key : lookupAlias(this.index.aliases.targets, key);
+        const stats = resolved ? this.index.targets[resolved]?.rule_stats : undefined;
+        if (!stats)
+            return emptyRuleStats();
+        const result = { by_enforcement: { ...stats.by_enforcement }, by_activation: { ...stats.by_activation }, required_checks: stats.required_checks };
+        for (const ruleId of this.index.targets[resolved].rules) {
+            if (!this.pinnedRuleIds.has(ruleId))
+                continue;
+            const activation = this.index.rules[ruleId]?.activation ?? 'unknown';
+            if (activation === 'kernel')
+                continue;
+            result.by_activation[activation] = Math.max(0, (result.by_activation[activation] ?? 0) - 1);
+            if (!result.by_activation[activation])
+                delete result.by_activation[activation];
+            result.by_activation.kernel = (result.by_activation.kernel ?? 0) + 1;
+        }
+        return result;
+    }
+}
+function readerWithPins(index, pinCwd) {
+    const pins = resolveRulePins({ configs: loadRulePinConfigs(pinCwd),
+        rules: Object.entries(index.rules).map(([id, rule]) => ({ ...rule, id })) });
+    return new RelationsReader(index, new Set(pins.rules.map(rule => rule.id)));
+}
+/** Missing, corrupt, or unsupported sidecars return null; invalid pin policy remains an explicit error. */
+export function loadBuiltRelations(cwd, pinCwd = cwd) {
+    let index;
+    try {
+        index = JSON.parse(fs.readFileSync(path.join(getGraphIndexDir(cwd, 'framework'), 'relations.json'), 'utf8'));
+        if (index.version !== RELATIONS_VERSION || index.$schema !== RELATIONS_SCHEMA
+            || index.fingerprint?.version !== RELATIONS_VERSION || !/^sha256:[a-f0-9]{64}$/.test(index.fingerprint.sources)
+            || !index.rules || !index.targets || !index.capabilities || !index.aliases?.targets || !index.aliases.rules)
+            return null;
+    }
+    catch {
+        return null;
+    }
+    return readerWithPins(index, pinCwd);
+}
+export const PREBUILT_RELATIONS_DIR = 'prebuilt/framework-relations';
+/** Validate the running root, never the root from which this module was loaded. */
+function selectPrebuiltRelationsSource(cwd, cacheSourceDigest = true) {
+    const root = resolveFrameworkIndexRoot(cwd);
+    const dir = path.join(root, PREBUILT_RELATIONS_DIR);
+    try {
+        const stamp = JSON.parse(fs.readFileSync(path.join(dir, 'manifest.json'), 'utf8'));
+        const pkg = JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8'));
+        if (stamp.schema_version !== 'aiwg.relationships.prebuilt.v1')
+            return { reader: null, reason: 'unsupported prebuilt relationship schema' };
+        if (stamp.package_version !== pkg.version)
+            return { reader: null, reason: 'prebuilt relationship package version differs' };
+        if (stamp.source_digest !== frameworkSourceDigest(root, cacheSourceDigest))
+            return { reader: null, reason: 'prebuilt relationship source digest differs (modified, added or removed corpus source)' };
+        const text = fs.readFileSync(path.join(dir, 'relations.json'), 'utf8');
+        if (createHash('sha256').update(text).digest('hex') !== stamp.checksums['relations.json'])
+            return { reader: null, reason: 'prebuilt relationship checksum differs' };
+        const bindings = fs.readFileSync(path.join(dir, 'bindings.json'), 'utf8');
+        if (createHash('sha256').update(bindings).digest('hex') !== stamp.checksums['bindings.json'])
+            return { reader: null, reason: 'prebuilt binding checksum differs' };
+        const index = JSON.parse(text);
+        if (index.version !== RELATIONS_VERSION || index.$schema !== RELATIONS_SCHEMA || !index.artifacts
+            || index.fingerprint?.version !== RELATIONS_VERSION || !/^sha256:[a-f0-9]{64}$/.test(index.fingerprint.sources)
+            || !index.rules || !index.targets || !index.capabilities || !index.aliases?.targets || !index.aliases.rules)
+            return { reader: null, reason: 'unsupported prebuilt relationship table' };
+        return { reader: new RelationsReader(index) };
+    }
+    catch {
+        return { reader: null, reason: 'prebuilt relationship tables unavailable or corrupt' };
+    }
+}
+/** Apply local pins only after cache validation so policy errors cannot masquerade as cache misses. */
+export function selectPrebuiltRelations(cwd, pinCwd = cwd, cacheSourceDigest = true) {
+    const selected = selectPrebuiltRelationsSource(cwd, cacheSourceDigest);
+    return selected.reader ? { reader: readerWithPins(selected.reader.index, pinCwd) } : selected;
+}
+/** Synchronous read API: prebuilt first, then this root's built sidecar. */
+export function loadRelations(cwd, pinCwd = cwd, cacheSourceDigest = true) {
+    return selectPrebuiltRelations(cwd, pinCwd, cacheSourceDigest).reader ?? loadBuiltRelations(cwd, pinCwd);
+}
+/** Read paths reconcile through the existing lock/receipt when prebuilt is stale. */
+export async function ensureRelations(cwd, pinCwd = cwd) {
+    const selected = selectPrebuiltRelations(cwd, pinCwd);
+    if (selected.reader)
+        return selected.reader;
+    const root = resolveFrameworkIndexRoot(cwd);
+    if (fs.existsSync(path.join(root, PREBUILT_RELATIONS_DIR, 'manifest.json'))) {
+        console.error(`Relationship tables: ${selected.reason}; using the per-root index (rebuilding if stale).`);
+    }
+    const { refreshFrameworkCapabilities } = await import('./framework-capabilities.js');
+    await refreshFrameworkCapabilities(root, false);
+    return loadBuiltRelations(cwd, pinCwd);
+}
+// Convenience entry points; use one loaded reader for a batch of lookups.
+export function rulesForTarget(type, id, cwd = process.cwd()) {
+    return loadRelations(cwd)?.rulesForTarget(type, id) ?? [];
+}
+export function targetsForRule(id, cwd = process.cwd()) {
+    return loadRelations(cwd)?.targetsForRule(id) ?? [];
+}
+export function rulesForCapability(id, tiers, cwd = process.cwd()) {
+    return loadRelations(cwd)?.rulesForCapability(id, tiers) ?? [];
+}
+export function ruleStats(type, id, cwd = process.cwd()) {
+    return loadRelations(cwd)?.ruleStats(type, id) ?? emptyRuleStats();
+}
+//# sourceMappingURL=relations.js.map

package/dist/src/artifacts/stats.js

@@ -7,6 +7,7 @@
  * @source @src/artifacts/types.ts
  * @tests @test/unit/artifacts/stats.test.ts
  */
+import { loadPrebuiltDeploymentIndex } from './prebuilt-deployment.js';
 import { GRAPH_CONFIGS, loadGlobalGraphConfigs, loadUserGraphConfigs, resolveGraphBackendType } from './types.js';
 import { loadIndexStats, loadGraphIndexFile } from './index-reader.js';
 import { collectGraphIndexFiles, indexPathFor } from './index-files.js';
@@ -34,7 +35,8 @@ export async function showStats(cwd, options = {}) {
     loadGlobalGraphConfigs();
     if (graph) {
         // Single graph mode
-        const stats = loadGraphIndexFile(cwd, 'stats.json', graph);
+        const stats = (graph === 'framework' ? loadPrebuiltDeploymentIndex(cwd)?.stats : undefined)
+            ?? loadGraphIndexFile(cwd, 'stats.json', graph);
         if (!stats) {
             console.error(`Error: No artifact index found for graph '${graph}'.`);
             console.log("Run 'aiwg index build' first to create the index.");
@@ -49,7 +51,8 @@ export async function showStats(cwd, options = {}) {
         .map(([name]) => name);
     const availableGraphs = [];
     for (const g of graphTypes) {
-        const s = loadGraphIndexFile(cwd, 'stats.json', g);
+        const s = (g === 'framework' ? loadPrebuiltDeploymentIndex(cwd)?.stats : undefined)
+            ?? loadGraphIndexFile(cwd, 'stats.json', g);
         if (s)
             availableGraphs.push({ type: g, stats: s });
     }

package/dist/src/artifacts/types.js

@@ -9,8 +9,10 @@
  * @tests @test/unit/artifacts/index-builder.test.ts
  */
 import fs from 'fs';
+import { validateIndexGraphOverrides } from '../config/index-graph-overrides.js';
 import os from 'node:os';
 import path from 'node:path';
+import { getFrameworkIndexBaseDir } from './framework-index-paths.js';
 import { load as loadYaml } from 'js-yaml';
 import { DEFAULT_PROJECT_AIWG_DIR, projectAiwgPath, projectControlPath, resolveProjectAiwgDir, } from '../config/project-artifacts.js';
 /**
@@ -108,7 +110,7 @@ export const INDEX_VERSION = '1.0.0';
  * making the serialized index schema incompatible; a mismatch simply forces a
  * one-time content re-extraction during the next incremental build.
  */
-export const INDEX_EXTRACTOR_VERSION = '2026.08.24.1';
+export const INDEX_EXTRACTOR_VERSION = '2026.10.19.1';
 /**
  * Built-in graph definitions
  */
@@ -463,10 +465,11 @@ export function loadModuleGraphConfigs(cwd, diagnostics) {
  * @implements #426 #726
  */
 export function loadUserGraphConfigs(cwd, diagnostics) {
-    // Built-ins are immutable in index.graphs, but codebase roots/extensions may
+    // Built-ins are immutable in index.graphs, but project/codebase scan fields may
     // be adapted through the explicitly bounded graphOverrides contract (#2123).
     // Reset on every project load so a prior cwd cannot leak its override or
     // detected Python package roots into a later build in the same process.
+    GRAPH_CONFIGS.project = freshBuiltinGraphConfig('project');
     GRAPH_CONFIGS.codebase = detectPythonCodebaseConfig(cwd, freshBuiltinGraphConfig('codebase'));
     projectGraphBackend = undefined;
     // Load module-declared graphs first (frameworks/addons)
@@ -493,8 +496,7 @@ export function loadUserGraphConfigs(cwd, diagnostics) {
             if (g && typeof g === 'object')
                 graphs = g;
             const overrides = idx?.graphOverrides;
-            if (overrides && typeof overrides === 'object')
-                graphOverrides = overrides;
+            graphOverrides = overrides;
         }
     }
     catch {
@@ -521,7 +523,7 @@ export function loadUserGraphConfigs(cwd, diagnostics) {
                     fromDeprecatedYaml = true;
                 }
                 const overrides = idx?.graphOverrides;
-                if (overrides && typeof overrides === 'object') {
+                if (overrides !== undefined) {
                     graphOverrides = overrides;
                     fromDeprecatedYaml = true;
                 }
@@ -531,9 +533,22 @@ export function loadUserGraphConfigs(cwd, diagnostics) {
             // best-effort
         }
     }
-    const codebaseOverride = graphOverrides?.codebase;
-    if (codebaseOverride && typeof codebaseOverride === 'object' && !Array.isArray(codebaseOverride)) {
-        GRAPH_CONFIGS.codebase = applyBuiltinGraphOverride(GRAPH_CONFIGS.codebase, codebaseOverride);
+    const warnOverride = (graph, reason) => {
+        if (diagnostics)
+            diagnostics.push({ graph, reason, source: 'operator-config' });
+        else
+            console.warn(`[aiwg index] Warning: ${reason}`);
+    };
+    const overrideErrors = validateIndexGraphOverrides(graphOverrides);
+    for (const reason of overrideErrors)
+        warnOverride('graphOverrides', reason);
+    if (graphOverrides && typeof graphOverrides === 'object' && !Array.isArray(graphOverrides)) {
+        for (const name of ['project', 'codebase']) {
+            const override = graphOverrides[name];
+            if (override === undefined || validateIndexGraphOverrides({ [name]: override }).length > 0)
+                continue;
+            GRAPH_CONFIGS[name] = applyBuiltinGraphOverride(GRAPH_CONFIGS[name], override);
+        }
     }
     if (!graphs)
         return loaded;
@@ -543,7 +558,10 @@ export function loadUserGraphConfigs(cwd, diagnostics) {
     }
     for (const [name, def] of Object.entries(graphs)) {
         if (name in BUILTIN_GRAPH_CONFIGS) {
-            // Cannot override built-in graph names
+            warnOverride(name, `index.graphs.${name}: built-in graph definitions cannot be overridden here; ` +
+                (name === 'project' || name === 'codebase'
+                    ? `use index.graphOverrides.${name} (supported: scanDirs, extensions)`
+                    : 'no built-in override is supported for this graph'));
             continue;
         }
         const graphConfig = parseGraphDef(name, def);
@@ -662,8 +680,10 @@ let yamlIndexDeprecationWarned = false;
  * @returns Absolute path to the graph's index directory
  */
 export function getGraphIndexDir(cwd, graphType) {
+    if (graphType === 'framework')
+        return path.join(getFrameworkIndexBaseDir(cwd), graphType);
     const config = GRAPH_CONFIGS[graphType];
-    if (graphType === 'framework' || config?.shared) {
+    if (config?.shared) {
         // Shared across projects — XDG data directory
         const xdgData = process.env.XDG_DATA_HOME ?? path.join(os.homedir(), '.local', 'share');
         return path.join(xdgData, 'aiwg', 'index', graphType);

package/dist/src/artifacts/watcher.js

@@ -38,7 +38,7 @@ export function getRunningPid(cwd) {
         return null;
     try {
         const pid = parseInt(fs.readFileSync(pidFile, 'utf-8').trim(), 10);
-        if (!Number.isFinite(pid))
+        if (!Number.isSafeInteger(pid) || pid <= 0)
             return null;
         // Check if the process is still alive
         try {

package/dist/src/auth/credential-store.js

@@ -1,3 +1,4 @@
+import { signalChild } from '../process/signal-child.mjs';
 import { spawn } from "node:child_process";
 import fs from "node:fs/promises";
 import os from "node:os";
@@ -10,7 +11,7 @@ export const defaultCommandRunner = (command, args, stdin = "") => new Promise((
     const collect = (target, chunk) => {
         outputBytes += chunk.length;
         if (outputBytes > 1024 * 1024)
-            child.kill();
+            signalChild(child);
         else
             target.push(chunk);
     };

package/dist/src/catalog/cli.d.mts

@@ -0,0 +1,5 @@
+export function printCatalogHelp(): void;
+export function handleCatalogList(args: string[]): Promise<void>;
+export function handleCatalogInfo(args: string[]): Promise<void>;
+export function handleCatalogSearch(args: string[]): Promise<void>;
+export function main(args: string[]): Promise<void>;

package/dist/src/channel/manager.d.mts

@@ -0,0 +1,20 @@
+export function getPackageRoot(): string;
+export function resolveEffectiveInstallationRoot(
+  packageRoot: string,
+  config: { devMode?: boolean; edgePath?: string } | null | undefined,
+): string;
+export function resolveMcpServerEntrypointPath(
+  packageRoot: string,
+  config: { devMode?: boolean; edgePath?: string } | null | undefined,
+): string;
+export function loadConfig(options?: Record<string, unknown>): Promise<any>;
+export function saveConfig(config: any, options?: Record<string, unknown>): Promise<void>;
+export function getChannel(): Promise<string>;
+export function getFrameworkRoot(options?: Record<string, unknown>): Promise<string>;
+export function switchToEdge(): Promise<void>;
+export function switchToStable(): Promise<void>;
+export function switchToDev(devPath: string): Promise<void>;
+export function switchToNext(): Promise<void>;
+export function switchToNightly(): Promise<void>;
+export function getVersionInfo(): Promise<any>;
+export function updateEdge(): Promise<void>;

package/dist/src/channel/manager.mjs

@@ -9,6 +9,7 @@
  * @version 2024.12.0
  */
 
+import { signalChild } from '../process/signal-child.mjs';
 import fs from 'fs/promises';
 import { readFileSync, existsSync } from 'fs';
 import path from 'path';
@@ -53,9 +54,9 @@ async function runWithTimeout(cmd, args, options = {}) {
     let settled = false;
     const timer = setTimeout(() => {
       if (settled) return;
-      try { child.kill('SIGTERM'); } catch { /* already exited */ }
+      try { signalChild(child, 'SIGTERM'); } catch { /* already exited */ }
       const kill9 = setTimeout(() => {
-        try { child.kill('SIGKILL'); } catch { /* already exited */ }
+        try { signalChild(child, 'SIGKILL'); } catch { /* already exited */ }
       }, 5_000);
       kill9.unref?.();
       settled = true;
@@ -540,6 +541,19 @@ export async function getVersionInfo() {
   const packageJsonPath = path.join(packageRoot, 'package.json');
   const packageJson = JSON.parse(await fs.readFile(packageJsonPath, 'utf8'));
 
+  const launcherRoot = process.env.AIWG_LAUNCHER_ROOT || packageRoot;
+  const runtimePath = resolveEffectiveInstallationRoot(launcherRoot, config);
+  const readVersion = async (root) => {
+    try {
+      const pkg = JSON.parse(await fs.readFile(path.join(root, 'package.json'), 'utf8'));
+      return typeof pkg.version === 'string' ? pkg.version : '(unknown)';
+    } catch {
+      return '(unknown)';
+    }
+  };
+  const launcherVersion = await readVersion(launcherRoot);
+  const runtimeVersion = await readVersion(runtimePath);
+
   // Detect pre-release channel from version string when channel.json says 'stable'
   // This handles the case where a user ran `npm install -g aiwg@next` directly —
   // npm updates the binary but channel.json stays as 'stable'.
@@ -559,6 +573,9 @@ export async function getVersionInfo() {
 
   const info = {
     version,
+    launcherVersion,
+    runtimeVersion,
+    runtimePath,
     channel,
     packageRoot,
     installation,

package/dist/src/cli/command-log.js

@@ -2,7 +2,7 @@ import { mkdir, readFile, rename, stat, writeFile, appendFile } from 'fs/promise
 import { existsSync } from 'fs';
 import { createHash } from 'crypto';
 import path from 'path';
-import os from 'os';
+import { getUserStateDir } from '../config/user-state.js';
 import { readAiwgConfig } from '../config/aiwg-config.js';
 import { PROJECT_AIWG_LOCATION_FILE, projectAiwgPath, projectControlPath, } from '../config/project-artifacts.js';
 const DEFAULT_MAX_BYTES = 1_048_576;
@@ -170,8 +170,7 @@ function resolveLogPath(scope, projectRoot, env) {
             return null;
         return projectAiwgPath(projectRoot, 'telemetry', 'cli-commands.jsonl');
     }
-    const stateHome = env.XDG_STATE_HOME || path.join(os.homedir(), '.local', 'state');
-    return path.join(stateHome, 'aiwg', 'cli-commands.jsonl');
+    return path.join(getUserStateDir(env), 'cli-commands.jsonl');
 }
 async function appendBoundedJsonl(filePath, event, maxBytes) {
     await mkdir(path.dirname(filePath), { recursive: true });

package/dist/src/cli/handlers/artifacts.js

@@ -32,6 +32,9 @@ export const artifactsHandler = {
     description: 'Move or inspect the configured project AIWG artifact root',
     category: 'index',
     aliases: ['artifact'],
+    async help() {
+        return { exitCode: 0, message: usage(), rawOutput: true };
+    },
     async execute(ctx) {
         const action = ctx.args.find(arg => !arg.startsWith('-')) ?? 'help';
         if (action === 'help' || ctx.args.includes('--help') || ctx.args.includes('-h')) {

package/dist/src/cli/handlers/auth.js

@@ -37,6 +37,9 @@ export function createAuthHandler(dependencies = {}) {
         description: "Log in, inspect access, and log out of paid AIWG web resources",
         category: "maintenance",
         aliases: [],
+        async help() {
+            return { exitCode: 0, message: usage(), rawOutput: true };
+        },
         async execute(ctx) {
             if (!ctx.args.length || ["help", "--help", "-h"].includes(ctx.args[0])) {
                 console.log(usage());