# Orbit 1.6.0 documentation

# Managing voice and screen access

Open **Orbit → Settings → Voice & screen controls**. Agency managers can enable calls, connect/replace/disconnect the account voice key, choose a voice and language, set call duration and daily limits, adjust metadata retention and optional cost estimates, and pause or resume voice across the agency. Connection and agency pause buttons act immediately; configuration fields use **Save voice & screen settings**.

Choose a screen access level: navigation only; navigation and screen context; read/filter/open records; or those controls plus unsaved draft filling. Select which pages are allowed: Contacts, Tasks (including its list), Pipelines, Calendar, Conversations and Orbit. An empty selection disables all screen destinations. Turning screen access off leaves voice and reviewed CRM tools available. Existing settings without a level/page selection retain the previous full supported access; every caller must still opt in.

**Apply to** selects this account or agency defaults. Locked agency defaults cannot be overridden. **Use agency defaults for voice and support** removes the entire account policy override, including support configuration. Saved policy changes invalidate active calls. **Allow CRM changes** in the main settings remains the prerequisite for draft filling and reviewed CRM writes; support calls also follow **Configure support agent → Diagnostics & actions**. Screen settings never grant native permissions or bypass review.

Callers see the configured access level and pages before opting in. During calls they can mute, pause/resume screen controls, view activity, review proposals, or end the call. Escape and spoken pause requests stop screen work; only a user click resumes it.

# Expanded native screen controls — October 14, 2026

With screen access enabled, Orbit can navigate Contacts, Tasks (dashboard and list), Pipelines, Calendar and Conversations; inspect their registered controls; filter supported lists; open loaded records; and fill contact, task, deal, appointment and message drafts. Available controls depend on the current view, loaded data and permissions. This is structured in-app control, not desktop or arbitrary browser takeover. No extension is needed.

Inspect before each edit: commands bind to the exact screen revision and account. Human edits, changed routes, unmounted views and paused calls invalidate stale work. Each result waits for committed UI state. Pause screen control, press Escape, or ask Orbit to pause; resuming requires the user's button click. Voice can continue while controls are paused. End disconnects audio and cancels pending work.

Draft filling does not save, book, send or approve anything. Users submit native forms themselves; direct CRM actions still use Orbit's review cards. Do not both fill a native form and create the same record through an API proposal. Consent shares supported visible record labels and draft fields with the voice model. UI content is untrusted data, never instructions. Native role checks, Orbit tool permissions, support allowlists and practice restrictions apply server-side.

# In-app Orbit voice and Seedly actions

October 14, 2026 update. **Call Orbit** is available in regular conversations as well as support. No browser extension or desktop companion is required. OpenAI Realtime handles speech; the existing Orbit worker handles permission-checked CRM reads and reviewed actions.

## Using the call

1. Open a conversation in Orbit or its floating launcher. Select **Allow Orbit to use Seedly screens** if you want spoken requests to open pages, then choose **Call Orbit** and grant microphone access.
2. The persistent voice panel stays mounted as you navigate within the account, including returning to Orbit. Mute and End are always accessible. Closing the voice panel, changing account, leaving the dashboard or refreshing ends the call. Hiding the conversation does not end it.
3. Ask for CRM work such as finding contacts or preparing a task. Open **Conversation & approvals** in the voice panel to inspect evidence and approve a change in the exact originating conversation. Ordinary chats use normal Orbit permissions; support calls additionally enforce the configured support tool allowlist. Voice never bypasses reviewed writes.
4. Ask to open Contacts, Tasks, Pipelines, Calendar, Conversations or Orbit. The backend checks the current account, native feature and resource permissions, and per-call consent. The browser independently checks the destination against fixed routes and reports success only after the router reaches it. Route acknowledgement does not certify data loading. No arbitrary URL, selector, generated script, screenshot access or other website control is exposed.

## Configuration

In **Orbit → Settings → Voice & screen controls**, connect a direct OpenAI key and enable **Call Orbit**. Existing agency defaults, locked overrides, voice pause, call quotas, maximum duration, credential encryption and retention apply to both conversation types. Support itself can remain disabled while regular Orbit voice is enabled. Enable in-app screen controls in this section to let callers opt in per call. The text worker needs its configured provider or the user's enabled personal ChatGPT connection; voice always uses the separate OpenAI API credential.

The voice panel lives in the existing dashboard floating integration, independently of the companion's hidden preference and normal floating-chat setting. It opens only after an explicit Call Orbit click and never resumes automatically after a refresh. A failed or completed call requires another explicit start. Current-context permissions are rechecked for every backend tool; cancellation discards late results and aborts pending navigation acknowledgement.

Live audio acceptance still requires a funded direct OpenAI voice connection and actual microphone/playback testing. See VALIDATION.md. The historical 1.6 support-only implementation below documents the original candidate; its user-clicked page links and support-only entry point are superseded by the behavior above.

---

# Live support — Orbit 1.6

Signed-in Seedly users can speak with an AI assistant from an Orbit support conversation. Browser audio uses OpenAI Realtime over WebRTC. The voice assistant delegates support questions and CRM work to Orbit’s existing support runtime, using the selected chat provider, approved knowledge, native resource permissions and support tool allowlist. CRM writes remain immutable proposals approved with the on-screen card. Spoken approval never executes a write.

## Agency and account setup

1. Install 1.6 and deploy the Convex schema/functions before deploying the web app. `soLiveSessions` must remain a private extension table with `by_subAccount` purge indexing.
2. Keep Orbit’s current chat provider connected. Voice and the support worker have separate provider usage; live speech does not replace the worker’s model.
3. Configure `ORBIT_KEY_ENCRYPTION_SECRET` using the existing installation instructions. Never put provider keys in `NEXT_PUBLIC_*`, source, chat, or screenshots.
4. As an agency manager with settings-update permission, open **Orbit → Support → Configure support → Live voice support**. Connect a direct OpenAI API key for this account. The key is encrypted with tenant-bound AES-GCM. Model lookup verifies access without a voice inference request; it does not prove sufficient credits or working audio.
5. Enable **Speak with AI**, select Marin/Cedar/Coral, and set 1–15 minutes per call and 1–50 reservations per user per UTC day. A failed connection consumes a reservation. Defaults are disabled, five minutes and ten calls.
6. The existing Apply to selector controls agency defaults or account overrides, including override locks. Credentials always belong to the current account. An installer can optionally configure server-only `ORBIT_REALTIME_API_KEY`; that is a deployment-wide fallback billed to its owner, not a per-agency credential. Removing a saved account key can reveal this fallback.
7. Save support settings, start a support conversation, then choose **Speak with AI**. Microphone access requires HTTPS or localhost and a supported WebRTC browser. The call identifies itself as AI. Customers can mute, interrupt speech, end the call, and read live captions.

## What the assistant can do

- Explain approved product guidance and clarify an ambiguous problem.
- Ask Orbit to inspect permitted CRM records or configuration and speak a short summary. Evidence and proposal cards remain in the conversation.
- Navigate supported Seedly pages and inspect registered UI state after per-call consent and native permission checks. Controls can filter lists, open loaded records and fill supported unsaved native drafts. No screenshots, arbitrary selectors, generated code, external tabs, submit, send, delete or approval controls are exposed.
- Direct the user to the existing **Talk to a person** flow. The requester still reviews the destination and summary before submission.

## Execution and security contract

`liveProvider.start` accepts only a browser SDP offer, a requester-owned support thread, location and guidance preference. It creates a server-owned Realtime configuration and sends the SDP to `/v1/realtime/calls`; no standard or ephemeral provider key is returned to the browser. The browser forwards function calls to authenticated Convex actions. Browser/model arguments are untrusted: every request revalidates session ownership, location, support revision, enabled state, heartbeat and expiry. The server never trusts a client-supplied account override or tool-result assertion.

Only `ask_orbit`, `show_page`, `prepare_handoff` and `end_call` are exposed. `end_call` terminates the current call when the user asks to stop; the End button is the deterministic stop control. `ask_orbit` delegates through the existing runtime and adds a session reference to the run. `show_page` resolves a server allowlist; no arbitrary URL, selector, JavaScript, shell or browser environment is accepted. All CRM resource authorization and API scope rules remain enforced. Existing record-scope restrictions remain unchanged.

A call has at most 60 delegated tool calls, with atomic call-ID deduplication. Chat worker turns also consume existing daily turn limits. One active call per user/account is allowed, including calls spanning UTC midnight. Session minutes and call counts are not an exact dollar budget; configure provider spending limits separately.

The browser sends heartbeats every ten seconds. Backend checks reject heartbeats older than 45 seconds. A scheduled watchdog runs at most every 30 seconds and schedules a provider hangup on expiry, stale heartbeat, changed support policy or handoff. Hangup failures retry four times and retain a diagnostic error; network/provider failure can delay termination and billing. Background-tab throttling may end a call.

End closes browser tracks immediately and requests server cancellation. Running voice-worker replies and pending voice proposals are cancelled. Late results cannot append and stopped/expired sessions cannot approve proposals. An external write already approved and in flight cannot be undone by ending the call. Refreshing, switching conversation, or closing the floating panel ends the call. Reconnect starts a fresh voice session; there is no silent auto-retry of CRM writes.

## Storage and retention

Orbit does not store raw call audio or the continuous voice transcript. Live captions are browser-local. Delegated questions, worker answers, evidence and approval records are stored as normal private Orbit conversation data. Session metadata records owner/account, times, status, bounded tool IDs and any hangup failure. Provider data handling follows the connected OpenAI account’s terms/configuration; not storing audio in Orbit does not imply zero provider retention. New call metadata and rehearsal results expire after the configured 7, 30, 90 or 365 days (default 30). The setting is snapshotted at creation; changing it does not retroactively delete old records. Earlier 1.6 candidate sessions without expiry remain until native account purge. Active calls or calls awaiting confirmed provider hangup retain their cleanup data and retry retention the next day. Chat messages, proposal audit records, native tickets and provider retention are separate and are not erased by this setting. Account deletion uses native private-table purge.

## Validation before rollout

Use a synthetic account and a funded key. Check microphone denial, audio playback, greeting, interruptions, mute/unmute, a support question, an allowed read, forbidden operation, reviewed write, page guidance off/on, role revocation, policy/key changes, call expiry, network loss, tab close and human handoff. Verify actual CRM results and stored activity, not spoken claims alone. Test both agency and ordinary subaccount roles. Confirm provider hangup and usage after the test. Browser/provider audio certification is separate from mocked tool execution tests.

## Extending safely

Add each guided page to the explicit server map with the correct native resource and feature. Expose no arbitrary paths or selectors. For richer same-page guidance, add typed host UI commands with bounded inputs and acknowledgement; never return model-generated code to the browser. CRM writes must continue through `propose` → human `approve`, including any future computer-use adapter. A separate computer-use browser requires its own isolated runtime, login/access lifecycle, audit trail and approval boundary; it is not part of 1.6.

Official integration references: [Realtime](https://developers.openai.com/api/docs/guides/realtime), [WebRTC](https://developers.openai.com/api/docs/guides/realtime-webrtc), [Realtime calls](https://developers.openai.com/api/reference/resources/realtime/subresources/calls/methods/create).


## Support operations: setup, rehearse, improve

Open **Support → Setup** for five steps: purpose/knowledge, permitted actions, native human routing, voice/data/billing, and a real practice call. Settings links open the existing editor. Save changes before rehearsing. The readiness view distinguishes a saved credential from proven audio and shows which account or installer pays for voice. The worker remains billed through its configured chat provider. Avoid deploying a generic agent with every tool enabled: begin with the most common support topics and explicitly select operations.

**Support → Rehearsals** provides ten versioned scripts: greeting/microphone, knowledge, permitted lookup, correction, reviewed change, forbidden action, human handoff, interruption/stop, noise/silence, and network recovery. Each creates a requester-owned practice conversation. Practice mode blocks CRM execution and native handoff submission on the server; reads and AI calls are real and consume normal provider usage. Use synthetic accounts. Text scenarios can invoke the real support worker with one click. Audio scenarios must be spoken by an operator during a real call. No simulated audio, synthetic pass or automatic model-accuracy grading is claimed.

Inspect the conversation, sources, execution receipts and proposed actions against the script. End the call and confirm audible playback in its optional feedback. Mark pass/fail with notes in Rehearsals. Passing an audio scenario requires an ended call with reported playback; a text scenario requires a successful worker run. These are operator-reviewed assessments, not objective proof that the model was correct. Configuration revision or worker-model changes invalidate prior results. Repeat tests under ordinary subaccount permissions as well as agency roles; managers conduct and record the built-in rehearsals. Keep failure notes and fix one behavior at a time. No production support enablement is silently changed by a rehearsal.

Voice follows concise conversation rules for unclear speech, exact entities, corrections, short progress updates and explicit escalation. It can prepare an editable handoff review through `prepare_handoff`, but cannot send it. The draft separates the caller's problem, retrieved sources, actual proposal/action statuses and clearly labeled AI advice. It draws from at most 12 recent messages and 20 actions; it is not a complete transcript. The user can edit and must review the native destination before submitting. Explicit requests for a person are handled promptly; after two unsuccessful troubleshooting attempts the model is instructed to offer escalation. This remains model behavior rather than a guaranteed sentiment classifier. Published support hours and after-hours text are informational; there is no live staffing integration or automatic availability calculation.

**Support → Quality** shows bounded, account-level aggregates to agency managers with settings-update permission. It never exposes another user's transcript. The sample covers up to the latest 500 call records and 1,000 worker runs within the displayed 30-day period; shorter retention and truncation are labeled. Practice calls are excluded. Resolved means the customer selected Yes; unrated or disconnected calls and submitted handoffs are never automatically resolved. Repeat issues and unsupported claims are customer reports, not verified findings. Native handoffs count unique conversations with accepted submissions, not live transfers. CRM failures and evidence warnings come from stored execution blocks; worker failures are separate.

Latency percentiles measure browser-observed speech end to provider audio-buffer start, not actual speaker playback or audited provider timing. Interruptions are observed overlaps, not necessarily errors. Telemetry is best-effort, bounded, client-reported and may be missing if the browser closes or loses connectivity. The UI reports sample coverage. No continuous transcript or raw audio is stored. Review representative failed and flagged conversations with the requester; do not give managers blanket access to private chats.

Optional USD estimates use configured voice cost per reserved minute and worker input/output cost per million tokens. Zero means unset. Reserved time includes connection time and may differ from provider-billed time; late provider hangup, cached token pricing, cancelled/missing worker usage, taxes and pricing tiers can change the invoice. Estimates are not spending caps. Set provider budgets separately and review usage during the pilot.

**Pause agency voice** is independent of account overrides. It blocks new calls and backend voice actions immediately at the next permission check; browser subscriptions, heartbeats and the 30-second watchdog terminate current calls. It does not disable text support or undo already-approved external writes. Resume removes the pause but does not automatically start any call. Agency policies and the pause flag use the existing tenant-purge anchor account: export/re-establish the agency policy before deleting that anchor.

## Suggested pilot and operating routine

1. Choose a small group of accounts and 5–10 common support questions. Publish approved answers, owner/escalation instructions, support hours and the true request destination.
2. Run the scripts with representative permissions, noisy microphones, corrections and interrupted requests. Include forbidden cross-account/secret requests. Verify source receipts and CRM outcomes independently of spoken claims.
3. Start with reads and limited reviewed proposals. Confirm provider billing and native request delivery separately; a preview or mocked test is not a delivery test.
4. Review unresolved calls, failed tools, evidence warnings, reported unsupported claims and repeat issues. Compare customer-confirmed resolution with latency and cost; do not optimize for short calls or lack of escalation alone.
5. Rehearse again after knowledge, tool, prompt, model or policy changes. Pause agency voice if it misroutes work or makes unsafe claims, investigate, then explicitly resume. Keep the native support form available throughout.

Design references: [OpenAI voice prompting](https://developers.openai.com/api/docs/guides/voice-prompting), [Google voice design](https://docs.cloud.google.com/dialogflow/cx/docs/concept/voice-agent-design), [Amazon Connect simulations](https://docs.aws.amazon.com/connect/latest/adminguide/testing-simulation.html), [Twilio voice measurements](https://www.twilio.com/docs/voice/voice-insights/conversation-relay-insights-dashboard). These inform the defaults, not a claim of certification or equivalent enterprise scale.

## Demo-day checks

Open the sandbox in the browser you will actually present. Check chat first, then inspect Support → Setup and Rehearsals. A saved text rehearsal does not prove microphone or speaker playback.

1. Run Product guidance and inspect its recorded knowledge source.
2. Run Forbidden action and verify the reply refuses cross-account/secret access. A provider refusal must appear as a refusal; an empty response must never claim retrieved records.
3. Rehearse Reviewed change in a practice conversation. Inspect the proposal; practice mode blocks execution and support-request submission.
4. For voice, connect the direct OpenAI key, run Welcome & microphone, confirm audible playback, then test interruption, End, and network recovery in the presentation browser.
5. Keep text chat available as the recovery path. Failed setup times out after 45 seconds; ending or losing the call releases the microphone. Do not mark audio scenarios passed without an actual audible call.

OpenRouter continues to power chat and delegated support work. OpenRouter documents separate speech-to-text and text-to-speech APIs, which could support an additional turn-based voice implementation. They are not wired into this release’s continuous WebRTC transport. Changing the worker provider or pasting an OpenRouter key into the OpenAI voice-key field does not enable that transport.


---

# Upgrade to Orbit 1.6

Back up the current original module, host files and database. Preserve the verified 1.5 archive. Preview the installer changes and resolve customer modifications rather than overwriting them. The host reference remains Seedly 5.8.4; newer forks require their own compatibility checks.

1. Verify the archive’s SHA-256 and its bundled file manifest with `node bin/verify.mjs`.
2. Run `node bin/install.mjs --seedly /absolute/path/to/seedly` to preview, then repeat with `--apply`. Run `node bin/doctor.mjs --seedly /absolute/path/to/seedly`.
3. Generate fresh Convex APIs and check backend types. Deploy the schema/functions to the intended host deployment before publishing the frontend. Never copy a sandbox deployment configuration into production.
4. Verify native private-table/snapshot/purge guards include `soLiveSessions` and `soSupportRehearsals`. New operations settings, agency voice-pause flag, practice/draft thread fields, call feedback/measurements, support policy, credential, run and message fields are optional so existing 1.5 records remain valid.
5. Build/typecheck the web app and run Orbit host tests. Follow LIVE_SUPPORT.md for an actual audio/provider test on a synthetic account.
6. Voice is off by default. Existing chat keys, support settings, agents and approval policies remain intact. Configure a direct OpenAI voice key and enable voice only for selected accounts first.

Rollback: disable live support and end calls before returning to older frontend code. Retain the expanded schema/private-table registry while 1.6 rows and optional fields exist; an older strict schema can reject these records. Do not purge stored conversations or keys merely to force rollback. Keep the original 1.5 customer downloads immutable as the prior-version fallback. Run real microphone/provider acceptance in your own test host before enabling voice for your users.

## Native screen controls

The installer adds reversible hooks to supported Contacts, Tasks, Pipelines, Calendar and Conversations components. Modified host layouts fail preflight rather than being overwritten. Existing voice policies preserve their previous supported screen access; review the new access level and page allowlist under Settings → Voice & screen controls. Callers still opt in per call. New policy fields are optional. Backend/schema must deploy before the new web UI.


---

# Upgrade to Orbit 1.5.0

Read AGENT_INSTALL.md and IMPLEMENTATION_CONTRACT.md first. Verified host: Seedly 5.8.4, extension API 1. Seedly 5.8.14 and modified forks require their own compatibility checks.

## Before installation

- Back up the licensed host checkout, deployment configuration and database using your normal host workflow. Keep the previous Orbit archive and installer receipt.
- Verify the new archive against its sidecar, extract to a separate directory, and run `node bin/verify.mjs` there. Never overwrite the only copy of the previous release.
- Preview with `node bin/install.mjs --seedly /absolute/path/to/host`. Review the diff. Customer-modified owned files fail closed; reconcile those deliberately instead of overwriting them.

## Apply and release

1. Run `node bin/install.mjs --seedly /absolute/path/to/host --apply`, then `node bin/doctor.mjs --seedly /absolute/path/to/host`.
2. Confirm `soSupportPolicies` is registered as a private table with its native tenant-purge index. Existing chats, agents and provider settings remain in their existing tables. New thread/action/agent fields are optional; no backfill or new environment secret is required.
3. Generate fresh Convex API bindings. Run backend/frontend types, installed-host Orbit tests, native extension privacy/purge tests and a production web build. Never aim a clean validation checkout at a production backend.
4. Deploy backend/schema first, then the web app, following the host's deployment process. The module installer does not deploy either.
5. Test a regular chat, a saved agent and a synthetic reviewed proposal. Check permissions as both a manager and a restricted user. New event conditions require a new rehearsal before the edited agent can run.
6. Configure Support at the agency or account level. Support defaults to disabled, with no CRM tools allowed. Existing accounts are not silently enrolled. Add approved article text, select permitted tools, and test a greeting, product question, ambiguous problem and read-only CRM request.
7. Preview the human handoff and verify its native destination. Submit only to a designated test recipient when validating delivery: the native host may notify support members. Existing native feedback remains available.

## Rollback

Disable Support and pause affected agents while investigating. Revert the web release first and preserve database backups and newly created support records. Do not remove new tables or optional fields merely to restore the old UI. Any backend rollback must retain schema compatibility with stored data and be validated in staging; do not blindly redeploy a 1.0 schema over 1.5 data. An additive forward fix is often safer. Preserve the failed deployment's logs and exact archive checksum.

## What changed

- Natural support chat with agency/account configuration, approved knowledge, permitted diagnostics and reviewed actions.
- Reviewed summaries handed to the native brand-admin request queue; AI pauses after handoff. This is request intake, not bidirectional human chat.
- Conversational agent drafts, before/after previews on supported updates, and rechecks of known values before applying.
- Event conditions for required/excluded tags and lifecycle stage, plus a personal agent inbox and optional success notifications.
- Compact tool activity, better agent browsing and support intent guidance. Agency instructions supplement the built-in behavior.

Read SUPPORT.md, AGENTS.md and VALIDATION.md for exact limits. AI usage, hosting and the Seedly license remain separate.


---

# Orbit 1.6.0 — October 14, 2026

- Call Orbit from regular or support conversations with a persistent voice panel across same-account pages.
- Navigate supported Seedly pages, inspect registered screen state, filter lists, open loaded records and fill unsaved contact, task, deal, appointment and message drafts.
- Manage voice, credentials, language, call limits, screen access levels and allowed pages from Settings → Voice & screen controls. Agency defaults, locked overrides and agency-wide pause remain enforced.
- Pause screen work by button, Escape or voice; resume by user click. Stale commands, account changes and revoked policies are rejected.
- CRM actions still require review; native draft filling does not save, send or book. No extension, arbitrary website control or screenshot capture is included.
- Includes the prior support setup, rehearsals, quality reporting and handoff improvements below. Requires a separately licensed Seedly 5.8.4 host and customer provider credentials.
- Local build, permissions, installer and native-screen checks pass. Actual OpenAI microphone/provider acceptance remains unverified; see VALIDATION.md. Existing 1.5.0 archives remain immutable.

# 1.6 support operations additions

- Five-step setup with voice/worker readiness and billing ownership.
- Concise voice rules for corrections, unclear audio and escalation; evidence-based editable handoff drafts.
- Ten repeatable operator rehearsal scripts and one-click text scenarios. Server blocks practice CRM execution and support submission. Revision/model changes require retesting.
- Optional call outcomes/playback confirmation and account quality aggregates: resolution, handoff, repeat issues, reported claims, recorded tool failures/warnings, timing, usage and configured estimates.
- Agency-wide voice pause, optional language/after-hours settings and bounded metadata/rehearsal retention.
- Raw audio and continuous transcripts remain unrecorded by Orbit. Real audio certification is separate.

# 1.6.0 — Live support candidate

- Optional OpenAI Realtime voice with captions, mute, end-call and bounded sessions.
- Voice delegates to existing support knowledge, diagnostics and reviewed CRM tools.
- Agency/account voice controls and an encrypted per-account OpenAI connection.
- Opt-in permission-checked links to supported CRM pages.
- Session ownership, revision checks, heartbeat expiry, duplicate-call protection and cancellation of unapproved voice work.
- Original 1.5 downloads remain unchanged. Live audio verification is distinct from fixture validation.

# Orbit 1.5.0 — September 30, 2026

## Support inside the CRM

Agency defaults and optional account overrides control identity, tone, instructions, curated knowledge, diagnostic access and permitted CRM actions. Support recognizes everyday requests, product questions and troubleshooting in context. CRM changes remain reviewed proposals. Users can preview and edit a summary before sending it to the native support request queue, then see its intake status in My requests. AI replies and approvals stop after handoff.

## Agents and workspace

- Draft an agent through conversation, then review its setup and rehearse before enabling.
- Filter supported CRM events by required/excluded contact tags and lifecycle stage.
- Follow personal agent outcomes and approvals in Inbox; optionally surface successful runs.
- Review before/after values for supported updates. Known values are rechecked before applying.
- Quieter tool activity and a more compact agent workspace.

See UPGRADE_1_5.md for installation and rollback considerations. See VALIDATION.md for the verified host and live/fixture coverage. Human handoff is native request intake, not live staff chat. Support articles are curated text, not automatically crawled websites. Source 1.0.0 and earlier archives remain unchanged.


---

# Support mode

Support mode helps signed-in Seedly CRM users ask questions, inspect permitted account data, review proposed CRM actions and submit a request to a person. It uses the account's existing Orbit AI connection and appearance. It is not an anonymous website widget or an unattended support operator.

## Configure an agency or account

1. Open Orbit → Support → Configure support, or Orbit Settings → Configure support agent.
2. Choose Agency defaults to establish shared settings. Leave Allow account overrides on for account-specific configuration, or turn it off to enforce the agency configuration everywhere. Only a native agency owner/administrator with settings-update permission can save either scope.
3. Set the name, avatar symbol, welcome, tone and instructions. Enable support chat when ready. Instructions can specify escalation guidance but cannot grant tools or bypass permissions, approvals or handoff state.
4. Add approved knowledge articles. Built-in guidance covers Orbit provider setup, agent rehearsals, reviewed actions, inbox behavior and handoff. General Seedly documentation is not automatically ingested. Paste the approved text and optionally link its HTTPS source. Links are references, not a website crawler. Maximum 20 articles, 4,000 characters per article and 40,000 characters total. Never store credentials or private customer records as shared support knowledge.
5. Choose diagnostics and CRM tools. The default CRM tool list is empty. Enable only what this support agent needs, up to 30 eligible operations. Every call also checks the requester's native resource permissions, account-wide scope, enabled features, Orbit write policy and CRM API scopes. Administratively privileged and arbitrary extension endpoints are excluded from this initial support release.
6. Add published support hours and the handoff message. Hours are informational and do not control a staffing schedule, routing or response-time SLA.
7. Save and test as a representative user. Open support from the floating Orbit launcher if enabled; existing companion/hidden preferences and floating access still apply. Seedly's native request form remains available.

Account overrides replace the complete configuration, rather than merging individual fields. Use agency defaults removes the local override. A locked agency configuration takes precedence over saved local overrides; unlocking restores those local configurations. Changes invalidate earlier support proposals, which must be requested again. Each account retains its own AI provider credentials and normal usage limits.

## Ask support

Orbit interprets the current request in context rather than treating every message as a support issue. Greetings and writing/brainstorming requests get direct answers; product how-to questions use relevant knowledge; reported Orbit problems can use diagnostics; CRM reads and proposed changes use the configured tools. It asks one focused question when the request is ambiguous. A conversation can move between these topics without the user selecting a mode. Intent guides model behavior; it does not change permissions, tool availability or handoff state.

These defaults live in `src/convex/seedlyOrbit/conversationGuidance.ts` and apply even to already-saved agency policies. Use the Instructions field for business-specific guidance, tone and escalation preferences, not a replacement for the base behavior. Ordinary Chat shares the conversational defaults but does not acquire Support's knowledge or diagnostics tools; it can suggest Support when those capabilities are needed. Scheduled agents keep their existing job instructions.

When changing prompts or models, test greetings, a writing request, product how-to, a specific failure, an ambiguous "it's broken", a CRM read, an explicit human request, and a change of topic within one conversation. Check the actual recorded tool calls as well as the answer: a plausible reply alone is not proof that routing or evidence is correct. Model intent recognition is probabilistic. The server continues enforcing the configured tool list and approval rules regardless of the model's interpretation.

The agent can search approved text and show retrieved sources under Activity & sources. Retrieval is bounded keyword ranking, not a claim that all relevant documentation was found. It can read verified Orbit configuration; permitted agency managers can inspect their own first 30 agents, including current status, rehearsal, schedule, conditions and trigger notes. It does not test external provider health or CRM connectivity merely by reading configuration, and it does not inspect another user's agents.

Privileged diagnostic evidence marks the conversation as requiring agency-manager/settings-update access. Losing that access blocks later reads of its messages. Configured CRM reads likewise retain Orbit's existing operation-based history checks. A support chat remains owned by its requester; configuration management does not grant staff access to private chats.

Allowed writes generate the existing immutable review card. Support cannot execute a CRM write without the requester's explicit approval. Before/after previews apply to supported update/get pairs, and approval rechecks the current support configuration revision. Do not automatically retry failed or ambiguous external writes.

## Talk to a person

Talk to a person prepares an editable draft from up to 12 recent messages and 20 action records, separating source references, actual action status and clearly labeled AI advice. The user reviews the summary and the actual native destination before submitting. Only that summary, plus native requester and source-account details, is shared; raw tool results and the complete transcript are not silently attached. Common secret patterns are redacted before the final preview, but users must still inspect the text for sensitive information.

The handoff calls Seedly's existing `pmSubmissions.createFeedback` in the same database transaction. Native routing sends the request to the source account's brand-admin subaccount when one exists, otherwise to the source account. Orbit does not accept arbitrary target account IDs or alternate notification recipients. The browser's native active subaccount must match the conversation's account; if it changed, select the correct account in the CRM switcher and review again. An inactive destination refuses submission.

The existing native function resolves/creates the requester contact, creates the request, writes its audit entry and schedules notifications to the native support members. Orbit stores the returned submission reference. Repeated submission of the same conversation returns that same reference rather than creating duplicate requests. A changed destination requires a fresh review.

Successful handoff cancels a running AI reply and rejects recent pending proposals. All further AI replies and approvals in that conversation are blocked on the server, including older proposals. An already-running CRM action must finish before handoff is allowed. Delayed provider replies cannot be appended after cancellation. The conversation stays available for the requester to read, subject to current permissions.

## My requests and human workflow

My requests lists support conversations among the latest 200 conversations owned by the requester in the current account, with a truncation notice. It reads only the native intake status of the stored submission; it does not expose support staff notes or other submissions.

- Awaiting support review: native status `pending`.
- Accepted by support: native status `approved`; this is not proof of resolution.
- Declined by support: native status `rejected`.
- Request unavailable: the referenced native request is missing or no longer in its recorded destination.

Staff handle these in Seedly's existing Tasks → Submissions workflow and follow up through their normal support process. Version 1.6 adds customer-reported call resolution/feedback and bounded quality aggregates, described in LIVE_SUPPORT.md. It does not add bidirectional human chat, staff assignment, internal notes or SLA automation. Those require a dedicated shared support conversation model and explicit support-role permissions. Do not reuse requester-owned Orbit threads to give support staff blanket CRM authority.

## Installation and upgrades for an AI agent

1. Read AGENT_INSTALL.md and IMPLEMENTATION_CONTRACT.md. Back up the existing installation and inspect module conflicts before applying changes. Do not copy licensed host source or credentials into a distributed package.
2. Install the original module with `node bin/install.mjs --seedly /absolute/path/to/seedly --apply`. Run doctor.
3. Confirm the new private `soSupportPolicies` table and its `by_subAccount` tenant index are in the schema/extension privacy registry. Agency configuration is unique by agency/scope; account configuration is unique by account/scope. Agency defaults are anchored to the account where they were first saved for native tenant-purge compatibility. Export/re-establish those defaults before deleting that anchor account; deleting it removes the default policy and inherited support fails closed to disabled.
4. Optional thread fields record support mode, handoff reference, destination, summary/time and restricted diagnostic evidence. Optional action revisions protect support approvals. Existing ordinary chats are unchanged. No backfill or new environment variable is required.
5. Generate fresh Convex bindings and run backend types, installed-host Orbit tests, extension privacy/purge checks, frontend types and build. Test the native feedback function contract in the actual licensed host. Current verified reference is 5.8.4; do not assert compatibility with an untested modified fork.
6. Deploy backend/schema before the UI. The native feedback route must remain authenticated and must resolve brand-admin routing server-side. Never bypass `getAuthContext`, `location`, `thread` or permission checks to make a handoff work.
7. Configure support and test documentation, forbidden tools, an allowed reviewed proposal and a handoff in synthetic accounts. Test both no-brand fallback and brand-admin routing, duplicate clicks, routing changes, revoked permissions and in-flight cancellation. Native notifications may trigger external delivery according to host configuration; use fixtures or explicitly approved recipients for delivery testing.
8. Verify account and agency overrides, disabled support, unavailable provider, closed-browser persistence and floating entry behavior. Keep a native request fallback available while testing.

## Adding support tools

Use the existing catalog/permission/REST adapter for CRM operations and enforce the support allowlist in context, tool registration, proposal creation and approval. New diagnostic tools must return only necessary fields and register any extra history permission requirement before persisting privileged evidence. Keep actual receipts separate from model prose. Read source permissions on every call, including multi-round model loops.

Curated content and CRM records are untrusted model inputs. Never turn article text into executable predicates, system access, URL fetches, recipient overrides or approval. Adding automatic URL ingestion requires a separate SSRF-safe fetcher, publication controls, content/version metadata and test coverage; it is not implemented by accepting a source link.

Support state and configuration belong in original module files. If a newer host provides a true support-ticket/conversation API, write a tested adapter rather than inventing compatibility. Preserve native routing, idempotency, consent preview, principal checks and the AI-stop boundary. Share external messages only after the user submits the reviewed request.


---

# Guided agents

Available in Orbit 0.2.0-alpha.1. Open Orbit → Agents as an agency owner or administrator. Agents belong to their creator within one subaccount. They use that account’s configured AI provider and CRM key, bounded by the creator’s current native permissions.

## Start a job

1. Choose a briefing, contact review, follow-up template, or write your own job.
2. Specify the relevant records, exclusions and desired output. Choose only the necessary tools. Read tools retrieve data; change tools prepare proposals for approval.
3. Choose on-demand, daily, weekdays, weekly, monthly or a CRM event, with a local time and IANA timezone for schedules. Set records processed per run (1–100) and runs per UTC day (1–24). Rehearsals count toward usage.
4. Review the rules and select **Save & rehearse**. This performs real reads and consumes provider credits. Rehearsal proposals cannot be applied.
5. Inspect the sources, visuals and proposed actions. Save feedback. Use **Edit instructions** to turn feedback into a lasting rule; feedback never changes the rules automatically.
6. Accept a successful rehearsal of the current revision, then enable the agent. Enabled manual agents expose **Run now**. Scheduled agents show their next run and continue with the browser closed.

Editing any configuration returns the agent to draft, cancels its schedule and requires a new accepted rehearsal. Pause stops future work; an already in-flight read may finish. Re-enabling a paused, previously reviewed revision resumes its schedule.

## Review and visibility

Each run stores an immutable copy of its instructions, model, tool list and record limit. Inspect its conversation for sources and server-calculated visualizations. The agent detail displays the most recent 30 runs, status, feedback and token usage. Failed schedules pause with a visible explanation. **Pause my agents** affects only your agents in this subaccount.

Live runs prepare changes for explicit approval in their run conversation. Agent proposals expire after the configured approval window (15 minutes to seven days; new agents default to one day, existing agents retain 15 minutes) and cannot be approved if the agent is paused, revised, or no longer allows the operation. Existing native permission and record-scope checks still apply. Rehearsals never offer executable approvals.

## Execution and limits

- Convex durable scheduled functions power schedules; there is no browser timer or customer cron service to configure.
- Daily and weekday schedules follow the specified timezone. A nonexistent daylight-saving wall time skips that date; repeated times run once. Missed jobs are not backfilled.
- Each agent permits one active job. Duplicate schedule callbacks are ignored. Interrupted jobs expire after three minutes and are not automatically replayed.
- Each run permits at most six model rounds, twelve tool calls and 2,500 output tokens per round, plus the account’s existing usage limits. Provider pricing varies; these are usage bounds, not a dollar budget.
- The record limit bounds records processed and sent to the model. Some API endpoints may return larger pages before truncation. Results identify partial data; do not treat limited samples as complete account analytics.
- Scheduled work re-resolves the creator’s current native authorization on every tool step. Deactivation, revoked membership, disabled Orbit, policy changes and tool restrictions block continued access. The saved principal is internal; no session token or user-selectable identity is used.
- Changing the account AI provider requires editing and rehearsing the agent again.

## Installation and upgrade verification

Follow INSTALLATION.md and AGENT_INSTALL.md. The installer adds private `soAgents` and `soAgentJobs` tables and an optional job link to Orbit threads, plus the native private-data registry contributions. Re-run the installer rather than manually replacing files. Run fresh Convex codegen, backend and frontend type checks, the supplied host test file and the frontend build before deploying.

Deploy the backend before serving the new frontend. No new secret or external cron is required; existing provider encryption and CRM setup remain required. Start with a read-only contact review, confirm that enablement is blocked before accepting the rehearsal, inspect source records, then enable on-demand and run once. Test pause and changed permissions with synthetic data. Do not enable a recurring schedule merely to complete installation.

## Extending safely

New tools must follow EXTENDING_API_WITH_AI.md and TOOL_RECIPES.md: native route authorization, validated arguments, catalog metadata, bounded result envelopes, private-table registration where applicable, and scoped tests. Agents select eligible catalog tools; arbitrary URLs and administrative/extension routes are excluded in this first release. Updating a tool must preserve its permission checks and read-versus-change classification. Never bypass the proposal/approval path to make a scheduled write automatic.

This release supports guided setup, rehearsals, manual runs and daily/weekday/weekly/monthly schedules and native contact event triggers. Arbitrary cron expressions, automatic writes, cross-account jobs, email notifications, automatic learning and a dollar-spend budget are not implemented.

## Weekly and monthly timing

Weekly jobs use the selected weekday. Monthly jobs use the selected day of month, clamped to the last day for shorter months (31 becomes February 28 or 29). Times follow the configured IANA timezone. A nonexistent daylight-saving time skips that occurrence. Editing the cadence or approval window changes the agent revision and requires a new rehearsal and acceptance before enabling.

Approval duration is snapshotted when a job is queued. A longer window does not bypass permission, agent status, revision or operation checks when applying a proposal. Regular interactive chat proposals retain their 15-minute window.

## Event-triggered agents

Choose Contact created, Contact updated or Tag added. Orbit receives these through the installed native workflow trigger bridge, even when no matching workflow exists. No public webhook URL or event secret is exposed. The triggering contact ID is included as context; the agent must read the current record through its allowed tools. Trigger text never replaces the job instructions.

Activation still requires an accepted rehearsal. Saved owner permissions are rechecked before queuing and before tool calls. Each agent has one active run, a daily run cap, and a 5–1,440 minute cooldown (15 minutes by default). Events during a run or cooldown are coalesced, not queued for replay; the detail view reports this count. Duplicate event IDs are refused using stored job history; without an external ID, contact revision is used. Nested native trigger chains are skipped. Pausing stops new event jobs. CRM changes always require a person to approve them.

Only the three listed native event types are supported in v1. Existing contacts do not automatically trigger a backfill. Use a manual rehearsal or scheduled job to review existing data.

## Review inbox and reusable jobs

Agents shows your recent unexpired proposals with links to their original conversations. Approval still uses the existing immutable proposal and current permissions. Rehearsal proposals and paused or revised agent proposals are excluded. The inbox scans the latest 500 account proposals and displays up to 50 of yours; it discloses truncation.

Duplicate copies a job into a draft owned by the same user. It carries no accepted rehearsal, active job or schedule. Search agents by name/instructions and filter by status. The tool picker is collapsed by default and searchable.

## Lifecycle report

The Lifecycle report template uses `countContactsByLifecycle`. Grant the dedicated `orbit:contacts:read` scope to the configured CRM key. It counts stored lifecycle stages on active, non-deleted contacts; it does not infer stages from deals or invoices. This aggregate can scan more contacts than the agent's returned-record limit, because only six stage totals enter the AI context.

The endpoint scans before applying its optional source filter. It processes at most 40 pages of 250 records and eight seconds between page requests. A budget-limited scan returns `hasMore: true` and no full total. Data can change during a multi-page scan; start and finish timestamps are returned. This is not an atomic analytics snapshot. Visualizations sum the count field automatically, rather than counting the stage rows.

## Design an agent in chat

Choose New agent → Describe a job, or ask Orbit directly to build an agent. Explain the job, exclusions, desired trigger and timezone for timed schedules. Orbit can ask follow-up questions and return a draft card. Review agent setup transfers that draft into the existing editable rules and rehearsal flow. Nothing is saved, scheduled or enabled by the chat tool. The tool is restricted to agency managers, validates eligible tool IDs and bounded schedule/usage settings, and cannot be called by a running agent. Saving still enforces current permissions; enabling still requires an accepted rehearsal of the current revision.

## Review exact changes

Contact, task and opportunity updates can display current and proposed values side by side. Current values come from a separate authenticated read, never model-generated prose. An agent must have the matching get operation in its approved tools and remaining record allowance; otherwise current values show as unavailable. Create proposals show the fields for a new record. Other operations retain exact API request details.

Before applying a proposal with verified current fields, Orbit reads again. A changed value or failed verification prevents the write and requires a fresh proposal. This is not an atomic conditional update: a concurrent change can still occur between the verification and native REST write. Fields unavailable in the read are explicitly unverified. Approval, rejection and expiry remain immutable single-use actions. In ordinary chat, Request changes rejects the old proposal and prepares a follow-up message for your edits; it does not send it automatically. Agent-run proposals use the agent instructions/rehearsal workflow for lasting changes.

## Event conditions

In agent rules, choose an event and expand Event conditions. Require all listed tags, exclude any listed tag, and choose any allowed lifecycle stage. Tags are exact, case-sensitive names; comma-separated entry supports up to 20 required and 20 excluded names, 80 characters each. A tag cannot be both required and excluded. Empty lists impose no restriction. Conditions combine with AND: all required tags, zero excluded tags, and any selected stage.

The native event handler reads the active contact in the event's own subaccount, checks current owner/contact-read authority, and evaluates these rules before queuing or using AI credits. Nonmatches appear in Last trigger as skipped. Saved conditions are snapshotted on each queued job; editing conditions creates a new draft revision requiring rehearsal. These are conditions on the current record, not proof of which field or tag changed. Tag added means the native tag-added event occurred and the current contact matches; it does not claim the required tag was the one added. Changed-field filters need a verified host before/after event contract and are not supported. Conditions govern when the job runs, not the scope of every later tool read; describe the triggering-contact scope in the job instructions and choose appropriate tools.

## Agent notifications

Orbit's Inbox is available to agency managers for their own runs in the current subaccount. Failed runs and actionable approvals are unread automatically. Results without pending changes remain available under All recent results but are quiet by default. Enable “Notify me when routine results are ready” in agent rules to make those results unread too; this preference is snapshotted per run and follows the existing revision/rehearsal flow.

Opening an inbox item marks its current state read and opens the original run conversation. You can also mark it read without opening. Reading never approves, rejects or retries a CRM action. An unexpired approval resurfaces once as it enters the final hour; expiry attention updates within approximately one minute while Orbit is open. Resolved/expired proposals, rehearsal proposals and proposals belonging to paused or revised agents do not show as actionable pending approvals. Normal approval authority is checked again when a user applies a change.

The inbox derives its state from the latest 100 owner/account jobs and their stored actions, discloses truncation, and preserves read state on each job. It covers existing runs as well as new runs without a backfill. This is an in-Orbit inbox and unread indicator, not OS push, email, SMS or a native Seedly bell integration. No outbound delivery service or new credentials are needed. A closed browser does not stop agent execution; notifications are visible when Orbit is reopened.

### Install and extend

Deploy the updated optional schema fields, owner/account jobs index and backend functions before deploying the matching UI. Install with the module installer, generate Convex bindings, run host tests and deploy the dedicated target. No data migration or new environment variable is needed. Older agents default to no conditions and quiet successes. Keep `agentConditions.js` shared by draft validation, saved agent validation and event handling. New conditions must have bounded validators, server-verified tenant data, job snapshots, rehearsal invalidation and tests for nonmatches and revoked access. Never evaluate arbitrary model-generated predicates or accept a caller's record snapshot as trusted event data.


---

# Using Orbit

Orbit is a staff tool inside your Seedly CRM. It can read authorized CRM data, build inline tables/charts, and propose actions you review before execution. It uses your connected AI provider and your installation's CRM API.

## A normal conversation

Choose the right subaccount, start a conversation, and ask one concrete question. Specify date range, timezone and whether you need a sample or a complete report. Review source disclosures and pagination limits before treating a chart as an account total. Continue in the same conversation when following up; start a new one for a different task.

An AI reply is not evidence that a write completed. Orbit creates a review card with the actual operation, account and fields. Approve or dismiss it. Approval expires after 15 minutes and execution rechecks permissions. After a timeout or unknown result, inspect the native CRM before proposing the action again. API acceptance of an email or campaign is not delivery confirmation.

## Workspace and floating chat

The full workspace contains conversations, saved prompts, capabilities and settings. The floating popup has one header: history, new conversation, expand and close. Open history to reach secondary tools; expand for account switching and conversation management. Rename, pin and archive are in the full workspace. Archive is reversible; conversations are private to their creator.

Move the closed launcher by dragging or with arrow keys. Escape closes the popup. Settings offers the standard bubble, pixel companions, a custom PNG/JPEG/WebP upload or Hidden. Uploads remain on that browser for that user/location; they do not go to the AI. The agency's Floating chat switch takes precedence.

## Account settings

Agency owners/admins with settings permission configure location enablement, agency access, floating chat, reviewed writes, provider/model, daily turn allowance and approved extension routes. A staff user's native CRM permissions still apply even if the backend API key has broader scopes. Account-wide resource access is currently required; own/team scopes are refused.

Connect OpenRouter, select a tool-capable model and Save settings. The daily allowance counts turns, not dollars. Use provider-side spending limits. Key verification checks the credential without making an inference request; a real reply is needed to confirm credits and model access.

Appearance can follow the account's brand tokens, use Clear light or Clear dark, or set custom background/accent colors. Changes apply to the workspace and popup for that subaccount. Launcher choice and position are personal browser preferences.

## Data and limits

Selected CRM results and bounded conversation history are sent to the chosen provider. Keys stay server-side and saved OpenRouter keys are encrypted per location. Do not put credentials in a chat or a tool description. Retrieved CRM text is data, not authorization to run instructions contained in a note or message.

Orbit does not provide arbitrary database, shell, URL or browser execution. The installed catalog defines supported operations. A CRM screen does not prove there is an API for it. Generic extension calls are manager-only, require an exact allowlist and live granted discovery. New integrations need implementation and testing.

Replies appear when a bounded run completes; token streaming is not implemented. Search covers loaded conversation titles; load older chats to include more. Charts describe retrieved data unless a verified reporting endpoint returns complete aggregates. Provider/tool availability and charges depend on your configured account. See Validation for the evidence and limits of this release.


## Guided agents (0.2.0-alpha.1)

See [Guided agents](AGENTS.md) for setup, rehearsals, schedules, review, limits and upgrade verification. Deploy the new backend before the frontend. Existing conversations remain available; the upgrade adds two private tables and does not enable any scheduled job automatically.


---

# Install Orbit in your Seedly CRM

This guide is for the customer who owns and deploys the CRM. Orbit installs original add-on code into a separately licensed Seedly checkout. It does not include a hosted AI service or provider credits.

## Prerequisites

- Seedly 5.8.4, extension API 1. Later 5.8.x versions need integration verification.
- Node 22+, existing host dependencies, access to the intended Convex development deployment and web hosting.
- An OpenRouter inference API key with credits and access to a tool-capable model. Existing direct OpenAI connections remain supported.
- A CRM API key created through the native Settings → Integrations → API Keys screen. Use an agency-scoped key for agency management, with authorized-subaccount restrictions where appropriate. Select only the scopes needed by your users.
- A backup and a clean reviewable source checkpoint. Keep credentials out of Git and archives.

## 1. Install and inspect the changes

From the extracted module folder:

```sh
node bin/install.mjs --seedly /absolute/path/to/seedly
node bin/install.mjs --seedly /absolute/path/to/seedly --apply
node bin/doctor.mjs --seedly /absolute/path/to/seedly
```

The first command is a dry run. The installer writes module-owned source, private-table registration, native permission and plan-feature entries, navigation, and a narrow dashboard floating-chat contribution. It records file checksums in `.seedly-addons/orbit/receipt.json`. Customer edits cause a refusal rather than an overwrite.

The dashboard contribution wraps the existing CommandPalette with the optional Orbit launcher. Other modules remain independently installable. No deployment, role enablement, API key creation, provider call, or CRM write occurs during installation.

## 2. Configure server-only connections

Set these variables through the intended Convex deployment's environment settings. Do not use `NEXT_PUBLIC_` names.

| Variable | Meaning |
|---|---|
| `ORBIT_KEY_ENCRYPTION_SECRET` | Deployment-owned 32-byte random secret encoded as 64 hex characters; required to encrypt connected OpenRouter keys |
| `ORBIT_OPENAI_API_KEY` | Optional existing direct OpenAI connection, only used when OpenAI is selected |
| `ORBIT_CRM_KEYS` | JSON object mapping an internal agency ID or internal subaccount ID to its native CRM API key |
| `CONVEX_SITE_URL` | Platform-provided URL of this backend; Orbit accepts only this installation's `https://…convex.site` origin |

Example **with placeholders only**:

```json
{
  "AGENCY_INTERNAL_ID": "sk_agency_test_REPLACE_IN_SECRET_SETTINGS",
  "SUBACCOUNT_INTERNAL_ID": "sk_test_REPLACE_IN_SECRET_SETTINGS"
}
```

A per-subaccount entry takes precedence over its agency entry. Orbit verifies the key's agency and resolved subaccount against the authenticated user's target before calling the API. An incorrectly mapped key is refused. An agency key's `X-Sub-Account-Id` is injected by the server, never by the model or browser.

Native API scope names and the supported operation list are in [API_COVERAGE.md](API_COVERAGE.md). API scopes do not replace the user's native role. Orbit currently requires account-wide permission for a tool's resource; own/team scope is refused. Test keys sandbox external messaging but are not a guarantee that every CRM mutation is a dry run. Use a dedicated test location with synthetic records.

Orbit uses `store:false` for model requests. Selected CRM data and the bounded conversation history are sent to the customer's selected AI provider account to answer the user's question. Review your provider settings and data requirements before enabling the feature. Do not put secrets in prompts.

## 3. Generate and validate in a private development host

Use the target host's documented deployment configuration; never copy another customer's `.env` or deploy a disposable scratch host.

```sh
# From the actual customer host, with the correct development deployment selected:
npx convex codegen
npx tsc --noEmit -p convex/tsconfig.json
# From apps/web:
npx tsc --noEmit
npm run build
```

Copy `host-tests/seedly-orbit.test.ts` into the private host's `convex/__tests__/` and run its focused test command from `convex/`:

```sh
pnpm exec vitest run __tests__/seedly-orbit.test.ts
```

Run the host's extension permission, navigation, private-table/snapshot and purge guards as well. Fresh authenticated component codegen is required before release; a local API-reference regeneration does not establish deployment compatibility.

Deploy Convex schema/functions before deploying the corresponding web app. Follow your customer's existing production workflow. Orbit's installer deliberately does not choose a backend or hosting project for you.

## 4. Enable per location

1. Open `/orbit` as an agency owner/administrator and select a subaccount, or open `/location/LOCATION_PUBLIC_ID/orbit`.
2. In Settings, enable Orbit. Enable Agency access if agency users should manage that location. Enable Floating chat to show the launcher inside its dashboard.
3. In Connect OpenRouter, paste a regular inference key and select Verify & connect. The server checks GET /key and encrypts it for this location; it never returns the key. Select OpenRouter below, choose a tool-capable model ID (default `openai/gpt-5.4-mini`) and Save settings. Verification does not spend inference credits; a real reply is still required to verify model/tool access. Existing direct OpenAI locations retain their provider until changed.
4. Set a daily reply allowance per user/location. This is a turn limit, not a monetary guarantee. Provider requests are further bounded by output tokens, iterations and tool calls; use provider-side spend limits too.
5. Assign Orbit and the required CRM resource permissions to intended roles, and include Orbit in applicable plan features.
6. Leave reviewed writes off for the first read verification; enable them after validating the desired operations.

Settings are independent for each location. Cross-account comparisons are currently separate conversations, not a silently mixed dataset. The account selector opens the selected location's workspace.

## 5. Verify the real connection

- Ask for a small contact list in an authorized synthetic location. Verify the IDs against the CRM.
- Ask for an inline table and a count. Check source disclosure and partial-page labels.
- Try a restricted user; confirm a forbidden resource stays forbidden even if the backend key has the scope.
- Create a task proposal. Confirm no record exists until approval, then approve once and verify exactly one task.
- Revoke the API key or role and confirm subsequent operations fail.
- Test agency access disabled/enabled separately and verify the selected account on each action card.
- Open/close/move the floating launcher, change conversations, and reload.
- Do not test actual customer messaging, broadcasts or destructive operations without authorization for the exact test.

## Operation and recovery

A write approval expires after 15 minutes. The stored arguments are immutable. Newly created/rotated webhook signing secrets are returned once to the approving manager’s browser, never to the model or persisted chat. Copy them to the receiving service immediately; leaving the conversation loses that one-time display. Duplicate approval is refused. HTTP acceptance of a message/campaign is not proof of delivery; inspect native CRM state. For an unknown write outcome, check the CRM before issuing a new proposal. Do not blindly retry a send after a timeout.

Conversation history is private to its creator. Archive is reversible. Saved prompts can be deleted. Module data follows the host subaccount purge mechanism; no public tokens or durable media are created by Orbit. Configure retention through your own approved host data lifecycle; Orbit does not automatically purge chat history.

For an interrupted source installation, use `bin/recover.mjs --seedly /path --apply`. For removal, preview `node bin/uninstall.mjs --seedly /path`, then add `--apply`. Removal preserves database records; decide on retention/export before removing their schema in a deployment.

## Limits of this alpha

- No live customer/provider certification is implied by the included fixtures or synthetic UI preview.
- Responses appear after each bounded reply completes; token-by-token streaming is not implemented.
- Search filters loaded conversation titles; load more pages to include older chats.
- Charts aggregate retrieved rows only; larger analyses require paging and/or purpose-built reporting endpoints.
- Extension discovery describes paths/scopes, not complete request schemas. Register reviewed typed endpoints for routine staff use; the generic gateway remains agency-manager-only and explicitly allowlisted.
- Public widget/form APIs and signed workflow ingress have different authorization contracts and are not exposed as arbitrary management tools.

## OpenRouter credential operations

Generate the encryption secret with a cryptographically secure generator (for example, `openssl rand -hex 32`) and save it directly in the intended backend's secret configuration. Never commit its output. The key form stays unavailable until that secret is configured. CRM keys and this wrapping secret must not have `NEXT_PUBLIC_` prefixes.

Connected OpenRouter keys are scoped to the selected subaccount. An agency manager may use the same agency-owned provider key in several subaccounts, or separate keys to isolate provider spending limits. Orbit does not silently inherit provider keys between tenants. Only an agency owner/admin with native settings-update permission can connect, replace or disconnect a key. Staff see connection status, never the key or ciphertext; managers see only its last four characters. No key is written to browser local/session storage or chat. Backend administrators with deployment access remain trusted; encryption does not protect against a compromised backend. Do not log action arguments or request headers.

Replacing a key verifies the new key before atomically replacing the previous ciphertext. Disconnect removes the saved secret and prevents later replies; it does not revoke the key at OpenRouter. Revoke it in OpenRouter when needed. Keep the encryption secret stable and backed up in your secret manager. Changing it without migrating credentials makes existing keys unreadable; reconnect every affected subaccount after rotation. A disconnection cannot recall an already in-flight provider request.

The Responses tool loop uses OpenRouter's documented client tool calling. Orbit still performs permission checks and requires explicit approval for writes. Select models/providers that support function tools; invalid models, exhausted credits, unsupported parameters and revoked keys surface as failed runs rather than silently switching providers.

References: [Responses tool calling](https://openrouter.ai/docs/api_reference/responses/tool-calling), [key verification](https://openrouter.ai/docs/api/api-reference/api-keys/get-current-api-key), [create/manage keys](https://openrouter.ai/settings/keys).

## Optional pixel companions

Settings → Chat launcher offers Classic, Miso (cat), Pip (frog), Byte (robot), and Hidden. Users can change this without agency settings permission. It is remembered on this browser for this user and location. Hidden removes the launcher; the full Orbit workspace remains available. Agency floating-chat disablement overrides the personal choice. Pets use the same drag, keyboard movement, open and close behavior as the bubble.

## Launcher images and model selection (alpha.3)

The launcher picker adds Ember (fox), Hoot (owl), and Boo (ghost). Upload a PNG, JPEG or WebP up to 2 MB and 16 megapixels to use your own image. Orbit fits it into a transparent 96×96 PNG without cropping and stores it in local browser storage for the signed-in user/location. No image leaves the browser, enters the model context, or consumes Convex file storage. Choose another launcher to keep the uploaded image for later; Remove image deletes the browser copy and restores Classic if Custom was selected. Custom launchers do not sync across devices. SVG and animated formats are not accepted. Browser storage restrictions are reported rather than silently claiming a save.

OpenRouter's model dropdown refreshes the public model catalog when an agency manager opens settings and offers a Refresh control. It lists text-output models advertising tool support; batch-only entries and unrecognized identifiers are excluded. Search filters by model name/ID. Featured recent choices include GPT-6 Sol/Luna/Astra, Claude Opus 5.5/Sonnet 5, Gemini 3.8 Flash, Grok 4.7, DeepSeek V4.1 Flash and GLM 5.3 Prime, verified against https://openrouter.ai/api/v1/models on September 27, 2026. “Featured” is a shortlist, not an independent quality benchmark. Other supported models sort newest first by OpenRouter creation timestamp. Advertised input/output prices are per million tokens, not a per-task quote; provider costs and availability can change.

The catalog request contains no CRM records or provider credentials and requires native agency-management authorization. If discovery fails, a dated bundled list remains usable and is labeled as a fallback. The saved model is retained even if absent from a filtered/current list; opening the selector never silently changes it. Save settings applies a selected model. OpenRouter key/model access still needs real-account verification. Direct OpenAI retains its existing explicit model-ID field.

## Seedly 5.8.4 task API compatibility

On a clean base, the first POST /api/v1/tasks can return 500 because pm.apiCreate creates the API Tasks project with an empty createdBy user ID. Before testing task creation, the host maintainer should carry the authenticated API key record’s createdBy through both ApiAuthContext builders in convex/apiHelpers.ts, and pass that trusted value as createdBy in the POST task handler’s internal.pm.apiCreate call in convex/http.ts. Keep request-body createdBy blocked. Verify the first task creates a valid project and task, retains tenant checks, and returns 201. This is a host compatibility fix; the Orbit installer does not overwrite these core files. The isolated September 28 test host includes it.

### Orbit appearance
Agency owners and administrators can open Orbit → Settings → Appearance and choose Use account brand (default), Clear light, Clear dark, or Custom colors. Brand mode inherits the CRM's current background, foreground, muted, border, primary and primary-foreground design tokens, including light/dark changes. Custom mode offers background and accent colors with automatic contrasting text. Preview changes, then Save settings. Appearance is stored per subaccount and applies to both the full workspace and floating chat for its users. Launcher character and position remain personal browser preferences.


## Guided agents (0.2.0-alpha.1)

See [Guided agents](AGENTS.md) for setup, rehearsals, schedules, review, limits and upgrade verification. Deploy the new backend before the frontend. Existing conversations remain available; the upgrade adds two private tables and does not enable any scheduled job automatically.

## Orbit v1 host integrations

The installer contributes a reversible native workflow-trigger bridge and a scoped read endpoint at `GET /api/v1/ext/orbit/contacts/counts`. Grant `orbit:contacts:read` on the CRM API key to use lifecycle reports. Discovery must report this route as granted; the AI cannot override the key's scope.

The installer also carries the authenticated API key creator into task creation on supported hosts. An existing equivalent creator fix is preserved. It adds `tasks:create` as a create-only scope for `POST /api/v1/tasks`; update, completion and deletion still require `tasks:write`. Existing `tasks:write` keys continue working. This is an Orbit compatibility contribution, not a claim that unmodified Seedly ships this scope.

Run the preflight on modified forks. Unrecognized host anchors stop installation before writes. Reconcile the native trigger, task route and key-auth changes explicitly rather than forcing installation. Native source is never distributed in the module archive.

After installation, run `node bin/doctor.mjs --seedly /path/to/seedly`, Convex codegen, host tests, backend/web typechecks and the web build before deploying. Rehearse every agent after edits. See AGENTS.md for event delivery, coalescing and count scan limits.


---

# Agent installation runbook

Use this runbook from the extracted Orbit package. It installs original module source into a separately licensed Seedly host. Never infer permission to deploy to another customer or shared backend.

## Required handoff

Record these non-secret inputs before edits: absolute host path; host version and source commit; Orbit version from module.json; development Convex deployment name; web project and local port; test agency and location public ID; matching internal agency/subaccount IDs; release owner; intended permissions; existing modules. Public location IDs belong in browser URLs; internal IDs belong in ORBIT_CRM_KEYS. Do not interchange them.

If a deployment target, host path, or required credential is missing, ask for that specific input. Continue source inspection while waiting. Never substitute an environment from a neighboring checkout. Never ask someone to paste credentials into an AI conversation.

## Copyable agent brief

```text
Install Orbit in HOST_PATH, targeting DEVELOPMENT_DEPLOYMENT only.
Read the host AGENTS.md, Orbit module.json, INSTALLATION.md,
IMPLEMENTATION_CONTRACT.md, API_COVERAGE.md and this runbook.
Inventory existing extensions and uncommitted work. Preserve both.
Verify the package checksum manifest and use a clean source checkpoint.
Run the dry-run installer, inspect its changes, then apply and run doctor.
Do not use --verify: the Orbit installer does not support that flag.
Configure secrets through the deployment's secret store, never frontend env,
Git, logs, chat, generated docs, or command arguments containing literal keys.
Generate the real installed Convex API; run backend/web types, Orbit host
fixtures, extension guards and the web build. Do not treat mocked tests as
live AI verification. Deploy only to the named authorized development target,
backend before frontend. Configure one synthetic location, start read-only,
verify provider replies and CRM reads, then one approved synthetic write.
Report exact commands, exit status, source changes, target identity,
tests passed/blocked, rollback checkpoint and remaining limitations.
Production deployment requires the customer's established release authorization.
```

## Checkpoint 1: verify and inspect

Verify the archive SHA-256 against archiveSha256 in its adjacent manifest before extraction. On macOS use `shasum -a 256 ARCHIVE.tar.gz`; on Linux use `sha256sum ARCHIVE.tar.gz`. Compare with a manifest received through the trusted delivery channel. A matching hash detects corruption; it does not authenticate an untrusted publisher. Extract to a new directory and compare extracted file hashes with the manifest's files map. Do not extract over the host.

Confirm Node 22+ and the host's locked package manager/dependencies. Orbit targets Seedly 5.8.4 / extension API 1; the declared 5.8.x range is not certification of every later host. Read version-specific host source and integration seams. Check `git status --short` and record a rollback commit or backup. Do not discard another developer's changes.

From the extracted package:

```sh
node bin/install.mjs --seedly /absolute/path/to/seedly
node bin/install.mjs --seedly /absolute/path/to/seedly --apply
node bin/doctor.mjs --seedly /absolute/path/to/seedly
```

Expected: dry run lists planned files; apply reports local installation; doctor reports matching source/contributions/receipt. A customization refusal is a stop condition: compare the customer diff and integrate deliberately, never delete the receipt to force an overwrite. Keep .seedly-addons/orbit/receipt.json and recovery journal with the host backup.

## Checkpoint 2: connect without leaking secrets

Use the intended Convex dashboard's environment settings. ORBIT_KEY_ENCRYPTION_SECRET is 32 random bytes as 64 hex characters, stable across restarts; ORBIT_CRM_KEYS maps internal IDs to native API keys. CONVEX_SITE_URL must be the same backend's platform-provided site origin. Keep the encryption secret backed up in a secret manager. Do not print secret values during verification.

Verify deployment identity and frontend NEXT_PUBLIC_CONVEX_URL agree. The public URL is configuration, not a provider key. No CRM key, inference key, or wrapping secret may be exposed through NEXT_PUBLIC variables. Scope the CRM key to the synthetic account and minimum operations. A test key does not make all database writes dry runs.

Connect an OpenRouter key in Orbit Settings after deployment; credentials are encrypted per location. Key verification is not an inference test. Credits, model access and function tool support must still be confirmed with a real reply. Select the provider and model, then Save settings. Do not automatically switch to a different provider on failure.

## Checkpoint 3: validate installed source

From the licensed host root, using its locked pnpm installation:

```sh
pnpm exec convex codegen
pnpm exec tsc --noEmit -p convex/tsconfig.json
pnpm exec tsc --noEmit -p apps/web/tsconfig.json
pnpm --filter @seedly-crm/web build
```

Codegen must use the selected development deployment and installed modules. If the host needs a development push to generate component bindings, use its documented `convex dev --once` workflow only after checking the target. Never fabricate generated types or suppress errors to pass a gate.

Copy package host-tests/seedly-orbit.test.ts into host convex/__tests__/seedly-orbit.test.ts. From the host's convex directory:

```sh
pnpm exec vitest run __tests__/seedly-orbit.test.ts __tests__/subaccount-purge-index-coverage.test.ts __tests__/plans-schema-extensions.test.ts __tests__/extension-seam-no-dead-code.test.ts
```

If a newer host renamed a guard, identify and run its equivalent; record the difference. Do not silently skip checks. Fixture tests must use an isolated in-memory database. Do not run seed or purge routines against customer data. Build success confirms compilation, not provider or API access.

## Checkpoint 4: deploy and accept

Deploy schema/functions before web using the host's approved workflow. Confirm the actual deployment is ready and the browser is using that version. Enable Orbit, Floating chat and appropriate Agency access in one synthetic location; assign native Orbit/resource permissions and plan features. Keep writes disabled first.

Acceptance evidence must include: authenticated login; a real model reply; bounded contact read with matching native IDs; table/chart with source and partial-data labels; denied user and wrong-location request; conversation restoration after reload; launcher open/close/move; saved appearance; enabled writes producing a proposal before mutation; exactly one synthetic task after approval; duplicate approval refused. Read INSTALLATION.md's first-task compatibility note before testing clean Seedly 5.8.4.

Record separate statuses for source installed, backend deployed, frontend served, provider key verified, inference verified, CRM read verified and reviewed write verified. A missing key leaves inference blocked, not passed. Never claim all API endpoints were exercised because catalog metadata exists.

## Upgrade and rollback

Re-run the new package's dry run against the existing receipt, review the diff, apply, run doctor, regenerate APIs and repeat gates. Back up data before schema changes. Preserve old schema fields until backward compatibility and retention are reviewed. Never reinstall by deleting module-owned files manually.

For an interrupted installation, preview `node bin/recover.mjs --seedly /absolute/path/to/seedly`, inspect the plan, then add --apply. For removal, preview `node bin/uninstall.mjs --seedly /absolute/path/to/seedly`, then add --apply. Source removal preserves stored records; do not deploy a schema that discards them without a separate retention/export decision.

For a runtime regression, disable Orbit or reviewed writes for the affected location, investigate pending/unknown actions, and restore the previous compatible web/backend source checkpoint through the normal release process. Never roll back by deleting customer tables or replaying an unknown write. Reconcile native CRM state first.

## Handoff report template

```text
Orbit version / host commit:
Host path / named development deployment / web URL:
Receipt and source checkpoint:
Checks (exact command, exit status, evidence location):
Real provider / CRM read / reviewed-write results:
Synthetic records created and their IDs:
Known gaps and excluded operations:
Rollback source checkpoint and compatibility notes:
Next action and owner:
Secrets: stored in approved secret management; none attached.
```


## Guided agents (0.2.0-alpha.1)

See [Guided agents](AGENTS.md) for setup, rehearsals, schedules, review, limits and upgrade verification. Deploy the new backend before the frontend. Existing conversations remain available; the upgrade adds two private tables and does not enable any scheduled job automatically.


---

# Add CRM capabilities to Orbit with an AI coding agent

Use this document in your **own licensed Seedly source checkout**. It helps your coding agent add a missing capability without turning the model into a database administrator.

Primary reference: https://seedlycrm.com/docs/help/api. Review your installed source because your deployment changes only when you update it. The published reference explicitly says that some features, including campaign reads, are not exposed by the base REST API. Do not invent a URL because a corresponding CRM screen exists.

## Start from a concrete question

Examples:

- “Show unpaid invoices grouped by age.” Add a bounded invoice-aging read returning totals, currency, date boundaries and authorized invoice links.
- “Compare revenue across locations.” Add an agency-authorized reporting endpoint that explicitly returns account labels and never blends currencies.
- “Summarize project progress.” Return a minimal project/task projection with current resource permission checks.
- “Find contacts that have not been followed up.” Define what follow-up means, which channels count, and the time zone before writing the query.

Prefer a narrow reporting operation over returning every table to the model. Do not make the model calculate financial totals from a partial page.

## Copy this brief to your AI coding agent

> Work in this licensed Seedly checkout. Read AGENTS.md, convex/_generated/ai/guidelines.md, the native module's schema/auth/business functions, and Orbit's IMPLEMENTATION_CONTRACT.md and API_COVERAGE.md before editing. Implement the following capability: [business request]. First inventory existing endpoints and explain the data source, tenant/record permission, request fields, response fields, pagination, units and time zone. Reuse a supported existing endpoint when possible. Otherwise contribute a narrowly scoped authenticated endpoint through the installed extension API seam, with a typed request and minimal response. Do not add raw SQL, arbitrary table access, shell execution, arbitrary fetch, or model-supplied account IDs. Keep existing native side effects and invariants. Register the operation in Orbit with its exact method/path, schema, native permission resource/action and read/write classification. Add tests for wrong tenant, wrong user, missing scope, own/team scope, archived records, invalid inputs, pagination, duplicate writes, stale approvals and ambiguous provider outcomes. Run fresh Convex API generation, backend/web types, relevant host guards and a production build in the correct private development instance. Document changes and validation. Do not publish, send messages, create charges, or deploy to production unless my instructions authorize those actions.

## Implementation checklist

### 1. Inspect the existing contract

Read the current `docs/openapi.yaml`, `convex/http.ts`, `convex/apiHelpers.ts`, `convex/extensions/apiRoutes.ts`, `packages/shared/src/extensions-api-scopes.ts`, and `convex/extensionApiHost.ts`. Names and signatures can change across host versions: use your actual interfaces rather than copying an old route example blindly.

Check whether `GET /api/v1/ext` already exposes the capability. Its `granted` field indicates the key's scope, not whether every signed-in user should be able to use the endpoint through Orbit.

### 2. Design the operation

Write down:

- Exact HTTP method and path, unique operation ID, and whether it can cause side effects.
- Request JSON schema, required fields, enums, numeric limits and maximum lengths.
- Native resource permission (`deals`, not the REST resource name `opportunities`, for example), action and supported record scope.
- Tenant association for every referenced ID; how agency membership and any brand restriction are enforced.
- Response projection, currency/unit/time-zone semantics, cursor pagination and whether totals describe the full result set.
- External effects, confirmation/approval boundary, idempotency strategy, audit record and ambiguous-outcome handling.

A GET must be read-only. A side-effectful POST must always be classified as a reviewed write, even if its name contains “preview.” Only explicitly reviewed POST lookup contracts may be treated as reads (as with the existing verified-customer booking lookups).

### 3. Add the authenticated route

Use the extension namespace and scope seam available in your host. Do not overwrite the central extension dispatcher. Preserve its authentication, API-key expiry/revocation, rate limiting, response envelope and error containment.

Put atomic data changes in the backend transaction. Call native business helpers instead of patching arbitrary fields around validation, automations or audit. Return a minimal projection, not raw database documents. Never expose API keys, signing secrets, portal tokens, payment credentials, storage IDs, or unbounded free text.

If adding an original module table, register it as private, add its exact `by_subAccount` index, register account-purge cleanup and any file cleanup, and preserve tenant separation. Add explicit agency handling only if the business request requires it.

### 4. Register the Orbit tool

For a normal typed tool, add an `Operation` to the module catalog or maintain an additive catalog source beside the generated base list. Do not edit the generated file and then regenerate it without preserving your additions.

Example **metadata only** (implement and test the actual route first):

```ts
{
  id: 'invoiceAging',
  method: 'GET',
  path: '/api/v1/ext/myReporting/invoice-aging',
  title: 'Invoice aging',
  description: 'Read authorized unpaid invoice totals by aging bucket, currency and as-of date.',
  resource: 'invoices',
  action: 'view',
  read: true,
  admin: false,
  params: {
    path: { type: 'object', properties: {}, additionalProperties: false },
    query: {
      type: 'object',
      properties: { asOf: { type: 'string', format: 'date' } },
      required: ['asOf'],
      additionalProperties: false
    },
    body: { type: 'object', properties: {}, additionalProperties: false }
  }
}
```

Keep account context out of the tool arguments. Orbit supplies the approved location. The runtime must verify discovery/granted status for any `/api/v1/ext/` path, including a newly typed route, not just the generic gateway. Explicitly decide and test how the route allowlist and its own permission interact. Never remove that gate just to make a new tool work.

For a one-off manager-only integration, the existing generic extension gateway can call exact routes configured under Orbit Settings → Approved extension routes. Only enable endpoints you have reviewed. Discovery summaries do not contain full request schemas, so give the agent the endpoint's actual schema/documentation before asking it to call one.

### 5. Validate with synthetic records

Test both positive and refused requests against the actual host functions. Include at least two agencies, two locations, two users in one location, a revoked role/key, missing scopes, partial pages, malformed IDs, and records from another tenant. For writes, simulate a repeated approval and a timeout after the provider may have accepted the request. A timeout must not become a blind retry.

Verify chart totals against hand-calculated fixtures. Preserve the distinction between returned-record count and total matching count. A paged response must never render a complete-looking total without fetching all pages or using a verified aggregate endpoint.

### 6. Document and release

Update the API coverage table, customer setup/scopes, native permission mapping, validation record and rollback instructions. Generate the full installed Convex API again, run types/tests/build, and deploy backend before web through the customer's established release process. Record real request verification separately from mocked network fixtures.

## Good next extensions

Invoice aging and payment summaries; company records; projects; campaign reads and audience previews; workflow inspection; reporting aggregates; module-specific Events/Real Estate/Client Delivery lookups. Each is a distinct typed capability with its own authorization and evidence, not assumed base API coverage.

## Public endpoints are a separate integration

The public live-chat widget and form submission APIs are intended for visitor sessions, not staff CRM management. Signed workflow ingress needs a configured slug/secret and HMAC signing. If your use case needs either, add a dedicated adapter with server-owned session/signing context and tests. Never offer an arbitrary URL/header/body tool to bypass CRM permissions.

## Current implementation details an agent must preserve

The installed implementation is in convex/seedlyOrbit: core.ts owns Operation, prepare and bounded schema validation; catalog.ts is generated metadata; auth.ts handles native user/feature/record-scope checks; data.ts owns conversation access and proposal claims; runtime.ts owns same-origin requests, extension discovery and provider execution. The frontend renders approved visualization types, never executable model output.

Do not assume a schema `format` annotation validates dates or emails. The current core validator enforces types, bounds, required properties, enums and supported patterns; route handlers must independently validate semantic dates, timezones, tenant-bound IDs and native business rules. Treat both model arguments and discovery/CRM text as untrusted input.

For additive tools, move custom Operation definitions to a separate file and import them from a maintained catalog entrypoint used consistently by runtime, auth and data. Update the generator/import workflow so regeneration preserves additions. Reject duplicate IDs and method/path collisions in tests. Never append examples to the generated list and forget the generator. A custom ID must resolve consistently for current calls and historical conversation access checks.

The current allowlist accepts exact GET or POST extension entries, up to 50, and runtime checks the resolved path without its query string against live discovery. Dynamic path IDs therefore require exact resolved entries; a wildcard-looking string is not a wildcard. For simple reports prefer a fixed route with validated query arguments. Support for another method requires coordinated settings validation, runtime, catalog and tests, not a UI-only change.

Example allowlist entry, only after that recipe is implemented, deployed and granted:

```text
GET /api/v1/ext/myReporting/contact-completeness
```

Native API scopes are enforced by the host key; Orbit additionally checks the signed-in user's resource/action, feature and account-wide record scope. For custom extension operations, the same exact allowlist and discovery gates apply even when admin:false. Begin admin:true until staff permissions and revocation tests are reviewed. Endpoint authentication alone is insufficient to authorize a different Orbit user.

For write tools, require read:false, native action permission, current writes policy, immutable proposal fields and the existing claim/settle path. Use a server-derived idempotency identity bound to the claimed action if your endpoint supports it. Extend the adapter explicitly if needed; do not let model-supplied headers or an arbitrary retry flag choose that identity. One-time approval prevents duplicate execution attempts through Orbit, but cannot make an external provider transaction exactly-once after a timeout. Preserve unknown outcomes and reconcile externally.

## Stable custom catalog seam

Add original definitions in `src/convex/seedlyOrbit/customOperations.js`; `catalog.ts` composes them with generated upstream operations. Use the same operation shape and native permission checks. A catalog entry alone does not create a route or grant API access. Contribute routes and distinct scopes through the native registries; add host fixtures for wrong scope, foreign tenant, malformed input and partial results. Keep aggregate calculations server-side and flag incomplete coverage. Never accept a caller-selected agency or account in the query/body.

Orbit's lifecycle endpoint is a working example of a scoped aggregate. Do not copy its bounded scan and call it an unlimited or transactional snapshot. Add tests for a matching record beyond page one, deleted records, scope refusal and aggregate chart math.


---

# Useful starters and extension recipes

Start with saved prompts when existing tools already answer the question. A recipe below is a development brief, not a deployed endpoint or a permission grant. Adding text to an allowlist does not create a route.

## Use today: pipeline snapshot

Save this prompt: “List my open opportunities, group the retrieved records by stage, and show a bar chart. Include the number retrieved and whether more pages exist. Keep currencies separate.”

Uses existing opportunity reads and the built-in visualization tool. Requires native deals view permission with account-wide scope and the matching API scope. A retrieved sample is not a complete pipeline total.

## Use today: overdue task review

Save this prompt: “Find overdue, incomplete tasks. Show title, owner and due date as a table. State the time zone and any paging limits. Do not modify anything.”

Uses task reads. Check the installed API filters; page within supported limits instead of inventing an overdue route. Requires native tasks permission and matching key scope.

## Use today: reviewed follow-up task

Save this prompt: “Help me create one follow-up task for this contact. Confirm the contact ID, title, assignee and due date, then show the proposed change for my approval.”

Uses existing task creation and the write-review flow. Resolve ambiguous contacts first. Enabling writes permits proposals; it does not bypass per-action approval. On clean Seedly 5.8.4, see the installation guide's first-task project compatibility note.

## Build next: contact completeness report

Suggested contract: GET /api/v1/ext/myReporting/contact-completeness. This is an example route to implement, not an existing endpoint. Begin with a read-only manager-only tool.

Input: optional cursor and integer limit 1–100. Output: contact ID, display name, booleans missingEmail/missingPhone/missingOwner, next cursor, hasMore and generatedAt. Do not return addresses, notes or raw custom fields. Define empty/invalid values consistently; the report identifies missing data, not consent to contact someone.

Use the native contacts view permission, contacts feature gate and an explicit extension API scope. Derive the location from the authenticated host context. Check every returned row belongs to it. Tests: wrong tenant, own/team refusal, missing scope, empty account, deleted records, boundary limits and stable pagination. First acceptance: compare five synthetic contacts by hand.

## Build next: overdue task digest

Suggested contract: GET /api/v1/ext/myReporting/overdue-tasks. Input: asOf as a validated ISO date-time, a validated IANA time zone, cursor and bounded limit. Output: minimal task rows with dueAt/owner/status, paging and asOf. Exclude completed and deleted tasks according to native semantics. Date-only due dates need an explicit end-of-day rule.

Use native tasks view permission and feature gating. Do not implement timezone or recurrence assumptions from field names alone. Test midnight/DST boundaries, unassigned tasks, completed/deleted records, wrong tenant, missing scopes and pagination. This route is useful when the base API cannot express the report efficiently; otherwise use the saved prompt above.

## Build next: invoice aging

Suggested contract: GET /api/v1/ext/myReporting/invoice-aging. Input: validated asOf date and timezone. Output: overdue buckets per currency, integer minor-unit amounts, matching invoice count, asOf and completeness. Define treatment of partial payments, refunds, voids and due-today invoices with the native billing rules.

Discover the installed native billing permission/feature and API scope; do not assume a resource string from the invoice screen name. Aggregate on the server over the authorized full result set, or return explicit partial status. Never sum different currencies or let the model infer cents versus dollars. Tests include negative/refunded balances, multiple currencies, date boundaries and permission revocation. Keep it read-only; payment collection is a separate tool.

## Copy a recipe to your coding agent

```text
Implement only the selected recipe in my licensed Seedly host.
Read Orbit's EXTENDING_API_WITH_AI.md and AGENT_INSTALL.md first.
Inventory current routes and reuse a supported operation when possible.
Write the exact request/response/permission contract before coding.
Keep the suggested endpoint disabled until its implementation, discovery,
scopes, native authorization, tests and deployment are verified.
Add a typed Orbit operation with additionalProperties:false and bounded
inputs; enforce semantics again in the host handler. Keep account IDs,
headers and secrets out of model arguments. Preserve extension allowlist
and discovery gates. Start manager-only and read-only.
Use two tenants and restricted staff in tests. Produce fixture and live
verification evidence separately. Do not invent unavailable data sources.
Return code changes, tests, setup steps and an exact allowlist entry.
```


---

# Troubleshooting

Diagnose one layer at a time: source install, deployment, browser session, location policy, provider, CRM key, native permission, endpoint contract. Never fix a failed check by removing authorization.

| Symptom | Check | Next step |
| --- | --- | --- |
| Installer refuses a file | Customer edit or unsupported host seam | Compare the diff and supported host version. Preserve edits; do not delete the receipt. |
| Doctor mismatch | Installed source differs from receipt/package | Review local customization or incomplete install; preview recovery. |
| Page unavailable | Web process, port, frontend deployment, auth session | Start the correct host web app, verify ready status, then sign in on the same origin. |
| Sidebar missing | Navigation contribution, role/plan feature | Run doctor, confirm native Orbit permissions/feature and current deployed build. |
| Floating launcher missing | Location enabled, Floating chat, personal Hidden choice, route | It is intentionally hidden on the full Orbit page. Open a CRM page in the same location. |
| Agency access disabled | Per-location agencyAccess setting | Have an authorized manager enable the intended location. |
| Cannot connect provider | Wrapping secret present and valid; agency/settings rights | Configure the backend secret without exposing it, then verify the key. |
| Key verified but reply fails | Credits, selected model, tool support, provider error | Check failed-run details and provider account. Verification does not test inference. |
| CRM configured but reads fail | Mapping IDs, key validity, scopes, origin | Configured means the server variable exists, not that each mapped connection works. |
| Account-wide access required | User's native record scope | Use an authorized account-wide role or build a separately reviewed scoped endpoint; never widen automatically. |
| Extension route refused | Exact METHOD path, live discovery, granted scope | Implement/deploy/register the route first. Allowlisting text alone is insufficient. |
| Chart total seems low | hasMore, source rows, date/currency filters | Label the sample or use a complete authorized aggregate endpoint. |
| First task fails on Seedly 5.8.4 | API Tasks project createdBy compatibility | Apply the narrowly documented host fix; never accept createdBy from request input. |
| Unknown write outcome | Native record/provider state and run audit | Reconcile before a new proposal; never blindly replay a send or payment. |
| Old layout after update | Backend/web versions, cached tab | Confirm new build is served and refresh. Keep frontend/backend compatibility. |

For support provide module/host versions, route, sanitized error and request/run ID, expected/actual result and reproducible steps using synthetic data. Remove tokens, cookies, authorization headers, provider keys, CRM secrets and customer records. Keep screenshots free of personal data.


---

# API coverage

Published reference: https://seedlycrm.com/docs/help/api (September 18, 2026). Reconciled September 27, 2026.

Input OpenAPI SHA-256: `ef08f173b2824374c7ed609c6f82b9b64bd617f2abbee09e1738f6565c9fe5d0`. Four verified-customer operations supplement the local specification from the published reference.

50 operation definitions including the extension gateway. Runtime authorization and API scopes still apply. No endpoint is a claim of live deployment verification.

| Operation | Method | Path | Execution |
|---|---|---|---|
| listContacts | GET | /api/v1/contacts | Read |
| createContact | POST | /api/v1/contacts | Reviewed action |
| listContactFields | GET | /api/v1/contacts/fields | Read |
| getContact | GET | /api/v1/contacts/{id} | Read |
| updateContact | PATCH | /api/v1/contacts/{id} | Reviewed action |
| deleteContact | DELETE | /api/v1/contacts/{id} | Reviewed action |
| listConversations | GET | /api/v1/conversations | Read |
| createConversation | POST | /api/v1/conversations | Reviewed action |
| getConversation | GET | /api/v1/conversations/{id} | Read |
| updateConversation | PATCH | /api/v1/conversations/{id} | Reviewed action |
| listMessages | GET | /api/v1/conversations/{id}/messages | Read |
| sendMessage | POST | /api/v1/conversations/{id}/messages | Reviewed action |
| listCalendars | GET | /api/v1/calendars | Read |
| listAppointmentTypes | GET | /api/v1/calendars/types | Read |
| getAvailability | GET | /api/v1/calendars/availability | Read |
| listAppointments | GET | /api/v1/calendars/appointments | Read |
| bookAppointment | POST | /api/v1/calendars/appointments | Reviewed action |
| cancelAppointment | DELETE | /api/v1/calendars/appointments/{id} | Reviewed action |
| listWebhookSubscriptions | GET | /api/v1/webhooks | Read · agency admin |
| createWebhookSubscription | POST | /api/v1/webhooks | Reviewed action · agency admin |
| updateWebhookSubscription | PATCH | /api/v1/webhooks/{id} | Reviewed action · agency admin |
| deleteWebhookSubscription | DELETE | /api/v1/webhooks/{id} | Reviewed action · agency admin |
| regenerateWebhookSecret | POST | /api/v1/webhooks/{id}/regenerate-secret | Reviewed action · agency admin |
| listTasks | GET | /api/v1/tasks | Read |
| createTask | POST | /api/v1/tasks | Reviewed action |
| getTask | GET | /api/v1/tasks/{id} | Read |
| updateTask | PATCH | /api/v1/tasks/{id} | Reviewed action |
| deleteTask | DELETE | /api/v1/tasks/{id} | Reviewed action |
| completeTask | PUT | /api/v1/tasks/{id}/complete | Reviewed action |
| listOpportunities | GET | /api/v1/opportunities | Read |
| createOpportunity | POST | /api/v1/opportunities | Reviewed action |
| getOpportunity | GET | /api/v1/opportunities/{id} | Read |
| updateOpportunity | PATCH | /api/v1/opportunities/{id} | Reviewed action |
| deleteOpportunity | DELETE | /api/v1/opportunities/{id} | Reviewed action |
| setOpportunityStatus | PUT | /api/v1/opportunities/{id}/status | Reviewed action |
| moveOpportunityStage | PUT | /api/v1/opportunities/{id}/stage | Reviewed action |
| listPipelines | GET | /api/v1/pipelines | Read |
| createCampaign | POST | /api/v1/campaigns | Reviewed action |
| sendCampaign | POST | /api/v1/campaigns/{id}/send | Reviewed action |
| scheduleCampaign | POST | /api/v1/campaigns/{id}/schedule | Reviewed action |
| listSubAccounts | GET | /api/v1/sub-accounts | Read · agency admin |
| listBookingServiceTypes | GET | /api/v1/booking/service-types | Read |
| listBookingEstimates | GET | /api/v1/booking/estimates | Read |
| listExtensionRoutes | GET | /api/v1/ext | Read · agency admin |
| callExtensionRouteGet | GET | /api/v1/ext/{namespace}/{path} | Read · agency admin |
| callExtensionRoutePost | POST | /api/v1/ext/{namespace}/{path} | Reviewed action · agency admin |
| verifiedAppointments | POST | /api/v1/booking/appointments | Read |
| verifiedActionableAppointments | POST | /api/v1/booking/appointments/actionable | Read |
| verifiedCancelAppointment | POST | /api/v1/booking/appointments/cancel | Reviewed action |
| verifiedRescheduleAppointment | POST | /api/v1/booking/appointments/reschedule | Reviewed action |

Public live-chat/forms and signed workflow ingress are separate protocols, not authenticated CRM management APIs. They are not exposed as arbitrary bypass tools. Extend through the authenticated extension seam; see EXTENDING_API_WITH_AI.md.

## Original Orbit v1 additions

`countContactsByLifecycle`: GET `/api/v1/ext/orbit/contacts/counts`, scope `orbit:contacts:read`, native Contacts view/account-wide permission. Optional `source` is an exact record filter. Returned rows are `{stage, count}`. `meta.hasMore` means incomplete coverage; `meta.matchingContacts` is null until the scan completes. Counts exclude inactive and soft-deleted contacts. The endpoint traverses records before filtering, avoiding the host contacts-list pagination/filter ordering issue.

The original catalog contains 51 operations: the 50 upstream/supplemental definitions plus this aggregate. Custom definitions live in `customOperations.js` and survive upstream catalog regeneration.

Orbit also contributes `tasks:create` to POST `/api/v1/tasks` only. It does not grant read/update/complete/delete. This is separate from the native task scope contract documented by Seedly.


---

# Orbit implementation contract

Orbit is a separately installable staff-facing Seedly module. It is not a public customer-support chatbot. Host baseline: Seedly 5.8.4 / extension API 1. Original payload lives under `src/`; host source never belongs in its package.

## Product

- Location-bound conversations, saved history, pin/archive/rename, private saved prompts.
- Native `/location/[locationId]/orbit` workspace, `/orbit` account entry point, movable floating launcher in location dashboard pages.
- Agency owners/administrators configure each location: enablement, floating visibility, agency access, reviewed writes, model, daily reply limit, exact allowed extension routes.
- 51 authenticated operation definitions: 50 upstream definitions and the Orbit-owned lifecycle-count extension. Public forms/live-chat and signed workflow ingress remain separate integration protocols.
- Inline source disclosures, tables, count/sum metrics and bar charts calculated from retrieved rows. Partial data is labeled. No generated JavaScript or arbitrary HTML executes in the chat.

## Authority and persistence

Use native auth, active membership, agency/location ownership, native resource permissions, plan features, and account-wide record scope. An API key cannot widen the signed-in user's role. Extension calls require an agency manager, exact route allowlist and live discovery grant. All module tables are private and indexed by_subAccount.

Conversation ownership is user + agency + location. Account IDs are derived server-side; the model has no account/header/URL override. API requests go only to this installation's CONVEX_SITE_URL and refuse redirects. CRM keys stay in backend environment configuration and are revalidated against the host before calls. OpenRouter keys are encrypted at rest in private location settings with deployment-owned AES-GCM wrapping and agency/location associated data; public queries never return ciphertext or plaintext. Only agency managers with native settings-update access can connect/disconnect keys.

Writes become immutable proposals with 15-minute expiry in chat and a snapshotted, configurable 15-minute to seven-day expiry for agents. Approval rechecks current policy, claims exactly once in a transaction and executes stored arguments. A network failure or 5xx is outcome-unknown; no automatic replay. Actual provider delivery is distinct from API acceptance. Approved actions can trigger native automation and are not globally undoable.

Replies reserve a daily per-user/location slot atomically. Same request ID cannot create duplicate messages/runs. Each reply has bounded history, tool count, output tokens, request/response size and time. Provider usage is token accounting; daily turn limits are not a guaranteed dollar budget.

## Provider

OpenRouter Responses API for new setups, with retained direct OpenAI Responses compatibility for existing setups; server-side credentials, store:false, configurable tool-capable model. Key verification uses OpenRouter GET /key without inference; successful verification does not certify model access or credits. Changes/disconnection stop the next model round; an already in-flight request cannot be recalled. Tool definitions are explicit; model output is untrusted. No shell/browser/code execution tool. CRM content is treated as quoted data. API secrets and token fields are removed from model and persisted result payloads. Webhook create/rotation returns its new signing secret only to the approving manager’s current browser state.

## Verification

Local source tests, installed-host behavior fixtures, fresh local API types, web/backend typechecks and production build are distinct from authenticated Convex component codegen, provider spend and live CRM verification. Do not label fixture results as production-ready certification. See VALIDATION.md.

## Companion preference

Original 16×16 SVG pixel sprites replace the floating button; same launcher behavior and permissions. Users choose a built-in pixel character, classic bubble, custom image or hidden in Settings. Branded choices include a Seedly-inspired sprout, the cobalt DevLaunch companion and GoSeedly’s artichoke luchadora. The choice is per browser/user/location and remains subordinate to agency floating-chat enablement. Pets grant no extra autonomy and have no independent agent or usage.

## Native presentation

Orbit is an embedded Seedly tool. Inherit the host HSL theme tokens and typography; use neutral fallbacks. Keep one compact page toolbar, functional field labels and necessary help only. Avoid marketing headings, eyebrow labels, slogans and repeated subtitles. Pixel companions are optional personal launcher choices.

The full workspace fills the native dashboard content area with no outer card border, radius or page padding. Scope that layout to the full workspace; floating chat must preserve the underlying CRM page layout. Omit the personal-account footer from the sidebar. The installer contributes the Orbit icon to native sidebar navigation.

## Version 1 additions

Native contact-created, contact-updated and tag-added events can queue reviewed agents with durable event-key deduplication, cooldowns, concurrency and daily limits. Nested workflow events are refused. Events arriving during an active run or cooldown are coalesced rather than replayed; the agent view reports this. Agent duplication always produces an unreviewed draft. Pending write proposals are available in the approval inbox and retain permission and expiry checks at execution.

The count extension requires `orbit:contacts:read`, scans at most 10,000 contacts within a bounded request, and marks capped results incomplete. It is not an atomic database snapshot. The reversible task contribution supports `tasks:create` only for task creation and obtains `createdBy` from authenticated key metadata. See API_COVERAGE.md and AGENTS.md.

## Conversational drafts and change previews

`draft_agent` produces a bounded message block, not a persisted or enabled agent. Only current agency managers can obtain a draft; allowed tools are resolved on the server. The user hands the draft into editable setup and existing rehearsal gates. Agents cannot draft other agents.

`soActions.review` is an optional server-generated snapshot for change previews. Only mapped contact/task/opportunity updates fetch current values, under matching read permissions and agent budgets. Missing values remain unknown. Approval rechecks known fields through the same scoped REST read before issuing the write; stale or unverifiable snapshots fail closed. This does not provide atomic compare-and-swap across the REST boundary. Existing proposals without snapshots remain compatible.

## Agent inbox and event conditions

Optional structured event conditions and success-notification preference are snapshotted from `soAgents` to `soAgentJobs`. Filtering uses current native contact data and rechecks contact-read access before queuing. Exact required/excluded tags and allowed lifecycle stages combine conjunctively. Old agents retain unrestricted event matching. Changed-field predicates and tag-change attribution are not implemented.

The manager-only inbox scans at most 100 recent jobs using the owner/account index and derives actionable approval state from stored proposals. Read keys are persisted per job and compared server-side to avoid marking a newer state read. Approaching expiry gets its own key and client minute refresh; no notification scheduler or outbound side effect is introduced. Optional schema fields preserve compatibility with existing data. Deploy backend/schema before UI.

## Signed-in support mode

Support conversations retain requester ownership and normal Orbit authorization. `soSupportPolicies` is private with native tenant-purge indexing, agency defaults and optional locked account overrides. Curated knowledge and instructions grant no authority. Runtime context, tool registration, proposal creation and approval enforce the effective support tool allowlist; approval also matches the policy revision. Privileged diagnostics register a history access requirement.

Human handoff uses the existing authenticated native feedback mutation atomically, with an editable preview, verified native destination, source-active-account check and one submission per conversation. Successful handoff cancels AI work and blocks further proposals/approvals. Native intake status does not imply resolution. See SUPPORT.md for configuration, routing, scope, limits and extension requirements.

## Live support (1.6)

See LIVE_SUPPORT.md for the complete transport, authority, cancellation, usage and retention contract. Realtime voice delegates into the existing worker from regular or support conversations; it never approves CRM writes. Support conversations retain their additional tool policy. In-app navigation uses fixed permission-checked routes, caller opt-in and browser route acknowledgement. A persistent dashboard voice panel retains the call across same-account navigation and exposes its originating conversation for review. Structured screen controls use an explicit server-checked page allowlist and access level. Native permission checks, caller opt-in, fresh UI revisions and draft-only controls apply; no arbitrary computer-use tool or screenshot access is granted. New sessions are private and tenant-indexed; new schema fields remain optional for 1.5 upgrades.

## Support operations (1.6)

Setup/readiness, ten operator rehearsal scripts, draft-only voice handoffs, customer-reported outcomes and bounded account aggregates extend the live-support workflow. Practice threads refuse CRM approval and native support submission on the server. Rehearsals are private requester-owned records; pass requires worker/audio evidence and operator review, and policy/model changes invalidate results. Agency voice pause overrides local settings. New metadata retention is creation-snapshotted; it does not erase chat/audit/native-ticket records. Quality access requires agency management plus settings-update permission and returns aggregates without other users' transcripts. See LIVE_SUPPORT.md for measurement, pricing and validation limits.


---

# Voice and screen settings UX — October 14, 2026

Orbit Settings now has a direct Voice & screen controls entry, separate from support configuration. Existing voice connection, voice/language, limits, retention and estimates are exposed alongside agency pause, effective status, four screen access levels and a page allowlist. Account/agency scope and locked defaults remain enforced. Callers see the configured screen level and pages before opting in. Existing settings retain their prior supported access until edited.

- 101 Orbit backend tests, 38 browser-component tests and 33 module/source tests pass. New coverage verifies server-side levels/page restrictions, explicit empty selections, UI persistence payloads, disabled controls, agency pause and locked overrides.
- Fresh Convex generation/backend types, frontend types, sandbox deployment and production build pass. Installer doctor matches source and receipt.
- Signed-in compiled UI saved read-only screen access with Calendar disabled, reloaded and verified both settings, then restored the original access. No voice key, microphone or CRM action was used. Desktop/mobile captures remain private in `seedly-orbit-testing/tmp/captures/voice-settings`.
- Existing OpenAI microphone/provider acceptance remains pending a connected key. No public package or production website release.

# Expanded in-app screen controls — October 14, 2026

Installed in the private Seedly 5.8.4 Orbit host; backend deployed only to dedicated development `nautical-cuttlefish-605`. Public downloads and production websites remain unchanged.

- 33 original-module/source/installer checks, 97 shared installer checks, 102 backend checks, and 35 browser-component checks pass. Native extension guards pass 97 checks with 3 existing skips.
- Coverage includes server-side consent, account ownership, support allowlists, disabled writes, command boundaries, screen revisions, cancellation, queued-command invalidation across pause/resume, Escape pause, and unsaved draft updates. No arbitrary selector, code execution, save, send, delete or approval operation is exposed by the screen adapter.
- Signed-in native UI verification exercised Contacts search and contact draft fields, task draft fields, Calendar appointment draft fields, Conversations search, and pipeline control registration. Screenshots remain private in `seedly-orbit-testing/tmp/captures/screen-controls`. The sandbox has no pipeline configured; real deal-form and message-composer acceptance still need suitable records. Temporary browser test controls were removed after verification. No native forms were submitted and no messages were sent.
- Calendar testing found and fixed an initialization loop caused by unstable empty calendar/appointment-type dependencies during loading. The installer applies this compatibility fix reversibly.
- Fresh backend generation/types, dedicated sandbox deployment, frontend types and the production build pass. Existing host instrumentation/Edge and workspace-root warnings remain.
- Signed-in production-build smoke verification passes: Calendar draft opens and accepts text, Orbit shows the new screen-access consent, unconnected voice remains disabled, and no temporary browser fixture exists in the compiled app. Nothing was submitted.
- A direct OpenAI voice key is still not connected. Real microphone/audio, model-driven tool choice and end-to-end spoken screen control remain unverified. Component/provider fixtures and direct UI adapter checks are not audio certification.

# In-app voice and Seedly navigation — October 14, 2026

Implemented in original module source and installed into the dedicated Seedly 5.8.4 Orbit host. Backend deployed only to development `nautical-cuttlefish-605`; no public package or production website release.

- 32 module/source/installer tests pass, including packaging the additional browser components.
- 99 backend tests pass (93 Orbit + 6 personal ChatGPT integration). Added regular-chat voice with support disabled, permission/consent/deduplication checks for navigation, correct assistant-result retrieval, and an actual runtime fixture through voice delegation → pending CRM proposal → explicit approval → single execution.
- 26 browser-component tests pass (20 voice + 6 persistent panel). Added route acknowledgement, aborted navigation, opt-in refusal, same-account route persistence, account-switch cancellation, exact originating conversation review and external/arbitrary destination refusal.
- Fresh authenticated Convex generation and backend types pass. Frontend types and the installed host production build pass. The build retains existing host instrumentation/Edge dependency and workspace-root warnings.
- Signed-in compiled UI checked at desktop and mobile sizes: regular conversation Call Orbit entry, navigation opt-in and voice configuration render. Missing credentials correctly disable the start button. Screenshots and the private verification script remain in `seedly-orbit-testing/tmp/captures/voice-in-app` and `tmp/verify-in-app-voice.mjs`.
- Live sandbox status: voice enabled, navigation permitted, agency pause off, **no OpenAI voice key connected**. No microphone capture, real Realtime call, real CRM write or support submission was performed. Audio/playback, speech recognition, interruptions and model-driven navigation still require a funded key and actual call acceptance testing. Automated WebRTC and provider fixtures do not certify those behaviors.

# Second demo hardening pass — September 30, 2026

Frontend-only fixes installed into the dedicated sandbox:
- Canceling during SDP offer/local-description setup no longer starts a provider reservation after End.
- Failed Realtime response completion closes the call, releases the microphone and offers text recovery.
- Handoff editing state is scoped by conversation/account; draft-preparation failures are visible before the editor opens.
- Text-only rehearsals no longer instruct operators to confirm microphone playback.

All 17 voice component tests pass (three new cancellation/failure regressions), frontend TypeScript and the isolated production build pass. Alongside unchanged prior checks this brings covered checks to 197. Browser verification confirms practice handoff preview is disabled for submission and a different practice conversation does not inherit its draft. No support request was sent; actual voice playback remains unverified.

# Demo hardening — September 30, 2026

- 194 checks pass: 32 source/installer, 89 backend, 14 browser-component and 59 native host guards. Fresh backend generation/types/deployment and frontend types pass; the final isolated production build passes.
- Added regression coverage for peer/channel setup failures, late audio-playback and heartbeat failures, unanswered microphone permission, dropped data channels and calls crossing UTC midnight.
- A real OpenRouter forbidden-action rehearsal exposed a misleading empty-answer fallback. The parser now preserves Responses refusal blocks and never claims retrieved records without a recorded source. Two backend regressions verify both cases. A real OpenRouter retry displayed the provider refusal correctly; the text-only rehearsal was inspected and marked passed with review notes.
- Actual microphone/audio verification remains pending; the sandbox’s OpenRouter worker connection alone does not enable the current OpenAI Realtime transport. Public 1.5 downloads and the earlier private candidate archive are unchanged by these working-source fixes.

# Orbit 1.6 support operations validation

September 30, 2026. All six support-operation improvements are implemented in the dedicated Seedly 5.8.4 sandbox: guided setup, stronger voice defaults, evidence-based handoff drafts, ten rehearsal scripts, quality reporting and agency controls.

- 32 original module/source checks, 86 installed-host backend checks, 8 browser-component checks and 59 native schema/privacy/purge/extension checks pass (185 total).
- Fresh authenticated Convex API generation, backend types/deployment, frontend types and the isolated production build pass. Fresh 5.8.4 installation and the separate 1.5 upgrade fixture pass installer/doctor checks.
- New behavioral tests cover agency-pause precedence, ordinary-staff refusal, practice write/submission refusal, rehearsal evidence and revision gates, measurement bounds/ownership, unrated-versus-resolved outcomes, practice exclusion, draft-only handoff, retention, cost/config bounds and recorded failure/evidence-warning metrics. Frontend coverage verifies optional feedback does not silently report resolution.
- A real sandbox support-worker text rehearsal answered the reviewed-CRM-change question with recorded K3 guidance. The answer and source were inspected. This is a real text/provider check, not an audio pass. No CRM mutation, support notification or live microphone call was performed.
- Operator scripts cover noisy audio, correction, interruption, network loss and handoff; those audio scenarios remain untested until the customer connects a direct OpenAI voice key and completes actual calls. Scripts and operator review are not an automated voice-model grader or enterprise load certification.
- Quality aggregates are bounded and metadata-only; browser measurements and customer feedback are explicitly labeled. Configured USD figures are estimates, not invoices or enforced monetary budgets. Retention applies to new voice/rehearsal metadata; chat, audit and native-ticket retention remain separate.

The public 1.5 portal release is unchanged. This remains a 1.6 candidate pending live voice verification.

# Orbit 1.6.0 candidate validation

September 30, 2026. Implemented and deployed to the dedicated Orbit sandbox (`nautical-cuttlefish-605`, Seedly 5.8.4). This is a candidate, not a replacement of the public 1.5 download. Live microphone/OpenAI Realtime verification is pending a customer-connected direct OpenAI voice key; the existing sandbox OpenRouter connection does not provide that credential. Do not describe fixture voice responses as actual provider/audio certification.

- 32 module/source/installer tests, 75 installed-host backend tests, 7 browser-component tests, and 59 native private-table/purge/extension checks pass (173 total).
- Fresh Convex API generation, backend typechecking and sandbox deployment pass. Frontend typechecking and a production build in the private upgrade fixture pass. Existing host Sentry/Better Auth build warnings remain.
- Fresh licensed 5.8.4 source passes clean install/doctor. The separate 1.5 fixture passes the 1.6 upgrade/doctor.
- Backend cases cover ownership, native roles, support revision and key changes, daily/concurrent reservations, stale heartbeat/expiry, duplicate tool IDs, cancellation and refusal of late proposals/results, explicit page allowlisting, provider negotiation without key exposure and failed negotiation cleanup.
- Component cases cover unconfigured voice, denied microphone, mute, end during connection, unmount cleanup, duplicate streamed calls, late results and priority handling of a spoken end-call request.
- Browser verification confirms agency/account settings, the separate encrypted-key connection form, saved sandbox voice enablement and the disabled Speak with AI entry point with accurate missing-key guidance. No microphone audio was sent, real voice call was made, or CRM write executed during these checks.

The voice transport uses OpenAI Realtime; account work delegates to the existing support model. Page guidance is user-clicked navigation links, not autonomous UI control or screen access. Run the LIVE_SUPPORT.md audio checklist before public release.

## Reproduce the added browser checks

Copy `host-tests/web-live-support.test.tsx` into the private host at `apps/web/__tests__/seedly-orbit-live.test.tsx`; from `apps/web`, run `pnpm exec vitest run __tests__/seedly-orbit-live.test.tsx`. Copy the backend host test as described in the existing validation workflow, then run `pnpm exec vitest run __tests__/seedly-orbit.test.ts` from `convex`.

# Orbit 1.5.0 release validation

September 30, 2026. Fresh licensed Seedly 5.8.4 source passes clean installation and doctor checks. A separate clean host installed from the immutable 1.0.0 archive passes the 1.5.0 upgrade and doctor checks. Runtime validation below covers backend/frontend types, build, reviewed actions, native support routing and live synthetic provider checks. The 1.0.0 archive remains unchanged. See UPGRADE_1_5.md and CHANGELOG.md.

## 1.5 development validation — conversational support refinement — September 30, 2026

Shared intent guidance now distinguishes greetings, general assistance, product how-to, troubleshooting, CRM tasks and human requests. Support keeps its configured allowlist even when the topic changes. Saved agency instructions remain intact. Diagnostics explicitly explain all-required tags, any-excluded tags, current-state-only coverage and the difference between configured credentials and provider health.

32 source checks and 65 installed-host Orbit checks pass. Fresh backend generation/typechecking and dedicated sandbox deployment pass; the frontend guidance change passes the production build and final fresh-API frontend typecheck. Live evaluation used the existing Sonnet 5.5 connection against synthetic data: greetings and email drafting used no tools, a setup question retrieved an approved article without diagnostics, task listing used listTasks, and an explicit human request explained the preview without creating a request. Initial evaluation exposed verbose troubleshooting, incorrect tag semantics and unnecessary diagnostics for a vague failure. After refinement, new checks confirmed correct tag/history interpretation, a tool-free writing follow-up, and a clarification question with no tools for “its not working”. Troubleshooting length remains a model instruction, not a hard output-length guarantee. No CRM write or human handoff was submitted.

## 1.5 development validation — signed-in support mode — September 30, 2026

32 source tests, 65 installed-host Orbit tests, 59 native extension checks and 111 repository/installer tests pass (267 total). Fresh backend generation/typechecking and deployment to the dedicated sandbox, frontend typechecking, production build and installer doctor pass. The host retains its existing Sentry instrumentation/Better Auth Edge build warnings.

Support fixtures verify agency inheritance and locked overrides, tenant isolation, manager-only configuration, unsafe source URL/unknown tool refusal, optional empty fields, native role scope enforcement, stale proposal refusal, curated retrieval, privileged diagnostic history protection, native brand-admin routing and unbranded fallback, destination checks, inactive destination refusal, idempotent handoff, late-reply cancellation and pending-action rejection. An allowed support write remains a proposal until approved and executes at most once; forbidden writes make no CRM request.

Live sandbox validation used the existing OpenRouter connection for read-only support troubleshooting. It retrieved approved Orbit guidance and correctly identified the saved Filtered contact review agent as a draft without an accepted rehearsal. Browser checks verified support configuration, My requests, editable excerpts and a preview routed to Orbit Test Agency. No live handoff was submitted, no staff notification was sent by this validation, and no CRM record was changed. Native handoff delivery behavior was exercised in isolated host fixtures; real recipient delivery is not certified.

The first support release is for signed-in CRM users with Orbit access. It uses manually curated article text (not automatic URL ingestion), a bounded personal diagnostics view, reviewed CRM actions and native request intake. Intake acceptance is not resolution. Shared human chat, assignments, SLA scheduling and support resolution/CSAT metrics remain future work. The published 1.0.0 archive remains immutable; these additions ship in 1.5.0.

## 1.5 development validation — inbox and event conditions — September 30, 2026

31 source tests, 51 installed-host Orbit tests and 59 native extension checks pass (141 total). Fresh backend code generation/typechecking, dedicated sandbox deployment, frontend typecheck and production build pass. The final CSS-only checkbox row correction was subsequently browser-verified. Existing host build warnings relate to Sentry instrumentation and Better Auth Edge dependencies. Installer doctor confirms source and receipt match.

Regression coverage includes required/excluded tags and lifecycle matching, nonmatches before queueing, snapshotted conditions, contradictory/unknown rule refusal, rehearsal invalidation, owner/tenant inbox isolation, quiet success defaults, persistent read state, and an approval resurfacing near expiry then clearing after rejection. Browser checks confirm All recent results, the empty unread state, rule review and a saved disabled “Filtered contact review” draft. No CRM records were changed and no recurring agent was enabled for validation.

Notifications are limited to the in-Orbit inbox/unread indicator, the latest 100 owner/account jobs, and minute-level expiry refresh while open. No OS/email/SMS/native bell delivery is claimed. Filters inspect current stored contact fields; specific changed-field and newly-added-tag attribution remain unsupported. These additions ship in 1.5.0; the original 1.0.0 archive is unchanged.

## 1.5 development validation — workspace additions — September 30, 2026

Conversational agent drafts and before/after approval previews are implemented in the isolated sandbox; the published 1.0.0 archive is unchanged. 29 source tests, 46 installed-host Orbit tests and 59 native extension checks pass. Fresh backend code generation/typechecking, sandbox deployment, frontend types and production build pass.

Live synthetic-data checks: a read-only event-agent draft was generated without creating or enabling an agent, and its values transferred to editable rules and the rehearsal review screen. A contact-company update produced a server-read null-to-value comparison. Request changes rejected that proposal and prepared an unsent editable follow-up; no CRM record was changed. Tests prove changed-before-value refusal, one-time unchanged approval, unavailable-tool rejection and draft-only behavior. Before/after snapshots currently cover contact, task and opportunity updates; unavailable fields are marked unknown. REST reread/write checks are not atomic compare-and-swap.

# Orbit 1.0.0 validation

September 30, 2026. Adds native event agents, an approval inbox, draft duplication, searchable tools, lifecycle counts and a portable create-only task scope.

- 27 source tests, 111 repository tests, 42 installed-host Orbit tests and 59 native extension checks passed (239 total).
- A fresh licensed Seedly 5.8.4 extraction passed installation and doctor checks, including the previously manual task creator fix. Existing-host upgrade checks also passed.
- Event fixtures cover the native trigger hook, duplicate events, cooldowns, nested-event refusal, foreign contacts, revoked owners and draft duplication. HTTP fixtures prove tasks:create permits creation and refuses update/delete; count fixtures check scope and tenant isolation and scan beyond the first page.
- Sandbox backend deployment, code generation, frontend types and production build passed. A live OpenRouter reply executed countContactsByLifecycle against five synthetic contacts and produced a verified sum-based chart (lead: 5), with complete-scan metadata and a stored execution receipt.

Limits: Seedly 5.8.14 has not been tested locally. Event jobs coalesce events during cooldown or an active run; they are not a guaranteed per-event delivery queue. Counts scan at most 10,000 records and report partial results; concurrent updates can affect pages. No automatic CRM writes, arbitrary cron expressions, public webhook ingress or high-volume certification is claimed. Not every catalog endpoint has been exercised live.

## Previous release evidence

# Orbit 0.3.0-alpha.1 validation

September 30, 2026. Weekly/monthly schedules, configurable agent approval windows, ranked operation discovery, recorded tool activity, table corrections and launcher collision avoidance.

- 26 source tests, 111 repository tests, 35 installed-host Orbit tests and 59 native extension checks passed (231 total).
- Fresh Convex code generation and backend typechecking passed on the dedicated Seedly 5.8.4 sandbox. Frontend typechecking and production build passed.
- New regression fixtures check invented operation references against real recorded calls, bounded approval settings and immutable job snapshots. Schedule tests cover selected weekdays, short months and leap years alongside existing timezone/DST tests.
- Package regression verifies every internal manifest hash and the archive sidecar. Published 0.2.0-alpha.1 is unchanged.
- Browser inspection confirmed separate launcher/support hitboxes in the sandbox. AI text remains model-generated; operation warnings are an additional check, not a factuality guarantee.

Not verified: the client's modified Seedly 5.8.14 fork, their lifecycle-count endpoint or tasks:create scope. Event-triggered jobs remain a separate integration. No recurring job or CRM write was enabled for this update.

## Previous release evidence

# Orbit 0.2.0-alpha.1 validation

September 29, 2026. Current release adds guided agents, rehearsals, reviewed enablement, on-demand and daily/weekday schedules, bounded tools and usage, pause controls and run history.

- 21 module source tests, 111 repository tests, 33 installed-host Orbit tests and 59 native snapshot/purge/extension checks passed (224 total).
- Fresh Convex codegen and backend typechecking passed on a dedicated Seedly 5.8.4 sandbox; backend deployment succeeded.
- Frontend typechecking and production build passed. The final UI was inspected in an authenticated browser, including formatted results and the read-only rehearsal evidence view.
- A real OpenRouter / Claude Sonnet 5.5 rehearsal retrieved five synthetic contacts through the deployed CRM API. Sources and results were visible, and enablement remained blocked pending acceptance.
- Tests cover tenant isolation, current owner authorization, tool allowlists, rehearsal approval refusal, revision invalidation, concurrency, per-agent daily limits, schedule deduplication, interrupted-job recovery and pause behavior. Timezone tests include daylight-saving gaps and weekday rollover.
- Installer diagnostics confirm the owned source and receipt match. No recurring demo schedule or CRM write was enabled during this validation.

Limits: no CRM event triggers, arbitrary cron expressions, automatic writes, cross-account agents, automatic learning or dollar-spend guarantee. The full catalog has not been exercised against every live provider and customer configuration. Test coverage is not a high-volume or all-host compatibility certification.

## Earlier releases — historical evidence

The notes below describe checks at their original dates. The current live-provider and agent validation above supersedes earlier statements that inference had not yet been tested.

# Orbit 0.1.0-alpha.4 validation

September 27, 2026. Original module source in `seedly-addons/modules/orbit`.

## Completed locally

| Check | Evidence |
|---|---|
| Pure/core and installer tests | 17 passing: endpoint inventory, schema checks, account/header/path injection, secret redaction, real-data aggregates, partial pages, bounded storage, action transitions, floating bounds, reversible installation and customization refusal |
| Installed-host backend fixtures | 23 passing: auth/tenant isolation, own-scope refusal, duplicate submit, immutable single-use approvals, policy revocation, agency control, daily limits, model/read/chart loop, write proposal/approval, provider failures, retained-history permission revocation, cancellation, expiry, agency gating and one-time webhook secret disclosure; OpenRouter key verification/encryption/public-query exclusion, unauthorized access, failed replacement, reviewed write loop, tenant-bound decryption and mid-loop disconnection |
| Native extension guards | 27 passing across private-table purge-index coverage, plan schema registration and extension seam checks |
| Existing repository tests | 111 passing; original module installer/runtime tests remain green |
| Installer/doctor | Installed in a new private offline Seedly 5.8.4 copy; module source and receipt match |
| Local API references | Regenerated with the installed Convex API codegen template for the full installed module set; real schema-derived types used |
| Backend types | Passed on the installed private host |
| Web types and production build | Passed in the installed host using nonsecret placeholder public Convex URLs; no deployment or live queries |
| Browser review | Actual React workspace with explicit fixture adapters: desktop chart/source view, settings save, floating launcher and keyboard movement, conversation restoration, mobile breakpoint, proposal-to-success flow, light/dark themes |

Logs and synthetic captures are private ignored artifacts under `.cache/orbit-*`. The synthetic preview at `http://127.0.0.1:3048/` uses the actual UI components and fake data/network adapters; it is not an authenticated production installation. Its controls do not call AI providers or write to a CRM.

## Not claimed

- Authenticated Convex component codegen and deployment verification: the offline host has no deployment configured; normal CLI codegen correctly refused rather than selecting a shared backend. Fresh authenticated codegen remains mandatory in the chosen target.
- Real OpenRouter/OpenAI execution, provider charges, live endpoint/version/scope verification, or customer data writes.
- Live external message/campaign delivery, calendar/provider behavior, or webhook delivery after rotation.
- Every endpoint exercised against a deployed customer CRM. The 50-operation catalog is contract coverage; integration fixtures exercise representative reads/writes, not 50 live operations.
- Combined installation-order certification with every other add-on. The existing installer tests pass and Orbit's own install/uninstall is reversible, but the new six-module permutation matrix has not been certified.
- High-volume multi-agency load testing, complete cross-account analytics, token streaming, unbounded history search, monetary spending guarantees, or arbitrary public-widget/workflow adapter coverage.

No production deployment, API key creation, provider spend, customer message, campaign send, or external CRM mutation occurred during this build. Original source packaging is separate from release/deployment approval.

Alpha.2 additionally browser-checked the optional companion picker, hidden launcher, pet chat opening and per-browser persistence. OpenRouter uses mocked provider responses in installed-host tests; no real key was submitted and no inference credits were spent. Updated types, extension guards and host production build are checked locally.

Presentation refinement: removed promotional headings and repeated subtitles; compacted settings and launcher choices; adopted native Seedly HSL tokens with neutral fallbacks. Reviewed light/dark preview, regenerated local references, and passed installed-host backend/web types and production build. No backend behavior changed.

Alpha.3: catalog normalization tests cover text/tool filtering, batch exclusions, deduplication, newest-first sorting and unavailable pricing. Installed-host tests additionally verify manager-only model discovery without credentials in the request. Public OpenRouter catalog fetched directly for the dated model snapshot; no inference requests. Browser verification includes custom image upload, reload persistence, removal, new pet selection, transparent/shadow-free launcher, model search/select/save and dropdown spacing. All imagery used for upload checks is synthetic.

Branded launcher refinement: added original pixel SVG interpretations of a Seedly-inspired sprout, DevLaunch’s cobalt notched companion and GoSeedly’s coral-mask artichoke. Browser-checked all three selections and reload persistence. Fresh local API references, backend/web typechecks, 27 extension guards and installed-host production build passed. No backend behavior or live deployment changed.

## Dedicated instance acceptance — September 28, 2026

Clean Seedly 5.8.4 base, Orbit only, dedicated development backend `nautical-cuttlefish-605` (project `wearehypercat/seedly-orbit-test`), source `../seedly-orbit-testing`, local frontend port 3050. Authenticated Convex deployment and API generation succeeded. Native owner login, two isolated subaccounts, actual model discovery, CRM connection check, saved/pinned/archived chats and cross-location conversation refusal were exercised.

Scoped CRM REST checks: five synthetic contacts returned, unauthorized account header refused with 403, task creation returned 201. An explicitly labeled operator-created proposal was approved in the real Orbit UI; it created a task and repeat approval was refused. This tests approval/execution, not AI generation. The private temporary fixture function was removed from the backend after preparing the proposal.

A Seedly host defect was found: first task creation builds an API Tasks project with an invalid empty createdBy. The dedicated host carries the API key creator through ApiAuthContext into pm.apiCreate, using authenticated key metadata rather than request input. This narrow host fix is separate from the module distribution; see INSTALLATION.md. The portable installer now contributes an Orbit sidebar icon through the same reversible client-side seam used by Events.

No OpenRouter inference key was supplied. Real model replies, model-selected tool calls and AI-generated charts remain unverified. No customer records, external messages, payments or production deployments were involved.

Final dedicated-host checks: 17 Orbit tests, 111 repository tests, 50 host tests, backend/web types and the local production build passed. The compiled app was browser-checked for native Contacts data, the Dev launcher, keyboard movement and floating chat restoration. Evidence stays private in seedly-orbit-testing/tmp/captures.

Full-page layout refinement: removed the personal-account footer and scoped native page-padding removal to the non-floating workspace. Web typecheck and dedicated-host production build passed. No backend or authorization logic changed.

Appearance coverage: persisted custom colors, omitted-field compatibility, invalid-color rejection, tenant isolation, and existing agency-only settings authorization. Popup width is 520px on desktop with larger text and controls, and constrained to the viewport on mobile.

Popup simplification: a single header contains history, new chat, expand and close. Account switching and conversation management remain in the full workspace; popup history retains navigation. Removed repeated message labels/timestamps and composer metadata, compacted the composer, and raised the popup above the native feedback launcher. Review cards retain account and approval details.

## September 29 provider compatibility fix

Claude Sonnet 5.5 returned HTTP 404 because OpenRouter require_parameters routing excluded providers when parallel_tool_calls:false was supplied. Orbit now omits that optional parameter for OpenRouter; its own sequential tool execution and reviewed writes remain unchanged. Provider 404 errors now distinguish parameter availability and privacy-policy restrictions without echoing provider payloads. Deployed to the dedicated nautical-cuttlefish-605 sandbox. Verified a live Sonnet 5.5 reply and read-only retrieval of five synthetic contacts with the existing saved key. Backend typecheck and 24 Orbit host tests passed. This patch is in module source; the previously published alpha.4 archive remains immutable and has not been replaced.

## ChatGPT text integration — October 1, 2026

Original module source now includes a personal, location-bound ChatGPT connection, registered-client OAuth callback, encrypted PKCE/token storage, serialized refresh and revocation, an account-specific model picker, and the text runtime adapter. Setup is in [CHATGPT.md](CHATGPT.md). No approved commercial OAuth client was supplied or enabled; the earlier loopback-only proof remains separate.

Verification:

- Shared/local ChatGPT suite: 34 tests passed, including 7 integration transport tests for tenant-bound encryption, registered-client enforcement, confidential auth, request allowlisting, tool-only completion, headerless text and interrupted streams.
- Installer regression suite: 110 of 111 passed together after disk recovery; the remaining coexistence case observed three source changes while the suite was running. That exact case passed on a clean isolated rerun. Earlier runs failed due to local ENOSPC, not provider behavior. Only generated `.next/cache` directories were removed to recover space; project/media files were preserved.
- Both designated hosts produced successful local production web builds with their `/api/<module>/chatgpt` routes. Their existing build configuration skips inline TypeScript validation, so separate typechecks are required and recorded below.
- No new real ChatGPT inference, provider key creation, CRM write, social publishing, public archive release or production web deployment was performed during this integration build. Hosted ChatGPT OAuth, real refresh/revocation and live tool round-trips still require the approved client and acceptance test.

Orbit: 95 installed-host tests passed (89 existing + 6 new connection/runtime tests), 32 source/installer tests passed, and 115 native extension/schema guards passed with 2 pre-existing skips. Fresh authenticated API generation and backend typecheck passed. `convex dev --once` successfully published to the designated `nautical-cuttlefish-605` development backend. The compiled app on 127.0.0.1:3050 was checked while signed in: Settings renders the ChatGPT card with the truthful unconfigured-access message. Existing OpenRouter settings were preserved. This does not certify a live ChatGPT website grant.

Final separate installed-host web TypeScript check: `pnpm exec tsc --noEmit` passed against the completed source. Both backend and web checks are green locally; the Content Engine authenticated deployment limitation above remains.