refactor: inherit service JSDoc from ServiceModel instead of duplicating (#594)

Service classes already implement their {Entity}ServiceModel interface, so
TypeScript inherits the interface's JSDoc onto each method's IDE hover when
the class method has no JSDoc of its own. The class-side JSDoc was a
duplicate that had already drifted out of sync across many methods.

Removes the duplicated class-side method JSDoc (170 methods across 28
files); docs now live only on the ServiceModel interfaces. Also fixes 7
interface docs that were thinner than the class copy (reordered
@experimental below the summary on agent-memory/governance methods; added
missing summaries to Cases/MaestroProcesses getAll), and updates rules.md.

Consumer hover is unchanged (summary + params + returns + example),
verified via the TS language service on source and the built .d.ts.
typecheck + lint clean; 2059 unit tests pass.

Generated with Claude Code

Co-authored-by: Claude <noreply@anthropic.com>

Author: Raina451

agent_docs/rules.md

@@ -59,7 +59,7 @@ JSDoc comments in `src/models/{domain}/*.models.ts` are the **source of truth fo
 - Use `<paramName>` placeholder convention for IDs in examples.
 - Use camelCase in examples, matching SDK response format. **NEVER** use PascalCase in JSDoc examples — users will write broken code.
 - Keep JSDoc in sync with method names.
-- **Keep JSDoc on service class methods in sync with `{Entity}ServiceModel`** — both the models file and the service implementation file must have identical JSDoc for each public method. `ServiceModel` is the source of truth for docs, but the service class copy aids developer navigation and IDE tooltips. When updating JSDoc on one, update the other.
+- **Do NOT duplicate JSDoc on service class methods** — service classes `implements {Entity}ServiceModel`, and TypeScript inherits the interface's JSDoc onto the implementing method's IDE hover when the class method has no JSDoc of its own. Write method JSDoc **only** on `{Entity}ServiceModel`; leave the service class method bare (keep the `@track` decorator and body). This makes the interface the single source of truth for both the docs site (TypeDoc renders the interface) and IDE tooltips (inherited via `implements`), so the two can't drift. A partial JSDoc comment on the class method silently disables inheritance — so class methods must carry **no** method JSDoc at all. Methods not declared on the interface keep their own JSDoc (nothing to inherit).
 - **When a method supports `expand`**, show multiple expandable entities in the `@example` (e.g., `expand: 'Robot,Machine,Release'`) so users see the comma-separated pattern.
 - **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.

src/models/agents/memory/memory.models.ts

@@ -34,15 +34,14 @@ import {
  */
 export interface AgentMemoryServiceModel {
   /**
+   * Gets agent memory state over time, with optional filters.
    *
    * @experimental
    *
    * /// warning
    * Preview: This method is experimental and may change or be removed in future releases.
    * ///
    *
-   * Gets agent memory state over time, with optional filters.
-   *
    * @param options - Optional time window and scope filters
    * @returns Promise resolving to an array of {@link AgentMemoryGetTimelineResponse}, one per time bucket.
    * @example
@@ -72,15 +71,14 @@ export interface AgentMemoryServiceModel {
   getTimeline(options?: AgentMemoryGetTimelineOptions): Promise<AgentMemoryGetTimelineResponse[]>;
 
   /**
+   * Gets the number of agent memory calls (accesses to the memory store) over time, with optional filters.
    *
    * @experimental
    *
    * /// warning
    * Preview: This method is experimental and may change or be removed in future releases.
    * ///
    *
-   * Gets the number of agent memory calls (accesses to the memory store) over time, with optional filters.
-   *
    * @param options - Optional time window and scope filters
    * @returns Promise resolving to an array of {@link AgentMemoryGetCallsTimelineResponse}, one per time bucket.
    * @example
@@ -110,15 +108,14 @@ export interface AgentMemoryServiceModel {
   getCallsTimeline(options?: AgentMemoryGetCallsTimelineOptions): Promise<AgentMemoryGetCallsTimelineResponse[]>;
 
   /**
+   * Gets the top memory spaces by memory count, with optional filters
    *
    * @experimental
    *
    * /// warning
    * Preview: This method is experimental and may change or be removed in future releases.
    * ///
    *
-   * Gets the top memory spaces by memory count, with optional filters
-   *
    * @param options - Optional limit, time window, and scope filters
    * @returns Promise resolving to an array of {@link AgentMemoryGetTopSpacesResponse}, ranked by memory count.
    * @example

src/models/governance/governance.models.ts

@@ -38,15 +38,14 @@ import type {
  */
 export interface GovernanceServiceModel {
   /**
+   * Gets per-policy enforcement decisions across the requested time range.
    *
    * @experimental
    *
    * /// warning
    * Preview: This method is experimental and may change or be removed in future releases.
    * ///
    *
-   * Gets per-policy enforcement decisions across the requested time range.
-   *
    * Each result row represents one policy's verdict within a single governance enforcement event.
    * A single user action can produce multiple rows when multiple policies were consulted.
    * Results are ordered by event start time, descending.
@@ -96,15 +95,14 @@ export interface GovernanceServiceModel {
   >;
 
   /**
+   * Gets aggregate governance enforcement counts across the requested time range.
    *
    * @experimental
    *
    * /// warning
    * Preview: This method is experimental and may change or be removed in future releases.
    * ///
    *
-   * Gets aggregate governance enforcement counts across the requested time range.
-   *
    * Returns the total number of evaluations along with how many resolved to
    * `Allow`, `Deny`, or `NoOp`.
    *

src/models/maestro/cases.models.ts

@@ -24,6 +24,8 @@ import { TopQueryOptions, IncidentTimelineResponse, InstanceStatusTimelineRespon
  */
 export interface CasesServiceModel {
   /**
+   * Get all case management processes with their instance statistics
+   *
    * @returns Promise resolving to an array of {@link CaseGetAllWithMethodsResponse}
    * @example
    * ```typescript

src/models/maestro/processes.models.ts

@@ -25,6 +25,8 @@ import { TopQueryOptions, IncidentTimelineResponse, InstanceStatusTimelineRespon
  */
 export interface MaestroProcessesServiceModel {
   /**
+   * Get all processes with their instance statistics
+   *
    * @returns Promise resolving to array of MaestroProcess objects with methods
    * {@link MaestroProcessGetAllResponse}
    * @example