Skip to content

docs: NOW.md refresh + RUNBOOK-INDEX walk/generate_town rows + KIMI-ONBOARDING (#1623) #1624

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
100yenadmin merged 3 commits into from
Jul 21, 2026
Merged

docs: NOW.md refresh + RUNBOOK-INDEX walk/generate_town rows + KIMI-ONBOARDING (#1623) #1624

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
00a7aa3
docs: NOW.md refresh + RUNBOOK-INDEX walk/generate_town rows + KIMI-O…
Jul 20, 2026
b8f364d
docs: review-fold — KIMI-ONBOARDING provenance + self-reference sweep…
Jul 21, 2026
30b193a
docs: truth fixes from third review — PR count/attribution/open-PR se…
Jul 21, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
115 changes: 115 additions & 0 deletions docs/KIMI-ONBOARDING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,115 @@
# KIMI-ONBOARDING — Kimi's routing doc into WorldOS

> Written 2026-07-20 by the Kimi orchestrator after a full 8-agent recon sweep.
> **Status: tracked — landed via PR #1624 (closes issue #1623).** It is the Kimi-side entry point; Claude-side agents
> can read it as-is.
> **Decision (owner-asked):** we *use and link to* the existing Claude-side documentation — it is live-edited
> within days, so duplicating it would stale immediately. This file is routing + interop glue only.

---

## 1. Where everything lives

| Thing | Path / identity | Notes |
|---|---|---|
| Canonical checkout | `/Users/lume/WorldOS` | GitHub `electricsheephq/WorldOS`; local branch **`base` tracks `origin/main`**; tip `fd23e972` (dress_focal v2 / #1621, 2026-07-16) |
| Live worktrees | `/Users/lume/WorldOS-worktrees/` (same dir as lowercase spelling, case-insensitive APFS) | `wt-owner-play` — owner's play copy, branch `main` @ `c8a0b155`, **`.worldos-keep` = never touch**; behind main → `git pull --ff-only origin main` BEFORE any owner reseed (schema-skew class, OPERATIONS.md). `walk-gate-hardening` — clean, @ `92edf8d7`, looks merged; only its owning lane may prune it |
| Stale clone (trap) | `/Volumes/LEXAR/repos/WorldOS` | Jul-1 clone @ `76439e2`, ~19 days behind. Do not mistake for canonical |
| Session scratch/evidence | `~/worldos-session-notes` → symlink to `/Volumes/LEXAR/Codex/offloaded-local/2026-07-09/worldos-session-notes` (9.8 GB) | Newest: `walkability-fix-2026-07-16/`, `ship-2026-07-15/` |
| Unity player install | `/Users/lume/Applications/WorldOSPlayer.app` | Jul 16 12:16 build |
| Built app | `dist/` — **EMPTY right now** (no `dist/WorldOS.app` exists) | AGENTS.md defines the built app as the product; last app evidence early July |
| GEX44 backups | `/Volumes/LEXAR/Codex/worldos-unity-backups/` | `worktree-20260716.tgz` confirmed |

## 2. Reading order (doc routing)

1. `docs/OPERATIONS.md` — the bootstrap (fresh, Jul 16). Universal Run Contract: every run closes HEALTH → EVIDENCE → SCORE → VERDICT → POINTER.
2. `VISION.md` — pillars + load-bearing invariants + decision-by-eval.
3. `docs/ACTIVE-GOAL.md` — the standing driver + blocker law (policy is ageless, blocker table stale by construction).
4. `docs/roadmap/PRODUCT-ROADMAP.md` — the plan (durable); its §4b execution-state block is stale (Jul 8).
5. **`docs/roadmap/PROCEDURAL-SCORECARD.md` (Jul 16) — the freshest narrative truth** for the generator chain; narrates the tip events (dress_focal v2/#1618, the wing hardening, the dwing-wing 0-adopted close-out).
6. `docs/ROOM-PIPELINE-RUNBOOK.md` (Jul 16) — the 11-step room pipeline; §10b sandbox hot-load gate loop; §11 walkability ship gate (BOTH beauty panel AND `qa/walk_test.py` GREEN to ship).
7. `qa/PANEL-PROTOCOL.md` (Jul 16) — the versioned blind-panel ruler; nobody freehands the ruler; author never renders own verdict.
8. Active sprint charter: GitHub issue **#1386** (Act II close-out, Rendered Felt) — box claim queue lives in its comments.
9. `docs/roadmap/NOW.md` — **refreshed to the 2026-07-20 truth in PR #1624** (the Jul-9 staleness is resolved); it is again the you-are-here surface. Keep it current per its session-close contract (update at every session close / charter transition).
10. Live plan (Claude-side but plain markdown): `~/.claude/plans/bubbly-cooking-stallman.md` — read **lines 596–668 first** (final log + queue); the CURRENT STATE block at 669+ is an older anchor.

## 3. Live state snapshot (verified 2026-07-20)

- **Generator chain merged & staged on main**: 13 PRs — spine (#1604–#1609, incl. sha-pinned certifications #1607 + ledger walk surface #1608), generator (#1610/#1611/#1621), instruments (#1613–#1616). dress_focal v2 gives every generated room 3 non-collinear fire beacons; paint has an `err_cells ≤ 0.35` hard gate with similarity re-registration; walk gates are fire-masked tri-state (GREEN/RED/ERROR).
- **Task #76 (next-cycle packet) is IN FLIGHT** — stage 1 (beacon regen) opened as PR #1625; the render → paint → gate half remains — see §4.
- **QA truth**: `qa/RRI.json` = RRI 2.7, release_ready=false, 3/11 gates, 1-of-5 personas — partial/harness-contaminated and unsuperseded (no valid release verdict exists). Scores ledger: 117 runs, visual-only since Jul 10. Walk-GREEN: crypt, tavern, throne_hall (live) + shop, tavern_snug (pinned certs in `qa/certifications/`). dwing wing: 0-adopted / 3 honest negatives (owner-falsified adoptions → "instruments adjudicate eyeballs").
- **Live campaign**: `play-state/app-gate-v105-b/campaigns/camp_280cfd4d22a0` — DM budget-stopped after 2 turns (Jul 8).
- **Open PRs that matter**: #1617 (Unity persistence runbook — its OPERATIONS.md sections are NOT in base yet), #1498 (outdoor LoRA, blocked on Scenario train-model quota — owner decision), #1298 (day-plate selection, intentionally unmerged pending owner), #1012 draft (slab tiering, A/B-gated), #1622 (dependabot).
- **GEX44**: reachable, up 19 days, near-idle (probed 2026-07-20). Unity project saved via LFS + autosave cron; **GitHub LFS push blocked on paid data pack (~$5/mo owner billing decision)** — local commits + LEXAR tarball are the save story meanwhile.

## 4. The next-cycle packet (Task #76 — the staged opener)

Source: `~/.claude/tasks/237280f0-e8fe-4529-bb6e-72957d537c61/76.json` (status: pending) + GitHub issues #1618/#1619/#1620 + plan STATE block. All paths verified to exist.

1. **Regen** the wing with dress_focal v2 via `tools/generate_town.py` (staged on main @ `fd23e972`).
2. **Box render ×3** per ROOM-PIPELINE-RUNBOOK §3 (greybox render — the shaded base + optional depth/normal sidecars) + `~/.claude/skills/gex44-unity-host/SKILL.md`; batch the #1616 T-pose registry-sync + player rebuild into the same box build; end the box session with `/home/unity/worldos-unity-save.sh`.
3. **Paint** via `qa/paint_room.py --boxes` (err_cells hard gate auto-warps via the similarity fit).
4. **Hot-load sandbox gates** per runbook §10b (fire-masked, tri-state; cycle `current_room` per room).
5. **Blind-adjudicated verdicts** per `qa/PANEL-PROTOCOL.md` — panels via `qa/panel_workflow.mjs` with `CAL_shipped_shop` calibration reference.
6. Adopt or park per verdict; certifications + `record_room_walk` on adoption.

- Companions: **#1619 render_recipe** (zero-CU code; consider landing BEFORE the repaint — it kills recipe-authoring bugs) and **#1620** experience gates.
- **Budget gate**: the cycle costs ~140 Scenario CU; ~160 CU remained as of 2026-07-16 19:00 local with a measured 2/6 bug-fix-repaint base rate → the previous orchestrator deliberately handed off rather than strand it mid-budget. **Update 2026-07-20: Scenario CU refilled (5k+) — the "needs fresh budget" blocker is cleared; still confirm the balance before starting step 3.**

## 5. GEX44 access (probed working 2026-07-20)

- Secrets (never print values): `~/.openclaw/secrets/evaos-gpu-gex44-1-key`, `~/.openclaw/secrets/gex44.env` (defines `GEX44_SSH_HOST/USER/PORT/KEY`, `GEX44_UNITY_*` etc.). Endpoint (from tracked docs): `root@46.4.26.123`. Moonlight/WireGuard configs also in that dir for display.
- **All box access multiplexes over ONE ControlMaster** at `/tmp/gex44-cm.sock` (rapid separate ssh trips trip fail2ban and kill the master for ~10–17 min — batch box checks into one ssh):
`ssh -i ~/.openclaw/secrets/evaos-gpu-gex44-1-key -o BatchMode=yes -o StrictHostKeyChecking=yes -o UserKnownHostsFile=~/.openclaw/support/known_hosts -o ConnectTimeout=15 -o ServerAliveInterval=30 -M -S /tmp/gex44-cm.sock -f -N root@46.4.26.123`
- Tunnels: Unity-MCP `ssh -N -L 8080:127.0.0.1:8080 …`; reverse combat-surface `-R 8765:127.0.0.1:8770` via the master; NoMachine desktop `-L 4000`.
- On box: Unity `6000.5.1f1` project `/home/unity/worldos-unity` (drive as user `unity`, **Built-in Render Pipeline — not URP**); Unity-MCP on localhost `:8080` (~42 tools, `execute_code` needs `action:"execute"` + `safety_checks:false`); ComfyUI finisher `:8188`; render scripts versioned in repo at `extensions/renderers/unity/scripts/` (deploy to box, never author box-only).
- **Discipline**: single-tenant — claim by commenting on charter #1386 BEFORE any box op; repo-side work first; `chown -R unity:unity` touched files → ctrl+r → restore the scene you found → **save** (`sudo -u unity /home/unity/worldos-unity-save.sh --push` if anything scene/asset/build changed) → comment release. One bounded MCP op at a time; never `pkill -9`; never touch Mac:8765 (Eva's bridge; WorldOS uses 8770).
- Box-drive recipe pattern: `qa/evidence/dungen-spike/BOX-DRIVE-RECIPE.md`.
- Fallback: 32 GB `support-vm-1` (`root@178.104.123.213`, key `~/.openclaw/secrets/cloud-deploy-key`), preflight via `python3 qa/support_vm_preflight.py`; cannot prove Mac-only surfaces.

## 6. Skills & agent profiles — porting decision (read-on-demand, NO symlinks/copies)

The skill surface is live-edited (worldos-dev touched Jul 15, blind-adjudicator born Jul 16); copies stale within days and symlinks would mis-register foreign files as Kimi-managed skills. Kimi reads absolute paths natively — so:

| Surface | Path | How Kimi uses it |
|---|---|---|
| Dev loop (canonical) | `/Users/lume/WorldOS/.claude/skills/worldos-dev/SKILL.md` | Read before any dev loop |
| Decision apparatus | `/Users/lume/WorldOS/.claude/skills/worldos-decide/SKILL.md` | Read when a decision lacks an eval |
| GEX44/Unity lane | `~/.claude/skills/gex44-unity-host/SKILL.md`, `~/.claude/skills/unity-asset-stack/SKILL.md` | Read before any box op |
| Visual critic / asset gen | `/Users/lume/WorldOS/.claude/skills/visual-critic/SKILL.md`, `.../asset-gen/SKILL.md` | Read on those lanes |
| Blind adjudicator | `~/.claude/agents/blind-adjudicator.md` | **Port the prompt verbatim** into a Kimi read-only subagent (`plan`/`explore` type) for gate verdicts — self-contained, model-agnostic |
| Other agent profiles | `~/.claude/agents/{coder,deep-reasoner,fast-worker,codex-worker}.md` | Map frontmatter to Kimi subagent types (`coder`/`plan`/`explore`) |
| WorldOS memory index | `~/.claude/projects/-Users-lume/memory/worldos-index.md` | Read on any WorldOS resume |
| Ops runbook | `~/.claude/runbooks/worldos-evaos-ops.md` | GLM lane, GitNexus reindex, Unity persistence |
| Routing ledger | `~/.claude/routing-ledger.jsonl` | **Shared append-only JSONL** — Kimi appends rows (`{"ts","lane","task","outcome","repo","note"}`) so Claude-side sessions see Kimi dispatches |
| Fable lane table | `~/.claude/CLAUDE.md` | "Fable = orchestrator only, the brain never types" → the Kimi orchestrator inherits that role; cheaper work delegates to subagents |

Do NOT port: Claude hooks, stop-guards, keepalive ticks (Claude-app mechanics; Kimi has its own turn lifecycle). `.mcp.json` (engine/rules/voice stdio servers) is portable in substance — substitute `${CLAUDE_PLUGIN_ROOT}` → `/Users/lume/WorldOS` if ever wired.

**Known gap — GitNexus**: this repo's AGENTS.md mandates GitNexus `impact` before edits and `detect_changes` before committing, but Kimi has no `mcp__gitnexus__*` tools. Fallback: the CLI (`node .gitnexus/run.cjs analyze`, index fresh at Jul 16 17:12) + grep — or the owner grants an explicit waiver / wires the MCP.

## 7. Kimi ↔ Claude interop contract (both sides co-drive)

Shared surfaces that make either side's work visible to the other:
1. **git + GitHub** — the trunk truth; PR loop per OPERATIONS.md (worktree off main → additive change → focused pytest + `qa/fast_gate.sh` → PR → review-gated merge; shepherd every PR to merged/parked; `gh pr merge <n> --squash --auto`).
2. **Routing ledger** — both sides append (`~/.claude/routing-ledger.jsonl`).
3. **Scores ledger** — every scored run to `qa/scores_db.py` with provider/methodology stamps.
4. **POINTER step** — update the lane's charter/issue + `docs/roadmap/NOW.md` at session close (NOW.md refreshed in #1624; the POINTER step keeps it current).
5. **Universal Run Contract** — HEALTH → EVIDENCE → SCORE → VERDICT → POINTER, every run type.
6. **Box claim queue** — charter #1386 comments, regardless of which agent drives.

## 8. Where Kimi can add value now (ordered, cheapest-first)

1. **Doc-hygiene PR — DONE (this file + NOW.md + RUNBOOK-INDEX land via #1624)** (zero CU, zero box): refreshed `docs/roadmap/NOW.md` to the 2026-07-20 truth + added RUNBOOK-INDEX rows for the `qa/walk_test.py` / `tools/generate_town.py` chain. Pure repo loop.
2. **#1619 render_recipe** (zero CU): the code half that kills recipe-authoring bugs — the previous session recommended landing it BEFORE the repaint. **Update: render_recipe PR #1626 opened, in review.**
3. **Task #76 next cycle** (CU refilled; box claim via #1386): the full regen → render → paint → gate → adjudicate loop, §4 above. **Update: stage 1 regen opened as PR #1625.**
4. **#1620 experience gates** and the open companions of #1618.
5. Later/larger: a valid 5-persona RRI sweep to replace the contaminated f5500ac row; dist/WorldOS.app rebuild; towns beyond the 4-room proof (exteriors/streetscape generator is the known gap; TILED-SPACE-SPIKE ruling says towns = layout problem).

## 9. Open questions for the owner

1. Scenario CU balance — **refilled 2026-07-20 (5k+)**; the "needs fresh budget" framing is stale. Open remainder: land #1619 (PR #1626, in review) first and defer paint?
2. GitHub LFS data pack for the box repo (~$5/mo) — buy, or keep tarball-only saves?
3. GitNexus — **RESOLVED 2026-07-20: the MCP is wired for Kimi** (impact/detect_changes live from the canonical checkout; index rebuild to the tip runs detached).
4. PR this onboarding doc (+ NOW.md refresh) through the normal loop? — **RESOLVED: landed via #1624.**
5. Green-light to claim the box on #1386 and start Task #76 — **GRANTED 2026-07-21** (CU refilled; reviews + merge first).
2 changes: 2 additions & 0 deletions docs/RUNBOOK-INDEX.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -49,6 +49,8 @@
| room/backdrop gen | `qa/export_scene_grid.py` → `qa/gen_room_from_scene_grid.sh` → `qa/deploy_room.sh` (live Unity lane; ⚠ `--layered` naming lives on the quarantined Godot tool) | Scenario CUs | plate PNG + pin-check + control-anchored panel (MUST include a disclosed WorldOS house-style anchor — e.g. crypt_dense_v1 — alongside the disguised PoE2/BG2 control; a PoE2-only or absolute-score reading is NOT sufficient for adoption, see plate-style-regression #2026-07-08) + room_recipes entry + library/rooms promotion | visual (panel) | asset-gen skill |
| character/asset gen | asset-gen skill (Meshy/Tripo/Scenario/PixelLab) | ~5-25 CU/asset | registry entry (gen_recipe) + grounded upright render per actor + evidence commit | ⚠ NONE today — gate via pre-gate + panel on first composed use | asset-gen skill |
| plate-sprint generate→gate→panel→gallery loop | `qa/plate_loop.py` (two-phase: phase 1 generates + runs the deterministic registration/pre-gates + stages the 5-scorer blind panel packet; phase 2 ingests the orchestrator-run panel verdict) | Scenario CUs + panel cost | registration-gate result + staged panel packet (phase 1) then the scores_db row + gallery row (phase 2); an HTML gallery contact sheet (`--gallery <html>`) is UPSERTED with one row per scored candidate (every iteration, not just the adopted one) — owner-facing morning posts embed the best-scoring frame from that gallery | visual (surface="visual", auto via phase 2) | worldos-dev skill + `docs/roadmap/PLATE-RECIPE-DECISION.md` (adopted recipe: flux ControlNet base + Gemini style pass, registration/panel thresholds) |
| town/room generation chain | `tools/generate_town.py` → `qa/seed_gfx_town.py` | free, zero-CU local | fail-loud static gates incl. the beacon-geometry bar (generator self-gate; seeded world walks every cross_door hop) | — (static gates; output feeds the walk gate) | `docs/roadmap/PROCEDURAL-SCORECARD.md` §THE TOWN COMMAND CHAIN · last-verified 2026-07-20 |
| room walkability gate (binding Tier-0 ship gate) | `qa/walk_test.py --room <room>` | free ($0), live player sandbox | `qa/evidence/walk-*/` reports (walk_report.json + contact sheet) | `walk_gate` in scores_db (class=room rows via `record_room_walk`) | `docs/ROOM-PIPELINE-RUNBOOK.md` §11 · last-verified 2026-07-20 |

## Known wiring gaps (tracked)
1. ~~**Manual-append bucket** (duo, sprint, sweep, app gate, RRI)~~ — CLOSED #1414: each runner now
Expand Down
Loading
Loading