@agent-native/core 0.107.2 → 0.109.0

package/corpus/templates/analytics/.agents/skills/feature-flags/SKILL.md

@@ -0,0 +1,169 @@
+---
+name: feature-flags
+description: >-
+  Declare, evaluate, manage, and remove framework feature flags. Use when
+  shipping a capability gradually, targeting users or organizations, or
+  replacing a compile-time rollout switch with a production-safe runtime flag.
+scope: dev
+metadata:
+  internal: true
+---
+
+# Feature Flags
+
+A feature flag is a boolean declared in app code, evaluated locally by Core,
+and managed from the Analytics fleet control plane. Code owns whether a flag
+exists. Runtime settings own only its rollout state.
+
+Flags let an app deploy dormant code and turn it on in the real environment
+without another deployment. They are not experiments: do not add variants,
+hypotheses, conversion metrics, exposure tracking, or lifecycle states.
+
+## When to use one
+
+Use a flag for a reversible rollout of a user-facing capability whose dormant
+code is safe to deploy. Flags are useful for production dogfooding, exact-user
+or organization pilots, and deterministic percentage rollouts.
+
+Do not use a flag for authentication, authorization, secrets, audit enablement,
+SSR cache behavior, or another security boundary. Client hiding is presentation
+only; every guarded server action must evaluate the same registered flag.
+
+## Agent workflow
+
+### 1. Declare
+
+Keep definitions in a shared TypeScript module so server and client code use the
+same stable key. Flags are boolean and default-off.
+
+```ts
+import { defineFeatureFlag } from "@agent-native/core/feature-flags";
+
+export const FULL_APP_BUILDING = defineFeatureFlag({
+  key: "full-app-building",
+  displayName: "Full app building",
+  description: "Create and edit Fusion-backed applications.",
+});
+```
+
+Keys are immutable, never reused, and contain only letters, numbers, dots,
+underscores, or hyphens. Prefer a concise app-owned name. Do not create flag
+definitions or rollout rows from Analytics.
+
+### 2. Register
+
+Register app definitions from a Nitro plugin before actions are discovered.
+Do not add app-specific flags to a Core registry.
+
+```ts
+import { createFeatureFlagsPlugin } from "@agent-native/core/server";
+
+import { FULL_APP_BUILDING } from "../../shared/feature-flags.js";
+
+export default createFeatureFlagsPlugin({ flags: [FULL_APP_BUILDING] });
+```
+
+### 3. Guard server and client
+
+The server action is the enforcement boundary:
+
+```ts
+import { isFeatureFlagEnabled } from "@agent-native/core/feature-flags";
+
+run: async (args, ctx) => {
+  if (!(await isFeatureFlagEnabled(FULL_APP_BUILDING, ctx))) {
+    throw new Error("Full app building is not enabled for this account.");
+  }
+  // guarded operation
+}
+```
+
+Use the client hook only to hide or reveal hydrated UI:
+
+```tsx
+import { useFeatureFlag } from "@agent-native/core/client";
+
+const enabled = useFeatureFlag(FULL_APP_BUILDING.key);
+return enabled ? <FullAppOption /> : null;
+```
+
+The client hook intentionally returns false while loading or for an unknown
+flag. Never replace that fail-closed behavior with app-local bucketing or a
+compile-time fallback. Never evaluate personalized flags in the public SSR
+shell; it is shared and cached for every visitor.
+
+### 4. Verify and roll out
+
+1. Verify the off path before changing rollout state.
+2. Confirm the registered flag appears in **Analytics → Feature flags** for the
+   app and is Off by default.
+3. Use **Enable for me** for initial production dogfood.
+4. Expand to exact emails, organization IDs, or a percentage only from
+   Analytics.
+5. Confirm the client presentation and authoritative server action agree.
+
+## Management contract
+
+Core mounts three actions in registered apps:
+
+| Action | Purpose |
+| --- | --- |
+| `get-feature-flags` | Return the current caller's evaluated boolean values. |
+| `list-feature-flags` | Return definitions and rollout metadata to an authorized operator. |
+| `set-feature-flag` | Atomically turn a flag off, enable it for the operator, or replace targeting rules. |
+
+Analytics calls the app-local operator actions through narrowly scoped A2A
+delegation. Tokens require an exact audience, organization, scope, operator
+role, and audit correlation id. Management is permission-checked and audited
+by the target app. Never manage flags through generic settings routes, raw SQL,
+or per-app toggle UIs.
+
+## Rollout semantics
+
+The operator modes are **Off**, **Targeted**, and **Everyone**. Core stores them
+as `off`, `rules`, and `on`.
+
+Targeted rules combine exact normalized emails, exact organization IDs, and a
+percentage with OR semantics. Exact matches are checked first. Percentage
+buckets use Core's stable hash of the flag key and authenticated user identity;
+anonymous callers fail closed. Raising a percentage preserves the users already
+included at a lower percentage. Do not implement bucketing in app code.
+
+Unknown definitions, missing state, malformed state, storage errors, and
+evaluation errors all return the code default (`false` in v1). Explicit Off
+wins over every target; Everyone enables every authenticated caller.
+
+## Remove a flag
+
+After a rollout is permanent:
+
+1. Replace guarded branches with the chosen behavior.
+2. Delete the server and client gates.
+3. Delete the definition and registration entry.
+4. Verify the flag disappears from the Analytics fleet.
+5. Remove stale tests and rollout instructions.
+
+A permanent flag is just an if statement with a pension plan.
+
+## Verification checklist
+
+- Unknown and unregistered keys evaluate false.
+- UI hiding and server enforcement use the same registered key.
+- Exact-user, organization, deterministic percentage, Everyone, and Off paths
+  have focused tests.
+- Increasing a percentage is monotonic; anonymous percentage evaluation is off.
+- Unauthorized callers cannot list targeting details or mutate flags.
+- Mutations are atomic, read back stored state, emit refresh, and appear in the
+  audit log with the flag key.
+- Analytics represents ready, no-definition, unsupported, forbidden, legacy,
+  and unreachable directory apps honestly.
+- Future agents can find this skill from root `AGENTS.md`, and
+  `pnpm guard:workspace-skills` passes after syncing generated copies.
+
+## Related skills
+
+- **adding-a-feature** — preserve UI/action/instruction/application-state parity
+- **actions** — define and call guarded app operations
+- **audit-log** — inspect automatic action mutation history
+- **reliable-mutations** — make rollout changes atomic and provable
+- **security** — keep security controls out of feature flags

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.

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

@@ -7,49 +7,31 @@ description: >
 
 # Pylon Integration (Support)
 
-## Connection
-
-- **Base URL**: `https://api.usepylon.com`
-- **Auth**: `Authorization: Bearer $PYLON_API_KEY`
-- **Env vars**: `PYLON_API_KEY`
-- **Caching**: 10-minute in-memory cache, max 120 entries
-
-## Server Lib & API Routes
-
-- **File**: `server/lib/pylon.ts`
-
-### Exported Functions
-
-| Function              | Description                          |
-| --------------------- | ------------------------------------ |
-| `getAccounts(query?)` | List/search accounts                 |
-| `getAccount(id)`      | Get single account                   |
-| `getIssues(params?)`  | List issues (30-day window enforced) |
-| `getContacts(query?)` | Search contacts                      |
-
-### API Routes
-
-| Route                     | Description          |
-| ------------------------- | -------------------- |
-| `GET /api/pylon/issues`   | List support tickets |
-| `GET /api/pylon/accounts` | List accounts        |
-
-## Script Usage
-
-```bash
-# Open support tickets for a customer
-pnpm action pylon-issues --account="Example Corp" --state=open
-
-# All issues
-pnpm action pylon-issues --query=search_term
-
-# List accounts
-pnpm action pylon-issues --accounts
-```
+Pylon access uses the shared provider API runtime. Do not add a separate Pylon
+client. `/api/pylon/issues` remains only as a thin compatibility route for an
+existing dashboard and delegates to the same action/provider runtime.
+
+## Access Paths
+
+- Use `provider-api-catalog`, `provider-api-docs`, and
+  `provider-api-request` with provider `pylon` for bounded account, contact,
+  and issue queries.
+- Use a data program with `providerFetchAll("pylon", ...)` for reusable joins,
+  exhaustive support-ticket analysis, or dashboard sources. Existing risk
+  meeting programs demonstrate the HubSpot-to-Pylon domain join.
+- Stage large responses and reduce them with `query-staged-dataset` or
+  `run-code` before returning results to chat.
+- For issue corpora, prefer `POST /issues/search` with the created-at filter and
+  body cursor. The older `GET /issues` endpoint has a 30-day window and should
+  not be used for broad dashboard coverage.
+
+Authentication is resolved from the current viewer's scoped Pylon credential
+through the shared provider runtime.
 
 ## Key Patterns & Gotchas
 
-- `getIssues` enforces a max 30-day window via `start_time` and `end_time` query params (API requirement)
-- API returns `{ data: ... }` wrappers or raw arrays — code handles both defensively
-- Pylon API exists in this analytics app (`code/`) but the secrets `pylon.api_key` and `pylon.api_secret` referenced elsewhere are in secrets manager, not env vars
-- No Pylon data in BigQuery — must query the API directly
+- Confirm the current endpoint, time-window, filter, and cursor contract with
+  `provider-api-docs`; do not impose a fixed lookback window in a wrapper.
+- Report inspected issue/account counts, pagination coverage, failed pages, and
+  truncation. A sampled response cannot support an exhaustive absence claim.
+- Query Pylon directly unless the user explicitly asks for a warehouse copy.