aiwg 2026.3.1 → 2026.3.2

package/bin/aiwg.mjs

@@ -43,7 +43,9 @@ async function main() {
 
   if (args[0] === '--use-dev') {
     const { switchToDev } = await import('../src/channel/manager.mjs');
-    await switchToDev(packageRoot);
+    // Accept optional path argument, default to cwd
+    const devPath = args[1] || process.cwd();
+    await switchToDev(devPath);
     return;
   }
 
@@ -58,10 +60,25 @@ async function main() {
     // Silently ignore update check failures
   });
 
+  // Dev mode: delegate to the dev repo's CLI facade so all code runs from
+  // the local build (not just framework content). This ensures commands like
+  // `aiwg index stats` use the locally compiled TypeScript.
+  const { loadConfig } = await import('../src/channel/manager.mjs');
+  const config = await loadConfig();
+  if (config.devMode && config.edgePath && config.edgePath !== packageRoot) {
+    const devFacade = path.join(config.edgePath, 'src', 'cli', 'facade.mjs');
+    try {
+      const { run: devRun } = await import(devFacade);
+      await devRun(args, { cwd: process.cwd() });
+      return;
+    } catch (err) {
+      console.error(`Dev mode: failed to load facade from ${config.edgePath}`);
+      console.error(`  ${err.message}`);
+      console.error('Falling back to installed version.');
+    }
+  }
+
   // Run the CLI via facade (supports both legacy and new routers)
-  // The facade will determine which router to use based on:
-  // - AIWG_USE_NEW_ROUTER environment variable
-  // - --experimental-router or --legacy-router flags
   await run(args, { cwd: process.cwd() });
 }
 

package/docs/cli-reference.md

@@ -1657,7 +1657,17 @@ aiwg sdlc-accelerate --auto "Quick prototype"
 
 ## Index Commands
 
-Commands for building and querying the artifact index. The index provides structured, pre-computed metadata about `.aiwg/` artifacts, enabling agents and developers to discover, search, and navigate project artifacts without manual file searching.
+Commands for building and querying the artifact index. The index provides structured, pre-computed metadata about project artifacts, enabling agents and developers to discover, search, and navigate artifacts without manual file searching.
+
+The index uses a **multi-graph architecture** with three built-in graph types:
+
+| Graph | Scans | Storage | Built by default |
+|-------|-------|---------|-----------------|
+| `project` | `.aiwg/` artifacts | `.aiwg/.index/project/` | Yes |
+| `codebase` | `src/`, `test/`, `tools/` | `.aiwg/.index/codebase/` | Yes |
+| `framework` | `agentic/code/`, `docs/` | `.aiwg/.index/framework/` | No (use `--graph framework`) |
+
+All commands without `--graph` operate across all available project-local graphs (`project` + `codebase`). Use `--graph <name>` to target a specific graph.
 
 ### index
 
@@ -1673,6 +1683,9 @@ aiwg index <subcommand> [options]
 - `deps` - Show artifact dependency graph
 - `stats` - Show index statistics
 
+**Global option (all subcommands):**
+- `--graph <type>` - Target a specific graph: `project`, `codebase`, or `framework`
+
 **Capabilities:** cli, index, artifacts, search, dependencies
 **Platforms:** All
 **Tools:** Read, Glob, Grep
@@ -1681,7 +1694,7 @@ aiwg index <subcommand> [options]
 
 ### index build
 
-Build or rebuild the artifact index by scanning `.aiwg/` directories.
+Build or rebuild the artifact index.
 
 ```bash
 aiwg index build [options]
@@ -1691,20 +1704,16 @@ aiwg index build [options]
 - `--force` - Full rebuild (ignore checksums, re-index everything)
 - `--verbose` - Show detailed progress during indexing
 - `--scope <dir>` - Limit scan to a specific subdirectory
+- `--graph <type>` - Build a single graph only (`project`, `codebase`, `framework`)
 
-**Behavior:**
-- Scans `.aiwg/` for `.md`, `.yaml`, and `.json` files
-- Extracts YAML frontmatter metadata (title, type, phase, tags)
-- Computes SHA-256 checksums for incremental indexing
-- Extracts @-mention dependencies from file content
-- Writes index files to `.aiwg/.index/`
+**Default behavior** (no `--graph`): Builds `project` + `codebase` graphs only. The `framework` graph covers the AIWG framework source (`agentic/code/`, `docs/`) and must be built explicitly with `--graph framework`.
 
-**Incremental mode** (default): Only re-indexes files whose checksum has changed since the last build. Use `--force` for a full rebuild.
+**Incremental mode** (default): Only re-indexes files whose checksum has changed. Use `--force` for a full rebuild.
 
 **Examples:**
 
 ```bash
-# Incremental build (fast - skips unchanged files)
+# Build project + codebase (default)
 aiwg index build
 
 # Full rebuild
@@ -1713,15 +1722,27 @@ aiwg index build --force
 # Verbose output
 aiwg index build --verbose
 
-# Scope to requirements only
-aiwg index build --scope requirements
+# Build framework graph (agentic/code/ + docs/)
+aiwg index build --graph framework
+
+# Build a single graph
+aiwg index build --graph project
 ```
 
-**Output files:**
-- `.aiwg/.index/metadata.json` - Artifact metadata entries
-- `.aiwg/.index/tags.json` - Tag index
-- `.aiwg/.index/deps.json` - Dependency graph
-- `.aiwg/.index/stats.json` - Index statistics
+**Output structure:**
+```
+.aiwg/.index/
+├── project/          # .aiwg/ artifacts
+│   ├── metadata.json
+│   ├── tags.json
+│   ├── dependencies.json
+│   └── stats.json
+└── codebase/         # src/, test/, tools/
+    ├── metadata.json
+    ├── tags.json
+    ├── dependencies.json
+    └── stats.json
+```
 
 ---
 
@@ -1742,29 +1763,29 @@ aiwg index query [search-text] [options]
 - `--tags <tag1,tag2>` - Filter by tags (AND logic — all tags must match)
 - `--path <glob>` - Filter by file path glob pattern
 - `--updated-after <date>` - Filter by last-modified date
-- `--limit <n>` - Maximum number of results
+- `--limit <n>` - Maximum number of results (default: 20)
+- `--graph <type>` - Search a specific graph only
 - `--json` - Output as JSON (recommended for agents)
 
+**Default behavior** (no `--graph`): Searches across `project` + `codebase` graphs combined.
+
 **Examples:**
 
 ```bash
-# Keyword search
+# Search all project-local graphs
 aiwg index query "authentication"
 
+# Search framework source only
+aiwg index query "artifact discovery" --graph framework
+
 # Filter by type
 aiwg index query --type use-case
 
-# Filter by phase
-aiwg index query --phase testing
-
 # Combined filters
 aiwg index query "login" --type use-case --phase requirements
 
 # JSON output for agents
 aiwg index query "auth" --json
-
-# Limit results
-aiwg index query --tags security --limit 5
 ```
 
 ---
@@ -1783,6 +1804,7 @@ aiwg index deps <path> [options]
 **Options:**
 - `--direction <dir>` - Direction: `upstream`, `downstream`, or `both` (default: `both`)
 - `--depth <n>` - Maximum traversal depth (default: 3)
+- `--graph <type>` - Use a specific graph's dependency data
 - `--json` - Output as JSON (recommended for agents)
 
 **Behavior:**
@@ -1790,6 +1812,8 @@ aiwg index deps <path> [options]
 - `downstream` - What depends on this artifact (mentions it)
 - `both` - Both directions
 
+**Default behavior** (no `--graph`): Merges dependency data from `project` + `codebase` graphs.
+
 **Examples:**
 
 ```bash
@@ -1801,6 +1825,9 @@ aiwg index deps .aiwg/requirements/UC-001.md --direction downstream
 
 # JSON output with limited depth
 aiwg index deps .aiwg/architecture/adr-001.md --depth 2 --json
+
+# Deps within framework source
+aiwg index deps agentic/code/frameworks/sdlc-complete/rules/artifact-discovery.md --graph framework
 ```
 
 ---
@@ -1814,8 +1841,13 @@ aiwg index stats [options]
 ```
 
 **Options:**
+- `--graph <type>` - Show stats for a specific graph only
 - `--json` - Output as JSON (recommended for agents)
 
+**Default behavior** (no `--graph`):
+- Human-readable: shows each available graph with a section header
+- JSON: returns an object keyed by graph name with all stats
+
 **Reports:**
 - Artifact counts by SDLC phase and type
 - Tag distribution
@@ -1825,11 +1857,17 @@ aiwg index stats [options]
 **Examples:**
 
 ```bash
-# Human-readable stats
+# Show all project-local graphs
 aiwg index stats
 
-# JSON output for agents
+# JSON output (aggregated, keyed by graph name)
 aiwg index stats --json
+
+# Single graph
+aiwg index stats --graph project --json
+
+# Framework graph stats
+aiwg index stats --graph framework
 ```
 
 ---

package/docs/development/aiwg-development-guide.md

@@ -100,22 +100,39 @@ Do not place framework components (schemas, templates, agent definitions) in `.a
    agentic/code/addons/voice-framework/skills/my-skill/SKILL.md
    ```
 
-2. **Deploy to `.claude/` for testing**:
+2. **Activate dev mode** (one-time setup — points the CLI at your local repo):
    ```bash
-   aiwg --use-dev    # Point at local repo (one-time)
-   aiwg use sdlc     # Redeploy from local source
+   aiwg --use-dev /path/to/ai-writing-guide
+   # From inside the repo directory:
+   aiwg --use-dev .
    ```
 
-3. **Test** — the skill/agent is now live in your Claude Code session.
+   Dev mode makes the `aiwg` command delegate **all** subcommands to your
+   local `src/cli/facade.mjs`, so changes to CLI code take effect after
+   `npm run build` without reinstalling the package.
 
-4. **Commit** — only the framework source (`agentic/code/`) goes into git.
+3. **Build and deploy**:
+   ```bash
+   npm run build          # Compile TypeScript changes
+   aiwg use sdlc          # Redeploy framework content from local source
+   ```
+
+4. **Test** — the skill/agent is now live in your Claude Code session. CLI
+   commands like `aiwg index stats` also run from your local build.
+
+5. **Commit** — only the framework source (`agentic/code/`) goes into git.
+
+6. **Switch back when done**:
+   ```bash
+   aiwg --use-stable
+   ```
 
 **Common Mistake**: Writing ONLY to `.claude/skills/my-skill/` without creating the source in `agentic/code/`. The skill works locally but never ships to users and disappears on next `aiwg use`.
 
 **For AI Agents**: When creating new skills, agents, commands, or rules, you MUST:
 1. Create the artifact in the correct `agentic/code/` source location
 2. Update the relevant manifest (`manifest.json`) if one exists
-3. Run `aiwg --use-dev && aiwg use <framework>` or manually copy to `.claude/`
+3. Run `aiwg --use-dev . && npm run build && aiwg use <framework>`
 4. Verify the artifact works from `.claude/`
 5. Only commit changes under `agentic/code/`
 

package/docs/releases/v2026.3.2-announcement.md

@@ -0,0 +1,104 @@
+# AIWG v2026.3.2 — Service Release
+
+**Release date:** 2026-03-04
+**Type:** Service release (bug fixes + dev workflow improvements)
+
+## Summary
+
+This service release fixes three bugs in the `aiwg index` multi-graph subsystem introduced in v2026.3.1, and upgrades `--use-dev` so it now delegates the full CLI to your local build — not just framework content deployment.
+
+## What's Fixed
+
+### `aiwg index` without `--graph` now works
+
+`stats`, `query`, and `deps` all failed with "No artifact index found" when called without `--graph`. The root cause was the same in all three: they checked for `.aiwg/.index/metadata.json` (the legacy pre-multi-graph path), which no longer exists. The index now lives in graph subdirectories:
+
+```
+.aiwg/.index/
+├── project/       ← .aiwg/ artifacts
+└── codebase/      ← src/, test/, tools/
+```
+
+All three commands now check graph subdirectories first, then fall back to the legacy root for backward compatibility.
+
+**Before:**
+```
+$ aiwg index stats --json
+Error: No artifact index found.
+Run 'aiwg index build' first to create the index.
+```
+
+**After:**
+```json
+{
+  "project": { "totalArtifacts": 495, "coverage": { "percentage": 100 } },
+  "codebase": { "totalArtifacts": 496, "coverage": { "percentage": 100 } }
+}
+```
+
+### `--use-dev` now delegates the full CLI
+
+Previously `--use-dev` only changed where `aiwg use` read framework content from. The CLI binary itself still ran the npm-installed code, so changes to TypeScript files like `src/artifacts/stats.ts` had no effect until you ran `npm install -g .`.
+
+Now when dev mode is active, the `aiwg` entry point dynamically imports `src/cli/facade.mjs` from your dev repo, making all commands run your local build:
+
+```bash
+# One-time setup (point at your local repo)
+aiwg --use-dev /path/to/ai-writing-guide
+# or from inside the repo:
+aiwg --use-dev .
+
+# Make changes, build, test immediately
+npm run build
+aiwg index stats   # runs local code
+aiwg use sdlc      # deploys from local source
+
+# Switch back
+aiwg --use-stable
+```
+
+Also fixed: `--use-dev` previously hardcoded the npm package root as the dev path. It now accepts an explicit path argument.
+
+## What's New
+
+### Framework graph
+
+You can now index the AIWG framework source (`agentic/code/`, `docs/`):
+
+```bash
+aiwg index build --graph framework
+# Indexed 1,625 artifacts in 669ms
+
+aiwg index stats --graph framework --json
+# { "totalArtifacts": 1625, "graphMetrics": { "totalEdges": 890 } }
+
+aiwg index query "artifact discovery" --graph framework --json
+```
+
+The framework graph is intentionally excluded from the default `aiwg index build` since it covers shared/global content. Build it explicitly when you need to navigate the framework source.
+
+### Multi-graph architecture documented
+
+`docs/cli-reference.md` now covers the full multi-graph architecture:
+- Graph types table (project, codebase, framework)
+- `--graph` flag on all index subcommands
+- Updated output structure paths
+- Cross-graph default behavior for each command
+
+## Upgrade
+
+```bash
+npm update -g aiwg
+aiwg version
+# 2026.3.2
+```
+
+## References
+
+- Fixes #425 — `aiwg index stats` no-graph failure
+- Issue #426 — Extensible graph types (future work)
+- `src/artifacts/stats.ts` — multi-graph stats aggregation
+- `src/artifacts/query-engine.ts` — cross-graph search
+- `src/artifacts/dep-graph.ts` — merged dependency traversal
+- `bin/aiwg.mjs` — dev mode CLI delegation
+- `src/channel/manager.mjs` — `switchToDev()` path handling

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aiwg",
-  "version": "2026.3.1",
+  "version": "2026.3.2",
   "description": "Cognitive architecture for AI-augmented software development with structured memory, ensemble validation, and closed-loop correction. FAIR-aligned artifacts, 84% cost reduction via human-in-the-loop, standards adopted by 100+ organizations.",
   "type": "module",
   "bin": {

package/src/artifacts/cli.ts

@@ -107,7 +107,7 @@ async function handleBuild(args: string[]): Promise<void> {
     // Build a specific graph
     await buildIndex(cwd, { force, verbose, scope, graph });
   } else {
-    // Default: build project + codebase (framework is built via `aiwg use`)
+    // Default: build project-local graphs only
     await buildIndex(cwd, { force, verbose, scope, graph: 'project' });
     await buildIndex(cwd, { force, verbose, graph: 'codebase' });
   }

package/src/artifacts/dep-graph.ts

@@ -10,7 +10,7 @@
  */
 
 import type { DependencyGraph, GraphType } from './types.js';
-import { loadDependencyGraph, indexExists, loadGraphIndexFile } from './index-reader.js';
+import { loadDependencyGraph, loadGraphIndexFile } from './index-reader.js';
 
 export interface DepsOptions {
   direction?: 'upstream' | 'downstream' | 'both';
@@ -95,18 +95,35 @@ export async function showDeps(
 ): Promise<void> {
   const { direction = 'both', depth = 3, json = false, graph: graphType } = options;
 
-  if (!graphType && !indexExists(cwd)) {
-    console.error('Error: No artifact index found.');
-    console.log("Run 'aiwg index build' first to create the index.");
-    process.exit(1);
-  }
+  let depGraph: DependencyGraph | null = null;
 
-  const depGraph = graphType
-    ? loadGraphIndexFile<DependencyGraph>(cwd, 'dependencies.json', graphType)
-    : loadDependencyGraph(cwd);
-  if (!depGraph) {
-    console.error('Error: Failed to load dependency graph.');
-    process.exit(1);
+  if (graphType) {
+    depGraph = loadGraphIndexFile<DependencyGraph>(cwd, 'dependencies.json', graphType);
+    if (!depGraph) {
+      console.error(`Error: No artifact index found for graph '${graphType}'.`);
+      console.log("Run 'aiwg index build' first to create the index.");
+      process.exit(1);
+    }
+  } else {
+    // Merge dependency graphs from project-local graphs
+    const graphTypes: GraphType[] = ['project', 'codebase'];
+    const merged: DependencyGraph = {};
+    for (const g of graphTypes) {
+      const partial = loadGraphIndexFile<DependencyGraph>(cwd, 'dependencies.json', g);
+      if (partial) Object.assign(merged, partial);
+    }
+
+    if (Object.keys(merged).length > 0) {
+      depGraph = merged;
+    } else {
+      // Legacy fallback
+      depGraph = loadDependencyGraph(cwd);
+      if (!depGraph) {
+        console.error('Error: No artifact index found.');
+        console.log("Run 'aiwg index build' first to create the index.");
+        process.exit(1);
+      }
+    }
   }
 
   if (!depGraph[artifactPath]) {

package/src/artifacts/query-engine.ts

@@ -11,7 +11,7 @@
 
 import { minimatch } from 'minimatch';
 import type { QueryParams, QueryResult, MetadataEntry, GraphType, ArtifactIndex } from './types.js';
-import { loadMetadataIndex, indexExists, loadGraphIndexFile } from './index-reader.js';
+import { loadMetadataIndex, loadGraphIndexFile } from './index-reader.js';
 
 export interface QueryOptions {
   json?: boolean;
@@ -66,23 +66,41 @@ export async function queryIndex(
   options: QueryOptions = {}
 ): Promise<void> {
   const { graph } = options;
+  const startTime = Date.now();
 
-  if (!graph && !indexExists(cwd)) {
-    console.error('Error: No artifact index found.');
-    console.log("Run 'aiwg index build' first to create the index.");
-    process.exit(1);
-  }
+  let candidates: MetadataEntry[];
 
-  const startTime = Date.now();
-  const index = graph
-    ? loadGraphIndexFile<ArtifactIndex>(cwd, 'metadata.json', graph)
-    : loadMetadataIndex(cwd);
-  if (!index) {
-    console.error('Error: Failed to load artifact index.');
-    process.exit(1);
-  }
+  if (graph) {
+    // Single graph mode
+    const index = loadGraphIndexFile<ArtifactIndex>(cwd, 'metadata.json', graph);
+    if (!index) {
+      console.error(`Error: No artifact index found for graph '${graph}'.`);
+      console.log("Run 'aiwg index build' first to create the index.");
+      process.exit(1);
+    }
+    candidates = Object.values(index.entries);
+  } else {
+    // No graph specified: search across all project-local graphs
+    const graphTypes: GraphType[] = ['project', 'codebase'];
+    const allEntries: MetadataEntry[] = [];
+    for (const g of graphTypes) {
+      const idx = loadGraphIndexFile<ArtifactIndex>(cwd, 'metadata.json', g);
+      if (idx) allEntries.push(...Object.values(idx.entries));
+    }
 
-  let candidates = Object.values(index.entries);
+    // Fall back to legacy root index
+    if (allEntries.length === 0) {
+      const legacy = loadMetadataIndex(cwd);
+      if (!legacy) {
+        console.error('Error: No artifact index found.');
+        console.log("Run 'aiwg index build' first to create the index.");
+        process.exit(1);
+      }
+      allEntries.push(...Object.values(legacy.entries));
+    }
+
+    candidates = allEntries;
+  }
 
   // Apply filters
   if (params.type) {

package/src/artifacts/stats.ts

@@ -12,7 +12,7 @@ import fs from 'fs';
 import path from 'path';
 import type { GraphType, IndexStats } from './types.js';
 import { GRAPH_CONFIGS } from './types.js';
-import { loadIndexStats, indexExists, loadGraphIndexFile } from './index-reader.js';
+import { loadIndexStats, loadGraphIndexFile } from './index-reader.js';
 
 export interface StatsOptions {
   json?: boolean;
@@ -60,23 +60,74 @@ export async function showStats(
 ): Promise<void> {
   const { graph } = options;
 
-  if (!graph && !indexExists(cwd)) {
-    console.error('Error: No artifact index found.');
-    console.log("Run 'aiwg index build' first to create the index.");
-    process.exit(1);
+  if (graph) {
+    // Single graph mode
+    const stats = loadGraphIndexFile<IndexStats>(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.");
+      process.exit(1);
+    }
+    await renderStats(cwd, stats, options, graph);
+    return;
+  }
+
+  // No graph specified: show per-project graphs (framework is global, use --graph framework)
+  const graphTypes: GraphType[] = ['project', 'codebase'];
+  const availableGraphs: { type: GraphType; stats: IndexStats }[] = [];
+  for (const g of graphTypes) {
+    const s = loadGraphIndexFile<IndexStats>(cwd, 'stats.json', g);
+    if (s) availableGraphs.push({ type: g, stats: s });
+  }
+
+  // Fall back to legacy root index
+  if (availableGraphs.length === 0) {
+    const legacyStats = loadIndexStats(cwd);
+    if (!legacyStats) {
+      console.error('Error: No artifact index found.');
+      console.log("Run 'aiwg index build' first to create the index.");
+      process.exit(1);
+    }
+    await renderStats(cwd, legacyStats, options);
+    return;
+  }
+
+  if (options.json) {
+    // JSON mode: aggregate all graphs into one response
+    const combined: Record<string, unknown> = {};
+    for (const { type, stats: s } of availableGraphs) {
+      const totalFiles = countArtifactFiles(cwd, type);
+      combined[type] = {
+        ...s,
+        coverage: {
+          indexed: s.totalArtifacts,
+          totalFiles,
+          percentage: totalFiles > 0 ? Math.round((s.totalArtifacts / totalFiles) * 100) : 100,
+        },
+      };
+    }
+    console.log(JSON.stringify(combined, null, 2));
+    return;
   }
 
-  const stats = graph
-    ? loadGraphIndexFile<IndexStats>(cwd, 'stats.json', graph)
-    : loadIndexStats(cwd);
-  if (!stats) {
-    console.error('Error: Failed to load index statistics.');
-    process.exit(1);
+  // Human-readable: show each graph
+  for (const { type, stats: s } of availableGraphs) {
+    console.log(`\n[${ type.toUpperCase() } GRAPH]`);
+    await renderStats(cwd, s, { ...options, json: false }, type);
   }
+}
 
+/**
+ * Render stats for a single graph (JSON or human-readable)
+ */
+async function renderStats(
+  cwd: string,
+  stats: IndexStats,
+  options: StatsOptions,
+  graphType?: GraphType
+): Promise<void> {
   if (options.json) {
-    // Add coverage info
-    const totalFiles = countArtifactFiles(cwd, graph);
+    const totalFiles = countArtifactFiles(cwd, graphType);
     console.log(JSON.stringify({
       ...stats,
       coverage: {
@@ -133,7 +184,7 @@ export async function showStats(
   console.log('');
 
   // Coverage
-  const totalFiles = countArtifactFiles(cwd, graph);
+  const totalFiles = countArtifactFiles(cwd, graphType);
   const coverage = totalFiles > 0
     ? Math.round((stats.totalArtifacts / totalFiles) * 100)
     : 100;

package/src/channel/manager.mjs

@@ -169,7 +169,12 @@ export async function switchToEdge() {
 }
 
 /**
- * Switch to dev mode (use local repo as framework source)
+ * Switch to dev mode (use local repo as both framework source and CLI)
+ *
+ * In dev mode, the CLI entry point delegates to the dev repo's facade,
+ * so all code (including `aiwg index`, `aiwg use`, etc.) runs from the
+ * local build rather than the npm-installed package.
+ *
  * @param {string} devPath - Path to the local development repository
  */
 export async function switchToDev(devPath) {
@@ -189,13 +194,26 @@ export async function switchToDev(devPath) {
     process.exit(1);
   }
 
+  // Verify CLI facade exists (needed for delegation)
+  try {
+    await fs.access(path.join(resolvedPath, 'src', 'cli', 'facade.mjs'));
+  } catch {
+    console.error(`Error: ${resolvedPath}/src/cli/facade.mjs not found.`);
+    console.error('Dev mode requires the source CLI facade. Is this the right repo?');
+    process.exit(1);
+  }
+
   config.channel = 'edge';
   config.edgePath = resolvedPath;
   config.devMode = true;
   await saveConfig(config);
 
   console.log('Switched to dev mode.');
-  console.log(`Framework source: ${resolvedPath}`);
+  console.log(`Dev repo:    ${resolvedPath}`);
+  console.log(`CLI source:  ${resolvedPath}/src/cli/facade.mjs`);
+  console.log('');
+  console.log('The aiwg command now runs code from your local repo.');
+  console.log('After making changes, run: npm run build');
   console.log('');
   console.log('Commands:');
   console.log('  aiwg use all          Deploy from local source');