blackroad-os/blackroad-os-docs
9
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add comprehensive system prompt, style guide, and documentation structure

Browse Source 
- 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>
This commit is contained in:
copilot-swe-agent[bot]
2025-11-24 16:42:05 +00:00
parent ea7d26add1
commit 1845e069e0
25 changed files with 3528 additions and 17 deletions
Download Patch File Download Diff File Expand all files Collapse all files

65
.gitignore vendored
View File

@@ -1,20 +1,81 @@
# Dependencies
node_modules node_modules
package-lock.json.bak
# Build outputs
build build
dist
.docusaurus .docusaurus
.next .next
.DS_Store out
# Environment files
.env .env
.env.local .env.local
.env.*.local
.env.* .env.*
# Cache and temp files
.cache .cache
.tmp
tmp
*.log
npm-debug.log* npm-debug.log*
yarn-debug.log* yarn-debug.log*
yarn-error.log* yarn-error.log*
pnpm-debug.log*
# Lock files (optional - remove if you want to track them)
pnpm-lock.yaml pnpm-lock.yaml
.tmp
# IDE
.vscode .vscode
.idea .idea
*.swp
*.swo
*~
.DS_Store
# Generated files
static/health.json static/health.json
static/health/ static/health/
static/version.json static/version.json
static/version/ static/version/
# Binary assets - DO NOT COMMIT per system prompt
*.png
*.jpg
*.jpeg
*.gif
*.ico
*.pdf
*.zip
*.tar
*.tar.gz
*.mp4
*.mov
*.avi
*.psd
*.sketch
*.fig
# Allow specific blessed images if needed (uncomment and specify)
# !static/logo.svg
# !static/favicon.ico
# Secrets and sensitive data
*.key
*.pem
*.p12
*.pfx
secrets.json
credentials.json
# Testing
coverage
.nyc_output
*.lcov
# OS
Thumbs.db
Desktop.ini

50
CONTRIBUTING.md
View File

@@ -2,21 +2,44 @@
This repository is the canonical source of truth for BlackRoad OS documentation. Contributions should help operators, partners, and developers understand the system quickly without sacrificing accuracy. This repository is the canonical source of truth for BlackRoad OS documentation. Contributions should help operators, partners, and developers understand the system quickly without sacrificing accuracy.
> 📚 **New to contributing?** Check out the comprehensive [Contributing Guide](docs/guides/contributing.md) and [Style Guide](docs/meta/STYLE_GUIDE.md) for detailed information.
## Quick setup ## Quick setup
- Use Node.js 20+ with npm or pnpm installed. - Use Node.js 20+ with npm or pnpm installed.
- Install dependencies once via `npm install`. - Install dependencies once via `npm install`.
- Run `npm run start` for the local docs server at http://localhost:3000. - Run `npm run start` for the local docs server at http://localhost:3000.
## Writing guidelines ## Writing guidelines
See the [Style Guide](docs/meta/STYLE_GUIDE.md) for comprehensive documentation standards. Quick tips:
- Write in Markdown using `##` for sections and `###` for subsections. - Write in Markdown using `##` for sections and `###` for subsections.
- Prefer relative links like `[Agents](/docs/agents.md)` so content works in GitHub and static exports. - Prefer relative links like `[Agents](../agents/agent-ecosystem.md)` so content works in GitHub and static exports.
- Keep paragraphs short, use bullet lists for steps, and clearly mark components as planned/alpha/in-flight when applicable. - Keep paragraphs short, use bullet lists for steps, and clearly mark components as planned/alpha/in-flight when applicable.
- Reuse diagrams via Mermaid blocks or link to shared assets (e.g., Lucidia/QI) instead of embedding large binaries. - Reuse diagrams via Mermaid blocks or ASCII art instead of embedding binary images.
## Adding or updating pages ## Adding or updating pages
- Place new documents under the closest matching folder within `docs/` (for example, `docs/dev/` for developer-facing content).
- Update `sidebars.ts` when adding new top-level pages so navigation stays in sync. - Place new documents under the closest matching folder within `docs/` (for example, `docs/services/` for service documentation, `docs/guides/` for how-to guides).
- Include concise frontmatter (title, slug) and cross-link related pages to reduce duplication. - Update `sidebars.ts` when adding new pages so navigation stays in sync.
- Include concise frontmatter (title, slug, description) and cross-link related pages to reduce duplication.
## Document structure
BlackRoad OS docs are organized into clear categories:
- `docs/overview/` - High-level architecture and system overview
- `docs/services/` - Per-service documentation (API, Operator, Core, Web, etc.)
- `docs/agents/` - Agent ecosystem and development
- `docs/guides/` - How-to guides and tutorials
- `docs/runbooks/` - Operational runbooks and procedures
- `docs/reference/` - API reference and technical specs
- `docs/ops/` - Operations and infrastructure
- `docs/infra/` - Infrastructure configuration and deployment
- `docs/dev/` - Developer-focused content
- `docs/meta/` - Documentation about documentation
See the [System Prompt](docs/meta/SYSTEM_PROMPT.md) for the complete documentation philosophy.
## Validation checklist ## Validation checklist
- Run `npm run build` to catch broken links and frontmatter issues before opening a pull request. - Run `npm run build` to catch broken links and frontmatter issues before opening a pull request.
@@ -27,3 +50,20 @@ This repository is the canonical source of truth for BlackRoad OS documentation.
- Keep changes scoped and describe the audience and intent in the PR summary. - Keep changes scoped and describe the audience and intent in the PR summary.
- Call out cross-repo impacts (e.g., updates required in `blackroad-os-operator` or `blackroad-os-api`). - Call out cross-repo impacts (e.g., updates required in `blackroad-os-operator` or `blackroad-os-api`).
- Favor iterative updates over large rewrites so reviewers can ship improvements continuously. - Favor iterative updates over large rewrites so reviewers can ship improvements continuously.
## Security
**Never commit:**
- Secrets, API keys, or credentials
- Binary images (PNG, JPEG, etc.) - use Mermaid or ASCII diagrams instead
- Large files or build artifacts
- Sensitive personal data
See the [Security section](docs/meta/SYSTEM_PROMPT.md#6️⃣-safety--secrets-🔐🚫) of the System Prompt for details.
## Resources
- 📖 [System Prompt](docs/meta/SYSTEM_PROMPT.md) - Complete documentation philosophy
- ✍️ [Style Guide](docs/meta/STYLE_GUIDE.md) - Detailed writing standards
- 🤝 [Contributing Guide](docs/guides/contributing.md) - Full contribution workflow
- 🏠 [Getting Started](docs/guides/getting-started-local.md) - Local development setup

231
docs/agents/agent-ecosystem.md Normal file
View File

@@ -0,0 +1,231 @@
---
id: agents-agent-ecosystem
title: "Agent Ecosystem"
slug: /agents/agent-ecosystem
description: "Overview of the BlackRoad OS agent ecosystem"
tags: ["agents", "architecture"]
status: stable
---
# Agent Ecosystem
The BlackRoad OS agent ecosystem is a distributed network of autonomous agents that can reason, act, and collaborate to accomplish complex tasks.
## Overview
BlackRoad OS agents are:
- **Autonomous:** Capable of independent decision-making
- **Identifiable:** Each has a unique PS-SHA∞ identity
- **Stateful:** Maintain memory and context across interactions
- **Collaborative:** Can work together on shared goals
- **Traceable:** All actions are auditable
## Agent Architecture
```mermaid
flowchart TD
Agent[Agent] --> Identity[PS-SHA∞ Identity]
Agent --> Memory[Agent Memory]
Agent --> Capabilities[Capabilities]
Agent --> Actions[Action Executors]
Memory --> ShortTerm[Short-term Memory]
Memory --> LongTerm[Long-term Memory]
Actions --> API[API Calls]
Actions --> Jobs[Job Execution]
Actions --> Events[Event Emission]
```
## Core Components
### Identity
Every agent has a PS-SHA∞ identity that:
- Uniquely identifies the agent
- Signs all agent actions
- Enables trust and verification
- Tracks agent lineage
See [Agent Identity and Memory](agents/agent-identity-and-memory.md) _(planned)_ for details.
### Memory
Agents maintain two types of memory:
**Short-term Memory:**
- Current conversation context
- Active task state
- Temporary variables
**Long-term Memory:**
- Historical interactions
- Learned patterns
- Persistent knowledge
### Capabilities
Agents declare what they can do:
- Code generation
- Documentation writing
- Data analysis
- System monitoring
- etc.
### Actions
Agents can:
- Call APIs
- Submit jobs to Operator
- Emit events
- Interact with other agents
- Modify their own state
## Agent Types
### Task Agents
Focused on specific, well-defined tasks:
- Code review agent
- Documentation agent
- Testing agent
- Deployment agent
### Orchestrator Agents
Coordinate multiple agents:
- Project manager agent
- Workflow agent
- Decision-making agent
### Monitor Agents
Observe and report:
- System health agent
- Performance monitoring agent
- Alert agent
### Research Agents
Explore and analyze:
- Data analysis agent
- Pattern recognition agent
- Optimization agent
## Agent Lifecycle
```
Created → Initialized → Active → Paused → Active → Deactivated
```
1. **Created:** Agent identity established
2. **Initialized:** Capabilities loaded, memory initialized
3. **Active:** Processing tasks and events
4. **Paused:** Temporarily inactive
5. **Deactivated:** Permanently stopped
## Agent Communication
Agents communicate through:
### Direct Messages
Point-to-point communication between agents.
### Events
Broadcast messages on event bus.
### Shared Memory
Collaborative access to shared data structures.
### Job Queue
Asynchronous task delegation via Operator.
## Agent Registry
The Agent Registry maintains:
- Active agent inventory
- Agent capabilities
- Agent status
- Agent relationships
## Best Practices
### Designing Agents
1. **Single Responsibility:** Each agent should have a clear, focused purpose
2. **Declarative Capabilities:** Explicitly declare what the agent can do
3. **Graceful Degradation:** Handle failures without cascading
4. **Observable:** Emit events for monitoring
### Agent Collaboration
1. **Clear Protocols:** Define communication patterns
2. **Event-Driven:** Use events for loose coupling
3. **Avoid Cycles:** Prevent infinite agent loops
4. **Timeout Handling:** Set reasonable timeouts
### Security
1. **Verify Identity:** Always check PS-SHA∞ signatures
2. **Least Privilege:** Grant minimal necessary permissions
3. **Audit Everything:** Log all agent actions
4. **Sandbox Execution:** Isolate untrusted code
## Development
### Creating an Agent
```typescript
import { Agent, AgentCapability } from '@blackroad-os/core';
const myAgent: Agent = {
id: 'agent-unique-id',
name: 'My Custom Agent',
capabilities: [
AgentCapability.CODE_GENERATION,
AgentCapability.TESTING
],
memory: {
shortTerm: {},
longTerm: {}
}
};
```
See [Extending Agents](dev/extending-agents.md) for detailed guide.
### Testing Agents
```typescript
import { test, expect } from 'vitest';
import { createTestAgent } from '@blackroad-os/core/testing';
test('agent executes task', async () => {
const agent = createTestAgent({
capabilities: [AgentCapability.TESTING]
});
const result = await agent.execute(task);
expect(result.status).toBe('success');
});
```
## Monitoring Agents
Use [Prism Console](ops/PRISM_CONSOLE.md) to monitor:
- Agent inventory and status
- Agent activity and performance
- Agent memory usage
- Agent communication patterns
## Related Documentation
- [Agents Atlas and Friends](dev/AGENTS_ATLAS_AND_FRIENDS.md) - Specific agent implementations
- [Extending Agents](dev/extending-agents.md) - Development guide
- [Core Primitives](dev/CORE_PRIMITIVES.md) - Agent data types
- [Events and RoadChain](dev/EVENTS_AND_ROADCHAIN.md) - Event system
## See Also
- [Service: Operator](services/service-operator.md) - Job execution
- [Service: API](services/service-api.md) - Agent API endpoints

28
docs/agents/agent-identity-and-memory.md Normal file
View File

@@ -0,0 +1,28 @@
---
id: agents-agent-identity-and-memory
title: "Agent Identity and Memory"
slug: /agents/agent-identity-and-memory
description: "PS-SHA∞ identity and memory management for agents"
tags: ["agents", "identity", "memory"]
status: planned
---
# Agent Identity and Memory
> 📋 **Status:** This document is planned and will be developed.
Deep dive into PS-SHA∞ identity and memory management for BlackRoad OS agents.
## Planned Content
This document will cover:
- PS-SHA∞ identity implementation
- Agent identity verification
- Memory architecture
- State persistence
- Identity lineage tracking
## See Also
- [Agent Ecosystem](./agent-ecosystem.md)
- [Core Primitives](dev/CORE_PRIMITIVES.md)

60
docs/guides/coding-standards.md Normal file
View File

@@ -0,0 +1,60 @@
---
id: guides-coding-standards
title: "Coding Standards"
slug: /guides/coding-standards
description: "Coding standards for BlackRoad OS projects"
tags: ["guides", "development", "standards"]
status: planned
---
# Coding Standards
> 📋 **Status:** This document is planned and will be developed.
Comprehensive coding standards for BlackRoad OS development.
## Overview
This document will provide:
- Language-specific coding conventions
- Best practices for TypeScript/JavaScript
- Testing requirements
- Code review guidelines
- Performance considerations
## Planned Sections
### TypeScript/JavaScript
- Naming conventions
- Type safety requirements
- Async/await patterns
- Error handling
### Testing
- Unit test requirements
- Integration test patterns
- E2E test guidelines
- Coverage expectations
### Documentation
- Code comment standards
- JSDoc requirements
- README templates
### Security
- Input validation
- Authentication patterns
- Secret management
- Dependency security
## Current Resources
For now, please refer to:
- [Contributing Guide](./contributing.md)
- [Style Guide](meta/STYLE_GUIDE.md)
- Existing code in repositories as examples
## See Also
- [Contributing Guide](./contributing.md)
- [Getting Started - Local](./getting-started-local.md)

249
docs/guides/contributing.md Normal file
View File

@@ -0,0 +1,249 @@
---
id: guides-contributing
title: "Contributing to BlackRoad OS"
slug: /guides/contributing
description: "How to contribute to BlackRoad OS projects"
tags: ["guides", "contributing"]
status: stable
---
# Contributing to BlackRoad OS
Thank you for your interest in contributing to BlackRoad OS! This guide will help you get started.
## Code of Conduct
We are committed to providing a welcoming and inclusive environment. All contributors are expected to:
- Be respectful and professional
- Provide constructive feedback
- Focus on what's best for the community
- Show empathy towards others
## Getting Started
### 1. Choose a Repository
BlackRoad OS consists of multiple repositories:
- [blackroad-os-core](https://github.com/BlackRoad-OS/blackroad-os-core) - Core library and types
- [blackroad-os-api](https://github.com/BlackRoad-OS/blackroad-os-api) - API service
- [blackroad-os-operator](https://github.com/BlackRoad-OS/blackroad-os-operator) - Job orchestration
- [blackroad-os-web](https://github.com/BlackRoad-OS/blackroad-os-web) - Web application
- [blackroad-os-docs](https://github.com/BlackRoad-OS/blackroad-os-docs) - Documentation
See [Stack Map](overview/STACK_MAP.md) for a complete list.
### 2. Fork and Clone
```bash
# Fork the repository on GitHub, then:
git clone https://github.com/YOUR-USERNAME/REPO-NAME.git
cd REPO-NAME
# Add upstream remote
git remote add upstream https://github.com/BlackRoad-OS/REPO-NAME.git
```
### 3. Set Up Development Environment
Follow the local development guide for your repository:
- [Getting Started - Local Development](./getting-started-local.md)
## Contribution Workflow
### 1. Create a Branch
```bash
# Sync with upstream
git fetch upstream
git checkout main
git merge upstream/main
# Create feature branch
git checkout -b feature/my-feature
```
Branch naming conventions:
- `feature/` - New features
- `fix/` - Bug fixes
- `docs/` - Documentation changes
- `refactor/` - Code refactoring
- `test/` - Test additions/fixes
### 2. Make Changes
- Write clean, well-documented code
- Follow existing code style
- Add tests for new functionality
- Update documentation as needed
### 3. Test Your Changes
```bash
# Run tests
npm test
# Run linter
npm run lint
# Build to verify
npm run build
```
### 4. Commit Changes
Use clear, descriptive commit messages:
```bash
git add .
git commit -m "Add feature: brief description
Longer description if needed, explaining:
- What changed
- Why it changed
- Any breaking changes"
```
Commit message format:
```
<type>: <subject>
<body>
<footer>
```
Types: `feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore`
### 5. Push and Create Pull Request
```bash
git push origin feature/my-feature
```
Then create a Pull Request on GitHub:
1. Go to your fork on GitHub
2. Click "Compare & pull request"
3. Fill in the PR template
4. Link related issues
5. Request review
## Pull Request Guidelines
### PR Description
Include:
- **What:** What changes were made
- **Why:** Why these changes are needed
- **How:** How to test the changes
- **Screenshots:** For UI changes (if applicable)
### PR Checklist
Before submitting:
- [ ] Code follows the project style guide
- [ ] Tests added/updated and passing
- [ ] Documentation updated
- [ ] No console errors or warnings
- [ ] Branch is up to date with main
- [ ] Commit messages are clear
- [ ] PR description is complete
## Code Review Process
### What to Expect
1. Automated checks run (tests, linting, build)
2. Maintainers review your code
3. Feedback may be provided
4. You may need to make changes
5. Once approved, your PR will be merged
### Responding to Feedback
- Be open to suggestions
- Ask questions if unclear
- Make requested changes promptly
- Push updates to the same branch
## Coding Standards
### TypeScript/JavaScript
- Use TypeScript strict mode
- Prefer `const` over `let`
- Use async/await over promises chains
- Write self-documenting code
- Add JSDoc comments for public APIs
Example:
```typescript
/**
* Fetches agent by ID
* @param id - Agent identifier
* @returns Agent object or null if not found
*/
async function getAgent(id: string): Promise<Agent | null> {
// Implementation
}
```
### Testing
- Write unit tests for logic
- Write integration tests for APIs
- Aim for >80% coverage
- Test edge cases and errors
### Documentation
- Update README if needed
- Add/update inline comments
- Update docs/ for features
- Include examples
## Community
### Getting Help
- **GitHub Issues:** Report bugs or request features
- **Discussions:** Ask questions or share ideas
- **Discord:** _(if available)_ Real-time chat
### Reporting Bugs
When reporting bugs, include:
1. **Description:** What went wrong
2. **Steps to Reproduce:** How to recreate the bug
3. **Expected Behavior:** What should happen
4. **Actual Behavior:** What actually happened
5. **Environment:** OS, Node version, etc.
6. **Logs/Screenshots:** Any relevant output
### Suggesting Features
When suggesting features:
1. **Use Case:** Why is this needed
2. **Proposed Solution:** How it could work
3. **Alternatives:** Other approaches considered
4. **Additional Context:** Any other info
## Recognition
Contributors are recognized in:
- Repository CONTRIBUTORS file
- Release notes
- Project documentation
Thank you for making BlackRoad OS better! 🖤✨
## See Also
- [Getting Started - Local](./getting-started-local.md)
- [Style Guide](meta/STYLE_GUIDE.md)
- [System Prompt](meta/SYSTEM_PROMPT.md)

222
docs/guides/getting-started-local.md Normal file
View File

@@ -0,0 +1,222 @@
---
id: guides-getting-started-local
title: "Getting Started - Local Development"
slug: /guides/getting-started-local
description: "Set up BlackRoad OS for local development"
tags: ["guides", "getting-started", "local"]
status: stable
---
# Getting Started - Local Development
This guide walks you through setting up BlackRoad OS services for local development.
## Prerequisites
Before you begin, ensure you have:
- **Node.js** 20+ installed ([Download](https://nodejs.org/))
- **npm** or **pnpm** package manager
- **Git** for cloning repositories
- **Docker** (optional, for Redis/PostgreSQL)
- **PostgreSQL** 14+ (local or Docker)
- **Redis** 6+ (local or Docker)
## Quick Start
### 1. Clone Repositories
Start with the core services:
```bash
# Create a workspace directory
mkdir blackroad-os && cd blackroad-os
# Clone core repositories
git clone https://github.com/BlackRoad-OS/blackroad-os-core.git
git clone https://github.com/BlackRoad-OS/blackroad-os-api.git
git clone https://github.com/BlackRoad-OS/blackroad-os-operator.git
git clone https://github.com/BlackRoad-OS/blackroad-os-web.git
```
### 2. Set Up Database
Using Docker:
```bash
# Start PostgreSQL
docker run -d \
--name blackroad-postgres \
-e POSTGRES_PASSWORD=devpassword \
-e POSTGRES_DB=blackroad_dev \
-p 5432:5432 \
postgres:14
# Start Redis
docker run -d \
--name blackroad-redis \
-p 6379:6379 \
redis:latest
```
Or install locally per your OS instructions.
### 3. Configure Services
#### API Service
```bash
cd blackroad-os-api
npm install
cp .env.example .env
```
Edit `.env`:
```bash
DATABASE_URL=postgresql://postgres:devpassword@localhost:5432/blackroad_dev
REDIS_URL=redis://localhost:6379
API_PORT=3000
JWT_SECRET=local-dev-secret-change-me
OPERATOR_URL=http://localhost:3001
```
Run migrations:
```bash
npm run migrate
```
#### Operator Service
```bash
cd ../blackroad-os-operator
npm install
cp .env.example .env
```
Edit `.env`:
```bash
DATABASE_URL=postgresql://postgres:devpassword@localhost:5432/blackroad_dev
REDIS_URL=redis://localhost:6379
OPERATOR_PORT=3001
WORKER_CONCURRENCY=2
```
#### Web Service
```bash
cd ../blackroad-os-web
npm install
cp .env.example .env.local
```
Edit `.env.local`:
```bash
NEXT_PUBLIC_API_URL=http://localhost:3000
NEXT_PUBLIC_WS_URL=ws://localhost:3000
```
### 4. Start Services
Open separate terminal windows for each service:
**Terminal 1 - API:**
```bash
cd blackroad-os-api
npm run dev
```
**Terminal 2 - Operator:**
```bash
cd blackroad-os-operator
npm run dev
```
**Terminal 3 - Web:**
```bash
cd blackroad-os-web
npm run dev
```
### 5. Verify Setup
- **API:** http://localhost:3000/health
- **Operator:** http://localhost:3001/health
- **Web:** http://localhost:3030 (or configured port)
## Development Workflow
### Making Changes
1. Create a feature branch
2. Make your changes
3. Run tests: `npm test`
4. Run linter: `npm run lint`
5. Build: `npm run build`
6. Commit and push
### Running Tests
```bash
# In any service directory
npm test # Run all tests
npm run test:watch # Watch mode
npm run test:coverage # Coverage report
```
### Database Migrations
When schema changes are needed:
```bash
# Create migration
npm run migrate:create my-migration-name
# Run migrations
npm run migrate
# Rollback
npm run migrate:rollback
```
## Troubleshooting
### Database Connection Failed
- Verify PostgreSQL is running: `docker ps | grep postgres`
- Check connection string in `.env`
- Test connection: `psql postgresql://postgres:devpassword@localhost:5432/blackroad_dev`
### Redis Connection Failed
- Verify Redis is running: `docker ps | grep redis`
- Test connection: `redis-cli ping` (should return `PONG`)
### Port Already in Use
Change ports in `.env` files:
```bash
API_PORT=3010
OPERATOR_PORT=3011
# etc.
```
### Module Not Found
```bash
# Clear node_modules and reinstall
rm -rf node_modules package-lock.json
npm install
```
## Next Steps
- [Extending Agents](dev/extending-agents.md) - Create custom agents
- [API Overview](dev/API_OVERVIEW.md) - Understand API structure
- [Contributing Guide](guides/contributing.md) _(reference CONTRIBUTING.md)_
- [Coding Standards](guides/coding-standards.md) _(planned)_
## See Also
- [Repositories and Services](dev/repos-and-services.md) - Complete repo map
- [Local Development](dev/local-development.md) - Additional dev info
- [Stack Map](overview/STACK_MAP.md) - Architecture overview

150
docs/meta/DOCS_CONTRIBUTING.md Normal file
View File

@@ -0,0 +1,150 @@
---
id: meta-docs-contributing
title: "Docs Contributing Guide"
slug: /meta/docs-contributing
description: "Specific guide for contributing to BlackRoad OS documentation"
tags: ["meta", "contributing", "documentation"]
status: stable
---
# Docs Contributing Guide
> 📚 This is the detailed contributing guide specifically for the `blackroad-os-docs` repository.
For general contribution guidelines across all BlackRoad OS repositories, see the [main Contributing Guide](guides/contributing.md).
## Documentation Structure
See the [System Prompt](meta/SYSTEM_PROMPT.md) for the complete philosophy and structure of BlackRoad OS documentation.
## Quick Reference
### Adding New Documentation
1. **Choose the right location:**
- `docs/overview/` - Architecture and high-level concepts
- `docs/services/` - Service-specific documentation
- `docs/agents/` - Agent ecosystem
- `docs/guides/` - How-to guides
- `docs/runbooks/` - Operational procedures
- `docs/reference/` - API and technical reference
- `docs/ops/` - Operations documentation
- `docs/meta/` - Documentation about documentation
2. **Create the file:**
```bash
# Use kebab-case for filenames
touch docs/guides/my-new-guide.md
```
3. **Add frontmatter:**
```yaml
---
id: guides-my-new-guide
title: "My New Guide"
slug: /guides/my-new-guide
description: "Brief description"
tags: ["guides", "topic"]
status: stable # or alpha, planned, deprecated
---
```
4. **Update sidebar:**
Edit `sidebars.ts` to add your new page to navigation.
5. **Build and verify:**
```bash
npm run build
```
## Writing Standards
Follow the [Style Guide](meta/STYLE_GUIDE.md) for:
- Markdown conventions
- Heading hierarchy
- Code block formatting
- Link formatting
- Diagram creation
## What NOT to Commit
Never commit:
- Binary images (PNG, JPEG, GIF, etc.)
- Secrets or credentials
- Large files
- Build artifacts
- IDE-specific files
See `.gitignore` for the complete list.
## Testing Documentation Changes
### Local Development
```bash
npm run start
# Visit http://localhost:3000
```
### Production Build
```bash
npm run build
npm run serve
# Visit http://localhost:3000
```
### Check for Broken Links
The build process will fail if there are broken links. Fix them before submitting.
## Pull Request Process
1. Create a feature branch
2. Make your documentation changes
3. Test locally with `npm run build`
4. Update sidebar if adding new pages
5. Create PR with clear description
6. Request review
## Documentation Types
Refer to the [Style Guide](meta/STYLE_GUIDE.md) for templates and conventions for:
- Architecture Docs
- Service Docs
- Runbooks
- How-To Guides
- Reference Docs
## Cross-Linking
Use relative links for internal documentation:
```md
See [Service API](../services/service-api.md)
See [Agent Ecosystem](../agents/agent-ecosystem.md)
```
## Marking Planned Content
For planned but not yet written content:
```md
> 📋 **Status:** This document is planned and will be developed.
```
Or mark links as planned:
```md
See [Future Guide](./future-guide.md) _(planned)_
```
## Questions?
- Check the [System Prompt](meta/SYSTEM_PROMPT.md)
- Review the [Style Guide](meta/STYLE_GUIDE.md)
- Look at existing docs for examples
- Open an issue for clarification
## See Also
- [System Prompt](meta/SYSTEM_PROMPT.md) - Documentation philosophy
- [Style Guide](meta/STYLE_GUIDE.md) - Writing standards
- [Contributing Guide](guides/contributing.md) - General contribution guide
- [CONTRIBUTING.md](https://github.com/BlackRoad-OS/blackroad-os-docs/blob/main/CONTRIBUTING.md) - Quick reference in root

517
docs/meta/STYLE_GUIDE.md Normal file
View File

@@ -0,0 +1,517 @@
---
id: meta-style-guide
title: "✍️ BlackRoad OS Docs Style Guide"
slug: /meta/style-guide
---
# ✍️ BlackRoad OS Docs Style Guide
This guide ensures consistency across all BlackRoad OS documentation, making it easier for both humans and agents to read, understand, and contribute.
---
## Document Structure
### Frontmatter
All Markdown files should include frontmatter with these fields:
```yaml
---
id: meta-style-guide # kebab-case, unique within docs
title: "BlackRoad OS Style Guide" # Human-readable title
slug: /meta/style-guide # URL path
description: "Style conventions for BlackRoad OS documentation" # Optional but recommended
tags: ["meta", "contributing"] # Optional, for categorization
status: stable # Optional: stable, alpha, planned, deprecated
---
```
### Heading Hierarchy
Use headings in logical order:
```md
# H1 - Document Title (auto-generated from frontmatter title, use sparingly)
## H2 - Major Sections
### H3 - Subsections
#### H4 - Fine-grained details
```
**Rules:**
- Only one H1 per document (usually auto-generated from frontmatter)
- Don't skip heading levels (e.g., H2 → H4)
- Use sentence case for headings: "Getting started" not "Getting Started"
---
## Writing Style
### Tone
- **Clear and direct** - Get to the point quickly
- **Friendly but professional** - Use emojis sparingly and only where they add clarity
- **Assume intelligence** - Don't over-explain, but do provide context
- **Action-oriented** - Use active voice and imperative mood for instructions
### Examples
✅ **Good:**
```md
Configure the API endpoint by setting the `API_URL` environment variable.
```
❌ **Avoid:**
```md
The API endpoint can be configured by you if you set the environment variable that is called `API_URL`.
```
### Terminology
Use consistent terminology across all docs:
| **Preferred** | **Avoid** |
|--------------|-----------|
| BlackRoad OS | Blackroad, blackroad, BR |
| Prism Console | Prism, Console, Dashboard |
| Operator | Worker, Runner |
| Pack | Plugin, Extension, Module |
| Service | Microservice, App |
Refer to the [Glossary](./GLOSSARY.md) for canonical definitions.
---
## Formatting
### Code Blocks
Always specify the language for syntax highlighting:
````md
```typescript
const config = {
apiUrl: process.env.API_URL
};
```
````
For shell commands, use `bash` or `sh`:
````md
```bash
npm install
npm run build
```
````
### Inline Code
Use backticks for:
- File names: `package.json`
- Environment variables: `API_URL`
- Code snippets: `const x = 42;`
- Commands: `npm install`
### Lists
**Unordered lists** for items without sequence:
```md
- First item
- Second item
- Third item
```
**Ordered lists** for sequential steps:
```md
1. Clone the repository
2. Install dependencies
3. Run the build
```
**Nested lists** should indent with 2 spaces:
```md
- Parent item
- Child item
- Another child
- Another parent
```
---
## Links
### Internal Links
Use **relative links** for internal documentation:
```md
See [Getting Started](guides/getting-started-local.md) for setup instructions.
```
For cross-references within the same directory:
```md
Refer to [Service API](./service-api.md) for details.
```
### External Links
Include descriptive text for external links:
✅ **Good:**
```md
Deploy using [Railway](https://railway.app)
```
❌ **Avoid:**
```md
Click [here](https://railway.app) to deploy
```
### Repository Links
Link to specific repos using full GitHub URLs:
```md
The API lives in [blackroad-os-api](https://github.com/BlackRoad-OS/blackroad-os-api)
```
---
## Diagrams
### Mermaid Diagrams
Prefer Mermaid for diagrams - they're text-based, versionable, and render nicely:
````md
```mermaid
flowchart TD
A[User Request] --> B{API Gateway}
B --> C[Core Service]
B --> D[Operator]
D --> E[Job Queue]
```
````
### ASCII Diagrams
For simple diagrams, ASCII art works well:
```
┌──────────┐ ┌──────────┐
│ API │─────▶│ Operator │
└──────────┘ └──────────┘
│ │
▼ ▼
┌──────────┐ ┌──────────┐
│ Core │ │ Packs │
└──────────┘ └──────────┘
```
### No Binary Images
**Never commit binary images** (PNG, JPEG, etc.). Instead:
- Use Mermaid or ASCII diagrams
- Link to external, publicly accessible diagrams if absolutely necessary
- Use SVG sparingly (must be text-based SVG, not exported from design tools)
---
## Document Types
### Architecture Docs
**Purpose:** Explain system design and component relationships
**Structure:**
```md
## Overview
Brief introduction to the component or system.
## Components
Description of major parts and their responsibilities.
## Data Flow
How information moves through the system.
## Related Topics
- Links to relevant guides
- Links to API references
```
**Example:** `docs/overview/architecture-map.md`
---
### Service Docs
**Purpose:** Document individual services in the BlackRoad OS ecosystem
**Structure:**
```md
## What it does
High-level purpose and responsibilities.
## Repository
Link to GitHub repo.
## Key Features
- Feature 1
- Feature 2
## Deployment
How this service is deployed (link to infra docs).
## Health Checks
Expected endpoints: /health, /ready, /version
## Related Services
Links to other services this one interacts with.
```
**Example:** `docs/services/service-api.md`
---
### Runbooks
**Purpose:** Step-by-step operational procedures
**Structure:**
```md
## When to Use
Describe the scenario requiring this runbook.
## Prerequisites
Required access, tools, or knowledge.
## Steps
1. First action with expected outcome
2. Second action with verification step
3. Continue until complete
## Verification
How to confirm success.
## Rollback
What to do if something goes wrong.
```
**Example:** `docs/runbooks/deploy-api.md`
---
### How-To Guides
**Purpose:** Task-oriented tutorials for achieving specific goals
**Structure:**
```md
## Goal
What you'll accomplish.
## Prerequisites
- Required tools
- Required knowledge
## Steps
1. First step
2. Second step
3. Final step
## Verification
How to verify it worked.
## Next Steps
What to do next or related guides.
```
**Example:** `docs/guides/getting-started-local.md`
---
### Reference Docs
**Purpose:** Exhaustive technical details (API, CLI, configuration)
**Structure:**
```md
## Overview
Brief introduction.
## [Feature/Endpoint Name]
### Description
What it does.
### Parameters
| Name | Type | Required | Description |
|------|------|----------|-------------|
| param1 | string | yes | Description |
### Examples
Code examples showing usage.
### Error Codes
Common errors and solutions.
```
**Example:** `docs/reference/api-surface.md`
---
## Special Elements
### Callouts
Use blockquotes for important notes:
```md
> ⚠️ **Warning:** This will delete all data. Make sure you have backups.
> ℹ️ **Note:** This feature is experimental and may change.
> ✅ **Tip:** Use the `--dry-run` flag to preview changes.
```
### Tables
Use tables for structured data:
```md
| Service | Repository | Status |
|---------|------------|--------|
| API | blackroad-os-api | ✅ Active |
| Operator | blackroad-os-operator | ✅ Active |
| Web | blackroad-os-web | 🚧 In Development |
```
### Status Badges
Use consistent status indicators:
- ✅ Stable / Active
- 🚧 In Development / Alpha
- 📋 Planned
- ⚠️ Deprecated
- ❌ Removed
---
## File Naming
### Convention
Use kebab-case for all file names:
✅ **Good:**
- `getting-started-local.md`
- `service-api.md`
- `deploy-to-railway.md`
❌ **Avoid:**
- `Getting Started Local.md`
- `service_api.md`
- `DeployToRailway.md`
### Service Docs
Prefix service documentation with `service-`:
- `service-api.md`
- `service-operator.md`
- `service-core.md`
### Runbooks
Keep runbook names action-oriented:
- `deploy-api.md`
- `rollback-operator.md`
- `debug-prism-console.md`
---
## Version Control
### Commit Messages
Use clear, descriptive commit messages:
✅ **Good:**
```
Add runbook for API deployment
Update service-operator.md with health check info
Fix broken links in getting-started guide
```
❌ **Avoid:**
```
Update docs
Fix stuff
WIP
```
### Pull Requests
- Keep PRs focused on a single topic or change
- Link to related issues or discussions
- Update the sidebar if adding new pages
- Run `npm run build` before submitting
---
## Accessibility
- Use descriptive link text (not "click here")
- Provide alt text for any visual elements
- Ensure code examples can be copied easily
- Use proper heading hierarchy for screen readers
---
## Common Mistakes to Avoid
❌ **Don't:**
- Include secrets, tokens, or credentials
- Commit binary images or large files
- Use absolute URLs for internal links
- Write in first person ("I think", "We did")
- Use time-bound references ("Yesterday", "Last week")
- Duplicate content across multiple pages
✅ **Do:**
- Use environment variable names, not values
- Keep documentation DRY (Don't Repeat Yourself)
- Link to authoritative sources
- Write in present tense
- Update related pages when making changes
- Cross-reference related documentation
---
## Review Checklist
Before submitting documentation changes:
- [ ] Frontmatter is complete and correct
- [ ] Headings follow proper hierarchy
- [ ] Code blocks specify language
- [ ] Internal links are relative
- [ ] No secrets or sensitive data
- [ ] Spelling and grammar checked
- [ ] `npm run build` passes
- [ ] Sidebar updated if needed
- [ ] Related docs cross-linked
---
## Questions?
For questions or suggestions about this style guide:
- Open an issue in [blackroad-os-docs](https://github.com/BlackRoad-OS/blackroad-os-docs)
- Refer to [DOCS_CONTRIBUTING.md](meta/DOCS_CONTRIBUTING.md)
- Check the [Glossary](meta/GLOSSARY.md) for terminology

315
docs/meta/SYSTEM_PROMPT.md Normal file
View File

@@ -0,0 +1,315 @@
---
id: meta-system-prompt
title: "📚 System Prompt for blackroad-os-docs ✨"
slug: /meta/system-prompt
---
# 📚 System Prompt for `blackroad-os-docs` ✨
You are an AI documentation engineer working **inside this repository**: `blackroad-os-docs` in the BlackRoad OS ecosystem. 🖤🌌
Your mission:
- Be the **single source of truth** for BlackRoad OS docs 🧠
- Capture **architecture, concepts, services, agents, runbooks, and how-tos** 🧩
- Make it easy for **10,000 agents + 1 human** to understand and extend the system 🤖👤
- Keep everything **clean, consistent, searchable, and safe** (no secrets, no binaries) 🔐
You operate **only in this repo**.
You **describe** the system; you do **not** replace code or infra in other repos. 🧭
---
## 1️⃣ Purpose & Scope 🎯
`blackroad-os-docs` is the **knowledge base** for the entire BlackRoad OS universe:
- 🏛️ High-level architecture (how all the repos fit together)
- 🔌 Service docs (API, Operator, Core, Web, Prism, Packs, Infra, etc.)
- 🧪 Research & theory summaries (with pointers to `blackroad-os-research`)
- 📖 How-to guides and tutorials (for humans + agents)
- 🛟 Runbooks & playbooks (deploy, debug, oncall, incident)
It is **NOT**:
- A scratchpad for random notes that never get cleaned up 😵‍💫
- A place to store secrets, logs, or raw data dumps 🔥
- A repository for binary assets (images, PDFs, videos) 🧱
Think: **BlackRoad OS Handbook + Codex** 📖✨
---
## 2️⃣ Recommended Layout 📁
You should maintain a **clear, predictable structure** like:
- `docs/`
- `overview/`
- `blackroad-os-overview.md`
- `architecture-map.md`
- `services/`
- `service-core.md`
- `service-api.md`
- `service-operator.md`
- `service-web.md`
- `service-prism-console.md`
- `service-<pack-name>.md`
- `infra/`
- `environments.md`
- `deploy-pipeline.md`
- `cloudflare-routing.md`
- `agents/`
- `agent-ecosystem.md`
- `agent-identity-and-memory.md`
- `runbooks/`
- `deploy-api.md`
- `debug-operator.md`
- `incident-playbook.md`
- `guides/`
- `getting-started-local.md`
- `contributing.md`
- `coding-standards.md`
- `reference/`
- `api-surface.md`
- `endpoint-conventions.md`
- `meta/`
- `DOCS_CONTRIBUTING.md`
- `STYLE_GUIDE.md`
You must **respect** whatever structure already exists and extend it in a consistent way 🧱
---
## 3️⃣ Document Types 🧾
You should write and maintain docs in a few clear categories:
### 🏛️ Architecture Docs
- Describe:
- Major components (Core, API, Operator, Web, Prism, Infra, Packs)
- How they talk to each other (calls, events, jobs)
- Environment story (local vs staging vs prod)
- Include simple diagrams **as text** (Mermaid, ASCII), not binary images.
Example file: `docs/overview/architecture-map.md`
---
### 🔌 Service Docs (Per Repo)
One doc per major service, e.g.:
- `docs/services/service-api.md`
- `docs/services/service-operator.md`
- `docs/services/service-web.md`
- `docs/services/service-prism-console.md`
- `docs/services/service-infra.md`
- `docs/services/service-pack-education.md` etc.
Each service doc should cover:
- What the service **does**
- What repo it lives in (GitHub path)
- Key endpoints / responsibilities
- How it's deployed (pointer to infra docs)
- Health/ready/version expectations
---
### 🧪 Theory / Research Summaries
If there is deep math / SIG / QLM / Lucidia theory in `blackroad-os-research`:
- Summarize the **concepts** here, with links back to research repo
- Keep it:
- High-level
- Non-symbol-spammy
- Friendly to future agents & humans 🧠✨
Example: `docs/overview/spiral-information-geometry.md`
---
### 🛟 Runbooks & Playbooks
Under `docs/runbooks/`, define **do-this-now** style documents:
- `deploy-api.md` – how to safely deploy `blackroad-os-api`
- `rollback-api.md` – how to roll back if something breaks
- `debug-operator.md` – how to inspect jobs, logs, stuck workflows
- `incident-playbook.md` – who/what/when during outages
Runbooks should be:
- Step-by-step ✅
- Short, numbered lists 🔢
- Explicit about **commands, dashboards, and expected outcomes** 🔍
---
### 👣 How-To Guides
Under `docs/guides/`:
- `getting-started-local.md` – clone, install, run basic services
- `adding-a-new-service.md` – how to wire a new service into:
- GitHub
- Infra
- Docs
- Service registry
- `creating-a-new-pack.md` – how to boot a new Pack repo + docs
Guides should be:
- Narrative + steps (what → why → how)
- Safe to follow by new contributors and agents 🧑‍💻🤖
---
## 4️⃣ Markdown Conventions ✍️
You primarily write **Markdown** (`.md` / `.mdx` if supported).
### Frontmatter (if supported)
If the doc site uses frontmatter (Docusaurus/Next/etc.), use:
```md
---
title: "BlackRoad OS – Architecture Overview"
description: "High-level view of all BlackRoad OS services and how they interact."
tags: ["architecture", "overview", "blackroad-os"]
---
# BlackRoad OS – Architecture Overview
```
If frontmatter is not present in existing docs, **match existing style** instead of inventing new patterns.
### Style Guidelines
* Use `#` → `####` headings in a logical hierarchy
* Use bullet lists, numbered lists, and short paragraphs
* Prefer **examples** and **snippets** over walls of text
* Avoid super personal or time-bound notes like "Yesterday I tried X" 🕰️
---
## 5️⃣ Cross-Linking 🕸️
Docs should **link to each other** so agents can walk the graph:
* From `service-api.md` → link to:
* `service-operator.md`
* `endpoint-conventions.md`
* Relevant runbooks
* From infra docs → link to:
* `blackroad-os-infra` repo
* Service docs that use those configs
Use **relative links** when possible so docs work both locally and in static sites.
Example:
```md
See [Service – Operator](./service-operator.md) for details on job orchestration.
```
---
## 6️⃣ Safety & Secrets 🔐🚫
You must **never** include secrets in docs:
* No API keys
* No passwords
* No raw connection strings
* No JWTs, tokens, or private URLs with signed params
You may include:
* **Names** of env vars
* **Patterns** (e.g. `postgres://USER:PASS@HOST:5432/dbname` but not real values)
* Instructions on where to configure secrets (Railway, GitHub Actions, Cloudflare, etc.)
If you see something that **looks** like a secret, add a note like:
> ⚠️ TODO: This looks like a secret; move to provider secrets and rotate credentials.
---
## 7️⃣ Binary Assets & Diagrams 🧩
Policy:
* ❌ Don't commit large images, PDFs, videos, or design source files
* ✅ Use:
* Mermaid diagrams in Markdown
* Simple ASCII diagrams
* Links to external, access-controlled resources if really needed
Example Mermaid snippet:
````md
```mermaid
flowchart LR
Web --> API
API --> Operator
Operator --> Packs
API --> Core
```
````
(escape backticks correctly in real files 😅)
---
## 8️⃣ Tooling & Builds 🛠️
If this repo powers a doc site (e.g., Docusaurus / Next / custom):
- Follow existing `README` / scripts
- Keep docs **buildable**:
- `npm run build`
- or `npm run docs`
- or relevant command
You must:
- Avoid breaking links or navigation sidebars if they are configured (e.g. `sidebars.js`)
- Keep slugs stable where possible (changing URLs is a big deal) 🚦
---
## 9️⃣ Coding Style (For Any Scripts) 🧑‍💻
If there are small helper scripts (link checkers, generators, etc.):
- Keep them **tiny and focused**
- Use TypeScript or Python with type hints, matching existing stack
- Avoid hitting external networks unless clearly intended (and documented)
Example scripts:
- `scripts/check-links.ts`
- `scripts/generate-service-docs.ts`
---
## 🔟 Pre-Commit Checklist ✅
Before finalizing changes in `blackroad-os-docs`, confirm:
1. 📄 All new/edited files are **Markdown or small text config**, not binaries.
2. 🧱 New docs are placed under the correct folder (`overview`, `services`, `runbooks`, `guides`, `infra`, etc.).
3. 🔗 Internal links between docs are valid and use correct relative paths.
4. 🔐 No secrets or sensitive personal data have been added.
5. 📚 Sections have clear headings and are easy to skim.
6. 🧪 If there's a docs build or linter, it still passes.
You are optimizing for:
- 🧠 A **coherent, readable mind** for BlackRoad OS
- 🧵 Smooth **narrative threads** tying infra, code, and agents together
- 🤖 Docs that **agents and humans** can both use as their map of the world 🌍✨

99
docs/reference/api-surface.md Normal file
View File

@@ -0,0 +1,99 @@
---
id: reference-api-surface
title: "API Reference"
slug: /reference/api-surface
description: "Complete API reference for BlackRoad OS"
tags: ["reference", "api"]
status: planned
---
# API Reference
> 🚧 **Status:** This is a planned document. Detailed API reference is being developed.
Complete API reference documentation for BlackRoad OS services.
## Overview
This page will provide comprehensive API documentation including:
- Authentication and authorization
- Endpoint specifications
- Request/response schemas
- Error codes and handling
- Rate limiting
- Webhooks and events
## Planned Sections
### Authentication
- PS-SHA∞ identity verification
- JWT token authentication
- API key authentication
- OAuth integration (if supported)
### Core Endpoints
#### Agents
- `GET /api/v1/agents` - List agents
- `POST /api/v1/agents` - Create agent
- `GET /api/v1/agents/:id` - Get agent
- `PATCH /api/v1/agents/:id` - Update agent
- `DELETE /api/v1/agents/:id` - Delete agent
#### Jobs
- `GET /api/v1/jobs` - List jobs
- `POST /api/v1/jobs` - Submit job
- `GET /api/v1/jobs/:id` - Get job status
- `DELETE /api/v1/jobs/:id` - Cancel job
#### Events
- `GET /api/v1/events` - List events
- `POST /api/v1/events/subscribe` - Subscribe to events
- `DELETE /api/v1/events/unsubscribe` - Unsubscribe
### Error Codes
Standard HTTP status codes plus BlackRoad-specific error codes.
### Rate Limiting
API rate limits and quotas.
### Webhooks
Webhook configuration and event types.
## Current Resources
For now, please refer to:
- [API Overview](dev/API_OVERVIEW.md) - High-level API concepts
- [Service: API](services/service-api.md) - API service documentation
- [Core Primitives](dev/CORE_PRIMITIVES.md) - Data models
## OpenAPI Specification
> 📋 **Coming Soon:** OpenAPI/Swagger specification will be published.
## SDKs and Client Libraries
> 📋 **Coming Soon:** Official client libraries for various languages.
## Contributing
To help build this API reference:
1. Review existing API endpoints in the codebase
2. Document request/response formats
3. Add examples and error cases
4. Submit PR to update this document
See [Contributing Guide](guides/contributing.md).
## See Also
- [Service: API](services/service-api.md)
- [Core Primitives](dev/CORE_PRIMITIVES.md)
- [Events and RoadChain](dev/EVENTS_AND_ROADCHAIN.md)

28
docs/runbooks/debug-operator.md Normal file
View File

@@ -0,0 +1,28 @@
---
id: runbooks-debug-operator
title: "Debug Operator Service"
slug: /runbooks/debug-operator
description: "Runbook for debugging the Operator service"
tags: ["runbooks", "debugging", "operator"]
status: planned
---
# Debug Operator Service
> 📋 **Status:** This runbook is planned and will be developed.
Procedures for debugging issues with the BlackRoad OS Operator service.
## Planned Content
This runbook will include:
- Common symptoms and causes
- Log analysis procedures
- Queue inspection commands
- Worker debugging
- Performance troubleshooting
## See Also
- [Service: Operator](services/service-operator.md)
- [Incident Playbook](./incident-playbook.md)

47
docs/runbooks/deploy-api.md Normal file
View File

@@ -0,0 +1,47 @@
---
id: runbooks-deploy-api
title: "Deploy API Service"
slug: /runbooks/deploy-api
description: "Runbook for deploying the BlackRoad OS API service"
tags: ["runbooks", "deployment", "api"]
status: planned
---
# Deploy API Service
> 📋 **Status:** This runbook is planned and will be developed.
Step-by-step procedures for deploying the BlackRoad OS API service.
## Planned Content
This runbook will include:
- Pre-deployment checklist
- Deployment steps for Railway
- Environment variable verification
- Health check validation
- Rollback procedures
- Post-deployment verification
## Current Deployment
Currently, API deployment is handled via:
- Railway automatic deployments from main branch
- Manual deployments via Railway dashboard
## Quick Reference
### Deploy via Railway Dashboard
1. Go to Railway project
2. Select `blackroad-os-api` service
3. Navigate to Deployments tab
4. Click "Deploy Latest"
### Environment Variables
See [Service: API](services/service-api.md) for required environment variables.
## See Also
- [Service: API](services/service-api.md)
- [Infra Guide](ops/INFRA_GUIDE.md)
- [Incident Playbook](./incident-playbook.md)

36
docs/runbooks/deploy-operator.md Normal file
View File

@@ -0,0 +1,36 @@
---
id: runbooks-deploy-operator
title: "Deploy Operator Service"
slug: /runbooks/deploy-operator
description: "Runbook for deploying the BlackRoad OS Operator service"
tags: ["runbooks", "deployment", "operator"]
status: planned
---
# Deploy Operator Service
> 📋 **Status:** This runbook is planned and will be developed.
Step-by-step procedures for deploying the BlackRoad OS Operator service.
## Planned Content
This runbook will include:
- Pre-deployment checklist
- Deployment steps for Railway
- Worker scaling considerations
- Queue migration procedures
- Health check validation
- Rollback procedures
## Current Deployment
Currently, Operator deployment is handled via:
- Railway automatic deployments from main branch
- Manual deployments via Railway dashboard
## See Also
- [Service: Operator](services/service-operator.md)
- [Operator Runtime](ops/OPERATOR_RUNTIME.md)
- [Incident Playbook](./incident-playbook.md)

28
docs/runbooks/deploy-prism.md Normal file
View File

@@ -0,0 +1,28 @@
---
id: runbooks-deploy-prism
title: "Deploy Prism Console"
slug: /runbooks/deploy-prism
description: "Runbook for deploying the Prism Console"
tags: ["runbooks", "deployment", "prism"]
status: planned
---
# Deploy Prism Console
> 📋 **Status:** This runbook is planned and will be developed.
Step-by-step procedures for deploying the Prism Console.
## Planned Content
This runbook will include:
- Pre-deployment checklist
- Deployment steps
- Configuration verification
- Access control setup
- Health check validation
## See Also
- [Service: Prism Console](services/service-prism-console.md)
- [Prism Console Guide](ops/PRISM_CONSOLE.md)

29
docs/runbooks/deploy-web.md Normal file
View File

@@ -0,0 +1,29 @@
---
id: runbooks-deploy-web
title: "Deploy Web Service"
slug: /runbooks/deploy-web
description: "Runbook for deploying the BlackRoad OS Web service"
tags: ["runbooks", "deployment", "web"]
status: planned
---
# Deploy Web Service
> 📋 **Status:** This runbook is planned and will be developed.
Step-by-step procedures for deploying the BlackRoad OS Web service.
## Planned Content
This runbook will include:
- Pre-deployment checklist
- Deployment steps for Vercel/Railway
- Build verification
- CDN cache invalidation
- Health check validation
- Rollback procedures
## See Also
- [Service: Web](services/service-web.md)
- [Incident Playbook](./incident-playbook.md)

337
docs/runbooks/incident-playbook.md Normal file
View File

@@ -0,0 +1,337 @@
---
id: runbooks-incident-playbook
title: "Incident Response Playbook"
slug: /runbooks/incident-playbook
description: "Step-by-step incident response procedures"
tags: ["runbooks", "incidents", "operations"]
status: stable
---
# Incident Response Playbook
This playbook provides step-by-step procedures for responding to incidents in BlackRoad OS.
## Severity Levels
| **Level** | **Description** | **Response Time** | **Examples** |
|-----------|-----------------|-------------------|--------------|
| **SEV1** | Critical - System down | < 15 min | Complete outage, data loss |
| **SEV2** | High - Major degradation | < 1 hour | API errors >50%, slow response |
| **SEV3** | Medium - Partial impact | < 4 hours | Single service degraded |
| **SEV4** | Low - Minor issue | < 24 hours | UI glitch, non-critical bug |
## Incident Response Process
### 1. Detection and Alert
**When an incident is detected:**
1. ✅ Acknowledge the alert
2. ✅ Create incident tracking issue/ticket
3. ✅ Determine severity level
4. ✅ Notify relevant stakeholders
**Communication Channels:**
- GitHub Issues: For tracking
- Slack/Discord: For real-time coordination (if available)
- Status page: For user communication
### 2. Initial Assessment
**Gather information (5-10 minutes):**
1. What is broken?
2. Since when?
3. What changed recently?
4. What is the user impact?
5. What services are affected?
**Check:**
- [Prism Console](ops/PRISM_CONSOLE.md) - System health
- Railway logs - Service logs
- GitHub Actions - Recent deployments
### 3. Containment
**For SEV1/SEV2 incidents:**
**Option A: Rollback (if recent deployment)**
```bash
# Via Railway dashboard or CLI
railway rollback --service=api
```
**Option B: Disable Failing Component**
```bash
# Scale down problematic service temporarily
railway scale --service=operator --replicas=0
```
**Option C: Enable Maintenance Mode**
- Return 503 status from API
- Display maintenance page on Web
### 4. Investigation
**Common investigation steps:**
**Check Logs:**
```bash
# Via Railway CLI
railway logs --service=api --tail=100
# Check for errors
railway logs --service=api | grep ERROR
```
**Check Database:**
```sql
-- Check database connection
SELECT 1;
-- Check recent errors
SELECT * FROM error_logs
ORDER BY created_at DESC
LIMIT 100;
```
**Check Job Queue:**
```bash
# Connect to Redis
redis-cli
# Check queue depth
LLEN bullmq:jobs:waiting
LLEN bullmq:jobs:active
LLEN bullmq:jobs:failed
```
**Check Service Health:**
```bash
# Test health endpoints
curl https://api.blackroad.dev/health
curl https://api.blackroad.dev/ready
```
### 5. Resolution
**Apply fix based on investigation:**
**Code Fix:**
1. Create hotfix branch
2. Make minimal fix
3. Test locally
4. Deploy to staging
5. Deploy to production
6. Verify fix
**Configuration Fix:**
```bash
# Update environment variable via Railway
railway variables set KEY=value --service=api
# Restart service
railway restart --service=api
```
**Database Fix:**
```sql
-- Apply migration or data fix
-- Always backup first!
```
**Infrastructure Fix:**
- Adjust scaling
- Modify resource limits
- Update networking config
### 6. Verification
**Confirm resolution:**
1. ✅ Service health checks passing
2. ✅ Error rates back to normal
3. ✅ User reports confirm fix
4. ✅ Metrics show recovery
5. ✅ No new errors in logs
**Monitor for 30+ minutes** to ensure stability.
### 7. Communication
**Update stakeholders:**
1. ✅ Post resolution update
2. ✅ Close incident ticket
3. ✅ Update status page
4. ✅ Thank responders
### 8. Post-Incident Review
**Within 48 hours, document:**
1. **Timeline:** When things happened
2. **Root Cause:** Why it happened
3. **Impact:** Who was affected
4. **Resolution:** How it was fixed
5. **Action Items:** How to prevent recurrence
**Template:**
```md
# Incident Post-Mortem: [YYYY-MM-DD] [Brief Title]
## Summary
Brief overview of what happened.
## Timeline (UTC)
- HH:MM - Incident began
- HH:MM - Alert triggered
- HH:MM - Investigation started
- HH:MM - Fix deployed
- HH:MM - Verified resolved
## Root Cause
Technical explanation of why it happened.
## Impact
- Users affected: X
- Duration: X minutes
- Services impacted: API, Operator
## Resolution
What we did to fix it.
## Action Items
- [ ] Add monitoring for X
- [ ] Improve Y process
- [ ] Document Z
```
## Common Incident Scenarios
### API Service Down
**Symptoms:**
- Health checks failing
- 500 errors
- Connection timeouts
**Quick Checks:**
1. Database connectivity
2. Environment variables
3. Recent deployments
4. Resource limits
**Common Fixes:**
- Restart service
- Rollback deployment
- Scale up resources
- Fix database connection
See [Service: API](services/service-api.md) for details.
---
### Operator Jobs Stuck
**Symptoms:**
- Jobs not processing
- Queue growing
- Workers idle
**Quick Checks:**
1. Redis connectivity
2. Worker processes running
3. Job errors in logs
4. Queue depths
**Common Fixes:**
- Restart Operator service
- Clear failed jobs
- Scale up workers
- Fix job timeouts
See [Service: Operator](services/service-operator.md) for details.
---
### Database Issues
**Symptoms:**
- Query timeouts
- Connection pool exhausted
- Slow responses
**Quick Checks:**
1. Active connections
2. Slow queries
3. Database size
4. Resource usage
**Common Fixes:**
- Restart service connections
- Kill long-running queries
- Increase connection pool
- Optimize slow queries
---
### High Error Rates
**Symptoms:**
- Errors >5% of requests
- Multiple error types
- Degraded performance
**Quick Checks:**
1. Error logs
2. Recent changes
3. External dependencies
4. Resource usage
**Common Fixes:**
- Identify error source
- Fix or rollback code
- Add error handling
- Scale resources
## Escalation
**When to escalate:**
- Incident not resolved in expected time
- Need additional expertise
- SEV1 lasting >1 hour
- Unclear root cause
**Escalation Path:**
1. Team lead / Senior engineer
2. Infrastructure team
3. External support (Railway, etc.)
## Tools and Resources
**Monitoring:**
- [Prism Console](ops/PRISM_CONSOLE.md)
- Railway Dashboard
- Cloudflare Analytics
**Logs:**
- Railway Logs
- Application logs
- Database logs
**Runbooks:**
- [Deploy API](runbooks/deploy-api.md) _(planned)_
- [Debug Operator](runbooks/debug-operator.md) _(planned)_
- [Rollback Procedures](runbooks/rollback-procedures.md) _(planned)_
**Documentation:**
- [Service: API](services/service-api.md)
- [Service: Operator](services/service-operator.md)
- [Infra Guide](ops/INFRA_GUIDE.md)
## See Also
- [Incidents and Incident Response](ops/incidents-and-incident-response.md)
- [Operator Runtime](ops/OPERATOR_RUNTIME.md)
- [Prism Console](ops/PRISM_CONSOLE.md)

29
docs/runbooks/rollback-procedures.md Normal file
View File

@@ -0,0 +1,29 @@
---
id: runbooks-rollback-procedures
title: "Rollback Procedures"
slug: /runbooks/rollback-procedures
description: "General rollback procedures for BlackRoad OS services"
tags: ["runbooks", "rollback", "recovery"]
status: planned
---
# Rollback Procedures
> 📋 **Status:** This runbook is planned and will be developed.
General procedures for rolling back deployments when issues occur.
## Planned Content
This runbook will include:
- When to rollback vs. hotfix
- Railway rollback procedures
- Database migration rollbacks
- Verification after rollback
- Communication procedures
## See Also
- [Incident Playbook](./incident-playbook.md)
- [Service: API](services/service-api.md)
- [Service: Operator](services/service-operator.md)

174
docs/services/service-api.md Normal file
View File

@@ -0,0 +1,174 @@
---
id: services-service-api
title: "Service: API"
slug: /services/service-api
description: "Documentation for the BlackRoad OS API service"
tags: ["services", "api"]
status: stable
---
# Service: API
## What it does
The **BlackRoad OS API** is the primary HTTP gateway for the BlackRoad OS ecosystem. It provides RESTful endpoints for:
- Agent management and orchestration
- Job submission and monitoring
- Identity and authentication via PS-SHA∞
- Event streaming and subscriptions
- Integration with external systems
## Repository
- **GitHub:** [BlackRoad-OS/blackroad-os-api](https://github.com/BlackRoad-OS/blackroad-os-api)
- **Primary Language:** TypeScript (Node.js)
- **Framework:** Express / Fastify
## Key Features
- 🔐 PS-SHA∞ identity authentication
- 🤖 Agent lifecycle management
- 📊 Real-time event streaming
- 🔄 Job queue integration with Operator
- 📝 Comprehensive request/response logging
- ⚡ High-performance async operations
## Architecture
```mermaid
flowchart LR
Client[Client/Web] --> API[API Service]
API --> Core[Core Service]
API --> Operator[Operator Service]
API --> DB[(Database)]
Operator --> Queue[Job Queue]
```
## Deployment
The API service is deployed using:
- **Platform:** Railway
- **Environment Variables:** See `.env.example` in the repository
- **Health Checks:** `/health`, `/ready`, `/version`
For deployment procedures, see:
- [Infra Guide](ops/INFRA_GUIDE.md)
- [Deploy API Runbook](runbooks/deploy-api.md) _(planned)_
## Health Checks
Standard endpoints:
| Endpoint | Purpose | Expected Response |
|----------|---------|-------------------|
| `GET /health` | Basic health check | `200 OK` with `{ status: "healthy" }` |
| `GET /ready` | Readiness check (DB connected) | `200 OK` when ready |
| `GET /version` | Service version info | `200 OK` with version details |
## Key Endpoints
### Authentication
- `POST /auth/login` - User/agent authentication
- `POST /auth/refresh` - Token refresh
- `POST /auth/verify` - Verify PS-SHA∞ signature
### Agents
- `GET /agents` - List agents
- `POST /agents` - Create new agent
- `GET /agents/:id` - Get agent details
- `PATCH /agents/:id` - Update agent
- `DELETE /agents/:id` - Deactivate agent
### Jobs
- `GET /jobs` - List jobs
- `POST /jobs` - Submit new job
- `GET /jobs/:id` - Get job status
- `DELETE /jobs/:id` - Cancel job
For complete API reference, see [API Surface](reference/api-surface.md) _(planned)_.
## Related Services
- [Service: Core](./service-core.md) _(planned)_ - Core domain logic and data models
- [Service: Operator](./service-operator.md) _(planned)_ - Job orchestration and execution
- [Service: Prism Console](./service-prism-console.md) _(planned)_ - Monitoring and observability UI
- [Service: Web](./service-web.md) _(planned)_ - User-facing web application
## Environment Configuration
Key environment variables (see repository for complete list):
- `DATABASE_URL` - PostgreSQL connection string
- `REDIS_URL` - Redis connection for sessions/cache
- `API_PORT` - Port to listen on (default: 3000)
- `JWT_SECRET` - Secret for JWT signing
- `OPERATOR_URL` - URL of Operator service
> ⚠️ **Security:** Never commit actual values. Use Railway secrets or equivalent.
## Development
Local development setup:
```bash
# Clone the repository
git clone https://github.com/BlackRoad-OS/blackroad-os-api.git
cd blackroad-os-api
# Install dependencies
npm install
# Set up environment
cp .env.example .env
# Edit .env with local values
# Run in development mode
npm run dev
```
See [Local Development Guide](dev/local-development.md) for more details.
## Monitoring
- **Logs:** Available via Railway dashboard
- **Metrics:** Prometheus-compatible endpoints (if configured)
- **Tracing:** OpenTelemetry support (if configured)
- **Dashboard:** [Prism Console](ops/PRISM_CONSOLE.md)
## Troubleshooting
Common issues:
### Service won't start
- Check environment variables are set correctly
- Verify database is accessible
- Check logs for connection errors
### Slow response times
- Check database query performance
- Review Redis cache hit rates
- Check Operator service health
### Authentication failures
- Verify JWT_SECRET is consistent across deployments
- Check token expiration settings
- Validate PS-SHA∞ signatures
For incident response, see [Incident Playbook](ops/incidents-and-incident-response.md).
## Contributing
To contribute to the API service:
1. Review [Contributing Guide](guides/contributing.md) _(reference CONTRIBUTING.md)_
2. Follow [Coding Standards](guides/coding-standards.md) _(planned)_
3. Submit PRs to the repository
4. Ensure all tests pass
## See Also
- [API Overview](dev/API_OVERVIEW.md) - High-level API concepts
- [Core Primitives](dev/CORE_PRIMITIVES.md) - Data models and types
- [Events and RoadChain](dev/EVENTS_AND_ROADCHAIN.md) - Event system

148
docs/services/service-core.md Normal file
View File

@@ -0,0 +1,148 @@
---
id: services-service-core
title: "Service: Core"
slug: /services/service-core
description: "Documentation for the BlackRoad OS Core service"
tags: ["services", "core"]
status: stable
---
# Service: Core
## What it does
The **BlackRoad OS Core** is the foundational library and service containing:
- Shared domain models and types
- PS-SHA∞ identity primitives
- Agent data structures
- Common utilities and helpers
- Business logic abstractions
Core is used as a library by other services (API, Operator, Web) to ensure consistency across the ecosystem.
## Repository
- **GitHub:** [BlackRoad-OS/blackroad-os-core](https://github.com/BlackRoad-OS/blackroad-os-core)
- **Primary Language:** TypeScript
- **Type:** Shared library + optional standalone service
## Key Features
- 🧬 Type-safe domain models
- 🔐 PS-SHA∞ identity implementation
- 🤖 Agent primitives and interfaces
- 📦 Exportable as npm package
- ✅ Comprehensive test coverage
## Core Primitives
The Core service defines fundamental types used across BlackRoad OS:
### Agent Types
- `Agent` - Core agent definition
- `AgentIdentity` - PS-SHA∞ identity metadata
- `AgentMemory` - Agent memory and state
### Job Types
- `Job` - Job definition and metadata
- `JobStatus` - Job lifecycle states
- `JobResult` - Job execution results
### Event Types
- `Event` - Event definition
- `EventPayload` - Event data structures
- `EventSubscription` - Event subscription patterns
See [Core Primitives](dev/CORE_PRIMITIVES.md) for detailed documentation.
## Architecture
```mermaid
flowchart TD
Core[Core Library] --> API[API Service]
Core --> Operator[Operator Service]
Core --> Web[Web Service]
Core --> Prism[Prism Console]
Core --> Packs[Pack Services]
```
## Usage as Library
Other services import Core as a dependency:
```typescript
import { Agent, Job, Event } from '@blackroad-os/core';
const agent: Agent = {
id: 'agent-123',
name: 'Documentation Bot',
capabilities: ['documentation', 'code-review']
};
```
## Deployment
Core can be deployed as:
1. **Library:** npm package imported by other services
2. **Service:** Standalone service for centralized logic (optional)
For most deployments, Core is used as a library only.
## Related Services
- [Service: API](./service-api.md) - Uses Core types for API contracts
- [Service: Operator](./service-operator.md) - Uses Core for job definitions
- [Service: Web](./service-web.md) _(planned)_ - Uses Core for client-side types
## Development
Local development:
```bash
# Clone the repository
git clone https://github.com/BlackRoad-OS/blackroad-os-core.git
cd blackroad-os-core
# Install dependencies
npm install
# Run tests
npm test
# Build
npm run build
```
## Testing
Core has comprehensive test coverage:
```bash
# Run all tests
npm test
# Run tests in watch mode
npm run test:watch
# Generate coverage report
npm run test:coverage
```
## Contributing
Core is critical infrastructure. All changes require:
1. Comprehensive tests
2. Type safety
3. Backward compatibility
4. Documentation updates
See [Contributing Guide](guides/contributing.md) _(reference CONTRIBUTING.md)_.
## See Also
- [Core Primitives](dev/CORE_PRIMITIVES.md) - Detailed type documentation
- [API Overview](dev/API_OVERVIEW.md) - How API uses Core types
- [PS-SHA∞ Architecture](../architecture/ps-sha-infinity.md) _(if exists)_

159
docs/services/service-infra.md Normal file
View File

@@ -0,0 +1,159 @@
---
id: services-service-infra
title: "Service: Infrastructure"
slug: /services/service-infra
description: "Documentation for the BlackRoad OS Infrastructure"
tags: ["services", "infrastructure", "devops"]
status: stable
---
# Service: Infrastructure
## What it does
The **BlackRoad OS Infrastructure** repository contains:
- Infrastructure as Code (IaC) configurations
- Deployment pipelines and scripts
- Environment configurations
- Terraform/Pulumi definitions
- CI/CD workflows
This is where the operational backbone of BlackRoad OS is defined and managed.
## Repository
- **GitHub:** [BlackRoad-OS/blackroad-os-infra](https://github.com/BlackRoad-OS/blackroad-os-infra)
- **Tools:** Terraform, GitHub Actions, Railway configs
- **Languages:** HCL, YAML, TypeScript
## Key Components
### Deployment Configurations
- Railway service definitions
- Environment variable templates
- Database migration scripts
- Secret management patterns
### CI/CD Pipelines
- Automated testing workflows
- Deployment automation
- Rollback procedures
- Environment promotion
### Monitoring & Observability
- Logging configuration
- Metrics collection
- Alert definitions
- Dashboard templates
## Architecture
```mermaid
flowchart TD
GitHub[GitHub Actions] --> Build[Build & Test]
Build --> Deploy[Deploy to Railway]
Deploy --> Staging[Staging Env]
Deploy --> Prod[Production Env]
Monitoring[Monitoring] --> Staging
Monitoring --> Prod
```
## Deployment Targets
### Railway
- **API Service:** `blackroad-os-api`
- **Operator Service:** `blackroad-os-operator`
- **Web Service:** `blackroad-os-web`
- **Prism Console:** `blackroad-os-prism-console`
### Cloudflare
- DNS management
- CDN configuration
- Edge routing
See [DNS and Networking](../infra/dns-and-networking.md) for details.
## Environment Management
### Staging
- Isolated testing environment
- Feature preview deployments
- Integration testing
- Performance validation
### Production
- High availability configuration
- Auto-scaling enabled
- Backup and disaster recovery
- Monitoring and alerting
See [Environments Guide](../infra/environments.md) for details.
## Development
Working with infrastructure code:
```bash
# Clone the repository
git clone https://github.com/BlackRoad-OS/blackroad-os-infra.git
cd blackroad-os-infra
# Install dependencies
npm install # or terraform init
# Validate configurations
npm run validate # or terraform validate
# Plan changes
npm run plan # or terraform plan
```
## Deployment Procedures
For step-by-step deployment instructions, see:
- [Deployments and Runbooks](../infra/deployments-and-runbooks.md)
- [Deploy API Runbook](runbooks/deploy-api.md) _(planned)_
- [Deploy Operator Runbook](runbooks/deploy-operator.md) _(planned)_
## Security
### Secret Management
- Use Railway/Vercel environment variables
- Never commit secrets to git
- Rotate secrets regularly
- Use least-privilege access
### Access Control
- GitHub repository protection
- Railway team permissions
- Cloudflare API token scoping
## Monitoring
Infrastructure monitoring includes:
- Service health checks
- Resource utilization
- Deployment success rates
- Rollback frequency
## Related Documentation
- [Infra Guide](ops/INFRA_GUIDE.md) - Operational guide
- [Environments](../infra/environments.md) - Environment details
- [DNS and Networking](../infra/dns-and-networking.md) - Network configuration
## Contributing
Infrastructure changes require:
1. Review by infrastructure team
2. Testing in staging environment
3. Validation of no downtime impact
4. Documentation updates
See [Contributing Guide](guides/contributing.md) _(reference CONTRIBUTING.md)_.
## See Also
- [Stack Map](../overview/STACK_MAP.md) - Complete system overview
- [Incident Response](ops/incidents-and-incident-response.md) - Incident handling

219
docs/services/service-operator.md Normal file
View File

@@ -0,0 +1,219 @@
---
id: services-service-operator
title: "Service: Operator"
slug: /services/service-operator
description: "Documentation for the BlackRoad OS Operator service"
tags: ["services", "operator", "jobs"]
status: stable
---
# Service: Operator
## What it does
The **BlackRoad OS Operator** is the job orchestration and execution engine. It manages:
- Asynchronous job processing
- Agent task execution
- Workflow orchestration
- Queue management
- Retry logic and error handling
The Operator is the backbone of BlackRoad OS automation, turning high-level requests from the API into executed work.
## Repository
- **GitHub:** [BlackRoad-OS/blackroad-os-operator](https://github.com/BlackRoad-OS/blackroad-os-operator)
- **Primary Language:** TypeScript (Node.js)
- **Queue System:** BullMQ / Redis
## Key Features
- 📋 Job queue management with BullMQ
- 🔄 Automatic retry with exponential backoff
- 🎯 Priority-based job scheduling
- 🔐 Secure job execution contexts
- 📊 Real-time job status updates
- 🧠 Agent memory and state management
## Architecture
```mermaid
flowchart TD
API[API Service] -->|Submit Job| Operator[Operator Service]
Operator --> Queue[(Redis Queue)]
Queue --> Worker1[Worker 1]
Queue --> Worker2[Worker 2]
Queue --> WorkerN[Worker N]
Worker1 --> Packs[Pack Executors]
Worker2 --> Packs
WorkerN --> Packs
Packs --> Results[Job Results]
Results --> DB[(Database)]
```
## Deployment
The Operator service is deployed using:
- **Platform:** Railway
- **Scaling:** Horizontal scaling via worker processes
- **Environment Variables:** See `.env.example` in repository
- **Health Checks:** `/health`, `/ready`, `/queue-status`
For deployment procedures, see:
- [Operator Runtime Guide](ops/OPERATOR_RUNTIME.md)
- [Deploy Operator Runbook](runbooks/deploy-operator.md) _(planned)_
## Health Checks
Standard endpoints:
| Endpoint | Purpose | Expected Response |
|----------|---------|-------------------|
| `GET /health` | Basic health check | `200 OK` |
| `GET /ready` | Readiness check (Redis connected) | `200 OK` when ready |
| `GET /queue-status` | Queue metrics | `200 OK` with queue stats |
| `GET /version` | Service version info | `200 OK` with version |
## Job Types
The Operator handles various job types:
### Agent Execution Jobs
Execute agent logic with specific contexts and memory.
### Workflow Jobs
Multi-step workflows with conditional logic and branching.
### Scheduled Jobs
Cron-style recurring tasks.
### Event-Triggered Jobs
Jobs triggered by system events or webhooks.
## Job Lifecycle
```
Pending → Active → Completed
│ │ ↓
│ └──→ Failed → Retrying
│ ↓
└───────────→ Cancelled
```
1. **Pending:** Job is queued, waiting for worker
2. **Active:** Worker is processing the job
3. **Completed:** Job finished successfully
4. **Failed:** Job encountered an error
5. **Retrying:** Failed job is being retried
6. **Cancelled:** Job was manually cancelled
## Related Services
- [Service: API](./service-api.md) - Submits jobs to Operator
- [Service: Core](./service-core.md) _(planned)_ - Core business logic
- [Service: Prism Console](./service-prism-console.md) _(planned)_ - Job monitoring UI
- **Packs:** Various pack services that execute specific job types
## Environment Configuration
Key environment variables:
- `REDIS_URL` - Redis connection for queue
- `DATABASE_URL` - PostgreSQL for job metadata
- `WORKER_CONCURRENCY` - Number of concurrent jobs per worker
- `JOB_TIMEOUT_MS` - Default job timeout
- `MAX_RETRIES` - Maximum retry attempts
- `RETRY_BACKOFF_MS` - Initial retry delay
> ⚠️ **Security:** Never commit actual values. Use Railway secrets or equivalent.
## Development
Local development setup:
```bash
# Clone the repository
git clone https://github.com/BlackRoad-OS/blackroad-os-operator.git
cd blackroad-os-operator
# Install dependencies
npm install
# Set up environment
cp .env.example .env
# Edit .env with local values
# Start Redis (via Docker)
docker run -d -p 6379:6379 redis:latest
# Run in development mode
npm run dev
```
See [Local Development Guide](dev/local-development.md) for more details.
## Monitoring
- **Queue Dashboard:** BullBoard UI (if enabled)
- **Metrics:** Job completion rates, failure rates, latency
- **Logs:** Structured logging with context
- **Alerts:** Configure alerts for queue depth, failed jobs
- **Prism Console:** [Real-time monitoring](ops/PRISM_CONSOLE.md)
## Performance Tuning
### Worker Concurrency
Adjust `WORKER_CONCURRENCY` based on:
- Available CPU/memory
- Job complexity
- External API rate limits
### Queue Priority
Set job priorities to ensure critical jobs execute first:
- **High:** User-facing operations
- **Normal:** Background tasks
- **Low:** Maintenance, cleanup jobs
### Memory Management
Monitor worker memory usage:
- Restart workers periodically if memory leaks detected
- Use separate queues for memory-intensive jobs
## Troubleshooting
Common issues:
### Jobs stuck in pending
- Check Redis connectivity
- Verify workers are running
- Review worker logs for errors
### High failure rates
- Check job timeout settings
- Review error logs for patterns
- Verify external service availability
### Queue growing indefinitely
- Increase worker count
- Reduce job creation rate
- Identify and fix failing jobs
For debugging procedures, see [Debug Operator Runbook](runbooks/debug-operator.md) _(planned)_.
## Contributing
To contribute to the Operator service:
1. Review [Contributing Guide](guides/contributing.md) _(reference CONTRIBUTING.md)_
2. Follow [Coding Standards](guides/coding-standards.md) _(planned)_
3. Understand job lifecycle and queue patterns
4. Submit PRs with tests
## See Also
- [Operator Runtime](ops/OPERATOR_RUNTIME.md) - Operational guide
- [Core Primitives](dev/CORE_PRIMITIVES.md) - Job data structures
- [Events and RoadChain](dev/EVENTS_AND_ROADCHAIN.md) - Event-driven architecture
- [Agents Atlas](dev/AGENTS_ATLAS_AND_FRIENDS.md) - Agent ecosystem

152
docs/services/service-prism-console.md Normal file
View File

@@ -0,0 +1,152 @@
---
id: services-service-prism-console
title: "Service: Prism Console"
slug: /services/service-prism-console
description: "Documentation for the BlackRoad OS Prism Console"
tags: ["services", "monitoring", "observability"]
status: stable
---
# Service: Prism Console
## What it does
The **Prism Console** is the operational command center for BlackRoad OS, providing:
- Real-time system monitoring
- Job and agent observability
- Performance metrics and dashboards
- Alert management
- System health visualization
Think of it as the "cockpit" for operating BlackRoad OS. 🛸
## Repository
- **GitHub:** [BlackRoad-OS/blackroad-os-prism-console](https://github.com/BlackRoad-OS/blackroad-os-prism-console)
- **Primary Language:** TypeScript (React)
- **Stack:** React + observability libraries
## Key Features
- 📊 Real-time metrics dashboards
- 🔍 Job and agent search/filtering
- 📈 Performance trending
- 🚨 Alert configuration and management
- 🗺️ System topology visualization
- 📝 Log aggregation and search
## Architecture
```mermaid
flowchart TD
Console[Prism Console UI] --> API[API Service]
API --> Metrics[(Metrics DB)]
API --> Logs[(Log Store)]
Console --> WS[WebSocket]
WS --> Events[Real-time Events]
```
## Deployment
The Prism Console is deployed using:
- **Platform:** Vercel / Railway
- **Environment Variables:** See `.env.example` in repository
- **Access:** Protected by authentication
For deployment procedures, see:
- [Prism Console Guide](ops/PRISM_CONSOLE.md)
- [Deploy Prism Runbook](runbooks/deploy-prism.md) _(planned)_
## Key Views
### System Overview
- Cluster health status
- Service availability
- Active agents count
- Job queue depth
### Agent View
- Agent inventory
- Agent status and health
- Agent memory usage
- Recent agent activity
### Job View
- Job queue monitoring
- Job success/failure rates
- Job execution timeline
- Failed job analysis
### Metrics View
- Custom dashboards
- Performance charts
- Resource utilization
- SLA tracking
## Environment Configuration
Key environment variables:
- `VITE_API_URL` or `NEXT_PUBLIC_API_URL` - API service URL
- `VITE_WS_URL` or `NEXT_PUBLIC_WS_URL` - WebSocket URL
- `AUTH_ENABLED` - Enable/disable authentication
> ⚠️ **Security:** Prism Console should always be protected in production.
## Development
Local development:
```bash
# Clone the repository
git clone https://github.com/BlackRoad-OS/blackroad-os-prism-console.git
cd blackroad-os-prism-console
# Install dependencies
npm install
# Set up environment
cp .env.example .env.local
# Edit .env.local
# Run development server
npm run dev
```
## Monitoring Best Practices
### Dashboard Setup
1. Configure key metrics for your use case
2. Set up alerts for critical thresholds
3. Create custom views for different teams
### Alert Configuration
- Job failure rate > 10%
- Queue depth > 1000 jobs
- Agent availability < 95%
- API response time > 2s
## Related Services
- [Service: API](./service-api.md) - Data source
- [Service: Operator](./service-operator.md) - Job monitoring
- [Service: Web](./service-web.md) _(planned)_ - User-facing application
## Troubleshooting
### Console not loading data
- Verify API service is running
- Check network connectivity
- Review browser console for errors
### Real-time updates not working
- Verify WebSocket connection
- Check firewall/proxy settings
- Review WebSocket server logs
## See Also
- [Prism Console Ops Guide](ops/PRISM_CONSOLE.md) - Operational documentation
- [Operator Runtime](ops/OPERATOR_RUNTIME.md) - Job monitoring context

107
docs/services/service-web.md Normal file
View File

@@ -0,0 +1,107 @@
---
id: services-service-web
title: "Service: Web"
slug: /services/service-web
description: "Documentation for the BlackRoad OS Web service"
tags: ["services", "web", "frontend"]
status: alpha
---
# Service: Web
## What it does
The **BlackRoad OS Web** is the user-facing web application providing:
- User interface for BlackRoad OS
- Agent management dashboard
- Job submission and monitoring
- Real-time updates and notifications
- Integration with API service
## Repository
- **GitHub:** [BlackRoad-OS/blackroad-os-web](https://github.com/BlackRoad-OS/blackroad-os-web)
- **Primary Language:** TypeScript (React/Next.js)
- **Framework:** Next.js with App Router
## Key Features
- ⚡ Server-side rendering with Next.js
- 🎨 Modern, responsive UI
- 🔄 Real-time updates via WebSockets
- 🔐 PS-SHA∞ authentication
- 📱 Mobile-friendly design
## Architecture
```mermaid
flowchart LR
User[User Browser] --> Web[Web Service]
Web --> API[API Service]
Web --> WS[WebSocket]
WS --> Events[Event Stream]
```
## Deployment
The Web service is deployed using:
- **Platform:** Vercel / Railway
- **CDN:** Cloudflare (for static assets)
- **Environment Variables:** See `.env.example` in repository
For deployment procedures, see:
- [Infra Guide](ops/INFRA_GUIDE.md)
- [Deploy Web Runbook](runbooks/deploy-web.md) _(planned)_
## Key Routes
- `/` - Home page
- `/dashboard` - User dashboard
- `/agents` - Agent management
- `/jobs` - Job monitoring
- `/settings` - User settings
## Environment Configuration
Key environment variables:
- `NEXT_PUBLIC_API_URL` - API service URL
- `NEXT_PUBLIC_WS_URL` - WebSocket URL
- `AUTH_SECRET` - NextAuth secret
- `DATABASE_URL` - Database for sessions (if applicable)
> ⚠️ **Security:** Never commit actual values. Use Vercel/Railway secrets.
## Development
Local development:
```bash
# Clone the repository
git clone https://github.com/BlackRoad-OS/blackroad-os-web.git
cd blackroad-os-web
# Install dependencies
npm install
# Set up environment
cp .env.example .env.local
# Edit .env.local with local values
# Run development server
npm run dev
```
Visit http://localhost:3000
## Related Services
- [Service: API](./service-api.md) - Backend API
- [Service: Prism Console](./service-prism-console.md) _(planned)_ - Operational dashboard
## See Also
- [Local Development](dev/local-development.md) - Development setup
- [Getting Started](../getting-started.md) - User guide

66
sidebars.ts
View File

@@ -13,6 +13,59 @@ const sidebars: SidebarsConfig = {
'overview/overview-seasons', 'overview/overview-seasons',
], ],
}, },
{
type: 'category',
label: 'Services',
items: [
'services/services-service-api',
'services/services-service-operator',
'services/services-service-core',
'services/services-service-web',
'services/services-service-prism-console',
'services/services-service-infra',
],
},
{
type: 'category',
label: 'Agents',
items: [
'agents/agents-agent-ecosystem',
'agents/agents-agent-identity-and-memory',
'dev/dev-agents-atlas-and-friends',
],
},
{
type: 'category',
label: 'Guides',
items: [
'guides/guides-getting-started-local',
'guides/guides-contributing',
'guides/guides-coding-standards',
],
},
{
type: 'category',
label: 'Runbooks',
items: [
'runbooks/runbooks-incident-playbook',
'runbooks/runbooks-deploy-api',
'runbooks/runbooks-deploy-operator',
'runbooks/runbooks-deploy-web',
'runbooks/runbooks-deploy-prism',
'runbooks/runbooks-debug-operator',
'runbooks/runbooks-rollback-procedures',
],
},
{
type: 'category',
label: 'Reference',
items: [
'reference/reference-api-surface',
'dev/dev-core-primitives',
'dev/dev-api-overview',
'dev/dev-events-and-roadchain',
],
},
{ {
type: 'category', type: 'category',
label: 'Operate the OS', label: 'Operate the OS',
@@ -22,16 +75,6 @@ const sidebars: SidebarsConfig = {
'ops/ops-infra-guide', 'ops/ops-infra-guide',
], ],
}, },
{
type: 'category',
label: 'Build on the OS',
items: [
'dev/dev-core-primitives',
'dev/dev-api-overview',
'dev/dev-agents-atlas-and-friends',
'dev/dev-events-and-roadchain',
],
},
{ {
type: 'category', type: 'category',
label: 'Business & Vision', label: 'Business & Vision',
@@ -44,6 +87,9 @@ const sidebars: SidebarsConfig = {
type: 'category', type: 'category',
label: 'Meta', label: 'Meta',
items: [ items: [
'meta/meta-system-prompt',
'meta/meta-style-guide',
'meta/meta-docs-contributing',
'meta/meta-docs-mega-prompt', 'meta/meta-docs-mega-prompt',
'meta/meta-glossary', 'meta/meta-glossary',
'meta/meta-master-codex-prompt', 'meta/meta-master-codex-prompt',