work/Convergence_Engine/quick-reference.txt

Convergence Engine Quick Reference
==================================
Codex was here. Monkey King had the aux cord. Keep it weird, keep it verified.

Cheat code
----------
techlady

If JupyterLab asks for a password, type:

techlady

That is the whole door. No paywall. No maze.

Code wheel
----------
Only one code is active at a time.
The current code is the one to try first.

Current code:

techlady

Reserve codes:

techlit
crayonlab
gamegenie
wordfood
tinydoor
livinglab
organismgarden
cocooncode
jupyterjoy

Entry is right there.
It only asks for one small sign that you read the door.

CAVEMAN SCIENTIST WAS HERE
   __________
  | _o_      |
  ||___|     |    "techlady"
  |     ___  |     one key. one door.
  |    |   | |     no maze. no paywall.
  |____|___|_|
       | |
      _| |__ /\/\

Read me first
-------------
This is the short path into the Convergence Engine.
It is written like a cheat sheet because the goal is to play, test, and learn by touching the system.

Playful wrapper. Serious receipts.
Commands are the drumline. Run them from the room named above.

Do the main path first.
Use the optional parts later.

Accessibility notes
-------------------
- Plain text only.
- Commands are one per line.
- No color-only meaning.
- No tables.
- Short headings for screen readers.
- Optional steps say optional.

Brotology rule
--------------
The name is a joke.
The method is not.

Be funny.
Be honest.
Read the room before you touch the machine.

The banger raid order is four beats:

1. get status
2. get sitrep
3. poke one thing
4. watch what changed

Use these first when you are unsure:

cd /workspace/Convergence_Engine
python cra_cli.py status
python cra_cli.py sitrep

If a command fails, read the error before inventing a spell.

Diagnostic feed
---------------
For CRA prompt continuity and source-of-truth rules, read:

docs/reference/CRA_DIAGNOSTIC_FEED_2026-05.md

Current critical facts:

neural.brain.input_dim=30
CRA model provider=HuggingFace Inference
Private CRA auth uses HF token plus CRA_INTERNAL_KEY when server fallback is enabled.

JupyterLab front door
---------------------
For a Hugging Face JupyterLab Space, set this Space secret:

JUPYTER_TOKEN=techlady

The Space uses that secret as the Jupyter password.

Bucket lane:

Keep the mounted bucket at /data with read and write access.
JupyterLab opens in /data/work.
Clone the repo there so Convergence_Engine/data lives on the bucket.
If the bucket is missing, the door can still run, but rebuilds can wipe the work.

ASTROPHYSICIST WAS HERE
       *   .    ✦   .   *
     .    .--------.   .
    .    /  /data   \    .       <-- this bucket holds the stars
       /              \
       \   __work__   /
        \ /          \ /
         '-------- ---'
       *   .    ✦   .   *

Important:

/data is the Hugging Face bucket.
/data/work is the working room inside the bucket.
/data/work/Convergence_Engine is the engine room.
/data/work/Convergence_Engine/data is the engine data room.

If a command mentions cra_cli.py, unified_entry.py, or build_curated_dataset.py, run it from:

/data/work/Convergence_Engine

For a local JupyterLab door:

python -m pip install jupyterlab
jupyter lab --ip 0.0.0.0 --port 7860 --ServerApp.token=techlady --ServerApp.password='' --no-browser

Open the JupyterLab URL.
Use the password:

techlady

Then open a Terminal inside JupyterLab and use the commands below.

Private CRA Space deploy
------------------------
This is the reliable private-space path for the CRA web server.

Local PowerShell:

$env:HF_TOKEN="hf_your_write_token"

Optional, if you already chose the internal key:

$env:CRA_INTERNAL_KEY="your-long-random-key"

Run from the repo root:

python deploy_private_cra_space.py --target tostido/convergence-engine-private

The script creates or updates the private Space secrets:

CRA_ALLOW_ENV_HF_TOKEN=1
CRA_INTERNAL_KEY=<generated or env value>
HF_TOKEN=<your local HF_TOKEN>

If the script generates CRA_INTERNAL_KEY, record it immediately.
Hugging Face will not show that secret value again.

Then push the current branch to the private Space remote:

git remote add private-space https://huggingface.co/spaces/tostido/convergence-engine-private
git push private-space hf-deploy:main

Private CRA verification
------------------------
Replace the URL if you used a different target Space.
Use --cra-key or set CRA_INTERNAL_KEY in the shell.

PowerShell:

$env:CRA_BASE="https://tostido-convergence-engine-private.hf.space"
$env:HF_SPACE_TOKEN=$env:HF_TOKEN
$env:CRA_INTERNAL_KEY="your-long-random-key"

Check the public health route:

python cra_cli.py --base-url $env:CRA_BASE --hf-auth-token $env:HF_SPACE_TOKEN api /health

If CRA_BASE is not an env var, paste the URL directly:

python cra_cli.py --base-url https://tostido-convergence-engine-private.hf.space --hf-auth-token $env:HF_TOKEN api /health

Check read-only CRA and telemetry routes:

python cra_cli.py --base-url $env:CRA_BASE --hf-auth-token $env:HF_SPACE_TOKEN status
python cra_cli.py --base-url $env:CRA_BASE --hf-auth-token $env:HF_SPACE_TOKEN sim-status
python cra_cli.py --base-url $env:CRA_BASE --hf-auth-token $env:HF_SPACE_TOKEN system

Check server-side Hugging Face token fallback:

python cra_cli.py --base-url $env:CRA_BASE --hf-auth-token $env:HF_SPACE_TOKEN --cra-key $env:CRA_INTERNAL_KEY api /api/cra/hub/providers/auto/models
python cra_cli.py --base-url $env:CRA_BASE --hf-auth-token $env:HF_SPACE_TOKEN --cra-key $env:CRA_INTERNAL_KEY chat "give me a concise private CRA status"

Check routing and diagnostic telemetry:

python cra_cli.py --base-url $env:CRA_BASE --hf-auth-token $env:HF_SPACE_TOKEN butterfly-chat "cooperate" --max-organisms 1
python cra_cli.py --base-url $env:CRA_BASE --hf-auth-token $env:HF_SPACE_TOKEN api /api/diagnostic/phase_sync
python cra_cli.py --base-url $env:CRA_BASE --hf-auth-token $env:HF_SPACE_TOKEN api /api/diagnostic/unified_health

Important:

GET /api/simulation/status is read-only.
It reports the web viewer control signal, not the whole organism runtime.
Fresh shared_state or logs are stronger evidence for live/recent telemetry.

Only POST /api/simulation/start or /api/simulation/stop when you intend to send a viewer control signal and write a receipt.

Tools
-----
Netron:
https://netron.app/

Optional public tunnel for the web UI:

ssh -R 80:localhost:5000 nokey@localhost.run

Clone and setup
---------------
Go to the workspace room:

cd /workspace

If the repo is not there yet:

git clone https://github.com/Yufok1/Convergence_Engine.git

If clone says the destination already exists, that is okay.
It means the repo is already there.

Enter the engine room:

cd Convergence_Engine

Confirm the room:

pwd

You should see:

/workspace/Convergence_Engine

Windows PowerShell:

python -m venv .venv
.\.venv\Scripts\Activate.ps1

Linux, macOS, Hugging Face, or bash:

python -m venv .venv
source .venv/bin/activate

Already inside conda or uv:

python -m pip install -r requirements.txt

Install the engine parts:

python -m pip install --upgrade pip
python -m pip install --upgrade setuptools wheel
python -m pip install -r requirements.txt
python check_setup.py

Vocabulary and language bootstrap
---------------------------------
Run these once after a fresh clone:

cd /workspace/Convergence_Engine
mkdir -p data
cp config.json data/config.json
mkdir -p /data/nltk_data
export NLTK_DATA=/data/nltk_data
python -m nltk.downloader -d /data/nltk_data wordnet omw-1.4

MONKEY KING WAS HERE\//
>---->--->--->--->-[\/]
                   {/\}
NEXT:<---<----<---[/<<\]

python build_curated_dataset.py
python merge_nuclear_vocab.py
python generate_innate_vocab.py

Optional smaller vocabulary:

python distill_vocabulary.py --input data/seeded_knowledge_web_250k.json --output data/knowledge_web_distilled.json --target 50000

Optional expanded knowledge web:

python reality_simulator/language/expand_knowledge_web.py --input data/seeded_knowledge_web_250k.json --output data/seeded_knowledge_web_expanded.json --concepts 50000 --min-weight 1.5

Recovery boot order
-------------------
Check first:

cd /workspace/Convergence_Engine
source .venv/bin/activate
mkdir -p data
cp config.json data/config.json
python unified_entry.py --config config.json --check-only --no-viz

Then start the world:

python unified_entry.py --config config.json --no-viz --debug

Open the web view:

http://localhost:5000

Hardware profiles
-----------------
Use the base config first.
Only switch to a rented-box profile when that machine actually matches the file.

Common profile names:

- config_vast_rtx3060_genesis.json
- config_vast_rtx4090_1tb_genesis.json
- config_vast_rtx5090_512gb_genesis.json
- config_vast_xeon_1.5tb_genesis.json
- config_shadow_epyc_genesis.json

Only use this on a genuinely huge machine:

config_vast_xeon_1.5tb_genesis.json

Direct large-box launch
-----------------------
python unified_entry.py --config config_vast_xeon_1.5tb_genesis.json --no-viz --debug

Useful extras
-------------
Open another terminal in the same repo.
Activate `.venv` again.

Status and dashboard:

python live_dashboard.py
python causation_web_ui.py
python cra_cli.py status
python cra_cli.py sitrep
python cra_cli.py training-status
python cra_cli.py exporter-status
python cra_cli.py organisms --limit 10
python cra_cli.py alliances

Talk and poke:

python cra_cli.py repl --model llama3.2
python cra_cli.py standin-chat "cooperate" --max-organisms 1
python cra_cli.py butterfly-chat "cooperate" --max-organisms 1
python cra_cli.py organism-chat <organism_id> "cooperate"

Tune a small thing:

python cra_cli.py config-set /simulation/max_frames 5000

Write a science note:

python cra_cli.py notepad --summary
python cra_cli.py notepad-add observation "Run started #baseline"
python cra_cli.py scientific-receipt --title "Baseline run receipt"

Export organisms
----------------
python cra_cli.py compile-cocoon --top-n 5 --format cocoon
python cra_cli.py compile-cocoon --top-n 5 --format package
python cra_cli.py compile-cocoon --alliance-id <id1> --alliance-id <id2> --format cocoon
python cra_cli.py compile-cocoon --alliance "Alliance Name" --alliance-id <id2> --format package
python cra_cli.py cocoon-validate Children/cocoon_ensemble_<timestamp>.zip
python cra_cli.py compile-learning --organism-id <id>

Cocoon plus Champion Council
----------------------------
Fresh exports include:

- connector-word curriculum in vocabulary.json
- bake-time alliance composition with selected_alliances and alliance_ids
- game_contracts.json for Council adapters
- curriculum/*.json and training_logs/schema.json
- native HTTP endpoints for health, action, learning, chat, teach, vocab, curriculum, training logs, score, snapshot, save, export, and capabilities

Run an exported Cocoon
----------------------
python cocoon.py --mode info --max-organisms 1
python cocoon.py --mode serve --port 8080
python cocoon.py --mode sphere --headless --balls 1 --misses 1 --train
python cocoon.py --mode gym --env CartPole-v1 --episodes 1 --no-learn

Persist live learned state
--------------------------
curl -X POST http://localhost:8080/save
curl -X POST http://localhost:8080/export -H "Content-Type: application/json" -d '{"path":"evolved_cocoon.py"}'

Tiny rescue riff
----------------
If setup fails:

python check_setup.py

If the world feels empty:

python build_curated_dataset.py
python merge_nuclear_vocab.py
python generate_innate_vocab.py

If the web view is stale:

python causation_web_ui.py

If you get lost:

python cra_cli.py sitrep

Shell sanity
------------
Bash uses forward slashes:

source .venv/bin/activate

PowerShell uses backslashes:

.\.venv\Scripts\Activate.ps1

When in doubt:

python --version
python -m pip --version

The whole groove
----------------
Code: techlady
Build the language food.
Start the world.
Check the receipts.
Then play Pokemon AI, baby.

THE BANGER RAID ORDER (four beats, no fudging)
   |      |      |      |
   |      |      |      |
  [1]----[2]----[3]----[4]    boom. boom. boom. BOOM.
 status sitrep  poke   watch
   |      |      |      |
   '------'------'------'
              \//
   MONKEY KING APPROVES THIS GROOVE