neuron/neuron-dev-setup/README.md

# neuron-dev-setup — one-command Neuron CORE dev stack

Stand up an identical **Neuron brain + agent** on a fresh Mac so any developer
gets the same local runtime to build against. This is the **CORE** dev stack
only — the four native `launchd` services that make Neuron think, remember, and
speak MCP to Claude Code. Will's personal automations (catalyst, telegram,
vessels, studio, self-review, world-integrator, council, compressor, snapshots,
act-runner, …) are **deliberately excluded**.

```
  ┌─────────────┐        ┌──────────────┐
  │  soul :7770 │ ─────► │ engram :8742 │     the mind ──► its memory substrate
  └─────────────┘        └──────────────┘
        ▲
        │
  ┌───────────────────┐
  │ mcp-wrapper :17779│  ─── MCP surface over the soul HTTP API (internal)
  └───────────────────┘
        ▲
        │
  ┌────────────────┐
  │ mcp-proxy :7779│  ◄─── Claude Code connects here (stable front door)
  └────────────────┘
```

Claude Code's `neuron` MCP server points at `http://127.0.0.1:7779/` — the proxy.
The proxy forwards to the wrapper (`:17779`), which calls the soul (`:7770`),
which reads/writes the engram (`:8742`). The engram is the persistent brain.

## Quick start

```bash
git clone <this-repo> && cd neuron-dev-setup
cp config.env.example config.env      # optional — edit ports/paths if you like
./install.sh                          # prompts for your Anthropic API key
```

Then verify:

```bash
curl http://localhost:8742/health     # engram
curl http://localhost:7770/health         # soul
curl http://localhost:7779/health         # mcp-proxy (what Claude Code uses)
launchctl list | grep ai.neuron
```

Open Claude Code — the `neuron` MCP tools should be live, backed by **your own**
local brain. `./install.sh --dry-run` shows every action without touching anything.

## What the installer does (8 phases)

| Phase | Action |
|------|--------|
| 1 | Preflight: macOS/arm64, ensure `git cc curl python3` + `openssl@3` (via Homebrew) |
| 2 | Prompt for the **Anthropic API key**, store it in the **macOS Keychain** (never a file) |
| 3 | Clone `neuron`, `engram`, `foundation`; fetch the El toolchain; build 4 binaries + `forge` |
| 4 | Lay down `~/.neuron/{bin,logs,engram}` and the templated `soul-wrapper.sh` |
| 5 | Generate + load the 4 core LaunchAgents (engram → soul → wrapper → proxy) |
| 6 | Seed a fresh engram with the **genesis identity** via `forge install` |
| 7 | Install Claude config: `neuron` agent, core hooks, local MCP registration |
| 8 | Health-check all four ports |

Everything is **idempotent** (safe to re-run) and **templated** to the invoking
user's `$HOME` — no path is hardcoded to another machine.

## Prerequisites

- macOS on Apple Silicon (uses `launchd`; soul build flags assume arm64).
- **Xcode Command Line Tools** (`xcode-select --install`) — provides `cc`, `git`.
- **Homebrew** — for `openssl@3`, `curl`.
- An **Anthropic API key** — the soul's inference provider. Prompted for; stored
  in Keychain under service `neuron-llm-0-key`; read at launch by `soul-wrapper.sh`.
- **Git access** to Gitea (`git.neuralplatform.ai`) for the source repos.
- **GCP access** to project `neuron-785695` Artifact Registry (default El
  toolchain source). Ask Will to grant it, or set `EL_TOOLCHAIN_SOURCE=local`.

## Core-stack map (what gets replicated)

| Service | Port | Binary | Built from | LaunchAgent |
|---------|------|--------|------------|-------------|
| soul | 7770 | `neuron/dist/neuron` | `dist/soul.c` + El runtime, `cc` (CI recipe) | `ai.neuron.soul` |
| engram | 8742 | `engram/dist/engram` | `engram` repo `src/server.el` via `elc`→`cc` | `ai.neuron.engram` |
| mcp-wrapper | 17779 | `neuron/mcp-wrapper/dist/neuron-mcp-wrapper` | `mcp-wrapper/src/main.el` | `ai.neuron.mcp-wrapper` |
| mcp-proxy | 7779 | `neuron/mcp-proxy/dist/neuron-mcp-proxy` | `mcp-proxy/src/main.el` | `ai.neuron.mcp-proxy` |

**`~/.neuron` layout the installer creates**

```
~/.neuron/
  bin/soul-wrapper.sh     # reads Anthropic key from Keychain, execs the soul binary
  logs/                   # soul.*.log, engram.log, mcp-*.log
  engram/                 # ENGRAM_DATA_DIR — the persistent brain (snapshot.json + db)
```

**Identity seed.** `foundation/forge/seeds/neuron-genesis-seed.json` carries
`identity_nodes[]` + `edges[]` with **fixed** knowledge-node IDs (e.g.
`kn-efeb4a5b-5aff-4759-8a97-7233099be6ee`, the "self" traversal root). Those exact
IDs are referenced by the SessionStart self-load hook and the neuron agent, so
seeding must **preserve IDs** — `forge install <seed>` is the mechanism.

**Claude config installed** (`~/.claude/`)

- `agents/neuron.md` — the Neuron agent (identity, session protocol, five primitives).
- `mcp.json` — registers `neuron` → `http://127.0.0.1:7779/`.
- `settings.json` hooks (CORE subset only):
  - `SessionStart` → `neuron-self-load.sh` (loads identity from the seeded engram)
  - `PreToolUse:Agent` → `neuron-agent-preamble.sh` (subagents load substrate first)
  - `PreCompact` → `pre-compact.sh` (clean context recovery)

### Deliberately EXCLUDED from core

- **`check-active-contexts.sh`** and **`require-execution-context.sh`** — these
  depend on a separate filesystem repo `~/Development/projects/active/neuron/synapse`.
  `require-execution-context.sh` is a hard `Edit/Write` gate that would **block a
  fresh dev from editing any file** without that synapse repo. Not core; excluded.
- `engram-mirror.py` (PostToolUse) — optional; mirrors MCP writes to engram.
- All Will-personal LaunchAgents: `catalyst-*`, `telegram-gateway`, `vessel.*`,
  `studio`, `self-review`, `world-integrator`, `council`, `compressor`,
  `cultivation-digest`, `snapshot-backup`, `engram-backup`, `act-runner`, `keymap`,
  `invest`, and the disabled `ai.neuron.api` (`:7771` is a personal Python
  perception helper — confirmed not core).

## Secrets — how they're handled

- **Anthropic key**: prompted for; stored in Keychain; read at launch. Never in a
  plist, this repo, or a log.
- **Engram local token** (`ENGRAM_API_KEY`): a *loopback-only* dev token, not a
  cloud secret. Defaults to a generated `ntn-dev-*` value; override in `config.env`.
- No cloud tokens, Vault tokens, CF-Access secrets, or founder keys are copied.
  (Will's live `start-daemon.sh`/`neuron-api-launch.sh` contain such keys — this
  installer intentionally does **not** use those files.)

## Uninstall

```bash
./uninstall.sh                # stop + remove the 4 LaunchAgents and added Claude hooks
./uninstall.sh --purge-data   # ALSO delete ~/.neuron/engram (destroys the brain)
```

## OPEN QUESTIONS (need Will to confirm)

1. **El toolchain acquisition.** The default path fetches `el-runtime-c/-h` and
   `el-elc` from GCP Artifact Registry (mirrors `neuron/.gitea/workflows/ci.yaml`).
   A new dev needs GCP access to `neuron-785695`. Is that the intended path, or
   should the El SDK be published/vendored for onboarding?
2. **`elc` invocation for engram/wrapper/proxy.** The soul build (`cc dist/soul.c
   + el_runtime.c`) is verified from CI. The `.el → .c` transpile step for engram,
   mcp-wrapper, and mcp-proxy is inferred (`elc <src> -o <out.c>`). Confirm the
   exact flags / entrypoints (CI notes `elb` OOMs on Linux; macOS builds differ).
3. **`forge install` ID preservation.** Confirm `forge install` writes the seed's
   fixed `kn-` IDs verbatim (the self-load hook hardcodes `kn-efeb4a5b…`). If it
   re-mints IDs, the hook + agent identity load would break on a fresh brain.
4. **engram repo layout.** The live engram binary is built from `src/server.el`
   (Gitea repo `neuron-technologies/engram`, cloned in CI). Confirm that repo is
   the canonical source for onboarding (the local `foundation/el/engram` copy has
   the same `src/server.el`).
5. **Home for this bundle** — see below.

## Where this should live (recommendation)

**Recommendation: a dedicated `neuron-dev-setup` (or `neuron-onboarding`) repo —
NOT `neuron-code`.** `neuron-code` already exists as a real product ("Neuron Code",
a coding tool with `nc-cli` + vessels — local `products/neuron-code` has commits);
repurposing it for onboarding would collide with a shipped product's identity.

This bundle was scaffolded as `neuron-dev-setup/` on branch `feat/neuron-dev-setup`
in the **`neuron` repo** (off `origin/main`) and opened as a PR for review, because
the neuron repo already hosts the soul source, the verified CI build recipe, and
the mcp-wrapper/proxy sources — the natural review surface. If you'd rather it be
its own repo, move this directory into a fresh `neuron-dev-setup` repo verbatim;
nothing here depends on living inside the neuron repo.