feat: add compact output layout with simple onboarding entry files

Author: baboonzero

.gitignore

@@ -5,10 +5,11 @@ __pycache__/
 # Skill local outputs
 code-explainer/.out*/
 code-explainer/.out-gh/
+code-explainer/.ci-out/
+code-explainer/code-explainer-output/
 
 # OS/editor
 .DS_Store
 Thumbs.db
 .vscode/
 .idea/
-

README.md

@@ -4,9 +4,14 @@
 
 Outputs include:
 
-- Crisp top-level overview (`OVERVIEW.md`)
-- Linked deep explainers (architecture, modules, flows, dependencies, glossary)
-- Interactive HTML explainer (`html/ONBOARDING.html`)
+- Compact entry files by default:
+- `START_HERE.md`
+- `DEEP_DIVE.md`
+- `ONBOARDING.html`
+- Detailed artifacts under `_details/`:
+- overview/deep markdown docs
+- diagrams (`.mmd`, `svg`, `png`)
+- metadata reports (`meta/*.json`)
 - Mermaid source diagrams (`.mmd`)
 - Rendered SVG and PNG diagrams
 - Confidence, attribution, and quality reports (`meta/*.json`)
@@ -145,9 +150,10 @@ powershell -ExecutionPolicy Bypass -File .\install_to_codex.ps1
 cd code-explainer
 python scripts/analyze.py analyze \
   --source <local_path_or_github_url> \
-  --output <output_dir> \
+  --output <optional_output_dir> \
   --mode standard \
   --format both \
+  --output-layout compact \
   --explainer-type onboarding \
   --audience nontech \
   --overview-length medium \
@@ -157,11 +163,17 @@ python scripts/analyze.py analyze \
   --enable-web-enrichment true
 ```
 
+Output path defaults:
+
+- Local folder source: `<source>/code-explainer-output`
+- GitHub URL source: `<current-working-directory>/code-explainer-output`
+
 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`
+- `--output-layout compact|full` (`compact` is default)
 - `--explainer-type onboarding|project-recap|plan-review|diff-review`
 - `--since "<window>"` for `project-recap`
 - `--plan-file <path>` for `plan-review`

code-explainer/SKILL.md

@@ -15,12 +15,14 @@ Builds onboarding-grade repository explainers from local or GitHub sources.
 
 ## Output Model
 
-Two-tier docs + rendered diagrams:
+Compact-first output + detailed artifacts:
 
-1. `overview/OVERVIEW.md` for non-technical orientation.
-2. `deep/*.md` explainers for architecture, modules, flows, dependencies, and glossary.
-3. `diagrams/*.mmd` + rendered `diagrams/svg/*.svg` and `diagrams/png/*.png`.
-4. `meta/*.json` quality, confidence, and attribution artifacts.
+1. Compact entry files (default): `START_HERE.md`, `DEEP_DIVE.md`, `ONBOARDING.html`.
+2. Detailed artifacts under `_details/` 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`.
+5. Diagrams include `.mmd`, `.svg`, and `.png`.
+6. Metadata includes quality, confidence, attribution, verification, and fact-check reports.
 
 See `references/output-contract.md` for exact files and semantics.
 
@@ -31,9 +33,10 @@ Run from this skill directory:
 ```bash
 python scripts/analyze.py analyze \
   --source <local_path_or_github_url> \
-  --output <output_dir> \
+  --output <optional_output_dir> \
   --mode <quick|standard|deep> \
   --format <markdown|html|both> \
+  --output-layout <compact|full> \
   --explainer-type <onboarding|project-recap|plan-review|diff-review> \
   --audience <nontech|mixed|engineering> \
   --overview-length <short|medium|long> \
@@ -52,13 +55,17 @@ Defaults:
 
 - `mode=standard`
 - `format=both`
+- `output-layout=compact`
 - `explainer-type=onboarding`
 - `audience=nontech`
 - `overview-length=medium`
 - `llm-mode=auto`
 - `ask-before-llm-use=true` (interactive terminals)
 - `prompt-for-llm-key=true` (interactive terminals)
 - `enable-web-enrichment=true`
+- `output` is optional:
+- local source -> `<source>/code-explainer-output`
+- GitHub URL -> `<current-working-directory>/code-explainer-output`
 
 ## Dependencies
 

code-explainer/references/mode-behavior.md

@@ -62,6 +62,14 @@ Goal: Maximum fidelity and audit-ready onboarding.
 - `--format both`: generate markdown + interactive HTML.
 - Default format is `both`.
 
+## 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 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`.
+- GitHub URL source: output goes to `<current-working-directory>/code-explainer-output`.
+
 ## Explainer Type
 
 - `--explainer-type onboarding`: default onboarding narrative.

code-explainer/references/output-contract.md

@@ -1,6 +1,22 @@
 # Output Contract
 
-`code-explainer` writes the following deterministic output tree under `<output>/`:
+`code-explainer` supports two output layouts:
+
+1. `compact` (default)
+2. `full`
+
+## Compact Layout (Default)
+
+Written under `<output>/`:
+
+1. `START_HERE.md`
+2. `DEEP_DIVE.md`
+3. `ONBOARDING.html` (when `--format html|both`)
+4. `_details/` 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`)
@@ -33,6 +49,7 @@
 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`)
 
 ## Manifest Schema
 
@@ -51,9 +68,11 @@
 - `audience`
 - `overview_length`
 - `output_format`
+- `output_layout`
 - `analysis_type`
 - `include_globs[]`
 - `exclude_globs[]`
+- `compact_entry_files[]`
 - `docs_discovered`
 - `docs_parsed`
 - `llm_descriptions_enabled`