lhumina_code/home
21
0
Fork 0
Code Issues 13 Pull requests Projects Releases Packages Wiki Activity Actions

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

New issue
Open
opened 2026-03-23 16:26:10 +00:00 by mik-tf · 1 comment
mik-tf commented 2026-03-23 16:26:10 +00:00
Owner
Copy link

Context

Consolidated documentation issue. Absorbs content from:

  • #42 (architecture docs)
  • #15 (cross-compilation & getting started)

docs_hero lives at lhumina_code/docs_hero and is served by hero_books. The AI agent uses search_hero_docs to query these docs, so updating them directly improves AI knowledge.

Scope

1. Service documentation

  • All Hero services and their purpose
  • hero_agent: chat, voice STT/TTS, MCP tools, OSIS storage (v0.7.2+)
  • hero_aibroker: model routing, OpenRouter fallback
  • hero_books: documentation search, Q&A, collections, read-aloud
  • hero_osis: domains, rootobjects, CRUD, RPC methods
  • MCP integration: discovery, registration, tool usage
  • OpenRPC: how specs are served and consumed

2. Architecture (from #42)

  • OSIS data flow: MCP client → hero_osis_ui → Unix socket → hero_osis_server → OTOML
  • OTOML format: O: prefix + TOML key-value pairs
  • Socket strategy: Unix domain sockets, per-context subdirectories
  • Domain structure: each OSIS domain with type_names and methods
  • OpenRPC → MCP → SDK → docs pipeline
  • HeroRpcServer / HeroUiServer pattern

3. Deployment & build pipeline (from #15)

  • Build pipeline: make dist → Docker build → push → deploy
  • Environment strategy: herodev vs demo (semver tagged)
  • Service configuration: zinit/hero_init service files, socket discovery
  • Smoke test suites and coverage

4. Getting started (from #15)

  • How to install Claude Code skills for Hero development
  • How to use the build container for local development
  • How to get a full hero_os container running locally
  • How to iterate: edit code → make dist → test → repeat
  • Prerequisites (Docker, Rust toolchain, forge access)
  • Environment setup (~/hero/cfg/env/env.sh, tokens)
  • Branching model and workflow

5. Cross-compilation (from #15)

  • ARM/Intel cross-compilation support
  • Multi-arch container images

6. Voice & AI

  • Voice pipeline: earshot VAD, kokoro TTS, Whisper STT
  • TTS routing: Kokoro → Groq → aibroker (3-tier)
  • Conversation mode, read aloud

Notes

  • Dependencies #78 and #80 are now complete
  • Can be done incrementally — start with architecture + services since those change most
## Context Consolidated documentation issue. Absorbs content from: - https://forge.ourworld.tf/lhumina_code/home/issues/42 (architecture docs) - https://forge.ourworld.tf/lhumina_code/home/issues/15 (cross-compilation & getting started) docs_hero lives at lhumina_code/docs_hero and is served by hero_books. The AI agent uses search_hero_docs to query these docs, so updating them directly improves AI knowledge. ## Scope ### 1. Service documentation - [ ] All Hero services and their purpose - [ ] hero_agent: chat, voice STT/TTS, MCP tools, OSIS storage (v0.7.2+) - [ ] hero_aibroker: model routing, OpenRouter fallback - [ ] hero_books: documentation search, Q&A, collections, read-aloud - [ ] hero_osis: domains, rootobjects, CRUD, RPC methods - [ ] MCP integration: discovery, registration, tool usage - [ ] OpenRPC: how specs are served and consumed ### 2. Architecture (from #42) - [ ] OSIS data flow: MCP client → hero_osis_ui → Unix socket → hero_osis_server → OTOML - [ ] OTOML format: `O:` prefix + TOML key-value pairs - [ ] Socket strategy: Unix domain sockets, per-context subdirectories - [ ] Domain structure: each OSIS domain with type_names and methods - [ ] OpenRPC → MCP → SDK → docs pipeline - [ ] HeroRpcServer / HeroUiServer pattern ### 3. Deployment & build pipeline (from #15) - [ ] Build pipeline: `make dist` → Docker build → push → deploy - [ ] Environment strategy: herodev vs demo (semver tagged) - [ ] Service configuration: zinit/hero_init service files, socket discovery - [ ] Smoke test suites and coverage ### 4. Getting started (from #15) - [ ] How to install Claude Code skills for Hero development - [ ] How to use the build container for local development - [ ] How to get a full hero_os container running locally - [ ] How to iterate: edit code → `make dist` → test → repeat - [ ] Prerequisites (Docker, Rust toolchain, forge access) - [ ] Environment setup (`~/hero/cfg/env/env.sh`, tokens) - [ ] Branching model and workflow ### 5. Cross-compilation (from #15) - [ ] ARM/Intel cross-compilation support - [ ] Multi-arch container images ### 6. Voice & AI - [ ] Voice pipeline: earshot VAD, kokoro TTS, Whisper STT - [ ] TTS routing: Kokoro → Groq → aibroker (3-tier) - [ ] Conversation mode, read aloud ## Notes - Dependencies #78 and #80 are now complete - Can be done incrementally — start with architecture + services since those change most
mik-tf changed title from Update docs_hero with complete Hero ecosystem features to Comprehensive Hero ecosystem docs update (consolidates #42, #15) 2026-03-26 00:21:00 +00:00
mik-tf commented 2026-03-26 00:49:34 +00:00
Author
Owner
Copy link

Additional scope: MCP/Python/uv pipeline docs

Need to document how the AI agent tool chain works end-to-end:

  • MCP tool discovery: register_service discovers Hero services via Unix sockets, ingests OpenRPC specs
  • Python client generation: auto-generates Python client + lightweight interface file per service
  • Code generation: AI generates Python from interface + user intent
  • uv execution: execute_code runs Python in managed uv environment with client libs available
  • search_hero_docs: agent searches hero_books content for Hero OS knowledge
  • OSIS storage (v0.7.2+): all conversations, messages, memories, audit, usage stored in OSIS

This is the core value prop of the AI Assistant — it can discover services, understand their APIs, write code, and execute it. Needs clear documentation.

Signed-off-by: mik-tf

## Additional scope: MCP/Python/uv pipeline docs Need to document how the AI agent tool chain works end-to-end: - **MCP tool discovery**: register_service discovers Hero services via Unix sockets, ingests OpenRPC specs - **Python client generation**: auto-generates Python client + lightweight interface file per service - **Code generation**: AI generates Python from interface + user intent - **uv execution**: execute_code runs Python in managed uv environment with client libs available - **search_hero_docs**: agent searches hero_books content for Hero OS knowledge - **OSIS storage** (v0.7.2+): all conversations, messages, memories, audit, usage stored in OSIS This is the core value prop of the AI Assistant — it can discover services, understand their APIs, write code, and execute it. Needs clear documentation. Signed-off-by: mik-tf
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
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#81
No description provided.