dojo.md 0.1.0 → 0.2.1

package/courses/postgresql-query-optimization/scenarios/level-5/database-regulatory-landscape.yaml

@@ -0,0 +1,76 @@
+meta:
+  id: database-regulatory-landscape
+  level: 5
+  course: postgresql-query-optimization
+  type: output
+  description: "Navigate database regulatory compliance — design PostgreSQL configurations for GDPR, PCI DSS, HIPAA, SOX, and emerging data sovereignty regulations"
+  tags: [PostgreSQL, compliance, GDPR, PCI-DSS, HIPAA, SOX, data-sovereignty, master]
+
+state: {}
+
+trigger: |
+  Your company is expanding into 3 new markets (EU, healthcare, and
+  government contracts). Each market has different database compliance
+  requirements, and your PostgreSQL infrastructure wasn't designed for
+  regulatory compliance. The legal team has given you 6 months to achieve
+  compliance or the expansion deals ($30M combined) will be lost.
+
+  Current PostgreSQL infrastructure:
+  - 20 clusters, all in US-East region
+  - No data classification (PII mixed with non-PII)
+  - Audit logging: only pg_log (not queryable, not tamper-evident)
+  - Encryption: TLS in transit, no encryption at rest, no column-level
+  - Access control: 5 shared database users for 200 engineers
+  - Data retention: No automated deletion, data kept forever
+  - Backups: Daily pg_dump, stored unencrypted in same region
+
+  Compliance requirements by market:
+
+  1. EU expansion (GDPR):
+  - Data residency: EU customer data must stay in EU
+  - Right to erasure: Must delete customer data on request within 30 days
+  - Data portability: Must export customer data in machine-readable format
+  - Breach notification: 72 hours to report data breaches
+  - Data minimization: Only collect what's necessary
+  - Audit trail: Prove who accessed what data and when
+
+  2. Healthcare (HIPAA):
+  - PHI must be encrypted at rest and in transit
+  - Access controls: Role-based, minimum necessary access
+  - Audit trail: All access to PHI must be logged and retained 6 years
+  - Business Associate Agreements with all vendors (including AWS)
+  - Breach notification: 60 days for breaches affecting 500+ individuals
+
+  3. Government (FedRAMP / NIST 800-53):
+  - Data must reside in US government-authorized regions
+  - FIPS 140-2 validated encryption modules
+  - Continuous monitoring and vulnerability scanning
+  - System categorization (Low, Moderate, High impact)
+  - Multi-factor authentication for all database access
+
+  Cross-cutting requirements:
+  - SOX compliance (public company): Database changes must be auditable,
+    separation of duties between development and production access
+  - PCI DSS (payment processing): Cardholder data encrypted, quarterly
+    vulnerability scans, access logging, tokenization
+
+  Task: Design the compliance architecture. Write: the data
+  classification and residency strategy, the encryption architecture
+  (at rest, in transit, column-level), the audit logging system (tamper-
+  evident, queryable, retained per regulation), the access control
+  redesign (from 5 shared users to RBAC), and the compliance automation
+  (how to continuously verify compliance, not just achieve it once).
+
+assertions:
+  - type: llm_judge
+    criteria: "Data classification and residency are addressed — defines data classification tiers (public, internal, confidential, restricted), maps PII/PHI/cardholder data to appropriate tiers, designs multi-region deployment for EU data residency (PostgreSQL in EU region with logical replication or partitioned access), and addresses right-to-erasure with soft-delete + scheduled purge patterns"
+    weight: 0.35
+    description: "Data classification and residency"
+  - type: llm_judge
+    criteria: "Encryption and access control are comprehensive — implements TDE or filesystem encryption at rest, column-level encryption (pgcrypto or application-level) for PII/PHI/cardholder data, redesigns access from 5 shared users to role-based access with per-engineer credentials, implements row-level security for data isolation, and addresses FIPS 140-2 requirements for government"
+    weight: 0.35
+    description: "Encryption and access control"
+  - type: llm_judge
+    criteria: "Audit logging and compliance automation are production-ready — implements tamper-evident audit logging (pgAudit or custom triggers with hash chains), retains logs per regulation (6 years for HIPAA, 7 for SOX), provides queryable audit trail, and designs continuous compliance monitoring (automated checks, drift detection, compliance dashboard) rather than point-in-time audits"
+    weight: 0.30
+    description: "Audit and compliance automation"

package/courses/postgresql-query-optimization/scenarios/level-5/master-optimization-shift.yaml

@@ -0,0 +1,66 @@
+meta:
+  id: master-optimization-shift
+  level: 5
+  course: postgresql-query-optimization
+  type: output
+  description: "Master optimization shift — advise a CEO on a complete database transformation combining M&A integration, regulatory compliance, AI adoption, and 10x scaling"
+  tags: [PostgreSQL, shift-simulation, transformation, CEO-advisory, comprehensive, master]
+
+state: {}
+
+trigger: |
+  You're an external database strategy advisor. A CEO calls you with
+  an urgent, complex situation that touches everything you know about
+  PostgreSQL.
+
+  The situation:
+  DataCorp ($500M ARR, 2,000 engineers) just acquired two companies
+  simultaneously:
+  - HealthSync ($50M ARR, healthcare SaaS, HIPAA-regulated)
+  - EuroTrade ($80M ARR, EU-based fintech, GDPR + PCI DSS)
+
+  DataCorp runs PostgreSQL 15 on Aurora (30 clusters, 100TB).
+  HealthSync runs PostgreSQL 13 on self-managed EC2 (5 clusters, 8TB).
+  EuroTrade runs PostgreSQL 16 on Citus (10 clusters, 40TB, sharded).
+
+  The board has set 4 concurrent mandates (18-month timeline):
+  1. Integrate all three databases into a unified platform
+  2. Achieve HIPAA, GDPR, and PCI DSS compliance across the platform
+  3. Prepare for IPO (99.99% availability, SOX compliance, cost optimization)
+  4. Support 10x growth (DataCorp expects to grow from $500M to $5B ARR
+     in 5 years)
+
+  Constraints:
+  - Total database team across all 3 companies: 15 DBAs
+  - Combined infrastructure cost: $2M/month
+  - Zero customer data loss is non-negotiable
+  - All 3 products must remain operational during integration
+  - EU data must stay in EU (HealthSync currently stores some EU patient
+     data in US)
+  - IPO due diligence begins in 12 months
+
+  The CEO asks: "Give me the plan. I need to know: What's the unified
+  architecture? What's the timeline? What's the budget? What's the risk?
+  And what should I tell the board?"
+
+  Task: Write the comprehensive advisory document. Include: the unified
+  database architecture (handling Aurora + self-managed + Citus), the
+  compliance strategy (achieving all 4 regulatory frameworks
+  simultaneously), the integration timeline (phased approach over 18
+  months), the budget projection (with cost optimization targets), and
+  the board communication strategy (how to frame this as opportunity,
+  not just cost).
+
+assertions:
+  - type: llm_judge
+    criteria: "Unified architecture handles all 3 database platforms — addresses Aurora-to-Citus or Citus-to-Aurora consolidation (or hybrid approach), PG 13→16 upgrade path for HealthSync, handles Citus sharding patterns (distributed tables, reference tables) during migration, and designs for 10x scale (100TB→1PB trajectory). Architecture is realistic given 15 DBAs"
+    weight: 0.35
+    description: "Viable unified architecture"
+  - type: llm_judge
+    criteria: "Compliance strategy achieves all 4 frameworks — HIPAA (PHI encryption, access logging, BAAs), GDPR (EU data residency, right to erasure, DPA), PCI DSS (cardholder tokenization, network segmentation), and SOX (audit trails, separation of duties). Addresses the immediate risk of EU patient data in US. Identifies overlapping requirements to reduce effort"
+    weight: 0.35
+    description: "Multi-framework compliance"
+  - type: llm_judge
+    criteria: "Timeline, budget, and board communication are executive-ready — 18-month phased plan with clear milestones and go/no-go gates, budget includes infrastructure, personnel, and opportunity cost, risk register identifies top 5 risks with mitigation strategies, and the board narrative frames integration as competitive advantage (unified data platform enables cross-sell, AI/ML, faster innovation) not just technical debt remediation"
+    weight: 0.30
+    description: "Executive-ready delivery"

package/courses/rest-api-error-handling/course.yaml

@@ -0,0 +1,11 @@
+id: rest-api-error-handling
+name: "REST API Error Handling"
+description: >
+  Master REST API error handling from basic HTTP status codes to enterprise
+  error governance. Learn error response design, RFC 7807 Problem Details,
+  retry and circuit breaker patterns, distributed system error propagation,
+  error budgets, compliance-aware error handling, and API reliability
+  architecture for large-scale systems.
+levels: 5
+scenarios_per_level: 10
+tags: [development, REST, API, error-handling, HTTP, status-codes, reliability, DevOps]

package/courses/rest-api-error-handling/scenarios/level-1/authentication-errors.yaml

@@ -0,0 +1,71 @@
+meta:
+  id: authentication-errors
+  level: 1
+  course: rest-api-error-handling
+  type: output
+  description: "Handle authentication errors — design error responses for auth failures without leaking security information"
+  tags: [REST, API, authentication, 401, 403, security, beginner]
+
+state: {}
+
+trigger: |
+  You're working on the authentication error handling for a healthcare
+  appointment booking API. The security team reviewed your error
+  responses and flagged several issues.
+
+  Current error responses (flagged as problematic):
+
+  1. Missing token:
+     401 { "error": "No Authorization header provided" }
+     Security note: "This is fine, but be consistent"
+
+  2. Malformed token:
+     401 { "error": "JWT format invalid: expected 3 parts, got 1" }
+     Security note: "Reveals token implementation (JWT)"
+
+  3. Expired token:
+     401 { "error": "Token expired at 2026-02-26T14:30:00Z, current
+     time is 2026-02-27T08:15:00Z" }
+     Security note: "Reveals server clock — useful for timing attacks"
+
+  4. Invalid signature:
+     401 { "error": "JWT signature verification failed using RS256" }
+     Security note: "Reveals signing algorithm"
+
+  5. Valid token but user deactivated:
+     401 { "error": "User account deactivated since 2026-01-15" }
+     Security note: "Confirms account existence and status"
+
+  6. Valid token but wrong role (patient trying admin endpoint):
+     403 { "error": "User john.doe@email.com has role 'patient',
+     requires role 'admin'" }
+     Security note: "Reveals user email and role system"
+
+  7. Valid token but IP not in allowlist:
+     403 { "error": "IP 192.168.1.50 not in allowlist for admin API" }
+     Security note: "Reveals IP allowlist exists"
+
+  8. API key instead of bearer token:
+     401 { "error": "Expected Bearer token, received API key
+     sk-abc...xyz" }
+     Security note: "Echoes back the credential!"
+
+  Task: Rewrite all 8 error responses to be secure (no information
+  leakage) while still being useful enough for legitimate developers
+  to debug. Explain the security principle behind each change. Then
+  write guidelines for the team on what authentication errors should
+  and should not reveal.
+
+assertions:
+  - type: llm_judge
+    criteria: "Rewritten errors eliminate information leakage — no JWT implementation details, no server timestamps, no user emails, no role system details, no IP allowlist information, and absolutely no credential echoing. Each response gives enough information to debug without revealing security internals"
+    weight: 0.35
+    description: "Secure error responses"
+  - type: llm_judge
+    criteria: "Security principles are correctly explained — covers information disclosure risks (token type, algorithm, clock), account enumeration prevention, principle of least information, and the difference between logging detailed errors server-side vs returning generic errors to clients"
+    weight: 0.35
+    description: "Correct security principles"
+  - type: llm_judge
+    criteria: "Team guidelines are practical — provides clear do/don't list for auth error messages, explains server-side logging of detailed errors for debugging, and addresses the balance between security and developer experience"
+    weight: 0.30
+    description: "Practical team guidelines"

package/courses/rest-api-error-handling/scenarios/level-1/content-negotiation-errors.yaml

@@ -0,0 +1,63 @@
+meta:
+  id: content-negotiation-errors
+  level: 1
+  course: rest-api-error-handling
+  type: output
+  description: "Handle content negotiation errors — respond correctly when clients send or request unsupported content types"
+  tags: [REST, API, content-type, accept, 406, 415, beginner]
+
+state: {}
+
+trigger: |
+  You're building an API that primarily serves JSON but also supports
+  XML for legacy enterprise clients. Users keep hitting confusing
+  errors related to content types.
+
+  Support tickets this week:
+
+  Ticket 1: "I'm sending a POST with form data (Content-Type:
+  application/x-www-form-urlencoded) but getting a 500 error with
+  'Unexpected token' in the response."
+
+  Ticket 2: "I set Accept: text/html but got back JSON anyway. My XML
+  parser is choking on it."
+
+  Ticket 3: "I'm uploading a file with Content-Type: multipart/
+  form-data to the /reports endpoint but it says 'invalid JSON'."
+
+  Ticket 4: "My request works in Postman but fails in my code. I
+  think it's because Postman auto-sets Content-Type but my HTTP
+  library doesn't."
+
+  Ticket 5: "I'm sending JSON but with Content-Type: text/plain
+  and getting a 400 error that says 'Request body is empty' — but
+  the body is definitely there!"
+
+  Ticket 6: "I need CSV export of my data. GET /reports with Accept:
+  text/csv returns JSON. Is CSV supported?"
+
+  Current behavior: The API ignores the Accept header entirely and
+  always returns JSON. For request bodies, it tries to parse
+  everything as JSON regardless of Content-Type, causing cryptic
+  errors.
+
+  Task: Design the correct content negotiation error handling. For
+  each ticket, explain: what's going wrong, what the correct HTTP
+  status code and response should be, and what headers the response
+  should include. Then write the content negotiation middleware logic
+  that handles both request (Content-Type) and response (Accept)
+  negotiation properly.
+
+assertions:
+  - type: llm_judge
+    criteria: "Correct status codes for each scenario — 415 Unsupported Media Type when the server can't parse the request body's content type, 406 Not Acceptable when the server can't produce the client's requested format, and appropriate error messages explaining what formats are supported"
+    weight: 0.35
+    description: "Correct content negotiation status codes"
+  - type: llm_judge
+    criteria: "All 6 tickets are addressed with clear explanations — explains why form-encoded data fails JSON parsing, why missing Content-Type causes issues, how Accept header should drive response format, and includes the supported content types in error responses"
+    weight: 0.35
+    description: "All tickets addressed"
+  - type: llm_judge
+    criteria: "Middleware logic is complete — validates Content-Type on requests with bodies, negotiates Accept header for responses, falls back to JSON when no Accept header is sent, and includes proper Content-Type header on all responses including error responses"
+    weight: 0.30
+    description: "Complete middleware logic"

package/courses/rest-api-error-handling/scenarios/level-1/error-logging-basics.yaml

@@ -0,0 +1,63 @@
+meta:
+  id: error-logging-basics
+  level: 1
+  course: rest-api-error-handling
+  type: output
+  description: "Set up API error logging — design structured error logs that make debugging fast without logging sensitive data"
+  tags: [REST, API, logging, debugging, structured-logs, beginner]
+
+state: {}
+
+trigger: |
+  You're debugging a production issue on a food delivery API.
+  Customers are getting 500 errors when placing orders, but your
+  current logs look like this:
+
+  2026-02-27 10:15:33 ERROR: Something went wrong
+  2026-02-27 10:15:34 ERROR: Something went wrong
+  2026-02-27 10:15:35 ERROR: null
+  2026-02-27 10:15:36 ERROR: Something went wrong
+  2026-02-27 10:15:37 ERROR: [object Object]
+
+  You have no idea: which endpoint failed, what the request was,
+  which user was affected, what the actual error was, or how to
+  reproduce it.
+
+  After 2 hours of blind debugging, you find it's a null pointer
+  in the restaurant menu lookup. You realize you need proper error
+  logging.
+
+  Your API has these components:
+  - Order placement (POST /orders)
+  - Payment processing (POST /orders/:id/pay)
+  - Restaurant communication (POST /restaurants/:id/notify)
+  - Delivery assignment (POST /deliveries)
+  - User notifications (POST /notifications)
+
+  Sensitive data that must NOT appear in logs:
+  - Credit card numbers, CVVs
+  - User passwords
+  - Full addresses (only city/zip is OK)
+  - API keys and tokens
+  - Phone numbers (mask all but last 4)
+
+  Task: Design the structured error logging system. Show: the log
+  format (structured JSON), what fields every error log must include,
+  what sensitive fields must be masked or excluded, example log entries
+  for 3 different error types (validation error, third-party timeout,
+  unhandled exception), and how to search these logs to debug the
+  original "customers getting 500 errors" issue quickly.
+
+assertions:
+  - type: llm_judge
+    criteria: "Log format is structured and searchable — uses JSON format with consistent fields (timestamp, level, request_id, method, path, status_code, error_type, message, duration_ms, user_id). Includes enough context to reproduce issues without needing to add more logging"
+    weight: 0.35
+    description: "Structured searchable log format"
+  - type: llm_judge
+    criteria: "Sensitive data handling is thorough — credit cards, passwords, tokens are never logged. Phone numbers and addresses are properly masked. Explains the masking strategy (middleware vs per-field) and how to prevent accidental logging of request/response bodies containing sensitive data"
+    weight: 0.35
+    description: "Thorough sensitive data handling"
+  - type: llm_judge
+    criteria: "Example log entries are realistic and the debugging workflow is practical — shows how to filter logs by request_id, status_code, error_type to quickly identify the root cause. The 3 example entries demonstrate different error severities and contexts"
+    weight: 0.30
+    description: "Realistic examples and debugging workflow"

package/courses/rest-api-error-handling/scenarios/level-1/error-response-format.yaml

@@ -0,0 +1,58 @@
+meta:
+  id: error-response-format
+  level: 1
+  course: rest-api-error-handling
+  type: output
+  description: "Design error response format — create a consistent JSON error response structure for a REST API"
+  tags: [REST, API, error-response, JSON, format, beginner]
+
+state: {}
+
+trigger: |
+  You're building a recipe sharing API and different endpoints return
+  errors in completely different formats. Your team lead says this is
+  confusing for frontend developers and asks you to standardize.
+
+  Current inconsistent error responses across your API:
+
+  Endpoint 1 - POST /recipes (validation error):
+  { "error": "Title is required" }
+
+  Endpoint 2 - GET /recipes/999 (not found):
+  { "message": "Recipe not found", "code": 404 }
+
+  Endpoint 3 - POST /recipes (auth error):
+  { "status": "error", "reason": "Invalid token" }
+
+  Endpoint 4 - POST /recipes/5/reviews (rate limit):
+  "Too many requests, please try again later"
+
+  Endpoint 5 - PATCH /recipes/5 (validation errors):
+  { "errors": ["Title too long", "Invalid category"] }
+
+  Frontend developers are complaining:
+  - "I never know which field to check for the error message"
+  - "Sometimes I get a string, sometimes an object"
+  - "Validation errors come in different shapes"
+  - "I can't tell if an error is my fault or the server's fault"
+  - "There's no way to show specific field errors in the form"
+
+  Task: Design a unified error response format for the entire API.
+  Show: the standard error response schema (with required and optional
+  fields), examples for each of the 5 error types above rewritten in
+  the new format, guidelines for when to include each optional field,
+  and the implementation approach (middleware vs per-handler).
+
+assertions:
+  - type: llm_judge
+    criteria: "Error format is well-designed — includes a machine-readable error code/type, a human-readable message, and the HTTP status code. Handles single errors and multiple validation errors in the same structure. Includes a way to associate errors with specific fields for form validation"
+    weight: 0.35
+    description: "Well-designed error format"
+  - type: llm_judge
+    criteria: "All 5 error types are rewritten consistently — validation errors show field-level detail, not-found errors include resource identification, auth errors distinguish authentication vs authorization, rate limit errors include retry-after information, and all follow the same top-level structure"
+    weight: 0.35
+    description: "Consistent error rewrites"
+  - type: llm_judge
+    criteria: "Implementation guidance is practical — recommends middleware/error handler pattern for consistency, explains how to throw standardized errors from route handlers, and addresses how to prevent internal error details from leaking to the client"
+    weight: 0.30
+    description: "Practical implementation guidance"

package/courses/rest-api-error-handling/scenarios/level-1/first-error-handling-shift.yaml

@@ -0,0 +1,67 @@
+meta:
+  id: first-error-handling-shift
+  level: 1
+  course: rest-api-error-handling
+  type: output
+  description: "First error handling shift — handle a stream of real-time API errors during a product launch event"
+  tags: [REST, API, error-handling, shift-simulation, launch, beginner]
+
+state: {}
+
+trigger: |
+  You're on your first on-call shift for a ticket marketplace API.
+  The company is launching sales for a major concert tonight and
+  traffic will spike 10x. Your job is to review the API's error
+  handling before the launch.
+
+  During your pre-launch review, you find these issues:
+
+  Issue 1 — No global error handler:
+  If any route throws an unhandled exception, Express returns:
+  <!DOCTYPE html><html><body><pre>TypeError: Cannot read property
+  'email' of undefined<br>&nbsp; at /app/src/routes/tickets.js:45
+  </pre></body></html>
+  (HTML error page with stack trace)
+
+  Issue 2 — Inconsistent error shapes:
+  - /tickets returns { "error": "..." }
+  - /orders returns { "message": "...", "code": 123 }
+  - /payments returns { "errors": ["..."] }
+  - /users returns { "status": "fail", "data": { "message": "..." } }
+
+  Issue 3 — Database errors leak:
+  When the database constraint prevents duplicate ticket purchases:
+  "duplicate key value violates unique constraint
+  'orders_user_id_ticket_id_key'"
+
+  Issue 4 — No rate limiting on search:
+  GET /tickets/search has no rate limit. During the last sale, bots
+  made 50,000 requests/second and the API crashed.
+
+  Issue 5 — Payment errors are too vague:
+  POST /orders/:id/pay returns 400 { "error": "Payment failed" }
+  for every payment issue (declined card, insufficient funds,
+  expired card, processing timeout, fraud detection).
+
+  Issue 6 — Timeout errors unhandled:
+  The external payment processor sometimes takes 30+ seconds. The API
+  has no timeout, so requests hang until the client gives up.
+
+  Task: Fix all 6 issues before the launch. For each, write: what's
+  wrong (the risk for tonight's launch), the fix (code structure or
+  configuration), and the expected error response after the fix.
+  Prioritize the fixes by launch impact.
+
+assertions:
+  - type: llm_judge
+    criteria: "All 6 issues are fixed with correct solutions — global error handler catches unhandled exceptions (no HTML/stack traces), error format is standardized, database errors are translated to user-friendly messages, rate limiting is implemented for search, payment errors are specific but secure, and timeout handling is added with appropriate status codes"
+    weight: 0.35
+    description: "All issues fixed correctly"
+  - type: llm_judge
+    criteria: "Prioritization is sound — identifies which issues pose the greatest risk for a high-traffic launch event (no global error handler and no rate limiting are critical, inconsistent formats are important but not urgent). Each fix includes the expected error response"
+    weight: 0.35
+    description: "Sound prioritization"
+  - type: llm_judge
+    criteria: "Solutions are launch-ready — fixes are quick to implement (no major refactors), handle the specific high-traffic scenario (10x spike), and include monitoring so the on-call engineer can see errors in real-time during the launch"
+    weight: 0.30
+    description: "Launch-ready solutions"

package/courses/rest-api-error-handling/scenarios/level-1/http-status-codes.yaml

@@ -0,0 +1,46 @@
+meta:
+  id: http-status-codes
+  level: 1
+  course: rest-api-error-handling
+  type: output
+  description: "Classify HTTP status codes — match API scenarios to correct status codes across 2xx, 4xx, and 5xx families"
+  tags: [REST, API, HTTP, status-codes, beginner]
+
+state: {}
+
+trigger: |
+  You're a junior backend developer who just joined a team building a
+  task management API. During your first code review, the senior
+  developer flagged that your endpoints return wrong status codes.
+
+  Your current mistakes:
+  1. POST /tasks returns 200 when a task is created (should be 201)
+  2. DELETE /tasks/:id returns 200 with empty body (should be 204)
+  3. GET /tasks/:id returns 200 with { error: "not found" } when the
+     task doesn't exist (should be 404)
+  4. POST /tasks with missing "title" field returns 500 (should be 400)
+  5. GET /tasks with expired auth token returns 403 (should be 401)
+  6. PUT /tasks/:id on someone else's task returns 404 (should be 403)
+  7. POST /tasks when the database is down returns 400 (should be 503)
+  8. PATCH /tasks/:id with Content-Type: text/plain returns 500
+     (should be 415)
+
+  Task: For each of the 8 mistakes, explain: (1) why your current
+  status code is wrong, (2) what the correct status code is and why,
+  and (3) the general rule for when to use that status code. Then
+  create a quick-reference cheat sheet mapping common API scenarios
+  to their correct HTTP status codes.
+
+assertions:
+  - type: llm_judge
+    criteria: "Correctly identifies all 8 status code fixes — 201 Created for resource creation, 204 No Content for successful deletion, 404 Not Found for missing resources, 400 Bad Request for validation errors, 401 Unauthorized for expired/missing auth, 403 Forbidden for insufficient permissions, 503 Service Unavailable for downstream failures, 415 Unsupported Media Type for wrong content types"
+    weight: 0.35
+    description: "Correct status code identification"
+  - type: llm_judge
+    criteria: "Explanations demonstrate understanding of status code semantics — distinguishes between 401 (identity unknown) and 403 (identity known, permission denied), between 400 (client mistake) and 500 (server mistake), and between 200 (response body) and 204 (no body)"
+    weight: 0.35
+    description: "Status code semantic understanding"
+  - type: llm_judge
+    criteria: "Cheat sheet is practical and organized — groups status codes by family (2xx success, 4xx client error, 5xx server error), covers common API scenarios beyond just the 8 mistakes, and is formatted for quick reference"
+    weight: 0.30
+    description: "Practical cheat sheet"

package/courses/rest-api-error-handling/scenarios/level-1/not-found-errors.yaml

@@ -0,0 +1,52 @@
+meta:
+  id: not-found-errors
+  level: 1
+  course: rest-api-error-handling
+  type: output
+  description: "Handle not-found errors — distinguish between missing resources, wrong URLs, and deleted content with appropriate responses"
+  tags: [REST, API, 404, not-found, routing, beginner]
+
+state: {}
+
+trigger: |
+  You're maintaining a blog API and users are reporting confusing
+  behavior. All of these return the same generic 404 response:
+
+  { "error": "Not found" }
+
+  But they represent very different situations:
+
+  1. GET /posts/42 — Post exists but is in draft status (not published)
+  2. GET /posts/99999 — Post ID doesn't exist at all
+  3. GET /posts/abc — Post ID is not a valid integer
+  4. GET /postz/42 — Typo in the URL path (postz instead of posts)
+  5. GET /posts/42 — Post existed but was deleted 3 days ago
+  6. GET /posts/42 — Post exists but belongs to a different tenant
+     in your multi-tenant system
+  7. GET /users/5/posts/42 — User 5 exists but post 42 belongs to
+     user 8
+  8. GET /v1/posts/42 — API v1 is deprecated, only v2 exists
+
+  The frontend developer says: "I can't tell if the user mistyped
+  the URL, if the post was deleted, if it's a permission issue, or
+  if the endpoint doesn't exist. They all look the same!"
+
+  Task: Design the appropriate response for each of the 8 scenarios.
+  Not all of them should be 404 — decide which HTTP status code
+  fits each case and explain why. Write the response body for each
+  scenario. Then create a decision tree for "when the resource isn't
+  there" that the team can follow.
+
+assertions:
+  - type: llm_judge
+    criteria: "Status code selection is correct for each case — distinguishes between 404 (truly not found), 400 (invalid ID format), 410 Gone (deleted content), 403 (wrong tenant/ownership), and appropriate handling for draft content and deprecated API versions. Not all 8 should be 404"
+    weight: 0.35
+    description: "Correct status code selection"
+  - type: llm_judge
+    criteria: "Response bodies are helpful without leaking information — draft posts don't reveal that the post exists (security consideration in multi-tenant), deleted posts may use 410 Gone with deletion context, invalid IDs explain the expected format, and deprecated versions redirect to the current version"
+    weight: 0.35
+    description: "Helpful secure responses"
+  - type: llm_judge
+    criteria: "Decision tree is clear and usable — provides a logical flow for developers to determine the right response when a resource isn't found, considers security implications (don't confirm existence to unauthorized users), and handles edge cases like soft deletes and multi-tenancy"
+    weight: 0.30
+    description: "Clear decision tree"

package/courses/rest-api-error-handling/scenarios/level-1/rate-limiting-errors.yaml

@@ -0,0 +1,56 @@
+meta:
+  id: rate-limiting-errors
+  level: 1
+  course: rest-api-error-handling
+  type: output
+  description: "Implement rate limiting errors — design 429 responses with proper headers and retry guidance for API consumers"
+  tags: [REST, API, rate-limiting, 429, throttling, beginner]
+
+state: {}
+
+trigger: |
+  You're building a weather data API that offers free and paid tiers.
+  The current rate limiting returns 429 with this response:
+
+  HTTP/1.1 429
+  { "error": "Too many requests" }
+
+  Customers are complaining:
+  - "When can I retry? 1 second? 1 hour?"
+  - "How many requests do I have left?"
+  - "I didn't even know there was a rate limit until my app broke"
+  - "My batch job got rate limited and I lost 2 hours of processing"
+  - "The paid plan says 1000 requests/minute but I got limited at 800"
+
+  Rate limit tiers:
+  - Free: 60 requests/minute, 1000 requests/day
+  - Basic ($29/mo): 600 requests/minute, 50,000 requests/day
+  - Pro ($99/mo): 3000 requests/minute, unlimited daily
+  - Enterprise: custom limits
+
+  Additional rules:
+  - Burst allowance: 2x the per-minute limit for up to 10 seconds
+  - Different limits for different endpoints (search: 10/min free,
+    forecast: 60/min free)
+  - Authenticated vs unauthenticated requests have different limits
+
+  Task: Design the complete rate limiting error response. Include:
+  the 429 response body with all necessary information, the rate
+  limit headers (standard and custom), the response headers that
+  should appear on ALL responses (not just 429) so clients can
+  proactively manage their usage, and a guide for API consumers
+  on how to handle rate limits gracefully (backoff strategies).
+
+assertions:
+  - type: llm_judge
+    criteria: "429 response includes standard rate limit headers — X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset (or Retry-After), with clear documentation of header semantics. Response body includes retry timing, current limit, and which limit was hit (per-minute vs daily)"
+    weight: 0.35
+    description: "Proper 429 response with headers"
+  - type: llm_judge
+    criteria: "Rate limit information appears on ALL responses — successful responses include remaining quota and reset time so clients can proactively avoid hitting limits. The design handles the complexity of multiple limit windows (per-minute and daily) and per-endpoint limits"
+    weight: 0.35
+    description: "Proactive rate limit headers"
+  - type: llm_judge
+    criteria: "Consumer guidance is practical — explains exponential backoff with jitter, how to read rate limit headers proactively, how to build a request queue that respects limits, and addresses the batch processing use case (how to process large workloads within rate limits)"
+    weight: 0.30
+    description: "Practical consumer guidance"