# atlas — brief

<!-- The genesis document: what this is, why it exists, who it's for, and what
     "done" looks like. Write-once-read-always. Keep it thin — it is always
     loaded. Detailed how-it-works goes in .logs/planning/ or docs. -->

**What:** The substrate's documentation and navigation portal at
`atlas.riverway.ca` (port 3159) — evolution plan §3.4. v1 carries the
**onboarding guide**: ten visual, interactive chapters that explain what is
being built (the lab and its tenants, the gateway, security, identity, the
project shape, the standards, caddie and the tools, building a caddie app,
working with Claude) plus a glossary, for a teammate with limited development
background. Every section is commentable; comments are section-anchored
`.comments.md` files the owner and a Claude session answer in place.
**Why:** Rian has trouble explaining the architecture and the intent in
conversation, and Claude's raw answers are hard for a newcomer to follow. A
few hours in this guide should give a new team member the same first moves
Rian would make on "go build a time tracking app for caddie". Later atlas
grows into the plans-index + project registry the evolution plan describes
(T4.2); the guide is its first content.
**Who:** rian (owner) + team members added as app members (adi first).
BW accounts that were never added see a "not in yet" screen, never content.
**Status:** v0.2.0 — the guide, the discussion panel and the glossary shipped
2026-09-05. Next: read-through by the first real reader; answer the comments;
then the plans-index (renders `type: plan` files) as atlas's second feature.

## Where everything is
| Role | Lives in |
|---|---|
| Build plan, decisions, gates | `.logs/planning/01-atlas-v1.md` |
| Session handoff (what next) | `.logs/handoff.md` |
| Project constitution | `agents.md` |
| The guide's content (chapters) | `main/frontend/src/guide/content/` — one file per chapter |
| The chapter list (ids, order, titles) | `main/frontend/src/guide/chapters.ts` |
| Glossary definitions | `main/frontend/src/guide/glossary.ts` |
| Comments (runtime state) | `data/comments/guide/<chapter>.comments.md` |
| Version history | `CHANGELOG.md` |

## Stack
The BW-app scaffold as generated (FastAPI + React 18 SPA, one Python process,
the vendored auth kit + React admin pack), with **no database sidecar**: atlas
is a pure renderer that owns nothing (plan §3.4, principle 1 — the filesystem
is the database). The auth kit keeps its stdlib SQLite store under `data/`; the
guide is authored React content; comments are markdown files. Standards
dispatch: `coding.md` → `react.md` → `frontend.md`, with the deviations
declared in `agents.md`.

## Not doing
- **No state of its own.** No Postgres, no event-maintained store, no
  "atlas database". Every view reads files; every write lands in a canonical
  file. If a feature needs a store, it is becoming bible-2.0 — stop.
- **No caddie-ui pack.** Atlas is substrate, not a caddie app; it shares the
  side-panel habit, not the chrome.
- **No atlas-chat, no tools.** If a chat is ever built it has no tools,
  enforced structurally (plan §3.4).
- **No reader tracking on the server.** Progress and quiz scores live in the
  reader's browser only.

## Known gaps
- Comment authors show as usernames (capitalised); the directory's first
  names are not fetched.
- The guide names live projects (caddie, punchlist, scout, easel, ticket,
  with, hosting) in its "suite today" table — a status surface that will
  churn and must be refreshed when the suite changes.
- No notification when a comment lands; the owner reads the discussion (or
  the files) on a visit. A bell is deliberately not built (one inbox, later).
- The plans-index and project registry (T4.2's real scope) are not started.