dojo.md 0.2.2 → 0.2.3

package/courses/api-documentation-writing/scenarios/level-3/interactive-api-explorer.yaml

@@ -0,0 +1,42 @@
+meta:
+  id: interactive-api-explorer
+  level: 3
+  course: api-documentation-writing
+  type: output
+  description: "Design interactive API explorer — create documentation for an interactive playground that lets developers test API calls directly from the docs"
+  tags: [API, documentation, interactive, playground, try-it-out, sandbox, advanced]
+
+state: {}
+
+trigger: |
+  Your API documentation is static — developers must switch between
+  reading docs and their terminal to test calls. You want to add an
+  interactive "Try it out" experience directly in the docs:
+
+  Requirements:
+  - Developers can make real API calls from the documentation page
+  - Sandbox environment with test data (pre-populated accounts, payments)
+  - Auto-fill authentication (sandbox API key) for logged-in developers
+  - Show request being constructed as developers fill in parameters
+  - Display formatted response with syntax highlighting
+  - Save and share request/response pairs
+  - Show equivalent curl/SDK code for any request built in the explorer
+
+  Task: Design and document the interactive API explorer experience.
+  Write the developer-facing documentation for using the explorer,
+  the sandbox environment setup guide, and the technical specification
+  for how the explorer generates code examples from interactions.
+
+assertions:
+  - type: llm_judge
+    criteria: "Explorer UX is fully documented — three-panel layout: (1) parameter input form (auto-populated from OpenAPI schema), (2) live request preview (curl command updating as parameters change), (3) response display (formatted JSON, status code, headers, timing). Authentication: sandbox key auto-injected for logged-in users, manual key input for others. Parameter inputs: dropdowns for enums, date pickers for dates, JSON editor for body. Validation: client-side validation before sending (required fields, format checks). History: recent requests saved per developer, shareable via URL. Request builder: clicking 'Send' makes real API call to sandbox, shows loading state, displays response"
+    weight: 0.35
+    description: "Explorer UX"
+  - type: llm_judge
+    criteria: "Sandbox environment is documented — pre-populated test data: 10 test customers, 50 test payments in various states, test webhook endpoint. Test credentials: publishable key (pk_test_...) and secret key (sk_test_...) per developer account. Sandbox limitations: no real charges, no real emails, data resets weekly (or on-demand). Test scenarios: special test values that trigger specific responses (amount 99999 triggers decline, customer_id 'cus_fail' triggers error). Sandbox vs production differences documented. How to create additional test data. Sandbox rate limits (more generous than production)"
+    weight: 0.35
+    description: "Sandbox docs"
+  - type: llm_judge
+    criteria: "Code generation from explorer is documented — after making a request, show equivalent code in: curl, Python, Node.js, Go, Java. Code is copy-paste ready with actual values from the request. 'Copy to clipboard' button for each language. Code includes error handling boilerplate. Option to generate a complete runnable script (with imports, auth setup, API call, response handling). Export options: save as Postman collection, import into Insomnia, generate SDK client code. Technical: code templates are Mustache/Handlebars with OpenAPI schema variables, maintained alongside API spec"
+    weight: 0.30
+    description: "Code generation"

package/courses/api-documentation-writing/scenarios/level-3/migration-guides.yaml

@@ -0,0 +1,42 @@
+meta:
+  id: migration-guides
+  level: 3
+  course: api-documentation-writing
+  type: output
+  description: "Write API migration guides — document breaking changes, provide step-by-step migration paths, and minimize developer friction during version upgrades"
+  tags: [API, documentation, migration, versioning, breaking-changes, upgrade, advanced]
+
+state: {}
+
+trigger: |
+  You're releasing API v2 with breaking changes from v1. 2,000 active
+  integrations need to migrate. The changes:
+
+  - Response envelope: { "user": {...} } → { "data": {...}, "meta": {...} }
+  - Pagination: offset/limit → cursor-based
+  - Authentication: API key in query param → Bearer token in header
+  - Field renames: "userName" → "user_name", "createdAt" → "created_at"
+  - Removed endpoints: GET /users/search (merged into GET /users with
+    query params)
+  - New required field: "idempotency_key" on all POST requests
+
+  Timeline: v1 deprecated now, sunset in 12 months.
+
+  Task: Write a comprehensive migration guide that walks developers
+  through upgrading from v1 to v2. Include: change catalog, migration
+  steps, code examples showing before/after, compatibility helpers,
+  and a testing strategy for the migration.
+
+assertions:
+  - type: llm_judge
+    criteria: "Change catalog is complete and categorized — every breaking change listed with: what changed, why it changed (business reason), impact level (high/medium/low), migration effort estimate. Categorized: (1) Authentication changes (API key → Bearer), (2) Response format changes (envelope, field renames), (3) Pagination changes (offset → cursor), (4) Endpoint changes (removed/merged), (5) New requirements (idempotency key). Each change has before/after code comparison. Impact assessment: which changes affect all integrations vs specific use cases. Quick reference table: v1 pattern → v2 pattern for scanning"
+    weight: 0.35
+    description: "Change catalog"
+  - type: llm_judge
+    criteria: "Migration steps are ordered and practical — recommended migration order: (1) Update authentication first (affects all requests), (2) Handle response envelope changes (wrap response parsing), (3) Update field names (find/replace with mapping), (4) Switch pagination (may require storage schema changes), (5) Update removed endpoints, (6) Add idempotency keys. Each step: code example (before → after), common pitfalls, how to test this step in isolation, rollback strategy if something breaks. Compatibility helpers: v1-compat middleware/SDK option that translates v2 responses to v1 format (temporary bridge). Dual-write period: send to both v1 and v2, compare responses"
+    weight: 0.35
+    description: "Migration steps"
+  - type: llm_judge
+    criteria: "Timeline and testing strategy enable safe migration — timeline: v1 deprecated now (no new features), v1 supported 12 months, monthly email reminders at 9/6/3/1 months, dashboard showing v1 usage per integration. Testing: sandbox environment with v2, migration verification endpoint (POST /v2/migration/verify — tests your integration against v2), automated compatibility checker that scans your code for v1 patterns. Monitoring: dashboard showing v1 vs v2 request ratio, per-endpoint migration status. Support: dedicated migration support channel, office hours for complex migrations, case studies of successful migrations. FAQ: address common migration fears (data loss, downtime, partial migration)"
+    weight: 0.30
+    description: "Timeline and testing"

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

@@ -0,0 +1,40 @@
+meta:
+  id: sdk-documentation
+  level: 3
+  course: api-documentation-writing
+  type: output
+  description: "Document SDK libraries — write SDK documentation that bridges REST API docs and language-idiomatic client libraries with installation, configuration, and usage patterns"
+  tags: [API, documentation, SDK, client-library, language-specific, advanced]
+
+state: {}
+
+trigger: |
+  Your API has official SDKs in Python, Node.js, Go, and Java. But the
+  SDK documentation is just auto-generated from code comments. Developers
+  complain:
+
+  - "The Python SDK docs are just a class list — where's the getting started?"
+  - "How do I configure retries? The REST docs mention it but the SDK docs don't"
+  - "Is the Node.js SDK async? Do I use callbacks or promises?"
+  - "The Go SDK returns errors differently than I expected"
+  - "How do I mock the SDK for testing?"
+
+  Task: Write SDK documentation for the Python and Node.js clients that
+  goes beyond auto-generated API reference. Include: installation,
+  configuration (auth, retries, timeouts), idiomatic usage patterns,
+  error handling in each language, pagination helpers, and testing
+  guidance. The docs should feel native to each language's ecosystem.
+
+assertions:
+  - type: llm_judge
+    criteria: "SDK setup and configuration is language-idiomatic — Python: pip install, client initialization with api_key parameter or PAYMENTS_API_KEY env var, configure timeout/retries via client options, type hints shown throughout. Node.js: npm install, ESM and CommonJS import examples, async/await throughout (no callbacks), TypeScript types included. Both: show how to configure base URL for sandbox vs production, set custom headers, configure HTTP proxy. Authentication: constructor parameter vs environment variable vs config file — show all three. Version pinning recommendation. Quick example: 5 lines from install to first API call"
+    weight: 0.35
+    description: "Language-idiomatic setup"
+  - type: llm_judge
+    criteria: "Error handling follows language conventions — Python: SDK raises typed exceptions (PaymentError, AuthenticationError, RateLimitError, NotFoundError) inheriting from base APIError. Show try/except patterns with specific exception types. Access error.code, error.message, error.param. Node.js: rejects with typed error classes, show try/catch with async/await, error instanceof checks. Both: map HTTP status codes to exception types (401→AuthenticationError, 404→NotFoundError, 429→RateLimitError). Auto-retry on 429 with configurable max_retries. Show idiomatic error handling for each language, not just translated REST error docs"
+    weight: 0.35
+    description: "Error handling"
+  - type: llm_judge
+    criteria: "Advanced patterns cover real usage — Pagination: Python SDK provides auto_paging_iter() that handles cursor pagination automatically (for payment in client.payments.list(limit=100).auto_paging_iter()). Node.js: async iterator (for await (const payment of client.payments.list())). Webhook verification: client.webhooks.verify_signature(payload, header, secret). Testing: mock the client for unit tests — show how to stub responses in pytest/jest. Logging: enable debug logging to see HTTP requests. Resource cleanup: context managers in Python (async with), proper client.close() in Node.js. Bulk operations: helpers for batch processing that respect rate limits"
+    weight: 0.30
+    description: "Advanced patterns"

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

@@ -0,0 +1,48 @@
+meta:
+  id: webhook-documentation
+  level: 3
+  course: api-documentation-writing
+  type: output
+  description: "Document webhooks — write comprehensive webhook documentation covering event types, payload schemas, security verification, and retry behavior"
+  tags: [API, documentation, webhooks, events, signatures, retry, advanced]
+
+state: {}
+
+trigger: |
+  Your platform sends webhooks for key events but the documentation
+  is sparse. Developers keep asking:
+
+  - "What events can I subscribe to?"
+  - "What does the payload look like for each event?"
+  - "How do I verify the webhook is really from you?"
+  - "My endpoint was down — will you retry? How many times?"
+  - "I'm getting duplicate events — is that expected?"
+  - "The timestamps don't match — what timezone are these in?"
+
+  Webhook events:
+  - payment.succeeded, payment.failed, payment.refunded
+  - customer.created, customer.updated, customer.deleted
+  - subscription.created, subscription.renewed, subscription.cancelled
+  - invoice.created, invoice.paid, invoice.overdue
+
+  Security: HMAC-SHA256 signature in X-Webhook-Signature header
+  Retry policy: 3 retries with exponential backoff (1min, 10min, 1hr)
+  Delivery: at-least-once (duplicates possible)
+
+  Task: Write complete webhook documentation including event catalog,
+  payload schemas, signature verification guide, retry behavior, and
+  best practices for building reliable webhook consumers.
+
+assertions:
+  - type: llm_judge
+    criteria: "Event catalog and payloads are complete — every event type listed with: event name, trigger condition (when it fires), payload schema with all fields typed and described. Common envelope: { id (unique event ID), type (event string), created_at (ISO 8601 UTC), data (event-specific payload), api_version }. For payment.succeeded: data includes payment object (id, amount, currency, customer_id, payment_method). For customer.updated: data includes previous_attributes showing what changed. Each event has a realistic full JSON example. Events grouped by resource (payment, customer, subscription, invoice)"
+    weight: 0.35
+    description: "Event catalog"
+  - type: llm_judge
+    criteria: "Security verification is step-by-step — HMAC-SHA256 verification: (1) extract X-Webhook-Signature header, (2) get raw request body (important: use raw bytes, not parsed JSON), (3) compute HMAC-SHA256 using your webhook secret, (4) compare signatures using constant-time comparison (prevent timing attacks). Code examples in at least 2 languages (Node.js, Python). Explain WHY each step matters (raw body because JSON parsing changes field order, constant-time comparison to prevent timing attacks). How to get/rotate webhook secret. What to do if verification fails (return 401, log, alert). Timestamp tolerance: reject events older than 5 minutes to prevent replay attacks"
+    weight: 0.35
+    description: "Security verification"
+  - type: llm_judge
+    criteria: "Reliability patterns are documented — retry behavior: 3 attempts at 1min, 10min, 1hr intervals, then event marked as failed (visible in dashboard). Your endpoint must return 2xx within 30 seconds or it's considered failed. At-least-once delivery: you MAY receive the same event twice — use event ID for idempotency. Best practices: (1) respond with 200 immediately, process async, (2) store event ID to deduplicate, (3) use a queue for processing, (4) handle out-of-order events (check timestamps), (5) set up webhook endpoint monitoring. Testing: provide a 'Send test event' button in dashboard. Webhook logs: show recent deliveries with response codes for debugging"
+    weight: 0.30
+    description: "Reliability patterns"

package/courses/api-documentation-writing/scenarios/level-3/websocket-sse-docs.yaml

@@ -0,0 +1,47 @@
+meta:
+  id: websocket-sse-docs
+  level: 3
+  course: api-documentation-writing
+  type: output
+  description: "Document real-time APIs — write documentation for WebSocket and Server-Sent Events endpoints covering connection lifecycle, message formats, and reconnection strategies"
+  tags: [API, documentation, WebSocket, SSE, real-time, streaming, events, advanced]
+
+state: {}
+
+trigger: |
+  Your platform is adding real-time features alongside the REST API:
+
+  1. WebSocket endpoint: wss://api.example.com/ws
+     - Real-time payment status updates
+     - Live dashboard data streaming
+     - Bi-directional: client can subscribe/unsubscribe to channels
+
+  2. Server-Sent Events: https://api.example.com/events/payments
+     - Uni-directional stream of payment events
+     - Simpler alternative for clients that only need to listen
+
+  Developers are confused:
+  - "Which should I use — WebSocket or SSE?"
+  - "How do I authenticate a WebSocket connection?"
+  - "What happens when the connection drops?"
+  - "What's the message format? Is it JSON?"
+  - "How do I subscribe to specific payment updates?"
+
+  Task: Document both the WebSocket and SSE endpoints. Include:
+  connection setup, authentication, message formats, subscription
+  management, error handling, reconnection strategies, and a
+  comparison to help developers choose between them.
+
+assertions:
+  - type: llm_judge
+    criteria: "WebSocket documentation covers full lifecycle — connection: wss:// URL, authentication via token query param or first message. Handshake example with headers. Message format: JSON with type field (subscribe, unsubscribe, ping, pong, event). Subscribe: { type: 'subscribe', channel: 'payments', filters: { customer_id: 'cus_123' } }. Server events: { type: 'event', channel: 'payments', event: 'payment.succeeded', data: {...}, timestamp: '...' }. Heartbeat: server sends ping every 30s, client must respond with pong within 10s or connection is closed. Connection states: connecting, open, closing, closed. Max message size, max connections per client, idle timeout"
+    weight: 0.35
+    description: "WebSocket docs"
+  - type: llm_judge
+    criteria: "SSE documentation and comparison are clear — SSE setup: EventSource API in browser, curl with streaming, library examples. Authentication: Bearer token via headers (not supported by native EventSource — show polyfill or library). Event format: event type, data (JSON), id (for resumption), retry. Last-Event-ID header for reconnection — server resumes from where client left off. Comparison table: WebSocket vs SSE — bidirectional vs unidirectional, protocol complexity, browser support, firewall friendliness, auto-reconnection (SSE has built-in), load balancer compatibility. Recommendation: SSE for simple event listening (payments feed), WebSocket for interactive features (live dashboard with filtering)"
+    weight: 0.35
+    description: "SSE and comparison"
+  - type: llm_judge
+    criteria: "Reconnection and error handling are production-ready — WebSocket reconnection: detect close event, implement exponential backoff (1s, 2s, 4s, 8s, max 30s), re-authenticate on reconnect, re-subscribe to channels, request missed events by timestamp. SSE reconnection: automatic via EventSource (browser handles it), Last-Event-ID for resumption, server backfills missed events. Error scenarios: invalid auth (close code 4001), rate limited (close code 4029), server restart (close code 1001), invalid subscription (error message with details). Code examples showing robust connection management in JavaScript and Python. Monitoring: how to detect connection health, metrics to track (connection duration, reconnection frequency, message latency)"
+    weight: 0.30
+    description: "Reconnection patterns"

package/courses/api-documentation-writing/scenarios/level-4/api-changelog-management.yaml

@@ -0,0 +1,44 @@
+meta:
+  id: api-changelog-management
+  level: 4
+  course: api-documentation-writing
+  type: output
+  description: "Manage API changelog — design a changelog system that communicates API changes effectively to different stakeholders with appropriate urgency and detail"
+  tags: [API, documentation, changelog, release-notes, communication, versioning, expert]
+
+state: {}
+
+trigger: |
+  Your API ships weekly updates. The changelog is a mess:
+
+  - Buried in a docs page nobody reads
+  - Mix of breaking changes and minor fixes with no differentiation
+  - No way for developers to know if a change affects their integration
+  - Enterprise customers surprised by breaking changes
+  - "When was this field added?" — nobody knows without git blame
+
+  Developers want:
+  - Advance notice of breaking changes
+  - Easy way to see what changed since their last integration update
+  - Ability to subscribe to changes relevant to their usage
+  - Clear migration guidance for breaking changes
+  - Historical record of all changes
+
+  Task: Design a comprehensive API changelog system. Include: change
+  categorization, notification system, migration guidance integration,
+  developer-facing changelog format, and tooling for automated changelog
+  generation from code changes.
+
+assertions:
+  - type: llm_judge
+    criteria: "Change categorization enables targeted communication — categories: (1) Breaking: requires integration changes (field removal, type change, endpoint removal), (2) Deprecation: still works but will break in future, (3) Feature: new endpoints, fields, or capabilities, (4) Fix: bug fixes (behavior change that matches documentation), (5) Security: security patches (may require action). Each entry: date, category, affected endpoints, description, migration guide link (for breaking). Severity levels for breaking changes: critical (integration will fail), moderate (degraded behavior), minor (cosmetic). Structured format: each entry has tags (resources affected, API version) enabling filtering"
+    weight: 0.35
+    description: "Change categorization"
+  - type: llm_judge
+    criteria: "Notification system reaches developers proactively — subscription options: email digest (weekly), RSS feed, webhook (for CI/CD integration), Slack/Discord bot, in-dashboard banner. Developers can filter: by resource (only payment changes), by severity (only breaking), by API version (only v2 changes). Breaking changes: 30-day advance notice via email + dashboard banner + API response header (X-API-Deprecation-Notice). Timeline: announced → preview (available in sandbox) → released → old behavior sunset. Personalized notifications: analyze developer's API usage to highlight changes that affect their specific integration patterns. Emergency changes: immediate notification via all channels with migration urgency"
+    weight: 0.35
+    description: "Notification system"
+  - type: llm_judge
+    criteria: "Automation and format are developer-friendly — automated generation: conventional commits or PR labels generate changelog entries. OpenAPI diff tool detects spec changes and auto-generates entries for new/modified/removed endpoints. Human review: auto-generated entries reviewed by tech writer for clarity before publishing. Format: reverse chronological, filterable by category, searchable. Each entry is linkable (deep link to specific change). Diff view: compare OpenAPI specs between any two dates. 'Changes since' query: developers enter their last integration date, see all changes since then. API endpoint: GET /changelog with query params (since, category, resource) — developers can programmatically check for changes in CI/CD. Integration: changelog entries link to relevant documentation sections and migration guides"
+    weight: 0.30
+    description: "Automation and format"

package/courses/api-documentation-writing/scenarios/level-4/api-governance-standards.yaml

@@ -0,0 +1,41 @@
+meta:
+  id: api-governance-standards
+  level: 4
+  course: api-documentation-writing
+  type: output
+  description: "Establish API documentation governance — create organization-wide standards, review processes, and quality metrics for API documentation across teams"
+  tags: [API, documentation, governance, standards, organization, quality, expert]
+
+state: {}
+
+trigger: |
+  Your organization has 8 engineering teams producing 15 APIs.
+  Documentation quality varies wildly:
+
+  - Team A: beautiful docs, interactive examples, 98% developer satisfaction
+  - Team B: auto-generated Swagger UI with no descriptions
+  - Team C: outdated wiki pages that reference deprecated endpoints
+  - Team D: no documentation at all ("read the code")
+
+  Leadership wants consistent documentation quality across all APIs.
+  You're tasked with creating the governance framework.
+
+  Task: Design an API documentation governance program. Include:
+  documentation standards (what every API must have), quality scoring
+  rubric, review and approval process, tooling requirements, team
+  responsibilities, and an adoption strategy that doesn't alienate
+  the teams that are currently behind.
+
+assertions:
+  - type: llm_judge
+    criteria: "Documentation standards define minimum requirements — tiered requirements: Bronze (minimum viable): OpenAPI spec with descriptions for all endpoints, at least one example per endpoint, authentication documented, error codes listed. Silver (good): getting started guide, all request/response schemas with examples, changelog maintained, sandbox available. Gold (excellent): SDK documentation, interactive explorer, migration guides, tutorials, code samples in 3+ languages. Every API must reach Bronze within 3 months, Silver within 6 months. Gold is aspirational. Checklist for each tier is specific and measurable (not subjective). Non-negotiables: valid OpenAPI spec, no undocumented public endpoints, security documentation"
+    weight: 0.35
+    description: "Standards tiers"
+  - type: llm_judge
+    criteria: "Quality scoring and review process are objective — scoring rubric: completeness (are all endpoints documented?), accuracy (do examples match actual behavior?), usability (can a new developer integrate in under 30 minutes?), maintenance (is the changelog current?). Automated scoring: CI tool that checks OpenAPI completeness, link validity, example freshness. Manual scoring: quarterly review by documentation team using rubric. API review gate: new APIs cannot launch without Bronze documentation (enforced in release process). Existing APIs: audit current state, create remediation plan per team. Documentation review board: cross-team group that reviews standards quarterly and handles exceptions"
+    weight: 0.35
+    description: "Quality scoring"
+  - type: llm_judge
+    criteria: "Adoption strategy is empathetic and practical — don't shame teams that are behind — celebrate teams that are ahead as examples. Provide: documentation templates (copy and fill in), starter OpenAPI specs generated from existing code, dedicated documentation support (tech writer office hours). Incentives: documentation quality in team OKRs, internal 'best docs' award, developer satisfaction scores shared. Training: documentation writing workshops, OpenAPI authoring courses, tool training sessions. Phase rollout: start with one willing team as pilot, iterate on standards based on feedback, then expand. Address common objections: 'no time' (templates reduce effort), 'docs get outdated' (automation keeps them fresh), 'developers should read code' (external developers can't)"
+    weight: 0.30
+    description: "Adoption strategy"

package/courses/api-documentation-writing/scenarios/level-4/api-product-strategy.yaml

@@ -0,0 +1,41 @@
+meta:
+  id: api-product-strategy
+  level: 4
+  course: api-documentation-writing
+  type: output
+  description: "Position documentation as product enabler — align API documentation strategy with product goals, partner onboarding, and revenue generation"
+  tags: [API, documentation, product-strategy, monetization, partner, business, expert]
+
+state: {}
+
+trigger: |
+  Your company's API is becoming a revenue product, not just a feature.
+  The API generates $2M ARR from 200 paying integrations. Growth targets:
+  $5M ARR, 500 integrations by end of year.
+
+  Current bottlenecks:
+  - Average onboarding: 3 weeks (competitor: 3 days)
+  - 30% of trials abandon during integration (most cite "confusing docs")
+  - Partner certification takes 2 months of back-and-forth
+  - Enterprise prospects require custom documentation for security review
+  - No self-service tier — all onboarding requires sales call
+
+  Task: Create a documentation strategy that directly supports revenue
+  growth. Include: self-service onboarding (eliminate sales dependency
+  for standard tier), partner acceleration program, enterprise
+  documentation package, and metrics linking documentation quality
+  to revenue. Show how documentation investment has measurable ROI.
+
+assertions:
+  - type: llm_judge
+    criteria: "Self-service onboarding enables growth without sales — self-service tier: developer signs up, gets sandbox key instantly, follows guided quickstart, upgrades to paid via self-service checkout. Documentation enables this by: comprehensive quickstart (no gaps requiring support), interactive sandbox with pre-populated data, troubleshooting guide that resolves 90% of integration issues, production readiness checklist. Pricing page with clear tier comparison. Self-service target: 80% of new integrations onboard without human contact. ROI: current cost-per-integration $5,000 (sales + support time), self-service reduces to $200 (documentation + infrastructure). Path: documentation investment of $X enables 300 additional self-service integrations"
+    weight: 0.35
+    description: "Self-service strategy"
+  - type: llm_judge
+    criteria: "Partner program uses docs to accelerate certification — partner documentation package: architecture guide, best practices, sample integration, certification test suite. Certification program: partners complete integration milestones documented as a checklist (authenticate, create first payment, handle webhooks, error handling, go-live review). Automated certification: partner runs test suite, scores automatically, badge issued. Reduces certification from 2 months to 2 weeks. Partner-specific docs: co-branded guides, partner-specific use cases, featured in marketplace. Revenue impact: faster partner certification → more partners → more transaction volume. Partner tiers (bronze/silver/gold) with documentation requirements for each"
+    weight: 0.35
+    description: "Partner acceleration"
+  - type: llm_judge
+    criteria: "Enterprise package and ROI metrics are compelling — enterprise documentation package: security whitepaper (encryption, compliance, pen test results), architecture diagram (data flow, multi-tenancy), SLA documentation, disaster recovery plan, data processing agreement — reduces security review from 6 weeks to 1 week. Revenue metrics dashboard: TTFC correlated with conversion rate (faster onboarding → higher conversion), documentation page visits mapped to integration completion, support ticket cost savings, trial-to-paid conversion by documentation path. Investment case: $500K annual documentation investment generates $3M incremental revenue (6x ROI) through faster onboarding, reduced support, and partner acceleration. Quarterly business review template with documentation KPIs"
+    weight: 0.30
+    description: "Enterprise and ROI"

package/courses/api-documentation-writing/scenarios/level-4/developer-portal-design.yaml

@@ -0,0 +1,48 @@
+meta:
+  id: developer-portal-design
+  level: 4
+  course: api-documentation-writing
+  type: output
+  description: "Design developer portal — architect a complete developer portal with documentation, API keys, dashboard, community, and self-service onboarding"
+  tags: [API, documentation, developer-portal, DX, onboarding, self-service, expert]
+
+state: {}
+
+trigger: |
+  You're building a developer portal from scratch for your platform.
+  It needs to be more than just API docs — it's the entire developer
+  experience:
+
+  Current developer journey (painful):
+  1. Find docs via Google (SEO is poor)
+  2. Read API reference (no quickstart)
+  3. Email sales to get API keys (2-day wait)
+  4. Trial and error with undocumented edge cases
+  5. Email support when stuck (1-day response)
+  6. Finally integrate after 2 weeks
+
+  Target developer journey:
+  1. Find portal via Google (optimized)
+  2. Sign up and get API keys instantly
+  3. Follow quickstart guide (10-minute integration)
+  4. Use interactive explorer for testing
+  5. Go to production with confidence
+
+  Task: Design the complete developer portal. Include: site architecture,
+  self-service features (API key management, usage dashboard), documentation
+  sections, community features, and the onboarding flow. Focus on reducing
+  time-to-first-call (TTFC) from 2 weeks to 10 minutes.
+
+assertions:
+  - type: llm_judge
+    criteria: "Portal architecture serves the complete developer lifecycle — sections: (1) Landing page with value prop, quickstart CTA, and trust signals. (2) Documentation: getting started, API reference, guides, tutorials, SDKs, webhooks, changelog. (3) Dashboard: API key management (create, rotate, restrict by IP/scope), usage analytics (requests, errors, latency), billing. (4) Interactive: API explorer, sandbox environment, webhook testing. (5) Community: forum/Discord, Stack Overflow tag, GitHub issues, status page. (6) Account: team management, notification preferences. Navigation: persistent sidebar, global search, contextual help. SEO: each endpoint is a crawlable page with structured data"
+    weight: 0.35
+    description: "Portal architecture"
+  - type: llm_judge
+    criteria: "Onboarding flow reduces TTFC to under 10 minutes — step 1: sign up (email/GitHub OAuth, no sales call required for sandbox). Step 2: instant sandbox API key displayed on welcome page. Step 3: interactive quickstart — choose your language, copy-paste code, make first call, see response — all on one page. Step 4: guided exploration — 'Now try creating a payment' with pre-filled values. Step 5: production checklist (webhook endpoint, error handling, go-live review). Progress tracker: visual indicator of onboarding progress. Skip option: experienced developers can skip to API reference. Measurement: track TTFC (time from signup to first successful API call), identify and remove friction points"
+    weight: 0.35
+    description: "Onboarding flow"
+  - type: llm_judge
+    criteria: "Self-service features reduce support dependency — API key management: create multiple keys with different scopes (read-only, write, admin), IP allowlisting, key rotation without downtime (grace period). Usage dashboard: real-time request volume, error rate, latency percentiles, top endpoints, rate limit proximity warnings. Logs: searchable request/response logs for debugging (last 7 days, filterable by endpoint, status code, time). Alerts: email/Slack when error rate spikes or approaching rate limits. Support integration: 'Report a bug' button pre-fills context (endpoint, error, request_id). Self-service: upgrade tier, manage team members, generate invoices — no support tickets needed. Estimated support ticket reduction: 60% from self-service + better docs"
+    weight: 0.30
+    description: "Self-service features"

package/courses/api-documentation-writing/scenarios/level-4/docs-as-code.yaml

@@ -0,0 +1,41 @@
+meta:
+  id: docs-as-code
+  level: 4
+  course: api-documentation-writing
+  type: output
+  description: "Implement docs-as-code workflow — design a documentation pipeline with version control, CI/CD, automated testing, and review processes for API documentation"
+  tags: [API, documentation, docs-as-code, CI/CD, automation, workflow, expert]
+
+state: {}
+
+trigger: |
+  Your documentation lives in a CMS, edited by technical writers.
+  Problems:
+  - Docs drift from actual API behavior (no one updates after code changes)
+  - No review process — writers publish directly
+  - No versioning — can't see what changed or roll back
+  - Developers don't contribute because they don't have CMS access
+  - Documentation builds break silently
+
+  You want to move to docs-as-code: documentation in the same repo
+  as code, using the same tools (Git, PRs, CI/CD).
+
+  Task: Design the complete docs-as-code workflow. Include: repository
+  structure, documentation format (MDX, OpenAPI, or both), build
+  pipeline, automated quality checks, review process, and how to keep
+  docs in sync with code changes. Explain how this reduces documentation
+  drift and enables developer contributions.
+
+assertions:
+  - type: llm_judge
+    criteria: "Repository structure and format choices are justified — documentation lives alongside code in /docs directory (or monorepo with docs package). OpenAPI spec is source of truth for API reference (auto-generates endpoint pages). Guides and tutorials in MDX (Markdown + React components for interactive elements). Directory structure: /docs/api (auto-generated from OpenAPI), /docs/guides (hand-written), /docs/tutorials, /docs/changelog. Build tool: Docusaurus, Nextra, or similar static site generator that supports OpenAPI rendering. Version docs alongside API versions (docs/v1, docs/v2). PR template includes 'Documentation updated?' checkbox"
+    weight: 0.35
+    description: "Repo structure"
+  - type: llm_judge
+    criteria: "CI/CD pipeline ensures quality — automated checks on every PR: (1) OpenAPI spec validation (no broken $ref, valid schemas), (2) link checking (no dead links), (3) spell checking, (4) code example testing (extract and run code snippets), (5) build check (docs site builds successfully), (6) screenshot comparison (visual regression for rendered docs). Deployment: staging preview for every PR (Vercel preview deployments or similar), production deploy on merge to main. OpenAPI diff: show breaking changes in PR comments when spec changes. Automated changelog generation from conventional commits. Build badge in README"
+    weight: 0.35
+    description: "CI/CD pipeline"
+  - type: llm_judge
+    criteria: "Review process and sync strategy prevent drift — review workflow: code PRs that change API behavior must include docs PR (enforced by CI check — 'API changed but no docs updated'). Documentation review: technical writer reviews developer-written docs, developer reviews writer-written technical accuracy. Sync mechanisms: (1) OpenAPI spec generates reference docs automatically, (2) contract tests verify examples match actual API behavior, (3) scheduled job runs all code examples against sandbox. Contribution guide: how developers write docs (templates, style guide link, local preview instructions). Metrics: track docs-to-code commit ratio, average time from API change to docs update, documentation coverage (% of endpoints with examples)"
+    weight: 0.30
+    description: "Review and sync"

package/courses/api-documentation-writing/scenarios/level-4/documentation-localization.yaml

@@ -0,0 +1,46 @@
+meta:
+  id: documentation-localization
+  level: 4
+  course: api-documentation-writing
+  type: output
+  description: "Localize API documentation — design a localization strategy for translating API docs into multiple languages while maintaining technical accuracy and consistency"
+  tags: [API, documentation, localization, i18n, translation, multi-language, expert]
+
+state: {}
+
+trigger: |
+  Your API is expanding internationally. Developer demographics:
+  - 45% English-speaking
+  - 20% Japanese-speaking
+  - 15% Portuguese-speaking (Brazil)
+  - 10% German-speaking
+  - 10% other languages
+
+  Current state: English-only documentation. You're losing deals in
+  Japan and Brazil where developers prefer native-language docs.
+
+  Challenges:
+  - Technical terms: should "endpoint" be translated or kept in English?
+  - Code examples: variable names in English, comments translated?
+  - Keeping translations in sync when English docs change
+  - Budget: can't translate everything — what to prioritize?
+  - Quality: machine translation of technical docs is often wrong
+
+  Task: Design a documentation localization strategy. Include: what to
+  translate (and what not to), translation workflow, quality assurance,
+  synchronization with English source, and a phased rollout plan
+  prioritized by market impact.
+
+assertions:
+  - type: llm_judge
+    criteria: "Translation scope is strategically prioritized — translate first: getting started guide, authentication, top 10 most-visited pages, error messages, dashboard UI. Translate later: full API reference, advanced guides, architecture docs. Never translate: code examples (keep English variable names), API field names, URLs/paths, technical terms that are industry-standard in English (API, JSON, REST, OAuth, webhook). For each language: glossary of technical terms with approved translations (or decision to keep English). Code comments and descriptions: translate. Variable names and code: never translate. Phased rollout: Japanese first (highest revenue impact per developer), then Portuguese, then German"
+    weight: 0.35
+    description: "Translation scope"
+  - type: llm_judge
+    criteria: "Translation workflow ensures quality and consistency — workflow: (1) English content finalized, (2) extract translatable strings (separate from code/markup), (3) professional translator with technical API background translates, (4) technical reviewer (native-speaking developer) verifies accuracy, (5) in-context review (see translation in actual docs layout). Tools: translation management system (Crowdin, Lokalise, Phrase) integrated with docs repo. Translation memory: reuse approved translations across pages. Glossary enforcement: TMS flags when glossary terms are translated inconsistently. Machine translation: use as first pass for professional translator to refine (not as final output). Style guide per language: tone, formality level, formatting conventions"
+    weight: 0.35
+    description: "Translation workflow"
+  - type: llm_judge
+    criteria: "Synchronization and maintenance prevent translation drift — sync strategy: when English source changes, affected translations flagged as 'needs update' in TMS. Change types: (1) minor (typo fix) — apply to all languages automatically, (2) content update — flag translations, prioritize by page traffic, (3) new content — add to translation queue. Dashboard: translation coverage percentage per language, pages needing update, average translation lag (days between English change and translation update). Fallback: untranslated pages show English with banner 'This page is not yet available in [language]'. URL strategy: /ja/docs/..., /pt-br/docs/..., with language switcher. Budget: estimate cost per word, annual budget per language, measure ROI (conversion rate lift per language launched)"
+    weight: 0.30
+    description: "Sync and maintenance"

package/courses/api-documentation-writing/scenarios/level-4/documentation-metrics.yaml

@@ -0,0 +1,45 @@
+meta:
+  id: documentation-metrics
+  level: 4
+  course: api-documentation-writing
+  type: output
+  description: "Measure documentation effectiveness — define and track metrics for developer experience including TTFC, task completion, satisfaction, and support ticket deflection"
+  tags: [API, documentation, metrics, TTFC, analytics, developer-experience, expert]
+
+state: {}
+
+trigger: |
+  Leadership asks: "How good are our API docs?" You have no data to
+  answer. You need metrics to:
+
+  1. Measure current documentation quality
+  2. Track improvement over time
+  3. Justify investment in documentation
+  4. Identify which docs need the most work
+
+  Available data sources:
+  - Documentation site analytics (page views, time on page, bounce rate)
+  - API usage logs (first API call timestamps, error rates by integration)
+  - Support tickets (tagged by category)
+  - Developer surveys (quarterly, low response rate)
+  - SDK download counts
+  - Sandbox vs production API key creation rates
+
+  Task: Design a documentation metrics program. Define key metrics
+  (leading and lagging), set up measurement methods, create dashboards,
+  and explain how to use metrics to prioritize documentation improvements.
+  Include benchmark targets for each metric.
+
+assertions:
+  - type: llm_judge
+    criteria: "Key metrics are defined with measurement methods — primary metrics: (1) Time to First Call (TTFC): median time from signup to first successful API call — measure via API logs. Target: under 15 minutes. (2) Task completion rate: can developers complete common tasks (create payment, set up webhooks) using only docs? — measure via usability testing. Target: 90%. (3) Support ticket deflection: percentage of docs-answerable questions that don't become tickets — measure via ticket analysis. Target: reduce doc-answerable tickets by 50%. (4) Developer satisfaction (CSAT/NPS): quarterly survey. Target: NPS > 40. Secondary: page views, search queries (what are developers looking for?), 404 rate, time on page, bounce rate per section"
+    weight: 0.35
+    description: "Key metrics"
+  - type: llm_judge
+    criteria: "Analytics implementation is detailed — documentation analytics: track page views, scroll depth, time on page, search queries (especially zero-result searches), copy-to-clipboard clicks on code examples, 'Was this helpful?' feedback per page. API correlation: link documentation page visits to subsequent API calls (did reading the guide lead to a successful integration?). Funnel analysis: signup → docs visit → sandbox call → production call — where do developers drop off? Support correlation: when a developer files a ticket, what docs pages did they visit first (indicates doc failure)? A/B testing: test different documentation approaches (more examples vs more explanation) and measure completion rates. Tools: Google Analytics/Plausible for docs, custom events for API correlation"
+    weight: 0.35
+    description: "Analytics implementation"
+  - type: llm_judge
+    criteria: "Metrics drive prioritization and ROI — prioritization framework: fix docs with highest (traffic × bounce rate × support ticket volume) first. Dashboard: real-time documentation health scorecard — TTFC trend, top searched terms, most-visited error pages, support ticket volume by category. ROI calculation: each support ticket costs $X, documentation that deflects Y tickets saves $XY per month — justify technical writer headcount. Quarterly review: compare metrics against targets, identify top 5 documentation improvements needed, report to leadership. Feedback loop: metrics identify problem areas → improve docs → measure impact → iterate. Common pitfall: don't optimize for page views (vanity metric) — optimize for task completion and reduced support load"
+    weight: 0.30
+    description: "Prioritization and ROI"

package/courses/api-documentation-writing/scenarios/level-4/documentation-testing.yaml

@@ -0,0 +1,41 @@
+meta:
+  id: documentation-testing
+  level: 4
+  course: api-documentation-writing
+  type: output
+  description: "Test API documentation — implement automated testing for documentation accuracy including contract tests, example validation, and link checking"
+  tags: [API, documentation, testing, contract-tests, validation, automation, expert]
+
+state: {}
+
+trigger: |
+  Your documentation has a trust problem. Developers have been burned
+  by inaccurate docs:
+
+  - Code example in docs returns 400 when copied verbatim
+  - Response schema in docs doesn't match actual response
+  - Documented endpoint was renamed 3 months ago
+  - "Required field" in docs is actually optional
+  - Link to authentication guide is 404
+
+  You need automated testing to guarantee documentation accuracy.
+
+  Task: Design a documentation testing strategy. Include: contract
+  testing (docs match API behavior), code example testing (examples
+  actually work), schema validation (OpenAPI spec matches responses),
+  link checking, and freshness monitoring. Provide implementation
+  details for each type of test.
+
+assertions:
+  - type: llm_judge
+    criteria: "Contract testing validates docs match API — contract tests: for each documented endpoint, make the documented request and verify: (1) response status matches documented status, (2) response body matches documented schema (all fields present, types correct), (3) required fields in request are actually required (test with/without), (4) documented error scenarios return documented error codes. Tools: Dredd (OpenAPI contract testing), Schemathesis (property-based API testing from OpenAPI), custom test suite. Run against sandbox in CI/CD on every API or docs change. Report: percentage of endpoints passing contract tests, specific failures with diff between documented and actual"
+    weight: 0.35
+    description: "Contract testing"
+  - type: llm_judge
+    criteria: "Code examples and schemas are tested automatically — code example extraction: parse documentation (MDX/Markdown), extract fenced code blocks tagged with language, identify API calls. Execution: run each code example against sandbox, verify it succeeds (non-error response). For curl examples: execute directly. For Python/Node.js: run in Docker container with dependencies installed. Schema validation: compare OpenAPI response schema against actual API responses using JSON Schema validation. Detect: extra fields in response not in schema, missing fields, type mismatches. Freshness: flag docs pages not updated in 90 days for review, detect OpenAPI spec changes that don't have corresponding docs updates"
+    weight: 0.35
+    description: "Example and schema testing"
+  - type: llm_judge
+    criteria: "Link checking and monitoring are comprehensive — link checking: crawl all documentation pages, verify internal links (no 404s), external links (still valid), anchor links (target exists on page). Run on every build and weekly scheduled scan. Monitoring dashboard: documentation health score (contract pass rate, broken links, stale pages, example failures). Alerts: Slack notification when contract test fails, weekly report of documentation health. Metrics tracked over time: documentation accuracy trend, mean time to fix broken docs, percentage of endpoints with passing tests. Integration: documentation test results visible in PR reviews, blocking merge if critical docs tests fail"
+    weight: 0.30
+    description: "Monitoring"