feat: add mode-aware explainers, verification checkpoint, and html output

Author: baboonzero

README.md

@@ -6,10 +6,14 @@ Outputs include:
 
 - Crisp top-level overview (`OVERVIEW.md`)
 - Linked deep explainers (architecture, modules, flows, dependencies, glossary)
+- Optional interactive HTML explainer (`html/ONBOARDING.html`)
 - Mermaid source diagrams (`.mmd`)
 - Rendered SVG and PNG diagrams
 - Confidence, attribution, and quality reports (`meta/*.json`)
 - Documentation coverage report (`meta/coverage_report.json`)
+- Verification checkpoint (`meta/verification_checkpoint.json`)
+- Fact-check report (`meta/fact_check_report.json`)
+- Content completeness report (`meta/content_completeness.json`)
 
 ## Repository Layout
 
@@ -143,6 +147,8 @@ python scripts/analyze.py analyze \
   --source <local_path_or_github_url> \
   --output <output_dir> \
   --mode standard \
+  --format both \
+  --explainer-type onboarding \
   --audience nontech \
   --overview-length medium \
   --enable-llm-descriptions true \
@@ -155,6 +161,11 @@ Useful optional controls:
 
 - `--include-glob "<pattern>"` (repeatable) to scope analysis to specific paths
 - `--exclude-glob "<pattern>"` (repeatable) to remove generated/irrelevant files
+- `--format markdown|html|both`
+- `--explainer-type onboarding|project-recap|plan-review|diff-review`
+- `--since "<window>"` for `project-recap`
+- `--plan-file <path>` for `plan-review`
+- `--git-ref <ref>` for `diff-review`
 
 For LLM-based narrative summaries:
 

code-explainer/SKILL.md

@@ -33,8 +33,13 @@ python scripts/analyze.py analyze \
   --source <local_path_or_github_url> \
   --output <output_dir> \
   --mode <quick|standard|deep> \
+  --format <markdown|html|both> \
+  --explainer-type <onboarding|project-recap|plan-review|diff-review> \
   --audience <nontech|mixed|engineering> \
   --overview-length <short|medium|long> \
+  --since <time_window> \
+  --git-ref <ref> \
+  --plan-file <path> \
   --include-glob <pattern> \
   --exclude-glob <pattern> \
   --enable-llm-descriptions <true|false> \
@@ -46,6 +51,8 @@ python scripts/analyze.py analyze \
 Defaults:
 
 - `mode=standard`
+- `format=markdown`
+- `explainer-type=onboarding`
 - `audience=nontech`
 - `overview-length=medium`
 - `enable-llm-descriptions=true`
@@ -83,13 +90,16 @@ bash ./scripts/install_runtime.sh
 2. Local index build (files/modules/symbol candidates).
 3. Stack/entrypoint/dependency/flow extraction.
 4. Documentation ingestion (`coverage_report.json`).
-5. Optional LLM narrative generation (`llm_summary.json`).
-6. Optional DeepWiki + web enrichment with attribution.
-7. Mermaid generation (Context + Container + flow set).
-8. Mermaid validation.
-9. SVG then PNG rendering.
-10. Overview + deep markdown generation.
-11. Quality gates and confidence report generation.
+5. Mode-specific context extraction (`explainer_context.json`).
+6. Verification checkpoint generation (`verification_checkpoint.json`).
+7. Optional LLM narrative generation (`llm_summary.json`).
+8. Optional DeepWiki + web enrichment with attribution.
+9. Mermaid generation (Context + Container + flow set).
+10. Mermaid validation.
+11. SVG then PNG rendering.
+12. Markdown and/or HTML explainer generation.
+13. Fact-check pass (`fact_check_report.json`).
+14. Quality gates, completeness checks, and confidence report generation.
 
 ## Notes
 

code-explainer/assets/templates/deep_architecture.md.j2

@@ -32,6 +32,10 @@ Architecture Pattern: **{{architecture_pattern}}**
 
 {{llm_deep_dive_starters}}
 
+## Mode-Specific Context
+
+{{mode_specific_context}}
+
 ## Where To Modify for Common Changes
 
 {{where_to_modify}}

code-explainer/assets/templates/overview.md.j2

@@ -29,6 +29,10 @@ It appears to follow a **{{architecture_pattern}}** architecture with a stack ce
 
 {{directory_plain_summaries}}
 
+## Explainer Focus
+
+{{analysis_focus_section}}
+
 ## Documentation Coverage
 
 {{docs_coverage}}

code-explainer/references/mode-behavior.md

@@ -50,3 +50,22 @@ Goal: Maximum fidelity and audit-ready onboarding.
 - `CODE_EXPLAINER_LLM_API_KEY` (or `OPENAI_API_KEY`)
 - `CODE_EXPLAINER_LLM_BASE_URL` (optional)
 - `CODE_EXPLAINER_LLM_MODEL` (optional)
+
+## Output Format
+
+- `--format markdown`: generate markdown explainers (overview + deep docs).
+- `--format html`: generate a single interactive HTML explainer page.
+- `--format both`: generate markdown + interactive HTML.
+
+## Explainer Type
+
+- `--explainer-type onboarding`: default onboarding narrative.
+- `--explainer-type project-recap`: emphasizes recent activity and mental model refresh.
+- `--explainer-type plan-review`: compares plan/spec references against actual codebase.
+- `--explainer-type diff-review`: frames explainer around code changes from `--git-ref`.
+
+Optional supporting flags:
+
+- `--since "<window>"` for `project-recap` (default: `2 weeks ago`)
+- `--plan-file <path>` for `plan-review`
+- `--git-ref <ref>` for `diff-review`

code-explainer/references/output-contract.md

@@ -2,31 +2,37 @@
 
 `code-explainer` writes the following deterministic output tree under `<output>/`:
 
-1. `overview/OVERVIEW.md`
-2. `deep/ARCHITECTURE_DEEP.md`
-3. `deep/MODULES_DEEP.md`
-4. `deep/FLOWS_DEEP.md`
-5. `deep/DEPENDENCIES_DEEP.md`
-6. `deep/GLOSSARY.md`
-7. `diagrams/*.mmd`
-8. `diagrams/svg/*.svg`
-9. `diagrams/png/*.png`
-10. `meta/analysis_manifest.json`
-11. `meta/confidence_report.json`
-12. `meta/source_attribution.json`
-13. `meta/index.json`
-14. `meta/stack.json`
-15. `meta/entrypoints.json`
-16. `meta/dependencies.json`
-17. `meta/flows.json`
-18. `meta/diagram_manifest.json`
-19. `meta/mermaid_validation.json`
-20. `meta/render_report.json`
-21. `meta/enrichment.json`
-22. `meta/coverage_report.json`
-23. `meta/llm_summary.json`
-24. `meta/docs_generation.json`
-25. `meta/quality_report.json`
+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`
 
 ## Manifest Schema
 
@@ -44,13 +50,18 @@
 - `diagram_count`
 - `audience`
 - `overview_length`
+- `output_format`
+- `analysis_type`
 - `include_globs[]`
 - `exclude_globs[]`
 - `docs_discovered`
 - `docs_parsed`
 - `llm_descriptions_enabled`
 - `llm_descriptions_used`
 - `llm_model`
+- `verification_fact_count`
+- `fact_check_passed`
+- `html_generated`
 
 ## Coverage Schema
 
@@ -65,6 +76,37 @@
 - `parsed_docs[]` with `path`, `title`, `summary`, `headings[]`, `line_count`, `size_bytes`, `keywords[]`
 - `skipped_docs[]` with `path`, `reason`
 
+## Explainer Context Schema
+
+`explainer_context.json` contains:
+
+- `generated_at`
+- `analysis_type` (`onboarding|project-recap|plan-review|diff-review`)
+- `source`
+- `repo_root`
+- `since`
+- `git_ref`
+- `plan_file`
+- `project_recap` (mode-specific)
+- `plan_review` (mode-specific)
+- `diff_review` (mode-specific)
+- `highlights[]`
+
+## Verification Schema
+
+`verification_checkpoint.json` contains:
+
+- `generated_at`
+- `analysis_type`
+- `fact_count`
+- `facts[]` with:
+- `claim_id`
+- `claim_text`
+- `expected_text`
+- `must_include_tokens[]`
+- `status`
+- `evidence_locations[]` with `path`, `line`, `excerpt`
+
 ## LLM Narrative Schema
 
 `llm_summary.json` contains:
@@ -82,6 +124,20 @@
 - `confidence_notes[]`
 - `error`
 
+## Fact-Check Schema
+
+`fact_check_report.json` contains:
+
+- `checked_at`
+- `output_format`
+- `analysis_type`
+- `fact_count`
+- `confirmed_count`
+- `mismatch_count`
+- `passed`
+- `checks[]`
+- `advisory_checks[]`
+
 ## Confidence Schema
 
 `confidence_report.json` contains: