This directory is the user-facing manual and the implementation reference for Koan. User docs explain how to operate Koan. Architecture and design docs capture the current system shape so humans and LLM agents can plan changes from the same baseline.
When code and docs disagree, treat code as the immediate source of truth, then update the relevant docs in the same change.
- User Manual - daily use, workflows, and command guide.
- Onboarding - first-run setup and configuration flow.
- Skills Reference - built-in command reference.
- Provider Setup - Claude, Codex, Copilot, and local providers.
- Messaging Setup - Telegram, Slack, Matrix, Discord, GitHub, and Jira.
Read these before planning or implementing daemon, lifecycle, provider, skill, memory, or integration changes:
- Architecture Overview
- Daemon Runtime
- Mission Lifecycle
- Shared State
- Provider Architecture
- Skills System
- Memory Architecture
- GitHub And Trackers
- GitHub Webhooks
- Design Decisions
users/- user manual, onboarding, and command references.setup/- installation and host runtime setup.providers/- CLI and local model provider setup and behavior.messaging/- messaging and issue-tracker integration setup.operations/- maintenance, self-update, and optional operational tools (dashboard, REST API, auto-update, RTK).architecture/- current daemon design and implementation references.security/- security review docs and threat models.design/- durable decisions, design notes, and larger specs.
Update docs when a change affects user behavior, configuration, command semantics, daemon flow, provider behavior, shared state, safety boundaries, or an important implementation decision. Prefer updating an existing page over adding a new page unless the topic is a new subsystem.