@clone-ai/prompt-prediction 0.7.0-bootstrap.0 → 0.7.0

package/docs/api.md

@@ -0,0 +1,69 @@
+# Direct HTTPS API
+
+## Authentication and base URL
+
+Base URL: `https://api.clone.is`. Send `Authorization: Bearer <app key>` from your backend. Never embed the key in browser or mobile bundles. [Download the OpenAPI contract](https://clone.is/api-platform/openapi.json) for exact field types and response schemas.
+
+| Method | Endpoint | Purpose |
+| --- | --- | --- |
+| POST | `/v1/predictions` | Complete a draft or predict the next prompt |
+| POST | `/v1/predictions/{request_id}/cancel` | Cancel pending work for the authenticated subject |
+| POST | `/v1/prediction-events` | Record a presentation, acceptance, edit, dismissal or successful submission |
+| POST | `/v1/prediction-feedback/clear` | Clear the authenticated product user's feedback memory |
+| GET | `/v1/usage` | App usage, billing model, remaining sandbox allowance and configured hard limit |
+| POST | `/v1/connections` | Start optional user-authorized personalization |
+| POST | `/v1/connections/exchange` | Exchange the one-time callback with PKCE and the same subject |
+| POST | `/v1/connections/{connection_id}/revoke` | Revoke only this app/user connection |
+
+App keys do not manage company billing or grant access to arbitrary Clone accounts. The owner-only `/v1/developer/apps` API uses a verified owner session or account management token. Use the [developer management reference](https://github.com/cloneisyou/clone-sdk/blob/main/docs/developer-apps.md).
+
+## Prediction fields
+
+| Field | Meaning |
+| --- | --- |
+| `request_id` | Stable identifier for one request and any replay of that exact body |
+| `user_id` | Subject derived from your backend's authenticated session |
+| `session_id` | Stable customer thread or workspace conversation |
+| `mode` | `next_prompt` with empty draft, or `complete_draft` with nonempty draft |
+| `draft` | `text` up to 8,000 characters and monotonic `revision` |
+| `context_revision` | Change when relevant conversation, artifact, preferences or selection changes |
+| `messages` | Up to 30 recent turns, each up to 8,000 characters; preserve `role` and `origin` |
+| `artifact` | Optional `video`, `slides` or `other` with ID, revision, selection and a known text summary |
+| `user_preferences` | Optional product-owned preferences, up to 4,000 characters |
+| `connection_id` | Omit or null for product context; otherwise an explicitly authorized connection |
+| `language` | Requested output language, default `auto` |
+
+Large context is subject to token-budget validation. Do not erase the user's latest correction to fit the envelope. See the schema for exact limits.
+
+## Responses and idempotency
+
+The result echoes request/session/draft/context/connection identity. `usage.prediction_units` is 0 or 1. Acceptance is valid only until `expires_at`; a retained replay receipt does not extend it. Result recovery is available for one hour. Never transform a timed-out paid request into a new ID automatically.
+
+`409 prediction_in_progress` means the original ID is pending; `409 idempotency_conflict` means its body or subject changed. `410 prediction_replay_expired` ends result recovery. Terminal failed or canceled IDs do not execute again. [Error and outage behavior](https://clone.is/docs/reliability).
+
+## Observation events
+
+Send `{ "event_id": "event-001", "request_id": "first-prediction-001", "user_id": "your-authenticated-user", "kind": "presented" }` to `/v1/prediction-events`. Kinds are `presented`, `accepted`, `edited`, `dismissed`, `submitted`, `rejected`, `feedback`, `outcome`. Keep the same event ID/body on retries. Ordinary observations contain no prompt text. Optional evaluation guidance and edited submitted text require explicit content opt-in; see [feedback](feedback.md). Events do not change billing.
+
+Record `submitted` only after your host accepts the send. Automatic Clone mode prompts have message origin `agent`; they must not be counted as independently human-written preferences or manual Tab acceptance.
+
+## Python, without the SDK
+
+```python
+import json, os, urllib.request
+
+with open("prediction.json", encoding="utf-8") as source:
+    payload = json.load(source)
+request = urllib.request.Request(
+    "https://api.clone.is/v1/predictions",
+    data=json.dumps(payload).encode(),
+    headers={"Authorization": "Bearer " + os.environ["CLONE_APP_KEY"],
+             "Content-Type": "application/json"},
+    method="POST",
+)
+with urllib.request.urlopen(request, timeout=15) as response:
+    result = json.load(response)
+# Validate identity and expiry before presenting result["completion"].
+```
+
+Use your host's cancellation and concurrency limits in production. The API returns predictions; your application owns agent execution and permissions.

package/docs/billing.md

@@ -0,0 +1,53 @@
+# Pricing and billing
+
+SDK 0.7.0 supports both sandbox and pay-as-you-go (PAYG) usage, including an optional company spending limit. Install the verified [0.7.0 release](https://github.com/cloneisyou/clone-sdk/releases/tag/v0.7.0). Hosted paid activation is available only when the developer console offers it; installing the SDK never enables payment.
+
+The company operating your product pays for hosted predictions. End users need no Clone account or personal subscription. SDK code is MIT licensed. The public catalog is [API pricing](https://clone.is/api-platform/pricing); availability depends on rollout, and existing individually negotiated contracts remain unchanged.
+
+| Item | PAYG policy |
+| --- | --- |
+| Sandbox | 1,000 valid suggestions once, shared across the developer account's apps; no card or automatic upgrade |
+| Production API | USD 0.02 per valid suggestion |
+| Monthly fee / minimum / included allowance | None |
+| Payer | One customer company account; all its enabled apps share a card and monthly invoice |
+| Default spending hard limit | None |
+| Alert budget | Optional company budget; email notices at 80% and 100%, no API interruption |
+| Hard stop | Only if the customer explicitly enables a separate company hard limit |
+| Billing cycle | Actual usage after each UTC calendar month, starting the next first day |
+
+Examples: 0 suggestions cost $0; 1,000 cost $20; 10,000 cost $200. A unit is a valid suggestion generated and settled by the server, whether the user accepts it or not. No suggestion, errors, cancellation before settlement, and identical request replays add no charge. Different requests can incur separate charges. Optional Clone personalization has the same unit price.
+
+## Card registration
+
+1. Open [Production setup](https://clone.is/developer/apps?setup=production) with a verified company developer account. Register or select the app. Store its one-time key before leaving the page and select **I saved the key** to continue to pricing and card setup. Existing apps expose **Continue production setup**. **Try the free sandbox** is a separate card-free evaluation path.
+2. Review and explicitly accept PAYG terms. **Add company card and enable PAYG** opens the hosted Stripe card-registration page. No usage fee is charged during card setup.
+3. Return to the console and confirm that the app shows PAYG as enabled. Returning from the payment page alone is not confirmation. Use **Refresh billing** if the status has not updated.
+4. The console shows SDK installation and verification instructions only after reading the active app's paid/PAYG state. Card registration alone does not mean the SDK is installed or tested.
+5. Additional apps remain sandbox until explicitly enabled through **Enable PAYG for this app**. They reuse the company card and invoice.
+
+Empty callbacks are valid for basic predictions; configured paid callbacks must use HTTPS and cannot enable loopback. The card number stays on Stripe. Incomplete setup leaves the app in sandbox. App creation, rotation, and disabling never replenish sandbox quota. An integration prompt alone does not authorize an agent to activate paid usage.
+
+## Usage, budgets, and payment recovery
+
+The console shows company totals, each app's usage, accrued charge, next billing date, card summary and invoice/receipt/PDF links. **Manage company card and invoices** opens the company Stripe portal, separate from personal Clone billing. To stop new usage, disable an app; only actual usage already incurred remains payable. There is no monthly subscription to cancel.
+
+Budget alerts do not stop service. The separate, unchecked-by-default hard-stop option covers usage across all PAYG apps, including pending requests. If explicitly enabled, it returns `402 customer_hard_limit_reached` before the limit is exceeded. Removing or raising the limit resumes new requests. Rate limits and security controls still apply.
+
+Missing, pending, or failed invoices do not automatically suspend PAYG predictions. Owners receive a payment notice and a 7-day recovery period. Update the card or complete payment/authentication through the hosted invoice. The end of this period does not automatically interrupt service; any later suspension requires a separate notice from Clone.
+
+Zero usage creates no Stripe charge. When an invoice is below Stripe's minimum charge, Stripe may mark it paid and carry the amount into the customer balance for a future invoice. The console separately reports the actual collected amount and balance carried forward. See [Stripe invoice behavior](https://docs.stripe.com/api/invoices). A Stripe `paid` status alone is not evidence that a card was charged.
+
+## Developer billing API
+
+Only a verified owner session or manual developer account token can access billing; app keys cannot. Cookie mutations require the approved web origin. These routes follow `/v1/developer/apps/{app_id}/billing`; the app identifies its owning company, while estimates, budgets and invoices are company-wide.
+
+| Method | Contract |
+| --- | --- |
+| GET root | App `config_revision`, company `billing_revision`, PAYG state, per-app/company usage, budget/hard limit, card, invoices and grace status |
+| POST `/checkout` | `expected_revision` from the app and `accepted_terms_version: "2026-09-23-payg"`; returns hosted card setup URL |
+| POST `/enable` | Same consent and app revision; enables another app on an active company mandate |
+| POST `/sync` | Refreshes card setup and invoice status |
+| POST `/portal` | Returns hosted company card/invoice portal URL |
+| PATCH `/budget` | Company `expected_revision`, nullable `budget_cents`, nullable `hard_limit_cents`; null removes that setting |
+
+Read state after changes. App and company revisions have different scopes. `409 billing_configuration_changed` or `app_configuration_changed` requires a refresh. `502 billing_processor_unavailable` requires reconciliation before retry. `409 billing_reconciliation_required` requires support, not a new app. Public `GET /v1/developer/pricing` is unauthenticated. `/v1/usage` remains app-specific; PAYG `monthly_cap_cents: null` means no hard limit, `cap_scope: company` identifies a configured limit's scope, and `invoice_cents` is that app's accrued charge, not a separate invoice.

package/docs/browser-onboarding.md

@@ -0,0 +1,69 @@
+# Account setup through browser and computer use
+
+This guide sets up the customer developer’s app and billing identity as part of the [one-prompt integration](start.md). End users do not need Clone accounts for basic predictions. The agent should navigate onboarding and resume implementation, rather than hand the customer a preparation checklist. Use only supported tools and the customer's authorized account. A documentation link does not grant new account, inbox or secret-store permissions.
+
+## Choose the shortest available path
+
+| Available access | Agent action |
+| --- | --- |
+| Existing app key in the approved backend secret store | Reuse it. Obtain owner access to verify production billing or change app settings; an app key cannot read company billing. |
+| Existing manual account token in the approved secret store | Use the [developer API](developer-apps.md). No browser bootstrap is necessary. |
+| Authorized browser/computer-use tools | Open [Production setup](https://clone.is/developer/apps?setup=production), reuse the signed-in owner session, or guide login/signup in that browser. A separate account token is not required. |
+| Neither account credentials nor browser access | Continue inspecting the product and implementing fixture tests. Ask the customer for browser access or one login at the exact console link, not a list of keys to create. |
+
+Before creating anything, inspect existing apps and the project's configuration. Establish where the one-time app key can be stored and whether the tools support transferring it without exposing it in transcripts. Do not create duplicates on retries or change a working key because you cannot see its plaintext.
+
+## Establish the Clone session
+
+1. Open `https://clone.is/developer/apps?setup=production`, or `?setup=sandbox` for an explicitly chosen evaluation. Preserve the complete `next` destination through login/signup so the selected path is retained. Read the actual screen before interacting. Check the owner identity through Account settings; never silently use a different signed-in account.
+2. Reuse the session or the customer's available authorized login method. If no account exists, follow **Sign up**, retaining the `next` destination. Use the customer's chosen identity. Do not invent an account, email address or password to complete the task.
+3. Let the customer complete unavailable credentials, new-password entry, identity checks and required agreements according to the tool's rules. Use an authorized email tool only for the specific verification message when such access is already granted; otherwise hand off that step in the browser. Never request a password, OTP or verification URL in chat. Optional analytics choices and selected context are not prerequisites for app registration.
+4. Return to Developer apps and verify that the app list/create form loads. A signed-in header alone is not proof of a verified developer account. If a required customer action interrupts the task, retain only non-secret progress and continue independent code work. Resume at the same step after it is completed.
+
+### Email verification and recovery
+
+If Developer apps reports that the account email needs verification, follow **Verify email** to `https://clone.is/verify-email`. Confirm the signed-in account shown there, then choose **Send verification email**. This sends to that account only. Use the newest link: sending another verification email invalidates older links.
+
+Never copy the verification link or token into chat, logs or source files. If the page asks for sign-in, use **Sign in** in the new tab, then return to the original verification tab and choose **I've signed in**. Keep that tab open. After a reload, reopen the original email link if it has not been used or expired. If the link belongs to another account, sign in to the intended account and reopen it.
+
+After verification succeeds, choose **Continue to Developer apps** and confirm that the app list/create form loads. A successful fixture test does not establish that a deployed environment can deliver email. If the page or email delivery is unavailable, report the exact service failure and continue independent integration work. Do not bypass verification or fabricate credentials.
+
+## Register the app in the console
+
+For basic predictions, leave callbacks empty. Only for optional Clone personalization, derive a callback from the customer’s actual backend and deployment configuration. Do not guess a production domain.
+
+1. In Developer apps, inspect **Your apps** and reuse the intended app. For an existing app, **Edit callbacks** opens its settings. Keep a still-needed old callback during rollout.
+2. For a new app, fill **App name** and **App ID**. **Callback URLs, one per line (optional)** can stay empty. The App ID field is a slug; the full resulting app ID must be read back rather than inferred. For local testing only, enable the checkbox for exact `http://127.0.0.1:<port>/<path>` callbacks. See [callback policy](developer-apps.md#callback-changes).
+3. In the default **Production integration** path, choose **Register app and continue**. For the separate **Try the free sandbox** path, choose **Create sandbox app and key**. Follow any required tool confirmation for creating credentials. Both initially register a sandbox app; registration alone never authorizes paid activation. The console exposes **Copy app key** and **I saved the key** after creation.
+4. Transfer the key directly into the approved backend secret store as `CLONE_APP_KEY`, verify its presence without showing its value, then dismiss it with **I saved the key**. Do not reload or navigate away before storage is confirmed. Save `CLONE_API_URL=https://api.clone.is` and any optional callback configuration too.
+5. Read back the app ID, callback list and sandbox state. If a save reports a configuration conflict, reload and reconcile. Never repeat a create/rotation blindly after a lost response. Keep non-secret app identity in the project configuration or integration report so later runs resume rather than restart.
+
+### One-time secrets and tool capabilities
+
+The current console renders the plaintext key once; an unrestricted screenshot or accessibility snapshot can therefore expose it. Check this before issuing a key. If the tooling supports a protected clipboard-to-secret-store or equivalent secret channel, use it without returning the value, recording the key region, or reading unrelated clipboard data. Never extract browser cookies or session storage to manufacture a management credential.
+
+If the available tools necessarily expose the secret, prepare the form and exact secret destination, then let the customer perform the issue/copy/save steps directly. Resume after the key is saved and dismissed. This is a specific capability limitation, not a reason to ask every customer to copy keys manually. Never fall back to pasting keys into the conversation or tracked files. A local ignored environment file is acceptable only under the customer's policy, with owner-only permissions.
+
+## Optional account token for API automation
+
+Prefer the browser session when it is enough. If repeated server-side management is needed and the customer intends to grant it, open [Account API keys](https://clone.is/clone-api). Fill **Key name** with a product-specific integration label and use **Create key**, respecting required credential-access confirmation and the same secret-transfer rules above. Store it as `CLONE_DEVELOPER_TOKEN` in the integration environment only. It is an account-level credential, not an app-scoped or automatically expiring onboarding grant.
+
+Use that token with the [developer API](developer-apps.md), which returns the runtime app key separately. After onboarding, revoke only the temporary account token created for this task and verify its removal. Do not revoke a pre-existing shared token. Keep `CLONE_APP_KEY` in the product backend; removing the temporary management token does not remove the app key.
+
+## Complete pricing and card setup
+
+In the production path, **I saved the key** opens pricing and card setup for that app. Show the current unit price and **No charge when you register your card. Actual usage is billed monthly.** The customer personally accepts the PAYG checkbox and completes Stripe card registration. Do not accept billing terms or enter card data on the customer's behalf. An existing company card can be reused through **Enable PAYG for this app** after explicit consent.
+
+On return, the console verifies setup through the server and reads current billing before showing **4. Install the SDK** and **Copy integration prompt**. Check the active app's `plan: "paid"`, `payg: true` and company mandate; do not treat `billing=success`, a saved-card summary or the sync response alone as completed activation. If setup is canceled, pending, or unavailable, reconcile the same app with **Refresh billing** and use **Add company card and enable PAYG** to reopen unfinished setup. Do not create another app/key or silently switch to a free trial. A deliberate switch to **Try the free sandbox** is allowed while the app is still sandbox.
+
+The free sandbox path shows installation after the key is saved and does not call paid checkout or enable. The URL stores only the selected path and non-secret app ID, so a return or reload resumes the app without preserving its one-time secret. The key must already be in the approved secret store.
+
+## Resume integration and verify
+
+After verified company billing, or an explicitly selected sandbox path, continue [package installation](start.md#2-obtain-and-install-the-package) and [integration](start.md#3-integrate-with-the-product) without asking for another setup prompt. The finished product must predict without showing Connect Clone first. If an end user chooses optional **Connect Clone** in settings, they separately sign in and consent to selected synced sources. App registration does not grant that consent. Do not preselect private context or claim connected tests passed without an authorized connection.
+
+Return the implemented files and test results, plus any exact outstanding authentication, secret-transfer, service-access or deployment dependency. Distinguish a verified existing-account flow from a fresh-account flow. Follow the [release access instructions](releases.md#release-access-and-ci) if GitHub access is restricted. No `npx` bootstrap command or docs MCP is currently supplied.
+
+## Paid billing requires the customer's explicit consent
+
+The [API pricing page](https://clone.is/api-platform/pricing) is public. Production setup shows pricing and card registration before installation. **Usage and billing** remains available for company budgets, invoices and payment recovery. Creating an app, integrating the SDK, and running the bounded sandbox test do not authorize recurring billing. Only start paid activation when the customer has explicitly approved that product, PAYG unit price and company billing terms. See [billing](billing.md).

package/docs/clone-mode.md

@@ -0,0 +1,40 @@
+# Clone mode
+
+## Separate suggestions from delegation
+
+Normal Tab completion never sends. Clone mode is an optional SDK 0.5.0 API that the customer must choose to expose. It starts only after the end user selects Start. No restored toggle, component mount, double Tab or prediction response starts it implicitly.
+
+Default bounds are three sends and five minutes. The host can choose one to 100 sends and a time bound up to one hour. The full next prompt is visible for at least one second (two seconds by default) before it is submitted. Always render the candidate, remaining turns, state and a visible Stop control.
+
+## Headless integration
+
+```ts
+import { CloneModeController } from '@clone-ai/prompt-prediction';
+const mode = new CloneModeController({
+  transport,
+  onSubmit: async (text, { requestId, origin, signal }) => {
+    // Check the signal and use the normal authorized host send path.
+    if (signal.aborted) return false;
+    return host.send(text, { requestId, origin, signal });
+  },
+});
+mode.update({ scopeId: authenticatedUser.id + ':' + thread.id,
+  context, draft: '', enabled: true, busy: false });
+// From the user's explicit Start button only:
+mode.start({ maxTurns: 3, maxDurationMs: 300000 });
+// After the host has finished the turn and provided a new context revision:
+mode.update(nextInput);
+mode.turnCompleted();
+// From Stop, logout, navigation, or a host execution failure:
+mode.stop();
+```
+
+React hosts can use `useCloneMode` from the `/react` entry. Supply the same input and callbacks, render `state.candidate.completion` during review, and call `turnCompleted()` after the real host turn finishes with fresh context. Disable ordinary background predictions while mode is active to avoid duplicate work.
+
+The host's `onSubmit` resolves true only after it accepted the send. It does not grant permission to purchases, publishing, file deletion or other host actions. Preserve the host's existing approval boundaries. Stop prevents future work and aborts the signal; it cannot retract a send already accepted by the host.
+
+## Stop conditions and attribution
+
+Draft edits, IME input, logout/disable, account or thread switches, changed personalization grants, hidden-page state in React, stale context during review, abstention, expiry, prediction errors and send failure stop the mode. There is no automatic retry. A pending unknown host send blocks restart until its receipt settles, preventing duplicate sends. Changing React `reviewMs` or `requestTimeoutMs` also stops the active run and preserves that pending-send guard.
+
+Only continue after an acknowledged host turn and a new context revision. Automatic messages use origin `agent`, not `human`. Personalized inference is a separate option; enabling Clone mode does not connect a Clone account or expand its selected sources. A server outage leaves manual typing and sending available.

package/docs/context-mapping.md

@@ -0,0 +1,28 @@
+# Customer context mappings
+
+These are integration examples, not claims about private customer code. Find each value's actual source in that customer's repository. Send concise text summaries, not raw video, images or slide binaries. No visual quality assessment is performed.
+
+| Contract | Video editor | Slide editor |
+|---|---|---|
+| `user_preferences` | Product-known editing/language preferences | Product-known audience, tone and formatting preferences |
+| `session_id` | Active editing/chat session | Active deck/chat session |
+| `context_revision` | Revision of combined messages + timeline + selection | Revision of messages + deck + slide selection |
+| `artifact.kind` | `video` | `slides` |
+| `artifact.id` | Project/timeline ID | Deck ID |
+| `artifact.revision` | Last stable timeline state revision | Last stable deck state revision |
+| `artifact.selection` | Selected clip IDs and time interval | Selected slide IDs/numbers |
+| `artifact.summary` | Known duration, cuts, captions, intended style | Known audience, outline, selected slide text, intended style |
+| `messages` | Current user/agent editing dialogue | Current user/agent slide dialogue |
+
+Only include state the application actually knows. Mark unavailable information as unavailable in the summary. Do not infer clip content or visual quality from a filename. Include the most recent human correction verbatim within the token envelope and update outdated preferences before sending. `origin` distinguishes `human`, `agent`, `accepted_prediction`, `edited_prediction`, `unknown`; acceptance does not transform generated text into independently observed user preference.
+
+```ts
+const artifact = {
+  kind: 'video' as const, id: timeline.id, revision: String(timeline.revision),
+  selection: selectedClipIds.join(', '),
+  summary: `Duration: ${timeline.durationSeconds}s. Captions: ${captionSummary}`,
+};
+// For slide editors use kind:'slides', deck revision, selected slide IDs and known slide text.
+```
+
+The host increments `context_revision` immediately when messages or selection change, even while no prediction request is running. Do not wait for the next agent response. Keep `artifact.revision` tied to actual artifact edits, independently of conversation changes. The SDK invalidates a displayed candidate on that change. Increment the context revision when user preferences change too. App-only responses have `connection_id: null`, `profile_revision: ""` and `grant_revision: 0`. For optional personalized responses, treat `profile_revision` and `grant_revision` as opaque service-issued values; do not derive or supply them yourself.

package/docs/data-and-service.md

@@ -0,0 +1,25 @@
+# Data and service boundaries
+
+The SDK is free under the MIT license. Clone's hosted prediction API is a separate service. The prepared PAYG policy is documented in [pricing and billing](billing.md). Confirm current availability and prices in the [service catalog](https://clone.is/api-platform/pricing) when hosted billing launches; retention commitments and any SLA must still be confirmed with Clone. This repository is not a service-level agreement. See Clone's [privacy policy](https://clone.is/privacy) and [terms](https://clone.is/terms), and confirm application-specific service commitments through [contact@clone.is](mailto:contact@clone.is).
+
+## What is sent
+
+The browser sends the current draft, recent app conversation, context revisions, optional app-scoped user preferences, and optional text summaries of the selected artifact to your own authenticated backend. Your backend supplies the authenticated user ID and calls Clone with its server-only app key. Do not send raw video/slide binaries or unrelated app data.
+
+By default `connection_id` is omitted or null and predictions use only the supplied product context. The service does not discover an end user’s Clone account or read any Clone profile in this mode. Send current permitted preferences on every request; basic requests do not carry preferences forward to future requests. Optional Connect Clone requires the user to sign in and explicitly select synced context. The SDK does not read or upload local Clone files. A disconnected or unsynced user must not be represented as having connected personalization. Source changes may require renewed consent; handle `context_changed_reconnect` by clearing the candidate and asking the user to reconnect.
+
+## Cancellation and accounting
+
+Keep each request ID stable when recovering an unknown transport outcome. The API can reject reuse with a different payload. New IDs may create new chargeable work. Acceptance/presentation events are separate from generation and do not indicate that a user sent a message.
+
+Aborting a client request prevents the SDK from inserting a late result. It does not guarantee that the service avoided work or reversed a charge already settled. Your backend should forward cancellation and use the service's cancellation endpoint where appropriate. Check service usage receipts for accounting.
+
+On logout or account switch, disable prediction and clear the displayed candidate, connection and attribution before binding the next authenticated host session. On Clone disconnect, clear the old candidate and connection; subsequent new requests can continue with product context. An explicitly invalid or revoked connection still fails, with no automatic fallback or duplicate billed request. Revocation cannot retract text the user has already copied or sent. Avoid logging drafts, context, keys, connection flow secrets, callback query strings, or completion text.
+
+## Test boundaries
+
+The demo returns deterministic synthetic suggestions. It proves UI mechanics only. Keep provisioned sandbox API behavior, consent/revocation, application authentication and browser/editor checks separate from fixture tests. Complete automated integration with available evidence; do not require additional human real-use sessions or manual QA. If app issuance is unavailable, report API verification as pending. Missing Clone consent affects only optional personalization verification; basic API predictions need no Clone end-user account. Native OS IME and human usefulness remain unverified without evidence specific to them. Do not present fixture success as evidence of suggestion quality or customer adoption. See [the agent entry point](start.md) for the bounded verification and onboarding workflow.
+
+## Feedback retention
+
+With the API feedback deployment, explicit evaluations and opted-in edited successful submissions are encrypted, scoped to the app/user/connection grant, capped at 50 records per user and retained for 30 days. They can influence subsequent new predictions as bounded evidence. Behavior receipts remain content-free; task outcomes are host reports. Clearing removes memory and fences off late old-request events, in-flight results and replay. No shared model-weight training is performed. See [feedback](feedback.md).

package/docs/developer-apps.md

@@ -0,0 +1,87 @@
+# Self-service developer apps
+
+Use [Developer apps](https://clone.is/developer/apps) for the browser flow. A coding agent can perform the same operations over HTTPS at `https://api.clone.is/v1/developer/apps`. This management API is separate from the SDK prediction client. SDK 0.5.0 retains PAYG usage types with a nullable spending cap and the existing prediction request contract. Request and response schemas are also available in the hosted API's `/openapi.json` under the `Developer apps` tag.
+
+## Authentication and ownership
+
+Use the customer's verified Clone account. If account access is not available yet, follow [browser onboarding](browser-onboarding.md) to guide login/signup and resume the task; do not require a customer-made token as the first step. The console uses its normal signed-in session, so browser agents can manage apps without a separate account token. A non-browser agent uses a **manual account API token**, issued at [Account API tokens](https://clone.is/clone-api), from the customer's approved secret store. In the examples, `CLONE_DEVELOPER_TOKEN` means that optional account token; it is not a new token type. It has account-level access, not an onboarding-only scope. Keep it out of the customer app runtime and revoke only a temporary integration token created for this task when the work is finished.
+
+Send `Authorization: Bearer <account token>` and JSON content type. Cookie requests require the exact Clone web Origin for writes. Server agents need no Origin header. Desktop credentials and `clnp_...` app keys cannot manage apps. Prediction calls continue to use `CLONE_APP_KEY`.
+
+An account owns one app collection and one shared lifetime sandbox allowance of 1,000 predictions. It can create up to 20 apps, including disabled apps. Do not create accounts or apps to evade limits. Existing operator-created apps cannot be claimed by specifying their IDs. Team membership delegation, ownership transfer, and restoring disabled apps are outside this API. Company PAYG card billing has separate owner-only [billing endpoints](billing.md).
+
+## Agent procedure
+
+1. Inspect the customer backend and authenticated user session. For basic predictions, create an app with `redirect_uris: []` (or omit it). No end-user Clone login or callback is required. Implement and register a state/PKCE callback only when adding optional Clone personalization.
+2. `GET /v1/developer/apps`. Reuse an existing intended app and its stored key. The response includes `apps`, aggregate `sandbox_used`, and `sandbox_limit`. It never returns keys or hashes.
+3. If there is no intended app, `POST /v1/developer/apps` with the request below. The `slug` is a stable customer-chosen suffix, lowercase letters/digits/hyphens, at most 40 characters. Save the full returned `app.id`; do not infer it from the slug.
+4. Save the returned `api_key` directly as `CLONE_APP_KEY` in the approved backend secret store. The response is the only display of that key. Store `CLONE_API_URL=https://api.clone.is`; configure and pass the callback explicitly.
+5. For a callback change, GET the current app list, then PATCH the full desired configuration with `expected_revision` equal to that app's `config_revision`.
+6. Run the integration and acceptance checks in [start.md](start.md). Fixture checks need no service credentials.
+
+Create request:
+
+```json
+{
+  "slug": "my-product-sandbox",
+  "name": "My product sandbox",
+  "redirect_uris": [],
+  "allow_loopback": false
+}
+```
+
+Successful creation is HTTP 201 with `{ "app": { ... }, "api_key": "clnp_..." }`. Treat `api_key` as a secret; never log the full response. `app` contains `id`, `tenant_id`, `name`, `redirect_uris`, `allow_loopback`, `config_revision`, `active`, `plan`, `monthly_cap_cents`, `payg`, and `sandbox_used`. The initial plan is sandbox. `monthly_cap_cents` is the legacy per-app manual-contract guard; PAYG returns null here and exposes the company hard limit through billing. It is not a charge or paid activation.
+
+If only a local environment file is available and the customer permits using it, exclude it from Git, use owner-only file permissions, and pass secrets through environment variables or a secret-store API. Do not put bearer tokens in command arguments, commit the file, print response bodies, or enable HTTP debug logging. Prefer the host's existing secret-management mechanism.
+
+## Callback changes
+
+`PATCH /v1/developer/apps/{app_id}` accepts the full editable configuration:
+
+```json
+{
+  "name": "My product sandbox",
+  "redirect_uris": [
+    "https://staging.customer.example/api/clone/callback",
+    "https://app.customer.example/api/clone/callback"
+  ],
+  "allow_loopback": false,
+  "expected_revision": 1
+}
+```
+
+The response is `{ "app": { ... } }` with an incremented revision. An empty list disables new Connect Clone attempts without disabling product-context predictions. For optional personalization, use HTTPS URLs matching exactly, with no wildcard, credentials, query or fragment. At most ten distinct URLs of 2,048 characters each are accepted. Sandbox apps may opt into literal `http://127.0.0.1:<port>/<path>` callbacks; paid apps require HTTPS.
+
+Adding a new callback preserves existing attempts. Removing an old callback invalidates pending authorization and code-exchange requests for that URL. Already exchanged connections remain active. Register both routes during a rollout, deploy the new route, then remove the old route when desired.
+
+## Rotation and disabling
+
+| Operation | Request body | Result |
+|---|---|---|
+| `POST /v1/developer/apps/{app_id}/rotate-key` | `{ "expected_revision": 2 }` | New `api_key` once, updated `app`; old key immediately invalid |
+| `POST /v1/developer/apps/{app_id}/disable` | `{ "expected_revision": 2 }` | Updated inactive `app`; all app-key access blocked |
+
+Only rotate or disable when explicitly intended by the customer. Neither operation resets usage. Rotation has no grace period: coordinate it with backend secret replacement. Disabling is not reversible through this API. An owner account deletion also blocks its self-service apps.
+
+## Failure and retry behavior
+
+Most domain failures use `{ "detail": { "code": "..." } }`; request-validation 422 responses contain a `detail` array with the affected fields and validation messages.
+
+| Status / code | Recovery |
+|---|---|
+| 401 / authentication failure | Use a valid account session or manual account token. Do not substitute the app key. |
+| 403 / `verified_account_required` | Complete the account's normal email verification. |
+| 403 / `developer_credential_required` | Replace a desktop credential with an account session or manual account token. |
+| 403 / `invalid_developer_origin` | Use the Clone console or a server HTTP client, not a foreign browser origin. |
+| 404 / `app_not_found` | The app is absent or belongs to another account. |
+| 409 / `app_already_exists` | List apps and reuse the existing ID. No key is reissued. |
+| 409 / `app_configuration_changed` | Read current state, reconcile intended changes, then send its new revision. |
+| 409 / `app_limit_reached` or `app_disabled` | Respect the account limit or inactive state. Do not recreate to reset usage. |
+| 400 / `invalid_callback_url` or `loopback_requires_sandbox` | Correct the callback policy or use a separate sandbox app. |
+| 422 | Correct the request schema; never send tenant, plan or quota overrides. |
+
+Do not automatically retry mutations after a lost response. GET the app list to find the result. If a create or rotation response was lost, the plaintext key cannot be recovered. Reuse a safely stored key if available; otherwise perform an explicitly intended rotation using the latest revision and immediately save its result. A timed-out PATCH can be verified by comparing the stored callback list and revision before deciding whether another write is needed.
+
+## Pricing and card billing
+
+Open [API pricing](https://clone.is/api-platform/pricing) without signing in. In [Developer apps](https://clone.is/developer/apps), open **Usage and billing** for an app to see its company usage, alert budget and optional hard limit, upcoming charge date, saved card, and invoices. Paid activation requires the customer’s explicit agreement and verified card setup. An ordinary SDK integration prompt does not authorize an agent to start a paid contract. See [billing](billing.md) for prices, timing, and recovery.

package/docs/feedback.md

@@ -0,0 +1,70 @@
+# Feedback loop
+
+SDK 0.6.2 adds `FeedbackTracker`, bounded event delivery, explicit rejection/evaluation/task outcomes, and clearing. These features require the API feedback deployment. Older clients and their five observation kinds remain supported. Missing or failed delivery is unknown, not negative feedback.
+
+## Host integration
+
+```ts
+import { FeedbackTracker, createEventTransport } from '@clone-ai/prompt-prediction';
+
+const feedback = new FeedbackTracker(createEventTransport('/api/clone/events'), {
+  collectSubmittedText: false, // default: no submitted text collection
+  onDelivery: receipt => diagnostics.record(receipt), // content-free
+});
+// Create the tracker once per identity scope, not on every render.
+// Supply onEvent and onValueChange to the composer component/controller.
+const onEvent = event => feedback.observe(event, draft);
+const onValueChange = value => {
+  feedback.input(value); // includes SDK insertion, human edits and Undo
+  setDraft(value);
+};
+// Call only AFTER the existing host send succeeds.
+function onHostSendSucceeded(text) {
+  const origin = feedback.submitted(text);
+  conversation.append({ role: 'user', content: text, origin });
+}
+```
+
+For React, pass both callbacks to `TabCompletionInput` or `useTabCompletion`. For a headless/custom editor, call `feedback.input(nextValue)` immediately after applying an accepted suggestion and after every later value change. Programmatic insertion does not necessarily emit a native DOM `input` event; listening only to DOM typing events is insufficient. Keep the tracker stable between renders and reset it when the identity scope changes.
+
+The authenticated host route calls `clone.recordEvent(session.user.id, body)`; Python uses `client.record_event(session.user.id, body)`. The server supplies the subject, never the browser body. Keep app keys on the server. Installing a package cannot connect your authentication, send or task-result callbacks automatically; wire these once in the host.
+
+Call `feedback.reset()` on logout/account/thread/connection changes before rebinding context. Old-scope delivery is aborted and local attribution cleared. Undo back to the original draft or clearing removes attribution without calling it quality rejection. Submission and collection must never trigger a send.
+
+## Explicit feedback
+
+```ts
+feedback.rejected(requestId, { reason: 'too_long' });
+feedback.feedback(requestId, { rating: 'positive' });
+// Only when the host has opted into content collection for this user:
+feedback.feedback(requestId, {
+  rating: 'negative', guidance: 'Keep it to one short sentence.', content_opt_in: true,
+});
+feedback.outcome(requestId, 'succeeded'); // the host must observe the actual task result
+```
+
+Kinds: `presented`, `accepted`, `edited`, `dismissed`, `submitted`, `rejected`, `feedback`, `outcome`. Presented means offered, not read; accepted means inserted, not sent. Escape/blur/expiry/silence is not explicit rejection. Sending is not task success. Automatic prompts are agent-origin, not manual acceptance or independently human-written preferences.
+
+Ratings: `positive`, `negative`. Reasons: `too_long`, `too_short`, `wrong_intent`, `wrong_language`, `incorrect`, `other`. Guidance has a 1,000-character limit and requires `content_opt_in: true`. With `collectSubmittedText: true`, the tracker sends `final_text` only after an edited prediction-assisted draft is successfully sent. The API limits it to 4,000 Unicode characters. Longer edits send submission attribution only, so optional text collection cannot prevent the event from being recorded. It never uploads per-character text, an unfinished edit or unchanged generated text. The API validates field/kind combinations.
+
+## Server memory and forgetting
+
+Only explicit evaluations/rejections and opted-in edited successful submissions enter encrypted memory. Behavior counts and host-reported outcomes are separate observations, not automatic preference labels. At most six recent records from the same app/user/connection grant enter the next new prediction. Basic and connected evidence stay separate. Current input, conversation and supplied preferences get the token envelope first. Feedback is untrusted evidence; edited submissions are past-task examples, not permanent preferences. No cross-customer pooling or model-weight training occurs.
+
+The response's `feedback_revision` identifies the records actually injected; empty means none. `feedback_enabled: false` omits feedback for a baseline/control. Replay retains its original response and revision. Memory expires after 30 days, with at most 50 records per app/user and hourly expiry cleanup.
+
+```ts
+await clone.clearFeedback(session.user.id); // authenticated host server
+```
+
+```python
+client.clear_feedback(authenticated_user_id)  # or await the async client
+```
+
+Clearing removes evidence and advances a user-scoped fence. Late old-prediction events cannot restore it. Replays and in-flight results that used cleared evidence are rejected. Content-free behavior receipts and billing remain intact; feedback does not generate or reverse a billable prediction.
+
+## Delivery and validation
+
+The browser transport has a two-second deadline per attempt and at most four concurrent deliveries. Network/429/5xx failures get at most two retries with the same event ID/body. Terminal identity/validation errors are not retried. Delivery is in-memory best effort, not a durable offline queue. `onDelivery` reports recorded/failed/cancelled without text. Input and host send remain independent.
+
+Verify edited send, Undo, rejection versus dismissal, duplicate/conflicting IDs, app/user/grant isolation, expiry, clearing during generation and late delivery. Compare feedback on/off using the same input/model configuration and fresh request IDs. Record the injected revision, human acceptance, edited submission and downstream results separately. Fixture comparisons prove wiring; quality uplift requires held-out or controlled live customer evaluation.

package/docs/pilot-validation.md

@@ -0,0 +1,35 @@
+# Validate a customer integration
+
+Install the verified tarball in a fresh project with `scripts/create-example.mjs` and run `npm install --ignore-scripts` and `npm run build`. This exercises the distributed files rather than repository imports. Use your authenticated server session for the user identity when adapting the example to a customer product.
+
+## Test the actual proxy
+
+The loopback example supports opt-in fault injection. Set `CLONE_DEMO_BACKEND=1`, server-only `CLONE_API_URL` and `CLONE_APP_KEY`, and `CLONE_DEMO_FAULTS=1`, then open `/?connected=1`. For another local port set `CLONE_SDK_DEMO_PORT`. The control is absent when fault injection is disabled. Never deploy this local example or fault controls as a production backend.
+
+Choose 503, 429, 402, network, malformed, timeout (a stalled response body), or latency (five seconds). In each state type, edit, Undo and manually send. Confirm that exactly your draft reaches the host once. Empty drafts must not produce a send. Tab without a candidate must retain normal focus movement. Restore `none`, accept a fresh suggestion with Tab, then send explicitly. Repeat with `?connected=1&assistant=1` for assistant-ui. Test IME on the target OS and customer editor; DOM automation alone does not prove native IME behavior.
+
+## Record observations
+
+Opt in with `CLONE_SDK_METRICS_FILE` pointing to a private local NDJSON file. Records contain timestamps, anonymous per-process request/session hashes, outcome, status and duration. They exclude drafts, responses, keys and account identity. Files are created with owner-only permissions. Keep this file outside source control and do not upload it by default.
+
+The default source is `fixture`. Set `CLONE_DEMO_PROVIDER_MODE=live` only when the connected test service really executes a model. Injected faults are labeled separately. Explicitly label a real customer pilot and obtain its measurement consent before recording its product behavior.
+
+The SDK transport exposes optional `onMetric` for duration through response-body completion, outcome and status. Your product can forward this to its existing diagnostics. Observers cannot block prediction or normal submission. See the example proxy for optional content-free collection.
+
+Operator observations:
+
+```sh
+node scripts/pilot-metrics.mjs start ./pilot.ndjson pilot-a
+# After clean installation, server wiring and a verified submit:
+node scripts/pilot-metrics.mjs verified ./pilot.ndjson pilot-a
+node scripts/pilot-metrics.mjs support ./pilot.ndjson pilot-a 10
+node scripts/pilot-metrics.mjs report ./pilot.ndjson
+```
+
+The report separates fixture, fault and live data; shows p50/p95 latency, failures, observed sessions, event delivery failures and ordered acceptance-to-submission. Optionally set `CLONE_SDK_PILOT_LABEL` to a non-personal consenting pilot label to count repeat sessions for that pilot. Missing telemetry is unknown. Session count does not establish returning customers. Record actual repeat visits and support work with the consenting pilot; do not infer adoption from test reloads or assign invented support minutes.
+
+## Acceptance boundary
+
+A local fixture validates package installation, HTTP wiring and interaction behavior. A live-provider run validates actual model latency and billing receipts. A customer run validates that customer's editor and integration. Each is separate evidence. Do not start broad outreach on the strength of fixture results alone.
+
+The example preserves each prediction's source for its metrics and event deliveries even after a fault changes. Source labels come from server admission. Unrecognized observations are omitted; the loopback example retains attribution for the latest 1,000 requests, rather than persisting a production analytics store.

package/docs/releases.md

@@ -0,0 +1,88 @@
+# Releases
+
+`cloneisyou/clone-sdk` is the canonical source. The SDK version is independent of Clone Desktop and the hosted API's schema version. Consumers install immutable package releases, not a Git submodule.
+
+During 0.x, breaking public contract changes increment the minor version; compatible fixes increment the patch. Once 1.0 is reached, use SemVer major/minor/patch rules. The public contract includes exported types and documented behavior such as Tab insertion, events, cancellation, and submission ownership. Never overwrite a published version or move its tag.
+
+## SDK 0.7.0
+
+Version 0.7.0 publishes the JavaScript SDK as `@clone-ai/prompt-prediction` and updates its install and import paths. Runtime exports and prediction behavior are unchanged. Version 0.6.4 updated the packaged npm installation guides. Version 0.6.3 keeps pilot measurements tied to the original prediction source, including late observations after a fault changes. Version 0.6.2 added the packaged feedback tracker, explicit evaluations and outcomes, feedback revision and clearing. Content-free diagnostics and pilot validation from 0.5.0 remain available. Feedback memory requires the matching API deployment; see [feedback](feedback.md). Python client 0.2.0 is distributed separately as a wheel and source archive. Optional presentation and Clone mode from 0.4.0 remain available; instant suggestions and manual submission remain the defaults. The older 0.3.1 artifact does not contain these features. Keep the installed archive and lockfile pinned until the upgrade passes in your own composer. `npm run test:package` builds, checks and installs the actual archive into independent React 18 and 19 examples.
+
+## Download and install
+
+The current release is [v0.7.0](https://github.com/cloneisyou/clone-sdk/releases/tag/v0.7.0). Install its public npm package with your existing package manager:
+
+```sh
+npm install --save-exact @clone-ai/prompt-prediction@0.7.0
+```
+
+Commit the lockfile. To install a checksum-verified GitHub archive instead, download its `.tgz` and `.sha256` into `vendor/clone-sdk`.
+
+When the repository is public, no GitHub credential is needed:
+
+```sh
+mkdir -p vendor/clone-sdk
+release_url=https://github.com/cloneisyou/clone-sdk/releases/download/v0.7.0
+curl --fail --location "$release_url/clone-ai-prompt-prediction-0.7.0.tgz" \
+  --output vendor/clone-sdk/clone-ai-prompt-prediction-0.7.0.tgz
+curl --fail --location "$release_url/clone-ai-prompt-prediction-0.7.0.tgz.sha256" \
+  --output vendor/clone-sdk/clone-ai-prompt-prediction-0.7.0.tgz.sha256
+```
+
+If GitHub reports restricted access, use an account with repository read access:
+
+```sh
+gh release download v0.7.0 --repo cloneisyou/clone-sdk \
+  --pattern 'clone-ai-prompt-prediction-0.7.0.tgz*' --dir vendor/clone-sdk
+```
+
+Then verify and install with your existing package manager:
+
+```sh
+(cd vendor/clone-sdk && shasum -a 256 -c clone-ai-prompt-prediction-0.7.0.tgz.sha256)
+npm install ./vendor/clone-sdk/clone-ai-prompt-prediction-0.7.0.tgz
+```
+
+On Linux, use `sha256sum -c` in place of `shasum -a 256 -c`. Commit the lockfile. Do not put access tokens in package URLs or lockfiles.
+
+## Prepare a release
+
+1. Update `package.json`, `CHANGELOG.md`, and versioned download links in the README.
+2. Generate types, run unit/browser/packaged consumer tests, and check dependencies.
+3. Run `pnpm check:public` and review the full staged diff, author metadata, generated output, and tarball contents against the [public documentation boundary](../CONTRIBUTING.md#public-documentation-boundary). Secret scanning alone is insufficient. A visibility change also exposes earlier repository records; review all refs, pull requests, releases, Actions artifacts and logs before changing visibility. Never import private Git history into a new public repository.
+4. Commit the SDK files, wait for CI, and create a matching `v<package version>` tag at that verified commit.
+5. The release workflow repeats the checks and creates a GitHub prerelease with the installable `.tgz`, SHA-256 checksum, Python wheel and source distribution. It downloads the uploaded archive using repository authentication, verifies its checksum, and tests installation. Verify the anonymous download separately after a visibility change.
+
+`npm pack` starts from a clean `dist` build, checks the actual package file selection for disclosure hazards, and creates `release-manifest.json`, which records hashes of distributed files. The external tarball checksum covers the archive, including `package.json` and the manifest. Neither a hash nor the fixture tests prove suggestion quality.
+
+## Registry publication
+
+The first public npm release, `@clone-ai/tab-completion@0.6.3`, passed an independent anonymous installation and matched its verified GitHub release. It used an authenticated local CLI and has no CI provenance. GitHub release archives remain available. The registry workflow refuses to run while the repository is private.
+
+Starting with 0.7.0, npm releases use `@clone-ai/prompt-prediction`. Publication requires a package-level trusted publisher for owner `cloneisyou`, repository `clone-sdk`, workflow `publish.yml` and environment `npm`, and `NPM_PUBLISH_ENABLED=true`. It allows direct `npm publish`. Distribution-tag management is not granted. Choose `next` (the default) for a preview or `latest` for a stable package when dispatching the workflow; the selected tag is assigned by publication itself. The manual workflow accepts an existing release tag and registry, repeats validation, compares all installed release content with the tested package, and uses OIDC instead of a stored npm token. See [npm's trusted publisher documentation](https://docs.npmjs.com/trusted-publishers/).
+
+The Python distribution is `clone-sdk`. Before the first PyPI publication, configure a pending trusted publisher with owner `cloneisyou`, repository `clone-sdk`, workflow `publish.yml`, environment `pypi` and the account owner's verified email. For an existing project, configure its publisher on that project instead. Enable `PYPI_PUBLISH_ENABLED=true` only after configuration. The PyPI job requires wheel and source bytes to match the release and verifies a fresh anonymous installation after publishing. See [PyPI publisher setup](https://docs.pypi.org/trusted-publishers/adding-a-publisher/).
+
+Account creation, email verification, 2FA and publisher authority must be complete before dispatch. Do not put passwords, OTPs or registry tokens in source files or chat. Registry install commands are available only after the exact version is published and independently installed.
+
+## Build this checkout
+
+For an unreleased checkout or local co-development, install dependencies with `pnpm install --frozen-lockfile` and pack the current source:
+
+```sh
+mkdir -p artifacts
+npm pack --pack-destination artifacts
+# In the consuming application, install the resulting versioned .tgz.
+```
+
+This local archive includes the current checkout, even when it still carries the existing package version. It is a test artifact, not a replacement for that published release. Assign a new version before publishing changes. Test the packaged application before updating downstream lockfiles. A dependency update does not migrate authentication, context storage, or server deployment.
+
+## Release access and CI
+
+For public releases, CI can use the anonymous download commands above. If repository access is restricted, use an authorized download or a verified archive delivered by your team.
+
+If permitted by the customer's artifact policy, a checked-in, checksum-verified `.tgz` dependency makes CI independent of download credentials. Commit the archive, external checksum, package manifest and lockfile together. Refresh from a new immutable release using an authorized developer account. The canonical SDK source remains here; do not modify the archive or copy individual SDK implementation files.
+
+If CI must fetch a restricted release directly, store a fine-grained token with read-only Contents access to this SDK repository as a CI secret and expose it only as `GH_TOKEN` to the download step. A consuming repository's default `GITHUB_TOKEN` is [limited to that repository](https://docs.github.com/en/actions/concepts/security/github_token) and cannot by itself read a different private repository. Do not copy a broad personal CLI token into CI. The SDK's own release workflow uses its same-repository `GITHUB_TOKEN` and needs no additional token.
+
+The MIT license remains unchanged. Old release versions and tags stay immutable. Changing visibility does not publish the package to npm or activate hosted billing.