📖 User documentation lives at tunaos.org — a Docusaurus
site in the tuna-os/docs repo. Installation
guides, variant overviews, system requirements, and companion-project docs all
live there. That is the canonical, user-facing home; this folder is not
mirrored to it.
The old in-repo mdBook (docs/book/) was removed once tunaos.org went live — it
duplicated the same user-facing content. (Its GitHub Pages deploy workflow was
already retired separately.)
- Roll your own gives the edit and build path.
- Primary configuration wiring lists the editable inputs, the generated adapters, defaults and unsupported operations.
- The package editor shows how to search and preview package additions. Flatpak declarations cover the separate application policy.
- Fork delivery defines the branded install, update and recovery journey. That journey is not yet complete.
The migration plan is design history. It is not the current schema.
These are developer/maintainer references that aren't part of the user-facing site:
| Doc | What it covers |
|---|---|
| CONTRIBUTOR-FIRST-PR.md | Five small tasks, fork commands, checks, and review help |
| CONTRIBUTOR-ROADMAP.md | Learning stages, weekly help, recognition, and program goals |
| GOVERNANCE.md | Community governance model: roles, authority, and lazy consensus decision process (#1168) |
| BUG-REPORT-EXAMPLE.md | Fictional bug report with reproduction steps, evidence, and privacy placeholders |
| review-rubric.md | PR review rubric: checks, green-criteria impact, and issue scope |
| BETA-RELEASE-READINESS.md | BETA product release gates, owners, audit and consumer documentation handoff (#2935) |
| AGENT_GUIDE.md | Repo architecture: variants, flavors, build stages, key files |
| HUMMINGBIRD.md | Fedora Hummingbird variant architecture, rolling release model, and package snapshot state |
| architecture/reusable-build-image-decomposition.md | Architectural plan for decomposing reusable-build-image.yml monolith |
| INSTALLER_SCREENSHOTS.md | Visual step-by-step walkthrough of the GUI installer for GNOME and Cosmic |
| build-pipeline.md | CI/CD workflow and build-stage overview |
| ci-troubleshooting/ | Diagnosing and fixing common CI failures |
| CI-WORKFLOW-PUBLISHING.md | Recovering GitHub App permission for workflow-file fixes (#1557) |
| LINTING.md | Pinned lint tool versions, bootstrap, and fail-closed gate contract |
| WORKFLOW-PERMISSIONS-AUDIT.md | Generated organization workflow permission audit at recorded repository commits |
| DEPENDENCY-FRESHNESS.md | Org-wide Renovate policy, Dependabot coordination, pinning, and health checks (#2833) |
| ../runbooks/rollback-a-bad-image-promotion.md | Containing a bad container image promotion: repointing the bare tag to a last-known-good dated tag |
| mkosi-investigation.md | Notes from the mkosi-based image build investigation |
| PIPELINE.md | Build pipeline reference: stages, workflows, artifact flow |
| PRIMARY-CONFIG-MIGRATION.md | Migration plan for unified tunaos.toml primary configuration (#3433, #3474) |
| PACKAGE-AUTHORING.md | Offline, index-backed package policy authoring tool for tunaos.toml |
| BASE-PACKAGE-SEARCH.md | Upstream base-image package search tool and catalog configuration |
| FLATPAK-DECLARATIONS.md | Primary Flatpak preinstall declarations in tunaos.toml and policy generation |
| ISO-BUILDER-CONFIG.md | ISO builder presentation configuration in tunaos.toml and exporter check |
| VENDORED-PARSER.md | Reviewed pure-Python Tomli vendor import, version pinning, and provenance check |
| OCI-RPM-CONSUMER.md | Opt-in build-only OCI RPM consumer, signature checks, and native dependency resolution |
| OCI-RPM-DIAGNOSTIC.md | One-cell DNF4 diagnostic with pinned inputs; not production qualification |
| BOOTC-CANDIDATE.md | Opt-in native-backend bootc candidate bootstrap and qualification boundaries |
| CONTENT-CLAIM-CHECKLIST.md | What a guide or campaign post must verify before it claims it — image refs, shipped tooling, hardware, readiness (#2289) |
| BRANCH-PROTECTION.md | Current-state audit + proposal for main-branch protection & required CI (#1167) |
| BRANCH-POLICY.md | Branch naming conventions, RFC disposition, and 30-day staleness rules |
| SDLC-ROADMAP.md | Phased SDLC rollout for tunaOS and the org: what Hive already enforces, protection baseline, upstream RFC plan |
| CI_SPEC.md | CI behavior specification |
| JUSTFILE-MODULARIZATION.md | Justfile module standard and cross-repo migration checklist (#508) |
| R2-COST-VISIBILITY.md | Cloudflare R2 cost, retention, and ownership runbook (#1618) |
| TESTING.md | ISO end-to-end test harness |
| INSTALL-PIPELINE-CHECKPOINTS.md | OCR screen checkpoints and visual assertions for ISO installation pipeline runs |
| MATRIX-STATUS.md | Which variant×desktop combinations are actually verified — and which have never been tested |
| EDITION-VARIANT-PAGE-CHECKLIST.md | Every published edition from the tunaos-packages#133 audit vs its tunaos.org variant page & download link (#1308) |
| ASAHI-HARDWARE-TIERS.md | Real Apple Silicon hardware CI: rented Scaleway rental + personal-machine tiers, and the m1n1/boot.bin safety rule both must follow |
| ASAHI-EL10-OBS-PROJECT.md | Open Build Service project for EL10 Asahi packages (#777) |
| BRANCH-HYGIENE.md | Operational checklist for finding and cleaning stale branches |
| GIT-HISTORY-REWRITE.md | Runbook and coordination procedure for rewriting Git history and large blobs (#2290) |
| rhel-setup.md | RHEL 10 (Redfin) local-build instructions |
| ROLL_YOUR_OWN.md | Guide to building custom TunaOS variants for your own use |
| BRANDING.md | What "branded" means across variants, desktop ownership, and asset inheritance |
| FORK-DELIVERY.md | Step-by-step procedure for building and installing a fork-owned branded desktop (#3474) |
| SECURE-BOOT.md | Secure Boot support by variant |
| LUKS-TPM.md | Disk encryption & TPM2 auto-unlock |
| VERIFY-ARTIFACTS.md | Verify TunaOS artifacts — signatures and SBOM attestations |
| INSTALLER-FRONTENDS.md | Installer frontends (cosmic/kde/niri/xfce): verification & parity |
| SCREENSHOTS.md | TunaOS screenshot gallery |
| SCREENSHOT-RELEASE.md | Screenshot URLs on the rolling screenshots release, mapped from the R2 keys (#3470) |
| IMAGE-FACTORY-GATE.md | Image factory completion gate & definition of done (#1283) |
| IMAGE-FACTORY-LIFECYCLE-GATE.md | Image factory lifecycle coverage & required gate (#1278) |
| ../VARIANT-LIFECYCLE.md | Variant/flavor admission, capacity, promotion, and deprecation policy (#1196, #1175) |
| RELEASE-AUTOMATION.md | Q4 release automation process, cadence, and verifiable publication criteria (#1186) |
| CFP-OSS-NA-2027.md | Open Source Summit North America 2027 CFP talk and panel proposal (#2714) |
| CFP-DEMO-SCRIPT.md | Shot list for the 3–5 min CFP demo video, shared by the 2027 CFP drafts |
| PRESSKIT.md | Project facts, descriptions, screenshots, and media contacts |
| DISTROWATCH-SUBMISSION.md | DistroWatch project submission draft |
| FEDORA45-RELEASE-OUTREACH.md | Fedora release-window positioning, shared adopter call, showcase evidence, and media notes (#3089) |
| FEDORA-OUTREACH-READINESS.md | Bonito completeness evidence and fedora-desktop outreach handoff (#3001) |
| ADOPTION-OUTREACH-STATUS.md | Evidence ledger for DistroWatch, CNCF, and adopter outreach |
| adoption-metrics/README.md | Adoption snapshot runbook, monthly collector workflow, and signal definitions (#2819) |
| outreach/Q4-PRODUCTION-PROSPECTS.md | Five proposed contacts, evaluation requests, and follow-up dates for #3146 |
| SNAPDRAGON.md | Copilot-PC support boundary, boot prerequisites, NPU evidence, test reports and prepared Discussion #93 reply |
| TECH-PRESS-PITCHES.md | Pitch pack for Linux technology press, with guardrails on what we may claim |
| outreach/LWN-FEATURE-PROPOSAL.md | LWN feature research, author policy, and outreach handoff (#3113) |
| ADOPTION-CALL.md | Public call for adopters and evaluation feedback |
| FEDIVERSE-PLAYBOOK.md | Release-announcement playbook for Fediverse communities |
| REDDIT-LEMMY-PLAYBOOK.md | Release-announcement playbook for Reddit / Lemmy |
| YOUTUBER-REVIEW-KIT.md | Linux YouTuber review kit — verified working downloads, ARM story (#1535) |
| FEDORA-MAGAZINE-PITCH.md | Guest-post pitch draft for Fedora Magazine |
| FEDORA45-TESTING-CALL.md | Fedora 45 Beta testing call guide for Bonito variant (#1609) |
| GNOME51-BETA-TESTING-CALL.md | GNOME 51 canary test plan and phased rollout decision (#1775) |
| HACKTOBERFEST-2026.md | Hacktoberfest 2026 contributor runbook |
| IMPROVEMENT_PLAN.md | Historical record of the May 2026 sprint + remaining roadmap items |
| agents/ | Hive agent guides (issue-tracker, triage-labels, domain) |
| adr/ | Architecture Decision Records |
| architecture/shared-just-recipes.md | Delivery contract for shared Just modules across tuna-os repositories (#1977, #508) |
| USER-GUIDE.md | Choosing an image, installing, updating, rolling back, apps, encryption |
| DEVELOPER-GUIDE.md | The whole pipeline and its plumbing, with diagrams |
| INSTALL.md | Building media locally, artifact verification, registry auth, pull troubleshooting |
| HARDWARE.md | System requirements and ARM laptop support status |
| X13S-SUPPORT.md | ARM64 payload evidence and DTB plan for the X13s profile; no hardware qualification |
| IMAGE-TAGS.md | Image tag reference: desktop and hardware suffixes |
| TACKLEBOX-CONTRACT.md | Contract between TunaOS image builds and Tacklebox media tooling |
| GREEN-CRITERIA.md | What "green" means for a cell — the criteria behind the composite score |
| GREEN-MASTER-PLAN.md | The workstreams driving the matrix to green |
| quality.md | Quality dashboard definition and green-criteria enforcement tiers |
| metrics.md | PR and build metrics status, existing reports, and planned pipeline |
These project policies live in this folder:
- VISION.md — project philosophy
- RFC-PROCESS.md — how RFCs are proposed, reviewed, and decided
- FEDORA-BASE-POLICY.md — adopted N+rawhide sequencing for Fedora-based variants (#1171)
- VERSIONING.md — tag scheme and stability tiers
- ADOPTERS.md / ADOPTION-METRICS.md — who uses TunaOS and how adoption is measured
- COMMUNITY.md — contribution ladder, metrics, communication
- CONTRIBUTING-ADVANCED.md — mentorship, office hours, and review escalation
- Q4-MATURE-DEFINITION.md — evidence contract for the Q4 maturity claim
These live at the repository root rather than in this folder:
- ROADMAP.md — project direction and feature status
- CONTRIBUTING.md — how to set up, build, and contribute
- CONTRIBUTORS.md — public credits with merged contribution links
- VARIANT-LIFECYCLE.md — Mature/Beta/Alpha admission gates and deprecation rules
- PACKAGE-SOURCING.md — package origin rules, Tideforge-first, and allowlist (#1319)
- TRIAGE-POLICY.md — triage states and SLAs (adopted, #1195)
- MIGRATION.md — switching from other distros
- SECURITY.md — vulnerability reporting and supported versions
- MAINTAINERS.md — maintainer playbook and bus factor plan
- CODE_OF_CONDUCT.md — community standards
For current project priorities see ROADMAP.md. For how to build and contribute see CONTRIBUTING.md.