@aiwg/cli 2026.10.1 → 2026.10.4

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/repair.js

@@ -1,7 +1,7 @@
 import { createHash } from 'node:crypto';
 import { mkdir, readFile, rm, writeFile } from 'node:fs/promises';
 import path from 'node:path';
-import { PROJECT_CONTROL_PLANE_FILES, auditProjectArtifactHealth, } from '../config/project-artifacts.js';
+import { PROJECT_CONTROL_PLANE_FILES, auditProjectArtifactHealth, isProjectArtifactRootExternal, } from '../config/project-artifacts.js';
 async function optionalBytes(filePath) {
     try {
         return await readFile(filePath);
@@ -21,14 +21,19 @@ async function writeAndVerify(destination, bytes) {
 }
 export async function repairProjectArtifacts(options) {
     const projectDir = path.resolve(options.projectDir);
+    // Refuse local mode before auditing — the audit's own payload scan is a
+    // no-op in local mode now (#274), but the refusal should not depend on
+    // running the audit first either (repair.ts:45-51 previously audited
+    // before this check existed, so the refusal reason always paid for the
+    // scan it was about to reject).
+    if (!isProjectArtifactRootExternal(projectDir)) {
+        throw new Error('No external AIWG artifact corpus is configured for this project.');
+    }
     const before = auditProjectArtifactHealth(projectDir);
     const copied = [];
     const migrated = [];
     const archivedConflicts = [];
     const removed = [];
-    if (!before.external_configured) {
-        throw new Error('No external AIWG artifact corpus is configured for this project.');
-    }
     if (!before.external_reachable) {
         throw new Error(`External AIWG artifact corpus is unavailable: ${before.artifact_root}`);
     }

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>;