docs/README.md

Brain-5D Documentation

This directory contains both current canonical documentation and historical/versioned records. Historical Alpha, Sprint, Release and dated change documents remain traceability artifacts and must not be read as the current repository state.

Source of truth

When documents disagree, use this order:

1. code, configuration schemas and machine-readable contracts on main;
2. current CI and verification artifacts;
3. experiment DATA/ and accepted EVID records;
4. the canonical documents listed below;
5. historical/versioned documents;
6. narrative or AI-generated interpretation.

Passing tests prove engineering behavior covered by those tests; they do not automatically establish a scientific claim.

Current baseline — 2026-09-07

• canonical branch: main
• package version: 0.5.0a7
• latest verified Python suite: 825 passed, 5 skipped
• latest verified browser suite: 5 passed with Chromium
• Research Catalog / variable-projection-dimension merge: 85e7209509b348bf7912dde01d3d9ebb078a2e61
• latest fully completed pre-merge main CI baseline: success (run #598)
• Python matrix: 3.11 / 3.12 / 3.13
• Black, Ruff, Pylint, Pre-Commit, Mypy, Pyright, Security, Scientific Integrity, wheel and Docker checks remain mandatory CI gates
• post-merge CI is authoritative for the merged baseline; do not describe it as fully green until the corresponding main run completes
• GitHub main is canonical; the configured Hugging Face mirror is synchronized from this branch after repository changes
• Live dashboard Space: https://huggingface.co/spaces/superdigger/Brain-5D-Space
• historical experiment DATA/EVID remains unchanged by documentation or registry cleanup

Historical EXP-GEN-0009 to EXP-GEN-0012 artifacts remain untouched. They recorded zero observable activity under the older probe contract. Current instrumentation measures published spike IDs plus tick, neuron and synaptic-event activity and persists those fields in new experiment DATA.

Canonical current documents

Area	Canonical document
Project overview	../README.md
Architecture	02-architecture/ARCHITECTURE.md
Adaptive Wesen body view	02-architecture/WESEN_ADAPTIVE_BODY.md
Neural Symbiosis / multi-network embodiment	02-architecture/NEURAL_SYMBIOSIS.md
MSBA / modality-specific pathways and energy homeostasis	02-architecture/MSBA.md
Storage format	02-architecture/B5D_FORMAT.md
Real-body embodiment	02-architecture/EMBODIMENT_REAL_BODY.md
Learning preparation	02-architecture/LEARNING_PREPARATION_STUDIO.md
Dashboard	03-dashboard/DASHBOARD.md
API reference	03-dashboard/API_REFERENCE.md
Quality gate	05-quality/QUALITY_GATE.md
Research positioning & evidence program	06-research/RESEARCH_POSITIONING_AND_EVIDENCE_PROGRAM.md
Development roadmap	08-roadmap/ROADMAP.md
Current TODO	08-roadmap/TODO.md
Research roadmap	08-roadmap/RESEARCH_ROADMAP.md
Research/evidence system	../research/README.md
Security	../SECURITY.md
Contribution workflow	../CONTRIBUTING.md

Current research-registry contract

The normal research workflow loads canonical base registries plus deterministic fragments:

• research/registry/questions.yaml
• research/registry/questions.*.yaml
• research/registry/hypotheses.yaml
• research/registry/hypotheses.*.yaml

Duplicate identifiers fail closed. MSBA questions/hypotheses are first-class entries rather than side documentation. The Experiment Workflow exposes them through a searchable Research Catalog and distinguishes questions with frozen/preregistered operational protocols from exploratory-only questions. Exploratory execution must not be confused with confirmatory evidence.

The repository-wide RQ/H audit reports references that are not represented in the canonical registry without rewriting historical sources.

Current dashboard terminology

• Overview — summary/runtime context;
• Control — explicit operator controls;
• Research — research/evidence workflows and searchable Research Catalog;
• Settings — configuration;
• Wesen — adaptive read-only live machine-body visualization;
• Embodiment — technical sensor/device/actuator/body-boundary surface;
• Neural Symbiosis — read-only multi-network/virtual-pipeline view inside Wesen;
• MSBA — modality-specific audio/vision/digital gateway contract plus resource/energy model inside Neural Symbiosis;
• Release/Gate — footer-accessed release-readiness surface;
• Network — no longer a primary user-facing workspace.

Wesen, Neural Symbiosis and MSBA must never be described as proof of consciousness, self-awareness, causal tool use or learned sensor control. Reachability, recurrence, loopback, morphology, pipeline availability, energy allocation candidates and gateway candidates are engineering/observation state until a preregistered experiment produces reviewable DATA/EVID.

Scientific boundary for Neural Symbiosis, MSBA and dimensions

The multi-network layer is part of Embodiment, not a rewrite of the SNN core. Peripheral CNN/Transformer/RNN/GNN/memory/generative/custom networks and virtual systems such as logic or knowledge databases are connected only through explicit adapter/gateway contracts.

MSBA specializes those gateway contracts by modality:

• audio: temporal-coherence features and candidate phase-weighted t-STDP;
• vision: spatial multiplexing, fixed sparse target degree and candidate locality/information/resource structural growth;
• digital: exact immutable payload outside the SNN, deterministic population representation and candidate meta-gating only;
• resource pressure: normalized energy accounting, explicit estimate-vs-measurement provenance and deterministic NORMAL/CONSERVE/CRITICAL/SURVIVAL protection states.

Current dimension rule:

• MSBA/external projection spaces may declare 1–32 dimensions;
• the productive persisted SNN core remains 5D for compatibility;
• productive core >5D requires a separately versioned neuron-ID/storage representation, generalized spatial indexing, .b5d migration, canonical state/equivalence tests and preregistered experiments;
• increased-dimensional projection experiments must not be mislabeled as productive-core N-D evidence.

Current gateway rules:

• open-set NetworkAreaAdapter contract;
• framework-neutral peripheral implementations;
• pipeline templates are disabled until explicitly instantiated;
• Neural-Symbiosis and MSBA gateway learning/growth/allocation are disabled by default;
• gateway RNG belongs to an experiment runner and must be persisted;
• endpoint reachability is not evidence of learned use;
• fixed semantics are not imposed on the five Brain-5D axes;
• measured joules are never inferred from normalized units without explicit calibration/provenance;
• historical DATA/EVID is never rewritten to reflect new adapters.

See 02-architecture/NEURAL_SYMBIOSIS.md and 02-architecture/MSBA.md.

Experiment-data compacting rule

Large experiment series preserve raw observations in immutable/compressed artifacts. Bounded projections such as runs.json and analysis/ai_packet.json exist for UI/review/small-model consumption and must carry provenance back to the raw record. Compact files are not replacements for scientific raw DATA.

Directory map

• 01-guides/ — operator/developer guides;
• 02-architecture/ — architecture and subsystem contracts;
• 03-dashboard/ — dashboard contracts and UI/API documentation;
• 04-integration/ — integration notes and overlays;
• 05-quality/ — quality and release-gate definitions;
• 06-research/ — research notes and canonical research-positioning documents;
• 07-changelog/ — dated change records;
• 08-roadmap/ — current roadmap/TODO plus historical phase-specific roadmaps;
• 09-sprints/ — time-boxed sprint records;
• 10-releases/ — release checklists and notes;
• 11-readme/ — historical README blocks;
• 12-updates/ — update manifests and integration snapshots;
• 99-archive/ — explicitly archived legacy material.

Historical-document rule

A filename containing a previous version, ALPHA*, SPRINT*, V0*, UPDATE*, RELEASE_*, or an entry under 99-archive/ is historical unless a canonical current document links to it as an active contract. Old test counts, commit hashes, milestones and implementation status in those files are not current project metadata.

Historical experiment DATA must not be silently rewritten when instrumentation improves. Corrections belong in code, canonical documentation and new versioned experiments.

Documentation maintenance

Avoid copying fixed test counts or commit hashes into many current documents. Where a fixed number is useful, date it and treat it as a verified snapshot. Scientific conclusions must cite experiment/evidence artifacts, not README prose or dashboard state alone.

Current development policy: main is canonical. Short-lived branches start from current origin/main, are verified before merge, and should be deleted after merge when repository tooling permits. A branch with no commits ahead of main contains nothing to integrate and must not be merged merely to make the branch list empty.