docs/KIT_GUIDE.md

# Cosmos kit guide

Use [`presentation.html`](presentation.html) for the visual tour, then use this page as
the clickable map of the repository.

| Area | Open this | Purpose |
|---|---|---|
| Research overview | [`FINDINGS.md`](FINDINGS.md) | Measurements, controls, null results, and provenance. |
| Visual walkthrough | [`presentation.html`](presentation.html) | Archive size, hardware backends, and architecture slides. |
| Train your own model | [`TRAINING.md`](TRAINING.md) | Plain-vs-CST training, sizing, and reproducibility. |
| Controlled trainer | [`train_your_own.py`](train_your_own.py) | Builds the standard and 54D Hebbian-attention arms with matched seeds. |
| Benchmarks | [`benchmarks/`](benchmarks) | Independent checks for the quantum, physics, topology, and integration claims. |
| Genesis Engine | [`genesis_engine/`](genesis_engine) | Local companion birth, memory, ledger, and browser UI. |
| Baseline weights | [`weights/`](weights) | The published `cosmos_born.pt` baseline artifact and metadata. |
| Local server | [`spark_serve.py`](spark_serve.py) | Ollama-compatible serving for the standalone PyTorch voice. |

## Two Hebbian layers

The kit documents two related but different mechanisms:

1. Genesis association learning updates concept-pair and salience state during local
   conversations.
2. CST Mixture-of-States attention adds a learned 54D projection, Gaussian state kernel,
   and gated blend inside the transformer. `train_your_own.py` is the reproducible path
   for training that mechanism.

The baseline `weights/cosmos_born.pt` and the CST experiment must not be described as the
same artifact. Publish a CST checkpoint only after the final held-out comparison and
checksum are recorded in the model card.

## Safe editing map

- Safe to customize: your corpus, local config, IBM token, output directory, and UI theme.
- Keep private: credentials, local experience logs, camera/audio captures, and `.env` files.
- Keep reproducible: benchmark scripts, fixed seeds, held-out split, and result JSON.
- Do not replace a published checkpoint in place until its architecture, hash, and test
  result are recorded in the model card.