Add Site Integration

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.

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