codemble 0.6.3__tar.gz → 0.7.0__tar.gz

{codemble-0.6.3 → codemble-0.7.0}/.gitignore

@@ -35,3 +35,4 @@ graphify-out/
 # Subagent-driven-development scratch coordination (not product truth)
 .superpowers/
 .remember
+.playwright-mcp/

{codemble-0.6.3 → codemble-0.7.0}/CHANGELOG.md

@@ -5,6 +5,128 @@ Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) · Versioning:
 
 ## [Unreleased]
 
+## [0.7.0] - 2026-07-22
+
+### Added
+- **Constellations you can tell apart.** Every parser-proven import community
+  now wears one of eight traditional Japanese colour families (seiji, fuji,
+  koke, asagi, toki, umenezumi, wakatake, kikyō), assigned deterministically
+  from the community id — same code, same sky, same colours. Galaxy stars keep
+  centrality as lightness inside the family hue, planets inherit their
+  system's family, and Architecture boxes tint toward it. Every hue is
+  lightness-capped beneath the unlit ceiling and the amber band is excluded
+  from the wheel, so a lit star stays the brightest object in the sky and
+  nothing unproven can read as understood. The Key gains a colour-family row.
+- **A counted shelf for unreachable modules.** On the Architecture map, modules
+  with no import route from Home fold away behind their exact count with a
+  **Show them** control (auto-folded above eight). On this repository that
+  turns a 1:3.2-tall drawing dominated by 80 test fixtures into a readable
+  connected core — with nothing hidden from the count and every module still
+  one click away.
+- **Class rings.** A structure the parser knows is a class wears a thin ring in
+  the system view — parser fact, not decoration.
+
+### Fixed
+- **Connections are visible.** Routes on both layers used to borrow the border
+  hairline at ~1.6:1 contrast — and the galaxy multiplied it to 32% opacity —
+  so the relationships the app teaches were its least visible marks. Both
+  layers now draw a dedicated route ink (4.0:1), arrowheads included, and a
+  *possible* relationship stays deliberately the more visible claim, dashed on
+  the map as before.
+- **The map's language stripe actually renders.** It set its colour through an
+  SVG presentation attribute, where `var()` is invalid, and silently fell back
+  to the box navy — the Key advertised Python/JS/TS colours the map never
+  drew. The stripe now paints through a style property.
+- **The nebula dawn no longer corrupts the lit system's name plate.** The
+  animation snapshotted one scale axis and restored all three from it, so the
+  celebration squashed the plate into a blurry square until a level change
+  rebuilt it. It now restores the full vector — the one bold moment ends
+  crisp.
+- **Escape steps back from anywhere on the Map.** The handler listened only
+  inside the stage, and the most common Easy path leaves focus on the page
+  body, so the documented recovery silently did nothing; the study exit also
+  said "Back to system" on the Diagram. Escape is now a window-level handler
+  (with dialog and typing guards) and the exit says "Back to the module".
+- **A resize cannot strand you in empty space.** Restored map viewports are
+  replayed only while they still show your focus; shrinking a desktop window
+  to phone width used to keep the desktop scroll and show empty layer bands.
+  Both the restore path and live resizes now re-centre on the parser-backed
+  target.
+- **Fit lands on something readable.** On tall drawings a true fit reached 7% —
+  a thumbnail with no names — so Fit now fits the width and lets the height
+  scroll when the whole shape would be unreadable, and keeps whole-shape fit
+  otherwise. The open Key also no longer covers the zoom controls, and the
+  region panel's actions no longer clip at desktop heights.
+- **Easy mode speaks its own register end to end.** "parser rank 0" became
+  "candidate 1", the checks header reads "Quiz · answers come from your code,
+  not AI", the lit celebration explains what the source hash means instead of
+  naming it, study metadata reads "What it is / Length / Evidence", and the
+  chrome attributes fixture errors to their shared directory ("2 could not be
+  read · all under tests/"). Expert keeps every precise term.
+- **Guidance stops sending beginners into tests first.** The nearest-unlit
+  ranking now charges test-scoped paths a bounded +1.5-hop penalty — a real
+  source module one hop farther wins the tie, an all-tests project is still
+  guided, and the displayed hop count stays the real one. On this repository
+  the second stop changed from `tests.test_python_ast` to
+  `codemble.adapters.project`.
+- **The study panel's connection diagram names its dots.** Six anonymous dots
+  used to decorate the labelled list below; each now carries its structure's
+  own (tail-truncated) name.
+
+## [0.6.4] - 2026-07-21
+
+### Fixed
+- **A missed check no longer hands back its own answer.** Getting a question
+  wrong printed the parser answer and its evidence, and the same question then
+  accepted that answer — so a region could light without understanding. A miss
+  now returns neither the answer nor the citations (an importer check's
+  evidence *is* its answer); both appear once the learner has proven it.
+- **The Map can show you the code it is asking about.** Easy mode lands on the
+  Map, which offered checks but no way to read a module. Region focus now
+  carries **Read the source** beside **Prove understanding**, and Easy guidance
+  recommends reading before proving instead of sending the learner to another
+  layer. Escape steps back a level on the Map, as it always has in the Galaxy.
+- **The checks panel is usable from the keyboard.** Opening it hands focus to
+  the panel instead of leaving it on the trigger behind ~114 tab stops, and
+  submitting keeps focus on the result rather than dropping it to the document.
+- **Enter opens the structure the arrow keys selected.** At study level the
+  canvas announced a sibling while the panel kept showing the old one; Enter
+  was a no-op despite the view's own instructions.
+- **Guidance is docked, and waits its turn.** The hint chip took its own strip
+  above the footer instead of floating over captions, name plates and its own
+  button, and it no longer appears during the audience, Home and coach steps —
+  where it used to recommend a target "because no import route reaches it from
+  Home" while no Home existed.
+- **Compact Map controls no longer stack.** At 375 px the Key button covered
+  40% of the "What runs first" tab and the zoom pill covered the top row of
+  boxes. Measured at 320 and 375: zero overlapping interactive rectangles.
+- **The study panel stops contradicting itself.** Easy mode showed "Used by 0"
+  above a summary saying five other parts use the file; the call-edge stat is
+  now "Called by", leaving "use" to imports.
+- **The audience question is asked once per learner, not once per project.**
+  A new project inherits the last answer; the header toggle still overrides any
+  single project.
+- **Home calibration is navigable on real projects.** It is now a modal sized
+  to the window rather than a card capped to a short stage, states how many
+  candidates exist, groups them by their real top-level scope (so test fixtures
+  no longer sit unmarked beside your entrypoint), and keeps "Explore without
+  Home" on screen instead of thousands of pixels below the fold.
+- **The star chart is reachable from anywhere and closes with Escape.** It kept
+  its header slot at every level instead of surrendering it to the level-return
+  button, and every exit now names the layer it returns to.
+- **Galaxy plates are named by path tail**, the rule the Map's boxes already
+  use, so two different `__init__.py` modules no longer wear identical names.
+- **Find opens on Home and the most-used modules** instead of a screen of
+  identical `__init__.py` rows.
+- **Easy guidance prefers a substantive module** when several sit the same
+  number of import hops from Home, instead of the alphabetically-first
+  four-line package init.
+- **The exception-handling lens note is true of `raise`,** not only of
+  `try`/`except`, since the parser files all three under one concept.
+- **Counts of one read as one** ("1 structure", not "1 structures").
+- **The picker opens beside your last project** rather than at your home
+  directory every time.
+
 ## [0.6.3] - 2026-07-21
 
 ### Fixed

{codemble-0.6.3 → codemble-0.7.0}/CLAUDE.md

@@ -167,9 +167,57 @@ 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-21 ·
-Session note: v0.6.3 closes the four follow-up findings from the 2026-07-21
-user-flow audit. Easy guidance is now level-aware and never offers an enabled
+**Current milestone: Phase 1 tester evidence** · Last updated: 2026-07-22 ·
+Session note: v0.7.0 implements all fourteen findings of a fresh evidence-based
+user-flow audit of the served v0.6.4 build (run as a first-run Easy learner on
+this repository at 1280/375/320, with before/after screenshots) plus the
+approved D1 design direction: parser-proven import communities now wear eight
+deterministic traditional Japanese colour families (galaxy stars, planets, and
+Architecture-box tints), lightness-capped beneath the unlit ceiling with the
+amber band excluded so understanding stays the brightest claim in the sky.
+Routes on both layers moved from the 1.6:1 border hairline to a dedicated
+4.0:1 route ink (possible relationships stay dashed and deliberately more
+visible); the Architecture map folds modules with no route from Home into a
+counted shelf behind a Show-them control; Fit fits width when whole-shape fit
+would be unreadable; and Easy guidance charges test-scoped paths a bounded
++1.5-hop penalty so a learner's own code outranks its test suite at equal
+distance. Mechanical fixes: the nebula dawn restores sprite scale as a vector
+(it squashed the lit system's name plate square), the map's language stripe
+paints via a style property (an SVG fill attribute cannot resolve var() and
+silently rendered navy), Escape on the Map is a window-level handler that
+works with focus on body, stale map viewports re-centre on the focus point on
+restore and on live resizes, the open Key stacks below the zoom controls, the
+region panel's actions no longer clip, study connection dots carry names, and
+the Easy register replaces parser vocabulary end to end ("candidate 1",
+"Quiz · answers come from your code, not AI", "What it is / Length /
+Evidence", fixture errors attributed "all under tests/"). Parser, graph,
+checks, progress, provider, and HTTP contracts are byte-unchanged; the suite
+grew a nebula-dawn scale-restore check plus community-colour, viewport, and
+guidance-penalty contract assertions (241 pytest, ruff clean, 12 frontend
+checks, rebuilt web_dist). Full planet realism explicitly remains a Phase 3
+decision under the game-art Non-Goal. The milestone does not advance: issue
+#13 still requires human tester evidence. Previously: v0.6.4 closes all twenty findings of a fresh end-to-end user-flow
+audit run against the served build on three real projects (Codemble, Golavo,
+FolioOrb) at 1280/375/320 px with a keyboard pass. The headline fix is a
+Correctness Contract one: a missed check printed the parser answer and its
+evidence and then accepted that answer, so a region could light without
+understanding; a miss now returns neither, and both appear only after the
+learner proves it. The Easy default layer gained the reading path it never had
+(**Read the source** on the Map, guidance that says read-before-prove, Escape
+stepping back a level), the checks panel became keyboard-usable (focus handoff
+on open, focus preserved across submits), Enter now opens the arrow-selected
+structure at study level, and the guidance chip is docked into its own strip
+and hidden until the first-run decisions finish. Home calibration is now a
+viewport-sized modal that states its candidate count, groups candidates by
+their real scope, and keeps its escape hatch on screen; the audience question
+is asked once per learner instead of once per project; the star chart is
+reachable from every level and closes with Escape; exits name the layer they
+return to; galaxy plates and the module index use path tails; Find opens on
+Home and the busiest modules; and compact Map controls no longer share touch
+targets (zero overlapping interactive rectangles at 320 and 375). Parser,
+graph, checks, progress, and provider contracts are unchanged except for the
+deliberate withholding of answers on a failed submission. Previously, v0.6.3
+closed the four follow-up findings from the earlier user-flow audit. Easy guidance is now level-aware and never offers an enabled
 no-op; compact Maps open at readable 100% around Home and preserve zoom/pan
 through data refreshes; Switch project confirms on the first compact-Menu click
 without leaking disclosure state across project or breakpoint changes; and Home
@@ -551,6 +599,15 @@ shows lower repeated-commit work without changing derived values.
 | 2026-07-21 | Easy guidance actions are derived from level, region, and layer, then executed by `LearnerSession`; the chip renders no button when the next step is already on screen | React must not guess a structure or own navigation truth, and an enabled action that commits the same state is a false promise. The nearest unlit region remains graph-derived; only the honest route to it changes with the learner's current context |
 | 2026-07-21 | Map zoom/pan is renderer-local state keyed by tab and Home, preserved through transient data remounts but cleared with the project lifecycle; compact Maps start at 100% centred on the parser-backed target | Auto-fitting made 56 px boxes as little as 8–18 px tall and re-ran after check-driven map refreshes. Fit is still a valid explicit overview, while session state stays reserved for graph and learning truth |
 | 2026-07-21 | Responsive disclosures and global surfaces own explicit focus handoffs; compact Menu closes on project exit and when crossing to the desktop rail | DOM focus and disclosure visibility are view concerns, but leaving focus on removed or hidden controls makes a successful navigation indistinguishable from a dead action to a keyboard or screen-reader user |
+| 2026-07-21 | A wrong check submission returns no answer, no answer labels and no evidence; all three are returned only once the learner answers correctly | The response printed the parser answer on every miss and the same question then accepted it, so a region could light on an answer the app itself had just displayed — illumination stopped meaning understanding, the same failure class as the 2026-07-19 "every check needs a wrong option" fix. Evidence is withheld with the answer because an importer check cites exactly the files that *are* its answer |
+| 2026-07-21 | The 2D Map gets a reading path: region focus offers **Read the source** beside the checks, Easy guidance recommends reading before proving, and Escape steps back a level there as it does in the Galaxy | Easy mode lands on the Map, where the only action was a quiz about code the layer could not show. The study panel is layer-neutral (`/api/node/:id/study`), so the Map only needed to select the module node the parser already produced — no new truth, and the audience that most needs to read first stops being sent to another layer to do it |
+| 2026-07-21 | The audience answer is stored per learner as well as per project (`learner.json` beside progress); a fresh bind seeds from it and skips the gate, while the header toggle still overrides one project | The gate asks who the *learner* is, but the answer lived only under the project key, so every new project re-asked an expert whether they were new to coding. The file carries no `schema_version`, which is what keeps recents from reading it as a project |
+| 2026-07-21 | Home calibration is a native modal sized to the viewport, grouped by the candidates' real top-level scope, with the candidate count stated and "Explore without Home" outside the scrolling list | It is the second step of the same required sequence as the audience gate and deserves the same shape. As a card capped to a share of the stage it showed one candidate of eleven with the escape hatch thousands of pixels below the fold, and a flat list put `tests/fixtures/...` beside the learner's entrypoint with nothing to tell them apart. Scope and rank are parser facts already in the payload; the leading group always opens so a project whose best candidate is rank 1 is never met by an all-collapsed list |
+| 2026-07-21 | Galaxy name plates use the same path-tail rule as map schema 3's `short_label`; the shared module index and the command palette use it too, and the palette's unfiltered order is Home → lit → centrality | Basenames collide hard in a Python project — every package carries an `__init__.py` — so identical plates named different modules, which is precisely the wrong a learner cannot detect, and the palette opened on a screen of indistinguishable rows |
+| 2026-07-22 | **Hue means import community.** Each parser-proven community takes one of eight traditional Japanese colour tokens (`--cm-com-0..7`) by `community id mod 8`; stars, planets and Architecture boxes all read the same arithmetic in `graphData.communityShade`. This amends the M2 encoding row: colour was "language", which is now the nebula/stripe channel only | Approved by UD. The sky had one hue for 109 systems, so nothing could be tracked without reading every plate — and the graph had proven communities since schema 5 that nothing rendered. Guardrails that keep the Correctness Contract intact: every token is lightness-tuned to `--cm-ink-2`'s luminance (0.389) so a lit star at 0.598 always wins, the kohaku band (~40°) is excluded so no community can read as "understood", a missing community id falls back to the old neutral ramp rather than borrowing a hue, and the mapping is pure arithmetic on graph truth so the same code always yields the same sky |
+| 2026-07-22 | Routes get their own ink (`--cm-route`, 4.0:1) on both layers, and it sits deliberately BELOW `--cm-route-possible` (6.4:1) | Edges borrowed `--cm-hairline`, the ink of box borders and panel rules, measuring 1.57:1 on the canvas ground — the relationships the product exists to teach were its least visible marks, which is the literal complaint that opened the audit. Ordering the two inks this way keeps the 2026-07-19 rule that an unproven claim must be the more visible one |
+| 2026-07-22 | Architecture-map modules with no import route from Home fold into a counted shelf behind an explicit control (auto-folded above 8), and Fit fits WIDTH when a whole-shape fit would land below 35% | On this repository 80 of 109 boxes are test fixtures and scripts, making the drawing 1:3.2 tall so the connected core fit at an unreadable 7%. Folding is view state, never truth: the note carries the exact count, **Show them** draws every one, and both surfaces still reach every module. Distinct from progressive reveal, which stays galaxy-only |
+| 2026-07-22 | Easy guidance charges test-scoped paths a bounded +1.5-hop penalty; the displayed hop count stays the real one | A CLI's nearest neighbour is usually its own test suite, so pure hop-distance sent a brand-new learner from Home straight into `tests/`. The penalty is bounded so a non-test module one hop farther wins while a distant one does not, and an all-tests project is still guided. Both inputs stay parser truth (the BFS count and the recorded file path); only the ranking key is biased, never the reported fact |
 
 ## Non-Goals — do NOT build (point here when asked)
 
@@ -563,7 +620,11 @@ shows lower repeated-commit work without changing derived values.
 - ❌ Accounts, cloud hosting, multi-user; share link waits for Phase 3
 - ❌ Extra quest types before Phase 3
 - ❌ GitHub-URL ingestion in v1
-- ❌ Elaborate game art before the loop teaches well
+- ❌ Elaborate game art before the loop teaches well — **still holds**: the
+  2026-07-22 visual pass shipped only encodings that carry parser facts
+  (community hue, class rings). Procedural planet surfaces, atmospheres and
+  rotation ("almost real planets, like a game") remain OUT until Phase 1
+  tester evidence lands, and would need their own Decision Log entry
 
 ## Gotchas
 
@@ -591,6 +652,11 @@ shows lower repeated-commit work without changing derived values.
 - **Canvas colours must be plain values, never `color-mix()`** — WebGL receives
   a custom property's authored text, so a computed token renders black. Add new
   canvas tokens through `readPalette`, which resolves them.
+- **`var()` never works in an SVG presentation attribute** — `fill="var(--x)"`
+  is invalid and falls back to the cascade *silently*, which is how the map's
+  language stripe rendered box-navy for a release while the legend advertised
+  three colours. Use `style={{ fill: … }}` (a CSS property) for any
+  token-driven SVG paint.
 
 ## Edge cases & limits
 

{codemble-0.6.3 → codemble-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codemble
-Version: 0.6.3
+Version: 0.7.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
@@ -66,7 +66,7 @@ Description-Content-Type: text/markdown
 </p>
 
 <p align="center">
-  <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">
+  <img src="https://github.com/udhawan97/Codemble/raw/main/docs-site/public/shots/galaxy.png" alt="Codemble at galaxy level: 109 star systems parsed from real source, 23 charted and named by file path, constellations wearing their import-community colour families in traditional Japanese hues around an amber lit Home, with language focus buttons, a Key disclosure, and a notice that two files could not be read — all under tests/" width="960">
 </p>
 
 <p align="center"><sub>
@@ -148,7 +148,7 @@ 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">
+  <img src="https://github.com/udhawan97/Codemble/raw/main/docs-site/public/shots/system.png" alt="A single star system, codemble.server.app, its functions and classes as planets in the system's own colour family, in call-depth orbits with the call edges between them" width="900">
 </p>
 
 <p align="center"><sub>
@@ -156,7 +156,7 @@ of your own code becomes a sky you understand.
 </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">
+  <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, 53 callers, parser-proven resolution, and a structural summary marked no model needed" width="900">
 </p>
 
 <p align="center"><sub>
@@ -188,9 +188,17 @@ computed in the graph layer and served as data.
 | **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.
-On a compact screen it opens at readable 100% around Home or the selected
-target; **Fit** is an explicit whole-diagram overview. Zoom and pan survive Map
-refreshes and layer switches instead of snapping back after a passed check.
+Click a box and it offers both halves of a step — **Read the source** opens that
+module's real source, lens notes and relationships without leaving the layer,
+and **Prove understanding** starts its checks. Escape steps back a level, as in
+the Galaxy. On a compact screen the Map opens at readable 100% around Home or
+the selected target; **Fit** is an explicit whole-diagram overview. Zoom and pan
+survive Map refreshes and layer switches instead of snapping back after a passed
+check.
+
+In Easy mode these surfaces carry plainer labels — the layer is **Diagram** and
+the tabs are **How it fits together** and **What runs first**. Same views, same
+evidence; only the wording follows the audience.
 
 ## Open a structure, read what the parser knows first
 
@@ -207,10 +215,14 @@ Sections other than the narration never involve a model at all.
 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. The hint opens that system, switches from Map to Galaxy when
-its internal structures are the next step, then becomes an instruction rather
-than an enabled no-op. It never changes graph truth, coordinates, progress, or
-how a check is scored.
+chosen by a model, and broken by parser-proven structure count when several sit
+the same distance away. The hint opens that system, offers to read its source,
+then becomes an instruction rather than an enabled no-op. It waits until the
+first-run choices are done before it appears at all, and it never changes graph
+truth, coordinates, progress, or how a check is scored.
+
+Codemble asks which audience you are **once** — the question is about you, not
+about the project — and each project still keeps its own mode.
 
 You can also switch project or change Home without leaving the app.
 
@@ -224,6 +236,7 @@ You can also switch project or change Home without leaving the app.
 | A route or edge | An import or call; approximate calls are labeled **possible** |
 | Size | Lines of code |
 | Brightness and glow | How many **distinct** structures call it |
+| Colour family | Import community — modules that import each other share one of eight traditional Japanese hues |
 | 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 |
@@ -231,9 +244,13 @@ You can also switch project or change Home without leaving the app.
 
 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.
+outshine one you have — every community hue is lightness-capped beneath it, and
+the amber band is excluded from the community wheel entirely. 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. On the
+flat Map, modules with no import route from Home fold into a counted shelf
+(**Show them** draws every one), so test scaffolding never buries the connected
+core it cannot reach.
 
 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

{codemble-0.6.3 → codemble-0.7.0}/README.md

@@ -34,7 +34,7 @@
 </p>
 
 <p align="center">
-  <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">
+  <img src="https://github.com/udhawan97/Codemble/raw/main/docs-site/public/shots/galaxy.png" alt="Codemble at galaxy level: 109 star systems parsed from real source, 23 charted and named by file path, constellations wearing their import-community colour families in traditional Japanese hues around an amber lit Home, with language focus buttons, a Key disclosure, and a notice that two files could not be read — all under tests/" width="960">
 </p>
 
 <p align="center"><sub>
@@ -116,7 +116,7 @@ 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">
+  <img src="https://github.com/udhawan97/Codemble/raw/main/docs-site/public/shots/system.png" alt="A single star system, codemble.server.app, its functions and classes as planets in the system's own colour family, in call-depth orbits with the call edges between them" width="900">
 </p>
 
 <p align="center"><sub>
@@ -124,7 +124,7 @@ of your own code becomes a sky you understand.
 </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">
+  <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, 53 callers, parser-proven resolution, and a structural summary marked no model needed" width="900">
 </p>
 
 <p align="center"><sub>
@@ -156,9 +156,17 @@ computed in the graph layer and served as data.
 | **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.
-On a compact screen it opens at readable 100% around Home or the selected
-target; **Fit** is an explicit whole-diagram overview. Zoom and pan survive Map
-refreshes and layer switches instead of snapping back after a passed check.
+Click a box and it offers both halves of a step — **Read the source** opens that
+module's real source, lens notes and relationships without leaving the layer,
+and **Prove understanding** starts its checks. Escape steps back a level, as in
+the Galaxy. On a compact screen the Map opens at readable 100% around Home or
+the selected target; **Fit** is an explicit whole-diagram overview. Zoom and pan
+survive Map refreshes and layer switches instead of snapping back after a passed
+check.
+
+In Easy mode these surfaces carry plainer labels — the layer is **Diagram** and
+the tabs are **How it fits together** and **What runs first**. Same views, same
+evidence; only the wording follows the audience.
 
 ## Open a structure, read what the parser knows first
 
@@ -175,10 +183,14 @@ Sections other than the narration never involve a model at all.
 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. The hint opens that system, switches from Map to Galaxy when
-its internal structures are the next step, then becomes an instruction rather
-than an enabled no-op. It never changes graph truth, coordinates, progress, or
-how a check is scored.
+chosen by a model, and broken by parser-proven structure count when several sit
+the same distance away. The hint opens that system, offers to read its source,
+then becomes an instruction rather than an enabled no-op. It waits until the
+first-run choices are done before it appears at all, and it never changes graph
+truth, coordinates, progress, or how a check is scored.
+
+Codemble asks which audience you are **once** — the question is about you, not
+about the project — and each project still keeps its own mode.
 
 You can also switch project or change Home without leaving the app.
 
@@ -192,6 +204,7 @@ You can also switch project or change Home without leaving the app.
 | A route or edge | An import or call; approximate calls are labeled **possible** |
 | Size | Lines of code |
 | Brightness and glow | How many **distinct** structures call it |
+| Colour family | Import community — modules that import each other share one of eight traditional Japanese hues |
 | 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 |
@@ -199,9 +212,13 @@ You can also switch project or change Home without leaving the app.
 
 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.
+outshine one you have — every community hue is lightness-capped beneath it, and
+the amber band is excluded from the community wheel entirely. 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. On the
+flat Map, modules with no import route from Home fold into a counted shelf
+(**Show them** draws every one), so test scaffolding never buries the connected
+core it cannot reach.
 
 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

{codemble-0.6.3 → codemble-0.7.0}/codemble/__init__.py

@@ -1,4 +1,4 @@
 """Codemble — a learning game that turns the code AI wrote for you into a galaxy
 you light up by understanding it. See CLAUDE.md for the agent brief and roadmap."""
 
-__version__ = "0.6.3"
+__version__ = "0.7.0"

{codemble-0.6.3 → codemble-0.7.0}/codemble/checks/service.py

@@ -124,22 +124,28 @@ class CheckService:
         if complete:
             self._progress.mark_understood(region_id)
 
-        answer_labels = [
-            option.label for option in check.options if option.id in check.answer_ids
-        ]
-        return {
+        result: dict[str, object] = {
             "correct": correct,
             "check_id": check.id,
-            "answer_ids": list(check.answer_ids),
-            "answer_labels": answer_labels,
-            "evidence": list(check.evidence),
             "message": (
                 "Correct. That answer is fixed by the parser graph."
                 if correct
-                else "Not yet. Re-read the graph relationship and try again."
+                else "Not yet. Re-read the relationship in your own code and try again."
             ),
             "region_understood": complete,
         }
+        if not correct:
+            # A miss returns no answer and no citations. An importer check
+            # cites the very files that are its answer, so handing either back
+            # let the next submission replay what the screen had just shown --
+            # and a region lit that way proves nothing.
+            return result
+        result["answer_ids"] = list(check.answer_ids)
+        result["answer_labels"] = [
+            option.label for option in check.options if option.id in check.answer_ids
+        ]
+        result["evidence"] = list(check.evidence)
+        return result
 
     def _region_checks(self, region_id: str) -> tuple[Check, ...]:
         if region_id not in self._checks:

{codemble-0.6.3 → codemble-0.7.0}/codemble/lens/python.py

@@ -47,10 +47,15 @@ _PYTHON_NOTES = {
             "expert": "Python calls this specially named method through a language protocol such as length, comparison, or display.",
         },
     ),
+    # One concept id covers `try`, `try*` and `raise` (python_ast visits all
+    # three), so the copy has to be true of a line that *signals* a problem as
+    # well as one that catches it. The old easy note taught catching only, and
+    # anchored to `raise SystemExit(main())` it claimed roughly the opposite of
+    # what that line does.
     "exception-handling": (
         "Exception handling",
         {
-            "easy": "This plans for something going wrong, so the program can react instead of crashing.",
+            "easy": "This treats failure as part of the plan: code like this either raises a problem for whoever called it, or catches one so the program can react instead of crashing.",
             "expert": "This construct makes failure part of explicit control flow by catching, grouping, or raising an exception.",
         },
     ),

{codemble-0.6.3 → codemble-0.7.0}/codemble/progress/store.py

@@ -12,6 +12,11 @@ from codemble.adapters.base import Graph
 from codemble.paths import data_dir
 
 _SCHEMA_VERSION = 1
+_MODES = frozenset({"easy", "expert"})
+# The audience answer is about the learner, not the project, so it is also kept
+# once per data directory. Project payloads still win, which is what keeps the
+# header toggle a genuine per-project override.
+_LEARNER_FILE = "learner.json"
 
 
 class UnknownRegionError(KeyError):
@@ -26,6 +31,7 @@ class ProgressStore:
         self._root = root or data_dir() / "progress"
         project_key = hashlib.sha256(graph.project_root.encode()).hexdigest()[:20]
         self.path = self._root / f"{project_key}.json"
+        self._learner_path = self._root / _LEARNER_FILE
         self._signatures = _region_signatures(graph)
 
     def understood_regions(self) -> frozenset[str]:
@@ -72,24 +78,55 @@ class ProgressStore:
     def mode(self) -> str:
         """Return the learner's audience mode; this never affects progress."""
 
-        payload = self._read()
-        value = payload.get("mode")
-        return value if value in {"easy", "expert"} else "easy"
+        value = self._read().get("mode")
+        if value in _MODES:
+            return value
+        return self._learner_mode() or "easy"
 
     def mode_chosen(self) -> bool:
-        """Return whether the learner has explicitly chosen an audience mode."""
+        """Return whether this learner has answered the audience question.
 
-        payload = self._read()
-        return payload.get("mode") in {"easy", "expert"}
+        Per project first, then the learner-level answer. The gate asks who
+        the *learner* is, so re-asking it on every project would be asking a
+        question they have already answered; the header toggle still overrides
+        any single project.
+        """
+
+        return self._read().get("mode") in _MODES or self._learner_mode() is not None
 
     def set_mode(self, mode: str) -> None:
         """Persist the audience mode beside progress without touching signatures."""
 
-        if mode not in {"easy", "expert"}:
+        if mode not in _MODES:
             raise ValueError("Mode must be 'easy' or 'expert'.")
         payload = self._read()
         payload["mode"] = mode
         self._write(payload)
+        self._write_learner_mode(mode)
+
+    def _learner_mode(self) -> str | None:
+        """Read the last audience answered on any project in this data dir."""
+
+        try:
+            payload = json.loads(self._learner_path.read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError, UnicodeDecodeError):
+            return None
+        if not isinstance(payload, dict):
+            return None
+        value = payload.get("mode")
+        return value if value in _MODES else None
+
+    def _write_learner_mode(self, mode: str) -> None:
+        self._root.mkdir(parents=True, exist_ok=True)
+        temporary = self._learner_path.with_suffix(f".{os.getpid()}.tmp")
+        try:
+            temporary.write_text(
+                json.dumps({"mode": mode}, indent=2, sort_keys=True) + "\n",
+                encoding="utf-8",
+            )
+            temporary.replace(self._learner_path)
+        finally:
+            temporary.unlink(missing_ok=True)
 
     def selected_entrypoint(self) -> str | None:
         """Return the learner's persisted Home choice, if one was stored.

{codemble-0.6.3 → codemble-0.7.0}/codemble/server/project_selection.py

@@ -69,7 +69,7 @@ class ProjectSelector:
     def browse(self, path: str | Path | None = None) -> FolderListing:
         """List non-hidden child directories for one allowed folder."""
 
-        resolved = self.resolve(path if path is not None else self._root)
+        resolved = self.resolve(path if path is not None else self._default_start())
         if not resolved.is_dir():
             raise ProjectFolderMissing("That folder does not exist.")
         try:
@@ -97,6 +97,21 @@ class ProjectSelector:
             if self._is_inside_root(Path(str(entry["project_root"])).resolve())
         )
 
+    def _default_start(self) -> Path:
+        """Open browsing beside the newest remembered project, else at the root.
+
+        Projects tend to live as siblings, so starting at the browse root made
+        every switch re-walk the same folders. Derived from recents rather than
+        stored, so it cannot drift, and it stays inside the same jail because
+        ``recents`` already filtered by it.
+        """
+
+        for entry in self.recents():
+            parent = Path(str(entry["project_root"])).parent
+            if self._is_inside_root(parent) and parent.is_dir():
+                return parent
+        return self._root
+
     def _require_inside_root(self, path: Path) -> None:
         if not self._is_inside_root(path):
             raise ProjectFolderForbidden(