docs(stack): canonical stack handbook for agent onboarding - #130
Merged
Conversation
Adds docs/stack/ — six component docs (postgres, dblab, supabase, zfs, routing, deploy) plus a README with read-order and non-negotiable owner policies. All facts are ground-truth verified from repos and live VM state (audit 2026-07-07); no memory-only claims. Wires the handbook into CLAUDE.md via a SAMO-STACK sync block so every agent session loads the pointer on open. Resolves the PG-version contradiction: 18 is the single documented standard; the samo.team control-plane PG 17 is documented as a known gap. Captures Supabase real state (no full stack deployed anywhere; GoTrue-only on samo.team; plain bcrypt on field-record). Documents the cx23 loopback DBLab minimal profile (verified on samograph 2026-07-07, ~EUR 0 incremental). References: ground-truth audit for #127 (SAMO client package standard). Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
JOB A: rebased onto clean origin/main — no #128 code in diff (docs-only). JOB B fixes: 1. dblab.md: module registry is empty on main; provisioning module lives in HELD PR #128 (not merged). Add explicit "in progress, held" note. 2. Clone image PG version: postgresai/extended-postgres:18-0.6.2 verified published on Docker Hub 2026-07-07 (resolves runbook's earlier UNVERIFIED note). Clone image is PG18. No PG16 mismatch. 3. Broken citations: src/commands/bootstrap.ts -> src/app/bootstrap.ts in postgres.md and routing.md. All src/ refs now resolve on clean main. 4. cx23 minimal profile caveat: added to both zfs.md and dblab.md — measured + proven on samograph but NOT yet formally blessed by Nik (his runbook targets 8 GB+ VMs); pending owner sign-off before it is the standard baseline. Reframed "100x over-provisioned" as measured comparison. 5. ANTHROPIC_API_KEY unconditionally banned in supabase.md (removed the conditional "unless Supabase enabled" qualifier). routing.md heading updated from "two required" to "three in total". zfs.md pool.ts source corrected: pool.ts is parameterized; template.ts line 503 hardcodes tank. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
… prefix consistency
Blockers fixed (verified against source):
1. routing.md — CF token attribution corrected:
- CLOUDFLARE_SAMOCAT (Token 1): removed 'dns status' from 'Used by' —
src/commands/dns.ts:81 reads CLOUDFLARE_API_TOKEN, NOT CLOUDFLARE_SAMOCAT
- CLOUDFLARE_API_TOKEN (Token 2): heading changed from '(Workers deploy only)'
to '(dns status + Workers deploy)'; explains dual-use with different scopes
(dns status needs DNS-read, wrangler needs Workers:Edit); verified against
dns.ts:81, wrangler.toml:15, setup-checklist.md "Two distinct Cloudflare tokens"
- Source citation: bare 'SPEC.md' → 'samo.team/SPEC.md (line 522 diagram)'
(samohost's own SPEC.md is 131 lines and has no routing content)
2. dblab.md — clone-registry state line corrected:
- 'infra/dblab/clone-registry.ts' does not exist in samohost (no infra/ dir)
- Correct: src/state/envs.ts class EnvStore persists to ~/.samohost/envs.json
- Verified: envs.ts docstring line 4 + defaultEnvsPath() line 28
Full audit of all 7 docs — additional inaccuracies fixed:
3. supabase.md: preview.ts 'lines 19-24' → 'line 20' (grep confirms comment at :20)
4. postgres.md: added samo.team/ prefix to all three ambiguous citations:
- prose: 'infra/cloud-init/template.ts' → 'samo.team/infra/cloud-init/template.ts'
- table: 'SPEC.md §7.1 lines 762-764' → 'samo.team/SPEC.md §7.1 lines 762-764'
- inline: '(SPEC.md lines 762-764)' → '(samo.team/SPEC.md lines 762-764)'
samohost's own SPEC.md is 131 lines; lines 762-764 only exist in samo.team/SPEC.md
5. zfs.md: 'infra/zfs/pool.ts' → 'samo.team/infra/zfs/pool.ts' in parenthetical
(the explicit Source line already had the prefix; made the inline consistent)
All src/ paths verified: 12/13 exist on main; src/cloudinit/dblab.ts correctly
noted as 'in progress in PR #128, HELD' (exists on feat/dblab-provisioning-module).
All docs/ references verified present. All samo.team/ file paths verified live.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Replaces the stacked PR #129 with a docs-only branch.
What changed vs #129
PR #129 was accidentally stacked on #128 (~2,400 lines of dblab provisioning code). This PR contains ONLY
CLAUDE.md+docs/stack/(8 files, 0 source code).Diff is docs-only
Files changed:
CLAUDE.md,docs/stack/README.md,docs/stack/dblab.md,docs/stack/deploy.md,docs/stack/postgres.md,docs/stack/routing.md,docs/stack/supabase.md,docs/stack/zfs.md. Nosrc/, notest/, nopackage.json.samorev REQUEST_CHANGES blockers fixed
Module registry / feat: dblab provisioning module + env-create honesty gate (#127) #128 coupling: dblab.md now clearly states the optional-module registry is empty on
main; the provisioning module is in PR feat: dblab provisioning module + env-create honesty gate (#127) #128 (HELD). No assertion that the module is registered.Clone image PG version:
postgresai/extended-postgres:18-0.6.2verified published on Docker Hub 2026-07-07. Clones run PG18. Runbook's earlier "UNVERIFIED" note resolved.Broken citations:
src/commands/bootstrap.ts→src/app/bootstrap.tsinpostgres.mdandrouting.md. All src/ citations verified against clean main.cx23 caveat added: both
zfs.mdanddblab.mdnow state "measured + proven on samograph, but NOT yet formally blessed by Nik (runbook targets 8 GB+ VMs); pending owner sign-off before treating as standard baseline." The CX33+volume comparison is framed as a measurement, not a directive.Minors:
ANTHROPIC_API_KEYunconditionally banned insupabase.md(removed conditional qualifier)routing.mdheading: "two required" → "three in total" (consistent with three token sections)zfs.mdpool source:pool.tsis parameterized;template.tsline 503 hardcodestankNot merged — per brief
🤖 Generated with Claude Code