@aiwg/cli 2026.10.4 → 2026.10.6

package/dist/src/artifacts/cli.js

@@ -20,6 +20,7 @@ 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 { resolveIndexWorkers } from './index-preparation.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';
@@ -328,10 +329,12 @@ export function printIndexUsage() {
     console.log('  build [--force] [--verbose] [--all] [--scope <dir>] [--graph <name>]');
     console.log('  refresh [--full] [--workspace <path>]... [--root <dir>]...');
     console.log('          [--only graphs|sessions|caches|runtime|models|issues] [--dry-run] [--json] [--lock-wait-ms <n>]');
+    console.log('  --only also accepts a registered index name (for example project) or all.');
     console.log('          [--max-record-bytes <n>] [--max-source-bytes <n>]');
     console.log('  Session import defaults: 67108864 bytes per record, 1073741824 bytes (1 GiB) per source; source 0 is unlimited.');
     console.log('  --exclude <id-or-glob> (repeatable): skip session IDs or absolute path globs; adds to sessions.import.exclude and AIWG_SESSIONS_IMPORT_EXCLUDE (comma-separated).');
     console.log('  Import limits: CLI flag > AIWG_SESSIONS_IMPORT_MAX_RECORD_BYTES / AIWG_SESSIONS_IMPORT_MAX_SOURCE_BYTES > workspace config > default.');
+    console.log('  build/refresh --index-workers <n>: preparation processes (0 = serial); flag > AIWG_INDEX_WORKERS > automatic CPU/memory limits.');
     console.log('  sync [--backend fortemi-core] [--graph <name> | --all] [--repo <name>]');
     console.log('       [--privacy private|sanitized|public] [--generated-at <iso>] [--json]');
     console.log('  --graph <name>  Target a specific graph (framework, project, codebase, source, user, or user-defined)');
@@ -503,6 +506,7 @@ async function handleBuild(args) {
         console.log('Usage: aiwg index build [options]');
         console.log('');
         console.log('Options:');
+        console.log('  --index-workers <n> Preparation processes (0 = serial); overrides AIWG_INDEX_WORKERS');
         console.log('  --force          Full rebuild (ignore checksums, re-index everything)');
         console.log('  --verbose        Show detailed progress during indexing');
         console.log('  --all            Build all known graphs (including user-defined)');
@@ -530,6 +534,15 @@ async function handleBuild(args) {
         console.log('  aiwg index sync --all');
         return;
     }
+    let workers;
+    try {
+        workers = resolveIndexWorkers(parseFlagValue(args, '--index-workers', 'Error: --index-workers requires a value'));
+    }
+    catch (error) {
+        console.error(`Error: ${error instanceof Error ? error.message : String(error)}`);
+        process.exitCode = 1;
+        return;
+    }
     // Dynamic import to keep the CLI router lightweight
     const { buildIndex } = await import('./index-builder.js');
     const cwd = process.cwd();
@@ -554,7 +567,7 @@ async function handleBuild(args) {
         // --graph X: build the JSON graph if X is one; otherwise X may be a
         // research-corpus markdown view, rendered below.
         if (graph in GRAPH_CONFIGS) {
-            await buildIndex(cwd, { force, verbose, scope, includeIgnored, graph, explicit: true });
+            await buildIndex(cwd, { force, verbose, scope, includeIgnored, workers, graph, explicit: true });
             jsonBuilt = true;
             builtGraphs.add(graph);
         }
@@ -562,7 +575,7 @@ async function handleBuild(args) {
     else if (all) {
         // Build all known graphs — user asked for everything, but don't hard-error on missing dirs
         for (const [name] of orderedGraphEntries(Object.entries(GRAPH_CONFIGS))) {
-            await buildIndex(cwd, { force, verbose, includeIgnored, graph: name, explicit: false });
+            await buildIndex(cwd, { force, verbose, includeIgnored, workers, graph: name, explicit: false });
             builtGraphs.add(name);
         }
         jsonBuilt = true;
@@ -571,7 +584,7 @@ async function handleBuild(args) {
         // Default: build graphs with defaultBuild=true; skip gracefully if their dirs don't exist
         for (const [name, config] of orderedGraphEntries(Object.entries(GRAPH_CONFIGS))) {
             if (config.defaultBuild) {
-                await buildIndex(cwd, { force, verbose, includeIgnored, scope: name === Object.keys(GRAPH_CONFIGS)[0] ? scope : undefined, graph: name, explicit: false });
+                await buildIndex(cwd, { force, verbose, includeIgnored, workers, scope: name === Object.keys(GRAPH_CONFIGS)[0] ? scope : undefined, graph: name, explicit: false });
                 builtGraphs.add(name);
             }
         }
@@ -1073,6 +1086,21 @@ async function handleExport(args) {
         process.exit(1);
     }
 }
+function warnSyncTextQuality(manifest) {
+    const quality = manifest.text_quality;
+    if (!quality?.degenerate)
+        return;
+    const config = GRAPH_CONFIGS[manifest.graph];
+    const source = config
+        ? ` Source: ${config.scanDirs.join(', ')} (nodeStrategy: ${config.nodeStrategy ?? 'default'}).`
+        : '';
+    if (manifest.item_count === 0) {
+        console.warn(`Warning: graph '${manifest.graph}' contains no indexed items; this graph cannot return results.${source}`);
+        return;
+    }
+    const percent = Math.round(quality.short_text_count / manifest.item_count * 100);
+    console.warn(`Warning: graph '${manifest.graph}': ${quality.short_text_count}/${manifest.item_count} items (${percent}%) have <${quality.short_text_threshold_chars} chars of indexed text; ${quality.filename_title_count} have a filename as title. This graph may return poor results. Check source content and extracted text sidecars.${source}`);
+}
 /**
  * Handle 'index sync' command
  */
@@ -1142,6 +1170,7 @@ async function handleSync(args) {
             console.log(`Fortemi Core sync: ${manifests.length} graph(s) succeeded, ${failures.length} failed`);
             for (const manifest of manifests) {
                 console.log(`  ${manifest.graph}: ${manifest.status}, ${manifest.item_count} item(s) → ${manifest.export_path}`);
+                warnSyncTextQuality(manifest);
             }
             for (const failure of failures) {
                 console.error(`  ${failure.graph}: failed — ${failure.error}`);
@@ -1157,6 +1186,7 @@ async function handleSync(args) {
             return;
         }
         console.log(`Fortemi Core ${manifest.status}: ${manifest.item_count} item(s) → ${manifest.export_path}`);
+        warnSyncTextQuality(manifest);
     }
     catch (err) {
         console.error('Error: ' + (err instanceof Error ? err.message : String(err)));
@@ -1288,7 +1318,7 @@ async function handleStats(args) {
  */
 async function handleStatus(args) {
     if (args.includes('--help') || args.includes('-h')) {
-        console.log('Usage: aiwg index status [--json]');
+        console.log('Usage: aiwg index status [--only <name|all>] [--json]');
         console.log('       aiwg index list   [--json]   (alias)');
         console.log('');
         console.log('Enumerate every registered index graph (built-in + module + operator)');
@@ -1302,7 +1332,10 @@ async function handleStatus(args) {
         return;
     }
     const { showIndexStatus } = await import('./index-status.js');
-    await showIndexStatus(process.cwd(), { json: args.includes('--json') });
+    const onlyAt = args.indexOf('--only');
+    if (onlyAt >= 0 && (!args[onlyAt + 1] || args[onlyAt + 1].startsWith('--')))
+        throw new Error('--only requires an index name');
+    await showIndexStatus(process.cwd(), { json: args.includes('--json'), only: onlyAt >= 0 ? args[onlyAt + 1] : undefined });
 }
 /**
  * Handle 'index neighbors' command
@@ -1510,7 +1543,7 @@ async function handleDiscover(args) {
     });
 }
 /**
- * Handle 'index show' command — print the full text of a specific
+ * Handle 'index show' command — show the metadata card of a specific
  * artifact by type and name.
  *
  * Shape (#1218):
@@ -1519,9 +1552,31 @@ async function handleDiscover(args) {
  * Type is positional (not a flag) so the verb reads as
  * "show <kind> <name>". `<type>` is one of the operational show types.
  *
- * Companion to `discover`: where discover ranks candidates, show fetches
- * the artifact body so consumers don't need to navigate the filesystem.
+ * Companion to `discover`: where discover ranks candidates, show returns
+ * a metadata card with section/body drill-ins so consumers don't need to navigate the filesystem.
  */
+const SHOW_FLAGS = new Set(['--json', '--first', '--bound-rule-bodies', '--graph', '--backend', '--resource-source',
+    '--aiwg-version', '--offline', '--body', '--section', '--rules', '--with-rule-bodies', '--resources', '--resource',
+    '--help']);
+// Section headings can themselves start with `--` (e.g. "--max-iterations (default: 10)"), and the card
+// tells agents to pass them verbatim. Only a missing value or another show flag counts as "no value".
+function showFlagValue(flags, index) {
+    const value = flags[index + 1];
+    if (!value || SHOW_FLAGS.has(value.split('=')[0]))
+        throw new Error(`${flags[index]} requires a value`);
+    return value;
+}
+/** Values for a repeatable value flag, accepting both `--flag value` and `--flag=value`. */
+function showFlagValues(flags, name) {
+    const values = [];
+    for (let i = 0; i < flags.length; i++) {
+        if (flags[i] === name)
+            values.push(showFlagValue(flags, i));
+        else if (flags[i].startsWith(`${name}=`))
+            values.push(flags[i].slice(name.length + 1));
+    }
+    return values;
+}
 async function handleShow(args) {
     const { showArtifact, showMetadata } = await import('./query-engine.js');
     const cwd = process.cwd();
@@ -1555,9 +1610,11 @@ async function handleShow(args) {
         '  aiwg show command discover',
         '  aiwg show skill intake-wizard --resource-source web --aiwg-version stable',
         '',
+        'Default: metadata card. --body restores full output; --section <heading> is repeatable.',
+        '--rules [--with-rule-bodies] | --resources | --resource <path>',
         'Bound rules: summaries and show pointers are appended for bound skills, agents, and flows.',
         'Fetch and follow every required_rule_checks entry before starting governed work; summaries do not replace full rules.',
-        'Use --bound-rule-bodies to include their full text (JSON: bound_rules[].content).',
+        'Use --rules --with-rule-bodies to include their full text (legacy alias: --bound-rule-bodies).',
         '',
         'Tip: use `aiwg discover "<phrase>" --json` first to find the stable id.',
     ].join('\n');
@@ -1623,6 +1680,12 @@ async function handleShow(args) {
     const params = {
         name,
         boundRuleBodies: flags.includes('--bound-rule-bodies'),
+        body: flags.includes('--body'),
+        sections: showFlagValues(flags, '--section'),
+        rules: flags.includes('--rules'),
+        withRuleBodies: flags.includes('--with-rule-bodies'),
+        resources: flags.includes('--resources'),
+        resource: showFlagValues(flags, '--resource')[0],
         typeFilter: type ? [type] : undefined,
         json,
         first,

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

@@ -244,6 +244,8 @@ function entryFromRecord(record) {
     const indexedScript = indexedFrontmatter.aiwg_script;
     return {
         path: record.source.path,
+        ...(indexedFrontmatter.aiwg_memory_record && typeof indexedFrontmatter.aiwg_memory_record === 'object'
+            ? { memoryRecord: indexedFrontmatter.aiwg_memory_record } : {}),
         type: artifactTypeFromRecord(record),
         kind: typeof indexedFrontmatter.aiwg_kind === "string"
             ? indexedFrontmatter.aiwg_kind

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

@@ -5,9 +5,9 @@ import { fileURLToPath } from "node:url";
 import { parse as parseYaml } from "yaml";
 import { GRAPH_CONFIGS, getProjectIndexRoot, loadGlobalGraphConfigs } from "./types.js";
 import { buildAiwgFortemiIndexExport, } from "./browser-export.js";
-import { loadGraphIndexFile } from "./index-reader.js";
+import { loadGraphIndexFile, publishIndexFiles } from "./index-reader.js";
 import { getFrameworkIndexBaseDir } from './framework-index-paths.js';
-function syncDir(cwd, graph) {
+export function getFortemiCoreIndexDir(cwd, graph) {
     loadGlobalGraphConfigs();
     if (graph === 'framework')
         return path.join(getFrameworkIndexBaseDir(cwd), 'fortemi-core', graph);
@@ -180,14 +180,15 @@ function writeExport(file, exported, maxChars) {
 }
 export function syncFortemiCoreIndex(cwd, options = {}) {
     const graph = options.graph ?? "project";
-    const dir = syncDir(cwd, graph);
+    const dir = getFortemiCoreIndexDir(cwd, graph);
     const exportPath = path.join(dir, "aiwg-fortemi-index-v2.json");
     const manifestPath = path.join(dir, "manifest.json");
     const maxChars = options.maxChunkChars ?? 64 * 1024;
     if (!Number.isSafeInteger(maxChars) || maxChars < 64)
         throw new Error("maxChunkChars must be an integer of at least 64");
     fs.mkdirSync(dir, { recursive: true });
-    const temporaryPath = path.join(dir, `.export-${randomUUID()}.tmp`);
+    const staging = fs.mkdtempSync(path.join(dir, ".sync-"));
+    const temporaryPath = path.join(staging, `.export-${randomUUID()}.tmp`);
     const previous = readManifest(manifestPath);
     const sourceBuiltAt = sourceIndexBuiltAt(cwd, graph);
     const buildExport = (generatedAt) => {
@@ -200,10 +201,25 @@ export function syncFortemiCoreIndex(cwd, options = {}) {
         });
         const checksum = writeExport(temporaryPath, exported, maxChars);
         const recordsWithConcepts = exported.items.filter((item) => (item.skos_concepts?.length ?? 0) > 0).length;
+        const shortTextThreshold = 200;
+        let shortTextCount = 0;
+        let filenameTitleCount = 0;
+        for (const item of exported.items) {
+            if (item.text.trim().length < shortTextThreshold)
+                shortTextCount++;
+            if (item.title.trim() === path.posix.basename(item.source.path))
+                filenameTitleCount++;
+        }
         return {
             generatedAt,
             checksum,
             itemCount: exported.items.length,
+            textQuality: {
+                short_text_threshold_chars: shortTextThreshold,
+                short_text_count: shortTextCount,
+                filename_title_count: filenameTitleCount,
+                degenerate: exported.items.length === 0 || shortTextCount / exported.items.length >= 0.8,
+            },
             skosCoverage: {
                 records_with_concepts: recordsWithConcepts,
                 total_records: exported.items.length,
@@ -228,7 +244,7 @@ export function syncFortemiCoreIndex(cwd, options = {}) {
                 }
             }
         }
-        fs.renameSync(temporaryPath, exportPath);
+        fs.renameSync(temporaryPath, path.join(staging, path.basename(exportPath)));
         const manifest = {
             schema_version: "aiwg.fortemi.core-sync.v1",
             backend: "fortemi-core",
@@ -238,19 +254,21 @@ export function syncFortemiCoreIndex(cwd, options = {}) {
             export_schema_version: "aiwg.fortemi.index.export.v2",
             export_checksum: built.checksum,
             item_count: built.itemCount,
+            text_quality: built.textQuality,
             skos_coverage: built.skosCoverage,
             status,
             source_index_built_at: sourceBuiltAt,
         };
-        fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2) + "\n", "utf-8");
+        fs.writeFileSync(path.join(staging, path.basename(manifestPath)), JSON.stringify(manifest, null, 2) + "\n", "utf-8");
+        publishIndexFiles(staging, dir);
         return manifest;
     }
     finally {
-        fs.rmSync(temporaryPath, { force: true });
+        fs.rmSync(staging, { recursive: true, force: true });
     }
 }
 export function getFortemiCoreSyncStatus(cwd, graph = "project") {
-    const dir = syncDir(cwd, graph);
+    const dir = getFortemiCoreIndexDir(cwd, graph);
     const manifestPath = path.join(dir, "manifest.json");
     const exportPath = path.join(dir, "aiwg-fortemi-index-v2.json");
     const { manifest, reason: manifestReadReason } = readManifestResult(manifestPath);

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

@@ -9,8 +9,17 @@
  * @tests @test/unit/artifacts/graph-query.test.ts
  */
 import { normalizeEdges } from './types.js';
-import { buildFortemiCoreDependencyGraph } from './fortemi-core-query-adapter.js';
+import { buildFortemiCoreDependencyGraph, loadFortemiCoreMetadataEntries } from './fortemi-core-query-adapter.js';
 import { closeGraphBackend, openGraphBackend } from './backend-runtime.js';
+import { loadGraphIndexFile } from './index-reader.js';
+import { isOrdinaryMemoryEntry } from './query-engine.js';
+function graphMemoryMetadata(cwd, graph, backend) {
+    const local = loadGraphIndexFile(cwd, 'metadata.json', graph)?.entries ?? {};
+    if (backend === 'fortemi-core') {
+        return { ...Object.fromEntries(loadFortemiCoreMetadataEntries(cwd, graph).entries.map(entry => [entry.path, entry])), ...local };
+    }
+    return local;
+}
 /**
  * Get neighbors of a node in a dependency graph.
  *
@@ -20,15 +29,15 @@ import { closeGraphBackend, openGraphBackend } from './backend-runtime.js';
  * @param edgeType - Optional filter by edge type
  * @returns Array of neighbor paths
  */
-export function getNeighbors(graph, node, direction = 'both', edgeType) {
+export function getNeighbors(graph, node, direction = 'both', edgeType, metadata = {}) {
     const entry = graph[node];
-    if (!entry)
+    if (!entry || (metadata[node] && !isOrdinaryMemoryEntry(metadata[node])))
         return [];
     const results = new Set();
     if (direction === 'in' || direction === 'both') {
         const edges = normalizeEdges(entry.upstream);
         for (const edge of edges) {
-            if (!edgeType || edge.type === edgeType) {
+            if ((!edgeType || edge.type === edgeType) && (!metadata[edge.path] || isOrdinaryMemoryEntry(metadata[edge.path]))) {
                 results.add(edge.path);
             }
         }
@@ -36,7 +45,7 @@ export function getNeighbors(graph, node, direction = 'both', edgeType) {
     if (direction === 'out' || direction === 'both') {
         const edges = normalizeEdges(entry.downstream);
         for (const edge of edges) {
-            if (!edgeType || edge.type === edgeType) {
+            if ((!edgeType || edge.type === edgeType) && (!metadata[edge.path] || isOrdinaryMemoryEntry(metadata[edge.path]))) {
                 results.add(edge.path);
             }
         }
@@ -134,7 +143,7 @@ export async function showNeighbors(cwd, options) {
         }
         process.exit(1);
     }
-    const neighbors = getNeighbors(graph, resolved, direction, edgeType);
+    const neighbors = getNeighbors(graph, resolved, direction, edgeType, graphMemoryMetadata(cwd, graphType, backend));
     if (json) {
         console.log(JSON.stringify({
             graph: graphType,
@@ -208,8 +217,9 @@ export async function executeSetQuery(cwd, options) {
         console.error(`Error: Node '${nodeB}' not found in graph '${graphType}'.`);
         process.exit(1);
     }
-    const neighborsA = getNeighbors(graph, resolvedA, direction, edgeType);
-    const neighborsB = getNeighbors(graph, resolvedB, direction, edgeType);
+    const metadata = graphMemoryMetadata(cwd, graphType, backend);
+    const neighborsA = getNeighbors(graph, resolvedA, direction, edgeType, metadata);
+    const neighborsB = getNeighbors(graph, resolvedB, direction, edgeType, metadata);
     let result;
     switch (op) {
         case 'intersection':