@ai-support-agent/cli 0.1.32 → 0.1.33-beta.1

package/dist/plugin/rules/documentation/test-docs.md

@@ -0,0 +1,39 @@
+# Test Documentation Conventions
+
+Tests are a specification. The goal is that reading the list of test names alone gives you a list of the spec's requirements, and reading a test's body gives you the detail (what it covers and why).
+
+## Writing describe / it blocks
+
+- **describe**: names the subject under test (class, function, or endpoint). Use nested describes to represent different scenarios ("when inventory is insufficient," "when the user has admin privileges").
+- **it / test**: write a **complete specification sentence that includes an observable outcome**, in the project's designated language.
+
+```typescript
+describe('EstimateApprovalService.approve', () => {
+  describe('when the estimate amount exceeds $10,000', () => {
+    it('does not become approved until director approval is complete', () => { ... });
+    it('throws PendingDirectorApprovalError when only the manager has approved', () => { ... });
+  });
+});
+```
+
+- Forbidden names: uninformative labels like "happy path," "error case 1," "test1," "works," "OK" — anything that doesn't convey the spec on its own.
+- **Whatever outcome the test name claims must actually be asserted in the body.** A name like "throws an exception" with no assertion verifying the exception is a mismatch that the update-docs workflow and code review should catch.
+
+## Structuring the test body
+
+- Separate Arrange / Act / Assert with blank lines so the flow is easy to follow.
+- For complex setup, add a comment explaining what scenario is being constructed.
+- Annotate meaningful test data with its rationale (e.g., `1_000_001 // one above the $10,000 threshold boundary`). Don't annotate values that have no particular significance.
+
+## Conventions by stack
+
+| Stack | Test naming | Notes |
+|---|---|---|
+| Jest / Vitest / Playwright | describe + it (as above) | Nest with `test.describe` where helpful |
+| pytest | Test function name (e.g., `test_requires_director_approval_above_threshold`, in the designated language if appropriate) | For complex cases, put the summary and intent in a docstring |
+| PHPUnit | Test method name | The `@testdox` annotation can spell out the spec sentence; `#[TestDox('throws an exception when inventory is insufficient')]` is recommended |
+
+## Scope of application
+
+- All new tests must follow this convention.
+- Rename existing tests opportunistically, as part of a change that already touches them — a rename-only bulk change isn't worth the review cost on its own.

package/dist/plugin/rules/logging/logging-rules.md

@@ -0,0 +1,83 @@
+# Logging Conventions
+
+Goal: make it possible for both humans and AI to complete debugging **by reading only the source comments and the logs**. The standard is that logs alone should let you reconstruct "which user's, which request's, which function, with what input, passed through and failed where."
+
+## Adoption and cost tuning
+
+- Projects adopting this convention should add `logging` to the "adopted conventions" list in the "## Documentation conventions" section of their CLAUDE.md.
+- Log volume translates directly into cost, so **control output level via an environment variable** and tune it per project (typical default: INFO in production, DEBUG in development/investigation as a debug mode).
+- For high-traffic code paths, consider sampling DEBUG output (emit only a fraction of events). Document any such tuning in CLAUDE.md.
+
+## Basics
+
+- **Structured logging (JSON) is the standard.** Emit a `message` plus fields — don't embed information via string concatenation.
+- Field names are **full English words in snake_case, never abbreviated** (`request_id`, not `req_id`; `user_id`, not `uid`; also `duration_ms`, `function_name`).
+- Write messages in the project's designated language (same as the documentation convention; default to English if undeclared). Field names are always in English.
+
+### Choosing a log level
+
+| Level | Use |
+|---|---|
+| ERROR | A failure that requires action. Always include the exception, correlation ID, and the ID of the affected resource. |
+| WARN | An anomaly that self-recovered, a retry, approaching a threshold — anything worth monitoring. |
+| INFO | Business events (start/completion of order confirmation, invoice issuance, etc.; state transitions). The standard production level. |
+| DEBUG | For investigation: function start/end, inputs/outputs, and the data behind branching decisions. |
+
+## Correlation IDs (end-to-end tracing)
+
+To let you trace all logs from a single request across the system, **attach the following to every log entry automatically** — never pass them manually at each call site.
+
+- `request_id`: capture the `X-Request-Id` header at the request entry point (generate one if absent), set it in the logging context, and echo it back in the response header.
+- `user_id` (set after authentication), `tenant_code` (in multi-tenant systems, also useful for verifying tenant isolation).
+- `trace_id`: if you have AWS X-Ray (or an equivalent tracing system) enabled, include the trace ID as well, so logs and traces can be cross-referenced (for Lambda, enabling active tracing propagates the header automatically).
+- **Propagation into async work**: when enqueuing a job, include `request_id` in the message and restore it into the logging context on the worker side. For batch-originated processing, generate a `job_id` per execution unit.
+
+### Implementing context propagation, by stack
+
+| Stack | Implementation |
+|---|---|
+| NestJS | nestjs-pino + AsyncLocalStorage (set request_id / user_id in middleware). On Lambda, AWS Lambda Powertools Logger + `injectLambdaContext`. |
+| Django / Flask | structlog + contextvars. Bind in middleware; propagate to Celery etc. via headers. |
+| Laravel | Set Log Context (`Context::add()`) in middleware. Propagate to queued jobs via Context dehydration. |
+| CakePHP | Attach common fields via a Monolog Processor. |
+
+## Debug mode (DEBUG level)
+
+- **Log the start and end of each function**: `function_name`, the input (INPUT) at start, and the output (OUTPUT) plus `duration_ms` at end.
+- Apply this to public methods in the service/use-case layer by default; skip trivial getters and one-line utilities.
+- Don't scatter this by hand — implement it cross-cuttingly (decorators, interceptors, etc.).
+
+```typescript
+// NestJS example: a method decorator that logs start/end/input/output at DEBUG level
+@LogExecution() // implementation lives in a shared project library
+async approveEstimate(input: ApproveEstimateInput): Promise<EstimateResult> { ... }
+// DEBUG: {"message":"function start","function_name":"approveEstimate","input":{...},"request_id":"..."}
+// DEBUG: {"message":"function end","function_name":"approveEstimate","output":{...},"duration_ms":42,"request_id":"..."}
+```
+
+### Masking (required even at DEBUG level)
+
+- Never log passwords, tokens, API keys, or personal information (name, email, address, etc., per your project's definition) — **even at DEBUG level**. Route these through a shared masking function.
+- Truncate large payloads (file contents, large arrays) down to a count/size summary.
+
+## Recording errors
+
+- Every ERROR log must include: the exception object (with stack trace), `request_id`, the ID of the affected resource (e.g., `order_id`), and what operation was being attempted.
+- **If the project uses Sentry, capture unhandled exceptions there too.**
+  - Send them via a single global exception handler (a NestJS exception filter, or the equivalent in Django/Laravel) rather than manually capturing at each call site. (Rule of thumb: only manually capture "handled" exceptions — ones that don't propagate to the caller — when they're operationally worth knowing about.)
+  - Set `request_id` / `user_id` as Sentry tags/context so they can be cross-referenced with logs and traces.
+  - Don't report exceptions that were caught and handled as part of normal flow — that's just noise and duplicate alerting.
+- The discipline of error handling itself (never swallow, preserve the cause) follows the standards in rules/common and the silent-failure-hunter criteria.
+
+## Checklist: logs an AI can debug from
+
+Confirm new feature logging design satisfies the following:
+
+- [ ] Every log for a given request (including async work) can be retrieved by `request_id`.
+- [ ] The retrieved logs alone reveal the order of functions traversed and their inputs/outputs (at DEBUG level).
+- [ ] On failure, the ERROR log has everything: where it happened, what was being attempted, what went wrong, and what resource was affected.
+- [ ] Read together with the source comments (constraints, intent), you can form a root-cause hypothesis without running the code.
+
+## Naming and clarity (a prerequisite shared with logging)
+
+Readable logs depend on readable naming in the implementation. Follow the naming rules in `rules/common/coding-guidelines.md` (**avoid abbreviations, use full English words; name functions so they read as a sentence describing what they do**). Ideally, `function_name` alone should read like a spec.

package/dist/plugin/rules/php/coding-rules.md

@@ -0,0 +1,40 @@
+# PHP Coding Rules
+
+For language-agnostic rules, see `rules/common/coding-guidelines.md`. This document covers only PHP-specific rules.
+
+## Language and types
+
+- Add `declare(strict_types=1)` to every new file (except views such as Blade templates).
+- Declare parameter and return types on public methods. Reserve `mixed` for cases that genuinely can't be expressed as a union type.
+- Mark constructor-promoted properties `readonly` when they're never reassigned.
+- Leave formatting to Pint / PHP CS Fixer (PSR-12) — don't debate formatting in review.
+- Never commit `var_dump()` / `dd()` / `dump()` calls.
+
+## Error handling
+
+- Empty `catch (\Exception $e) {}` blocks are forbidden. Log the error and handle it (propagate, retry, notify).
+- When re-throwing, preserve the cause: `throw new XxxException('...', previous: $e)`.
+- Don't ignore the return value of APIs that return `false` on failure (e.g., `save()`).
+
+## Laravel
+
+- Define `$fillable` on every model. `$guarded = []` is forbidden.
+- Don't pass `$request->all()` directly into a save. Define a FormRequest and use `$request->validated()`; implement `authorize()` too.
+- Use `with()` / `load()` for eager loading whenever you access a relation in a loop.
+- Any user input passed into `DB::raw()` / `whereRaw()` must use parameter binding.
+- Never use Blade's `{!! !!}` on user-supplied data. If you must, comment the sanitization rationale.
+- Implement `failed()` on queued jobs and configure `$tries` / `$backoff`. Write jobs to be idempotent.
+- Authorize via `auth` middleware plus `Gate` / `Policy` — don't rely on hiding UI elements alone.
+- Define `$casts` for date, JSON, and boolean columns.
+
+## CakePHP
+
+- Never set `'*' => true` in an Entity's `$_accessible`. Explicitly list which fields allow mass assignment.
+- Use `contain()` when accessing related data in a loop.
+- Use `validationDefault()` for input format validation, and `buildRules()` for domain rules like uniqueness/existence checks — keep the two separate.
+- Always check the return value of `save()`.
+- Never interpolate variables directly into query conditions (`"field = '$value'"`). Use array conditions or parameter binding instead.
+
+## Documentation
+
+- For PHPDoc format and comment language, see `rules/documentation/`.

package/dist/plugin/rules/python/coding-rules.md

@@ -0,0 +1,40 @@
+# Python Coding Rules
+
+For language-agnostic rules, see `rules/common/coding-guidelines.md`. This document covers only Python-specific rules.
+
+## Type hints and syntax
+
+- Add type hints to public functions. Reserve `Any` for receiving data at external boundaries — narrow it to a concrete type internally.
+- Make optionality explicit with `X | None` (3.10+) or `Optional[X]`.
+- Mutable default arguments (`def f(items=[])`) are forbidden. Default to `None` and construct the value inside the function.
+- Never compare against `None` with `==`. Use `is None` / `is not None`.
+- Don't shadow builtin names (`list`, `dict`, `id`, `type`).
+- Leave formatting and import ordering to ruff / black — don't debate them in review.
+
+## Error handling
+
+- Bare `except:` and `except Exception: pass` are forbidden. Catch specific exceptions and handle them (log and propagate, retry, or notify).
+- Manage files, connections, and locks with `with` (context managers).
+- When re-raising, preserve the cause with `raise ... from e`.
+
+## Django
+
+- Always use `select_related` (FK/OneToOne) or `prefetch_related` (M2M/reverse relations) when accessing related objects in a loop.
+- Never do a read-increment-save cycle for counters; update atomically with an `F()` expression.
+- Wrap multiple writes in `transaction.atomic()`.
+- Every model change needs a migration; drop columns via a two-phase deploy (make nullable → remove references → drop the column in a later release).
+- DRF: `fields = '__all__'` on a Serializer is forbidden. List fields explicitly and set `read_only_fields`. List endpoints must be paginated.
+- Use `save(update_fields=[...])` for partial updates so you don't clobber concurrent writes.
+- Don't use signals for intra-app model-to-model coordination; prefer explicit calls from the service layer.
+
+## Flask
+
+- Use the application factory pattern (`create_app()`). Don't instantiate `app` at module level.
+- Split routes into feature-scoped Blueprints.
+- Validate `request.json` / `request.args` with marshmallow or pydantic before use.
+- Keep request-scoped state in `g` and configuration in `app.config`. Don't share state through mutable module-level globals.
+- Ensure `db.session.commit()` failures trigger a `rollback()` (via try/except/finally or a teardown handler).
+
+## Documentation
+
+- For docstring format (Google style) and comment language, see `rules/documentation/`.

package/dist/plugin/rules/typescript/coding-rules.md

@@ -0,0 +1,45 @@
+# TypeScript Coding Rules
+
+For language-agnostic rules, see `rules/common/coding-guidelines.md`. This document covers only TypeScript-specific rules.
+
+## Types
+
+- Assume `strict: true`. Any change that weakens tsconfig strictness needs justification in review.
+- `any` is forbidden as a rule. Receive external data as `unknown` and narrow it. If you must use `any`, comment why.
+- Give public/exported functions an explicit return type.
+- Prefer type guards and early returns over the non-null assertion (`value!`).
+- Don't silence a type error with an `as` cast — if a cast feels necessary, fix the type definition instead.
+- Consider type aliases or branded types for domain values (avoid parameter lists that are all bare `string`).
+
+## Asynchronous code
+
+- Always `await` a Promise, or mark an intentional fire-and-forget with a `void` prefix and a comment explaining why.
+- `array.forEach(async ...)` is forbidden. Use `for...of` (sequential) or `Promise.all` (parallel).
+- Don't sequentially `await` independent async operations — batch anything that can run in parallel with `Promise.all`.
+- Set a timeout on external calls via `AbortController` or client configuration.
+
+## Modules and syntax
+
+- Default to `const`; use `let` only when reassignment is required. Never use `var`.
+- Use only `===` / `!==` for equality comparisons.
+- Prefer a union type (`type Status = 'active' | 'inactive'`) or `as const` over `enum`.
+- Don't overuse barrel files (re-exporting everything through `index.ts`) — they cause circular imports and bundle bloat.
+
+## NestJS
+
+- Always receive input through a DTO with class-validator decorators. Set `whitelist: true` on the global `ValidationPipe`.
+- Explicitly attach a Guard (authentication + authorization) to protected routes. Any use of `@Public()` needs justification in review.
+- Direct access to `process.env` is forbidden. Use `ConfigService` with startup-time schema validation.
+- If you find yourself needing `forwardRef()`, treat it as a signal to revisit the design (extract a shared module, or move to an event-driven approach instead).
+- Convert exceptions via `HttpException` subclasses or an exception filter — never leak internal details into the response.
+
+## Next.js
+
+- Place `"use client"` close to the interactive leaf component that needs it — not at the top of a page or layout.
+- Treat Server Actions and Route Handlers as public endpoints: check the session, authorize, and validate the schema at the top of each one.
+- Never put secrets in `NEXT_PUBLIC_*` variables.
+- Use `next/image` for content images and `next/link` for internal navigation.
+
+## Documentation
+
+- For TSDoc format, comment language, and the OpenAPI workflow (NestJS → Next.js type generation), see `rules/documentation/`.

package/dist/plugin/skills/api-design/SKILL.md

@@ -0,0 +1,269 @@
+---
+name: api-design
+description: A pattern library for REST API design. Provides guidance on resource naming, choosing HTTP methods and status codes, error response formats, pagination, versioning, idempotency, authentication/authorization, and rate limiting. Use this when designing endpoints for a new API, reviewing the design of an existing API, or when you need decision criteria for a discussion about API conventions.
+---
+
+# REST API Design Patterns
+
+A collection of decision criteria and patterns for designing and implementing REST APIs. Reference this skill when adding new endpoints, revising an existing API, or doing a design review. Implementation examples favor NestJS, Django REST Framework, and Laravel.
+
+This skill covers HTTP interface design — formats and conventions. For server-side implementation details of authorization, rate limiting, and error handling, see the backend-patterns skill.
+
+## 1. Resource Design and Naming
+
+### Basic Principles
+
+- Represent resources as **plural nouns**. Don't use verbs.
+  - Good: `GET /users`, `POST /orders`, `GET /users/123`
+  - Bad: `GET /getUsers`, `POST /createOrder`
+- Use lowercase kebab-case for paths (`/purchase-orders`). For query parameters, pick either snake_case or camelCase and stay consistent within the project.
+- Represent IDs as path segments: `/users/{userId}`
+
+### Nesting Depth
+
+Keep nesting to **at most two levels** (two resources).
+
+```
+GET /users/123/orders                 # Acceptable: a user's orders
+GET /users/123/orders/456/items/789   # Avoid: too deep
+GET /order-items/789                  # Preferred: reference directly if the ID is unique
+```
+
+If a child resource can be uniquely identified without its parent, promote it to a top-level resource. Reserve nesting for expressing "belongs-to" relationships and narrowing list results.
+
+### Expressing Relationships
+
+- Express a relationship lookup either as a sub-resource (`/users/123/orders`) or as a filter (`/orders?user_id=123`). If you offer both, make sure their behavior matches.
+- Express many-to-many association/disassociation as POST/DELETE on a sub-resource.
+
+```
+POST   /articles/10/tags        # body: {"tag_id": 5} to attach a tag
+DELETE /articles/10/tags/5      # remove a tag
+```
+
+- Keep embedded related data in responses to the bare minimum (roughly an ID and a display name), or only expand it when explicitly requested (e.g. via `?include=`). Embedding deep relations unconditionally is a common source of N+1 queries and bloated payloads.
+
+## 2. HTTP Methods and Status Codes
+
+### Choosing a Method
+
+| Method | Purpose | Idempotent |
+|---|---|---|
+| GET | Retrieval. Must not have side effects | Yes |
+| POST | Create, or execute a non-idempotent action | No |
+| PUT | Replace the entire resource | Yes |
+| PATCH | Partial update | Not guaranteed (depends on design) |
+| DELETE | Delete | Yes |
+
+### When to Use Each Status Code
+
+- **200 OK**: Successful retrieval or update. Response body present.
+- **201 Created**: Successful creation. It's good practice to return the new resource's URL in the `Location` header.
+- **204 No Content**: Success with no body. The standard response for a successful DELETE.
+- **400 Bad Request**: The request is malformed syntactically (broken JSON, missing required parameters, etc.).
+- **401 Unauthorized**: Not authenticated. Token missing, invalid, or expired.
+- **403 Forbidden**: Authenticated, but not authorized for this action.
+- **404 Not Found**: The resource doesn't exist.
+- **409 Conflict**: A state conflict — unique constraint violation, optimistic lock failure, an operation that's already been processed, etc.
+- **422 Unprocessable Entity**: Well-formed but semantically invalid (validation error). Decide once, per project, how you split this from 400.
+- **500 Internal Server Error**: An unexpected server-side error. Log the details; never return them to the client.
+
+### Choosing Between 404 and 403
+
+Return 404 when you don't want an unauthorized user to even know the resource exists (e.g. another tenant's data, an unpublished draft). Return 403 when the resource's existence is public knowledge and only the action is forbidden (e.g. no edit permission on a published article). The deciding question is: "would revealing existence itself be a data leak?" In multi-tenant APIs, default to 404.
+
+## 3. Error Responses
+
+### Use One Consistent Shape
+
+Return the same error structure from every endpoint. At minimum, include a code, a message, and details.
+
+```json
+{
+  "error": {
+    "code": "VALIDATION_ERROR",
+    "message": "There were errors in your input.",
+    "details": [
+      { "field": "email", "code": "invalid_format", "message": "Email address format is invalid." },
+      { "field": "age", "code": "out_of_range", "message": "Must be between 0 and 150." }
+    ]
+  }
+}
+```
+
+- `code` should be a machine-readable constant string. Clients should branch on the code, not on the message text.
+- Return validation errors **per field** in a `details` array, so forms can display errors next to each field.
+- Aligning with RFC 9457 (Problem Details, `application/problem+json`) is also a solid choice. Either way, standardize on one shape.
+
+### Don't Leak Internal Information
+
+- Never include stack traces, raw SQL, file paths, or a library's raw exception message in a response.
+- For 5xx errors, return only a generic message and a correlation ID (request ID); log the details server-side.
+- On authentication failure, don't distinguish between "user doesn't exist" and "wrong password" in the response.
+
+### Implementation Example (NestJS)
+
+```typescript
+// An exception filter that converts all errors into the common shape
+@Catch()
+export class AppExceptionFilter implements ExceptionFilter {
+  catch(exception: unknown, host: ArgumentsHost) {
+    const res = host.switchToHttp().getResponse();
+    if (exception instanceof HttpException) {
+      res.status(exception.getStatus()).json({ error: this.toErrorBody(exception) });
+      return;
+    }
+    // Unexpected exception: log the details, return a generic message to the client
+    this.logger.error(exception);
+    res.status(500).json({
+      error: { code: 'INTERNAL_ERROR', message: 'An internal server error occurred.' },
+    });
+  }
+}
+```
+
+In Django REST Framework, point the `EXCEPTION_HANDLER` setting at a custom handler that repacks `ValidationError.detail` into the common shape. In Laravel, customize `render` via `withExceptions` in `bootstrap/app.php` (or the exception Handler).
+
+## 4. Pagination
+
+### Choosing a Strategy
+
+- **Offset-based** (`?page=2&per_page=20` / `?offset=20&limit=20`)
+  - Well suited to page-number UIs. Simple to implement.
+  - Downsides: gets slow at large offsets. Inserts/deletes mid-list cause duplicates or gaps.
+- **Cursor-based** (`?cursor=eyJpZCI6MTIzfQ&limit=20`)
+  - Well suited to infinite scroll, frequently-updated lists, and large datasets.
+  - The cursor encodes an opaque key that uniquely identifies the last row returned (e.g. `created_at` + `id`).
+
+Decision rule: if you need a total-count display and arbitrary page jumps, use offset-based. If the dataset is large, updated frequently, or performance-sensitive, use cursor-based.
+
+### Enforce a Limit Ceiling
+
+The server must **always enforce an upper bound** on `limit`/`per_page` (e.g. default 20, max 100). Never use the client-supplied value as-is.
+
+```python
+# Django REST Framework
+class StandardPagination(PageNumberPagination):
+    page_size = 20
+    page_size_query_param = "per_page"
+    max_page_size = 100  # requests above this are clamped to 100
+```
+
+Include metadata in the response: for offset-based, `total` / `page` / `per_page`; for cursor-based, `next_cursor` (null when there's no next page).
+
+## 5. Filtering, Sorting, and Search
+
+- Express filters as query parameters: `GET /orders?status=shipped&user_id=123`
+- Standardize a suffix convention for range conditions and stick to it: `?created_at_gte=2026-01-01&created_at_lt=2026-02-01` (or a `?created_at[gte]=...` style — pick one).
+- For sorting, a comma-separated list with a `-` prefix for descending order is concise: `?sort=-created_at,name`.
+- Route full-text/fuzzy search through `?q=keyword`, kept separate from structured filters.
+- Enforce an **allowlist**. The server must explicitly enumerate which fields are filterable/sortable, and must never accept an arbitrary column name (this prevents SQL injection and unintended index scans).
+
+```php
+// Laravel: restrict sortable fields with an allowlist
+$sortable = ['created_at', 'name', 'price'];
+$sort = $request->query('sort', '-created_at');
+$direction = str_starts_with($sort, '-') ? 'desc' : 'asc';
+$column = ltrim($sort, '-');
+abort_unless(in_array($column, $sortable, true), 400);
+$query->orderBy($column, $direction);
+```
+
+## 6. Versioning
+
+### Policy
+
+**Prefer URL-path versioning (`/v1/users`).** It's explicit, and it's easy to work with in routing, logging, caching, and documentation alike.
+
+Options and decision criteria:
+
+| Approach | Example | Characteristics |
+|---|---|---|
+| URL path | `/v1/users` | Most explicit. Recommended. Easy to inspect via browser or curl |
+| Header | `Accept: application/vnd.api.v1+json` | Keeps the URL clean, but harder to debug and more costly to adopt |
+| Query param | `/users?version=1` | Tends to complicate cache keys. Not recommended |
+
+### Operating Rules
+
+- Version only the major number (`v1`, `v2`). Don't bump the version for backward-compatible changes (added fields, new endpoints).
+- Only cut a new version for breaking changes (removed fields, type changes, making a field required, changed behavior).
+- Announce a deprecation date for old versions and signal it via `Deprecation` / `Sunset` headers.
+- For internal-only APIs, it's reasonable to skip versioning and deploy the client and server together. For public APIs, versioning is mandatory.
+
+## 7. Idempotency
+
+- Implement **GET, PUT, and DELETE as idempotent**: sending the same request multiple times must leave the resource in the same state.
+  - A second DELETE may return 404 (the state — "doesn't exist" — is unchanged). If you'd rather keep the client logic simple, returning 204 again on the second call is also acceptable.
+- **POST is not idempotent**. You need a defense against duplicate execution from network failures or retries (double charges, duplicate orders).
+
+### Idempotency Keys
+
+The client sends a unique-per-request key (a UUID) in an `Idempotency-Key` header, and the server stores the key alongside the processing result for some retention window. On a retry with the same key, **return the stored response as-is**.
+
+```typescript
+// NestJS: sketch of duplicate-POST protection via an idempotency key
+@Post('payments')
+async create(@Headers('idempotency-key') key: string, @Body() dto: CreatePaymentDto) {
+  if (!key) throw new BadRequestException('Idempotency-Key header is required');
+  const cached = await this.idempotencyStore.find(key);
+  if (cached) return cached.response;           // Retry: return the stored result
+  const result = await this.payments.create(dto);
+  await this.idempotencyStore.save(key, result, { ttl: '24h' });
+  return result;
+}
+```
+
+- Store the key under a unique constraint, and prevent concurrent-execution races with a transaction or lock.
+- This is mandatory for any POST where duplicate execution causes real harm — payments, orders, notification sends.
+
+## 8. Authentication and Authorization
+
+### Token Authentication Basics
+
+- Send tokens via the `Authorization: Bearer <token>` header. Never put a token in a query parameter (it leaks into logs and referrers).
+- Keep access tokens short-lived (minutes to an hour) and refresh them with a refresh token.
+- 401 means "authentication failed"; 403 means "authenticated, but not authorized." Don't conflate them.
+
+### Per-Resource Authorization Checks
+
+Keep authentication (who you are) separate from authorization (what you can do), and **always check ownership/permission against the specific resource being accessed**. Letting a request through on authentication alone, with direct object access by ID, is the textbook API vulnerability (IDOR / BOLA).
+
+- Filter list endpoints at the query level. Filtering after fetching breaks pagination and result counts.
+- When denying access to a single resource because the caller lacks permission, return 404 if you want to hide its existence (see section 2).
+- For the authorization implementation mechanics and code examples (NestJS Guards, Laravel Policies, DRF `permission_classes`, etc.), see backend-patterns.
+
+## 9. Rate Limiting
+
+- Limit request counts per user (or token, or IP). Apply stricter limits to unauthenticated endpoints.
+- On exceeding the limit, return **429 Too Many Requests** with a `Retry-After` header telling the client how many seconds until it can retry.
+- Report the current limit state in every response's headers.
+
+```
+RateLimit-Limit: 100
+RateLimit-Remaining: 42
+RateLimit-Reset: 1718100000
+Retry-After: 30          # only present on 429
+```
+
+(The `X-RateLimit-*` header family is also widely used. Pick one convention per project.)
+
+- Apply a separate, stricter limit to authentication-related endpoints (login, password reset) than to the rest of the API.
+- For implementation mechanics (each framework's throttling middleware, etc.), see backend-patterns.
+
+## 10. Design Review Checklist
+
+- [ ] Are paths plural nouns, with nesting no deeper than two levels?
+- [ ] Does each endpoint's method and status codes (including 201/204/409/422) match its actual semantics?
+- [ ] Do all endpoints return errors in the same shape? Are validation errors broken out per field?
+- [ ] Do errors avoid leaking internal information (stack traces, SQL, file paths)?
+- [ ] Does every list endpoint paginate, with the limit enforced server-side?
+- [ ] Are filterable/sortable fields restricted to an allowlist?
+- [ ] Is the versioning policy defined, including how breaking changes are handled?
+- [ ] Do POSTs where duplicate execution causes real harm have idempotency-key protection?
+- [ ] Is there object-level authorization on every resource (IDOR protection)? Is the 403/404 policy consistent?
+- [ ] Is rate limiting configured, with 429 and RateLimit headers reported?
+
+## Related
+
+- Use the `/code-review` command for post-implementation code review.
+- Delegate detailed API implementation review criteria (security, performance, convention compliance) to code-reviewer subagents.