khabotcli 1.0.0

package/.OLD/STEP-3/FACTS.md

@@ -0,0 +1,225 @@
+# KhaBotCLI — FACTS v2 (Post Step-2 — Final Alignment)
+
+> **Purpose:** Updated facts incorporating all your feedback from FACTS v1, Step 2 answers, and research results. Comment ✅/❌/✏️ on items marked with ❓ — everything else is already confirmed.
+
+---
+
+## Identity & Purpose
+
+1. ✅ **Enterprise autonomous agent runtime**, not a developer assistant. Rebuilt OpenClaw with Claude Code-level engineering.
+2. ✅ **API-first, UI-agnostic.** REST API only. No TUI. No streaming. UIs built separately.
+3. ✅ **Local-first, offline-capable.** File-system for definitions, SQLite for runtime data.
+4. ✅ **Forkable/white-label-ready** via `config.json` (renamed from `branding.json`).
+
+---
+
+## Tech Stack (Confirmed by Research)
+
+5. ✅ **Node.js + JSDoc** (no TypeScript)
+6. ✅ **SQLite** via `better-sqlite3` (sync, fastest for local)
+7. ✅ **Express** for REST API (simplest, most maintained)
+8. ✅ **`openai` npm** for LLM client (OpenAI-compatible, native tools/vision/retries)
+9. ✅ **`ajv`** for JSON Schema validation of tool arguments
+10. ✅ **`node-cron`** for daemon scheduling
+11. ✅ **`util.parseArgs`** (built-in) for CLI argument parsing — zero deps
+12. ✅ **Single LLM interface:** `base_url` + `api_key`. No provider-specific code.
+
+---
+
+## Agent Architecture — MODES (Changed from Types)
+
+13. ✅ **Chat, Task, Daemon are invocation MODES, not agent types.** An agent is just an agent. How it's invoked determines behavior. Same agent can support multiple modes.
+
+14. ✅ **Agent defined by two files:** `AGENT.md` (instructions/prompt) + `agent.json` (config/modes).
+
+15. ❓ **Proposed `agent.json` structure:**
+```json
+{
+  "name": "researcher",
+  "description": "Deep research agent",
+  "model": "anthropic/claude-3.5-sonnet",
+  "temperature": 0.7,
+  "modes": {
+    "chat": {
+      "enabled": true,
+      "tools": [],
+      "skills": [],
+      "autoLoadSkills": [],
+      "permissions": {}
+    },
+    "task": {
+      "enabled": true,
+      "tools": [],
+      "skills": [],
+      "autoLoadSkills": [],
+      "maxIterations": 50,
+      "maxDurationSeconds": 300,
+      "permissions": {}
+    },
+    "daemon": {
+      "enabled": false,
+      "cron": "*/5 * * * *",
+      "triggers": ["task.completed", "task.failed"],
+      "tools": [],
+      "skills": [],
+      "permissions": {}
+    }
+  }
+}
+```
+Empty `tools`/`skills` arrays = inherit all defaults. Non-empty = override (whitelist).
+Does this structure match what you had in mind?
+✅ But I just dont understand the `"triggers": ["task.completed", "task.failed"]` part, like which tasks are we talking about, all tasks, or just the tasks of this agent, and whats the benefit of `task.completed` if the agent already marks the task as completed? I forgot th eimportant of this since we decided to make tools to subscribe to task events on specific tasks
+
+16. ✅ **Any agent can be a sub-agent.** No separate sub-agent concept. Explore = an agent with read-only tools, works in any mode.
+
+17. ✅ **Agents are file-defined only.** Discovered on invocation (no file watcher, no startup scan).
+
+18. ✅ **Built-in hidden agents:** compact, title, summary. Use cheaper models automatically.
+
+19. ❓ **Does HEARTBEAT.md stay?** With modes, the daemon config (cron, triggers) moves to `agent.json`. HEARTBEAT.md would only contain the **checklist instructions** the agent reads each tick. Or should the checklist go in AGENT.md with a daemon-specific section? My recommendation: keep HEARTBEAT.md for the checklist (separation of concerns), put scheduling/triggers in `agent.json`.
+✅ ACCEPTED
+
+---
+
+## Model Delegation (v1 Simplified)
+
+20. ✅ **3 model roles for v1** (apply layer deferred):
+    - `main` — reasoning, planning, file edits (str_replace)
+    - `compact` — context compaction / summarization
+    - `title` — session title, session summary
+
+21. ✅ **No apply layer for v1.** File edits via search-and-replace using the main model (like Claude Code). Apply layer is a future optimization.
+
+---
+
+## Tools & Extensions
+
+22. ✅ **Built-in tools (22 tools):** bash, read_file, write_file, edit_file, list_dir, glob, grep, web_fetch, web_search, memory_write, memory_read, todo_write, todo_read, task_create, task_status, task_respond, agent_spawn, agent_message, agent_send, tool_search, sleep, log_write.
+
+23. ✅ **`agent_message`** = sync (blocks, waits for response). **`agent_send`** = async (fire-and-forget, returns message_id).
+
+24. ✅ **Custom JS tools** (`tool.json` + `index.js`). No sandboxing — user's responsibility.
+
+25. ✅ **MCP support** via existing client library. Not the primary extension mechanism.
+
+26. ✅ **Tool discovery: Hybrid tiered loading.** Built-in always in context. Others listed name+description, full schema on-demand via `tool_search`.
+
+27. ❓ **`task_subscribe` tool** — You suggested agents should subscribe to task events (completion/failure). Two options:
+    - **(a)** A built-in tool `task_subscribe(taskId)` that blocks until the task finishes (like `await`)
+    - **(b)** Callback-style: agent registers interest, gets notified via a system message injected into its conversation
+    - **(c)** Just use `task_status` polling (simplest for v1, defer subscriptions)
+    Which approach?
+✅ B and C, I think both are needed for different usecases
+
+---
+
+## Context Engineering
+
+28. ✅ **Auto-compaction** at 85% threshold. Hidden compact agent preserves key decisions, file paths, TODOs.
+29. ✅ **Observation masking.** Old tool outputs replaced with placeholders.
+30. ✅ **Structured notes.** `todo_write`/`todo_read`. TODOs survive compaction.
+31. ✅ **Token tracking** per session/task. Input/output/cache tokens, estimated cost.
+
+---
+
+## System Prompts
+
+32. ✅ **7-layer modular assembly.** Base Core → Safety → Environment → Agent Instructions → Tools → Heuristics → Session Context.
+33. ✅ **System reminders** injected mid-conversation on triggers.
+34. ✅ **Priority hierarchy:** Safety > User message > AGENT.md > SOUL.md > MEMORY.md > Defaults.
+
+---
+
+## Storage
+
+35. ✅ **SQLite** (`~/.khabot/data.db`). WAL mode. Lazy loading. LRU cache.
+36. ✅ **Configurable retention.** 90d sessions, 30d tasks. Archive to gzipped JSONL.
+37. ✅ **Config files stay as files** (agent.json, settings.json, AGENT.md) — human-editable, versionable.
+
+---
+
+## Communication & Orchestration
+
+38. ✅ **Sync messaging:** `agent_message` — blocks, gets response.
+39. ✅ **Async messaging:** `agent_send` — fire-and-forget, returns message_id.
+40. ✅ **Sub-agent spawning** via `agent_spawn`. Isolated context. Returns condensed summary.
+41. ❓ **Sub-agent return control:** You said "maybe the sub-agent is responsible for returned message, or maybe per `agent_spawn` args." My proposal: `agent_spawn` accepts an optional `returnMode` param:
+    - `"summary"` (default) — runtime condenses sub-agent output to ~1k-2k tokens
+    - `"raw"` — sub-agent's final message returned as-is (may be large)
+    - `"lastMessage"` — only the sub-agent's last assistant message returned
+    Does this work?
+✅ ACCEPT
+
+---
+
+## Daemon Mode
+
+42. ✅ **Cron + event triggers** for v1 (task.completed, task.failed, agent.error).
+43. ✅ **HEARTBEAT_OK / HEARTBEAT_ALERT** output contract.
+44. ✅ **Alert routing:** log, webhook, another agent, Ably channel.
+45. ✅ **Conflict handling:** skip | queue | restart when tick fires mid-execution.
+
+---
+
+## Progress & Events
+
+46. ✅ **Agent-driven progress.** Not a fixed schema. The agent pushes whatever progress it wants.
+47. ❓ **Progress mechanism:** How does the agent push progress?
+    - **(a)** A built-in tool `progress_push(data)` — agent explicitly calls it
+    - **(b)** Runtime auto-emits events on each iteration (tool name, duration) + agent can add custom data via `log_write`
+    - **(c)** Both: runtime emits automatic events + agent can push custom events via `progress_push`
+    My recommendation: **(c)** — runtime emits standard iteration events automatically, agent can add custom progress via a tool. This gives both structure (for generic UIs) and flexibility (for agent-specific UIs).
+✅ ACCEPTED Option C, we just add the field `progressState.Type = "iteration"` so APIs can different custom progress from iteration progress 
+
+---
+
+## API & CLI
+
+48. ✅ **REST API** on localhost. No streaming. Optional `X-KhaBot-Secret` auth.
+49. ✅ **CLI modes:** server (`start`), one-shot (`run`), management (`stop`, `status`, `agents`), import, login.
+50. ✅ **Permissions:** deny → ask → allow. **Configurable per agent** in agent.json modes.
+51. ✅ **Two hooks:** PreToolUse, PostToolUse.
+52. ✅ **No LSP for v1.**
+53. ✅ **Testing: Unit + API tests only** for v1.
+
+---
+
+## Ably (Confirmed by Research)
+
+54. ✅ **One channel per KhaBotCLI instance** (`khabot:instance:<instanceId>`).
+55. ✅ **RPC over pub/sub** via `requestId` correlation.
+56. ✅ **`authCallback`** with KhaBot.com-issued scoped tokens (1h TTL, auto-refresh).
+57. ✅ **64 KiB message limit.** Truncate + reference URL for large payloads.
+58. ✅ **<2 min offline = auto-resume. >2 min = messages lost.** Stale request detection.
+
+---
+
+## Compatibility & Import
+
+59. ✅ **Claude Code compatible.** CLAUDE.md → AGENT.md, .claude/ → .khabot/.
+60. ✅ **`khabot import`** with interactive follow-up questions to set up agent modes/config since KhaBot agents differ from Claude Code agents.
+
+---
+
+## KhaBot.com (v1)
+
+61. ✅ **Token validation + registry + Ably credential provisioning.** No usage analytics (AI provider handles that).
+
+---
+
+## What We're NOT Building
+
+62. ✅ No UI. No browser automation. No email/Telegram. No database beyond SQLite. No LLM cost management. No LSP (v1). No apply layer (v1).
+
+---
+
+## Remaining Questions Summary
+
+| # | Question | Options |
+|---|----------|---------|
+| **15** | Does the proposed `agent.json` structure match your vision? | ✅/✏️ |
+| **19** | Keep HEARTBEAT.md for checklist + daemon scheduling in agent.json? | ✅/✏️ |
+| **27** | Task subscription mechanism for v1? | (a) blocking / (b) callback / (c) polling only |
+| **41** | Sub-agent `returnMode` param: summary/raw/lastMessage? | ✅/✏️ |
+| **47** | Progress mechanism: tool only / auto only / both? | (a) / (b) / (c) |

package/.OLD/STEP-4/FACTS.md

@@ -0,0 +1,117 @@
+# KhaBotCLI — STEP 4 FACTS (Plan Refinement)
+
+> **13 changes** applied to the PLAN/ files based on user feedback. 3 questions marked with ❓ for user confirmation — reasonable defaults chosen, adjust if needed.
+
+---
+
+## Changes Applied
+
+### 1. ✅ Removed `commands/` folder
+Claude Code deprecated commands. Removed from `12-folder-structure.md`.
+
+### 2. ✅ Added `skillDiscovery` field to agent.json
+When `false`, no skill names/descriptions listed in system prompt. Agent is skill-blind unless given via `autoLoadSkills`. Default: `true`.
+
+### 3. ✅ Clarified `$ARGUMENTS` template variables
+These are **SKILL.md-only** variables (used when a skill is invoked). Added explicit note to `05-tools.md`.
+
+### 4. ✅ Added `mcpServers` field per mode in agent.json
+Whitelist of MCP server names the agent can use. Empty = all configured servers.
+
+### 5. ❓ Moved root-level files into `.khabot/`
+`AGENT.md` moved from project root to `.khabot/AGENT.md`. Project root stays clean.
+**Default chosen:** Support BOTH locations — check `.khabot/AGENT.md` first, fall back to `./AGENT.md` for Claude Code compat.
+**Question:** Is this dual-location lookup OK, or should we only check `.khabot/AGENT.md`?
+Check only for `.khabot/AGENT.md`, if its a claude code agent, then it should be manually
+**ANSWER:** ✅ Uconverted to a KhaBot agent, this compatibility is adding complexity.
+
+### 6. ✅ Added `disallowedTools` field per mode
+Blacklist alternative to `tools` whitelist:
+- `tools` non-empty → whitelist (only these)
+- `disallowedTools` non-empty → blacklist (all EXCEPT these)
+- Both empty → all tools available
+- Both set → validation error
+
+### 7. ✅ Added `allowedAgents` / `disallowedAgents` to subagent mode
+Controls which agents a sub-agent can spawn/message. Same whitelist/blacklist logic as tools.
+
+### 8. ✅ Added `~/.khabot/skills/` to global folder structure
+Skill resolution order: agent-level → project-level → global → not found.
+
+### 9. ✅ Skill invocation via agent_spawn/agent_send
+When instruction starts with `/skill-name`, runtime triggers that skill on the target agent.
+Example: `agent_spawn(agent: "researcher", instruction: "/deep-analysis What are the security risks?")`
+
+### 10. ✅ Memory system redesign ⭐
+**Agent folders are now STATIC** (read-only, downloadable from registry).
+
+New memory structure:
+```
+.khabot/
+├── memory/
+│   ├── MEMORY.md           ← global memory (always loaded, 200-line cap)
+│   ├── <topic>.md          ← auto-exported memory files
+│   └── agents/
+│       └── <agentName>/
+│           ├── MEMORY.md   ← agent-specific memory (always loaded, 200-line cap)
+│           └── <topic>.md  ← auto-exported agent memory files
+```
+
+Key features:
+- Main MEMORY.md always loaded, capped at ~200 lines (configurable)
+- Auto-export: when exceeding cap, compact model moves older entries to `<topic>.md`
+- Pre-compaction memory: before context compaction, model extracts key learnings → writes to MEMORY.md (model can return `NO_MEMORY` to skip)
+- Memory tools: `memory_write`, `memory_read`, `memory_search` (searches all memory files)
+- Per-agent config: `"memory": { "enabled": true }` in agent.json
+- All memory files listed in system prompt so agent knows what's available
+
+❓ **Question:** Should the 200-line cap be configurable per-agent? And should pre-compaction memory extraction be on by default or opt-in? **Default chosen:** Configurable, on by default.
+**ANSWER:** ✅ pre-compaction memory extraction Configurable, on by default, the 200-line cap be configurable per-agent
+
+### 11. ✅ Message queue for busy agents
+When a message targets an agent that's currently processing:
+- Message is **queued** in SQLite
+- Queue drained at **safe injection points** (between tool calls)
+- Messages tagged `followup: true` → only injected when agent fully finishes
+- Injected as system messages: `[Message from <agentName>]: <content>`
+
+❓ **Question:** When `agent_message` (sync/blocking) targets a busy agent — should it **queue and wait** until the agent processes it, or **fail with "agent busy"**? **Default chosen:** Queue and wait (since it's already a blocking call).
+**ANSWER:** ✅ Queue and wait
+
+### 12. ✅ Heartbeat files moved to `.khabot/heartbeats/`
+```
+.khabot/heartbeats/<agentName>.md
+```
+- Removed from agent definition folder (now static)
+- Removed from project root
+- agent.json daemon mode gets optional `heartbeatFile` field (defaults to `.khabot/heartbeats/<agentName>.md`)
+**ANSWER:** ✅
+
+### 13. ✅ Modularity confirmation
+Added extensibility note to `13-operations.md`. Source code split: `core/`, `api/`, `cli/`, `tools/`, `infrastructure/`. Each concern isolated. New modes, tools, transports don't touch unrelated code.
+**ANSWER:** ✅
+
+---
+
+## Summary of Agent Folder Changes
+
+**Before (mutable):**
+```
+.khabot/agents/<name>/
+├── AGENT.md, agent.json, SOUL.md
+├── MEMORY.md        ← REMOVED (now in .khabot/memory/)
+├── HEARTBEAT.md     ← REMOVED (now in .khabot/heartbeats/)
+├── skills/, tools/
+```
+
+**After (static, read-only):**
+```
+.khabot/agents/<name>/
+├── AGENT.md         ← instructions (read-only)
+├── agent.json       ← config (read-only)
+├── SOUL.md          ← persona (read-only)
+├── skills/          ← skill templates + scripts (read-only)
+└── tools/           ← agent-level custom tools (read-only)
+```
+
+All mutable state lives in `.khabot/memory/` and `.khabot/heartbeats/`.

package/.OLD/STEP-5/AUDIT.md

@@ -0,0 +1,242 @@
+# KhaBotCLI Plan Audit Report
+
+**Spec version:** v3.0
+**Audit date:** 2026-03-01
+**Files reviewed:** 14 (PLAN/README.md through PLAN/13-operations.md)
+
+---
+
+## 🔴 Contradictions
+
+1. **README lists 3 modes, spec defines 4** — README.md ToC entry for 03-agents says `(chat/task/daemon)`, omitting `subagent`.
+   - README.md line 13: `"modes (chat/task/daemon), agent.json, sub-agents"`
+   - 03-agents.md line 5: `"chat, task, daemon, subagent"`
+   - Recommendation: Update README to `(chat/task/daemon/subagent)`.
+
+2. **`task_create` sub-agent mode trigger is contradicted within the same file** — The sub-agent mode section intro says `task_create` triggers sub-agent mode, but the detail section says `task_create` uses `modes.task`.
+   - 03-agents.md line 144: `"Another agent calls agent_spawn(agent: "<name>") or task_create(agent: "<name>")"`  — implies both trigger subagent mode.
+   - 03-agents.md line 154: `"task_create — Asynchronous. Creates a task in the queue. Parent can continue or wait. Uses modes.task."`
+   - Recommendation: Fix line 144. Only `agent_spawn` triggers `modes.subagent`. `task_create` always uses `modes.task`. The intro line is misleading.
+
+3. **Agent discovery: "on invocation only, no startup scan" vs startup daemon auto-start and `GET /agents`** — Three files conflict on when agents are discovered.
+   - 03-agents.md line 170: `"Agents discovered on invocation only (no file watcher, no startup scan)"`
+   - 08-api-cli.md line 115: `"Loads all agent definitions, auto-starts daemons, exposes REST API"`
+   - 13-operations.md line 20: `"Auto-start all agents with daemon.enabled: true"`
+   - 08-api-cli.md line 16: `GET /agents` — `"List all discovered agents"` (requires scanning)
+   - Recommendation: Clarify. Either (a) there IS a startup scan for daemon auto-start and `GET /agents` (remove "no startup scan" from 03-agents), or (b) daemons are explicitly registered and `GET /agents` returns only previously-invoked agents. Option (a) is simpler.
+
+4. **`agent_message` context type: "shared session" vs "temporary chat session"** — The summary table and the description disagree.
+   - 06-communication.md line 124 (table): `agent_message` → Context: `"Shared session"`
+   - 06-communication.md line 14: `"Runtime creates a temporary chat session for Agent B"`
+   - Recommendation: Fix the table. A temporary session created by the runtime is NOT "shared". Change to `"Temporary session"` or `"Dedicated session"`.
+
+5. **`agent_message` busy-agent behavior: "after finish" vs "at safe injection point"** — Two descriptions in the same file contradict.
+   - 06-communication.md lines 17-19: `"Message queued. Agent A blocks until B finishes current work, then B processes the queued message"`
+   - 06-communication.md lines 194-195: `"The message is queued, and once the target processes it (at the next safe point or after finishing), the response is returned"`
+   - Recommendation: Pick one. If `agent_message` messages are injected at safe points mid-loop (like normal queued messages), state that clearly. If they wait until finish, state that. The two descriptions are incompatible.
+
+6. **Claude Code compatibility: "reads CLAUDE.md" vs "must convert via import"** — Three files give different impressions.
+   - 01-vision.md line 23: `"Claude Code ecosystem compatible — reads CLAUDE.md, .claude/ settings, skills, commands"`
+   - 03-agents.md line 179: `"Global instructions: .khabot/AGENT.md only. No fallback to project root. Claude Code projects must be converted via khabot import."`
+   - 13-operations.md line 72: Section titled `"Claude Code Compatible (Out of the Box)"` but body says `"CLAUDE.md → Converted to .khabot/AGENT.md via khabot import"`
+   - Recommendation: 01-vision.md overstates native compat. Update it to say "Claude Code ecosystem importable" or similar. Clarify in 13-operations that the title "Out of the Box" means the import tool handles everything, not that it's zero-config.
+
+7. **`$AGENT_FOLDER` scope: works in AGENT.md vs "SKILL.md only"** — Two files directly contradict on whether `$AGENT_FOLDER` is resolved in AGENT.md.
+   - 03-agents.md line 108: `"The runtime exposes $AGENT_FOLDER as a template variable in AGENT.md, SKILL.md, and heartbeat files."`
+   - 05-tools.md lines 170-171: `"Template Variables (SKILL.md only) — These variables are resolved when a skill is invoked. They do NOT apply to AGENT.md or agent.json."` — and `$AGENT_FOLDER` is listed in this table (line 180).
+   - Recommendation: Separate `$AGENT_FOLDER` from the SKILL.md-only variables. 03-agents.md is likely correct that `$AGENT_FOLDER` works in AGENT.md, SKILL.md, and heartbeat files. The other SKILL.md variables (`$ARGUMENTS`, `$1`, `${KHABOT_SESSION_ID}`, etc.) are SKILL.md-only. Rewrite the 05-tools.md section to make this distinction explicit.
+
+8. **Schema version tracking: `user_version` pragma vs `schema_version` table** — Two different mechanisms defined for the same purpose.
+   - 07-storage.md line 130: `"user_version pragma tracks current version"`
+   - 07-storage.md lines 107-110: `schema_version` table with `version` and `applied_at` columns
+   - Recommendation: Pick one. `user_version` pragma is simpler and standard for SQLite. If the `schema_version` table adds value (e.g., tracking timestamps), keep it and remove the pragma reference. If not, drop the table and use pragma only.
+
+---
+
+## 🟡 Mismatches
+
+1. **`tasks` table missing `token_cache` column** — Task fields spec includes cache tokens, but the SQLite schema doesn't.
+   - 06-communication.md line 154: `"tokenUsage — input/output/cache tokens + cost"`
+   - 07-storage.md tasks table (lines 66-68): Only `token_input`, `token_output`, `estimated_cost` — no `token_cache`.
+   - Also: sessions table (07-storage.md line 32) HAS `token_cache`. Inconsistency between sessions and tasks tables.
+   - Recommendation: Add `token_cache INTEGER` to the tasks table.
+
+2. **`maxDurationSeconds` (agent.json) vs `timeoutSeconds` (tasks table / API)** — Same concept, different names across files.
+   - 03-agents.md line 58, 11-file-formats.md line 33: agent.json uses `maxDurationSeconds`
+   - 07-storage.md line 65: tasks table column is `timeout_seconds`
+   - 06-communication.md line 153: task fields say `timeoutSeconds`
+   - 08-api-cli.md line 59: create task request uses `timeoutSeconds`
+   - Recommendation: Unify naming. Suggest `maxDurationSeconds` everywhere for config, `max_duration_seconds` for the SQLite column (snake_case convention). Or use `timeoutSeconds` everywhere.
+
+3. **`autoLoadSkills` absent from daemon mode** — Present in chat, task, and subagent modes but silently missing from daemon mode in both agent.json examples.
+   - 03-agents.md lines 74-86: daemon mode has `skills` but no `autoLoadSkills`
+   - 11-file-formats.md lines 49-61: same omission
+   - 11-file-formats.md line 93: field table says `modes.*.autoLoadSkills` — the wildcard implies all modes
+   - Recommendation: Either add `autoLoadSkills` to daemon mode examples, or document why daemon mode doesn't support it.
+
+4. **Ably `maxRequestAge` in 10-ably.md but missing from settings.json** — The Ably spec defines it, the settings.json example omits it.
+   - 10-ably.md line 102: `"maxRequestAge": 60000`
+   - 11-file-formats.md lines 338-343: ably settings only show `enabled`, `instanceId`, `tokenEndpoint`, `requestTimeout`
+   - Recommendation: Add `maxRequestAge` to the settings.json ably section in 11-file-formats.md.
+
+5. **`daemon.triggers` example values differ** — One file shows empty default, the other shows populated values.
+   - 03-agents.md line 77: `"triggers": []`
+   - 11-file-formats.md line 52: `"triggers": ["task.completed", "task.failed"]`
+   - Recommendation: Choose one canonical example. If the default is empty, both should show `[]`. If the example is demonstrating usage, add a comment or note that `[]` is the default.
+
+6. **`KHABOT_AGENT_FOLDER` not in hooks environment variables** — Documented for custom tools but missing from hooks.
+   - 03-agents.md line 117: `"Also available in custom tool execution as the KHABOT_AGENT_FOLDER environment variable."`
+   - 09-permissions.md lines 77-84: Hook env vars table — does not include `KHABOT_AGENT_FOLDER`
+   - Recommendation: Either add it to the hooks env vars table (likely useful), or explicitly note that hooks don't receive it.
+
+7. **Chat API response missing cache tokens** — Token tracking includes cache, but the API example doesn't show it.
+   - 04-runtime.md lines 96-97: `"Input tokens, output tokens, cache tokens"`
+   - 08-api-cli.md line 37: `"tokenUsage": { "input": 1500, "output": 300 }` — no `cache` field
+   - Recommendation: Add `"cache": 0` (or appropriate value) to the chat response example.
+
+8. **`version.json` referenced but absent from folder structure and file formats** — Mentioned in operations, not defined anywhere.
+   - 13-operations.md line 116: `"Each cached agent/tool has a version.json with SHA256 hash"`
+   - 12-folder-structure.md global agents structure (lines 53-55): no `version.json` shown
+   - 11-file-formats.md: no `version.json` format defined
+   - Recommendation: Add `version.json` to the global agent folder structure in 12-folder-structure.md, and define its format in 11-file-formats.md.
+
+9. **`disallowedSkills` implied but never defined** — Field rules claim skills use the same whitelist/blacklist logic as tools, but only `skills` (whitelist) exists.
+   - 03-agents.md line 95: `"Same whitelist/blacklist logic for skills, mcpServers, allowedAgents/disallowedAgents."`
+   - No `disallowedSkills` field in any agent.json example, field table, or file format definition.
+   - Recommendation: Either add `disallowedSkills` to agent.json examples and field tables, or rewrite line 95 to exclude skills from the "same logic" claim if blacklisting skills isn't supported.
+
+10. **`permissions.ask` in settings.json but not in agent.json** — Settings-level permissions have three arrays; agent-level has two.
+    - 11-file-formats.md line 298-301: settings.json permissions: `{ "allow": [], "ask": [], "deny": [] }`
+    - 11-file-formats.md line 95: agent.json permissions: `{ allow: [], deny: [] }`
+    - 09-permissions.md lines 48-51: agent.json example only shows `allow` and `deny`
+    - Recommendation: Document why `ask` isn't available at the agent level (likely because `ask` is an interactive-mode concept, and per-mode permissions are for allow/deny only). A one-line note in 09-permissions.md would suffice.
+
+---
+
+## ⚪ Missing Pieces
+
+1. **Global memory write path** — `memory_write` tool description only references agent-specific memory. No mechanism for writing to project-wide global memory (`.khabot/memory/MEMORY.md`).
+   - Where: 05-tools.md line 16: `"Write to agent's memory (.khabot/memory/agents/<name>/MEMORY.md)"`
+   - 11-file-formats.md line 133: `.khabot/memory/MEMORY.md` described as `"global memory"`
+   - Recommendation: Clarify whether `memory_write` can target global memory (e.g., via a `scope: "global"` parameter) or if global memory is only written by the runtime/user manually.
+
+2. **Built-in tool input schemas** — 24 tools listed with name + description only. No input parameters documented for any built-in tool.
+   - Where: 05-tools.md lines 5-31
+   - Recommendation: At minimum, document key parameters for complex tools (`agent_spawn` returnMode, `agent_send` followup, `task_create` priority/tags, `edit_file` operation, `web_fetch` modes). Full JSON Schema for all 24 is ideal but can be deferred to implementation.
+
+3. **`onExhausted: "wait"` undocumented as valid value** — Described in failure behavior but not listed as a settings option.
+   - 13-operations.md line 8: `"If exhausted and onExhausted: "wait" → task status = waiting"`
+   - 11-file-formats.md line 336: `"onExhausted": "fail"` — only `"fail"` shown
+   - Recommendation: Document valid values for `onExhausted` in 11-file-formats.md: `"fail"` (default) or `"wait"`.
+
+4. **`auth.json` LLM config vs `settings.json` models config — relationship undefined** — Both files can configure LLM credentials. No merge/priority rule stated.
+   - 11-file-formats.md lines 270-274: auth.json has `llm.base_url` and `llm.api_key`
+   - 11-file-formats.md lines 286-290: settings.json has `models.main.base_url` and `models.main.api_key`
+   - Recommendation: Document the relationship. Likely: auth.json `llm` provides default credentials, settings.json `models.main` can override per-role. State this explicitly.
+
+5. **`khabot login` default scope** — The `--global` flag is shown but default behavior is undocumented.
+   - Where: 08-api-cli.md line 146: `"khabot login --key <token> [--global]"`
+   - Recommendation: State whether default is project-level (`.khabot/auth.json`) or global (`~/.khabot/auth.json`).
+
+6. **Chat mode progress mechanism** — API spec says "No streaming. No WebSocket." Chat requests can take many seconds (tool execution). No mechanism for clients to know the agent is still working.
+   - Where: 08-api-cli.md line 7
+   - Recommendation: Either document that chat requests block until complete (HTTP long-poll), or add a note about expected response times and client timeout guidance.
+
+7. **`instance_folder` column in sessions table** — Defined but never referenced or explained beyond "Project folder path".
+   - Where: 07-storage.md line 25
+   - Recommendation: Clarify purpose. Likely tracks which project directory the session was started from. Add a sentence explaining when/why this is useful.
+
+8. **`mcpServers` configuration schema** — settings.json shows `"mcpServers": {}` but never defines the format of MCP server entries.
+   - Where: 11-file-formats.md line 307
+   - Recommendation: Add an example with at least one MCP server entry showing transport type, command/URL, and any options.
+
+9. **`settings.local.json` format** — Referenced in 3 files as a settings resolution layer but never defined.
+   - Where: 09-permissions.md line 31, 11-file-formats.md line 352, 12-folder-structure.md line 10
+   - Recommendation: Add a note that it uses the same format as settings.json (partial overrides merged). One sentence is sufficient.
+
+10. **`task_subscribe` lifecycle when subscribing agent finishes** — What happens to the subscription if Agent A completes or is stopped before the subscribed task finishes?
+    - Where: 06-communication.md lines 99-118
+    - Recommendation: Document behavior: subscription is per-session, lost when session closes. Or: notification is stored and delivered when agent next starts. Pick one.
+
+11. **Daemon runtime state storage** — `GET /daemons` returns status, next tick, last result. Where is this stored? Not in any SQLite table.
+    - Where: 08-api-cli.md line 73
+    - Recommendation: Clarify that daemon state is in-memory only (rebuilt on restart from agent.json cron). Or add a `daemons` table to 07-storage.md.
+
+12. **Memory folder missing from global `~/.khabot/` structure** — `memory_search` tool says "search across all memory files" but global home directory structure has no `memory/` folder.
+    - Where: 12-folder-structure.md lines 48-66 (global structure)
+    - 05-tools.md line 18: `"Search across all memory files (global + agent)"`
+    - Recommendation: Either add `memory/` to the global structure (if global-level memory is supported) or clarify that "global" in the memory context means project-wide (not `~/.khabot/`).
+
+---
+
+## 🔵 Ambiguities
+
+1. **Observation Masking vs Tool Result Clearing — order and interaction unclear** — Two mechanisms that both trim old tool outputs, described adjacently with no explanation of which runs first or how they interact.
+   - Where: 04-runtime.md lines 84-92
+   - Recommendation: Clarify order of operations: (1) Observation masking replaces tool outputs beyond N turns, (2) Tool result clearing truncates large outputs in deep history, (3) If context still exceeds 85%, compaction triggers. State whether they are independent or sequential.
+
+2. **`config.json` — source-code-only vs user-editable** — config.json is defined as "forkable branding" in 11-file-formats.md but only appears in the source code tree (`config/config.json`) in 12-folder-structure.md.
+   - Where: 11-file-formats.md lines 242-258, 12-folder-structure.md line 77
+   - Recommendation: Clarify that config.json is a source code file changed when forking the project, NOT a user-facing config file. This distinguishes it from settings.json.
+
+3. **`agent` field in SKILL.md means "model", not "agent"** — The field name is confusing in a system where "agent" is a core concept.
+   - Where: 11-file-formats.md line 215: `"agent — Model to use (fork mode only)"`
+   - 05-tools.md line 143: `"agent: anthropic/claude-3-haiku"`
+   - Recommendation: Flag as known terminology debt. Consider renaming to `model` in a future version, or add a note explaining the Claude Code naming heritage.
+
+4. **`permissions.ask` only at settings level — intentional but unexplained** — Settings permissions have `allow`/`ask`/`deny`, agent.json permissions only have `allow`/`deny`. The asymmetry is never justified.
+   - Where: 11-file-formats.md lines 298-301 vs line 95
+   - Recommendation: Add a note in 09-permissions.md: "Per-agent/per-mode permissions only support `allow` and `deny`. The `ask` level is only available in settings.json because it requires interactive approval."
+
+5. **Sub-agent fallback behavior only documented in one file** — When `modes.subagent` is undefined, `agent_spawn` falls back to chat-like behavior. This is only stated in 03-agents.md, not in 06-communication.md where `agent_spawn` is fully specified.
+   - Where: 03-agents.md line 147, absent from 06-communication.md
+   - Recommendation: Add a "Fallback" note to the `agent_spawn` section in 06-communication.md.
+
+6. **"N turns" for observation masking is never defined** — The spec says tool outputs "beyond N turns old" are masked, but N is never given a value or made configurable.
+   - Where: 04-runtime.md line 85: `"Tool outputs beyond N turns old are replaced with placeholders"`
+   - Recommendation: Define N (or reference a settings.json field for it).
+
+7. **Compaction: who does the compacting?** — 04-runtime.md says the "hidden compact agent" compacts. 04-runtime.md also says the "compact model" is used. But 03-agents.md says the compact agent uses the "compact model". The relationship between the compact agent and the compact model role could be clearer.
+   - Where: 04-runtime.md line 70, 03-agents.md line 164
+   - Recommendation: One sentence clarifying: "The hidden `compact` agent runs using the `compact` model role from settings.json."
+
+---
+
+## 💀 Dead References
+
+1. **01-vision.md references "reads CLAUDE.md"** — The spec does NOT natively read CLAUDE.md. It must be converted via `khabot import`.
+   - Where: 01-vision.md line 23: `"reads CLAUDE.md, .claude/ settings, skills, commands"`
+   - Recommendation: Change to `"imports CLAUDE.md projects"` or `"Claude Code ecosystem importable"`.
+
+2. **01-vision.md references "commands"** — The `commands/` folder concept was removed from the spec. No file in PLAN/ defines or supports a commands mechanism.
+   - Where: 01-vision.md line 23: `"skills, commands"`
+   - Recommendation: Remove `"commands"` from this line.
+
+3. **`disable-model-invocation` in SKILL.md field table but absent from all examples** — Defined in the field table but never shown in any SKILL.md example across the spec.
+   - Where: 11-file-formats.md line 216: `"disable-model-invocation — boolean — Only user can trigger, not agent"`
+   - Absent from: 05-tools.md SKILL.md example (lines 137-152), 11-file-formats.md SKILL.md example (lines 188-206)
+   - Recommendation: Add it to at least one SKILL.md example, or remove from field table if it's a deferred feature.
+
+4. **01-vision.md references ".claude/ settings"** — While 13-operations.md says `.claude/` is "Read as `.khabot/`", the vision statement implies native reading of the `.claude/` namespace, which is actually an import/compatibility shim, not a core feature.
+   - Where: 01-vision.md line 23
+   - Recommendation: Reword to make clear this is via compatibility layer, not native support.
+
+---
+
+## ✅ Summary
+
+| Severity | Count |
+|----------|-------|
+| 🔴 **Contradictions** (Critical) | 8 |
+| 🟡 **Mismatches** (Medium) | 10 |
+| ⚪ **Missing Pieces** (Medium) | 12 |
+| 🔵 **Ambiguities** (Low-Medium) | 7 |
+| 💀 **Dead References** (Low) | 4 |
+| **Total issues** | **41** |
+
+### Top Priority Fixes
+1. **Agent discovery contradiction** (#🔴3) — fundamental architectural question that affects startup, API, and daemon behavior.
+2. **`task_create` mode confusion** (#🔴2) — self-contradicting within 03-agents.md, will confuse implementers.
+3. **`agent_message` busy behavior** (#🔴5) — two incompatible descriptions of the same mechanism.
+4. **`$AGENT_FOLDER` scope** (#🔴7) — direct contradiction between two files on where this variable works.
+5. **`maxDurationSeconds` vs `timeoutSeconds` naming** (#🟡2) — will cause bugs at implementation time if not unified.