track the architecture docs

They were written outside git, so the reasoning that produces the design
had no history and no way to be superseded. capabilities.md and
geometry-vs-code.md are both known stale at this commit; they are tracked
as-is so the corrections are visible as movement rather than as a rewrite.

design/completing-el.html

@@ -0,0 +1,153 @@
+<title>Completing El</title>
+<style>
+:root{
+  --board:#f4f2ec; --board-line:#e2ded2; --ink:#1c1f26; --ink-soft:#4a5160;
+  --ink-faint:#8b8f9a; --rule:#d8d3c6; --card:#fbfaf6;
+  --red:#a8321e; --amber:#9a6a12; --green:#2f6b46; --blue:#1f4e79;
+  --accent:#1f4e79;
+}
+@media (prefers-color-scheme: dark){
+  :root:not([data-theme="light"]){
+    --board:#14161b; --board-line:#212530; --ink:#e8e6df; --ink-soft:#a8adb8;
+    --ink-faint:#6f7480; --rule:#2a2f3a; --card:#191c23;
+    --red:#e4785f; --amber:#d9a441; --green:#6fbf8e; --blue:#7fb2e0;
+    --accent:#7fb2e0;
+  }
+}
+:root[data-theme="dark"]{
+  --board:#14161b; --board-line:#212530; --ink:#e8e6df; --ink-soft:#a8adb8;
+  --ink-faint:#6f7480; --rule:#2a2f3a; --card:#191c23;
+  --red:#e4785f; --amber:#d9a441; --green:#6fbf8e; --blue:#7fb2e0;
+  --accent:#7fb2e0;
+}
+*{box-sizing:border-box}
+body{
+  margin:0; background:var(--board); color:var(--ink);
+  font:16px/1.65 ui-serif,Georgia,"Iowan Old Style",Palatino,serif;
+  background-image:linear-gradient(var(--board-line) 1px,transparent 1px),
+                   linear-gradient(90deg,var(--board-line) 1px,transparent 1px);
+  background-size:28px 28px;
+}
+.wrap{max-width:960px;margin:0 auto;padding:56px 24px 96px}
+.mono{font-family:ui-monospace,SFMono-Regular,Menlo,Consolas,monospace}
+header{border-bottom:2px solid var(--ink);padding-bottom:18px;margin-bottom:8px}
+h1{font-size:clamp(2rem,5vw,3rem);margin:0;letter-spacing:-.02em;text-wrap:balance}
+.sub{color:var(--ink-soft);font-size:1.05rem;margin:10px 0 0}
+.meta{font-family:ui-monospace,SFMono-Regular,Menlo,monospace;font-size:.78rem;
+  color:var(--ink-faint);text-transform:uppercase;letter-spacing:.09em;margin-top:14px}
+h2{font-size:1.45rem;margin:52px 0 6px;letter-spacing:-.01em}
+h2 .n{font-family:ui-monospace,monospace;font-size:.8rem;color:var(--accent);
+  display:block;letter-spacing:.12em;margin-bottom:4px;font-weight:400}
+.lede{color:var(--ink-soft);margin:0 0 18px}
+p{margin:0 0 14px}
+.card{background:var(--card);border:1px solid var(--rule);border-radius:3px;padding:20px 22px;margin:16px 0}
+.scroll{overflow-x:auto;-webkit-overflow-scrolling:touch}
+table{border-collapse:collapse;width:100%;font-size:.9rem;min-width:640px}
+th{text-align:left;font-family:ui-monospace,monospace;font-size:.72rem;
+  text-transform:uppercase;letter-spacing:.09em;color:var(--ink-faint);
+  border-bottom:1px solid var(--ink);padding:0 12px 8px 0;font-weight:400}
+td{padding:11px 12px 11px 0;border-bottom:1px solid var(--rule);vertical-align:top}
+td.f{font-weight:600;white-space:nowrap}
+td.m{font-family:ui-monospace,monospace;font-size:.83rem;font-variant-numeric:tabular-nums}
+.dead{color:var(--red);font-weight:600}
+.part{color:var(--amber);font-weight:600}
+.ok{color:var(--green);font-weight:600}
+blockquote{margin:18px 0;padding:2px 0 2px 20px;border-left:3px solid var(--accent);
+  color:var(--ink-soft);font-style:italic}
+ul{margin:0 0 14px;padding-left:22px} li{margin-bottom:9px}
+.q{border-left:3px solid var(--amber);padding:14px 0 14px 20px;margin:18px 0}
+.q b{display:block;font-size:1.05rem;margin-bottom:5px;font-style:normal}
+.q span{color:var(--ink-soft);font-size:.94rem}
+code{font-family:ui-monospace,monospace;font-size:.88em;background:var(--card);
+  border:1px solid var(--rule);border-radius:2px;padding:1px 5px}
+hr{border:0;border-top:1px solid var(--rule);margin:44px 0}
+.foot{color:var(--ink-faint);font-size:.86rem;margin-top:60px;
+  border-top:1px solid var(--rule);padding-top:18px}
+.tag{display:inline-block;font-family:ui-monospace,monospace;font-size:.68rem;
+  letter-spacing:.08em;text-transform:uppercase;border:1px solid var(--rule);
+  border-radius:2px;padding:2px 7px;color:var(--ink-faint);margin-left:8px;vertical-align:middle}
+</style>
+
+<div class="wrap">
+
+<header>
+  <h1>Completing El</h1>
+  <p class="sub">A working surface. Nothing here is settled, and none of the code is assumed right — El is self-hosting, so all of it can change and be rebuilt.</p>
+  <p class="meta">Whiteboard v0 · no sacred cows · not a plan, not a task list</p>
+</header>
+
+<h2><span class="n">01</span>What we established</h2>
+
+<p>El is a <b>concept-oriented language</b> — the first, and intended as the last, because every other family is oriented toward a <em>representation</em> of a concept rather than the concept. Procedures, objects, functions, predicates are the shapes concepts get flattened into. Once the primitive is the concept, there is no further rung.</p>
+
+<p>Everything here is El. The engram is an El program, the soul is El, <code>elp</code> is El, ingest is El. Which gives the load-bearing consequence:</p>
+
+<blockquote>A concept with no home in El does not disappear. It becomes C, or it becomes a convention.</blockquote>
+
+<p>Both are measurable, and both were measured. As C: <span class="mono">20,504</span> lines of <code>el_runtime.c</code> — 2.3× the entire self-hosting language it serves (<span class="mono">9,089</span> lines), ~47% of it engram code that has its own six sibling files. As convention, from <code>language.md</code> §18.0 — <em>"these are not four problems, they are one absence, four times"</em>:</p>
+
+<div class="card scroll">
+<table>
+<thead><tr><th>Concern</th><th>Fragments</th><th>The convention it became</th></tr></thead>
+<tbody>
+<tr><td class="f">Process identity</td><td class="m">0 guards</td><td>"check nothing is already running first"</td></tr>
+<tr><td class="f">Configuration</td><td class="m">20 env vars</td><td>"remember the right default here"</td></tr>
+<tr><td class="f">Durability</td><td class="m">62 call sites</td><td>"after you mutate, remember to persist"</td></tr>
+<tr><td class="f">Request auth</td><td class="m">10 per-route</td><td>"check the token in this handler too"</td></tr>
+<tr><td class="f">Index-after-append</td><td class="m">9 of 9 failed</td><td>"after you append, remember to index"</td></tr>
+</tbody>
+</table>
+</div>
+
+<p>The last row is the strongest evidence available about what this class of convention is worth: it failed at <b>100% of its sites</b>.</p>
+
+<h2><span class="n">02</span>The decomposition axis</h2>
+
+<p class="lede">Not by file, module, or subsystem. <b>By faculty.</b></p>
+
+<p>Every defect fought in the last day resolves to a faculty rather than a bug, and each one leaked out of El into something else — into C, into a Swift binary, into a shell script with a curl timeout, into a convention nobody performs.</p>
+
+<div class="card scroll">
+<table>
+<thead><tr><th>Faculty</th><th>State</th><th>Measured</th><th>Where it leaked to</th></tr></thead>
+<tbody>
+<tr><td class="f">Ingest <span class="tag">take in</span></td><td class="dead">dead</td><td class="m">2 min → 0 nodes</td><td>separate process, uploads bytes over HTTP to a process with direct fs access; 5 functions where there is 1</td></tr>
+<tr><td class="f">Recall <span class="tag">remember</span></td><td class="dead">dead</td><td class="m">own definition ranked 8th</td><td>lexical substring scan; empty on 23 of 24 multi-token queries</td></tr>
+<tr><td class="f">Transduce <span class="tag">perceive</span></td><td class="dead">dead</td><td class="m">1 node, 0 edges</td><td>intake flattens signal to a point; <code>realized:false</code>; caller must declare the modality</td></tr>
+<tr><td class="f">Think <span class="tag">reason</span></td><td class="dead">dead</td><td class="m">direction [0,0,0,…]</td><td>null gradient from any anchor, any faculty, byte-identical; confidence at the uninformed prior</td></tr>
+<tr><td class="f">Realize <span class="tag">express</span></td><td class="part">partial</td><td class="m">13-word vocabulary</td><td>organ was 939 lines of Swift beside the language; voice read from a file path</td></tr>
+<tr><td class="f">Body <span class="tag">substrate</span></td><td class="part">partial</td><td class="m">CC 356 / 1,626 lines</td><td><code>engram_activate_inner</code> — recall itself, with 356 unexamined paths</td></tr>
+<tr><td class="f">Persist <span class="tag">endure</span></td><td class="ok">live</td><td class="m">100% embedded</td><td>works; every signal placed in geometry at intake, 13,562 of 13,562</td></tr>
+</tbody>
+</table>
+</div>
+
+<p>Stated plainly: it cannot take in, cannot remember, cannot perceive, cannot reason, and barely speaks. These were filed as tickets against a repository. They are faculties of the thing the repository <em>is</em>.</p>
+
+<h2><span class="n">03</span>The ordering principle</h2>
+
+<p>El's compiler is written in El. Every concept the language gains, the compiler can then be written <em>in</em> — so the tool improves the tool, and the fixpoint (stage2 ≡ stage3, byte-identical) makes each turn provable rather than hopeful. The verifier answers in <span class="mono">2.9s</span>.</p>
+
+<p>Which means the ordering criterion is not size of payoff:</p>
+
+<blockquote>Order by leverage on the <em>next</em> iteration. Which concept, added to El, most increases the ability to add the following one?</blockquote>
+
+<p>In a recursive system that dominates immediate value — a small early gain that compounds beats a large one that doesn't. It also bounds itself correctly: unbounded in depth, bounded in rate, because nothing lands that the compiler and the fixpoint have not passed.</p>
+
+<h2><span class="n">04</span>Open — for the whiteboard</h2>
+
+<div class="q"><b>What does a declaration bind to?</b><span>If <code>cat</code> names a region rather than a struct — one that shifts and completes against the engram and the neighbouring code — then what is written at the declaration site, and what is resolved at use? This is the centre of the whole thing and it is not specified anywhere yet.</span></div>
+
+<div class="q"><b>Is "the type checker" a type checker at all?</b><span>§2.3 records annotations as parsed and skipped, and every codegen hazard is downstream of that — <code>+</code> dispatching on AST node kind, <code>==</code> lowering to <code>str_eq</code> unless both operand names are in an int-name set. But if a declaration names a region, checking is asking whether the geometry supports the use. That is grounding, not unification. Naming this wrong builds the wrong thing.</span></div>
+
+<div class="q"><b>Is the faculty list above right?</b><span>Seven were derived from what broke. Derived-from-failure is a biased sample — it finds what is loud, not what is missing. What faculty is absent entirely and therefore never failed?</span></div>
+
+<div class="q"><b>Which concept has the highest leverage on the next turn?</b><span>Candidates so far: the prologue/epilogue seam (§19.3 names it as the prerequisite and its stated blocker has expired — it would collapse 62 + 10 convention sites); <code>protocol</code>/<code>impl</code> (the absence that produced five ingest functions); and the resolution question above. These are not equal and the criterion in §03 should decide it, not preference.</span></div>
+
+<div class="q"><b>What is the seam that makes cognition non-optional?</b><span>"Use the ops" is itself a convention — present in context every turn, enforced by nothing, and it failed at ~100% of sites in a full session. A stronger instruction is still a convention. What makes reasoning-outside-Neuron <em>fail</em>, the way <code>@manager</code> makes <code>dharma_emit</code> outside the boundary a compile error rather than a lint?</span></div>
+
+<hr>
+
+<p class="foot">Working surface, not a design document. The design is what we put on it. Everything above is either measured or quoted from <code>lang/spec/language.md</code>; nothing is inferred and presented as fact.</p>
+
+</div>