docs: default to deterministic excalidraw exporter

Author: baboonzero

PUBLISHING.md

@@ -15,7 +15,7 @@ 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` copies the current package cleanly, including `package.json` and `package-lock.json`.
+4. `install_to_codex.ps1` copies the current package cleanly.
 5. `meta/excalidraw_report.json` is part of the output contract and the self-audit proves editable scene generation.
 
 Recommended:
@@ -54,9 +54,7 @@ Recommended for higher-fidelity diagram rendering:
 
 - Mermaid CLI (`@mermaid-js/mermaid-cli`)
 
-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`.
+Even without live LLM access, the proof path still works through `CODE_EXPLAINER_MOCK_LLM=true`. The deterministic Excalidraw scene generator is now the default production path, so the repo does not need to ship the official bridge dependency in its default install surface. If a developer wants to experiment with the official bridge anyway, they can install it locally with `npm install --no-save @excalidraw/mermaid-to-excalidraw` and enable `--enable-official-excalidraw-bridge true`.
 
 ## GitHub Distribution
 

README.md

@@ -45,8 +45,6 @@ The older build looked polished but produced weak output. The current contract i
 ```text
 code-explainer/
   SKILL.md
-  package.json
-  package-lock.json
   agents/openai.yaml
   assets/
     fixtures/
@@ -70,10 +68,6 @@ Recommended:
 
 - Mermaid CLI (`mmdc`) from `@mermaid-js/mermaid-cli`
 
-Installed locally by the skill runtime:
-
-- `@excalidraw/mermaid-to-excalidraw`
-
 Windows:
 
 ```powershell
@@ -94,7 +88,7 @@ From this repository root:
 powershell -ExecutionPolicy Bypass -File .\install_to_codex.ps1
 ```
 
-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.
+This copies the current skill package into `~/.codex/skills/code-explainer`. Restart Codex after installation.
 
 ## Run
 
@@ -110,6 +104,7 @@ python scripts/analyze.py analyze \
   --overview-length medium \
   --enable-llm-descriptions true \
   --enable-excalidraw-export true \
+  --enable-official-excalidraw-bridge false \
   --ask-before-llm-use false \
   --prompt-for-llm-key false \
   --enable-web-enrichment false
@@ -124,13 +119,14 @@ Useful controls:
 - `--explainer-type onboarding|project-recap|plan-review|diff-review`
 - `--audience nontech|mixed|engineering`
 - `--enable-excalidraw-export true|false`
+- `--enable-official-excalidraw-bridge 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`.
+- The deterministic local scene generator is the default production path.
+- The official Excalidraw bridge is opt-in only through `--enable-official-excalidraw-bridge true` and is intended for development experiments, not the default runtime.
 
 ## LLM Behavior
 

code-explainer/SKILL.md

@@ -52,6 +52,7 @@ python scripts/analyze.py analyze \
   --exclude-glob <pattern> \
   --enable-llm-descriptions <true|false> \
   --enable-excalidraw-export <true|false> \
+  --enable-official-excalidraw-bridge <true|false> \
   --ask-before-llm-use <true|false> \
   --prompt-for-llm-key <true|false> \
   --enable-web-enrichment <true|false>
@@ -66,6 +67,7 @@ Defaults:
 - `overview-length=medium`
 - `enable-llm-descriptions=true`
 - `enable-excalidraw-export=true`
+- `enable-official-excalidraw-bridge=false`
 - `ask-before-llm-use=false`
 - `prompt-for-llm-key=false`
 - `enable-web-enrichment=true`
@@ -84,10 +86,11 @@ 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. 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.
+6. Export those diagrams into editable Excalidraw scenes through the deterministic local exporter.
+7. Optionally prefer the official Excalidraw bridge only when explicitly enabled for development experiments.
+8. Generate overview and deep docs from the explanation plan plus narrative layer.
+9. Run fact-check and explanation-quality evaluation.
+10. Fail the run if quality gates do not clear the rubric.
 
 ## Proof Path
 
@@ -110,7 +113,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
+- Node.js is only required for GitHub cloning and optional development-time Excalidraw bridge experiments
 
 Install dependencies:
 
@@ -129,7 +132,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`.
+- The deterministic local Excalidraw exporter is the canonical production path.
+- The official `@excalidraw/mermaid-to-excalidraw` bridge is opt-in only via `--enable-official-excalidraw-bridge true` and should be treated as a development experiment, not a required runtime dependency.
 - Use include/exclude globs to narrow analysis when the repository is very large or noisy.
 
 ## References

code-explainer/references/diagram-style-guide.md

@@ -7,6 +7,7 @@
 3. Keep labels short and plain-language-first for non-technical readers.
 4. Split diagrams when readability is degraded by scale.
 5. Mermaid remains the canonical source; Excalidraw exports are editable derivatives of those same diagrams.
+6. The deterministic local Excalidraw exporter is the default production path; the official bridge is optional and development-only.
 
 ## Standard Mode Diagram Set
 

code-explainer/references/output-contract.md

@@ -70,6 +70,8 @@
 - `excalidraw_export_requested`
 - `excalidraw_export_status`
 - `excalidraw_scene_count`
+- `official_excalidraw_bridge_requested`
+- `official_excalidraw_bridge_used`
 - `html_generated`
 
 ## Coverage Schema
@@ -185,6 +187,8 @@
 - `environment_blocked`
 - `scene_count`
 - `failed_count`
+- `official_bridge_requested`
+- `official_bridge_used`
 - `warnings[]`
 - `runtime`
 - `results[]` where each result has:

code-explainer/scripts/analyze.py

@@ -127,6 +127,8 @@ def _write_manifest(
         "excalidraw_export_requested": excalidraw_payload.get("requested", False),
         "excalidraw_export_status": excalidraw_payload.get("status", "disabled"),
         "excalidraw_scene_count": excalidraw_payload.get("scene_count", 0),
+        "official_excalidraw_bridge_requested": excalidraw_payload.get("official_bridge_requested", False),
+        "official_excalidraw_bridge_used": excalidraw_payload.get("official_bridge_used", 0),
         "html_generated": bool(html_payload.get("output_file")),
         "module_count": module_count,
         "diagram_count": diagram_count,
@@ -147,6 +149,7 @@ def run_pipeline(
     enable_web_enrichment: bool,
     enable_llm_descriptions: bool,
     enable_excalidraw_export: bool,
+    enable_official_excalidraw_bridge: bool = False,
     ask_before_llm_use: bool = False,
     prompt_for_llm_key: bool = False,
     include_globs: List[str] | None = None,
@@ -255,6 +258,7 @@ def run_pipeline(
             rendered_diagrams_dir=output_root / "diagrams",
             meta_dir=meta_dir,
             enabled=enable_excalidraw_export,
+            prefer_official_bridge=enable_official_excalidraw_bridge,
         )
 
         docs_gen_payload = generate_docs.generate_docs(
@@ -356,6 +360,7 @@ def run_pipeline(
             "renderer": render_payload.get("renderer", ""),
             "excalidraw_status": excalidraw_payload.get("status", "disabled"),
             "excalidraw_scene_count": excalidraw_payload.get("scene_count", 0),
+            "official_excalidraw_bridge_used": excalidraw_payload.get("official_bridge_used", 0),
             "html_generated": bool(html_payload.get("output_file")),
             "fact_check_passed": fact_check_payload.get("passed", False),
             "quality_passed": quality_payload.get("passed", False),
@@ -399,6 +404,7 @@ def _parse_args() -> argparse.Namespace:
     parser.add_argument("--enable-web-enrichment", default="true")
     parser.add_argument("--enable-llm-descriptions", default="true")
     parser.add_argument("--enable-excalidraw-export", default="true")
+    parser.add_argument("--enable-official-excalidraw-bridge", default="false")
     parser.add_argument("--ask-before-llm-use", default="false")
     parser.add_argument("--prompt-for-llm-key", default="false")
     return parser.parse_args()
@@ -414,6 +420,7 @@ def main() -> int:
     web_enabled = common.bool_from_string(args.enable_web_enrichment)
     llm_enabled = common.bool_from_string(args.enable_llm_descriptions)
     excalidraw_enabled = common.bool_from_string(args.enable_excalidraw_export)
+    official_excalidraw_bridge_enabled = common.bool_from_string(args.enable_official_excalidraw_bridge)
     ask_before_llm_use = common.bool_from_string(args.ask_before_llm_use)
     prompt_for_llm_key = common.bool_from_string(args.prompt_for_llm_key)
     summary = run_pipeline(
@@ -427,6 +434,7 @@ def main() -> int:
         enable_web_enrichment=web_enabled,
         enable_llm_descriptions=llm_enabled,
         enable_excalidraw_export=excalidraw_enabled,
+        enable_official_excalidraw_bridge=official_excalidraw_bridge_enabled,
         ask_before_llm_use=ask_before_llm_use,
         prompt_for_llm_key=prompt_for_llm_key,
         include_globs=args.include_glob,
@@ -453,6 +461,7 @@ def main() -> int:
         "renderer",
         "excalidraw_status",
         "excalidraw_scene_count",
+        "official_excalidraw_bridge_used",
         "html_generated",
         "fact_check_passed",
         "quality_passed",

code-explainer/scripts/export_excalidraw.py

@@ -31,17 +31,14 @@ def _runtime_status() -> Dict[str, Any]:
     node = common.which("node")
     bridge = SCRIPT_DIR / "mermaid_to_excalidraw.mjs"
     package_dir = SKILL_DIR / "node_modules" / "@excalidraw" / "mermaid-to-excalidraw"
-    package_json = SKILL_DIR / "package.json"
 
     issues: List[str] = []
     if not node:
         issues.append("Node.js was not found on PATH.")
     if not bridge.exists():
         issues.append("The Mermaid-to-Excalidraw bridge script is missing.")
-    if not package_json.exists():
-        issues.append("package.json is missing from the skill runtime.")
     if not package_dir.exists():
-        issues.append("The @excalidraw/mermaid-to-excalidraw package is not installed.")
+        issues.append("The @excalidraw/mermaid-to-excalidraw package is not installed in this skill directory.")
 
     return {
         "ok": len(issues) == 0,
@@ -352,6 +349,7 @@ def export_excalidraw(
     rendered_diagrams_dir: Path,
     meta_dir: Path,
     enabled: bool = True,
+    prefer_official_bridge: bool = False,
 ) -> Dict[str, Any]:
     scene_dir = common.ensure_dir(rendered_diagrams_dir / "excalidraw")
     svg_dir = common.ensure_dir(scene_dir / "svg")
@@ -366,16 +364,29 @@ def export_excalidraw(
             "environment_blocked": False,
             "scene_count": 0,
             "failed_count": 0,
+            "official_bridge_requested": False,
+            "official_bridge_used": 0,
             "results": [],
             "warnings": ["Excalidraw export disabled by caller."],
         }
         common.write_json(report_path, payload)
         return payload
 
-    runtime = _runtime_status()
+    runtime = (
+        _runtime_status()
+        if prefer_official_bridge
+        else {
+            "ok": False,
+            "node": "",
+            "bridge": (SCRIPT_DIR / "mermaid_to_excalidraw.mjs").as_posix(),
+            "package_dir": (SKILL_DIR / "node_modules" / "@excalidraw" / "mermaid-to-excalidraw").as_posix(),
+            "issues": [],
+        }
+    )
     results: List[Dict[str, Any]] = []
     scene_count = 0
     failed_count = 0
+    bridge_used_count = 0
     renderer_svg_dir = rendered_diagrams_dir / "svg"
     renderer_png_dir = rendered_diagrams_dir / "png"
 
@@ -401,7 +412,7 @@ def export_excalidraw(
         }
 
         bridge_error = ""
-        if runtime["ok"]:
+        if prefer_official_bridge and runtime["ok"]:
             code, stdout, stderr = common.run_cmd(
                 [
                     runtime["node"],
@@ -420,6 +431,7 @@ def export_excalidraw(
                 payload = common.read_json(scene_path, default={})
                 entry["status"] = "ok"
                 entry["exporter"] = "official-bridge"
+                bridge_used_count += 1
                 entry["element_count"] = len(payload.get("elements", []))
                 entry["file_count"] = len(payload.get("files", {}))
                 if stdout.strip():
@@ -443,7 +455,7 @@ def export_excalidraw(
                 entry["file_count"] = len(fallback.get("files", {}))
                 if bridge_error:
                     entry["warnings"].append(bridge_error)
-                if not runtime["ok"]:
+                if prefer_official_bridge and not runtime["ok"]:
                     entry["warnings"].extend(runtime["issues"])
             except Exception as exc:
                 failed_count += 1
@@ -468,7 +480,7 @@ def export_excalidraw(
         status = "partial" if scene_count > 0 else "failed"
 
     warnings: List[str] = []
-    if not runtime["ok"]:
+    if prefer_official_bridge and not runtime["ok"]:
         warnings.append("Official Excalidraw bridge runtime unavailable; used the local deterministic scene generator.")
         warnings.extend(runtime["issues"])
 
@@ -479,6 +491,8 @@ def export_excalidraw(
         "environment_blocked": False,
         "scene_count": scene_count,
         "failed_count": failed_count,
+        "official_bridge_requested": prefer_official_bridge,
+        "official_bridge_used": bridge_used_count,
         "results": results,
         "warnings": warnings,
         "runtime": runtime,
@@ -493,13 +507,15 @@ def main() -> int:
     parser.add_argument("--rendered-diagrams-dir", required=True)
     parser.add_argument("--meta-dir", required=True)
     parser.add_argument("--enabled", default="true")
+    parser.add_argument("--prefer-official-bridge", default="false")
     args = parser.parse_args()
 
     payload = export_excalidraw(
         diagrams_dir=Path(args.diagrams_dir).resolve(),
         rendered_diagrams_dir=Path(args.rendered_diagrams_dir).resolve(),
         meta_dir=Path(args.meta_dir).resolve(),
         enabled=common.bool_from_string(args.enabled),
+        prefer_official_bridge=common.bool_from_string(args.prefer_official_bridge),
     )
     print(
         json.dumps(

code-explainer/scripts/install_runtime.ps1

@@ -14,20 +14,14 @@ npm --version
 Write-Host "Checking Git..."
 git --version
 
-Write-Host "Installing local Node runtime packages..."
-Push-Location $SkillDir
-npm install
-Pop-Location
-
 Write-Host "Installing Mermaid CLI (mmdc)..."
 npm install -g @mermaid-js/mermaid-cli
 
 Write-Host "Validating mmdc..."
 mmdc --version
 
-Write-Host "Validating Excalidraw export bridge..."
-Push-Location $SkillDir
-node ".\\scripts\\mermaid_to_excalidraw.mjs" --help | Out-Null
-Pop-Location
+Write-Host "Optional: to enable the official Excalidraw bridge for development, run:"
+Write-Host "  cd `"$SkillDir`""
+Write-Host "  npm install --no-save @excalidraw/mermaid-to-excalidraw"
 
 Write-Host "Runtime install complete."

code-explainer/scripts/install_runtime.sh

@@ -14,16 +14,14 @@ npm --version
 echo "Checking Git..."
 git --version
 
-echo "Installing local Node runtime packages..."
-(cd "$SKILL_DIR" && npm install)
-
 echo "Installing Mermaid CLI (mmdc)..."
 npm install -g @mermaid-js/mermaid-cli
 
 echo "Validating mmdc..."
 mmdc --version
 
-echo "Validating Excalidraw export bridge..."
-(cd "$SKILL_DIR" && node "./scripts/mermaid_to_excalidraw.mjs" --help >/dev/null)
+echo "Optional: to enable the official Excalidraw bridge for development, run:"
+echo "  cd \"$SKILL_DIR\""
+echo "  npm install --no-save @excalidraw/mermaid-to-excalidraw"
 
 echo "Runtime install complete."

code-explainer/scripts/self_audit.py

@@ -45,6 +45,7 @@ def _run_fixture(base_output: Path, fixture: Dict[str, Any]) -> Dict[str, Any]:
         enable_web_enrichment=False,
         enable_llm_descriptions=True,
         enable_excalidraw_export=True,
+        enable_official_excalidraw_bridge=False,
     )
     quality = common.read_json(output_root / "meta" / "quality_report.json", default={})
     explanation_quality = common.read_json(output_root / "meta" / "explanation_quality.json", default={})