# CLI-First Arch Gaming OS — Specification Index

This directory is the starting point for project planning and later implementation.

## Source-of-truth rules

- The numbered topic files collectively contain the complete specification.
- They began as a structural split of the original specification and have since evolved through later numbered revisions recorded in the change log.
- `99_FULL_SPEC_ARCHIVE.md` remains the preserved monolithic v0.4 reference and historical source. It is not updated in lockstep with later numbered revisions.
- When updating the project, edit the relevant topic file and keep this index current. Avoid adding a second statement of the same decision elsewhere.
- Open questions must remain explicitly marked as open; proposals are not confirmed requirements.
- Before saving any planning change, apply the mandatory cross-spec integrity procedure in `01_PROJECT_FOUNDATION.md`. Do not guess when a conflict would change scope, release boundaries, architecture, or user-visible behavior; ask the project owner for clarification first.

## Quick navigation

| File | Use it for |
| --- | --- |
| [01_PROJECT_FOUNDATION.md](01_PROJECT_FOUNDATION.md) | Document usage, vision, goals, non-goals, principles, and confirmed requirements |
| [02_ARCHITECTURE_AND_BACKEND.md](02_ARCHITECTURE_AND_BACKEND.md) | System layers, components, process model, unified launcher API/CLI, records, launch plans, and external-client contract |
| [03_PROVIDERS_SESSIONS_AND_INPUT.md](03_PROVIDERS_SESSIONS_AND_INPUT.md) | Steam/Heroic/Lutris/provider strategy, graphical session behavior, runtime profiles, launcher lifecycle, fallbacks, and controllers |
| [04_BASE_PERFORMANCE_RELIABILITY.md](04_BASE_PERFORMANCE_RELIABILITY.md) | Arch base system, performance policy and benchmarking, recovery, privacy, and security |
| [05_FRONTENDS_AND_SESSION_POLICIES.md](05_FRONTENDS_AND_SESSION_POLICIES.md) | Graphical policies, Pegasus integration, fork/custom-frontend policy, and provider-interface behavior |
| [06_DEVELOPMENT_ROADMAP_AND_ACCEPTANCE.md](06_DEVELOPMENT_ROADMAP_AND_ACCEPTANCE.md) | Development environments, validation, delivery phases, and version 1 acceptance criteria |
| [07_RISKS_DECISIONS_AND_HISTORY.md](07_RISKS_DECISIONS_AND_HISTORY.md) | Risks, open questions, decision log, change log, and reference notes |

## Suggested agent reading order

1. Read this index.
2. Read `01_PROJECT_FOUNDATION.md` for scope and confirmed constraints.
3. Read only the topic files relevant to the current task.
4. Before changing architecture or scope, also read `07_RISKS_DECISIONS_AND_HISTORY.md` to avoid reviving rejected or deferred ideas.
5. Use the monolithic reference only for integrity checks or when cross-topic context is genuinely needed.

## Integrity note

The numbered topic files are the current v0.15 source of truth. `99_FULL_SPEC_ARCHIVE.md` preserves the complete monolithic v0.4 specification for historical and integrity checks, so it no longer matches the evolving numbered files byte-for-byte.