docs: update Claude docs from PR review analysis

Agents.md

@@ -17,6 +17,10 @@ npm run typecheck        # tsc --noEmit
 npm run docs:api         # typedoc + post-process
 ```
 
+## Release workflow
+
+- Version bumps go in a **separate PR** — never include a version bump in a feature or fix PR. Other in-flight changes may need to ship in the same version, so the bump is always a dedicated step.
+
 @agent_docs/architecture.md
 @agent_docs/conventions.md
 @agent_docs/rules.md

agent_docs/conventions.md

@@ -22,6 +22,7 @@
 - Every public service method must be decorated with `@track('ServiceName.MethodName')` for telemetry — gaps are invisible until production debugging, when they're expensive.
 - Use named imports/exports (avoid default exports). Use barrel exports (`index.ts`) for public API. Never export internal types from barrel exports.
 - **Barrel files must use `export * from`**, not `export type * from`. Using `export type` re-exports only type declarations and silently drops runtime values (class constructors, enums), causing `undefined` errors for SDK consumers who import them.
+- When a service method makes multiple independent API calls (e.g., chunk-based key resolution), parallelize them with `Promise.all` — sequential calls compound latency unnecessarily.
 
 ## Type naming
 

agent_docs/rules.md

@@ -55,6 +55,7 @@ JSDoc comments in `src/models/{domain}/*.models.ts` are the **source of truth fo
 - **Add a one-line description of what the response includes** beyond the method signature (e.g., "Returns the full job details including state, timing, and input/output arguments. Use `expand` to include related entities like Robot, Machine, or Release").
 - **NEVER** reference unrelated parameters in JSDoc examples — keep examples focused on the method being documented. If `getOutput()` doesn't accept `folderId`, don't show `folderId` in its example.
 - **Show bare minimum call first** in the first `@example`, then a second example with filtering/options. Never use `$` prefix on OData params in examples (`expand` not `$expand`).
+- **NEVER** assign a `void` return to a variable in JSDoc examples — if a method returns `Promise<void>`, write `await service.method()` not `const result = await service.method()`. Assigning void implies the return value is usable, which misleads users.
 - **Add JSDoc to non-obvious enum values** — if an enum has values whose meaning isn't clear from the name alone, add a brief comment to each value.
 
 ## Post-implementation verification checklist