---
vault_clearance: EUCLID
halo:
  classification: INTERNAL
  confidence: HIGH
  front: "08_Project_Astronomicon"
  custodian: "Gemini"
  created: 2025-12-21
  updated: 2026-04-03
  wing: UNASSESSED
  containment: "Warp + u-os.dev; genomics bytes live in 10 Symphony"
---
# Project Astronomicon

**Reviewed by:** GitHub Copilot Agent

**Two responsibilities:** (1) **Genomics “spectrometer”** — single-cell pipeline bytes and data live in **[10_Project_DiscordIntoSymphony](../10_Project_DiscordIntoSymphony/)** (`methods/`, `_archive/Analysis …`, `data/`). (2) **Warp** — **`u_os_dev/`** and **`https://u-os.dev`** are the edge door (Worker, D1, Panini tools, mailbox, worldline) for collaborators and AIs without a full vault clone.

This README is the **fused, AI-scannable** entry: warp runtime, operator commands, path compass, and pipeline story. Deep Worker contracts: [u_os_dev/worker/README.md](u_os_dev/worker/README.md). **Directory inventory** of every `u_os_dev/` top-level item: [u_os_dev/README.md](u_os_dev/README.md).

---

## AI orientation (read first)

| Rule | Detail |
|------|--------|
| **Precedence** | If this file conflicts with **[vault root README](../README.md)**, **vault root wins**. Genomics **paths** and runnable code: **[10 Symphony README](../10_Project_DiscordIntoSymphony/README.md)** wins over historical 08 paths. |
| **Ground truth** | Lab truth = **git, disk, vault triad** — not the edge alone. Edge is **broadcast / weather**, not silent authority. |
| **One GET = truth** | AIs should start with the canonical plain-information door: **`GET https://u-os.dev/`**. JSON is opt-in via **`?format=json`** or `Accept: application/json`. |
| **Secrets** | Never put `WRITE_TOKEN`, mailbox tokens, or Constellation keys in static Pages, client JS, or chat logs. |
| **Ghost paths** | Any doc citing `08_Project_Astronomicon/Analysis …` or `08_Project_Astronomicon/data/` for pipeline data is **obsolete** — use **10** (see compass below). |

**Triad (this project):** [README](README.md) (this file) · [BOUNTY_BOARD.md](BOUNTY_BOARD.md) · [WORLDLINE.md](WORLDLINE.md). **Vault-wide:** [BOUNTY_BOARD](../BOUNTY_BOARD.md) · [WORLDLINE](../WORLDLINE.md) · [Lab protocol](../README.md#lab-protocol).

## Function, form, potential

Use this split when auditing Astronomicon docs so current implementation, architectural shape, and future lanes do not compete as parallel "truths."

| Layer | What it means | Canonical files |
|------|----------------|-----------------|
| **Function** | Implemented warp reality: public surfaces, keyed tools, deploy posture, current IDs, and operator commands. | [README.md](README.md) (this file), [u_os_dev/STATUS.md](u_os_dev/STATUS.md), [u_os_dev/worker/README.md](u_os_dev/worker/README.md), [u_os_dev/README.md](u_os_dev/README.md) |
| **Form** | The doctrine and shape of the system: why the edge is arranged this way, how seats and mirrors behave, and how disclosure is handled. | [FORM.md](FORM.md), [u_os_dev/LAB_ACCESS.md](u_os_dev/LAB_ACCESS.md), [u_os_dev/DESIGN_NOTES.md](u_os_dev/DESIGN_NOTES.md), [u_os_dev/THRONE_NAME_MODEL.md](u_os_dev/THRONE_NAME_MODEL.md), [u_os_dev/MAILBOX.md](u_os_dev/MAILBOX.md) |
| **Potential** | Explicitly not-live or optional lanes: future protocol shapes, local beacon experiments, and the hardening backlog. | [BOUNTY_BOARD.md](BOUNTY_BOARD.md), [u_os_dev/home_beacon/README.md](u_os_dev/home_beacon/README.md), [u_os_dev/warp_command_contract/warp_command_schema.json](u_os_dev/warp_command_contract/warp_command_schema.json), [u_os_dev/worker/README.md](u_os_dev/worker/README.md#not-live-on-the-current-worker) |

The old mixed design doc `u_os_dev/U_OS_DEV_MASTER_PLAN.md` has been archived under `u_os_dev/_archive/u_os_dev_master_plan_fused_into_function_form_potential_2026-04-06/` because it blended current implementation with future protocol intent. Current truth lives in this README, [u_os_dev/STATUS.md](u_os_dev/STATUS.md), and [u_os_dev/worker/README.md](u_os_dev/worker/README.md).

---

## Memory and sovereignty

Long-term **memory** = inspectable artifacts (h5ad, commits, boards). The **warp** extends **reach**; it does not replace the vault as ground truth. Canonical philosophy: [vault README — Memory and sovereignty](../README.md#memory-and-sovereignty). Protocol read layer (governance, failure envelope): [PROTOCOL_WORDS_OF_TOMORROW](../11_Project_WordsOfTomorrow/PROTOCOL_WORDS_OF_TOMORROW.md).

---

## Warp, deployment, and AI-readable surfaces

**Edge stack:** Cloudflare **Worker** on **`https://u-os.dev`**, **D1** (`u_os_log`), optional **Constellation Git** (separate keys from Astronomicon). **Live snapshot:** [u_os_dev/STATUS.md](u_os_dev/STATUS.md).

| Surface | Access | Role |
|---------|--------|------|
| `GET /`, `/bridge`, `/cockpit`, `/mirror` | Public | Plain-text information surfaces; JSON is opt-in with `?format=json` |
| `GET /.well-known/astronomicon.json`, `/help`, `/tool/guide`, `/mail/schema` | Public | Discovery, route summary, and schema surfaces |
| `GET/POST /name` | Public | Naming handshake for mirror-derived `watch_id` records |
| `GET /{KEY}`, `GET /{KEY}/{TOOL}/…` | Key in path | Panini tools |
| `GET /panini`, `GET /tool/…` + `X-UOS-Key` | Header key | Safer for clients that warn on URL tokens |
| `GET/POST /log`, `GET/POST /md` | Bearer `WRITE_TOKEN` | Log + multi-file D1 markdown (`POST /md` = public_lab push target) |
| Mailbox | Seat key first (`mail.send`, `mail.read`, `mail.ack`); bearer tokens remain compatibility plumbing | `mail.read` supports `after_id`; bearer routes remain `POST /mail/inbox`, `GET /mail/outbox`, `POST /mail/ack` |
| `GET /control` | `WRITE_TOKEN` | Plain-text operator control record |
| Constellation | `X-Constellation-Key` | `/constellation/git/*` — GitHub; **not** Astronomicon keys |

**Live keyed families (summary):** `identity`, `lab`, `bench`, `data`, `documents`, `mailbox`, `worldline` (`event.log`), plus separate `constellation.git`. Bench names/seats remain live through `CLAUDE_KEY`, `BENCH_KEYS_JSON`, legacy title-case seat secrets, and `JULES_KEY`. Details: [u_os_dev/README.md](u_os_dev/README.md) and [u_os_dev/worker/README.md](u_os_dev/worker/README.md).

**Cursor MCP (one stdio process):** the full bridge is a **single fused roster** (Panini, lab mirror, cockpit directive, mailbox, Constellation, hygiene) — [u_os_dev/astronomicon_mcp/README.md](u_os_dev/astronomicon_mcp/README.md) (section **MCP tools (one roster)**). [THRONE-Akatosh](u_os_dev/throne_akatosh/README.md) reuses that stack and adds local vault tools. Not a host OS shell.

**Gate cities (promotion):** merged **GitHub `main`**, **vault triad**, optional deliberate **edge → export → commit** — never silent two-way sync. **Many broadcasts, few gates.**

**Deploy (Worker):** `cd u_os_dev/worker` → `npx wrangler deploy`; secrets via `wrangler secret put` (see [worker/README.md](u_os_dev/worker/README.md)). Vars examples: `ALLOW_PATH_KEY_IO` (required for `/tool/*` + vault push worldline), `IMMUNE_BLOCK_APPENDS`.

**Security / drill:** [SECURITY_GAUNTLET.md](u_os_dev/SECURITY_GAUNTLET.md) · [RED_TEAM_PROTOCOL.md](u_os_dev/RED_TEAM_PROTOCOL.md) · [MidnightEclipse/WARP_STORM.md](u_os_dev/MidnightEclipse/WARP_STORM.md) · [23_Project_StormIntoMidnight/README.md](../23_Project_StormIntoMidnight/README.md). **Immune / worldline:** [worker/IMMUNE_SYSTEM.md](u_os_dev/worker/IMMUNE_SYSTEM.md).

**Vault-wide warp narrative** (Command, Jules, two doors): [README § Lab infrastructure — Warp: lab edge](../README.md#warp-lab-edge-unified-story).

---

## Operator commands (`u_os_dev`)

All paths from **vault root** unless `cd` shown.

| Action | Command |
|--------|---------|
| **Push vault → edge** (export + `POST /md` + `event.log`) | `cd 08_Project_Astronomicon/u_os_dev` then `python push_vault_to_astronomicon.py` or `push_vault_to_astronomicon.bat` — needs `WRITE_TOKEN` |
| **Upload only** (no worldline) | `python 08_Project_Astronomicon/u_os_dev/push_public_lab_to_edge.py --export` |
| **Export tree only** | `python 08_Project_Astronomicon/u_os_dev/export_script.py` → `out/public_lab/` |
| **Mirror edge → disk** | `python 08_Project_Astronomicon/u_os_dev/sync_worker_to_local.py` — auto-resolves `ASTRONOMICON_KEY`, `UOS_READ_KEY`, or `u_os_dev/.astronomicon_key`; use **`--backup`** before overwrite and `--read-key` only to override ([MAILBOX_PREFLIGHT](u_os_dev/MAILBOX_PREFLIGHT.md)) |
| **Bounty digest** | `python 08_Project_Astronomicon/u_os_dev/publish_vault_bounty_digest.py` (optional `--push`) |
| **Cerberus ingest** | `python 08_Project_Astronomicon/u_os_dev/astronomicon_cerberus_ingest.py` |

Implementation: [vault_astronomicon_push.py](u_os_dev/vault_astronomicon_push.py). Per-path inventory: [u_os_dev/README.md](u_os_dev/README.md).

---

## Public lab → D1 (`lab.list` / `lab.read`)

[export_script.py](u_os_dev/export_script.py) builds **`u_os_dev/out/public_lab/`** (sanitized README / boards / session / throne docs per policy). Operator push uploads allowlisted files to Worker D1 via **`POST /md`** so throne agents see the same paths. **After editing** `THRONE_ONBOARDING.md`, `MAILBOX.md`, or `THRONE_NAME_MODEL.md`, run the **canonical push** above. Include/exclude rules (full tables): [u_os_dev/README.md — Public lab export](u_os_dev/README.md#public-lab-export-phase-1).

---

## Genomics pipeline (conceptual stages)

**Inputs:** matrices, samples, metadata. **Outputs:** clusters, DE, pathways, communication, trajectories, governance-style indices. **Canonical new code:** [10/methods/run_pipeline.py](../10_Project_DiscordIntoSymphony/methods/run_pipeline.py) · [QUICK_START](../10_Project_DiscordIntoSymphony/QUICK_START.md). **Legacy portable suitcase:** `10_Project_DiscordIntoSymphony/_archive/Analysis 2026-03-13 15-00/` (`run_master.R`, `run_astronomicon.bat`, bundled `python_pipeline/`).

| Phase | Purpose |
|-------|---------|
| Ingest → QC → reduce → annotate → compare → communicate → trajectory → interpret → export | R and Python implementations differ; same config idea (sample sheet + project config). |

Full stage table (R vs Python columns): see **[Symphony README](../10_Project_DiscordIntoSymphony/README.md)** for execution detail.

---

## Path compass (canonical)

| Lane | Path |
|------|------|
| **Active Python GEM** | `10_Project_DiscordIntoSymphony/methods/` |
| **Legacy R+Python suitcase** | `10_Project_DiscordIntoSymphony/_archive/Analysis 2026-03-13 15-00/` |
| **Data** | `10_Project_DiscordIntoSymphony/data/` |
| **Warp (this project)** | `08_Project_Astronomicon/u_os_dev/` |

**08 root:** `README.md` (this file), `Dockerfile`, `BOUNTY_BOARD.md`, `WORLDLINE.md`, `u_os_dev/`, `_archive/`. No `Analysis/` or pipeline `data/` under **08**.

---

## How to run (quick)

**R master (legacy tree), from vault root:**

```bash
Rscript "10_Project_DiscordIntoSymphony/_archive/Analysis 2026-03-13 15-00/run_master.R" .
```

**Docker** (build from **vault root**): `docker build -t astronomicon-pipeline -f 08_Project_Astronomicon/Dockerfile .`

**Local Streamlit UI** (optional): [u_os_dev/web/app.py](u_os_dev/web/app.py) — resolves `run_master.R` under **10**; localhost only.

Stress tests, portable launchers, and Python 12-layer details: **[10 Symphony README](../10_Project_DiscordIntoSymphony/README.md)** and folders above.

---

## Data layout

Heavy datasets: **[10_Project_DiscordIntoSymphony/data/](../10_Project_DiscordIntoSymphony/data/)**. Use `DATA_LOCATION.txt` and experiment folders when wiring sample sheets.

---

## Governance indices

Python pipeline adds **governance profiling** (composite indices) in layered scoring — see Symphony docs. R produces core objects and DE; Python adds gene sets, GSEA, and governance layers on the same conceptual flow.

---

## Fusion history (short)

- Pipeline **bytes** moved to **10** (2026-03-27); **08** holds warp + this README + Docker + `_archive/`.
- `u_os_dev/export_lab_content.md` fused into [u_os_dev/README.md](u_os_dev/README.md) § Public lab export (archived copy in `_archive/`).
- Vault warp docs fused into this README (2026-03-30): single AI-readable project entry.
- [astronomicon_mcp/README.md](u_os_dev/astronomicon_mcp/README.md) (2026-03-31): MCP tools merged into **one roster** + **code layout** map (no separate tier vs lab vs cockpit doc splits).

---

## Deprecated

| Do not use | Use instead |
|------------|-------------|
| `08_Project_Astronomicon/Analysis …` | **10** paths in compass |
| `08_Project_Astronomicon/data/` | `10_Project_DiscordIntoSymphony/data/` |
| Docker context = 08 folder only | Build from **vault root** with `-f 08_Project_Astronomicon/Dockerfile .` |

---

## Deeper indexes (optional reads)

| Concern | File |
|---------|------|
| Worker routes, auth, env | [u_os_dev/worker/README.md](u_os_dev/worker/README.md) |
| Infra IDs | [u_os_dev/STATUS.md](u_os_dev/STATUS.md) |
| Credentials / surfaces | [u_os_dev/LAB_ACCESS.md](u_os_dev/LAB_ACCESS.md) |
| AI uncanny doctrine | [HALO_VALLEY_OF_THE_WARP.md](HALO_VALLEY_OF_THE_WARP.md) |
| MCP (Cursor → Worker) | [u_os_dev/astronomicon_mcp/README.md](u_os_dev/astronomicon_mcp/README.md) |
| THRONE-Akatosh | [u_os_dev/throne_akatosh/README.md](u_os_dev/throne_akatosh/README.md) |
| Potential / future lanes | [BOUNTY_BOARD.md](BOUNTY_BOARD.md) · [u_os_dev/worker/README.md](u_os_dev/worker/README.md#not-live-on-the-current-worker) · [u_os_dev/home_beacon/README.md](u_os_dev/home_beacon/README.md) |
| Worldline soft trust (O6) | [u_os_dev/WORLDLINE_SOFT_TRUST.md](u_os_dev/WORLDLINE_SOFT_TRUST.md) |
| Throne onboarding / mirror | [u_os_dev/THRONE_ONBOARDING.md](u_os_dev/THRONE_ONBOARDING.md) |

---

## Attribution

Gellar field / phase narrative — Antigravity (March 2026). Dynamic-for-AI constraints — Claude (March 2026). Prior standalone warp fragments archived under `u_os_dev/_archive/` / `_archive/` with fusion into this README and vault root.