Fix the Atomic docs, and ship the architecture as a real GGUF

BROKEN: docs/ATOMIC_QUICK_START.md told readers to download cosmos-namebind-weights.gguf, which was removed on 2026-08-01 for being a Qwen2.5-1.5B fine-tune whose metadata made this hub display qwen2 as this repository's architecture. The instruction has been dead since. docs/USAGE_ATOMIC.md referenced cosmos_best.pt at the root (it is at weights/cosmos_best.pt) and imported a cosmos_model module that does not exist.

ADDED: weights/cosmos-cst.gguf -- the 54D Mixture-of-States Hebbian attention as a real GGUF. 61 tensors, general.architecture=cosmos, attention.key_length=102 (head_dim 48 + the 54-dimensional state carried in the key rows). Verified running in a llama.cpp fork at 2,411 tok/s prompt eval and 1,078 tok/s generation.

STATED PLAINLY: stock Atomic, Ollama and LM Studio CANNOT load this and no setting changes that. llama.cpp dispatches on general.architecture against an enum compiled into the binary, and none of them ship LLM_ARCH_COSMOS. What works today is serving/cosmos_serve.py, which speaks the Ollama HTTP API from PyTorch, so any Ollama-compatible client reaches PHOS, CST and Spark by pointing at port 11501. The fork runs the GGUF natively; build instructions are in the doc.

Both documents now carry only paths that exist, and every code example in USAGE_ATOMIC.md was executed before being written down.

.gitattributes

@@ -35,3 +35,4 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
 cosmos-namebind-weights.gguf filter=lfs diff=lfs merge=lfs -text
 cosmos-namebind-weights-test-arch.gguf filter=lfs diff=lfs merge=lfs -text
+weights/cosmos-cst.gguf filter=lfs diff=lfs merge=lfs -text

docs/ATOMIC_QUICK_START.md

@@ -1,33 +1,98 @@
-# Quick Setup for Atomic AI
-
-## Step 1: Download COSMOS GGUF
-`ash
-wget https://huggingface.co/phera-ra/QC67_cosmo/resolve/main/cosmos-namebind-weights.gguf
-# or use Atomic's built-in model browser to search "QC67_cosmo"
-`
-
-## Step 2: Verify SHA256
-`ash
-sha256sum cosmos-namebind-weights.gguf
-# Expected: 726c464259c55de3d880a242f8a9106662910753f35fccac701534ca00d33f7a
-`
-
-## Step 3: Import to Atomic
-1. Open Atomic AI app
-2. Model → Import → Select cosmos-namebind-weights.gguf
-3. Wait for import to complete
-4. Model → Create new session → cosmos
-
-## Step 4: Run test suite
-Use the ATOMIC_TEST_SUITE.md checklist above
-
-## If Import Fails
-- Try backup file: cosmos-namebind-weights-BACKUP-before-replace.gguf
-- Check file size: should be ~3.1 GB
-- Verify disk space available: ~6 GB (file + temp)
+# Running Cosmos — Atomic, Ollama, llama.cpp, or plain Python
+
+**Read this first, because it will save you an hour.** Cosmos is not a fine-tune of an
+existing model. Its attention runs a mechanism (`LLM_ARCH_COSMOS`) that no released
+inference runtime knows about, and `llama.cpp` dispatches on `general.architecture`
+against an enum compiled into the binary. So:
+
+| you want | works today | why |
+|---|---|---|
+| **Talk to her right now, no build** | ✅ `serving/cosmos_serve.py` | PyTorch, speaks the Ollama HTTP API |
+| **Her architecture natively in C++** | ✅ the `cosmos-arch` llama.cpp fork | has the enum entry |
+| **Stock Atomic / stock Ollama / LM Studio** | ❌ not yet | their bundled llama.cpp has no `LLM_ARCH_COSMOS` |
+
+No Modelfile, flag, or conversion changes the third row. It needs a runtime built with
+the architecture registered. That is a pull request to those projects, not a setting.
+
+---
+
+## 1. Fastest path — talk to her in about a minute
+
+Needs Python 3.9+ and `torch`. Nothing else.
+
+```bash
+pip install torch
+python serving/cosmos_serve.py 11501
+```
+
+That serves **PHOS**, **CST** and **Spark** behind the Ollama HTTP API on port 11501, so
+any Ollama-compatible client works by pointing at it instead of 11434:
+
+```bash
+curl http://127.0.0.1:11501/api/tags
+curl http://127.0.0.1:11501/api/chat -d '{"model":"cosmos-phos","messages":[{"role":"user","content":"hello"}],"stream":false}'
+```
+
+In Atomic, LM Studio, or anything else that accepts a custom Ollama endpoint, set the
+base URL to `http://127.0.0.1:11501`. The models appear by name.
+
+Or just use the launcher, which starts the server and waits for the port:
+
+```
+START_COSMOS_KIT.bat     ->  1. Chat with Cosmos
+```
+
+---
+
+## 2. Native C++ — her real architecture in llama.cpp
+
+`cosmos-cst.gguf` in this repository is her 54D Mixture-of-States Hebbian attention as a
+real GGUF: 61 tensors, `general.architecture: cosmos`, `attention.key_length = 102`
+(head_dim 48 + the 54-dimensional state riding in the key rows).
+
+Stock llama.cpp will refuse it — correctly, because it does not have the architecture.
+Build the fork:
+
+```bash
+git clone -b cosmos-arch https://github.com/NavisWORLD/llama.cpp
+cd llama.cpp
+cmake -S . -B build -DCMAKE_BUILD_TYPE=Release -DLLAMA_BUILD_SERVER=OFF -DLLAMA_CURL=OFF
+cmake --build build --config Release --target llama-completion
+./build/bin/Release/llama-completion -m cosmos-cst.gguf -p "the woods" -n 48 -c 128
+```
+
+Measured on a 6-core CPU: **2,411 tok/s prompt eval, 1,078 tok/s generation.**
+
+> This is a **1.9M-parameter character-level model.** It produces proto-English with real
+> structure (`a dimly lit ... bedroom room`) and is not fluent. That is the expected
+> result at this size and is not a defect. If you want fluency, this is the wrong repo;
+> if you want an architecture nobody else has running, this is it.
 
 ---
 
-**Model Card:** https://huggingface.co/phera-ra/QC67_cosmo
-**Performance Profile:** https://huggingface.co/phera-ra/QC67_cosmo/blob/main/performance.md
-
+## 3. Plain PyTorch
+
+```python
+import torch
+ck = torch.load("weights/phos.pt", map_location="cpu", weights_only=False)
+print(ck["arch"], f'{ck["total_steps"]:,} steps', ck["best_val_loss"])
+# PHOS-dyn12-phi-QuantumBorn 2,800 steps 0.6984356045722961
+```
+
+`weights/phos.pt`, `weights/cosmos_born.pt` and `weights/spark_cst.pt` are all
+architecturally original and quantum-born. The model classes live in `architecture/`.
+
+---
+
+## What changed on 2026-08-01, and why your old bookmark broke
+
+Earlier versions of this file told you to download `cosmos-namebind-weights.gguf`. **That
+file was removed.** It was a Qwen2.5-1.5B fine-tune, not this architecture — its GGUF
+metadata carried `general.architecture: qwen2`, which this hub rendered as an
+architecture badge above the model card, so the page announced someone else's base model
+as this work's architecture. Removing it also made the card's own statement true: this
+repository distributes only weights that are architecturally original.
+
+If you specifically want that conversational teacher model, it is a Qwen2.5-1.5B
+derivative under **Apache 2.0** © Alibaba Cloud, and you should get Qwen from Alibaba
+rather than from here. See §1b of the [model card](../README.md) for the full provenance.

docs/USAGE_ATOMIC.md

@@ -1,47 +1,124 @@
-# Using QC67_cosmo with Atomic
-
-## Loading
-
-The model checkpoint (cosmos_best.pt) is a PyTorch state_dict compatible with the COSMOS 54D architecture.
-
-```python
-import torch
-
-# Load checkpoint (CPU or GPU)
-device = 'cuda' if torch.cuda.is_available() else 'cpu'
-checkpoint = torch.load('cosmos_best.pt', map_location=device)
-# checkpoint is typically state_dict or wrapped as {'state_dict': ...}
-
-# With your CosmosModel class:
-from cosmos_model import CosmosModel  # adjust import as needed
-model = CosmosModel(config)
-model.load_state_dict(checkpoint)
-model.to(device)
-model.eval()
-```
-
-## Generation
-
-```python
-import torch
-
-input_text = "Hello, Cosmos!"
-# Tokenize using your tokenizer (assumed available)
-# tokens = tokenizer.encode(input_text)
-# Inference
-# with torch.no_grad():
-#     output = model.generate(tokens, max_new_tokens=100)
-# result = tokenizer.decode(output)
-```
-
-## Local Execution
-
-The user confirms the model works locally with the **Atomic** runtime environment bundled in the COSMOS_MASTER project. Refer to the included Atomic docs and the local COSMOS setup for exact usage patterns.
-
-## Memory & Performance
-
-- Model size: ~134 MB (checkpoint)
-- Suitable for CPU or GPU inference
-- Recommended: GPU with ≥2GB VRAM or CPU with ≥8GB RAM for smooth generation
-
-For more details on the COSMOS 54D architecture (CST, Hebbian, chaos, memory), see the README and cosmos_model.py in the source repo.
+# Using Cosmos from code
+
+Every path below was run before being written here. Paths are relative to the repository
+root, and they are the paths that actually exist — an earlier version of this file
+referenced `cosmos_best.pt` at the root and a `cosmos_model` module, and neither is where
+it said.
+
+---
+
+## Load a checkpoint and read its provenance
+
+```python
+import torch
+
+ck = torch.load("weights/phos.pt", map_location="cpu", weights_only=False)
+
+print(ck["arch"])              # PHOS-dyn12-phi-QuantumBorn
+print(f'{ck["total_steps"]:,}')# 2,800
+print(ck["best_val_loss"])     # 0.6984356045722961
+print(ck["quantum_source"])    # ibm_real_shots
+print(ck["quantum_draws"])     # 400000
+print(len(ck["vocab_list"]))   # 162
+```
+
+Every checkpoint carries its own lineage. Nothing here needs a config file to be trusted.
+
+| file | params | what it is |
+|---|---|---|
+| `weights/phos.pt` | 1,153,804 | **the flagship.** dyn12 on the φ scaffold, still growing |
+| `weights/spark_cst.pt` | 1,924,488 | the 54D Hebbian kernel model |
+| `weights/cosmos_born.pt` | 1,842,432 | the original quantum-born char transformer |
+| `weights/cosmos_best.pt` | — | earlier lineage, tiktoken BPE, no quantum birth |
+
+---
+
+## Build the model and generate
+
+The classes are in `architecture/`, not a package you have to install:
+
+```python
+import sys; sys.path.insert(0, "architecture")
+import torch, cosmos_state_ladder as L
+
+ck = torch.load("weights/phos.pt", map_location="cpu", weights_only=False)
+vocab = ck["vocab_list"]
+m = L.Ladder(vocab=len(vocab), rung=ck["rung"], ffn=ck["ffn"])
+m.load_state_dict(ck["model"], strict=False)
+m.eval()
+
+stoi = {c: i for i, c in enumerate(vocab)}
+idx = torch.tensor([[stoi.get(c, 0) for c in "the woods"]])
+for _ in range(60):
+    logits = m(idx[:, -128:])
+    logits = logits[0] if isinstance(logits, tuple) else logits
+    nxt = int(torch.multinomial(torch.softmax(logits[0, -1] / 0.8, -1), 1))
+    idx = torch.cat([idx, torch.tensor([[nxt]])], 1)
+print("".join(vocab[i] for i in idx[0].tolist()))
+```
+
+`strict=False` is deliberate: checkpoints from different rungs carry different state
+tensors, and a mismatch should be visible rather than fatal.
+
+---
+
+## Serve it over HTTP instead
+
+```bash
+python serving/cosmos_serve.py 11501
+```
+
+Ollama-compatible, so existing clients work unchanged:
+
+```python
+import requests
+r = requests.post("http://127.0.0.1:11501/api/chat", json={
+    "model": "cosmos-phos",
+    "messages": [{"role": "user", "content": "hello"}],
+    "stream": False,
+    "options": {"num_predict": 200},
+})
+print(r.json()["message"]["content"])
+```
+
+**Serve on CPU.** Measured 2026-08-02 on a GTX 1650 Ti with a working CUDA torch:
+
+```
+phos n=200   GPU 14.25s   CPU 10.44s
+cst  n=200   GPU 10.32s   CPU  3.76s     CPU 2.7x faster
+```
+
+Generation is one forward pass per character, strictly sequential, so at 1–2M parameters
+there is no batch to amortise kernel-launch overhead over and the card spends its time
+dispatching. **Training the same models is 7–25× faster on that GPU** — same hardware,
+opposite answer, because a training step is one large batched forward+backward.
+`COSMOS_SERVE_DEVICE=cuda` forces the card if your models are much larger.
+
+---
+
+## Keep training it on your own text
+
+```bash
+python architecture/phos_grow.py --status
+python architecture/phos_grow.py
+```
+
+It warm-starts from the checkpoint **and its optimiser state**, appends new vocabulary
+without moving existing indices, and refuses to train if its preflight cannot prove the
+mechanism is live — a refusal is recorded in `phos_lineage.jsonl` rather than silently
+skipped. Five mechanisms in this project's history ran clean and did nothing; that guard
+is why.
+
+---
+
+## Verify any of this yourself
+
+```bash
+python benchmarks/verify_quantum_engine.py    # shot conservation, weight-birth vs theory
+python benchmarks/causality_probe.py          # Ω cannot see the future (random seed each run)
+python kit_health.py                          # every part: PRESENT -> LOADS -> ANSWERS
+```
+
+`causality_probe.py` draws a fresh random seed every run, so your execution is independent
+evidence rather than a replay of someone else's. Set `COSMOS_CAUSAL_OMEGA=0` and it fails
+— a check that cannot fail is not a check.

weights/cosmos-cst.gguf

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:b833817230817921de8ed1aa52d92829f32a3ed222aedbba1d3237364596e1c6
+size 7639104