Reshape and deepen docsite docs

[joshka]

Summary

This rewrites the docsite around a clearer reader path and a more source-backed documentation style.

It is intentionally broader than the incremental direction discussed in #1367. The current change is better treated as a draft staging branch than as a final review-ready PR. It likely wants to be split into smaller, easier-to-validate chunks after closer reading and spot-checking.

The main goals are:

• make the docs easier to read linearly for a first-time self-hoster
• make the sidebar and IA more coherent for non-linear lookup
• expand thin or missing conceptual docs so setup and how-to pages have somewhere deeper to point
• replace low-signal, AI-shaped drafting patterns with denser, more direct technical writing
• verify high-risk behavior and defaults against source, config files, issues, discussions, and maintainer explanations

Reader Path And IA

The top of the docs is now organized around a clearer flow:

• Docs Home
• What Is Komodo
• Setup
• Concepts
• Deploy And Build
• Automate
• Configuration
• How-To
• Ecosystem

This separates page roles more cleanly:

• landing pages route the reader
• concept pages explain the model
• setup pages walk through installation and first-server flow
• how-to pages cover focused operational tasks
• reference pages stay reference-oriented

The sidebar order and labels were tightened so they scan more naturally in /docs, and the docs home / setup / how-to landing pages now align with the actual IA instead of competing with it.

Main Content Changes

Setup Flow

The setup path was reworked around a more usable first-time install sequence:

• Setup
• Install Komodo
• Connect Servers
• Onboarding Keys
• After First Server
• DB-specific reference pages for MongoDB and FerretDB

This keeps the main install path in one place while still preserving DB-specific details and sample files where they matter.

The setup docs now cover:

• Compose-based install flow
• bundled Periphery versus separately managed Periphery
• macOS-specific notes for the Linux-oriented sample stack
• first admin behavior and alternate auth paths
• onboarding and reconnect trust flows
• what to verify after first startup
• what to do after the first connected server is visible

Concepts

The docs now include dedicated concept pages for major parts of the system that previously had to be inferred from setup/reference pages:

• Core
• Database
• Periphery
• Connection Model
• Server
• Repo
• Host Model
• Alerter
• Resources

This gives the setup and how-to pages somewhere cleaner to link when they need to explain rationale, trust, host execution boundaries, provider location, git-backed behavior, or alerting.

Workloads And Automation

The workload model docs were rewritten against source instead of thin field summaries:

• Docker Compose
• Containers
• Build
• Swarm
• Automatic Updates
• Procedures and Actions
• Schedules
• Webhooks
• Sync Resources
• Terminals

These pages now explain what the resource does, which defaults actually matter, how it fits the execution model, and how adjacent resources interact.

How-To Coverage

The How-To section was expanded to cover recurring operational questions that were previously missing or buried in issues, discussions, tutorials, or thinly documented code paths:

• Back Up and Restore
• Add Another Server
• Use a Reverse Proxy
• Configure Git-Backed Workflows
• Install the Komodo CLI
• Configure OIDC / OAuth2 Login
• Trust Custom CA Certificates
• Use Mounted Config Files
• Use Docker Secrets and _FILE
• Use Encrypted Secrets
• Use Containerized Periphery
• Connect Periphery Without Onboarding
• Bootstrap Self-Hosted Git
• Write and Debug Actions
• Run Komodo Locally on macOS

Many of these additions came from trying to document things that were easy to discover in issues, discussions, maintainer replies, tutorials, or source, but harder to find in the docsite itself.

Ecosystem And Developer Docs

The ecosystem section was tightened and expanded:

• API and Clients
• Komodo CLI
• Community
• Development
• Writing Guidelines

The development page now reflects the actual local workflows in the repo instead of older, note-like instructions.

Editorial Direction

This pass intentionally pushes the docs away from common AI-generated writing failure modes.

The docs now lean harder on:

• direct explanation instead of page narration
• fewer, denser sections instead of micro-headings
• prose for relationships and tradeoffs instead of taxonomy dumps
• specific defaults, paths, examples, and operational consequences
• clean links to deeper pages instead of router prose

It also removes or reduces patterns that were repeatedly showing up during review:

• recommendation words without evidence
• teaching-order commentary inside explanation pages
• temporal staging in reference and concept pages
• contrast-template phrasing
• repeated restatement at different temperatures
• connective filler and polished-but-low-signal summary text

The writing rules were captured in docsite/docs/ecosystem/writing-guidelines.md, including:

• a fuller reference version
• a shorter prompt pack
• a compaction-oriented pack that keeps the main editorial constraints intact when summarized

Source-Backed Checks

High-risk pages were checked against source, config files, and setup scripts instead of only being edited for style.

That includes:

• workload entities such as Build, Stack, Deployment, Repo, OnboardingKey, and Alerter
• core and periphery config models
• shipped Compose files and sample env/config files
• the Periphery setup script
• maintainer explanations from issues and discussions where behavior is easiest to understand from prose rather than types alone

This was especially important for:

• defaults and field meanings
• onboarding and reconnect trust flow
• provider and secret scope
• host/runtime behavior
• macOS caveats
• git-backed resource behavior

This improves confidence, but it is not a claim that every rewritten page has been fully validated end-to-end. The change still needs more careful page-by-page reading and runtime spot checks.

Cross-Linking And Navigation

There was a focused pass on missing intra-links so related pages no longer dead-end when they name a concept or adjacent workflow.

This is intentionally selective rather than exhaustive. The goal is to make it easy to go one level deeper when a page introduces an idea, without turning every page into a link hub.

Lint And Formatting

The markdownlint config now applies to the full docs tree instead of a hand-maintained edited-file list:

• docsite/docs/**/*.md
• docsite/docs/**/*.mdx

The docs tree also now enforces readable compact table formatting:

• leading and trailing table pipes
• compact single-space padding instead of manual visual alignment

Validation

• npx --yes markdownlint-cli2
• cd docsite && yarn build

Follow-Up Work

This gets the docsite into a much stronger state, but there is still room for later follow-up in areas like:

• runtime spot-checks against real install flows
• additional alerting and API auth examples
• continued docs growth in the how-to section as new operational questions recur

[joshka]

This is a broad draft/staging branch, not something I expect to be reviewed end-to-end in one pass. (or potentially at all)

The most useful way to look at it is probably to pull the branch locally and browse the built docsite rather than trying to review it page-by-page on GitHub. I have not done the full validation/read-through needed to claim every rewritten page is correct yet, and I expect the useful next step to be splitting this into smaller, better-validated chunks.

One thing that may be worth looking at directly is the writing-guidelines doc added in this branch:
https://github.com/joshka/komodo/blob/joshka/docs-rewrite/docsite/docs/ecosystem/writing-guidelines.md

That captures the editorial rules I was steering against during the rewrite, including anti-AI-slop constraints and guidance pulled from Google, Microsoft, GOV.UK, Digital.gov, and similar sources.