docs

name	docs
description	Review and maintain documentation across the Syner OS monorepo
user_invocable	true

Documentation Review Skill

You are a documentation reviewer for Syner OS. Your job is to analyze, review, and help maintain documentation across the monorepo following established standards.

When to Use

• User runs /docs to review documentation
• User asks to check if docs are up to date
• User wants to create or update README.md or AGENTS.md files

Documentation Philosophy

Syner OS uses a two-file documentation system:

File	Audience	Purpose
README.md	Humans	Why this exists, how to set it up
AGENTS.md	AI Agents	How to work here, what to use, rules

These files serve different purposes and should NOT duplicate content.

Structure by Level

Apps (apps/*/)

Apps are entry points to the system. Humans need to understand the app's purpose. Agents need to know routes and how to test.

README.md Structure:

# {App Name}

## What is {App Name}?

{Human-friendly, non-technical explanation of why this app exists and what value it provides. 2-3 paragraphs max.}

## Getting Started

### Prerequisites
{What you need before starting}

### Installation
{Step by step setup}

### Development
{How to run locally, ports, commands}

## Learn More

{Links to related docs, OS Protocol, etc.}

AGENTS.md Structure:

# {App Name}

{One-line: what this app does in the Syner OS system}

## Routes

| Path | Method | Description |
|------|--------|-------------|
| `/api/v1/...` | POST | ... |

## Structure

{Brief explanation of folder organization if non-obvious}

## Testing

```bash
curl -s -X POST http://localhost:{port}/api/... \
  -H "Content-Type: application/json" \
  -d '{}' | jq .

Environment

{Required env vars for this app, if any}

---

### Packages (`packages/*/`)

Packages are building blocks. Humans need to understand what it exports and how to use it. Agents need architecture, exports, and rules.

**README.md Structure:**
```markdown
# {Package Name}

## What is {Package Name}?

{Human-friendly explanation of what this package does and why it exists. Connect it to the larger Syner OS vision.}

## Installation

```bash
bun add {package-name}

Usage

{Basic usage examples}

API

{Public API reference - can link to more detailed docs}

Related

• OS Protocol - {if applicable}
• {Other relevant links}

**AGENTS.md Structure:**
```markdown
# {Package Name}

{One-line: what this package implements or provides}

## Architecture

{Diagram or explanation of internal structure}

## Exports

```typescript
// Main entry
import { ... } from '{package-name}'

// Subpath exports
import { ... } from '{package-name}/subpath'

Key Concepts

{Important abstractions or patterns to understand}

Rules

MUST:

• {Required behaviors}

NEVER:

• {Prohibited behaviors}

SHOULD:

• {Recommended behaviors}

---

### Extensions (`extensions/*/`)

Extensions are vendor integrations that provide tools for Syner OS agents. Humans need to understand what vendor capability is available. Agents need quick usage and key files.

**README.md Structure:**
```markdown
# @syner/{vendor}

{Vendor} integration for Syner OS.

## What is this?

{Human-friendly explanation: This extension brings {Vendor}'s {capability} into Syner OS as tools that agents can use. Explain the VALUE - what can agents do with this?}

## Available Tools

| Tool | Description |
|------|-------------|
| `{toolName}()` | {What it does} |

## Setup

### 1. {Vendor} Account
{How to get credentials from the vendor}

### 2. Environment Variables
```env
{VENDOR}_API_KEY=...

3. Installation

bun add @syner/{vendor}

API Reference

{Detailed API documentation}

License

MIT

**AGENTS.md Structure:**
```markdown
# @syner/{vendor}

{One-line: what interface from OS Protocol this implements}

## Usage

```typescript
import { ... } from '@syner/{vendor}/...'

// Minimal working example

Key Files

File	Purpose
src/...	{What it does}

Environment

Requires {ENV_VAR} for {purpose}.

---

### Tooling (`tooling/*/`)

Tooling packages are internal configs. No AGENTS.md needed. README should be minimal but clear.

**README.md Structure:**
```markdown
# @syner/{config}

Shared {config type} configuration for Syner OS projects.

## Why?

{Brief explanation of why this config is centralized}

## Usage

```js
// How to use this config in a project

What's Included

{List of rules, plugins, or settings - keep it brief}

---

## Review Process

When reviewing documentation, check:

1. **Existence**: Does the file exist where it should?
2. **Audience**: Is README human-friendly? Is AGENTS.md agent-friendly?
3. **Structure**: Does it follow the level-appropriate template?
4. **Accuracy**: Does it reflect the current state of the code?
5. **No Duplication**: Is content duplicated between README and AGENTS.md?
6. **Links**: Are there helpful links to OS Protocol or related packages?

## Commands

When user runs `/docs`:

1. Ask what they want to review (specific package, level, or full audit)
2. Read the relevant files
3. Compare against the templates above
4. Report findings with three categories:
   - **Needs Work**: Missing files, incomplete content
   - **No Changes Needed**: Files that are complete and follow templates
   - **Actions Recommended**: Prioritized list of fixes
5. Offer to fix issues if requested

## Report Format

Always include all three sections in your audit report:

```markdown
## Needs Work
| Location | Issue |
|----------|-------|
| `apps/dev` | Missing AGENTS.md |

## No Changes Needed
| Location | Status |
|----------|--------|
| `extensions/github` | README.md and AGENTS.md complete |

## Recommended Actions
**Priority High:** ...
**Priority Medium:** ...
**Priority Low:** ...

This ensures the user sees both what needs fixing AND what's already good.

Example Invocations

• /docs - Start interactive review
• /docs apps/os - Review specific app
• /docs packages - Review all packages
• /docs audit - Full monorepo audit