feat(website): legendary landing + 4x docs + modern light theme
- Landing: full TUI gallery (12 window-chromed terminal mocks: slash palette, @mentions, permission panel, intra-line diff, processes, /sdiff, /cost sparkline, /memory, /tasks, verify repair loop, markdown, steering), hero glow, stats band, macOS-style terminal window chrome everywhere - Docs 4x: 11 new pages (cookbook, verification, worktrees, repograph, memory, context, fork-replay, cli, architecture, events, theming) + restructured 7-group sidebar across all 21 pages - Legendary modern light theme: warm paper + ink + ember, soft shadows, terminals stay obsidian for contrast - Deployed to www.khaelor.sh Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
23 changed files +2,036 −34
added
website/public/docs/architecture.html
+149 −0
@@ -0,0 +1,149 @@ | ||
| 1 | +<!doctype html> | |
| 2 | +<!-- | |
| 3 | +KHAELOR | |
| 4 | +File: website/public/docs/architecture.html | |
| 5 | +Description: Docs — The small kernel, the services around it, the world seam, and the layering rules that keep KHAELOR honest. | |
| 6 | +Author: Simon-Pierre Boucher | |
| 7 | +Contact: contact@spboucher.ai | |
| 8 | +--> | |
| 9 | +<html lang="en"> | |
| 10 | +<head> | |
| 11 | +<meta charset="utf-8"> | |
| 12 | +<meta name="viewport" content="width=device-width, initial-scale=1"> | |
| 13 | +<title>Architecture — KHAELOR docs</title> | |
| 14 | +<meta name="description" content="The small kernel, the services around it, the world seam, and the layering rules that keep KHAELOR honest."> | |
| 15 | +<link rel="stylesheet" href="/styles.css"> | |
| 16 | +<script> | |
| 17 | +(function(){try{var t=localStorage.getItem("khaelor-theme");if(!t&&window.matchMedia&&window.matchMedia("(prefers-color-scheme: light)").matches)t="light";if(t==="light")document.documentElement.setAttribute("data-theme","light");}catch(e){}})(); | |
| 18 | +</script> | |
| 19 | +<script defer src="/site.js"></script> | |
| 20 | +</head> | |
| 21 | +<body> | |
| 22 | + | |
| 23 | +<header class="site-header"><div class="inner"> | |
| 24 | + <a class="wordmark" href="/"><span class="glyph">❯</span><span class="g-ember">KHAELOR</span></a> | |
| 25 | + <nav> | |
| 26 | + <a href="/docs/getting-started.html">Docs</a> | |
| 27 | + <a href="/#install">Install</a> | |
| 28 | + <button id="theme-toggle" type="button" aria-label="Toggle color theme">light</button> | |
| 29 | + </nav> | |
| 30 | +</div></header> | |
| 31 | + | |
| 32 | +<main class="page"><div class="docs-layout"> | |
| 33 | + | |
| 34 | +<aside class="sidebar"> | |
| 35 | + <div class="group"><div class="group-title">Start</div> | |
| 36 | + <a href="/docs/getting-started.html">Getting started</a> | |
| 37 | + <a href="/docs/cookbook.html">Cookbook</a> | |
| 38 | + </div> | |
| 39 | + <div class="group"><div class="group-title">Using KHAELOR</div> | |
| 40 | + <a href="/docs/usage.html">The TUI</a> | |
| 41 | + <a href="/docs/commands.html">Commands & keyboard</a> | |
| 42 | + <a href="/docs/tools.html">Tools</a> | |
| 43 | + <a href="/docs/sessions.html">Sessions</a> | |
| 44 | + </div> | |
| 45 | + <div class="group"><div class="group-title">Autonomy</div> | |
| 46 | + <a href="/docs/phases.html">Phase gates</a> | |
| 47 | + <a href="/docs/verification.html">Verification</a> | |
| 48 | + <a href="/docs/worktrees.html">Parallel worktrees</a> | |
| 49 | + <a href="/docs/daemon.html">The daemon</a> | |
| 50 | + </div> | |
| 51 | + <div class="group"><div class="group-title">Intelligence</div> | |
| 52 | + <a href="/docs/repograph.html">Semantic index</a> | |
| 53 | + <a href="/docs/memory.html">Project memory</a> | |
| 54 | + <a href="/docs/context.html">Context engine</a> | |
| 55 | + <a href="/docs/fork-replay.html">Fork · replay · sdiff</a> | |
| 56 | + </div> | |
| 57 | + <div class="group"><div class="group-title">Control</div> | |
| 58 | + <a href="/docs/permissions.html">Permissions</a> | |
| 59 | + <a href="/docs/configuration.html">Configuration</a> | |
| 60 | + <a href="/docs/cli.html">CLI reference</a> | |
| 61 | + </div> | |
| 62 | + <div class="group"><div class="group-title">Internals</div> | |
| 63 | + <a href="/docs/architecture.html">Architecture</a> | |
| 64 | + <a href="/docs/events.html">The event model</a> | |
| 65 | + <a href="/docs/theming.html">Theming & terminal</a> | |
| 66 | + </div> | |
| 67 | + <div class="group"><div class="group-title">Help</div> | |
| 68 | + <a href="/docs/faq.html">FAQ & troubleshooting</a> | |
| 69 | + </div> | |
| 70 | +</aside> | |
| 71 | + | |
| 72 | +<article class="content"> | |
| 73 | + | |
| 74 | +<h1>Architecture</h1> | |
| 75 | +<p class="lead">One rule above all: <strong>the kernel stays small</strong>. Complexity lives in | |
| 76 | +services around it — never inside it.</p> | |
| 77 | + | |
| 78 | +<h2 id="map">The map<a class="anchor" href="#map">#</a></h2> | |
| 79 | +<pre><code> KHAELOR TUI ──── khaelord (daemon) | |
| 80 | + │ │ | |
| 81 | + ▼ ▼ | |
| 82 | + Session Engine (JSONL event log) | |
| 83 | + │ | |
| 84 | + ▼ | |
| 85 | + Agent Kernel ← deriveNext(state) — a pure fold | |
| 86 | + ┌───────────────┼───────────────────┐ | |
| 87 | + ▼ ▼ ▼ | |
| 88 | + Context Engine Tool Runtime Model Runtime | |
| 89 | + (tiers, cache, (permissions, (Anthropic SDK, | |
| 90 | + compaction) phase gate, streaming) | |
| 91 | + │ verify loop) | |
| 92 | + ▼ ▼ | |
| 93 | + RepoGraph Workspace ── the ONLY fs/process seam | |
| 94 | + Memory │ | |
| 95 | + Phases Files · Processes · Git worktrees</code></pre> | |
| 96 | + | |
| 97 | +<h2 id="kernel">The kernel is a fold<a class="anchor" href="#kernel">#</a></h2> | |
| 98 | +<p>Each iteration, the kernel re-derives “what next” from the recorded event log — not from | |
| 99 | +loop-local flags. <code>foldTurnState(events)</code> → <code>deriveNext(state)</code> → dispatch to | |
| 100 | +a service. Interruption, steering injection, compaction, verification, completion: all are | |
| 101 | +positions in the log, which is why resume, fork, and replay are cheap and exact.</p> | |
| 102 | + | |
| 103 | +<h2 id="services">Services around the kernel<a class="anchor" href="#services">#</a></h2> | |
| 104 | +<table> | |
| 105 | + <tr><th>Service</th><th>Owns</th></tr> | |
| 106 | + <tr><td>PhaseService</td><td class="wrap">The gate: per-phase capability policy, design approval, phase events. Consulted by the Tool Runtime — the kernel never sees it.</td></tr> | |
| 107 | + <tr><td>VerifyRunner</td><td class="wrap">Native checks after edit batches, the bounded repair loop.</td></tr> | |
| 108 | + <tr><td>PermissionService</td><td class="wrap">Capability evaluation (deny > ask > allow), grants, the panel seam.</td></tr> | |
| 109 | + <tr><td>ContextEngine</td><td class="wrap">Tiers, byte-stable history projection, prune/compact decisions.</td></tr> | |
| 110 | + <tr><td>RepoGraphService</td><td class="wrap">The incremental semantic index behind symbols/refs/skeletons.</td></tr> | |
| 111 | + <tr><td>SubtaskManager</td><td class="wrap">Worktree lifecycle, child engines, supervised merges.</td></tr> | |
| 112 | + <tr><td>GoalStore / BudgetGuard / ApprovalQueue</td><td class="wrap">The daemon's persistence: goals, ledgers, pending approvals — plain files under <code>.khaelor/daemon/</code>.</td></tr> | |
| 113 | +</table> | |
| 114 | + | |
| 115 | +<h2 id="seams">The seams that matter<a class="anchor" href="#seams">#</a></h2> | |
| 116 | +<ul> | |
| 117 | + <li><strong>Workspace</strong> — four methods (<code>cwd</code>, <code>readFile</code>, | |
| 118 | + <code>writeFile</code>, <code>exec</code>); the only module allowed to import | |
| 119 | + <code>node:fs</code>/<code>child_process</code>. Everything above it is testable and portable.</li> | |
| 120 | + <li><strong>ModelClient</strong> — one streaming interface over the Anthropic SDK. Not a | |
| 121 | + multi-provider framework; just a clean wall.</li> | |
| 122 | + <li><strong>ChannelAdapter</strong> — daemon notifications (webhook, command today; richer | |
| 123 | + channels later without touching the core).</li> | |
| 124 | +</ul> | |
| 125 | + | |
| 126 | +<h2 id="rules">House rules<a class="anchor" href="#rules">#</a></h2> | |
| 127 | +<ul> | |
| 128 | + <li>Every displayed number comes from real data — usage metadata, exit codes, git diffs. No | |
| 129 | + fabricated progress, ever.</li> | |
| 130 | + <li>Baseline git state is recorded before edits; KHAELOR never assumes an existing diff is its | |
| 131 | + own, and never commits unless asked.</li> | |
| 132 | + <li>Whenever something is tempted into the kernel, the question is asked: <em>can this be a | |
| 133 | + service around it?</em> The answer so far has always been yes.</li> | |
| 134 | +</ul> | |
| 135 | + | |
| 136 | +<div class="pager"> | |
| 137 | + <div class="next"><span class="label">Next</span><a href="/docs/events.html">The event model →</a></div> | |
| 138 | +</div> | |
| 139 | + | |
| 140 | +</article> | |
| 141 | +</div></main> | |
| 142 | + | |
| 143 | +<footer class="site-footer"><div class="inner"> | |
| 144 | + <span>KHAELOR — Simon-Pierre Boucher · <a href="mailto:contact@spboucher.ai">contact@spboucher.ai</a></span> | |
| 145 | + <span>Anthropic-powered · terminal-native by design</span> | |
| 146 | +</div></footer> | |
| 147 | + | |
| 148 | +</body> | |
| 149 | +</html> | |
added
website/public/docs/cli.html
+138 −0
@@ -0,0 +1,138 @@ | ||
| 1 | +<!doctype html> | |
| 2 | +<!-- | |
| 3 | +KHAELOR | |
| 4 | +File: website/public/docs/cli.html | |
| 5 | +Description: Docs — Every khaelor and khaelord flag and subcommand, with environment variables and exit behavior. | |
| 6 | +Author: Simon-Pierre Boucher | |
| 7 | +Contact: contact@spboucher.ai | |
| 8 | +--> | |
| 9 | +<html lang="en"> | |
| 10 | +<head> | |
| 11 | +<meta charset="utf-8"> | |
| 12 | +<meta name="viewport" content="width=device-width, initial-scale=1"> | |
| 13 | +<title>CLI reference — KHAELOR docs</title> | |
| 14 | +<meta name="description" content="Every khaelor and khaelord flag and subcommand, with environment variables and exit behavior."> | |
| 15 | +<link rel="stylesheet" href="/styles.css"> | |
| 16 | +<script> | |
| 17 | +(function(){try{var t=localStorage.getItem("khaelor-theme");if(!t&&window.matchMedia&&window.matchMedia("(prefers-color-scheme: light)").matches)t="light";if(t==="light")document.documentElement.setAttribute("data-theme","light");}catch(e){}})(); | |
| 18 | +</script> | |
| 19 | +<script defer src="/site.js"></script> | |
| 20 | +</head> | |
| 21 | +<body> | |
| 22 | + | |
| 23 | +<header class="site-header"><div class="inner"> | |
| 24 | + <a class="wordmark" href="/"><span class="glyph">❯</span><span class="g-ember">KHAELOR</span></a> | |
| 25 | + <nav> | |
| 26 | + <a href="/docs/getting-started.html">Docs</a> | |
| 27 | + <a href="/#install">Install</a> | |
| 28 | + <button id="theme-toggle" type="button" aria-label="Toggle color theme">light</button> | |
| 29 | + </nav> | |
| 30 | +</div></header> | |
| 31 | + | |
| 32 | +<main class="page"><div class="docs-layout"> | |
| 33 | + | |
| 34 | +<aside class="sidebar"> | |
| 35 | + <div class="group"><div class="group-title">Start</div> | |
| 36 | + <a href="/docs/getting-started.html">Getting started</a> | |
| 37 | + <a href="/docs/cookbook.html">Cookbook</a> | |
| 38 | + </div> | |
| 39 | + <div class="group"><div class="group-title">Using KHAELOR</div> | |
| 40 | + <a href="/docs/usage.html">The TUI</a> | |
| 41 | + <a href="/docs/commands.html">Commands & keyboard</a> | |
| 42 | + <a href="/docs/tools.html">Tools</a> | |
| 43 | + <a href="/docs/sessions.html">Sessions</a> | |
| 44 | + </div> | |
| 45 | + <div class="group"><div class="group-title">Autonomy</div> | |
| 46 | + <a href="/docs/phases.html">Phase gates</a> | |
| 47 | + <a href="/docs/verification.html">Verification</a> | |
| 48 | + <a href="/docs/worktrees.html">Parallel worktrees</a> | |
| 49 | + <a href="/docs/daemon.html">The daemon</a> | |
| 50 | + </div> | |
| 51 | + <div class="group"><div class="group-title">Intelligence</div> | |
| 52 | + <a href="/docs/repograph.html">Semantic index</a> | |
| 53 | + <a href="/docs/memory.html">Project memory</a> | |
| 54 | + <a href="/docs/context.html">Context engine</a> | |
| 55 | + <a href="/docs/fork-replay.html">Fork · replay · sdiff</a> | |
| 56 | + </div> | |
| 57 | + <div class="group"><div class="group-title">Control</div> | |
| 58 | + <a href="/docs/permissions.html">Permissions</a> | |
| 59 | + <a href="/docs/configuration.html">Configuration</a> | |
| 60 | + <a href="/docs/cli.html">CLI reference</a> | |
| 61 | + </div> | |
| 62 | + <div class="group"><div class="group-title">Internals</div> | |
| 63 | + <a href="/docs/architecture.html">Architecture</a> | |
| 64 | + <a href="/docs/events.html">The event model</a> | |
| 65 | + <a href="/docs/theming.html">Theming & terminal</a> | |
| 66 | + </div> | |
| 67 | + <div class="group"><div class="group-title">Help</div> | |
| 68 | + <a href="/docs/faq.html">FAQ & troubleshooting</a> | |
| 69 | + </div> | |
| 70 | +</aside> | |
| 71 | + | |
| 72 | +<article class="content"> | |
| 73 | + | |
| 74 | +<h1>CLI reference</h1> | |
| 75 | +<p class="lead">Two binaries: <code>khaelor</code> (the interactive agent) and | |
| 76 | +<code>khaelord</code> (the autonomous daemon).</p> | |
| 77 | + | |
| 78 | +<h2 id="khaelor">khaelor<a class="anchor" href="#khaelor">#</a></h2> | |
| 79 | +<table> | |
| 80 | + <tr><th>Flag</th><th>Meaning</th></tr> | |
| 81 | + <tr><td><code>--model <id></code></td><td class="wrap">Anthropic model id for this run.</td></tr> | |
| 82 | + <tr><td><code>--aux-model <id></code></td><td class="wrap">Cheaper model used for context compaction summaries.</td></tr> | |
| 83 | + <tr><td><code>--thinking <mode></code></td><td class="wrap">off · adaptive · always.</td></tr> | |
| 84 | + <tr><td><code>--max-output-tokens <n></code></td><td class="wrap">Output ceiling per model response.</td></tr> | |
| 85 | + <tr><td><code>--gate <mode></code></td><td class="wrap">Phase-gate rigor: strict · auto (default) · off.</td></tr> | |
| 86 | + <tr><td><code>-p, --print "<prompt>"</code></td><td class="wrap">Headless single turn: run, print the final answer, exit. Permission asks resolve to deny.</td></tr> | |
| 87 | + <tr><td><code>--resume <session-id></code></td><td class="wrap">Resume a session (resume = exact replay of its log).</td></tr> | |
| 88 | + <tr><td><code>--splash</code></td><td class="wrap">Show the full gradient-sweep splash (~600 ms, any key skips).</td></tr> | |
| 89 | + <tr><td><code>--doctor-tui</code></td><td class="wrap">Print the detected terminal capabilities — colors, unicode, OSC 8/52 — with the reason for each, then exit. Attach it to display bug reports.</td></tr> | |
| 90 | + <tr><td><code>--debug</code></td><td class="wrap">Developer logs to <code>~/.khaelor/logs/</code>. The TUI stays clean; keys are never logged.</td></tr> | |
| 91 | + <tr><td><code>-v, --version</code> / <code>-h, --help</code></td><td class="wrap">Version / help.</td></tr> | |
| 92 | +</table> | |
| 93 | + | |
| 94 | +<h2 id="khaelord">khaelord<a class="anchor" href="#khaelord">#</a></h2> | |
| 95 | +<pre><code>khaelord start # foreground; detach with nohup / launchd / systemd | |
| 96 | +khaelord stop | status | |
| 97 | + | |
| 98 | +khaelord goal add "<description>" [--type maintain|achieve|watch] | |
| 99 | + [--schedule "<cron>"|heartbeat] [--check "<cmd>"] | |
| 100 | + [--budget <usd>] [--runs <n>] [--escalation notify|draft-pr|auto-merge-if-verified] | |
| 101 | +khaelord goal list | pause <id> | resume <id> | |
| 102 | + | |
| 103 | +khaelord approvals # pending asynchronous approvals | |
| 104 | +khaelord approve <id> | deny <id></code></pre> | |
| 105 | +<p>Full semantics: <a href="/docs/daemon.html">The daemon</a>. The daemon reads | |
| 106 | +<code>.khaelor/daemon/config.json</code> (budget, activeHours, heartbeatMinutes, models, channels, | |
| 107 | +pricing) and exposes a JSON-line control socket at <code>.khaelor/daemon/daemon.sock</code>.</p> | |
| 108 | + | |
| 109 | +<h2 id="env">Environment<a class="anchor" href="#env">#</a></h2> | |
| 110 | +<table> | |
| 111 | + <tr><td><code>ANTHROPIC_API_KEY</code></td><td class="wrap">Required. Read from the environment on every start; never stored, never logged, rejected if found in config files.</td></tr> | |
| 112 | + <tr><td><code>NO_COLOR</code></td><td class="wrap">Full monochrome degradation — every state keeps a symbol or word.</td></tr> | |
| 113 | + <tr><td><code>TERM</code>, <code>COLORTERM</code></td><td class="wrap">Drive the truecolor → 256 → 16 → mono ladder (see <code>--doctor-tui</code>).</td></tr> | |
| 114 | +</table> | |
| 115 | + | |
| 116 | +<h2 id="exit">Exit behavior<a class="anchor" href="#exit">#</a></h2> | |
| 117 | +<ul> | |
| 118 | + <li><code>--print</code> exits 0 on a completed turn, 1 on failure, 2 on bad arguments — and | |
| 119 | + writes an honest usage summary (real tokens) to stderr.</li> | |
| 120 | + <li>Interactive quit stops background processes, flushes and closes the session log. | |
| 121 | + <kbd>Ctrl+C</kbd> twice force-quits; the log's torn-line recovery handles the rest on resume.</li> | |
| 122 | +</ul> | |
| 123 | + | |
| 124 | +<div class="pager"> | |
| 125 | + <div><span class="label">Previous</span><a href="/docs/configuration.html">← Configuration</a></div> | |
| 126 | + <div class="next"><span class="label">Next</span><a href="/docs/architecture.html">Architecture →</a></div> | |
| 127 | +</div> | |
| 128 | + | |
| 129 | +</article> | |
| 130 | +</div></main> | |
| 131 | + | |
| 132 | +<footer class="site-footer"><div class="inner"> | |
| 133 | + <span>KHAELOR — Simon-Pierre Boucher · <a href="mailto:contact@spboucher.ai">contact@spboucher.ai</a></span> | |
| 134 | + <span>Anthropic-powered · terminal-native by design</span> | |
| 135 | +</div></footer> | |
| 136 | + | |
| 137 | +</body> | |
| 138 | +</html> | |
modified
website/public/docs/commands.html
+16 −1
@@ -34,6 +34,7 @@ Contact: contact@spboucher.ai | ||
| 34 | 34 | <aside class="sidebar"> |
| 35 | 35 | <div class="group"><div class="group-title">Start</div> |
| 36 | 36 | <a href="/docs/getting-started.html">Getting started</a> |
| 37 | + <a href="/docs/cookbook.html">Cookbook</a> | |
| 37 | 38 | </div> |
| 38 | 39 | <div class="group"><div class="group-title">Using KHAELOR</div> |
| 39 | 40 | <a href="/docs/usage.html">The TUI</a> |
@@ -42,12 +43,26 @@ Contact: contact@spboucher.ai | ||
| 42 | 43 | <a href="/docs/sessions.html">Sessions</a> |
| 43 | 44 | </div> |
| 44 | 45 | <div class="group"><div class="group-title">Autonomy</div> |
| 45 | − <a href="/docs/phases.html">Phase gates & verify</a> | |
| 46 | + <a href="/docs/phases.html">Phase gates</a> | |
| 47 | + <a href="/docs/verification.html">Verification</a> | |
| 48 | + <a href="/docs/worktrees.html">Parallel worktrees</a> | |
| 46 | 49 | <a href="/docs/daemon.html">The daemon</a> |
| 47 | 50 | </div> |
| 51 | + <div class="group"><div class="group-title">Intelligence</div> | |
| 52 | + <a href="/docs/repograph.html">Semantic index</a> | |
| 53 | + <a href="/docs/memory.html">Project memory</a> | |
| 54 | + <a href="/docs/context.html">Context engine</a> | |
| 55 | + <a href="/docs/fork-replay.html">Fork · replay · sdiff</a> | |
| 56 | + </div> | |
| 48 | 57 | <div class="group"><div class="group-title">Control</div> |
| 49 | 58 | <a href="/docs/permissions.html">Permissions</a> |
| 50 | 59 | <a href="/docs/configuration.html">Configuration</a> |
| 60 | + <a href="/docs/cli.html">CLI reference</a> | |
| 61 | + </div> | |
| 62 | + <div class="group"><div class="group-title">Internals</div> | |
| 63 | + <a href="/docs/architecture.html">Architecture</a> | |
| 64 | + <a href="/docs/events.html">The event model</a> | |
| 65 | + <a href="/docs/theming.html">Theming & terminal</a> | |
| 51 | 66 | </div> |
| 52 | 67 | <div class="group"><div class="group-title">Help</div> |
| 53 | 68 | <a href="/docs/faq.html">FAQ & troubleshooting</a> |
modified
website/public/docs/configuration.html
+16 −1
@@ -34,6 +34,7 @@ Contact: contact@spboucher.ai | ||
| 34 | 34 | <aside class="sidebar"> |
| 35 | 35 | <div class="group"><div class="group-title">Start</div> |
| 36 | 36 | <a href="/docs/getting-started.html">Getting started</a> |
| 37 | + <a href="/docs/cookbook.html">Cookbook</a> | |
| 37 | 38 | </div> |
| 38 | 39 | <div class="group"><div class="group-title">Using KHAELOR</div> |
| 39 | 40 | <a href="/docs/usage.html">The TUI</a> |
@@ -42,12 +43,26 @@ Contact: contact@spboucher.ai | ||
| 42 | 43 | <a href="/docs/sessions.html">Sessions</a> |
| 43 | 44 | </div> |
| 44 | 45 | <div class="group"><div class="group-title">Autonomy</div> |
| 45 | − <a href="/docs/phases.html">Phase gates & verify</a> | |
| 46 | + <a href="/docs/phases.html">Phase gates</a> | |
| 47 | + <a href="/docs/verification.html">Verification</a> | |
| 48 | + <a href="/docs/worktrees.html">Parallel worktrees</a> | |
| 46 | 49 | <a href="/docs/daemon.html">The daemon</a> |
| 47 | 50 | </div> |
| 51 | + <div class="group"><div class="group-title">Intelligence</div> | |
| 52 | + <a href="/docs/repograph.html">Semantic index</a> | |
| 53 | + <a href="/docs/memory.html">Project memory</a> | |
| 54 | + <a href="/docs/context.html">Context engine</a> | |
| 55 | + <a href="/docs/fork-replay.html">Fork · replay · sdiff</a> | |
| 56 | + </div> | |
| 48 | 57 | <div class="group"><div class="group-title">Control</div> |
| 49 | 58 | <a href="/docs/permissions.html">Permissions</a> |
| 50 | 59 | <a href="/docs/configuration.html">Configuration</a> |
| 60 | + <a href="/docs/cli.html">CLI reference</a> | |
| 61 | + </div> | |
| 62 | + <div class="group"><div class="group-title">Internals</div> | |
| 63 | + <a href="/docs/architecture.html">Architecture</a> | |
| 64 | + <a href="/docs/events.html">The event model</a> | |
| 65 | + <a href="/docs/theming.html">Theming & terminal</a> | |
| 51 | 66 | </div> |
| 52 | 67 | <div class="group"><div class="group-title">Help</div> |
| 53 | 68 | <a href="/docs/faq.html">FAQ & troubleshooting</a> |
added
website/public/docs/context.html
+145 −0
@@ -0,0 +1,145 @@ | ||
| 1 | +<!doctype html> | |
| 2 | +<!-- | |
| 3 | +KHAELOR | |
| 4 | +File: website/public/docs/context.html | |
| 5 | +Description: Docs — How KHAELOR decides what the model sees: tiers, byte-stable history, pruning, structured compaction checkpoints, /context and /cost. | |
| 6 | +Author: Simon-Pierre Boucher | |
| 7 | +Contact: contact@spboucher.ai | |
| 8 | +--> | |
| 9 | +<html lang="en"> | |
| 10 | +<head> | |
| 11 | +<meta charset="utf-8"> | |
| 12 | +<meta name="viewport" content="width=device-width, initial-scale=1"> | |
| 13 | +<title>Context engine — KHAELOR docs</title> | |
| 14 | +<meta name="description" content="How KHAELOR decides what the model sees: tiers, byte-stable history, pruning, structured compaction checkpoints, /context and /cost."> | |
| 15 | +<link rel="stylesheet" href="/styles.css"> | |
| 16 | +<script> | |
| 17 | +(function(){try{var t=localStorage.getItem("khaelor-theme");if(!t&&window.matchMedia&&window.matchMedia("(prefers-color-scheme: light)").matches)t="light";if(t==="light")document.documentElement.setAttribute("data-theme","light");}catch(e){}})(); | |
| 18 | +</script> | |
| 19 | +<script defer src="/site.js"></script> | |
| 20 | +</head> | |
| 21 | +<body> | |
| 22 | + | |
| 23 | +<header class="site-header"><div class="inner"> | |
| 24 | + <a class="wordmark" href="/"><span class="glyph">❯</span><span class="g-ember">KHAELOR</span></a> | |
| 25 | + <nav> | |
| 26 | + <a href="/docs/getting-started.html">Docs</a> | |
| 27 | + <a href="/#install">Install</a> | |
| 28 | + <button id="theme-toggle" type="button" aria-label="Toggle color theme">light</button> | |
| 29 | + </nav> | |
| 30 | +</div></header> | |
| 31 | + | |
| 32 | +<main class="page"><div class="docs-layout"> | |
| 33 | + | |
| 34 | +<aside class="sidebar"> | |
| 35 | + <div class="group"><div class="group-title">Start</div> | |
| 36 | + <a href="/docs/getting-started.html">Getting started</a> | |
| 37 | + <a href="/docs/cookbook.html">Cookbook</a> | |
| 38 | + </div> | |
| 39 | + <div class="group"><div class="group-title">Using KHAELOR</div> | |
| 40 | + <a href="/docs/usage.html">The TUI</a> | |
| 41 | + <a href="/docs/commands.html">Commands & keyboard</a> | |
| 42 | + <a href="/docs/tools.html">Tools</a> | |
| 43 | + <a href="/docs/sessions.html">Sessions</a> | |
| 44 | + </div> | |
| 45 | + <div class="group"><div class="group-title">Autonomy</div> | |
| 46 | + <a href="/docs/phases.html">Phase gates</a> | |
| 47 | + <a href="/docs/verification.html">Verification</a> | |
| 48 | + <a href="/docs/worktrees.html">Parallel worktrees</a> | |
| 49 | + <a href="/docs/daemon.html">The daemon</a> | |
| 50 | + </div> | |
| 51 | + <div class="group"><div class="group-title">Intelligence</div> | |
| 52 | + <a href="/docs/repograph.html">Semantic index</a> | |
| 53 | + <a href="/docs/memory.html">Project memory</a> | |
| 54 | + <a href="/docs/context.html">Context engine</a> | |
| 55 | + <a href="/docs/fork-replay.html">Fork · replay · sdiff</a> | |
| 56 | + </div> | |
| 57 | + <div class="group"><div class="group-title">Control</div> | |
| 58 | + <a href="/docs/permissions.html">Permissions</a> | |
| 59 | + <a href="/docs/configuration.html">Configuration</a> | |
| 60 | + <a href="/docs/cli.html">CLI reference</a> | |
| 61 | + </div> | |
| 62 | + <div class="group"><div class="group-title">Internals</div> | |
| 63 | + <a href="/docs/architecture.html">Architecture</a> | |
| 64 | + <a href="/docs/events.html">The event model</a> | |
| 65 | + <a href="/docs/theming.html">Theming & terminal</a> | |
| 66 | + </div> | |
| 67 | + <div class="group"><div class="group-title">Help</div> | |
| 68 | + <a href="/docs/faq.html">FAQ & troubleshooting</a> | |
| 69 | + </div> | |
| 70 | +</aside> | |
| 71 | + | |
| 72 | +<article class="content"> | |
| 73 | + | |
| 74 | +<h1>The context engine</h1> | |
| 75 | +<p class="lead">One of KHAELOR's most important components: it decides what the model actually | |
| 76 | +receives — and never simply appends everything forever.</p> | |
| 77 | + | |
| 78 | +<h2 id="layout">What the model sees<a class="anchor" href="#layout">#</a></h2> | |
| 79 | +<table> | |
| 80 | + <tr><th>Tier</th><th>Content</th><th>Stability</th></tr> | |
| 81 | + <tr><td>SYSTEM</td><td class="wrap">Identity & behavior (the three phases live here), tool guidance, project instructions (<code>KHAELOR.md</code> / <code>CLAUDE.md</code> / <code>AGENTS.md</code> + project memory).</td><td class="wrap">Byte-stable per session — prompt-cache breakpoints land at tier ends.</td></tr> | |
| 82 | + <tr><td>HISTORY</td><td class="wrap">A deterministic projection of the durable event log into Anthropic messages — same events, same bytes, every time.</td><td class="wrap">Append-only between compactions.</td></tr> | |
| 83 | + <tr><td>VOLATILE</td><td class="wrap">Current-turn context (git status, mention contents, verification nudges) — injected into the API copy of the current message only, never recorded.</td><td class="wrap">Per call.</td></tr> | |
| 84 | +</table> | |
| 85 | + | |
| 86 | +<h2 id="pressure">Context pressure, three stages<a class="anchor" href="#pressure">#</a></h2> | |
| 87 | +<ol> | |
| 88 | + <li><strong>Prune</strong> (cheap, deterministic, no LLM): old tool results are blanked with an | |
| 89 | + explicit placeholder — recorded as a durable <code>context.pruned</code> event, so the rebuild is | |
| 90 | + byte-exact.</li> | |
| 91 | + <li><strong>Compact</strong>: when nothing prunable remains, the aux model writes a structured | |
| 92 | + checkpoint and a pairing-safe cut of history is replaced by it — durable | |
| 93 | + <code>context.compacted</code>.</li> | |
| 94 | + <li><strong>Reactive</strong>: a context-overflow error from the API routes straight to | |
| 95 | + compaction and the call retries.</li> | |
| 96 | +</ol> | |
| 97 | +<pre><code>objective: fix the renderer memory leak | |
| 98 | +completed: [ring buffer in render.ts, tests updated] | |
| 99 | +current_state: all checks green, awaiting user review | |
| 100 | +important_files: | |
| 101 | + - path: src/tui/render.ts | |
| 102 | + reason: the ring buffer implementation | |
| 103 | +failed_attempts: [capping the array in place — broke scrollback] | |
| 104 | +decisions: [keep the 16ms tick contract untouched] | |
| 105 | +running_processes: [] | |
| 106 | +next_steps: [consider the same fix for the composer history]</code></pre> | |
| 107 | +<p>The checkpoint is YAML with fixed sections — objective, completed, state, files with reasons, | |
| 108 | +failed attempts, decisions, processes, next steps — so nothing load-bearing dissolves into prose.</p> | |
| 109 | +<div class="termwrap"><div class="termbar"><span class="dot r"></span><span class="dot y"></span><span class="dot g"></span><span class="title">/context</span></div> | |
| 110 | +<pre class="term" data-no-copy><code> <span class="t-b">context · section estimates</span> <span class="t-dim">(~4 chars/token)</span> | |
| 111 | + system:identity ~1,240 tokens | |
| 112 | + system:tools ~2,610 tokens | |
| 113 | + system:project-instructions ~3,905 tokens | |
| 114 | + tools ~1,878 tokens | |
| 115 | + history ~38,412 tokens | |
| 116 | + <span class="t-b">total (estimated) ~48,045 tokens</span> | |
| 117 | + window 200,000 · usable 168,000 <span class="t-dim">(output + compaction reserve held back)</span> | |
| 118 | + last real total 45,208 tokens · pressure <span class="gauge">27%</span></code></pre></div> | |
| 119 | +<h2 id="cache">Prompt caching<a class="anchor" href="#cache">#</a></h2> | |
| 120 | +<p>System tiers are frozen at assembly and never re-rendered; switching models starts a fresh cache | |
| 121 | +lineage on purpose. The status-bar gauge shows <em>real</em> pressure (last real token total vs the | |
| 122 | +usable window) — estimates are always labeled as estimates.</p> | |
| 123 | + | |
| 124 | +<h2 id="commands">Commands<a class="anchor" href="#commands">#</a></h2> | |
| 125 | +<table> | |
| 126 | + <tr><td><code>/context</code></td><td class="wrap">The budget breakdown above.</td></tr> | |
| 127 | + <tr><td><code>/compact</code></td><td class="wrap">Manual compaction: prune first, summarize-compact only if nothing prunable remains.</td></tr> | |
| 128 | + <tr><td><code>/cost</code></td><td class="wrap">Real usage per model — requests, input/output, cache read/write. Dollar figures only with configured pricing.</td></tr> | |
| 129 | +</table> | |
| 130 | + | |
| 131 | +<div class="pager"> | |
| 132 | + <div><span class="label">Previous</span><a href="/docs/memory.html">← Project memory</a></div> | |
| 133 | + <div class="next"><span class="label">Next</span><a href="/docs/fork-replay.html">Fork · replay · sdiff →</a></div> | |
| 134 | +</div> | |
| 135 | + | |
| 136 | +</article> | |
| 137 | +</div></main> | |
| 138 | + | |
| 139 | +<footer class="site-footer"><div class="inner"> | |
| 140 | + <span>KHAELOR — Simon-Pierre Boucher · <a href="mailto:contact@spboucher.ai">contact@spboucher.ai</a></span> | |
| 141 | + <span>Anthropic-powered · terminal-native by design</span> | |
| 142 | +</div></footer> | |
| 143 | + | |
| 144 | +</body> | |
| 145 | +</html> | |
added
website/public/docs/cookbook.html
+142 −0
@@ -0,0 +1,142 @@ | ||
| 1 | +<!doctype html> | |
| 2 | +<!-- | |
| 3 | +KHAELOR | |
| 4 | +File: website/public/docs/cookbook.html | |
| 5 | +Description: Docs — Recipes for real KHAELOR workflows: bug fixes, refactors, model comparisons, nightly maintenance, migrations. | |
| 6 | +Author: Simon-Pierre Boucher | |
| 7 | +Contact: contact@spboucher.ai | |
| 8 | +--> | |
| 9 | +<html lang="en"> | |
| 10 | +<head> | |
| 11 | +<meta charset="utf-8"> | |
| 12 | +<meta name="viewport" content="width=device-width, initial-scale=1"> | |
| 13 | +<title>Cookbook — KHAELOR docs</title> | |
| 14 | +<meta name="description" content="Recipes for real KHAELOR workflows: bug fixes, refactors, model comparisons, nightly maintenance, migrations."> | |
| 15 | +<link rel="stylesheet" href="/styles.css"> | |
| 16 | +<script> | |
| 17 | +(function(){try{var t=localStorage.getItem("khaelor-theme");if(!t&&window.matchMedia&&window.matchMedia("(prefers-color-scheme: light)").matches)t="light";if(t==="light")document.documentElement.setAttribute("data-theme","light");}catch(e){}})(); | |
| 18 | +</script> | |
| 19 | +<script defer src="/site.js"></script> | |
| 20 | +</head> | |
| 21 | +<body> | |
| 22 | + | |
| 23 | +<header class="site-header"><div class="inner"> | |
| 24 | + <a class="wordmark" href="/"><span class="glyph">❯</span><span class="g-ember">KHAELOR</span></a> | |
| 25 | + <nav> | |
| 26 | + <a href="/docs/getting-started.html">Docs</a> | |
| 27 | + <a href="/#install">Install</a> | |
| 28 | + <button id="theme-toggle" type="button" aria-label="Toggle color theme">light</button> | |
| 29 | + </nav> | |
| 30 | +</div></header> | |
| 31 | + | |
| 32 | +<main class="page"><div class="docs-layout"> | |
| 33 | + | |
| 34 | +<aside class="sidebar"> | |
| 35 | + <div class="group"><div class="group-title">Start</div> | |
| 36 | + <a href="/docs/getting-started.html">Getting started</a> | |
| 37 | + <a href="/docs/cookbook.html">Cookbook</a> | |
| 38 | + </div> | |
| 39 | + <div class="group"><div class="group-title">Using KHAELOR</div> | |
| 40 | + <a href="/docs/usage.html">The TUI</a> | |
| 41 | + <a href="/docs/commands.html">Commands & keyboard</a> | |
| 42 | + <a href="/docs/tools.html">Tools</a> | |
| 43 | + <a href="/docs/sessions.html">Sessions</a> | |
| 44 | + </div> | |
| 45 | + <div class="group"><div class="group-title">Autonomy</div> | |
| 46 | + <a href="/docs/phases.html">Phase gates</a> | |
| 47 | + <a href="/docs/verification.html">Verification</a> | |
| 48 | + <a href="/docs/worktrees.html">Parallel worktrees</a> | |
| 49 | + <a href="/docs/daemon.html">The daemon</a> | |
| 50 | + </div> | |
| 51 | + <div class="group"><div class="group-title">Intelligence</div> | |
| 52 | + <a href="/docs/repograph.html">Semantic index</a> | |
| 53 | + <a href="/docs/memory.html">Project memory</a> | |
| 54 | + <a href="/docs/context.html">Context engine</a> | |
| 55 | + <a href="/docs/fork-replay.html">Fork · replay · sdiff</a> | |
| 56 | + </div> | |
| 57 | + <div class="group"><div class="group-title">Control</div> | |
| 58 | + <a href="/docs/permissions.html">Permissions</a> | |
| 59 | + <a href="/docs/configuration.html">Configuration</a> | |
| 60 | + <a href="/docs/cli.html">CLI reference</a> | |
| 61 | + </div> | |
| 62 | + <div class="group"><div class="group-title">Internals</div> | |
| 63 | + <a href="/docs/architecture.html">Architecture</a> | |
| 64 | + <a href="/docs/events.html">The event model</a> | |
| 65 | + <a href="/docs/theming.html">Theming & terminal</a> | |
| 66 | + </div> | |
| 67 | + <div class="group"><div class="group-title">Help</div> | |
| 68 | + <a href="/docs/faq.html">FAQ & troubleshooting</a> | |
| 69 | + </div> | |
| 70 | +</aside> | |
| 71 | + | |
| 72 | +<article class="content"> | |
| 73 | + | |
| 74 | +<h1>Cookbook</h1> | |
| 75 | +<p class="lead">Concrete recipes — each one uses the workflow KHAELOR was built around.</p> | |
| 76 | + | |
| 77 | +<h2 id="bugfix">Fix a bug, verified<a class="anchor" href="#bugfix">#</a></h2> | |
| 78 | +<pre><code>khaelor | |
| 79 | +❯ users report the export button 500s when the list is empty — find it and fix it</code></pre> | |
| 80 | +<p>KHAELOR explores with <code>symbols</code>/<code>refs</code>/<code>read</code> (understand), | |
| 81 | +submits a design (a small one auto-approves), edits, and the verify loop runs your typecheck and | |
| 82 | +tests before it answers. If a test fails, it repairs — bounded to 3 rounds, then an honest report.</p> | |
| 83 | + | |
| 84 | +<h2 id="compare">Compare two models on the same task<a class="anchor" href="#compare">#</a></h2> | |
| 85 | +<pre><code>❯ /replay # type the finished session's id — re-runs its user turns | |
| 86 | +❯ /model # or switch model first, then /replay | |
| 87 | +❯ /sdiff # "<idA> <idB>" — turns, tool calls, files, tokens, verify failures</code></pre> | |
| 88 | +<p>The replay executes inside a throwaway git worktree, so re-run tool calls never touch your | |
| 89 | +working copy. <em>Run it twice, diff the runs.</em></p> | |
| 90 | + | |
| 91 | +<h2 id="parallel">Two features in parallel<a class="anchor" href="#parallel">#</a></h2> | |
| 92 | +<pre><code>❯ /spawn # "fix the auth bug" | |
| 93 | +❯ /spawn # "add rate limiting to the API" | |
| 94 | +❯ /tasks # watch both: phase, diff stats, verify state | |
| 95 | +❯ /merge # supervised --no-ff merge of each finished branch</code></pre> | |
| 96 | +<p>Each subtask gets its own worktree, branch (<code>khaelor/<id></code>), and child session | |
| 97 | +with attenuated permissions. Conflicts abort cleanly; ask KHAELOR to resolve them with both | |
| 98 | +designs in context.</p> | |
| 99 | + | |
| 100 | +<h2 id="nightly">Nightly dependency maintenance<a class="anchor" href="#nightly">#</a></h2> | |
| 101 | +<pre><code>khaelord goal add "npm deps stay fresh without breaking changes" \ | |
| 102 | + --type maintain --schedule "0 6 * * 1" \ | |
| 103 | + --check "npm outdated --json | grep -q ." --escalation draft-pr | |
| 104 | +khaelord start</code></pre> | |
| 105 | +<p>Monday 06:00: the cheap <code>check</code> decides whether there is anything to do; a real run | |
| 106 | +opens a worktree, designs, upgrades, verifies, and leaves a branch for your review. Budget-capped, | |
| 107 | +fully event-logged.</p> | |
| 108 | + | |
| 109 | +<h2 id="branch-experiment">Branch an exploration without losing the thread<a class="anchor" href="#branch-experiment">#</a></h2> | |
| 110 | +<pre><code>❯ /fork # pick "❯ now add tests" — the fork opens there | |
| 111 | +# try the risky approach in the fork; the original session is untouched | |
| 112 | +❯ /sessions # jump back anytime — resume = exact replay</code></pre> | |
| 113 | + | |
| 114 | +<h2 id="teach">Teach KHAELOR your project once<a class="anchor" href="#teach">#</a></h2> | |
| 115 | +<pre><code>❯ our error convention: everything returns Result<T,KError>, never throw in src/core — remember that</code></pre> | |
| 116 | +<p>The agent persists it via the <code>remember</code> tool into <code>.khaelor/MEMORY.md</code> | |
| 117 | +with provenance. Every future session starts knowing it. Audit with <code>/memory</code>.</p> | |
| 118 | + | |
| 119 | +<h2 id="headless">Headless in CI or scripts<a class="anchor" href="#headless">#</a></h2> | |
| 120 | +<pre><code>khaelor --print "summarize the churn in src/ since last tag" --gate off | |
| 121 | +# permission asks resolve to DENY headless — grant what CI needs in .khaelor/config.json</code></pre> | |
| 122 | + | |
| 123 | +<h2 id="strict">High-stakes change, strict gate<a class="anchor" href="#strict">#</a></h2> | |
| 124 | +<pre><code>khaelor --gate strict | |
| 125 | +❯ migrate the session store from JSON to SQLite</code></pre> | |
| 126 | +<p>Nothing gets written until you approve the design panel — goal, approach, files, risks, | |
| 127 | +verification — with a single keystroke.</p> | |
| 128 | + | |
| 129 | +<div class="pager"> | |
| 130 | + <div class="next"><span class="label">Next</span><a href="/docs/usage.html">The TUI →</a></div> | |
| 131 | +</div> | |
| 132 | + | |
| 133 | +</article> | |
| 134 | +</div></main> | |
| 135 | + | |
| 136 | +<footer class="site-footer"><div class="inner"> | |
| 137 | + <span>KHAELOR — Simon-Pierre Boucher · <a href="mailto:contact@spboucher.ai">contact@spboucher.ai</a></span> | |
| 138 | + <span>Anthropic-powered · terminal-native by design</span> | |
| 139 | +</div></footer> | |
| 140 | + | |
| 141 | +</body> | |
| 142 | +</html> | |
modified
website/public/docs/daemon.html
+16 −1
@@ -34,6 +34,7 @@ Contact: contact@spboucher.ai | ||
| 34 | 34 | <aside class="sidebar"> |
| 35 | 35 | <div class="group"><div class="group-title">Start</div> |
| 36 | 36 | <a href="/docs/getting-started.html">Getting started</a> |
| 37 | + <a href="/docs/cookbook.html">Cookbook</a> | |
| 37 | 38 | </div> |
| 38 | 39 | <div class="group"><div class="group-title">Using KHAELOR</div> |
| 39 | 40 | <a href="/docs/usage.html">The TUI</a> |
@@ -42,12 +43,26 @@ Contact: contact@spboucher.ai | ||
| 42 | 43 | <a href="/docs/sessions.html">Sessions</a> |
| 43 | 44 | </div> |
| 44 | 45 | <div class="group"><div class="group-title">Autonomy</div> |
| 45 | − <a href="/docs/phases.html">Phase gates & verify</a> | |
| 46 | + <a href="/docs/phases.html">Phase gates</a> | |
| 47 | + <a href="/docs/verification.html">Verification</a> | |
| 48 | + <a href="/docs/worktrees.html">Parallel worktrees</a> | |
| 46 | 49 | <a href="/docs/daemon.html">The daemon</a> |
| 47 | 50 | </div> |
| 51 | + <div class="group"><div class="group-title">Intelligence</div> | |
| 52 | + <a href="/docs/repograph.html">Semantic index</a> | |
| 53 | + <a href="/docs/memory.html">Project memory</a> | |
| 54 | + <a href="/docs/context.html">Context engine</a> | |
| 55 | + <a href="/docs/fork-replay.html">Fork · replay · sdiff</a> | |
| 56 | + </div> | |
| 48 | 57 | <div class="group"><div class="group-title">Control</div> |
| 49 | 58 | <a href="/docs/permissions.html">Permissions</a> |
| 50 | 59 | <a href="/docs/configuration.html">Configuration</a> |
| 60 | + <a href="/docs/cli.html">CLI reference</a> | |
| 61 | + </div> | |
| 62 | + <div class="group"><div class="group-title">Internals</div> | |
| 63 | + <a href="/docs/architecture.html">Architecture</a> | |
| 64 | + <a href="/docs/events.html">The event model</a> | |
| 65 | + <a href="/docs/theming.html">Theming & terminal</a> | |
| 51 | 66 | </div> |
| 52 | 67 | <div class="group"><div class="group-title">Help</div> |
| 53 | 68 | <a href="/docs/faq.html">FAQ & troubleshooting</a> |
added
website/public/docs/events.html
+142 −0
@@ -0,0 +1,142 @@ | ||
| 1 | +<!doctype html> | |
| 2 | +<!-- | |
| 3 | +KHAELOR | |
| 4 | +File: website/public/docs/events.html | |
| 5 | +Description: Docs — 40 durable event types, the JSONL contract, byte-exact replay, pairing safety, and why auditability falls out for free. | |
| 6 | +Author: Simon-Pierre Boucher | |
| 7 | +Contact: contact@spboucher.ai | |
| 8 | +--> | |
| 9 | +<html lang="en"> | |
| 10 | +<head> | |
| 11 | +<meta charset="utf-8"> | |
| 12 | +<meta name="viewport" content="width=device-width, initial-scale=1"> | |
| 13 | +<title>The event model — KHAELOR docs</title> | |
| 14 | +<meta name="description" content="40 durable event types, the JSONL contract, byte-exact replay, pairing safety, and why auditability falls out for free."> | |
| 15 | +<link rel="stylesheet" href="/styles.css"> | |
| 16 | +<script> | |
| 17 | +(function(){try{var t=localStorage.getItem("khaelor-theme");if(!t&&window.matchMedia&&window.matchMedia("(prefers-color-scheme: light)").matches)t="light";if(t==="light")document.documentElement.setAttribute("data-theme","light");}catch(e){}})(); | |
| 18 | +</script> | |
| 19 | +<script defer src="/site.js"></script> | |
| 20 | +</head> | |
| 21 | +<body> | |
| 22 | + | |
| 23 | +<header class="site-header"><div class="inner"> | |
| 24 | + <a class="wordmark" href="/"><span class="glyph">❯</span><span class="g-ember">KHAELOR</span></a> | |
| 25 | + <nav> | |
| 26 | + <a href="/docs/getting-started.html">Docs</a> | |
| 27 | + <a href="/#install">Install</a> | |
| 28 | + <button id="theme-toggle" type="button" aria-label="Toggle color theme">light</button> | |
| 29 | + </nav> | |
| 30 | +</div></header> | |
| 31 | + | |
| 32 | +<main class="page"><div class="docs-layout"> | |
| 33 | + | |
| 34 | +<aside class="sidebar"> | |
| 35 | + <div class="group"><div class="group-title">Start</div> | |
| 36 | + <a href="/docs/getting-started.html">Getting started</a> | |
| 37 | + <a href="/docs/cookbook.html">Cookbook</a> | |
| 38 | + </div> | |
| 39 | + <div class="group"><div class="group-title">Using KHAELOR</div> | |
| 40 | + <a href="/docs/usage.html">The TUI</a> | |
| 41 | + <a href="/docs/commands.html">Commands & keyboard</a> | |
| 42 | + <a href="/docs/tools.html">Tools</a> | |
| 43 | + <a href="/docs/sessions.html">Sessions</a> | |
| 44 | + </div> | |
| 45 | + <div class="group"><div class="group-title">Autonomy</div> | |
| 46 | + <a href="/docs/phases.html">Phase gates</a> | |
| 47 | + <a href="/docs/verification.html">Verification</a> | |
| 48 | + <a href="/docs/worktrees.html">Parallel worktrees</a> | |
| 49 | + <a href="/docs/daemon.html">The daemon</a> | |
| 50 | + </div> | |
| 51 | + <div class="group"><div class="group-title">Intelligence</div> | |
| 52 | + <a href="/docs/repograph.html">Semantic index</a> | |
| 53 | + <a href="/docs/memory.html">Project memory</a> | |
| 54 | + <a href="/docs/context.html">Context engine</a> | |
| 55 | + <a href="/docs/fork-replay.html">Fork · replay · sdiff</a> | |
| 56 | + </div> | |
| 57 | + <div class="group"><div class="group-title">Control</div> | |
| 58 | + <a href="/docs/permissions.html">Permissions</a> | |
| 59 | + <a href="/docs/configuration.html">Configuration</a> | |
| 60 | + <a href="/docs/cli.html">CLI reference</a> | |
| 61 | + </div> | |
| 62 | + <div class="group"><div class="group-title">Internals</div> | |
| 63 | + <a href="/docs/architecture.html">Architecture</a> | |
| 64 | + <a href="/docs/events.html">The event model</a> | |
| 65 | + <a href="/docs/theming.html">Theming & terminal</a> | |
| 66 | + </div> | |
| 67 | + <div class="group"><div class="group-title">Help</div> | |
| 68 | + <a href="/docs/faq.html">FAQ & troubleshooting</a> | |
| 69 | + </div> | |
| 70 | +</aside> | |
| 71 | + | |
| 72 | +<article class="content"> | |
| 73 | + | |
| 74 | +<h1>The event model</h1> | |
| 75 | +<p class="lead">The append-only event log is the source of truth. Everything else — the | |
| 76 | +conversation, the costs, the diffs, the phases — is a fold over it.</p> | |
| 77 | + | |
| 78 | +<h2 id="envelope">The envelope<a class="anchor" href="#envelope">#</a></h2> | |
| 79 | +<pre><code>{"v":1,"id":"01J8…","sessionId":"01J8…","seq":42,"ts":1765400000000, | |
| 80 | + "type":"tool.completed","payload":{…}}</code></pre> | |
| 81 | +<ul> | |
| 82 | + <li><code>seq</code> is gapless and assigned at append time; one complete line per write, never interleaved.</li> | |
| 83 | + <li>A torn final line (crash mid-write) is quarantined to a <code>.torn</code> file and truncated | |
| 84 | + away on open — corruption anywhere else refuses to resume rather than silently repairing.</li> | |
| 85 | + <li><code>tool.requested</code> inputs are canonicalized (sorted keys) so a replayed history | |
| 86 | + reproduces identical bytes on every rebuild.</li> | |
| 87 | +</ul> | |
| 88 | + | |
| 89 | +<h2 id="families">The 40 durable types, by family<a class="anchor" href="#families">#</a></h2> | |
| 90 | +<table> | |
| 91 | + <tr><th>Family</th><th>Types</th></tr> | |
| 92 | + <tr><td>Session</td><td class="wrap">started · resumed · renamed · model-changed · git.baseline-recorded</td></tr> | |
| 93 | + <tr><td>User</td><td class="wrap">message-created · steering-queued · steering-injected · interrupted</td></tr> | |
| 94 | + <tr><td>Model</td><td class="wrap">request-started · text/thinking-block-completed · response-completed · request-failed</td></tr> | |
| 95 | + <tr><td>Tools</td><td class="wrap">requested · approved · started · completed · failed · cancelled</td></tr> | |
| 96 | + <tr><td>Permissions</td><td class="wrap">requested · granted · denied</td></tr> | |
| 97 | + <tr><td>Files & processes</td><td class="wrap">file.read · file.modified · process.started · process.exited</td></tr> | |
| 98 | + <tr><td>Context</td><td class="wrap">pruned · compacted</td></tr> | |
| 99 | + <tr><td>Completion</td><td class="wrap">verification-requested · task.completed · task.failed</td></tr> | |
| 100 | + <tr><td>Phases (v2)</td><td class="wrap">phase.entered · phase.artifact · phase.approved · phase.rejected</td></tr> | |
| 101 | + <tr><td>Verify / memory / subtasks (v2)</td><td class="wrap">verify.result · memory.written · subtask.created · subtask.completed</td></tr> | |
| 102 | +</table> | |
| 103 | +<p>Six ephemeral types (streaming deltas, live tool output) flow on the bus but are never | |
| 104 | +persisted — the log records what settled, not the typing noise.</p> | |
| 105 | + | |
| 106 | +<h2 id="pairing">Pairing safety<a class="anchor" href="#pairing">#</a></h2> | |
| 107 | +<p>Every <code>tool_use</code> must meet its <code>tool_result</code> — across interruptions, | |
| 108 | +crashes, and compactions. Resume closes dangling calls with synthetic cancellations; a compaction | |
| 109 | +cut is validated so it can never orphan a pair. This single invariant is why the API replay of any | |
| 110 | +KHAELOR session is always well-formed.</p> | |
| 111 | + | |
| 112 | +<h2 id="folds">Everything is a fold<a class="anchor" href="#folds">#</a></h2> | |
| 113 | +<table> | |
| 114 | + <tr><th>Question</th><th>Fold</th></tr> | |
| 115 | + <tr><td>What does the model see?</td><td class="wrap"><code>buildConversation(events)</code> — deterministic, byte-stable, prune/compaction re-applied from their recorded payloads.</td></tr> | |
| 116 | + <tr><td>What did this cost?</td><td class="wrap"><code>buildUsageTotals(events)</code> — sums only <code>response-completed</code> usage. Nothing else may contribute.</td></tr> | |
| 117 | + <tr><td>What changed on disk?</td><td class="wrap"><code>buildFileChangeSet(events)</code> — baseline + file.modified, attribution-aware.</td></tr> | |
| 118 | + <tr><td>What phase am I in?</td><td class="wrap"><code>foldPhaseState(events)</code>.</td></tr> | |
| 119 | + <tr><td>What should happen next?</td><td class="wrap"><code>foldTurnState(events)</code> → <code>deriveNext</code> — the kernel itself.</td></tr> | |
| 120 | +</table> | |
| 121 | + | |
| 122 | +<h2 id="audit">Why audit falls out for free<a class="anchor" href="#audit">#</a></h2> | |
| 123 | +<p>Because state is never anywhere else, <em>explaining</em> any behavior — including a daemon | |
| 124 | +run at 3 AM — is reading a file. <code>/fork</code> is a file-prefix copy. <code>/replay</code> is | |
| 125 | +re-driving the user turns. <code>/sdiff</code> is two folds side by side. None of these are | |
| 126 | +features bolted on; they are corollaries of the event model.</p> | |
| 127 | + | |
| 128 | +<div class="pager"> | |
| 129 | + <div><span class="label">Previous</span><a href="/docs/architecture.html">← Architecture</a></div> | |
| 130 | + <div class="next"><span class="label">Next</span><a href="/docs/theming.html">Theming & terminal →</a></div> | |
| 131 | +</div> | |
| 132 | + | |
| 133 | +</article> | |
| 134 | +</div></main> | |
| 135 | + | |
| 136 | +<footer class="site-footer"><div class="inner"> | |
| 137 | + <span>KHAELOR — Simon-Pierre Boucher · <a href="mailto:contact@spboucher.ai">contact@spboucher.ai</a></span> | |
| 138 | + <span>Anthropic-powered · terminal-native by design</span> | |
| 139 | +</div></footer> | |
| 140 | + | |
| 141 | +</body> | |
| 142 | +</html> | |
modified
website/public/docs/faq.html
+16 −1
@@ -34,6 +34,7 @@ Contact: contact@spboucher.ai | ||
| 34 | 34 | <aside class="sidebar"> |
| 35 | 35 | <div class="group"><div class="group-title">Start</div> |
| 36 | 36 | <a href="/docs/getting-started.html">Getting started</a> |
| 37 | + <a href="/docs/cookbook.html">Cookbook</a> | |
| 37 | 38 | </div> |
| 38 | 39 | <div class="group"><div class="group-title">Using KHAELOR</div> |
| 39 | 40 | <a href="/docs/usage.html">The TUI</a> |
@@ -42,12 +43,26 @@ Contact: contact@spboucher.ai | ||
| 42 | 43 | <a href="/docs/sessions.html">Sessions</a> |
| 43 | 44 | </div> |
| 44 | 45 | <div class="group"><div class="group-title">Autonomy</div> |
| 45 | − <a href="/docs/phases.html">Phase gates & verify</a> | |
| 46 | + <a href="/docs/phases.html">Phase gates</a> | |
| 47 | + <a href="/docs/verification.html">Verification</a> | |
| 48 | + <a href="/docs/worktrees.html">Parallel worktrees</a> | |
| 46 | 49 | <a href="/docs/daemon.html">The daemon</a> |
| 47 | 50 | </div> |
| 51 | + <div class="group"><div class="group-title">Intelligence</div> | |
| 52 | + <a href="/docs/repograph.html">Semantic index</a> | |
| 53 | + <a href="/docs/memory.html">Project memory</a> | |
| 54 | + <a href="/docs/context.html">Context engine</a> | |
| 55 | + <a href="/docs/fork-replay.html">Fork · replay · sdiff</a> | |
| 56 | + </div> | |
| 48 | 57 | <div class="group"><div class="group-title">Control</div> |
| 49 | 58 | <a href="/docs/permissions.html">Permissions</a> |
| 50 | 59 | <a href="/docs/configuration.html">Configuration</a> |
| 60 | + <a href="/docs/cli.html">CLI reference</a> | |
| 61 | + </div> | |
| 62 | + <div class="group"><div class="group-title">Internals</div> | |
| 63 | + <a href="/docs/architecture.html">Architecture</a> | |
| 64 | + <a href="/docs/events.html">The event model</a> | |
| 65 | + <a href="/docs/theming.html">Theming & terminal</a> | |
| 51 | 66 | </div> |
| 52 | 67 | <div class="group"><div class="group-title">Help</div> |
| 53 | 68 | <a href="/docs/faq.html">FAQ & troubleshooting</a> |
added
website/public/docs/fork-replay.html
+141 −0
@@ -0,0 +1,141 @@ | ||
| 1 | +<!doctype html> | |
| 2 | +<!-- | |
| 3 | +KHAELOR | |
| 4 | +File: website/public/docs/fork-replay.html | |
| 5 | +Description: Docs — Session lineage as an instrument: fork any checkpoint, replay user turns sandboxed, diff two runs structurally. | |
| 6 | +Author: Simon-Pierre Boucher | |
| 7 | +Contact: contact@spboucher.ai | |
| 8 | +--> | |
| 9 | +<html lang="en"> | |
| 10 | +<head> | |
| 11 | +<meta charset="utf-8"> | |
| 12 | +<meta name="viewport" content="width=device-width, initial-scale=1"> | |
| 13 | +<title>Fork · replay · sdiff — KHAELOR docs</title> | |
| 14 | +<meta name="description" content="Session lineage as an instrument: fork any checkpoint, replay user turns sandboxed, diff two runs structurally."> | |
| 15 | +<link rel="stylesheet" href="/styles.css"> | |
| 16 | +<script> | |
| 17 | +(function(){try{var t=localStorage.getItem("khaelor-theme");if(!t&&window.matchMedia&&window.matchMedia("(prefers-color-scheme: light)").matches)t="light";if(t==="light")document.documentElement.setAttribute("data-theme","light");}catch(e){}})(); | |
| 18 | +</script> | |
| 19 | +<script defer src="/site.js"></script> | |
| 20 | +</head> | |
| 21 | +<body> | |
| 22 | + | |
| 23 | +<header class="site-header"><div class="inner"> | |
| 24 | + <a class="wordmark" href="/"><span class="glyph">❯</span><span class="g-ember">KHAELOR</span></a> | |
| 25 | + <nav> | |
| 26 | + <a href="/docs/getting-started.html">Docs</a> | |
| 27 | + <a href="/#install">Install</a> | |
| 28 | + <button id="theme-toggle" type="button" aria-label="Toggle color theme">light</button> | |
| 29 | + </nav> | |
| 30 | +</div></header> | |
| 31 | + | |
| 32 | +<main class="page"><div class="docs-layout"> | |
| 33 | + | |
| 34 | +<aside class="sidebar"> | |
| 35 | + <div class="group"><div class="group-title">Start</div> | |
| 36 | + <a href="/docs/getting-started.html">Getting started</a> | |
| 37 | + <a href="/docs/cookbook.html">Cookbook</a> | |
| 38 | + </div> | |
| 39 | + <div class="group"><div class="group-title">Using KHAELOR</div> | |
| 40 | + <a href="/docs/usage.html">The TUI</a> | |
| 41 | + <a href="/docs/commands.html">Commands & keyboard</a> | |
| 42 | + <a href="/docs/tools.html">Tools</a> | |
| 43 | + <a href="/docs/sessions.html">Sessions</a> | |
| 44 | + </div> | |
| 45 | + <div class="group"><div class="group-title">Autonomy</div> | |
| 46 | + <a href="/docs/phases.html">Phase gates</a> | |
| 47 | + <a href="/docs/verification.html">Verification</a> | |
| 48 | + <a href="/docs/worktrees.html">Parallel worktrees</a> | |
| 49 | + <a href="/docs/daemon.html">The daemon</a> | |
| 50 | + </div> | |
| 51 | + <div class="group"><div class="group-title">Intelligence</div> | |
| 52 | + <a href="/docs/repograph.html">Semantic index</a> | |
| 53 | + <a href="/docs/memory.html">Project memory</a> | |
| 54 | + <a href="/docs/context.html">Context engine</a> | |
| 55 | + <a href="/docs/fork-replay.html">Fork · replay · sdiff</a> | |
| 56 | + </div> | |
| 57 | + <div class="group"><div class="group-title">Control</div> | |
| 58 | + <a href="/docs/permissions.html">Permissions</a> | |
| 59 | + <a href="/docs/configuration.html">Configuration</a> | |
| 60 | + <a href="/docs/cli.html">CLI reference</a> | |
| 61 | + </div> | |
| 62 | + <div class="group"><div class="group-title">Internals</div> | |
| 63 | + <a href="/docs/architecture.html">Architecture</a> | |
| 64 | + <a href="/docs/events.html">The event model</a> | |
| 65 | + <a href="/docs/theming.html">Theming & terminal</a> | |
| 66 | + </div> | |
| 67 | + <div class="group"><div class="group-title">Help</div> | |
| 68 | + <a href="/docs/faq.html">FAQ & troubleshooting</a> | |
| 69 | + </div> | |
| 70 | +</aside> | |
| 71 | + | |
| 72 | +<article class="content"> | |
| 73 | + | |
| 74 | +<h1>Fork · replay · sdiff</h1> | |
| 75 | +<p class="lead">Because resume is a replay of the JSONL, three operations come almost for free — | |
| 76 | +and together they turn sessions into a comparison instrument no other CLI agent offers.</p> | |
| 77 | + | |
| 78 | +<h2 id="fork">/fork — branch a conversation<a class="anchor" href="#fork">#</a></h2> | |
| 79 | +<div class="termwrap"><div class="termbar"><span class="dot r"></span><span class="dot y"></span><span class="dot g"></span><span class="title">/fork — checkpoint picker</span></div> | |
| 80 | +<pre class="term" data-no-copy><code> <span class="t-b">fork · pick a checkpoint</span> | |
| 81 | + <span class="sel"> ❯ now add tests seq 41 · user-turn </span> | |
| 82 | + ✓ design approved <span class="t-dim">seq 28 · design-approved</span> | |
| 83 | + ⊟ context checkpoint <span class="t-dim">seq 19 · compaction</span> | |
| 84 | + ❯ fix the auth bug <span class="t-dim">seq 2 · user-turn</span></code></pre></div> | |
| 85 | +<p>The JSONL prefix up to the chosen event is copied into a fresh session (envelope session ids are | |
| 86 | +rewritten; seq, ids, and payloads are byte-preserved) and a sidecar records the lineage:</p> | |
| 87 | +<pre><code>.khaelor/sessions/<project>/ | |
| 88 | + 01J8K2….jsonl | |
| 89 | + 01J8Q7….jsonl # the fork | |
| 90 | + 01J8Q7….meta.json # { "parent": "01J8K2…", "forkPoint": 41 }</code></pre> | |
| 91 | +<p>KHAELOR opens the fork immediately. The original is untouched — explore the risky approach, | |
| 92 | +keep the safe thread.</p> | |
| 93 | + | |
| 94 | +<h2 id="replay">/replay — same questions, different run<a class="anchor" href="#replay">#</a></h2> | |
| 95 | +<p><code>/replay <sessionId></code> extracts the <em>user turns</em> of a finished session and | |
| 96 | +re-runs them sequentially in a fresh session. Two properties matter:</p> | |
| 97 | +<ul> | |
| 98 | + <li><strong>Tool calls re-execute for real</strong> — this is a genuine second run, not a tape | |
| 99 | + playback; that is what makes the comparison meaningful.</li> | |
| 100 | + <li><strong>Sandboxed by construction</strong>: the replay runs inside a throwaway git worktree | |
| 101 | + that is deleted afterwards — zero side effects on your working copy.</li> | |
| 102 | +</ul> | |
| 103 | +<p>Switch models first (<code>/model</code>) to answer “what would haiku have done with the exact | |
| 104 | +same requests?”</p> | |
| 105 | + | |
| 106 | +<h2 id="sdiff">/sdiff — diff the runs<a class="anchor" href="#sdiff">#</a></h2> | |
| 107 | +<div class="termwrap"><div class="termbar"><span class="dot r"></span><span class="dot y"></span><span class="dot g"></span><span class="title">/sdiff</span></div> | |
| 108 | +<pre class="term" data-no-copy><code> <span class="t-b">sdiff</span> | |
| 109 | + <span class="t-dim">01J8K2… (sonnet)</span> <span class="t-dim">01J8K9… (haiku)</span> | |
| 110 | + agent turns 12 17 | |
| 111 | + tool calls 34 61 | |
| 112 | + files modified 2 3 | |
| 113 | + tokens (in/out) 145k / 12k 210k / 19k | |
| 114 | + cache reads 118k 96k | |
| 115 | + verify failures <span class="t-ok">0</span> <span class="t-err">2</span> | |
| 116 | + outcome <span class="t-ok">completed</span> <span class="t-ok">completed</span> | |
| 117 | + <span class="t-dim">files only in B: src/c.ts</span> | |
| 118 | + <span class="t-dim">files in both: src/a.ts, src/b.ts</span></code></pre></div> | |
| 119 | +<p>Every number is folded from the two durable logs — real usage events, real diff attribution. | |
| 120 | +Combined with <code>/replay</code>, this is the cheapest honest model/prompt comparison you can | |
| 121 | +run: <em>run it twice, diff the runs</em>.</p> | |
| 122 | + | |
| 123 | +<h2 id="lineage">Lineage is queryable<a class="anchor" href="#lineage">#</a></h2> | |
| 124 | +<p>Forks record <code>parent</code> + <code>forkPoint</code>; replays record <code>replayOf</code>; | |
| 125 | +subtask children record their orchestrator. Your session directory is a family tree, not a pile.</p> | |
| 126 | + | |
| 127 | +<div class="pager"> | |
| 128 | + <div><span class="label">Previous</span><a href="/docs/context.html">← Context engine</a></div> | |
| 129 | + <div class="next"><span class="label">Next</span><a href="/docs/permissions.html">Permissions →</a></div> | |
| 130 | +</div> | |
| 131 | + | |
| 132 | +</article> | |
| 133 | +</div></main> | |
| 134 | + | |
| 135 | +<footer class="site-footer"><div class="inner"> | |
| 136 | + <span>KHAELOR — Simon-Pierre Boucher · <a href="mailto:contact@spboucher.ai">contact@spboucher.ai</a></span> | |
| 137 | + <span>Anthropic-powered · terminal-native by design</span> | |
| 138 | +</div></footer> | |
| 139 | + | |
| 140 | +</body> | |
| 141 | +</html> | |
modified
website/public/docs/getting-started.html
+16 −1
@@ -34,6 +34,7 @@ Contact: contact@spboucher.ai | ||
| 34 | 34 | <aside class="sidebar"> |
| 35 | 35 | <div class="group"><div class="group-title">Start</div> |
| 36 | 36 | <a href="/docs/getting-started.html">Getting started</a> |
| 37 | + <a href="/docs/cookbook.html">Cookbook</a> | |
| 37 | 38 | </div> |
| 38 | 39 | <div class="group"><div class="group-title">Using KHAELOR</div> |
| 39 | 40 | <a href="/docs/usage.html">The TUI</a> |
@@ -42,12 +43,26 @@ Contact: contact@spboucher.ai | ||
| 42 | 43 | <a href="/docs/sessions.html">Sessions</a> |
| 43 | 44 | </div> |
| 44 | 45 | <div class="group"><div class="group-title">Autonomy</div> |
| 45 | − <a href="/docs/phases.html">Phase gates & verify</a> | |
| 46 | + <a href="/docs/phases.html">Phase gates</a> | |
| 47 | + <a href="/docs/verification.html">Verification</a> | |
| 48 | + <a href="/docs/worktrees.html">Parallel worktrees</a> | |
| 46 | 49 | <a href="/docs/daemon.html">The daemon</a> |
| 47 | 50 | </div> |
| 51 | + <div class="group"><div class="group-title">Intelligence</div> | |
| 52 | + <a href="/docs/repograph.html">Semantic index</a> | |
| 53 | + <a href="/docs/memory.html">Project memory</a> | |
| 54 | + <a href="/docs/context.html">Context engine</a> | |
| 55 | + <a href="/docs/fork-replay.html">Fork · replay · sdiff</a> | |
| 56 | + </div> | |
| 48 | 57 | <div class="group"><div class="group-title">Control</div> |
| 49 | 58 | <a href="/docs/permissions.html">Permissions</a> |
| 50 | 59 | <a href="/docs/configuration.html">Configuration</a> |
| 60 | + <a href="/docs/cli.html">CLI reference</a> | |
| 61 | + </div> | |
| 62 | + <div class="group"><div class="group-title">Internals</div> | |
| 63 | + <a href="/docs/architecture.html">Architecture</a> | |
| 64 | + <a href="/docs/events.html">The event model</a> | |
| 65 | + <a href="/docs/theming.html">Theming & terminal</a> | |
| 51 | 66 | </div> |
| 52 | 67 | <div class="group"><div class="group-title">Help</div> |
| 53 | 68 | <a href="/docs/faq.html">FAQ & troubleshooting</a> |
added
website/public/docs/memory.html
+139 −0
@@ -0,0 +1,139 @@ | ||
| 1 | +<!doctype html> | |
| 2 | +<!-- | |
| 3 | +KHAELOR | |
| 4 | +File: website/public/docs/memory.html | |
| 5 | +Description: Docs — Auto-maintained project memory with event-anchored provenance: the remember tool, MEMORY.md format, hygiene. | |
| 6 | +Author: Simon-Pierre Boucher | |
| 7 | +Contact: contact@spboucher.ai | |
| 8 | +--> | |
| 9 | +<html lang="en"> | |
| 10 | +<head> | |
| 11 | +<meta charset="utf-8"> | |
| 12 | +<meta name="viewport" content="width=device-width, initial-scale=1"> | |
| 13 | +<title>Project memory — KHAELOR docs</title> | |
| 14 | +<meta name="description" content="Auto-maintained project memory with event-anchored provenance: the remember tool, MEMORY.md format, hygiene."> | |
| 15 | +<link rel="stylesheet" href="/styles.css"> | |
| 16 | +<script> | |
| 17 | +(function(){try{var t=localStorage.getItem("khaelor-theme");if(!t&&window.matchMedia&&window.matchMedia("(prefers-color-scheme: light)").matches)t="light";if(t==="light")document.documentElement.setAttribute("data-theme","light");}catch(e){}})(); | |
| 18 | +</script> | |
| 19 | +<script defer src="/site.js"></script> | |
| 20 | +</head> | |
| 21 | +<body> | |
| 22 | + | |
| 23 | +<header class="site-header"><div class="inner"> | |
| 24 | + <a class="wordmark" href="/"><span class="glyph">❯</span><span class="g-ember">KHAELOR</span></a> | |
| 25 | + <nav> | |
| 26 | + <a href="/docs/getting-started.html">Docs</a> | |
| 27 | + <a href="/#install">Install</a> | |
| 28 | + <button id="theme-toggle" type="button" aria-label="Toggle color theme">light</button> | |
| 29 | + </nav> | |
| 30 | +</div></header> | |
| 31 | + | |
| 32 | +<main class="page"><div class="docs-layout"> | |
| 33 | + | |
| 34 | +<aside class="sidebar"> | |
| 35 | + <div class="group"><div class="group-title">Start</div> | |
| 36 | + <a href="/docs/getting-started.html">Getting started</a> | |
| 37 | + <a href="/docs/cookbook.html">Cookbook</a> | |
| 38 | + </div> | |
| 39 | + <div class="group"><div class="group-title">Using KHAELOR</div> | |
| 40 | + <a href="/docs/usage.html">The TUI</a> | |
| 41 | + <a href="/docs/commands.html">Commands & keyboard</a> | |
| 42 | + <a href="/docs/tools.html">Tools</a> | |
| 43 | + <a href="/docs/sessions.html">Sessions</a> | |
| 44 | + </div> | |
| 45 | + <div class="group"><div class="group-title">Autonomy</div> | |
| 46 | + <a href="/docs/phases.html">Phase gates</a> | |
| 47 | + <a href="/docs/verification.html">Verification</a> | |
| 48 | + <a href="/docs/worktrees.html">Parallel worktrees</a> | |
| 49 | + <a href="/docs/daemon.html">The daemon</a> | |
| 50 | + </div> | |
| 51 | + <div class="group"><div class="group-title">Intelligence</div> | |
| 52 | + <a href="/docs/repograph.html">Semantic index</a> | |
| 53 | + <a href="/docs/memory.html">Project memory</a> | |
| 54 | + <a href="/docs/context.html">Context engine</a> | |
| 55 | + <a href="/docs/fork-replay.html">Fork · replay · sdiff</a> | |
| 56 | + </div> | |
| 57 | + <div class="group"><div class="group-title">Control</div> | |
| 58 | + <a href="/docs/permissions.html">Permissions</a> | |
| 59 | + <a href="/docs/configuration.html">Configuration</a> | |
| 60 | + <a href="/docs/cli.html">CLI reference</a> | |
| 61 | + </div> | |
| 62 | + <div class="group"><div class="group-title">Internals</div> | |
| 63 | + <a href="/docs/architecture.html">Architecture</a> | |
| 64 | + <a href="/docs/events.html">The event model</a> | |
| 65 | + <a href="/docs/theming.html">Theming & terminal</a> | |
| 66 | + </div> | |
| 67 | + <div class="group"><div class="group-title">Help</div> | |
| 68 | + <a href="/docs/faq.html">FAQ & troubleshooting</a> | |
| 69 | + </div> | |
| 70 | +</aside> | |
| 71 | + | |
| 72 | +<article class="content"> | |
| 73 | + | |
| 74 | +<h1>Project memory</h1> | |
| 75 | +<p class="lead">KHAELOR maintains its own memory of your project — and unlike free-form notes, | |
| 76 | +every entry is anchored to the exact session and event that produced it.</p> | |
| 77 | + | |
| 78 | +<h2 id="cycle">The life cycle<a class="anchor" href="#cycle">#</a></h2> | |
| 79 | +<ol> | |
| 80 | + <li><strong>Write</strong> — when the agent discovers a durable fact (a convention, a build | |
| 81 | + command, a pitfall) it calls the lightweight <code>remember</code> tool. Auto-approved: writing | |
| 82 | + to <code>.khaelor/MEMORY.md</code> is allowed in every phase, because remembering IS understanding.</li> | |
| 83 | + <li><strong>Read</strong> — the file is injected into the instruction tier at every session | |
| 84 | + start, alongside <code>KHAELOR.md</code>/<code>CLAUDE.md</code>.</li> | |
| 85 | + <li><strong>Audit</strong> — <code>/memory</code> lists entries with their provenance.</li> | |
| 86 | + <li><strong>Hygiene</strong> — low-confidence entries not re-confirmed surface as purge | |
| 87 | + candidates at the next <code>/compact</code>.</li> | |
| 88 | +</ol> | |
| 89 | + | |
| 90 | +<h2 id="format">The format<a class="anchor" href="#format">#</a></h2> | |
| 91 | +<pre><code># Project memory | |
| 92 | + | |
| 93 | +## Conventions | |
| 94 | +- Errors flow through Result<T, KError>; never throw in src/core. | |
| 95 | + <!-- khaelor: session=01J8K2… tool=toolu_01… confidence=high date=2026-08-10 --> | |
| 96 | + | |
| 97 | +## Commands | |
| 98 | +- Full build: npm run check (includes the mandatory header check). | |
| 99 | + <!-- khaelor: session=01J8K2… tool=toolu_02… confidence=high date=2026-08-10 --> | |
| 100 | + | |
| 101 | +## Pitfalls | |
| 102 | +- src/tui/render.ts: never touch the buffer outside the 16ms tick — tearing. | |
| 103 | + <!-- khaelor: session=01J8F1… tool=toolu_09… confidence=medium date=2026-08-09 --></code></pre> | |
| 104 | +<p>Readable, hand-editable, git-versionable. The provenance comment is the differentiator: the | |
| 105 | +<code>tool</code> id links to a durable <code>tool.requested</code> event in the referenced | |
| 106 | +session's JSONL — you can open the log and see exactly what the agent had just observed when it | |
| 107 | +decided to remember.</p> | |
| 108 | + | |
| 109 | +<h2 id="tool">The remember tool<a class="anchor" href="#tool">#</a></h2> | |
| 110 | +<table> | |
| 111 | + <tr><th>Param</th><th>Meaning</th></tr> | |
| 112 | + <tr><td><code>fact</code></td><td class="wrap">One or two sentences. Durable facts only — never transient task state.</td></tr> | |
| 113 | + <tr><td><code>section</code></td><td class="wrap">conventions · commands · pitfalls · architecture · notes.</td></tr> | |
| 114 | + <tr><td><code>confidence</code></td><td class="wrap">high · medium (default) · low. Low-confidence entries are purge candidates.</td></tr> | |
| 115 | +</table> | |
| 116 | +<p>Each write also emits a durable <code>memory.written</code> event in the current session — | |
| 117 | +memory changes are themselves part of the auditable history.</p> | |
| 118 | + | |
| 119 | +<h2 id="vs">Versus free-form memory files<a class="anchor" href="#vs">#</a></h2> | |
| 120 | +<p>Plain markdown memories rot: you find a claim and cannot tell when it was true or what justified | |
| 121 | +it. KHAELOR's memories always answer three questions — <em>who wrote this</em> (which session), | |
| 122 | +<em>based on what</em> (which event), <em>how sure was it</em> (confidence) — and the hygiene loop | |
| 123 | +retires what stops being confirmed.</p> | |
| 124 | + | |
| 125 | +<div class="pager"> | |
| 126 | + <div><span class="label">Previous</span><a href="/docs/repograph.html">← Semantic index</a></div> | |
| 127 | + <div class="next"><span class="label">Next</span><a href="/docs/context.html">Context engine →</a></div> | |
| 128 | +</div> | |
| 129 | + | |
| 130 | +</article> | |
| 131 | +</div></main> | |
| 132 | + | |
| 133 | +<footer class="site-footer"><div class="inner"> | |
| 134 | + <span>KHAELOR — Simon-Pierre Boucher · <a href="mailto:contact@spboucher.ai">contact@spboucher.ai</a></span> | |
| 135 | + <span>Anthropic-powered · terminal-native by design</span> | |
| 136 | +</div></footer> | |
| 137 | + | |
| 138 | +</body> | |
| 139 | +</html> | |
modified
website/public/docs/permissions.html
+16 −1
@@ -34,6 +34,7 @@ Contact: contact@spboucher.ai | ||
| 34 | 34 | <aside class="sidebar"> |
| 35 | 35 | <div class="group"><div class="group-title">Start</div> |
| 36 | 36 | <a href="/docs/getting-started.html">Getting started</a> |
| 37 | + <a href="/docs/cookbook.html">Cookbook</a> | |
| 37 | 38 | </div> |
| 38 | 39 | <div class="group"><div class="group-title">Using KHAELOR</div> |
| 39 | 40 | <a href="/docs/usage.html">The TUI</a> |
@@ -42,12 +43,26 @@ Contact: contact@spboucher.ai | ||
| 42 | 43 | <a href="/docs/sessions.html">Sessions</a> |
| 43 | 44 | </div> |
| 44 | 45 | <div class="group"><div class="group-title">Autonomy</div> |
| 45 | − <a href="/docs/phases.html">Phase gates & verify</a> | |
| 46 | + <a href="/docs/phases.html">Phase gates</a> | |
| 47 | + <a href="/docs/verification.html">Verification</a> | |
| 48 | + <a href="/docs/worktrees.html">Parallel worktrees</a> | |
| 46 | 49 | <a href="/docs/daemon.html">The daemon</a> |
| 47 | 50 | </div> |
| 51 | + <div class="group"><div class="group-title">Intelligence</div> | |
| 52 | + <a href="/docs/repograph.html">Semantic index</a> | |
| 53 | + <a href="/docs/memory.html">Project memory</a> | |
| 54 | + <a href="/docs/context.html">Context engine</a> | |
| 55 | + <a href="/docs/fork-replay.html">Fork · replay · sdiff</a> | |
| 56 | + </div> | |
| 48 | 57 | <div class="group"><div class="group-title">Control</div> |
| 49 | 58 | <a href="/docs/permissions.html">Permissions</a> |
| 50 | 59 | <a href="/docs/configuration.html">Configuration</a> |
| 60 | + <a href="/docs/cli.html">CLI reference</a> | |
| 61 | + </div> | |
| 62 | + <div class="group"><div class="group-title">Internals</div> | |
| 63 | + <a href="/docs/architecture.html">Architecture</a> | |
| 64 | + <a href="/docs/events.html">The event model</a> | |
| 65 | + <a href="/docs/theming.html">Theming & terminal</a> | |
| 51 | 66 | </div> |
| 52 | 67 | <div class="group"><div class="group-title">Help</div> |
| 53 | 68 | <a href="/docs/faq.html">FAQ & troubleshooting</a> |
modified
website/public/docs/phases.html
+16 −1
@@ -34,6 +34,7 @@ Contact: contact@spboucher.ai | ||
| 34 | 34 | <aside class="sidebar"> |
| 35 | 35 | <div class="group"><div class="group-title">Start</div> |
| 36 | 36 | <a href="/docs/getting-started.html">Getting started</a> |
| 37 | + <a href="/docs/cookbook.html">Cookbook</a> | |
| 37 | 38 | </div> |
| 38 | 39 | <div class="group"><div class="group-title">Using KHAELOR</div> |
| 39 | 40 | <a href="/docs/usage.html">The TUI</a> |
@@ -42,12 +43,26 @@ Contact: contact@spboucher.ai | ||
| 42 | 43 | <a href="/docs/sessions.html">Sessions</a> |
| 43 | 44 | </div> |
| 44 | 45 | <div class="group"><div class="group-title">Autonomy</div> |
| 45 | − <a href="/docs/phases.html">Phase gates & verify</a> | |
| 46 | + <a href="/docs/phases.html">Phase gates</a> | |
| 47 | + <a href="/docs/verification.html">Verification</a> | |
| 48 | + <a href="/docs/worktrees.html">Parallel worktrees</a> | |
| 46 | 49 | <a href="/docs/daemon.html">The daemon</a> |
| 47 | 50 | </div> |
| 51 | + <div class="group"><div class="group-title">Intelligence</div> | |
| 52 | + <a href="/docs/repograph.html">Semantic index</a> | |
| 53 | + <a href="/docs/memory.html">Project memory</a> | |
| 54 | + <a href="/docs/context.html">Context engine</a> | |
| 55 | + <a href="/docs/fork-replay.html">Fork · replay · sdiff</a> | |
| 56 | + </div> | |
| 48 | 57 | <div class="group"><div class="group-title">Control</div> |
| 49 | 58 | <a href="/docs/permissions.html">Permissions</a> |
| 50 | 59 | <a href="/docs/configuration.html">Configuration</a> |
| 60 | + <a href="/docs/cli.html">CLI reference</a> | |
| 61 | + </div> | |
| 62 | + <div class="group"><div class="group-title">Internals</div> | |
| 63 | + <a href="/docs/architecture.html">Architecture</a> | |
| 64 | + <a href="/docs/events.html">The event model</a> | |
| 65 | + <a href="/docs/theming.html">Theming & terminal</a> | |
| 51 | 66 | </div> |
| 52 | 67 | <div class="group"><div class="group-title">Help</div> |
| 53 | 68 | <a href="/docs/faq.html">FAQ & troubleshooting</a> |
added
website/public/docs/repograph.html
+133 −0
@@ -0,0 +1,133 @@ | ||
| 1 | +<!doctype html> | |
| 2 | +<!-- | |
| 3 | +KHAELOR | |
| 4 | +File: website/public/docs/repograph.html | |
| 5 | +Description: Docs — The RepoGraph: symbols and refs tools, incremental indexing, file skeletons, and the token economics. | |
| 6 | +Author: Simon-Pierre Boucher | |
| 7 | +Contact: contact@spboucher.ai | |
| 8 | +--> | |
| 9 | +<html lang="en"> | |
| 10 | +<head> | |
| 11 | +<meta charset="utf-8"> | |
| 12 | +<meta name="viewport" content="width=device-width, initial-scale=1"> | |
| 13 | +<title>Semantic index — KHAELOR docs</title> | |
| 14 | +<meta name="description" content="The RepoGraph: symbols and refs tools, incremental indexing, file skeletons, and the token economics."> | |
| 15 | +<link rel="stylesheet" href="/styles.css"> | |
| 16 | +<script> | |
| 17 | +(function(){try{var t=localStorage.getItem("khaelor-theme");if(!t&&window.matchMedia&&window.matchMedia("(prefers-color-scheme: light)").matches)t="light";if(t==="light")document.documentElement.setAttribute("data-theme","light");}catch(e){}})(); | |
| 18 | +</script> | |
| 19 | +<script defer src="/site.js"></script> | |
| 20 | +</head> | |
| 21 | +<body> | |
| 22 | + | |
| 23 | +<header class="site-header"><div class="inner"> | |
| 24 | + <a class="wordmark" href="/"><span class="glyph">❯</span><span class="g-ember">KHAELOR</span></a> | |
| 25 | + <nav> | |
| 26 | + <a href="/docs/getting-started.html">Docs</a> | |
| 27 | + <a href="/#install">Install</a> | |
| 28 | + <button id="theme-toggle" type="button" aria-label="Toggle color theme">light</button> | |
| 29 | + </nav> | |
| 30 | +</div></header> | |
| 31 | + | |
| 32 | +<main class="page"><div class="docs-layout"> | |
| 33 | + | |
| 34 | +<aside class="sidebar"> | |
| 35 | + <div class="group"><div class="group-title">Start</div> | |
| 36 | + <a href="/docs/getting-started.html">Getting started</a> | |
| 37 | + <a href="/docs/cookbook.html">Cookbook</a> | |
| 38 | + </div> | |
| 39 | + <div class="group"><div class="group-title">Using KHAELOR</div> | |
| 40 | + <a href="/docs/usage.html">The TUI</a> | |
| 41 | + <a href="/docs/commands.html">Commands & keyboard</a> | |
| 42 | + <a href="/docs/tools.html">Tools</a> | |
| 43 | + <a href="/docs/sessions.html">Sessions</a> | |
| 44 | + </div> | |
| 45 | + <div class="group"><div class="group-title">Autonomy</div> | |
| 46 | + <a href="/docs/phases.html">Phase gates</a> | |
| 47 | + <a href="/docs/verification.html">Verification</a> | |
| 48 | + <a href="/docs/worktrees.html">Parallel worktrees</a> | |
| 49 | + <a href="/docs/daemon.html">The daemon</a> | |
| 50 | + </div> | |
| 51 | + <div class="group"><div class="group-title">Intelligence</div> | |
| 52 | + <a href="/docs/repograph.html">Semantic index</a> | |
| 53 | + <a href="/docs/memory.html">Project memory</a> | |
| 54 | + <a href="/docs/context.html">Context engine</a> | |
| 55 | + <a href="/docs/fork-replay.html">Fork · replay · sdiff</a> | |
| 56 | + </div> | |
| 57 | + <div class="group"><div class="group-title">Control</div> | |
| 58 | + <a href="/docs/permissions.html">Permissions</a> | |
| 59 | + <a href="/docs/configuration.html">Configuration</a> | |
| 60 | + <a href="/docs/cli.html">CLI reference</a> | |
| 61 | + </div> | |
| 62 | + <div class="group"><div class="group-title">Internals</div> | |
| 63 | + <a href="/docs/architecture.html">Architecture</a> | |
| 64 | + <a href="/docs/events.html">The event model</a> | |
| 65 | + <a href="/docs/theming.html">Theming & terminal</a> | |
| 66 | + </div> | |
| 67 | + <div class="group"><div class="group-title">Help</div> | |
| 68 | + <a href="/docs/faq.html">FAQ & troubleshooting</a> | |
| 69 | + </div> | |
| 70 | +</aside> | |
| 71 | + | |
| 72 | +<article class="content"> | |
| 73 | + | |
| 74 | +<h1>The semantic index — RepoGraph</h1> | |
| 75 | +<p class="lead">KHAELOR understands your repository without stuffing it into context: an incremental | |
| 76 | +symbol index answers “where is it defined?” and “who uses it?” in milliseconds.</p> | |
| 77 | + | |
| 78 | +<h2 id="tools">Two tools replace most exploratory greps<a class="anchor" href="#tools">#</a></h2> | |
| 79 | +<div class="termwrap"><div class="termbar"><span class="dot r"></span><span class="dot y"></span><span class="dot g"></span><span class="title">symbols</span></div> | |
| 80 | +<pre class="term" data-no-copy><code> <span class="t-dim">├─</span> symbols <span class="t-teal">"class:*Controller"</span> <span class="t-dim">· 2 hits · 9ms</span> | |
| 81 | + src/http/auth.ts:24 <span class="t-dim">[class]</span> export class AuthController { | |
| 82 | + <span class="t-dim">Login/logout endpoints.</span> | |
| 83 | + src/http/admin.ts:11 <span class="t-dim">[class]</span> export class AdminController {</code></pre></div><div class="termwrap"><div class="termbar"><span class="dot r"></span><span class="dot y"></span><span class="dot g"></span><span class="title">refs — blast radius before an edit</span></div> | |
| 84 | +<pre class="term" data-no-copy><code> <span class="t-dim">├─</span> refs <span class="t-teal">handleAuth · callers</span> <span class="t-dim">· 14 sites</span> | |
| 85 | + src/http/auth.ts:31 await handleAuth(token) | |
| 86 | + src/http/middleware.ts:88 if (!(await handleAuth(t))) return deny() | |
| 87 | + src/cli/login.ts:52 const ok = await handleAuth(input)</code></code></pre></div> | |
| 88 | +<table> | |
| 89 | + <tr><th>Tool</th><th>Input</th><th>Returns</th></tr> | |
| 90 | + <tr><td><code>symbols</code></td><td class="wrap"><code>query</code> (wildcards: <code>*Controller</code>, shorthand <code>class:*</code>), <code>kind</code> (function · class · type · export · variable · method), <code>scope</code> (glob).</td><td class="wrap">file:line, kind, signature, doc comment.</td></tr> | |
| 91 | + <tr><td><code>refs</code></td><td class="wrap"><code>symbol</code>, <code>direction</code> = callers · callees · importers.</td><td class="wrap">Usage sites with a line of context each.</td></tr> | |
| 92 | +</table> | |
| 93 | + | |
| 94 | +<h2 id="indexing">Indexing<a class="anchor" href="#indexing">#</a></h2> | |
| 95 | +<ul> | |
| 96 | + <li><strong>Incremental by mtime</strong>: only changed files re-extract; queries lazily refresh | |
| 97 | + (debounced ~5 s), so results are never stale for long and startup stays instant.</li> | |
| 98 | + <li><strong>Warm-up in the background</strong> at engine assembly — the first tool call does not pay for it.</li> | |
| 99 | + <li>Languages today: TypeScript/JavaScript and Python, via a dependency-free heuristic extractor. | |
| 100 | + tree-sitter grammars are the documented upgrade path — the service interface will not change.</li> | |
| 101 | + <li><code>node_modules</code>, <code>.git</code>, <code>dist</code>, <code>references</code> are always excluded.</li> | |
| 102 | +</ul> | |
| 103 | + | |
| 104 | +<h2 id="skeletons">Skeletons — the token economics<a class="anchor" href="#skeletons">#</a></h2> | |
| 105 | +<p>The index can render any file as a <em>skeleton</em>: its signatures and doc comments with line | |
| 106 | +anchors — typically 5–15% of the tokens of the full file:</p> | |
| 107 | +<pre><code>src/kernel/dispatch.ts — skeleton (9 symbols; re-read the file if you need bodies) | |
| 108 | + 18 | export interface DispatchOptions { // Kernel dispatch configuration. | |
| 109 | + 42 | export function dispatch(call: ToolCall): Result<Obs> // The single entrypoint. | |
| 110 | + 97 | function verifyGrant(cap: Capability): boolean</code></pre> | |
| 111 | +<p>Exploration that used to cost a 3,000-token file read costs a 200-token skeleton. The agent is | |
| 112 | +prompted to reach for <code>symbols</code>/<code>refs</code> before <code>grep</code>.</p> | |
| 113 | + | |
| 114 | +<h2 id="honest">What it will not pretend<a class="anchor" href="#honest">#</a></h2> | |
| 115 | +<p><code>callees</code> is a heuristic (identifiers called within the defining region, resolved | |
| 116 | +against known symbols) — good for orientation, not a type-checked call graph. When precision | |
| 117 | +matters, KHAELOR confirms with <code>read</code>. Dynamic dispatch and reflection are invisible to | |
| 118 | +any static index; the tools say so instead of guessing.</p> | |
| 119 | + | |
| 120 | +<div class="pager"> | |
| 121 | + <div class="next"><span class="label">Next</span><a href="/docs/memory.html">Project memory →</a></div> | |
| 122 | +</div> | |
| 123 | + | |
| 124 | +</article> | |
| 125 | +</div></main> | |
| 126 | + | |
| 127 | +<footer class="site-footer"><div class="inner"> | |
| 128 | + <span>KHAELOR — Simon-Pierre Boucher · <a href="mailto:contact@spboucher.ai">contact@spboucher.ai</a></span> | |
| 129 | + <span>Anthropic-powered · terminal-native by design</span> | |
| 130 | +</div></footer> | |
| 131 | + | |
| 132 | +</body> | |
| 133 | +</html> | |
modified
website/public/docs/sessions.html
+16 −1
@@ -34,6 +34,7 @@ Contact: contact@spboucher.ai | ||
| 34 | 34 | <aside class="sidebar"> |
| 35 | 35 | <div class="group"><div class="group-title">Start</div> |
| 36 | 36 | <a href="/docs/getting-started.html">Getting started</a> |
| 37 | + <a href="/docs/cookbook.html">Cookbook</a> | |
| 37 | 38 | </div> |
| 38 | 39 | <div class="group"><div class="group-title">Using KHAELOR</div> |
| 39 | 40 | <a href="/docs/usage.html">The TUI</a> |
@@ -42,12 +43,26 @@ Contact: contact@spboucher.ai | ||
| 42 | 43 | <a href="/docs/sessions.html">Sessions</a> |
| 43 | 44 | </div> |
| 44 | 45 | <div class="group"><div class="group-title">Autonomy</div> |
| 45 | − <a href="/docs/phases.html">Phase gates & verify</a> | |
| 46 | + <a href="/docs/phases.html">Phase gates</a> | |
| 47 | + <a href="/docs/verification.html">Verification</a> | |
| 48 | + <a href="/docs/worktrees.html">Parallel worktrees</a> | |
| 46 | 49 | <a href="/docs/daemon.html">The daemon</a> |
| 47 | 50 | </div> |
| 51 | + <div class="group"><div class="group-title">Intelligence</div> | |
| 52 | + <a href="/docs/repograph.html">Semantic index</a> | |
| 53 | + <a href="/docs/memory.html">Project memory</a> | |
| 54 | + <a href="/docs/context.html">Context engine</a> | |
| 55 | + <a href="/docs/fork-replay.html">Fork · replay · sdiff</a> | |
| 56 | + </div> | |
| 48 | 57 | <div class="group"><div class="group-title">Control</div> |
| 49 | 58 | <a href="/docs/permissions.html">Permissions</a> |
| 50 | 59 | <a href="/docs/configuration.html">Configuration</a> |
| 60 | + <a href="/docs/cli.html">CLI reference</a> | |
| 61 | + </div> | |
| 62 | + <div class="group"><div class="group-title">Internals</div> | |
| 63 | + <a href="/docs/architecture.html">Architecture</a> | |
| 64 | + <a href="/docs/events.html">The event model</a> | |
| 65 | + <a href="/docs/theming.html">Theming & terminal</a> | |
| 51 | 66 | </div> |
| 52 | 67 | <div class="group"><div class="group-title">Help</div> |
| 53 | 68 | <a href="/docs/faq.html">FAQ & troubleshooting</a> |
added
website/public/docs/theming.html
+149 −0
@@ -0,0 +1,149 @@ | ||
| 1 | +<!doctype html> | |
| 2 | +<!-- | |
| 3 | +KHAELOR | |
| 4 | +File: website/public/docs/theming.html | |
| 5 | +Description: Docs — The khaelis theme, OKLCH gradients, the capability ladder, the motion doctrine, and --doctor-tui. | |
| 6 | +Author: Simon-Pierre Boucher | |
| 7 | +Contact: contact@spboucher.ai | |
| 8 | +--> | |
| 9 | +<html lang="en"> | |
| 10 | +<head> | |
| 11 | +<meta charset="utf-8"> | |
| 12 | +<meta name="viewport" content="width=device-width, initial-scale=1"> | |
| 13 | +<title>Theming & terminal — KHAELOR docs</title> | |
| 14 | +<meta name="description" content="The khaelis theme, OKLCH gradients, the capability ladder, the motion doctrine, and --doctor-tui."> | |
| 15 | +<link rel="stylesheet" href="/styles.css"> | |
| 16 | +<script> | |
| 17 | +(function(){try{var t=localStorage.getItem("khaelor-theme");if(!t&&window.matchMedia&&window.matchMedia("(prefers-color-scheme: light)").matches)t="light";if(t==="light")document.documentElement.setAttribute("data-theme","light");}catch(e){}})(); | |
| 18 | +</script> | |
| 19 | +<script defer src="/site.js"></script> | |
| 20 | +</head> | |
| 21 | +<body> | |
| 22 | + | |
| 23 | +<header class="site-header"><div class="inner"> | |
| 24 | + <a class="wordmark" href="/"><span class="glyph">❯</span><span class="g-ember">KHAELOR</span></a> | |
| 25 | + <nav> | |
| 26 | + <a href="/docs/getting-started.html">Docs</a> | |
| 27 | + <a href="/#install">Install</a> | |
| 28 | + <button id="theme-toggle" type="button" aria-label="Toggle color theme">light</button> | |
| 29 | + </nav> | |
| 30 | +</div></header> | |
| 31 | + | |
| 32 | +<main class="page"><div class="docs-layout"> | |
| 33 | + | |
| 34 | +<aside class="sidebar"> | |
| 35 | + <div class="group"><div class="group-title">Start</div> | |
| 36 | + <a href="/docs/getting-started.html">Getting started</a> | |
| 37 | + <a href="/docs/cookbook.html">Cookbook</a> | |
| 38 | + </div> | |
| 39 | + <div class="group"><div class="group-title">Using KHAELOR</div> | |
| 40 | + <a href="/docs/usage.html">The TUI</a> | |
| 41 | + <a href="/docs/commands.html">Commands & keyboard</a> | |
| 42 | + <a href="/docs/tools.html">Tools</a> | |
| 43 | + <a href="/docs/sessions.html">Sessions</a> | |
| 44 | + </div> | |
| 45 | + <div class="group"><div class="group-title">Autonomy</div> | |
| 46 | + <a href="/docs/phases.html">Phase gates</a> | |
| 47 | + <a href="/docs/verification.html">Verification</a> | |
| 48 | + <a href="/docs/worktrees.html">Parallel worktrees</a> | |
| 49 | + <a href="/docs/daemon.html">The daemon</a> | |
| 50 | + </div> | |
| 51 | + <div class="group"><div class="group-title">Intelligence</div> | |
| 52 | + <a href="/docs/repograph.html">Semantic index</a> | |
| 53 | + <a href="/docs/memory.html">Project memory</a> | |
| 54 | + <a href="/docs/context.html">Context engine</a> | |
| 55 | + <a href="/docs/fork-replay.html">Fork · replay · sdiff</a> | |
| 56 | + </div> | |
| 57 | + <div class="group"><div class="group-title">Control</div> | |
| 58 | + <a href="/docs/permissions.html">Permissions</a> | |
| 59 | + <a href="/docs/configuration.html">Configuration</a> | |
| 60 | + <a href="/docs/cli.html">CLI reference</a> | |
| 61 | + </div> | |
| 62 | + <div class="group"><div class="group-title">Internals</div> | |
| 63 | + <a href="/docs/architecture.html">Architecture</a> | |
| 64 | + <a href="/docs/events.html">The event model</a> | |
| 65 | + <a href="/docs/theming.html">Theming & terminal</a> | |
| 66 | + </div> | |
| 67 | + <div class="group"><div class="group-title">Help</div> | |
| 68 | + <a href="/docs/faq.html">FAQ & troubleshooting</a> | |
| 69 | + </div> | |
| 70 | +</aside> | |
| 71 | + | |
| 72 | +<article class="content"> | |
| 73 | + | |
| 74 | +<h1>Theming & the terminal</h1> | |
| 75 | +<p class="lead">KHAELOR's identity is <strong>khaelis</strong>: obsidian and magma. A warm ember | |
| 76 | +that flows through the phase ribbon, the prompt, the panels — not another violet-cyan CLI theme.</p> | |
| 77 | + | |
| 78 | +<h2 id="palette">The khaelis palette<a class="anchor" href="#palette">#</a></h2> | |
| 79 | +<table> | |
| 80 | + <tr><th>Token</th><th>Value</th><th>Used for</th></tr> | |
| 81 | + <tr><td>ember</td><td><code>#FF6B35</code></td><td class="wrap">The accent: active phase, prompt, actions, panel borders.</td></tr> | |
| 82 | + <tr><td>ember-glow</td><td><code>#FFB86B</code></td><td class="wrap">Gradient top: highlights, warm success.</td></tr> | |
| 83 | + <tr><td>teal</td><td><code>#2DD4BF</code></td><td class="wrap">The cool counterpoint: info, paths, symbols.</td></tr> | |
| 84 | + <tr><td>bg / text</td><td><code>#0B0E14</code> / <code>#C9D1E3</code></td><td class="wrap">Cold near-black, calm foreground.</td></tr> | |
| 85 | + <tr><td>success / warning / error</td><td><code>#7EE787</code> / <code>#F0B429</code> / <code>#FF5C57</code></td><td class="wrap">States — always paired with a symbol or word, never color alone.</td></tr> | |
| 86 | +</table> | |
| 87 | + | |
| 88 | +<h2 id="gradients">OKLCH gradients<a class="anchor" href="#gradients">#</a></h2> | |
| 89 | +<p>The signature ember→glow ramps (wordmark, phase ribbon, active panel borders, splash sweep) are | |
| 90 | +interpolated in OKLCH — perceptually uniform, so the midpoints never turn muddy the way naive RGB | |
| 91 | +lerps do. Ramps are precomputed per length and cached: painting a gradient is a string concat, well | |
| 92 | +inside the 16 ms frame budget.</p> | |
| 93 | + | |
| 94 | +<h2 id="ladder">The capability ladder<a class="anchor" href="#ladder">#</a></h2> | |
| 95 | +<table> | |
| 96 | + <tr><th>Detected</th><th>Rendering</th></tr> | |
| 97 | + <tr><td>truecolor (<code>COLORTERM=truecolor</code>)</td><td class="wrap">Full khaelis + gradients + line tints.</td></tr> | |
| 98 | + <tr><td>256 colors</td><td class="wrap">Precomputed quantization — no math at paint time.</td></tr> | |
| 99 | + <tr><td>16 colors</td><td class="wrap">Role-mapped SGR codes.</td></tr> | |
| 100 | + <tr><td>mono (<code>NO_COLOR</code>, dumb, piped)</td><td class="wrap">Identity — zero escape codes. Every state keeps its symbol or word, so nothing loses meaning.</td></tr> | |
| 101 | +</table> | |
| 102 | + | |
| 103 | +<h2 id="motion">The motion doctrine<a class="anchor" href="#motion">#</a></h2> | |
| 104 | +<p>Exactly six animations exist, each carrying meaning: the splash sweep · the phase-transition | |
| 105 | +flash · the approval panel's breathing · the gauge drain on compact · post-stream code | |
| 106 | +colorization · the verify strip contraction. Three hard rules:</p> | |
| 107 | +<ol> | |
| 108 | + <li>An animation is a <em>state</em> advanced only inside the existing render tick — zero extra | |
| 109 | + timers, zero re-renders outside the 16 ms budget.</li> | |
| 110 | + <li>Transitions ≤ 300 ms; waiting indicators ≤ 1 Hz.</li> | |
| 111 | + <li><code>--motion off</code> (and screen-reader detection) reduces everything to static states | |
| 112 | + instantly. Accessibility is not negotiable.</li> | |
| 113 | +</ol> | |
| 114 | + | |
| 115 | +<h2 id="doctor">--doctor-tui<a class="anchor" href="#doctor">#</a></h2> | |
| 116 | +<div class="termwrap"><div class="termbar"><span class="dot r"></span><span class="dot y"></span><span class="dot g"></span><span class="title">khaelor --doctor-tui</span></div> | |
| 117 | +<pre class="term" data-no-copy><code> <span class="t-b">doctor-tui · detected capabilities</span> | |
| 118 | + tty true stdout is a terminal | |
| 119 | + colors truecolor COLORTERM=truecolor · TERM=xterm-256color | |
| 120 | + unicode utf-8 LANG=en_US.UTF-8 | |
| 121 | + width 142 full layout | |
| 122 | + osc8 links yes TERM_PROGRAM=iTerm.app — fallback: text (url) | |
| 123 | + osc52 clipboard yes fallback: copy hint hidden | |
| 124 | + | |
| 125 | + theme: khaelis (obsidian + magma) · degradation: truecolor → 256 → 16 → mono | |
| 126 | + <span class="t-dim">report display bugs with this block attached.</span></code></pre></div> | |
| 127 | +<p>Every capability comes with the <em>reason</em> it was detected — a display bug report with this | |
| 128 | +block attached is already half-diagnosed.</p> | |
| 129 | + | |
| 130 | +<h2 id="site">This site, same system<a class="anchor" href="#site">#</a></h2> | |
| 131 | +<p>The documentation you are reading uses the same tokens: khaelis dark by default, and a warm | |
| 132 | +paper-and-ink light theme where the terminals deliberately stay obsidian — the contrast between a | |
| 133 | +bright modern page and dark living terminals is the look. Toggle it in the header.</p> | |
| 134 | + | |
| 135 | +<div class="pager"> | |
| 136 | + <div><span class="label">Previous</span><a href="/docs/events.html">← The event model</a></div> | |
| 137 | + <div class="next"><span class="label">Next</span><a href="/docs/faq.html">FAQ →</a></div> | |
| 138 | +</div> | |
| 139 | + | |
| 140 | +</article> | |
| 141 | +</div></main> | |
| 142 | + | |
| 143 | +<footer class="site-footer"><div class="inner"> | |
| 144 | + <span>KHAELOR — Simon-Pierre Boucher · <a href="mailto:contact@spboucher.ai">contact@spboucher.ai</a></span> | |
| 145 | + <span>Anthropic-powered · terminal-native by design</span> | |
| 146 | +</div></footer> | |
| 147 | + | |
| 148 | +</body> | |
| 149 | +</html> | |
modified
website/public/docs/tools.html
+16 −1
Large diff (34 lines) is not loaded by default to keep the page fast.Load diff
modified
website/public/docs/usage.html
+16 −1
Large diff (34 lines) is not loaded by default to keep the page fast.Load diff
added
website/public/docs/verification.html
+149 −0
Large diff (149 lines) is not loaded by default to keep the page fast.Load diff
added
website/public/docs/worktrees.html
+132 −0
Large diff (132 lines) is not loaded by default to keep the page fast.Load diff
modified
website/public/index.html
+185 −5
Large diff (260 lines) is not loaded by default to keep the page fast.Load diff
modified
website/public/styles.css
+132 −19
Large diff (164 lines) is not loaded by default to keep the page fast.Load diff