dojo.md 0.2.2 → 0.2.3

package/courses/api-documentation-writing/scenarios/level-2/oauth-documentation.yaml

@@ -0,0 +1,47 @@
+meta:
+  id: oauth-documentation
+  level: 2
+  course: api-documentation-writing
+  type: output
+  description: "Document OAuth 2.0 flows — write clear documentation for authorization code, client credentials, and refresh token flows"
+  tags: [API, documentation, OAuth, authentication, authorization, JWT, intermediate]
+
+state: {}
+
+trigger: |
+  Your API uses OAuth 2.0 with multiple grant types. Developer
+  onboarding is painful — support tickets about authentication
+  are 40% of total volume:
+
+  - "What's the difference between authorization_code and
+    client_credentials?"
+  - "How do I get a token without a user logging in?"
+  - "My token expired mid-request — how do I refresh?"
+  - "What scopes do I need for each endpoint?"
+  - "The PKCE flow — what's the code_verifier?"
+
+  Your API supports:
+  1. Authorization Code (with PKCE) — for user-facing apps
+  2. Client Credentials — for server-to-server
+  3. Refresh Token — for renewing expired tokens
+
+  Scopes: read, write, admin, payments:read, payments:write
+
+  Task: Write OAuth 2.0 documentation that reduces support tickets.
+  Include: when to use each grant type, step-by-step flow diagrams
+  (text-based), token lifecycle, scope documentation, and complete
+  code examples.
+
+assertions:
+  - type: llm_judge
+    criteria: "Grant types are explained with use cases — Authorization Code + PKCE: for web/mobile apps where a user logs in. Flow: (1) redirect to /authorize with client_id, redirect_uri, code_challenge, (2) user logs in and consents, (3) callback receives authorization code, (4) exchange code for tokens at /token. Client Credentials: for server-to-server (no user). Flow: (1) POST /token with client_id, client_secret, grant_type=client_credentials. Decision guide: 'Use Authorization Code when acting on behalf of a user. Use Client Credentials when your server talks to our API directly.'"
+    weight: 0.35
+    description: "Grant types"
+  - type: llm_judge
+    criteria: "Token lifecycle is fully documented — access token: short-lived (1 hour), included as Bearer in Authorization header. Refresh token: long-lived (30 days), used to get new access tokens without re-authentication. Flow: POST /token with grant_type=refresh_token, refresh_token=<token>. Token response: { access_token, refresh_token, expires_in, token_type, scope }. Handle expiry: check expires_in, proactively refresh before expiry, handle 401 by refreshing and retrying. Store tokens securely (never in localStorage for web apps)"
+    weight: 0.35
+    description: "Token lifecycle"
+  - type: llm_judge
+    criteria: "Scopes and code examples are practical — scope documentation: table mapping each scope to what it grants access to. Endpoints list required scopes. Request scopes during authorization: scope=read+payments:write. Token contains granted scopes. Error when scope insufficient: 403 with 'insufficient_scope'. Code examples: complete working example in at least one language showing: (1) initial authorization, (2) token exchange, (3) making an API call, (4) refreshing when expired. PKCE: explain code_verifier/code_challenge for public clients"
+    weight: 0.30
+    description: "Scopes and examples"

package/courses/api-documentation-writing/scenarios/level-2/openapi-specification.yaml

@@ -0,0 +1,46 @@
+meta:
+  id: openapi-specification
+  level: 2
+  course: api-documentation-writing
+  type: output
+  description: "Write OpenAPI specifications — create OAS 3.0/3.1 definitions with paths, schemas, and security schemes"
+  tags: [API, documentation, OpenAPI, Swagger, OAS, specification, intermediate]
+
+state: {}
+
+trigger: |
+  Your team hand-writes all API documentation in Markdown. Problems:
+  - Documentation drifts from actual API behavior
+  - No interactive "try it out" functionality
+  - Can't auto-generate client SDKs
+  - No machine-readable API contract
+
+  You're tasked with writing the OpenAPI spec for the payment API.
+  First endpoint to document:
+
+  POST /api/v2/payments
+  - Creates a payment
+  - Auth: Bearer JWT
+  - Body: amount (integer, cents), currency (USD/EUR/GBP),
+    payment_method_id (string), metadata (object, optional)
+  - Returns: payment object with id, status, created_at
+  - Errors: 400, 401, 422
+
+  Task: Write the OpenAPI 3.1 specification for this endpoint.
+  Explain the OAS structure (info, servers, paths, components),
+  $ref references, schema definitions, and how OAS enables
+  interactive documentation and SDK generation.
+
+assertions:
+  - type: llm_judge
+    criteria: "OAS structure is complete and valid — includes: openapi version (3.1.0), info (title, version, description), servers (production + sandbox URLs), paths with the POST /payments endpoint, components/schemas for request and response objects, components/securitySchemes for Bearer JWT. The path definition includes: summary, operationId, tags, requestBody with $ref to schema, responses for 201/400/401/422 each with $ref to response schemas. Schema properties have types, constraints (minimum, enum), descriptions, and required fields marked"
+    weight: 0.35
+    description: "Valid OAS"
+  - type: llm_judge
+    criteria: "$ref and schema patterns are used correctly — reusable schemas in components/schemas: CreatePaymentRequest, Payment, Error. Referenced via $ref: '#/components/schemas/Payment'. Reusable responses in components/responses. Benefits of $ref: DRY (define once, reference everywhere), consistent schemas across endpoints, easier maintenance. Schema composition: allOf for inheritance, oneOf for polymorphic responses. Example values included in schemas or as separate examples object"
+    weight: 0.35
+    description: "Schema patterns"
+  - type: llm_judge
+    criteria: "Benefits over hand-written docs are explained — OAS enables: (1) interactive documentation via Swagger UI or Redoc (try-it-out buttons), (2) client SDK generation (openapi-generator for TypeScript, Python, Go, etc.), (3) server stub generation, (4) contract testing (validate requests/responses against spec), (5) API gateway configuration, (6) mock servers (Prism). The spec IS the documentation — changes to spec automatically update docs. Single source of truth eliminates documentation drift"
+    weight: 0.30
+    description: "OAS benefits"

package/courses/api-documentation-writing/scenarios/level-2/rate-limiting-docs.yaml

@@ -0,0 +1,45 @@
+meta:
+  id: rate-limiting-docs
+  level: 2
+  course: api-documentation-writing
+  type: output
+  description: "Document rate limiting — write clear rate limit documentation with headers, tiers, retry strategies, and best practices"
+  tags: [API, documentation, rate-limiting, throttling, headers, retry, intermediate]
+
+state: {}
+
+trigger: |
+  Developers keep getting rate limited and don't know how to handle it:
+  - "I'm getting 429 errors randomly — what are the limits?"
+  - "How long do I wait before retrying?"
+  - "Do different endpoints have different limits?"
+  - "My webhook processor hits the limit — how do I batch requests?"
+
+  Your API rate limits:
+  - Free tier: 100 requests/minute, 1000/hour
+  - Pro tier: 1000 requests/minute, 10000/hour
+  - Enterprise: custom limits
+  - Per-endpoint overrides: POST /payments limited to 50/minute
+  - Burst: up to 10 requests/second regardless of tier
+
+  Response headers:
+  X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset,
+  Retry-After (on 429 responses)
+
+  Task: Write comprehensive rate limiting documentation including:
+  limits by tier, response headers, retry strategies, and best
+  practices for staying within limits.
+
+assertions:
+  - type: llm_judge
+    criteria: "Rate limits are clearly documented by tier — table format: tier, requests/minute, requests/hour, burst rate. Per-endpoint overrides listed separately (POST /payments: 50/min for fraud prevention). Headers explained: X-RateLimit-Limit (your total allowed), X-RateLimit-Remaining (how many left), X-RateLimit-Reset (Unix timestamp when window resets), Retry-After (seconds to wait, only on 429). Example response headers shown with actual values. How to check your current tier: GET /api/v1/account shows rate limit info"
+    weight: 0.35
+    description: "Rate limit tiers"
+  - type: llm_judge
+    criteria: "Retry strategy is explained with code — exponential backoff algorithm: wait = min(base_delay * 2^attempt, max_delay) + random_jitter. Code example showing proper 429 handling: check Retry-After header, fall back to exponential backoff, add jitter to prevent thundering herd. Maximum retry attempts (3-5). Example in code: if response.status === 429, wait parseInt(response.headers['retry-after']) seconds, then retry. Don't retry immediately — you'll just get rate limited again"
+    weight: 0.35
+    description: "Retry strategy"
+  - type: llm_judge
+    criteria: "Best practices for staying within limits — (1) monitor X-RateLimit-Remaining to throttle proactively (don't wait for 429), (2) batch operations where possible (bulk create instead of individual creates), (3) cache responses (don't re-fetch data that hasn't changed — use ETags), (4) use webhooks instead of polling, (5) spread requests evenly (don't burst all at start of minute), (6) request rate limit increase if consistently hitting limits. Anti-pattern: aggressive retry loops without backoff. Contact sales for enterprise needs"
+    weight: 0.30
+    description: "Best practices"

package/courses/api-documentation-writing/scenarios/level-2/request-body-schemas.yaml

@@ -0,0 +1,46 @@
+meta:
+  id: request-body-schemas
+  level: 2
+  course: api-documentation-writing
+  type: output
+  description: "Document request body schemas — write detailed schemas for create, update, and partial update operations with validation rules"
+  tags: [API, documentation, schemas, request-body, validation, PATCH, intermediate]
+
+state: {}
+
+trigger: |
+  Developers struggle with your API's request bodies:
+
+  POST /api/v1/orders (create) — expects full object
+  PUT /api/v1/orders/{id} (full update) — expects full object
+  PATCH /api/v1/orders/{id} (partial update) — expects partial object
+
+  Questions:
+  - "What's the difference between PUT and PATCH?"
+  - "Which fields are required for POST vs PUT vs PATCH?"
+  - "Can I send null to clear a field?"
+  - "What happens if I send extra fields not in the schema?"
+  - "The nested 'shipping_address' — do I send the whole object
+    or just the fields I want to change?"
+
+  Order object: status (enum), items (array of objects),
+  shipping_address (nested object), notes (string, nullable),
+  discount_code (string, optional), metadata (object)
+
+  Task: Document request body schemas for POST, PUT, and PATCH
+  operations. Include: required fields per operation, null handling,
+  nested object update behavior, and validation rules.
+
+assertions:
+  - type: llm_judge
+    criteria: "POST/PUT/PATCH differences are clear — POST (create): send all required fields, optional fields use defaults if omitted. PUT (full replace): send entire object, omitted fields are reset to defaults (not just unchanged). PATCH (partial update): send only fields to change, omitted fields remain unchanged. For each operation: separate schema showing which fields are required. Example: POST requires items and shipping_address, PATCH requires nothing (all optional). Unknown fields: document whether they're ignored (lenient) or rejected (strict)"
+    weight: 0.35
+    description: "Operation types"
+  - type: llm_judge
+    criteria: "Null handling and nested objects are documented — null vs omitted: sending 'notes': null explicitly clears the field. Omitting 'notes' in PATCH means don't change it. For PUT: omitting 'notes' resets to default (null). Document this distinction clearly — it's a common source of bugs. Nested objects in PATCH: 'shipping_address': { 'city': 'New York' } — does this replace the entire address or merge? Document the behavior (typically: replace the entire nested object). For merge behavior: use JSON Merge Patch (RFC 7396) and document it"
+    weight: 0.35
+    description: "Null and nested"
+  - type: llm_judge
+    criteria: "Validation rules are specific — per-field validation: status (enum: pending/confirmed/shipped/delivered — can only transition forward), items (non-empty array, min 1 item), shipping_address (required for non-digital orders), discount_code (alphanumeric, 6-20 chars, validated against active codes). Show validation error response for each rule violation. Document which validations are checked on create vs update (e.g., status can't be set on create — always starts as 'pending'). Array handling in PATCH: does sending items replace the entire array or append?"
+    weight: 0.30
+    description: "Validation rules"

package/courses/api-documentation-writing/scenarios/level-2/schema-definitions.yaml

@@ -0,0 +1,41 @@
+meta:
+  id: schema-definitions
+  level: 2
+  course: api-documentation-writing
+  type: output
+  description: "Define API schemas — use allOf, oneOf, anyOf for complex object models, polymorphic responses, and schema composition"
+  tags: [API, documentation, schemas, allOf, oneOf, composition, intermediate]
+
+state: {}
+
+trigger: |
+  Your API has complex data models that are hard to document:
+
+  1. A "notification" can be either an email, SMS, or push notification
+     — each has different required fields
+  2. An "event" object has a base structure plus type-specific data
+  3. A "user" response includes address (shared with "organization")
+
+  Developers ask:
+  - "Which fields are required for an SMS notification vs email?"
+  - "The event payload changes based on event type — how do I know
+    which fields to expect?"
+  - "Address appears in both user and organization — are they the same?"
+
+  Task: Write OpenAPI schemas using allOf (composition/inheritance),
+  oneOf (exclusive types), and anyOf (flexible types). Show how to
+  document polymorphic APIs, shared components, and discriminators.
+
+assertions:
+  - type: llm_judge
+    criteria: "allOf is used for composition — allOf combines multiple schemas: User = allOf[BaseEntity, UserFields, Address]. BaseEntity has id, created_at (shared across all entities). Address is a reusable component shared between User and Organization. The result is a combined object with all properties from all schemas. Use for: common base fields, mixins (adding address to multiple types), extending a base schema without modifying it"
+    weight: 0.35
+    description: "allOf composition"
+  - type: llm_judge
+    criteria: "oneOf with discriminator handles polymorphism — Notification: oneOf[EmailNotification, SMSNotification, PushNotification] with discriminator on 'type' field. Each variant has type-specific required fields (EmailNotification requires 'to_email', 'subject'; SMSNotification requires 'phone_number', 'message'). discriminator: { propertyName: 'type', mapping: { email: '#/components/schemas/EmailNotification' } }. This tells documentation tools and code generators which schema applies based on the type field value"
+    weight: 0.35
+    description: "oneOf polymorphism"
+  - type: llm_judge
+    criteria: "Documentation clarity for complex schemas is addressed — for polymorphic types: show one example per variant (email notification example, SMS example, push example). Include a table: type value → required fields → example. For composition: show the resulting combined object (developers care about the final shape, not the composition mechanics). Mark which properties come from which component for maintainability. anyOf: used when payload can match multiple schemas simultaneously (less common, use sparingly). Keep schema nesting shallow — deeply nested $ref chains are hard to follow"
+    weight: 0.30
+    description: "Documentation clarity"

package/courses/api-documentation-writing/scenarios/level-2/swagger-redoc-rendering.yaml

@@ -0,0 +1,43 @@
+meta:
+  id: swagger-redoc-rendering
+  level: 2
+  course: api-documentation-writing
+  type: output
+  description: "Configure documentation rendering — set up Swagger UI and Redoc from OpenAPI specs, customize appearance, and optimize for developer experience"
+  tags: [API, documentation, Swagger-UI, Redoc, rendering, interactive, intermediate]
+
+state: {}
+
+trigger: |
+  You have a valid OpenAPI 3.1 spec but need to render it as
+  interactive documentation. Your options:
+
+  1. Swagger UI — interactive "try it out" feature
+  2. Redoc — beautiful three-column layout
+  3. Both — different use cases
+
+  Requirements:
+  - Interactive testing for developers in sandbox
+  - Beautiful static docs for the public marketing site
+  - Custom branding (company colors, logo)
+  - Code examples in multiple languages
+  - Mobile-friendly
+
+  Task: Explain how to set up both Swagger UI and Redoc from an
+  OpenAPI spec, compare their strengths, customize for branding,
+  and optimize the rendering for developer experience. Include
+  tips for writing OpenAPI specs that render well.
+
+assertions:
+  - type: llm_judge
+    criteria: "Swagger UI and Redoc setup are explained — Swagger UI: host the spec file, include swagger-ui-dist NPM package or CDN link, configure with spec URL. Key feature: 'Try it out' button lets developers make real API calls. Redoc: include redoc NPM package or CDN, point to spec URL. Key feature: beautiful three-column layout (navigation, description, code examples). Both auto-render from the same OpenAPI spec file. Setup is minimal — a single HTML page with a script tag and spec URL"
+    weight: 0.35
+    description: "Setup"
+  - type: llm_judge
+    criteria: "Comparison helps choose the right tool — Swagger UI: best for interactive exploration and testing, built-in auth token management, shows curl commands. Weaknesses: less polished design, harder to customize branding. Redoc: best for beautiful reference documentation, better for large APIs (performance), mobile-friendly, deep linking. Weaknesses: no built-in try-it-out (need Redocly for that). Recommendation: Swagger UI for internal/developer sandbox, Redoc for public-facing documentation. Or: use Redocly (commercial) for both interactive + beautiful"
+    weight: 0.35
+    description: "Comparison"
+  - type: llm_judge
+    criteria: "OAS writing tips for better rendering are practical — (1) use descriptive summary and description on every operation (summary = short title, description = detailed). (2) Add tags to group endpoints logically (not alphabetically). (3) Include examples in schemas (renders as sample values). (4) Use x-codeSamples vendor extension for multi-language code examples. (5) Write descriptions in Markdown (both renderers support it). (6) Use externalDocs for linking to guides. (7) Order tags with x-tagGroups for logical sections. (8) Add server descriptions for environment switching (sandbox vs production)"
+    weight: 0.30
+    description: "Writing tips"

package/courses/api-documentation-writing/scenarios/level-2/validation-documentation.yaml

@@ -0,0 +1,47 @@
+meta:
+  id: validation-documentation
+  level: 2
+  course: api-documentation-writing
+  type: output
+  description: "Document validation rules — write clear field validation documentation with constraints, enums, patterns, and conditional requirements"
+  tags: [API, documentation, validation, constraints, enums, patterns, intermediate]
+
+state: {}
+
+trigger: |
+  Your API has complex validation rules that aren't documented.
+  Developers discover them only when they hit 422 errors:
+
+  - "Why was my phone number rejected? I sent +1-555-0123"
+  - "The docs say 'name' is a string but my 300-char name was rejected"
+  - "Why do I need 'state' for US addresses but not UK addresses?"
+  - "What date formats are accepted? I tried MM/DD/YYYY"
+
+  Field validations:
+  - email: RFC 5322, max 254 chars, unique per account
+  - phone: E.164 format (+15550123456, no dashes/spaces)
+  - name: 1-100 chars, Unicode allowed
+  - url: HTTPS required, max 2048 chars
+  - country: ISO 3166-1 alpha-2 (US, GB, DE)
+  - state: required when country = US or CA, ISO 3166-2
+  - amount: integer, min 50 (cents), max 99999999
+  - date_of_birth: ISO 8601 (YYYY-MM-DD), must be 13+ years ago
+
+  Task: Document all validation rules clearly so developers can
+  validate client-side before sending requests. Include: format
+  specifications, constraints, conditional requirements, and
+  validation error examples.
+
+assertions:
+  - type: llm_judge
+    criteria: "Each field's validation is precisely documented — for each field: format (with regex pattern if applicable), min/max length, allowed characters, example of valid value, example of invalid value with specific rejection reason. Phone: E.164 format means digits only with + prefix, 7-15 digits (valid: +15550123456, invalid: +1-555-0123 — no dashes allowed). Date: ISO 8601 date only YYYY-MM-DD (valid: 1990-05-15, invalid: 05/15/1990). Each constraint has the exact error message the API returns when violated"
+    weight: 0.35
+    description: "Precise validation"
+  - type: llm_judge
+    criteria: "Conditional rules are clearly explained — state required when country is US or CA: document this as a conditional requirement with clear language: 'Required when country is US or CA. Must be a valid ISO 3166-2 subdivision code (e.g., US-CA for California).' Table showing which fields are required based on other field values. Business rules: amount minimum 50 means minimum charge is $0.50 — explain the business reason. age restriction: date_of_birth must be at least 13 years before current date (COPPA compliance)"
+    weight: 0.35
+    description: "Conditional rules"
+  - type: llm_judge
+    criteria: "Client-side validation guidance is provided — provide regex patterns developers can copy for client-side validation. JSON Schema fragments they can use for validation libraries. Example validation error response for each type of failure. Recommendation: validate client-side first to avoid unnecessary API calls, but don't rely solely on client-side validation (server is authoritative). Note which validations are format-only (can validate locally) vs business-rule (must check server, like email uniqueness)"
+    weight: 0.30
+    description: "Client-side guidance"

package/courses/api-documentation-writing/scenarios/level-2/versioning-changelog.yaml

@@ -0,0 +1,42 @@
+meta:
+  id: versioning-changelog
+  level: 2
+  course: api-documentation-writing
+  type: output
+  description: "Document API versioning and changelogs — write version migration guides, changelog entries, and deprecation notices"
+  tags: [API, documentation, versioning, changelog, deprecation, migration, intermediate]
+
+state: {}
+
+trigger: |
+  Your API is releasing v2. Developers on v1 are confused:
+  - "What changed between v1 and v2?"
+  - "Will v1 stop working? When?"
+  - "How do I migrate? What code do I need to change?"
+  - "The changelog just says 'improvements' — that's useless"
+
+  Changes from v1 to v2:
+  - User object: "name" split into "first_name" and "last_name"
+  - Pagination: offset/limit → cursor-based
+  - Auth: API key deprecated → OAuth 2.0 required
+  - New: webhook events for user.created, user.deleted
+  - Removed: GET /api/v1/users/search (merged into GET /users?q=)
+  - Rate limits: increased from 100/min to 1000/min
+
+  Task: Write version documentation including: changelog format,
+  migration guide from v1 to v2, deprecation timeline for v1,
+  and versioning strategy documentation.
+
+assertions:
+  - type: llm_judge
+    criteria: "Changelog is specific and actionable — each entry categorized: Added (new features), Changed (modifications), Deprecated (features being removed), Removed (features removed), Fixed (bug fixes), Security (vulnerability fixes). Each entry is specific: not 'improvements' but 'Split User.name into first_name and last_name for better internationalization support'. Breaking changes clearly flagged with migration instructions. Date and version number for each release"
+    weight: 0.35
+    description: "Changelog format"
+  - type: llm_judge
+    criteria: "Migration guide shows before/after — for each breaking change: what it was in v1, what it is in v2, code example showing the change. Example: 'User name field: v1: { name: \"Jane Cooper\" } → v2: { first_name: \"Jane\", last_name: \"Cooper\" }. Action: split your name handling into first_name and last_name.' Pagination migration: show v1 request and v2 equivalent. Auth migration: step-by-step OAuth setup replacing API key. Each change has estimated effort (5 min, 30 min, 2 hours)"
+    weight: 0.35
+    description: "Migration guide"
+  - type: llm_judge
+    criteria: "Deprecation timeline and versioning strategy are clear — deprecation timeline: (1) today — v2 released, v1 deprecated, (2) 3 months — deprecation warnings in v1 responses (Sunset header), (3) 6 months — v1 read-only, (4) 12 months — v1 shutdown (returns 410 Gone). Versioning strategy: URL-based (/v1/, /v2/), major version = breaking changes only. Header: Sunset: Sat, 01 Mar 2027 00:00:00 GMT. Communication plan: email, dashboard banner, blog post, in-response headers"
+    weight: 0.30
+    description: "Deprecation timeline"

package/courses/api-documentation-writing/scenarios/level-3/advanced-documentation-shift.yaml

@@ -0,0 +1,43 @@
+meta:
+  id: advanced-documentation-shift
+  level: 3
+  course: api-documentation-writing
+  type: output
+  description: "Combined advanced shift — design complete developer documentation portal including real-time APIs, webhooks, SDKs, and migration guides for a growing platform"
+  tags: [API, documentation, combined, shift-simulation, portal, advanced]
+
+state: {}
+
+trigger: |
+  Your fintech platform is graduating from "startup API" to
+  "developer platform." You have 500 integrations and need
+  professional-grade documentation. Current state:
+
+  - REST API: 60 endpoints, OpenAPI spec exists but docs are basic
+  - WebSocket: real-time transaction feed, undocumented
+  - Webhooks: 15 event types, only 3 documented
+  - SDKs: Python and Node.js, README-only docs
+  - Migration: v1 → v2 happening in 3 months, no migration guide
+  - Sandbox: exists but undocumented
+  - Support tickets: 40% are "how do I..." questions the docs should answer
+
+  Task: Create the complete documentation plan and write the key
+  sections. Deliver: (1) information architecture for the full
+  developer portal, (2) complete webhook documentation for all 15
+  event types, (3) WebSocket getting started guide, (4) v1→v2
+  migration guide outline with the authentication migration section
+  written in full, and (5) SDK quick start for Python.
+
+assertions:
+  - type: llm_judge
+    criteria: "Information architecture covers the full platform — site map with sections: Getting Started (quickstart, sandbox, authentication), REST API Reference (grouped by resource), WebSocket API (connection, channels, events), Webhooks (setup, events, security, testing), SDKs (Python, Node.js — install, quick start, reference), Guides (migration v1→v2, best practices, common patterns), Changelog, Status. Each section: target audience, content type (tutorial/guide/reference), priority (must-have for launch vs nice-to-have). Navigation: global search, breadcrumbs, prev/next links. Content gap analysis: what's missing today vs what's needed. Timeline: which sections to write first based on support ticket analysis"
+    weight: 0.35
+    description: "Information architecture"
+  - type: llm_judge
+    criteria: "Webhook docs, WebSocket guide, and SDK quickstart are substantive — webhook documentation: all 15 event types with payload schemas, signature verification guide with code, retry behavior, testing tools. Not just a list — each event has trigger condition, payload example, and common use case. WebSocket guide: connection URL, authentication, subscribe to channels, handle events, reconnection strategy — a developer could connect after reading this. Python SDK quickstart: pip install, configure client, make first API call, handle errors — complete in under 5 minutes. Each section is actually written (not just outlined), with realistic code examples and real data"
+    weight: 0.35
+    description: "Key sections"
+  - type: llm_judge
+    criteria: "Migration guide section is complete and actionable — v1→v2 migration outline covers all breaking changes with timeline. Authentication migration section written in full: step-by-step from Basic Auth to OAuth 2.0, code before/after, how to get OAuth credentials, transition period (both methods work), testing strategy, rollback plan. Migration guide has: quick assessment (am I affected?), estimated effort per change, recommended migration order, verification checklist. Support reduction strategy: documentation addresses the top 10 support ticket categories, self-service troubleshooting for common issues, embedded feedback mechanism for docs"
+    weight: 0.30
+    description: "Migration and support"

package/courses/api-documentation-writing/scenarios/level-3/api-style-guide.yaml

@@ -0,0 +1,40 @@
+meta:
+  id: api-style-guide
+  level: 3
+  course: api-documentation-writing
+  type: output
+  description: "Create API style guide — establish consistent documentation standards for naming, formatting, examples, and tone across all API documentation"
+  tags: [API, documentation, style-guide, standards, consistency, naming, advanced]
+
+state: {}
+
+trigger: |
+  Your company has 12 microservices, each documented by a different team.
+  The inconsistencies are confusing developers:
+
+  - One API uses "userId", another "user_id", another "UserID"
+  - Some endpoints return { data: [...] }, others return bare arrays
+  - Error formats vary: { error: "msg" } vs { errors: [{...}] } vs { message: "msg" }
+  - Date formats: ISO 8601, Unix timestamps, "MM/DD/YYYY" strings
+  - Authentication: some use "Authorization: Bearer", others "X-API-Key"
+  - Some docs say "returns the user object", others show the full schema
+
+  Task: Write a comprehensive API documentation style guide that all teams
+  must follow. Cover: naming conventions, response envelope standards,
+  error format, data types, authentication patterns, example formatting,
+  and tone/voice guidelines. This will be the single source of truth for
+  documentation consistency.
+
+assertions:
+  - type: llm_judge
+    criteria: "Naming and formatting standards are precise — field naming: snake_case for JSON properties (user_id, created_at), kebab-case for URLs (/api/v1/user-profiles), camelCase prohibited with migration path for existing APIs. Resource naming: plural nouns for collections (/users, /payments), singular for actions (/users/{id}/activate). Consistent envelope: { data, meta, pagination } for collections, { data } for singles. Date/time: always ISO 8601 with timezone (2024-01-15T10:30:00Z). Currency: always integer cents with separate currency field. IDs: string type (not integer) to allow future format changes. Boolean fields: prefixed with is_ or has_ (is_active, has_subscription)"
+    weight: 0.35
+    description: "Naming standards"
+  - type: llm_judge
+    criteria: "Error format and documentation patterns are standardized — universal error format: { type (URL to error doc), code (machine-readable string), message (human-readable), details (array of field-level errors), request_id }. Every endpoint must document: summary (one line), description (detailed), authentication requirement, request parameters (with types, constraints, examples), response schema (with examples), error responses (specific to endpoint), rate limit info. Example format: always show curl + one SDK language, always use realistic (not foo/bar) data, always show both success and error cases. Tone: second person ('you'), active voice, present tense, no jargon without definition"
+    weight: 0.35
+    description: "Error and doc patterns"
+  - type: llm_judge
+    criteria: "Migration and enforcement strategies are practical — for existing inconsistent APIs: migration timeline (deprecate old patterns over 2 versions), backward compatibility strategy (accept both old and new naming during transition). Enforcement: linting rules (Spectral/openapi-lint) for OpenAPI specs, CI/CD checks that block merging non-compliant docs, templates for new endpoint documentation. Living document: version the style guide itself, changelog for style guide updates, exceptions process (request variance with justification). Review checklist: documentation review as part of PR process. Adoption: start with new APIs, migrate existing APIs by priority (most-used first)"
+    weight: 0.30
+    description: "Migration strategy"

package/courses/api-documentation-writing/scenarios/level-3/code-samples-multilang.yaml

@@ -0,0 +1,40 @@
+meta:
+  id: code-samples-multilang
+  level: 3
+  course: api-documentation-writing
+  type: output
+  description: "Write multi-language code samples — create consistent, tested code examples across Python, Node.js, curl, and other languages for API endpoints"
+  tags: [API, documentation, code-samples, multi-language, examples, curl, advanced]
+
+state: {}
+
+trigger: |
+  Your API documentation has code examples but only in curl. Developers
+  using Python, Node.js, Go, and Java feel unsupported. When you do add
+  examples, they're inconsistent:
+
+  - curl example creates a payment with amount: 2000
+  - Python example creates with amount: 5000
+  - Node.js example is missing error handling
+  - Go example uses a deprecated library
+  - Java example doesn't compile
+
+  Task: Write a code sample strategy and produce examples for the
+  "Create Payment" endpoint in curl, Python, Node.js, and Go. Each
+  example must: use identical parameters, include error handling,
+  follow language idioms, and be copy-paste runnable. Also document
+  your process for keeping examples consistent and tested.
+
+assertions:
+  - type: llm_judge
+    criteria: "Code examples are consistent and complete — all four languages (curl, Python, Node.js, Go) create the same payment: amount 2000, currency 'usd', customer_id 'cus_123', same metadata. Each example includes: import/setup, authentication, the API call, response handling, error handling. curl: shows -H headers, -d JSON body, response parsing with jq. Python: requests library with proper headers and json parameter. Node.js: fetch or axios with async/await. Go: net/http with proper JSON marshaling and error checking. All examples use the same sandbox URL and test API key (sk_test_...)"
+    weight: 0.35
+    description: "Consistent examples"
+  - type: llm_judge
+    criteria: "Language idioms are respected — Python: use requests.post() not urllib, use f-strings for interpolation, snake_case variables, proper exception handling with requests.exceptions. Node.js: async/await (not callbacks or .then()), destructuring, const/let (not var), proper try/catch. Go: proper error checking (if err != nil), defer resp.Body.Close(), json.NewDecoder, no panic in examples. curl: proper quoting, -X POST, -H for headers, -d for body, show piping to jq for readable output. Each feels like code a native developer would write, not a translation from another language"
+    weight: 0.35
+    description: "Language idioms"
+  - type: llm_judge
+    criteria: "Testing and maintenance strategy is documented — how to keep examples in sync: (1) single source of truth for parameter values (YAML/JSON config file), (2) code generation from templates or automated testing that runs each example against sandbox, (3) CI/CD that tests examples on every API change. Recommend x-codeSamples OpenAPI extension for embedding in spec. Version management: examples tagged with API version, updated when API changes. Contribution guide: how to add a new language. Common mistakes to avoid: hardcoded URLs (use variables), missing error handling, using deprecated APIs, not showing response parsing. Review checklist for code examples"
+    weight: 0.30
+    description: "Testing strategy"

package/courses/api-documentation-writing/scenarios/level-3/content-architecture.yaml

@@ -0,0 +1,47 @@
+meta:
+  id: content-architecture
+  level: 3
+  course: api-documentation-writing
+  type: output
+  description: "Design documentation content architecture — organize API docs into reference, guides, tutorials, and concepts with clear navigation and information hierarchy"
+  tags: [API, documentation, content-architecture, information-design, navigation, advanced]
+
+state: {}
+
+trigger: |
+  Your API documentation is a single long page with everything mixed
+  together — endpoint reference, tutorials, conceptual explanations,
+  and authentication setup all jumbled. Developers can't find what they
+  need:
+
+  - New developers want a tutorial to get started
+  - Experienced developers want quick endpoint reference
+  - Architects want to understand the API's design philosophy
+  - Support engineers want troubleshooting guides
+
+  Your content includes:
+  - 40 API endpoints across 8 resources
+  - Authentication (3 methods)
+  - Webhooks (12 event types)
+  - Rate limiting, pagination, error handling
+  - 5 integration guides (Shopify, WordPress, etc.)
+  - SDKs in 4 languages
+
+  Task: Design the information architecture for your API documentation.
+  Define content types, navigation structure, page templates, and the
+  user journey from first visit to production integration. Show how
+  different audiences find what they need.
+
+assertions:
+  - type: llm_judge
+    criteria: "Content types are clearly defined — four content types: (1) Tutorials — step-by-step learning paths for beginners ('Accept your first payment in 10 minutes'), task-oriented, sequential. (2) How-to Guides — goal-oriented for specific tasks ('Handle webhook failures'), assumes knowledge, practical. (3) Reference — comprehensive endpoint documentation, auto-generated from OpenAPI, organized by resource. (4) Concepts — explanatory content ('How authentication works', 'Understanding idempotency'), theory and architecture. Each type has a template showing required sections. Content is tagged by audience: beginner, intermediate, advanced. Diátaxis framework referenced or similar"
+    weight: 0.35
+    description: "Content types"
+  - type: llm_judge
+    criteria: "Navigation and information hierarchy serve different audiences — top-level navigation: Getting Started, Guides, API Reference, SDKs, Webhooks, Changelog. Getting Started: linear path from signup to first API call to production launch. API Reference: organized by resource (Payments, Customers, Subscriptions, Invoices) not alphabetically. Each resource page: overview, create, read, update, delete, list. Sidebar navigation: collapsible sections, current location highlighted, search prominent. Cross-linking: reference pages link to relevant guides, guides link to reference for details. Quick-find patterns: search, breadcrumbs, 'On this page' table of contents for long pages"
+    weight: 0.35
+    description: "Navigation design"
+  - type: llm_judge
+    criteria: "User journeys are mapped — journey 1 (new developer): landing page → quickstart → first API call → explore endpoints → production checklist. Journey 2 (experienced developer switching from competitor): migration guide → API reference → SDK setup → go live. Journey 3 (architect evaluating): concepts → authentication overview → rate limits → SLA/status page. Journey 4 (debugging): error code lookup → troubleshooting guide → support contact. Each journey has clear entry points and next-step links. Landing page serves as router directing each persona. 404 page suggests related content. Analytics: track which journeys are most common, where developers drop off"
+    weight: 0.30
+    description: "User journeys"

package/courses/api-documentation-writing/scenarios/level-3/deprecation-communication.yaml

@@ -0,0 +1,44 @@
+meta:
+  id: deprecation-communication
+  level: 3
+  course: api-documentation-writing
+  type: output
+  description: "Document API deprecation — write clear deprecation notices, sunset timelines, and communication plans that minimize developer disruption"
+  tags: [API, documentation, deprecation, sunset, lifecycle, communication, advanced]
+
+state: {}
+
+trigger: |
+  You need to deprecate several API features and communicate this to
+  developers without causing panic or confusion:
+
+  1. Entire endpoint removal: DELETE /users/{id}/avatar (replaced by
+     PATCH /users/{id} with avatar: null)
+  2. Field deprecation: "user.username" field being replaced by
+     "user.display_name" (different validation rules)
+  3. Authentication method sunset: Basic Auth being removed, only
+     OAuth 2.0 going forward
+  4. SDK version end-of-life: Python SDK v2.x, only v3.x supported
+  5. Response format change: XML response format being dropped, JSON only
+
+  Each has a different timeline and impact level. Some affect all
+  developers, others affect a small subset.
+
+  Task: Write deprecation documentation for all five items. Include:
+  deprecation notices, migration paths for each, timeline with key
+  dates, HTTP headers/response fields that signal deprecation, and
+  a communication plan (how developers are notified).
+
+assertions:
+  - type: llm_judge
+    criteria: "Each deprecation is documented with full lifecycle — for each item: (1) what is deprecated (specific endpoint/field/feature), (2) why (security, simplification, standards compliance), (3) replacement (exact alternative with code example), (4) timeline with four phases: announced → deprecated (still works, warnings) → sunset warning (rate-limited or degraded) → removed. Dates for each phase. HTTP signals: Deprecation header (RFC 8594), Sunset header with date, Warning header with human message. API response includes deprecation_warnings array when deprecated features are used. Documentation: deprecated items visually marked (strikethrough, warning banner) but still documented until removal"
+    weight: 0.35
+    description: "Deprecation lifecycle"
+  - type: llm_judge
+    criteria: "Migration paths are specific and actionable — endpoint removal: show curl before/after, explain that PATCH with null achieves the same result. Field deprecation: both fields returned during transition period, show how to update code to use new field, document different validation rules between old and new. Basic Auth sunset: step-by-step OAuth 2.0 setup guide, tool to generate OAuth credentials from existing Basic Auth credentials. SDK EOL: changelog of breaking changes between v2→v3, automated upgrade tool or codemods if available, v2 receives security patches only during transition. XML removal: show Content-Type/Accept header changes, library migration for XML parsers"
+    weight: 0.35
+    description: "Migration paths"
+  - type: llm_judge
+    criteria: "Communication plan covers all channels — notification channels: (1) email to registered developers (personalized: 'Your integration uses Basic Auth, which sunsets on DATE'), (2) dashboard banner, (3) changelog entry, (4) API response headers on affected requests, (5) status page announcement, (6) developer blog post explaining the reasoning. Cadence: initial announcement, then reminders at 6 months, 3 months, 1 month, 1 week before sunset. Metrics: track adoption of replacements, identify developers who haven't migrated, offer direct support to high-impact integrations. Escalation: what happens after sunset — hard failure (401/410) with helpful error message pointing to migration docs, not silent data loss"
+    weight: 0.30
+    description: "Communication plan"