- Python 86.4%
- C 8.4%
- Shell 5.2%
| Filename | Latest commit message | Latest commit date |
|---|---|---|
9e2e193af3
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. |
||
| blueline | ||
| docs | ||
| PAF | ||
| tools | ||
| CLAUDE.md | ||
| START-HERE.md | ||
| STATE.md | ||
SouveraineOS — docs
Two subjects live here, and the split is real:
- this directory — the device. Session authority, lock, power, sensors, shell, packaging, hardware.
substrate/— the agent. Consciousness, memory, sensorium, felt state, federation transport, TUI. Rescued 2026-07-26 out of a gitignored directory on a full disk; read its README before trusting anything in it.
The device — read in this order
Why. SESSION-AUTHORITY-DOCTRINE.md —
§13 first (who owns the device), then §4 (never hold state the protocol owns),
§9 (sensors are evidence), §10–11 (one authority).
What is built. DEVICE-STATE-MACHINE.md — the
unified machine: the audit that found each bug, the evidence model, the error
contract, prior art, source health, and the trail.
What is true of the hardware.
LOCK-DPMS-LESSONS.md — ordering, the FTS controller,
suspend, with receipts.
Contracts and status. SESSION-TRUST-ARCHITECTURE.md
(the contract), TRUST-BOUNDARY-MATRIX.md
(what is actually gated), SECURITY-AUDIT.md (P1–P7 and
the threat register), souveraine-components/ (the
authority binaries and their audit ladder).
Designs of record. STORAGE-ENCRYPTION.md,
FEDERATION.md,
session-authority-boot-order.md.
The shell and its apps. FIRST-CLASS-APPS.md (the
nine requirements), SHELL-ECOSYSTEM.md (layer registry,
manifests, guarded methods — the substrate doctrine §13's chaining needs),
SETTINGS-AUTHORITY.md,
AUDIO-PRIVACY.md,
INTERFACE-ARCHITECTURE.md (intent),
HOW-IT-WORKS.md (current wiring),
REFERENCE-EXTRACTION.md (what to steal from whom),
SETTINGS-APP-PLAN.md.
Work. tasks/README.md is the index. Single-session
units, numbered. Fewer files, not more — a finding goes in the doc that owns
the subject.
archive/ is superseded material kept as evidence. It is not
authoritative and it is not deleted.
The rule that governs all of it
Where a doc and the code disagree, the code is right — fix one or the other in the same change, and never leave a third story.