codemble 0.3.1__tar.gz → 0.5.0__tar.gz

{codemble-0.3.1 → codemble-0.5.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.5.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.5.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.5.0/CHANGELOG.md

@@ -0,0 +1,344 @@
+# Changelog
+
+All notable changes to Codemble are documented here.
+Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) · Versioning: [SemVer](https://semver.org/).
+
+## [Unreleased]
+
+## [0.5.0] - 2026-07-20
+
+### Added
+- Large projects now show a staged loading screen instead of a frozen tab.
+  Parsing runs on a worker thread; the app polls `GET /api/picker/progress` and
+  names the stage it is in — discovering, parsing, resolving, checks, layout —
+  with a real file count while files are read, and a narrated sub-step
+  (resolving imports, resolving calls, building the galaxy map, composing the
+  project) once the parse moves past counting files. A failed parse reports
+  the parser's own message and offers an in-app retry; cancelling stops the
+  parse at the next file boundary. A realistic 1,000-file Python project
+  parses and renders an interactive galaxy end to end; the parse itself is
+  1.56x faster after removing a parser hotspot (below), and the one-pass check
+  index builds a full 1,000-region suite in under a second.
+- The over-cap prompt is actionable in-app: the busiest subdirectories are
+  buttons that navigate the picker, and a typed path field accepts any folder
+  inside your home directory. Outside-home paths are still refused.
+- A **Clear this project's progress** control on the star chart, behind a
+  confirmation, scoped to the open project only.
+- A non-interactive `codemble` run now prints the busiest-scope suggestions
+  with the scale refusal instead of a bare message.
+
+### Changed
+- The scale cap moved from 300 to 1,000 supported source files. LOD and
+  clustering remain Phase 2 work.
+- `POST /api/picker/select` returns `202 {"state": "parsing"}` instead of
+  blocking until the graph is ready.
+- `CODEMBLE_DATA_DIR` now relocates **everything** Codemble keeps under your home
+  directory — saved progress, the narration cache, and the `config` file — rather
+  than progress alone. All three resolve through one helper, so pointing the
+  variable somewhere else moves them together. Unset, the default is unchanged:
+  `~/.codemble`.
+- Language focus now also projects onto the **2D Map**, matching the galaxy: a
+  focused language keeps its boxes, rows, and edges while the others are dropped,
+  and the survivors keep their backend-computed coordinates. The projection
+  happens in the frontend and never re-lays-out or mutates the immutable graph,
+  so focus finally means the same thing on both layers.
+- The no-WebGL message now points the learner to the Map/Diagram layer, which
+  draws the same parser evidence as plain SVG and is one switch away, instead of
+  only stating that the galaxy needs WebGL.
+
+### Fixed
+- Check generation walked every graph edge up to four times per region, and
+  rebuilt the node lookup and the option pool per region — an O(regions × graph)
+  freeze at bind. One index is now built per bind in a single pass, measured
+  ~16x faster at 1,000 files. A committed golden fixture proves the generated
+  suites and answers are byte-identical for the Python and mixed fixtures.
+- `GET /api/graph` and `GET /api/map` re-hydrated progress and re-sorted every
+  node and edge on every request. The serialized document is cached and
+  invalidated on region light-up, Home selection, and project bind or reset —
+  measured ~25-26x faster warm.
+- The Python adapter resolved a node's owning module with an O(definitions ×
+  modules) scan; it now walks the node id's own dotted prefixes in O(depth),
+  a further 1.56x on total parse wall-clock. Output is byte-identical.
+- The test suite no longer reads the developer's `~/.codemble/config` or their
+  `ANTHROPIC_API_KEY` / `OPENAI_API_KEY`. Every server test that built an app
+  without an explicit study service inherited whatever the machine had
+  configured, so the same test could construct a live provider locally and none
+  in CI. The two tests that request `/explanation` would then make a real, billed
+  API call and cache the reply under the developer's home directory.
+- First-run onboarding assumed the learner was on the galaxy, but Easy — the
+  default audience — opens on the 2D Map. The coach-marks and the footer control
+  hint now key on the active layer, so a learner on the Map reads map guidance
+  ("click a box or row to study, switch tabs") instead of galaxy scroll/camera
+  controls that are not on screen.
+- The audience-mode gate and the first-run coach-marks no longer open as two
+  stacked modals on a genuine first run; the coach-marks wait until a mode has
+  been chosen, so the gate resolves first.
+- With no parser-recognisable entrypoint the "Change Home" control is not
+  rendered, so both Map tabs now state that reason instead of pointing at a
+  button that is not there. The has-candidates-but-unselected copy is unchanged.
+- A project bind slow enough to outlast a parse cancellation could commit after
+  the picker had already been reset, resurrecting the just-released project or
+  clobbering the next selection. The commit now re-checks cancellation under the
+  same lock that performs it, so a stale bind can never rebind a released project.
+
+## [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
+- Packaging metadata only, no behavior change: added PyPI classifiers (Beta
+  status, Python 3.11-3.13, Apache-2.0 license, dev/education audience), moved
+  license metadata to the PEP 639 SPDX form so the License field is concise
+  instead of dumping the full Apache text, made README links absolute so the
+  PyPI project page renders them, and excluded internal tooling directories
+  from the sdist.
+
+## [0.3.0] - 2026-07-19
+
+### Added
+- Bare `codemble` now opens the browser to an in-app project picker: browse
+  home folders, reopen recent projects, and re-scope over-cap projects without
+  touching the terminal.
+- The local server rejects foreign `Host` headers, keeping the picker API
+  reachable only from the learner's own machine.
+- Codemble is published to PyPI, so installing is `uvx codemble` or
+  `pipx install codemble` with no git URL or tag.
+
+### Changed
+- `codemble` with flags but no path serves the picker instead of the current
+  directory; pass a path (or `--path`) for the previous behaviour.
+- Rebuilt the packaged app on the Formal Edo palette, so the galaxy and the
+  public site finally share one set of values. The app's tokens already imported
+  the site's, but `codemble/web_dist` had not been rebuilt since before the
+  redesign, so every shipped build still rendered the retired palette.
+- Self-hosted Shippori Mincho and Zen Kaku Gothic New in the app and dropped
+  Sora and Inter. The site loads these faces from the Google Fonts CDN; the app
+  must not, because it runs locally and offline. Net bundle change is smaller.
+- Illumination now owns the top of the brightness range: the unlit centrality
+  ramp stops at `--cm-ink-2` (8.2:1) and a lit star uses `--cm-star-high`
+  (12.1:1). Previously a busy un-understood module outshone an understood one
+  17.4:1 to 8.5:1, which inverted the meaning of lighting a region.
+
+### Fixed
+- Canvas colours authored as `color-mix()` reached WebGL as unparsed text and
+  rendered black, because a custom property returns its authored value rather
+  than a resolved colour. Affected unchartable nodes and every "possible call"
+  edge — exactly the uncertainty the Correctness Contract requires to stay
+  visible. Palette values are now resolved to plain `rgb()` before rendering.
+- The partial-parse notice said "its language parser" when reporting more than
+  one file.
+- Multi-answer checks offered no wrong option once a question had four or more
+  correct answers, so selecting every option lit the region without proving
+  anything. Checks now always offer wrong options alongside their answers, and a
+  question the graph cannot supply a wrong option for is dropped rather than
+  asked. On this repository the change removed all 17 such questions out of 107
+  while leaving every region's check count unchanged.
+
+### Added
+- Expanding site search in the header of both the landing page and every docs
+  page, backed by Pagefind with keyboard shortcut, arrow-key navigation, and an
+  explicit message when the index has not been built yet.
+- Generated Edo star-atlas plate artwork (`docs-site/scripts/build-plates.mjs`),
+  emitted from a fixed seed so the same script always produces the same sky.
+- A standalone landing page at `docs-site/src/pages/index.astro`, structured as
+  four numbered plates in 起承転結 order with a layered tatebanko hero.
+
+### Changed
+- Centralized graph canonicalization, Home selection, centrality, annotation
+  normalization, edge deduplication, and deterministic layout behind one graph
+  finalization interface shared by every language adapter and project composition.
+- Moved scale guarding and scope selection into `ProjectParser`, with one
+  reusable project intake that preserves adapter file ownership through parsing
+  instead of rediscovering the same scope in each adapter.
+- Moved learner navigation, language focus, study/check/Home requests, progress
+  refresh, and illumination sequencing behind one testable learner-session
+  interface with HTTP and in-memory adapters, leaving React to render snapshots.
+- Reused one internal JavaScript/TypeScript syntax-evidence index across
+  entrypoint, concept, call, binding, and imported-symbol resolution passes,
+  eliminating repeated ownership maps and whole-graph symbol scans.
+- Rebuilt the public site on the Formal Edo palette (kachi indigo, ruri lapis,
+  kohaku amber, gofun white) with Shippori Mincho and Zen Kaku Gothic New. The
+  accent contracts are unchanged: kohaku still means understanding, ruri still
+  means interaction.
+
+### Fixed
+- The current docs page was marked with a filled kohaku pill, which claimed
+  "understood" about a navigation state; it now uses ruri, the interaction accent.
+- The landing hero overflowed a 320px viewport, putting a call to action and the
+  install command outside the clipped area where they could not be reached.
+
+### Removed
+- `docs-site/src/content/docs/index.mdx`, replaced by the standalone landing
+  page; its content moved there.
+
+## [0.2.0] - 2026-07-19
+
+### Added
+- Language-neutral `ProjectParser` discovery and graph composition with global
+  Home selection, adapter collision checks, and Python graph-byte compatibility.
+- Official tree-sitter JavaScript/TypeScript adapter for JS, JSX, MJS, CJS, TS,
+  TSX, MTS, and CTS modules, definitions, imports, calls, entrypoint ranking,
+  exact source spans, file hashes, and honest partial-parse recovery.
+- Language-tagged graph schema 4 concept annotations plus deterministic
+  JavaScript/TypeScript Lens notes for async/await, arrows, destructuring,
+  optional chaining, nullish coalescing, modules, types, interfaces, generics,
+  and JSX.
+- Accessible language focus for mixed galaxies, systems, Study navigation, and
+  the star chart. It filters a view of the graph without changing coordinates,
+  progress, source truth, uncertainty, or cross-language navigation.
+- Phase 1 mixed-project fixtures, pure frontend focus/chart contracts, packaged
+  production SPA, public documentation, and a versioned `v0.2.0` wheel.
+
+## [0.1.0] - 2026-07-19
+
+### Added
+- Repository scaffold: README, CLAUDE.md agent brief, docs, docs-site (Astro + Starlight), CI, community files.
+- Deterministic Python AST parser with language-neutral graph models, source spans,
+  imports and calls with explicit certainty, entrypoint ranking, render metadata,
+  file hashes, partial-parse reporting, and schema-versioned JSON.
+- `codemble parse <path> --out graph.json` CLI command.
+- Parser fixture suite covering exact resolution, ambiguity, external calls,
+  ignored files, syntax errors, entrypoints, centrality, and byte determinism.
+- Deterministic galaxy and system coordinates with one source module per region,
+  aggregated import routes, LOC sizing, centrality brightness, and Home markers.
+- `codemble <path>` local FastAPI server with graph/source APIs, production SPA
+  serving, scripted three-level semantic zoom, keyboard navigation, responsive
+  observatory UI, WebGL failure handling, and a 1,000-node renderer probe.
+- Web build gate in CI and `scripts/dev.sh` for the backend/Vite development loop.
+- Study payloads with exact source lines, parser-proven neighbor evidence, and
+  clickable `file:line` citations in the responsive study panel.
+- Deep narration module with direct Anthropic Messages and OpenAI Responses
+  adapters, environment/TOML BYO-key configuration, file-hash disk caching,
+  response grounding validation, and explicit no-key/error states.
+- Parser-proven Python concept annotations for decorators, comprehensions,
+  generators, context managers, async/await, dunder methods, exception handling,
+  and type hints, serialized in graph schema 2.
+- Python Lens notes anchored to exact source lines plus a language star chart
+  that separates concepts encountered, structures studied this session, and
+  graph-derived understanding without inventing progress.
+- Four deterministic active-check families derived and scored only from call
+  edges, import edges, direct callers, and parser-ranked entrypoints.
+- Region illumination persisted atomically under `~/.codemble/progress`, with
+  per-region file signatures so editing one file re-dims only its own system.
+- Responsive System check flow with explicit wrong-answer evidence, suite
+  progress, restart-safe completion, and star-chart understanding updates.
+- Honest Home calibration when top-ranked entrypoints are ambiguous, plus a
+  parser-validated `--entrypoint` override.
+- A 300-file Phase 0 guard with interactive subdirectory selection and an
+  explicit non-interactive `--path` route.
+- Unchartable syntax-error nodes, raw-source access, and model narration
+  suppression for partial parses.
+- Production SPA assets inside the Python wheel, versioned `pipx`/`uvx` Git
+  install routes, an automated real-app demo recorder, and the v0.1.0 GIF.

{codemble-0.3.1 → codemble-0.5.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,55 @@ 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, and were released together as **v0.4.0** (tag `v0.4.0`, published
+to PyPI, verified end to end from a clean `uvx codemble==0.4.0` install: the
+wheel's SPA bundle is byte-identical to the tag, all 27 regions draw unclipped,
+and the galaxy renders deep space with no console errors). Phase C (M13:
+~1,000-file scale with staged parse progress) has since shipped from that
+plan: parsing now runs on a worker thread behind a `202`-accepted picker
+select and a polled `GET /api/picker/progress` through five honest stages,
+cancellation is checked between files and a crashed worker reports as an
+in-app error rather than a hung server, the scale cap moved 300 → 1,000 with
+the over-cap prompt offering clickable busiest scopes plus a home-jailed typed
+path, a one-pass check index replaced the per-region edge scans
+(byte-identical suites, pinned by a golden fixture before the refactor),
+`/api/graph` and `/api/map` responses are now cached with invalidation on
+light-up, Home change, and binding, and a Clear this project's progress
+control was added to the star chart. A dedicated verification pass at a
+realistic ~1,000-file project then found the `resolving` stage — the slowest
+one — showed no moving signal for most of the wait; the fix narrates its real
+sub-steps instead of leaving the screen static, and a parser hotspot found
+alongside it (an O(definitions × modules) module-resolution scan in the Python
+adapter) was fixed too, together taking real parse wall-clock on a 1,000-file
+Python project from roughly 11.5s to roughly 7.5s with byte-identical output.
+Suite hermeticity was also closed on the read side: `CODEMBLE_DATA_DIR` now
+relocates the narration cache and the `config` file as well as saved progress
+through one `codemble/paths.py` helper, and the test suite clears every
+provider variable `from_environment` reads, so a server test can no longer make
+a real billed API call against a developer's exported key. A pre-release
+re-audit then closed a cluster of first-run gaps that converged on the
+Easy-default learner (who lands on the 2D Map): the coach-marks and footer now
+teach the layer the learner is actually on, the audience gate and coach-marks
+no longer stack as two modals, the no-entrypoint Map tabs stop pointing at a
+Change Home button that isn't shown, language focus now filters the Map as a
+frontend projection, and a parse `bind` that outlasts a cancel can no longer
+rebind a released project. Phase C plus that gap-fix wave shipped as **v0.5.0**;
+the parse work collided with an independent implementation of the same three
+foundational commits on `main`, reconciled by taking the branch's verified
+superset while preserving main's unique `CODEMBLE_DATA_DIR`/config-isolation
+fix, which lived in files the branch never touched.
 
 ### M0 — Repo, docs & website scaffold ✅ (2026-07-19)
 - [x] Root: README, LICENSE (Apache-2.0), CoC, SECURITY, CONTRIBUTING,
@@ -309,6 +354,48 @@ 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.
+
+### M13 — Galaxy UX Phase C: scale ✅ (2026-07-20)
+- [x] Threaded parse behind `202` select, `GET /api/picker/progress`, and a
+      staged loading screen with real file counts
+- [x] Cancellation checked between files; a crashed worker becomes an error
+      state, never a hung server
+- [x] Scale cap 300 → 1,000; clickable busiest scopes plus a jailed path field;
+      suggestions in the non-TTY CLI refusal
+- [x] One per-bind check index replacing the per-region edge scans, pinned by a
+      golden suite fixture
+- [x] Cached `/api/graph` and `/api/map` documents invalidated on light-up,
+      Home, and binding
+- [x] Terminal stage lines for `codemble <path>`; reset-progress control
+
+**Acceptance:** a ~1,000-file project parses with live progress and reaches an
+interactive galaxy; re-fetching the graph does not re-sort the world; the scale
+prompt is actionable entirely in-app; generated check suites are byte-identical
+to before the index change.
+
 ## Decision Log **[AGENT-MAINTAINED — append only]**
 
 | Date | Decision | Why |
@@ -360,14 +447,28 @@ 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 |
+| 2026-07-20 | `CODEMBLE_DATA_DIR` owns every home-directory path — progress, the narration cache, and the `config` file — through one `codemble/paths.py` helper; the test suite additionally clears every provider variable `StudyService.from_environment` reads | The variable redirected progress only, while `StudyService` hardcoded `Path.home()` for the other two, so `create_app`'s default study service read the developer's real config and `ANTHROPIC_API_KEY`. Two server tests GET `/explanation` and assert only that a `status` key came back — true of `no_key`, `ready`, and `error` alike — so on a machine with a key they made a real billed API call and cached the reply under the developer's home while still passing. Redirecting the directory does nothing about the process environment, which is why the suite must clear the keys as well. No new variable is introduced, the default stays `~/.codemble`, and explicit `environ`/`config_path`/`cache_root` arguments still win over both channels |
+| 2026-07-20 | Progress reporting is a thread-scoped per-file hook (`note_file_parsed`) bound by `ProjectParser`, not a new `LanguageAdapter` parameter | The public adapter seam must stay unchanged for Phase 2 languages; one hook site per adapter also gives cancellation its exact "between files" meaning |
+| 2026-07-20 | Phase C adds `DELETE /api/progress`, the `CLEAR_PROGRESS` session event, and a `clearProgress` adapter method beyond the shared contract's Phase C rows | The contract's Phase C rows covered parse progress only, while the no-reset-progress-control gap is mapped to Phase C by the spec; recorded here rather than silently widened |
+| 2026-07-20 | Generated check suites are pinned by a committed golden fixture before any performance work touches `checks/service.py` | The Correctness Contract makes suite drift top-severity, and a refactor that changes an answer is invisible without a byte-level pin |
 
 ## 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
@@ -401,7 +502,7 @@ JS/TS certainty and concept evidence remain parser-proven through the unchanged
 
 ## Edge cases & limits
 
-- >~300 supported source files → prompt to scope to a subdirectory (LOD arrives Phase 2)
+- >~1,000 supported source files → prompt to scope to a subdirectory (LOD arrives Phase 2)
 - No clear entrypoint → ranked candidates; user picks Home
 - Syntax errors / partial parses → parse what you can, flag the rest, never crash
 - Missing/invalid key → galaxy + structure + checks work; explanations show "add your key"