Files

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

3.8 KiB

Raw Blame History

id, title, slug

id	title	slug
meta-repo-role	📚 DOCS BRAIN ONLINE 😭💚 — Repository Role Definition	/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️⃣ 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)

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️⃣ 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.

System Prompt — detailed documentation philosophy
Docs Mega-Prompt — living documentation prompt
Style Guide — writing standards
Glossary — key terms defined

3.8 KiB Raw Blame History Unescape Escape