[nu-demo] Documentation index: heronu deployment flow, AI grounding chain, per-service gaps #23

New issue

Open

opened 2026-04-28 12:20:36 +00:00 by mik-tf · 0 comments

mik-tf commented

2026-04-28 12:20:36 +00:00

Owner

Why this issue

During the heronu nu-shell demo deploy (single TF Grid VM, no Docker), we re-learned the whole Hero stack the hard way — by trial, error, and tailing logs. Most of the friction was missing documentation rather than broken code; the architecture is clean, but devs and ops have no single reference for:

the physical topology of a running Hero box (which binary binds which socket, who supervises what);
the AI grounding chain (agent → aibroker → tool_router → search_hero_docs → books → embedder → docs_hero);
which env vars each service expects and why;
the WASM release + compression path.

This issue is the map that points to every individual gap already filed, plus the canonical flow for each subsystem. Use it as the starting point; each row links to its own fix.

1. Deployment topology (nu-shell, single VM)

┌─ TF Grid gateway (heronu.gent01.grid.tf, HTTPS/TLS) ─────────────────┐
│                                                                       │
│   ↓ HTTPS :443 → VM mycelium IP :9988                                 │
│                                                                       │
│   hero_router (TCP 9988, bound to VM internal IP 10.1.2.2)            │
│       ├── /hero_osis/*        → ~/hero/var/sockets/hero_osis/*.sock   │
│       ├── /hero_aibroker/*    → ~/hero/var/sockets/hero_aibroker/*    │
│       ├── /hero_books/*       → ~/hero/var/sockets/hero_books/*       │
│       ├── /hero_agent/*       → ~/hero/var/sockets/hero_agent/*       │
│       ├── /hero_embedder/*    → ~/hero/var/sockets/hero_embedder/*    │
│       └── ... 22 services total                                       │
│                                                                       │
│   hero_proc (PID-1-style supervisor, under GNU screen)                │
│       - Owns all `<service>_server`, `<service>_ui` actions           │
│       - `hero_proc action get <name>` / `hero_proc action set <file>` │
│       - `hero_proc restart <service>`                                 │
│                                                                       │
│   Storage:  /data (btrfs, 100 GB)  ←─ symlink /home/driver            │
│   Sockets:  ~/hero/var/sockets/<svc>/{rpc,ui,rest}.sock               │
│   Data:     ~/hero/var/<svc>/ (each service's persistent state)       │
│   Code:     ~/hero/code0/<repo>/ (checked out sources, patchable)     │
│   Bins:     ~/hero/bin/ (installed by service_<name>.nu)              │
└───────────────────────────────────────────────────────────────────────┘

Key points most newcomers miss:

hero_router is the only TCP ingress. Everything else speaks over Unix domain sockets. If a service talks to another, it goes through the router (http://10.1.2.2:9988/hero_<svc>/<path>). There is no hero_proxy on port 6666 in nu-shell mode — that was a hero_zero (Docker) thing.
Three sockets per service by convention. rpc.sock = JSON-RPC 2.0, ui.sock = HTML dashboard + /api/*, rest.sock = REST (where applicable, e.g. hero_aibroker speaks OpenAI-compatible REST). The router-to-socket mapping is in hero_router's scanner (hero_router/src/scanner.rs) and follows the hero_sockets convention. See https://forge.ourworld.tf/lhumina_code/hero_router/src/branch/development/CLAUDE.md.
Multi-tenancy via header. Every inter-service call carries X-Hero-Context: <number> (or name). hero_router was previously overwriting it with state.context — fix in lhumina_code/home#125.

2. AI grounding chain — the whole flow

This is the path that makes "What is Hero OS?" come back with real docs_hero content instead of a hallucination:

┌────────────────────────────────────────────────────────────────────┐
│ Browser → /hero_agent/rpc → agent.chat { message, model }          │
│                                                                    │
│   hero_agent_server   (env: AIBROKER_API_ENDPOINT, *_MODELS, ...)  │
│     │                                                              │
│     ├─ llm_client (Claude via aibroker, NOT OpenRouter direct)     │
│     │     HTTP → http://10.1.2.2:9988/hero_aibroker/rest/v1/       │
│     │            chat/completions  (OpenAI-compatible)             │
│     │                                                              │
│     │   hero_aibroker_server picks provider from modelsconfig.yml  │
│     │   → anthropic / openai / groq / openrouter                   │
│     │                                                              │
│     └─ tool_router (58 built-in tools)                             │
│          tools offered to LLM = always_include + matched groups    │
│          `search_hero_docs` MUST be in always_include              │
│                                                                    │
│   LLM decides: call search_hero_docs({query, top_k})               │
│                                                                    │
│   tool exec → hero_books_server.search.query                       │
│     │                                                              │
│     ├─ embedder.embed(query, Q1 fast)   [hero_embedder_server]     │
│     │     └─ hero_embedderd (TCP 127.0.0.1:8092)                   │
│     │          └─ ONNX BGE-small (/usr/local/onnxruntime/)         │
│     │                                                              │
│     ├─ cosine search in namespace="hero" (redb index)              │
│     │                                                              │
│     └─ embedder.rerank(query, candidates, Q1)                      │
│                                                                    │
│   tool result (top-k Q&A snippets from docs_hero) → LLM            │
│                                                                    │
│   LLM composes grounded answer → JSON-RPC response → browser       │
└────────────────────────────────────────────────────────────────────┘

Env vars the hero_agent_server action MUST set

Var	Value	Why
`AIBROKER_API_ENDPOINT`	`http://10.1.2.2:9988/hero_aibroker/rest/v1`	Route LLM through aibroker (Claude available) instead of OpenRouter direct (Gemini Flash — ignores tool-use hints). This is the hero_zero precedent — copied from `hero_zero/services/hero_agent.toml`.
`HERO_AGENT_AIBROKER_MODELS`	`claude-haiku-4.5,claude-3-5-sonnet-latest,gpt-4o-mini`	Model list aibroker actually has configured.
`OSIS_URL`	`http://10.1.2.2:9988/hero_osis/ui`	Used by agent's hero_osis tool to read/write per-context data.
`OSIS_CONTEXT`	`default`	Default context name if X-Hero-Context not in header.
`OPENROUTER_API_KEY(S)`	`sk-or-v1-...`	Fallback provider. hero_agent reads plural, hero_zero uses singular — set both. See lhumina_code/home#136.

These are missing from current service_agent.nu (lhumina_code/home#135 — module doesn't even exist yet). Applied manually on heronu via hero_proc action set /home/driver/tmp_action.json.

Gaps already filed on this chain

lhumina_code/home#125 — hero_router was clobbering client X-Hero-Context header
lhumina_code/home#135 — service_agent.nu missing entirely (hero_agent not installable via service_install_all)
lhumina_code/home#136 — hero_agent reads OPENROUTER_API_KEYS (plural) with no fallback to singular
lhumina_code/home#137 + lhumina_code/home#138 — hero_aibroker Groq-only config + --reset clobbers edits
lhumina_code/home#140 — (separate, compression — see §4 below)
lhumina_code/home#145 — hero_embedder_server panics with blocking reqwest inside tokio async context; namespace.create rejects Q1 in daemon mode
(follow-up, not yet filed): tool_router.rs needs search_hero_docs in default always_include; prompt.rs needs MANDATORY directive for hero_* questions or tool_choice=required plumbed through.

3. libraries.txt → hero_books flow

hero_books indexes external markdown doc repos into the embedder on startup. Config at $BOOKS_DIR/libraries.txt (one name URL per line):

hero        https://forge.ourworld.tf/lhumina_code/docs_hero
mycelium    https://forge.ourworld.tf/mycelium/docs_mycelium
ourworld    https://forge.ourworld.tf/ourworld/docs_owh
geomind     https://forge.ourworld.tf/geomind/docs_geomind

On startup: hero_books_server reads that file → git clone or git pull each repo → indexes all .md into embedder namespace=<name> → serves via search.query. FORGEJO_TOKEN must be in env for private repos (only hero worked on heronu — the other three returned 404/auth; see open gap).

4. WASM compression (lhumina_code/home#140 — completed on heronu)

Before: hero_os WASM shell = 211 MB debug build, ServeDir with runtime CompressionLayer. First page load ≥60 s on any real network.

After (merged in development_mik_nu_demo on the VM, commits 71abce9 + e997afc):

hero_os Makefile now honors CARGO_TARGET_DIR / CARGO_BUILD_JOBS in both install-assets-release and install / installdev targets.
New dist-release-compressed target: builds WASM in release mode (wasm-opt -Oz), then generates *.wasm.br (brotli -q 11) and *.wasm.gz (gzip -9) sidecars alongside the raw WASM.
hero_os_ui/src/main.rs: all four ServeDir + two ServeFile now call .precompressed_br().precompressed_gzip() — tower-http serves the sidecar automatically based on Accept-Encoding. CompressionLayer removed (was doing work at request time; sidecars pre-compute it once).

Verified over public gateway:

Encoding	Bytes	Ratio
identity	9,345,153 (9.3 MB release)	1×
gzip -9	2,833,400 (2.8 MB)	3.3×
brotli -q 11	1,802,642 (1.8 MB)	5.2×

Combined reduction vs. old debug path: 211 MB → 1.8 MB = ~117×. Well inside the ≤8 MB budget for first paint.

5. The gap catalog (lhumina_code/home#122 – 147)

Every fix-in-place on heronu was paired with a [nu-demo] issue so reviewers can opt in later. Full list:

#	Subsystem	Title (summary)
122	hero_slides	hardcoded `/Volumes/T7` macOS path in dashboard.js
123	hero_os_app	island-room + others missing from `web` feature (WASM 404)
124	UX	every island needs polished empty/error state
125	hero_router	clobbers client X-Hero-Context header
126	hero_livekit_ui	Axum Extension added inside whitelist middleware (wrong order)
127	hero_slides	path dep on hero_lib but no service_lib clones it
128	hero_skills	installers.nu missing libseccomp/libcap-ng/protobuf-compiler/...
129	service_osis.nu	does not populate contexts registry or pass HERO_CONTEXTS/HERO_SEED_DIR
130	hero_osis_ai	domain not registered in per-domain server list
131	hero_os Makefile	ignored CARGO_TARGET_DIR, hardcoded `~/.cargo/bin/dx`
132	service_codescalers	socket naming mismatch: `_server` vs plain
133	service_livekit	no redis preflight — install fails on fresh VM
134	packages.nu	service_browser/office/books/matrixchat/voice commented out
135	service_agent.nu	missing entirely — hero_agent not installable
136	hero_agent	reads `OPENROUTER_API_KEYS` plural with no singular fallback
137	hero_aibroker	modelsconfig.yml ships Groq-only with no fallback chain
138	hero_aibroker	`--reset` reseeds modelsconfig.yml and clobbers operator edits
139	hero_foundry	not pointed at seed_media — Files/Videos/Photos/Songs don't stream
140	hero_os	WASM was 211 MB debug — needs release + wasm-opt + brotli/gzip (fixed)
141	service_books.nu	nu parse error on literal parens inside string interpolation
142	hero_skills	tools/install.sh silently fails to install nushell
143	hero_osis SDK	CRUD delete returns bool from server, SDK expects String
144	Office (roadmap)	seed Office archipelago with per-library generated PDFs/docs
145	hero_embedder	blocking reqwest inside tokio async panics; Q1 rejected in daemon mode
146	Photos	`<img>` tags don't render despite webdav serving valid JPEGs
147	hero_collab	island uses its own dark theme, doesn't follow hero_os tokens

6. Where this belongs once merged

docs_hero/collections/hero_os_guide/architecture.md — currently lists hero_services, zinit, hero_shrimp. Needs rewrite: hero_zero, hero_proc, hero_agent, hero_router added to repo table; 4-crate OServer pattern documented; nu-shell deploy path alongside Docker.
docs_hero/collections/hero_os_guide/services.md — "AI Assistant (Shrimp)" should become "AI Assistant (hero_agent)"; add hero_router, hero_proc, hero_logic, hero_db, hero_livekit, hero_collab, hero_slides, hero_whiteboard, hero_browser, hero_office, hero_codescalers, hero_books, hero_matrixchat. Supervisor is hero_proc, not zinit.
docs_hero/collections/hero_os_guide/quickstart.md — add "Option B: direct nu-shell install on Linux VM" alongside the existing Docker path, pointing at hero_skills install-all && hero_proc start ....
hero_zero/README.md or new hero_proc/OPS.md — the physical topology diagram and env-var table from §1 and §2.

All edits staged on development_mik_nu_demo branch — reviewers can opt in when ready.

7. Quick reference card for the next dev who lands on a fresh heronu-style VM

source ~/hero/cfg/env/env.sh                          # API keys & FORGEJO_TOKEN
export PATH=$HOME/hero/bin:$PATH
hero_proc list                                        # What's running?
hero_proc action get hero_agent_server --format yaml  # What env does it have?
hero_proc restart hero_agent                          # After you patch env

# Direct socket probe (bypass router):
curl --unix-socket ~/hero/var/sockets/hero_agent/rpc.sock \
     -X POST http://localhost/rpc \
     -H 'Content-Type: application/json' \
     -H 'X-Hero-Context: default' \
     -d '{"jsonrpc":"2.0","id":1,"method":"agent.chat","params":{"message":"...","model":"claude-haiku-4.5"}}'

# Router-path probe (as a browser would):
curl http://10.1.2.2:9988/hero_aibroker/rest/v1/models

# Tail logs for a specific action:
ls ~/hero/var/log/                                    # per-action log files

Signed-off-by: mik-tf

Originally filed as home#148 on 2026-04-24 by mik-tf — moved to hero_demo as part of consolidating issue tracking.

## Why this issue During the heronu nu-shell demo deploy (single TF Grid VM, no Docker), we re-learned the whole Hero stack the hard way — by trial, error, and tailing logs. Most of the friction was **missing documentation** rather than broken code; the architecture is clean, but devs and ops have no single reference for: - the physical topology of a running Hero box (which binary binds which socket, who supervises what); - the AI grounding chain (agent → aibroker → tool_router → search_hero_docs → books → embedder → docs_hero); - which env vars each service expects and why; - the WASM release + compression path. This issue is the **map** that points to every individual gap already filed, plus the canonical flow for each subsystem. Use it as the starting point; each row links to its own fix. --- ## 1. Deployment topology (nu-shell, single VM) ``` ┌─ TF Grid gateway (heronu.gent01.grid.tf, HTTPS/TLS) ─────────────────┐ │ │ │ ↓ HTTPS :443 → VM mycelium IP :9988 │ │ │ │ hero_router (TCP 9988, bound to VM internal IP 10.1.2.2) │ │ ├── /hero_osis/* → ~/hero/var/sockets/hero_osis/*.sock │ │ ├── /hero_aibroker/* → ~/hero/var/sockets/hero_aibroker/* │ │ ├── /hero_books/* → ~/hero/var/sockets/hero_books/* │ │ ├── /hero_agent/* → ~/hero/var/sockets/hero_agent/* │ │ ├── /hero_embedder/* → ~/hero/var/sockets/hero_embedder/* │ │ └── ... 22 services total │ │ │ │ hero_proc (PID-1-style supervisor, under GNU screen) │ │ - Owns all `<service>_server`, `<service>_ui` actions │ │ - `hero_proc action get <name>` / `hero_proc action set <file>` │ │ - `hero_proc restart <service>` │ │ │ │ Storage: /data (btrfs, 100 GB) ←─ symlink /home/driver │ │ Sockets: ~/hero/var/sockets/<svc>/{rpc,ui,rest}.sock │ │ Data: ~/hero/var/<svc>/ (each service's persistent state) │ │ Code: ~/hero/code0/<repo>/ (checked out sources, patchable) │ │ Bins: ~/hero/bin/ (installed by service_<name>.nu) │ └───────────────────────────────────────────────────────────────────────┘ ``` Key points most newcomers miss: - **hero_router is the only TCP ingress.** Everything else speaks over Unix domain sockets. If a service talks to another, it goes through the router (`http://10.1.2.2:9988/hero_<svc>/<path>`). There is no hero_proxy on port 6666 in nu-shell mode — that was a hero_zero (Docker) thing. - **Three sockets per service by convention.** `rpc.sock` = JSON-RPC 2.0, `ui.sock` = HTML dashboard + /api/*, `rest.sock` = REST (where applicable, e.g. hero_aibroker speaks OpenAI-compatible REST). The router-to-socket mapping is in hero_router's scanner (`hero_router/src/scanner.rs`) and follows the `hero_sockets` convention. See https://forge.ourworld.tf/lhumina_code/hero_router/src/branch/development/CLAUDE.md. - **Multi-tenancy via header.** Every inter-service call carries `X-Hero-Context: <number>` (or name). hero_router was previously overwriting it with `state.context` — fix in https://forge.ourworld.tf/lhumina_code/home/issues/125. --- ## 2. AI grounding chain — the whole flow This is the path that makes "What is Hero OS?" come back with _real_ docs_hero content instead of a hallucination: ``` ┌────────────────────────────────────────────────────────────────────┐ │ Browser → /hero_agent/rpc → agent.chat { message, model } │ │ │ │ hero_agent_server (env: AIBROKER_API_ENDPOINT, *_MODELS, ...) │ │ │ │ │ ├─ llm_client (Claude via aibroker, NOT OpenRouter direct) │ │ │ HTTP → http://10.1.2.2:9988/hero_aibroker/rest/v1/ │ │ │ chat/completions (OpenAI-compatible) │ │ │ │ │ │ hero_aibroker_server picks provider from modelsconfig.yml │ │ │ → anthropic / openai / groq / openrouter │ │ │ │ │ └─ tool_router (58 built-in tools) │ │ tools offered to LLM = always_include + matched groups │ │ `search_hero_docs` MUST be in always_include │ │ │ │ LLM decides: call search_hero_docs({query, top_k}) │ │ │ │ tool exec → hero_books_server.search.query │ │ │ │ │ ├─ embedder.embed(query, Q1 fast) [hero_embedder_server] │ │ │ └─ hero_embedderd (TCP 127.0.0.1:8092) │ │ │ └─ ONNX BGE-small (/usr/local/onnxruntime/) │ │ │ │ │ ├─ cosine search in namespace="hero" (redb index) │ │ │ │ │ └─ embedder.rerank(query, candidates, Q1) │ │ │ │ tool result (top-k Q&A snippets from docs_hero) → LLM │ │ │ │ LLM composes grounded answer → JSON-RPC response → browser │ └────────────────────────────────────────────────────────────────────┘ ``` ### Env vars the hero_agent_server action MUST set | Var | Value | Why | |---|---|---| | `AIBROKER_API_ENDPOINT` | `http://10.1.2.2:9988/hero_aibroker/rest/v1` | Route LLM through aibroker (Claude available) instead of OpenRouter direct (Gemini Flash — ignores tool-use hints). This is the **hero_zero precedent** — copied from `hero_zero/services/hero_agent.toml`. | | `HERO_AGENT_AIBROKER_MODELS` | `claude-haiku-4.5,claude-3-5-sonnet-latest,gpt-4o-mini` | Model list aibroker actually has configured. | | `OSIS_URL` | `http://10.1.2.2:9988/hero_osis/ui` | Used by agent's hero_osis tool to read/write per-context data. | | `OSIS_CONTEXT` | `default` | Default context name if X-Hero-Context not in header. | | `OPENROUTER_API_KEY(S)` | `sk-or-v1-...` | Fallback provider. hero_agent reads plural, hero_zero uses singular — set both. See https://forge.ourworld.tf/lhumina_code/home/issues/136. | These are missing from current `service_agent.nu` (https://forge.ourworld.tf/lhumina_code/home/issues/135 — module doesn't even exist yet). Applied manually on heronu via `hero_proc action set /home/driver/tmp_action.json`. ### Gaps already filed on this chain - https://forge.ourworld.tf/lhumina_code/home/issues/125 — hero_router was clobbering client X-Hero-Context header - https://forge.ourworld.tf/lhumina_code/home/issues/135 — `service_agent.nu` missing entirely (hero_agent not installable via service_install_all) - https://forge.ourworld.tf/lhumina_code/home/issues/136 — hero_agent reads `OPENROUTER_API_KEYS` (plural) with no fallback to singular - https://forge.ourworld.tf/lhumina_code/home/issues/137 + https://forge.ourworld.tf/lhumina_code/home/issues/138 — hero_aibroker Groq-only config + `--reset` clobbers edits - https://forge.ourworld.tf/lhumina_code/home/issues/140 — (separate, compression — see §4 below) - https://forge.ourworld.tf/lhumina_code/home/issues/145 — hero_embedder_server panics with blocking reqwest inside tokio async context; namespace.create rejects Q1 in daemon mode - _(follow-up, not yet filed)_: `tool_router.rs` needs `search_hero_docs` in default `always_include`; prompt.rs needs MANDATORY directive for hero_* questions or `tool_choice=required` plumbed through. --- ## 3. libraries.txt → hero_books flow hero_books indexes external markdown doc repos into the embedder on startup. Config at `$BOOKS_DIR/libraries.txt` (one `name URL` per line): ``` hero https://forge.ourworld.tf/lhumina_code/docs_hero mycelium https://forge.ourworld.tf/mycelium/docs_mycelium ourworld https://forge.ourworld.tf/ourworld/docs_owh geomind https://forge.ourworld.tf/geomind/docs_geomind ``` On startup: hero_books_server reads that file → `git clone` or `git pull` each repo → indexes all .md into embedder namespace=`<name>` → serves via `search.query`. FORGEJO_TOKEN must be in env for private repos (only `hero` worked on heronu — the other three returned 404/auth; see open gap). --- ## 4. WASM compression (https://forge.ourworld.tf/lhumina_code/home/issues/140 — completed on heronu) **Before:** hero_os WASM shell = 211 MB debug build, ServeDir with runtime CompressionLayer. First page load ≥60 s on any real network. **After (merged in `development_mik_nu_demo` on the VM, commits `71abce9` + `e997afc`):** - hero_os Makefile now honors `CARGO_TARGET_DIR` / `CARGO_BUILD_JOBS` in both `install-assets-release` and `install` / `installdev` targets. - New `dist-release-compressed` target: builds WASM in release mode (`wasm-opt -Oz`), then generates `*.wasm.br` (brotli -q 11) and `*.wasm.gz` (gzip -9) sidecars alongside the raw WASM. - `hero_os_ui/src/main.rs`: all four `ServeDir` + two `ServeFile` now call `.precompressed_br().precompressed_gzip()` — tower-http serves the sidecar automatically based on `Accept-Encoding`. `CompressionLayer` removed (was doing work at request time; sidecars pre-compute it once). **Verified over public gateway:** | Encoding | Bytes | Ratio | |---|---|---| | identity | 9,345,153 (9.3 MB release) | 1× | | gzip -9 | 2,833,400 (2.8 MB) | 3.3× | | **brotli -q 11** | **1,802,642 (1.8 MB)** | **5.2×** | Combined reduction vs. old debug path: **211 MB → 1.8 MB = ~117×**. Well inside the ≤8 MB budget for first paint. --- ## 5. The gap catalog (https://forge.ourworld.tf/lhumina_code/home/issues/122 – 147) Every fix-in-place on heronu was paired with a `[nu-demo]` issue so reviewers can opt in later. Full list: | # | Subsystem | Title (summary) | |---|---|---| | 122 | hero_slides | hardcoded `/Volumes/T7` macOS path in dashboard.js | | 123 | hero_os_app | island-room + others missing from `web` feature (WASM 404) | | 124 | UX | every island needs polished empty/error state | | 125 | hero_router | clobbers client X-Hero-Context header | | 126 | hero_livekit_ui | Axum Extension added inside whitelist middleware (wrong order) | | 127 | hero_slides | path dep on hero_lib but no service_lib clones it | | 128 | hero_skills | installers.nu missing libseccomp/libcap-ng/protobuf-compiler/... | | 129 | service_osis.nu | does not populate contexts registry or pass HERO_CONTEXTS/HERO_SEED_DIR | | 130 | hero_osis_ai | domain not registered in per-domain server list | | 131 | hero_os Makefile | ignored CARGO_TARGET_DIR, hardcoded `~/.cargo/bin/dx` | | 132 | service_codescalers | socket naming mismatch: `_server` vs plain | | 133 | service_livekit | no redis preflight — install fails on fresh VM | | 134 | packages.nu | service_browser/office/books/matrixchat/voice commented out | | 135 | service_agent.nu | missing entirely — hero_agent not installable | | 136 | hero_agent | reads `OPENROUTER_API_KEYS` plural with no singular fallback | | 137 | hero_aibroker | modelsconfig.yml ships Groq-only with no fallback chain | | 138 | hero_aibroker | `--reset` reseeds modelsconfig.yml and clobbers operator edits | | 139 | hero_foundry | not pointed at seed_media — Files/Videos/Photos/Songs don't stream | | 140 | hero_os | **WASM was 211 MB debug — needs release + wasm-opt + brotli/gzip (fixed)** | | 141 | service_books.nu | nu parse error on literal parens inside string interpolation | | 142 | hero_skills | tools/install.sh silently fails to install nushell | | 143 | hero_osis SDK | CRUD delete returns bool from server, SDK expects String | | 144 | Office (roadmap) | seed Office archipelago with per-library generated PDFs/docs | | 145 | hero_embedder | blocking reqwest inside tokio async panics; Q1 rejected in daemon mode | | 146 | Photos | `<img>` tags don't render despite webdav serving valid JPEGs | | 147 | hero_collab | island uses its own dark theme, doesn't follow hero_os tokens | --- ## 6. Where this belongs once merged - **`docs_hero/collections/hero_os_guide/architecture.md`** — currently lists `hero_services`, `zinit`, `hero_shrimp`. Needs rewrite: `hero_zero`, `hero_proc`, `hero_agent`, `hero_router` added to repo table; 4-crate OServer pattern documented; nu-shell deploy path alongside Docker. - **`docs_hero/collections/hero_os_guide/services.md`** — "AI Assistant (Shrimp)" should become "AI Assistant (hero_agent)"; add hero_router, hero_proc, hero_logic, hero_db, hero_livekit, hero_collab, hero_slides, hero_whiteboard, hero_browser, hero_office, hero_codescalers, hero_books, hero_matrixchat. Supervisor is hero_proc, not zinit. - **`docs_hero/collections/hero_os_guide/quickstart.md`** — add "Option B: direct nu-shell install on Linux VM" alongside the existing Docker path, pointing at `hero_skills install-all && hero_proc start ...`. - **`hero_zero/README.md` or new `hero_proc/OPS.md`** — the physical topology diagram and env-var table from §1 and §2. All edits staged on `development_mik_nu_demo` branch — reviewers can opt in when ready. --- ## 7. Quick reference card for the next dev who lands on a fresh heronu-style VM ```bash source ~/hero/cfg/env/env.sh # API keys & FORGEJO_TOKEN export PATH=$HOME/hero/bin:$PATH hero_proc list # What's running? hero_proc action get hero_agent_server --format yaml # What env does it have? hero_proc restart hero_agent # After you patch env # Direct socket probe (bypass router): curl --unix-socket ~/hero/var/sockets/hero_agent/rpc.sock \ -X POST http://localhost/rpc \ -H 'Content-Type: application/json' \ -H 'X-Hero-Context: default' \ -d '{"jsonrpc":"2.0","id":1,"method":"agent.chat","params":{"message":"...","model":"claude-haiku-4.5"}}' # Router-path probe (as a browser would): curl http://10.1.2.2:9988/hero_aibroker/rest/v1/models # Tail logs for a specific action: ls ~/hero/var/log/ # per-action log files ``` Signed-off-by: mik-tf --- *Originally filed as [home#148](https://forge.ourworld.tf/lhumina_code/home/issues/148) on 2026-04-24 by mik-tf — moved to hero_demo as part of consolidating issue tracking.*