Adds the canonical role definition for `blackroad-os-docs` as the
documentation hub for BlackRoad OS, Lucidia, Quantum Lab, and agents.
### Changes
- **New file `docs/meta/REPO_ROLE.md`** — Complete repository role
definition including:
- Mission statement and ownership boundaries
- Quality rules (concrete examples, linked pages, owner tags)
- Compliance/safety guidelines (no secrets, compliance markers)
- Design principles for 3 personas (curious user, implementer/dev,
infra/operator)
- Emoji legend and success criteria
- Cross-links to related meta docs
### Structure
```markdown
## 🎯 MISSION
## 🏗️ YOU OWN (✅)
## 🚫 YOU DO *NOT* OWN
## 🧪 QUALITY RULES
## 🔐 COMPLIANCE / SAFETY
## 📏 DESIGN PRINCIPLES
## 🧬 LOCAL EMOJI LEGEND
## 🎯 SUCCESS CRITERIA
```
Accessible at `/meta/repo-role` in the docs site.
<!-- START COPILOT CODING AGENT SUFFIX -->
<details>
<summary>Original prompt</summary>
> 📚 DOCS BRAIN ONLINE 😭💚
>
> This one is **only** for `blackroad-os-docs` — docs hub for OS +
Lucidia + Quantum Lab + agents. Big emoji, one message, paste straight
in.
>
> ```txt
> 📚 REPO: blackroad-os-docs
> ROLE: Docs Hub 📚🧭 – canonical documentation for BlackRoad OS, Lucidia,
Quantum Lab, and agents.
>
> 🎯 MISSION
> • Be the **single source of truth** for all public + internal docs.
> • Translate architecture, math, and infra into words, diagrams, and
examples.
> • Make it easy for humans + agents to understand, use, and extend
BlackRoad OS.
>
> 🏗️ YOU OWN (✅)
> 📚 Documentation content:
> • “What is BlackRoad OS?” overviews 🧠
> • Lucidia + Quantum Lab explainers ⚛️
> • Agent concepts + how to work with agents 🤖
> • Getting started guides (install, login, first workflows) 🚀
>
> 🧭 Information architecture:
> • Clear nav structure (Overview → Concepts → Guides → Reference) 🗺️
> • Cross-links between OS, packs, agents, infra, research 🔗
> • Versioning strategy when APIs/features change 🔢
>
> 📓 Guides & tutorials:
> • “Hello, OS” – first-time user path 🌱
> • “Add a new app / agent / pack” step-by-step guides 🧩
> • “Connect infra pieces” (Railway, Cloudflare, GitHub) walkthroughs ☁️
>
> 📑 Reference:
> • API docs sourced from `blackroad-os-api` / `-api-gateway` 🌐
> • Core concepts & glossary (workspaces, envs, agents, packs, SIG,
etc.) 📘
> • Links out to deeper math in `blackroad-os-research` where needed 🧪
>
> 🚫 YOU DO *NOT* OWN
> 🚫 Actual implementation code → other repos (core, web, api, operator,
etc.) 💻
> 🚫 Infra definitions → `blackroad-os-infra` ☁️
> 🚫 Company handbook / policies → `blackroad-os-home` 🏠
> 🚫 Brand system source → `blackroad-os-brand` 🎨
> 🚫 Raw research / derivations → `blackroad-os-research` 🧪
> 🚫 System logs / append-only history → `blackroad-os-archive` 🧾
>
> 🧪 QUALITY RULES
> • Every page should be:
> ✅ Concrete: include at least one example or screenshot/diagram
> ✅ Linked: show “Related” / “Next steps” links at the bottom
> ✅ Owned: have an owner/area tag (Core, Web, Infra, Agents, Packs,
etc.)
>
> • Any code snippet must:
> 🧪 Actually compile/run in principle (no nonsense)
> 🔐 Use fake keys/accounts, never real secrets
>
> 🔐 COMPLIANCE / SAFETY
> • Do not embed live secrets or private identifiers in docs 🚫
> • Mark compliance-relevant docs clearly (e.g., logging, identity,
finance flows):
> 👉 `⚖️ COMPLIANCE-SENSITIVE DOC` at the top
>
> 📏 DESIGN PRINCIPLES
> • `blackroad-os-docs` is **for understanding**, not for dumping:
> 🧭 Prefer short, linked pages over one giant wall.
> 🎯 Write for 3 personas:
> 1) Curious user
> 2) Implementer/dev
> 3) Infra/operator
>
> • Each doc should answer:
> 1️⃣ What is this thing?
> 2️⃣ Why does it exist / when would I use it?
> 3️⃣ How do I actually do it, step by step?
>
> 🧬 LOCAL EMOJI LEGEND (SNAPSHOT)
> 📚 docs hub / content
> 🧭 navigation / structure
> 📓 guides / tutorials
> 📑 reference / API
> 🔗 cross-links
> 🧪 links to deeper research
> ⚖️ compliance-sensitive topics
>
> 🎯 SUCCESS CRITERIA
> If a new human or agent lands here from the outside world, they should
be able to:
> 1️⃣ Understand what BlackRoad OS + Lucidia + Quantum Lab are.
> 2️⃣ Follow a clear path to “first success” (first login, first
app/agent, first deploy).
> 3️⃣ Discover where to go next for deeper infra, math, or
implementation details.
> ```
>
> Hit me with **“Next!”** again and we’ll do `blackroad-os-brand` 🎨 next
so the neon road gods are properly documented 😭🛣️✨
</details>
<!-- START COPILOT CODING AGENT TIPS -->
---
💡 You can make Copilot smarter by setting up custom instructions,
customizing its development environment and configuring Model Context
Protocol (MCP) servers. Learn more [Copilot coding agent
tips](https://gh.io/copilot-coding-agent-tips) in the docs.
---------
Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: blackboxprogramming <118287761+blackboxprogramming@users.noreply.github.com>
- Add SYSTEM_PROMPT.md with full documentation philosophy
- Add STYLE_GUIDE.md with detailed writing standards
- Create services/ directory with docs for API, Operator, Core, Web, Prism, Infra
- Create agents/ directory with agent ecosystem documentation
- Create guides/ directory with getting-started and contributing guides
- Create runbooks/ directory with incident playbook and deployment runbooks
- Create reference/ directory with API reference placeholder
- Update sidebars.ts to include all new sections
- Update CONTRIBUTING.md to reference new comprehensive guides
- Update .gitignore to exclude binary assets per system prompt requirements
- All documentation builds successfully with no broken links
Co-authored-by: blackboxprogramming <118287761+blackboxprogramming@users.noreply.github.com>
