aiwg 2026.7.16 → 2026.7.18

package/LICENSE

@@ -18,4 +18,4 @@ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+SOFTWARE.

package/README.md

@@ -6,13 +6,26 @@
 
 **Multi-agent AI framework for Claude Code, Copilot, Cursor, Warp, and 6 more platforms**
 
-200+ agents, 67+ CLI commands, 400+ deployable agent/skill/command/rule artifacts, 8 core frameworks, 27 addons, and a training marketplace package. SDLC workflows, digital forensics, research management, marketing operations, media curation, ops infrastructure, knowledge base, and fine-tuning dataset curation — all deployable with one command.
+200+ agents, 109+ CLI commands, 400+ deployable agent/skill/command/rule artifacts, 8 core frameworks, 27 addons, and a training marketplace package. SDLC workflows, digital forensics, research management, marketing operations, media curation, ops infrastructure, knowledge base, and fine-tuning dataset curation — all deployable with one command.
 
 ```bash
-npm i -g aiwg        # install globally
+npm i -g aiwg        # full CLI and local resource corpus
 aiwg use sdlc        # deploy SDLC framework
 ```
 
+For a smaller CLI install that resolves signed, versioned resources from the
+release host:
+
+```bash
+npm i -g @aiwg/cli
+aiwg discover "architecture evolution"
+aiwg show skill architecture-evolution
+```
+
+See [Web-Backed AIWG Resources](docs/install/web-backed-resources.md) for source
+selection, exact-version overrides, cache verification, offline use, and the
+current framework-graph constraints.
+
 Then ask your AI assistant to set up the project for AIWG. The agent-led setup
 conversation should establish remotes, issue storage, delivery behavior,
 signing policy, and provider choices; the assistant may call `aiwg setup project`
@@ -111,10 +124,18 @@ Around that core, AIWG ships agent-facing utilities for things the base platform
 
 ### Project scope (recommended) vs user scope (global)
 
-`aiwg use` writes artifacts at one of two scopes. Both are first-class supported (see ADR-NUA-001 in `.aiwg/studies/novice-user-adoption/`):
+`aiwg use` supports project deployments, additive user mirrors, and a
+user-global bootstrap:
 
 - **Project scope** — default. Run `aiwg use sdlc` from a project root and the artifacts land in `./.claude/agents/`, `./.claude/skills/`, etc. One project's agent set never bleeds into another's session. **This is the recommended default for most use cases.**
-- **User scope (global install)** — `aiwg use sdlc --scope user` writes to `~/.claude/agents/`, `~/.claude/skills/`, etc. Same artifact set loads into every session, regardless of project. Fits "AIWG in every conversation" workflows and is the canonical mode for OpenClaw and Hermes (whose primary discovery is user-scope).
+- **User scope (additive mirror)** — `aiwg use sdlc --scope user` keeps the
+  project deployment and mirrors it to `~/.claude/agents/`,
+  `~/.claude/skills/`, etc.
+- **Global bootstrap** — `aiwg use sdlc --provider claude --global` installs
+  framework and kernel assets in native user-level paths while leaving only
+  lightweight context and provider bootstrap files in the current project.
+  Use `aiwg regenerate --provider <name>` to wire additional projects without
+  deploying their own skill copies.
 
 The trade-off is real: when the same agent set loads into every session, context from one project can bleed into reasoning about another. Research (REF-720, *Lost in Multi-Turn Conversation*, MSR/Salesforce 2025) measured a 39% capability drop when this happens. The non-blocking project-isolation warning surfaces the trade-off at deploy time so the scope choice is informed. Neither scope is wrong; pick the one that fits the workflow.
 

package/dist/src/agents/grounding/knowledge-base.js

@@ -6,6 +6,7 @@
  */
 import { promises as fs } from 'fs';
 import path from 'path';
+import { projectAiwgPath } from '../../config/project-artifacts.js';
 // ============================================================================
 // KnowledgeStore
 // ============================================================================
@@ -20,7 +21,7 @@ export class KnowledgeStore {
      * Load knowledge bases from .aiwg/knowledge/
      */
     async load() {
-        const knowledgeDir = path.join(this.projectPath, '.aiwg/knowledge');
+        const knowledgeDir = projectAiwgPath(this.projectPath, 'knowledge');
         try {
             const domains = await fs.readdir(knowledgeDir);
             for (const domain of domains) {
@@ -73,7 +74,7 @@ export class KnowledgeStore {
         existing.entries.push(...entries);
         this.bases.set(domain, existing);
         // Persist
-        const domainDir = path.join(this.projectPath, '.aiwg/knowledge', domain);
+        const domainDir = projectAiwgPath(this.projectPath, 'knowledge', domain);
         await fs.mkdir(domainDir, { recursive: true });
         const outFile = path.join(domainDir, path.basename(filePath));
         await fs.copyFile(filePath, outFile);

package/dist/src/api/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Supported programmatic entry points for the installed AIWG package.
+ *
+ * `run()` dispatches through the same router used by `bin/aiwg.mjs`. Resource
+ * helpers expose the signed web-release contract without requiring callers to
+ * import private `dist/` paths.
+ */
+export { run } from '../cli/router.js';
+export * from '../resources/index.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/src/api/index.js

@@ -0,0 +1,10 @@
+/**
+ * Supported programmatic entry points for the installed AIWG package.
+ *
+ * `run()` dispatches through the same router used by `bin/aiwg.mjs`. Resource
+ * helpers expose the signed web-release contract without requiring callers to
+ * import private `dist/` paths.
+ */
+export { run } from '../cli/router.js';
+export * from '../resources/index.js';
+//# sourceMappingURL=index.js.map

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

@@ -22,6 +22,7 @@ import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { computeContentHash, list as listEnrichments, resolveSemanticRoot, get as getEnrichment, } from '../enrichment/store.js';
 import { validateEnrichmentOutput } from '../enrichment/prompt.js';
+import { projectAiwgPath } from '../../config/project-artifacts.js';
 import { detectDrift } from './drift.js';
 import { DEFAULT_THRESHOLDS } from './types.js';
 export async function main(args) {
@@ -115,7 +116,7 @@ export async function main(args) {
 }
 function loadThresholds() {
     // Try .aiwg/index/audit.config.yaml → fall back to defaults
-    const path = join(process.cwd(), '.aiwg', 'index', 'audit.config.yaml');
+    const path = projectAiwgPath(process.cwd(), 'index', 'audit.config.yaml');
     if (!existsSync(path))
         return DEFAULT_THRESHOLDS;
     try {

package/dist/src/artifacts/browser-export.js

@@ -505,6 +505,9 @@ function recordForEntry(cwd, entry, graphName, dependencyGraph, privacy, schemaV
                 embeddings: [],
                 skos_concepts: skos?.concepts ?? [],
                 skos_relations: skos?.relations ?? [],
+                ...(entry.operationalState
+                    ? { operational_state: entry.operationalState }
+                    : {}),
             }
             : {}),
         updated_at: entry.updated,

package/dist/src/artifacts/cli.js

@@ -16,8 +16,40 @@
  * @source @src/cli/handlers/subcommands.ts
  * @tests @test/unit/artifacts/cli.test.ts
  */
+import path from 'node:path';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
 import { GRAPH_CONFIGS, OPERATIONAL_DISCOVERY_TYPES, OPERATIONAL_SHOW_TYPES, isOperationalShowType, loadUserGraphConfigs, loadGlobalGraphConfigs, orderedGraphEntries, } from './types.js';
 import { SUPPORTED_VIEWS } from './corpus-views/renderers.js';
+import { parseResourceSelector, readVerifiedRegularFile, } from '../resources/web-release.js';
+import { findPackageRoot } from '../cli/find-package-root.js';
+const MAX_RESOURCE_TRUST_ROOT_BYTES = 64 * 1024;
+function webReleaseOptionsFromEnvironment() {
+    const baseUrl = process.env.AIWG_RESOURCE_BASE_URL;
+    const cacheRoot = process.env.AIWG_RESOURCE_CACHE_ROOT;
+    const trustRootFile = process.env.AIWG_RESOURCE_TRUST_ROOT_FILE;
+    let publicKeyPem;
+    if (trustRootFile !== undefined) {
+        if (trustRootFile.trim().length === 0) {
+            throw new Error('AIWG_RESOURCE_TRUST_ROOT_FILE must name a non-empty public PEM file');
+        }
+        publicKeyPem = readVerifiedRegularFile(path.resolve(trustRootFile), {
+            label: 'AIWG_RESOURCE_TRUST_ROOT_FILE public PEM',
+            maxBytes: MAX_RESOURCE_TRUST_ROOT_BYTES,
+        });
+        if (publicKeyPem.toString('utf8').trim().length === 0) {
+            throw new Error('AIWG_RESOURCE_TRUST_ROOT_FILE public PEM is empty');
+        }
+    }
+    return {
+        ...(baseUrl === undefined ? {} : { baseUrl }),
+        ...(cacheRoot === undefined ? {} : { cacheRoot }),
+        ...(publicKeyPem === undefined ? {} : { publicKeyPem }),
+        ...(process.env.AIWG_RESOURCE_ALLOW_INSECURE_LOOPBACK_HTTP === '1'
+            ? { allowInsecureLoopbackHttp: true }
+            : {}),
+    };
+}
 /** Parse --graph flag from args, returns undefined for "all graphs" */
 function parseGraphFlag(args) {
     const idx = args.indexOf('--graph');
@@ -53,6 +85,67 @@ function parseBackendFlag(args) {
 function parseSearchBackendFlag(args) {
     return parseBackendFlag(args) ?? 'fortemi-core';
 }
+/**
+ * The full `aiwg` package owns a local corpus, while `@aiwg/cli` intentionally
+ * ships only executable code and embedded runtime metadata. Select web
+ * resources automatically for the lightweight distribution so a normal
+ * `aiwg discover` / `aiwg show` invocation works immediately after install.
+ *
+ * Resolve from this module rather than process.argv so the exported API gets
+ * the same package-aware default as the npm binary.
+ */
+function defaultResourceSource() {
+    const packageRoot = findPackageRoot(path.dirname(fileURLToPath(import.meta.url)));
+    if (!packageRoot)
+        return 'local';
+    try {
+        const manifest = JSON.parse(readFileSync(path.join(packageRoot, 'package.json'), 'utf8'));
+        return manifest.name === '@aiwg/cli' ? 'web' : 'local';
+    }
+    catch {
+        return 'local';
+    }
+}
+function parseResourceSourceFlag(args) {
+    const indices = args
+        .map((arg, index) => arg === '--resource-source' ? index : -1)
+        .filter((index) => index >= 0);
+    if (indices.length > 1) {
+        console.error('Error: --resource-source may be specified only once');
+        process.exit(1);
+    }
+    if (indices.length === 0)
+        return defaultResourceSource();
+    const value = args[indices[0] + 1];
+    if (value === 'local' || value === 'web' || value === 'auto')
+        return value;
+    console.error('Error: --resource-source must be local, web, or auto');
+    process.exit(1);
+}
+function parseAiwgVersionFlag(args) {
+    const indices = args
+        .map((arg, index) => arg === '--aiwg-version' ? index : -1)
+        .filter((index) => index >= 0);
+    if (indices.length > 1) {
+        console.error('Error: --aiwg-version may be specified only once');
+        process.exit(1);
+    }
+    if (indices.length === 0)
+        return undefined;
+    const value = args[indices[0] + 1];
+    if (!value || value.startsWith('--')) {
+        console.error('Error: --aiwg-version requires an exact calendar-semver version or channel name');
+        process.exit(1);
+    }
+    try {
+        parseResourceSelector(value);
+    }
+    catch (error) {
+        console.error(`Error: ${error instanceof Error ? error.message : String(error)}`);
+        process.exit(1);
+    }
+    return value;
+}
 function firstPositionalArg(args, valueFlags) {
     const skip = new Set();
     for (let i = 0; i < args.length; i++) {
@@ -1215,13 +1308,14 @@ async function handleDiscover(args) {
     if (!phrase) {
         console.error('Error: aiwg index discover requires a search phrase');
         console.log('');
-        console.log('Usage: aiwg index discover "<phrase>" [--type <kinds>] [--limit N] [--json|--format json|text] [--pretty|--compact] [--graph <name>] [--backend local|fortemi-core]');
+        console.log('Usage: aiwg index discover "<phrase>" [--type <kinds>] [--limit N] [--json|--format json|text] [--pretty|--compact] [--graph <name>] [--backend local|fortemi-core] [--resource-source local|web|auto] [--aiwg-version <exact-or-channel>] [--offline]');
         console.log('');
         console.log('Examples:');
         console.log('  aiwg index discover "create intake"');
         console.log('  aiwg index discover "deploy production" --limit 5');
         console.log(`  aiwg index discover "audit security" --type ${OPERATIONAL_DISCOVERY_TYPES.join(',')}`);
         console.log('  aiwg index discover "intake" --format json --pretty');
+        console.log('  aiwg discover "intake" --resource-source web --aiwg-version stable');
         process.exit(1);
     }
     const typeValue = parseFlagValue(flags, '--type', 'Error: --type requires a value');
@@ -1244,6 +1338,12 @@ async function handleDiscover(args) {
     const jsonPretty = !flags.includes('--compact');
     const graph = parseGraphFlag(flags);
     const backend = parseSearchBackendFlag(flags);
+    const resourceSource = parseResourceSourceFlag(flags);
+    const aiwgVersion = parseAiwgVersionFlag(flags);
+    const offline = flags.includes('--offline');
+    const webReleaseOptions = resourceSource === 'local'
+        ? undefined
+        : webReleaseOptionsFromEnvironment();
     await discoverCapability(cwd, {
         phrase,
         typeFilter,
@@ -1252,6 +1352,10 @@ async function handleDiscover(args) {
         jsonPretty,
         graph,
         backend,
+        resourceSource,
+        aiwgVersion,
+        offline,
+        webReleaseOptions,
         includePaths: false,
     });
 }
@@ -1284,8 +1388,8 @@ async function handleShow(args) {
     }
     const HELP_TEXT = [
         '',
-        'Usage: aiwg show <type> <name> [--json] [--first] [--graph <name>] [--backend local|fortemi-core]',
-        '       aiwg show metadata <id-or-name-or-path> [--json] [--first] [--graph <name>] [--backend local|fortemi-core]',
+        'Usage: aiwg show <type> <name> [--json] [--first] [--graph <name>] [--backend local|fortemi-core] [--resource-source local|web|auto] [--aiwg-version <exact-or-channel>] [--offline]',
+        '       aiwg show metadata <id-or-name-or-path> [--json] [--first] [--graph <name>] [--backend local|fortemi-core] [--resource-source local|web|auto] [--aiwg-version <exact-or-channel>] [--offline]',
         '       aiwg index show <type> <name> ...',
         '',
         `Types: ${OPERATIONAL_SHOW_TYPES.join(' | ')}`,
@@ -1299,6 +1403,7 @@ async function handleShow(args) {
         '  aiwg show metadata aiwg:skill:4840fa441622f676 --json',
         '  aiwg show agent aiwg-steward',
         '  aiwg show command discover',
+        '  aiwg show skill intake-wizard --resource-source web --aiwg-version stable',
         '',
         'Tip: use `aiwg discover "<phrase>" --json` first to find the stable id.',
     ].join('\n');
@@ -1355,6 +1460,12 @@ async function handleShow(args) {
     }
     const graph = parseGraphFlag(flags);
     const backend = parseSearchBackendFlag(flags);
+    const resourceSource = parseResourceSourceFlag(flags);
+    const aiwgVersion = parseAiwgVersionFlag(flags);
+    const offline = flags.includes('--offline');
+    const webReleaseOptions = resourceSource === 'local'
+        ? undefined
+        : webReleaseOptionsFromEnvironment();
     const params = {
         name,
         typeFilter: type ? [type] : undefined,
@@ -1362,6 +1473,10 @@ async function handleShow(args) {
         first,
         graph,
         backend,
+        resourceSource,
+        aiwgVersion,
+        offline,
+        webReleaseOptions,
     };
     if (metadataMode)
         await showMetadata(cwd, params);

package/dist/src/artifacts/fortemi-core-query-adapter.js

@@ -1,6 +1,8 @@
 import fs from "node:fs";
+import { createHash } from "node:crypto";
 import { bm25Rank } from "./fulltext.js";
 import { getFortemiCorePrebuiltStatus, getFortemiCoreSyncStatus } from "./fortemi-core-sync.js";
+import { operationalStateQueryProjection, } from "./operational-state.js";
 function tokenize(text) {
     return text
         .toLowerCase()
@@ -59,6 +61,9 @@ function recordToStaticResult(record, score, matched) {
         summary: record.summary ?? record.search?.summary,
         score: Math.round(score * 1000) / 1000,
         matched,
+        ...(record.operational_state
+            ? { operational_state: operationalStateQueryProjection(record.operational_state) }
+            : {}),
     };
 }
 function recordBody(record) {
@@ -85,7 +90,83 @@ function matchesPath(recordPath, pattern) {
     }
     return recordPath.includes(pattern);
 }
-export function loadFortemiCoreExport(cwd, graph = "project") {
+function readVerifiedRegularFile(pathname, expectedSize, expectedSha256, label) {
+    if (!Number.isSafeInteger(expectedSize) || expectedSize < 0) {
+        throw new Error(`${label} has an invalid signed size`);
+    }
+    const pathStat = fs.lstatSync(pathname);
+    if (pathStat.isSymbolicLink() || !pathStat.isFile()) {
+        throw new Error(`${label} must be a regular file and may not be a symlink`);
+    }
+    if (pathStat.size !== expectedSize) {
+        throw new Error(`${label} size does not match the signed release descriptor`);
+    }
+    const noFollow = typeof fs.constants.O_NOFOLLOW === "number"
+        ? fs.constants.O_NOFOLLOW
+        : 0;
+    const fd = fs.openSync(pathname, fs.constants.O_RDONLY | fs.constants.O_NONBLOCK | noFollow);
+    try {
+        const openedStat = fs.fstatSync(fd);
+        if (!openedStat.isFile() || openedStat.size !== expectedSize) {
+            throw new Error(`${label} changed before it could be read safely`);
+        }
+        const bytes = Buffer.alloc(expectedSize + 1);
+        let offset = 0;
+        while (offset < bytes.length) {
+            const count = fs.readSync(fd, bytes, offset, bytes.length - offset, null);
+            if (count === 0)
+                break;
+            offset += count;
+        }
+        if (offset !== expectedSize) {
+            throw new Error(`${label} changed size while being read`);
+        }
+        const verified = bytes.subarray(0, expectedSize);
+        const digest = createHash("sha256").update(verified).digest("hex");
+        if (digest !== expectedSha256) {
+            throw new Error(`${label} does not match the signed release descriptor`);
+        }
+        return verified;
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}
+export function loadFortemiCoreExport(cwd, graph = "project", sourcePaths) {
+    if (sourcePaths) {
+        try {
+            const manifestBytes = readVerifiedRegularFile(sourcePaths.manifestPath, sourcePaths.manifestSize, sourcePaths.manifestSha256, "Verified Fortemi Core manifest");
+            const exportBytes = readVerifiedRegularFile(sourcePaths.exportPath, sourcePaths.exportSize, sourcePaths.exportSha256, "Verified Fortemi Core export");
+            const manifestSha256 = createHash("sha256").update(manifestBytes).digest("hex");
+            const exportSha256 = createHash("sha256").update(exportBytes).digest("hex");
+            if (manifestSha256 !== sourcePaths.manifestSha256 ||
+                exportSha256 !== sourcePaths.exportSha256) {
+                return { reason: "Verified Fortemi Core source bytes do not match the signed release descriptor." };
+            }
+            const manifest = JSON.parse(manifestBytes.toString("utf-8"));
+            const exported = JSON.parse(exportBytes.toString("utf-8"));
+            if (manifest.schema_version !== "aiwg.fortemi.prebuilt.v1" ||
+                manifest.backend !== "fortemi-core" ||
+                manifest.graph !== graph ||
+                manifest.export_path !== "aiwg-fortemi-index-v2.json" ||
+                manifest.export_schema_version !== "aiwg.fortemi.index.export.v2") {
+                return { reason: "Verified Fortemi Core source manifest is incompatible with the requested graph." };
+            }
+            if (manifest.export_checksum !== exportSha256 ||
+                exported.schema_version !== "aiwg.fortemi.index.export.v2" ||
+                exported.source?.graph !== graph ||
+                !Array.isArray(exported.items) ||
+                manifest.item_count !== exported.items.length) {
+                return { reason: "Verified Fortemi Core source export does not match its manifest." };
+            }
+            return { exported };
+        }
+        catch (err) {
+            return {
+                reason: `Verified Fortemi Core source could not be read: ${err instanceof Error ? err.message : String(err)}`,
+            };
+        }
+    }
     let status = getFortemiCoreSyncStatus(cwd, graph);
     if ((!status.optedIn || !status.built || status.stale) && graph === "framework") {
         const prebuilt = getFortemiCorePrebuiltStatus(graph);
@@ -164,16 +245,17 @@ function entryFromRecord(record) {
         kernel: typeof record.search?.frontmatter?.kernel === "boolean"
             ? record.search.frontmatter.kernel
             : undefined,
+        operationalState: record.operational_state,
     };
 }
-export function loadFortemiCoreMetadataEntries(cwd, graph = "project") {
-    const loaded = loadFortemiCoreExport(cwd, graph);
+export function loadFortemiCoreMetadataEntries(cwd, graph = "project", sourcePaths) {
+    const loaded = loadFortemiCoreExport(cwd, graph, sourcePaths);
     if (!loaded.exported)
         return { entries: [], reason: loaded.reason };
     return { entries: loaded.exported.items.map(entryFromRecord) };
 }
 export async function queryFortemiCoreAiwgDiscovery(cwd, options) {
-    const loaded = loadFortemiCoreExport(cwd, options.graph ?? "framework");
+    const loaded = loadFortemiCoreExport(cwd, options.graph ?? "framework", options.sourcePaths);
     if (!loaded.exported) {
         return {
             results: [],
@@ -328,6 +410,9 @@ export function queryFortemiCoreStaticFulltextIndex(cwd, options) {
                 summary: record.summary ?? record.search?.summary ?? record.text,
                 score: Math.round(hit.score * 1000) / 1000,
                 matched: hit.matchedTerms,
+                ...(record.operational_state
+                    ? { operational_state: operationalStateQueryProjection(record.operational_state) }
+                    : {}),
             };
         }),
     };

package/dist/src/artifacts/fortemi-core-sync.js

@@ -1,7 +1,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { createHash } from "node:crypto";
-import { GRAPH_CONFIGS, loadGlobalGraphConfigs } from "./types.js";
+import { GRAPH_CONFIGS, getProjectIndexRoot, loadGlobalGraphConfigs } from "./types.js";
 import { buildAiwgFortemiIndexExport, } from "./browser-export.js";
 import { loadGraphIndexFile } from "./index-reader.js";
 function syncDir(cwd, graph) {
@@ -11,7 +11,7 @@ function syncDir(cwd, graph) {
         const xdgData = process.env.XDG_DATA_HOME ?? path.join(process.env.HOME ?? cwd, ".local", "share");
         return path.join(xdgData, "aiwg", "index", "fortemi-core", graph);
     }
-    return path.join(cwd, ".aiwg", ".index", "fortemi-core", graph);
+    return path.join(getProjectIndexRoot(cwd), "fortemi-core", graph);
 }
 function findPackageRoot(startDir) {
     let current = startDir;

package/dist/src/artifacts/hybrid-query.js

@@ -9,6 +9,7 @@
  */
 import { promises as fs } from 'fs';
 import path from 'path';
+import { resolveProjectAiwgDir } from '../config/project-artifacts.js';
 // ============================================================================
 // ArtifactIndex
 // ============================================================================
@@ -24,7 +25,7 @@ export class ArtifactIndex {
      */
     async build() {
         this.artifacts = [];
-        const aiwgDir = path.join(this.projectPath, '.aiwg');
+        const aiwgDir = resolveProjectAiwgDir(this.projectPath);
         try {
             await this.scanDirectory(aiwgDir, '');
         }

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

@@ -13,30 +13,50 @@ import fs from 'fs';
 import path from 'path';
 import { createHash } from 'crypto';
 import { load as loadYaml } from 'js-yaml';
-import { DEFAULT_INDEX_EXTENSIONS, INDEX_EXTRACTOR_VERSION, INDEX_VERSION, INDEX_DIR, OPERATIONAL_DISCOVERY_TYPES, PHASE_DIRECTORIES, GRAPH_CONFIGS, TEMPLATE_INDEX_EXTENSIONS, loadUserGraphConfigs, loadGlobalGraphConfigs, } from './types.js';
+import { DEFAULT_INDEX_EXTENSIONS, INDEX_EXTRACTOR_VERSION, INDEX_VERSION, INDEX_DIR, OPERATIONAL_DISCOVERY_TYPES, PHASE_DIRECTORIES, GRAPH_CONFIGS, TEMPLATE_INDEX_EXTENSIONS, resolveGraphScanDir, loadUserGraphConfigs, loadGlobalGraphConfigs, } from './types.js';
 import { parseCitationSidecar, citationResultToEdges, buildRefToPathMap } from './citation-parser.js';
 import { writeIndexFile, resolveIndexDir, loadGraphIndexFile } from './index-reader.js';
 import { loadManifest, writeManifest, statMatches, makeEntry } from './checksum-manifest.js';
 import { workspaceLinkedFiles } from '../smiths/context-pipeline/workspace-context.js';
-function expandScanDir(cwd, scanDir) {
-    if (scanDir === '~')
-        return process.env.HOME ?? scanDir;
-    if (scanDir.startsWith('~/')) {
-        return path.join(process.env.HOME ?? '', scanDir.slice(2));
-    }
-    if (path.isAbsolute(scanDir))
-        return scanDir;
-    return path.join(cwd, scanDir);
+import { normalizeOperationalState } from './operational-state.js';
+import { DEFAULT_PROJECT_AIWG_DIR, resolveProjectAiwgDir, } from '../config/project-artifacts.js';
+function pathContains(parent, child) {
+    const relative = path.relative(parent, child);
+    return relative === '' || (!relative.startsWith('..') && !path.isAbsolute(relative));
+}
+function toPosixPath(value) {
+    return value.split(path.sep).join('/');
 }
-function indexPathFor(cwd, fullPath) {
+function indexPathFor(cwd, fullPath, graph) {
+    if (!graph || graph === 'project') {
+        const artifactRoot = resolveProjectAiwgDir(cwd);
+        if (pathContains(artifactRoot, fullPath)) {
+            const relative = toPosixPath(path.relative(artifactRoot, fullPath));
+            return relative ? `${DEFAULT_PROJECT_AIWG_DIR}/${relative}` : DEFAULT_PROJECT_AIWG_DIR;
+        }
+    }
     const rel = path.relative(cwd, fullPath);
     if (!rel.startsWith('..') && !path.isAbsolute(rel))
-        return rel;
+        return toPosixPath(rel);
     return fullPath;
 }
-function absoluteEntryPath(cwd, entryPath) {
+function absoluteEntryPath(cwd, entryPath, graph) {
+    if ((!graph || graph === 'project') && entryPath.startsWith(`${DEFAULT_PROJECT_AIWG_DIR}/`)) {
+        return path.join(resolveProjectAiwgDir(cwd), entryPath.slice(DEFAULT_PROJECT_AIWG_DIR.length + 1));
+    }
     return path.isAbsolute(entryPath) ? entryPath : path.join(cwd, entryPath);
 }
+function loadIndexFromDir(indexDir, filename) {
+    const filePath = path.join(indexDir, filename);
+    if (!fs.existsSync(filePath))
+        return null;
+    try {
+        return JSON.parse(fs.readFileSync(filePath, 'utf-8'));
+    }
+    catch {
+        return null;
+    }
+}
 /**
  * Parse YAML frontmatter from markdown content
  */
@@ -664,12 +684,12 @@ export async function buildIndex(cwd, options = {}) {
         fileExtensions = [...DEFAULT_INDEX_EXTENSIONS];
     }
     else if (graphConfig) {
-        scanDirs = graphConfig.scanDirs.map(d => expandScanDir(cwd, d));
+        scanDirs = graphConfig.scanDirs.map(d => resolveGraphScanDir(cwd, d));
         fileExtensions = graphConfig.extensions;
     }
     else {
         // Default: scan .aiwg/ (backward compatible)
-        scanDirs = [path.join(cwd, '.aiwg')];
+        scanDirs = [resolveProjectAiwgDir(cwd)];
         fileExtensions = [...DEFAULT_INDEX_EXTENSIONS];
     }
     // Verify at least one scan directory exists
@@ -699,7 +719,7 @@ export async function buildIndex(cwd, options = {}) {
         indexOutputDir = resolveIndexDir(cwd, graph);
     }
     else {
-        indexOutputDir = path.join(cwd, INDEX_DIR);
+        indexOutputDir = resolveIndexDir(cwd);
     }
     fs.mkdirSync(indexOutputDir, { recursive: true });
     // effectiveOutputCwd is used for backward-compat loadMetadataIndex calls
@@ -718,7 +738,11 @@ export async function buildIndex(cwd, options = {}) {
         return;
     }
     // Load existing index for incremental updates
-    const existingIndex = force ? null : loadGraphIndexFile(effectiveOutputCwd, 'metadata.json', graph);
+    const existingIndex = force
+        ? null
+        : outputDir
+            ? loadIndexFromDir(indexOutputDir, 'metadata.json')
+            : loadGraphIndexFile(effectiveOutputCwd, 'metadata.json', graph);
     const canReuseExisting = existingIndex?.version === INDEX_VERSION
         && existingIndex.extractorVersion === INDEX_EXTRACTOR_VERSION;
     const existingEntries = canReuseExisting ? existingIndex.entries : {};
@@ -762,7 +786,7 @@ export async function buildIndex(cwd, options = {}) {
     let unchangedCount = 0;
     const useFilenameMetadata = graphConfig?.nodeStrategy === 'filename-metadata';
     for (const fullPath of files) {
-        const relativePath = indexPathFor(cwd, fullPath);
+        const relativePath = indexPathFor(cwd, fullPath, graph);
         let entry;
         if (useFilenameMetadata) {
             // Filename-metadata strategy: derive metadata from filename, skip content read.
@@ -857,6 +881,7 @@ export async function buildIndex(cwd, options = {}) {
             const kernel = data.kernel === true || data.kernel === 'true' ? true : undefined;
             // Script entrypoint metadata is meaningful for skills only (#1227).
             const script = type === 'skill' ? extractSkillScript(data) : undefined;
+            const operationalState = normalizeOperationalState(data.operational_state);
             // Canonical short name (#1233) — used by the scorer to floor exact-name
             // queries to 1.0 so hyphenated kernel-skill names like `aiwg-doctor`
             // remain searchable even when the rendered title strips the hyphen.
@@ -881,6 +906,7 @@ export async function buildIndex(cwd, options = {}) {
                 ...(searchTerms && searchTerms.length > 0 ? { searchTerms } : {}),
                 ...(kernel ? { kernel } : {}),
                 ...(script ? { script } : {}),
+                ...(operationalState ? { operationalState } : {}),
             };
         }
         entries[relativePath] = entry;
@@ -935,7 +961,7 @@ export async function buildIndex(cwd, options = {}) {
         // Build REF-XXX → path map from all entries with ref frontmatter
         const entryFrontmatter = new Map();
         for (const entryPath of Object.keys(entries)) {
-            const fullPath = absoluteEntryPath(cwd, entryPath);
+            const fullPath = absoluteEntryPath(cwd, entryPath, graph);
             if (fs.existsSync(fullPath)) {
                 const content = fs.readFileSync(fullPath, 'utf-8');
                 const { data } = parseFrontmatter(content);
@@ -946,7 +972,7 @@ export async function buildIndex(cwd, options = {}) {
         // Parse each entry as a citation sidecar and extract edges
         let citationEdgeCount = 0;
         for (const entryPath of Object.keys(entries)) {
-            const fullPath = absoluteEntryPath(cwd, entryPath);
+            const fullPath = absoluteEntryPath(cwd, entryPath, graph);
             if (!fs.existsSync(fullPath))
                 continue;
             const content = fs.readFileSync(fullPath, 'utf-8');