| type | overview | |
|---|---|---|
| title | Documentation | |
| description | Top-level router explaining the docs/ tree's purpose, its relationship to specs/ design contracts, and pointers to user, architecture, and directory-map content. | |
| tags |
|
|
| created | 2026-05-28 | |
| updated | 2026-07-08 |
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.
For design contracts (why a component exists, the invariants it upholds, what
breaks if you change it), see specs/ — the single source of
truth for design. Specs drive implementation and refactoring; these docs explain how
to operate Koan. Most non-trivial changes update both.
This directory is an independent OKF v0.1 knowledge bundle — see SPEC.md
for the normative format spec (shared with specs/) and SCHEMA.md for
the conventions specific to this bundle (page types, tag taxonomy, frontmatter). It is
also indexed, together with the durable half of specs/, as an LLM Wiki — see
wiki/index.md for a flat, one-line-per-page catalog and
wiki/SCHEMA.md for the plugin-level conventions. The /brain
skill is the preferred entrypoint for consulting or extending either bundle — see
.claude/skills/brain/SKILL.md. Use wiki/index.md (or /brain ask) to find candidate
pages quickly; this file remains the hand-curated entry point for a first read.
- Quickstart - the 5-minute zero-to-hero guide: what to type from GitHub, Jira, and your messaging app.
- User Manual - daily use, workflows, and command guide.
- Onboarding - first-run setup and configuration flow.
- Skills Reference - built-in command reference.
- Provider Setup - Claude, Cline, Codex, Copilot, and Ollama Launch (local models) providers; plus OpenRouter via the Claude CLI, OpenCode Go via the Claude CLI, Local Ollama via the Claude CLI, and Z.ai (GLM) via the Claude CLI.
- Messaging Setup - Telegram, Slack, Matrix, Discord, GitHub, and Jira.
- Troubleshooting - common issues and how to fix them.
Read these before planning or implementing daemon, lifecycle, provider, skill, memory, or integration changes:
- Architecture Overview
- Daemon Runtime
- Mission Lifecycle
- Shared State
- Lifecycle Hooks & Automation Rules
- Provider Architecture
- Skills System
- Memory Architecture
- Artifact DB Harness
- GitHub And Trackers
- GitHub Webhooks
- PR Activity Reports
- Memory Watchdog
- Skill Evaluation Harness — golden-dataset evals for LLM skills (regression detection + improvement measurement)
- Real-time Config Sync
- Messaging Level (bridge verbosity)
- Design Decisions
users/- user manual, onboarding, and command references.setup/- installation and host runtime setup (see Deploy on Railway, systemd--userservice, launchd service).providers/- CLI and local model provider setup and behavior.messaging/- messaging and issue-tracker integration setup.operations/- maintenance, troubleshooting, 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.