bde961c6f2
PAF becomes saf/device (history kept), STATE.md dissolves into saf/state.md with the dated era archived, the substrate SAF moves up from souveraine, and every agreement points at saf/INDEX.md and nowhere else. one map, nothing to remember
71 lines
3.4 KiB
Markdown
71 lines
3.4 KiB
Markdown
# SouveraineOS — docs
|
||
|
||
> **The map is [`saf/INDEX.md`](../saf/INDEX.md) — read it first.** This
|
||
> directory is the older doctrinal set; the SAF spine owns the living
|
||
> architecture and is reached from the index.
|
||
|
||
Two subjects live here, and the split is real:
|
||
|
||
- **this directory** — the device. Session authority, lock, power, sensors,
|
||
shell, packaging, hardware.
|
||
- **[`substrate/`](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
|
||
|
||
**The distribution.** [`../distribution/`](../distribution/) — the canonical
|
||
body, package, installer-profile, and release graph. Component repositories
|
||
build the declared pieces; they do not define the OS.
|
||
|
||
**Why.** [`SESSION-AUTHORITY-DOCTRINE.md`](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`](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`](LOCK-DPMS-LESSONS.md) — ordering, the FTS controller,
|
||
suspend, with receipts.
|
||
|
||
**Contracts and status.** [`SESSION-TRUST-ARCHITECTURE.md`](SESSION-TRUST-ARCHITECTURE.md)
|
||
(the contract), [`TRUST-BOUNDARY-MATRIX.md`](TRUST-BOUNDARY-MATRIX.md)
|
||
(what is actually gated), [`SECURITY-AUDIT.md`](SECURITY-AUDIT.md) (P1–P7 and
|
||
the threat register), [`souveraine-components/`](souveraine-components/) (the
|
||
authority binaries and their audit ladder).
|
||
|
||
**Shared state.** [`SHARED-STATE-ARCHITECTURE.md`](SHARED-STATE-ARCHITECTURE.md)
|
||
is the design of record for household tasks, calendar, contacts, and their
|
||
sync. Culver is a Personal-class client; Culver/machined owns identity and
|
||
admission; the shared-state service owns the canonical event trail and local
|
||
projection; QML only renders it. Loro is an offline merge substrate, never an
|
||
authority.
|
||
|
||
**Designs of record.** [`STORAGE-ENCRYPTION.md`](STORAGE-ENCRYPTION.md),
|
||
[`WAYDROID.md`](WAYDROID.md), [`../USB/README.md`](../USB/README.md),
|
||
[`FEDERATION.md`](FEDERATION.md),
|
||
[`session-authority-boot-order.md`](session-authority-boot-order.md).
|
||
|
||
**The shell and its apps.** [`FIRST-CLASS-APPS.md`](FIRST-CLASS-APPS.md) (the
|
||
nine requirements), [`SHELL-ECOSYSTEM.md`](SHELL-ECOSYSTEM.md) (layer registry,
|
||
manifests, guarded methods — the substrate doctrine §13's chaining needs),
|
||
[`SETTINGS-AUTHORITY.md`](SETTINGS-AUTHORITY.md),
|
||
[`AUDIO-PRIVACY.md`](AUDIO-PRIVACY.md),
|
||
[`INTERFACE-ARCHITECTURE.md`](INTERFACE-ARCHITECTURE.md) (intent),
|
||
[`HOW-IT-WORKS.md`](HOW-IT-WORKS.md) (current wiring),
|
||
[`REFERENCE-EXTRACTION.md`](REFERENCE-EXTRACTION.md) (what to steal from whom),
|
||
[`SETTINGS-APP-PLAN.md`](SETTINGS-APP-PLAN.md).
|
||
|
||
**Work.** [`tasks/README.md`](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/`](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.
|