The canonical source for published user, operator, architecture, and contributor documentation is docs.kwatch.dev. This repository owns the code-derived generators and the rules that keep generated references in sync with runtime behavior.

Do not create a second manually maintained copy of public configuration, feature, provider, CLI, RBAC, metrics, health, or architecture documentation here. Root-level repository entry points may link to the website, and implementation-only notes may remain beside code when they are not published.

• Project README — product overview and quick installation.
• kwatch.sh manager — installer and day-to-day manager.
• Upgrading from v0.10.x to v1.0.0 — what to change before the upgrade, what happens on first start, and how to roll back.
• Real-cluster scenarios — regression scenarios and the contributor workflow.
• Configuration catalog — generated settings metadata used by the installer and documentation pipeline.
• Provider catalog — generated provider metadata used by the installer and documentation pipeline.
• Feature catalog — generated capability metadata and dependency information.

• How kwatch works — the pipeline, the four concepts, one incident from crash to message, watch modes, storage, endpoints and the single-replica Lease lock; the published architecture is maintained on kwatch.dev.
• Contributor architecture guide — the package table, import direction rules and where new code belongs.
• The life of an incident — settle, announce, updates, reminders, resolve hold, reopen and supersede, with the timings.
• Contributor guides, each five steps with a real example and test command: add a detector, add a propagation rule, add a source or kind schema, add a message fact, add a labeled scenario.
• What happens to alerts when kwatch restarts — what is kept, resent or lost across a restart.
• Production operations — readiness, restarts, recovery, outage handling, and release operations.
• Configuration notes — offline configuration and endpoint notes; the published reference remains on kwatch.dev.
• Provider notes — offline provider behavior and transport notes; the published reference remains on kwatch.dev.
• Dashboard UI notes — how the dashboard pages read and how its browser notifications work, with their limits.
• Kubernetes coverage — monitored resources and graceful degradation boundaries.
• Permission matrix — feature-to-RBAC guidance.
• Production goals — the quality, scale, reliability and security bar kwatch must meet.
• Release integrity — image, manifest, and chart verification.
• Licensing — project and dependency licensing.
• Third-party notices — bundled notices.
• Trademarks — name and logo usage.

When a setting or behavior changes, update the code and its tests first, then regenerate the site reference and update the relevant website tutorial, how-to, explanation, or runbook. Avoid copying an entire reference page into both repositories.