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	Selects the scope checklist and reuses preparation, outcome and delivery rules
User/account site: detection, balance, plans, usage, keys, aff/invite	Account sites	Owns user identity, account credentials, units, and user actions
Management/admin site: connect, channels, providers, native resources	Managed sites and management checklist	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 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	Owns read-only discovery, execution, day/status semantics, and rewards
Deployment investigation, retained artifacts, or live validation	Evidence and validation	Shared evidence and reproducible test infrastructure
CDP/UI validation and visual handoff	Visual previews 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.

Before choosing the adaptation, investigate the official experience for the scoped user tasks: goals, ordinary steps, decision-making information, defaults and recovery. Use that evidence to decide how the extension should serve those tasks and where it can improve effort, clarity or reliability through existing shared workflows. Record the proposed adaptation and intended improvements in the task spec before implementation. Preserve the verified meaning and core task outcomes while allowing different layouts, controls and interactions; one-to-one reproduction of the official interface is not the acceptance target. Validate the delivered improvements against those task outcomes and explain any tradeoffs.

As part of that design, inspect existing adapters, canonical models, policies and UI workflows for reusable patterns. Reuse a suitable owner first; when verified common behavior is duplicated or an existing seam cannot express the new contract cleanly, extend it or extract the smallest coherent shared layer. Put common orchestration and presentation there, with provider-specific wire formats and policy differences at explicit adapter/capability boundaries. Use the shared path from the affected callers and validate representative existing and new consumers. Record the reuse or extraction choice and its benefit; keep unrelated migrations out of scope and avoid abstractions based only on similar-looking code or hypothetical future sites.

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 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 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.

   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 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; 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. Represent unsupported capabilities explicitly. Update public support/usage docs and locale resources when supported features, user actions or limitations change; when public catalog entries or advertised support boundaries change, synchronize the affected support tables and root compatibility lists across locales, following public catalog conventions. Capability-only adaptations do not require catalog edits while existing entries remain accurate; put user-facing workflow details in the relevant usage guide. Keep durable protocol rationale beside its owning code and deployment observations in task evidence, following the documentation ownership map. When a type, family/domain boundary or known upstream source changes, update the relationship overview. 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 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 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.
• 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. 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.