el/tools/neuron-sandbox/STACK.md

sandbox — the Neuron STACK sandbox

Work on a whole stack at once, not one repo at a time. sandbox assembles every constituent repo of a named stack into one combined worktree workspace, wired so they build and run together, on an isolated clean base — then tears it all down cleanly. The live soul/engram (:7770 / :8742) are never touched.

It is the multi-repo sibling of nsbx: where nsbx dev stands up one repo's worktree + an isolated engram, sandbox stands up every repo of a stack as sibling git worktrees under a single workspace.

export PATH="$PWD:$PATH"            # or symlink `sandbox` onto your PATH

sandbox neuron-stack tim           # el + neuron soul + NeuronUI, assembled together
cd ~/Development/neuron-technologies/stack-worktrees/neuron-stack-tim
source .stack-env                  # EL_REPO + PATH now point at the SANDBOX el
./build.sh                         # engram compiles, soul compiles, UI present & buildable
sandbox down neuron-stack tim      # remove every worktree; live untouched

The two profiles

el-stack — the whole EL kit

The compiler + language + framework + tooling are all one repo (foundation/el: lang/ = elc/elb + runtime, engram/src/server.el, elp/ = NLG, ui/ = the el-ui framework, plus ql, ide, epm, arbor, tools). Its downstream SDK consumers come along so a change to elc can be proven end-to-end across the kit.

repo	required	role
foundation/el	✓	elc + elb compiler, el_runtime, engram source, el-ui framework, elp/ql/ide/epm tooling
engram-language		language-faculty reference POC (Python) — being ported into el/elp
foundation/forge		downstream SDK consumer — make build
foundation/dharma		downstream SDK consumer — CGI provenance registry

build.sh proves it: elc compiles a real stack source and cc links it against the runtime into a native binary (elc + runtime build together), and — if present — forge builds against the freshly-assembled SDK.

neuron-stack — the full product

Substrate + soul + UI. Engram is not a separate repo — its source lives inside foundation/el.

repo	required	role
foundation/el	✓	substrate: elc + el_runtime + engram source + the elp NLG the soul imports
neuron	✓	the soul (:7770) + engram build; soul.el imports ../foundation/el/elp/src/elp.el
products/NeuronUI	✓	the app/UI (Kotlin/Compose desktop client; bundles the soul binary)
products/web		marketing site + interactive soul-demo

build.sh proves it: engram builds (elc engram/src/server.el → cc … el_runtime.c → native binary), the soul compiles with its cross-repo ../foundation/el import resolving to the sandbox el, and the UI is present with its build entry.

Why it works — mirrored-layout wiring

The repos reference each other by relative sibling paths (e.g. the soul imports ../foundation/el/elp/src/elp.el). So sandbox lays every worktree out at its natural relative path inside the workspace:

stack-worktrees/neuron-stack-tim/
├── foundation/el/          ← worktree of foundation/el   (the sandbox el)
├── neuron/                 ← worktree of neuron
└── products/NeuronUI/      ← worktree of products/NeuronUI

From neuron/, ../foundation/el resolves to …/neuron-stack-tim/foundation/el — the sandbox copy, never the live tree. No symlinks, no path rewriting: the layout is the wiring. .stack-env additionally pins EL_REPO and prepends the sandbox elc/elb to PATH.

Commands

command	does
sandbox el-stack <name> [--minimal]	assemble the EL kit (--minimal = required repos only)
sandbox neuron-stack <name> [--minimal]	assemble the full product
sandbox build <profile> <name>	run the workspace's combined build.sh
sandbox status <profile> <name>	per-repo head + clean/dirty
sandbox list	list assembled workspaces
sandbox down <profile> <name> [--delete-branch]	remove every worktree + drop the workspace (branch kept unless --delete-branch)

Flags: --minimal (required repos only), --branch B (branch name; default sandbox/<profile>-<name>), --base REF (fork point; default each repo's committed HEAD).

Rails (always)

• Clean base — worktrees fork off each repo's committed HEAD; the dirty state of the live checkout is deliberately not carried in.
• Persistent — the workspace lives under NSBX_STACK_ROOT (default ~/Development/neuron-technologies/stack-worktrees), never /tmp (ablated on compaction).
• Never touches live — sandbox only does git worktree + offline cc. It never binds :8742/:7770, never launchctl, never pkill. Bringing up an isolated engram is delegated, opt-in, to nsbx (which guards the live store and refuses the live ports).
• Idempotent & safe — refuses to clobber an existing workspace; a failed assembly rolls back its partial worktrees; teardown removes worktrees through their origin repo and prunes.
• Own-the-core — pure bash + git worktree. No new dependencies.

Env knobs

NSBX_STACK_ROOT (workspace root), NEURON_DEV_ROOT (the dir holding all the peer repos, default ~/Development/neuron-technologies).

Isolated engram for neuron-stack (opt-in)

sandbox gets the code building together; to run the soul against an isolated engram (never live), delegate to nsbx from inside the workspace:

source .stack-env
nsbx create $STACK_NAME --source "$EL_REPO"    # clone live store onto a non-default port
nsbx up     $STACK_NAME
nsbx status $STACK_NAME                          # prints the isolated engram URL