Documentation Registry Hub¶

1. What a doc hub is¶

A doc hub is a Git repository that:

Stores documentation as .md files with machine-readable frontmatter (title, summary, read_when)
Runs a CI pipeline on every push that validates frontmatter and regenerates index.json
Publishes index.json at a stable URL

An agent references one or more doc hubs. At query time it searches the index, finds relevant docs, and loads their full content into context on demand — the same progressive disclosure pattern as skills.

2. When a doc hub is useful¶

Doc hubs are most valuable for stable, reusable reference material that is:

Domain-specific — API references, protocol specs, data model docs for a specific technology
Shared across agents or teams — a team knowledge base, onboarding guides, architecture decisions
Too large to inject always — reference material that should only load when relevant

Less useful for project-specific or rapidly-changing docs, which belong in the local workspace.

Examples of good doc hub content:

REST API reference for an internal service
Compliance rules for a regulated domain (finance, healthcare)
Coding standards and architecture decisions for a team
Domain glossary for a specialized field

3. Hub repository structure¶

my-doc-hub/
├── .github/
│   └── workflows/
│       └── publish.yml     # validate + generate index.json on push
├── docs/
│   ├── api-reference.md
│   ├── data-model.md
│   ├── compliance-rules.md
│   └── ...
└── index.json              # generated by CI

Each .md file must have valid frontmatter:

---
title: "Payment API Reference"
summary: "Endpoints, auth, error codes, and rate limits for the Payment API."
read_when:
  - Implementing or debugging payment API calls
  - Reviewing error handling for payment flows
---

CI pipeline responsibilities¶

Validate each .md file has required frontmatter fields (title, summary, read_when)
Reject docs that fail validation — push fails, index.json not updated
Generate index.json from all valid docs' frontmatter
Publish index.json to the hub's stable URL

Implementation: The agentctl CLI provides hub validate and hub generate commands for CI pipeline integration.

index.json schema¶

Formal schema: schemas/docs-index.json

Naming convention: Use index.json for doc-only repos. If a repo contains both skills and docs, use skills.json and docs.json to avoid conflicts.

{
  "hub_id": "my-doc-hub",
  "generated_at": "2025-07-01T12:00:00Z",
  "docs": [
    {
      "slug": "api-reference",
      "title": "Payment API Reference",
      "summary": "Endpoints, auth, error codes, and rate limits for the Payment API.",
      "read_when": [
        "Implementing or debugging payment API calls",
        "Reviewing error handling for payment flows"
      ],
      "requires_skills": ["payment-api"],
      "git_url": "https://github.com/myorg/my-doc-hub",
      "path": "docs/api-reference.md",
      "commit": "abc123"
    }
  ]
}

requires_skills is omitted from the index entry when empty.

4. Multi-hub configuration¶

An agent holds a list of doc hub sources alongside skill hub sources:

[
  {
    "id": "payment-domain",
    "index_url": "https://myorg.github.io/payment-docs/index.json",
    "git_url": "https://github.com/myorg/payment-docs",
    "enabled": true,
    "ttl_hours": 24
  },
  {
    "id": "team-knowledge",
    "index_url": "https://raw.githubusercontent.com/myorg/kb/main/index.json",
    "git_url": "https://github.com/myorg/kb",
    "enabled": true,
    "ttl_hours": 6
  }
]

5. Two fetch modes¶

Same pattern as the skill hub:

Index fetch (for search) — GET index_url, cache with TTL. Fast, no clone.
Git fetch (for loading a doc) — sparse checkout of the specific .md file at the pinned commit. The full content is only fetched when the agent decides to load it.

This preserves progressive disclosure: the agent sees summary + read_when at search time, and only fetches the full doc body when it decides to load it into context.

6. Search and loading¶

Search¶

read_when entries are the primary search signal — they are written as load conditions, which maps directly to "find docs relevant to this situation". summary provides secondary signal.

Scorer weights (analogous to skill scorer):

read_when match +3 (primary load signal)
summary match +2
title match +1

When requires_skills is present, the agent annotates the result with the skill status:

All required skills installed → result is fully actionable
Some skills missing → result is flagged; agent can suggest installing them

Missing skills do not suppress the result — the doc may still be informational.

Loading¶

When the agent decides a doc is relevant:

Check requires_skills — if any are missing, surface a suggestion to install them
Fetch the full .md file content (sparse clone or raw URL)
Strip frontmatter, inject body into context
Optionally cache locally with TTL

No lock file needed — docs are read-only context, not installed artifacts.

7. Comparison to skill hub¶

	Skill hub	Doc hub
Unit	Skill directory (`SKILL.md` + scripts)	Single `.md` file
Effect	Injected into system prompt	Loaded into context on demand
Discovery field	`description`	`summary` + `read_when`
Install step	Yes — copied to local skills folder	No — fetched at load time
Lock file	Yes — tracks installed version	No
Versioning	Critical (behavior changes)	Less critical (docs drift slowly)
Validation	Schema + frontmatter validation	Schema only

The two hubs are complementary: skills add capabilities, doc hubs add knowledge.

8. Security¶

Validated at source — index.json only contains docs that passed CI frontmatter validation.
Read-only — docs are loaded as context only; no execution, no install step.
Git integrity — sparse fetch over HTTPS.
No auto-load — the agent decides when a doc is relevant; it does not load all hub docs unconditionally.

9. Setting up a doc hub¶

Create a Git repo
Add .md files according to authoring-guide.md, and organize them according to organization.md
Add a CI workflow that validates frontmatter and generates index.json
Publish index.json at a stable URL

For detailed frontmatter requirements and document formatting standards, see authoring-guide.md.

Implementation: Use agentctl hub validate to validate documentation frontmatter and agentctl hub generate to create the index.json file.