From 2127d86a403a9afb7886d1777f6d92c3aad4b8bd Mon Sep 17 00:00:00 2001
From: Obed0101 <dibujos.obed@gmail.com>
Date: Tue, 25 Aug 2026 13:42:48 -0500
Subject: [PATCH] docs: reorganize navigation and Mermaid fixtures

---
 docs/README.md                                | 112 ++++++------------
 docs/architecture.md                          |   2 +-
 docs/changes-review.md                        |  24 +---
 docs/features.md                              |  19 +--
 docs/mermaid-ascii-rendering.md               | 101 ++++++++--------
 docs/plan-mode.md                             |   6 +-
 docs/source-map.md                            |  90 ++++++++++++++
 docs/tui-plugins-and-widgets.md               |   2 +-
 docs/usage-insights.md                        |   7 +-
 .../test/cli/tui/markdown-render.test.ts      |   2 +
 10 files changed, 196 insertions(+), 169 deletions(-)
 create mode 100644 docs/source-map.md

diff --git a/docs/README.md b/docs/README.md
index d8d438c8..e6f9882b 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -2,59 +2,53 @@
 
 These docs describe the MendCode-owned product surface: the public `mendcode` CLI, `.mendcode/` configuration, setup flow, runtime packages, model roles, prompt modes, memory, permissions, TUI customization, Plan Mode, Changes Review, Loop Workflows, Usage Insights, mflow, optional TSM/worktrees, and release/security policy.
 
-If you are deciding what to show on GitHub or the website, start with [Feature Map](features.md). If you only read one setup page after this index, read [CLI, setup, and configuration](cli-setup-configuration.md). If you are shaping the visual product experience, read [Customization](customization.md).
+Use this index by intent. **Use MendCode** explains the public workflow, **Features and pages** describes what the TUI can do, and **Build and maintain** is for packages, extensions, source paths, and releases. The [Source Map](source-map.md) is intentionally separate so normal product docs do not repeat internal `opencode` paths.
 
-## Start Here
+## Use MendCode
 
-1. [Feature Map](features.md): the full product inventory for README, website, screenshots, and demos.
-2. [CLI, setup, and configuration](cli-setup-configuration.md): install/open commands, setup state, config paths, focus profiles, model roles, prompt modes (including named project-local `custom.md` context), budget posture, permissions, and memory.
-3. [Customization](customization.md): prompt input, input marker, prompt status, home centered/split modes, Agent View, ASCII title/mascot, activity states, and team profile examples.
-4. [Custom tool calls](custom-tool-calls.md): project-local and package-shared assistant tools with typed arguments, execution context, metadata, and permission checks.
-5. [Plan Mode](plan-mode.md): interactive plan review modal, approve/edit/comment/reject flow, Mermaid support, and post-approval implementation handoff.
-6. [Mermaid ASCII rendering](mermaid-ascii-rendering.md): chat canvas controls, fit and pan behavior, supported diagram families, stress fixtures, and exact expected ASCII output.
-7. [Changes Review](changes-review.md): `/changes` diff workspace, keybinds, comments, responsive layout, and agent-visible review context.
-8. [Loop Workflows](loop-workflows.md): verified goals, recurring scheduled jobs, bounded runs, Agent View loop roots, `/loop` creation, `/loops` supervision with live countdowns, durable permission waits, execution modes, and the per-project OS scheduler.
-9. [Memory Center](memory-center.md): saved memories, proposals, categories, Dream status, project grouping, and the constrained memory side agent for questions, explanations, and draft proposals.
-10. [Usage Insights](usage-insights.md): global/project activity dashboard, token heatmap, AI time, top tools/agents/models, cache behavior, and weather.
-11. [Packages and team sharing](packages-and-team-sharing.md): package commands, agents, modes, skills, prompts, MCP files, widgets, TUI profiles, model policy, permissions, memory, and worktree policy for teams.
-12. [Automation runtime](automation-runtime.md): session automation commands, versioned JSON envelopes, shared model selection, progress inspection, events, waiting, and cancellation.
+- [CLI, setup, and configuration](cli-setup-configuration.md): install/open commands, setup state, config paths, focus profiles, model roles, prompt modes, permissions, and memory.
+- [Session history](session-history.md): browse, inspect, and resume previous sessions.
+- [Automation runtime](automation-runtime.md): JSON envelopes, shared model selection, progress inspection, events, waiting, and cancellation.
+- [Independent Workflows](workflows.md): one-shot plans, task sequencing, completion evidence, and operator controls.
+- [Loop Workflows](loop-workflows.md): verified goals, recurring jobs, bounded runs, durable permission waits, and `/loops` supervision.
+- [mflow coordination](mflow.md): local-first coordination, relay modes, file locks, and same-worktree editing.
+- [TSM and worktrees](tsm-and-worktrees.md): optional terminal sessions, worktree routing, registry ownership, and preview-first safety.
+- [Packages and team sharing](packages-and-team-sharing.md): share commands, agents, modes, skills, prompts, MCP, widgets, profiles, and policy.
 
-## Configure The Harness
+## Features and pages
 
-- [CLI, setup, and configuration](cli-setup-configuration.md): required setup steps, optional setup steps, config files, provider/model roles, prompt modes, permissions, and memory.
-- [Package index](package-index.md): source package map and the distinction between npm workspace packages and runtime `.mendcode` packages.
-- [Architecture and packages](architecture.md): repo layout, MendCode-owned runtime layer, public command router, package map, and safety model.
-- [Provider-aware context continuity](features.md#provider-aware-context-continuity): OAuth Responses Lite continuity, local compaction, and provider-aware limits.
+### Product features
 
-## Shape The Terminal
+- [Feature Map](features.md): complete inventory of product behavior, shortcuts, slash commands, and demo surfaces.
+- [Customization](customization.md): prompt chrome, input marker, status placement, home identity, Agent View, mascot, activity states, and profiles.
+- [Mermaid ASCII rendering](mermaid-ascii-rendering.md): terminal-native diagrams, fit/pan controls, local scrolling, supported families, and expanded fixtures.
+- [Custom Tool Calls](custom-tool-calls.md): project-local and package-shared tools with typed context and permission checks.
+- [TUI Plugins and Widgets](tui-plugins-and-widgets.md): status rows, widgets, slots, commands, dialogs, routes, themes, keybinds, and package distribution.
+- [Themes](themes.md): terminal theme reference.
 
-- [Feature Map](features.md): concise inventory of demo-worthy surfaces, shortcuts, slash commands, and feature claims.
-- [Customization](customization.md): static TUI profile, prompt chrome, prompt marker, prompt status, home identity, Agent View, mascot/activity behavior, and screenshot guidance.
-- [TUI plugins and widgets](tui-plugins-and-widgets.md): dynamic runtime extensions, custom status rows, widgets, slots, command palette entries, slash commands, dialogs, routes, themes, keybinds, and package distribution.
+### TUI pages and operator surfaces
 
-## Review, Memory, And Observability
+- [Plan Mode](plan-mode.md): review, edit, comment, approve, or reject a plan before implementation.
+- [Changes Review](changes-review.md): diff workspace, responsive layout, comments, and agent-visible review context.
+- [Loop Workflows](loop-workflows.md): active/history dashboard, phases, runs, permissions, and recovery controls.
+- [Memory Center](memory-center.md): saved memories, proposals, categories, Dream status, and constrained side chat.
+- [Usage Insights](usage-insights.md): activity scopes, token heatmap, AI time, tools/agents/models, cache behavior, and weather.
 
-- [Plan Mode](plan-mode.md): planning without silent implementation.
-- [Changes Review](changes-review.md): working-tree diff review with comments, keybinds, and agent-visible review context.
-- [Loop Workflows](loop-workflows.md): verified goals and recurring scheduled jobs with explicit completion, cadence, permission, and safety contracts.
-- [Memory Center](memory-center.md): approval-first memory review, Dream maintenance, and constrained side-agent proposals.
-- [Usage Insights](usage-insights.md): local usage visibility without overclaiming productivity.
-- [Automation runtime](automation-runtime.md): machine-readable session control, progress events, lifecycle waiting, cancellation, and shared model selection.
-- [CLI, setup, and configuration](cli-setup-configuration.md#permissions-and-memory): permission modes, smart reviewer role, memory scopes, search/preview, and approval-gated proposals.
+## Build and maintain
 
-## Coordinate Local Work
+- [Architecture and packages](architecture.md): ownership, runtime boundary, repository layout, package map, and safety model.
+- [Package index](package-index.md): workspace packages versus runtime `.mendcode` packages.
+- [MendCode Source Map](source-map.md): one maintained map from public features to implementation and test paths.
+- [Releasing](releasing.md): installer contract, checksums, release notes, and public installer smoke tests.
+- [Changelog](../CHANGELOG.md): versioned behavior changes and regression coverage for recent releases.
+- [Supply chain security](supply-chain-security.md): provenance, SBOM, pinned actions, dependency review, and scanner policy.
+- [Public readiness audit](public-readiness-audit.md): branch, secret, dependency, legacy-reference, and public-surface checks.
 
-- [mflow coordination](mflow.md): optional local-first coordination, relay modes, file locks, and same-worktree multi-agent editing.
-- [TSM and worktrees](tsm-and-worktrees.md): `mendcode --worktree`, `mendcode --tsm`, optional TSM lifecycle, registry ownership, and preview-first worktree safety.
+## Community and publication
 
-## Release And Public Readiness
-
-- [Releasing](releasing.md): release assets, installer contract, checksums, release notes, and public installer smoke tests.
-- [Supply chain security](supply-chain-security.md): release provenance, SBOM, pinned actions, dependency review, and scanner policy.
-- [Public readiness audit](public-readiness-audit.md): current branch, secret, old-repo-reference, and public-surface audit notes.
-- [Community](community.md): issues, discussions, PRs, and labels.
-- [Wiki](wiki.md): GitHub wiki setup and doc sync.
-- [Lineage and acknowledgements](../ACKNOWLEDGEMENTS.md): opencode attribution and MendCode downstream scope.
+- [Community](community.md): issues, discussions, pull requests, and labels.
+- [Wiki](wiki.md): GitHub wiki structure and synchronization.
+- [Lineage and acknowledgements](../ACKNOWLEDGEMENTS.md): upstream attribution and MendCode downstream scope.
 
 ## Main Commands
 
@@ -112,34 +106,6 @@ Ctrl+X then l -> Session switcher
 
 CLI profile inspection exists for compatibility/debugging, but it is not the normal customization path.
 
-## Source Map
-
-- `src/mendcode/packages/opencode/src/mend/cli/public-bin.ts`: public `mendcode` command router.
-- `src/mendcode/packages/opencode/src/mend/config/project.ts`: project config, focus profiles, generated runtime config, package metadata.
-- `src/mendcode/packages/opencode/src/mend/config/models.ts`: model roles, projection, and shared prompt-model precedence.
-- `src/mendcode/packages/opencode/src/cli/cmd/session.ts` and `src/mendcode/packages/opencode/src/cli/automation.ts`: session automation commands and the `mendcode.cli.v1` JSON envelope.
-- `src/mendcode/packages/opencode/src/cli/cmd/run.ts` and `src/mendcode/packages/opencode/src/cli/model-selection.ts`: headless streaming and runtime model/agent resolution.
-- `src/mendcode/packages/opencode/src/mend/config/permissions.ts`: global permission mode and smart-reviewer role config.
-- `src/mendcode/packages/opencode/src/mend/prompt/mode.ts`: prompt modes: `minimal`, `focus`, `full`, and project-local `custom`.
-- `src/mendcode/packages/opencode/src/mend/prompt/custom.ts`: bounded, root-safe loader for `.mendcode/prompts/custom.md`.
-- `src/mendcode/packages/opencode/src/mend/memory/`: approval-gated memory storage, proposals, retrieval, graph, Dream, side chat, workspaces, and category policy.
-- `src/mendcode/packages/opencode/src/cli/cmd/tui/routes/memory/index.tsx`: Memory Center route, category policy, Dream panel, inspector, and constrained memory side agent.
-- `src/mendcode/packages/opencode/src/mend/config/mflow.ts`: local-first mflow setup, relay config, edit-lock enforcement.
-- `src/mendcode/packages/opencode/src/mend/config/tsm.ts`: optional TSM lifecycle and detection.
-- `src/mendcode/packages/opencode/src/mend/config/worktree.ts`: worktree status, dry-run planning, adoption, destructive previews.
-- `src/mendcode/packages/opencode/src/mend/runtime/pack.ts`: runtime package snapshots.
-- `src/mendcode/packages/opencode/src/mend/runtime/packages.ts`: installed package state and active package projection.
-- `src/mendcode/packages/opencode/src/mend/profile.ts`: TUI profile schema and defaults.
-- `src/mendcode/packages/opencode/src/tool/plan-review.ts`: Plan Review tool and post-approval agent switch.
-- `src/mendcode/packages/opencode/src/cli/cmd/tui/routes/changes/`: Changes Review route, diff loading, comments, responsive renderer, and review state.
-- `src/mendcode/packages/opencode/src/tool/review.ts`: assistant-facing review workspace tool.
-- `src/mendcode/packages/opencode/src/cli/cmd/tui/routes/loops/`: Loop Workflows dashboard route.
-- `src/mendcode/packages/opencode/src/mend/runtime/loop-service.ts`: durable loop service, status, activation, and run state.
-- `src/mendcode/packages/opencode/src/session/loop.ts`: loop workflow model and lifecycle.
-- `src/mendcode/packages/opencode/src/session/loop-runner.ts`: loop wakeup execution path.
-- `src/mendcode/packages/opencode/src/tool/loop.ts`: assistant-facing loop workflow tool.
-- `src/mendcode/packages/opencode/src/server/routes/instance/loop.ts` and `src/mendcode/packages/opencode/src/server/routes/instance/httpapi/handlers/loop.ts`: legacy and Effect loop read/control routes.
-- `src/mendcode/packages/opencode/src/mend/cli/control-plane.ts` and `src/mendcode/packages/opencode/src/mend/runtime/loop-service.ts`: public loop CLI controls and project OS service lifecycle.
-- `src/mendcode/packages/opencode/src/cli/cmd/tui/routes/stats/index.tsx`: Usage Insights TUI route.
-- `src/mendcode/packages/opencode/src/provider/claude-code.ts`: local Claude Code CLI provider bridge and validation.
-- `src/mendcode/packages/plugin/src/tui.ts`: public TUI plugin/widget types.
+## Implementation pointers
+
+The maintained implementation and test paths now live in the dedicated [MendCode Source Map](source-map.md). This index stays focused on the public product documentation.
diff --git a/docs/architecture.md b/docs/architecture.md
index 32a41462..adf8ca10 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -1,6 +1,6 @@
 # Architecture and Packages
 
-MendCode has a MendCode-owned control plane wrapped around an adapted terminal coding runtime. The public surface is the `mendcode` CLI. The runtime source lives in `src/mendcode/packages/opencode`, but public commands are routed through MendCode modules under `src/mendcode/packages/opencode/src/mend`.
+MendCode has a MendCode-owned control plane wrapped around an adapted terminal coding runtime. The public surface is the `mendcode` CLI. The internal runtime package is documented in the [MendCode Source Map](source-map.md#why-some-paths-say-opencode); public commands are routed through MendCode-owned control-plane modules.
 
 ## Lineage
 
diff --git a/docs/changes-review.md b/docs/changes-review.md
index 2150c09d..e27244d8 100644
--- a/docs/changes-review.md
+++ b/docs/changes-review.md
@@ -176,24 +176,6 @@ record. Clearing the active review state clears the cache for that workspace.
 Durable review artifacts can be added later if comments need to survive process
 restart, sync across terminals, or become part of a PR/review workflow.
 
-## Source Map
-
-- `src/mendcode/packages/opencode/src/cli/cmd/tui/routes/changes/index.tsx`:
-  route shell, loading, key handling, reload, comments, and responsive layout.
-- `src/mendcode/packages/opencode/src/cli/cmd/tui/routes/changes/load-diff.ts`:
-  tracked and untracked diff loading.
-- `src/mendcode/packages/opencode/src/cli/cmd/tui/routes/changes/review-state.ts`:
-  parsed files, diff blocks, lines, selection, stats, and navigation.
-- `src/mendcode/packages/opencode/src/cli/cmd/tui/routes/changes/review-comments.ts`:
-  comment creation, filtering, clearing, and stale-anchor reconciliation.
-- `src/mendcode/packages/opencode/src/cli/cmd/tui/routes/changes/review-context.ts`:
-  bounded assistant summaries and optional selected-file patch access.
-- `src/mendcode/packages/opencode/src/cli/cmd/tui/routes/changes/review-actions.ts`:
-  process-local active review registry, local cache bridge, and imperative
-  actions.
-- `src/mendcode/packages/opencode/src/cli/cmd/tui/routes/changes/renderer-adapter.tsx`:
-  header, file navigation, diff renderer, inline comments, and keybind bar.
-- `src/mendcode/packages/opencode/src/tool/review.ts`: assistant-facing
-  `review` tool.
-- `src/mendcode/packages/opencode/src/session/prompt.ts`: injects
-  `<mendcode_review_context>` into model turns when a review is active.
+## Implementation paths
+
+See [MendCode Source Map — Changes Review](source-map.md#tui-pages-and-product-surfaces) for the route, diff state, comments, renderer, tool, and prompt-context files. Paths are centralized there so this page remains readable for operators.
diff --git a/docs/features.md b/docs/features.md
index d1473a41..163507fa 100644
--- a/docs/features.md
+++ b/docs/features.md
@@ -530,19 +530,6 @@ For a README, website, or creator demo, show these in order:
 11. Packages show how a team shares commands, agents, modes, skills, prompts, TUI profile, widgets, permissions, memory defaults, and worktree policy.
 12. mflow/TSM/worktree surfaces show parallel workflow coordination.
 
-## Source Map
-
-- `src/mendcode/packages/opencode/src/mend/cli/public-bin.ts`: public `mendcode` command router and help.
-- `src/mendcode/packages/opencode/src/config/keybinds.ts`: default keybindings such as `Shift+Tab`, `Tab`, `F2`, and `F3`.
-- `src/mendcode/packages/opencode/src/cli/cmd/tui/app.tsx`: command palette entries, slash commands, route registration, and MendCode TUI actions.
-- `src/mendcode/packages/opencode/src/mend/profile.ts`: TUI profile schema and defaults.
-- `src/mendcode/packages/opencode/src/mend/tui/`: prompt chrome, prompt status, presentation, mascot, and profile actions.
-- `src/mendcode/packages/opencode/src/tool/plan-review.ts`: Plan Mode tool and post-approval agent switch.
-- `src/mendcode/packages/opencode/src/cli/cmd/tui/routes/session/plan-review.tsx`: Plan Review modal UI.
-- `src/mendcode/packages/opencode/src/cli/cmd/tui/routes/stats/index.tsx`: Usage Insights route.
-- `src/mendcode/packages/opencode/src/cli/cmd/tui/util/usage-insights.ts`: Usage Insights aggregation.
-- `src/mendcode/packages/opencode/src/mend/memory/`: memory config, store, retrieval, proposals, graph, Dream, side chat, workspaces, and category policy.
-- `src/mendcode/packages/opencode/src/cli/cmd/tui/routes/memory/index.tsx`: route-level Memory page.
-- `src/mendcode/packages/opencode/src/mend/runtime/pack.ts`: runtime package snapshot creation.
-- `src/mendcode/packages/opencode/src/mend/runtime/packages.ts`: installed/enabled package projection.
-- `src/mendcode/packages/plugin/src/tui.ts`: public TUI plugin/widget type contract.
+## Implementation paths
+
+The implementation and test paths for all product surfaces are maintained in the dedicated [MendCode Source Map](source-map.md). This feature page stays focused on behavior and user-visible contracts.
diff --git a/docs/mermaid-ascii-rendering.md b/docs/mermaid-ascii-rendering.md
index a519e7dc..497c51bb 100644
--- a/docs/mermaid-ascii-rendering.md
+++ b/docs/mermaid-ascii-rendering.md
@@ -1,6 +1,6 @@
 # Mermaid ASCII Rendering
 
-MendCode renders Mermaid fences as local, terminal-native ASCII diagrams in Markdown and rich chat presentation modes. The renderer keeps diagram semantics visible without requiring a browser, SVG canvas, or network request.
+MendCode renders Mermaid fences as local, terminal-native ASCII diagrams in Markdown and rich chat presentation modes. The renderer keeps diagram semantics visible without requiring a browser, SVG canvas, or network request. This page reflects the current v0.1.38 behavior; it is documentation-only and does not require a version bump.
 
 ## Chat Canvas Behavior
 
@@ -12,12 +12,17 @@ Every rendered Mermaid diagram is placed in its own bounded chat canvas:
 - Shift-wheel or the horizontal scrollbar pans the canvas directly.
 - Diagrams taller than 28 rows use an internal vertical viewport.
 - The viewport does not clip the generated ASCII geometry; supported diagrams retain their generated nodes, labels, fields, and connectors behind local scrolling when necessary.
+- During streaming, stable Markdown segments keep completed cards in place while the active tail continues to update; each card can recover its original Mermaid source in message order.
+
+## Catalog interaction
+
+Every fixture below is expanded on first load so the expected output is immediately visible. Use the fixture summary to collapse an individual diagram when comparing several examples. The expanded state is part of the documentation contract and is covered by the executable Markdown/TUI test.
 
 Terminal cells have a fixed font size, so the controls perform semantic layout zoom rather than bitmap scaling. If a diagram cannot fit without losing information, the card preserves the full geometry and exposes local scrolling.
 
 ## Coverage Contract
 
-The canonical executable coverage is in [`markdown-render.test.ts`](../src/mendcode/packages/opencode/test/cli/tui/markdown-render.test.ts). It checks:
+The canonical executable coverage is the Markdown/TUI regression suite listed in the [MendCode Source Map](source-map.md#tests-docs-and-release-references). It checks:
 
 - every supported Mermaid family;
 - expanded flowchart shapes;
@@ -27,7 +32,7 @@ The canonical executable coverage is in [`markdown-render.test.ts`](../src/mendc
 - safe handling of Mermaid metadata;
 - bounded per-card viewport behavior and source-to-card ordering.
 
-The catalog below is generated from the same fixture set used for visual QA. Each section shows the exact text canvas expected from MendCode.
+The catalog below is kept in sync with the fixture set used for visual QA. Each section shows the exact text canvas expected from MendCode.
 
 ## Rendered Fixture Catalog
 
@@ -35,7 +40,7 @@ The catalog below is generated from the same fixture set used for visual QA. Eac
 
 ### `flowchart`
 
-<details>
+<details open>
 <summary>Expected MendCode ASCII output</summary>
 
 ```text
@@ -64,7 +69,7 @@ The catalog below is generated from the same fixture set used for visual QA. Eac
 
 ### `swimlane-beta`
 
-<details>
+<details open>
 <summary>Expected MendCode ASCII output</summary>
 
 ```text
@@ -88,7 +93,7 @@ The catalog below is generated from the same fixture set used for visual QA. Eac
 
 ### `sequenceDiagram`
 
-<details>
+<details open>
 <summary>Expected MendCode ASCII output</summary>
 
 ```text
@@ -110,7 +115,7 @@ The catalog below is generated from the same fixture set used for visual QA. Eac
 
 ### `classDiagram`
 
-<details>
+<details open>
 <summary>Expected MendCode ASCII output</summary>
 
 ```text
@@ -127,7 +132,7 @@ The catalog below is generated from the same fixture set used for visual QA. Eac
 
 ### `stateDiagram-v2`
 
-<details>
+<details open>
 <summary>Expected MendCode ASCII output</summary>
 
 ```text
@@ -162,7 +167,7 @@ The catalog below is generated from the same fixture set used for visual QA. Eac
 
 ### `erDiagram`
 
-<details>
+<details open>
 <summary>Expected MendCode ASCII output</summary>
 
 ```text
@@ -179,7 +184,7 @@ The catalog below is generated from the same fixture set used for visual QA. Eac
 
 ### `journey`
 
-<details>
+<details open>
 <summary>Expected MendCode ASCII output</summary>
 
 ```text
@@ -199,7 +204,7 @@ The catalog below is generated from the same fixture set used for visual QA. Eac
 
 ### `gantt`
 
-<details>
+<details open>
 <summary>Expected MendCode ASCII output</summary>
 
 ```text
@@ -217,7 +222,7 @@ The catalog below is generated from the same fixture set used for visual QA. Eac
 
 ### `pie`
 
-<details>
+<details open>
 <summary>Expected MendCode ASCII output</summary>
 
 ```text
@@ -234,7 +239,7 @@ The catalog below is generated from the same fixture set used for visual QA. Eac
 
 ### `quadrantChart`
 
-<details>
+<details open>
 <summary>Expected MendCode ASCII output</summary>
 
 ```text
@@ -269,7 +274,7 @@ The catalog below is generated from the same fixture set used for visual QA. Eac
 
 ### `requirementDiagram`
 
-<details>
+<details open>
 <summary>Expected MendCode ASCII output</summary>
 
 ```text
@@ -288,7 +293,7 @@ The catalog below is generated from the same fixture set used for visual QA. Eac
 
 ### `gitGraph`
 
-<details>
+<details open>
 <summary>Expected MendCode ASCII output</summary>
 
 ```text
@@ -308,7 +313,7 @@ The catalog below is generated from the same fixture set used for visual QA. Eac
 
 ### `C4Context`
 
-<details>
+<details open>
 <summary>Expected MendCode ASCII output</summary>
 
 ```text
@@ -324,7 +329,7 @@ The catalog below is generated from the same fixture set used for visual QA. Eac
 
 ### `mindmap`
 
-<details>
+<details open>
 <summary>Expected MendCode ASCII output</summary>
 
 ```text
@@ -344,7 +349,7 @@ The catalog below is generated from the same fixture set used for visual QA. Eac
 
 ### `timeline`
 
-<details>
+<details open>
 <summary>Expected MendCode ASCII output</summary>
 
 ```text
@@ -367,7 +372,7 @@ The catalog below is generated from the same fixture set used for visual QA. Eac
 
 ### `zenuml`
 
-<details>
+<details open>
 <summary>Expected MendCode ASCII output</summary>
 
 ```text
@@ -390,7 +395,7 @@ The catalog below is generated from the same fixture set used for visual QA. Eac
 
 ### `sankey`
 
-<details>
+<details open>
 <summary>Expected MendCode ASCII output</summary>
 
 ```text
@@ -410,7 +415,7 @@ The catalog below is generated from the same fixture set used for visual QA. Eac
 
 ### `xychart-beta`
 
-<details>
+<details open>
 <summary>Expected MendCode ASCII output</summary>
 
 ```text
@@ -440,7 +445,7 @@ The catalog below is generated from the same fixture set used for visual QA. Eac
 
 ### `block-beta`
 
-<details>
+<details open>
 <summary>Expected MendCode ASCII output</summary>
 
 ```text
@@ -456,7 +461,7 @@ The catalog below is generated from the same fixture set used for visual QA. Eac
 
 ### `packet-beta`
 
-<details>
+<details open>
 <summary>Expected MendCode ASCII output</summary>
 
 ```text
@@ -474,7 +479,7 @@ The catalog below is generated from the same fixture set used for visual QA. Eac
 
 ### `kanban`
 
-<details>
+<details open>
 <summary>Expected MendCode ASCII output</summary>
 
 ```text
@@ -494,7 +499,7 @@ The catalog below is generated from the same fixture set used for visual QA. Eac
 
 ### `architecture-beta`
 
-<details>
+<details open>
 <summary>Expected MendCode ASCII output</summary>
 
 ```text
@@ -518,7 +523,7 @@ The catalog below is generated from the same fixture set used for visual QA. Eac
 
 ### `radar-beta`
 
-<details>
+<details open>
 <summary>Expected MendCode ASCII output</summary>
 
 ```text
@@ -534,7 +539,7 @@ The catalog below is generated from the same fixture set used for visual QA. Eac
 
 ### `eventmodeling`
 
-<details>
+<details open>
 <summary>Expected MendCode ASCII output</summary>
 
 ```text
@@ -563,7 +568,7 @@ The catalog below is generated from the same fixture set used for visual QA. Eac
 
 ### `treemap-beta`
 
-<details>
+<details open>
 <summary>Expected MendCode ASCII output</summary>
 
 ```text
@@ -582,7 +587,7 @@ The catalog below is generated from the same fixture set used for visual QA. Eac
 
 ### `venn-beta`
 
-<details>
+<details open>
 <summary>Expected MendCode ASCII output</summary>
 
 ```text
@@ -613,7 +618,7 @@ The catalog below is generated from the same fixture set used for visual QA. Eac
 
 ### `ishikawa-beta`
 
-<details>
+<details open>
 <summary>Expected MendCode ASCII output</summary>
 
 ```text
@@ -644,7 +649,7 @@ The catalog below is generated from the same fixture set used for visual QA. Eac
 
 ### `wardley-beta`
 
-<details>
+<details open>
 <summary>Expected MendCode ASCII output</summary>
 
 ```text
@@ -677,7 +682,7 @@ The catalog below is generated from the same fixture set used for visual QA. Eac
 
 ### `cynefin-beta`
 
-<details>
+<details open>
 <summary>Expected MendCode ASCII output</summary>
 
 ```text
@@ -717,7 +722,7 @@ The catalog below is generated from the same fixture set used for visual QA. Eac
 
 ### `treeView-beta`
 
-<details>
+<details open>
 <summary>Expected MendCode ASCII output</summary>
 
 ```text
@@ -745,7 +750,7 @@ The catalog below is generated from the same fixture set used for visual QA. Eac
 
 ### `STRESS · swimlane 4 lanes`
 
-<details>
+<details open>
 <summary>Expected MendCode ASCII output</summary>
 
 ```text
@@ -779,7 +784,7 @@ The catalog below is generated from the same fixture set used for visual QA. Eac
 
 ### `STRESS · class relation matrix`
 
-<details>
+<details open>
 <summary>Expected MendCode ASCII output</summary>
 
 ```text
@@ -812,7 +817,7 @@ The catalog below is generated from the same fixture set used for visual QA. Eac
 
 ### `STRESS · state branches and terminal`
 
-<details>
+<details open>
 <summary>Expected MendCode ASCII output</summary>
 
 ```text
@@ -856,7 +861,7 @@ The catalog below is generated from the same fixture set used for visual QA. Eac
 
 ### `STRESS · ER fields and cross-links`
 
-<details>
+<details open>
 <summary>Expected MendCode ASCII output</summary>
 
 ```text
@@ -888,7 +893,7 @@ The catalog below is generated from the same fixture set used for visual QA. Eac
 
 ### `STRESS · journey multi-section`
 
-<details>
+<details open>
 <summary>Expected MendCode ASCII output</summary>
 
 ```text
@@ -924,7 +929,7 @@ The catalog below is generated from the same fixture set used for visual QA. Eac
 
 ### `STRESS · gantt dependencies`
 
-<details>
+<details open>
 <summary>Expected MendCode ASCII output</summary>
 
 ```text
@@ -949,7 +954,7 @@ The catalog below is generated from the same fixture set used for visual QA. Eac
 
 ### `STRESS · quadrant labels and points`
 
-<details>
+<details open>
 <summary>Expected MendCode ASCII output</summary>
 
 ```text
@@ -984,7 +989,7 @@ The catalog below is generated from the same fixture set used for visual QA. Eac
 
 ### `STRESS · requirement relations`
 
-<details>
+<details open>
 <summary>Expected MendCode ASCII output</summary>
 
 ```text
@@ -1005,7 +1010,7 @@ The catalog below is generated from the same fixture set used for visual QA. Eac
 
 ### `STRESS · git branches and merge`
 
-<details>
+<details open>
 <summary>Expected MendCode ASCII output</summary>
 
 ```text
@@ -1025,7 +1030,7 @@ The catalog below is generated from the same fixture set used for visual QA. Eac
 
 ### `STRESS · mixed XY`
 
-<details>
+<details open>
 <summary>Expected MendCode ASCII output</summary>
 
 ```text
@@ -1055,7 +1060,7 @@ The catalog below is generated from the same fixture set used for visual QA. Eac
 
 ### `STRESS · radar 6 axes`
 
-<details>
+<details open>
 <summary>Expected MendCode ASCII output</summary>
 
 ```text
@@ -1092,7 +1097,7 @@ The catalog below is generated from the same fixture set used for visual QA. Eac
 
 ### `STRESS · deep TreeView`
 
-<details>
+<details open>
 <summary>Expected MendCode ASCII output</summary>
 
 ```text
@@ -1144,7 +1149,7 @@ The catalog below is generated from the same fixture set used for visual QA. Eac
 
 ### `LONG FLOWCHART (120 NODES)`
 
-<details>
+<details open>
 <summary>Expected MendCode ASCII output</summary>
 
 ```text
@@ -1879,7 +1884,7 @@ The catalog below is generated from the same fixture set used for visual QA. Eac
 
 ### `CYCLES AND BRANCHES`
 
-<details>
+<details open>
 <summary>Expected MendCode ASCII output</summary>
 
 ```text
@@ -1922,7 +1927,7 @@ The catalog below is generated from the same fixture set used for visual QA. Eac
 
 ### `ADVERSARIAL METADATA`
 
-<details>
+<details open>
 <summary>Expected MendCode ASCII output</summary>
 
 ```text
diff --git a/docs/plan-mode.md b/docs/plan-mode.md
index 2e09c2be..ac8cd733 100644
--- a/docs/plan-mode.md
+++ b/docs/plan-mode.md
@@ -86,8 +86,6 @@ Use this behavior to separate planning from writing:
 - Implementation agents should edit files only after approval.
 - If the user edits or rejects the plan, the edited Markdown or rejection reason overrides the previous draft.
 
-## Source Map
+## Implementation paths
 
-- `src/mendcode/packages/opencode/src/tool/plan-review.ts`: tool schema, approve/edit/reject handling, and implementation-agent switch.
-- `src/mendcode/packages/opencode/src/cli/cmd/tui/routes/session/plan-review.tsx`: modal UI, preview/edit/comment/reject stages, keyboard handling, and Markdown rendering.
-- `src/mendcode/packages/opencode/src/session/prompt/plan.txt`: agent instruction to use `plan_review` instead of asking for approval in prose.
+See [MendCode Source Map — TUI pages and product surfaces](source-map.md#tui-pages-and-product-surfaces) for the Plan Review tool, modal, and prompt-instruction files.
diff --git a/docs/source-map.md b/docs/source-map.md
new file mode 100644
index 00000000..bb8bf27d
--- /dev/null
+++ b/docs/source-map.md
@@ -0,0 +1,90 @@
+# MendCode Source Map
+
+This page is for contributors and maintainers who need to find the implementation behind a MendCode feature. If you are learning how to use MendCode, start with the [user documentation](README.md) or the [Feature Map](features.md) instead.
+
+## Why some paths say `opencode`
+
+`src/mendcode/packages/opencode/` is the internal runtime package directory. MendCode owns the public command surface and the product layers around that runtime, while the package name preserves the upstream OpenCode lineage. It does **not** mean that users should run a second product or use an `opencode` command.
+
+- Public users run `mendcode`.
+- MendCode configuration and control-plane modules are under `src/mendcode/packages/opencode/src/mend/`.
+- The underlying runtime and compatibility boundary remain under `src/mendcode/packages/opencode/src/`.
+- The development-only `mend` shim is not the public installation contract.
+- Lineage and licensing details live in [Architecture and Packages](architecture.md#lineage) and [ACKNOWLEDGEMENTS.md](../ACKNOWLEDGEMENTS.md).
+
+## Start with the right boundary
+
+| Need | Start here |
+| --- | --- |
+| Add or change a public CLI command | `src/mendcode/packages/opencode/src/mend/cli/public-bin.ts` |
+| Change setup, project config, models, permissions, or prompt modes | `src/mendcode/packages/opencode/src/mend/config/`, `src/mendcode/packages/opencode/src/mend/profile.ts`, `src/mendcode/packages/opencode/src/mend/prompt/` |
+| Change a TUI page or route | `src/mendcode/packages/opencode/src/cli/cmd/tui/routes/` |
+| Change session automation or streaming | `src/mendcode/packages/opencode/src/cli/cmd/session.ts`, `src/mendcode/packages/opencode/src/cli/cmd/run.ts`, `src/mendcode/packages/opencode/src/cli/automation.ts` |
+| Change a tool or model-facing contract | `src/mendcode/packages/opencode/src/tool/` and `src/mendcode/packages/opencode/src/session/` |
+| Change a plugin, widget, or extension API | `src/mendcode/packages/plugin/src/` and the corresponding TUI host under `src/mendcode/packages/opencode/src/cli/cmd/tui/plugin/` |
+| Change package distribution or runtime snapshots | `src/mendcode/packages/opencode/src/mend/runtime/` |
+| Change release assets or public readiness | `src/mendcode/packages/script/`, `.github/workflows/`, and `docs/releasing.md` |
+
+## Public CLI and control plane
+
+- `src/mendcode/packages/opencode/src/mend/cli/public-bin.ts`: public `mendcode` command router and help surface.
+- `src/mendcode/packages/opencode/src/mend/config/project.ts`: project configuration, focus profiles, generated runtime config, and package metadata.
+- `src/mendcode/packages/opencode/src/mend/config/models.ts`: model roles, projection, and shared prompt-model precedence.
+- `src/mendcode/packages/opencode/src/mend/config/permissions.ts`: permission mode and smart-reviewer role configuration.
+- `src/mendcode/packages/opencode/src/mend/prompt/mode.ts`: `minimal`, `focus`, `full`, and project-local `custom` prompt modes.
+- `src/mendcode/packages/opencode/src/mend/prompt/custom.ts`: bounded, root-safe `.mendcode/prompts/custom.md` loader.
+- `src/mendcode/packages/opencode/src/cli/cmd/session.ts`: session create/send/inspect/wait/events/cancel lifecycle.
+- `src/mendcode/packages/opencode/src/cli/automation.ts`: versioned `mendcode.cli.v1` envelopes and secret-like field redaction.
+- `src/mendcode/packages/opencode/src/cli/cmd/run.ts` and `src/mendcode/packages/opencode/src/cli/model-selection.ts`: headless streaming and shared model/agent resolution.
+
+## TUI pages and product surfaces
+
+- `src/mendcode/packages/opencode/src/cli/cmd/tui/app.tsx`: TUI shell, command palette entries, slash aliases, and route registration.
+- `src/mendcode/packages/opencode/src/cli/cmd/tui/routes/changes/`: Changes Review loading, diff state, comments, responsive renderer, and review context. The key files are `index.tsx`, `load-diff.ts`, `review-state.ts`, `review-comments.ts`, `review-context.ts`, `review-actions.ts`, and `renderer-adapter.tsx`.
+- `src/mendcode/packages/opencode/src/cli/cmd/tui/routes/session/plan-review.tsx`: Plan Review modal and its approve/edit/comment/reject stages.
+- `src/mendcode/packages/opencode/src/tool/plan-review.ts`: Plan Review tool schema and implementation-agent switch.
+- `src/mendcode/packages/opencode/src/tool/review.ts`: assistant-facing Changes Review tool.
+- `src/mendcode/packages/opencode/src/session/prompt.ts`: active review context injection into model turns.
+- `src/mendcode/packages/opencode/src/session/prompt/plan.txt`: Plan Review instruction for planning agents.
+- `src/mendcode/packages/opencode/src/cli/cmd/tui/routes/loops/`: Loop Workflows dashboard and operator controls.
+- `src/mendcode/packages/opencode/src/cli/cmd/tui/routes/memory/index.tsx`: Memory Center route, category policy, Dream panel, inspector, and side agent.
+- `src/mendcode/packages/opencode/src/cli/cmd/tui/routes/stats/index.tsx`: Usage Insights route, scope handling, cache, shortcuts, and weather integration.
+- `src/mendcode/packages/opencode/src/cli/cmd/tui/util/usage-insights.ts`: Usage Insights aggregation and normalization.
+- `src/mendcode/packages/opencode/src/cli/cmd/tui/component/styled-plan-markdown.tsx`: stable Markdown presentation, Mermaid cards, local viewport controls, and source-to-card recovery.
+- `src/mendcode/packages/opencode/src/cli/cmd/tui/util/markdown-render.ts`: Markdown/streaming rendering and Mermaid ASCII card generation.
+- `src/mendcode/packages/opencode/src/mend/profile.ts` and `src/mendcode/packages/opencode/src/mend/tui/`: TUI profile, prompt chrome, status, presentation, mascot, and customization actions.
+
+## Sessions, loops, and coordination
+
+- `src/mendcode/packages/opencode/src/session/loop.ts`: Loop Workflow model and lifecycle state.
+- `src/mendcode/packages/opencode/src/session/loop-runner.ts`: loop wakeup and iteration execution.
+- `src/mendcode/packages/opencode/src/tool/loop.ts`: assistant-facing loop tool contract.
+- `src/mendcode/packages/opencode/src/mend/runtime/loop-service.ts`: durable loop service, status, activation, and run state.
+- `src/mendcode/packages/opencode/src/mend/cli/control-plane.ts`: public loop CLI controls and service lifecycle.
+- `src/mendcode/packages/opencode/src/server/routes/instance/loop.ts` and `src/mendcode/packages/opencode/src/server/routes/instance/httpapi/handlers/loop.ts`: loop read/control route stacks.
+- `src/mendcode/packages/opencode/src/mend/config/mflow.ts`: local-first mflow setup, relay configuration, and edit locks.
+- `src/mendcode/packages/opencode/src/mend/config/tsm.ts` and `src/mendcode/packages/opencode/src/mend/config/worktree.ts`: optional TSM/worktree lifecycle, previews, and safety registry.
+
+## Memory, packages, providers, and extensions
+
+- `src/mendcode/packages/opencode/src/mend/memory/`: approval-gated storage, proposals, retrieval, graph, Dream, side chat, workspaces, and category policy.
+- `src/mendcode/packages/opencode/src/mend/runtime/pack.ts`: runtime package snapshot creation.
+- `src/mendcode/packages/opencode/src/mend/runtime/packages.ts`: installed/enabled package projection.
+- `src/mendcode/packages/opencode/src/provider/claude-code.ts`: local Claude Code CLI provider bridge and validation.
+- `src/mendcode/packages/plugin/src/tui.ts`: public plugin/widget type contract.
+- `src/mendcode/packages/opencode/src/cli/cmd/tui/plugin/`: TUI plugin host, slots, routes, commands, dialogs, themes, and runtime registration.
+
+## Tests, docs, and release references
+
+- `src/mendcode/packages/opencode/test/cli/tui/`: executable coverage for Markdown, Mermaid, TUI pages, and interaction contracts.
+- `src/mendcode/packages/opencode/test/tui/usage-insights.test.ts`: Usage Insights aggregation and selected-day regression coverage.
+- `docs/`: public behavior, setup, feature, page, release, and security documentation.
+- `src/mendcode/packages/script/` and `.github/workflows/`: release helpers, asset assembly, provenance, and CI gates.
+
+## Related documentation
+
+- [Architecture and Packages](architecture.md): ownership, runtime boundary, repository layout, and safety model.
+- [CLI, Setup, and Configuration](cli-setup-configuration.md): public commands and user-facing configuration.
+- [TUI Plugins and Widgets](tui-plugins-and-widgets.md): supported extension API.
+- [Releasing MendCode](releasing.md): installer and release workflow.
+- [Lineage and acknowledgements](../ACKNOWLEDGEMENTS.md): upstream attribution and licensing.
diff --git a/docs/tui-plugins-and-widgets.md b/docs/tui-plugins-and-widgets.md
index df06e2d4..c37bd97f 100644
--- a/docs/tui-plugins-and-widgets.md
+++ b/docs/tui-plugins-and-widgets.md
@@ -2,7 +2,7 @@
 
 MendCode TUI plugins are local or packaged JavaScript/TypeScript modules that extend the terminal UI without editing runtime internals. They are the right place for company dashboards, status lines, prompt-side context, custom footers, command palettes, dialogs, routes, themes, shell-backed widgets, and editor widgets.
 
-The public API is exported from `@mendcode/plugin/tui`. The active host implementation lives in `src/mendcode/packages/opencode/src/cli/cmd/tui/plugin/`, and the type contract lives in `src/mendcode/packages/plugin/src/tui.ts`. For assistant-facing custom tool calls, see [Custom Tool Calls](custom-tool-calls.md).
+The public API is exported from `@mendcode/plugin/tui`. The host implementation and type contract are listed in the [MendCode Source Map](source-map.md#memory-packages-providers-and-extensions). For assistant-facing custom tool calls, see [Custom Tool Calls](custom-tool-calls.md).
 
 ## Register a Plugin
 
diff --git a/docs/usage-insights.md b/docs/usage-insights.md
index 61bc9b87..30cb8b92 100644
--- a/docs/usage-insights.md
+++ b/docs/usage-insights.md
@@ -131,9 +131,6 @@ Current aggregation includes session/message metadata available to the TUI:
 
 If a provider or session does not supply a field, that field may be zero or absent. That is better than inventing a number.
 
-## Source Map
+## Implementation paths
 
-- `src/mendcode/packages/opencode/src/cli/cmd/tui/app.tsx`: command palette entries and slash aliases.
-- `src/mendcode/packages/opencode/src/cli/cmd/tui/routes/stats/index.tsx`: Usage Insights route, responsive layout, shortcuts, cache, scope handling, and weather integration.
-- `src/mendcode/packages/opencode/src/cli/cmd/tui/util/usage-insights.ts`: aggregation and normalization for days, totals, tools, agents, models, token mix, duration, cache data, selected-day detail, and streaks.
-- `src/mendcode/packages/opencode/test/tui/usage-insights.test.ts`: regression coverage for token aggregation, user words, response time, tools, active-day streaks, selected-day activity, and normalized cache input.
+See [MendCode Source Map — TUI pages and product surfaces](source-map.md#tui-pages-and-product-surfaces) for the route, aggregation, command-palette, and regression-test files.
diff --git a/src/mendcode/packages/opencode/test/cli/tui/markdown-render.test.ts b/src/mendcode/packages/opencode/test/cli/tui/markdown-render.test.ts
index be200af7..33b66e91 100644
--- a/src/mendcode/packages/opencode/test/cli/tui/markdown-render.test.ts
+++ b/src/mendcode/packages/opencode/test/cli/tui/markdown-render.test.ts
@@ -173,6 +173,8 @@ test("public Mermaid ASCII documentation includes the complete visual fixture ca
   expect(documentation.match(/^### `/gm)).toHaveLength(fixtureNames.length)
   expect(documentation).toContain("[Fit]")
   expect(documentation).toContain("LONG FLOWCHART (120 NODES)")
+  expect(documentation.match(/^<details open>$/gm)).toHaveLength(fixtureNames.length)
+  expect(documentation).not.toMatch(/^<details>$/m)
 })
 
 test("stable text mode keeps markdown renderer for inline formatting", () => {