incitaciones 0.7.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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "incitaciones",
-  "version": "0.7.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).