semantic-map and claude commands/skills

.claude/commands/semantic-map-light-query.md

@@ -0,0 +1,14 @@
+---
+description: >-
+  Local keyword search over indexed docs/context (markdown-chunks.json) in the semantic-map bundle.
+---
+
+Requires **`markdown-chunks.json`** in the bundle (from **`semantic-map index`** or **`analyze -markdown-index`**).
+
+Set **`BUNDLE`** to **`semantic-map`** (default **`analyze`** output under the app clone). If you used **`-output`**, use that directory instead.
+
+```bash
+/path/to/semantic-map/bin/semantic-map query "$PWD/$BUNDLE" "your keywords here"
+```
+
+Pass **`-n 20`** to the binary if you need more than 15 hits (see **`semantic-map help query`**).

.claude/commands/semantic-map-light-validate.md

@@ -0,0 +1,15 @@
+---
+description: >-
+  Validate semantic map Markdown under the bundle docs/context (relative bundle root, usually semantic-map/).
+---
+
+Set **`BUNDLE`** to **`semantic-map`** (default **`analyze`** layout) or the path you passed to **`-output`**.
+
+From a machine with **semantic-map** built:
+
+```bash
+make -C /path/to/semantic-map build
+/path/to/semantic-map/bin/semantic-map validate "$PWD/$BUNDLE/docs/context"
+```
+
+Replace **`BUNDLE`** with the relative path under this repo’s root. Exit code **1** means missing required `##` sections per **`concept.md`** in your semantic-map tool checkout.

.claude/skills/semantic-map-light/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: semantic-map-light
+description: >-
+  Application repo: read semantic-map/docs/context and JSON while coding (bugs, features).
+  Map authoring (analyze, orchestrate, augment module.md) runs from the semantic-map tool
+  checkout—see semantic-map/ANALYSIS.md and upstream docs.
+---
+
+# Semantic map (light — application bundle)
+
+This skill covers **using** a checked-in bundle **while you change code** (read **`docs/context/`**, **`go-facts.json`**, etc.). It does **not** document the full **map build** pipeline—that lives in the **semantic-map** tool repository (**`analyze`**, **`orchestrate`**, Claude augmentation recipes). Your team’s **`semantic-map/ANALYSIS.md`** points at that workflow; refreshing facts still requires the **`semantic-map`** binary from **that** checkout.
+
+## Bundle location
+
+After adopting the **semantic-map** tool (this application repo’s `semantic-map/ANALYSIS.md` records which fork/version you use), the artifact tree is typically:
+
+```text
+semantic-map/                        # bundle root (<clone>/semantic-map after analyze)
+```
+
+- **`docs/context/root.md`** — L0 atlas (start here).
+- **`docs/context/<path>/module.md`** — L1 per Go source directory.
+- **`go-facts.json`**, **`repo-tree.json`**, **`deps-graph.json`** — deterministic inputs for agents.
+- **`prompts/`** — pinned copies of Architect / Analyst / Auditor templates used when this bundle was generated.
+- **`manifest.json`** — bundle metadata (paths may be absolute to the machine that last ran `analyze`).
+
+The **semantic-map tool repository** may also ship **example** trees under **`map/<owner>/<repo>/map/`**; that layout is not what **`analyze`** emits by default.
+
+## Read-first workflow (no tool install)
+
+1. Open **`docs/context/root.md`** for system overview.
+2. Jump to the relevant **`module.md`** under **`docs/context/`** matching the package path.
+3. Cross-check exports and imports with **`go-facts.json`** / **`deps-graph.json`** when precision matters.
+
+## When you need the semantic-map CLI
+
+You need a built **`semantic-map` binary** and the upstream tool checkout (or install path) to:
+
+- Run **`analyze`** again after large code moves, new `cmd/` trees, or to refresh JSON facts.
+- Run **`orchestrate`**, **`index`**, **`validate`**, or **`query`** on the bundle.
+
+The canonical flags for this repo should live in **`semantic-map/ANALYSIS.md`** (or the path your team chose when copying **`contrib/target-repo/`** from the semantic-map tool repository).
+
+## Prompt expansion
+
+**`prompts expand`** reads templates from **`prompts/`** inside the bundle, not from the tool repo. You still need the **binary** and a **`manifest.json`** whose paths match the current machine (see ANALYSIS.md portable manifests note).

semantic-map/ANALYSIS.md

@@ -0,0 +1,53 @@
+# Canonical semantic-map analysis recipe
+
+Run from a machine that has the **semantic-map** repository built (`make build` → `bin/semantic-map`). Run **`analyze`** from the **semantic-map** checkout so **`prompts/`** can be copied (or pass **`-prompts-from`**).
+
+| Placeholder | Meaning |
+|-------------|---------|
+| `CLONE` | Absolute path to your **local clone** of this application repository |
+| `OWNER` | GitHub/GitLab org or user (first segment of `owner/repo`) |
+| `REPO` | Repository name (second segment of `owner/repo`) |
+| `SEMANTIC_MAP` | Absolute path to your **semantic-map** tool checkout (contains `Makefile`, `prompts/`) |
+
+**Default:** artifacts go under **`CLONE/semantic-map/`** (bundle root).
+
+## One-shot refresh (facts, stubs, index, orchestration)
+
+```bash
+cd "$SEMANTIC_MAP"
+make build
+
+./bin/semantic-map analyze "$CLONE" \
+  --slug OWNER/REPO \
+  --write-facts \
+  --refresh-root \
+  --refresh-modules \
+  -markdown-index
+
+BUNDLE="$CLONE/semantic-map"
+
+./bin/semantic-map orchestrate "$BUNDLE"
+./bin/semantic-map index "$BUNDLE"
+```
+
+Derive `OWNER/REPO` from `git -C "$CLONE" remote get-url origin` if you omit **`--slug`**.
+
+**Custom bundle location:**
+
+```bash
+./bin/semantic-map analyze "$CLONE" -output "$HOME/semantic-maps/OWNER/REPO" --write-facts
+# set BUNDLE to that -output path for orchestrate/index
+```
+
+## Optional: expand prompts only (binary + bundle)
+
+Uses **`bundle/prompts/`** from the analyzed tree.
+
+```bash
+./bin/semantic-map prompts expand "$BUNDLE"
+```
+
+## Portable manifests
+
+`manifest.json` records **absolute** paths (`clone_dir`, `artifact_root`). After another engineer clones this repo, re-run **`analyze`** (or at least refresh paths and **`prompts expand`**) on their machine before trusting **`prompts-expanded/`** for Architect/Analyst/Auditor flows.
+