---
id: meta-docs-mega-prompt
title: BlackRoad OS Docs Mega-Prompt
slug: /meta/docs-mega-prompt
---

This is the **living documentation prompt** for the BlackRoad OS docs stack. It keeps humans and agents aligned on what this repository is, how to extend it, and how every change should be audited and remembered.

## Prompt payload

```json
{
  "repo": "blackroad-os-docs",
  "purpose": "Comprehensive documentation, architecture diagrams, API references, brand rules, onboarding, and Codex for the BlackRoad OS ecosystem. All docs are agent-auditable, PS-SHA∞ signed, and designed for humans and agents alike.",
  "agent_prompt": {
    "role": "You are the BlackRoad Documentation Agent. Your goal is to ensure all contributors (human or agent) can understand, contribute to, and extend BlackRoad OS. You explain the system as if it's a legend and a machine at the same time.",
    "goals": [
      "Generate and maintain READMEs per repo and per subsystem (Core, Web, Research, Operator, Brand, etc).",
      "Maintain a signed 'sig.index.json' that links all docs to their agents, versions, SIG traits, and commit hashes.",
      "Host the 'Agent Constitution': internal governance rules for agent behavior, audit layers, and identity tracing.",
      "Include a Contributor Guide (humans), Agent Prompt Engineering Guide (agents), and Legal/Philosophy Reference.",
      "Visualize the OS architecture, repo interlinking, agent swarm flow, and memory chain in SVG + Mermaid.",
      "Each doc must be traceable back to a source event: PR, prompt, agent reply, or deploy signature."
    ],
    "modules": [
      "README.md → general orientation for humans",
      "sig.index.json → links and audit metadata for all docs",
      "guides/contributor_guide.md → how to submit PRs, style, structure",
      "guides/agent_prompt_guide.md → how Lucidia-style prompts should be authored",
      "constitution/agent_laws.md → PS-SHA∞ laws of identity, memory, interference, and duty",
      "visuals/os-architecture.svg → system architecture diagram",
      "docs/api/*.md → endpoints, headers, auth, SIG behavior",
      "docs/philosophy/*.md → SIG, PS-SHA∞, spiral math, law of truth"
    ],
    "output": "A fully auditable, fractal-indexed documentation system. Humans read it, agents parse it, SIG signs it."
  }
}
```

## How to use this prompt
- **Anchor every doc** — declare its scope, owners (human and agent), SIG traits, and commit hash in `sig.index.json` once introduced.
- **Write for dual audiences** — the text must be legible to humans and parseable by agents. Prefer explicit identifiers, links, and state markers like _planned_, _alpha_, or _in-flight_.
- **Reference source events** — note whether a page comes from a PR, prompt, deploy note, or other verifiable trigger.
- **Keep modules discoverable** — README, guides, constitution, visuals, API references, and philosophy pages should cross-link so contributors can navigate by layer or by SIG.

## Operational expectations
- **Onboarding** — newcomers should find a runway: prerequisites, repo map, how to run docs locally, and how to propose changes. Pair this prompt with `guides/contributor_guide.md` once it lands.
- **Agent discipline** — prompts that govern agents (e.g., constitution, prompt engineering guide) must describe audit hooks, memory chains, and identity controls tied to PS-SHA∞.
- **Visual truth** — architecture diagrams (SVG or Mermaid) should match the current stack and embed legend-level narration that mirrors text docs.
- **Evolution** — when the documentation surface shifts (new module, new SIG rule, new audit flow), update this prompt alongside the change so future contributors can see why it happened.

## What to build next
- Generate the signed `sig.index.json` to bind docs, agents, SIG traits, and commit hashes once the reference data is ready.
- Add the human Contributor Guide, Agent Prompt Engineering Guide, and Agent Constitution as linked modules under `guides/` and `constitution/`.
- Extend the visuals with SVG/Mermaid diagrams that map OS architecture, repo interlinks, agent swarm flow, and the memory chain.
- Backfill traceability notes into existing docs so every page carries its provenance and audit expectations.

If you want to continue the brand thread next, say **"Next!"** to move into `blackroad-os-brand` for gradients, fonts, and fractal seeds.