What This Covers

Rules for writing and publishing documentation for your Tawa product. Drop this file into .claude/rules/tawa-docs.md in your project so your Claude automatically follows these conventions.

Two Doc Surfaces

Every Tawa product maintains docs on two separate surfaces. Know which one you're writing for before you start.

Developer Portal docs explain how to use your product. System docs explain how your product behaves internally — errors it emits, config it reads, and what breaks when dependencies fail. System docs are also the foundation for future agent-assisted remediation: when a runtime error occurs, a monitoring agent can match the error code to a Bible entry, find the stackRef pointing to the responsible code, and open an automated fix request.

See ops-guidelines for the full system/ops authoring spec.

Your Responsibility

Every deployed service must maintain documentation in the Bible DB. Your Claude is your primary authoring tool. When you build a feature, your Claude writes the doc. When you change an API, your Claude updates it.

Doc Schema

Every doc has these required fields:

The full identifier (fullSlug) is always: {product}/{type}/{slug}

Doc Types and When to Use Each

guide — Task-oriented walkthrough. Answers "how do I do X?"

Use for: getting started, integrating your service, testing, common use cases.

reference — Complete specification. Answers "what is X / what does X accept?"

Use for: API endpoints, config fields, environment variables, SDK methods, error codes.

architecture — System design explanation. Answers "why is X built this way?"

Use for: data flow, component relationships, design decisions.

changelog — Breaking changes and migrations. Required whenever you break an interface.

Use for: removed fields, renamed env vars, changed behavior, SDK version bumps.

Required Docs (Every Product)

These three docs are mandatory before a product is considered platform-ready:

{product}/guide/getting-started     — How to use or integrate the product
{product}/guide/testing             — How to test integrations (sandbox, mocks, credentials)
{product}/reference/api             — All public endpoints with request/response schemas

When to Create or Update Docs

Create a new doc when:

• You ship a new feature developers need to integrate with
• You add a new public API endpoint
• You add a new configuration option or env var
• You onboard devs to a non-obvious workflow

Update an existing doc when:

• An API endpoint, field, or behavior changes
• You deprecate or remove something
• A code example in the doc no longer works
• You add a new config option to an existing feature

Create a changelog when:

• Any change is breaking (removed fields, renamed vars, changed response shape)
• You deprecate something with a timeline
• You bump a major SDK version

Publishing Workflow (jci-mcp Tools)

ALWAYS follow this sequence. Never skip the review step.

Step 1 — Draft

bible_create({
  product: "your-product",
  type: "guide",
  slug: "getting-started",
  title: "Getting Started with Your Product",
  summary: "One sentence summary.",
  content: "...",
  tags: ["guide", "your-product"]
})

This creates a draft. It is NOT visible on the docs site yet.

Step 2 — Show the draft to the user

Always output the full markdown content for user review before publishing. Ask:

"Ready to publish this doc? I'll make it live on the docs site."

Step 3 — Publish

bible_publish({ fullSlug: "your-product/guide/getting-started" })

The doc goes live within 60 seconds.

Updating an existing doc

bible_edit({
  fullSlug: "your-product/guide/getting-started",
  content: "..updated content..",
  summary: "..updated summary if needed.."
})
bible_publish({ fullSlug: "your-product/guide/getting-started" })

Always republish after editing. Edits to published docs do NOT go live until republished.

Slug Conventions

• Lowercase, hyphen-separated only
• No underscores, no spaces, no camelCase
• Changelog slugs: v2-0-0 or relay-v2-breaking

getting-started          ✓
api-reference            ✓
testing                  ✓
gettingStarted           ✗
api_reference            ✗
V2 Breaking Changes      ✗

Content Style Rules

Present tense, active voice.

Returns a quote object.      ✓
A quote object is returned.  ✗

Never explain what things are — explain how to use them.

# Wrong
The raterspot API is a RESTful service that...

# Right
## Calling the Rating API
POST /api/raterspot/quote with the following body:

Code blocks for everything — commands, env vars, config, API requests, responses. No inline backtick-only examples for multi-line content.

Tables for reference data. Use tables for fields, options, env vars, and error codes.

No internal infrastructure details.

# Wrong
The rating result is stored in MongoDB at raterspot-prod.quotes

# Right
Rating results are persisted automatically.

Never mention: internal hostnames, K8s secret names, cluster DNS patterns, encryption algorithms, internal service ports, MinIO, Vault paths.

No marketing language. "Best-in-class", "powerful", "seamless" — cut it. Write what the thing does.

Start every doc with "## What This Covers" — one or two sentences saying exactly what the reader will learn. No preamble.

Content Templates

Guide Template

## What This Covers
One sentence describing the task this guide accomplishes.

## Prerequisites
- What the reader needs before starting (accounts, dependencies, env vars)

## Step 1 — [Action]
Explanation of what this step does and why.

[Code or config example]

## Step 2 — [Action]
...

## Verifying It Works
How to confirm the integration is working. Include a concrete test or expected output.

## Common Issues
Short table or list of the most frequent problems and how to fix them.

Reference Template

## What This Covers
One sentence describing what feature/API/SDK this reference documents.

## [Feature Name]
Brief description of what it does.

### Fields / Parameters

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `name` | string | Yes | ... |
| `value` | number | No | Default: 0 |

### Example

[Request or usage code block]

[Response or result code block]

### Error Codes

| Code | Meaning |
|------|---------|
| 400 | Missing required field |
| 403 | Token does not have required scope |

Changelog Template

## Summary
[N breaking changes, N deprecations, N additions]

## Breaking Changes

### [Thing That Changed]
**Before:**
[old code or behavior]

**After:**
[new code or behavior]

**Migration:**
[Exactly what the developer needs to change]

## Deprecations

### [Deprecated Feature]
Deprecated in vX.Y. Removed in vX.Z. Use [alternative] instead.

## New Features

### [New Feature]
[What it is and how to use it]

Common Mistakes

Tags Convention

Include at minimum: [doc-type, product-name]. Add feature-specific tags.

["guide", "raterspot", "getting-started", "api", "authentication"]
["reference", "raterspot", "api", "endpoints", "quote"]
["changelog", "raterspot", "v2", "breaking-change", "migration"]