---
name: add-site-integration
description: Add or extend account, managed-site or check-in integrations, improve native editors or compare their UX, or decide site-type boundaries. Uses scoped capability and workflow checks; not isolated bug fixes.
---

# Add Site Integration

## Select the workflow

Keep one entrypoint for shared evidence, authentication, and validation decisions. Load only the references needed for the requested outcome; account support, managed support, and check-in support are independent capabilities, not three mandatory stages.

| Requested outcome | Read | Why |
| --- | --- | --- |
| Every integration: prevent incomplete adaptation | [Checklist map and shared rules](references/capability-assessment.md#checklist-map) | Selects the scope checklist and reuses preparation, outcome and delivery rules |
| User/account site: detection, balance, plans, usage, keys, aff/invite | [Account sites](references/account-sites.md) | Owns user identity, account credentials, units, and user actions |
| Management/admin site: connect, channels, providers, native resources | [Managed sites](references/managed-sites.md) and [management checklist](references/managed-site-checklist.md) | Owns admin scopes and resource operations; assessed separately from account capabilities |
| Add, extend or compare a native editor, including existing integrations | [Native editor workflow parity](references/native-editor-parity.md) and the relevant account/managed checklist | Establishes common tasks and type/mode variants before choosing fields and layout |
| Check-in for a new or existing site | [Check-in](references/check-in.md) | Owns read-only discovery, execution, day/status semantics, and rewards |
| Deployment investigation, retained artifacts, or live validation | [Evidence and validation](references/evidence-and-validation.md) | Shared evidence and reproducible test infrastructure |
| CDP/UI validation and visual handoff | [Visual previews](references/visual-previews.md) and the project live-extension skill | Shows the actual current-worktree result alongside assertions |

For combined scopes, compose the relevant workflows and reuse captured contracts. For check-in-only work on a registered site, confirm its existing type/auth contract and update only check-in capabilities and consumers; skip unrelated onboarding, key management, and managed-site work. Split these into independent skills only if their invocation or shared workflow actually diverges; separate references already keep loading selective.

For existing-editor work, reuse confirmed site boundaries, authentication and deployment evidence. Apply the affected workflow/editor checks; revisit wider integration decisions only when their contracts change. UX comparison is in scope even without a new site type or API endpoint.

If only an audit is requested, use the checklist to report gaps and evidence limits; do not implement features or perform resource writes solely to fill the checklist.

## Required for every integration

1. Use the [integration guide](../../../docs/agents/site-integrations.md) for the relevant type relationships, upstream references, registration and adapter. Read the current task's `.scratch/<feature>/` spec and retained evidence if present, plus the closest existing adapter and tests. Reuse evidence whose deployment, version, identity scope, and contract still match; re-probe only missing or changed facts and record why. Follow [evidence and validation](references/evidence-and-validation.md) when investigating a deployment or planning live checks. Check a feature branch against its intended base before substantial implementation; preserve unrelated work.
2. Decide the **site type, scope, and adapter family separately** before coding. Record the evidence, alternatives rejected, and chosen count of site types in the spec or task report. Compare who owns the platform, how the app distinguishes account instances, credential validity, currency and balance meaning, authentication, and the user-visible account choice. Shared branding, endpoint shapes, or protocol alone do not settle the type decision:

   | Observed relationship | Registration choice | Precedent |
   | --- | --- | --- |
   | Equivalent domains reach the same accounts and credentials | One type with hostname aliases | Grsai's two console domains |
   | Fixed platforms from one provider have separate account/key worlds and regional credentials or balances, but share protocol | Separate site types using one configurable adapter family | Kimi China and Global |
   | Self-hosted installations or a fork share a product contract; each installation already has its own account URL | Keep the type and add a deployment override where needed | AI-ROUTER under Sub2API |
   | A backend version changes wire behavior without changing the user's site identity | Keep the type and isolate version-specific behavior | Rix API 6.x |
   | No existing family has the target authentication and resource contract | Add a type and dedicated adapter family | Grsai versus New API |

   Proactively inspect official homepages, documentation, console links, and endpoint/connection notices for additional domains before settling this boundary; the user's supplied URL is the starting deployment, not evidence that it is the only entrypoint. Record discovered domains by role (console/session, account API, management, inference, documentation) and their stated regional or fallback purpose. Verify account and credential equivalence separately for each relevant role and authentication method; a shared inference API Key does not establish shared console tokens or cookies. Use official listings and bounded read-only inspection rather than guessing subdomains. For account integrations, follow [domain discovery](references/account-sites.md#discover-domains-and-account-boundaries).

   Verify the boundary with provider docs or observed behavior. Separate account stores alone do not imply a new type for self-hosted sites: the saved site URL already identifies the installation. Do not try another region's API with a credential as an automatic fallback after an authentication failure.
3. Define the requested capability set and its evidence before advertising it. Use the [checklist map](references/capability-assessment.md#checklist-map) to copy the selected scope's checklist into the existing task spec and track it during discovery, implementation and validation. Management has a [separate checklist](references/managed-site-checklist.md); reuse common preparation and delivery rules without requiring account features for management-only work. Open-ended account adaptation must investigate every account item, not only balance and keys; explicit narrow scopes may exclude sections with a stated reason. Close each item with an outcome, how and why it is adapted, any omitted part and reason, and actual validation or the missing prerequisite. Apply the relevant workflow reference for scope-specific contracts, and use official source/docs or the target deployment. Save original requests, responses, and source excerpts as they are discovered, with provenance and artifact pointers; a prose conclusion alone is insufficient. Local developer evidence retains raw information by default and stays out of Git. A model list visible to one key is key-scoped evidence, not a full catalog. If a required contract remains unknown, ask for the deployment, version, or trace and continue independent work.

   Within the selected workflow, survey the provider's visible feature surface and existing app capabilities. For account-site work this includes **aff/referral/invite links**, check-in, redemption, announcements, usage, plans, pricing, and key actions; use the managed/check-in references for their respective surveys. Distinguish implemented, upstream unsupported, not adapted, unverified, deferred, and out of scope/not applicable. Adapter presence, inherited family behavior and candidate registration do not prove target support; absent code does not prove upstream absence. For an open-ended integration, implement simple supported features whose verified contract fits an existing capability/UI, especially invite-link retrieval/copy; do not stop at balance and keys by default. Respect an explicit narrower scope. Defer substantial new product flows separately, and do not label an unexplored feature unsupported. An invite link does not imply support for referral payouts or withdrawal.
4. **Compare authentication options and prioritize sustainable access before implementation.** Investigate the provider's supported console credentials, including personal access tokens, tokens with refresh, cookies/browser sessions, and interactive login. Compare required scope, verified lifetime and renewal, background independence, multi-account isolation, acquisition effort, revocation, and rotation effects. Unless the user chooses otherwise, prioritize implementing and defaulting to the best verified method that meets the account contract: a durable per-account token or safely renewable credential will usually be preferable to an ambient browser session. Ease of extracting a Cookie is not sufficient reason to select it; a manual security-verification step is a guidance requirement, not a reason to silently skip a better method. Record the default, viable alternatives, recovery path, and evidence; unknown expiry does not establish permanence. Keep the account bound to its origin and identity, and do not silently issue, rotate, replace, or downgrade credentials. A browser OAuth login does not renew a saved credential unless that link is verified. Follow the selected workflow reference for acquisition and recovery guidance.
5. Use TDD for the promised behavior. Start with a failing focused test; then update registration in `src/services/accountSiteDefinitions/` only where needed, detection/onboarding in their owning modules, wire protocol in `src/services/apiService/`, and account or managed capabilities in `src/services/apiAdapters/`. Reuse a family only for contracts actually shared. Cover the relevant success, auth failure/renewal, parsing, units, and dispatch paths. Read `docs/agents/storage.md` when credentials or cross-context writes change.
6. Wire the user paths promised by the scope: add/recover account, connect managed site, or discover/execute check-in; display data and offered actions. For account onboarding, complete the normal automatic-detection path through credential acquisition or guidance, verification, save, and refresh; do not wait for the user to request the missing guide. Follow [account onboarding](references/account-sites.md#complete-automatic-onboarding). Represent unsupported capabilities explicitly. Update public support/usage docs and locale resources when supported features, user actions or limitations change. Keep durable protocol rationale beside its owning code and deployment observations in task evidence, following the [documentation ownership map](../../../docs/agents/site-integrations.md#documentation-ownership). When a type, family/domain boundary or known upstream source changes, update the [relationship overview](../../../docs/agents/site-integrations.md#site-types-and-upstream-relationships). Preserve this navigable context; individual endpoint changes and live runs do not need another technical profile in general guidance.
7. Review the task-scoped diff for unsupported claims, leaked credentials, stale inventories, and documentation drift. Finish the evidence index, capability dispositions, reproducible probe/CDP commands, and cleanup results before handing off. In the user-facing handoff, state the chosen authentication default and reason, available alternatives and their implementation/validation status, and any required user step or re-login boundary; recording these only in internal evidence is insufficient. Report discovered service domains, their roles, which are supported/live-verified, and unresolved equivalence or justified deferrals. Run affected checks and commit only isolated task-owned changes; push only when authorized.

At each consequential stage, record **choice, evidence, alternatives, and reason** in the spec or evidence index: discovery approach, type/scope/family, capability coverage, authentication/recovery, endpoint roles, implementation reuse, validation target/layer, and any deferral or re-probe. Explain what the choice establishes and its limits; brief entries suffice. Record these decisions as work proceeds so a later agent can continue without reconstructing the investigation.

## Required when the condition applies

- **Native editor UI is added, extended or compared:** Complete [native workflow comparison](references/native-editor-parity.md) before selecting the field subset and layout, and reconcile it before the first completion claim. Working CRUD, preservation of unsupported fields and green tests alone do not establish usability parity.
- **A gateway/managed site is added or gateway selector/navigation order changes:** Follow the [gateway presentation order policy](../../../docs/agents/site-integrations.md#gateway-presentation-order) for evidence, placement in `MANAGED_SITE_TYPE_ORDER`, and validation of selector/navigation consumers.
- **Reversible resource writes are promised:** Use Playwright in an authorized, logged-in target deployment to exercise real create, edit, and delete behavior where those actions exist. Record the starting state, use disposable resources, read back each mutation, and confirm the original state is restored. Verify the observed authentication/signing sequence; keep raw secrets and account data out of committed evidence. For check-in or other irreversible grants, follow the selected workflow's execution limits and record the actual change. Mocks or source inspection do not establish a live write contract.
- **A durable personal access token is selected:** Reuse and verify an existing token before issuing another. Check whether creation rotates or overwrites an older token; never replay an issuance request after a lost response. New API's personal-access-token path illustrates this choice, but other family members can differ.
- **Expiring or rotating tokens are selected:** Verify expiry, 401, concurrent requests, uncertain refresh responses, and browser-session loss. Serialize single-use rotation, validate the replacement against the expected account, and persist the complete new credentials together before further requests. Do not replay an uncertain rotation or overwrite usable credentials after failure. Sub2API illustrates this choice and may require a matching browser fetch context for renewal or recovery.
- **A browser cookie or session is selected:** Verify whether it remains usable from the extension's required contexts and after the browser tab closes. Recover only from the matching origin and account identity; expose the re-login boundary when browser state cannot renew it.
- **A deployment splits browser, API, or export origins:** Keep the saved account URL bound to the browser/session origin. Resolve request and external-export origins at their respective boundaries; check every consumer of the saved URL, including browser recovery, detection, duplicate matching, current-tab fetch eligibility, and credential exports. Verify representative requests and exports reach the intended host.
- **Native keys or multiple origins are exposed:** Distinguish console credentials from inference keys and each deployment's export base URL. Treat masked list values as non-exportable; retain plaintext only when a verified create response supplies it. Do not invent a secret-reveal fallback.
- **Discovery or behavior varies by deployment or backend version:** Prefer structural, read-only evidence over branding; test rejection of other families and distinguish provider version from deployment build labels. Probe endpoint/auth differences when a version alone does not predict them. Exercise the complete transport and response envelope, including pagination beyond one page where the provider exposes it; a parser-only test cannot establish the wire contract.
- **An edit endpoint may replace omitted fields:** Determine its write semantics before mapping a partial UI edit to PUT. Preserve the original writable fields the provider requires, exclude secrets and server-owned fields, then read back both the requested change and unrelated fields.
- **Site registration changes modules loaded by the extension build configuration:** Run the actual extension build; unit tests and type checks do not cover configuration-time module resolution.
- **The backend can be self-hosted:** Inspect server source and runnable deployment instructions, then use or provision a disposable real backend when feasible within the authorized task. Extend the existing `e2e/realSite/` harness where it fits; record the pinned version, deployment recipe, test configuration names, and cleanup. A local backend is a real-site test, but does not prove a hosted fork's configuration or contract. Explain why self-hosting was selected or skipped; a public repository or mocked API alone is insufficient. See [validation target selection](references/evidence-and-validation.md#choose-validation-targets).
- **The integration is user-facing:** Finish with a site-specific CDP run against the current worktree's built extension in the dedicated development browser. Follow `.agents/skills/live-extension-ui-automation/SKILL.md`; drive the requested workflow and each promised feature action that the available account permits, including simple invite-link flows. Persist the site-specific automation using the existing CDP helpers; do not leave the only reproduction in a terminal or transient browser evaluation. Save and directly display representative screenshots following [visual previews](references/visual-previews.md). A generic CDP smoke run does not prove the site flow. Identify the worktree extension and target account in the evidence, and confirm cleanup.
- **Browser behavior cannot be established below E2E:** Add a focused mocked extension E2E for that behavior. It complements the live Playwright and CDP checks.
- **A relevant contract cannot be verified live:** Mark that capability or path unverified and explain the missing access or evidence. Do not call the integration fully live-validated.

## Optional, based on scope

- Substantial new flows such as redemption, referral settlement, alternate export formats, or managed resources depend on the agreed scope and verified provider support. Use the capability survey above to distinguish justified deferrals from missing investigation; do not use this optional scope to exclude simple supported features by default.
- Sync an existing account into the dedicated dev browser only if needed for the CDP path; use the existing profile deliberately. Add broad browser E2E only for a concrete remaining risk. Reuse or extend the existing CDP automation when it can express the required site-specific path.