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

docs: call out hero_embedder as a prerequisite and explain degraded mode #96

Merged
mahmoud merged 1 commit from development_docs_hero_embedder_prerequisite into development 2026-04-21 06:12:50 +00:00
Conversation 1 Commits 1 Files changed 2 +35
mahmoud commented 2026-04-21 05:58:42 +00:00
Owner
Copy link

Summary

Document hero_embedder as a required prerequisite for the full Hero Books feature set, explain degraded-mode behavior when it is not running, and surface the scary WARN message as a Troubleshooting entry so new users know it is informational.

Related Issue

Closes #87

Changes

  • README.md — new ### Prerequisites subsection at the top of Installation explaining the hero_embedder dependency, what features it enables, what "degraded mode" means, and pointing at the Hero-native install path (hero_skills + service_embedder + service_books). New ### Troubleshooting subsection that explains the WARN Cannot persist state line users were hitting, plus the "socket in use" case.
  • docs/manual/server.md — new "External Dependency: hero_embedder" section near the top describing the dependency, default endpoints, and degraded-mode behavior, linking to search.md and ai_processing.md for feature details.

Test Results

Docs-only change; no build or test suite affected.

## Summary Document `hero_embedder` as a required prerequisite for the full Hero Books feature set, explain degraded-mode behavior when it is not running, and surface the scary `WARN` message as a Troubleshooting entry so new users know it is informational. ## Related Issue Closes https://forge.ourworld.tf/lhumina_code/hero_books/issues/87 ## Changes - **`README.md`** — new `### Prerequisites` subsection at the top of Installation explaining the `hero_embedder` dependency, what features it enables, what "degraded mode" means, and pointing at the Hero-native install path (`hero_skills` + `service_embedder` + `service_books`). New `### Troubleshooting` subsection that explains the `WARN Cannot persist state` line users were hitting, plus the "socket in use" case. - **`docs/manual/server.md`** — new "External Dependency: hero_embedder" section near the top describing the dependency, default endpoints, and degraded-mode behavior, linking to `search.md` and `ai_processing.md` for feature details. ## Test Results Docs-only change; no build or test suite affected.
docs: call out hero_embedder as a prerequisite and explain degraded mode
All checks were successful
Test / test (pull_request) Successful in 9m19s
Details
Test / integration (pull_request) Successful in 4m5s
Details
b0a54811f8 
New users following the README's binary-install path were hitting a scary
"WARN Cannot persist state (hero_embedder unavailable)" line on first run
and assuming hero_books was broken (see issue #87). The dependency was
documented deep inside docs/manual/search.md and docs/manual/ai_processing.md
but never called out in the top-level README or the server manual — exactly
where a first-time user lands.

README.md:
- Add a Prerequisites subsection at the top of Installation explaining
  hero_embedder is a separate service, what features it enables, and what
  "degraded mode" means when it is not running.
- Point at the Hero-native install path (hero_skills + service_embedder +
  service_books) as the recommended way to bring both up together.
- Add a Troubleshooting subsection that explains the WARN log line and
  the "socket in use" case.

docs/manual/server.md:
- Add an "External Dependency: hero_embedder" section near the top
  describing the dependency, default endpoints, and degraded-mode
  behaviour, linking to search.md and ai_processing.md for feature details.

#87
mahmoud merged commit 1f20840072 into development 2026-04-21 06:12:50 +00:00
mahmoud deleted branch development_docs_hero_embedder_prerequisite 2026-04-21 06:12:55 +00:00
mahmoud commented 2026-04-21 06:38:00 +00:00
Author
Owner
Copy link

Superseded by #97, which rewrites the README in the hero_compute / hero_whiteboard style and folds the Prerequisites + Troubleshooting content from this PR into it (along with broader alignment work against hero_sockets, cargo_deps, and several other Hero skills). Recommending this one be closed once #97 lands.

Superseded by #97, which rewrites the README in the hero_compute / hero_whiteboard style and folds the Prerequisites + Troubleshooting content from this PR into it (along with broader alignment work against `hero_sockets`, `cargo_deps`, and several other Hero skills). Recommending this one be closed once #97 lands.
Sign in to join this conversation.
Reviewers
No reviewers
Labels
Clear labels   
prio_critical

   
prio_low

   
type_bug

   
type_contact

   
type_issue

   
type_lead

   
type_question

   
type_story

   
type_task
No labels
prio_critical
prio_low
type_bug
type_contact
type_issue
type_lead
type_question
type_story
type_task
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/hero_books!96
No description provided.