How HERA Docs Work

HERA documentation is fully dynamic and data-driven. Pages are not static markdown files - they are stored in the database and rendered at runtime. This means you can create, update, and publish documentation without any code deployment.

Data-Driven Architecture

All documentation content lives in the Sacred Six tables (core_entities + core_dynamic_data), following HERA's constitutional data model.

Architecture Overview

Each documentation article is a CONTENT_DOC entity with its content stored as structured blocks in dynamic data.

data-model.txt

core_entities
├── id: uuid
├── entity_type: 'CONTENT_DOC'
├── entity_name: 'Article Title'
└── smart_code: 'HERA.DOCS.ENTITY.DOC.SLUG.v1'

core_dynamic_data
├── slug: 'how-docs-work'
├── status: 'PUBLISHED' | 'DRAFT'
├── version: 1
├── summary: 'Brief description'
├── body_blocks: [ ...blocks JSON... ]
└── nav_level: 0

text

Runtime Flow

Route Resolution

User visits /docs/[slug] - Next.js catches the route

Database Query

Server queries core_entities for CONTENT_DOC with matching slug

Status Check

Only articles with status=PUBLISHED are served (drafts return 404)

Block Rendering

DocsArticleRenderer interprets body_blocks JSON and renders each block type

Block Types

The renderer supports six block types, each with its own schema:

block-types.ts

type BlockType = 
  | 'heading'    // level: 1-3, text, id
  | 'paragraph'  // text (supports inline formatting)
  | 'code'       // code, language, filename
  | 'callout'    // variant: info|warning|success|danger, title, text
  | 'steps'      // items: { title, text }[]
  | 'divider'    // no props needed

typescript

Creating Documentation

Use the docs factory CLI to create and manage documentation:

terminal

# Create a new doc (starts as DRAFT)
node mcp-server/scripts/hera-docs-factory.v1.mjs upsert \
  --slug=my-article \
  --title="My Article" \
  --summary="What this article covers" \
  --body-file=fixtures/docs/my-article.json

# Publish when ready
node mcp-server/scripts/hera-docs-factory.v1.mjs publish --slug=my-article

# List all docs
node mcp-server/scripts/hera-docs-factory.v1.mjs list

# Validate a doc
node mcp-server/scripts/hera-docs-factory.v1.mjs validate --slug=my-article

bash

Safe Publishing Model

Two-Stage Publishing

Claude CLI can only create/update documents as DRAFT. Publishing requires explicit action, ensuring human review before content goes live.

publishing-model.txt

┌──────────────┬──────────────────────────┐
│    Actor     │          Can Do          │
├──────────────┼──────────────────────────┤
│ Claude CLI   │ Create/update DRAFT only │
├──────────────┼──────────────────────────┤
│ Human/Policy │ Flip status to PUBLISHED │
└──────────────┴──────────────────────────┘

text

Why Dynamic?

This architecture provides several benefits over static documentation:

No Deployment Required

Update docs instantly via database - no build, no deploy, no CI/CD

Version Control in Data

Each update increments version number, maintaining history in the database

Access Control

DRAFT vs PUBLISHED status controls visibility without file-level permissions

Structured Content

JSON blocks ensure consistent formatting and enable future features like search indexing

AI-Native

Claude can create and update documentation using the factory CLI

You're Reading Dynamic Content

This very page was created using the docs factory and is served dynamically from the database. No static files involved!