Update the architecture atlas

Keep docs/architecture-atlas/ an evidence-backed, versioned view of Curie's current architecture and accepted vision. The JSON snapshots are the source of truth; index.html is a generic renderer.

Create a version

Resolve the exact target commit and the prior registered version. Create the new file and manifest entry with:

python3 .claude/skills/update-architecture-atlas/scripts/new_snapshot.py \
  --version <version-id> \
  --commit <full-target-commit> \
  --branch <branch> \
  --date <YYYY-MM-DD>

Use --from-version when the default snapshot is not the correct baseline. The helper copies data; it does not claim that the copied facts are current.

Never overwrite a registered snapshot. A historical version is immutable. If its renderer needs a compatibility fix, change the generic HTML or bump the atlas schema with an explicit migration.

Research the diff

Read AGENTS.md, README.md, ARCHITECTURE.md, and llms.txt, then inspect:

git diff --name-status <prior-commit>..<target-commit>
git log --oneline --decorate <prior-commit>..<target-commit>

Group changed paths by ownership boundary. For each affected component or cross-component seam, read its scoped CLAUDE.md, INTERFACE.md, relevant ADRs, and the implementation at the target commit. Use generated docs/interfaces.md as an index, not as sole proof when it conflicts with code.

Update only facts that the diff can affect. Preserve untouched descriptions, positions, and identifiers so version comparison remains meaningful. Ground external SDK or API claims in provider documentation or observed behavior.

Model the architecture

• Keep implementations collapsed behind stable roles. Adding another channel, substrate, model endpoint, or MCP server should expand its implementation disclosure, not add another top-level architecture box.
• Show current service-key MCP auth separately from planned per-person OAuth. Service and delegated identity modes must be explicit and have no fallback.
• Use current for shipped routes and planned for accepted or draft vision. Do not draw planned behavior as current because an ADR exists.
• Set bidirectional: true for one request/response route. Opposing raw routes between the same boxes are rendered as one line with two arrowheads and one tooltip; keep both raw routes only when distinct flow steps need their own ids.
• Keep every conceptual node inside its declared zone. Move nodes before shrinking labels or boxes.
• Store detailed text in node, seam, flow, and ADR records. Map bubbles stay title-only; tooltips and the inspector carry the detail.

Classify substitutability, not health:

• green: multiple real implementations exercise the same boundary.
• yellow: one real implementation sits behind a credible clean interface.
• red: replacing it still requires coordinated knowledge or changes across owners.
• planned: the intended boundary is documented but has no real implementation.

Do not promote a seam based on types, tests, or an ADR alone. Name concrete implementations and the evidence that they exercise the boundary.

Decisions and drift

Add or update ADR records when a decision changes the visible current or vision architecture. Link to a commit-pinned public URL and use placeholder identifiers required by AGENTS.md.

Re-verify every documentationDrift entry against the target commit. Remove a resolved drift. Add a drift only when current code and current documentation make different claims, and include resolvable evidence ids. Creating, closing, or commenting on GitHub issues is a separate external mutation and requires explicit authorization.

Validate and preview

Run:

python3 .claude/skills/update-architecture-atlas/scripts/validate_atlas.py
python3 -m http.server 8767 --directory docs/architecture-atlas

Open http://localhost:8767/ and inspect Current, Vision, and Delta at desktop width. Confirm the new version selector entry, rich route tooltips, collapsed implementation disclosures, and that no box overlaps or escapes its zone. Stop the temporary server when verification is complete.

Finish with the exact target commit, compared range, changed architecture facts, remaining uncertainty, and the validator output. Do not run product E2E tiers for a JSON-and-renderer-only update.