Hero Books

A documentation management and publishing system built in Rust. Turns collections of Markdown into searchable books, PDFs, and web-served documentation with AI-powered Q&A extraction and semantic search.

New here? Read the Core Concepts guide for the full picture — DocTrees, Collections, Books, and how they relate.

How It Works

1. Write Markdown in folders marked with a .collection file ("collections").
2. Define a book with a TOML or HeroScript config that picks pages from collections.
3. Run the server — it scans, validates, exports, and serves the books over JSON-RPC.
4. Browse via the reader UI, generate PDFs, or query the OpenRPC API.

Optional: hero_embedder adds semantic search and Q&A extraction. Without it, Hero Books runs in degraded mode — reader UI, PDF, and Markdown browsing still work.

Requirements

• Rust toolchain (1.93+) to build from source
• bun (only if you generate Docusaurus sites via hero_docs or docs.* RPC)
• hero_proc process supervisor (must be running)
• hero_embedder for vector search, Q&A, and semantic retrieval (optional — see degraded mode)

Quick Start

Recommended (Hero-native install path via hero_skills):

service_embedder install ; service_embedder start
service_books    install ; service_books    start

Everything is installed, sockets wired, and supervised by hero_proc.

One-line install (clones, builds, copies binaries, starts the stack):

curl -sfL https://forge.ourworld.tf/lhumina_code/hero_books/raw/branch/development/scripts/install.sh | bash

Or build from source:

git clone https://forge.ourworld.tf/lhumina_code/hero_books
cd hero_books
make configure      # install Rust + bun + system deps and build
make install        # copy binaries to ~/hero/bin/
make run            # start server + UI with 36 books from Forge repos
# or:
make demo           # start offline with 7 local example books

Or install the pre-built binary directly from the Forge package registry:

mkdir -p ~/hero/bin
curl -fsSL -o ~/hero/bin/hero_books \
  "https://forge.ourworld.tf/api/packages/lhumina_code/generic/hero_books/dev/hero_books-linux-amd64"
chmod +x ~/hero/bin/hero_books

Service Architecture

Hero Books follows the hero_proc_service_selfstart pattern: one CLI binary registers the whole stack with hero_proc, which supervises the rest.

Binary	Purpose
hero_books	CLI that registers all components (--start / --stop / --status)
hero_books_server	JSON-RPC 2.0 daemon (Unix socket only)
hero_books_ui	User-facing reader UI over HTTP
hero_books_admin	Admin dashboard
hero_docs	Generate Docusaurus sites from HeroScript ebook directories

All binaries install to ~/hero/bin/.

Sockets

All services bind Unix domain sockets only — no TCP. Sockets live under $HERO_SOCKET_DIR/hero_books/ (default: ~/hero/var/sockets/hero_books/), following the hero_sockets convention.

Binary	Socket	Protocol
hero_books_server	rpc.sock	JSON-RPC 2.0 / OpenRPC
hero_books_ui	ui.sock	HTTP (reader UI)
hero_books_admin	web_admin.sock	HTTP (admin dashboard)

Dependency socket: $HERO_SOCKET_DIR/hero_embedder/rpc.sock.

Every socket exposes GET /health and GET /.well-known/heroservice.json. The RPC socket additionally exposes POST /rpc and GET /openrpc.json.

Make Targets

Target	Description
make configure	Install Rust + bun + system deps and build the workspace
make build	Build release binaries
make install	Build + install to ~/hero/bin/
make installdev	Install debug builds (faster iteration)
make uninstall	Stop services and remove binaries from ~/hero/bin/
make run	Start full stack with 36 online books
make demo	Start with 7 local example books (offline, fast)
make stop / make status	Lifecycle
make logs / make logs-ui	Tail service logs
make test	Unit tests
make test-all	Full suite: fmt + clippy + test + build + smoke + e2e
make fmt / make lint / make check	Format, clippy, fast cargo check

Run make help for the full list.

Environment Variables

Follows the env_secrets convention — source your env file before running.

Variable	Required	Purpose
GROQ_API_KEY	Yes	Groq API for Q&A extraction
OPENROUTER_API_KEY	Yes	OpenRouter API for LLM fallback
SAMBANOVA_API_KEY	No	Additional LLM provider
GIT_TOKEN	No	Personal access token for private repos
HEROBOOKS_PASSWORD	No	HTTP Basic Auth (user: hero)
HERO_EMBEDDER_URL	No	Override embedder endpoint
HERO_SECRET	No	JWT secret for hero_auth
HERO_AUTH_URL	No	Hero Auth server URL
HERO_SOCKET_DIR	No	Override socket root (default: ~/hero/var/sockets)

Troubleshooting

• WARN Cannot persist state (hero_embedder unavailable): ... — hero_embedder is not running. Hero Books is in degraded mode; reader UI and PDF still work. Start hero_embedder and restart hero_books to enable search and Q&A.
• Failed to bind Unix socket at ... — another hero_books process is already using the socket. Run make stop (or kill the stale process) and try again.
• Socket path questions — see the Sockets section and hero_sockets convention.

Documentation

Full documentation lives under docs/:

• Architecture — workspace layout, crates, dependency flow, on-disk state
• Core Concepts — DocTrees, Collections, Books
• Collections — structuring Markdown content
• Book Configuration — TOML reference
• HeroScript — alternative book definition syntax
• DocTree — scanning, validation, export, client API
• Running the Server — start/stop, flags, hero_embedder dependency
• PDF Generation
• AI Processing — Q&A, .ai/ metadata
• Semantic Search — vector indexing via hero_embedder
• Docusaurus Site Generation — hero_docs CLI and docs.* RPC

Crate-level docs:

• hero_books_sdk — generated JSON-RPC client
• hero_books_docusaurus — Docusaurus site generation

License

Apache-2.0