incitaciones 0.6.0 → 0.8.0

package/README.md

@@ -39,13 +39,10 @@ cd incitaciones
 **Install options:**
 
 ```bash
-./install.sh --bundle essentials    # Core prompts only
-./install.sh --bundle planning      # Planning workflows
-./install.sh --bundle reviews       # Review prompts
-./install.sh --bundle documentation # Documentation tools
+./install.sh --bundle essentials    # Core prompts only (see all 8 bundles: --list)
+./install.sh --list                 # Show available prompts and bundles
 ./install.sh --format commands      # Legacy flat-file format for other tools
 ./install.sh --disable-model-invocation # Require explicit /skill:name usage
-./install.sh --list                 # Show available prompts
 ./install.sh --help                 # Show all options
 ```
 
@@ -83,12 +80,12 @@ pi install git:github.com/charly-vibes/incitaciones
 pi install .
 ```
 
-The repository includes checked-in pi package resources under `pi-package/`, and the generation step can refresh them when content changes:
+The npm package ships generated pi package resources under `pi-package/`. The directory is **gitignored, not checked in** — CI regenerates it during npm publish (`npm-publish.yml` runs `scripts/generate-pi-resources.mjs` before `npm publish`), so there is nothing to commit. Locally, the pre-push hook runs `just validate-pi-package`, which regenerates and verifies the resources match the manifest:
 
 - `pi-package/skills/` — Agent Skills with pi-compatible frontmatter
 - `pi-package/prompts/` — prompt templates for slash-command shortcuts
 
-After changing distilled content or manifest entries, run `just generate-pi-resources` and commit the updated `pi-package/` files.
+After changing distilled content or manifest entries, you don't need to touch `pi-package/` — it is regenerated and validated automatically (CI on publish, pre-push hook locally). To preview the generated resources manually, run `just generate-pi-resources`.
 
 ### Publishing a new version
 

package/content/distilled/codebase-cartography/SKILL.md

@@ -31,11 +31,12 @@ Pick the entry level from the request:
 - Before gathering evidence for any map (and again before rendering), read `references/zoom-levels.md` — per-level evidence collection commands and text rendering formats.
 - Before any health check or when the user asks about "health", "smells", or refactoring targets, read `references/smell-signatures.md` — anti-pattern proxies, evidence requirements, severity ratings.
 - Before writing the final output, read `references/report-template.md` — output structure per mode.
-- When the user asks for an HTML export or a shareable version of the report, read the "Optional HTML Export" section at the end of `references/report-template.md`.
+- When the user asks for an HTML export or a shareable version of the report, read the "Optional HTML Export" section at the end of `references/report-template.md`; when the request spans multiple reports (batch), also read its "Batch export" section.
 
 ## Zoom Discipline
 
-- Offer adjacent levels as follow-ups; never dump all three maps unrequested.
+- Offer adjacent levels as follow-ups; never dump all three maps unrequested. An explicit batch request ("all reports", "map every module") is a user request — the offer-don't-dump rule applies to unprompted follow-ups only (batch procedure in `references/report-template.md`, "Batch export" section).
+- Re-verify every embedded count and fan-in/fan-out number against a fresh command run immediately before writing each report (one consolidated pass per batch is fine) — counts gathered early in a long session drift.
 - Every claim carries a file reference (`path`, or `path:line` for specific symbols).
 - State dependency direction explicitly (A → B); never "related to".
 - Distinguish observed evidence from inference; label inference explicitly.
@@ -48,4 +49,4 @@ Pick the entry level from the request:
 - Prefer structural facts over narrative: dependency direction, counts, boundaries.
 - Health-check findings follow the evidence format in `references/smell-signatures.md` (pattern, evidence, quantity, severity) — never unanchored opinions.
 - Maps are diff-able artifacts: tables and Mermaid, not prose walls.
-- HTML export is derived output, produced only on request; the markdown report remains the artifact of record.
+- HTML export is derived output, produced only on request; the markdown report remains the artifact of record. Exports live in `docs/cartography/` as a self-contained directory (index + shared assets); see the "Optional HTML Export" section of `references/report-template.md`.

package/content/distilled/codebase-cartography/references/report-template.md

@@ -60,16 +60,67 @@ One finding block per pattern (format in `smell-signatures.md`), ordered by seve
 
 **Adjacent levels offered** — one line each, e.g. "meso map of ledger available on request".
 
+## Batch export
+
+An explicit batch request ("generate all the reports", "map every module") is a user request — Zoom Discipline's offer-don't-dump rule applies to unprompted follow-ups only.
+
+- Enumerate targets from the module inventory. Confirm the list once when it exceeds 3 targets or the scope is ambiguous; proceed unless corrected.
+- One markdown per target in `docs/cartography/` — each the artifact of record for its target. For each, re-verify counts immediately before writing (Zoom Discipline).
+- Include a health report only if the batch request names health/smells.
+- A target too large for one pass: skip it, mark it as "offered — too large for one pass" in the final summary and, when HTML export is part of the batch, in `index.html`. Do not stop the batch to ask.
+- Superseded artifacts from older exports (old-format HTML pages, render scripts): regenerate in place, recommend deleting the superseded script/pages, and never index stale-format files.
+- When HTML export is part of the batch request or separately requested, HTML pages and `index.html` follow the Optional HTML Export section (regenerate the index once at the end, covering all reports).
+
 ## Optional HTML Export
 
-Produce only on request ("export as HTML", "shareable report"). The markdown report is the source of truth; the HTML file is a derived, regenerable view — never hand-edit it, regenerate it from the markdown.
+Produce only on request ("export as HTML", "shareable report"). The markdown report is the source of truth; the HTML files are a derived, regenerable view — never hand-edit them, regenerate them from the markdown.
+
+The export is a **self-contained directory**: all pages plus shared assets under one folder, opening correctly via `file://`, offline, with no server, CDN at view time, or build step. JavaScript is permitted only as a local vendored asset (see Diagrams).
+
+### Output directory
+
+- All exports live in `docs/cartography/` (create directories as needed). If `docs/` does not already exist in the repo, confirm once with the user before creating it.
+- Pages reference assets with relative paths (`assets/...`), never absolute or remote URLs.
+
+### Files
+
+- One page per report: `cartography-<level>-<target>.html` (e.g. `cartography-meso-payments-billing.html`; slugify the target with hyphens, no dots or spaces). The zoom level in the name prevents exports of different levels overwriting each other. Re-exporting the same level+target overwrites the previous file — intended; there is no history.
+- `index.html` — regenerated on every export; never hand-maintained.
+- `assets/mermaid.min.js` — vendored Mermaid v9.4.3 IIFE build, shared by all pages.
+
+### Index
+
+Regenerate `index.html` on every export from what is on disk plus what is known this session:
+
+- Scan `docs/cartography/*.html` (excluding `index.html`), group entries by zoom level (macro / meso / micro / health), sorted alphabetically.
+- Each entry links to the page and shows its target plus a one-line scope taken from the report header.
+- Also list markdown reports known to this session (the artifact of record), linked with a repo-relative path from the HTML location. Do not invent paths for reports you cannot locate.
+- The template must handle N=1 (a single entry) without looking broken.
+- Deterministic: sorted, no timestamps, no generator metadata.
+
+### Navigation
+
+- Every page (including `index.html`) has a plain nav header: `← Index` plus links to parent-context and adjacent-level pages when they exist (meso → its macro page; micro → its macro/meso parent). Relative links only.
+- Static links only — no interactivity. Do not evolve the export into an application — no servers, frameworks, or interactive controls. If live interaction is requested, note it is out of scope for this skill.
+
+### Diagrams
+
+- Render Mermaid client-side with the vendored local asset: `<script src="assets/mermaid.min.js"></script>` plus `<pre class="mermaid">` blocks. Use only the v9.x IIFE build (global `mermaid`); v10+ is ESM-only and is blocked by CORS under `file://`.
+- Asset acquisition: on the first export, download `mermaid.min.js` v9.4.3 into `assets/` if absent (e.g. from jsDelivr); reuse thereafter. If the download fails (offline machine), still emit all pages — diagrams degrade to their source in a styled `<pre>` and the report footer notes "diagrams show source; rerun the export with network access to enable rendering". Never fail the whole export because of assets.
+- Every diagram keeps its Mermaid source in `<details><pre class="mermaid-source">` as the no-JS fallback, so nothing is ever blank.
+- Prose stays pre-rendered HTML — do not client-render markdown. The markdown report remains the artifact of record.
+
+### Handoff
+
+- Final step of any export (including the first): tell the user to open `docs/cartography/index.html` directly in a browser — `file://` works with no server; diagram rendering is guaranteed by the Diagrams section.
+- Never start a server for static reports unless the user explicitly asks.
 
-Produce ONE self-contained file, `cartography-<level>-<target>.html` (e.g. `cartography-meso-payments-billing.html`; slugify the target with hyphens), next to the markdown report — or, if no report file was written this session, ask the user where to save it (default `docs/`). The zoom level in the name prevents exports of different levels overwriting each other.
+### Invariants
 
-- **Self-contained:** one inline `<style>` block. No CDN, no external CSS/JS/fonts, no build step, no server. Must open correctly offline.
-- **No JavaScript:** diagrams render as styled `<pre>` blocks (text diagrams) or inline SVG producible without new dependencies. Keep the Mermaid source in the file (e.g. `<pre class="mermaid-source">`) so the diagram stays manipulable.
+- **Write HTML directly:** no render scripts, build pipelines, or new dependencies (pandoc etc.) — even in batch mode. The regeneration path is re-running this skill, not a committed pipeline; exception only on explicit user request (note the dependency caveat in the reply).
 - **Mirror, don't redesign:** same sections, same order, same content as the markdown report. The HTML adds presentation only (readable typography; `prefers-color-scheme` support optional).
 - **Deterministic:** stable section order, no timestamps, no generator metadata.
 - **Size guard:** render large reports as-is; never paginate, collapse, or add interactivity.
+- **Commit-able:** reports and `assets/` are self-contained and offline-safe; suggest committing them, never silently gitignore.
 
-Do not evolve the export into an application — no servers, frameworks, or interactive controls. If live interaction is requested, note it is out of scope for this skill.
+Decision record: diagrams use a vendored local Mermaid v9.4.3 IIFE; prose is pre-rendered. Rationale: offline rendering, `file://` compatibility, no ESM/CORS issues. Render scripts and build pipelines are banned because agent-regeneration keeps the navigation/diagram/index guarantees that build scripts historically dropped (wai cartography batch, 2026-09-01: a pandoc pipeline produced 12 pages with zero cross-links and unrendered diagrams).

package/content/distilled/whisper/SKILL.md

@@ -32,6 +32,17 @@ Manage `~/.whisper/` — a global, tiered knowledge directory that accumulates o
 
 **Worktree slot rule:** `basename $(git rev-parse --git-common-dir 2>/dev/null)` (the `.git` worktree dir name), or `basename $(pwd)` when not in a worktree.
 
+**Canonical repo key rule — derive it, never invent it:**
+
+```bash
+repo_url=$(git remote get-url origin 2>/dev/null | sed 's|https://||;s|http://||;s|ssh://||;s|git@||;s|:|/|g;s|\.git$||')
+[ -z "$repo_url" ] && repo_url="local/$(basename "$(git rev-parse --show-toplevel 2>/dev/null || pwd)")"
+```
+
+`git@cv:org/repo.git` → `cv/org/repo`; `https://github.com/u/r` → `github.com/u/r`; no remote → `local/<repo-name>`. Colons always become slashes (keeps keys path-safe). The same key must come out of the same repo on every machine.
+
+If a directory keyed some other way already exists for this repo (bare name like `genesis/`, owner-only like `charly-vibes/`, alias host with a colon like `cv:charly-vibes/`), do **not** add a fourth variant — route new knowledge into the canonical key and offer `/w consolidate` to migrate the legacy one.
+
 ## Knowledge Routing
 
 When a session learns something worth keeping, route it by scope:
@@ -47,6 +58,7 @@ When a session learns something worth keeping, route it by scope:
 **Rules:**
 - **No secrets anywhere.** Never write tokens, keys, passwords, or PII into `~/.whisper/`.
 - **Extend, don't duplicate.** Append to or correct an existing note rather than creating a new one that says the same thing.
+- **One repo, one key.** If more than one `repos/` directory belongs to the same repo, write into the canonical key and propose `/w consolidate` — never create a new variant.
 - **Search first.** Before creating a new entry, check if one already exists for the same topic.
 - If `bd` is not available, everything falls back to `~/.whisper/` files — there's no beads-backed alternative.
 
@@ -61,6 +73,7 @@ Determine mode from how the skill is triggered:
 | `/w check` or called by `renew` | **check** |
 | `/w link [<path>]` or "link plan" | **link** |
 | `/w decommission` | **decommission** |
+| `/w consolidate` or "dedupe whisper repos" | **consolidate** |
 
 See each reference file for the full procedure:
 
@@ -69,6 +82,7 @@ See each reference file for the full procedure:
 - `references/status.md`
 - `references/link.md`
 - `references/decommission.md`
+- `references/consolidate.md`
 
 ## Rules
 

package/content/distilled/whisper/references/check.md

@@ -6,7 +6,8 @@ Validate the workspace before starting work. Detects stale branch slots and work
 
 1. Get repo URL and branch slug:
    ```bash
-   repo_url=$(git remote get-url origin 2>/dev/null | sed 's|https://||;s|git@||;s|\.git$||')
+   repo_url=$(git remote get-url origin 2>/dev/null | sed 's|https://||;s|http://||;s|ssh://||;s|git@||;s|:|/|g;s|\.git$||')
+   [ -z "$repo_url" ] && repo_url="local/$(basename "$(git rev-parse --show-toplevel 2>/dev/null || pwd)")"
    branch=$(git rev-parse --abbrev-ref HEAD)
    branch_slug=$(echo "$branch" | sed 's|/|--|g')
    context_path=~/.whisper/repos/"${repo_url}"/branches/"${branch_slug}"/context.md

package/content/distilled/whisper/references/consolidate.md

@@ -0,0 +1,41 @@
+# Consolidate
+
+Merge duplicate `~/.whisper/repos/` directories for the same repo into the single canonical key. One repo, one key.
+
+## Why
+
+Older sessions keyed repos inconsistently — bare repo name (`genesis/`), owner dir (`charly-vibes/`), ssh-alias host with a colon (`cv:charly-vibes/`), full URL in the wrong shape. The same repo's knowledge ends up scattered across several trees, so `check` and `status` miss notes that exist. Consolidation restores the invariant; the canonical key derivation is defined in SKILL.md.
+
+## Steps
+
+1. **Inventory candidates** — non-canonical top-level entries. Canonical = at least 2 slashes and no colon in the first segment; also flag alias-host dirs (`<alias>:<owner>`):
+
+   ```bash
+   for d in ~/.whisper/repos/*/; do echo "${d#$HOME/.whisper/repos/}"; done
+   ```
+   A key is a candidate if it has 0 or 1 slashes, or contains `:`.
+
+2. **Derive the canonical target per candidate** — check the actual repo's remote:
+
+   ```bash
+   cd <repo checkout> && git remote get-url origin | sed 's|https://||;s|http://||;s|ssh://||;s|git@||;s|:|/|g;s|\.git$||'
+   ```
+   If no checkout is reachable for a candidate, leave it in place and report it — never guess the mapping from the name alone.
+
+3. **Produce a migration table and WAIT for approval** — one row per candidate: old key → canonical key, files found, merge conflicts detected. The user must explicitly approve before anything moves. If running non-interactively, output the plan and stop.
+
+4. **Merge per file on approval:**
+   - `env.md` — append the candidate's content under a `## Migrated from <old-key>` heading; merge only verbatim-identical lines.
+   - `branches/<slug>/*` — if the canonical tree has the same slug, append notes with a provenance heading; otherwise `mv` the whole branch slot into `branches/`.
+   - `worktrees/<name>/*` — same rule as branch slots.
+   - Never overwrite an existing file silently. Never delete a file.
+
+5. **Clean up** — remove candidate directories only if they are now empty (`rmdir -p --ignore-fail-on-non-empty`). Anything left behind is reported, not deleted.
+
+6. **Verify** — re-run the candidate scan (step 1): nothing non-canonical remains, or every remaining entry is accounted for with a reason. Run the `check` flow for the current repo and confirm it resolves to the canonical tree.
+
+## Rules
+
+- Provenance headings are mandatory — the user must be able to trace every merged block back to its original location.
+- `git mv` nothing: `~/.whisper/` is not a git repository. Plain `mv`/append only.
+- If two candidates map to the same canonical key (e.g. `charly-vibes/genesis` and `genesis/`), consolidate them sequentially and re-scan between rounds.

package/content/distilled/whisper/references/decommission.md

@@ -8,7 +8,8 @@ Safely wind down a worktree or branch: defer open work under the branch epic, re
 
 2. Get repo URL and branch slug:
    ```bash
-   repo_url=$(git remote get-url origin 2>/dev/null | sed 's|https://||;s|git@||;s|\.git$||')
+   repo_url=$(git remote get-url origin 2>/dev/null | sed 's|https://||;s|http://||;s|ssh://||;s|git@||;s|:|/|g;s|\.git$||')
+   [ -z "$repo_url" ] && repo_url="local/$(basename "$(git rev-parse --show-toplevel 2>/dev/null || pwd)")"
    branch=$(git rev-parse --abbrev-ref HEAD)
    branch_slug=$(echo "$branch" | sed 's|/|--|g')
    branch_dir=~/.whisper/repos/"${repo_url}"/branches/"${branch_slug}"

package/content/distilled/whisper/references/init.md

@@ -20,7 +20,8 @@ Create `~/.whisper/` and the current workspace slot.
 
 3. Compute the repo path and branch slug:
    ```bash
-   repo_url=$(git remote get-url origin 2>/dev/null | sed 's|https://||;s|git@||;s|\.git$||')
+   repo_url=$(git remote get-url origin 2>/dev/null | sed 's|https://||;s|http://||;s|ssh://||;s|git@||;s|:|/|g;s|\.git$||')
+   [ -z "$repo_url" ] && repo_url="local/$(basename "$(git rev-parse --show-toplevel 2>/dev/null || pwd)")"
    branch=$(git rev-parse --abbrev-ref HEAD)
    branch_slug=$(echo "$branch" | sed 's|/|--|g')
    ```

package/content/distilled/whisper/references/link.md

@@ -10,7 +10,8 @@ This mode is self-contained — it does NOT require `create-plan` to have been u
 
 2. Get repo URL and branch slug:
    ```bash
-   repo_url=$(git remote get-url origin 2>/dev/null | sed 's|https://||;s|git@||;s|\.git$||')
+   repo_url=$(git remote get-url origin 2>/dev/null | sed 's|https://||;s|http://||;s|ssh://||;s|git@||;s|:|/|g;s|\.git$||')
+   [ -z "$repo_url" ] && repo_url="local/$(basename "$(git rev-parse --show-toplevel 2>/dev/null || pwd)")"
    branch=$(git rev-parse --abbrev-ref HEAD)
    branch_slug=$(echo "$branch" | sed 's|/|--|g')
    branch_dir=~/.whisper/repos/"${repo_url}"/branches/"${branch_slug}"

package/content/distilled/whisper/references/status.md

@@ -6,7 +6,8 @@ Show the state of the current workspace.
 
 1. Get repo URL and branch slug:
    ```bash
-   repo_url=$(git remote get-url origin 2>/dev/null | sed 's|https://||;s|git@||;s|\.git$||')
+   repo_url=$(git remote get-url origin 2>/dev/null | sed 's|https://||;s|http://||;s|ssh://||;s|git@||;s|:|/|g;s|\.git$||')
+   [ -z "$repo_url" ] && repo_url="local/$(basename "$(git rev-parse --show-toplevel 2>/dev/null || pwd)")"
    branch=$(git rev-parse --abbrev-ref HEAD)
    branch_slug=$(echo "$branch" | sed 's|/|--|g')
    context_path=~/.whisper/repos/"${repo_url}"/branches/"${branch_slug}"/context.md

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "incitaciones",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "Reusable prompts and skills for CLI LLM tools, with native pi package support.",
   "repository": {
     "type": "git",

package/pi-package/skills/codebase-cartography/SKILL.md

@@ -37,11 +37,12 @@ Pick the entry level from the request:
 - Before gathering evidence for any map (and again before rendering), read `references/zoom-levels.md` — per-level evidence collection commands and text rendering formats.
 - Before any health check or when the user asks about "health", "smells", or refactoring targets, read `references/smell-signatures.md` — anti-pattern proxies, evidence requirements, severity ratings.
 - Before writing the final output, read `references/report-template.md` — output structure per mode.
-- When the user asks for an HTML export or a shareable version of the report, read the "Optional HTML Export" section at the end of `references/report-template.md`.
+- When the user asks for an HTML export or a shareable version of the report, read the "Optional HTML Export" section at the end of `references/report-template.md`; when the request spans multiple reports (batch), also read its "Batch export" section.
 
 ## Zoom Discipline
 
-- Offer adjacent levels as follow-ups; never dump all three maps unrequested.
+- Offer adjacent levels as follow-ups; never dump all three maps unrequested. An explicit batch request ("all reports", "map every module") is a user request — the offer-don't-dump rule applies to unprompted follow-ups only (batch procedure in `references/report-template.md`, "Batch export" section).
+- Re-verify every embedded count and fan-in/fan-out number against a fresh command run immediately before writing each report (one consolidated pass per batch is fine) — counts gathered early in a long session drift.
 - Every claim carries a file reference (`path`, or `path:line` for specific symbols).
 - State dependency direction explicitly (A → B); never "related to".
 - Distinguish observed evidence from inference; label inference explicitly.
@@ -54,4 +55,4 @@ Pick the entry level from the request:
 - Prefer structural facts over narrative: dependency direction, counts, boundaries.
 - Health-check findings follow the evidence format in `references/smell-signatures.md` (pattern, evidence, quantity, severity) — never unanchored opinions.
 - Maps are diff-able artifacts: tables and Mermaid, not prose walls.
-- HTML export is derived output, produced only on request; the markdown report remains the artifact of record.
+- HTML export is derived output, produced only on request; the markdown report remains the artifact of record. Exports live in `docs/cartography/` as a self-contained directory (index + shared assets); see the "Optional HTML Export" section of `references/report-template.md`.

package/pi-package/skills/codebase-cartography/references/report-template.md

@@ -60,16 +60,67 @@ One finding block per pattern (format in `smell-signatures.md`), ordered by seve
 
 **Adjacent levels offered** — one line each, e.g. "meso map of ledger available on request".
 
+## Batch export
+
+An explicit batch request ("generate all the reports", "map every module") is a user request — Zoom Discipline's offer-don't-dump rule applies to unprompted follow-ups only.
+
+- Enumerate targets from the module inventory. Confirm the list once when it exceeds 3 targets or the scope is ambiguous; proceed unless corrected.
+- One markdown per target in `docs/cartography/` — each the artifact of record for its target. For each, re-verify counts immediately before writing (Zoom Discipline).
+- Include a health report only if the batch request names health/smells.
+- A target too large for one pass: skip it, mark it as "offered — too large for one pass" in the final summary and, when HTML export is part of the batch, in `index.html`. Do not stop the batch to ask.
+- Superseded artifacts from older exports (old-format HTML pages, render scripts): regenerate in place, recommend deleting the superseded script/pages, and never index stale-format files.
+- When HTML export is part of the batch request or separately requested, HTML pages and `index.html` follow the Optional HTML Export section (regenerate the index once at the end, covering all reports).
+
 ## Optional HTML Export
 
-Produce only on request ("export as HTML", "shareable report"). The markdown report is the source of truth; the HTML file is a derived, regenerable view — never hand-edit it, regenerate it from the markdown.
+Produce only on request ("export as HTML", "shareable report"). The markdown report is the source of truth; the HTML files are a derived, regenerable view — never hand-edit them, regenerate them from the markdown.
+
+The export is a **self-contained directory**: all pages plus shared assets under one folder, opening correctly via `file://`, offline, with no server, CDN at view time, or build step. JavaScript is permitted only as a local vendored asset (see Diagrams).
+
+### Output directory
+
+- All exports live in `docs/cartography/` (create directories as needed). If `docs/` does not already exist in the repo, confirm once with the user before creating it.
+- Pages reference assets with relative paths (`assets/...`), never absolute or remote URLs.
+
+### Files
+
+- One page per report: `cartography-<level>-<target>.html` (e.g. `cartography-meso-payments-billing.html`; slugify the target with hyphens, no dots or spaces). The zoom level in the name prevents exports of different levels overwriting each other. Re-exporting the same level+target overwrites the previous file — intended; there is no history.
+- `index.html` — regenerated on every export; never hand-maintained.
+- `assets/mermaid.min.js` — vendored Mermaid v9.4.3 IIFE build, shared by all pages.
+
+### Index
+
+Regenerate `index.html` on every export from what is on disk plus what is known this session:
+
+- Scan `docs/cartography/*.html` (excluding `index.html`), group entries by zoom level (macro / meso / micro / health), sorted alphabetically.
+- Each entry links to the page and shows its target plus a one-line scope taken from the report header.
+- Also list markdown reports known to this session (the artifact of record), linked with a repo-relative path from the HTML location. Do not invent paths for reports you cannot locate.
+- The template must handle N=1 (a single entry) without looking broken.
+- Deterministic: sorted, no timestamps, no generator metadata.
+
+### Navigation
+
+- Every page (including `index.html`) has a plain nav header: `← Index` plus links to parent-context and adjacent-level pages when they exist (meso → its macro page; micro → its macro/meso parent). Relative links only.
+- Static links only — no interactivity. Do not evolve the export into an application — no servers, frameworks, or interactive controls. If live interaction is requested, note it is out of scope for this skill.
+
+### Diagrams
+
+- Render Mermaid client-side with the vendored local asset: `<script src="assets/mermaid.min.js"></script>` plus `<pre class="mermaid">` blocks. Use only the v9.x IIFE build (global `mermaid`); v10+ is ESM-only and is blocked by CORS under `file://`.
+- Asset acquisition: on the first export, download `mermaid.min.js` v9.4.3 into `assets/` if absent (e.g. from jsDelivr); reuse thereafter. If the download fails (offline machine), still emit all pages — diagrams degrade to their source in a styled `<pre>` and the report footer notes "diagrams show source; rerun the export with network access to enable rendering". Never fail the whole export because of assets.
+- Every diagram keeps its Mermaid source in `<details><pre class="mermaid-source">` as the no-JS fallback, so nothing is ever blank.
+- Prose stays pre-rendered HTML — do not client-render markdown. The markdown report remains the artifact of record.
+
+### Handoff
+
+- Final step of any export (including the first): tell the user to open `docs/cartography/index.html` directly in a browser — `file://` works with no server; diagram rendering is guaranteed by the Diagrams section.
+- Never start a server for static reports unless the user explicitly asks.
 
-Produce ONE self-contained file, `cartography-<level>-<target>.html` (e.g. `cartography-meso-payments-billing.html`; slugify the target with hyphens), next to the markdown report — or, if no report file was written this session, ask the user where to save it (default `docs/`). The zoom level in the name prevents exports of different levels overwriting each other.
+### Invariants
 
-- **Self-contained:** one inline `<style>` block. No CDN, no external CSS/JS/fonts, no build step, no server. Must open correctly offline.
-- **No JavaScript:** diagrams render as styled `<pre>` blocks (text diagrams) or inline SVG producible without new dependencies. Keep the Mermaid source in the file (e.g. `<pre class="mermaid-source">`) so the diagram stays manipulable.
+- **Write HTML directly:** no render scripts, build pipelines, or new dependencies (pandoc etc.) — even in batch mode. The regeneration path is re-running this skill, not a committed pipeline; exception only on explicit user request (note the dependency caveat in the reply).
 - **Mirror, don't redesign:** same sections, same order, same content as the markdown report. The HTML adds presentation only (readable typography; `prefers-color-scheme` support optional).
 - **Deterministic:** stable section order, no timestamps, no generator metadata.
 - **Size guard:** render large reports as-is; never paginate, collapse, or add interactivity.
+- **Commit-able:** reports and `assets/` are self-contained and offline-safe; suggest committing them, never silently gitignore.
 
-Do not evolve the export into an application — no servers, frameworks, or interactive controls. If live interaction is requested, note it is out of scope for this skill.
+Decision record: diagrams use a vendored local Mermaid v9.4.3 IIFE; prose is pre-rendered. Rationale: offline rendering, `file://` compatibility, no ESM/CORS issues. Render scripts and build pipelines are banned because agent-regeneration keeps the navigation/diagram/index guarantees that build scripts historically dropped (wai cartography batch, 2026-09-01: a pandoc pipeline produced 12 pages with zero cross-links and unrendered diagrams).

package/pi-package/skills/whisper/SKILL.md

@@ -38,6 +38,17 @@ Manage `~/.whisper/` — a global, tiered knowledge directory that accumulates o
 
 **Worktree slot rule:** `basename $(git rev-parse --git-common-dir 2>/dev/null)` (the `.git` worktree dir name), or `basename $(pwd)` when not in a worktree.
 
+**Canonical repo key rule — derive it, never invent it:**
+
+```bash
+repo_url=$(git remote get-url origin 2>/dev/null | sed 's|https://||;s|http://||;s|ssh://||;s|git@||;s|:|/|g;s|\.git$||')
+[ -z "$repo_url" ] && repo_url="local/$(basename "$(git rev-parse --show-toplevel 2>/dev/null || pwd)")"
+```
+
+`git@cv:org/repo.git` → `cv/org/repo`; `https://github.com/u/r` → `github.com/u/r`; no remote → `local/<repo-name>`. Colons always become slashes (keeps keys path-safe). The same key must come out of the same repo on every machine.
+
+If a directory keyed some other way already exists for this repo (bare name like `genesis/`, owner-only like `charly-vibes/`, alias host with a colon like `cv:charly-vibes/`), do **not** add a fourth variant — route new knowledge into the canonical key and offer `/w consolidate` to migrate the legacy one.
+
 ## Knowledge Routing
 
 When a session learns something worth keeping, route it by scope:
@@ -53,6 +64,7 @@ When a session learns something worth keeping, route it by scope:
 **Rules:**
 - **No secrets anywhere.** Never write tokens, keys, passwords, or PII into `~/.whisper/`.
 - **Extend, don't duplicate.** Append to or correct an existing note rather than creating a new one that says the same thing.
+- **One repo, one key.** If more than one `repos/` directory belongs to the same repo, write into the canonical key and propose `/w consolidate` — never create a new variant.
 - **Search first.** Before creating a new entry, check if one already exists for the same topic.
 - If `bd` is not available, everything falls back to `~/.whisper/` files — there's no beads-backed alternative.
 
@@ -67,6 +79,7 @@ Determine mode from how the skill is triggered:
 | `/w check` or called by `renew` | **check** |
 | `/w link [<path>]` or "link plan" | **link** |
 | `/w decommission` | **decommission** |
+| `/w consolidate` or "dedupe whisper repos" | **consolidate** |
 
 See each reference file for the full procedure:
 
@@ -75,6 +88,7 @@ See each reference file for the full procedure:
 - `references/status.md`
 - `references/link.md`
 - `references/decommission.md`
+- `references/consolidate.md`
 
 ## Rules
 

package/pi-package/skills/whisper/references/check.md

@@ -6,7 +6,8 @@ Validate the workspace before starting work. Detects stale branch slots and work
 
 1. Get repo URL and branch slug:
    ```bash
-   repo_url=$(git remote get-url origin 2>/dev/null | sed 's|https://||;s|git@||;s|\.git$||')
+   repo_url=$(git remote get-url origin 2>/dev/null | sed 's|https://||;s|http://||;s|ssh://||;s|git@||;s|:|/|g;s|\.git$||')
+   [ -z "$repo_url" ] && repo_url="local/$(basename "$(git rev-parse --show-toplevel 2>/dev/null || pwd)")"
    branch=$(git rev-parse --abbrev-ref HEAD)
    branch_slug=$(echo "$branch" | sed 's|/|--|g')
    context_path=~/.whisper/repos/"${repo_url}"/branches/"${branch_slug}"/context.md

package/pi-package/skills/whisper/references/consolidate.md

@@ -0,0 +1,41 @@
+# Consolidate
+
+Merge duplicate `~/.whisper/repos/` directories for the same repo into the single canonical key. One repo, one key.
+
+## Why
+
+Older sessions keyed repos inconsistently — bare repo name (`genesis/`), owner dir (`charly-vibes/`), ssh-alias host with a colon (`cv:charly-vibes/`), full URL in the wrong shape. The same repo's knowledge ends up scattered across several trees, so `check` and `status` miss notes that exist. Consolidation restores the invariant; the canonical key derivation is defined in SKILL.md.
+
+## Steps
+
+1. **Inventory candidates** — non-canonical top-level entries. Canonical = at least 2 slashes and no colon in the first segment; also flag alias-host dirs (`<alias>:<owner>`):
+
+   ```bash
+   for d in ~/.whisper/repos/*/; do echo "${d#$HOME/.whisper/repos/}"; done
+   ```
+   A key is a candidate if it has 0 or 1 slashes, or contains `:`.
+
+2. **Derive the canonical target per candidate** — check the actual repo's remote:
+
+   ```bash
+   cd <repo checkout> && git remote get-url origin | sed 's|https://||;s|http://||;s|ssh://||;s|git@||;s|:|/|g;s|\.git$||'
+   ```
+   If no checkout is reachable for a candidate, leave it in place and report it — never guess the mapping from the name alone.
+
+3. **Produce a migration table and WAIT for approval** — one row per candidate: old key → canonical key, files found, merge conflicts detected. The user must explicitly approve before anything moves. If running non-interactively, output the plan and stop.
+
+4. **Merge per file on approval:**
+   - `env.md` — append the candidate's content under a `## Migrated from <old-key>` heading; merge only verbatim-identical lines.
+   - `branches/<slug>/*` — if the canonical tree has the same slug, append notes with a provenance heading; otherwise `mv` the whole branch slot into `branches/`.
+   - `worktrees/<name>/*` — same rule as branch slots.
+   - Never overwrite an existing file silently. Never delete a file.
+
+5. **Clean up** — remove candidate directories only if they are now empty (`rmdir -p --ignore-fail-on-non-empty`). Anything left behind is reported, not deleted.
+
+6. **Verify** — re-run the candidate scan (step 1): nothing non-canonical remains, or every remaining entry is accounted for with a reason. Run the `check` flow for the current repo and confirm it resolves to the canonical tree.
+
+## Rules
+
+- Provenance headings are mandatory — the user must be able to trace every merged block back to its original location.
+- `git mv` nothing: `~/.whisper/` is not a git repository. Plain `mv`/append only.
+- If two candidates map to the same canonical key (e.g. `charly-vibes/genesis` and `genesis/`), consolidate them sequentially and re-scan between rounds.

package/pi-package/skills/whisper/references/decommission.md

@@ -8,7 +8,8 @@ Safely wind down a worktree or branch: defer open work under the branch epic, re
 
 2. Get repo URL and branch slug:
    ```bash
-   repo_url=$(git remote get-url origin 2>/dev/null | sed 's|https://||;s|git@||;s|\.git$||')
+   repo_url=$(git remote get-url origin 2>/dev/null | sed 's|https://||;s|http://||;s|ssh://||;s|git@||;s|:|/|g;s|\.git$||')
+   [ -z "$repo_url" ] && repo_url="local/$(basename "$(git rev-parse --show-toplevel 2>/dev/null || pwd)")"
    branch=$(git rev-parse --abbrev-ref HEAD)
    branch_slug=$(echo "$branch" | sed 's|/|--|g')
    branch_dir=~/.whisper/repos/"${repo_url}"/branches/"${branch_slug}"

package/pi-package/skills/whisper/references/init.md

@@ -20,7 +20,8 @@ Create `~/.whisper/` and the current workspace slot.
 
 3. Compute the repo path and branch slug:
    ```bash
-   repo_url=$(git remote get-url origin 2>/dev/null | sed 's|https://||;s|git@||;s|\.git$||')
+   repo_url=$(git remote get-url origin 2>/dev/null | sed 's|https://||;s|http://||;s|ssh://||;s|git@||;s|:|/|g;s|\.git$||')
+   [ -z "$repo_url" ] && repo_url="local/$(basename "$(git rev-parse --show-toplevel 2>/dev/null || pwd)")"
    branch=$(git rev-parse --abbrev-ref HEAD)
    branch_slug=$(echo "$branch" | sed 's|/|--|g')
    ```

package/pi-package/skills/whisper/references/link.md

@@ -10,7 +10,8 @@ This mode is self-contained — it does NOT require `create-plan` to have been u
 
 2. Get repo URL and branch slug:
    ```bash
-   repo_url=$(git remote get-url origin 2>/dev/null | sed 's|https://||;s|git@||;s|\.git$||')
+   repo_url=$(git remote get-url origin 2>/dev/null | sed 's|https://||;s|http://||;s|ssh://||;s|git@||;s|:|/|g;s|\.git$||')
+   [ -z "$repo_url" ] && repo_url="local/$(basename "$(git rev-parse --show-toplevel 2>/dev/null || pwd)")"
    branch=$(git rev-parse --abbrev-ref HEAD)
    branch_slug=$(echo "$branch" | sed 's|/|--|g')
    branch_dir=~/.whisper/repos/"${repo_url}"/branches/"${branch_slug}"

package/pi-package/skills/whisper/references/status.md

@@ -6,7 +6,8 @@ Show the state of the current workspace.
 
 1. Get repo URL and branch slug:
    ```bash
-   repo_url=$(git remote get-url origin 2>/dev/null | sed 's|https://||;s|git@||;s|\.git$||')
+   repo_url=$(git remote get-url origin 2>/dev/null | sed 's|https://||;s|http://||;s|ssh://||;s|git@||;s|:|/|g;s|\.git$||')
+   [ -z "$repo_url" ] && repo_url="local/$(basename "$(git rev-parse --show-toplevel 2>/dev/null || pwd)")"
    branch=$(git rev-parse --abbrev-ref HEAD)
    branch_slug=$(echo "$branch" | sed 's|/|--|g')
    context_path=~/.whisper/repos/"${repo_url}"/branches/"${branch_slug}"/context.md