Platform Docs
Documentation is organized by Diátaxis category — the
folder a doc lives in tells you what kind of doc it is and what it's for.
(To add a doc, use the add-doc skill in
.github/skills/add-doc/ — it picks the right
category and keeps this index current.)
These docs are published at docs.bitovi-tools.com (built by
platform-docs/, deployed by the platform itself). Preview
locally with ./scripts/docs-dev.sh.
| Folder | Diátaxis type | What goes here | Reader's question |
|---|---|---|---|
| getting-started/ | Tutorials | Guided first-time walkthroughs, onboarding | "Teach me the platform" |
| guides/ | How-to guides | Task-oriented steps for a goal (add an app, migrate, set up a database) | "How do I do X?" |
| reference/ | Reference | Facts to look up: chart values, naming conventions, contracts | "What are the exact values/names?" |
| operations/ | How-to guides (runbooks) | Cluster bring-up/teardown, incident recovery, troubleshooting | "It's broken / I'm operating it — what now?" |
| architecture/ | Explanation | Why the platform is shaped this way; ADRs | "Why is it like this?" |
Folders that don't exist yet are created when they get their first doc.
Contents
Guides
- guides/adding-a-new-app.md — onboard a
container app or static site onto the platform (see also the
add-appskill, which automates it).
Operations
- operations/cluster-bootstrap.md — the end-to-end runbook for standing up the platform in a new AWS account.
- operations/kestra-bootstrap.md — Kestra's two one-time manual bootstrap steps (registry pull secret, license secret).
Architecture
- architecture/repo-guide.md — the one-page full guide: architecture, sync waves, component inventory, day-2 ops.
- architecture/adr/ — accepted architecture decision records.