codemble 0.3.1__tar.gz → 0.4.0__tar.gz

{codemble-0.3.1 → codemble-0.4.0}/.github/workflows/ci.yml

@@ -10,7 +10,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v7
-      - uses: actions/setup-python@v5
+      - uses: actions/setup-python@v6
         with:
           python-version: "3.11"
       - name: Install
@@ -23,7 +23,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v7
-      - uses: actions/setup-node@v4
+      - uses: actions/setup-node@v7
         with:
           node-version: "22"
       - name: astro check
@@ -35,7 +35,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v7
-      - uses: actions/setup-node@v4
+      - uses: actions/setup-node@v7
         with:
           node-version: "22"
       - name: build web app
@@ -47,7 +47,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v7
-      - uses: actions/setup-python@v5
+      - uses: actions/setup-python@v6
         with:
           python-version: "3.11"
       - name: Build wheel and verify packaged SPA

{codemble-0.3.1 → codemble-0.4.0}/.github/workflows/pages.yml

@@ -22,16 +22,16 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v7
-      - uses: actions/setup-node@v4
+      - uses: actions/setup-node@v7
         with:
           node-version: "22"
-      - uses: actions/configure-pages@v5
+      - uses: actions/configure-pages@v6
       - name: Build Astro site
         run: |
           cd docs-site
           npm install
           npm run build
-      - uses: actions/upload-pages-artifact@v3
+      - uses: actions/upload-pages-artifact@v5
         with:
           path: docs-site/dist
   deploy:
@@ -42,4 +42,4 @@ jobs:
       url: ${{ steps.deployment.outputs.page_url }}
     steps:
       - id: deployment
-        uses: actions/deploy-pages@v4
+        uses: actions/deploy-pages@v5

{codemble-0.3.1 → codemble-0.4.0}/.gitignore

@@ -28,3 +28,9 @@ logs/
 .idea/
 .vscode/
 _to_delete/
+
+# graphify knowledge graph (build artifact, regenerate with: graphify update .)
+graphify-out/
+
+# Subagent-driven-development scratch coordination (not product truth)
+.superpowers/

{codemble-0.3.1 → codemble-0.4.0}/CHANGELOG.md

@@ -5,6 +5,120 @@ Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) · Versioning:
 
 ## [Unreleased]
 
+## [0.4.0] - 2026-07-20
+
+The galaxy read as flat spheres on a plain background, connections were hard to
+follow at any zoom level, and once a project was bound the only way to open a
+different one was killing the server. This release lands the redesign, adds a
+second way to look at the same graph, and puts what the parser already knew on
+screen.
+
+### Added
+- A second **Map** layer beside the galaxy, switchable from the header. Its
+  *Architecture* tab lays modules out as boxes grouped by directory and layered
+  by import distance from Home; its *Workflow* tab walks the call tree from your
+  entrypoint, where the first hop is the `defines` relation the parser recorded
+  and deeper hops are `calls`. Both layouts are computed by the parser-backed
+  graph layer and served by a new `GET /api/map`, so the map and the galaxy can
+  never disagree.
+- The Map layer is plain SVG and needs no WebGL, so a machine that cannot draw
+  the galaxy can still read the project.
+- The study panel now shows what the parser knows before any model is asked: a
+  structural summary rendered from parser facts through fixed templates, with no
+  key, no network, and no provider involved.
+- Grounded narration finally reaches the panel. The explanation endpoint had
+  shipped but was never called, so the narration block always rendered empty.
+- A Connections section lists every parser relationship into and out of the
+  selected structure, grouped inbound and outbound, each row stating direction,
+  certainty, and a `file:line` citation for where that structure is defined —
+  plus a small SVG diagram of callers, this structure, and callees. Clicking a
+  row opens that structure's study.
+- Local narration through Ollama, so a learner with no API key can still get
+  grounded prose without their source leaving the machine. It is explicit
+  opt-in (`CODEMBLE_PROVIDER=ollama`, or `provider = "ollama"` in
+  `~/.codemble/config`) with no auto-detection, the host is refused at
+  construction unless it is plain `http` on loopback, no credential is ever
+  sent, and the output passes exactly the same grounding validation as a cloud
+  provider. Honest caveat: that validation catches an invented identifier, not
+  a wrong claim about a real one, and smaller local models make the second kind
+  of mistake more often.
+- Guidance when no model is configured, including the local Ollama path, driven
+  by whether a loopback Ollama is actually reachable and which models it has.
+- An Easy/Expert audience toggle in the header. Easy uses plain language for
+  narration, check questions, panel labels, Lens notes, and the legend; Expert
+  keeps full terminology. The choice persists per project and never changes
+  graph truth, coordinates, progress, or how a check is scored.
+- Easy mode opens on the Map, hides galaxy links unrelated to the selected
+  structure, and shows a hint chip naming the nearest unlit region to Home. The
+  hint is counted in import-route hops over the graph; no model chooses it.
+- Switch project: a header control releases the current project and returns to
+  the picker, so a second project no longer needs a terminal.
+- Change Home: the entrypoint picker can be reopened whenever the parser ranked
+  at least one candidate, and the Home you select is remembered for the next run
+  of the same project.
+- Edge arrowheads below the galaxy level, hover tooltips on every edge naming
+  both structures, the relationship, its certainty and the line it was seen on,
+  and hover/selection highlighting.
+- First-run coach-marks explain what you see, how to move, and what lights
+  stars. Dismissing them is a local UI preference, not progress.
+- A clickable breadcrumb, and a legend naming dim, amber-understood, unchartable
+  syntax-error files, certain versus possible relationships, and one swatch per
+  language. It describes only the encodings the layer on screen actually draws:
+  size and brightness are galaxy-only, language tint appears at galaxy level and
+  on the Architecture tab, and the possible-relationship swatch dashes on the Map
+  to match the SVG while staying colour-only for the galaxy.
+- Correct check answers now get an affirmation, not just silence.
+- A `<noscript>` message and a React error boundary, so a render failure
+  explains itself and offers a reload instead of showing a blank page.
+
+### Changed
+- The galaxy gained depth: nodes carry a canvas-generated halo, an
+  `UnrealBloomPass` is tuned so lit amber blooms hard while the unlit ramp
+  barely registers, and a background starfield is seeded by hashing the
+  project's own file hashes — the same code always produces the same sky.
+- At galaxy level, Python, JavaScript and TypeScript systems sit in a faint
+  language-tinted nebula. A system in any other language renders no fog rather
+  than borrowing another language's hue.
+- Keyboard focus in the galaxy now carries a visible reticle as well as its
+  live text readout.
+- Passing a region's checks plays a 1.2s "nebula dawn" the next time you are at
+  galaxy level: amber washes across that system's halo and fog and recedes. The
+  lit state is already committed before it runs, so the animation celebrates a
+  fact rather than delivering it. `prefers-reduced-motion` skips it entirely and
+  goes straight to the finished lit state.
+- System orbits are laid out by call depth instead of by member index, so an
+  inner ring means "this runs first". Ring 1 is what the module's entry node
+  calls directly plus every member no sibling calls; members no certain call
+  reaches keep the outermost ring rather than being placed by guesswork. Only
+  certain calls decide placement. Layout coordinates changed once; saved
+  progress is unaffected because region signatures derive from file hashes, not
+  coordinates.
+- Drifting particles mark **certain** call edges only, at system and study
+  level. A possible call stays still, so motion can never imply proof.
+  `prefers-reduced-motion` stops them too.
+- Centrality now counts the distinct structures that call a node, not the call
+  sites they contain, so a helper hammered from one loop no longer outshines a
+  shared utility. The study panel's label follows: "Callers", not "Calls in".
+- The study panel leads with the structural summary and narration, then
+  connections, then source and lens notes.
+- The study level keeps the selected structure's connections visible instead of
+  dimming the whole scene.
+- A region with no safe check now explains that Codemble refuses to ask a
+  question the graph cannot answer, rather than only stating that none exists.
+- The zero-candidate Home screen no longer tells you to restart with a CLI
+  flag; every option is in the app.
+- The star chart labels studied counts "this session", which is what they have
+  always measured.
+
+### Fixed
+- The partial-parse notice rode a code path that never executed; it now renders
+  with the narration block, and the structural summary states it as well.
+- A failed graph load offered only "Restart Codemble and reload this page"; it
+  now retries in place.
+- Contributors only: pinned the docs site back to TypeScript 6.x. An automated
+  7.0.2 bump had broken the `astro check` CI gate, because TypeScript's native
+  7.x compiler does not yet expose the programmatic API that check relies on.
+
 ## [0.3.1] - 2026-07-19
 
 ### Changed

{codemble-0.3.1 → codemble-0.4.0}/CLAUDE.md

@@ -167,7 +167,7 @@ Polish, then the coordinated launch (Show HN / X; lit-galaxy GIF as hero).
 
 ## Current State **[AGENT-MAINTAINED]**
 
-**Current milestone: Phase 1 tester evidence** · Last updated: 2026-07-19 ·
+**Current milestone: Phase 1 tester evidence** · Last updated: 2026-07-20 ·
 Session note: architecture-deepening maintenance is complete after the verified
 v0.2.0 release; all four report recommendations are merged in phases while issue
 #13 remains open for human tester evidence. The public site was then redesigned
@@ -182,10 +182,21 @@ repository were affected and no region lost a check. The root README was then
 restructured around the learning loop, fast tester setup, correctness, and the
 local/AI boundary. Its top mark now uses self-contained, GitHub-safe motion with
 a static reduced-motion state; no product or app behavior changed. Bare
-`codemble` now serves a one-shot in-app project picker (home-jailed browse +
+`codemble` now serves an in-app project picker (home-jailed browse +
 recents, Host-header allowlisted) instead of the current directory; README,
 docs-site, the changelog, and a new PyPI release checklist now lead with
-`uvx codemble` ahead of the pending first PyPI publish.
+`uvx codemble` ahead of the pending first PyPI publish. A galaxy UX overhaul
+design was then interviewed and approved (spec
+`docs/superpowers/specs/2026-07-19-galaxy-ux-overhaul-design.md`): three phases —
+light up the shipped-but-inert narration/mode/connections surface plus project
+switching, then the "living cosmos" visual overhaul with a 2D Map layer, then
+~1,000-file scale with staged parse progress; four Decision Log entries record
+the approved Non-Goal and binding relaxations. Phase A (the narration/mode/
+connections surface and project switching) and Phase B (M12: call-depth
+orbits, the 2D Map layer, and the living-cosmos visual overhaul) have both
+since shipped. Phase C (~1,000-file scale with staged parse progress) has not
+started — there is still no threaded parse or parse-progress screen, and the
+scale cap remains ~300 files.
 
 ### M0 — Repo, docs & website scaffold ✅ (2026-07-19)
 - [x] Root: README, LICENSE (Apache-2.0), CoC, SECURITY, CONTRIBUTING,
@@ -309,6 +320,30 @@ intake avoids repeated discovery; learner transitions are tested above local HTT
 JS/TS certainty and concept evidence remain parser-proven through the unchanged
 `LanguageAdapter` interface.
 
+### M12 — Living cosmos + 2D map (galaxy UX overhaul, Phase B) ✅ (2026-07-20)
+- [x] System orbits by call depth from the region's entry node, hash-seeded and
+      deterministic; layout coordinates changed once, saved progress did not
+- [x] `GET /api/map`: deterministic Architecture and Workflow 2D layouts
+      computed in `codemble/graph/`, reading the same graph as `GET /api/graph`
+- [x] A 2D Map layer (Architecture + Workflow tabs) switchable from the header,
+      plain SVG, no WebGL dependency
+- [x] Canvas-generated halos, language-tinted nebulae, a hash-seeded starfield,
+      composited bloom, and drifting particles on certain call edges only
+- [x] The ~1.2s nebula-dawn light-up moment, with an instantly finished lit
+      state under reduced motion
+- [x] Easy mode defaults to the Map with reduced edge density and a
+      graph-derived hint chip; Expert defaults to the galaxy; an explicit
+      layer choice always beats the mode default
+- [x] First-run coach-marks, a clickable breadcrumb, and a language-tint
+      legend key
+
+**Acceptance:** the map and the galaxy read one graph and cannot disagree;
+uncertainty renders distinctly in both — colour-only in the 3D galaxy (no
+line-dash support there), genuinely dashed in the 2D map; region signatures
+hash file content, never coordinates, so the orbit relayout did not re-dim any
+region; reduced motion always yields the finished lit state with zero
+animation.
+
 ## Decision Log **[AGENT-MAINTAINED — append only]**
 
 | Date | Decision | Why |
@@ -360,14 +395,24 @@ JS/TS certainty and concept evidence remain parser-proven through the unchanged
 | 2026-07-19 | The root README uses a self-contained animated ensō mark; app icons and favicons remain static | GitHub strips page-level scripting, so motion belongs inside the referenced SVG. The loop is restrained to illumination, transforms, and opacity, and reduced-motion users receive the finished lit state |
 | 2026-07-19 | Bare `codemble` serves a one-shot in-app project picker (browse + recents) on a single two-phase server; binding is one-shot and the API is home-jailed with a Host-header allowlist | Approved by UD this session: easiest possible run flow for learners without a second server, without free filesystem enumeration, and without changing the one-graph app model |
 | 2026-07-19 | Codemble publishes to PyPI from the next tagged release; install collapses to `uvx codemble` | Approved by UD this session: the git+tag install was the biggest onboarding hurdle for the target learner |
+| 2026-07-19 | Local models (Ollama) are now allowed, reversing the 2026-07-18 Non-Goal; guardrails: loopback-and-`http`-only enforced at construction, explicit opt-in with no auto-detection, the same grounding validation applied to every provider, and the deterministic Tier 0 summary always available as a floor | Approved by UD this session. Residual risk stated honestly: grounding validation catches an invented identifier, not a wrong claim about a real one, and small local models make that second kind of error more often |
+| 2026-07-19 | A 2D Map layer (architecture + workflow-tree tabs) joins the 3D galaxy behind one switcher, superseding the "no second 2D renderer in v1" Non-Goal; layouts are computed deterministically in the graph layer and React stays a pure SVG renderer | Approved by UD in the galaxy UX overhaul interview (spec `docs/superpowers/specs/2026-07-19-galaxy-ux-overhaul-design.md`); beginners read flat maps more easily and the render-ready graph rule makes the second view cheap and truthful |
+| 2026-07-19 | Scale target raised to ~1,000 supported files with a worker-thread parse, polled staged progress, and an honest loading screen; the subdirectory prompt moves to the new cap | Approved by UD: a deliberate partial pull-forward of Phase 2 scale work; full LOD/clustering stays in Phase 2 |
+| 2026-07-19 | One-shot project binding relaxed to an explicit in-app reset (`POST /api/picker/reset`); home jail and Host allowlist unchanged | Approved by UD: learners must be able to switch projects without killing the server; per-project progress makes switching safe |
+| 2026-07-19 | App art direction is "living cosmos" within the Formal Edo palette: halo sprites, bloom, hash-seeded starfield, language-tinted nebulae, call-depth system orbits (layout bytes change once, still deterministic), and an Easy/Expert UI toggle riding the shipped audience-mode backend | Approved by UD section-by-section; amber keeps its monopoly on understanding, uncertainty stays dashed in both layers, and Easy-mode guidance is graph-deterministic (nearest unlit region by route hops), never model-decided |
+| 2026-07-20 | System orbits are call depth from the module's entry node, with the seed widened to include members no sibling calls | A module node makes no intra-project calls, so the spec's literal seed was always empty and stranded every member in the outermost ring. Both spec rules are preserved: the entry's callees are ring 1, and unreachable members take the outermost ring by node id |
+| 2026-07-20 | The workflow tree's first hop is labelled `defines`, not `calls` | The selected entrypoint is usually a module, and the parser observed no call from a module to its own function. Containment is real parser truth (`Node.region`); relabelling it a call would have invented an edge |
+| 2026-07-20 | Nebula tints ship lighter than the values in the design spec | The spec's starting values measured 3.19–4.46:1 against `--cm-ground-2` and failed the 4.5:1 legend floor. Hue is held; only lightness moved, and all three stay below `--cm-ink-2` so amber's monopoly is intact |
+| 2026-07-20 | Bloom resolution is capped with `composer.setPixelRatio(1)`, not the `UnrealBloomPass` constructor | `EffectComposer.setSize` forwards the canvas size to every pass on resize, overwriting the constructor's `resolution`. The pixel ratio is the cap that survives |
+| 2026-07-20 | **Corrects the row above**: bloom is capped by wrapping the bloom pass's own `setSize`, and the composer keeps the renderer's pixel ratio | The pixel ratio *did* cap bloom, but `EffectComposer.setSize` multiplies it into `renderTarget1/2` and every pass, so the whole scene rendered at 1x and upscaled — measured 1280x611 scene passes on a 2560x1221 buffer at dpr 2. Wrapping the one pass caps the one expensive thing: scene now 2560x1221, bloom mip 0 800x382 (1280x611 uncapped), `?benchmark` at 951 nodes unchanged at 928.8 → 961.5 fps median |
+| 2026-07-20 | **Corrects "binding is one-shot"** (2026-07-19 picker row): binding is one-*at-a-time*. `serve_project` attaches `PickerConfig(browse_root=Path.home())` too, so a `codemble <path>` run also exposes the picker endpoints after a reset, and browse then enumerates non-hidden directories under `$HOME` | The Switch project control has to work without a process restart, which is what that config is for — but the earlier row still claimed a permanent 409 for the path-opened flow, and this file is the source of truth. The home jail and the Host-header allowlist are unchanged; only the "one-shot" claim was false. An app built with no `PickerConfig` at all remains genuinely one-shot and refuses reset |
 
 ## Non-Goals — do NOT build (point here when asked)
 
 - ❌ Free-flight 3D navigation — semantic zoom only
 - ❌ XP, streaks, levels, leaderboards
-- ❌ A second 2D renderer/toggle in v1 (render-ready graph keeps one possible later)
+- ❌ ~~A second 2D renderer/toggle in v1~~ — superseded 2026-07-19: the 2D Map layer is approved (see Decision Log); free-form/client-computed 2D layouts remain out
 - ❌ Accounts, cloud hosting, multi-user; share link waits for Phase 3
-- ❌ Local models (Ollama)
 - ❌ Extra quest types before Phase 3
 - ❌ GitHub-URL ingestion in v1
 - ❌ Elaborate game art before the loop teaches well

{codemble-0.3.1 → codemble-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codemble
-Version: 0.3.1
+Version: 0.4.0
 Summary: A learning game that turns the code AI wrote for you into a galaxy you light up by understanding it.
 Project-URL: Homepage, https://udhawan97.github.io/Codemble/
 Project-URL: Repository, https://github.com/udhawan97/Codemble
@@ -43,8 +43,9 @@ Description-Content-Type: text/markdown
 
 <p align="center">
   Codemble is a local-first learning game for projects built with Claude Code,
-  Codex, and other coding agents. It maps real parser evidence into a 3D galaxy,
-  then lights each region only after you prove you understand it.
+  Codex, and other coding agents. It maps real parser evidence into a 3D galaxy
+  and a flat architecture map, then lights each region only after you prove you
+  understand it.
 </p>
 
 <p align="center"><strong>Your project · Your key · Your machine · No invented structure</strong></p>
@@ -65,9 +66,15 @@ Description-Content-Type: text/markdown
 </p>
 
 <p align="center">
-  <img src="https://github.com/udhawan97/Codemble/raw/main/assets/demo.gif" alt="Codemble maps a project, enters Home, runs graph-derived checks, and lights the system" width="960">
+  <img src="https://github.com/udhawan97/Codemble/raw/main/docs-site/public/shots/galaxy.png" alt="Codemble at galaxy level: eighty dim star systems parsed from real source, with a legend, language focus buttons, and a notice that two files are unchartable because their parser reported a syntax error" width="960">
 </p>
 
+<p align="center"><sub>
+  Galaxy level. Every system is one module; size is lines of code, brightness is
+  how many distinct structures call it. Files the parser could not read stay
+  visible and say so.
+</sub></p>
+
 > [!IMPORTANT]
 > **Codemble is in its Phase 1 tester release.** It maps Python,
 > JavaScript, TypeScript, and mixed projects in one parser-proven galaxy,
@@ -77,22 +84,52 @@ Description-Content-Type: text/markdown
 
 ## Quick start
 
+Two steps. The first is once per machine; the second is how you run Codemble
+from then on.
+
+| | Step | Command |
+| :---: | --- | --- |
+| <img src="https://github.com/udhawan97/Codemble/raw/main/docs-site/public/brand/icons/install.svg" width="22" height="22" alt=""> | **1 · Install uv** — the runner that fetches Codemble on demand | `brew install uv` |
+| <img src="https://github.com/udhawan97/Codemble/raw/main/docs-site/public/brand/icons/asterism.svg" width="22" height="22" alt=""> | **2 · Chart your project** — nothing to install, nothing left behind | `uvx codemble` |
+
+<details>
+<summary><strong>Installing uv without Homebrew</strong></summary>
+
 ```bash
-uvx codemble            # or: pipx install codemble && codemble
+# macOS · Linux
+curl -LsSf https://astral.sh/uv/install.sh | sh
+
+# Windows (PowerShell)
+powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
 ```
 
+Already have `pipx`? You can skip uv entirely: `pipx install codemble`, then run
+`codemble`. Plain `pip install codemble` works too. uv is the recommended path
+because `uvx` runs the current release without adding anything to your system
+Python.
+
+</details>
+
 Codemble opens your browser — pick your project folder there. To skip the
 picker, pass a path: `codemble ./your-ai-built-project`.
 
 The wheel already contains the web app, so Node.js is not required. No API key
-is needed for the galaxy, source viewer, language Lens, checks, lighting, or
-saved progress. Add your own Anthropic or OpenAI key only if you want grounded
-prose explanations:
+is needed for the galaxy, the map, the structural summary, source viewer,
+language Lens, checks, lighting, or saved progress. Add your own Anthropic or
+OpenAI key only if you want grounded prose explanations:
 
 ```bash
 export ANTHROPIC_API_KEY=sk-ant-...   # or OPENAI_API_KEY=sk-...
 ```
 
+Prefer to send nothing anywhere? Point Codemble at a local
+[Ollama](https://ollama.com) instead — same grounding validation, loopback only,
+never automatic:
+
+```bash
+ollama pull gemma4:12b && export CODEMBLE_PROVIDER=ollama
+```
+
 [Installation, configuration, and troubleshooting →](https://udhawan97.github.io/Codemble/installation/)
 
 ## How the learning loop works
@@ -100,7 +137,7 @@ export ANTHROPIC_API_KEY=sk-ant-...   # or OPENAI_API_KEY=sk-...
 | Step | What Codemble does | What you gain |
 | --- | --- | --- |
 | **1. Chart** | Parses your project without running its code or package scripts | A deterministic map made from source evidence |
-| **2. Navigate** | Guides you from galaxy → system → study on scripted camera rails | Orientation without getting lost in free flight |
+| **2. Navigate** | Two layers over one graph: a 3D galaxy on scripted camera rails, and a flat map of architecture and workflow | Orientation without getting lost in free flight |
 | **3. Study** | Shows the real source, exact line numbers, neighbors, and parser-detected language idioms | Context tied to code you can inspect |
 | **4. Prove** | Generates and scores checks from the graph—never from the model | A region lights only when understanding is demonstrated |
 | **5. Return** | Saves progress locally; changing one file re-dims only its module | A living map that stays honest as the project changes |
@@ -108,6 +145,59 @@ export ANTHROPIC_API_KEY=sk-ant-...   # or OPENAI_API_KEY=sk-...
 No XP. No streaks. No leaderboard. The visible reward is the useful one: more
 of your own code becomes a sky you understand.
 
+## What it looks like
+
+<p align="center">
+  <img src="https://github.com/udhawan97/Codemble/raw/main/docs-site/public/shots/system.png" alt="A single star system, codemble.server.app, showing its functions and classes in orbits with call edges and a keyboard focus reticle" width="900">
+</p>
+
+<p align="center"><sub>
+  System level. Members orbit by call depth, so the inner ring runs first.
+</sub></p>
+
+<p align="center">
+  <img src="https://github.com/udhawan97/Codemble/raw/main/docs-site/public/shots/study-panel.png" alt="The study panel for create_app, showing kind, span, 36 callers, a structural summary marked no model needed, guidance for configuring a provider or a local Ollama, and a parser connections diagram with an inbound call citing a real file and line" width="900">
+</p>
+
+<p align="center"><sub>
+  Study. Everything on this panel except the narration comes from the parser —
+  and this one has no model configured at all.
+</sub></p>
+
+## Two layers over one graph
+
+Codemble draws the same parser evidence two ways, switchable in the header. The
+map cannot show you a relationship the galaxy does not have — both layouts are
+computed in the graph layer and served as data.
+
+| Layer | What it is | When it helps |
+| --- | --- | --- |
+| **Galaxy** | 3D, camera on rails through galaxy → system → study | Orientation, and the shape of the whole project |
+| **Map · Architecture** | Modules as boxes, grouped by folder, layered by import distance from Home | Seeing how the project fits together |
+| **Map · Workflow** | The call tree from your entrypoint, depth by depth | Seeing what runs first |
+
+The Map is plain SVG, so it still works on a machine that cannot draw WebGL.
+
+## Open a structure, read what the parser knows first
+
+The study panel builds itself outward from the most certain evidence: a
+structural summary written from parser facts alone — no key, no network, no
+model — then grounded narration if you configured a provider, then every
+connection into and out of the structure with its direction, its certainty, and
+a `file:line` you can click, then the real source and the language Lens notes.
+
+Sections other than the narration never involve a model at all.
+
+## Easy or Expert
+
+A header toggle changes how Codemble talks to you and how much it puts on
+screen: plain language, larger type, the Map by default, and a hint chip naming
+the nearest unlit region to Home — counted in import hops over the graph, not
+chosen by a model. It never changes graph truth, coordinates, progress, or how a
+check is scored.
+
+You can also switch project or change Home without leaving the app.
+
 ## Read the galaxy
 
 | In the galaxy | In your project |
@@ -117,9 +207,18 @@ of your own code becomes a sky you understand.
 | The Home system | The selected parser-ranked entrypoint |
 | A route or edge | An import or call; approximate calls are labeled **possible** |
 | Size | Lines of code |
-| Brightness | Structural centrality |
+| Brightness and glow | How many **distinct** structures call it |
+| Nebula tint | Language, at galaxy level |
+| Orbit ring | Call depth — the inner ring runs first |
+| Drifting particles | A call the parser proved; a possible call stays still |
 | Dim → lit | Not yet proven → understood |
 
+Understanding owns the top of the brightness range: the unlit ramp stops below
+the amber a lit star uses, so a busy module you have not proven can never
+outshine one you have. Pass a region's checks and that system plays a short
+amber "nebula dawn" — after the light is already saved, so the animation marks
+a fact rather than delivering one.
+
 Python-only, JavaScript-only, TypeScript-only, and mixed projects share the same
 graph contract. Language focus changes only what you are looking at; it never
 changes coordinates, progress, or parser truth.
@@ -134,7 +233,9 @@ mistake. Accuracy therefore outranks spectacle:
   identifiers and relationships.
 - Language Lens notes appear only where a parser detected the construct.
 - Check answers come from the graph, never an LLM.
-- Approximate relationships stay visibly uncertain.
+- Approximate relationships stay visibly uncertain — a distinct colour and no
+  drifting particles in the 3D galaxy, a genuinely dashed line in the 2D map,
+  and the legend swatch follows whichever layer is on screen.
 - Provider output that fails grounding validation is withheld instead of being
   softened into a guess.
 
@@ -146,12 +247,13 @@ A wrong explanation is a highest-severity bug—[report it without mercy](https:
 | Stays on your machine | Leaves only when you ask |
 | --- | --- |
 | Project discovery and parsing | The bounded Study context sent to your configured provider |
-| Graph, language Lens, and checks | A request triggered only when you open Study |
+| Graph, structural summary, language Lens, and checks | A request triggered only when you open Study |
 | Local server and packaged web app | Nothing in the background |
 | Progress and explanation cache in `~/.codemble/` | No accounts, telemetry, or Codemble cloud |
+| Narration too, if you choose a local Ollama | Nothing at all in that case |
 
-No key? Codemble remains a complete parser-backed map and learning game; only
-the optional prose narration is unavailable.
+No model at all? Codemble remains a complete parser-backed map and learning
+game; only the optional prose narration is unavailable.
 
 ## Boundaries that keep the map truthful
 
@@ -164,8 +266,9 @@ the optional prose narration is unavailable.
   `--entrypoint NODE_ID`.
 - **Broken source:** syntax errors remain visible; Codemble maps safe partial
   evidence instead of crashing or inventing the missing structure.
-- **Rendering:** WebGL is required. There is intentionally no misleading 2D
-  fallback in this release.
+- **Rendering:** the 3D galaxy needs WebGL. If your machine cannot draw it, the
+  Map layer still works — it is plain SVG over the same parser evidence, not a
+  degraded guess.
 
 ## Help test the release