This repository has two kinds of markdown:
- stable user/operator guides
- maintainer notes, design docs, and working plans
If you only want the supported product docs, start with the files below.
../README.md: product overview and end-to-end quick startconfiguration.md: core configuration objects and how they fit togethercommit-signing.md: how valid Git signatures map to platform verificationgithub-setup-guide.md: GitHub repository and credential setupsops-age-guide.md: Secret encryption with SOPS + agesecurity-model.md: controller access, trust boundaries, and the Git credentials Secret shapebi-directional.md: safe shared-path and handoff patternsalternatives.md: nearby tools and when another approach fits betterUPGRADING.md: breaking changes and migration steps, newest first../CONTRIBUTING.md: contributor workflow and validation commands../test/e2e/E2E_DEBUGGING.md: e2e troubleshooting, reuse, and.stamps
These directories are useful when changing internals, but they are not the primary user-facing docs surface:
design/: architecture notes, investigations, and implementation plansfinished/: design docs and reports for work that has shipped or been resolved, kept for historical contextci/: CI/devcontainer rationale and troubleshootingfuture/: ideas that are intentionally deferredserious-bug/: worked bug reports against upstream projectsaudit-setup/: cluster-specific audit delivery notes and examples
These root-level files are also working notes rather than polished user docs:
TODO.md*plan*.md*analysis*.md
If you are cleaning up documentation, that maintainer-notes layer is usually the first place to trim, archive, or merge.