# u-os.dev — `u_os_dev` inventory

**Reviewed by:** GitHub Copilot Agent

**Fused AI-readable warp story + operator commands:** [../README.md](../README.md) (Project Astronomicon: *Warp and edge*, *Operator commands*, *AI orientation*).

This README is the **per-path inventory** of `u_os_dev/` and **copy-paste procedures** (public lab export, push, bounty digest). **Worker route authority:** [worker/README.md](worker/README.md).

**Quick links:** [../README.md#operator-commands](../README.md#operator-commands) · [MAILBOX_PREFLIGHT.md](MAILBOX_PREFLIGHT.md) · [STATUS.md](STATUS.md)

Implemented warp reality lives in [../README.md](../README.md), [STATUS.md](STATUS.md), and [worker/README.md](worker/README.md). Potential lanes that are **not** live on the worker yet live in [../BOUNTY_BOARD.md](../BOUNTY_BOARD.md), [home_beacon/README.md](home_beacon/README.md), and [warp_command_contract/warp_command_schema.json](warp_command_contract/warp_command_schema.json).

## Root directory (what each top-level item is)

Hygiene: one row per **folder or file** at `u_os_dev/` (not recursive into `worker/`, etc.).

| Path | Role |
|------|------|
| **`worker/`** | Cloudflare Worker source (`u-os.dev`) — routes, D1, deploy via Wrangler. |
| **`warp_command_contract/`** | `POST /warp/command` **stub** + `warp_command_schema.json` + `sample_request.json` (local tests, [home_beacon](home_beacon/README.md)). |
| **`astronomicon_mcp/`** | MCP server (Cursor → Worker HTTP). **Unified tool roster:** [astronomicon_mcp/README.md](astronomicon_mcp/README.md) (one table — Panini, lab, cockpit, mailbox, Constellation, hygiene). |
| **`MidnightEclipse/`** | Tier B smoke / `--storm` / `--grandmaster` edge sweep (BreakSuite, recovery checks, safe burst). Project 23 wraps this for host + vault reality checks. |
| **`BreakSuite/`** | Executable SECURITY_GAUNTLET probes (`break_suite.py`). |
| **`ADVERSARY_PLAYBOOK.md`** | Layered adversary program: OWASP API Top 10 map, Tier C tools (Nuclei / ZAP / RESTler), rules of engagement — complements Break Suite + storm. |
| **`openapi/`** | Partial `astronomicon_worker_stub.yaml` for RESTler / contract inventory. |
| **`adversary_tools/`** | Optional example scripts + `env.example` for Tier C (tools not vendored). |
| **`home_beacon/`** | Your PC as a warp target (local HTTP + tunnel). |
| **`local_mirror/`** | Output of `sync_worker_to_local.py` (`bench/BENCH.md`, inbox, shared pad, bounty mirror). |
| **`out/public_lab/`** | Generated tree from `export_script.py` (sanitized vault mirror). **Include/exclude rules:** [§ Public lab export](#public-lab-export-phase-1). |
| **`tests/`** | Stdlib tests (`publish_vault_bounty_digest`, etc.). |
| **`MAILBOX.md`** | Mailbox queue — single canonical page (Panini vs Bearer). |
| **`THRONE_NAME_MODEL.md`** | NAME vs THRONE vs `mech`; starter registry table. |
| **`colab/`** | Notebooks (mailbox / warp helpers). |
| **`web/`** | Local pipeline launcher and small helper assets. |
| **`_archive/`** | Superseded worker and documentation artifacts kept for history after unification passes. |
| **`scaffold_time_gated/`** | Legacy scaffold / experiments. |
| **`_archive_pre_unification/`** | Historical notes (not canonical). |
| **`export_script.py`** | Builds `out/public_lab/` (see [§ Public lab export](#public-lab-export-phase-1)). |
| **`vault_astronomicon_push.py`** | **Single implementation module** (export, POST `/md`, `event.log`, helpers). Entry points below are thin wrappers. |
| **`push_vault_to_astronomicon.py`** | **Canonical CLI:** calls `main_full_push` — same as module’s default behavior. See [§ After export](#after-export). |
| **`push_vault_to_astronomicon.bat`** | **Windows:** runs `push_vault_to_astronomicon.py` (`py -3` or `python`); optional `.write_token`. |
| **`push_public_lab_to_edge.py`** | **Upload-only CLI:** calls `main_upload_only` (POST `/md`; no `event.log`). |
| **`ASTRONOMICON_CERBERUS_BIOSHIP_PIPELINE.md`** | Edge ingest: parallel Cerberus scan on a tree (Lantern VM), optional Bioship ferry to local machines. |
| **`astronomicon_cerberus_ingest.py`** | Implements that pipeline — default root `out/public_lab/`; `--include-documentation` for `.md`; `--bioship-out` wraps **PROMOTE** payloads. |
| **`MidnightEclipse/WARP_STORM.md`** | **Canonical** Warp Storm runbook (operational full test suite); dual totems, layers, WS-01. |
| **`MidnightEclipse/warp_storm_full_stack.py`** | One-run **Dual Totems**: Edge + FORM primers + `public_lab` ingest + Lantern checklist. |
| **`LANTERN_TOTEM_SCENARIOS.md`** | White-hat Lantern 1/2 drills and `CONTROL_*` artifact names. |
| **`sync_worker_to_local.py`** | Pull edge state into `local_mirror/`. |
| **`publish_vault_bounty_digest.py`** | Merges boards → `VAULT_BOUNTY_DIGEST.md` (regenerate; do not hand-edit long-term). |
| **`VAULT_BOUNTY_DIGEST.md`** | Generated digest (refresh via script above). |
| **`STATUS.md`** | Live stack IDs and pointers. |
| **`LAB_ACCESS.md`** | Credential classes and surfaces. |
| **`DESIGN_NOTES.md`** | Disclosure / design philosophy. |
| **`RESOURCE_MAP.md`** | Cost / subscription accounting. |
| **`SECURITY_GAUNTLET.md`** | Pre-rollout test matrix. |
| **`WORLDLINE_SOFT_TRUST.md`** | Threat model for D1/worldline as soft trust (vault **O6** part a). |
| **`worldline_chain_append.py`** | Minimal hash-chained JSONL for local exports (vault **O6** part b prototype). |
| **`RED_TEAM_PROTOCOL.md`** | Staged adversary protocol (incl. Jules). |
| **`CLOUDFLARE_TUNNEL_ON_BOOT.md`** | Tunnel boot order for home lab. |
| **`MAILBOX_PREFLIGHT.md`** | Snapshot mailbox mirror before overwrite; edge vs vault `MAILBOX.md`. |

**Protocol (read layer):** [../../11_Project_WordsOfTomorrow/PROTOCOL_WORDS_OF_TOMORROW.md](../../11_Project_WordsOfTomorrow/PROTOCOL_WORDS_OF_TOMORROW.md) — governance read contract; not duplicated here.

## Runtime surfaces (summary)

**AI door:** `GET https://u-os.dev/` for the canonical plain-information record, with JSON available via `?format=json`. **Surfaces + tool families (tables):** [../README.md § Warp, deployment, and AI-readable surfaces](../README.md#warp-deployment-and-ai-readable-surfaces). **Full route matrix:** [worker/README.md](worker/README.md).

## Constellation Git setup (security separated)

Constellation Git is a Gate Constellation: full GitHub collaboration while keeping lab machinery and keys separate.

Required Worker settings:

- `CONSTELLATION_GIT_KEY` (secret; required on `/constellation/git/*` operational routes)
- `CONSTELLATION_ALLOWED_REPOS` (CSV allowlist, e.g. `owner/repo-a,owner/repo-b`)
- `GITHUB_APP_ID`
- `GITHUB_APP_INSTALLATION_ID`
- `GITHUB_APP_PRIVATE_KEY` (secret; GitHub App private key PEM)

## Local mirror parity

Run local sync to keep file-native parity with edge state:

```bash
python 08_Project_Astronomicon/u_os_dev/sync_worker_to_local.py --watch-seconds 15
```

The sync script now resolves the seat key from `ASTRONOMICON_KEY`, `UOS_READ_KEY`, or a one-line local file at `08_Project_Astronomicon/u_os_dev/.astronomicon_key`.

If you want the root vault loop to do this automatically while the computer is up, run:

```bash
python scripts/vault_daemon.py --interval 30
```

With a seat key present, mailbox sync auto-starts; when the computer is down, the worker keeps the mailbox rows and the daemon catches up on resume.

Output:

- `local_mirror/bench/BENCH.md`
- `local_mirror/inbox/INBOX.md`
- `local_mirror/inbox/messages.json`
- `local_mirror/shared/SHARED_PAD.md`
- `local_mirror/bounty/BOUNTY_BOARD.md`

## Public lab export (Phase 1)

Produce a **sanitized** directory tree from the vault root for static hosting (e.g. GitHub → Cloudflare Pages) or zip upload. **Goal:** paths like `GET /README.md` and `GET /05_Project_LENG/BOUNTY_BOARD.md` can be served as markdown. The Worker now serves mirrored markdown directly at those vault-relative paths when the files are present in D1, while `lab.list` and `lab.search` remain the discovery layer.

### What to include

**Vault root (one level):**

| Path | Include | Note |
|------|---------|------|
| `_VAULT_STATE.md` | Yes | Live generated vault inventory; canonical ring snapshot for edge readers |
| `README.md` | Yes | Lab home + § Lab protocol |
| `BOUNTY_BOARD.md` | Yes | Vault cross-project bounties |
| `WORLDLINE.md` | If present | Vault session narrative (pushed to edge when in allowlist) |
| `DAEMON_PROTOCOL.md` | If present | Root daemon doctrine mirrored into `lab.read`; documentation only on the current edge |
| `HALO_PROTOCOL.md` | If present | Root protocol handoff |
| `u_os_dev/THRONE_ONBOARDING.md`, `MAILBOX.md`, `THRONE_NAME_MODEL.md` | Copied by [export_script.py](export_script.py) to `out/public_lab/` | Throne onboarding; [MAILBOX.md](MAILBOX.md); [THRONE_NAME_MODEL.md](THRONE_NAME_MODEL.md) |

**Per project (every top-level `NN_Project_*` that contains `README.md`):**

| Path | Include | Note |
|------|---------|------|
| `NN_Project_*/README.md` | Yes | **Auto-discovered** — no hardcoded list; new projects (e.g. 21, 22) export when the folder exists |
| `NN_Project_*/BOUNTY_BOARD.md` | If present | |
| `NN_Project_*/WORLDLINE.md` | If present | Canonical session narrative exported to the edge |
| `NN_Project_*/HALO_PROTOCOL.md` | If present | e.g. DiscordIntoSymphony |
| `NN_Project_*/BOOK.md` | If present | Bibliography + methods; Symphony includes **§5 Combined Codex** (fused registry) |

Legacy `SESSION_BREAKTHROUGHS_CURRENT.md` mirrors are no longer exported. The public lab follows the current `WORLDLINE.md` convention and removes stale session exports on regeneration.

**Exclude:** `_archive/`, `99_Archive/`, `.git/`; large analysis trees (e.g. `Analysis 2026-03-13 15-00/` — or README-only if you extend the script); any folder with `.venv`, `.R_libs_portable`, `node_modules`, `__pycache__`; `data/`, raw secrets, `.env`, keys; sanitize absolute paths if needed.

### Run

From **vault root**:

```bash
python 08_Project_Astronomicon/u_os_dev/export_script.py
```

Implementation: [export_script.py](export_script.py). Output: **`out/public_lab/`** — zip, push to a repo branch, or upload to Pages.

### After export

- **Throne / mailbox docs:** After editing `THRONE_ONBOARDING.md`, `MAILBOX.md`, or `THRONE_NAME_MODEL.md`, run the canonical push below (or `export_script.py` then [push_public_lab_to_edge.py](push_public_lab_to_edge.py) `--export`) so edge `lab.read` matches the vault.
- Commit `out/public_lab/` to a public repo or branch for Cloudflare Pages, **or**
- Push the same tree into Worker D1 so agents can use **`lab.list` / `lab.read`** on the edge (operator token).

**Canonical push (export + D1 upload + edge worldline):** one entrypoint from `u_os_dev` runs `export_script.py`, POSTs each allowlisted file to `/md`, then appends a Panini **`event.log`** entry on thread `vault-public-lab` (override with `UOS_WORLDLINE_THREAD`). Worldline logging uses **`GET /tool/event.log/...`** with `Authorization: Bearer` — the Worker must have **`ALLOW_PATH_KEY_IO=true`** so `/tool/*` Panini routing is enabled (see [worker/README.md](worker/README.md) vars / [STATUS.md](STATUS.md)).

**Unix / shell:**

```bash
cd 08_Project_Astronomicon/u_os_dev
export WRITE_TOKEN="<operator write token>"
python push_vault_to_astronomicon.py
```

**Windows (unified):** run [push_vault_to_astronomicon.bat](push_vault_to_astronomicon.bat) from Explorer or `cmd` (it `cd`s to this folder). Pass-through flags work: `push_vault_to_astronomicon.bat --dry-run --no-export`. Optional: create `u_os_dev/.write_token` with a single line (token); the batch file sets `WRITE_TOKEN_FILE` only if `WRITE_TOKEN` / `UOS_WRITE_TOKEN` / `ASTRONOMICON_KEY` are unset.

For the simpler live posture, keep exactly two local secrets if you need both lanes:

- `u_os_dev/.astronomicon_key` for the person's live seat key
- `u_os_dev/.write_token` for operator/version updates

- **`--no-export`** — skip export (use existing `out/public_lab/`).
- **`--dry-run`** — list files only; no POST, no `event.log` (pair with `--no-export` for a fast listing without regenerating).
- **`--worldline best-effort`** — if upload succeeds but `event.log` fails, exit 0 with a warning (default **`required`** = exit non-zero so you do not lose audit trail silently).
- **`--note-vault-worldline`** — append a short line to the vault root `WORLDLINE.md` after success (optional).

**Easier token handling (no token in shell history):** put the token alone in a file (e.g. `.write_token` in `u_os_dev`, gitignored) and run `WRITE_TOKEN_FILE=.write_token python push_vault_to_astronomicon.py`, or `python push_vault_to_astronomicon.py --token-file .write_token`.

**Lower-level upload only (no worldline):** [push_public_lab_to_edge.py](push_public_lab_to_edge.py) — e.g. `python push_public_lab_to_edge.py --export`.

**Preview:** `python push_public_lab_to_edge.py --export --dry-run` lists paths without POSTing.

Implementation: [vault_astronomicon_push.py](vault_astronomicon_push.py). CLIs: [push_vault_to_astronomicon.py](push_vault_to_astronomicon.py), [push_public_lab_to_edge.py](push_public_lab_to_edge.py). Redeploy the Worker after changing `lab.*` handlers.

*This section supersedes the former standalone `export_lab_content.md` (archived March 2026).*

## Vault-wide bounty digest (repo + optional edge)

Merge every project `BOUNTY_BOARD.md` **OPEN** section into one file (excludes `_archive/`, `out/public_lab/`, `local_mirror/`, etc.):

```bash
cd 08_Project_Astronomicon/u_os_dev
python publish_vault_bounty_digest.py
# default: writes VAULT_BOUNTY_DIGEST.md here only (no edge write)
# to push D1 copy at 08_Project_Astronomicon/VAULT_BOUNTY_DIGEST.md:
#   export ASTRONOMICON_KEY="<operator key with bounty.write>"
#   python publish_vault_bounty_digest.py --push
```

Use an **operator** key (not Jules watcher). Large digests may hit GET URL limits; the script warns if the request URL would be excessive.

Self-check (stdlib tests for skip rules, OPEN extraction, URL encoding): `python -m unittest discover -s tests -p "test_*.py" -v` from this directory.

## Canonical doc map

| Concern | Canonical file |
|---|---|
| Gellar field / deployment / dynamic-for-AI / deploy checklist | [../README.md § Warp, deployment, and AI-readable surfaces](../README.md#warp-deployment-and-ai-readable-surfaces) · [worker/README.md](worker/README.md) |
| **Pre-rollout security gauntlet (P0/P1, Tier A–C)** | [SECURITY_GAUNTLET.md](SECURITY_GAUNTLET.md) |
| **Red-team protocol (Tier D, Jules integration)** | [RED_TEAM_PROTOCOL.md](RED_TEAM_PROTOCOL.md) |
| **MidnightEclipse (Tier B thin smoke)** | [MidnightEclipse/README.md](MidnightEclipse/README.md) |
| **Break Suite (Tier B full battery, executable)** | [BreakSuite/README.md](BreakSuite/README.md) |
| **Astronomicon MCP (Cursor mech suit — fused stdio roster → Worker)** | [astronomicon_mcp/README.md](astronomicon_mcp/README.md) |
| **THRONE-Akatosh (Panini + local WordsOfTomorrow vault + audit + Cerberus + degraded queue)** | [throne_akatosh/README.md](throne_akatosh/README.md), [THRONE_AKATOSH.md](throne_akatosh/THRONE_AKATOSH.md) |
| **NAME / THRONE model (seats vs MCP body vs `mech`)** | [THRONE_NAME_MODEL.md](THRONE_NAME_MODEL.md) |
| **Mailbox queue (one page)** | [MAILBOX.md](MAILBOX.md) |
| **Throne onboarding (lab mirror vs `data/`, bench)** | [THRONE_ONBOARDING.md](THRONE_ONBOARDING.md) |
| **Vault bounty digest (merge all boards → file + optional edge)** | [publish_vault_bounty_digest.py](publish_vault_bounty_digest.py), output [VAULT_BOUNTY_DIGEST.md](VAULT_BOUNTY_DIGEST.md) |
| **Warp Storm (white-hat edge pressure: ME + red protocol + cadence)** | [MidnightEclipse/WARP_STORM.md](MidnightEclipse/WARP_STORM.md) |
| Claude bootstrap (warp) | [Vault README § Warp: lab edge](../../README.md#warp-lab-edge-unified-story) · [08 README § Warp](../README.md#warp-deployment-and-ai-readable-surfaces) |
| Runtime routes/auth/tool contracts | [worker/README.md](worker/README.md) |
| Protocol governance + failure envelope (read layer canonical) | [../../11_Project_WordsOfTomorrow/PROTOCOL_WORDS_OF_TOMORROW.md](../../11_Project_WordsOfTomorrow/PROTOCOL_WORDS_OF_TOMORROW.md) |
| Immune / worldline senescence | [worker/IMMUNE_SYSTEM.md](worker/IMMUNE_SYSTEM.md) |
| Infrastructure posture + resource IDs | [STATUS.md](STATUS.md) |
| Potential lanes and local beacon experiments | [../BOUNTY_BOARD.md](../BOUNTY_BOARD.md) · [home_beacon/README.md](home_beacon/README.md) · [warp_command_contract/warp_command_schema.json](warp_command_contract/warp_command_schema.json) |
| Access surfaces and credential classes | [LAB_ACCESS.md](LAB_ACCESS.md) |
| Design/disclosure philosophy | [DESIGN_NOTES.md](DESIGN_NOTES.md) |
| Cost/resource accounting | [RESOURCE_MAP.md](RESOURCE_MAP.md) |

## Project triad links

- Project README: [../README.md](../README.md)
- Project board: [../BOUNTY_BOARD.md](../BOUNTY_BOARD.md)
- Project session: [../WORLDLINE.md](../WORLDLINE.md)