@shaykec/bridge 0.4.25 → 0.4.27

package/modules/ai-test-generation/exercises.md

@@ -0,0 +1,98 @@
+# AI-Assisted Test Generation Exercises
+
+## Exercise 1: Write a Test Generation Prompt
+
+**Task:** For this function, write a prompt you'd use to generate unit tests. Include: framework (Vitest), desired cases, and any style preferences.
+
+```javascript
+function slugify(text) {
+  return String(text)
+    .toLowerCase()
+    .trim()
+    .replace(/\s+/g, '-')
+    .replace(/[^a-z0-9-]/g, '');
+}
+```
+
+**Validation:**
+- [ ] Prompt includes the function (or clear reference)
+- [ ] Framework specified
+- [ ] At least 3 case types (e.g., happy, empty, special chars)
+- [ ] Prompt is specific enough to get usable output
+
+**Hints:**
+1. What happens with "Hello World", "", "UPPERCASE", "a—b"?
+2. Specify assert style: toBe, toEqual, toMatch
+3. Include "trim and replace" behavior in the prompt
+
+---
+
+## Exercise 2: Critique and Fix a Generated Test
+
+**Task:** This test was AI-generated. Identify 2 problems and fix them.
+
+```javascript
+test('fetchUser works', async () => {
+  const result = await fetchUser(1);
+  expect(result).toBeTruthy();
+});
+```
+
+**Validation:**
+- [ ] Identifies shallow assertion (toBeTruthy)
+- [ ] Identifies missing mock/setup if fetchUser hits network
+- [ ] Proposes concrete improvements (e.g., expect(result.name).toBe('Alice'))
+
+**Hints:**
+1. What does toBeTruthy actually verify?
+2. Does fetchUser need a mock? What would happen without it?
+3. What would a strong assertion look like?
+
+---
+
+## Exercise 3: Generate and Review
+
+**Task:** Use Claude (or another AI) to generate tests for `slugify` from Exercise 1. Run them. Then review using the checklist: assertions verify behavior? Edge cases covered? Tests independent? List 2 improvements you'd make.
+
+**Validation:**
+- [ ] Tests were generated and run
+- [ ] At least one improvement identified
+- [ ] Improvement is actionable (specific change, not vague)
+
+**Hints:**
+1. Try the prompt you wrote in Exercise 1
+2. Run with `npx vitest run` or your project's test command
+3. Look for toBeDefined, toBeTruthy, or missing edge cases
+
+---
+
+## Exercise 4: AI for Integration Test Setup
+
+**Task:** You have an API endpoint `POST /users` that creates a user. Writing integration tests requires: DB setup, request body, and assertions. Write a prompt that asks AI to generate one integration test, including setup and teardown. Specify your stack (e.g., Node, Express, Jest, supertest).
+
+**Validation:**
+- [ ] Prompt specifies stack and tools
+- [ ] Asks for setup (DB, server) and teardown
+- [ ] Asks for clear assertion (status, body shape)
+- [ ] Understands AI may need refinement—integration is complex
+
+**Hints:**
+1. "Generate integration test for POST /users with Jest and supertest"
+2. Include: how to start/stop server, reset DB
+3. Ask for status 201 and body containing id, name, email
+
+---
+
+## Exercise 5: Build a Prompt Template
+
+**Task:** Create a reusable prompt template for unit test generation. Use placeholders like [FUNCTION], [FRAMEWORK], [CASES]. Write 2 example fills (different functions) showing how you'd use it.
+
+**Validation:**
+- [ ] Template has clear placeholders
+- [ ] Template includes context that improves output (framework, style, cases)
+- [ ] Both examples would produce usable prompts
+
+**Hints:**
+1. Start with: "Generate [FRAMEWORK] unit tests for [FUNCTION]..."
+2. Add: "Include [CASES]. Use [STYLE]."
+3. Example: [FUNCTION]=parsePrice, [CASES]=happy, null, invalid

package/modules/ai-test-generation/module.yaml

@@ -0,0 +1,39 @@
+slug: ai-test-generation
+title: "AI-Assisted Test Generation — Using Claude for Coverage"
+version: 1.0.0
+description: "Use AI to generate tests—prompting strategies, review practices, and combining human judgment with AI speed."
+category: quality-assurance
+tags: [ai, testing, test-generation, claude, automation, coverage]
+difficulty: intermediate
+
+xp:
+  read: 15
+  walkthrough: 40
+  exercise: 25
+  quiz: 20
+  quiz-perfect-bonus: 10
+
+time:
+  quick: 5
+  read: 20
+  guided: 50
+
+prerequisites: [test-strategy]
+related: [ai-pair-programming, prompt-engineering]
+
+triggers:
+  - "How can AI help me write tests?"
+  - "Can Claude generate unit tests?"
+  - "How do I use AI for test coverage?"
+  - "What's the best way to prompt AI for tests?"
+
+visuals:
+  diagrams: [diagram-mermaid, diagram-flow]
+  quiz-types: [quiz-timed-choice, quiz-matching]
+  playground: javascript
+  slides: true
+
+sources:
+  - url: "https://docs.anthropic.com"
+    label: "Anthropic Claude Documentation"
+    type: docs

package/modules/ai-test-generation/quick-ref.md

@@ -0,0 +1,65 @@
+# AI-Assisted Test Generation Quick Reference
+
+## Prompt Checklist
+
+- [ ] Function/code under test
+- [ ] Framework (Jest, Vitest, Playwright)
+- [ ] Case types (happy, edge, error)
+- [ ] One example test for style
+- [ ] Constraints (no mocks for X, use RTL)
+
+## AI Strengths
+
+| Strength | Use For |
+|----------|---------|
+| Boilerplate | describe, it, expect structure |
+| Edge cases | Empty, null, boundary suggestions |
+| Test data | Fixtures, mocks, invalid inputs |
+| Test doubles | Stub/mock generation |
+
+## AI Weaknesses
+
+| Weakness | Human Must |
+|----------|------------|
+| Intent | Provide context and priorities |
+| What matters | Choose what to test |
+| Assertion quality | Review and strengthen |
+| Framework quirks | Specify and verify |
+
+## Review Checklist for Generated Tests
+
+- [ ] Assertions verify behavior, not just "defined"
+- [ ] Edge cases and errors covered
+- [ ] Mocks justified (not over-used)
+- [ ] Test names are descriptive
+- [ ] Tests are independent
+
+## Common Pitfalls
+
+| Pitfall | Fix |
+|---------|-----|
+| expect(x).toBeDefined() | Assert expected value (toBe, toEqual) |
+| Over-mocking | Use real deps for integration |
+| Wrong framework | Specify in prompt; refine and regenerate |
+| Missing edge cases | Ask for "boundary and invalid inputs" |
+
+## Iteration Loop
+
+```
+Prompt → Generate → Run → Review → Refine prompt → (repeat)
+```
+
+## By Layer
+
+| Layer | AI Does | You Do |
+|-------|---------|--------|
+| Unit | Draft + edge cases | Verify assertions, add critical cases |
+| Integration | Setup, fixtures | Verify real flows, DB state |
+| E2E | Steps, selectors | Choose scenarios, reduce flakiness |
+
+## One-Liners
+
+- **Context wins**: Function + framework + examples = better tests.
+- **Review always**: AI drafts; you verify.
+- **Iterate prompts**: Save what works for your stack.
+- **Human + AI**: You direct; AI speeds you up.

package/modules/ai-test-generation/quiz.md

@@ -0,0 +1,74 @@
+# AI-Assisted Test Generation Quiz
+
+## Question 1
+
+What is AI typically good at when generating tests?
+
+A) Deciding which tests matter most for your business
+B) Generating boilerplate, edge cases, and test data
+C) Knowing your team's testing conventions without being told
+D) Writing perfect tests that never need review
+
+<!-- ANSWER: B -->
+<!-- EXPLANATION: AI excels at generating structure (describe, it, expect), suggesting edge cases, and creating fixtures. It does not know your business priorities or conventions without explicit context. -->
+
+## Question 2
+
+Why should you review AI-generated tests critically?
+
+A) AI always produces bugs
+B) AI often produces shallow assertions and over-mocking that need strengthening
+C) Review is only for style
+D) AI-generated tests don't need review
+
+<!-- ANSWER: B -->
+<!-- EXPLANATION: AI commonly produces tests with weak assertions (e.g., toBeDefined), excessive mocking, or missing edge cases. Human review ensures tests actually verify behavior. -->
+
+## Question 3
+
+What improves AI test generation prompts?
+
+A) Longer prompts are always better
+B) Providing the function, framework, example tests, and desired cases
+C) Asking for "comprehensive" tests without specifics
+D) Avoiding any examples to keep output original
+
+<!-- ANSWER: B -->
+<!-- EXPLANATION: Context matters: the function under test, the framework (Jest, Vitest), one example test for style, and specific case types (happy, edge, error) all improve output quality. -->
+
+## Question 4
+
+When is AI most useful for test generation?
+
+A) Only for e2e tests
+B) For unit test boilerplate and edge case suggestions; human decides strategy
+C) To replace all manual test writing
+D) Only when you have no tests yet
+
+<!-- ANSWER: B -->
+<!-- EXPLANATION: AI is strongest for unit-level drafts and suggestions. Human judgment is essential for prioritization, integration/e2e strategy, and verifying assertions are meaningful. -->
+
+## Question 5
+
+What should you do when AI generates tests with the wrong framework (e.g., Jest instead of Vitest)?
+
+A) Manually rewrite every test
+B) Refine the prompt to specify the framework and regenerate
+C) Switch your project to match the AI output
+D) Use the tests as-is since APIs are similar
+
+<!-- ANSWER: B -->
+<!-- EXPLANATION: Refining the prompt to explicitly specify Vitest (vi.fn(), vi.mock()) and regenerating is efficient. Building a prompt library for your stack avoids repeats. -->
+
+## Question 6
+
+Match the AI capability to the test layer:
+
+<!-- VISUAL: quiz-matching -->
+
+- Unit tests :: Boilerplate, edge cases, mocks — human verifies assertions
+- Integration tests :: Setup, fixtures, contracts — human verifies real flows
+- E2E tests :: Selectors, steps — human chooses scenarios
+
+<!-- ANSWER: (implicit from matching) -->
+<!-- EXPLANATION: AI can draft at all layers, but human responsibility differs. Unit: verify assertions. Integration: verify real system behavior. E2E: choose what matters, avoid flakiness. -->

package/modules/ai-test-generation/resources.md

@@ -0,0 +1,41 @@
+# AI-Assisted Test Generation — Resources
+
+## AI & Prompting
+
+- [Anthropic Claude Documentation](https://docs.anthropic.com/) — Claude API, prompting, best practices.
+- [Claude Prompt Engineering](https://docs.anthropic.com/claude/docs/prompt-engineering) — Context, examples, and structure.
+- [OpenAI Prompt Engineering](https://platform.openai.com/docs/guides/prompt-engineering) — General prompting patterns (apply to Claude).
+- [Prompt Engineering Guide](https://www.promptingguide.ai/) — Techniques for better prompts across models.
+
+## Testing Frameworks
+
+- [Vitest](https://vitest.dev/) — Fast, ESM-native test runner. Great for JS/TS.
+- [Jest](https://jestjs.io/) — Popular unit testing framework. Large ecosystem.
+- [Playwright](https://playwright.dev/) — E2E testing. AI can help with selectors and flows.
+- [Testing Library](https://testing-library.com/) — User-centric component tests. Specify in prompts.
+
+## Articles
+
+- [AI-Generated Tests: What to Watch For](https://martinfowler.com/articles/ai-testing.html) — Martin Fowler (if available) or similar. Pitfalls of AI tests.
+- [Using AI for Test Automation](https://www.ministryoftesting.com/articles) — Ministry of Testing. Practical tips.
+- [Test Doubles and Mocks](https://martinfowler.com/bliki/TestDouble.html) — So AI generates the right kind.
+- [Meaningful Assertions](https://kentcdodds.com/blog/what-to-test) — Kent C. Dodds. What to verify.
+
+## Tools
+
+- [Cursor](https://cursor.com/) — AI-assisted IDE. Inline test generation.
+- [GitHub Copilot](https://github.com/features/copilot) — Test generation in the editor.
+- [Claude Code / Claude Codex](https://www.anthropic.com/product) — Coding-focused Claude.
+- [Mocha / Chai](https://mochajs.org/) — Alternative test framework. Specify in prompts if used.
+
+## Best Practices
+
+- [Test Strategy — Martin Fowler](https://martinfowler.com/articles/practical-test-pyramid.html) — Foundation for what to test.
+- [Test-Driven Development](https://martinfowler.com/bliki/TestDrivenDevelopment.html) — TDD and AI: who drives?
+- [Refactoring with Tests](https://refactoring.com/) — Safe refactoring; AI-generated tests support this.
+
+## Community
+
+- [Ministry of Testing](https://www.ministryoftesting.com/) — Testing community, AI in testing discussions.
+- [r/QualityAssurance](https://www.reddit.com/r/QualityAssurance/) — QA discussions, tool experiences.
+- [Claude Community](https://www.anthropic.com/community) — Claude usage and prompting tips.

package/modules/ai-test-generation/walkthrough.md

@@ -0,0 +1,100 @@
+# AI-Assisted Test Generation Walkthrough — Learn by Doing
+
+## Before We Begin
+
+**Diagnostic Question:** When AI generates tests, what could go wrong? What would you still need to verify or add yourself?
+
+**Checkpoint:** You recognize that AI can draft tests but may miss edge cases, use the wrong assertions, or assume a different framework. Human review is essential.
+
+---
+
+## Step 1: Provide Context for a Test Prompt
+
+You want AI to generate tests for this function:
+
+<!-- hint:code language="javascript" highlight="1,5" -->
+
+```javascript
+function parsePrice(input) {
+  if (input == null || input === '') return null;
+  const num = parseFloat(String(input).replace(/[^0-9.-]/g, ''));
+  return isNaN(num) ? null : Math.round(num * 100) / 100;
+}
+```
+
+**Task:** Write a prompt you'd send to Claude (or another AI) to generate unit tests. Include: the function, the framework (e.g., Vitest), what cases you want, and one example of a test style you prefer.
+
+**Question:** What would happen if you only said "Generate tests for this function" without context?
+
+**Checkpoint:** User includes: function code, Vitest, requested cases (happy, empty, null, invalid string, decimals), and maybe one example test. They understand minimal prompts produce generic output; context yields better tests.
+
+---
+
+## Step 2: Review AI-Generated Tests
+
+<!-- hint:card type="warning" title="AI test pitfalls" -->
+
+Suppose AI produced:
+
+```javascript
+test('parses price', () => {
+  const result = parsePrice('$19.99');
+  expect(result).toBeDefined();
+});
+```
+
+**Task:** Why is this test weak? Rewrite it (or describe what to change) so it actually verifies behavior.
+
+**Question:** What's the difference between "the code ran" and "the code did the right thing"?
+
+**Checkpoint:** User identifies: toBeDefined() only checks non-null. Should assert expect(result).toBe(19.99) or similar. They understand assertions must verify expected output, not just "it didn't crash."
+
+---
+
+## Step 3: Generate Tests with Claude
+
+**Task:** Pick a small function from your codebase (or use `parsePrice` above). Use Claude to generate unit tests. Provide: the function, framework, and at least 3 case types you want. Run the tests. What passed? What did you have to fix or improve?
+
+**Question:** What did you learn about prompting from the first attempt? What would you add to the prompt next time?
+
+**Checkpoint:** User completes the task, runs tests, and reflects. They note: maybe add "use toBe for numbers, toBeNull for null", or "include $ and , in input" to improve next output.
+
+---
+
+## Step 4: Use AI for Edge Cases
+
+<!-- hint:buttons type="single" prompt="Which edge case would you add first?" options="17 and 121,18.5,eighteen" -->
+
+You have a function that validates a user age (must be 18–120). You've written happy path tests.
+
+**Task:** Prompt AI: "Suggest 5 edge case inputs for a function that validates age 18–120. Include boundary and invalid cases." List what AI suggests. Then evaluate: which would you actually add to your test suite? Why or why not?
+
+**Question:** When would you reject an AI-suggested edge case?
+
+**Checkpoint:** User gets suggestions (e.g., 17, 18, 120, 121, -1, "eighteen", 18.5). They evaluate: 18 and 120 are must-haves; 17 and 121 test boundaries; -1 and "eighteen" test invalid; 18.5 might be optional. They reject cases that don't match real usage (e.g., if age is always integer).
+
+---
+
+## Step 5: AI for Test Data
+
+You need to test an API that accepts `{ name, email, createdAt }`. You want 3 valid and 2 invalid payloads.
+
+**Task:** Write a prompt for AI to generate these payloads. What specific requirements would you include? (e.g., email format, date format, invalid examples)
+
+**Question:** Why might AI-generated test data still need your review?
+
+**Checkpoint:** User writes a clear prompt with constraints (valid email, ISO date, name length). They note: AI might generate data that passes validation but doesn't match real-world edge cases (Unicode, SQL injection attempts); human review catches those.
+
+---
+
+## Step 6: Iterate on a Failed Prompt
+
+<!-- hint:celebrate -->
+
+Your first prompt produced tests that used `jest.fn()` but your project uses Vitest (`vi.fn()`). The tests also didn't handle async.
+
+**Task:** Write a refined prompt that would fix these issues. What would you add or change?
+
+**Question:** How do you build a "prompt library" for test generation over time?
+
+**Checkpoint:** User adds: "Use Vitest (vi.fn(), vi.mock())", "This function is async—use async/await in tests". They see value in saving successful prompts for reuse (framework, style, common patterns).

package/modules/api-design/content.md

@@ -0,0 +1,189 @@
+# API Design — REST, GraphQL, and Contract-First Thinking
+
+<!-- hint:slides topic="API design: REST principles, GraphQL tradeoffs, contract-first design, versioning, pagination, and error handling" slides="6" -->
+
+## REST Principles
+
+**REST** (Representational State Transfer) models the web as resources identified by URLs, manipulated via HTTP verbs.
+
+| Principle | Meaning |
+|-----------|---------|
+| **Resources** | Nouns in URLs: `/users`, `/users/123`, `/users/123/orders` |
+| **HTTP verbs** | GET (read), POST (create), PUT (replace), PATCH (partial update), DELETE (remove) |
+| **Status codes** | 200 OK, 201 Created, 400 Bad Request, 404 Not Found, 429 Too Many Requests |
+| **HATEOAS** | Responses include links to related resources (optional in practice) |
+
+## REST Naming Conventions
+
+- **Plural nouns:** `/users` not `/user`
+- **Hierarchy:** `/users/123/orders`
+- **No verbs in URL:** Use POST `/users` not `POST /createUser`
+- **Snake_case or camelCase:** Be consistent (JSON often uses camelCase)
+
+Example:
+
+```http
+GET /users/42/orders?status=active&limit=10
+POST /users
+{
+  "email": "alice@example.com",
+  "name": "Alice"
+}
+```
+
+```mermaid
+sequenceDiagram
+    participant Client
+    participant Gateway as API Gateway
+    participant Server
+    participant DB as Database
+    Client->>Gateway: HTTP Request
+    Gateway->>Server: Forward Request
+    Server->>DB: Query
+    DB-->>Server: Result
+    Server-->>Gateway: Response
+    Gateway-->>Client: HTTP Response
+```
+
+## GraphQL Basics
+
+**GraphQL** lets clients request exactly the fields they need with a single endpoint.
+
+```graphql
+query {
+  user(id: "42") {
+    name
+    email
+    orders(limit: 5) {
+      id
+      total
+    }
+  }
+}
+```
+
+- **Queries** — Read data
+- **Mutations** — Create, update, delete
+- **Schemas** — Strong typing; tools generate clients
+- **Resolvers** — Server-side functions that fetch each field
+
+## REST vs GraphQL
+
+```mermaid
+sequenceDiagram
+    participant C as Client
+    participant R as REST API
+    participant G as GraphQL API
+    C->>R: GET /users/1
+    R-->>C: Full user object
+    C->>R: GET /users/1/orders
+    R-->>C: Orders
+    Note over C,G: vs GraphQL
+    C->>G: POST /graphql { user { name orders { total } } }
+    G-->>C: Only requested fields, one round-trip
+```
+
+| Criterion | REST | GraphQL |
+|-----------|------|--------|
+| **Over-fetching** | Common (full objects) | Client specifies fields |
+| **Under-fetching** | Multiple requests (N+1) | Single request, nested |
+| **Caching** | HTTP cache, CDN | Custom (normalized cache) |
+| **Discoverability** | URLs, OpenAPI | Schema, introspection |
+| **Complexity** | Simpler | Schema, resolvers, tooling |
+
+**Use REST** when: CRUD-heavy, HTTP caching matters, clients are simple. **Use GraphQL** when: flexible queries, mobile (bandwidth), many clients with different needs.
+
+## Contract-First Design
+
+Define the API before coding: **OpenAPI** (Swagger) for REST, **GraphQL schema** for GraphQL.
+
+```yaml
+# OpenAPI snippet
+paths:
+  /users/{id}:
+    get:
+      summary: Get user by ID
+      parameters:
+        - name: id
+          in: path
+          required: true
+          schema:
+            type: string
+      responses:
+        '200':
+          description: User object
+        '404':
+          description: Not found
+```
+
+Benefits: generate clients, mock servers, documentation, validation.
+
+## API Versioning
+
+| Strategy | Example | Pros / Cons |
+|----------|---------|-------------|
+| **URL** | `/v1/users`, `/v2/users` | Clear, cacheable; more URLs |
+| **Header** | `Accept: application/vnd.api+json;version=2` | Clean URLs; less visible |
+| **Query param** | `?version=2` | Simple; can be forgotten |
+| **Media type** | `application/vnd.myapi.v2+json` | RESTful; verbose |
+
+Common: **URL versioning** (`/v1/`, `/v2/`) — predictable, easy to route.
+
+## Pagination
+
+| Strategy | Use Case |
+|----------|----------|
+| **Offset** | `?offset=20&limit=10` — Simple, can skip; inconsistent if data changes |
+| **Cursor** | `?cursor=abc123&limit=10` — Stable for feeds; no random access |
+| **Page** | `?page=3&per_page=10` — Human-friendly; same issues as offset |
+
+**Cursor-based** is preferred for feeds and infinite scroll.
+
+## Error Handling
+
+Return structured errors:
+
+```json
+{
+  "error": {
+    "code": "VALIDATION_ERROR",
+    "message": "Invalid email format",
+    "details": [
+      { "field": "email", "reason": "Must be a valid email" }
+    ]
+  }
+}
+```
+
+Use appropriate status codes: `400` (client error), `401` (unauthorized), `403` (forbidden), `404` (not found), `429` (rate limited), `500` (server error).
+
+## Rate Limiting
+
+Protect the API: return `429 Too Many Requests` and include headers:
+
+```http
+X-RateLimit-Limit: 1000
+X-RateLimit-Remaining: 42
+X-RateLimit-Reset: 1640995200
+Retry-After: 60
+```
+
+## Authentication
+
+| Method | Use Case |
+|--------|----------|
+| **API Key** | Simple, server-to-server |
+| **OAuth 2.0** | Delegated access, user consent |
+| **JWT** | Stateless, signed tokens; include in `Authorization: Bearer <token>` |
+
+Always use HTTPS for credentials.
+
+## Key Takeaways
+
+- **REST:** Resources, verbs, status codes; good for CRUD
+- **GraphQL:** Flexible queries, one endpoint; good for varied clients
+- **Contract-first:** Define schema/OpenAPI before implementation
+- **Version** explicitly (URL or header)
+- **Pagination:** Prefer cursor for feeds
+- **Errors:** Structured body, correct status codes
+- **Rate limit** and **authenticate** securely

package/modules/api-design/exercises.md

@@ -0,0 +1,84 @@
+# API Design Exercises
+
+## Exercise 1: REST Resource Design
+
+**Task:** Design REST endpoints for a "books" API: list books, get one book, create a book, update a book, delete a book. Include: URL, method, request body (where applicable), and key response codes.
+
+**Validation:**
+- [ ] Plural resource name (`/books`)
+- [ ] Correct HTTP verbs for each action
+- [ ] 201 for create, 200 for get/update, 204 for delete
+- [ ] Request body for create and update
+
+**Hints:**
+1. GET /books — list, GET /books/:id — get one
+2. POST /books — create (body: title, author, isbn)
+3. PUT or PATCH /books/:id — update
+4. DELETE /books/:id — delete (204 No Content)
+
+---
+
+## Exercise 2: GraphQL Query and Mutation
+
+**Task:** Design a GraphQL schema and one query + one mutation for a "tasks" API. Query: get task by id with title, status, assignee name. Mutation: create task with title and assigneeId. Write the schema types and the query/mutation.
+
+**Validation:**
+- [ ] Task type with id, title, status, assignee
+- [ ] Query: task(id: ID!): Task
+- [ ] Mutation: createTask(title: String!, assigneeId: ID!): Task
+- [ ] Assignee can be embedded or referenced
+
+**Hints:**
+1. type Task { id: ID! title: String! status: String assignee: User }
+2. type User { id: ID! name: String }
+3. createTask returns Task (with id from server)
+
+---
+
+## Exercise 3: OpenAPI Snippet
+
+**Task:** Write OpenAPI 3.0 for `GET /books` and `POST /books`. Include: parameters (optional: author, limit), request/response schemas, status codes 200, 201, 400.
+
+**Validation:**
+- [ ] paths./books with get and post
+- [ ] GET has parameters; POST has requestBody
+- [ ] Schemas for Book (id, title, author)
+- [ ] Correct status codes
+
+**Hints:**
+1. openapi: 3.0.0, paths, components.schemas
+2. parameters: author (query), limit (query, default 20)
+3. requestBody for POST: application/json, required: title, author
+
+---
+
+## Exercise 4: Pagination Comparison
+
+**Task:** Compare offset and cursor pagination for a feed of 10,000 items. Scenario: user requests page 5 (offset 40). Between requests, 3 items are inserted at the start. What does the user see with offset vs cursor? Which is better for a social feed?
+
+**Validation:**
+- [ ] Offset: might see duplicates or miss items when data shifts
+- [ ] Cursor: stable, no duplicates; better for feeds
+- [ ] Recommendation: cursor for feeds, offset for admin UIs
+
+**Hints:**
+1. Offset 40 = items 41–50. After insert, "page 5" might return different items
+2. Cursor points to last seen item; next page is "after cursor"
+3. Social feeds: cursor preferred (consistent infinite scroll)
+
+---
+
+## Exercise 5: Error and Rate Limit Response
+
+**Task:** Design the full HTTP response for: (1) 400 Bad Request — invalid JSON body, (2) 429 Too Many Requests — client exceeded 100 req/min. Include status, headers, and body format.
+
+**Validation:**
+- [ ] 400: body has error code, message, optionally details
+- [ ] 429: Retry-After header, optionally X-RateLimit-* headers
+- [ ] Content-Type: application/json
+- [ ] Body is parseable and actionable for clients
+
+**Hints:**
+1. 400: { "error": { "code": "INVALID_JSON", "message": "..." } }
+2. 429: Retry-After: 60 (seconds)
+3. X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset