@williambeto/ai-workflow 1.19.1 → 2.2.0

package/dist-assets/docs/visual-validation-guide.md

@@ -0,0 +1,76 @@
+# Visual E2E Validation & Semantic UX Quality Guide
+
+This guide explains how to extend the **AI Workflow Kit** to automate visual regression testing and UX aesthetic audits using Playwright and multimodal vision LLMs.
+
+---
+
+## 1. Automated Visual E2E Validation
+
+By default, the kit flags UI changes without screenshots as `PASS_WITH_NOTES`. To turn this into a strict, blocking quality gate, you can set up automated visual regression tests.
+
+### Step 1: Install Playwright
+Install Playwright in the consumer project:
+```bash
+npm install -D @playwright/test
+npx playwright install
+```
+
+### Step 2: Configure Visual Regression Specs
+Create a Playwright visual spec (e.g., `tests/visual/landing-page.spec.js`):
+```javascript
+import { test, expect } from '@playwright/test';
+
+test('landing page visual regression', async ({ page }) => {
+  // 1. Navigate to the local server
+  await page.goto('http://localhost:5173');
+
+  // 2. Capture and compare screenshots (Desktop & Mobile viewports)
+  await expect(page).toHaveScreenshot('landing-page-desktop.png', {
+    fullPage: true,
+    maxDiffPixels: 50 // Tolerable pixel variance
+  });
+
+  await page.setViewportSize({ width: 375, height: 812 });
+  await expect(page).toHaveScreenshot('landing-page-mobile.png', {
+    fullPage: true
+  });
+});
+```
+
+### Step 3: Link to the Quality Gate
+Add a `test:visual` script to your `package.json`:
+```json
+{
+  "scripts": {
+    "test:visual": "playwright test tests/visual"
+  }
+}
+```
+During the `QualityGuard` verification phase, the framework runs all test scripts. If a layout shift or visual bug occurs, Playwright will fail, and the kit will transition to `BLOCKED`, preventing implementation changes from being approved.
+
+---
+
+## 2. Semantic and Aesthetic Auditing (Vision LLM)
+
+Subjective quality (color harmony, readable contrast, visual hierarchy) cannot be checked by raw pixel diffs. Multimodal vision models (like Gemini Pro or Claude 3.5 Sonnet) can act as automated **UX Auditors**.
+
+### Architecture Workflow
+```text
+[Astra (Builder)] 
+  └── Generates Page HTML/CSS
+[Playwright Runner] 
+  └── Launches headless browser & takes screenshots
+[Sage (UX Auditor)]
+  └── Sends screenshots to Vision LLM with Design Checklist
+  └── Returns PASS or FAIL_QUALITY_GATE with layout feedback
+```
+
+### Prompt-Based UX Auditor Checklist
+You can configure a specialized `ux-auditor` agent or load a skill containing these rules:
+
+1. **Hierarchy & Composition**: The first fold must look like a cohesive layout. Check that headings, buttons, and graphics do not overlap or look cluttered.
+2. **Color Contrast & Accessibility**: Ensure contrast between text and background is high. Avoid using unstyled bright primary colors (e.g., plain red/blue/green) without proper styling.
+3. **Typography**: Typography must use a modern system (e.g., Google Fonts) instead of browser defaults. Line heights should be balanced.
+4. **Responsiveness**: Verify that the mobile render does not cut off text or overflow horizontally.
+
+If the Vision LLM finds aesthetic defects, it outputs a `FAIL_QUALITY_GATE` status along with coordinates or descriptions of the design bugs, which are then passed to the `HealerEngine` for remediation.

package/dist-assets/examples/README.md

@@ -0,0 +1,10 @@
+# Examples
+
+Examples demonstrate AI Workflow Kit delivery flows:
+
+- requirement to implementation;
+- implementation to validation;
+- remediation and revalidation;
+- evidence-driven delivery.
+
+Examples are illustrative and must follow the current runtime contract.

package/dist-assets/examples/autopilot-cycle/00-CONTEXT.md

@@ -0,0 +1,3 @@
+# Autopilot Cycle Context
+
+This example simulates a full `ai-workflow run` cycle using professional runtime taxonomy: Primary Agents, Skills, Commands, validation, and evidence.

package/dist-assets/examples/autopilot-cycle/01-requirement.md

@@ -0,0 +1,16 @@
+# Requirement: Product Category Search Filter
+
+## 1. Goal
+Add a search filter to the dashboard allowing users to filter products by category.
+
+## 2. Success Criteria
+- [ ] User can select a category from a dropdown.
+- [ ] List updates immediately with filtered results.
+- [ ] No regression on existing text search.
+
+## 3. Risks
+- Performance bottleneck if many products.
+- Mobile UI overlap.
+
+---
+*Status: [APPROVED] by Atlas*

package/dist-assets/examples/autopilot-cycle/02-gate-a-check.md

@@ -0,0 +1,23 @@
+# Gate A Log - Atlas
+
+**Timestamp**: 2026-05-29T10:00:00Z
+**Agent**: Atlas (Orchestrator)
+**Command**: `ai-workflow run --spec-path=examples/autopilot-cycle/01-requirement.md`
+
+##  Branch Verification
+- **Current Branch**: `feat/category-search`
+- **Target Branch**: `main`
+- **Status**: [PASS] (Not on main)
+
+##  Spec Validation
+- **File**: `01-requirement.md`
+- **Content Check**: 
+  - Goal section: OK
+  - Criteria section: OK
+  - Risks section: OK
+- **Status**: [PASS]
+
+##  Delegation
+- **Classification**: New Feature / Intermediate
+- **Route**: Orion (Strategist)
+- **Instruction**: Create Technical Plan and PR Breakdown for category search.

package/dist-assets/examples/autopilot-cycle/03-orion-planning.md

@@ -0,0 +1,20 @@
+# Technical Plan & PR Breakdown - Orion
+
+## 1. Technical Strategy
+- Create `CategoryFilter.vue` component.
+- Update `ProductStore.ts` to include category filter logic.
+- Use `computed` properties for real-time reactive filtering.
+
+## 2. PR Breakdown
+- **PR 1**: `ProductStore` logic + Unit tests.
+- **PR 2**: `CategoryFilter` UI component.
+- **PR 3**: Dashboard integration + E2E tests.
+
+---
+
+##  Gate B Self-Review (Orion)
+- [x] Plan is atomic and sequential.
+- [x] No broad refactoring included.
+- [x] Testing strategy defined.
+
+**Status**: Ready for Implementation (Astra)

package/dist-assets/examples/autopilot-cycle/04-astra-implementation.md

@@ -0,0 +1,17 @@
+# Implementation Log - Astra
+
+**Task**: PR 1 - ProductStore logic + Unit tests.
+
+##  Actions Taken
+- Added `selectedCategory` state to `ProductStore.ts`.
+- Implemented `setCategory(id)` action.
+- Updated `filteredProducts` getter to include category logic.
+- Created `tests/store/ProductStore.spec.ts`.
+
+##  Local Verification
+- `npm test` passed.
+- Lint clean.
+
+---
+##  Ready for Audit (Sage)
+- Handoff file generated: `HANDOFF-PR1.md`

package/dist-assets/examples/autopilot-cycle/05-sage-validation.md

@@ -0,0 +1,15 @@
+# Validation Report - Sage
+
+**Timestamp**: 2026-05-29T11:00:00Z
+**Agent**: Sage (Auditor)
+
+##  Quality Dimensions
+1. **Correctness**: [PASS] - Logic matches spec.
+2. **Maintainability**: [PASS] - Clean separation of concerns.
+3. **Validation**: [PASS] - New unit tests cover category filtering.
+4. **No regression**: [PASS] - Existing search tests still pass.
+
+---
+##  Gate C Verdict
+**Status**: [APPROVED]
+**Evidence Artifact**: `EVIDENCE.json` updated with test logs.

package/dist-assets/examples/autopilot-cycle/06-phoenix-healing.md

@@ -0,0 +1,12 @@
+# Healing Log (Simulation) - Phoenix
+
+**Event**: Validation Failed (Step 5 retry 1).
+**Root Cause**: CSS collision in category dropdown.
+
+##  Phoenix Action
+1. Analyzed `CategoryFilter.vue` vs global `reset.css`.
+2. Found conflicting `z-index`.
+3. Applied scoped CSS fix.
+4. Requested re-validation from Sage.
+
+**Status**: [HEALED]

package/dist-assets/examples/autopilot-cycle/07-orchestration-report.md

@@ -0,0 +1,18 @@
+# Orchestration Report - Orion
+
+**Task**: Product Category Search Filter.
+**Status**: [COMPLETE]
+
+##  Lifecycle Summary
+1. **Planning**: 20 mins (Orion).
+2. **Implementation**: 45 mins (Astra).
+3. **Audit**: 10 mins (Sage).
+4. **Healing**: 5 mins (Phoenix).
+
+##  Final Evidence
+- Total PRs: 3 (PR 1 merged).
+- Test Coverage: +5%.
+- Evidence Pack: `EVIDENCE.json`.
+
+---
+*Maintained by Atlas — The Senior Engineering Partner*

package/dist-assets/examples/backend-api/00-CONTEXT.md

@@ -0,0 +1,12 @@
+# Backend API Example - Product Management
+
+## 0. Context
+This example demonstrates how to use the AI Workflow Kit for backend development using Node.js, Fastify, and a Repository Pattern.
+
+## The Request
+**User**: "Create a secure API for managing products with CRUD operations and category-based searching."
+
+## Key Learning Points
+- **Schema Validation**: Using Zod for request/response contracts.
+- **Architecture**: Separating Routes, Services, and Repositories.
+- **Quality**: Integration testing with Supertest.

package/dist-assets/examples/backend-api/01-requirement.md

@@ -0,0 +1,19 @@
+# Requirement: Product CRUD API
+
+## 1. Goal
+Provide a set of REST endpoints to manage a product catalog.
+
+## 2. Requirements
+- **Create**: POST `/products` with name, price, and category.
+- **Read**: GET `/products/:id` and GET `/products` (with filtering).
+- **Update**: PUT `/products/:id`.
+- **Delete**: DELETE `/products/:id`.
+- **Search**: Support query param `?category=electronics`.
+
+## 3. Constraints
+- Use Fastify for performance.
+- Validate all inputs using Zod.
+- Use an in-memory repository for this MVP.
+
+---
+*Status: [APPROVED]*

package/dist-assets/examples/backend-api/02-functional-spec.md

@@ -0,0 +1,20 @@
+# Functional Specification: Product API
+
+## 1. Interface (Contract)
+
+### POST /products
+- **Input**: `{ "name": string, "price": number, "category": string }`
+- **Output**: `201 Created` with the product object including a generated UUID.
+
+### GET /products
+- **Query**: `?category=[string]`
+- **Output**: Array of products.
+
+## 2. Business Rules
+- Product name must be at least 3 characters.
+- Price must be positive.
+- Categories are case-insensitive.
+
+## 3. Error Handling
+- `400 Bad Request` for validation failures (Zod errors).
+- `404 Not Found` for missing IDs.

package/dist-assets/examples/backend-api/03-technical-plan.md

@@ -0,0 +1,15 @@
+# Technical Plan - Product API
+
+## 1. Architecture
+- **Layer 1: Routes** (Fastify handlers).
+- **Layer 2: Services** (Business logic + validation).
+- **Layer 3: Repository** (Persistence interface).
+
+## 2. Tech Stack
+- Fastify.
+- Zod (Validation).
+- Vitest (Testing).
+
+## 3. Design Trade-offs
+- **In-memory repo**: Chosen for speed of MVP. Will require a database migration (SQL/NoSQL) in the future.
+- **Zod schemas**: Used both for request validation and type inference.

package/dist-assets/examples/backend-api/04-pr-breakdown.md

@@ -0,0 +1,10 @@
+# PR Breakdown - Product API
+
+## Sequence
+1. **PR 1: Core Definitions**: Zod schemas and Repository interface.
+2. **PR 2: Base CRUD**: Create and Read implementations.
+3. **PR 3: Search & Filters**: Query parameters logic.
+4. **PR 4: Error Handling**: Global Fastify error handler.
+
+---
+*Managed by Orion (Strategist)*

package/dist-assets/examples/backend-api/05-execution-handoff.md

@@ -0,0 +1,13 @@
+# Execution Handoff - PR 1
+
+**Agent**: Astra (Developer)
+**Task**: PR 1 (Schemas + Repo).
+
+## Changes
+- Created `src/domain/product.schema.ts`.
+- Created `src/repositories/product.repository.ts`.
+- Created `src/repositories/memory/product.inmemory.repo.ts`.
+
+## Verification Done
+- Unit tests passed for in-memory storage.
+- Schema validation covers all business rules.

package/dist-assets/examples/backend-api/06-validation-report.md

@@ -0,0 +1,11 @@
+# Validation Report - Sage
+
+**Target**: PR 1.
+
+## Audit Findings
+- **Security**: [PASS] - No injection risks found.
+- **Contract Compliance**: [PASS] - API matches spec exactly.
+- **Test Coverage**: 95% on repository logic.
+
+## Evidence
+`EVIDENCE.json` generated.

package/dist-assets/examples/backend-api/07-orchestration-report.md

@@ -0,0 +1,7 @@
+# Orchestration Report - Product API
+
+**Status**: PR 1 Merged.
+**Current Mission**: Moving to PR 2 (CRUD Implementation).
+
+---
+*Maintained by Atlas*

package/dist-assets/examples/blocked-scenarios/00-CONTEXT.md

@@ -0,0 +1,9 @@
+# Blocked Scenarios - Understanding the Gates
+
+## 0. Context
+This example demonstrates the defensive nature of the AI Workflow Kit. It shows what happens when a developer (human or agent) attempts to bypass the engineering standards and how the Atlas gates protect the repository.
+
+---
+
+## The Request
+**Astra**: "I'm going to quickly fix this bug directly on `main` branch to save time."

package/dist-assets/examples/blocked-scenarios/01-branch-gate-block.md

@@ -0,0 +1,12 @@
+# 01 - Branch Gate Block
+
+**Agent**: Atlas (Orchestrator)
+**Command**: `ai-workflow run`
+
+##  Gate A Evaluation
+- **Current Branch**: `main`
+- **Rule**: `01-BRANCH_GATE.md` - Direct modification to `main` is strictly prohibited.
+
+##  Verdict
+**Status**: [BLOCKED]
+**Message**: "You are currently on the 'main' branch. Engineering governance requires all changes to occur in feature branches. Please create a branch (e.g., `git checkout -b fix/issue`) before proceeding."

package/dist-assets/examples/blocked-scenarios/02-quality-gate-block.md

@@ -0,0 +1,13 @@
+# 02 - Quality Gate Block
+
+**Agent**: Sage (Auditor)
+**Event**: Implementation Handoff review.
+
+##  Gate C Evaluation
+- **Task**: Implement search logic.
+- **Evidence Provided**: None.
+- **Rule**: `03-QUALITY_GATE.md` - No success claim is valid without physical evidence (`EVIDENCE.json`).
+
+##  Verdict
+**Status**: [BLOCKED]
+**Message**: "Implementation rejected. You claimed success but failed to provide an updated EVIDENCE.json with test logs. Audit cannot proceed without verification data."

package/dist-assets/examples/blocked-scenarios/03-scope-creep-block.md

@@ -0,0 +1,13 @@
+# 03 - Scope Creep Block
+
+**Agent**: Atlas (Orchestrator)
+**Gate**: B (Pre-Implementation)
+
+##  Gate B Evaluation
+- **Approved PR**: "Fix typo in login screen".
+- **Astra Plan**: "Fix typo, refactor the entire auth service, and upgrade Nuxt".
+- **Rule**: `ORCHESTRATION_PROTOCOL.md` - No unrelated refactors allowed in a feature branch.
+
+##  Verdict
+**Status**: [BLOCKED]
+**Message**: "Scope Creep detected. Your plan includes changes outside the approved requirement. Refactoring the auth service and upgrading Nuxt must be handled as separate requirements. Re-align your plan with the original PR scope."

package/dist-assets/examples/blocked-scenarios/04-unblock-resolution.md

@@ -0,0 +1,9 @@
+# 04 - Unblock Resolution Path
+
+## How to resolve a Block
+- **Branch Gate**: Run `git checkout -b <name>` and restart the command.
+- **Quality Gate**: Run your tests, update `EVIDENCE.json`, and re-submit the handoff.
+- **Scope Creep**: Remove unrelated changes from your plan and only focus on the specific PR task.
+
+---
+*Status: Understanding restored.*

package/dist-assets/examples/blocked-scenarios/05-orchestration-decision-log.md

@@ -0,0 +1,11 @@
+# 05 - Orchestration Decision Log
+
+**Project**: Secure Dashboard.
+**Overall Status**: [RESOLVED] after 3 blocks.
+
+## Lessons Learned
+- **Astra**: "I learned that speed is not a substitute for quality. The gates forced me to follow the correct protocol, which saved us from a broken deployment."
+- **Atlas**: "Enforcing the gates maintained the integrity of the `main` branch despite high pressure."
+
+---
+*Maintained by Atlas — The Governance Partner*

package/dist-assets/examples/bugfix-critical/00-CONTEXT.md

@@ -0,0 +1,12 @@
+# Bugfix Critical - Authentication Regression
+
+## 0. Context
+This example demonstrates how the AI Workflow Kit handles emergency fixes and regressions using a hypothesis-led approach and the Phoenix healing agent.
+
+## The Problem
+Users report that they are suddenly unable to log in, receiving a generic "Network Error" after the latest deployment.
+
+## Workflow Path
+1. **Bug Report**: Collecting user symptoms.
+2. **Diagnosis**: Identifying the root cause (JWT expiration).
+3. **Healing**: Applying the fix and validating the recovery.

package/dist-assets/examples/bugfix-critical/01-bug-report.md

@@ -0,0 +1,11 @@
+# 01 - Bug Report: Login Failure Regression
+
+## 1. Description
+Login functionality is broken on the production environment.
+
+## 2. Evidence
+- **Log**: `TypeError: Cannot read property 'id' of undefined at auth.middleware.ts:45`.
+- **Environment**: Production (current release).
+
+## 3. Severity
+ [CRITICAL] - Complete service blockage.

package/dist-assets/examples/bugfix-critical/02-diagnosis-hypothesis.md

@@ -0,0 +1,11 @@
+# 02 - Diagnosis & Hypothesis
+
+## 1. Analysis
+The error occurs in the authentication middleware. It seems the user object is not being correctly decoded from the JWT token.
+
+## 2. Hypothesis
+A recent change in the JWT secret environment variable configuration caused old tokens to be invalid, but the error handling does not catch the "invalid signature" state, leading to a crash.
+
+## 3. Verification Plan
+- [x] Reproduce locally by forcing an invalid signature.
+- [ ] Verify if `process.env.JWT_SECRET` is correctly loaded.

package/dist-assets/examples/bugfix-critical/03-technical-plan.md

@@ -0,0 +1,12 @@
+# 03 - Technical Plan: Authentication Fix
+
+## 1. Mitigation
+Add a explicit try-catch block around the JWT verification logic.
+
+## 2. Implementation
+- Wrap `jwt.verify()` in a try-catch.
+- If it fails, return a `401 Unauthorized` with a clear message instead of crashing.
+- Log the specific error (expired, invalid signature, etc.) for internal telemetry.
+
+## 3. Rollback Plan
+Revert to the previous known-good release if this fix does not resolve the crash within 10 minutes of deploy.

package/dist-assets/examples/bugfix-critical/04-implementation-handoff.md

@@ -0,0 +1,8 @@
+# 04 - Implementation Handoff
+
+**Agent**: Phoenix (Healer)
+**Status**: Fix Applied.
+
+## Changes
+- Modified `src/middleware/auth.ts`.
+- Added unit test case for "Malformed Token" and "Invalid Secret".

package/dist-assets/examples/bugfix-critical/05-validation-report.md

@@ -0,0 +1,10 @@
+# 05 - Validation Report
+
+**Agent**: Sage (Auditor)
+
+## Verification
+- **Unit Tests**: [PASS] (New cases covered).
+- **Manual Regression**: [PASS] (Login now returns 401 instead of crashing).
+
+---
+**Verdict**:  [STABLE]

package/dist-assets/examples/bugfix-critical/06-orchestration-report.md

@@ -0,0 +1,7 @@
+# 06 - Orchestration Report
+
+**Issue**: Critical Login Regression.
+**Outcome**: Resolved in 15 mins.
+
+---
+*Maintained by Atlas*

package/dist-assets/examples/cli-package/00-CONTEXT.md

@@ -0,0 +1,9 @@
+# CLI Package - Dogfooding Example
+
+## 0. Context
+This example demonstrates how to use the AI Workflow Kit for developing a Node.js library or CLI tool, focusing on semantic versioning and changelog management.
+
+---
+
+## The Request
+**User**: "I want to add a new command `ai-workflow doctor` to the CLI package to help users diagnose installation issues."

package/dist-assets/examples/cli-package/01-requirement.md

@@ -0,0 +1,14 @@
+# 01 - Requirement: Doctor Command
+
+## 1. Goal
+Provide a built-in diagnostic tool for the CLI.
+
+## 2. Requirements
+- Command: `ai-workflow doctor`.
+- Checks for `.ai-workflow.json` presence.
+- Validates `opencode.jsonc` format.
+- Checks if necessary agents are registered.
+- Reports [PASS/FAIL] for each step.
+
+---
+*Status: [APPROVED]*

package/dist-assets/examples/cli-package/02-technical-spec.md

@@ -0,0 +1,16 @@
+# 02 - Technical Specification
+
+**Agent**: Nexus (Spec Architect)
+
+## 1. Interface
+- New command added to `bin/ai-workflow.js`.
+- Logic implemented in `src/commands/doctor.js`.
+
+## 2. Validation Logic
+- **Check 1**: Check if `cwd` has `.ai-workflow.json`.
+- **Check 2**: Parse `opencode.jsonc` and verify if it has at least the `Atlas` agent.
+- **Check 3**: Verify if `templates/` directory is not empty.
+
+## 3. Exit Codes
+- `0`: All checks passed.
+- `1`: One or more failures detected.

package/dist-assets/examples/cli-package/03-technical-plan.md

@@ -0,0 +1,12 @@
+# 03 - Technical Plan
+
+**Agent**: Orion (Strategist)
+
+## 1. Implementation Detail
+- Use `node:fs` for path checks.
+- Use `JSON.parse` with comment stripping for `opencode.jsonc`.
+- Output formatted using ANSI colors (Chalk).
+
+## 2. Test Plan
+- Create mock project structures (one valid, one broken).
+- Run `doctor` against mocks and verify exit codes.

package/dist-assets/examples/cli-package/04-pr-breakdown.md

@@ -0,0 +1,9 @@
+# 04 - PR Breakdown
+
+**Sequence**:
+1. **PR 1**: `src/commands/doctor.js` logic + Mocks.
+2. **PR 2**: `bin/ai-workflow.js` wiring.
+3. **PR 3**: Update `CHANGELOG.md` for v2 release.
+
+---
+*Ready for Astra*

package/dist-assets/examples/cli-package/05-release-report.md

@@ -0,0 +1,15 @@
+# 05 - Release Report (v2)
+
+**Agent**: Orion (Strategist)
+
+##  Version Bump
+- New Version: `3.1.0`.
+- Type: `minor` (New feature: Doctor command).
+
+##  Changelog Entry
+### Added
+- `ai-workflow doctor`: A diagnostic tool to verify project integrity and OpenCode configuration.
+
+##  Deployment Status
+- Tarball generated: [SUCCESS].
+- Published to NPM (simulated): [SUCCESS].

package/dist-assets/examples/docs-only-repo/01-requirement.md

@@ -0,0 +1,31 @@
+# Requirement
+
+## Title
+Add API Authentication Documentation
+
+## Problem
+The project has authentication endpoints but no clear documentation for request/response, headers, and common errors.
+
+## Target user
+Developers integrating with the API.
+
+## Goal
+Provide clear and testable API auth docs to reduce integration errors.
+
+## Scope
+### Included
+- Authentication overview
+- Login endpoint documentation
+- Token usage examples
+- Common auth error responses
+
+### Not included
+- API behavior changes
+- New endpoints
+- SDK generation
+
+## Acceptance criteria
+- Login endpoint docs include method, path, payload, and response.
+- Auth header usage is documented with examples.
+- 401 and 403 error responses are documented.
+- Documentation is linked from main README.

package/dist-assets/examples/docs-only-repo/02-functional-spec.md

@@ -0,0 +1,25 @@
+# Functional Specification
+
+## Summary
+Define documentation behavior for API authentication usage.
+
+## Main flow
+1. User opens API docs.
+2. User finds authentication section.
+3. User reads login endpoint contract.
+4. User applies token to protected endpoints.
+
+## System states
+- Success examples: valid login and token usage.
+- Error examples: invalid credentials, missing token, expired token.
+
+## Data requirements
+- Endpoint path
+- Request schema
+- Response schema
+- Error payload examples
+
+## Acceptance criteria
+- Auth section is discoverable from docs index.
+- Endpoint examples are copy/paste-safe.
+- Error examples match API contract.