feat: add proof-backed excalidraw exports

Author: baboonzero

.gitignore

@@ -4,11 +4,14 @@ __pycache__/
 
 # Skill local outputs
 .out*/
+.audit_tmp/
 code-explainer-output/
 code-explainer/.out*/
 code-explainer/.out-gh/
 code-explainer/.ci-out/
+code-explainer/.audit_tmp/
 code-explainer/code-explainer-output/
+code-explainer/node_modules/
 
 # OS/editor
 .DS_Store

PUBLISHING.md

@@ -6,8 +6,7 @@ From repository root:
 
 ```bash
 git add .
-git commit -m "feat: rebuild code-explainer around grounded explanation quality"
-git remote add origin https://github.com/<your-org-or-user>/code-explainer.git
+git commit -m "feat: add proof-backed Excalidraw exports"
 git push -u origin main
 ```
 
@@ -16,12 +15,14 @@ git push -u origin main
 1. The repo-level docs match the shipped skill contract.
 2. `code-explainer/SKILL.md` reflects the current pipeline and proof path.
 3. `python code-explainer/scripts/self_audit.py` passes.
-4. `install_to_codex.ps1` installs the current package cleanly.
+4. `install_to_codex.ps1` copies the current package cleanly, including `package.json` and `package-lock.json`.
+5. `meta/excalidraw_report.json` is part of the output contract and the self-audit proves editable scene generation.
 
 Recommended:
 
 ```bash
 cd code-explainer
+pwsh ./scripts/install_runtime.ps1
 python scripts/self_audit.py
 ```
 
@@ -49,11 +50,13 @@ Users need:
 - Node.js `18+` and npm
 - Git
 
-Recommended for full diagram rendering:
+Recommended for higher-fidelity diagram rendering:
 
 - Mermaid CLI (`@mermaid-js/mermaid-cli`)
 
-Even without live LLM access, the proof path still works through `CODE_EXPLAINER_MOCK_LLM=true`.
+The repo also ships a local Excalidraw bridge dependency through `package.json`.
+
+Even without live LLM access, the proof path still works through `CODE_EXPLAINER_MOCK_LLM=true`. Even if the official Excalidraw bridge is browser-dependent in the local environment, the shipped deterministic fallback scene generator keeps the editable-diagram proof path working and records the downgrade in `meta/excalidraw_report.json`.
 
 ## GitHub Distribution
 
@@ -82,11 +85,13 @@ Suggested GitHub topics:
 - `codebase-analysis`
 - `onboarding`
 - `mermaid`
+- `excalidraw`
 - `developer-tools`
 
 Useful publishing assets:
 
 1. A short README section showing `overview/OVERVIEW.md`
-2. One example diagram image
+2. One example Mermaid diagram and one example Excalidraw scene screenshot
 3. The self-audit result summary
-4. A release note that explains the rebuild from generic output to proof-backed output
+4. The latest `audit-skill` report
+5. A release note that explains the shift from generic output to proof-backed explanation plus editable diagrams

README.md

@@ -1,6 +1,6 @@
 # code-explainer
 
-`code-explainer` is a Codex skill for explaining a local repository or GitHub repository in simple, concrete language. The rebuilt version is explanation-first: it creates a grounded narrative plan, generates onboarding docs and focused diagrams from that plan, and scores the output for clarity, specificity, grounding, usefulness, and honesty.
+`code-explainer` is a Codex skill for turning a local repository or GitHub repository URL into grounded onboarding material. It is explanation-first: it builds a narrative plan from real repo evidence, generates docs and diagrams from that plan, and proves output quality with a shipped self-audit.
 
 ## What It Produces
 
@@ -15,6 +15,9 @@ A standard run writes:
 - `diagrams/*.mmd`
 - `diagrams/svg/*.svg`
 - `diagrams/png/*.png`
+- `diagrams/excalidraw/*.excalidraw.json`
+- `diagrams/excalidraw/svg/*.svg`
+- `diagrams/excalidraw/png/*.png`
 - `meta/*.json`
 
 Important proof artifacts:
@@ -23,22 +26,27 @@ Important proof artifacts:
 - `meta/explanation_quality.json`
 - `meta/verification_checkpoint.json`
 - `meta/fact_check_report.json`
+- `meta/excalidraw_report.json`
 - `meta/quality_report.json`
 
 ## Why This Version Is Better
 
-The older build overpromised and produced generic output. This rebuild changes the contract:
+The older build looked polished but produced weak output. The current contract is stricter:
 
-- the explanation is planned before docs are written
-- diagrams are tied to onboarding questions
-- the quality gate can fail generic or weakly grounded output
-- the repo ships fixture repos plus a self-audit path
+- explanation planning happens before doc generation
+- every diagram has an onboarding purpose
+- Mermaid is the canonical diagram source
+- editable Excalidraw scenes are generated from the same diagram set
+- quality gates fail generic, weakly grounded, or incomplete output
+- the repo ships fixture repos and a self-audit path
 
 ## Repository Layout
 
 ```text
 code-explainer/
   SKILL.md
+  package.json
+  package-lock.json
   agents/openai.yaml
   assets/
     fixtures/
@@ -50,7 +58,7 @@ PUBLISHING.md
 install_to_codex.ps1
 ```
 
-## Install Runtime Dependencies
+## Runtime Dependencies
 
 Required:
 
@@ -62,6 +70,10 @@ Recommended:
 
 - Mermaid CLI (`mmdc`) from `@mermaid-js/mermaid-cli`
 
+Installed locally by the skill runtime:
+
+- `@excalidraw/mermaid-to-excalidraw`
+
 Windows:
 
 ```powershell
@@ -82,7 +94,7 @@ From this repository root:
 powershell -ExecutionPolicy Bypass -File .\install_to_codex.ps1
 ```
 
-This copies the skill into `~/.codex/skills/code-explainer`. Restart Codex after installation.
+This copies the current skill package into `~/.codex/skills/code-explainer`. Restart Codex after installation, then run the skill runtime installer inside the installed copy if you need the local Node dependencies there.
 
 ## Run
 
@@ -97,6 +109,7 @@ python scripts/analyze.py analyze \
   --audience nontech \
   --overview-length medium \
   --enable-llm-descriptions true \
+  --enable-excalidraw-export true \
   --ask-before-llm-use false \
   --prompt-for-llm-key false \
   --enable-web-enrichment false
@@ -110,6 +123,14 @@ Useful controls:
 - `--mode quick|standard|deep`
 - `--explainer-type onboarding|project-recap|plan-review|diff-review`
 - `--audience nontech|mixed|engineering`
+- `--enable-excalidraw-export true|false`
+
+## Diagram and Excalidraw Behavior
+
+- Mermaid remains the canonical source of truth.
+- The skill exports editable Excalidraw scenes from that Mermaid set.
+- If the official Excalidraw bridge works in the local runtime, it is used directly.
+- If the official bridge is browser-dependent or unavailable, the skill falls back to a deterministic local scene generator for the Mermaid subset it emits and records that downgrade in `meta/excalidraw_report.json`.
 
 ## LLM Behavior
 
@@ -132,7 +153,12 @@ This runs the skill against fixture repositories in `assets/fixtures/` and write
 
 ## Current Status
 
-The rebuilt skill audited at `97.1/100` and is currently `production-grade` under the local `audit-skill` rubric.
+The current build audits at `98.8/100` and is `production-grade` under the local `audit-skill` rubric. The self-audit currently proves:
+
+- `2` fixture repositories
+- `5` diagrams per fixture
+- `5` Excalidraw scenes per fixture
+- `97.1` explanation-quality score per fixture
 
 ## Publishing
 

code-explainer/SKILL.md

@@ -24,9 +24,11 @@ This skill should fail quality gates if the output is generic, vague, or weakly
 1. `overview/OVERVIEW.md` for the plain-language explanation.
 2. `deep/*.md` for architecture, modules, flows, dependencies, and glossary.
 3. `diagrams/*.mmd` plus rendered `diagrams/svg/*.svg` and `diagrams/png/*.png`.
-4. `meta/explanation_plan.json` describing the intended narrative.
-5. `meta/explanation_quality.json` scoring clarity, specificity, grounding, usefulness, diagram usefulness, and honesty.
-6. `meta/*.json` for indexing, verification, confidence, attribution, and quality reports.
+4. `diagrams/excalidraw/*.excalidraw.json` plus mirrored preview assets under `diagrams/excalidraw/svg/*.svg` and `diagrams/excalidraw/png/*.png`.
+5. `meta/explanation_plan.json` describing the intended narrative.
+6. `meta/explanation_quality.json` scoring clarity, specificity, grounding, usefulness, diagram usefulness, and honesty.
+7. `meta/excalidraw_report.json` proving whether editable Excalidraw scenes were created or why that export was blocked.
+8. `meta/*.json` for indexing, verification, confidence, attribution, and quality reports.
 
 See `references/output-contract.md` for exact artifacts and `references/evaluation-rubric.md` for the passing bar.
 
@@ -49,6 +51,7 @@ python scripts/analyze.py analyze \
   --include-glob <pattern> \
   --exclude-glob <pattern> \
   --enable-llm-descriptions <true|false> \
+  --enable-excalidraw-export <true|false> \
   --ask-before-llm-use <true|false> \
   --prompt-for-llm-key <true|false> \
   --enable-web-enrichment <true|false>
@@ -62,6 +65,7 @@ Defaults:
 - `audience=nontech`
 - `overview-length=medium`
 - `enable-llm-descriptions=true`
+- `enable-excalidraw-export=true`
 - `ask-before-llm-use=false`
 - `prompt-for-llm-key=false`
 - `enable-web-enrichment=true`
@@ -80,9 +84,10 @@ Defaults:
 3. Build `explanation_plan.json` with top modules, audience starting points, diagram purposes, and caveats.
 4. Generate the narrative layer with LLM or grounded mock/deterministic fallback.
 5. Build focused diagrams tied to onboarding questions.
-6. Generate overview and deep docs from the explanation plan plus narrative layer.
-7. Run fact-check and explanation-quality evaluation.
-8. Fail the run if quality gates do not clear the rubric.
+6. Export those diagrams into editable Excalidraw scenes when the local runtime is installed.
+7. Generate overview and deep docs from the explanation plan plus narrative layer.
+8. Run fact-check and explanation-quality evaluation.
+9. Fail the run if quality gates do not clear the rubric.
 
 ## Proof Path
 
@@ -105,6 +110,7 @@ Required:
 Recommended:
 
 - Mermaid CLI (`mmdc`) from `@mermaid-js/mermaid-cli` for higher-fidelity diagram rendering
+- `@excalidraw/mermaid-to-excalidraw` installed locally via `npm install` for editable Excalidraw scene export
 
 Install dependencies:
 
@@ -122,6 +128,8 @@ bash ./scripts/install_runtime.sh
 
 - This skill does not mutate the analyzed repository.
 - If the explanation-quality score is below the rubric threshold, treat the output as failed even if files were produced.
+- If Excalidraw export is enabled, treat missing or partial editable scene generation as a real quality issue, not a cosmetic extra.
+- When the official Excalidraw bridge is unavailable or browser-dependent in the local runtime, the skill falls back to a deterministic local scene generator for the Mermaid subset it emits and records that downgrade in `meta/excalidraw_report.json`.
 - Use include/exclude globs to narrow analysis when the repository is very large or noisy.
 
 ## References