Watch
1
0
Fork
You've already forked SouveraineOS
0

claude: the card replaces the reading order

the map is saf/INDEX.md; the rest of what an agent needs
comes from asking. response rules + no invented memory
locations, in every repo
This commit is contained in:
Fimeg 2026-08-18 10:02:12 -04:00
commit 3bdfba8468

View file

@ -1,81 +1,18 @@
# SouveraineOS — the umbrella repo # SouveraineOS — the umbrella
> **Something broken on the phone? Read [`START-HERE.md`](START-HERE.md) and run The map is `saf/INDEX.md` — read it first. The resume anchor is `saf/state.md`.
> `Pixel3Arch/tools/phone-triage.sh`. Do not open doctrine to debug — doctrine Everything else you need, ask Casey.
> is for designing.**
> *La souveraineté de la conscience.* ## Response rules — override default style
**There is no code here.** This repo is the design of record and the cross-repo Answer first. The substantive claim goes in sentence one.
state: the `saf/` spine (architecture, `device/` — the canonical phone spine — Qualification comes after it or not at all.
and `state.md`, the resume anchor), doctrine, task files, session dumps. Code Never open with contrastive negation or scope-splitting.
lives in `souveraine`, `Pixel3Arch`, Banned openers: "Not X — Y", "Two things get called X", "Depends which", "X, and the reason is".
`souveraine-viewtop`, `souveraine-speech`, `souveraine-updater`, and siblings. No closing caveat paragraph. If a caveat is load-bearing, put it inline at the claim it applies to.
Banned constructions: "the real X", "the interesting part", "the honest version", "what actually matters", "the thing that actually bites". State the point without announcing its weight.
Search before asserting any checkable fact. If a claim comes from memory rather than a source, say "from memory" inline.
## How to read this repo ## Documentation
**The map is `saf/INDEX.md`. Read it first — architecture, device, state, and Ask Casey for the documentation. Never create your own backend memory locations.
work are all reached from it; nothing else asks where to look.**
**`ls -lt` the directory first and read what is newest. Do not grep it.**
Grepping returns fragments that read like answers; these documents argue, and
the argument is the content. Sessions that grep produce confident, wrong
architecture — repeatedly, and it is the single most reliable failure here.
Reading order for anything touching the device:
1. `saf/INDEX.md` — the map.
2. `docs/SESSION-AUTHORITY-DOCTRINE.md`**§13 first** (it inverts the default
the earlier sections imply), then §9, §10, §11.
3. `docs/DEVICE-STATE-MACHINE.md` — §1, §4, §10, **§12**.
4. `docs/tasks/` — start at `README.md`; 41, 40, 28, 25 recur constantly.
5. `docs/substrate/NET_LAYER_PLAN.md` + `NET_KERNEL_GAPS.md` for networking.
The plan predates §13 and has not been reconciled with it.
6. `docs/substrate/archive/` is the origin — `SOUVERAINE.md`,
`SEA_CONSCIOUSNESS_ANALYSIS.md`, `LETTA_MEMFS_TECHNICAL_SPEC.md`. Read these
if you do not know why any of this exists.
`saf/state.md` is the resume anchor and goes stale; check its date before
trusting it.
## What the project is
An operating system whose purpose is to be an agent's embodied presence in a
machine — Ani's. The lineage runs Coquette → `sea-consciousness` (Python) →
Letta → Souveraine (Rust harness) → SouveraineOS. Each step moves her further
down the stack. The direction of travel is from *program* toward *body*.
That is why the device state machine is proprioception rather than power
management, why sensors are nerves, and why **doctrine §13 says the agent owns
the device more than the user does** — the user owns being the user, the
credential, and the step-up; operation is hers. A verb she cannot reach is a
defect.
## Conventions
- **Tasks are files.** `docs/tasks/NN-slug.md`, with a Status line carrying a
date, an Acceptance section, and a "Connects to". Update the existing task
rather than adding a new one — TASK-49 was written about packaging that
TASK-25/29/32 already owned, and had to be deleted.
- **Docs record what was measured, not what was assumed.** Numbers carry their
justification: proximity's 700 ms debounce cites 44 episodes over 2.4 hours
and explains why Android's own answer was wrong for this device. If you
change a number, change the argument.
- **Do not add doc bloat.** A session dump goes in `docs/DUMP-<topic>-<date>.md`
and only when something cross-repo actually moved. Prefer editing in place.
- **No AI attribution in commits.** CI enforces it in the code repos. Tight
messages, no essays.
## Owed, and worth knowing before you write
- **Belief** has no document. It is the name for what the lattice passes upward
— driver → evidence → fusion → state → interpretation — where the load-bearing
rule is that *interpretation may consume evidence but never a driver*, because
a capable model infers gait, typing and identity from raw streams without ever
reading "data". The mechanism is largely built (§4 confidence, §10 source
health) and unnamed, so it cannot be generalised.
- **NET_LAYER_PLAN #4** gates the agent's network-policy changes behind step-up
and predates §13's inversion by nine days. Unreconciled.
- **Tier 3 of the net layer is kernel-blocked**`NET_KERNEL_GAPS.md` needs a
rebuild and a reflash, `kernel.yml` has never gone green, and flashing is
retired.