# atlas — agents.md

Project constitution. Inherits from `/srv/CLAUDE.md` (server scope) and
`/srv/apps/CLAUDE.md` (tenant scope). Only rules meeting the admission rubric
(failure-backed, tool-enforceable, decision-encoding, or triggerable) belong
here — no generic advice a model already applies. Budget: ~200 lines.

Model-independence: this file is the source of truth. `CLAUDE.md` is a symlink
to it so Claude Code loads the same content.

## Read first (in order)
1. **`brief.md`** — what this project is, and the stack decision.
2. **`.logs/planning/`** — the build plan: locked decisions, milestones, gates.
3. **`/srv/projects/standards/README.md`** — server-wide coding standards
   (dispatches by stack: `coding.md` → your stack doc → `frontend.md`).
4. **`.logs/handoff.md`** — newest-first; where the last session left off.

## Project-specific rules
- **Atlas owns nothing (plan §3.4).** Every view reads source-of-truth files;
  every write lands in a canonical file. There is no database sidecar and no
  event-maintained store, and the auth kit's SQLite store is the ONE
  exception (it is the kit's, not atlas's). A feature that needs "an atlas
  table" is the bible-2.0 failure the plan names — refuse it or redesign it as
  a file. This is a **declared deviation** from `react.md`'s "Postgres from
  day one" and it is deliberate.
- **Comments are `.comments.md` files, parsed on every request** —
  `main/app/services/comments_store.py` is the format's contract (a tolerant
  parser: malformed lines vanish, they never crash). The owner and Claude
  sessions reply by editing `data/comments/guide/<chapter>.comments.md` with
  author `claude` reserved for sessions; the API only ever posts as the
  session user, which is what makes that author meaningful. Keep files
  group-writable (0664) so the shell can edit what the container wrote.
- **Membership, not just a session, gates the guide.** A BW account can sign
  in without ever being added to atlas; `routers/comments.member_user` and
  `/api/whoami.is_member` are the two places that rule lives. A new route that
  serves guide data must depend on `member_user`, never on `optional_user`
  alone.
- **The chapter list is `guide/chapters.ts`; the content registry is
  `guide/content/index.ts`.** A chapter id is also its comments file name and
  its URL segment — renaming one orphans its threads. Add chapters; do not
  rename them.
- **Definitions live in `guide/glossary.ts` only.** The inline `Term` hints and
  the Glossary page both read it; never type a definition into a chapter.
- **The "suite today" table (chapter 7) is a status surface** and may name
  projects; the rest of the guide teaches durable concepts. When a project is
  renamed or retired, that table is the only place that needs an edit.
- **TS shapes for atlas's own two API routes are hand-declared in
  `discussion/types.ts`** — a declared deviation from `react.md`'s
  generated client, accepted because the scaffold ships without the
  three-stage build and the surface is two small shapes. Replace with the
  generated client when the scaffolder gains it; until then, a change to the
  Pydantic models in `routers/comments.py` is a change to that file too.
- **Server state uses the scaffold's fetch pattern** (no TanStack Query yet):
  the kit's own components use it, and atlas has one server-state consumer
  (the discussion panel). Adopt the query layer when a second appears.
- **Deploy gate:** `npx tsc --noEmit` in `main/frontend` and the full backend
  suite from `main/` with the project venv
  (`/srv/apps/atlas/.bw-venv/bin/python -m pytest -q`), both green before
  `srv-gw deploy --build`.

## Operational
- **Manage:** `srv-gw {deploy,restart,logs,status} --project atlas`.
- **Deploy confirmation:** the running version is visible (`/api/meta`, UI
  footer, or equivalent). Every change bumps it and adds a newest-first
  CHANGELOG line — the visible version is how you confirm a deploy landed.
- **Write access:** `atlas-dev` Unix group (setgid + default ACL). New files need
  `chmod 664` / dirs `775`, or `srv-gw fix-permissions --project atlas`,
  so the service user can read them.
- **Create new subdirectories under `sg atlas-dev`.** If the session's groups
  don't include `atlas-dev`, the kernel silently strips setgid on `chmod 2775`
  and files underneath get the wrong group.

## Layout
```
/srv/apps/atlas/          # workspace — docs and runtime state
├── brief.md  agents.md  CLAUDE.md -> agents.md
├── .logs/{planning/, handoff.md, diary.md}
├── .memory/  .archive/  notes/
└── main/                  # the instance — code only
```
Runtime state (uploads, dumps) belongs at the workspace root, not in
`main/`. The compose file and `.env` sit at the workspace root because
`srv-gw deploy` requires them there — a documented deviation until T3.1.