khabotcli 1.0.0

package/PLAN/12-folder-structure.md

@@ -0,0 +1,205 @@
+# 12 — Folder Structure
+
+## Project-Level
+
+```
+./                              ← any folder user runs khabot from (clean, no KhaBot files at root)
+└── .khabot/
+    ├── AGENT.md               ← global instructions for all agents in this project
+    ├── settings.json          ← project settings (committed to git)
+    ├── settings.local.json    ← local overrides (gitignored)
+    ├── auth.json              ← local auth override (gitignored)
+    ├── runtime.pid            ← written on server start, deleted on stop
+    ├── agents/                ← agent definitions (STATIC, read-only)
+    │   └── <agentName>/       ← $AGENT_FOLDER resolves to this path
+    │       ├── AGENT.md       ← agent instructions
+    │       ├── agent.json     ← agent config (modes, model, tools)
+    │       ├── SOUL.md        ← optional persona
+    │       ├── skills/
+    │       │   └── <skillName>/
+    │       │       ├── SKILL.md
+    │       │       └── scripts/   ← scripts referenced by the skill
+    │       └── tools/         ← agent-level custom tools
+    │           └── <toolName>/
+    │               ├── tool.json
+    │               └── index.js
+    ├── memory/                ← persistent memory (MUTABLE)
+    │   ├── MEMORY.md          ← global memory (always loaded, ~200-line cap)
+    │   ├── <topic>.md         ← auto-exported global memory files
+    │   └── agents/
+    │       └── <agentName>/
+    │           ├── MEMORY.md  ← agent-specific memory (always loaded, ~200-line cap)
+    │           └── <topic>.md ← auto-exported agent memory files
+    ├── heartbeats/            ← daemon checklists (MUTABLE)
+    │   └── <agentName>.md     ← per-agent heartbeat checklist
+    ├── skills/                ← shared skills available to all agents
+    │   └── <skillName>/
+    │       └── SKILL.md
+    └── tools/                 ← project-level custom tools
+        └── <toolName>/
+            ├── tool.json
+            └── index.js
+```
+
+**Global instructions:** `.khabot/AGENT.md` only. No fallback to project root. Claude Code projects must be converted via `khabot import`.
+
+> **Common mistake:** Placing agents in `./agents/` (project root) instead of `./.khabot/agents/`. The runtime only scans `.khabot/agents/`.
+
+## Global
+
+```
+~/.khabot/
+├── auth.json                   ← KhaBot.com token + LLM API config
+├── settings.json               ← global default settings
+├── data.db                     ← SQLite database (all runtime data)
+├── agents/                     ← agents cached from KhaBot.com (static)
+│   └── <agentName>/
+│       ├── version.json        ← SHA256 hash for registry version checking
+│       └── ...                 ← same structure as project agent
+├── skills/                     ← global shared skills
+│   └── <skillName>/
+│       └── SKILL.md
+├── tools/                      ← global custom tools
+│   └── <toolName>/
+│       ├── tool.json
+│       ├── index.js
+│       └── version.json        ← SHA256 hash for registry version checking
+├── backups/                    ← auto-backups of data.db
+│   └── data-2026-03-01.db
+└── archive/                    ← archived old sessions/tasks (gzipped JSONL)
+    └── sessions-2026-03.jsonl.gz
+```
+
+## Source Code (Runtime)
+
+```
+khabotcli/
+├── package.json                ← bin: { "khabot": "./src/cli/index.js" }  ← MUST point here
+├── config/
+│   └── config.json             ← forkable branding/naming
+├── src/
+│   ├── core/                   ← Pure business logic (transport agnostic)
+│   │   ├── loop.js             ← Agentic loop (async generator)
+│   │   ├── router.js           ← Multi-model delegation (IntelligenceRouter)
+│   │   ├── registry.js         ← Tool registration + ajv compilation
+│   │   ├── prompt.js           ← System prompt assembly (7 layers)
+│   │   ├── compaction.js       ← Context compaction logic
+│   │   ├── agent.js            ← Agent loader + discovery
+│   │   ├── memory.js           ← Memory management (read/write/search/export)
+│   │   └── queue.js            ← Agent message queue
+│   ├── api/                    ← REST-specific transport
+│   │   ├── routes.js
+│   │   ├── middleware.js
+│   │   └── controllers.js
+│   ├── cli/
+│   │   ├── index.js            ← CLI entry point (bin target)
+│   │   ├── parser.js
+│   │   └── formatter.js
+│   ├── llm/
+│   │   └── client.js           ← Native fetch-based LLM client (no SDK)
+│   ├── settings/
+│   │   └── fields.js           ← Settings field name constants (single source of truth)
+│   ├── utils/
+│   │   ├── context.js          ← CWD singleton — set once at startup, read everywhere
+│   │   ├── id.js               ← generateId() via crypto.randomBytes (no nanoid)
+│   │   └── paths.js            ← Path helpers: getProjectAgentsDir(cwd), etc.
+│   ├── tools/                  ← Built-in tool implementations
+│   │   ├── bash.js
+│   │   ├── read-file.js
+│   │   ├── write-file.js
+│   │   └── ...
+│   ├── infrastructure/         ← External resource management
+│   │   ├── database.js         ← SQLite setup, migrations, queries
+│   │   ├── scheduler.js        ← Cron scheduling for daemons
+│   │   ├── ably.js             ← Ably bridge
+│   │   └── mcp.js              ← MCP client wrapper
+│   └── system-prompts/         ← System prompt fragments
+│       ├── base-core.md
+│       ├── safety-rules.md
+│       ├── environment.md
+│       ├── task-heuristics.md
+│       └── reminders/
+│           ├── anti-drift.md
+│           ├── stall-recovery.md
+│           └── ...
+├── migrations/                 ← SQLite migration files (all use IF NOT EXISTS)
+│   ├── 001-initial.sql
+│   └── ...
+├── examples/                   ← Reference agents guaranteed to pass schema validation
+│   └── agents/
+│       └── hello/              ← Minimal chat-only agent (used in smoke test)
+│           ├── AGENT.md
+│           └── agent.json
+└── test/
+    ├── unit/
+    ├── api/
+    └── smoke.js                ← Fast startup + health + one chat call
+```
+
+### Critical Implementation Rules
+
+**1. CWD singleton (`src/utils/context.js`):**
+The server's working directory is set **once** at startup (in `src/cli/index.js`) and stored in a singleton. All routes, agents, and tools read from `context.getCwd()`. **Never call `process.cwd()` inside `src/core/`, `src/api/`, `src/tools/`, or `src/infrastructure/`.** Only `src/cli/index.js` may call `process.cwd()` (at launch time).
+
+```javascript
+// src/utils/context.js
+let _cwd = null;
+module.exports = {
+  setCwd(cwd) { _cwd = cwd; },
+  getCwd() {
+    if (!_cwd) throw new Error('Context not initialized — call setCwd() at startup');
+    return _cwd;
+  }
+};
+// Usage in routes:
+const { getCwd } = require('../utils/context');
+const agentsDir = paths.getProjectAgentsDir(getCwd());
+```
+
+This also eliminates the circular dependency that arises when routes import from `server.js` to get `cwd` and `server.js` imports routes.
+
+**2. Path helpers (`src/utils/paths.js`):**
+All path construction goes through named helpers. **Do not construct `.khabot/` paths inline.**
+
+```javascript
+// Correct — explicit, clear:
+const agentsDir = paths.getProjectAgentsDir(cwd);  // → cwd/.khabot/agents
+
+// Wrong — was getAgentsDir(cwd) which returned cwd/agents (missing .khabot):
+const agentsDir = paths.getAgentsDir(cwd); // REMOVED — ambiguous name
+```
+
+Key functions in `paths.js`:
+- `getProjectConfigDir(cwd)` → `cwd/.khabot/`
+- `getProjectAgentsDir(cwd)` → `cwd/.khabot/agents/`
+- `getProjectSettingsPath(cwd)` → `cwd/.khabot/settings.json`
+- `getGlobalAgentsDir()` → `~/.khabot/agents/`
+- `getAgentDir(cwd, agentName)` → full path for a named agent
+
+**3. Settings field names (`src/settings/fields.js`):**
+```javascript
+// src/settings/fields.js — single source of truth
+module.exports = {
+  MODEL_BASE_URL: 'base_url',
+  MODEL_API_KEY: 'api_key',
+  MODEL_NAME: 'model',
+  // ... all other field names
+};
+// Never hardcode 'api_key' or 'base_url' as strings in any other file.
+```
+
+**4. `package.json` bin path:**
+```json
+{ "bin": { "khabot": "./src/cli/index.js" } }
+```
+The root `index.js` does NOT exist. The CLI entry is always `src/cli/index.js`.
+
+**5. Version reading:**
+Do NOT use `require('../../package.json')` inside deeply-nested route files — the relative depth varies and causes `Cannot find module` errors. Instead, read version at startup and pass it via `context.js` or a `constants.js` file:
+```javascript
+// Set once at startup in src/cli/index.js:
+const { version } = require('../package.json'); // correct relative path from cli/
+context.setVersion(version);
+// In routes:
+const version = context.getVersion();
+```

package/PLAN/13-operations.md

@@ -0,0 +1,212 @@
+# 13 — Operations
+
+## Failure & Recovery
+
+### LLM Call Failure
+- Retry up to `retry.maxAttempts` times with `retry.delaySeconds` delay (exponential backoff via `openai` SDK)
+- If exhausted and `onExhausted: "fail"` → task status = failed
+- If exhausted and `onExhausted: "wait"` → task status = waiting (human can retry)
+
+### Iteration/Duration Limits
+- `maxIterations` reached → task failed, error = "Max iterations exceeded"
+- `maxDurationSeconds` reached → task failed, error = "Max duration exceeded"
+- Both configurable globally (settings.json) and per-agent per-mode (agent.json)
+
+### Startup Recovery
+On server start:
+1. Open SQLite database, run pending migrations
+2. Scan for tasks with status `pending` or `processing`
+3. Set all to `failed` with error: "Runtime terminated unexpectedly"
+4. Auto-start all agents with `daemon.enabled: true`
+5. Begin accepting API requests
+
+### Graceful Shutdown
+On `khabot stop` or SIGTERM/SIGINT:
+1. Stop accepting new HTTP connections
+2. Stop all cron schedulers
+3. Wait for active agent loops to reach a safe point (tool boundary)
+4. Leave Ably presence, close Ably connection
+5. Close SQLite database (checkpoints WAL)
+6. Delete runtime.pid, exit 0
+7. Failsafe: force exit after 10s timeout
+
+### Multiple Instances
+- Multiple one-shot instances: fully supported (SQLite WAL handles concurrent writes)
+- Multiple server instances on same port: OS port conflict error
+- Multiple server instances on different ports: supported, shared SQLite
+- Concurrent memory file writes: last-write-wins in v1
+
+---
+
+## Testing Strategy (v1)
+
+### Scope
+**Smoke test + Unit tests + API tests** — fastest path to ship with confidence.
+
+### Smoke Test (`test/smoke.js`) — Run First
+A fast automated test run immediately after `npm install`. Catches ~14 of the 20 real bugs found during testing before any manual effort. Runs with `npm test`.
+
+What it verifies:
+1. Server starts without errors (Node version check passes, all deps resolve)
+2. `GET /health` returns 200
+3. Example agent (`examples/agents/hello/`) loads and validates against schema
+4. `POST /agents/hello/chat` returns a response (mock LLM)
+5. Server shuts down cleanly
+
+```bash
+# package.json
+{ "scripts": { "test": "node test/smoke.js && node --test test/unit/ test/api/" } }
+```
+
+### Unit Tests
+- Agentic loop logic (mock LLM responses via fetch mock)
+- System prompt assembly (7-layer composition)
+- Tool argument validation (ajv)
+- Permission evaluation (deny/ask/allow resolution)
+- Settings resolution (merge order — including field name constants)
+- Agent discovery (file lookup logic with `getProjectAgentsDir(cwd)`)
+- SQLite queries (in-memory test database)
+- `context.js` singleton (set/get, throws if uninitialized)
+- `id.js` ID generation (no nanoid, crypto-based)
+
+### API Tests
+- All REST endpoints (happy path + error cases)
+- Authentication (with/without secret)
+- Pagination
+- Task lifecycle (create → process → finish)
+- Session lifecycle (create → message → close)
+
+### Integration Test (`test/integration.js`)
+Boots the full server with mock LLM. Exercises task lifecycle end-to-end. Catches wiring bugs that unit tests miss (circular deps, wrong exports, signature mismatches). Should pass before any release.
+
+### Mock LLM
+For tests that need LLM responses: mock native `fetch` (not an openai SDK mock) to return predefined responses with tool calls. No real LLM calls in CI. Pattern:
+```javascript
+global.fetch = async (url, options) => {
+  return { ok: true, json: async () => ({ choices: [{ message: { content: 'Hello!', tool_calls: [] } }] }) };
+};
+```
+
+### Test Runner
+Node.js built-in test runner (`node:test`) — zero external deps.
+
+---
+
+## Compatibility
+
+### Claude Code Compatibility (via Import)
+KhaBotCLI imports Claude Code project structures via `khabot import`:
+
+| Claude Code | KhaBotCLI Equivalent |
+|-------------|---------------------|
+| `CLAUDE.md` | Converted to `.khabot/AGENT.md` via `khabot import` |
+| `.claude/` | Read as `.khabot/` |
+| `.claude/skills/` | Read as skills |
+| `settings.json` | All Claude Code fields supported |
+| MCP server definitions | Fully supported |
+| Permission format | Fully supported |
+| Template variables | Fully supported |
+
+### Import Adapters
+
+`khabot import --type=<adapter> --source <path>`
+
+| Adapter | Source | Transform |
+|---------|--------|-----------|
+| `claude-code` | Claude Code project | CLAUDE.md → AGENT.md, .claude/ → .khabot/, generates agent.json with mode config |
+| `openclaw` | OpenClaw project | Maps OpenClaw agent definitions to KhaBotCLI format |
+| `raw` | Any folder | Copies as-is, creates minimal agent.json |
+
+**Interactive import:** Since KhaBotCLI agents have modes (chat/task/daemon) which Claude Code doesn't, the import tool asks follow-up questions:
+- Which modes should this agent support?
+- What tools should be available per mode?
+- What model should it use?
+- Any permission overrides?
+
+---
+
+## KhaBot.com Integration (v1)
+
+### API Surface
+| Endpoint | Purpose |
+|----------|---------|
+| `POST /api/v1/validate-token` | Validate khabot_token |
+| `GET /api/v1/registry/agents` | List available agents |
+| `GET /api/v1/registry/agents/:name` | Download agent |
+| `GET /api/v1/registry/tools` | List available tools |
+| `GET /api/v1/registry/tools/:name` | Download tool |
+| `POST /api/v1/ably/token` | Get scoped Ably TokenRequest |
+
+### Version Checking
+- Each cached agent/tool has a `version.json` with SHA256 hash
+- On startup (if connected), KhaBotCLI checks hashes against KhaBot.com manifest
+- If different → auto-update global agents/tools
+- Project-local agents are never auto-updated (user owns them)
+
+### No Usage Analytics
+KhaBotCLI does NOT send usage data to KhaBot.com. Token counts and costs are tracked locally in SQLite. The AI provider (OpenRouter, etc.) handles their own analytics.
+
+---
+
+## Images & Files
+
+### Image Handling
+- **Vision:** Images sent as base64 in messages (Claude, GPT-4V, Gemini support)
+- **From URL:** `web_fetch` auto-converts image URLs to base64
+- **From file:** `read_file` on image files returns base64
+- **Generation:** Via standard LLM API (models that support image generation)
+- **MCP:** Available for users who want DALL-E, Stable Diffusion, etc.
+
+### File/URL Resolution
+Task input supports multiple file sources:
+
+| Type | Format | Example |
+|------|--------|---------|
+| Local file | `./path/to/file` | `./src/auth.js` |
+| Absolute path | `/path/to/file` | `/home/user/project/src/auth.js` |
+| HTTP URL | `https://...` | `https://raw.githubusercontent.com/...` |
+| Data URL | `data:...` | `data:text/plain;base64,SGVsbG8=` |
+
+Unified resolver with mime type detection. URLs fetched and cached for the session duration.
+
+---
+
+## Modularity & Extensibility
+
+The codebase is designed to be modular, making it easy to add or modify features without touching unrelated code.
+
+### Source Code Boundaries
+| Module | Responsibility | Can change without affecting |
+|--------|---------------|----------------------------|
+| `core/loop.js` | Agentic loop | API routes, CLI |
+| `core/registry.js` | Tool registration | Agent loading, prompts |
+| `core/prompt.js` | System prompt assembly | Tool execution, storage |
+| `core/memory.js` | Memory read/write/search/export | Loop, tools |
+| `core/queue.js` | Agent message queue | Storage, prompts |
+| `api/` | REST transport | Core logic |
+| `cli/` | CLI transport | Core logic |
+| `infrastructure/` | SQLite, Ably, MCP, cron | Core logic |
+| `tools/` | Individual tool implementations | Each tool is independent |
+| `utils/context.js` | CWD singleton | All modules (no circular deps) |
+| `utils/paths.js` | Path construction | Prevents inline `.khabot/` string bugs |
+| `settings/fields.js` | Field name constants | Prevents field name drift across modules |
+| `llm/client.js` | Native fetch LLM client | Replaces openai SDK, no version drift |
+
+### Extension Points
+- **New mode:** Add a new key to `modes` in agent.json, handle in `loop.js`
+- **New built-in tool:** Add file to `tools/`, register in `registry.js`
+- **New transport:** Add folder alongside `api/` and `cli/` (e.g., `grpc/`)
+- **New storage backend:** Replace `infrastructure/database.js` (core uses abstract queries)
+- **New MCP transport:** Add to `infrastructure/mcp.js`
+
+### Implementation Standards (enforced by code review + tests)
+
+1. **Schema-first loading:** `agent.json` and `settings.json` are validated against their JSON schemas using ajv at load time. Any invalid file produces a clear error and the agent/setting is not used. Never use unvalidated config.
+
+2. **No `process.cwd()` in modules:** Only `src/cli/index.js` may call `process.cwd()`. All other modules receive `cwd` via `context.getCwd()`. Enforced by grep in CI: `grep -r 'process.cwd()' src/ --exclude='src/cli/*'` must return empty.
+
+3. **Settings field names from constants:** All references to settings field names (`base_url`, `api_key`, etc.) must use `src/settings/fields.js` exports. No inline string literals.
+
+4. **Locked dependencies:** `package.json` uses exact versions. CI runs `npm ci`. Before merging, run `node -e "const p = require('./package.json'); const used = []; /* grep all requires */"` to audit all `require()`d packages are listed.
+
+5. **Example agent in CI:** `examples/agents/hello/agent.json` is validated against the schema in the smoke test. If it fails, the build fails. This is the canary for schema changes.

package/PLAN/README.md

@@ -0,0 +1,23 @@
+# KhaBotCLI — Specification v3.0
+
+KhaBotCLI is an **enterprise autonomous agent runtime** — a locally-running Node.js server that manages autonomous AI agents via a REST API.
+
+---
+
+## Table of Contents
+
+| # | Section | Description |
+|---|---------|-------------|
+| 01 | [Vision](01-vision.md) | Identity, philosophy, non-goals |
+| 02 | [Tech Stack](02-tech-stack.md) | Language, dependencies, confirmed choices |
+| 03 | [Agents](03-agents.md) | Agent definition, modes (chat/task/daemon/subagent), agent.json, sub-agents |
+| 04 | [Runtime](04-runtime.md) | Agentic loop, model delegation, context engineering, system prompts |
+| 05 | [Tools](05-tools.md) | Built-in tools, custom JS tools, MCP, skills, discovery |
+| 06 | [Communication](06-communication.md) | A2A messaging, sub-agent spawning, task system |
+| 07 | [Storage](07-storage.md) | SQLite, retention, file-based config |
+| 08 | [API & CLI](08-api-cli.md) | REST API endpoints, CLI commands |
+| 09 | [Permissions & Hooks](09-permissions.md) | Permission system, PreToolUse/PostToolUse |
+| 10 | [Ably](10-ably.md) | Remote access via Ably Realtime |
+| 11 | [File Formats](11-file-formats.md) | agent.json, config.json, settings.json, AGENT.md, SKILL.md, tool.json |
+| 12 | [Folder Structure](12-folder-structure.md) | Project-level, global |
+| 13 | [Operations](13-operations.md) | Failure/recovery, testing, compatibility, import, KhaBot.com |

package/README.md

@@ -0,0 +1,128 @@
+# KhaBotCLI
+
+**Enterprise autonomous agent runtime — local, API-first, multi-model.**
+
+KhaBotCLI lets you define AI agents as simple files, run them as a local REST server, and control them through a clean HTTP API or interactive CLI. Agents can chat, run multi-step tasks with tools, spawn sub-agents, schedule cron jobs, and maintain persistent memory — all without external services.
+
+---
+
+## Key Features
+
+- **4 agent modes** — Chat, Task, Daemon (cron), Subagent
+- **24 built-in tools** — bash, file I/O, web search/fetch, memory, multi-agent communication, todos, and more
+- **Persistent memory** — per-agent and project-wide Markdown memory files
+- **Multi-agent orchestration** — parallel fan-out, durable subscriptions, sync/async spawning
+- **Layered config** — global → project → local → CLI flags
+- **Any OpenAI-compatible LLM** — OpenRouter, local Ollama, Azure, etc.
+- **Zero external dependencies** — SQLite storage, native fetch, Node.js only
+
+---
+
+## Requirements
+
+- **Node.js ≥ 18.3.0**
+- An OpenAI-compatible API key (e.g. [OpenRouter](https://openrouter.ai))
+
+---
+
+## Installation
+
+```bash
+npm install -g khabotcli
+```
+
+---
+
+## Quick Start
+
+```bash
+# 1. Set up a workspace
+mkdir my-workspace && cd my-workspace
+
+# 2. Save your API key (Optional)
+khabot login --key sk-or-v1-...
+
+# 3. Start the server
+khabot start
+
+# 4. Chat with the default agent
+curl -X POST http://localhost:5050/agents/hello/chat \
+  -H "Content-Type: application/json" \
+  -d '{"message": "Hello!"}'
+
+# 5. Run a task with tools
+curl -X POST http://localhost:5050/agents/assistant/task \
+  -H "Content-Type: application/json" \
+  -d '{"input": "List all .js files in the current directory"}'
+```
+
+→ See **[docs/guide/01-quickstart.md](docs/guide/01-quickstart.md)** for the full walkthrough.
+
+---
+
+## Documentation
+
+### API Reference
+| Doc | Contents |
+|-----|----------|
+| [docs/api/README.md](docs/api/README.md) | Overview, auth, error codes |
+| [docs/api/01-system.md](docs/api/01-system.md) | `/health`, `/status`, `/shutdown` |
+| [docs/api/02-agents.md](docs/api/02-agents.md) | List and inspect agents |
+| [docs/api/03-chat.md](docs/api/03-chat.md) | Chat endpoint, multi-turn sessions |
+| [docs/api/04-tasks.md](docs/api/04-tasks.md) | Task lifecycle, events, polling |
+| [docs/api/05-sessions.md](docs/api/05-sessions.md) | Session management and messages |
+| [docs/api/06-daemons.md](docs/api/06-daemons.md) | Daemon control endpoints |
+
+### Project Guide
+| Doc | Contents |
+|-----|----------|
+| [docs/guide/README.md](docs/guide/README.md) | Guide index |
+| [docs/guide/01-quickstart.md](docs/guide/01-quickstart.md) | Install, first agent, first request |
+| [docs/guide/02-folder-structure.md](docs/guide/02-folder-structure.md) | `.khabot/` layout explained |
+| [docs/guide/03-configuration.md](docs/guide/03-configuration.md) | `settings.json` + `auth.json` full reference |
+| [docs/guide/04-agents.md](docs/guide/04-agents.md) | `agent.json`, `AGENT.md`, all 4 modes |
+| [docs/guide/05-cli.md](docs/guide/05-cli.md) | `khabot` CLI commands reference |
+| [docs/guide/06-tools.md](docs/guide/06-tools.md) | All 24 built-in tools |
+| [docs/guide/07-permissions.md](docs/guide/07-permissions.md) | Permissions system |
+| [docs/guide/08-memory.md](docs/guide/08-memory.md) | Memory + context compaction |
+| [docs/guide/09-multi-agent.md](docs/guide/09-multi-agent.md) | Orchestration patterns |
+| [docs/guide/10-daemons.md](docs/guide/10-daemons.md) | Daemon / cron agents |
+
+---
+
+## CLI Reference (Quick)
+
+```
+khabot start [--port 5050] [--folder ./workspace] [--secret <token>]
+khabot run --agent hello --input "What time is it?"
+khabot stop
+khabot status
+khabot agents list
+khabot agents inspect <name>
+khabot login --key <api-key> [--global]
+```
+
+→ Full reference: [docs/guide/05-cli.md](docs/guide/05-cli.md)
+
+---
+
+## Project Layout
+
+```
+KhaBotCli/
+  cli/          ← khabot CLI entry point
+  api/          ← Express REST server + routes
+  core/         ← agent loader, loop, router, memory, compaction
+  tools/        ← 24 built-in tools
+  infrastructure/ ← SQLite database + scheduler
+  utils/        ← settings, paths, context
+  schemas/      ← JSON schemas for agent.json and settings.json
+  system-prompts/ ← base system prompt layers
+  examples/     ← reference agent definitions
+```
+
+---
+
+## License
+
+MIT