Home

OS Project Documentation Hub

This wiki is the canonical developer and contributor knowledge hub for the os project. It organizes the project documentation system using Diataxis and provides the narrative layer that links implementation details, operational procedures, and formal artifacts into one coherent learning path.

The project is a Rust workspace implementing a desktop-style runtime and app shell that can run in browser (wasm32) or Tauri-hosted environments. It is organized into contract, runtime, host, storage-adapter, and app crates, with state managed through a reducer/effect model and persistence routed through typed host/storage abstractions.

Contributor workflows are standardized through Rust-native Cargo/xtask commands for verification, docs contract enforcement, wiki management, performance workflows, and E2E orchestration. Current automated coverage is moderate, with unit/integration testing concentrated in runtime and adapter logic.

Start Here (Recommended Contributor Path)

Read in this order if you are new to the project:

1. Tutorials to get hands-on with the prototype and the documentation workflow.
2. Explanations to understand architecture, core abstractions, technology choices, and design constraints.
3. How-To Guides to complete concrete development, debugging, and operational tasks.
4. Reference when you need exact APIs, commands, registries, and interface facts.

Progressive Learning Path (Narrative Sequence)

Phase 1: Hands-on onboarding (Tutorials)

Use tutorials to learn by doing. Complete the three tutorial pages in order:

1. Tutorial: Run the Prototype Locally
2. Tutorial: Trace a Desktop Action End to End
3. Tutorial: First Documentation Change

Outcome: you can run the system, follow a real runtime flow, and make a documentation change without breaking the docs workflow.

Phase 2: Mental model and rationale (Explanations)

Read the explanation pages in order to understand why the system is shaped the way it is:

1. Explanation: System Architecture Overview
2. Explanation: Browser Host Boundary and Storage Model
3. Explanation: Technology Choices and Tooling Ecosystem
4. Explanation: Performance Engineering Strategy
5. Explanation: Documentation Architecture and Governance

Outcome: you can reason about the system's architectural layers, runtime/effect boundaries, persistence constraints, technology stack, and contributor tooling.

Phase 3: Task execution (How-to Guides)

Use how-to guides after you understand the system basics. They are organized by job-to-be-done:

• verification and docs checks
• app integration and feature work
• persistence/debug investigation
• performance benchmarking and profiling
• documentation updates in pull requests

Start with How-to Run Local Verification and Docs Checks if you are preparing a change.

Phase 4: Exact facts and canonical artifacts (Reference)

Use reference pages for neutral, up-to-date facts:

• Rust APIs (rustdoc) and crate/module surfaces
• architecture maps and system diagrams
• ADR and SOP registries
• command and verification catalogs
• design/material artifact indexes

Start at Reference and branch to the exact registry or map you need.

How the Documentation System Is Split (Canonical Storage by Artifact Type)

The wiki is the canonical navigation and narrative layer. It intentionally links to canonical artifacts stored elsewhere when tooling or validation requirements demand it.

Artifact type	Canonical source	Why
API signatures and code-level behavior	rustdoc generated from //! / /// comments	best place for typed reference + examples
Formal decisions (ADRs)	docs/adr/*	machine-validated governance artifacts
SOPs and operational procedures	docs/sop/*	contract validation + auditability
Formal reference/support artifacts	docs/reference/*, docs/assets/*	versioned source files and diagrams/specs
Reader journey and Diataxis navigation	GitHub Wiki repository	curated contributor-oriented knowledge system

Use Reference: Documentation Artifact Registry for the complete inventory.

Diataxis Boundaries (Strict Intent Separation)

Category	Reader intent	What belongs	What does not belong
Tutorials	Learn by completing a first-time outcome	guided, linear, finishable walkthroughs	exhaustive command catalogs or policy matrices
How-to Guides	Complete a specific task	task procedures, checks, recovery notes	broad architecture narratives
Explanations	Understand why the system is designed this way	rationale, constraints, tradeoffs, principles	operational checklists
Reference	Look up exact facts	APIs, commands, maps, registries, schemas	opinionated guidance or learning sequences

Contributing and Documentation Maintenance

Before editing code or docs, review Contributing Standards (Code + Docs + Wiki). That page defines the required documentation updates for code changes, the cargo wiki status / cargo wiki clone / cargo wiki verify workflow, and how rustdoc, wiki pages, and repo-native docs stay synchronized.