@aiwg/cli 2026.8.7 → 2026.8.10

package/README.md

@@ -21,11 +21,23 @@ agents, CI, and web-backed installations.
 
 ```text
 Install or repair AIWG for this project by following
-https://raw.githubusercontent.com/jmagly/aiwg/main/setup.aiwg.yaml
+https://aiwg.io/setup.aiwg.yaml
 Explain the plan before changing anything, preserve my existing work, and ask
 me only for choices you cannot safely determine.
 ```
 
+The equivalent manual path is three steps:
+
+```bash
+npm install --global aiwg
+cd /path/to/your/project
+aiwg use all --provider <provider>
+```
+
+The final command deploys, refreshes indices and project context, verifies the
+provider wiring, and reports one result. Standalone index, regenerate, status,
+and doctor commands remain advanced maintenance and recovery tools.
+
 [![npm version](https://img.shields.io/npm/v/%40aiwg%2Fcli/latest?label=%40aiwg%2Fcli&color=CB3837&logo=npm&style=flat-square)](https://www.npmjs.com/package/@aiwg/cli)
 [![npm downloads](https://img.shields.io/npm/dm/%40aiwg%2Fcli?color=CB3837&logo=npm&style=flat-square)](https://www.npmjs.com/package/@aiwg/cli)
 [![full distribution](https://img.shields.io/npm/v/aiwg/latest?label=aiwg&color=CB3837&logo=npm&style=flat-square)](https://www.npmjs.com/package/aiwg)
@@ -221,7 +233,7 @@ offline operation is required.
 
 For a first installation, an uncertain environment, or a machine with an old
 or broken AIWG setup, use the full `aiwg` package and the
-[agentic installer manifest](https://raw.githubusercontent.com/jmagly/aiwg/main/setup.aiwg.yaml).
+[agentic installer manifest](https://aiwg.io/setup.aiwg.yaml).
 The flow detects development checkouts and preserves development mode unless
 the user explicitly approves switching to the published package.
 
@@ -263,7 +275,7 @@ rather than merely printed.
 Agents do not need to memorize the remaining command surface. AIWG discovery
 finds the relevant skill, and the skill supplies the right CLI step. Operators
 who need the complete syntax and examples can use the
-[AIWG CLI reference](https://github.com/jmagly/aiwg/blob/main/docs/agents/cli-reference.md).
+[AIWG CLI reference](https://github.com/jmagly/aiwg/blob/main/docs/cli/reference.md).
 
 ## How It Works
 
@@ -454,7 +466,7 @@ This README therefore documents the operating model, package boundary, trust
 model, and troubleshooting path instead of duplicating every command and flag.
 The complete operator reference is maintained at:
 
-**[AIWG CLI Reference — every command and example](https://github.com/jmagly/aiwg/blob/main/docs/agents/cli-reference.md)**
+**[AIWG CLI Reference — every command and example](https://github.com/jmagly/aiwg/blob/main/docs/cli/reference.md)**
 
 Keeping the command catalog in one canonical location prevents package
 documentation from drifting as the runtime grows.
@@ -508,7 +520,7 @@ security guidance.
 Do not routinely call `aiwg help` and place the full output in the model
 context. If a skill exists, use it. If a maintainer or operator needs an
 unfamiliar command, link to the canonical
-[CLI reference](https://github.com/jmagly/aiwg/blob/main/docs/agents/cli-reference.md) or retrieve only
+[CLI reference](https://github.com/jmagly/aiwg/blob/main/docs/cli/reference.md) or retrieve only
 the relevant section.
 
 ## Using AIWG from a Web-Connected Chat
@@ -1064,7 +1076,7 @@ Package invariants include:
 
 ## Documentation
 
-- [Complete AIWG CLI reference](https://github.com/jmagly/aiwg/blob/main/docs/agents/cli-reference.md)
+- [Complete AIWG CLI reference](https://github.com/jmagly/aiwg/blob/main/docs/cli/reference.md)
 - [AIWG documentation](https://docs.aiwg.io/)
 - [AIWG project README](https://github.com/jmagly/aiwg#readme)
 - [Web-backed resources guide](https://github.com/jmagly/aiwg/blob/main/docs/install/web-backed-resources.md)
@@ -1086,7 +1098,10 @@ opening a public issue.
 
 ## License
 
-MIT. See the
+AIWG-authored code is MIT licensed. See the
 [AIWG license](https://github.com/jmagly/aiwg/blob/main/LICENSE).
 
-The package includes its own copy of `LICENSE` in every published tarball.
+Runtime dependencies retain their own licenses. Every published tarball
+includes `LICENSE` and `THIRD_PARTY_NOTICES.md`; the latter identifies the
+reviewed Fortemi and Bytecask AGPL boundary, corresponding source links, and
+commands for inspecting the versions npm resolved.

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,35 @@
+# Third-party notices
+
+AIWG-authored source is distributed under the MIT license in [`LICENSE`](LICENSE). AIWG also declares runtime dependencies that retain their own licenses. This notice does not replace those licenses or change their terms.
+
+## Fortemi Core
+
+- Package: `@fortemi/core@2026.7.15`
+- License declared by the package: `AGPL-3.0-only`
+- Source: <https://github.com/Fortemi/fortemi-react/tree/5cab4ea2d3d4bb985ea0d38f8bcb1ea790b32cf7/packages/core>
+- Source tag: <https://github.com/Fortemi/fortemi-react/tree/v2026.7.15/packages/core>
+- Registry integrity: `sha512-49GThHQHzLFD2BbjgXB7AUznRrwtWo8MsH6IcFMhSmCKj/h+Q5j18EBpkwPHJfC5E7crp+rVzy/GcrT/PF1SXA==`
+
+AIWG uses the `@fortemi/core/aiwg-index` and `@fortemi/core/aiwg-index-shard` entry points and selected validation/archive exports from the package root. These modules execute in the AIWG Node.js process.
+
+## Bytecask Core
+
+- Reviewed package: `@bytecask/core@2026.7.5`
+- License declared by the package: `AGPL-3.0-only`
+- Source: <https://github.com/jmagly/bytecask/tree/bef7ba9590e74f8bfcd724e65928f2f84a5667d4/packages/core>
+- Source tag: <https://github.com/jmagly/bytecask/tree/v2026.7.5/packages/core>
+- Registry integrity: `sha512-CsLJqmw8lNuBxRLGdRzoDdZ4/2iQlluueaiiYOR+l39NOdoG5cfDel/g71QDopRpVEHJOw7hQ3QngmWmi5IjBw==`
+
+Fortemi declares Bytecask as a runtime dependency. The reviewed AIWG lockfile resolves version `2026.7.5`; downstream npm resolution can select a later compatible version. Inspect the installed version with:
+
+```bash
+npm ls @fortemi/core @bytecask/core
+```
+
+Each installed dependency package includes its own `LICENSE` and `package.json`. To inspect the exact source reference for a different resolved version, run `npm view @fortemi/core@<version> repository license` or `npm view @bytecask/core@<version> repository license`.
+
+## Distribution boundary
+
+The `aiwg` and `@aiwg/cli` npm archives do not copy Fortemi or Bytecask object code into their own tarballs. npm resolves those packages separately during installation. AIWG does, however, intentionally import Fortemi in-process at runtime, so separate archive delivery is not by itself a legal conclusion about whether execution forms a combined work.
+
+The reviewed architecture and unresolved legal questions are recorded in [`docs/contributing/fortemi-agpl-runtime-boundary.md`](docs/contributing/fortemi-agpl-runtime-boundary.md). Operators who modify an AGPL-covered package or expose a modified version for remote network interaction should review the GNU AGPL requirements and obtain qualified legal advice for their distribution and deployment model.

package/agentic/code/providers/capability-matrix.yaml

@@ -323,9 +323,9 @@ providers:
     aggregated_output: true
 
   windsurf:
-    display_name: Windsurf
-    status: experimental
-    # Windsurf is an IDE extension requiring VS Code host — daemon not supported
+    display_name: Devin Desktop
+    status: stable
+    # Devin Desktop uses the Windsurf compatibility surface and requires a VS Code host — daemon not supported
     daemon_tier: unsupported
     daemon_pty_adapter: false
     artifact_paths:

package/bin/aiwg.mjs

@@ -67,9 +67,134 @@ function maybeHandleFastVersion(args) {
   return true;
 }
 
+const FAST_HELP_TEXT = `
+  ◆ AIWG
+────────────────────────────────────────────────────────
+
+  Usage: aiwg <command> [options]
+
+  FRAMEWORK
+    use <framework>              Deploy framework (sdlc, marketing, media-curator, research, forensics, security-engineering, ops, validation, knowledge-base, all)
+    use cockpit                  Install the opt-in @aiwg/cockpit package outside the base aiwg footprint
+    list                         List installed frameworks and addons
+    remove <id>                  Remove a framework or addon
+
+  PROJECT
+    new <name>                   Create new project with SDLC templates
+    init                         Create the baseline .aiwg/aiwg.config file
+    setup project                CLI helper used by agents for repo/tracker/delivery/signing policy
+    quickref generate --project  Generate the canonical project quickref skill (--dry-run previews deterministic output)
+    quickref deploy --project    Deploy the project quickref to configured provider kernel surfaces
+
+  WORKSPACE
+    status                       Show workspace health and installed frameworks
+    migrate-workspace            Migrate legacy .aiwg/ to framework-scoped structure
+    rollback-workspace           Rollback workspace migration from backup
+
+  MCP SERVER
+    mcp serve                    Start AIWG MCP server (stdio transport)
+    mcp install [target]         Generate MCP client config (claude, copilot, factory, cursor)
+    mcp info                     Show MCP server capabilities
+
+  TOOLSMITH
+    runtime-info                 Show runtime environment summary
+    runtime-info --discover      Full tool discovery and catalog generation
+    runtime-info --check <tool>  Check specific tool availability
+
+  CATALOG
+    catalog list                 List all models in catalog
+    catalog info <id>            Show detailed model information
+    catalog search <q>           Search models by query
+
+  DISCOVERY
+    discover "<phrase>"          Find skills/agents/commands/rules by capability
+    show <type> <name>           Stream the body of an indexed artifact
+    versions <list|resolve|show> Browse and resolve signed AIWG web resource releases
+    auth <login|status|logout>   Authenticate for paid AIWG web resources
+    index <subcommand>           Manage the artifact index (build/query/discover/deps/stats)
+    artifacts move --to <path>   Move/rename the project AIWG artifact root and reindex
+
+  DISPATCH
+    run skill <name>             Execute a script-bearing skill
+    run <script-name>            Run a user-defined script from .aiwg/aiwg.config
+
+  FEATURES
+    features                     Show optional feature install status
+    cockpit [--status]           Launch the opt-in AIWG Cockpit control plane
+
+  VALIDATION
+    validate-metadata [path]     Validate AIWG component metadata (defaults to agentic/code)
+    context-firewall [scan]      Audit provider context, trust, drift, poisoning signals, and budget
+    context-firewall baseline    Plan or explicitly write the reviewed context baseline
+
+  METRICS
+    cost-report --fleet          Observe OpenRouter per-bot MTD spend and correlate local activity
+
+  EVIDENCE
+    evidence export --output <dir> Package portable activity, report, source, eval, and provenance evidence
+    evidence verify <bundle>     Verify every member hash and the bundle checkpoint
+
+  SCAFFOLDING
+    new-bundle <name>            Create project-local bundle (--type extension|addon|framework|plugin|provider, --starter skill|rule|agent|minimal, --dry-run)
+    new-extension <name>         Alias for new-bundle --type extension
+    new-addon <name>             Alias for new-bundle --type addon
+    new-framework <name>         Alias for new-bundle --type framework
+    new-plugin <name>            Alias for new-bundle --type plugin
+    new-provider <name>          Alias for new-bundle --type provider
+    add-agent <name>             Add agent to existing bundle
+    add-command <name>           Add command to existing bundle
+    add-skill <name>             Add skill to existing bundle
+    scaffold-addon <name>        [legacy] Use new-addon instead
+    scaffold-framework <name>    [legacy] Use new-framework instead
+
+  PROMOTE
+    promote <name>               Graduate project-local bundle to upstream (--to upstream|corpus, --dry-run, --cleanup)
+
+  RALPH LOOP
+    ralph "<task>"               Execute iterative task loop (--completion, --max-iterations)
+    ralph-status                 Check current loop status
+    ralph-abort                  Abort running loop
+    ralph-resume                 Resume interrupted loop
+
+  MAINTENANCE
+    doctor                       Check installation health
+    version                      Show version and channel info
+    refresh                      Update AIWG and redeploy frameworks (formerly: sync)
+    update                       Update the active installation and re-deploy installed frameworks (alias: upgrade)
+    help                         Show this help message
+
+  CHANNEL
+    --use-dev [path]             Customize AIWG live from a local clone or fork
+    --use-main                   Switch to edge channel (bleeding edge)
+    --use-stable                 Switch back to stable npm package
+────────────────────────────────────────────────────────
+
+  Providers: claude (default), copilot, factory, codex, cursor, opencode, warp, windsurf
+
+  Examples:
+    aiwg use sdlc                   Install SDLC framework
+    aiwg use sdlc --global          Install user assets + lightweight project wiring
+    aiwg use cockpit                Install opt-in Cockpit package
+    aiwg cockpit                    Launch Cockpit after install
+    aiwg discover "deploy"          Find skills by capability
+    aiwg show skill intake-wizard   Stream a skill body
+    aiwg doctor                     Check installation health
+    aiwg refresh                    Pull latest + redeploy frameworks
+`;
+
+function maybeHandleFastHelp(args) {
+  if (args.length !== 1) return false;
+  if (!['help', '--help', '-help', '-h'].includes(args[0])) return false;
+  process.stdout.write(`${FAST_HELP_TEXT}\n`);
+  return true;
+}
+
 if (maybeHandleFastVersion(process.argv.slice(2))) {
   process.exit(0);
 }
+if (maybeHandleFastHelp(process.argv.slice(2))) {
+  process.exit(0);
+}
 
 // Preflight: verify dist/ is built before any of the dynamic imports below
 // try to resolve files that don't exist. Without this, a missing/incomplete

package/dist/src/artifacts/backends/graphology-backend.js

@@ -5,13 +5,14 @@
  * Provides typed/attributed edges, BFS/DFS traversal, community detection,
  * and shortest-path algorithms.
  *
- * Install: npm install graphology graphology-types graphology-operators graphology-traversal
+ * Enable with: aiwg features install graph
  *
  * @implements #728
  * @source @src/artifacts/graph-backend.ts
  * @tests @test/unit/artifacts/graphology-backend.test.ts
  */
 import { normalizeEdges } from '../types.js';
+import { loadFeaturePackage } from '../../features/runtime.js';
 /**
  * Graphology-backed graph with rich traversal and operator ecosystem.
  *
@@ -31,13 +32,13 @@ export class GraphologyBackend {
      */
     static async create() {
         try {
-            const graphology = await import('graphology');
+            const graphology = await loadFeaturePackage('graphology');
             const Graph = graphology.default ?? graphology;
             const graph = new Graph({ type: 'directed', multi: true });
             return new GraphologyBackend(graph);
         }
         catch {
-            throw new Error('graphology backend requires: npm install graphology graphology-types graphology-operators graphology-traversal');
+            throw new Error('graphology backend is unavailable; run `aiwg features install graph`');
         }
     }
     // --- Mutation ---

package/dist/src/artifacts/backends/sqlite-backend.js

@@ -6,13 +6,14 @@
  * (INTERSECT/EXCEPT/UNION), recursive CTE traversal, and cross-graph
  * federation via ATTACH DATABASE.
  *
- * Install: npm install better-sqlite3 @types/better-sqlite3
+ * Enable with: aiwg features install sqlite
  *
  * @implements #729
  * @source @src/artifacts/graph-backend.ts
  * @tests @test/unit/artifacts/sqlite-backend.test.ts
  */
 import { normalizeEdges } from '../types.js';
+import { requireFeaturePackage } from '../../features/runtime.js';
 /**
  * SQLite-backed graph with persistent storage and native SQL operations.
  *
@@ -29,13 +30,11 @@ export class SqliteGraphBackend {
      */
     constructor(dbPath = ':memory:') {
         try {
-            // Dynamic require so missing package gives a clear error
-            // eslint-disable-next-line @typescript-eslint/no-require-imports
-            const Database = require('better-sqlite3');
+            const Database = requireFeaturePackage('better-sqlite3');
             this.db = new Database(dbPath);
         }
         catch {
-            throw new Error('sqlite backend requires: npm install better-sqlite3 @types/better-sqlite3');
+            throw new Error('sqlite backend is unavailable; run `aiwg features install sqlite`');
         }
         this.db.pragma('journal_mode = WAL');
         this.initSchema();

package/dist/src/artifacts/cli.js

@@ -697,7 +697,7 @@ async function requireEmbeddingIndex(cwd, graph) {
     if (!deps.available) {
         console.error(`Error: semantic search needs optional dependencies: ${deps.missing.join(', ')}`);
         console.error('Install them to enable semantic features:');
-        console.error('  npm install @xenova/transformers hnswlib-node');
+        console.error('  aiwg features install embeddings');
         return null;
     }
     const dir = resolveIndexDir(cwd, graph);
@@ -845,7 +845,7 @@ async function handleEmbed(args) {
     const deps = await checkEmbeddingDeps();
     if (!deps.available) {
         console.error(`Error: embedding needs optional dependencies: ${deps.missing.join(', ')}`);
-        console.error('  npm install @xenova/transformers hnswlib-node');
+        console.error('  aiwg features install embeddings');
         process.exit(1);
     }
     const index = loadGraphIndexFile(cwd, 'metadata.json', graph);

package/dist/src/artifacts/corpus-tools/cli.js

@@ -72,6 +72,7 @@ Usage:
   aiwg corpus frontmatter-backfill [--write] [--out PATH]
   aiwg corpus profile-edges [--out PATH]
   aiwg corpus profile-similar --entity PROF-P-x [--top K] | --predict-collabs [--threshold T] [--out PATH]
+  aiwg corpus retrieval-lab --queries PATH --concepts PATH [--expected-scheme-hash SHA256] [--limit K] [--latency-ceiling MS] [--json] [--out PATH]
   aiwg corpus vision-extract --slug SLUG [--images DIR] [--out DIR] [--start N] [--end N] [--provider codex|command] [--command TMPL] [--model M] [--retries N] [--title T] [--force] [--rasterize PDF] [--dpi N]
 
 radar-init scaffolds radar sidecars (dry-run unless --write; skips existing).
@@ -98,6 +99,7 @@ snapshot computes one-shot corpus snapshot metrics and renders full markdown, te
 frontmatter-backfill adds minimal ref_id/title/year/pdf_hash frontmatter to legacy analysis docs lacking it (dry-run unless --write; additive, skips docs that already have frontmatter).
 profile-edges builds the profile→REF edge graph (first-class adjacency; reconciled against the citation graph so only edges to existing REFs are kept).
 profile-similar embeds person profiles (text-embedding; opt-in @xenova/transformers) → nearest researchers (--entity) or collaboration link-prediction (--predict-collabs).
+retrieval-lab benchmarks current research-query and direct lexical baselines against vector, BM25, typed graph PPR, and RRF without changing production query behavior.
 vision-extract transcribes scanned page PNGs → per-page + combined Markdown via a provider-neutral vision adapter (codex | command template), resumable with retry/validation; --rasterize PDF first renders pages via pdftoppm.
 `;
 function radarInit(root, args) {
@@ -385,6 +387,31 @@ export async function corpusMain(args, cwd = process.cwd()) {
             const top = flagValue(rest, '--top') ? parseInt(flagValue(rest, '--top'), 10) : 10;
             return emit(renderSimilar(entity, profileSimilar(emb, entity, top)), flagValue(rest, '--out'), root);
         }
+        case 'retrieval-lab': {
+            const queries = flagValue(rest, '--queries');
+            const concepts = flagValue(rest, '--concepts');
+            if (!queries || !concepts)
+                throw new Error('retrieval-lab requires --queries <jsonl> and --concepts <json>');
+            const expectedSchemeHash = flagValue(rest, '--expected-scheme-hash');
+            if (expectedSchemeHash && !/^[0-9a-f]{64}$/i.test(expectedSchemeHash))
+                throw new Error('retrieval-lab --expected-scheme-hash must be a SHA-256 hex digest');
+            const limit = flagValue(rest, '--limit');
+            const latencyCeiling = flagValue(rest, '--latency-ceiling');
+            if (limit && (!Number.isInteger(Number(limit)) || Number(limit) < 1))
+                throw new Error('retrieval-lab --limit must be a positive integer');
+            if (latencyCeiling && (!Number.isFinite(Number(latencyCeiling)) || Number(latencyCeiling) <= 0))
+                throw new Error('retrieval-lab --latency-ceiling must be a positive number');
+            const { runRetrievalLab, renderRetrievalLab } = await import('./retrieval-lab.js');
+            const report = await runRetrievalLab({
+                root,
+                queriesPath: path.resolve(root, queries),
+                conceptsPath: path.resolve(root, concepts),
+                expectedSchemeHash,
+                ...(limit ? { limit: Number(limit) } : {}),
+                ...(latencyCeiling ? { latencyCeilingMs: Number(latencyCeiling) } : {}),
+            });
+            return emit(hasFlag(rest, '--json') ? `${JSON.stringify(report, null, 2)}\n` : renderRetrievalLab(report), flagValue(rest, '--out'), root);
+        }
         default:
             process.stderr.write(`Unknown corpus subcommand: ${sub}\n\n${HELP}`);
             throw new Error(`unknown corpus subcommand: ${sub}`);

package/dist/src/artifacts/corpus-tools/profile-embed.js

@@ -17,6 +17,7 @@
  */
 import { loadProfiles, loadCorpus } from '../corpus-views/ref-parser.js';
 import { checkEmbeddingDeps, DEFAULT_EMBEDDING_MODEL } from '../embedding-index.js';
+import { loadFeaturePackage } from '../../features/runtime.js';
 function cosine(a, b) {
     let dot = 0;
     // Vectors are L2-normalized at embed time (normalize: true), so dot == cosine.
@@ -31,7 +32,7 @@ function cosine(a, b) {
 export async function buildProfileEmbeddings(corpusRoot, model = DEFAULT_EMBEDDING_MODEL) {
     const deps = await checkEmbeddingDeps();
     if (!deps.available) {
-        throw new Error(`profile embeddings need optional deps: ${deps.missing.join(', ')} (npm install @xenova/transformers)`);
+        throw new Error(`profile embeddings need optional deps: ${deps.missing.join(', ')}; run \`aiwg features install embeddings\``);
     }
     const titleByRef = new Map();
     for (const r of loadCorpus(corpusRoot).records)
@@ -52,7 +53,7 @@ export async function buildProfileEmbeddings(corpusRoot, model = DEFAULT_EMBEDDI
         texts.push(text);
         refs.push(new Set(p.corpusRefs));
     }
-    const transformersMod = await (new Function('m', 'return import(m)'))('@xenova/transformers');
+    const transformersMod = await loadFeaturePackage('@xenova/transformers');
     const embed = await transformersMod.pipeline('feature-extraction', model);
     const vectors = [];
     for (const t of texts) {