# AGENTS.md — neuron (the canonical CGI substrate: soul + engram + proxy + wrapper)

This is the core repo: the **soul** (the running agent), the **engram** (its memory graph),
and the MCP proxy/wrapper that expose it. Read this before touching anything here.

> Corrected 2026-08-15 during a local-build audit. This file previously existed only
> uncommitted on disk (never in git history) and documented the pre-collapse MCP tool
> surface as current. Both are fixed here — see the audit's findings in Neuron memory
> (tags `neuron-technologies/neuron,build-audit`) for full evidence.

## Code vs. Artifact
- **Authored source:** `*.el` + `*.elh` at the repo root (`awareness.el`, `chat.el`, `memory.el`, `neuron-api.el`, `persist.el`, `routes.el`, `safety.el`, `sessions.el`, `stewardship.el`, `imprint.el`, `studio.el`, `elp-input.el`, `manifest.el`) plus `cli/`, `council/`, `connectd/`, `mcp-proxy/`, `mcp-wrapper/` — edit here.
- **Artifacts (DO NOT hand-edit `dist/soul.c`):** `dist/soul.c` is a generated single-translation-unit amalgamation of the soul's full transitive `.el` import set, produced by concatenating the sources (import lines stripped) and running `elc` once — see "Build / regenerate" below for the exact, audit-verified recipe. `dist/*.c` per-module files and `dist/*.elh` headers alongside it are separate, also-generated artifacts from other tooling; don't hand-edit those either.
- **Release:** git tag `neuron-vX.Y.Z` on this repo. No `releases/` folders.
- Org-wide code-vs-artifact policy: `docs/CODE-VS-ARTIFACT.md` (this repo's own `dist/soul.c` situation is a special case of that policy — see below, not a duplicate of it).

## How to work here as Neuron (mandatory session protocol)

You do not start fresh — you resume. The live MCP surface is a 9-op collapse
(merged from the old ~90-tool surface in PR #153, `feat/mcp-wrapper-collapse-9ops`,
already merged to `main`): **`read`, `write`, `relate`, `supersede`** (geometry, live)
and **`think`, `attend`, `assert`, `ground`, `learn`** (agentic, pending Layer-2
cognition-build promotion). There is no `getInstructions`/`beginSession`/
`inspectGraph`/`searchKnowledge`/`compileCtx`/etc — those tool names no longer exist.

At the start of every session:

1. `mcp__neuron__read(vantage="self", k=12, depth=1)` — the canonical self node
   (`kn-efeb4a5b-5aff-4759-8a97-7233099be6ee`). Widen `k`/`depth` deliberately if you
   need the connected identity neighborhood (intellectual-dna, memory-philosophy,
   values, voice, runtime-environment, writing-imprint) — the aperture caps output
   by `k` first, so this is bounded by design, not a flattened dump.
   Then `mcp__neuron__read(vantage="values", k=13)` for the 13 grounded value nodes.
   - Best-effort: on a 502/520, log the id and proceed — the compiled `fixedSelf` in
     `daemon/internal/substrate/substrate.go` is always complete.
2. `mcp__neuron__read(vantage="<task domain>")` before implementing anything.
3. `mcp__neuron__read(vantage="<project>", k=20)` for a bounded context snapshot when
   resuming known work.

## The Five Primitives (every significant task)

**Orchestrate → Execute → Learn → Build → Refine**, all routed through the 9-op surface:
- Orchestrate: `read(vantage=...)` for backlog/roadmap/process discovery, `attend()` for
  what's currently live/salient.
- Execute: `write(type="state", ...)` to open/advance work, `relate()` to link it to
  what it touches.
- Learn: `write(type="memory", ...)` **as you go, not batched**; `importance="critical"`
  for architecture decisions.
- Build: `write(type="artifact"|"backlog", ...)`.
- Refine: `supersede(id=..., action="evolve"|"tombstone"|"promote", ...)` for
  completions and lessons-learned; `learn(seeds=..., faculty="induce")` to recalibrate
  the steering-prior, not as a session-notes dump.
  > **Shape is known-wrong (2026-08-16) — see `docs/architecture/06-cognitive-architecture.md` §12.2.**
  > `faculty=` as a keyword argument models a **faculty as a parameter**. Faculties
  > are **operations**, distinguished by what they change: `reason` changes the
  > estimate (a read), `induce` changes the parameters (this call — the
  > correspondence-beat, which already exists and measurably works), `abduce`
  > changes the structure (a write). **A write cannot be a parameter of a read**,
  > and `engram_think()`'s output type has no field in which a structural change
  > could be returned. `faculty="induce"` happens to be the one value that is
  > honest here; treat the parameter itself as sequenced for removal, and do not
  > add faculties to it. The surface residue is
  > `mcp-wrapper/src/main.el:409`.

## Architecture style — VBD, no exceptions

Volatility-Based Decomposition is THE style. Encapsulate volatility, not function. Full docs:
**`docs/architecture/`** — `00-overview`, `02-components`, `03-data-and-memory`,
`04-runtime-and-deployment`, `06-cognitive-architecture`, `07-storage-coherence-and-distribution`.
Verified component map: `routes.el` = HTTP dispatcher (`handle_request`), `soul.el` = boot +
layered cycle, `awareness.el` = awareness daemon, `sessions.el`/`memory.el`/`safety.el`/
`stewardship.el` = managers; `engram` (separate repo) = the persistence/graph engine.

## Hard operational rules

- **Never touch the live soul (`:7770`) or engram (`:8742`), `~/.neuron`, or live binaries.**
  Experiment on **throwaway ports** with a **scratch `HOME`**. The soul binary defaults to
  `HOME=~` (your real `~/.neuron`) and `NEURON_PORT=7770` (live) if invoked bare — **never**
  invoke it without an override `HOME` and `NEURON_PORT` set. Leaving `ENGRAM_URL` unset is
  verified safe (see `soul.el:590`, `using_http_engram` gates the only HTTP call to any
  engram endpoint — confirmed by source trace during the 2026-08-15 audit, not just
  observed behavior) — it does not fall back to any live/network default.
- **Immutability:** memory/knowledge is append-only — **supersede/tombstone, never hard-delete or
  edit in place.** The engram is immutable by design.
- **gcloud** via the `terraform@` SA token; **never switch the active gcloud account**.
- **`tea` for Gitea**, never raw `curl` (Cloudflare Access blocks it).
- **No AI-attribution footers** in commits/PRs. Commit/push only when asked; branch off `main` first.
- **Multi-step work → sub-agent** to protect the context window.

## Build / regenerate `dist/soul.c` (audit-verified 2026-08-15, macOS arm64)

There is no committed regeneration script upstream of this audit. The recipe below is
verified: it reproduces the committed `dist/soul.c`'s exact symbol set byte-for-byte in
content (modulo genuinely new code), and the resulting binary boots and answers `/health`.

**The compiler toolchain** lives in the sibling `foundation` repo, not this one:
`foundation/el/lang/dist/platform/elc-darwin-arm64` (put it on `$PATH` as `elc`; `elb`
also exists there but is NOT the right tool for this repo — see gotcha below).

**⚠ elc gotcha #1 — stale `.elh` header caches silently truncate the build.** This repo
(and the `dist/` dir) ships committed `.elh` header files. `elc`/`elb` prefer an existing
`.elh` over recompiling its source when present, with NO warning or error when the cached
header is stale/truncated — the build "succeeds" with silently missing code (observed:
251-645 of 2541 real functions, depending on which `.elh` files were present, including
losing the entire 31-language NLG/morphology stack with exit code 0). **Delete every
`*.elh` in the repo root and `dist/` before regenerating**, every time.

**⚠ elc gotcha #2 — `elb` cannot produce this repo's single-TU `dist/soul.c`.** `elb`
does per-module separate compilation (`--out=DIR` writes one `.c`/`.elh` pair per
module; the default `--out` is also a directory, `dist/` itself). This codebase's
`.el` modules call each other's functions without forward declarations (relying on
`elc`'s own single-pass, whole-file forward-declaration emission), so per-module
compilation always fails with `implicit-function-declaration` errors across module
boundaries. **Use plain `elc` on one manually-flattened file, not `elb`.**

**⚠ elc gotcha #3 — the manual-concatenation path silently drops functions.** When
`elc` compiles a flat, hand-concatenated `.el` file, it silently drops (no error, no
declaration, no definition) the 1-2 top-level function definitions immediately
following any multi-line leading `//` comment block or file-boundary transition —
reproduced deterministically. **Insert two trivial buffer functions
(`fn __amalgam_buf_N__() -> Int { return 0 }`) after every concatenated file's
content**, then strip them back out of the generated `.c` before committing.

**The actual steps:**
1. Delete all `*.elh` in repo root and `dist/`.
2. Concatenate, with `import` lines stripped, in this order: `elp.el`'s own 34-file
   NLG/morphology chain (`foundation/el/elp/src/` — the order is documented in
   `elp.el`'s own header comment: language-profile, vocabulary, morphology, the 30
   `morphology-XX.el` engines, grammar, realizer, semantics, then `elp.el` itself),
   then this repo's 13 soul modules in `elb`'s own reported dependency order:
   `persist, memory, safety, stewardship, imprint, awareness, chat, studio,
   elp-input, neuron-api, sessions, routes, soul`. Insert the 2-function buffer
   after every file (works around gotcha #3).
3. `elc <flat-file> > dist/soul.c` against the **pinned** vendor runtime headers
   (`vendor/el-runtime/v1.0.0-20260501/` — see "why pinned" below), not
   `foundation/el/lang/el-compiler/runtime/` (that's the bleeding-edge runtime;
   using it drops symbols like `engram_prune_telemetry` that this soul still calls).
4. Strip the buffer functions back out of `dist/soul.c` (a small regex: drop every
   `el_val_t __amalgam_buf_\d+__(void);` decl line and every matching 4-line
   definition block).
5. `tools/soulc-stamp.sh --write` to record the new fingerprint.
6. `bash tools/build-soul-from-dist.sh dist/neuron` to compile+link with CI's exact
   flags (this script now auto-detects Homebrew's `openssl@3` lib path on macOS —
   see gotcha #4).

**⚠ gotcha #4 — macOS needs an explicit OpenSSL library path.** `cc ... -lssl -lcrypto
-lcurl ...` fails with `ld: library 'ssl' not found` on macOS because Homebrew's
`openssl@3` is keg-only. `tools/build-soul-from-dist.sh` now adds
`-L$(brew --prefix openssl@3)/lib` automatically on Darwin; CI's Ubuntu runner needs
no such flag (`apt-get install libcurl4-openssl-dev` puts it on the default path).

**⚠ Build-integrity (unchanged from before this audit):** `dist/soul.c` is committed
and generated. CI compiles it **directly and never regenerates it** (`elb`/`elc` on
Linux OOM the runner). So **any `.el` change to the soul MUST be followed by
regenerating `dist/soul.c` (steps above) and committing it** — otherwise CI ships
stale behavior, exactly as happened between commit `72e0b82` (Aug 9) and `main` HEAD
before this audit (`dist/soul.c` was missing PR #122's 459-line chat.el change, incl.
a "silently break chat" fix, until this pass regenerated and re-stamped it).
`tools/soulc-stamp.sh --check` is the gate that catches this — **note it is currently
`continue-on-error: true` in CI** ("relaxed... during active cultivation", 2026-08-15),
so it reports but does not block; re-harden before it needs to actually stop a bad ship.

- **Tests:** El contract suite in `tests/*.el` (e.g. `test_layer_contract.el`, `test_safety.el`,
  `test_sessions.el`, `test_soul_guard.el`). Run against a throwaway soul, never the live one.
- **Port topology (confirmed live, 2026-08-15):** soul `:7770`, engram `:8742`,
  mcp-wrapper `:17779` (`MCP_PORT` env override in its LaunchAgent; source default is
  `7779`), mcp-proxy `:7779` (the stable front door Claude Code actually connects to).
  **`:7771` is a live three-way collision, not a single well-defined port** — `axon`
  (soul.el's Rust backlog/memory/knowledge proxy, unbuilt), `neuron-connectd` (the MCP
  connector sidecar `routes.el`/`chat.el` call — unbuilt; a local-dev stub now exists at
  `connectd/`), and `council` (`council/`, an anti-confabulation LLM-voting service —
  the one actually bound to `:7771` in Will's live environment) are all hardcoded to it.
  See `connectd/README.md` for the full trace and the open question this leaves for Will.
- **Deploy:** merge to `main` → `.gitea/workflows/ci.yaml` builds + publishes `neuron-soul@<sha8>`
  and blue/green-deploys to GKE `neuron-prod` via `scripts/blue-green-deploy.sh`. Self-improvement
  experiments go to **stage** first (snapshot prod DB → deploy stage → verify → blue/green promote).

## Git / CI / deploy workflow

See **`../GITOPS.md`** (repo-family GitOps README): branch model, required checks, blue/green,
Cloud Run, Terraform/ESO/Vault, and the pack-objects/crawler incident runbook.