dojo.md 0.2.1 → 0.2.3

package/courses/GENERATION_LOG.md

@@ -513,3 +513,23 @@ Tracks all auto-generated courses for dojo.md.
 - **Scenarios**: 50 (10 per level × 5 levels)
 - **Type**: output
 - **Sources**: AWS Lambda documentation (lifecycle, invocation types, event sources, VPC, layers, extensions), AWS SAM/CDK documentation, API Gateway docs, CloudWatch/X-Ray monitoring, Step Functions workflow docs, DynamoDB Streams, SQS/SNS/EventBridge, Kinesis Data Streams, Lambda Powertools (Python/TypeScript/Java), AWS Well-Architected Serverless Lens, DORA metrics research
+
+---
+
+## Course 53: Terraform Infrastructure Setup
+- **Generated**: 2026-02-27
+- **Category**: Development & DevOps
+- **Directory**: `courses/terraform-infrastructure-setup/`
+- **Topics researched**: terraform init errors (backend initialization, provider installation, module download, registry connectivity, proxy/air-gapped), HCL syntax errors (block structure, attribute assignment, string interpolation, terraform fmt canonical format), provider configuration (AWS credential chain, provider aliases, multi-region, assume_role, OIDC), variables and outputs (types, validation blocks, value precedence, tfvars, TF_VAR_, sensitive), resource creation failures (dependency graph, partial apply, duplicate resources, permissions, quotas), state file basics (JSON mapping, drift detection, refresh, locking, local vs remote), plan output reading (symbols +/-/~/−/+, forces replacement, known after apply, detailed-exitcode), resource references (implicit/explicit dependencies, circular dependencies, data sources, splat expressions), terraform fmt and validate (formatting enforcement, CI/CD pre-commit hooks, TFLint), module structure (inputs/outputs contracts, local/registry/git sources, composition patterns), remote state backend (S3+DynamoDB setup, state migration, locking mechanics, terraform_remote_state), count vs for_each (index shift problems, stable keys, moved blocks migration), lifecycle rules (create_before_destroy, prevent_destroy, ignore_changes, replace_triggered_by), terraform import (import workflow, import blocks 1.5+, generate-config-out, terraformer), workspace management (workspace isolation, terraform.workspace variable, directory-based alternative), provisioner pitfalls (local-exec/remote-exec, taint on failure, user_data/Packer/Ansible alternatives), locals and expressions (common tags, for expressions, conditionals, built-in functions), dependency management (DAG, implicit/explicit, depends_on, terraform graph), state surgery (state mv, state rm, pull/push, moved blocks, module extraction), multi-provider config (aliases, assume_role, cross-account, provider passing to modules), dynamic blocks (for_each iteration, nested dynamics, iterator naming, over-engineering warnings), Terraform Cloud/Enterprise (remote execution, VCS integration, Sentinel policies, migration), drift detection (refresh-only, selective handling, continuous detection, prevention), conditional resources (count ternary, for_each conditional, safe referencing, feature flags), TF_LOG debugging (TRACE/DEBUG/INFO/WARN/ERROR, provider-specific, crash logs), large-scale refactoring (monolith to modules, state splitting, moved blocks, phased migration), API rate limiting (throttling, parallelism reduction, state splitting, quota increases), IaC organization strategy (mono-repo vs multi-repo, state architecture, team ownership, governance), CI/CD pipeline design (GitOps, Atlantis, GitHub Actions, Terraform Cloud, Spacelift), infrastructure testing (terraform test 1.6+, Terratest, checkov, tfsec, testing pyramid), multi-account strategy (AWS Organizations, account vending, SCPs, cross-account IAM), cost estimation governance (Infracost, policy-based controls, environment sizing, tagging), compliance as code (SOC2/HIPAA/PCI-DSS enforcement, Sentinel, checkov, AWS Config), module registry design (private registry, versioning, testing requirements, consumption governance), blast radius management (state boundaries, change classification, approval workflows, recovery), incident response IaC (rollback strategies, emergency procedures, post-incident reconciliation), enterprise IaC transformation (phased adoption, champion teams, enablement, governance balance), Terraform vs alternatives (Pulumi/CDK/CloudFormation/OpenTofu evaluation, migration paths), platform engineering (self-service, golden paths, Backstage, developer experience), board infrastructure investment (ROI analysis, competitive positioning, executive narrative), multi-cloud strategy (per-cloud modules, state per cloud, team upskilling, realism check), M&A infrastructure consolidation (phased migration, account structure, state migration, team onboarding), regulatory compliance automation (framework mapping, policy enforcement, evidence generation, audit prep), disaster recovery IaC (multi-region, state backup, DR testing, cost optimization), IaC technology evolution (AI-assisted, ephemeral environments, platform engineering, hype vs reality), fractional CTO advisory (phased roadmap, hiring, compliance sprint, Series C readiness)
+- **Scenarios**: 50 (10 per level × 5 levels)
+- **Type**: output
+- **Sources**: HashiCorp Terraform documentation (CLI commands, language, backends, providers), Terraform Cloud/Enterprise docs, Spacelift blog (best practices, comparisons), AWS provider documentation, Sentinel policy language, Terratest documentation, checkov/tfsec scanning tools, Infracost documentation, OpenTofu project, Atlantis documentation, platform engineering resources, IaC maturity models
+
+### Course 54: API Documentation Writing
+- **Generated**: 2026-02-27
+- **Category**: Writing & Communication
+- **Directory**: `courses/api-documentation-writing/`
+- **Topics researched**: endpoint descriptions (method, path, summary, detailed descriptions), HTTP status codes (2xx success, 4xx client errors, 5xx server errors, error bodies), request parameters (path vs query vs header, required/optional, types), request/response examples (realistic values, multiple scenarios, edge cases), authentication documentation (API keys, Bearer tokens, OAuth quickstart), getting started guides (TTFC optimization, 5-minute quickstart, sandbox), data types and formats (ISO 8601 dates, E.164 phone, cents for currency, pagination cursors), pagination documentation (offset vs cursor, response structure, navigation), error documentation (consistent schemas, error codes, troubleshooting), OpenAPI 3.1 specification (paths, components, $ref, info, servers), schema definitions (allOf composition, oneOf discriminator, nested objects, nullable), OAuth 2.0 documentation (authorization code, client credentials, PKCE, token refresh), versioning and changelog (URL vs header versioning, deprecation timeline, migration guides), error patterns (unified format, error code catalog, error type URLs), rate limiting docs (tiers, headers, exponential backoff, jitter, best practices), request body schemas (POST/PUT/PATCH differences, null handling, nested object behavior), Swagger UI vs Redoc (setup, comparison, customization, rendering tips), validation documentation (regex patterns, conditional rules, client-side guidance), API style guides (naming conventions, response envelopes, consistency standards), webhook documentation (event catalog, HMAC-SHA256 verification, retry behavior, idempotency), SDK documentation (language-idiomatic setup, error handling, pagination helpers, testing), multi-language code samples (consistency, language idioms, testing strategy), content architecture (Diátaxis framework, tutorials vs guides vs reference vs concepts), migration guides (change catalog, step-by-step migration, compatibility helpers), deprecation communication (lifecycle phases, HTTP headers, notification channels), interactive API explorer (sandbox, parameter forms, code generation), WebSocket and SSE documentation (connection lifecycle, message formats, reconnection), docs-as-code workflow (Git-based docs, CI/CD pipeline, automated quality checks), API governance standards (documentation tiers, quality scoring, adoption strategy), developer portal design (self-service onboarding, API key management, usage dashboard), documentation testing (contract tests, example validation, link checking, monitoring), documentation metrics (TTFC, task completion, support deflection, ROI calculation), multi-audience documentation (progressive disclosure, persona routing, content layering), API product strategy (self-service revenue, partner acceleration, enterprise packages), documentation localization (translation scope, workflow, synchronization, phased rollout), API changelog management (change categorization, notification system, automation), documentation program strategy (3-year vision, team growth, technology investments), DX as competitive advantage (competitive analysis, DX roadmap, community moat), API-first documentation (design-first process, internal-to-external transformation, change management), board API strategy (executive summary, financial model, risk of inaction), API marketplace documentation (provider standards, discovery features, quality scoring), ecosystem documentation (cross-product guides, extension builder docs, coordination model), documentation team structure (hybrid org model, role definitions, career ladder, retention), AI-powered documentation (honest AI assessment, enhancement strategy, risks and roadmap), industry documentation patterns (Stripe/Twilio/GitHub analysis, emerging trends, evaluation framework)
+- **Scenarios**: 50 (10 per level × 5 levels)
+- **Type**: output
+- **Sources**: OpenAPI Initiative (OAS 3.1 specification), Swagger UI documentation, Redoc documentation, Stripe API documentation (industry benchmark), Twilio documentation patterns, GitHub API documentation, Diátaxis documentation framework, RFC 8594 (Deprecation header), RFC 7396 (JSON Merge Patch), Spectral linting documentation, Dredd contract testing, Schemathesis API testing, Docusaurus/Nextra static site generators, developer experience research and best practices

package/courses/api-documentation-writing/course.yaml

@@ -0,0 +1,12 @@
+id: api-documentation-writing
+name: "API Documentation Writing"
+description: >
+  Master API documentation writing from basic endpoint descriptions
+  to enterprise developer portal strategy. Progress through OpenAPI
+  specifications, schema definitions, authentication documentation,
+  developer experience design, and organizational documentation
+  programs — the complete journey from writing your first endpoint
+  doc to leading API documentation strategy.
+levels: 5
+scenarios_per_level: 10
+tags: [writing, API, documentation, OpenAPI, developer-experience, technical-writing]

package/courses/api-documentation-writing/scenarios/level-1/authentication-basics.yaml

@@ -0,0 +1,46 @@
+meta:
+  id: authentication-basics
+  level: 1
+  course: api-documentation-writing
+  type: output
+  description: "Document authentication — write clear instructions for API key, Bearer token, and basic authentication with examples"
+  tags: [API, documentation, authentication, API-key, Bearer, authorization, beginner]
+
+state: {}
+
+trigger: |
+  New developers consistently fail their first API call because they
+  can't figure out authentication. Your current docs say:
+
+  "Authentication: This API uses Bearer tokens. Include your token
+  in the header."
+
+  Developer complaints:
+  - "Where do I get a token?"
+  - "What header exactly? What's the format?"
+  - "My token expired — how do I refresh it?"
+  - "Can I use an API key instead for server-to-server?"
+  - "I keep getting 401 — what's wrong?"
+
+  The API supports:
+  1. Bearer tokens (OAuth 2.0, expires in 1 hour, refresh token flow)
+  2. API keys (for server-to-server, passed in X-API-Key header)
+
+  Task: Write authentication documentation that enables developers
+  to successfully authenticate on their first try. Include: how to
+  get credentials, how to include them in requests, token lifecycle,
+  common authentication errors, and code examples.
+
+assertions:
+  - type: llm_judge
+    criteria: "Authentication methods are clearly documented — Bearer token: (1) how to get: POST /oauth/token with client_id, client_secret, grant_type. (2) how to use: Authorization: Bearer <token> header. (3) lifecycle: expires in 3600 seconds, use refresh_token to get new access_token. (4) example curl showing full auth flow. API key: (1) how to get: generate in dashboard Settings → API Keys. (2) how to use: X-API-Key: <key> header. (3) lifecycle: doesn't expire, can be revoked. (4) when to use: server-to-server communication, CI/CD, scripts"
+    weight: 0.35
+    description: "Auth methods"
+  - type: llm_judge
+    criteria: "Examples enable first-try success — step-by-step quickstart: (1) get credentials (curl to /oauth/token or dashboard screenshot). (2) make authenticated request (curl with Authorization header). (3) handle token expiry (curl to refresh). Full curl examples with actual headers. Code examples in at least one language (e.g., JavaScript fetch with headers). Common mistakes: forgetting 'Bearer ' prefix (just the token without 'Bearer'), using expired token, sending API key in wrong header, including token in query string (insecure)"
+    weight: 0.35
+    description: "First-try success"
+  - type: llm_judge
+    criteria: "Troubleshooting is included — 401 Unauthorized: token missing, expired, or malformed. Check: is 'Bearer ' prefix included? Is the token current? Is it the right token type? 403 Forbidden: token is valid but lacks permissions. Check: does the token have the required scope? Common auth errors table: symptom → cause → fix. Security notes: never include tokens in URLs (use headers), never log tokens, rotate API keys periodically, use short-lived tokens for client applications"
+    weight: 0.30
+    description: "Troubleshooting"

package/courses/api-documentation-writing/scenarios/level-1/data-types-formats.yaml

@@ -0,0 +1,45 @@
+meta:
+  id: data-types-formats
+  level: 1
+  course: api-documentation-writing
+  type: output
+  description: "Document data types and formats — describe JSON types, date formats, currency handling, enums, and nested objects clearly"
+  tags: [API, documentation, data-types, JSON, formats, schemas, beginner]
+
+state: {}
+
+trigger: |
+  Developers keep sending incorrectly formatted data to your API.
+  Common errors:
+  - Dates sent as "01/15/2024" instead of ISO 8601 "2024-01-15T00:00:00Z"
+  - Prices sent as "$19.99" instead of integer cents (1999)
+  - Booleans sent as "true" (string) instead of true (boolean)
+  - Phone numbers without country code
+  - UUIDs in wrong format
+
+  Your API accepts these field types:
+  - Strings: name, email, phone, URL, UUID
+  - Numbers: integer (count, cents), float (latitude, longitude)
+  - Booleans: is_active, is_verified
+  - Dates: created_at, due_date, expires_at
+  - Enums: status, role, priority
+  - Arrays: tags, permissions
+  - Nested objects: address, metadata
+
+  Task: Write data type documentation that prevents formatting errors.
+  For each type: specify the format, show valid/invalid examples,
+  and explain the rationale (e.g., why prices are in cents).
+
+assertions:
+  - type: llm_judge
+    criteria: "Each data type is precisely documented — strings: max length, format constraints (email: RFC 5322, phone: E.164 format +1234567890, UUID: v4 format). Numbers: integer for counts and money (in cents to avoid floating point issues), float for coordinates. Dates: ISO 8601 format (2024-01-15T10:30:00Z), always UTC, timezone specified. Booleans: JSON true/false (not strings). Enums: list all valid values with descriptions. Arrays: element type specified. Nested objects: full schema documented. Each type shows valid AND invalid examples"
+    weight: 0.35
+    description: "Precise types"
+  - type: llm_judge
+    criteria: "Format rationale is explained — money in cents: avoids floating point precision issues (19.99 * 100 can give 1998.9999... in floating point). Dates in ISO 8601 UTC: unambiguous, sortable, timezone-safe. Phone in E.164: international standard, parseable. UUID v4: globally unique, no sequential information leaked. These explanations help developers understand WHY and reduce questions. Show conversion examples: 'To convert $19.99 to API format: 19.99 * 100 = 1999'"
+    weight: 0.35
+    description: "Format rationale"
+  - type: llm_judge
+    criteria: "Null and optional handling are addressed — document: which fields can be null, what null means vs omitted (null = explicitly clear the value, omitted = don't change), empty string vs null (are they treated differently?). Required vs optional fields clearly marked. Default values documented: 'if is_active is omitted, defaults to true'. Array fields: can they be empty? What's the max length? Metadata object: is it schemaless? What are the limits (max keys, max value size)?"
+    weight: 0.30
+    description: "Null and optional"

package/courses/api-documentation-writing/scenarios/level-1/endpoint-description.yaml

@@ -0,0 +1,45 @@
+meta:
+  id: endpoint-description
+  level: 1
+  course: api-documentation-writing
+  type: output
+  description: "Write endpoint descriptions — document HTTP method, path, purpose, and usage for a REST API endpoint"
+  tags: [API, documentation, endpoints, REST, HTTP-methods, beginner]
+
+state: {}
+
+trigger: |
+  You're documenting a REST API for a task management application.
+  A developer gives you this information about an endpoint:
+
+  - It creates a new task
+  - URL: /api/v1/tasks
+  - Method: POST
+  - Needs authentication
+  - Request body: title (required), description (optional),
+    due_date (optional, ISO 8601), priority (optional: low/medium/high)
+  - Returns the created task with an ID
+  - Returns 201 on success
+
+  The developer's current "documentation" is just a Slack message:
+  "POST /tasks to make a new task, send JSON with title etc"
+
+  Task: Write proper endpoint documentation for this API endpoint.
+  Include: HTTP method and path, description, request body with field
+  descriptions and types, example request/response, status codes,
+  and authentication requirement. Also explain what makes good
+  endpoint documentation vs bad.
+
+assertions:
+  - type: llm_judge
+    criteria: "Endpoint documentation is complete — includes: (1) HTTP method and path: POST /api/v1/tasks, (2) clear one-line description of what the endpoint does ('Creates a new task in the authenticated user's task list'), (3) authentication: requires Bearer token, (4) request body: JSON object with field names, types, required/optional status, descriptions, and constraints (priority enum values). Example request with headers (Content-Type, Authorization) and JSON body. Example response (201 Created) with full task object including generated id, created_at timestamp"
+    weight: 0.35
+    description: "Complete documentation"
+  - type: llm_judge
+    criteria: "Examples are realistic and helpful — request example shows actual JSON with realistic values (not 'string' or 'example'). Response example shows the full object as the API actually returns it (including server-generated fields like id, created_at, updated_at, status). Headers included in examples. Multiple status codes documented: 201 (success), 400 (validation error with example error response), 401 (unauthorized), 422 (unprocessable entity). Each status code has a description of when it occurs"
+    weight: 0.35
+    description: "Realistic examples"
+  - type: llm_judge
+    criteria: "Good vs bad documentation is explained — bad: 'POST /tasks to make a new task' (no types, no examples, no error codes, ambiguous). Good: structured, includes every field with type and description, shows real examples, documents errors, explains authentication. Key principles: developers should be able to call the endpoint from documentation alone without guessing. Include: what parameters are required, what format dates should be in, what values enums accept, what the response looks like on success AND failure"
+    weight: 0.30
+    description: "Good vs bad"

package/courses/api-documentation-writing/scenarios/level-1/error-documentation.yaml

@@ -0,0 +1,45 @@
+meta:
+  id: error-documentation
+  level: 1
+  course: api-documentation-writing
+  type: output
+  description: "Document API errors — write helpful error descriptions, troubleshooting guides, and consistent error response schemas"
+  tags: [API, documentation, errors, troubleshooting, error-codes, beginner]
+
+state: {}
+
+trigger: |
+  Your API returns errors but developers can't figure out what went
+  wrong. Current error response:
+
+  ```json
+  { "error": "Something went wrong" }
+  ```
+
+  Developer feedback:
+  - "The error message doesn't tell me what I did wrong"
+  - "I got an error code 'E1042' — what does that mean?"
+  - "Different endpoints return errors in different formats"
+  - "Is there a list of all possible errors?"
+
+  You need to design and document a consistent error response format
+  and create an error reference guide.
+
+  Task: Design a standard error response format, document common
+  errors with troubleshooting steps, and create an error code
+  reference table. Show both the error schema documentation and
+  endpoint-specific error documentation.
+
+assertions:
+  - type: llm_judge
+    criteria: "Error response schema is consistent and informative — standard format: { 'error': { 'type': 'validation_error', 'code': 'INVALID_EMAIL', 'message': 'The email address is not valid', 'details': [{ 'field': 'email', 'message': 'Must be a valid email address', 'value': 'not-an-email' }], 'request_id': 'req_abc123', 'documentation_url': 'https://docs.api.com/errors/INVALID_EMAIL' } }. Each field explained: type (category), code (machine-readable), message (human-readable), details (field-level), request_id (for support), documentation_url (link to fix)"
+    weight: 0.35
+    description: "Error schema"
+  - type: llm_judge
+    criteria: "Error reference table is complete — categorized error codes: authentication errors (INVALID_TOKEN, TOKEN_EXPIRED, MISSING_AUTH), validation errors (INVALID_EMAIL, REQUIRED_FIELD, INVALID_FORMAT), resource errors (NOT_FOUND, ALREADY_EXISTS, CONFLICT), rate limiting (RATE_LIMITED), server errors (INTERNAL_ERROR, SERVICE_UNAVAILABLE). Each error: code, HTTP status, description, common causes, fix. Table format for quick scanning. Error codes are stable (won't change between API versions)"
+    weight: 0.35
+    description: "Error reference"
+  - type: llm_judge
+    criteria: "Troubleshooting guidance is developer-friendly — for each common error: (1) what you sent (example bad request), (2) what you got back (error response), (3) what to fix (specific action). Example: 'INVALID_EMAIL — You sent email: \"john@\" — email must include domain: email: \"john@example.com\"'. Per-endpoint error docs: list which errors each endpoint can return. Encourage developers to log request_id for support escalation. SDK error handling example: try/catch with error type checking"
+    weight: 0.30
+    description: "Troubleshooting"

package/courses/api-documentation-writing/scenarios/level-1/first-documentation-shift.yaml

@@ -0,0 +1,47 @@
+meta:
+  id: first-documentation-shift
+  level: 1
+  course: api-documentation-writing
+  type: output
+  description: "Combined beginner shift — document a complete API endpoint set for a simple CRUD resource from scratch"
+  tags: [API, documentation, combined, shift-simulation, CRUD, beginner]
+
+state: {}
+
+trigger: |
+  You're the new technical writer. Day one task: document the /users
+  CRUD API endpoints. The developer hands you this list:
+
+  GET    /api/v1/users          — list all users (paginated)
+  POST   /api/v1/users          — create a user
+  GET    /api/v1/users/{id}     — get one user
+  PUT    /api/v1/users/{id}     — update a user
+  DELETE /api/v1/users/{id}     — delete a user
+
+  User object: id (UUID), name (string), email (string, unique),
+  role (admin/member), is_active (boolean), created_at, updated_at
+
+  Auth: Bearer token required for all endpoints.
+  Admin-only: POST, PUT, DELETE.
+
+  Constraints: name 1-100 chars, email must be valid, role enum.
+
+  You have no existing documentation to work from.
+
+  Task: Write complete API documentation for all 5 CRUD endpoints.
+  Include: endpoint descriptions, parameters, request/response
+  examples, status codes, authentication, and permissions.
+
+assertions:
+  - type: llm_judge
+    criteria: "All 5 endpoints are fully documented — each endpoint has: method + path, description, authentication (Bearer token), permissions (who can call it), parameters (path, query, body as applicable), request example (for POST/PUT), response example with realistic data, status codes (success + relevant errors). GET /users includes pagination parameters. POST includes request body schema. GET /{id} shows single resource response. PUT shows partial update behavior. DELETE shows 204 No Content response"
+    weight: 0.35
+    description: "Complete coverage"
+  - type: llm_judge
+    criteria: "Documentation is consistent across endpoints — same user object shape in all responses. Same error format for all endpoints. Same authentication pattern documented once and referenced. Consistent naming (id vs user_id — pick one). Examples use the same user across endpoints (create Jane Cooper → get Jane Cooper → update Jane Cooper → delete). Status codes consistent: 200 for GET/PUT, 201 for POST, 204 for DELETE, 404 for non-existent resources"
+    weight: 0.35
+    description: "Consistency"
+  - type: llm_judge
+    criteria: "Documentation is usable by a new developer — a developer who has never used the API can: (1) authenticate (auth docs included), (2) create a user (POST with example body), (3) list users with pagination, (4) get a specific user by ID, (5) update user fields, (6) delete a user. All from the documentation alone. Includes curl examples for each endpoint. Notes: DELETE returns 204 (no body), PUT with unchanged fields is idempotent, listing returns paginated results"
+    weight: 0.30
+    description: "Usability"

package/courses/api-documentation-writing/scenarios/level-1/getting-started-guide.yaml

@@ -0,0 +1,42 @@
+meta:
+  id: getting-started-guide
+  level: 1
+  course: api-documentation-writing
+  type: output
+  description: "Write a getting started guide — create a quickstart that takes developers from zero to first successful API call in minutes"
+  tags: [API, documentation, getting-started, quickstart, onboarding, beginner]
+
+state: {}
+
+trigger: |
+  Your API has comprehensive reference documentation but developers
+  still struggle to get started. Analytics show:
+  - Average time to first API call: 45 minutes
+  - 60% of developers never make a second call
+  - Top search query: "how to get started"
+  - Support tickets: "I don't know where to begin"
+
+  The API is a payment processing API (like Stripe). Key flows:
+  1. Create account → get API key
+  2. Create a customer
+  3. Create a payment method
+  4. Charge the customer
+
+  Task: Write a getting started guide that takes a developer from
+  zero to their first successful payment in under 10 minutes.
+  Include: prerequisites, step-by-step instructions with curl
+  examples, expected output at each step, and next steps.
+
+assertions:
+  - type: llm_judge
+    criteria: "Guide has clear structure and flow — starts with: what you'll build (outcome), prerequisites (account, API key, curl/Postman), estimated time (10 minutes). Steps numbered and sequential: (1) get your API key, (2) make your first call (simple GET to verify auth works), (3) create a customer, (4) add a payment method, (5) charge the customer. Each step has: what you'll do, curl command, expected response, what to note from the response (e.g., 'save the customer_id for the next step')"
+    weight: 0.35
+    description: "Clear structure"
+  - type: llm_judge
+    criteria: "Examples are copy-paste ready — curl commands that work out of the box (just replace API key). Use test/sandbox mode API key (no real charges). Full command with headers, body, and expected output. Each step's output feeds into the next step (customer_id from step 3 used in step 4). Environment setup: 'export API_KEY=your_key_here' at the start, then reference $API_KEY in all commands. Highlight values that developers need to copy from one step to the next"
+    weight: 0.35
+    description: "Copy-paste ready"
+  - type: llm_judge
+    criteria: "Onboarding experience is optimized — progressive complexity: start with simplest possible call, add complexity gradually. Success validation at each step: 'You should see a response with status 200 and...' Troubleshooting inline: 'If you see 401, check that your API key is correct.' End with: what you built, next steps (link to specific guides for production setup, webhooks, error handling). Call to action: 'Ready for production? Read our Production Checklist.' Don't overwhelm: guide covers one happy path, not every option"
+    weight: 0.30
+    description: "Optimized onboarding"

package/courses/api-documentation-writing/scenarios/level-1/pagination-docs.yaml

@@ -0,0 +1,51 @@
+meta:
+  id: pagination-docs
+  level: 1
+  course: api-documentation-writing
+  type: output
+  description: "Document pagination — write clear pagination documentation for offset, cursor, and keyset pagination patterns"
+  tags: [API, documentation, pagination, offset, cursor, collections, beginner]
+
+state: {}
+
+trigger: |
+  Your API returns lists of resources (users, orders, transactions).
+  Developers ask:
+  - "How do I get the next page?"
+  - "How do I know if there are more results?"
+  - "The total count changes between pages — is that a bug?"
+  - "Cursor pagination? What's a cursor?"
+
+  Your API supports two pagination styles:
+  1. Offset pagination (legacy): ?page=2&per_page=20
+  2. Cursor pagination (recommended): ?after=cursor_abc123&limit=20
+
+  Response format (cursor):
+  ```json
+  {
+    "data": [...],
+    "pagination": {
+      "has_more": true,
+      "next_cursor": "cursor_def456",
+      "previous_cursor": "cursor_abc123"
+    }
+  }
+  ```
+
+  Task: Document both pagination styles, explain when to use each,
+  show step-by-step examples of paginating through results, and
+  explain the pagination response fields.
+
+assertions:
+  - type: llm_judge
+    criteria: "Both pagination styles are documented — offset: ?page=1&per_page=20 (page 1 of 20 results). Response includes total_count, total_pages, current_page. Pros: jump to any page. Cons: inconsistent with concurrent writes (items shift between pages). Cursor: ?after=<cursor>&limit=20. Response includes has_more, next_cursor. Pros: consistent results even with concurrent writes, better performance on large datasets. Cons: can't jump to page N. Recommendation: use cursor for real-time data (transactions, events), offset for stable data (reports)"
+    weight: 0.35
+    description: "Both styles"
+  - type: llm_judge
+    criteria: "Step-by-step pagination examples are shown — cursor example: (1) first page: GET /api/v1/orders?limit=20 → get data + next_cursor. (2) next page: GET /api/v1/orders?after=cursor_abc&limit=20 → get more data + next_cursor. (3) last page: has_more = false, no next_cursor. Complete curl commands for each step. Show how to implement a loop: 'keep fetching while has_more is true'. Offset example: page=1, page=2, etc. Show total_pages for loop termination"
+    weight: 0.35
+    description: "Step-by-step"
+  - type: llm_judge
+    criteria: "Edge cases and best practices are covered — empty results: data is empty array, has_more is false. Rate limiting: respect rate limits when paginating (don't blast all pages at once). Maximum limit value documented (e.g., limit max 100). Default limit documented (e.g., 20). Invalid cursor: returns 400 with clear error message. Sorting: document whether sort order affects pagination. Filter + paginate: show example combining filters with pagination. Total count: may be expensive to compute on cursor pagination (document whether it's available)"
+    weight: 0.30
+    description: "Edge cases"

package/courses/api-documentation-writing/scenarios/level-1/request-parameters.yaml

@@ -0,0 +1,46 @@
+meta:
+  id: request-parameters
+  level: 1
+  course: api-documentation-writing
+  type: output
+  description: "Document request parameters — differentiate and document path parameters, query parameters, headers, and request body fields"
+  tags: [API, documentation, parameters, query, path, headers, beginner]
+
+state: {}
+
+trigger: |
+  A developer is confused by your API because parameter documentation
+  is unclear. They're trying to call this endpoint:
+
+  GET /api/v1/projects/{project_id}/tasks?status=active&sort=due_date&limit=20
+
+  Headers:
+  Authorization: Bearer <token>
+  Accept: application/json
+  X-Request-ID: <uuid>
+
+  Their questions:
+  - "Do I put project_id in the URL or as a query parameter?"
+  - "Is 'status' a path param or query param?"
+  - "What values can 'sort' accept?"
+  - "Is limit required? What's the default?"
+  - "What headers do I need?"
+
+  Task: Write clear parameter documentation that distinguishes between
+  path parameters, query parameters, and headers. Include: parameter
+  name, location (path/query/header), type, required/optional, default
+  value, description, valid values, and examples.
+
+assertions:
+  - type: llm_judge
+    criteria: "Parameter types are clearly distinguished — path parameters: project_id (in URL path, required, string/UUID, identifies the project). Query parameters: status (optional, string, enum: active/completed/archived, default: all), sort (optional, string, enum: due_date/created_at/priority, default: created_at), limit (optional, integer, range: 1-100, default: 20), offset or page for pagination. Headers: Authorization (required, Bearer token), Accept (optional, default: application/json), X-Request-ID (optional, UUID for request tracing). Each parameter location is explicitly labeled"
+    weight: 0.35
+    description: "Parameter types"
+  - type: llm_judge
+    criteria: "Documentation format is scannable — table or structured list format with columns: name, location, type, required, default, description. Each parameter has constraints documented (enum values, min/max, format). Example full URL shown: GET /api/v1/projects/550e8400-e29b-41d4-a716-446655440000/tasks?status=active&sort=due_date&limit=20. Curl example with all parameters including headers. Response shows how parameters affect the result (filtered by status, sorted by due_date, limited to 20)"
+    weight: 0.35
+    description: "Scannable format"
+  - type: llm_judge
+    criteria: "Common parameter patterns are explained — path parameters: identify specific resources (always required, part of the URL). Query parameters: filter, sort, paginate collections (usually optional with defaults). Headers: authentication, content negotiation, request tracking. Body parameters: create/update data (POST, PUT, PATCH only). Never mix: don't send the same data as both query parameter and body field. Document default behavior when optional params are omitted. Document parameter encoding (URL encoding for special characters in query params)"
+    weight: 0.30
+    description: "Parameter patterns"

package/courses/api-documentation-writing/scenarios/level-1/request-response-examples.yaml

@@ -0,0 +1,48 @@
+meta:
+  id: request-response-examples
+  level: 1
+  course: api-documentation-writing
+  type: output
+  description: "Write request/response examples — create realistic JSON examples with proper formatting, annotations, and edge cases"
+  tags: [API, documentation, examples, JSON, request, response, beginner]
+
+state: {}
+
+trigger: |
+  Your API documentation has examples like this:
+
+  ```
+  Request:
+  { "name": "string", "email": "string", "age": 0 }
+
+  Response:
+  { "id": "string", "name": "string", "email": "string" }
+  ```
+
+  Developers complain: "These examples are useless. I don't know what
+  format the email should be, what a realistic age looks like, or what
+  the actual ID format is."
+
+  The endpoint is: POST /api/v1/users (create a new user)
+  Fields: name (string, 1-100 chars), email (string, valid email),
+  age (integer, 13-120), role (enum: admin/member/viewer),
+  avatar_url (string, optional, URL), metadata (object, optional)
+
+  Task: Rewrite the examples with realistic values, proper formatting,
+  multiple scenarios (success, validation error, conflict), and
+  annotations explaining notable fields. Explain principles of
+  writing good API examples.
+
+assertions:
+  - type: llm_judge
+    criteria: "Examples use realistic values — instead of 'string' and 0, use actual values: name = 'Jane Cooper', email = 'jane@example.com', age = 28, role = 'member'. ID format shown realistically (UUID or sequential). Timestamps in ISO 8601. URLs as proper URLs. Response includes server-generated fields (id, created_at, updated_at). Multiple examples: (1) minimal request (only required fields), (2) full request (all fields including optional), (3) error response (validation failure with specific field errors)"
+    weight: 0.35
+    description: "Realistic values"
+  - type: llm_judge
+    criteria: "Multiple scenarios are documented — success case: 201 Created with full response. Validation error: 422 with details array showing which fields failed (e.g., 'age must be at least 13'). Conflict: 409 when email already exists. Each scenario shows both the request that triggers it and the exact response. Annotations: comments or callouts explaining non-obvious fields (e.g., 'id is a UUID v4 generated by the server', 'created_at is in UTC', 'metadata is a free-form JSON object')"
+    weight: 0.35
+    description: "Multiple scenarios"
+  - type: llm_judge
+    criteria: "Example writing principles are explained — (1) use realistic data, not placeholders (developers copy-paste examples). (2) show the complete request including headers (Content-Type, Authorization). (3) show complete response, not truncated. (4) include curl command for easy testing. (5) show both happy path and error paths. (6) annotate non-obvious fields (format, constraints, behavior). (7) keep examples consistent (same user across related endpoints). (8) don't use 'foo', 'bar', 'test' — use domain-appropriate data"
+    weight: 0.30
+    description: "Writing principles"

package/courses/api-documentation-writing/scenarios/level-1/status-codes.yaml

@@ -0,0 +1,45 @@
+meta:
+  id: status-codes
+  level: 1
+  course: api-documentation-writing
+  type: output
+  description: "Document HTTP status codes — write clear descriptions for success, client error, and server error responses with example bodies"
+  tags: [API, documentation, status-codes, errors, HTTP, beginner]
+
+state: {}
+
+trigger: |
+  Your API returns various status codes but the documentation just
+  lists "200 OK" and "400 Bad Request" with no details. Developers
+  keep asking support questions like:
+
+  - "What's the difference between 401 and 403?"
+  - "Why am I getting a 409? What does it mean?"
+  - "The API returned 422 — what field is wrong?"
+  - "I got a 429 — when can I retry?"
+  - "What does the error response body look like?"
+
+  The API uses these status codes:
+  200 (OK), 201 (Created), 204 (No Content), 400 (Bad Request),
+  401 (Unauthorized), 403 (Forbidden), 404 (Not Found),
+  409 (Conflict), 422 (Unprocessable Entity), 429 (Too Many Requests),
+  500 (Internal Server Error), 503 (Service Unavailable)
+
+  Task: Write comprehensive status code documentation for this API.
+  For each code: explain when it's returned, show an example response
+  body, and provide guidance on how developers should handle it.
+  Also document the standard error response format.
+
+assertions:
+  - type: llm_judge
+    criteria: "Status codes are accurately documented — each code has: when it's returned (specific scenario), example response body, developer guidance. Key distinctions: 401 (authentication failed — invalid/missing token) vs 403 (authorized but not permitted — lacks required role/permission). 400 (malformed request, wrong types) vs 422 (valid JSON but business logic validation failed — e.g., invalid email format). 409 (resource conflict — e.g., duplicate email). 429 (rate limited — include Retry-After header guidance). 204 for successful DELETE (no body). 201 for successful POST (returns created resource)"
+    weight: 0.35
+    description: "Accurate codes"
+  - type: llm_judge
+    criteria: "Error response format is standardized — consistent error response structure documented: { 'error': { 'code': 'VALIDATION_ERROR', 'message': 'Human-readable description', 'details': [{ 'field': 'email', 'message': 'Invalid email format' }] } }. Machine-readable error codes (not just HTTP status) enable programmatic error handling. The details array helps developers identify which specific field(s) failed validation. Document that 5xx errors use the same format but with less detail (don't expose internals)"
+    weight: 0.35
+    description: "Error format"
+  - type: llm_judge
+    criteria: "Developer guidance is actionable — for each error: what to do. 401: check token is valid, not expired, included in Authorization header. 403: check user has required permissions/role. 404: verify resource ID exists. 409: handle conflict (e.g., show 'email already taken' to user). 422: parse details array to show field-level errors. 429: respect Retry-After header, implement exponential backoff. 500: retry with backoff, report to API provider if persistent. 503: service temporarily unavailable, retry after delay"
+    weight: 0.30
+    description: "Developer guidance"

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

@@ -0,0 +1,48 @@
+meta:
+  id: error-patterns
+  level: 2
+  course: api-documentation-writing
+  type: output
+  description: "Document error response patterns — design and document consistent error schemas with machine-readable codes, field-level details, and troubleshooting links"
+  tags: [API, documentation, errors, error-codes, patterns, consistency, intermediate]
+
+state: {}
+
+trigger: |
+  Your API has inconsistent error responses across endpoints:
+
+  Endpoint A returns:
+  ```json
+  { "error": "Invalid email" }
+  ```
+
+  Endpoint B returns:
+  ```json
+  { "code": 422, "errors": [{ "field": "email", "msg": "bad format" }] }
+  ```
+
+  Endpoint C returns:
+  ```json
+  { "status": "error", "reason": "email_invalid" }
+  ```
+
+  Developers can't write generic error handling because every endpoint
+  is different. You need to design and document a unified error pattern.
+
+  Task: Design a standard error response format and document it
+  comprehensively. Include: error schema, error code catalog,
+  per-endpoint error documentation, and SDK error handling examples.
+
+assertions:
+  - type: llm_judge
+    criteria: "Standard error format is designed — consistent structure: { 'error': { 'type': 'validation_error' (category), 'code': 'INVALID_EMAIL' (machine-readable, stable), 'message': 'The email address format is invalid' (human-readable, may change), 'param': 'email' (which parameter caused the error), 'documentation_url': 'https://docs.api.com/errors/INVALID_EMAIL' (link to detailed docs) } }. For validation errors with multiple fields: 'details' array with per-field errors. HTTP status code in response, error code for programmatic handling"
+    weight: 0.35
+    description: "Error format"
+  - type: llm_judge
+    criteria: "Error code catalog is organized — categories: authentication_error (INVALID_TOKEN, TOKEN_EXPIRED, MISSING_AUTH), validation_error (REQUIRED_FIELD, INVALID_FORMAT, OUT_OF_RANGE), resource_error (NOT_FOUND, ALREADY_EXISTS, CONFLICT, GONE), rate_limit_error (RATE_EXCEEDED), payment_error (INSUFFICIENT_FUNDS, CARD_DECLINED, EXPIRED_CARD), server_error (INTERNAL_ERROR, SERVICE_UNAVAILABLE). Each code: stable identifier (won't change), HTTP status, description, common causes, how to handle. Error codes are part of the API contract — adding new ones is non-breaking, removing is breaking"
+    weight: 0.35
+    description: "Error catalog"
+  - type: llm_judge
+    criteria: "Per-endpoint and SDK documentation are practical — each endpoint documents which error codes it can return (not every endpoint returns every error). SDK error handling example: try { await api.createPayment(data) } catch (err) { if (err.code === 'CARD_DECLINED') { showMessage('Card declined, try another') } else if (err.type === 'validation_error') { showFieldErrors(err.details) } }. Type-based handling (validation_error → show form errors) vs code-based handling (CARD_DECLINED → specific action). Anti-pattern: don't match on message strings (they change)"
+    weight: 0.30
+    description: "SDK integration"

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

@@ -0,0 +1,48 @@
+meta:
+  id: intermediate-documentation-shift
+  level: 2
+  course: api-documentation-writing
+  type: output
+  description: "Combined intermediate shift — write complete OpenAPI spec with authentication, error patterns, and versioning for a payment API"
+  tags: [API, documentation, combined, shift-simulation, OpenAPI, intermediate]
+
+state: {}
+
+trigger: |
+  You're writing the complete documentation for a new payments API
+  launching next month. You need to deliver:
+
+  1. OpenAPI 3.1 spec for 4 endpoints:
+     - POST /payments (create payment)
+     - GET /payments/{id} (get payment)
+     - POST /payments/{id}/refund (refund payment)
+     - GET /payments (list payments, paginated)
+
+  2. Authentication: OAuth 2.0 client credentials
+
+  3. Error response format (consistent across all endpoints)
+
+  4. Rate limits: 100 req/min (standard), 1000 req/min (pro)
+
+  Payment object: id, amount (cents), currency, status
+  (pending/processing/succeeded/failed/refunded), customer_id,
+  payment_method_id, created_at, metadata
+
+  This is v1 launching alongside legacy v0 (deprecated in 6 months).
+
+  Task: Write the complete API documentation package including
+  all of the above, ready for developer consumption.
+
+assertions:
+  - type: llm_judge
+    criteria: "OpenAPI spec is complete for all 4 endpoints — POST /payments: request body schema with required fields, 201 response with payment object, errors (400, 401, 422). GET /payments/{id}: path parameter, 200 response, 404 error. POST /payments/{id}/refund: path parameter, optional amount in body (partial refund), errors (400, 404, 409 for already refunded). GET /payments: query parameters (status filter, customer_id filter, pagination with cursor), 200 response with paginated list. All endpoints: consistent error responses, auth required"
+    weight: 0.35
+    description: "Complete spec"
+  - type: llm_judge
+    criteria: "Auth, errors, and rate limits are documented — OAuth 2.0 client credentials: step-by-step to get token, example curl, token in Authorization header. Error format: consistent { type, code, message, param, documentation_url } across all endpoints. Error codes documented: INVALID_AMOUNT, PAYMENT_NOT_FOUND, ALREADY_REFUNDED, etc. Rate limits: headers documented, per-tier limits, 429 handling with Retry-After. All three cross-cutting concerns documented once and referenced, not repeated per endpoint"
+    weight: 0.35
+    description: "Cross-cutting docs"
+  - type: llm_judge
+    criteria: "Documentation is launch-ready — includes getting started section (5-minute quickstart), realistic examples for each endpoint, deprecation notice for v0 with timeline and migration guide, sandbox environment details (test API keys, test payment methods). A developer could integrate this API using only the documentation. Changelog entry for v1.0.0 launch. Status page link for uptime monitoring"
+    weight: 0.30
+    description: "Launch ready"