blackroad-os/blackroad-os-docs
9
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
dc207ec852e2dac1712a12bdbdc86f5f77e83603
blackroad-os-docs/docs/meta/REPO_ROLE.md
Copilot 554417c3ce 📚 DOCS BRAIN ONLINE — Add Repository Role Definition (#53) 
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>
2025-11-29 22:22:19 -06:00

132 lines
3.8 KiB
Markdown
Raw Blame History

This file contains invisible Unicode characters
This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
---
id: meta-repo-role
title: 📚 DOCS BRAIN ONLINE 😭💚 — Repository Role Definition
slug: /meta/repo-role
---
# 📚 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. 1️⃣ What is this thing?
2. 2️⃣ Why does it exist / when would I use it?
3. 3️⃣ How do I actually do it, step by step?
---
## 🧬 LOCAL EMOJI LEGEND (SNAPSHOT)
| Emoji | Meaning |
|-------|---------|
| 📚 | 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. 1️⃣ Understand what BlackRoad OS + Lucidia + Quantum Lab are.
2. 2️⃣ Follow a clear path to "first success" (first login, first app/agent, first deploy).
3. 3️⃣ Discover where to go next for deeper infra, math, or implementation details.
---
## Related
- [System Prompt](./SYSTEM_PROMPT.md) — detailed documentation philosophy
- [Docs Mega-Prompt](./DOCS_MEGA_PROMPT.mdx) — living documentation prompt
- [Style Guide](./STYLE_GUIDE.md) — writing standards
- [Glossary](./GLOSSARY.mdx) — key terms defined
Reference in New Issue View Git Blame Copy Permalink