SPB Git

spb/khaelor

Public

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

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 (Aug 10, 2026) parent 072345a Browse files

23 changed files +2,036 −34

added website/public/docs/architecture.html +149 −0
@@ -0,0 +1,149 @@
1 +<!doctype html>
2 +<!--
3 +KHAELOR
4 +File: website/public/docs/architecture.html
5 +Description: Docs — The small kernel, the services around it, the world seam, and the layering rules that keep KHAELOR honest.
6 +Author: Simon-Pierre Boucher
7 +Contact: contact@spboucher.ai
8 +-->
9 +<html lang="en">
10 +<head>
11 +<meta charset="utf-8">
12 +<meta name="viewport" content="width=device-width, initial-scale=1">
13 +<title>Architecture — KHAELOR docs</title>
14 +<meta name="description" content="The small kernel, the services around it, the world seam, and the layering rules that keep KHAELOR honest.">
15 +<link rel="stylesheet" href="/styles.css">
16 +<script>
17 +(function(){try{var t=localStorage.getItem("khaelor-theme");if(!t&&window.matchMedia&&window.matchMedia("(prefers-color-scheme: light)").matches)t="light";if(t==="light")document.documentElement.setAttribute("data-theme","light");}catch(e){}})();
18 +</script>
19 +<script defer src="/site.js"></script>
20 +</head>
21 +<body>
22 +
23 +<header class="site-header"><div class="inner">
24 + <a class="wordmark" href="/"><span class="glyph">&#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
Large diff (34 lines) is not loaded by default to keep the page fast.Load diff
modified website/public/docs/usage.html +16 −1
Large diff (34 lines) is not loaded by default to keep the page fast.Load diff
added website/public/docs/verification.html +149 −0
Large diff (149 lines) is not loaded by default to keep the page fast.Load diff
added website/public/docs/worktrees.html +132 −0
Large diff (132 lines) is not loaded by default to keep the page fast.Load diff
modified website/public/index.html +185 −5
Large diff (260 lines) is not loaded by default to keep the page fast.Load diff
modified website/public/styles.css +132 −19
Large diff (164 lines) is not loaded by default to keep the page fast.Load diff
Menu

Theme