Updating docs for new --explain feature

Author: dejo1307

ARCHITECTURE.md

@@ -137,6 +137,8 @@ Stage by stage:
 
 Three plugin roles drive the middle of the pipeline — **extractors** (source → facts), **explainers** (facts → insights), and **renderers** (snapshot → artifacts). Each is a small Go interface with a registry, so adding a language or an analysis is a self-contained addition rather than a change to the engine.
 
+**One-shot explain mode.** `enola --explain [repo_path]` is an alternative exit path through the pipeline: stages 1–6 run normally, but instead of proceeding to stage 7 (Renderer) and stage 8 (Artifacts), `pkg/explain.Compute()` reads the fact store, produces a `Report` struct, and `report.Render()` prints a human-readable statistical summary to stdout. No artifacts are written; `.enola/` is not touched. See [The explain package (`pkg/explain`)](#the-explain-package-pkgexplain) below.
+
 ---
 
 ## Insights (explainers)
@@ -149,6 +151,36 @@ Explainers turn raw facts into architectural observations. Each insight carries
 
 ---
 
+## The explain package (`pkg/explain`)
+
+`pkg/explain` ([`pkg/explain/explain.go`](pkg/explain/explain.go)) is a **public** package rather than `internal/` for one reason: `enola-enterprise` imports it to append its own license-gated sections (dead code, package metrics) to the base `Report` before rendering. It is the only package in the OSS codebase with that cross-module consumer.
+
+### `Report` and `Compute()`
+
+`Compute(eng *bootstrap.Engine) *Report` reads the engine's current fact store and snapshot — it does not generate a snapshot; callers do that first. The fields it populates map directly to the seven output sections:
+
+| Report field(s) | Output section |
+|---|---|
+| `RepoPath`, `GeneratedAt`, `Duration`, `Extractors`, `TotalFacts` | Overview |
+| `KindCounts` | Architectural kinds |
+| `SymbolKinds` | Symbol breakdown |
+| `Routes`, `RoutesByMethod`, `Storage` | API & data surface |
+| `DepSources` | Dependencies |
+| `Architecture`, `ArchConfidence`, `Cycles`, `LayerViolations`, `CrossRepoEdges` | Architecture |
+| `Modules`, `HighCriticality`, `MediumCriticality`, `Hotspots`, `CouplingUnresolved` | Impact analysis (hotspots) |
+
+`CouplingUnresolved` is a special flag: it is set when dependency facts exist but no import edge resolved to a module, meaning coupling analysis is unavailable rather than genuinely zero. The renderer surfaces this as an explanatory note instead of implying the codebase has no coupling.
+
+### Extensibility via `ExtraSections`
+
+`Report.ExtraSections []Section` is the extension point for enterprise code. After calling `Compute()`, enterprise calls `report.AddSection(title, body)` (or directly appends `explain.Section{...}`) and then calls `report.Render()`. The renderer appends the extra sections after the seven base sections, using the same plain-text format. This design means `enola-enterprise` only depends on the exported `pkg/explain` surface and never needs to import `internal/facts` or `internal/engine` directly.
+
+### Output format
+
+`Render()` produces plain aligned text (not Markdown), designed to read well in a terminal without paging. Sections are separated by `═` rule lines (60 characters). Key-value pairs use `fmt.Fprintf` with a 20-character label width; tables (hotspots) use fixed-width column formats. No color codes — output is safe to pipe or capture in CI.
+
+---
+
 ## The tools
 
 enola is a stdio [MCP](https://modelcontextprotocol.io/) server. It exposes **seven tools** and no MCP resources — everything flows through tool calls. The tools defined in [`internal/server/server.go`](internal/server/server.go) are listed below, each leading with the question it answers.

README.md

@@ -186,6 +186,38 @@ Artifacts are written to the configured `output.dir` (default `.enola/`). Config
 
 ---
 
+## Explain a repository at a glance
+
+`enola --explain [repo_path]` is a one-shot mode that generates a snapshot, computes statistics over the fact graph, and prints a human-readable report to stdout — no MCP server started, no artifacts written to `.enola/`.
+
+**When to use it:**
+- New contributor getting a first orientation — module count, architecture pattern, hottest packages.
+- Pre-refactor sanity check — cycles, layer violations, blast radius of top modules.
+- Quick audit without spinning up an AI agent.
+
+```bash
+# Use the config in the current directory (mcp-arch.yaml)
+enola --explain
+
+# Analyze a specific repository path
+enola --explain /path/to/repo
+```
+
+**The report covers seven sections:**
+- **Overview** — path, analysis time, active languages, total fact count
+- **Architectural kinds** — counts of modules, symbols, routes, storage, dependencies, services
+- **Symbol breakdown** — functions, methods, structs, interfaces, and other kinds
+- **API & data surface** — route count broken down by HTTP method, plus storage count
+- **Dependencies** — external, internal, and stdlib import counts
+- **Architecture** — detected pattern with confidence, cyclic dependencies, layer violations, cross-repo edges
+- **Impact analysis (hotspots)** — top modules ranked by fan-in + fan-out coupling, with criticality tier and blast radius
+
+No artifacts are written; `.enola/` is not touched. For a persistent snapshot with agent-readable output, use `--generate` or the MCP server.
+
+For interactive per-module blast-radius queries with configurable depth, see the `impact_analysis` tool reference in **[ARCHITECTURE.md → The tools](ARCHITECTURE.md#the-tools)**.
+
+---
+
 ## Learn more
 
 - **[ARCHITECTURE.md](ARCHITECTURE.md)** — the concept, the fact model, the pipeline, and the full tool reference.