feat: humanize explainers and improve default visual readability

Author: baboonzero

.gitignore

@@ -3,6 +3,8 @@ __pycache__/
 *.py[cod]
 
 # Skill local outputs
+.out*/
+code-explainer-output/
 code-explainer/.out*/
 code-explainer/.out-gh/
 code-explainer/.ci-out/

README.md

@@ -6,9 +6,9 @@ Outputs include:
 
 - Compact entry files by default:
 - `START_HERE.md`
-- `DEEP_DIVE.md`
+- `SYSTEM_DEEP_DIVE.md`
 - `ONBOARDING.html`
-- Detailed artifacts under `_details/`:
+- Detailed artifacts under `evidence/`:
 - overview/deep markdown docs
 - diagrams (`.mmd`, `svg`, `png`)
 - metadata reports (`meta/*.json`)

code-explainer/SKILL.md

@@ -17,10 +17,10 @@ Builds onboarding-grade repository explainers from local or GitHub sources.
 
 Compact-first output + detailed artifacts:
 
-1. Compact entry files (default): `START_HERE.md`, `DEEP_DIVE.md`, `ONBOARDING.html`.
-2. Detailed artifacts under `_details/` in compact layout.
+1. Compact entry files (default): `START_HERE.md`, `SYSTEM_DEEP_DIVE.md`, `ONBOARDING.html`.
+2. Detailed artifacts under `evidence/` in compact layout.
 3. Optional full layout writes docs/diagrams/meta directly under output root.
-4. Detailed docs include `overview/OVERVIEW.md` and `deep/*.md`.
+4. Detailed docs include `overview/OVERVIEW.md` and `deep/SYSTEM_DEEP_DIVE.md`.
 5. Diagrams include `.mmd`, `.svg`, and `.png`.
 6. Metadata includes quality, confidence, attribution, verification, and fact-check reports.
 

code-explainer/references/mode-behavior.md

@@ -64,7 +64,7 @@ Goal: Maximum fidelity and audit-ready onboarding.
 
 ## Output Layout
 
-- `--output-layout compact`: default. Produces a minimal root with `START_HERE.md`, `DEEP_DIVE.md`, `ONBOARDING.html`, and stores full artifacts in `_details/`.
+- `--output-layout compact`: default. Produces a minimal root with `START_HERE.md`, `SYSTEM_DEEP_DIVE.md`, `ONBOARDING.html`, and stores full artifacts in `evidence/`.
 - `--output-layout full`: writes the full docs/diagrams/meta tree directly under output root.
 - If `--output` is omitted:
 - Local source: output goes to `<source>/code-explainer-output`.

code-explainer/references/output-contract.md

@@ -10,46 +10,42 @@
 Written under `<output>/`:
 
 1. `START_HERE.md`
-2. `DEEP_DIVE.md`
+2. `SYSTEM_DEEP_DIVE.md`
 3. `ONBOARDING.html` (when `--format html|both`)
-4. `_details/` containing the full artifact tree listed below
+4. `evidence/` containing the full artifact tree listed below
 
 ## Full Layout
 
 Written directly under `<output>/`:
 
 1. `overview/OVERVIEW.md` (when `--format markdown|both`)
-2. `deep/ARCHITECTURE_DEEP.md` (when `--format markdown|both`)
-3. `deep/MODULES_DEEP.md` (when `--format markdown|both`)
-4. `deep/FLOWS_DEEP.md` (when `--format markdown|both`)
-5. `deep/DEPENDENCIES_DEEP.md` (when `--format markdown|both`)
-6. `deep/GLOSSARY.md` (when `--format markdown|both`)
-7. `html/ONBOARDING.html` (when `--format html|both`)
-8. `diagrams/*.mmd`
-9. `diagrams/svg/*.svg`
-10. `diagrams/png/*.png`
-11. `meta/analysis_manifest.json`
-12. `meta/confidence_report.json`
-13. `meta/source_attribution.json`
-14. `meta/index.json`
-15. `meta/stack.json`
-16. `meta/entrypoints.json`
-17. `meta/dependencies.json`
-18. `meta/flows.json`
-19. `meta/diagram_manifest.json`
-20. `meta/mermaid_validation.json`
-21. `meta/render_report.json`
-22. `meta/enrichment.json`
-23. `meta/coverage_report.json`
-24. `meta/explainer_context.json`
-25. `meta/verification_checkpoint.json`
-26. `meta/llm_summary.json`
-27. `meta/docs_generation.json`
-28. `meta/html_generation.json` (when `--format html|both`)
-29. `meta/fact_check_report.json`
-30. `meta/content_completeness.json`
-31. `meta/quality_report.json`
-32. `meta/compact_output.json` (when `--output-layout compact`)
+2. `deep/SYSTEM_DEEP_DIVE.md` (when `--format markdown|both`)
+3. `html/ONBOARDING.html` (when `--format html|both`)
+4. `diagrams/*.mmd`
+5. `diagrams/svg/*.svg`
+6. `diagrams/png/*.png`
+7. `meta/analysis_manifest.json`
+8. `meta/confidence_report.json`
+9. `meta/source_attribution.json`
+10. `meta/index.json`
+11. `meta/stack.json`
+12. `meta/entrypoints.json`
+13. `meta/dependencies.json`
+14. `meta/flows.json`
+15. `meta/diagram_manifest.json`
+16. `meta/mermaid_validation.json`
+17. `meta/render_report.json`
+18. `meta/enrichment.json`
+19. `meta/coverage_report.json`
+20. `meta/explainer_context.json`
+21. `meta/verification_checkpoint.json`
+22. `meta/llm_summary.json`
+23. `meta/docs_generation.json`
+24. `meta/html_generation.json` (when `--format html|both`)
+25. `meta/fact_check_report.json`
+26. `meta/content_completeness.json`
+27. `meta/quality_report.json`
+28. `meta/compact_output.json` (when `--output-layout compact`)
 
 ## Manifest Schema
 

code-explainer/scripts/analyze.py

@@ -196,20 +196,20 @@ def run_pipeline(
         output_layout = (output_layout or "compact").strip().lower()
         if output_layout not in {"compact", "full"}:
             output_layout = "compact"
-        artifact_root = output_root if output_layout == "full" else output_root / "_details"
+        artifact_root = output_root if output_layout == "full" else output_root / "evidence"
 
         if output_layout == "compact":
             _clear_generated_paths(
                 output_root,
                 [
-                    "_details",
+                    "evidence",
                     "meta",
                     "overview",
                     "deep",
                     "diagrams",
                     "html",
                     "START_HERE.md",
-                    "DEEP_DIVE.md",
+                    "SYSTEM_DEEP_DIVE.md",
                     "ONBOARDING.html",
                 ],
             )
@@ -242,7 +242,7 @@ def run_pipeline(
         stack_payload = detect_stack.analyze_stack(repo_root, index_payload, meta_dir)
         entry_payload = map_entrypoints.map_entrypoints(index_payload, repo_root, meta_dir)
         dep_payload = map_dependencies.map_dependencies(repo_root, index_payload, meta_dir)
-        flow_payload = map_flows.map_flows(stack_payload, entry_payload, dep_payload, meta_dir, mode)
+        flow_payload = map_flows.map_flows(repo_root, stack_payload, entry_payload, dep_payload, meta_dir, mode)
         coverage_payload = ingest_docs.ingest_docs(repo_root, index_payload, meta_dir, mode)
         context_payload = explainer_context.build_explainer_context(
             repo_root=repo_root,