Documentation
Documentation is a first-class project artifact. Architecture and UX contracts are updated before implementation when behavior changes.
The root README is the public summary. For a specific topic, use the canonical document below. Within its own subject, a canonical document takes precedence over a historical STEP report. If two canonical documents disagree, resolve the conflict before implementation; do not silently choose one.
Source-of-truth order
- Architecture: compositor ownership and technical invariants.
- UX contract: user-visible behavior and interaction invariants.
- Packaging: binary and package coexistence.
- Upstream maintenance: provenance and forward ports.
- Development: reproducible workflow.
- Known limitations: current support boundary.
- Roadmap: ordered future work, not proof of implementation.
- STEP20A and STEP20B: historical evidence.
Project
| Document |
Role |
Purpose |
| README |
Summary |
Public landing page and current status |
| Contributing |
Normative |
Scope, docs-first flow, checks |
| Changelog |
Historical |
Repository evolution |
| Notice |
Normative |
Attribution boundary |
Architecture and user experience
| Document |
Role |
Purpose |
| Architecture |
Normative |
Runtime model, ownership, IPC, transactions, scene |
| UX contract |
Normative |
Interaction rules, row behavior, undecided choices |
| Known limitations |
Planning/current evidence |
Unsupported and unvalidated paths |
Development, packaging, and upstream
| Document |
Role |
Purpose |
| Development |
Normative |
Build, test, staging, patch workflow |
| Packaging |
Normative |
File ownership, versioning, fallback |
| Upstream maintenance |
Normative |
SwayFX relationship, pinned base, forward ports |
Roadmap and historical reports
| Document |
Role |
Purpose |
| Roadmap |
Planning |
Step goals, exit criteria, required documentation |
| STEP20A |
Historical |
Native foundation implementation evidence |
| STEP20B |
Historical |
First scrollable-row implementation evidence |
STEP reports record what was observed and decided at the time. They are not the canonical source for current behavior. When a STEP report conflicts with current canonical documentation, the canonical documentation wins. The original French reports are preserved as historical artifacts; their opening notices point here.
