@agent-native/core 0.108.0 → 0.109.1

package/corpus/core/src/templates/workspace-core/.agents/skills/a2a-protocol/SKILL.md

@@ -117,6 +117,54 @@ const answer = await callAgent(
 // answer is a plain string
 ```
 
+### Fast bounded read: `invokeAgentAction()`
+
+When the caller knows the exact receiver-owned read action and arguments, skip
+the receiver's model loop:
+
+```ts
+import { invokeAgentAction } from "@agent-native/core/a2a";
+
+const { result } = await invokeAgentAction({
+  target: "analytics",
+  action: "gong-calls",
+  input: { company: "Acme", days: 90, includeTranscripts: true },
+  userEmail,
+  orgDomain,
+  orgSecret,
+});
+```
+
+The receiver still owns schema validation, credentials, access scoping, audit
+attribution, and exposure policy. Direct invocation is available only for
+cataloged, authenticated, explicitly exposed read-only actions that do not
+require approval. Its JWT is audience-bound to the receiving app. Use normal
+message delegation for planning, synthesis, multi-step work, or mutations.
+
+Inside an agent loop, `call-agent` exposes the same path with `action` + `input`;
+omit `message` and `taskId` in that mode.
+
+### Retry safety and trace linkage
+
+`call-agent` automatically derives an owner-scoped idempotency key from the
+originating turn, target, and exact message. If a retry reaches the receiver
+after the caller timed out, asynchronous `message/send` returns the existing
+active or completed task instead of starting a duplicate agent run. Failed and
+canceled tasks release the key for an intentional retry; synchronous calls are
+never deduplicated. Lower-level clients may pass an
+`idempotencyKey` explicitly; keep it stable for the same logical submission and
+change it when the work changes. Dedupe is scoped to the JWT-authenticated
+owner and verified org, and keys are limited to 128 characters.
+
+The caller also forwards bounded correlation metadata (`callerApp`,
+`callerThreadId`, `parentRunId`, `parentTurnId`, and direct-read
+`invocationId`). These fields
+are telemetry hints only. Receivers must continue to derive identity,
+ownership, org scope, access, and approval from the verified request context.
+Delegated model loops emit `$ai_generation` with A2A/MCP lineage, while direct
+reads emit the content-free `$a2a_read_invoke` event; neither event includes
+action arguments or results.
+
 ### Advanced: `A2AClient` (full control)
 
 ```ts
@@ -178,6 +226,7 @@ cannot carry these grants.
 | ---------------- | -------------------------------- | ------------- |
 | `message/send`   | Send a message, get a task back  | Yes           |
 | `message/stream` | Send a message, stream responses | Yes           |
+| `actions/invoke` | Invoke one exposed read action   | Yes, JWT      |
 | `tasks/get`      | Get task status by ID            | Yes           |
 | `tasks/cancel`   | Cancel a running task            | Yes           |
 

package/corpus/core/src/templates/workspace-core/.agents/skills/composable-mini-apps/SKILL.md

@@ -42,6 +42,11 @@ The main agent should discover available siblings before assuming capability:
 - In the agent loop, use `call-agent` with the sibling app id when another app
   owns the work or data. Never call the current app through `call-agent`; use
   local actions instead.
+- When the exact sibling-owned read action and input are already known, use
+  `invokeAgentAction()` or `call-agent` with `action` + `input`. This preserves
+  the receiver's credentials and access checks while skipping its second model
+  loop. Use prompt-based `invokeAgent()` only when the sibling must reason,
+  synthesize, mutate, or perform a multi-step workflow.
 
 Send narrow prompts to siblings: name the exact question, relevant ids, date
 ranges, and expected output shape. Preserve returned ids and URLs verbatim.

package/corpus/core/src/templates/workspace-core/.agents/skills/observability/SKILL.md

@@ -285,7 +285,13 @@ LLM generation:
 - Agent Native Analytics shape: the same event lands in `analytics_events` with
   mirrored query-friendly properties such as `run_id`, `thread_id`,
   `cost_cents_x100`, `duration_ms`, `tool_calls`, `successful_tools`,
-  `failed_tools`, and `status`.
+  `failed_tools`, and `status`. A content-free `tools` array includes at most
+  50 tool names, start offsets, durations, statuses, and coarse error classes;
+  interrupted calls are finalized as errors, and failed runs still emit with
+  zero or known usage. `tools_truncated` marks longer runs while the rollup counts remain complete.
+  Delegated runs add `delegation_protocol`, `caller_app`, `a2a_task_id`, and
+  `parent_run_id` when available. `parent_turn_id` is separate because one
+  logical turn may span multiple concrete runs.
 
 Do not build a separate LLM-observability ingestion API unless there is a clear
 reason the tracking provider registry cannot express the use case. Keep prompt,

package/corpus/core/src/templates/workspace-core/.agents/skills/performance/SKILL.md

@@ -99,6 +99,19 @@ index the growing tables first.
   `await`s — each `await` is another round-trip.
 - Prefer **one composed endpoint** over several dependent calls.
 
+For provider wrappers, inspect the upstream API before building a list-then-
+enrich flow. Prefer the richest endpoint that can apply the real filters and
+return the needed associations or participants in one paginated operation.
+Cursor pagination is already serial; adding a serial detail/enrichment request
+to every page doubles its critical path. Exhaustive records belong in corpus
+recipes or data programs with explicit coverage, not one agent tool call per
+page or item.
+
+First-class provider actions should represent one stable conceptual operation.
+Keep arbitrary endpoint, filter, and pagination access in the provider API
+substrate; do not turn a convenience action into a capability ceiling or
+duplicate the provider transport, auth, quota, and cache implementation.
+
 ## 4. Avoid client-side waterfalls
 
 - Don't gate query B on query A's result unless B truly needs it. Fire

package/corpus/core/src/templates/workspace-core/.agents/skills/tracking/SKILL.md

@@ -141,7 +141,7 @@ Other framework-level baseline events:
 - `signup` from Better Auth user creation, with `auth_provider`, `auth_user_id`, and first-touch referral attribution (`referral_source`, `referrer_user`, `referral_medium`, `referral_campaign`, `utm_*`, `first_touch_path`, `landing_referrer` — see "Referral / viral attribution" above)
 - `builder connect clicked` and `builder connect popup blocked` from browser Connect Builder CTAs
 - `builder connect started`, `builder connect succeeded`, `builder connect failed`, `builder disconnect succeeded`, and `builder disconnect failed` from the Builder connection routes, with LLM connection context when resolvable
-- `$ai_generation` from instrumented agent loops, with PostHog AI Observability fields such as `$ai_trace_id`, `$ai_session_id`, `$ai_model`, `$ai_provider`, `$ai_input_tokens`, `$ai_output_tokens`, `$ai_latency`, `$ai_total_cost_usd`, and mirrored Agent Native query fields such as `run_id`, `thread_id`, `cost_cents_x100`, `duration_ms`, `tool_calls`, and `status`. Prompt, tool argument, and output content is not included by default.
+- `$ai_generation` from instrumented agent loops, with PostHog AI Observability fields such as `$ai_trace_id`, `$ai_session_id`, `$ai_model`, `$ai_provider`, `$ai_input_tokens`, `$ai_output_tokens`, `$ai_latency`, `$ai_total_cost_usd`, and mirrored Agent Native query fields such as `run_id`, `thread_id`, `cost_cents_x100`, `duration_ms`, `tool_calls`, and `status`. A bounded `tools` array contains names, start offsets, durations, statuses, and coarse error classes only; interrupted tools and failed runs remain visible, and delegated runs include protocol/task/parent-run/parent-turn correlation. Prompt, tool argument, result, and output content is excluded.
 
 For new lifecycle events, call `track()` server-side when the server is the source of truth, and `trackEvent()` client-side only for browser interactions.
 

package/corpus/templates/analytics/.agents/skills/dashboard-management/SKILL.md

@@ -83,7 +83,7 @@ When the user asks for a dashboard:
 2. If a metric definition, date range, or grain is ambiguous and the choice would change the panel's numbers, use the `ask-question` clarifying tool once before building. Skip it when the dictionary or the user already settled it.
 3. If a metric is not documented, do not guess column names. Ask for the table/columns or introspect the provider schema, then propose a dictionary entry with `save-data-dictionary-entry`.
 4. Build a complete `SqlDashboardConfig` with `name` and `panels`. Optionally set top-level `columns` (1–6, default 2) to control how many grid columns the panels before any section use.
-5. Every panel needs `id`, `title`, `source`, `chartType`, `width`, and `sql`. `width` is the number of grid columns the panel spans (1..6, clamped to the active section's column count). Section panels skip `source` and `sql` and may set their own `columns` (1–6) to override the dashboard default for the panels following the section. Extension panels (`chartType: "extension"`) also skip `source` and `sql`; use `config.extensionSlotId` for new panels, with legacy `config.extensionId` supported for existing direct embeds (see "Embedding An Extension As A Panel").
+5. Every panel needs `id`, `title`, `source`, `chartType`, `width`, and `sql`. `width` is the number of grid columns the panel spans (1..6, clamped to the active section's column count). Section panels skip `source` and `sql` and may set their own `columns` (1–6) to override the dashboard default for the panels following the section. Extension panels (`chartType: "extension"`) also skip `source` and `sql`; use `config.extensionId` for ordinary author-selected shared embeds. Use `config.extensionSlotId` only when the user explicitly asks for a personal/per-viewer slot (see "Embedding An Extension As A Panel").
 6. Persist with `update-dashboard`, not raw SQL or settings writes.
 7. Navigate to it with `pnpm action navigate --view=adhoc --dashboardId=<id>`.
 
@@ -115,8 +115,27 @@ rather than forcing it into a native dashboard config.
 ## Embedding An Extension As A Panel
 
 Use `chartType: "extension"` to add an extension box alongside normal SQL
-charts. The panel skips `source` and `sql`. New boxes use a stable slot id in
-`config.extensionSlotId`:
+charts. The panel skips `source` and `sql`. For ordinary requests such as "put
+X in this dashboard," save the author-selected extension id in
+`config.extensionId`. This makes the selection part of the shared dashboard and
+keeps the widget present in scheduled report captures:
+
+```jsonc
+{
+  "id": "pipeline-widget",
+  "title": "Pipeline Widget",
+  "chartType": "extension",
+  "width": 3,
+  "config": { "extensionId": "extension-123" },
+}
+```
+
+Direct embeds receive the dashboard id, name, description, current filters,
+and panel context. Embedding does not grant extension access, so share the
+extension with the dashboard audience.
+
+Use a stable `config.extensionSlotId` only when the user explicitly wants each
+viewer to choose or install their own widget:
 
 ```text
 analytics.dashboard.<dashboard-id>.panel.<panel-id>
@@ -141,14 +160,14 @@ Empty slots show the normal install affordance instead of a broken iframe.
 
 Notes:
 
-- Slot-backed extensions receive the dashboard id, name, description, current
-  filters, and panel id/title/slot id as live context.
+- Both direct and slot-backed extensions receive dashboard and panel context.
 - Installs and extension access are per viewer. Sharing the dashboard does not
   automatically install or grant access to its extension for other viewers.
-- `config.extensionId` remains supported for legacy direct embeds. Use it only
-  when preserving an existing dashboard; new boxes should use a slot.
+- Slot installs are per-user preferences. Different viewers can see different
+  widgets, and scheduled reports running as a service identity may show an
+  empty slot. This is why slots are opt-in rather than the default.
 
-## Cloning A Legacy Direct-Extension Dashboard (e.g. per-customer copies)
+## Cloning A Direct-Extension Dashboard (e.g. per-customer copies)
 
 When the user asks for a copy of an existing extension-backed dashboard for a
 different customer/org (for example "make an Intuit version of the Roku usage
@@ -159,7 +178,7 @@ from that written file — never by pulling the body into chat context first or
 re-typing it as a `content` argument.
 
 1. `get-sql-dashboard` with `includeConfig: true` on the source dashboard and
-   confirm the target panel is a legacy `chartType: "extension"` panel with
+   confirm the target panel is a `chartType: "extension"` panel with
    `config.extensionId`; grab that extension id. For a slot-backed panel, clone
    the dashboard panel with a new stable `extensionSlotId`, then target and
    install the desired extension into that slot instead of using this body-copy
@@ -405,7 +424,7 @@ type PanelInput = PanelPatch & {
   chartType: NonNullable<PanelPatch["chartType"]>;
   source?: PanelPatch["source"]; // required for non-section / non-extension panels
   sql?: string; // required for non-section / non-extension panels
-  // For chartType "extension": use config.extensionSlotId; extensionId is legacy direct embed compatibility.
+  // For chartType "extension": use config.extensionId by default; extensionSlotId is opt-in per-viewer content.
 };
 
 type PanelFilter = {

package/corpus/templates/analytics/.agents/skills/gong/SKILL.md

@@ -12,6 +12,15 @@ dive that asks what happened in customer conversations.
 
 ## Actions
 
+- `gong-native-insights` — one provider-native qualitative synthesis operation
+  (`ask_account`, `ask_deal`, or `generate_brief`) through Gong's connected MCP.
+  Use it for themes, risks, summaries, and deck narrative when the native tools
+  are connected. One action invocation makes at most one Gong AI request; omit
+  `operation` to inspect its schemas without spending a credit request, and set
+  `allowCreditRequest=true` only for the one consolidated request you intend to
+  send. Paid calls also require a workspace owner to enable them once with
+  `configure-gong-native-insights`; the policy defaults off and disabling it
+  never blocks the raw evidence path.
 - `account-deep-dive` — first choice for named account/deal deep dives that
   need HubSpot plus Gong. It searches by account/deal/company/contact domain,
   loads Gong call details, and returns compact transcript excerpts for synthesis.
@@ -19,18 +28,32 @@ dive that asks what happened in customer conversations.
   a single transcript by call ID, or return transcript excerpts for matching
   calls.
 
-## Two-Pass Search Algorithm
+## Route Synthesis and Evidence Separately
 
-Gong search uses `POST /v2/calls/extensive` (not `GET /v2/calls` — that returns
-no parties). The search works in two passes:
+- Use `gong-native-insights` for qualitative synthesis where Gong may retrieve
+  and analyze evidence internally. Its result is provider synthesis: coverage
+  is unknown and raw transcript evidence is unavailable.
+- Use `gong-calls` or `provider-corpus-job` for quotes, exact counts, transcript
+  records, coverage-sensitive claims, and proof that something was absent.
+- Consolidate related native questions into one narrowly scoped request. Each
+  native operation independently consumes Gong credits, so do not make one call
+  per slide, bullet, or sub-question.
+- From a sibling app, call the exact cataloged read action directly through
+  `call-agent`'s `action` + `input` mode. This skips Analytics' second model loop.
+  Use ordinary message delegation only when Analytics must plan, join sources,
+  or synthesize across multiple operations.
 
-1. **Title match first**: filter calls whose title contains any search variant
-   directly.
-2. **Party/email-domain match second**: for calls that did not title-match,
-   fetch party data via the extensive endpoint and match against external
-   participant names, emails, and email domains.
+## Account Search Algorithm
 
-This two-pass approach catches calls titled "Builder <> Acme" when you search
+Gong search pages `POST /v2/calls/extensive` directly with the requested date
+window and party data (not `GET /v2/calls`, which returns no parties). Each call
+is matched against both:
+
+1. **Title variants**: the call title contains a generated search variant.
+2. **External parties**: an external participant's name, email, or domain
+   matches a generated search variant.
+
+This catches calls titled "Builder <> Acme" when you search
 "Acme Corp" by matching the "acme" name variant or "@acme.com" domain variant.
 The lib generates variants by stripping deal suffixes (`- New Deal`, `- Fusion`),
 corporate suffixes (`Group`, `Inc`, `Corp`, `LLC`), and deriving first word and
@@ -63,6 +86,10 @@ For account or deal deep dives:
 4. Use `transcriptLimit` around 3-5 for a first pass. For broad coverage of a
    named account, increase to 10-20 — the action supports up to 50. Increase
    when the returned calls don't cover the time window or key people you need.
+   For a bounded "review all calls" request with at most 50 matches, make one
+   call with `exhaustive=true`, `after`, `before`, and
+   `includeTranscripts=true`; do not split discovery and transcripts into
+   separate agent tool calls.
 5. Use the compact transcript excerpts returned by `includeTranscripts=true`.
    Do not fetch raw individual transcripts unless the user asks for exhaustive
    quoting, debugging, or export.
@@ -91,22 +118,26 @@ When a single transcript is needed, `gong-calls(transcript: "...")` returns
 compact extracted text by default. Set `rawTranscript=true` only for
 debugging/export, and never pass raw transcript payloads into `save-analysis`.
 
-## Complete-Coverage Transcript Scan (corpus-first)
+## Complete-Coverage Transcript Scan
 
 When the question is "do ANY of these calls mention X?" or "how many calls across
 this cohort mention X?" — where missing a single call makes the answer wrong — do
-NOT rely on `includeTranscripts` excerpts. They load only the newest few calls,
-truncated, and concluding "not mentioned" from that sample is how you ship a false
-negative. Use this two-step pattern:
-
-1. **Discover every call (cheap, metadata only).** For each account/deal, call
-   `gong-calls` with `exhaustive: true` and a bounded window via `after` (e.g. the
-   deal's closed-won date) and optionally `before`. This returns ALL matching
-   calls — not just `limit` — and never auto-loads transcripts, so it stays under
-   the function timeout. Collect the full `calls[]` (IDs + titles) across the cohort.
-
-2. **Batch-search the raw transcript endpoint.** Prefer `provider-corpus-job`
-   with `mode: "batch-search"` over one-call-at-a-time loops. Use
+NOT conclude absence from a sampled `includeTranscripts` result. Choose the
+smallest complete path for the bounded cohort:
+
+1. **Named account, up to 50 calls, qualitative review.** Make one `gong-calls`
+   call with `exhaustive=true`, a bounded `after`/`before` window, and
+   `includeTranscripts=true`. The action discovers every matching call and
+   fetches transcript excerpts in batches, returning `transcriptCoverage`. Do
+   not fetch the same call IDs one at a time afterward.
+
+2. **Bounded mention/absence search, up to 200 calls.** Make one `gong-calls`
+   call with `exhaustive=true`, the date window, `transcriptQuery`, and an
+   adequate `transcriptScanLimit`. Report its coverage fields and only make an
+   absence claim when coverage is complete.
+
+3. **Larger or multi-account corpus.** Prefer `provider-corpus-job` with
+   `mode: "batch-search"` over one-call-at-a-time loops. Use
    `provider-api-catalog(provider: "gong")` and its `corpusRecipes` if you need
    the exact shape. The canonical request is `POST /calls/transcript` with
    `batch.itemBodyPath: "filter.callIds"`, `batch.responseItemsPath:
@@ -115,7 +146,7 @@ negative. Use this two-step pattern:
    call IDs through `batch.inputDatasetId` + `batch.inputValuePath` or through
    `batch.items`.
 
-3. **Use `run-code` only for joins/reductions around the corpus path.** After
+4. **Use `run-code` only for joins/reductions around the corpus path.** After
    the transcript job exists, use `run-code`, `query-staged-dataset`, or job
    results to join hits back to deals/accounts, compute variants, dedupe, and
    format evidence. A `run-code` loop over `gong-calls(transcript: id)` is a

package/corpus/templates/analytics/.builder/skills/apollo/SKILL.md

@@ -7,54 +7,32 @@ description: >
 
 # Apollo.io Integration (Contact & Company Enrichment)
 
-## Connection
+## Use the shared provider API actions
 
-- **Base URL**: `https://api.apollo.io`
-- **Auth**: `x-api-key: $APOLLO_API_KEY`
-- **Env vars**: `APOLLO_API_KEY`
-- **Caching**: 10-minute in-memory cache, max 120 entries
+Apollo has no provider-specific action, route, or server client in Analytics.
+Use the shared provider API substrate:
 
-## Server Lib & API Routes
+- `provider-api-catalog` with `provider: "apollo"` to inspect the registered
+  base URL, authentication, official docs, placeholders, and examples.
+- `provider-api-docs` before relying on a remembered endpoint or request body.
+- `provider-api-request` for the authenticated request. The server injects
+  `APOLLO_API_KEY` as `x-api-key`; never pass the key in action arguments.
 
-- **File**: `server/lib/apollo.ts`
+For large searches, pass `stageAs` and the documented pagination settings, then
+use `query-staged-dataset` to filter or aggregate without loading the full
+response into agent context.
 
-### Exported Functions
-
-| Function                              | Description                                         |
-| ------------------------------------- | --------------------------------------------------- |
-| `searchPeople(params)`                | Search people by criteria                           |
-| `enrichPerson(email)`                 | Enrich a contact by email (returns null on failure) |
-| `searchOrganizations(query, params?)` | Search companies                                    |
-| `enrichOrganization(domain)`          | Enrich company by domain (returns null on failure)  |
-
-### API Routes
-
-| Route                    | Description               |
-| ------------------------ | ------------------------- |
-| `GET /api/apollo/search` | Search contacts/companies |
-
-## Script Usage
+## Example workflow
 
 ```bash
-# Search by email
-pnpm action apollo-search --email=user@example.com
-
-# Search by company
-pnpm action apollo-search --company=Example Inc
-
-# Search by domain
-pnpm action apollo-search --domain=example.com
-
-# Find decision-makers
-pnpm action apollo-search --company=Example Inc --title=CTO
-
-# Search by name
-pnpm action apollo-search --name="John Smith"
+pnpm action provider-api-catalog --provider=apollo
+pnpm action provider-api-docs --provider=apollo
+pnpm action provider-api-request --provider=apollo --method=POST --path=/api/v1/mixed_people/search --body='{"q_keywords":"vp marketing","page":1,"per_page":10}'
 ```
 
 ## Key Patterns & Gotchas
 
-- `enrichPerson` and `enrichOrganization` swallow errors and return `null` on failure (try/catch)
-- API uses POST for all searches and enrichment — POST responses are cached for 10 minutes
-- API endpoints: `/v1/mixed_people/search`, `/v1/people/match`, `/v1/mixed_companies/search`, `/v1/organizations/enrich`
-- Pagination info available via `response.pagination?.total_entries`
+- Apollo search and enrichment endpoints use POST; confirm current endpoint
+  paths and payloads through `provider-api-docs` before calling them.
+- Report the method, path, filters, returned row count, and pagination coverage.
+- Do not treat a default page as complete coverage.

package/corpus/templates/analytics/.builder/skills/commonroom/SKILL.md

@@ -7,48 +7,33 @@ description: >
 
 # Common Room Integration (Community)
 
-## Connection
+## Use the shared provider API actions
 
-- **Base URL**: `https://api.commonroom.io/community/v1`
-- **Auth**: `Authorization: Bearer $COMMONROOM_API_TOKEN`
-- **Env vars**: `COMMONROOM_API_TOKEN`
-- **Caching**: 10-minute in-memory cache, max 120 entries
+Common Room has no provider-specific action, route, or server client in
+Analytics. Use the shared provider API substrate:
 
-## Server Lib & API Routes
+- `provider-api-catalog` with `provider: "commonroom"` to inspect the
+  registered base URL, authentication, official docs, and examples.
+- `provider-api-docs` before relying on a remembered endpoint, filter, or
+  pagination shape.
+- `provider-api-request` for the authenticated request. The server injects
+  `COMMONROOM_API_TOKEN` as a bearer token; never pass it in action arguments.
 
-- **File**: `server/lib/commonroom.ts`
+For broad member or activity pulls, pass `stageAs` and the documented
+pagination settings, then use `query-staged-dataset` to search or aggregate the
+complete staged cohort.
 
-### Exported Functions
-
-| Function                         | Description                                         |
-| -------------------------------- | --------------------------------------------------- |
-| `getTokenStatus()`               | Check API token validity                            |
-| `getMemberByEmail(email)`        | Look up a member by email (returns null on failure) |
-| `getMembers(params?)`            | Search members (POST with query, cursor, limit)     |
-| `getActivityForMember(memberId)` | Get activity feed for a member                      |
-| `getSegments()`                  | List community segments                             |
-
-### API Routes
-
-| Route                         | Description              |
-| ----------------------------- | ------------------------ |
-| `GET /api/commonroom/members` | Search community members |
-
-## Script Usage
+## Example workflow
 
 ```bash
-# Search by email
-pnpm action commonroom-members --email=user@example.com
-
-# Search by query
-pnpm action commonroom-members --query=search_term
-
-# List segments
-pnpm action commonroom-members --segments
+pnpm action provider-api-catalog --provider=commonroom
+pnpm action provider-api-docs --provider=commonroom
+pnpm action provider-api-request --provider=commonroom --method=GET --path=/members
 ```
 
 ## Key Patterns & Gotchas
 
-- `getMemberByEmail` uses POST `/members/search` and returns single `CommunityMember` or null on error
-- API returns `{ items: ... }` wrappers or raw arrays — code handles both
-- Use for finding community engagement signals to enrich customer profiles
+- Verify member-search, activity, and segment endpoints in
+  `provider-api-docs`; do not rely on the removed bespoke client's assumptions.
+- Report the method, path, filters, returned row count, and pagination coverage.
+- Use raw activity/member evidence for exhaustive or absence-sensitive claims.

package/corpus/templates/analytics/.builder/skills/github/SKILL.md

@@ -7,70 +7,29 @@ description: >
 
 # GitHub Integration
 
-## Connection
-
-- **Base URL**: `https://api.github.com` (REST v3), `https://api.github.com/graphql` (GraphQL v4)
-- **Auth**: `Authorization: Bearer $GITHUB_TOKEN` (personal access token)
-- **Env vars**: `GITHUB_TOKEN`
-- **Caching**: 5-minute in-memory cache, max 200 entries
-
-## Server Lib & API Routes
-
-- **Server lib**: `server/lib/github.ts`
-- **Route handler**: `server/routes/github.ts`
-
-### Exported Functions
-
-| Function                        | Description                                                     |
-| ------------------------------- | --------------------------------------------------------------- |
-| `searchPRs(opts)`               | Search PRs using GitHub search syntax                           |
-| `searchIssues(opts)`            | Search issues using GitHub search syntax                        |
-| `getPR(owner, repo, number)`    | Full PR detail — commits, reviews, files (4 parallel API calls) |
-| `getIssue(owner, repo, number)` | Issue detail with labels, assignees                             |
-| `listPRs(owner, repo, opts)`    | List repo PRs by state (open/closed/all)                        |
-| `searchOrgPRs(opts)`            | Convenience wrapper — prepends the `org:<org> is:pr` qualifiers |
-| `runGraphQL(query, variables?)` | Raw GraphQL query                                               |
-
-### API Routes
-
-| Route                                                                | Description                            |
-| -------------------------------------------------------------------- | -------------------------------------- |
-| `GET /api/github/search?q=...&type=pr\|issue&limit=30`               | Full GitHub search syntax              |
-| `GET /api/github/pr?owner=...&repo=...&number=...`                   | PR detail with commits, reviews, files |
-| `GET /api/github/issue?owner=...&repo=...&number=...`                | Issue detail                           |
-| `GET /api/github/prs?owner=...&repo=...&state=open\|closed\|all`     | List repo PRs                          |
-| `GET /api/github/org-prs?org=<org>&q=...&state=OPEN\|CLOSED\|MERGED` | Org-wide PR search                     |
-| `POST /api/github/graphql` body: `{ query, variables? }`             | Raw GraphQL                            |
-
-## Script Usage
-
-```bash
-# Search open PRs in an org
-pnpm action github-prs --org=<org> --query="is:open label:bug"
-
-# List PRs for a specific repo
-pnpm action github-prs --repo=<org>/<repo> --state=open
-
-# Get full PR detail (commits, reviews, files)
-pnpm action github-prs --pr=<org>/<repo>/1234
-
-# Get issue detail
-pnpm action github-prs --issue=<org>/<repo>/567
-
-# Full GitHub search syntax (works across all orgs/repos)
-pnpm action github-prs --search="fix authentication is:pr is:merged"
-pnpm action github-prs --search="memory leak" --type=issue
-
-# Raw GraphQL
-pnpm action github-prs --graphql='{ viewer { login } }'
-
-# Filtering with built-in helpers
-pnpm action github-prs --org=<org> --grep="auth" --fields=number,title,state,url
-```
+GitHub access uses the shared provider API runtime and the Analytics GitHub
+OAuth connection. Do not add a separate GitHub client or `/api/github/*`
+pass-through routes.
+
+## Access Paths
+
+- Use `github-repo-files` for repository file discovery, bounded text search,
+  and file reads. It is the stable, agent-friendly wrapper around the shared
+  core implementation.
+- Use `provider-api-catalog`, `provider-api-docs`, and
+  `provider-api-request` with provider `github` for pull requests, issues,
+  searches, and GraphQL operations not modeled by `github-repo-files`.
+- For broad or paginated analysis, stage the provider response and reduce it
+  with `query-staged-dataset` or `run-code` instead of returning a large corpus
+  to chat.
+
+Authentication remains owned by `server/lib/github-oauth.ts`; provider calls
+must resolve the current viewer's OAuth grant or scoped credential through the
+shared runtime.
 
 ## Key Patterns & Gotchas
 
-### GitHub search qualifiers (useful for --search and --query)
+### GitHub search qualifiers
 
 - `org:<org>` — all repos in org
 - `repo:<org>/<repo>` — specific repo
@@ -84,9 +43,6 @@ pnpm action github-prs --org=<org> --grep="auth" --fields=number,title,state,url
 - `review:approved` — approved PRs
 - `review:changes_requested`
 
-### Implementation Notes
-
-- `searchOrgPRs()` is a convenience wrapper that prepends `org:<org> is:pr` — use `searchPRs()` / `searchIssues()` directly for full control
-- The REST search API returns up to 100 results per call; paginated list endpoints use `restGetPaginated()` with Link header traversal
-- `getPR()` makes 4 parallel API calls: PR data, commits, reviews, files — provides a complete picture in one shot
-- 5-minute in-memory cache on all requests
+Use provider documentation to confirm endpoint, version, pagination, and search
+behavior before making absence claims. Report the repository or organization,
+filters, page coverage, and any truncation with the answer.