api-tsdoc

name	api-tsdoc
description	Enrich TSDoc comments in Smartico's public-api SDK (`/Users/aa/Desktop/SM/public-api/src/`) by mining real-world usage from the `ach` codebase and validating against server-side handlers. Use when the user asks to document, enrich, or improve TSDoc for any `_smartico.api.*` method or related WSAPI type.

api-tsdoc

Enrich a Smartico public-api SDK method's TSDoc with real-world implementation insights from ach (the in-tracker gamification UI) + r-server (the protocol-handler backend). Apply edits directly, never commit.

When to invoke

• User types /api-tsdoc <method-or-feature>
• User asks: "enrich TSDoc for X", "document X using ach", "improve SDK docs for X"
• User points at a _smartico.api.* method whose TSDoc is thin

Hard scope rules

• ONLY edit .ts files under /Users/aa/Desktop/SM/public-api/src/ (the domain class files: WSAPI/WSAPI<Domain>.ts — see "File layout" below — plus WSAPI/WSAPITypes.ts for return-type interfaces, occasionally SmarticoLib/*).

• ONLY write UI guidance to .md files under /Users/aa/Desktop/SM/public-api/docs/ui/<domain>/UIGuide_<methodName>.md — never inline long UI sections in TSDoc. The method's TSDoc gets a single **UI guidance**: see [link] reference.

• NEVER edit /Users/aa/Desktop/SM/public-api/docs/api/** — TypeDoc-generated; gets overwritten by npm run doc.

• NEVER run npm run doc — human-triggered separately after a batch of approved enrichments.

• NEVER commit, stage, or push. All changes wait for human review.

• NEVER skip the validation pass — server-side semantics (Java handlers in r-server) are the most common place ach-only extraction misses something. The first round on requestMissionOptIn literally got the error-code list wrong without validation.

• NEVER paste ach-internal types (AchievementOptinRequest, ProtocolMessage, Context.interaction.*, anything from lib-common/protocol/*) into examples or @remarks. Translate to SDK-shaped behavior.

• NEVER use pseudo-API handlers in @example blocks (showError, showUnlockTasks, refreshUI, notify, toast, etc.). Instead, use console.log() / console.error() with descriptive messages that state what the consumer's UI should actually do at that point. The example then doubles as documentation of expected UI behavior without committing to any particular framework. Bad: showError(r.err_message) Good: console.error('[smartico] opt-in failed — show error toast with this message to the user:', r.err_message)

• NEVER expose internal Smartico implementation details in /** */ blocks. This is the public SDK contract — 3rd-party integrators read these docs. Specifically banned in @remarks / @example / @param / @returns:

  • DB schemas / table / column / function names: cjm_ach.ach_category, ach_completed, ach_completed_recurring, cjm.users, sm_crm.*, spk_ai.*, fnc_get_user_achievements_map, fnc_ach_unlock, etc. Talk about behavior, not storage.
  • Server-side class / method / file references: AchievementService.java, AchievementOptinRequestHandler, AchievementsMultiLabelConsumer:L182-191, WsSessionManager.postProcess, TagReplacementDbService, AchievementsDbService.optInToAchievement, etc. Talk about what the server does, not which class does it.
  • Internal numeric status / enum codes: "(status 1)", "(status 4)", "category_status_id = 1", "ach_status_id = 7". Refer to public enums by name (e.g. AchievementStatus.RECURRING, AchievementAvailabilityStatus) but never expose raw numeric codes for internal-only enums.
  • Internal label-setting keys: DEMO_ALWAYS_SEND_RELOAD_ACHIEVEMENT, SHOW_COMPLETED_GAMIFICATION_NOT_VISIBLE, GAMIFICATION_VISTOR_MODE_USER_EXT_ID. Talk about configurable behavior, not setting keys.
  • Internal cache / infra names: OCache, ECacheContext, CACHE_DATA_SEC, "server-side OCache 60 s", "HTTP Cache-Control: max-age=300", "BigQuery analytics event", "Kafka event", "in-memory cache invalidated", "updateMissions()". Say "the SDK caches the response for 30 seconds" — not which class/key/constant implements it.
  • Jira ticket refs: (SMR-46737), DESK-1234. Internal tracker noise.
  • BO admin paths: "BO → Gamification → Settings → Categories". Say "configured by the operator" or omit. Operator-facing UI paths are out of scope for the SDK contract.
  • File:line refs into r-server / bo-server / ach: AchievementService.java:L375-405, AchievementsDbService:L3378-3385. These belong in the agent's return summary for the human reviewer, not in any source-file comment.
  • ClassId enum values (e.g. ClassId.MISSION_OPTIN_RESPONSE, ClassId.BUY_SHOP_ITEM_RESPONSE, ClassId.CLIENT_PUBLIC_PROPERTIES_CHANGED_EVENT, ClassId.RELOAD_ACHIEVEMENTS_EVENT). Even though ClassId is technically exported, it's a protocol-layer abstraction the SDK consumer should never need to think about. The consumer's mental model is "I call getMissions({onUpdate}) and my callback fires" — NOT "I subscribe to MISSION_OPTIN_RESPONSE". Every push event reaches the consumer via some API surface (an onUpdate callback on a fetch method, a Promise resolution on a mutation, a state-update on a user-profile field). Describe the API trigger, not the wire-level event. Examples:
    • Bad: {@link ClassId.MISSION_OPTIN_RESPONSE} — fired after opt-in.
    • Good: Fires after \requestMissionOptIn(...)` resolves (any `err_code`).`
    • Bad: the SDK refreshes on a {@link ClassId.BUY_SHOP_ITEM_RESPONSE} push
    • Good: the SDK refreshes after every \buyStoreItem(...)` call resolves`
    • Bad: balances arrive via {@link ClassId.CLIENT_PUBLIC_PROPERTIES_CHANGED_EVENT}
    • Good: balances on \getUserProfile()` are kept live by the SDK's user-properties channel`

  What IS safe to reference in /** */:

  • Public status/enum types: AchievementStatus, AchievementAvailabilityStatus, SAWSpinErrorCode, JoinClanErrorCode, etc. — anything export enum-ed under src/Missions/, src/MiniGames/, etc. Reference by enum name, not by numeric value.
  • Fields on the public return type (e.g. TMissionOrBadge.is_opted_in, mission.ach_public_meta.hide_locked_mission) — these are part of the SDK contract.
  • Numeric error codes returned by the SDK method itself (e.g. 40010, 40014) — these reach the consumer in err_code, so consumers must branch on them. Document the codes WITHOUT exposing which internal handler emits them.
  • Other public SDK methods ({@link buyStoreItem}, {@link getMissions}) — these are part of the SDK contract.

  Reference UI naming: when documenting "the reference UI does X" (e.g. ach's specific rendering pattern), call it "the default Smartico UI" — not "the official tracker", "ach", "the tracker UI", or any internal name. This matches public marketing language.

  Rule of thumb: if removing the internal-name reference makes the doc less useful to a 3rd-party widget developer, you needed a better consumer-facing phrasing — not the internal name. Internal-reference audit trails belong in the agent's return summary to the human reviewer, NOT in source-file comments.

Type / method documentation contract

A clean separation between the type docs (WSAPITypes.ts field comments) and the method docs (WSAPI<Domain>.ts TSDoc) keeps both useful without bifurcating information across two large surfaces.

WSAPITypes.ts field comments — terse, lookup-friendly reference. One short sentence per field stating:

• What it is (the SDK field name and what it represents)
• Type if non-obvious (e.g. "Unix ms timestamp", "0–100 integer percentage")
• Null/undefined semantics ("Undefined for badges", "Null when unlimited")
• Cross-reference to a public enum if the values come from one

That's it. Do NOT expand field comments into multi-paragraph behavioral essays. Consumers and AI agents look these up; they don't read them top-to-bottom.

Method WSAPI<Domain>.ts TSDoc — narrative, usage-oriented prose. Explains how to use the call:

• Preconditions, error codes, refresh semantics, idempotency, side effects, cache, visitor mode
• WHEN fields update relative to the call (e.g. "after requestMissionOptIn(...) resolves, is_opted_in flips on the next refresh — not optimistically")
• Recommended UI patterns that depend on field combinations
• Inline references to specific fields when they're load-bearing for the explanation

Do NOT include a Field semantics bullet section in method TSDoc that parallels the type's field list. That creates a second field-by-field reference that drifts from the type docs over time, and forces AI agents to load both WSAPITypes.ts and the method file to assemble the full picture.

Discriminator 1 — parallel reference (method-side)

If you're about to write a bullet that's "field_name is/means X" and the next bullet is the same shape for another field, you're writing a parallel reference and should stop. Move that content into prose somewhere else in @remarks — Refresh after success / Subscription model / UI guidance — where the field is mentioned in the context of WHAT YOU DO with it, not WHAT IT IS.

Bad (parallel reference)	Good (usage prose)
**Field semantics** - is_opted_in does NOT flip optimistically... - dt_start doubles as opt-in timestamp...	**Refresh after success** The SDK auto-refreshes the mission list on response. is_opted_in becomes true on the refreshed array; don't flip it optimistically. dt_start on the refreshed mission is the opt-in timestamp; expiration is dt_start + time_limit_ms.

Discriminator 2 — definition vs. instruction (type-side)

A field comment answers: "what is this field?" — a definition. A method TSDoc answers: "what do I do with it?" — an instruction.

If a field comment contains any of these, the content belongs in the method TSDoc, not the field:

• An imperative verb in the consumer's voice ("sort by …", "pass to …", "never cache …", "always read from a fresh fetch", "must call X first")
• A code snippet showing the consumer using the value (e.g. categories.sort(...))
• A multi-step instruction
• A cross-method invariant ("call Y before this", "after Z the field flips")

Field comments may include: what the value represents · type/units (px, ms, 0–100 percent, Unix-ms timestamp) · null/undefined semantics · cross-ref to the public enum the values come from · one short "Returned by getX()" pointer. That's it.

Bad (instruction in field comment)	Good (definition in field; instruction in method)
name: Display label. Pre-translated to the user's stored language. In visitor mode driven by _smartico.vapi(lang) . Falls back to EN. Never null.	Field: name: Display label, pre-translated server-side. Never null. Method TSDoc: **Localization**: server pre-translates to user language; falls back to EN; visitor mode uses vapi(lang) argument.
order: Relative position (lower first). Server does NOT pre-sort — caller must run categories.sort((a,b)=>a.order-b.order) . Default 1.	Field: order: Relative display position (lower = first). Default 1. Method TSDoc: **Sort order**: server does NOT pre-sort; caller must sort by order ascending.
xxx_completed_id: Stable identifier of the completion. Pass to requestXxxClaim() . Always re-read from a fresh getXxxs() result; never synthesise or cache across sessions. Undefined for badges and incomplete entries.	Field: xxx_completed_id: Stable identifier of this completion. Undefined for entries not yet completed. Method @param block: usage / never-cache / freshness guidance.

Wrapper result types — the most common type-side violation

Interfaces that exist solely to wrap one method's return value — typically TXResult with err_code / err_message — are 1:1 with their owning method. The method's TSDoc owns the full error-code table; the wrapper type's err_code field is one short sentence + pointer:

/** Error code. `0` = success. See `<methodName>` TSDoc for the full table. */
err_code: number;
/** Optional error message; populated on non-zero `err_code`. */
err_message: string;

Do NOT enumerate the same codes in both places. Two places to maintain when a new code is added is exactly the bifurcation the contract is meant to prevent. If you find an existing wrapper-type comment with the table duplicated (an artifact from pre-contract enrichment), trim it on the spillover pass — see step 8.

Organic cleanup: For existing docs that violate either discriminator: rewrite when next touching that method or type. Don't do a sweep-clean — organic cleanup is fine.

File layout

The SDK surface is split across one class per domain via an inheritance chain. The public name WSAPI is the terminator; consumers call _smartico.api.X(...) and the method resolves up the prototype chain. Each domain class lives in its own file:

Domain class	File	Methods
WSAPIBase	src/WSAPI/WSAPIBase.ts	abstract; constructor, shared state, clearCaches, updateEntity helper, onUpdateContextKey enum
WSAPIUser	src/WSAPI/WSAPIUser.ts	getUserProfile, getCurrentLevel, getLevels, getUserLevelExtraCounters, checkSegmentMatch, checkSegmentListMatch
WSAPIGeneral	src/WSAPI/WSAPIGeneral.ts	getCustomSections, getTranslations, reportImpressionEvent, reportClickEvent, getActivityLog, getRelatedItemsForGame
WSAPIMissions	src/WSAPI/WSAPIMissions.ts	getMissions, getBadges, getAchCategories, requestMissionOptIn, requestMissionClaimReward
WSAPIBonuses	src/WSAPI/WSAPIBonuses.ts	getBonuses, claimBonus
WSAPIStore	src/WSAPI/WSAPIStore.ts	getStoreItems, buyStoreItem, getStoreCategories, getStorePurchasedItems
WSAPITournaments	src/WSAPI/WSAPITournaments.ts	getTournamentsList, getTournamentInstanceInfo, registerInTournament, getClanTournamentPlayers
WSAPIClans	src/WSAPI/WSAPIClans.ts	getClans, getClanInfo, joinClan
WSAPIJackpots	src/WSAPI/WSAPIJackpots.ts	jackpotGet, jackpotOptIn, jackpotOptOut, getJackpotWinners, getJackpotEligibleGames
WSAPIRaffles	src/WSAPI/WSAPIRaffles.ts	getRaffles, getRaffleDrawRun, getRaffleDrawRunsHistory, claimRafflePrize, requestRaffleOptin
WSAPIMiniGames	src/WSAPI/WSAPIMiniGames.ts	getMiniGames, getMiniGamesHistory, playMiniGame, miniGameWinAcknowledgeRequest, playMiniGameBatch
WSAPIAvatars	src/WSAPI/WSAPIAvatars.ts	getAvatarsList, getAvatarsCustomized, getAvatarPrompts, setAvatar
WSAPIGamePick	src/WSAPI/WSAPIGamePick.ts	gamePickGet*, gamePickSubmit* (9 methods)
WSAPILeaderBoard	src/WSAPI/WSAPILeaderBoard.ts	getLeaderBoard
WSAPIInbox	src/WSAPI/WSAPIInbox.ts	getInboxMessages, getInboxUnreadCount, markInboxMessageAsRead, markAllInboxMessagesAsRead, markUnmarkInboxMessageAsFavorite, deleteInboxMessage, deleteAllInboxMessages, getInboxMessageBody
WSAPI (terminator)	src/WSAPI/WSAPI.ts	empty body; constructor runs push-subscription wiring

UI guides live at docs/ui/<domain-slug>/UIGuide_<methodName>.md. Domain slugs in use today: missions/, store/. When enriching a method in a domain that doesn't have a UI directory yet, create it (docs/ui/<lowercase-domain>/).

Workflow

1. Locate the SDK method

First identify which domain class file owns the method using the file layout below. Then read that file and find the target method. Capture:

• Current TSDoc (the floor — don't lose existing content like "Visitor mode: not supported")
• Method signature + return type
• The internal this.api.xxx(...) it wraps — that's the protocol-layer name (e.g. requestMissionOptIn wraps missionOptIn)
• The return-type interface in WSAPITypes.ts (e.g. TMissionOptInResult) — read it too

2. Hive extraction (mcp__hive__chat)

Call hive with goal: "Deep Dive Code", mode: "high". Pass both names (SDK + protocol-layer) so hive can locate both sides.

Prompt template:

Investigate the Smartico ach codebase (the in-tracker gamification UI at
/Users/aa/Desktop/SM/tracker/ach/src) for the **<FEATURE>** flow.

Context: I'm enriching the TSDoc of `_smartico.api.<SDK_METHOD>(...)`. The
SDK wraps an internal `<PROTOCOL_METHOD>` that goes over the protocol layer
(ClassId `<CID_REQUEST>` → `<CID_RESPONSE>`). I need observable behavior
the SDK consumer needs.

Return a structured summary with these sections, citing ach files with
line numbers.

**Part A — API behavior**:

1. Call sequence — what runs before and after; prerequisite calls; follow-up calls
2. Response handling — which response fields ach consumes; which it ignores
3. Error codes — every distinct errCode value handled, with UI behavior per code
4. Refresh cadence / triggers — what triggers re-fetch after the call; push vs poll
5. Prerequisites / gating — user state, mission flags, level/brand/auth requirements
6. Idempotency — safe to call twice? guards against double-clicks?
7. Edge cases — locked, time-elapsed, deleted, network failure, timeout
8. Observable side effects — what other state changes (points, badges, visibility)

**Part B — UI rendering** (mandatory for fetch methods returning rich
entities and mutations with state-dependent buttons; omit subsections that
don't apply for the method type):

9. **List view** (fetch methods returning arrays of rich entities): how is
   the list organized? Tabs / sections / filter chips / flat list? Status
   bucketing — what buckets and what's the priority order for assignment?
   Sort order per bucket? Empty state copy per bucket? Pagination /
   virtualization (if any)?
10. **Item card / tile** (list-renderable entities): EVERY field from the
    response type that appears on a card; the visual hierarchy
    (title-image-status-progress-reward-CTA layout); what's NOT on the
    card and lives only in the detail view; whole-card click vs sub-element
    handlers.
11. **Detail view / popup** (entities with a "view more" expansion): the
    top-to-bottom section list; what fields appear ONLY in the detail vs
    also on the card; image size differences.
12. **Action button decision matrix** (entities with state-dependent
    actions): for every meaningful combination of entity state flags
    (locked, opted-in, completed, requires_claim, missed, expired, etc.),
    what button is shown with what label, when enabled/disabled, what
    click action is dispatched. This must be exhaustive.
13. **Image / asset specs**: documented source dimensions and aspect
    ratios for all image-bearing fields (entity icon, ribbon, thumbnails,
    etc.). Fallback handling when fields are empty.
14. **Status-specific visual treatments**: per status (locked / completed
    / missed / in-progress / featured / claimable), what visual modifier
    is applied (overlay icon, tint, glow, grayscale, etc.).
15. **Countdown / timing formatting** (entities with deadlines): the
    string format for time-remaining displays; update cadence;
    not-yet-started vs in-progress vs expired text variants.
16. **Animations / transitions**: list entry animations, popup open/close,
    progress bar fill, success celebrations, loading indicators.
17. **Mobile vs desktop**: differences in grid layout, card density, or
    interaction patterns.
18. **Empty / loading / error states**: copy and visual treatment.

Constraints on your answer:
- Focus on observable SDK-consumer behavior. Translate protocol-layer
  internals (ClassId, ProtocolMessage, lib-common/protocol/*,
  Context.interaction.protocolRequest) into "what happens" terms.
- Do NOT describe Redux/InteractionSlave/Context plumbing.
- Flag tracker-only behaviors (iframe height messaging, deep-link
  auto-dispatch, parent-frame postMessage scroll locks, etc.) as
  "tracker-only, ignore for SDK".
- Cite ach files with `file.ts:line` for every claim.
- For Part B, prefer concrete numbers (px, %, aspect ratios) over vague
  descriptions. If the dimension lives in SCSS that's not indexed, say so
  and quote the documented size from the TSDoc on the public type.

3. Direct verification

Read 3–5 cited ach files via Bash+sed or Read to verify hive's claims against actual code. Especially verify:

• Exact error code numeric values (OptInErrorCode.AlreadyOptedIn = 40010 etc.)
• Field-naming mismatch: ach uses camelCase internally (mission.isOptedIn); SDK exposes snake_case (mission.is_opted_in). Examples must use SDK shape.
• Control-flow branches: response.errCode branches and what each one does

Do not skip this — hive's summary occasionally collapses or paraphrases logic that the direct read catches.

4. Draft TSDoc using the template below

5. Hive validation pass (MANDATORY)

A second mcp__hive__chat call to verify the draft's specific claims, especially anything sourced from server-side handlers (r-server Java code) that the ach-side analysis can't see.

Prompt template:

VALIDATION PASS for `<SDK_METHOD>`.

Context: I'm finalizing TSDoc for `_smartico.api.<SDK_METHOD>`. Verify
these claims with citations to the authoritative code path (use r-server
handlers, DB functions, ach engines — whatever is canonical).

For each claim, reply CONFIRMED / INCORRECT / PARTIAL with citation:

1. <claim>
2. <claim>
3. <claim>
4. <claim>

Don't re-narrate the full flow — just verify these claims.

Pick 3–5 claims that are:

• Server-side behavior (error codes, DB writes, side effects) — ach can't authoritatively confirm
• Cross-system invariants ("X is/isn't idempotent", "X triggers Y")
• Numeric thresholds (cadences, limits, timeouts)

If validation returns INCORRECT or PARTIAL for any claim, update the draft before applying. Add the corrected info; do not paper over the discrepancy.

6. Apply the Edit (TSDoc)

Use the Edit tool to replace the existing TSDoc block in the domain class file. The TSDoc keeps only API behavior: summary, @remarks sections (Preconditions, Error codes, Refresh, Idempotency, Side effects, Cache TTL, Visitor mode), @param, @returns, @example. UI guidance does NOT go inline — it lives in a separate markdown file (see step 7).

Replace any pre-existing **UI guidance — X** subsections with a single line:

 * **UI guidance**: see [UI Guide — `<methodName>`](../../docs/ui/<domain>/UIGuide_<methodName>.md).

The relative path ../../docs/ui/... resolves from src/WSAPI/ to the docs tree (this is the source-side path). The post-doc cleanup script (scripts/postdoc-cleanup.js) automatically rewrites this to ../../ui/<domain>/... for the typedoc-rendered output at docs/api/classes/<class>.md, where the correct relative path is one segment shorter. If you ever bypass the post-doc cleanup, the rendered .md files will have broken UI guide links pointing into docs/docs/ui/... (which doesn't exist).

Pre-apply audit (10-second check on the draft before calling Edit):

• No bullet block in @remarks where each bullet has the shape `field_name` is/means X (Discriminator 1).
• No comma-separated prose list of fields all stating the same predicate (e.g. "a, b, c, d are not used") — group categorically instead ("opt-in / claim / recurring fields are not used"). A grouped phrase reads as one fact; an itemized list reads as a parallel reference.
• No two @remarks sections describing the same conceptual axis (e.g. **Subscription model** and **What triggers async refresh** both cover "what fires updates" — merge into one section with a sub-list, not two separate sections). LLMs doing section-level retrieval pull only one.
• No claim in @remarks that the summary sentence already states word-for-word. The summary is the one-line orientation; @remarks add detail, not echoes.
• Wrapper result type (TXResult) being touched in spillover: its err_code field comment is a one-line pointer to the method TSDoc, NOT a re-enumeration of the codes.
• Code snippet in @example uses only public SDK methods, public enums, and console.log/error for UI guidance (no pseudo-handlers).

Fix the draft before calling Edit. These violations are cheap to fix pre-write and expensive to find post-write.

Apply directly. Do NOT commit. Do NOT push. Do NOT run npm run doc.

Do NOT leave any TODO:, TODOYY:, FIXME:, XXX:, or similar reviewer-note comments in the source. All uncertainty — anything you're not 100% sure of, anything sourced only from hive without direct verification, anything that needs human / system-owner confirmation — goes into the return summary to the user, not into the code.

7. Write / update the UI guide markdown

For methods of type "Rich-entity fetch", "Single-entity detail fetch", or "Mutation with state-dependent label/branching" (see classifier below), write the full UI guidance to:

docs/ui/<domain>/UIGuide_<methodName>.md

The file is plain markdown — sections are ## Heading, lists are markdown lists, code blocks are fenced. Structure:

# UI Guide — `<methodName>`

## List view organization
<bucketing, sort, empty states>

## Item card / tile
<field-by-field render list, click target>

## Detail view / popup
<top-to-bottom layout>

## Action button decision matrix
<priority-ordered list of state combinations>

## Companion action caveats
<synchronous deep-links, etc.>

## Image / asset specs
<dimensions, aspect ratios, fallbacks>

## Status-specific visual treatments
<per status>

## Countdown / timing format
<6-tier compact format>

## Empty / loading / error states

## Animations / transitions

## Mobile vs desktop

## Performance

Omit sections that don't apply for the method type (e.g. a metadata-only fetch like getStoreCategories needs only ## List view organization, ## Empty states, ## Cache / refresh notes).

Style rules for the markdown (same as the TSDoc rules):

• No protocol-layer references (no ClassId.X, no DB schema, no internal class names).
• Code examples use console.log() / console.error() with descriptive messages, never pseudo-API handlers.
• Reference the reference UI as "the default Smartico UI", not "official tracker" / "ach" / "the tracker".
• The TSDoc method link uses the format above so docs renderers (typedoc, GitHub, etc.) can navigate to the file.

For metadata-getters / scalars / fire-and-forget telemetry — do NOT create a UI guide file. The TSDoc just doesn't include the **UI guidance**: see ... line. The skill's classifier determines this.

8. Spillover updates and other cross-method effects

If the investigation surfaced corrections to OTHER methods, error codes, types, or mappings, apply those too. Common cases:

• Related interface in WSAPITypes.ts — apply the type/method contract (Discriminator 2 — definition vs. instruction). Two specific sub-patterns:
  • Wrapper result type (TXResult with err_code / err_message — exists 1:1 with one method): the err_code field comment is ONE line + pointer to the method TSDoc. Never enumerate the same code table in both files. If you find an existing wrapper with the table duplicated (pre-contract enrichment artifact), trim it now — this is the spillover step where that gets caught.
  • Domain type (e.g. TStoreItem, TTournament, TMissionOrBadge, TAchCategory): each field comment is a definition + null/undefined semantics. Scan for usage-prose drift (sort instructions, "never cache", translation chains, multi-step "always do X then Y" guidance) and strip — the method TSDoc owns it. Add a one-line Returned by getX() `` pointer if missing.
• A neighbor method has the same error codes — note them in its TSDoc too if applicable. Cross-reference with "See <other_method> for the full error-code table."
• An incorrect existing claim in nearby TSDoc — fix it.
• A type alias that returns the wrong shape — fix the type and flag it as a potential breaking change in the return summary.

For each spillover, the same rules apply: apply directly, never commit, surface uncertainty in the return summary (not in code comments).

9. Post-write housekeeping (manual-support files)

Each per-method enrichment produces small deltas to manually-maintained files. Apply them as part of the same run.

9a. Update the project README.md

The README.md at the public-api project root has an API reference table with a UI Guides column. After writing a UI guide markdown file (per step 7), add a link to it in the relevant row.

Format: each cell is a ·-separated list of [`<methodName>`](docs/ui/<domain>/UIGuide_<methodName>.md) entries. Insert the new link in source-order (matches the order methods are declared in the domain class).

If the row currently shows — (no UI guides yet for that domain), replace — with the new link.

Skip this step for method-types where no UI guide was created (metadata getters / scalars / telemetry — see classifier).

9b. Update doc-todo.md running tally

Add one row to the Running tally table at the bottom of /Users/aa/Desktop/SM/public-api/doc-todo.md:

| YYYY-MM-DD | `<methodName>` | ✅ | <todoyy-count> | $<hive-cost> | ~<min> min | — | <one-line note> |

Mark the method's checkbox in its domain section ([ ] → [x]) and add a brief one-line summary inline if applicable.

If the per-batch totals row at the bottom needs an update (cumulative method count, cost, etc.), update it too.

9c. Fix cross-document links in the just-written UI guide

UI guide markdown is written into docs/ui/<domain>/UIGuide_<methodName>.md. When the source content was extracted (or hive-pulled) from a typedoc-rendered context, embedded links assume docs/api/classes/ adjacency and are wrong from docs/ui/<domain>/. Three patterns recur:

Original (wrong)	Fixed
(WSAPIMissions.md#getmissions)	(../../api/classes/WSAPIMissions.md#getmissions)
(WSAPIStore.md#buystoreitem)	(../../api/classes/WSAPIStore.md#buystoreitem)
(../enumerations/AchievementAvailabilityStatus.md)	(../../api/enumerations/AchievementAvailabilityStatus.md)
(../interfaces/TMissionOrBadge.md)	(../../api/interfaces/TMissionOrBadge.md)
(#buystoreitem) (bare anchor that pointed to a sibling method)	(../../api/classes/WSAPI<Class>.md#buystoreitem) — figure out the class from the inheritance chain

Rule of thumb: any relative path in a UI guide that points to an SDK reference resource (class doc, interface doc, enum doc) must be prefixed with ../../api/ from docs/ui/<domain>/.

Run all three of these greps on the new UI guide and fix every match:

# Cross-class refs (the wsapi class name as a relative file)
grep -nE "\]\(WSAPI[A-Za-z]+\.md" docs/ui/<domain>/UIGuide_<methodName>.md

# Wrong-depth enum / interface refs (single `../` instead of `../../api/`)
grep -nE "\]\(\.\./[a-z]+/" docs/ui/<domain>/UIGuide_<methodName>.md

# Bare same-page anchors that should point to a sibling class
grep -nE "\]\(#[a-z]" docs/ui/<domain>/UIGuide_<methodName>.md

Then sanity-check that every target file exists:

# For each `(../../api/X/Y.md...)` reference, verify the file exists:
grep -ohE "\(\.\./\.\./api/[^)#]+\)" docs/ui/<domain>/UIGuide_<methodName>.md \
  | tr -d '()' \
  | while read p; do
      target="docs/$(echo "$p" | cut -c7-)"
      [ -f "$target" ] && echo "OK    $p" || echo "MISS  $p (looking at $target)"
    done

If any are MISS, the reference points to a doc typedoc never generated (e.g. a type that isn't in tsconfig.entryPoints). Two options: add the entry point and re-run npm run doc, or convert the broken link to backtick-code (`AchievementClaimPeriodTypeId`) so it renders as plain reference without a hyperlink.

9d. Verify npm run doc still emits cleanly

Run npm run doc (from /Users/aa/Desktop/SM/public-api) and confirm:

• Exit code 0
• No new warnings beyond pre-existing ones
• docs/api/classes/<DomainClass>.md reflects the new TSDoc
• docs/api/_media/ does NOT contain a stale copy of the new UI guide (post-doc cleanup handles this)

If warnings appear about unresolved {@link X} references, fix them by converting to backtick-code (`X`) when X is a public method in a class that's later in the inheritance chain — those don't resolve and there's no point in fighting it.

Verify UI guide links in the generated class doc resolve correctly. The post-doc cleanup script rewrites paths from ../../docs/ui/... (source-side, relative to src/WSAPI/) to ../../ui/... (rendered-side, relative to docs/api/classes/). Any broken rewrite would point at docs/docs/ui/..., which doesn't exist. Quick sanity check:

# Confirm no stray ../../docs/ui/ in rendered class docs (correct prefix is ../../ui/)
grep -rn "../../docs/ui/" docs/api/classes/ && echo "BROKEN" || echo "OK"

# Resolve every UI guide link in class docs and confirm the target exists
for p in $(grep -rohE '\(\.\./\.\./ui/[^)]+\)' docs/api/classes/ | tr -d '()' | sort -u); do
  target=$(python3 -c "import os; print(os.path.normpath('docs/api/classes/$p'))")
  [ -f "$target" ] && echo "  ✓ $p" || echo "  ✗ $p (missing $target)"
done

Same idea for UI guides: any reference into docs/api/... from a UI guide must use ../../api/... (single docs/ segment in the resolved path). Quick check for class docs and UI guides together:

# UI guides should not have a bare ../../docs/ui pattern either; they live in docs/ui/.
grep -rn "docs/docs/" docs/api/ docs/ui/ && echo "BROKEN" || echo "OK"

10. Present the result

Output a tight summary (under 300 words). Include:

• Files edited with paths
• Sections added/changed per file
• Open questions / unverified claims — anything sourced from hive that you didn't directly verify, anything that needs human or system-owner confirmation. This is the audit trail; be specific (cite the originating ach / r-server location for each claim so the reviewer can re-check).
• Reviewer checklist — server-side claims to confirm, type-shape risks, breaking changes, spillover edits to other methods/types
• Cost (hive call totals + duration)

Then stop. Do not commit. Do not run docs regeneration. Do not push.

Output template — TSDoc structure

Use this skeleton for any async server-roundtrip SDK method. Trim sections that don't apply, but keep the order:

/**
 * <One-line summary of WHAT the method does and WHO it's for.>
 *
 * <Optional second sentence with the most important behavioral hook —
 * "events fired before opt-in don't count retroactively" — that the
 * consumer must know before reading the @remarks.>
 *
 * @remarks
 * **Preconditions**
 * <What must be true before calling. Reference the source of truth
 * for these flags (usually getX() / getProfile()).>
 *
 * **Error codes** (in `err_code`)
 * - `0` — success; <what happens>
 * - `<code>` — <semantic meaning>. <UI handling guidance.>
 * - <... one bullet per distinct named code from server>
 * - other non-zero — generic server error. Surface `err_message` if any.
 *
 * **<Behavior-specific section>** (e.g. "Time-limited missions",
 * "Pagination", "Cache TTL")
 * <Server-recorded invariants and timing rules.>
 *
 * **Refresh after success**
 * <How the SDK / consumer state updates after this call. Mention
 * any onUpdate callbacks, automatic cache busts, manual re-fetch
 * requirements.>
 *
 * **Idempotency**: <yes/no>. <If no, what code does a retry return?>
 * <Guidance on guarding the call site.>
 *
 * **Side effects**: <points, badges, levels, visibility of other
 * entities. Be explicit about what DOESN'T happen too.>
 *
 * **UI guidance**: see [UI Guide — `<methodName>`](../../docs/ui/<domain>/UIGuide_<methodName>.md).
 *
 * (UI guidance body lives in the linked markdown file — list bucketing,
 * card/detail layouts, action-button matrix, image specs, animations,
 * etc. The TSDoc only links; the markdown owns the content.)
 *
 * (Omit the `**UI guidance**: see ...` line entirely for metadata-only
 * getters, scalar counters, and fire-and-forget telemetry methods —
 * those don't need a UI guide. See the classifier below.)
 *
 * **Visitor mode**: <supported / not supported>
 *
 * @param <name>  <Description. Reference the source for the value.>
 * @returns <Shape. Success condition.>
 *
 * @example
 * ```ts
 * <Realistic snippet using SDK types only. Show the preconditions gate,
 * the loading state, and the per-error-code branches. Use console.log /
 * console.error with descriptive messages stating what the consumer's UI
 * should do at that point — NEVER use pseudo-handlers like showError,
 * showUnlockTasks, refreshUI, notify, toast, etc. The example must run
 * as-is (so a consumer can paste it and verify the flow in devtools)
 * AND describe expected UI behavior in the log message.>
 * ```
 */
public async <method>(...) { ... }

No reviewer-note comments (TODO:, FIXME:, XXX:, etc.) above the signature. Surface uncertainty in the return summary instead.

Feature → ach subtree map

Orientation for hive prompts. Hive can explore wider on its own; this is just where to start.

Feature	ach subtree(s)
Missions / Achievements	core/engine/AchievementEngine.ts, core/redux/achievement/*, component/missions/*, component/ach3/modal/ModalMission.tsx, component/ach3/page/PageMissions*.tsx, component/ach3/page/PageLiquidSection.tsx
Tournaments	core/engine/TournamentEngine.ts, core/redux/tournament/*, component/tournament/*, component/ach3/tournament/*, component/ach3/tournament-new/*, component/ach3/page/PageTournament*.tsx
Jackpots	core/engine/JackpotEngine.ts, core/redux/jackpots/*
Raffles / Draws	core/engine/RaffleEngine.ts, core/redux/raffle/*, component/ach3/raffle/*
Store / Shop	core/engine/StoreEngine.ts, core/redux/store/*
Inbox / Messages	core/engine/InboxEngine.ts, core/redux/inbox/*, core/redux/shortInbox/*, component/inbox/*
Levels	core/redux/levels/*, core/engine/UserEngine.ts
SAW / MiniGame / Lootbox	core/engine/SawEngine.ts, component/saw/*
Avatars	core/engine/AvatarsV2Engine.ts, core/redux/avatarsV2/*
Clans	core/engine/ClansEngine.ts
User profile	core/engine/UserEngine.ts, core/redux/user/*
Bonuses	core/engine/BonusEngine.ts
LeaderBoards	core/engine/LeaderBoardEngine.ts
Activity Log	core/engine/ActivityLogEngine.ts, component/activityLog/*

Method-type classifier — how much UI depth?

Not every method needs the full UI matrix. Classify the target method first; produce the matching depth.

Method shape	Example	UI depth	UI guide file?
Rich-entity fetch + subscription	getMissions({onUpdate}), getStoreItems({onUpdate}), getTournamentsList({onUpdate})	Full: list bucketing + card + detail popup + action matrix + image specs + animations	Yes — write docs/ui/<domain>/UIGuide_<method>.md
Rich-entity fetch (no subscription)	getBadges(), getRaffles({onUpdate}), getJackpotWinners	Full minus subscription — same as above but no onUpdate lifecycle	Yes
Mutation with state-dependent label/branching	buyStoreItem, requestMissionOptIn, claimRafflePrize, joinClan	Action-focused: button-states matrix per error code + loading + error-handling UI + idempotency UI guard	Yes
Single-entity detail fetch	getTournamentInstanceInfo, getClanInfo, getRaffleDrawRun	Detail-focused: section layout + image specs + state-specific treatments	Yes
Metadata / categories	getStoreCategories, getAchCategories, getLevels	Light: rendering hints (sort, translation, fallback), empty state	Yes — short (1–2 KB)
Counter / scalar	getInboxUnreadCount, getCurrentLevel	Minimal: how to render the single value, refresh behavior	No — TSDoc only
Fire-and-forget telemetry	reportImpressionEvent, reportClickEvent	None for UI — focus on call-site placement guidance instead	No — TSDoc only

When a UI guide is written, the method's TSDoc gets the **UI guidance**: see [UI Guide — ](../../docs/ui/<domain>/UIGuide_<method>.md). link line. When not, the TSDoc omits the UI line entirely.

When in doubt, ask: "would a designer reading the docs need to know this to build a screen?" If yes, document it. If no, leave it out.

Argument handling

• <method_name> — a specific SDK method like requestMissionOptIn. Skill focuses on that one method end-to-end.
• <feature_keyword> — a feature like missions or tournaments. Skill lists candidate SDK methods in that area and asks the user which to enrich (or processes them in sequence on confirmation).
• No argument — skill scans all src/WSAPI/WSAPI<Domain>.ts files for methods with thin TSDoc (single-line description) and presents a candidate list.

Cost guidance

• Per method: ~$1 hive cost + ~5 minutes wall-clock. Across 50 SDK methods: ~$50 + ~4 hours of operator review time.
• If a method's hive extraction looks unusually short (under 30s) or unusually long (over 5min), that's a signal to re-prompt with more context. Don't accept low-quality output silently.

Anti-patterns to avoid

• "Looks good, applying" without verification — always read at least 2 ach files directly to spot-check hive's claims.
• Leaving any reviewer-note comments (TODO:, TODOYY:, FIXME:, XXX:, etc.) in the source. Uncertainty goes into the return summary, not into code.
• Inventing error codes that hive didn't surface — if hive didn't find a code and validation didn't surface it, the SDK consumer doesn't need to handle it. Don't pad the list.
• Using Promise<T> shape that doesn't match the actual return — always re-read the method body to confirm what's actually returned, not what feels right.
• Skipping the validation pass on a "trivial" enrichment — the first real run found a 5-vs-1 error-code discrepancy. Validation isn't optional.
• Two @remarks sections covering the same conceptual axis — e.g. **Subscription model** and **What triggers async refresh** are both about "what fires updates". Merge into one section with a sub-list, not two. LLMs doing section-level retrieval pull only one and miss the other; human readers skim section headers and lose half the story.
• Duplicating an error-code table between the method TSDoc and the result-type field comment — see Discriminator 2 / "Wrapper result types" in the contract section. The method owns the table; the result type's err_code field is a one-line pointer.
• Usage instructions in field comments — sort/translate/never-cache/always-re-read verbs belong in the method TSDoc, not the field. Field comments answer "what is this"; method TSDocs answer "what do I do with it". See Discriminator 2.
• Summary that's echoed by an @remarks section verbatim — the summary is one-line orientation; @remarks add detail. If the summary already says "no opt-in, no claim", don't open a "Differences" section by re-stating "no opt-in, no claim" — start it with the next level of detail (what badges DO have, what fields drive behavior instead).
• Comma-separated prose lists of fields all stating the same predicate — e.g. "a, b, c, d, e are not used" is just Discriminator 1 in disguise. Group categorically ("opt-in / claim / recurring fields are not used") so it reads as one fact, not five.

Capability pages (RAG ingestion) — capture real responses + regenerate

The IDE coding agent does NOT read this repo's raw source or the TypeDoc pages. It retrieves from capability pages — one self-contained markdown doc per method at docs/capabilities/<method>.md, produced by the deterministic generator scripts/gen-capabilities.js (npm run gen-capabilities). The generator stitches: the method TSDoc you just enriched (summary / @remarks contract / @param / @example / {@link} → Related) + the return type's own field comments (per-type resolved, inheritance-aware — so id/name/type get the right domain's definition) + a captured REAL response payload.

Never hand-edit docs/capabilities/*.md — they are generated and overwritten. Your job per method is the two inputs the generator can't synthesize: a clean TSDoc (the rest of this skill) and a captured response.

Step A — capture the real response shape

The single highest-leverage doc artifact (it removes the agent's ~20-probe live-SDK fallback). Use the mcp__hive__run_public_api MCP tool — it runs the real @smartico/public-api WSAPI server-side, bound to a label+brand+player, and returns the SAME transformed T-shapes a browser sees. No user-hash, no browser, no CORS. Default test player (env4 — confirm/refresh with the user if rotated):

• label_api_key: a6e7ac26-c368-4892-9380-96e7ff82cf3e-4
• brand_api_key: f86271e6
• user_ext_id: 4579cace-9069-4d65-93ff-9b8b6c83c45b

Call the method, slice arrays to 1 representative item, return it:

// code arg to run_public_api:
const r = await api.<method>(<params>);
return Array.isArray(r) ? r.slice(0, 1) : r;

Write the result to docs/capabilities/_responses/<method>.json (raw array/object the method returns; the generator trims long strings + re-slices). Anonymize before saving: replace real CDN hosts with https://cdn.example/..., GUIDs / message_guid / any user identifier with zero-GUIDs, and trim operator HTML (tournament/mission description) to a short placeholder. Product config (mission names, store-item names, prize tables) is fine to keep — it's the field shape that matters.

Caveat — tracker-state methods can't be captured this way. getUserProfile (and other methods that read tracker state, not a WSAPI roundtrip) return "Tracker is not initialized". For those few, capture via the headless-browser fallback: load the SDK on a page (_smartico('init', LABEL, { brand_key })), identify the player, call the method, dump JSON from devtools. Note the method in the return summary as browser-captured.

Step B — regenerate + verify

Run npm run gen-capabilities, then spot-check the new docs/capabilities/<method>.md:

• Returns lists the real fields with the right per-domain comments (if a field shows another domain's definition, the field-comment collision means the return type is missing that field — fix the type, not the page).
• Behavioral contract carries your @remarks (no empty (see ) — those mean a {@link} target the generator couldn't render; usually fine).
• Example response shows the real shape.
• No internal leaks surfaced from a type comment (DB tables, ClassId, etc.) — if one appears, fix the source field comment (it violates the public-contract rule).

Do NOT run gen-capabilities as part of an unrelated code change, and do not commit. It is part of the doc batch (see api-tsdoc-final).