lhumina_code/docs_hero
0
0
Fork 0
Code Issues 1 Pull requests Projects Releases Packages Wiki Activity Actions

[content] Comprehensive docs_hero coverage — make the AI Assistant measurably smarter #1

New issue
Open
opened 2026-05-01 02:05:21 +00:00 by mik-tf · 0 comments
mik-tf commented 2026-05-01 02:05:21 +00:00
Owner
Copy link

Premise

Every screenshot of the AI Assistant on herodemo proves the same thing: the AI is only as smart as the docs it grounds on.

  • "What is Hero OS?" → returns a clean, multi-section answer because docs_hero has good content for that question.
  • "Who are my contacts in hero_biz?" → eventually returns the answer, but only after 30 lines of trial-and-error, because docs_hero doesn't tell the agent how to query biz cleanly.
  • "What can Hero OS do?" → the agent has to extrapolate because docs_hero doesn't enumerate capabilities concretely.

Investing in docs_hero is the single highest-ROI activity for AI Assistant quality. A few hours of structured writing makes the agent measurably smarter without changing a line of agent code. The agent reads the docs the moment they're embedded.

What docs_hero needs to be

Two audiences, same content:

  1. Humans discovering what Hero OS can do.
  2. The AI Assistant grounding on docs to answer user questions.

For (2) to work well, every page needs:

  • Concrete examples of prompts that should hit this content.
  • Per-context behaviour explained (what changes when the user is in Geomind vs ThreeFold).
  • The MCP tool names involved (so the agent can match a description to a tool to call).
  • Common task patterns (how does a user normally do X with this service).

Pages to write — phase 1 (capability coverage)

The agent should be able to answer any question in this list by grounding on docs_hero alone.

services/biz.md

  • What hero_biz is (CRM: Persons, Companies, Contacts, Deals, Opportunities, Instruments, Contracts, Transactions).
  • Per-context: each context has its own contacts. The active context filters everything.
  • MCP tools: biz.list_contacts, biz.add_contact, etc. (from filed hero_agent issue).
  • Example prompts:
    • "Who are my contacts?" → biz.list_contacts(active_context)
    • "Add Alice from Acme as a contact" → biz.add_contact(name='Alice', company='Acme')
    • "What's my deal pipeline?" → biz.list_deals(stage_aggregate=true)
  • Common tasks: adding a person, linking to a company, creating a deal, marking won/lost.

services/calendar.md

  • What hero_osis_calendar is (events, attendees, registrations).
  • Per-context behaviour.
  • MCP tools.
  • Example prompts:
    • "What's on my calendar today?" / "tomorrow?" / "this week?"
    • "Schedule a meeting with Alice on Tuesday at 2pm"
    • "Show me free slots tomorrow afternoon"

services/photos.md and services/videos.md

  • What they are (per-context media library backed by hero_foundry webdav).
  • Storage path layout (webdav/<context>/Photos/).
  • MCP tools.
  • Example prompts:
    • "Show me recent photos"
    • "Play that conference talk video"

services/books.md

  • What hero_books is (libraries.txt → cloned + embedded → searchable + AI-summarised).
  • "Ask the Librarian" feature with AI summary.
  • Library auto-discovery from libraries.txt.
  • Example prompts:
    • "Summarise the OurWorld library"
    • "What does the Hero documentation say about contexts?"

services/foundry.md

  • What hero_foundry is (per-context webdav file storage + Git over HTTP).
  • File API endpoints.
  • Path conventions.

services/agent.md

  • What hero_agent is (the AI Assistant itself).
  • Wake word, conversation mode, top-right widget (when shipped).
  • How tool calling works (via MCP discovery).
  • Per-context awareness — the agent always knows the user's active context.

concepts/contexts.md

  • The multi-tenancy model: each context = an isolated workspace.
  • How to switch contexts. What persists per context vs across contexts.
  • Why per-context routing matters for the AI's tool calls (the agent automatically scopes queries to active context).

concepts/intelligence.md

  • The stack: hero_agent → hero_aibroker (provider routing) → hero_embedder (semantic) → hero_indexer (triage) → MCP tools.
  • How the agent picks tools (semantic discovery, not enumeration).
  • How docs_hero embedding makes the agent smarter.

concepts/voice.md

  • TTS (Kokoro + Groq fallback) and STT (Whisper-style).
  • Wake word, conversation mode.
  • Top-right widget when shipped.
  • Customising voice and wake word.

getting-started/common-tasks.md

  • 10 common Hero OS prompts and what they do.
  • Each maps to expected agent behaviour and the tools involved.

getting-started/per-context-mental-model.md

  • "What context am I in? How does it change what I see?"
  • The default/geomind/threefold/incubaid distinction in the demo, generalised.

Pages to write — phase 2 (depth)

Once the capability coverage is in place, fill in:

  • Detailed per-tool reference (one page per major MCP tool).
  • Per-island user guides.
  • Customisation: wake word, voice, theme, model selection.
  • Operator docs for self-hosting Hero OS (deploy, env, secrets).
  • Troubleshooting: when the agent gets confused, what to check.

Writing principles

  • Write for the agent first, the human second. If a human can read it, the agent can ground on it. The reverse is not true (agents reward explicit structure that humans skim past).
  • Lead with the question, not the answer. Each page's first H2 should be a question a user would actually ask. The text below answers it. The agent's retrieval works on this.
  • Concrete prompts, not generic descriptions. "You can manage contacts with hero_biz" is weak. "Ask the AI Assistant: 'who are my contacts?' or 'add Alice Smith as a contact'" is strong.
  • Per-context everywhere. Every capability page mentions what changes per context, even if briefly. The agent needs to know to scope queries.
  • Cross-link MCP tools. Where a capability description references a tool, link to that tool's reference page (when it exists). Aids agent disambiguation.

Acceptance

  • Phase 1 pages all exist in docs_hero/ and are pushed to the development branch.
  • hero_books on herodemo picks up the new content (the libraries.txt flow already pulls docs_hero — verified).
  • hero_embedder re-embeds the new pages (automatic on next index cycle).
  • AI Assistant on herodemo, asked the example prompts in each page, answers cleanly grounded on the new content.
  • Specifically: "who are my contacts?" → answer comes from services/biz.md reference + the curated biz.list_contacts tool, not from brute-forcing socket paths.
  • Phase 2 depth pages prioritised based on actual user questions the agent fumbles on.

How to measure improvement

  • Pick 10 representative prompts (mix of read and write, across services).
  • Run them through the AI Assistant before phase 1 ships → record answer quality + scratchpad volume.
  • Run them again after phase 1 ships → compare.
  • Expect: noticeable drop in scratchpad text, faster answers, fewer "let me try X" lines.

Cross-references

  • Vision: lhumina_code/hero_demo#52
  • 24-hour demo plan: lhumina_code/hero_demo#53 (calls for phase 1 docs in Hour 0-4)
  • MCP tool discovery: filed alongside (hero_agent) — docs_hero pages reference tool names from there
  • Ambient AI widget: filed alongside (hero_agent) — concepts/voice.md documents this when shipped

Signed-off-by: mik-tf

## Premise Every screenshot of the AI Assistant on herodemo proves the same thing: **the AI is only as smart as the docs it grounds on.** - "What is Hero OS?" → returns a clean, multi-section answer because docs_hero has good content for that question. - "Who are my contacts in hero_biz?" → eventually returns the answer, but only after 30 lines of trial-and-error, because docs_hero doesn't tell the agent how to query biz cleanly. - "What can Hero OS do?" → the agent has to extrapolate because docs_hero doesn't enumerate capabilities concretely. Investing in docs_hero is the **single highest-ROI activity** for AI Assistant quality. A few hours of structured writing makes the agent measurably smarter without changing a line of agent code. The agent reads the docs the moment they're embedded. ## What docs_hero needs to be Two audiences, same content: 1. **Humans** discovering what Hero OS can do. 2. **The AI Assistant** grounding on docs to answer user questions. For (2) to work well, every page needs: - Concrete examples of prompts that should hit this content. - Per-context behaviour explained (what changes when the user is in Geomind vs ThreeFold). - The MCP tool names involved (so the agent can match a description to a tool to call). - Common task patterns (how does a user normally do X with this service). ## Pages to write — phase 1 (capability coverage) The agent should be able to answer any question in this list by grounding on docs_hero alone. ### `services/biz.md` - What hero_biz is (CRM: Persons, Companies, Contacts, Deals, Opportunities, Instruments, Contracts, Transactions). - Per-context: each context has its own contacts. The active context filters everything. - MCP tools: `biz.list_contacts`, `biz.add_contact`, etc. (from filed hero_agent issue). - Example prompts: - "Who are my contacts?" → `biz.list_contacts(active_context)` - "Add Alice from Acme as a contact" → `biz.add_contact(name='Alice', company='Acme')` - "What's my deal pipeline?" → `biz.list_deals(stage_aggregate=true)` - Common tasks: adding a person, linking to a company, creating a deal, marking won/lost. ### `services/calendar.md` - What hero_osis_calendar is (events, attendees, registrations). - Per-context behaviour. - MCP tools. - Example prompts: - "What's on my calendar today?" / "tomorrow?" / "this week?" - "Schedule a meeting with Alice on Tuesday at 2pm" - "Show me free slots tomorrow afternoon" ### `services/photos.md` and `services/videos.md` - What they are (per-context media library backed by hero_foundry webdav). - Storage path layout (`webdav/<context>/Photos/`). - MCP tools. - Example prompts: - "Show me recent photos" - "Play that conference talk video" ### `services/books.md` - What hero_books is (libraries.txt → cloned + embedded → searchable + AI-summarised). - "Ask the Librarian" feature with AI summary. - Library auto-discovery from `libraries.txt`. - Example prompts: - "Summarise the OurWorld library" - "What does the Hero documentation say about contexts?" ### `services/foundry.md` - What hero_foundry is (per-context webdav file storage + Git over HTTP). - File API endpoints. - Path conventions. ### `services/agent.md` - What hero_agent is (the AI Assistant itself). - Wake word, conversation mode, top-right widget (when shipped). - How tool calling works (via MCP discovery). - Per-context awareness — the agent always knows the user's active context. ### `concepts/contexts.md` - The multi-tenancy model: each context = an isolated workspace. - How to switch contexts. What persists per context vs across contexts. - Why per-context routing matters for the AI's tool calls (the agent automatically scopes queries to active context). ### `concepts/intelligence.md` - The stack: hero_agent → hero_aibroker (provider routing) → hero_embedder (semantic) → hero_indexer (triage) → MCP tools. - How the agent picks tools (semantic discovery, not enumeration). - How docs_hero embedding makes the agent smarter. ### `concepts/voice.md` - TTS (Kokoro + Groq fallback) and STT (Whisper-style). - Wake word, conversation mode. - Top-right widget when shipped. - Customising voice and wake word. ### `getting-started/common-tasks.md` - 10 common Hero OS prompts and what they do. - Each maps to expected agent behaviour and the tools involved. ### `getting-started/per-context-mental-model.md` - "What context am I in? How does it change what I see?" - The default/geomind/threefold/incubaid distinction in the demo, generalised. ## Pages to write — phase 2 (depth) Once the capability coverage is in place, fill in: - Detailed per-tool reference (one page per major MCP tool). - Per-island user guides. - Customisation: wake word, voice, theme, model selection. - Operator docs for self-hosting Hero OS (deploy, env, secrets). - Troubleshooting: when the agent gets confused, what to check. ## Writing principles - **Write for the agent first, the human second.** If a human can read it, the agent can ground on it. The reverse is not true (agents reward explicit structure that humans skim past). - **Lead with the question, not the answer.** Each page's first H2 should be a question a user would actually ask. The text below answers it. The agent's retrieval works on this. - **Concrete prompts, not generic descriptions.** "You can manage contacts with hero_biz" is weak. "Ask the AI Assistant: 'who are my contacts?' or 'add Alice Smith as a contact'" is strong. - **Per-context everywhere.** Every capability page mentions what changes per context, even if briefly. The agent needs to know to scope queries. - **Cross-link MCP tools.** Where a capability description references a tool, link to that tool's reference page (when it exists). Aids agent disambiguation. ## Acceptance - [ ] Phase 1 pages all exist in `docs_hero/` and are pushed to the development branch. - [ ] hero_books on herodemo picks up the new content (the `libraries.txt` flow already pulls docs_hero — verified). - [ ] hero_embedder re-embeds the new pages (automatic on next index cycle). - [ ] AI Assistant on herodemo, asked the example prompts in each page, answers cleanly grounded on the new content. - [ ] Specifically: "who are my contacts?" → answer comes from `services/biz.md` reference + the curated `biz.list_contacts` tool, not from brute-forcing socket paths. - [ ] Phase 2 depth pages prioritised based on actual user questions the agent fumbles on. ## How to measure improvement - Pick 10 representative prompts (mix of read and write, across services). - Run them through the AI Assistant before phase 1 ships → record answer quality + scratchpad volume. - Run them again after phase 1 ships → compare. - Expect: noticeable drop in scratchpad text, faster answers, fewer "let me try X" lines. ## Cross-references - Vision: https://forge.ourworld.tf/lhumina_code/hero_demo/issues/52 - 24-hour demo plan: https://forge.ourworld.tf/lhumina_code/hero_demo/issues/53 (calls for phase 1 docs in Hour 0-4) - MCP tool discovery: filed alongside (hero_agent) — docs_hero pages reference tool names from there - Ambient AI widget: filed alongside (hero_agent) — `concepts/voice.md` documents this when shipped Signed-off-by: mik-tf
mik-tf self-assigned this 2026-05-01 02:05:21 +00:00
Sign in to join this conversation.
No Branch/Tag specified
Branches Tags
development
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
mik-tf
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/docs_hero#1
No description provided.