SPB Git

spb/khaelor Public

KHAELOR — a terminal-native autonomous engineering agent powered by Anthropic.

aiagentclianthropictypescript
TypeScript 82.9% HTML 14.9% CSS 1.1% JavaScript 0.7%

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>
Simon-Pierre Boucher committed 4 h ago (Aug 10, 2026) parent 072345a

Showing 23 changed files with +2,036 and −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">&#10095;</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 &amp; 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 &amp; terminal</a>
66 + </div>
67 + <div class="group"><div class="group-title">Help</div>
68 + <a href="/docs/faq.html">FAQ &amp; 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 &gt; ask &gt; 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 &rarr;</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 &middot; <a href="mailto:contact@spboucher.ai">contact@spboucher.ai</a></span>
145 + <span>Anthropic-powered &middot; 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">&#10095;</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 &amp; 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 &amp; terminal</a>
66 + </div>
67 + <div class="group"><div class="group-title">Help</div>
68 + <a href="/docs/faq.html">FAQ &amp; 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 &lt;id&gt;</code></td><td class="wrap">Anthropic model id for this run.</td></tr>
82 + <tr><td><code>--aux-model &lt;id&gt;</code></td><td class="wrap">Cheaper model used for context compaction summaries.</td></tr>
83 + <tr><td><code>--thinking &lt;mode&gt;</code></td><td class="wrap">off · adaptive · always.</td></tr>
84 + <tr><td><code>--max-output-tokens &lt;n&gt;</code></td><td class="wrap">Output ceiling per model response.</td></tr>
85 + <tr><td><code>--gate &lt;mode&gt;</code></td><td class="wrap">Phase-gate rigor: strict · auto (default) · off.</td></tr>
86 + <tr><td><code>-p, --print "&lt;prompt&gt;"</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 &lt;session-id&gt;</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 "&lt;description&gt;" [--type maintain|achieve|watch]
99 + [--schedule "&lt;cron&gt;"|heartbeat] [--check "&lt;cmd&gt;"]
100 + [--budget &lt;usd&gt;] [--runs &lt;n&gt;] [--escalation notify|draft-pr|auto-merge-if-verified]
101 +khaelord goal list | pause &lt;id&gt; | resume &lt;id&gt;
102 +
103 +khaelord approvals # pending asynchronous approvals
104 +khaelord approve &lt;id&gt; | deny &lt;id&gt;</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">&larr; Configuration</a></div>
126 + <div class="next"><span class="label">Next</span><a href="/docs/architecture.html">Architecture &rarr;</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 &middot; <a href="mailto:contact@spboucher.ai">contact@spboucher.ai</a></span>
134 + <span>Anthropic-powered &middot; 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 &amp; 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 &amp; terminal</a>
51 66 </div>
52 67 <div class="group"><div class="group-title">Help</div>
53 68 <a href="/docs/faq.html">FAQ &amp; 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 &amp; 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 &amp; terminal</a>
51 66 </div>
52 67 <div class="group"><div class="group-title">Help</div>
53 68 <a href="/docs/faq.html">FAQ &amp; 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">&#10095;</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 &amp; 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 &amp; terminal</a>
66 + </div>
67 + <div class="group"><div class="group-title">Help</div>
68 + <a href="/docs/faq.html">FAQ &amp; 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 &amp; 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">&larr; Project memory</a></div>
133 + <div class="next"><span class="label">Next</span><a href="/docs/fork-replay.html">Fork · replay · sdiff &rarr;</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 &middot; <a href="mailto:contact@spboucher.ai">contact@spboucher.ai</a></span>
141 + <span>Anthropic-powered &middot; 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">&#10095;</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 &amp; 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 &amp; terminal</a>
66 + </div>
67 + <div class="group"><div class="group-title">Help</div>
68 + <a href="/docs/faq.html">FAQ &amp; 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 # "&lt;idA&gt; &lt;idB&gt;" — 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/&lt;id&gt;</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&lt;T,KError&gt;, 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 &rarr;</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 &middot; <a href="mailto:contact@spboucher.ai">contact@spboucher.ai</a></span>
138 + <span>Anthropic-powered &middot; 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 &amp; 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 &amp; terminal</a>
51 66 </div>
52 67 <div class="group"><div class="group-title">Help</div>
53 68 <a href="/docs/faq.html">FAQ &amp; 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">&#10095;</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 &amp; 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 &amp; terminal</a>
66 + </div>
67 + <div class="group"><div class="group-title">Help</div>
68 + <a href="/docs/faq.html">FAQ &amp; 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 &amp; 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">&larr; Architecture</a></div>
130 + <div class="next"><span class="label">Next</span><a href="/docs/theming.html">Theming &amp; terminal &rarr;</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 &middot; <a href="mailto:contact@spboucher.ai">contact@spboucher.ai</a></span>
138 + <span>Anthropic-powered &middot; 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 &amp; 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 &amp; terminal</a>
51 66 </div>
52 67 <div class="group"><div class="group-title">Help</div>
53 68 <a href="/docs/faq.html">FAQ &amp; 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">&#10095;</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 &amp; 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 &amp; terminal</a>
66 + </div>
67 + <div class="group"><div class="group-title">Help</div>
68 + <a href="/docs/faq.html">FAQ &amp; 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/&lt;project&gt;/
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 &lt;sessionId&gt;</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">&larr; Context engine</a></div>
129 + <div class="next"><span class="label">Next</span><a href="/docs/permissions.html">Permissions &rarr;</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 &middot; <a href="mailto:contact@spboucher.ai">contact@spboucher.ai</a></span>
137 + <span>Anthropic-powered &middot; 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 &amp; 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 &amp; terminal</a>
51 66 </div>
52 67 <div class="group"><div class="group-title">Help</div>
53 68 <a href="/docs/faq.html">FAQ &amp; 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">&#10095;</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 &amp; 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 &amp; terminal</a>
66 + </div>
67 + <div class="group"><div class="group-title">Help</div>
68 + <a href="/docs/faq.html">FAQ &amp; 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&lt;T, KError&gt;; never throw in src/core.
95 + &lt;!-- khaelor: session=01J8K2… tool=toolu_01… confidence=high date=2026-08-10 --&gt;
96 +
97 +## Commands
98 +- Full build: npm run check (includes the mandatory header check).
99 + &lt;!-- khaelor: session=01J8K2… tool=toolu_02… confidence=high date=2026-08-10 --&gt;
100 +
101 +## Pitfalls
102 +- src/tui/render.ts: never touch the buffer outside the 16ms tick — tearing.
103 + &lt;!-- khaelor: session=01J8F1… tool=toolu_09… confidence=medium date=2026-08-09 --&gt;</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">&larr; Semantic index</a></div>
127 + <div class="next"><span class="label">Next</span><a href="/docs/context.html">Context engine &rarr;</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 &middot; <a href="mailto:contact@spboucher.ai">contact@spboucher.ai</a></span>
135 + <span>Anthropic-powered &middot; 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 &amp; 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 &amp; terminal</a>
51 66 </div>
52 67 <div class="group"><div class="group-title">Help</div>
53 68 <a href="/docs/faq.html">FAQ &amp; 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 &amp; 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 &amp; terminal</a>
51 66 </div>
52 67 <div class="group"><div class="group-title">Help</div>
53 68 <a href="/docs/faq.html">FAQ &amp; 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">&#10095;</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 &amp; 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 &amp; terminal</a>
66 + </div>
67 + <div class="group"><div class="group-title">Help</div>
68 + <a href="/docs/faq.html">FAQ &amp; 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&lt;Obs&gt; // 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 &rarr;</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 &middot; <a href="mailto:contact@spboucher.ai">contact@spboucher.ai</a></span>
129 + <span>Anthropic-powered &middot; 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 &amp; 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 &amp; terminal</a>
51 66 </div>
52 67 <div class="group"><div class="group-title">Help</div>
53 68 <a href="/docs/faq.html">FAQ &amp; 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">&#10095;</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 &amp; 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 &amp; terminal</a>
66 + </div>
67 + <div class="group"><div class="group-title">Help</div>
68 + <a href="/docs/faq.html">FAQ &amp; troubleshooting</a>
69 + </div>
70 +</aside>
71 +
72 +<article class="content">
73 +
74 +<h1>Theming &amp; 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">&larr; The event model</a></div>
137 + <div class="next"><span class="label">Next</span><a href="/docs/faq.html">FAQ &rarr;</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 &middot; <a href="mailto:contact@spboucher.ai">contact@spboucher.ai</a></span>
145 + <span>Anthropic-powered &middot; terminal-native by design</span>
146 +</div></footer>
147 +
148 +</body>
149 +</html>
modified website/public/docs/tools.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 &amp; 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 &amp; terminal</a>
51 66 </div>
52 67 <div class="group"><div class="group-title">Help</div>
53 68 <a href="/docs/faq.html">FAQ &amp; troubleshooting</a>
modified website/public/docs/usage.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 &amp; 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 &amp; terminal</a>
51 66 </div>
52 67 <div class="group"><div class="group-title">Help</div>
53 68 <a href="/docs/faq.html">FAQ &amp; troubleshooting</a>
added website/public/docs/verification.html +149 −0
@@ -0,0 +1,149 @@
1 +<!doctype html>
2 +<!--
3 +KHAELOR
4 +File: website/public/docs/verification.html
5 +Description: Docs — The native verify loop: configuration, auto-detection, the repair loop, policies, and honest failure reporting.
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>Verification — KHAELOR docs</title>
14 +<meta name="description" content="The native verify loop: configuration, auto-detection, the repair loop, policies, and honest failure reporting.">
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">&#10095;</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 &amp; 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 &amp; terminal</a>
66 + </div>
67 + <div class="group"><div class="group-title">Help</div>
68 + <a href="/docs/faq.html">FAQ &amp; troubleshooting</a>
69 + </div>
70 +</aside>
71 +
72 +<article class="content">
73 +
74 +<h1>Verification</h1>
75 +<p class="lead">KHAELOR never claims completion because the model produced a confident sentence.
76 +It runs your checks itself — and repairs what fails, before you ever see the answer.</p>
77 +
78 +<h2 id="how">How the loop works<a class="anchor" href="#how">#</a></h2>
79 +<ol>
80 + <li>The model finishes a batch of edits (<code>write</code>/<code>edit</code> tool calls).</li>
81 + <li>The Tool Runtime launches the configured checks <strong>in parallel</strong> through the
82 + workspace seam (autofix checks like <code>eslint --fix</code> run last, serially).</li>
83 + <li>Each check lands as a durable <code>verify.result</code> event: name, command, real exit
84 + code, duration, and output truncated <em>errors-first</em>.</li>
85 + <li>Failing results are injected back into the conversation — the model repairs them before
86 + the turn can complete.</li>
87 + <li>The loop is bounded: after <code>maxRepairLoops</code> failing rounds (default 3) per user
88 + turn, checks stop re-running and the honest failure report stands.</li>
89 +</ol>
90 +<div class="termwrap"><div class="termbar"><span class="dot r"></span><span class="dot y"></span><span class="dot g"></span><span class="title">the repair loop</span></div>
91 +<pre class="term" data-no-copy><code> <span class="t-dim">├─</span> edit <span class="t-teal">src/context/compaction.ts</span> <span class="t-ok">+14</span> <span class="t-err">−3</span>
92 + <span class="t-glow">⟳</span> <span class="t-b">verify</span> typecheck <span class="t-ok">✓</span> <span class="t-dim">1.2s</span> · tests <span class="t-err">✗</span> <span class="t-dim">4.8s</span> · lint <span class="t-ok">✓</span>
93 + <span class="t-dim">FAIL src/context/engine.test.ts — compaction preserves running processes</span>
94 + <span class="t-dim">KHAELOR is repairing the failure…</span>
95 + <span class="t-dim">├─</span> edit <span class="t-teal">src/context/compaction.ts</span> <span class="t-ok">+6</span> <span class="t-err">−2</span>
96 + <span class="t-glow">⟳</span> <span class="t-b">verify</span> typecheck <span class="t-ok">✓</span> · tests <span class="t-ok">✓</span> <span class="t-dim">5.3s</span> · lint <span class="t-ok">✓</span>
97 + <span class="t-ok">✓ verified 5.3s</span></code></pre></div>
98 +
99 +<h2 id="config">Configuration<a class="anchor" href="#config">#</a></h2>
100 +<pre><code>// .khaelor/verify.json
101 +{
102 + "typecheck": { "cmd": "npx tsc --noEmit", "timeout": 60 },
103 + "test": { "cmd": "npx vitest run --changed", "timeout": 120 },
104 + "lint": { "cmd": "npx eslint --fix", "timeout": 30, "autofix": true },
105 + "policy": "after-each-edit-batch",
106 + "maxRepairLoops": 3
107 +}</code></pre>
108 +<table>
109 + <tr><th>Field</th><th>Meaning</th></tr>
110 + <tr><td><code>&lt;name&gt;.cmd</code></td><td class="wrap">The command; its exit code is the verdict. Run through your shell, in the project root.</td></tr>
111 + <tr><td><code>&lt;name&gt;.timeout</code></td><td class="wrap">Seconds before the check is killed (recorded as exit <code>null</code>, i.e. failed).</td></tr>
112 + <tr><td><code>&lt;name&gt;.autofix</code></td><td class="wrap">The check mutates files — run it after the parallel read-only checks.</td></tr>
113 + <tr><td><code>policy</code></td><td class="wrap"><code>after-each-edit-batch</code> (default) · <code>before-final-answer</code> (model-run, nudged) · <code>off</code>.</td></tr>
114 + <tr><td><code>maxRepairLoops</code></td><td class="wrap">Failing rounds per user turn before KHAELOR stops looping and reports.</td></tr>
115 +</table>
116 +
117 +<h2 id="detect">Auto-detection<a class="anchor" href="#detect">#</a></h2>
118 +<p>Without a <code>verify.json</code>, KHAELOR detects conservatively:</p>
119 +<table>
120 + <tr><th>Found</th><th>Checks</th></tr>
121 + <tr><td><code>package.json</code> scripts</td><td class="wrap"><code>npm run typecheck</code> / <code>npm test</code> / <code>npm run lint</code> when the scripts exist; <code>npx tsc --noEmit</code> when only <code>tsconfig.json</code> exists.</td></tr>
122 + <tr><td><code>Cargo.toml</code></td><td class="wrap"><code>cargo check</code>, <code>cargo test</code>.</td></tr>
123 + <tr><td><code>pyproject.toml</code></td><td class="wrap"><code>python3 -m pytest -x -q</code>.</td></tr>
124 +</table>
125 +
126 +<h2 id="honesty">Honesty rules<a class="anchor" href="#honesty">#</a></h2>
127 +<ul>
128 + <li>Passing checks stay out of the model's context (evidence only) — failures enter it verbatim.</li>
129 + <li>Output is truncated errors-first: lines matching failure patterns are kept ahead of noise,
130 + with an explicit truncation marker.</li>
131 + <li><code>/verify</code> runs the whole suite on demand; the daemon refuses to escalate a goal
132 + run whose checks failed.</li>
133 +</ul>
134 +
135 +<div class="pager">
136 + <div><span class="label">Previous</span><a href="/docs/phases.html">&larr; Phase gates</a></div>
137 + <div class="next"><span class="label">Next</span><a href="/docs/worktrees.html">Parallel worktrees &rarr;</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 &middot; <a href="mailto:contact@spboucher.ai">contact@spboucher.ai</a></span>
145 + <span>Anthropic-powered &middot; terminal-native by design</span>
146 +</div></footer>
147 +
148 +</body>
149 +</html>
added website/public/docs/worktrees.html +132 −0
@@ -0,0 +1,132 @@
1 +<!doctype html>
2 +<!--
3 +KHAELOR
4 +File: website/public/docs/worktrees.html
5 +Description: Docs — Isolated parallel subtasks: git worktrees, child sessions, capability attenuation, supervised merges.
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>Parallel worktrees — KHAELOR docs</title>
14 +<meta name="description" content="Isolated parallel subtasks: git worktrees, child sessions, capability attenuation, supervised merges.">
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">&#10095;</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 &amp; 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 &amp; terminal</a>
66 + </div>
67 + <div class="group"><div class="group-title">Help</div>
68 + <a href="/docs/faq.html">FAQ &amp; troubleshooting</a>
69 + </div>
70 +</aside>
71 +
72 +<article class="content">
73 +
74 +<h1>Parallel worktrees</h1>
75 +<p class="lead">Run several tasks at once without ever letting an agent touch your working copy.</p>
76 +
77 +<h2 id="model">The isolation model<a class="anchor" href="#model">#</a></h2>
78 +<p>Every <code>/spawn</code> creates:</p>
79 +<ol>
80 + <li>a git worktree at <code>.khaelor/worktrees/&lt;taskId&gt;</code> on branch <code>khaelor/&lt;taskId&gt;</code>;</li>
81 + <li>a <strong>child session</strong> — its own JSONL log, with <code>meta.parent</code> pointing at the orchestrator session;</li>
82 + <li>a full agent engine over that worktree with <strong>attenuated capabilities</strong>: permissions
83 + are non-interactive (every ask resolves to deny), scoped to the worktree — capability attenuation,
84 + a real security argument, not a convention.</li>
85 +</ol>
86 +<div class="termwrap"><div class="termbar"><span class="dot r"></span><span class="dot y"></span><span class="dot g"></span><span class="title">/tasks</span></div>
87 +<pre class="term" data-no-copy><code> <span class="t-b">tasks</span>
88 + <span class="t-ember">●</span> fix-auth-bug <span class="t-ember">◑ design</span> <span class="t-dim">$0.42</span> ⠹ edit…
89 + <span class="t-ok">✓</span> add-rate-limit <span class="t-ok">done</span> <span class="t-ok">+118</span> <span class="t-err">−24</span> · verify <span class="t-ok">✓</span>
90 + <span class="t-err">✗</span> flaky-retry <span class="t-err">failed</span> <span class="t-dim">verify ✗ — see child session</span></code></pre></div>
91 +
92 +<h2 id="lifecycle">Lifecycle<a class="anchor" href="#lifecycle">#</a></h2>
93 +<table>
94 + <tr><th>Step</th><th>What happens</th></tr>
95 + <tr><td><code>/spawn</code></td><td class="wrap">Worktree + branch + child session created; a durable <code>subtask.created</code> event lands in the orchestrator log.</td></tr>
96 + <tr><td>run</td><td class="wrap">The child works with phase gates and the verify loop active — designs and checks happen inside the isolation too.</td></tr>
97 + <tr><td>finish</td><td class="wrap">Changes are committed onto the subtask branch; <code>subtask.completed</code> records the outcome, REAL git diff stats, and the verify verdict.</td></tr>
98 + <tr><td><code>/merge</code></td><td class="wrap">Supervised <code>git merge --no-ff</code> of the branch into your current branch. Conflicts abort cleanly, leaving the tree untouched.</td></tr>
99 +</table>
100 +
101 +<h2 id="conflicts">Conflict resolution<a class="anchor" href="#conflicts">#</a></h2>
102 +<p>When two subtask branches collide, the merge aborts and reports. The recommended move: ask
103 +KHAELOR to resolve, giving it both designs — they are in the logs — as context. The orchestrator
104 +can even <code>/spawn</code> a dedicated resolution subtask.</p>
105 +
106 +<h2 id="replay-sandbox">The same mechanics power /replay<a class="anchor" href="#replay-sandbox">#</a></h2>
107 +<p><code>/replay</code> reuses the worktree machinery as a sandbox: the re-executed tool calls run
108 +in a throwaway copy that is removed afterwards, branch and all. See
109 +<a href="/docs/fork-replay.html">Fork · replay · sdiff</a>.</p>
110 +
111 +<h2 id="hygiene">Hygiene<a class="anchor" href="#hygiene">#</a></h2>
112 +<ul>
113 + <li>Worktrees live under <code>.khaelor/worktrees/</code> — add it to <code>.gitignore</code> if you have not.</li>
114 + <li>Merged branches are deleted; failed ones are kept for inspection.</li>
115 + <li>The daemon's goal runs use the same mechanism (<code>khaelor/goal-&lt;runId&gt;</code> branches).</li>
116 +</ul>
117 +
118 +<div class="pager">
119 + <div><span class="label">Previous</span><a href="/docs/verification.html">&larr; Verification</a></div>
120 + <div class="next"><span class="label">Next</span><a href="/docs/daemon.html">The daemon &rarr;</a></div>
121 +</div>
122 +
123 +</article>
124 +</div></main>
125 +
126 +<footer class="site-footer"><div class="inner">
127 + <span>KHAELOR — Simon-Pierre Boucher &middot; <a href="mailto:contact@spboucher.ai">contact@spboucher.ai</a></span>
128 + <span>Anthropic-powered &middot; terminal-native by design</span>
129 +</div></footer>
130 +
131 +</body>
132 +</html>
modified website/public/index.html +185 −5
@@ -2,7 +2,7 @@
2 2 <!--
3 3 KHAELOR
4 4 File: website/public/index.html
5 −Description: KHAELOR site — landing page v2: the auditable autonomous engineer (phase gates, verify, fork/replay/sdiff, daemon).
5 +Description: KHAELOR site — legendary landing: the auditable autonomous engineer, full TUI gallery, phase gates, daemon.
6 6 Author: Simon-Pierre Boucher
7 7 Contact: contact@spboucher.ai
8 8 -->
@@ -26,6 +26,7 @@ Contact: contact@spboucher.ai
26 26 <a href="/docs/getting-started.html">Docs</a>
27 27 <a href="/docs/phases.html">Phase gates</a>
28 28 <a href="/docs/daemon.html">Daemon</a>
29 + <a href="/#interface">The interface</a>
29 30 <a href="/#install">Install</a>
30 31 <button id="theme-toggle" type="button" aria-label="Toggle color theme">light</button>
31 32 </nav>
@@ -54,11 +55,19 @@ Contact: contact@spboucher.ai
54 55 <a href="/docs/daemon.html">The daemon &rarr;</a>
55 56 </div>
56 57
58 + <div class="stats">
59 + <div class="stat"><b>40</b><span>durable event types</span></div>
60 + <div class="stat"><b>11</b><span>powerful tools</span></div>
61 + <div class="stat"><b>698</b><span>tests, all green</span></div>
62 + <div class="stat"><b>0</b><span>invented numbers</span></div>
63 + </div>
64 +
57 65 <div class="principle">Understand first. Design second. Implement third. <span class="g-ember">Verify always. Even at 3&nbsp;AM.</span></div>
58 66 </section>
59 67
60 − <div class="section-title">The cockpit</div>
68 + <div class="section-title">One session, start to finish</div>
61 69
70 + <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 — ~/dev/my-project</span></div>
62 71 <pre class="term" data-no-copy><code> <span class="t-b g-ember">KHAELOR</span> <span class="t-dim">▸ my-project · main</span>
63 72
64 73 <span class="t-ember">❯</span> fix the memory leak in the renderer
@@ -76,7 +85,7 @@ Contact: contact@spboucher.ai
76 85 <span class="t-glow">⟳</span> <span class="t-b">verify</span> typecheck <span class="t-ok">✓</span> <span class="t-dim">1.2s</span> · tests <span class="t-ok">✓</span> <span class="t-dim">4.1s</span> · lint <span class="t-ok">✓</span>
77 86 <span class="t-ok">✓ verified 4.1s</span>
78 87
79 − <span class="t-ember">●</span> IMPLEMENT <span class="t-dim">─</span> <span class="t-dim">main</span> <span class="t-dim">│</span> sonnet <span class="t-dim">│</span> <span class="gauge">▰▰▰▱▱▱▱▱ 38%</span> <span class="t-dim">│ in 45k · out 3.2k</span></code></pre>
88 + <span class="t-ember">●</span> IMPLEMENT <span class="t-dim">─</span> <span class="t-dim">main</span> <span class="t-dim">│</span> sonnet <span class="t-dim">│</span> <span class="gauge">▰▰▰▱▱▱▱▱ 38%</span> <span class="t-dim">│ in 45k · out 3.2k</span></code></pre></div>
80 89
81 90 <div class="section-title">Not another coding agent</div>
82 91
@@ -119,6 +128,173 @@ Contact: contact@spboucher.ai
119 128 </div>
120 129 </div>
121 130
131 + <div class="section-title" id="interface">The interface</div>
132 + <p class="lead" style="max-width:46rem;">No spinner theater, no screen flicker — a print-once
133 + scrollback, a bounded live region, and a 16&nbsp;ms frame budget. Here is what your day
134 + actually looks like.</p>
135 +
136 + <div class="gallery">
137 +
138 + <figure>
139 + <div class="termwrap"><div class="termbar"><span class="dot r"></span><span class="dot y"></span><span class="dot g"></span><span class="title">slash palette</span></div>
140 + <pre class="term" data-no-copy><code> <span class="t-ember">❯</span> /f<span class="cursor"> </span>
141 + <span class="t-dim">╭──────────────────────────────────────────╮</span>
142 + <span class="t-dim">│</span> <span class="sel"> /<span class="match">f</span>ork fork this session at a checkpoint </span><span class="t-dim">│</span>
143 + <span class="t-dim">│</span> /di<span class="match">f</span>f working-tree changes <span class="t-dim">│</span>
144 + <span class="t-dim">│</span> /veri<span class="match">f</span>y run the verify checks now <span class="t-dim">│</span>
145 + <span class="t-dim">│</span> /con<span class="match">f</span>ig resolved configuration <span class="t-dim">│</span>
146 + <span class="t-dim">╰──────────────────────────────────────────╯</span></code></pre></div>
147 + <figcaption><b>Slash palette.</b> Type <code>/</code> — fuzzy filtering, descriptions,
148 + keyboard-only. <kbd>Ctrl+K</kbd> opens the same registry as a universal palette.</figcaption>
149 + </figure>
150 +
151 + <figure>
152 + <div class="termwrap"><div class="termbar"><span class="dot r"></span><span class="dot y"></span><span class="dot g"></span><span class="title">@ file mentions</span></div>
153 + <pre class="term" data-no-copy><code> <span class="t-ember">❯</span> refactor @ker<span class="cursor"> </span>
154 + <span class="t-dim">╭──────────────────────────────────────────╮</span>
155 + <span class="t-dim">│</span> <span class="sel"> src/agent/<span class="match">ker</span>nel.ts </span><span class="t-dim">│</span>
156 + <span class="t-dim">│</span> tests/agent/<span class="match">ker</span>nel.test.ts <span class="t-dim">│</span>
157 + <span class="t-dim">│</span> docs/research/<span class="match">KER</span>NEL_NOTES.md <span class="t-dim">│</span>
158 + <span class="t-dim">╰──────────────────────────────────────────╯</span></code></pre></div>
159 + <figcaption><b>File mentions.</b> <code>@</code> opens fuzzy repository search backed by the
160 + live index; selection inserts a structured reference, not a pasted file.</figcaption>
161 + </figure>
162 +
163 + <figure>
164 + <div class="termwrap"><div class="termbar"><span class="dot r"></span><span class="dot y"></span><span class="dot g"></span><span class="title">permission panel</span></div>
165 + <pre class="term" data-no-copy><code> <span class="t-ember">╭─ KHAELOR requests permission ──────────────╮</span>
166 + <span class="t-ember">│</span> <span class="t-b">Run</span> <span class="t-ember">│</span>
167 + <span class="t-ember">│</span> <span class="t-teal">npm install</span> <span class="t-ember">│</span>
168 + <span class="t-ember">│</span> <span class="t-ember">│</span>
169 + <span class="t-ember">│</span> <span class="t-dim">Working directory ~/dev/my-project</span> <span class="t-ember">│</span>
170 + <span class="t-ember">│</span> <span class="t-b">[Enter]</span> allow once <span class="t-ember">│</span>
171 + <span class="t-ember">│</span> <span class="t-b">[a]</span> always allow in this project <span class="t-ember">│</span>
172 + <span class="t-ember">│</span> <span class="t-b">[Esc]</span> deny <span class="t-ember">│</span>
173 + <span class="t-ember">╰────────────────────────────────────────────╯</span></code></pre></div>
174 + <figcaption><b>Permissions.</b> Capability-based (<code>process.execute</code>,
175 + <code>git.modify</code>, <code>network.access</code>…), deny &gt; ask &gt; allow. The
176 + interaction takes milliseconds; silence is never consent.</figcaption>
177 + </figure>
178 +
179 + <figure>
180 + <div class="termwrap"><div class="termbar"><span class="dot r"></span><span class="dot y"></span><span class="dot g"></span><span class="title">diff — intra-line highlight</span></div>
181 + <pre class="term" data-no-copy><code> <span class="t-b">edit · src/kernel/dispatch.ts</span> <span class="t-ok">+8</span> <span class="t-err">−3</span>
182 + <span class="t-dim"> 42 │</span> if (!grant) {
183 + <span class="t-dim"> 43 │</span><span class="d-del">− <span class="d-del-hi">throw new</span> PermissionError(cap);</span>
184 + <span class="t-dim"> 43 │</span><span class="d-add">+ <span class="d-add-hi">return Result.err(new</span> PermissionError(cap)<span class="d-add-hi">)</span>;</span>
185 + <span class="t-dim"> 44 │</span><span class="d-add">+ // phase gate: blocked in understand</span>
186 + <span class="t-dim"> ⋮ 2 hunks folded — [x] expand</span></code></pre></div>
187 + <figcaption><b>The signature diff.</b> Tinted line backgrounds, only the changed characters
188 + at full saturation, long hunks auto-folded. <code>d</code> expands any edit instantly;
189 + <code>/diff</code> goes full-screen side-by-side.</figcaption>
190 + </figure>
191 +
192 + <figure>
193 + <div class="termwrap"><div class="termbar"><span class="dot r"></span><span class="dot y"></span><span class="dot g"></span><span class="title">/processes</span></div>
194 + <pre class="term" data-no-copy><code> <span class="t-b">processes</span>
195 + <span class="t-ok">●</span> 3121 npm run dev <span class="t-teal">running</span> 04:32
196 + <span class="t-ok">●</span> 3198 pytest -x <span class="t-teal">running</span> 00:18
197 + <span class="t-dim">○</span> 3012 npm test <span class="t-dim">exited code 0</span>
198 +
199 + <span class="t-dim">the agent starts a dev server, keeps editing,
200 + reads its output, runs tests — nothing blocks</span></code></pre></div>
201 + <figcaption><b>Background processes.</b> Long-running commands never block the loop:
202 + start → continue editing → inspect output → stop. First-class, not an afterthought.</figcaption>
203 + </figure>
204 +
205 + <figure>
206 + <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 — run it twice, diff the runs</span></div>
207 + <pre class="term" data-no-copy><code> <span class="t-b">sdiff</span>
208 + <span class="t-dim">01J8K2… (sonnet)</span> <span class="t-dim">01J8K9… (haiku)</span>
209 + agent turns 12 17
210 + tool calls 34 61
211 + files modified 2 3
212 + tokens (in/out) 145k / 12k 210k / 19k
213 + verify failures <span class="t-ok">0</span> <span class="t-err">2</span>
214 + outcome <span class="t-ok">completed</span> <span class="t-ok">completed</span>
215 + <span class="t-dim">files only in B: src/c.ts</span></code></pre></div>
216 + <figcaption><b>Session diff.</b> The cheapest honest model comparison in any CLI:
217 + <code>/replay</code> a run with another model, then <code>/sdiff</code> the two logs.</figcaption>
218 + </figure>
219 +
220 + <figure>
221 + <div class="termwrap"><div class="termbar"><span class="dot r"></span><span class="dot y"></span><span class="dot g"></span><span class="title">/cost — real usage only</span></div>
222 + <pre class="term" data-no-copy><code> <span class="t-b">cost · this session</span> <span class="t-dim">(real API usage)</span>
223 + per turn <span class="t-glow">⣀⣄⣤⣶⣿⣷⣄⣀⣠⣤</span>
224 + requests 14
225 + input tokens 145,032 <span class="t-dim">cache-read 118,240</span>
226 + output tokens 12,884
227 + <span class="t-b">total $2.14</span> <span class="t-dim">(with configured pricing)</span></code></pre></div>
228 + <figcaption><b>Cost, honestly.</b> Every number is summed from the API's usage metadata —
229 + braille sparkline per turn. No pricing configured → no dollar figure invented.</figcaption>
230 + </figure>
231 +
232 + <figure>
233 + <div class="termwrap"><div class="termbar"><span class="dot r"></span><span class="dot y"></span><span class="dot g"></span><span class="title">/memory — provenance included</span></div>
234 + <pre class="term" data-no-copy><code> <span class="t-b">memory · .khaelor/MEMORY.md</span> <span class="t-dim">(4 entries)</span>
235 + <span class="t-glow">Conventions</span>
236 + · errors flow through Result&lt;T,KError&gt; <span class="t-dim">[high · 2026-08-10 · session 01J8K2…]</span>
237 + <span class="t-glow">Commands</span>
238 + · full build: npm run check <span class="t-dim">[high · 2026-08-10 · session 01J8K2…]</span>
239 + <span class="t-glow">Pitfalls</span>
240 + · never touch render buffer off-tick <span class="t-dim">[medium · session 01J8F1…]</span>
241 + <span class="t-dim">1 low-confidence entry — purge candidate at next /compact</span></code></pre></div>
242 + <figcaption><b>Memory you can audit.</b> Each fact links back to the session and event
243 + that produced it — <kbd>Enter</kbd> opens the source. You always know <em>why</em>.</figcaption>
244 + </figure>
245 +
246 + <figure>
247 + <div class="termwrap"><div class="termbar"><span class="dot r"></span><span class="dot y"></span><span class="dot g"></span><span class="title">/tasks — parallel subtasks</span></div>
248 + <pre class="term" data-no-copy><code> <span class="t-b">tasks</span>
249 + <span class="t-ember">●</span> fix-auth-bug <span class="t-ember">◑ design</span> <span class="t-dim">$0.42</span> ⠹ edit…
250 + <span class="t-ok">✓</span> add-rate-limit <span class="t-ok">done</span> <span class="t-ok">+118</span> <span class="t-err">−24</span> · verify <span class="t-ok">✓</span>
251 + <span class="t-dim">○</span> deps-update <span class="t-dim">(goal)</span> idle · next run 06:00
252 +
253 + <span class="t-dim">merge a finished task with /merge (--no-ff, supervised)</span></code></pre></div>
254 + <figcaption><b>The task board.</b> Each subtask lives in its own git worktree and child
255 + session with attenuated capabilities — capability attenuation, a real security argument.</figcaption>
256 + </figure>
257 +
258 + <figure>
259 + <div class="termwrap"><div class="termbar"><span class="dot r"></span><span class="dot y"></span><span class="dot g"></span><span class="title">verify strip — repair loop</span></div>
260 + <pre class="term" data-no-copy><code> <span class="t-glow">⟳</span> <span class="t-b">verify</span> typecheck <span class="t-ok">✓</span> <span class="t-dim">1.2s</span> · tests <span class="t-err">✗</span> · lint <span class="t-ok">✓</span>
261 + <span class="t-dim">FAIL src/context/engine.test.ts
262 + → compaction preserves running processes</span>
263 + <span class="t-dim">KHAELOR is repairing the failure…</span>
264 + <span class="t-dim">├─</span> edit <span class="t-teal">src/context/compaction.ts</span> <span class="t-ok">+6</span> <span class="t-err">−2</span>
265 + <span class="t-glow">⟳</span> <span class="t-b">verify</span> typecheck <span class="t-ok">✓</span> · tests <span class="t-ok">✓</span> <span class="t-dim">5.3s</span> · lint <span class="t-ok">✓</span>
266 + <span class="t-ok">✓ verified 5.3s</span></code></pre></div>
267 + <figcaption><b>The repair loop.</b> Failures come back to the model automatically —
268 + bounded (3 rounds), then an honest report. Verification is not optional politeness.</figcaption>
269 + </figure>
270 +
271 + <figure>
272 + <div class="termwrap"><div class="termbar"><span class="dot r"></span><span class="dot y"></span><span class="dot g"></span><span class="title">markdown + syntax highlighting</span></div>
273 + <pre class="term" data-no-copy><code> <span class="t-glow">─── Here is the fix ───────────────────────</span>
274 + The leak came from <span class="t-teal">`appendLine`</span> growing the
275 + buffer unboundedly. Ring buffer instead:
276 +
277 + <span class="t-dim">╭─ typescript ───────────────────────╮</span>
278 + <span class="t-dim">│</span> <span class="t-ember">export class</span> <span class="t-teal">RingBuffer</span> { <span class="t-dim">│</span>
279 + <span class="t-dim">│</span> <span class="t-ember">constructor</span>(<span class="t-warn">capacity</span>: <span class="t-teal">number</span>) {} <span class="t-dim">│</span>
280 + <span class="t-dim">│</span> } <span class="t-dim">│</span>
281 + <span class="t-dim">╰────────────────────────── ⏎ copy ──╯</span></code></pre></div>
282 + <figcaption><b>Markdown done right.</b> Streamed text renders live; code blocks colorize
283 + the instant they settle. OSC&nbsp;52 copy where the terminal supports it.</figcaption>
284 + </figure>
285 +
286 + <figure>
287 + <div class="termwrap"><div class="termbar"><span class="dot r"></span><span class="dot y"></span><span class="dot g"></span><span class="title">steering — type while it works</span></div>
288 + <pre class="term" data-no-copy><code> <span class="t-dim">├─</span> bash <span class="t-teal">npm test</span> <span class="t-dim">· running · 12s</span>
289 +
290 + <span class="t-ember">❯</span> also update the CHANGELOG<span class="cursor"> </span>
291 + <span class="t-warn">⋯ 1 queued</span> <span class="t-dim">— injected at the next safe seam</span></code></pre></div>
292 + <figcaption><b>Steering.</b> Keep typing while KHAELOR works — messages queue and inject
293 + at a safe boundary, never corrupting a tool batch. <kbd>Esc</kbd> interrupts cleanly.</figcaption>
294 + </figure>
295 +
296 + </div>
297 +
122 298 <div class="section-title">khaelord — the engineer that lives</div>
123 299
124 300 <p class="lead" style="max-width: 46rem;">
@@ -127,6 +303,7 @@ Contact: contact@spboucher.ai
127 303 asynchronous approval queue: a suspended run costs zero.
128 304 </p>
129 305
306 + <div class="termwrap"><div class="termbar"><span class="dot r"></span><span class="dot y"></span><span class="dot g"></span><span class="title">khaelord — 3 AM, fully audited</span></div>
130 307 <pre class="term" data-no-copy><code> <span class="t-dim">$</span> khaelord goal add <span class="t-teal">"keep npm deps fresh without breaking changes"</span> \
131 308 --type maintain --schedule <span class="t-teal">"0 6 * * 1"</span> --budget 5 --escalation draft-pr
132 309
@@ -136,7 +313,7 @@ Contact: contact@spboucher.ai
136 313 <span class="t-dim">03:12</span> <span class="t-ember">●</span> goal <span class="t-teal">deps-fresh</span> check failed → run r7f2 in worktree khaelor/goal-r7f2
137 314 <span class="t-dim">03:14</span> <span class="t-ember">◑</span> design recorded <span class="t-dim">· 3 files · in the log, replayable</span>
138 315 <span class="t-dim">03:17</span> <span class="t-ok">✓ verified</span> <span class="t-dim">· typecheck ✓ tests ✓</span> · branch left for review
139 − <span class="t-dim">03:17</span> <span class="t-dim">spent today: $1.84 / $20 · runs 1/8</span></code></pre>
316 + <span class="t-dim">03:17</span> <span class="t-dim">spent today: $1.84 / $20 · runs 1/8</span></code></pre></div>
140 317
141 318 <div class="pitch">
142 319 <p>Other agents give you an assistant that lives. <strong>KHAELOR gives you an engineer that
@@ -147,6 +324,7 @@ Contact: contact@spboucher.ai
147 324
148 325 <div class="section-title">Approval, when it matters</div>
149 326
327 + <div class="termwrap"><div class="termbar"><span class="dot r"></span><span class="dot y"></span><span class="dot g"></span><span class="title">design panel — strict mode</span></div>
150 328 <pre class="term panel breath" data-no-copy><code> <span class="t-ember">╭─ ◑ DESIGN — approval required ─────────────────────────╮</span>
151 329 <span class="t-ember">│</span> <span class="t-dim">Goal</span> Fix the renderer memory leak <span class="t-ember">│</span>
152 330 <span class="t-ember">│</span> <span class="t-dim">Files</span> src/tui/render.ts · src/tui/buffer.ts <span class="t-ember">│</span>
@@ -155,7 +333,7 @@ Contact: contact@spboucher.ai
155 333 <span class="t-ember">│</span> <span class="t-dim">Verify</span> vitest run tests/tui + manual demo <span class="t-ember">│</span>
156 334 <span class="t-ember">├────────────────────────────────────────────────────────┤</span>
157 335 <span class="t-ember">│</span> <span class="t-b">[a]</span> approve <span class="t-b">[r]</span> reject <span class="t-ember">│</span>
158 − <span class="t-ember">╰────────────────────────────────────────────────────────╯</span></code></pre>
336 + <span class="t-ember">╰────────────────────────────────────────────────────────╯</span></code></pre></div>
159 337
160 338 <div class="section-title">Everything is real</div>
161 339
@@ -177,6 +355,7 @@ khaelor</code></pre>
177 355
178 356 <div class="cta-row" style="margin-bottom: 3rem;">
179 357 <a href="/docs/getting-started.html">Getting started &rarr;</a>
358 + <a href="/docs/cookbook.html">Cookbook &rarr;</a>
180 359 <a href="/docs/commands.html">All commands &rarr;</a>
181 360 <a href="/docs/faq.html">FAQ &rarr;</a>
182 361 </div>
@@ -189,6 +368,7 @@ khaelor</code></pre>
189 368 <a href="/docs/getting-started.html">Docs</a>
190 369 <a href="/docs/phases.html">Phase gates</a>
191 370 <a href="/docs/daemon.html">Daemon</a>
371 + <a href="/docs/architecture.html">Architecture</a>
192 372 </div></footer>
193 373
194 374 </body>
modified website/public/styles.css +132 −19
@@ -35,28 +35,35 @@
35 35 color-scheme: dark;
36 36 }
37 37
38 +/* Legendary light — warm paper + ink + ember. Terminal blocks stay obsidian:
39 + the contrast between a bright modern page and dark living terminals IS the look. */
38 40 html[data-theme="light"] {
39 − --bg: #fbfaf8;
40 − --bg-alt: #f4f2ee;
41 − --bg-code: #f6f4f1;
42 − --bg-inline: #eeebe5;
43 − --border: #e2ddd4;
44 − --border-soft: #eae6de;
45 − --text: #2a3040;
46 − --text-strong: #14181f;
47 − --dim: #646b7a;
48 − --dimmer: #949bab;
49 − --accent: #d84f16;
50 − --accent2: #b06722;
51 − --teal: #0f766e;
52 − --accent-soft: rgba(216, 79, 22, 0.09);
53 − --teal-soft: rgba(15, 118, 110, 0.08);
54 − --success: #467a1c;
55 − --warning: #96660e;
56 − --error: #c53b58;
57 − --ember-gradient: linear-gradient(100deg, #d84f16 0%, #b06722 55%, #d84f16 100%);
41 + --bg: #faf8f3;
42 + --bg-alt: #ffffff;
43 + --bg-code: #f3efe7;
44 + --bg-inline: #eee8dd;
45 + --border: #e5ddce;
46 + --border-soft: #ede7da;
47 + --text: #3b362e;
48 + --text-strong: #1c1811;
49 + --dim: #6f695e;
50 + --dimmer: #9d968a;
51 + --accent: #d84a10;
52 + --accent2: #b06718;
53 + --teal: #0d7c72;
54 + --accent-soft: rgba(216, 74, 16, 0.08);
55 + --teal-soft: rgba(13, 124, 114, 0.08);
56 + --success: #3f7d18;
57 + --warning: #92650a;
58 + --error: #c23a55;
59 + --ember-gradient: linear-gradient(100deg, #d84a10 0%, #e8862e 55%, #d84a10 100%);
60 + --shadow: 0 1px 2px rgba(28, 24, 17, 0.05), 0 10px 30px rgba(28, 24, 17, 0.08);
58 61 color-scheme: light;
59 62 }
63 +html[data-theme="light"] .card { box-shadow: var(--shadow); border-color: var(--border-soft); }
64 +html[data-theme="light"] .termwrap { box-shadow: 0 2px 6px rgba(28, 24, 17, 0.12), 0 18px 48px rgba(28, 24, 17, 0.18); }
65 +html[data-theme="light"] .pitch { box-shadow: var(--shadow); }
66 +html[data-theme="light"] .site-header { background: color-mix(in srgb, #faf8f3 82%, transparent); }
60 67
61 68 /* ───────────────────────── base ───────────────────────── */
62 69
@@ -545,3 +552,109 @@ kbd {
545 552
546 553 /* Comparison table accent */
547 554 table.vs td:first-child { color: var(--text-strong); }
555 +
556 +/* ───────────────────────── legendary pass: terminal windows, gallery, hero glow ───────────────────────── */
557 +
558 +/* Terminal window chrome — every mock reads as a living terminal. */
559 +.termwrap {
560 + border: 1px solid #1d2330;
561 + border-radius: 12px;
562 + overflow: hidden;
563 + background: #0a0d13;
564 + margin: 1.1rem 0;
565 +}
566 +.termbar {
567 + display: flex;
568 + align-items: center;
569 + gap: 0.45rem;
570 + padding: 0.55rem 0.85rem;
571 + background: #0e121a;
572 + border-bottom: 1px solid #171c28;
573 +}
574 +.termbar .dot { width: 11px; height: 11px; border-radius: 50%; flex: none; }
575 +.termbar .dot.r { background: #ff5f57; }
576 +.termbar .dot.y { background: #febc2e; }
577 +.termbar .dot.g { background: #28c840; }
578 +.termbar .title {
579 + margin-left: 0.55rem;
580 + font-family: var(--mono);
581 + font-size: 0.72rem;
582 + color: #5b657a;
583 + white-space: nowrap;
584 + overflow: hidden;
585 + text-overflow: ellipsis;
586 +}
587 +.termwrap pre.term, .termwrap pre {
588 + border: none;
589 + border-radius: 0;
590 + margin: 0;
591 + background: #0a0d13;
592 +}
593 +
594 +/* The interface gallery */
595 +.gallery {
596 + display: grid;
597 + grid-template-columns: repeat(auto-fit, minmax(400px, 1fr));
598 + gap: 1.2rem;
599 + margin: 1.4rem 0 2.6rem;
600 + align-items: start;
601 +}
602 +.gallery figure { margin: 0; min-width: 0; }
603 +.gallery .termwrap { margin: 0; }
604 +.gallery figcaption {
605 + font-size: 0.84rem;
606 + color: var(--dim);
607 + padding: 0.55rem 0.2rem 0;
608 + line-height: 1.5;
609 +}
610 +.gallery figcaption b { color: var(--text-strong); font-weight: 600; }
611 +@media (max-width: 880px) { .gallery { grid-template-columns: 1fr; } }
612 +
613 +/* Hero glow — the magma under the obsidian. */
614 +.hero { position: relative; }
615 +.hero::before {
616 + content: "";
617 + position: absolute;
618 + top: -6rem;
619 + left: -12%;
620 + width: 70%;
621 + height: 22rem;
622 + background: radial-gradient(closest-side, rgba(255, 107, 53, 0.14), transparent 72%);
623 + pointer-events: none;
624 + z-index: -1;
625 +}
626 +html[data-theme="light"] .hero::before {
627 + background: radial-gradient(closest-side, rgba(216, 74, 16, 0.10), transparent 72%);
628 +}
629 +
630 +/* Stats band under the hero */
631 +.stats {
632 + display: flex;
633 + flex-wrap: wrap;
634 + gap: 2.2rem;
635 + margin: 2.4rem 0 0.6rem;
636 +}
637 +.stats .stat b {
638 + display: block;
639 + font-family: var(--mono);
640 + font-size: 1.45rem;
641 + color: var(--text-strong);
642 + line-height: 1.2;
643 +}
644 +.stats .stat span {
645 + font-size: 0.78rem;
646 + color: var(--dimmer);
647 + text-transform: uppercase;
648 + letter-spacing: 0.08em;
649 +}
650 +
651 +/* Palette / selector mocks */
652 +.term .sel { background: rgba(255, 107, 53, 0.18); color: #eceff4; }
653 +.term .match { color: #ff6b35; font-weight: 700; }
654 +.term .cursor { background: #c9d1e3; color: #0a0d13; }
655 +
656 +/* Intra-line diff emphasis */
657 +.term .d-add { background: rgba(126, 231, 135, 0.16); }
658 +.term .d-del { background: rgba(255, 92, 87, 0.16); }
659 +.term .d-add-hi { background: rgba(126, 231, 135, 0.42); color: #eceff4; }
660 +.term .d-del-hi { background: rgba(255, 92, 87, 0.42); color: #eceff4; }
548 661