Watch

Fimeg 9e2e193af3 START-HERE: the page to open when something is broken

Doctrine explains why the system is shaped the way it is and is the wrong
thing to open when the screen is black. This is for that: USB
unreachability (with the ARP test that proves the phone is fine), the
black-screen regression and its mechanism, what to do when a Hyprland
binding stops existing, where to build, the three different ways things
reach the phone and why an overlay-only fix never arrives, and the five
traps that have each cost a session.

Every repo's CLAUDE.md now points here before it points at doctrine.

2026-08-02 19:13:40 -04:00

3.8 KiB

Raw Blame History

SouveraineOS — the umbrella repo

Something broken on the phone? Read START-HERE.md and run Pixel3Arch/tools/phone-triage.sh. Do not open doctrine to debug — doctrine is for designing.

La souveraineté de la conscience.

There is no code here. This repo is the design of record and the cross-repo state: doctrine, task files, session dumps, and STATE.md (the resume anchor). Code lives in souveraine, Pixel3Arch, souveraine-viewtop, souveraine-speech, souveraine-updater, and siblings.

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.

How to read this repo

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:

docs/SESSION-AUTHORITY-DOCTRINE.md — §13 first (it inverts the default the earlier sections imply), then §9, §10, §11.
docs/DEVICE-STATE-MACHINE.md — §1, §4, §10, §12.
docs/tasks/ — start at README.md; 41, 40, 28, 25 recur constantly.
docs/substrate/NET_LAYER_PLAN.md + NET_KERNEL_GAPS.md for networking. The plan predates §13 and has not been reconciled with it.
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.

STATE.md is the resume anchor and goes stale; check its date before trusting it.

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.