docs: update Claude docs from PR review analysis

[claude]

Summary

Weekly analysis of PR comments (2026-08-24 -> 2026-08-31).
Analyzed 10 PRs with 73 resolved/effectively-resolved threads. Found 4 actionable insights.

Changes

agent_docs/rules.md

• Extend transform completeness rule to cover method overloads — when getById has multiple overloads (positional vs options-object form), each dispatch branch in the implementation has its own transform call, and a completeness test on the positional form does not exercise the options-object branch. Both branches need their own completeness test.
  Source: PR refactor(queues): fold WithMethods variants into getAll and getById [PLT-104203] #681 — reviewer @swati354 flagged that the options-form getById overload lacked a completeness check despite the positional form having one.

  "the options-object getById overload has its own transformFn closure (separate from the positional form) but the test suite for this overload has no transform completeness check"

• Clarify polling-loop try-catch exception — the "NEVER wrap integration test calls in try/catch" rule now documents the narrow exception: polling loops that handle transient visibility errors may catch, but scope the catch to only the specific transient call. State-changing operations (e.g., retry(), cancel()) must be outside the catch so their failures propagate naturally.
  Source: PR test(maestro): reuse an existing faulted instance before seeding one for retry #688 — reviewer @claude identified that retry() was inside a catch scoped for getById visibility errors; a retry() failure would be swallowed and faultRetried never set.

  "The retry() call sits inside the try block whose catch is scoped to swallow transient getById visibility errors. If retry() throws, the exception is silently swallowed"

agent_docs/conventions.md

• Interface synchronization on method signature changes — when a public method signature changes (new params, new overloads), the corresponding interface declaration (IUiPath, {Entity}ServiceModel, etc.) must also be updated. An interface holding the old signature causes TypeScript errors at any call site holding an interface reference.
  Source: PR feat(auth): end the platform session on logout (OIDC RP-initiated logout) [PLT-107228] #636 — reviewer @claude caught that IUiPath still declared logout(): void while the implementation was updated to logout(options?: LogoutOptions): void.

  "IUiPath still declares logout(): void with no parameters, while this implementation now accepts options?: LogoutOptions. Any internal caller holding an IUiPath reference who tries instance.logout({ endCloudSession: true }) will get a TypeScript error"

• Do NOT extend FolderScopedOptions for services without OData — FolderScopedOptions inherits expand/select from BaseOptions; extending it for services that don't accept OData params leaks those fields into query parameters and request bodies. Use a service-specific scoping type instead.
  Source: PR feat(integration-service): add folderId/folderPath scoping options [APPS-35792] #641 — PR author @anil-uipath explained why Integration Service needed its own scoping type.

  "it can't be reused because FolderScopedOptions extends BaseOptions, so it carries OData query params expand and select. Integration Service endpoints don't accept these OData query params"

No changes

• CLAUDE.md — no relevant insights found
• Agents.md — no relevant insights found
• agent_docs/architecture.md — no relevant insights found

PRs Analyzed

PR	Title	Resolved threads
#698	refactor(integration-service): remove Connections reauthenticate API	0
#635	feat(data-fabric): mark entity + choiceset schema-lifecycle methods @experimental	8
#675	feat(core): zero-config authentication from the execution context	9
#688	test(maestro): reuse an existing faulted instance before seeding one for retry	4
#683	feat(refs): add resolveRefToId helper for the resource-resolution framework	4
#681	refactor(queues): fold WithMethods variants into getAll and getById	3
#592	chore(docs): JSDoc completeness validation check	2
#669	feat(functions): acquire a Studio Web license before invoking	12
#636	feat(auth): end the platform session on logout (OIDC RP-initiated logout)	7
#641	feat(integration-service): add folderId/folderPath scoping options	5

[claude]

✅ No issues found. Checked for bugs and CLAUDE.md compliance.