Hero OS: comprehensive dev + ops documentation (freezone-style docs/) #99

New issue

Closed

opened 2026-03-27 00:42:59 +00:00 by mik-tf · 1 comment

mik-tf commented 2026-03-27 00:42:59 +00:00

Owner

Copy link

Goal

Create a structured docs/ directory in hero_services matching the pattern established in znzfreezone_deploy/docs/. Every developer and operator should be able to onboard, test, release, and troubleshoot from these docs alone.

Supersedes #81 (ecosystem docs) with a concrete structure.

Target structure

docs/
├── README.md              # Index + quick links
├── dev/
│   ├── e2e_checklist.md   # Upgrade existing — add vision, architecture table, how-to-run, layer counts
│   ├── architecture.md    # Infra diagram, service topology, socket strategy, proxy routing
│   ├── release.md         # Versioning, build pipeline, image tagging, deploy steps
│   ├── repos.md           # Repo map, how they relate, SSOT sources
│   └── testing.md         # 7-layer pyramid, how to run each layer, test file inventory
└── ops/
    ├── README.md          # Ops quick reference
    ├── runbook.md         # Troubleshooting: Mycelium down, service crash, socket missing, WASM stale
    ├── deploy.md          # Deploy checklist, rollback, verification, environment parity
    └── secrets.md         # Env vars, tokens, where they live, how to rotate

What exists today

• docs/e2e_checklist.md — 97 items, all passing, but lacks vision section, how-to-run, layer architecture table
• CLAUDE.md — has build system, branching, deploy pipeline mixed in with AI assistant instructions
• prompt.md — per-session context, not developer docs

Much of the content exists but is scattered across CLAUDE.md. The goal is to extract it into standalone docs that any developer can read without needing the AI context.

Per-file details

docs/dev/e2e_checklist.md (upgrade)

Model after https://forge.ourworld.tf/znzfreezone_code/znzfreezone_deploy/src/branch/development/docs/dev/e2e_checklist.md:

• Add Vision section (why the checklist exists, spec-first workflow)
• Add Test Architecture table (file → layer → purpose)
• Add 7-Layer Pyramid with current counts vs targets
• Add How to Run section with copy-paste commands for each layer
• Keep all 97 feature rows, ensure each maps to a specific test file

docs/dev/architecture.md (new)

• Service topology: hero_proc manages 30+ services via Unix sockets
• Proxy routing: URL prefix → socket lookup strategy (exact, _ui suffix, _http suffix)
• WASM shell: Dioxus hero_os_app, iframe islands, dock/window system
• OSIS: multi-context object storage, 546+ RPC methods, 9 domain schemas
• Build system: Docker container builds, [patch] injection, cargo-local-patches

docs/dev/release.md (new)

• Semver with -dev suffix
• Build targets (dist, dist-quick, dist-clean-wasm)
• Pack + push pipeline
• Forgejo release creation
• Deploy to herodev (registry vs direct transfer)
• Rollback procedure

docs/dev/repos.md (new)

• All repos under lhumina_code/ with purpose, language, binaries produced
• How they relate (hero_foundry builds both server + UI, hero_os builds WASM shell separately)
• SSOT sources: schemas, configs, profiles, service TOMLs

docs/dev/testing.md (new)

• 7-layer pyramid with test counts (253 total)
• How to run each layer locally and against remote
• Test file inventory (18 spec files, what each covers)
• Writing new tests: conventions, patterns, helper functions
• API vs browser blind spot rule

docs/ops/runbook.md (new)

• Mycelium down → mycelium-restart
• Service failed → hero_proc restart
• Socket missing → check binary, check TOML, check profile
• WASM stale → dist-clean-wasm, verify with strings
• Foundry UI broken → check which binary is deployed
• Registry push fails → direct SCP transfer workaround

docs/ops/deploy.md (new)

• Pre-deploy checklist (all tests pass, WASM verified)
• Deploy to herodev (pack, transfer, load, run)
• Post-deploy verification (smoke, integration, E2E, visual)
• Environment parity (same image, same env vars, same TOMLs)
• Rollback: make update ENV=herodev VERSION=<previous>

docs/ops/secrets.md (new)

• Required env vars: FORGEJO_TOKEN, OPENROUTER_API_KEY, GROQ_API_KEY, HERO_SECRET
• Where they live: ~/hero/cfg/env/env.sh
• How to source: source ~/hero/cfg/env/env.sh
• Docker login for registry

Approach

1. Move existing docs/e2e_checklist.md to docs/dev/e2e_checklist.md and upgrade
2. Extract content from CLAUDE.md into standalone docs (CLAUDE.md keeps AI-specific instructions only)
3. Write new ops docs from operational knowledge accumulated in prompt.md and memory
4. Keep docs minimal and actionable — no prose walls, lots of tables and commands

Signed-off-by: mik-tf

## Goal Create a structured `docs/` directory in `hero_services` matching the pattern established in [znzfreezone_deploy/docs/](https://forge.ourworld.tf/znzfreezone_code/znzfreezone_deploy/src/branch/development/docs). Every developer and operator should be able to onboard, test, release, and troubleshoot from these docs alone. Supersedes https://forge.ourworld.tf/lhumina_code/home/issues/81 (ecosystem docs) with a concrete structure. ## Target structure ``` docs/ ├── README.md # Index + quick links ├── dev/ │ ├── e2e_checklist.md # Upgrade existing — add vision, architecture table, how-to-run, layer counts │ ├── architecture.md # Infra diagram, service topology, socket strategy, proxy routing │ ├── release.md # Versioning, build pipeline, image tagging, deploy steps │ ├── repos.md # Repo map, how they relate, SSOT sources │ └── testing.md # 7-layer pyramid, how to run each layer, test file inventory └── ops/ ├── README.md # Ops quick reference ├── runbook.md # Troubleshooting: Mycelium down, service crash, socket missing, WASM stale ├── deploy.md # Deploy checklist, rollback, verification, environment parity └── secrets.md # Env vars, tokens, where they live, how to rotate ``` ## What exists today - `docs/e2e_checklist.md` — 97 items, all passing, but lacks vision section, how-to-run, layer architecture table - `CLAUDE.md` — has build system, branching, deploy pipeline mixed in with AI assistant instructions - `prompt.md` — per-session context, not developer docs Much of the content exists but is scattered across CLAUDE.md. The goal is to extract it into standalone docs that any developer can read without needing the AI context. ## Per-file details ### docs/dev/e2e_checklist.md (upgrade) Model after https://forge.ourworld.tf/znzfreezone_code/znzfreezone_deploy/src/branch/development/docs/dev/e2e_checklist.md: - Add **Vision** section (why the checklist exists, spec-first workflow) - Add **Test Architecture** table (file → layer → purpose) - Add **7-Layer Pyramid** with current counts vs targets - Add **How to Run** section with copy-paste commands for each layer - Keep all 97 feature rows, ensure each maps to a specific test file ### docs/dev/architecture.md (new) - Service topology: hero_proc manages 30+ services via Unix sockets - Proxy routing: URL prefix → socket lookup strategy (exact, _ui suffix, _http suffix) - WASM shell: Dioxus hero_os_app, iframe islands, dock/window system - OSIS: multi-context object storage, 546+ RPC methods, 9 domain schemas - Build system: Docker container builds, [patch] injection, cargo-local-patches ### docs/dev/release.md (new) - Semver with -dev suffix - Build targets (dist, dist-quick, dist-clean-wasm) - Pack + push pipeline - Forgejo release creation - Deploy to herodev (registry vs direct transfer) - Rollback procedure ### docs/dev/repos.md (new) - All repos under lhumina_code/ with purpose, language, binaries produced - How they relate (hero_foundry builds both server + UI, hero_os builds WASM shell separately) - SSOT sources: schemas, configs, profiles, service TOMLs ### docs/dev/testing.md (new) - 7-layer pyramid with test counts (253 total) - How to run each layer locally and against remote - Test file inventory (18 spec files, what each covers) - Writing new tests: conventions, patterns, helper functions - API vs browser blind spot rule ### docs/ops/runbook.md (new) - Mycelium down → mycelium-restart - Service failed → hero_proc restart - Socket missing → check binary, check TOML, check profile - WASM stale → dist-clean-wasm, verify with strings - Foundry UI broken → check which binary is deployed - Registry push fails → direct SCP transfer workaround ### docs/ops/deploy.md (new) - Pre-deploy checklist (all tests pass, WASM verified) - Deploy to herodev (pack, transfer, load, run) - Post-deploy verification (smoke, integration, E2E, visual) - Environment parity (same image, same env vars, same TOMLs) - Rollback: `make update ENV=herodev VERSION=<previous>` ### docs/ops/secrets.md (new) - Required env vars: FORGEJO_TOKEN, OPENROUTER_API_KEY, GROQ_API_KEY, HERO_SECRET - Where they live: ~/hero/cfg/env/env.sh - How to source: `source ~/hero/cfg/env/env.sh` - Docker login for registry ## Approach 1. Move existing `docs/e2e_checklist.md` to `docs/dev/e2e_checklist.md` and upgrade 2. Extract content from CLAUDE.md into standalone docs (CLAUDE.md keeps AI-specific instructions only) 3. Write new ops docs from operational knowledge accumulated in prompt.md and memory 4. Keep docs minimal and actionable — no prose walls, lots of tables and commands Signed-off-by: mik-tf

mik-tf referenced this issue 2026-03-27 00:43:11 +00:00

Comprehensive Hero ecosystem docs update (consolidates #42, #15) #81

mik-tf commented 2026-03-27 00:55:11 +00:00

Author

Owner

Copy link

Completed

Created comprehensive docs/ structure in hero_services, modeled after znzfreezone_deploy/docs/.

New structure

docs/
├── README.md              — Index + architecture overview
├── dev/
│   ├── architecture.md    — Service topology, proxy, WASM, OSIS, build system (349 lines)
│   ├── e2e_checklist.md   — Upgraded: vision, test architecture, how-to-run + 97 items (327 lines)
│   ├── release.md         — Versioning, build targets, deploy, rollback (170 lines)
│   ├── repos.md           — Repo map, SSOT sources, service inventory (106 lines)
│   └── testing.md         — 7-layer pyramid, 253 tests, conventions (191 lines)
├── ops/
│   ├── deploy.md          — Full deploy procedure, direct transfer, rollback (237 lines)
│   ├── runbook.md         — Troubleshooting: Mycelium, sockets, WASM, registry (224 lines)
│   └── secrets.md         — Env vars, tokens, Docker login (123 lines)
├── profile.md             — Profile TOML format (kept)
├── service.md             — Service TOML format (kept)
└── TOML_FORMAT_REFERENCE.md — Complete TOML reference (kept)

Removed (superseded)

• architecture.md → dev/architecture.md
• ecosystem.md → dev/repos.md
• SESSION_STATUS.md → stale
• ops/deployment.md → ops/deploy.md

Total: 1,587 lines added, 844 removed. 12 docs covering dev and ops.

Signed-off-by: mik-tf

## Completed Created comprehensive docs/ structure in hero_services, modeled after [znzfreezone_deploy/docs/](https://forge.ourworld.tf/znzfreezone_code/znzfreezone_deploy/src/branch/development/docs). ### New structure ``` docs/ ├── README.md — Index + architecture overview ├── dev/ │ ├── architecture.md — Service topology, proxy, WASM, OSIS, build system (349 lines) │ ├── e2e_checklist.md — Upgraded: vision, test architecture, how-to-run + 97 items (327 lines) │ ├── release.md — Versioning, build targets, deploy, rollback (170 lines) │ ├── repos.md — Repo map, SSOT sources, service inventory (106 lines) │ └── testing.md — 7-layer pyramid, 253 tests, conventions (191 lines) ├── ops/ │ ├── deploy.md — Full deploy procedure, direct transfer, rollback (237 lines) │ ├── runbook.md — Troubleshooting: Mycelium, sockets, WASM, registry (224 lines) │ └── secrets.md — Env vars, tokens, Docker login (123 lines) ├── profile.md — Profile TOML format (kept) ├── service.md — Service TOML format (kept) └── TOML_FORMAT_REFERENCE.md — Complete TOML reference (kept) ``` ### Removed (superseded) - architecture.md → dev/architecture.md - ecosystem.md → dev/repos.md - SESSION_STATUS.md → stale - ops/deployment.md → ops/deploy.md Total: 1,587 lines added, 844 removed. 12 docs covering dev and ops. Signed-off-by: mik-tf

mik-tf closed this issue 2026-03-27 00:55:12 +00:00

mik-tf referenced this issue 2026-03-28 05:07:00 +00:00

Hero OS — Master Roadmap #38

Sign in to join this conversation.

No Branch/Tag specified

Branches Tags

development

main

No results found.

Labels

Clear labels

No items

No labels

Milestone

Clear milestone

No items

No milestone

Projects

Clear projects

No items

No project

Assignees

Clear assignees

No assignees

1 participant

Notifications

Subscribe

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

lhumina_code/home#99

No description provided.