Home

spikeforge — long-form reference

This folder holds the detailed, implementation-oriented documentation for spikeforge. It is written for contributors and LLM coding agents that need the full picture. The top-level README is the short, human-facing entry point and links back here.

If you also see a docs/ folder locally: that is a generated, git-ignored MkDocs build (scripts/build_docs.sh regenerates it from this folder plus plans/) and never appears on GitHub — this folder is the one source of truth to read or edit.

Start with the architecture and project layout, then follow the capability you need.

Orientation

Document	What it covers
Quickstart	Install paths and the first run
Requirements	Dependencies, optional extras, and licensing
Usage	Docker, local dev, CLI, and device selection
Architecture	The TopologySpec spine and the data flow
Project layout	Module-by-module map and code conventions
Development	The scripts/dev.sh task runner

Capabilities

• Features — the full feature inventory.
• Interpreter spine (Phase 1) — topology presets, neuron registry, NIR export/validation.
• Dual-mode introspection (Phase 2) — educational/production execution, trajectory metrics, surrogate curves.
• Dashboard (Phase 3) — panels, walkthroughs, and WebSocket actions.
• Event datasets (Phase 4) — N-MNIST, DVS, Tonic, and the event bridge.
• Targets and interoperability (Phase 5) — deployment targets, capability matrix, NIR round-trips.
• Production workflows (Phase 6) — manifests, model registry, scale-ups, benchmarks.
• Model hub (WS-A) — curated catalog, downloads, inspect → compat → promote.
• Backend execution (WS-B) — substitutions and the reference/Norse/Lava backends.
• Sequence primitives (WS-C) — per-stage neurons and attention presets.
• Streaming time series (UC-1) — windowing, a synthetic stream, train/eval, and bundle serving parity.
• Event runtime and energy (WS-D) — sparse runner and SOP/MAC/AC accounting.
• Operational maturity (WS-E) — persisted metrics, tracking sinks, determinism, docs site.
• Interop fold-ins (WS-F) — event training, ONNX bridge, nirtorch extraction, quantization.
• Model deployment: bundles and modules — bundling a checkpoint, running it headless, and installing it as a standalone command.

Honesty and limits

Read these before trusting a number:

• Implications and boundaries — the six cross-cutting limitations, why they exist, and what they imply.
• Notes — phase-specific limitations and caveats.

Related material

• Project rules — code style, hard limits, and design invariants.
• Cookbook — copy-pasteable recipes.
• Examples — fifteen runnable end-to-end scripts.
• Protocol contract — the WebSocket JSON Schema source of truth.
• Open-source checklist — pre-release readiness.
• plans/ — the ARCH-0001 repository-split design, roadmaps, and workstream plans; use that folder's index.md as its table of contents.