docs: document new generator features and stale-cleanup fix

- Generator options tables (root README, generator README, CLAUDE.md):
  add verbose flag
- Key properties list (root README): add cookie params, binary body,
  response unions, @deprecated JSDoc
- Generator README anatomy sections: add GET with cookie params,
  deprecated operations, binary/octet-stream body, response type unions
- Stale cleanup section (generator README): expand to cover index.ts
  barrel removal and empty tag folder deletion
- Key decisions table (CLAUDE.md): update stale cleanup row; add rows
  for cookie params, @deprecated, response unions, binary body

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: constantant

CLAUDE.md

@@ -208,8 +208,8 @@ provideHttpClient(withInterceptors([myapiDigestAuthInterceptor])),
 5. `@apidevtools/swagger-parser` — dereference all `$ref` chains for endpoint extraction.
 6. `parseSecuritySchemes(api)` — extract security schemes into `SecuritySchemeModel[]`.
 7. `buildEndpoints(api, tags, convention)` — map each operation to `EndpointModel`.
-8. `renderTokenFile()` / `renderSecurityTokenFile()` — emit token files as strings.
-9. Stale file cleanup — delete any `.token.ts` / `.security-token.ts` files present before the run that weren't produced this run.
+8. `renderTokenFile()` / `renderSecurityTokenFile()` / `renderMockFile()` — emit token and mock files as strings.
+9. Stale file cleanup — snapshot `.token.ts`, `.security-token.ts`, `.mock.ts`, `mocks.manifest.json`, `index.ts`, and `index.mock.ts` files before the run; delete any that weren't produced this run.
 10. `@nx/devkit` `formatFiles()` — run Prettier over all written files.
 
 ### Schema inputs (`schema.json`)
@@ -223,7 +223,8 @@ provideHttpClient(withInterceptors([myapiDigestAuthInterceptor])),
   "namingConvention":"camel | kebab (default: kebab for filenames, SCREAMING_SNAKE for token names)",
   "providedIn":      "none | root (default: none)",
   "includeMocks":    "true | false (default: false) — emit *.mock.ts alongside each *.token.ts",
-  "specId":          "string — embedded in MockResourceMeta._meta; must match the specId used when importing the spec into the DevTools panel"
+  "specId":          "string — embedded in MockResourceMeta._meta; must match the specId used when importing the spec into the DevTools panel",
+  "verbose":         "true | false (default: false) — print +/~/- summary of created/updated/deleted files after generation"
 }
 ```
 
@@ -484,7 +485,11 @@ Conventional Commits PR title (it becomes the squash commit). See
 | Security tokens — digest | `InjectionToken<HttpInterceptorFn>` + named host-scoped interceptor | Challenge-response at HTTP layer; base URL token prevents cross-API interceptor conflicts |
 | Remote spec URL | `specPath` accepts `http://`/`https://` URLs — downloads to a temp file, then processes identically to local files | Eliminates the `curl` pre-step; temp file is cleaned up in the `finally` block regardless of success/failure |
 | Header params | `in: header` params become named string args (required or optional), rendered into a `headers` block alongside auth scheme headers | Consistent with how path params are surfaced; keeps the public API surface explicit and typed |
-| Stale file cleanup | Before generation, snapshot existing `.token.ts`/`.security-token.ts` files; after generation, delete any that weren't produced this run | Prevents phantom exports when endpoints are removed or `tagFilter` narrows the output |
+| Cookie params | `in: cookie` params become named string args (after header params) and are combined into a single `Cookie` header using `[...].join('; ')`; optional cookies use a conditional spread | Cookie params work in SSR (Node HttpClient); browser Cookie header is a forbidden header — document that constraint at usage time rather than in the type |
+| `@deprecated` JSDoc | Generator emits `/** @deprecated */` above the `InjectionToken` constant when `operation.deprecated === true` in the spec | TypeScript deprecation warning at the inject() call site; no runtime cost |
+| Response type unions | Generator collects all 2xx codes with `application/json` content (not just the first); emits a `\|`-union type alias when multiple codes exist | Some endpoints legitimately return 200 (update) or 201 (create) with different shapes; a union preserves that information instead of silently picking one |
+| Binary body | When `requestBody` has no json/form/multipart content type (e.g. `application/octet-stream`, `image/*`), the generated `Body` type alias is `Blob \| ArrayBuffer` instead of the `paths` chain | `paths[...]['requestBody']['content']['application/octet-stream']` would be `string \| Blob` from openapi-typescript — not useful for Angular's `HttpClient` which needs the actual binary object |
+| Stale file cleanup | Before generation, snapshot `.token.ts`, `.security-token.ts`, `.mock.ts`, `mocks.manifest.json`, `index.ts`, and `index.mock.ts` files; after generation, delete any that weren't produced this run | Prevents phantom exports when endpoints are removed or `tagFilter` narrows the output; including barrel files ensures orphaned tag folders (with their `index.ts`) are also removed |
 | Nx executor | `@constantant/openapi-resource-gen:generate` executor wraps the generator so users can declare a `generate` target in `project.json` | `nx run mylib:generate` is easier to remember and can be wired into CI; uses `FsTree`+`flushChanges` from `nx/src/generators/tree` (not in `@nx/devkit` public API) |
 | Lint cache invalidation | `@nx/eslint:lint` has an `externalDependencies` input listing the ESLint plugin packages (`eslint`, `angular-eslint`, `typescript-eslint`, `@eslint/js`, …) in `nx.json` | A rule-strengthening dependency bump (e.g. an `angular-eslint` major) must re-lint against current source, not return a stale cached "pass". Without this, the angular-eslint 22 upgrade merged green while leaving `master` failing `prefer-on-push-component-change-detection` |
 | `includeMocks` + MockResourceMeta | Generator emits `*.mock.ts` alongside each `*.token.ts`; each mock file exports `_meta: MockResourceMeta` with `specId`, `operationId`, `path`, `method`, `tag` | DevTools panel needs this metadata to display operation info and match mock keys to spec entries |

README.md

@@ -94,6 +94,7 @@ Re-run the generator command whenever your spec changes — it overwrites genera
 | `providedIn` | no | `none` | `none` (use `provideX()` helpers) or `root` (self-registering) |
 | `includeMocks` | no | `false` | Co-generate `.mock.ts` providers, `index.mock.ts` barrels, and `mocks.manifest.json` — requires `@constantant/openapi-resource-mocks` |
 | `specId` | no | derived | Identifier embedded in `MockResourceMeta` and `mocks.manifest.json`. Defaults to `baseUrlToken` with `_BASE_URL` stripped (e.g. `PETSTORE_BASE_URL` → `petstore`). Must match when importing into the DevTools panel. |
+| `verbose` | no | `false` | Print a `+`/`~`/`-` summary of created, updated, and deleted files after generation. |
 
 See [`tools/openapi-resource-gen/README.md`](tools/openapi-resource-gen/README.md) for full documentation.
 
@@ -148,6 +149,10 @@ Key properties of every generated file:
 - **Request suppression** — returning `undefined` from the lambda keeps the resource idle (no request)
 - **Scoped base URL** — each lib has its own `InjectionToken<string>` so different parts of an app can point at different environments
 - **Header params** — `in: header` parameters become named string args on the factory function and are merged into the `headers` object alongside any auth scheme headers
+- **Cookie params** — `in: cookie` parameters become named string args (after header params) and are combined into a single `Cookie` header value; optional cookies are conditionally included
+- **Binary body** — non-json/form/multipart request bodies (e.g. `application/octet-stream`, `image/*`) emit `Blob | ArrayBuffer` as the body type
+- **Response type unions** — when an endpoint returns multiple 2xx JSON response codes (e.g. 200 and 201), the generated `Response` type alias is a union of all of them
+- **`@deprecated` JSDoc** — operations marked `deprecated: true` in the spec emit `/** @deprecated */` above the token constant, surfacing the warning at every `inject()` call site
 - **Security tokens** — signal-based schemes (`bearer`, `basic`, `apiKey`) emit `InjectionToken<Signal<string | null>>`; `digest` schemes emit `InjectionToken<HttpInterceptorFn>` + a named, host-scoped interceptor that delegates only to requests matching the lib's base URL, preventing cross-API conflicts
 
 ---

tools/openapi-resource-gen/README.md

@@ -88,6 +88,7 @@ Re-run the same command whenever your spec changes — the generator overwrites
 | `providedIn` | no | `none` | `none` or `root` — see table above |
 | `includeMocks` | no | `false` | Emit a `.mock.ts` per endpoint plus `index.mock.ts` barrels and a `mocks.manifest.json` — requires [`@constantant/openapi-resource-mocks`](https://www.npmjs.com/package/@constantant/openapi-resource-mocks) |
 | `specId` | no | derived from `baseUrlToken` | Identifier embedded in every generated `MockResourceMeta` and in `mocks.manifest.json`. Defaults to `baseUrlToken` with `_BASE_URL` stripped and lowercased (e.g. `PETSTORE_BASE_URL` → `petstore`). Must match the value used when importing the spec into the DevTools panel. |
+| `verbose` | no | `false` | Print a `+`/`~`/`-` summary of created, updated, and deleted files after generation. |
 
 ---
 
@@ -218,8 +219,13 @@ are never accidentally bundled into a production build.
 
 ### Stale cleanup
 
-Re-running the generator without `--includeMocks` deletes any `.mock.ts` files from
-the previous run. Removing an endpoint from the spec also removes its `.mock.ts`.
+Re-running the generator cleans up any file it no longer produces. This includes:
+- `.token.ts` / `.mock.ts` for removed endpoints
+- `.security-token.ts` for removed security schemes
+- `{tag}/index.ts` / `{tag}/index.mock.ts` barrel files when all endpoints for a tag are removed (e.g. after narrowing `--tagFilter`)
+- `mocks.manifest.json` when `--includeMocks` is dropped
+
+Stale tag folders (left empty after their barrels are removed) are also deleted.
 
 ---
 
@@ -303,6 +309,42 @@ headers: {
 },
 ```
 
+### GET with cookie params
+
+`in: cookie` parameters become named string args placed after header params. Required
+cookies are required args; optional ones get `?`. All cookies for the endpoint are
+combined into a single `Cookie` header value at request time:
+
+```typescript
+export const GET_CURRENT_USER = new InjectionToken<
+  (session: string, theme?: string) => ReturnType<typeof httpResource<GetCurrentUserResponse>>
+>('GET_CURRENT_USER');
+```
+
+Inside the resource the cookie header is built as an array join, so absent optional
+cookies are not included:
+
+```typescript
+headers: {
+  Cookie: [`session=${session}`, ...(theme != null ? [`theme=${theme}`] : [])].join('; '),
+},
+```
+
+> **Browser note:** The `Cookie` header is a [forbidden header name](https://developer.mozilla.org/en-US/docs/Glossary/Forbidden_header_name) — browsers silently block it. Cookie params work correctly in Angular Universal / SSR (Node's `HttpClient` has no such restriction). For browser-only apps, set cookies via `document.cookie` before making the request and pass `withCredentials: true`.
+
+### Deprecated operations
+
+When the spec marks an operation with `deprecated: true`, the generator emits a
+`/** @deprecated */` JSDoc comment immediately above the token constant:
+
+```typescript
+/** @deprecated */
+export const OLD_ENDPOINT = new InjectionToken<...>('OLD_ENDPOINT');
+```
+
+TypeScript then surfaces the deprecation warning at every `inject(OLD_ENDPOINT)` call
+site with no runtime cost.
+
 ### Mutation (POST/PUT/PATCH/DELETE)
 
 The factory returns `(body: BodyType | Signal<BodyType>) => httpResource(...)`.
@@ -382,6 +424,38 @@ const submitForm = inject(SUBMIT_FORM);
 readonly result = submitForm({ username: 'alice', password: 's3cr3t' });
 ```
 
+#### Binary / octet-stream body
+
+When the spec declares `application/octet-stream`, `image/*`, `application/pdf`, or
+any other non-JSON/form/multipart content type, the generated body type is
+`Blob | ArrayBuffer` rather than a `paths[...]` derivation:
+
+```typescript
+export type UploadBinaryBody = Blob | ArrayBuffer;
+
+export const UPLOAD_BINARY = new InjectionToken<
+  (body: UploadBinaryBody | Signal<UploadBinaryBody>)
+    => ReturnType<typeof httpResource<UploadBinaryResponse>>
+>('UPLOAD_BINARY');
+```
+
+Pass a `Blob`, `File`, or `ArrayBuffer` directly — `HttpClient` sends binary bodies
+as-is without any encoding step.
+
+### Response type unions
+
+When an endpoint can return JSON on multiple 2xx status codes (e.g. `200` for an
+update and `201` for a create), the generated `Response` type alias is a union:
+
+```typescript
+export type UpsertResourceResponse =
+  | paths['/resources']['put']['responses']['200']['content']['application/json']
+  | paths['/resources']['put']['responses']['201']['content']['application/json'];
+```
+
+The `httpResource<UpsertResourceResponse>` call site receives a value that is the
+union of all possible success shapes.
+
 ### Security schemes
 
 The generator emits one file per security scheme. Two patterns are used depending on the