Add agent skill (SKILL.md + per-domain reference)

skills/rudder-web-sdk/reference/quests.md

@@ -0,0 +1,75 @@
+# Quests — `client.quests`
+
+`QuestsService` (source: `src/quests/QuestsService.ts`). The player's **global**
+quests — list, claim, report metric progress. Plain call-and-response service,
+NOT observable (no sync revision key): re-list after a claim or report.
+
+Distinct from scenario quest nodes, which advance through
+`client.effects.onQuest` (see `reference/scenarios.md`).
+
+## Methods
+
+```ts
+list(): Promise<Quest[]>
+claim(questId: string): Promise<ClaimQuestResponse>
+reportProgress(metric: string, amount: number): Promise<string[]>  // ids of quests completed by this report
+```
+
+## Types
+
+```ts
+interface Quest {
+  id?: string;
+  name?: string;
+  objectives?: QuestObjectiveProgress[];
+  rewards?: Reward[];
+  status?: 'active' | 'claimed' | 'completed';
+}
+
+interface QuestObjectiveProgress {
+  completed?: boolean;
+  current?: number;
+  metric?: string;
+  objectiveId?: string;
+  target?: number;
+}
+
+interface ClaimQuestResponse {
+  alreadyClaimed?: boolean;
+  error?: string;
+  granted?: Reward[];   // { amount?, currency?, itemId? }
+  success?: boolean;
+}
+```
+
+## Usage notes
+
+```ts
+const quests = await client.quests.list();
+for (const quest of quests) {
+  if (quest.status === 'completed' && quest.id) {
+    const res = await client.quests.claim(quest.id);
+    // res.success / res.alreadyClaimed / res.granted
+  }
+}
+const completedIds = await client.quests.reportProgress('kills', 1);
+```
+
+- `claim` is idempotent server-side; check `success` / `alreadyClaimed` /
+  `error` in the response rather than relying on exceptions.
+- Objective completion is judged server-side from metric reports.
+
+## `QuestMetrics` helpers
+
+Exported as a namespace: `import { QuestMetrics } from '@rudder/js-sdk'`
+(source: `src/quests/QuestMetrics.ts`).
+
+```ts
+QuestMetrics.purchaseOffer('starter-pack');  // "purchase.offer:starter-pack"
+QuestMetrics.purchaseItem('moonberry');      // "purchase.item:moonberry"
+```
+
+Purchase metrics are reported automatically server-side by the store purchase
+fan-out — these helpers exist so quest configs and client code name the format
+consistently. Catalog counter slugs are reported via `reportProgress`. Custom
+free-text metrics no longer progress quests — they no-op at runtime.