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.

Or download the pre-built binaries:

service books install --download
service books start

Service Architecture

Hero Books is supervised by hero_proc via the hero_skills nu service scripts.

Binary	Purpose
hero_books_server	JSON-RPC 2.0 daemon (Unix socket only)
hero_books_web	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_web	web.sock	HTTP (reader UI)
hero_books_admin	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.

Service Commands

Use Nushell service scripts from hero_skills:

service books install        # build and install all binaries
service books start          # register with hero_proc and start
service books stop           # stop and unregister
service books status         # show service status
service books install --download   # download pre-built binaries
service books start --update       # pull latest code, rebuild, restart

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 service books 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