feat: strengthen onboarding explainers with llm modes and quality gates

Author: baboonzero

README.md

@@ -6,7 +6,7 @@ Outputs include:
 
 - Crisp top-level overview (`OVERVIEW.md`)
 - Linked deep explainers (architecture, modules, flows, dependencies, glossary)
-- Optional interactive HTML explainer (`html/ONBOARDING.html`)
+- Interactive HTML explainer (`html/ONBOARDING.html`)
 - Mermaid source diagrams (`.mmd`)
 - Rendered SVG and PNG diagrams
 - Confidence, attribution, and quality reports (`meta/*.json`)
@@ -151,9 +151,9 @@ python scripts/analyze.py analyze \
   --explainer-type onboarding \
   --audience nontech \
   --overview-length medium \
-  --enable-llm-descriptions true \
-  --ask-before-llm-use false \
-  --prompt-for-llm-key false \
+  --llm-mode auto \
+  --ask-before-llm-use true \
+  --prompt-for-llm-key true \
   --enable-web-enrichment true
 ```
 
@@ -171,9 +171,11 @@ For LLM-based narrative summaries:
 
 - Set `CODE_EXPLAINER_LLM_API_KEY` (or `OPENAI_API_KEY`)
 - Optional: `CODE_EXPLAINER_LLM_BASE_URL`, `CODE_EXPLAINER_LLM_MODEL`
+- Control behavior via `--llm-mode auto|required|off`
 - Optional interactive controls:
-- `--ask-before-llm-use true` (prompt for permission)
-- `--prompt-for-llm-key true` (securely prompt for key when missing)
+- `--ask-before-llm-use true` (prompt for permission in interactive terminals)
+- `--prompt-for-llm-key true` (securely prompt for key when missing in interactive terminals)
+- Legacy compatibility: `--enable-llm-descriptions true|false` maps to `auto|off`
 
 ## Install From GitHub (For Other Developers)
 

code-explainer/SKILL.md

@@ -42,7 +42,7 @@ python scripts/analyze.py analyze \
   --plan-file <path> \
   --include-glob <pattern> \
   --exclude-glob <pattern> \
-  --enable-llm-descriptions <true|false> \
+  --llm-mode <auto|required|off> \
   --ask-before-llm-use <true|false> \
   --prompt-for-llm-key <true|false> \
   --enable-web-enrichment <true|false>
@@ -51,13 +51,13 @@ python scripts/analyze.py analyze \
 Defaults:
 
 - `mode=standard`
-- `format=markdown`
+- `format=both`
 - `explainer-type=onboarding`
 - `audience=nontech`
 - `overview-length=medium`
-- `enable-llm-descriptions=true`
-- `ask-before-llm-use=false`
-- `prompt-for-llm-key=false`
+- `llm-mode=auto`
+- `ask-before-llm-use=true` (interactive terminals)
+- `prompt-for-llm-key=true` (interactive terminals)
 - `enable-web-enrichment=true`
 
 ## Dependencies
@@ -108,9 +108,11 @@ bash ./scripts/install_runtime.sh
 - Without `mmdc`, fallback rendering is used and flagged in reports.
 - For LLM narrative summaries, set `CODE_EXPLAINER_LLM_API_KEY` (or `OPENAI_API_KEY`).
 - Optional: set `CODE_EXPLAINER_LLM_BASE_URL` and `CODE_EXPLAINER_LLM_MODEL`.
-- If you want interactive control, enable:
+- Interactive prompts are supported:
 - `--ask-before-llm-use true`
 - `--prompt-for-llm-key true`
+- If you need strict narrative generation, run with `--llm-mode required`.
+- Legacy flag remains supported: `--enable-llm-descriptions <true|false>`.
 - This skill does not mutate the analyzed target repository.
 
 ## Dependency Troubleshooting

code-explainer/references/mode-behavior.md

@@ -42,10 +42,14 @@ Goal: Maximum fidelity and audit-ready onboarding.
 
 ## LLM Narrative
 
-- Controlled with `--enable-llm-descriptions <true|false>`.
-- Optional interactive controls:
-- `--ask-before-llm-use true`
-- `--prompt-for-llm-key true`
+- Controlled with `--llm-mode <auto|required|off>`.
+- `auto`: try LLM when possible, otherwise continue with deterministic fallback.
+- `required`: fail quality gate unless LLM narrative is successfully used.
+- `off`: deterministic-only mode; no LLM attempt.
+- Interactive controls (enabled by default in `analyze.py`):
+- `--ask-before-llm-use true|false`
+- `--prompt-for-llm-key true|false`
+- Legacy compatibility: `--enable-llm-descriptions <true|false>` maps to `auto|off`.
 - Reads API config from env vars:
 - `CODE_EXPLAINER_LLM_API_KEY` (or `OPENAI_API_KEY`)
 - `CODE_EXPLAINER_LLM_BASE_URL` (optional)
@@ -56,6 +60,7 @@ Goal: Maximum fidelity and audit-ready onboarding.
 - `--format markdown`: generate markdown explainers (overview + deep docs).
 - `--format html`: generate a single interactive HTML explainer page.
 - `--format both`: generate markdown + interactive HTML.
+- Default format is `both`.
 
 ## Explainer Type
 

code-explainer/references/output-contract.md

@@ -58,6 +58,7 @@
 - `docs_parsed`
 - `llm_descriptions_enabled`
 - `llm_descriptions_used`
+- `llm_mode`
 - `llm_model`
 - `verification_fact_count`
 - `fact_check_passed`
@@ -113,9 +114,13 @@
 
 - `generated_at`
 - `enabled`
+- `llm_mode`
 - `used`
 - `asked_before_use`
+- `consent_granted`
+- `consent_mode`
 - `prompted_for_key`
+- `api_key_source`
 - `provider`
 - `model`
 - `repo_summary_paragraph`

code-explainer/scripts/analyze.py

@@ -93,6 +93,7 @@ def _write_manifest(
     entry_payload: Dict[str, Any],
     docs_payload: Dict[str, Any],
     llm_payload: Dict[str, Any],
+    llm_mode: str,
     verification_payload: Dict[str, Any],
     html_payload: Dict[str, Any],
     fact_check_payload: Dict[str, Any],
@@ -118,6 +119,7 @@ def _write_manifest(
         "docs_parsed": docs_payload.get("parsed_count", 0),
         "llm_descriptions_enabled": llm_payload.get("enabled", False),
         "llm_descriptions_used": llm_payload.get("used", False),
+        "llm_mode": llm_mode,
         "llm_model": llm_payload.get("model", ""),
         "verification_fact_count": verification_payload.get("fact_count", 0),
         "fact_check_passed": fact_check_payload.get("passed", False),
@@ -139,7 +141,7 @@ def run_pipeline(
     output_format: str,
     analysis_type: str,
     enable_web_enrichment: bool,
-    enable_llm_descriptions: bool,
+    llm_mode: str,
     ask_before_llm_use: bool = False,
     prompt_for_llm_key: bool = False,
     include_globs: List[str] | None = None,
@@ -209,7 +211,7 @@ def run_pipeline(
             docs_payload=coverage_payload,
             context_payload=context_payload,
             out_dir=meta_dir,
-            enabled=enable_llm_descriptions,
+            llm_mode=llm_mode,
             ask_before_use=ask_before_llm_use,
             prompt_for_key=prompt_for_llm_key,
         )
@@ -289,6 +291,7 @@ def run_pipeline(
             entry_payload=entry_payload,
             docs_payload=coverage_payload,
             llm_payload=llm_payload,
+            llm_mode=llm_mode,
             verification_payload=verification_payload,
             html_payload=html_payload,
             fact_check_payload=fact_check_payload,
@@ -303,6 +306,7 @@ def run_pipeline(
             mode=mode,
             output_format=output_format,
             analysis_type=analysis_type,
+            llm_mode=llm_mode,
         )
 
         return {
@@ -313,6 +317,7 @@ def run_pipeline(
             "output_format": output_format,
             "audience": audience,
             "overview_length": overview_length,
+            "llm_mode": llm_mode,
             "file_count": index_payload.get("file_count", 0),
             "docs_discovered": coverage_payload.get("discovered_count", 0),
             "docs_parsed": coverage_payload.get("parsed_count", 0),
@@ -339,7 +344,7 @@ def _parse_args() -> argparse.Namespace:
     parser.add_argument("--mode", default="standard", choices=["quick", "standard", "deep"])
     parser.add_argument("--audience", default="nontech", choices=["nontech", "mixed", "engineering"])
     parser.add_argument("--overview-length", default="medium", choices=["short", "medium", "long"])
-    parser.add_argument("--format", default="markdown", choices=["markdown", "html", "both"])
+    parser.add_argument("--format", default="both", choices=["markdown", "html", "both"])
     parser.add_argument(
         "--explainer-type",
         default="onboarding",
@@ -361,9 +366,10 @@ def _parse_args() -> argparse.Namespace:
         help="Glob(s) to exclude from indexing.",
     )
     parser.add_argument("--enable-web-enrichment", default="true")
-    parser.add_argument("--enable-llm-descriptions", default="true")
-    parser.add_argument("--ask-before-llm-use", default="false")
-    parser.add_argument("--prompt-for-llm-key", default="false")
+    parser.add_argument("--llm-mode", default="auto", choices=["auto", "required", "off"])
+    parser.add_argument("--enable-llm-descriptions", default="")
+    parser.add_argument("--ask-before-llm-use", default="true")
+    parser.add_argument("--prompt-for-llm-key", default="true")
     return parser.parse_args()
 
 
@@ -375,7 +381,9 @@ def main() -> int:
 
     mode = common.normalize_mode(args.mode)
     web_enabled = common.bool_from_string(args.enable_web_enrichment)
-    llm_enabled = common.bool_from_string(args.enable_llm_descriptions)
+    llm_mode = (args.llm_mode or "auto").strip().lower()
+    if args.enable_llm_descriptions.strip():
+        llm_mode = "auto" if common.bool_from_string(args.enable_llm_descriptions) else "off"
     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(
@@ -387,7 +395,7 @@ def main() -> int:
         output_format=args.format,
         analysis_type=args.explainer_type,
         enable_web_enrichment=web_enabled,
-        enable_llm_descriptions=llm_enabled,
+        llm_mode=llm_mode,
         ask_before_llm_use=ask_before_llm_use,
         prompt_for_llm_key=prompt_for_llm_key,
         include_globs=args.include_glob,
@@ -405,6 +413,7 @@ def main() -> int:
         "output_format",
         "audience",
         "overview_length",
+        "llm_mode",
         "file_count",
         "docs_discovered",
         "docs_parsed",

code-explainer/scripts/common.py

@@ -199,9 +199,17 @@ def top_level_modules(files: Iterable[Dict[str, Any]], max_items: int = 60) -> L
 
         top = path.split("/", 1)[0]
         if top not in buckets:
-            buckets[top] = {"name": top, "type": "directory", "file_count": 0, "total_bytes": 0}
+            buckets[top] = {
+                "name": top,
+                "type": "directory",
+                "file_count": 0,
+                "total_bytes": 0,
+                "examples": [],
+            }
         buckets[top]["file_count"] += 1
         buckets[top]["total_bytes"] += size
+        if len(buckets[top]["examples"]) < 10:
+            buckets[top]["examples"].append(path)
 
     ranked = sorted(
         buckets.values(), key=lambda m: (m["file_count"], m["total_bytes"]), reverse=True