---
type: plan
title: Atlas v1 — the onboarding guide
slug: atlas-v1-guide
status: active
owner: rian
created: 2026-09-05
related:
  - /srv/.logs/planning/server-evolution-2026.md
  - /srv/.logs/planning/evolution-progress.md
summary: >
  Atlas's first content: an interactive onboarding guide that explains what
  rian is building, for a teammate with limited development background, with
  section-anchored comments the owner and Claude answer in place. Decisions,
  what shipped, and what comes next (the plans-index).
---

# Atlas v1 — the onboarding guide

## 1. Why now

The evolution plan reserves atlas as the documentation and navigation portal
(§3.4) and leans on `atlas.riverway.ca` as its domain (§5 Q2). Nothing was on
it. The immediate need (2026-09-05) was a way to explain the architecture, the
intent, the vibe and the standards to a team member so that a one-sentence
request produces the same first moves rian would make. That is atlas's *user
manual* half, so the guide is atlas's first content rather than a separate
site.

## 2. Decisions

- **D1 — A BW app, not a static site.** Comments need identity and the guide
  is internal, so the house standard (Pattern B via the scaffolder) applies.
  Membership in the app (not merely a BW session) gates the content: an
  external client with a BW account must never read the server's internals.
- **D2 — The domain is `atlas.riverway.ca`** (the plan's lean; Q2 was still
  open). Changing it later is a DNS record and a redirect-URI update.
- **D3 — No database.** Atlas is a pure renderer (§3.4 + principle 1). The
  kit's SQLite store is the kit's; comments are files. Declared deviation from
  `react.md`. Rejected: a Postgres sidecar "for later"; an atlas comments table.
- **D4 — Comments are section-anchored `.comments.md` files**, exactly as
  §3.4 specifies, in a hand-editable shape so a Claude session (or rian) can
  reply by editing the file. `data/comments/guide/<chapter>.comments.md`;
  author `claude` is reserved. Rejected: JSON (less readable by hand), a
  database (D3), an "ask Claude" route (atlas-chat is explicitly deferred and
  would need tools).
- **D5 — The guide is authored React content, not rendered markdown.** The
  interactive pieces (clickable diagrams, sorters, quizzes, the worksheet) are
  the point, and a markdown-with-widgets renderer is a bigger build than the
  guide. The plans-index (next) IS a markdown renderer and stays separate.
- **D6 — Reader progress stays in the browser.** Atlas owns nothing; a
  reader's progress is theirs. Rejected: server-side "who finished what".
- **D7 — Project names appear only in the status table** (chapter 7) and the
  worked example uses an invented app. Everything else teaches durable
  concepts, so the guide ages like the standards do.

## 3. What shipped (0.2.0)

Ten chapters (start, the lab, the request flow, security, identity, the
project shape, the standards, caddie, building a caddie app, working with
Claude) with: a clickable substrate/tenants diagram, a request-flow stepper, a
folder-tree explorer, four sorters (gateway-or-not, the five auth patterns,
rule-or-filler, the six states), an ordering exercise for the runbook, a mock
client project page, a design worksheet that posts to the discussion, and an
end-of-chapter quiz per chapter. A glossary page shares one definition source
with the inline term hints. A discussion panel per chapter with per-section
threads, reply, resolve, delete-own, owner moderation, nav badges. Phone-width
layout and dark mode. Backend: `services/comments_store.py` + `routers/comments.py`,
with tests (`tests/test_comments.py`) covering the file round-trip, the
hand-edited-file tolerance, slug validation, permissions and the authz matrix.

## 4. Gates

- Conformance pack green (`new-bw-app.sh --check`) — the full user system.
- Backend suite green incl. the comments tests; `tsc` clean; build clean.
- Security audit run after deploy.
- Behavioural: anonymous → sign-in screen; a signed-in non-member → "not in
  yet"; a member → the guide; a thread posted through the UI lands in the
  file; a reply written into the file by hand renders with the AI badge.

## 5. Next

1. **First real read-through** (adi). Answer comments in place; graduate
   recurring questions into the chapters.
2. **Plans-index** (T4.2's first feature): scan `<scope>/.logs/planning/*.md`
   with `type: plan` frontmatter and render them, signed-in users seeing the
   projects they hold access to. Reads files per request; no store.
3. **Project registry view** after that; then bible retires.
4. Small: fetch display names from the directory for comment authors.