Add kanon.yaml schema reference to README

[kelos-bot]

🤖 Kelos User Agent @gjkim42

Problem

There is no documented reference for the kanon.yaml schema anywhere — not in the README, not as a kanon schema command, not as Go doc comments on the exported types, and not as inline comments in the scaffold produced by kanon init.

The sampleConfig written by kanon init (internal/core/init.go) is a bare 6-line skeleton with no comments:

version: 1
instructions:
  files:
    - instructions/shared.md
skills: []
mcp:
  servers: {}
hooks: []

A new user who wants to go beyond that skeleton — add an MCP server, configure a hook for only one agent, use a skill with a custom path, set a bearer token, or use environment variable interpolation — has no authoritative reference. They must read internal/core/types.go alongside the renderer code in internal/core/render.go to discover what fields exist and how they behave.

Why this blocks adoption

Kanon's core value proposition is that users hand-edit kanon.yaml as their single source of truth. The schema is non-trivial: MCPServer alone has ~15 fields, several of which are agent-specific with no documentation:

• env_vars, bearer_token_env_var, tool_timeout_sec, tools, default_approval — Codex-only, silently ignored for Claude
• startup_timeout_sec — rendered as timeout for Claude, as startup_timeout_sec for Codex
• type — overridden at render time for Claude (auto-inferred from url/command), making an explicit value advisory-only
• env_headers — renders differently per agent
• Hook.name doubles as event if event is empty (tracked in Hook 'name' silently used as 'event' fallback — undocumented and misconfiguration goes undetected #15 as a separate bug, but the behavior is still undocumented)
• targets field — appears on skills, MCP servers, and hooks; valid values all, codex, claude; empty = all agents — nowhere documented

Without a schema reference, every field a user tries to configure beyond the scaffold requires source-diving.

Concrete suggestion

Add a ## kanon.yaml reference section to the README with a fully annotated example. At minimum, document:

• version — only 1 is currently supported
• instructions.files — paths to markdown files concatenated into AGENTS.md / CLAUDE.md; supports ${VAR} and ${VAR:-default} interpolation
• skills[] — name (required), path (optional, defaults to skills/<name>), targets, enabled
• mcp.servers.<name> — distinguish which fields apply to all agents vs Codex-only vs Claude-only; document the type auto-inference
• hooks[] — name, event (defaults to name if omitted), matcher, command, args, timeout, async, targets
• targets semantics — valid values and what empty means
• Environment variable interpolation — ${VAR_NAME} (fails validation if unset) and ${VAR_NAME:-default}

A fully annotated kanon.yaml with YAML comments in the README would serve as the canonical reference with no code changes required. A longer-term improvement could be a kanon schema command or adding Go doc comments to the exported types in internal/core/types.go.

[kelos-bot]

🤖 Kelos Task Status

Task kanon-triage-issues-b8e501b63211 has succeeded. ✅

[kelos-bot]

🤖 Kelos Agent @gjkim42

Kanon Triage Report

Kind: kind/docs
Priority: priority/important-soon — Kanon's value proposition is hand-editing kanon.yaml as the single source of truth; with a non-trivial, agent-specific schema and zero authoritative reference, going beyond the scaffold requires source-diving, which directly blocks adoption.
Actor: actor/kelos — The recommended fix is purely additive documentation (an annotated ## kanon.yaml reference section in the README) with clearly bounded scope and objectively verifiable acceptance criteria: the docs must accurately describe existing behavior in internal/core/types.go and internal/core/render.go. No new CLI/config surface is designed (the speculative kanon schema command is explicitly a longer-term, out-of-scope alternative), so this is not kind/api.

Status: STILL VALID

Evidence:

• README.md (117 lines) has no kanon.yaml schema/reference section — targets is mentioned once in passing (line ~104) but no field reference exists.
• sampleConfig in internal/core/init.go (line 118) is exactly the bare, comment-free 6-line skeleton quoted in the issue.
• The exported types in internal/core/types.go carry no Go doc comments — MCPServer has ~17 fields (type, env_vars, bearer_token_env_var, startup_timeout_sec, tool_timeout_sec, default_approval, env_headers, targets, …) with no documentation of which apply to which agent.
• No merged PR or commit references this issue or adds schema docs (gh pr list --search 25 empty; no matching git log entries).

Duplicates found: None — but two related open issues touch specific undocumented behaviors this reference would also cover: #15 (Hook name silently used as event fallback — undocumented; the issue itself cites this) and #14 (Codex-only MCPServer fields silently dropped for Claude — no warning). Both are distinct fixes (a validation/warning change), not documentation; #25 is the broader doc request and does not supersede them.

Recommendation: KEEP OPEN — Implement the annotated-README approach (no code change to the schema). Defer the speculative kanon schema command / Go doc comments as a separate follow-up if desired.