docs: replace retired /gsd-intel with /gsd-map-codebase --query (#3258) (#3260)

* test: forbid stale /gsd-intel references in workflow/reference docs (#3258)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* docs: replace retired /gsd-intel with /gsd-map-codebase --query (#3258)

Fixes 5 stale references across the two primary source files called out in
the issue. PR #2790 folded /gsd-intel into /gsd-map-codebase --query; these
prose surfaces were not updated at that time.

Fixes #3258

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* docs: fix additional stale /gsd-intel references found in adversarial sweep (#3258)

Sweep found 7 more occurrences in docs/INVENTORY.md (x2), docs/USER-GUIDE.md (x4),
docs/FEATURES.md (x2), and agents/gsd-intel-updater.md (x2). All replaced with
/gsd-map-codebase --query. The gsd-intel-updater agent name itself (without leading
slash) is intentionally preserved.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* changeset: pr=3260 for #3258

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* test: fail loudly on unreadable files in bug-3258 regression scan (CR finding)

Replace silent early-return on readFileSync failure with an explicit
throw so unreadable files surface as test failures rather than skipped
coverage gaps.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

---------

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>

.changeset/bold-elks-zip.md

@@ -0,0 +1,5 @@
+---
+type: Fixed
+pr: 3260
+---
+**`/gsd-settings` Intel question now points to the correct command** — was telling users to use the retired `/gsd-intel` (folded into `/gsd-map-codebase --query` by #2790). Same correction applied to `references/planning-config.md`, `docs/USER-GUIDE.md`, `docs/FEATURES.md`, `docs/INVENTORY.md`, and `agents/gsd-intel-updater.md`. No backend change.

agents/gsd-intel-updater.md

@@ -44,15 +44,15 @@ Write machine-parseable, evidence-based intelligence. Every claim references act
 <upstream_input>
 ## Upstream Input
 
-### From `/gsd-intel` Command
+### From `/gsd-map-codebase --query` Command
 
-- **Spawned by:** `/gsd-intel` command
+- **Spawned by:** `/gsd-map-codebase --query` command
 - **Receives:** Focus directive -- either `full` (all 5 files) or `partial --files <paths>` (update specific file entries only)
 - **Input format:** Spawn prompt with `focus: full|partial` directive and project root path
 
 ### Config Gate
 
-The /gsd-intel command has already confirmed that intel.enabled is true before spawning this agent. Proceed directly to Step 1.
+The /gsd-map-codebase --query command has already confirmed that intel.enabled is true before spawning this agent. Proceed directly to Step 1.
 </upstream_input>
 
 ## Project Scope

docs/FEATURES.md

@@ -2064,7 +2064,7 @@ Test suite that scans all agent, workflow, and command files for embedded inject
 
 ### 90. Queryable Codebase Intelligence
 
-**Command:** `/gsd-intel [query <term>|status|diff|refresh]`
+**Command:** `/gsd-map-codebase --query [<term>|status|diff|refresh]`
 **Config:** `intel.enabled`
 
 **Purpose:** Maintain a queryable JSON index of codebase structure, API surface, dependency graph, file roles, and architecture decisions in `.planning/intel/`. Enables targeted lookups without reading the entire codebase.
@@ -2614,7 +2614,7 @@ Users who run a memory / knowledge-base MCP server (for example, ExoCortex-style
 
 ### 121. Knowledge Graph Integration
 
-**Purpose:** Build, query, and inspect a lightweight knowledge graph of the project in `.planning/graphs/`. Opt-in per project. Exposed as the `/gsd-graphify` user-facing command and the `gsd-tools.cjs graphify …` programmatic verb family. Complements `/gsd-intel` (snapshot-oriented) with a graph-oriented view of nodes and edges across commands, agents, workflows, and phases.
+**Purpose:** Build, query, and inspect a lightweight knowledge graph of the project in `.planning/graphs/`. Opt-in per project. Exposed as the `/gsd-graphify` user-facing command and the `gsd-tools.cjs graphify …` programmatic verb family. Complements `/gsd-map-codebase --query` (snapshot-oriented) with a graph-oriented view of nodes and edges across commands, agents, workflows, and phases.
 
 **Requirements:**
 - REQ-GRAPH-01: Opt-in via `graphify.enabled: true` in `.planning/config.json`. When disabled, `/gsd-graphify` prints an activation hint and stops without writing.

docs/INVENTORY.md

@@ -46,7 +46,7 @@ Full roster at `agents/gsd-*.md`. The "Primary doc" column flags whether [`docs/
 | gsd-eval-planner | Designs structured evaluation strategy for an AI phase (AI-SPEC.md §5–§7). | `/gsd-ai-integration-phase` | advanced stub |
 | gsd-eval-auditor | Retroactive audit of an AI phase's evaluation coverage; produces EVAL-REVIEW.md (COVERED/PARTIAL/MISSING). | `/gsd-eval-review` | advanced stub |
 | gsd-framework-selector | ≤6-question interactive decision matrix that scores and recommends an AI/LLM framework. | `/gsd-ai-integration-phase`, `/gsd-select-framework` | advanced stub |
-| gsd-intel-updater | Writes structured intel files (`.planning/intel/*.json`) used as a queryable codebase knowledge base. | `/gsd-intel` | advanced stub |
+| gsd-intel-updater | Writes structured intel files (`.planning/intel/*.json`) used as a queryable codebase knowledge base. | `/gsd-map-codebase --query` | advanced stub |
 | gsd-doc-classifier | Classifies a single planning document as ADR, PRD, SPEC, DOC, or UNKNOWN; spawned in parallel to process the doc corpus. | `/gsd-ingest-docs` | advanced stub |
 | gsd-doc-synthesizer | Synthesizes classified planning docs into a single consolidated context with precedence rules, cycle detection, and three-bucket conflicts report. | `/gsd-ingest-docs` | advanced stub |
 
@@ -382,7 +382,7 @@ Full listing: `get-shit-done/bin/lib/*.cjs`.
 | `init-command-router.cjs` | Thin CJS subcommand router adapter for `gsd-tools init` |
 | `init.cjs` | Compound context loading for each workflow type |
 | `install-profiles.cjs` | Install profile allowlist + skill staging for `--minimal` install (#2762); single source of truth for which `gsd-*` skills/agents land in runtime config dirs |
-| `intel.cjs` | Codebase intel store backing `/gsd-intel` and `gsd-intel-updater` |
+| `intel.cjs` | Codebase intel store backing `/gsd-map-codebase --query` and `gsd-intel-updater` |
 | `learnings.cjs` | Cross-phase learnings extraction for `/gsd-extract-learnings` |
 | `milestone.cjs` | Milestone archival, requirements marking |
 | `model-profiles.cjs` | Model profile resolution table (authoritative profile data) |

docs/USER-GUIDE.md

@@ -821,10 +821,10 @@ For queryable codebase insights without reading the entire codebase, enable the
 Then build the index:
 
 ```bash
-/gsd-intel refresh             # Analyze codebase and write .planning/intel/ files
-/gsd-intel query auth          # Search for a term across all intel files
-/gsd-intel status              # Check freshness of intel files
-/gsd-intel diff                # See what changed since last snapshot
+/gsd-map-codebase --query refresh             # Analyze codebase and write .planning/intel/ files
+/gsd-map-codebase --query auth               # Search for a term across all intel files
+/gsd-map-codebase --query status             # Check freshness of intel files
+/gsd-map-codebase --query diff               # See what changed since last snapshot
 ```
 
 Intel files cover stack, API surface, dependency graph, file roles, and architecture decisions.

get-shit-done/references/planning-config.md

@@ -319,11 +319,11 @@ Set via `learnings.*` namespace (e.g., `"learnings": { "max_inject": 5 }`). Used
 
 ### Intel Fields
 
-Set via `intel.*` namespace (e.g., `"intel": { "enabled": true }`). Controls the queryable codebase intelligence system consumed by `/gsd-intel`.
+Set via `intel.*` namespace (e.g., `"intel": { "enabled": true }`). Controls the queryable codebase intelligence system consumed by `/gsd-map-codebase --query`.
 
 | Key | Type | Default | Allowed Values | Description |
 |-----|------|---------|----------------|-------------|
-| `intel.enabled` | boolean | `false` | `true`, `false` | Enable queryable codebase intelligence system. When `true`, `/gsd-intel` commands build and query a JSON index in `.planning/intel/`. |
+| `intel.enabled` | boolean | `false` | `true`, `false` | Enable queryable codebase intelligence system. When `true`, `/gsd-map-codebase --query` builds and queries a JSON index in `.planning/intel/`. |
 
 ### Manager Fields
 

get-shit-done/workflows/settings.md

@@ -49,7 +49,7 @@ Parse current values (default to `true` if not present):
 - `workflow.code_review_depth` — default depth for /gsd-code-review: `quick`, `standard`, or `deep` (default: `"standard"` if absent; only relevant when `code_review` is on)
 - `workflow.ui_review` — run visual quality audit (/gsd-ui-review) in autonomous mode (default: true if absent)
 - `commit_docs` — whether `.planning/` files are committed to git (default: true if absent)
-- `intel.enabled` — enable queryable codebase intelligence (/gsd-intel) (default: false if absent)
+- `intel.enabled` — enable queryable codebase intelligence (/gsd-map-codebase --query) (default: false if absent)
 - `graphify.enabled` — enable project knowledge graph (/gsd-graphify) (default: false if absent)
 - `model_profile` — which model each agent uses (default: `balanced`)
 - `git.branching_strategy` — branching approach (default: `"none"`)
@@ -292,12 +292,12 @@ AskUserQuestion([
     ]
   },
   {
-    question: "Enable Intel? (queryable codebase intelligence via /gsd-intel — builds a JSON index in .planning/intel/)",
+    question: "Enable Intel? (queryable codebase intelligence via /gsd-map-codebase --query — builds a JSON index in .planning/intel/)",
     header: "Intel",
     multiSelect: false,
     options: [
       { label: "No (Recommended)", description: "Skip intel indexing. Use when codebase is small or intel queries are not needed." },
-      { label: "Yes", description: "Enable /gsd-intel commands. Builds and queries a JSON index of the codebase." }
+      { label: "Yes", description: "Enable /gsd-map-codebase --query commands. Builds and queries a JSON index of the codebase." }
     ]
   },
   {

tests/bug-3258-no-stale-gsd-intel-references.test.cjs

@@ -0,0 +1,109 @@
+// allow-test-rule: source-text-is-the-product — workflow, reference, and docs .md files
+// ARE what the runtime loads and what users read; asserting their text content
+// tests the deployed skill surface contract, not implementation internals.
+
+'use strict';
+
+// Regression tests for bug #3258.
+//
+// PR #2790 folded `/gsd-intel` into `/gsd-map-codebase --query`. After that
+// consolidation, five prose occurrences in two source files continued to
+// reference the retired `/gsd-intel` slash command. Users invoking the wizard
+// were directed to a command that no longer exists.
+//
+// Fix: replace each `/gsd-intel` (the retired user-facing slash command) with
+// `/gsd-map-codebase --query` in:
+//   - get-shit-done/references/planning-config.md
+//   - get-shit-done/workflows/settings.md
+//   - docs/INVENTORY.md
+//   - docs/USER-GUIDE.md
+//   - docs/FEATURES.md
+//
+// Allowed: `gsd-intel-updater` (still-valid agent name, no leading slash),
+//          `intel.cjs` / `intel.enabled` / `intel.*` (internal backend, not user command),
+//          CHANGELOG.md (historical record), test files themselves.
+//
+// This test distinguishes `/gsd-intel` (the retired slash command, leading slash)
+// from `gsd-intel-updater` (still-valid agent) by grepping for the literal
+// string `/gsd-intel` and then asserting no match survives after excluding
+// the `-updater` suffix.
+
+const { describe, test } = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const path = require('node:path');
+
+const ROOT = path.join(__dirname, '..');
+
+/** Walk a directory recursively and return absolute paths of all .md files. */
+function walkMd(dir) {
+  const results = [];
+  if (!fs.existsSync(dir)) return results;
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const abs = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      results.push(...walkMd(abs));
+    } else if (entry.isFile() && entry.name.endsWith('.md')) {
+      results.push(abs);
+    }
+  }
+  return results;
+}
+
+/**
+ * Return all lines in `src` that contain `/gsd-intel` (the retired slash
+ * command) but are NOT the agent name `gsd-intel-updater`.
+ * We match the literal substring `/gsd-intel` (with leading slash) and then
+ * exclude any line where the match is immediately followed by `-updater`.
+ */
+function staleLinesIn(src) {
+  return src.split('\n').filter((line) => {
+    if (!line.includes('/gsd-intel')) return false;
+    // Remove all occurrences of the valid agent name; if nothing remains, skip.
+    const stripped = line.replace(/\/gsd-intel-updater/g, '');
+    return stripped.includes('/gsd-intel');
+  });
+}
+
+const SOURCE_DIRS = [
+  path.join(ROOT, 'commands', 'gsd'),
+  path.join(ROOT, 'get-shit-done', 'workflows'),
+  path.join(ROOT, 'get-shit-done', 'references'),
+  path.join(ROOT, 'agents'),
+  path.join(ROOT, 'docs'),
+];
+
+describe('#3258: no stale /gsd-intel slash-command references in product source dirs', () => {
+  for (const dir of SOURCE_DIRS) {
+    const files = walkMd(dir);
+    for (const file of files) {
+      const rel = path.relative(ROOT, file);
+
+      // Allowed exclusions:
+      // - CHANGELOG.md is a historical record; /gsd-intel appears in release notes
+      // - test files (under tests/) are excluded automatically by SOURCE_DIRS scope
+      if (rel === 'CHANGELOG.md') continue;
+
+      test(`${rel} has no stale /gsd-intel references`, () => {
+        let src;
+        try {
+          src = fs.readFileSync(file, 'utf8');
+        } catch (err) {
+          throw new Error(`failed reading ${rel}: ${err.message}`);
+        }
+
+        const staleLines = staleLinesIn(src);
+        assert.strictEqual(
+          staleLines.length,
+          0,
+          [
+            `${rel} contains ${staleLines.length} stale /gsd-intel reference(s).`,
+            'Replace with /gsd-map-codebase --query (retired by PR #2790).',
+            'Stale lines:',
+            ...staleLines.map((l) => `  ${l.trim()}`),
+          ].join('\n'),
+        );
+      });
+    }
+  }
+});