Narrative Chapters & Reading Levels
Relevant source files
The following files were used as context for generating this wiki page:
The Narrative Chapters and Reading Levels system organizes complex architectural diagrams into a structured, multi-layered guide. This framework allows readers to navigate the GestaltView Master Wiki through seven distinct thematic chapters and three specific levels of technical depth. The system prioritizes context preservation while enabling progressive disclosure of technical details.
Sources: README.md:22-26, diagram_inventory.json:20-65
Narrative Chapters
The project organizes 54 visuals into seven narrative chapters. Each chapter contains a title, a story-oriented title, and a "dek" (a short summary) to provide thematic context. These chapters guide the user through the lifecycle of a thought, from initial capture to final artifact creation and governance.
Chapter Organization
The builder script and inventory file define the sequence and metadata for these chapters. Each visual item in the repository is assigned a chapter_id to ensure it appears in the correct section of the interactive guide.
The diagram shows the sequential flow of narrative chapters as defined in the system metadata.
| Chapter ID | Title | Story Title | Purpose |
|---|---|---|---|
foundation | The recognition gap | Why being seen needs infrastructure | Introduces the need for context preservation. |
capture | Capture and rooms | A thought gets somewhere safe to land | Details the ingestion and spatial room models. |
continuity | Memory and continuity | Memory is more than finding a sentence | Explains vector retrieval and temporal context. |
companions | Billy and collaboration | Help is a system of roles | Describes agent orchestration and skills. |
creation | Creation and artifacts | An artifact passes through a gate | Outlines the rendering and validation pipeline. |
governance | Governance and evidence | Safety is part of the architecture | Details invariants and access controls. |
topology | The map behind the map | The filing cabinet, with its drawers | Maps repository structures to code entities. |
Sources: diagram_inventory.json:20-65, build_story_artifact.py:51-96
Reading Levels (Depth Lenses)
The system provides three reading levels, or "depth lenses," for every curated diagram. These levels filter the explanatory text to match the reader's needs. The story_template.html file manages the state of the active level and updates the UI dynamically.
Levels of Depth
- Get Oriented (Orientation): Uses plain language to explain what the system does and why its pieces matter.
- Understand the System (System): Focuses on product surfaces, roles, data movement, and system boundaries.
- Explore the Architecture (Architecture): Provides technical details on runtime relationships, implementation labels, and source code mappings.
The sequence diagram illustrates how the application switches between reading levels to change the displayed technical depth.
Sources: README.md:22-26, story_template.html:213-217, build_story_artifact.py:98-163
Data Mapping and Implementation
The implementation relies on a mapping between visual items and their chapter/level metadata. The build_story_artifact.py script assembles these relationships into a single JSON payload.
Level Switching Logic
In story_template.html, the activeLevel variable dictates which string from the explanations object is shown. When a user clicks a "lens-tab", the system updates the explanation-text element.
// Example of level switching logic in the template
main.querySelectorAll('[data-lens]').forEach(button => button.addEventListener('click', () => {
activeLevel = button.dataset.lens;
document.getElementById('level-chip').textContent = levels[activeLevel].label;
document.getElementById('explanation-text').textContent = item.explanations[activeLevel];
}));
Sources: story_template.html:252-262, build_story_artifact.py:348-355
Key Idea Selectors
For the 13 curated diagrams, the system includes "Key Idea" selectors. These are not spatial coordinates but text-based reading aids. They provide focused explanations for specific parts of a diagram within the context of the currently selected reading level.
Sources: README.md:27-28, diagram_inventory.json:11-12, story_template.html:246-251
The Narrative Chapters and Reading Levels provide a structured entry point for developers and users. This dual-axis navigation (thematic chapter vs. technical depth) ensures that the 116-page source PDF is accessible without overwhelming the reader.
Sources: README.md:1-8, build_story_artifact.py:365-370