@opengeni/runtime 3.0.1 → 4.0.0

package/src/bundled_default_skills/opengeni-client/references/product-integration-shapes.md

@@ -0,0 +1,232 @@
+# Product Integration Shapes
+
+This reference helps a customer-side agent decide how a product should use a
+standalone OpenGeni deployment. It is intentionally architecture-level. Verify
+exact methods and props against the installed `@opengeni/sdk` and
+`@opengeni/react` versions.
+
+When the OpenGeni repository is available, read `docs/product-integration.md`
+first. It is the canonical contract for organization API keys, organization
+workspaces, Personal-workspace exclusion, and external Skill ownership.
+
+## The Common Architecture
+
+```text
+customer browser / mobile app
+            |
+            | customer session, same-origin product API
+            v
+customer backend / tenant boundary
+  - stores one organization API key
+  - maps the chosen product sharing boundary -> organization workspace
+  - stores/version-controls product Skills
+            |
+            | @opengeni/sdk, server-held OpenGeni credential
+            v
+standalone OpenGeni API -> sessions, workers, tools, storage, compute
+```
+
+The customer does not need to embed OpenGeni's database, workers, router, event
+bus, or sandbox runtime. "Embedded agent" usually means the product presents an
+OpenGeni-backed agent in its own experience while OpenGeni remains a service.
+
+This integration skill belongs to the customer's development agent. Runtime
+skills selected in `CreateSessionRequest.skills` belong to the OpenGeni session
+it creates. Keep those layers separate: integration knowledge should not be
+copied into every runtime agent prompt, and runtime skills should not redefine
+the product's trust boundary.
+
+The external product is the runtime Skill source of truth. There is no
+organization-wide Skill registry or Skill inheritance in the product
+integration contract; selected Skills are sent inline for each product-created
+session.
+
+## Choose The Isolation Unit
+
+One workspace per product tenant is correct only when that tenant may share
+workspace-scoped agent authority and resources. Default to:
+
+| Sharing requirement | Workspace mapping |
+| --- | --- |
+| Tenant/team chats may collaborate | Per tenant/team |
+| Chats are private between end users | Per end user |
+| Every chat is a hard boundary, including within one user | Per chat |
+| Data is shared but chats are private | Per user/chat, with equivalent scoped data access |
+
+A live agent with the relevant first-party session tools can reach unrelated
+sessions in the same workspace. Turning Knowledge authoring off does not change
+that. Removing all unnecessary cross-session and workspace-wide tools is useful
+defense in depth for an explicitly softer design, but a hard requirement needs
+separate workspaces.
+
+An organization API key creates workspace-visible top-level sessions. It does
+not impersonate the customer's end user as an OpenGeni managed human and cannot
+use Only-me visibility as a substitute for the mapping above.
+
+## Decision Matrix
+
+| Need | Recommended surface | Product renders | OpenGeni package |
+| --- | --- | --- | --- |
+| Send users to the complete stock experience | Link/deep-link | Product entry point only | None |
+| Custom UI in any framework, mobile, CLI, or automation | Headless SDK | Everything user-facing | `@opengeni/sdk` |
+| Custom React UI using canonical session behavior | Headless React session hooks | Product timeline/composer/layout | `@opengeni/react/session` |
+| Packaged OpenGeni chat/session controls | Styled React surfaces | Product shell and domain UI | `@opengeni/react/session-ui`, `/composer`, `/realtime` |
+| Agent workspace with files, changes, terminal, or desktop | Workbench | Product shell plus chosen tabs | `@opengeni/react` |
+| OpenGeni runtime inside the host process | Advanced in-process embedding | Host owns infrastructure seams | Repo-level packages; see `docs/embedding.md` |
+
+Start with the headless SDK. Add React surfaces rather than designing a larger
+boundary up front. The packages are composable; using one hook does not require
+mounting the stock OpenGeni application.
+
+## Server And Browser Responsibilities
+
+### Product server
+
+- Authenticates its own user and enforces its own tenant/business permissions.
+- Maps that principal to one allowed OpenGeni organization workspace and
+  allowed sessions. Personal workspaces are excluded.
+- Holds the organization API key or delegated credentials.
+- Calls `ensureWorkspace` with the product tenant's stable external identity and
+  stores `result.workspace.id`; `result.created` distinguishes create from
+  idempotent replay.
+- Loads product-owned Skills and passes the selected definitions inline in
+  `CreateSessionRequest.skills` for each product-created session.
+- Sends explicit minimal `tools` and `firstPartyMcpTools` selections. Omission
+  inherits workspace/deployment defaults; an explicit empty array suppresses
+  that category.
+- Calls `OpenGeniClient` and returns product-shaped responses.
+- Re-streams session SSE with `proxySessionEventStream` when the browser needs a
+  live timeline.
+- Rejects caller-supplied workspace/session IDs that are not already authorized
+  by the product relationship.
+
+### Product browser
+
+- Talks to the product's same-origin routes or the deployment's normal browser
+  auth boundary.
+- May use the SDK with a custom `fetch`/same-origin base URL.
+- May mount React hooks/components against a structural proxy client.
+- Never receives an organization API key just because it renders an agent.
+
+The browser may PUT file bytes directly to a short-lived signed object-storage
+URL returned by the SDK flow. That URL is scoped upload authority, not the
+OpenGeni API credential. The SDK omits ambient cookies and auth on the storage
+request. The deployment must configure storage CORS for intended browser
+origins when browser uploads are enabled.
+
+## UI Composition
+
+### Headless session semantics
+
+Use `@opengeni/react/session` when the product owns every visual decision but
+wants canonical event, queue, composer, goal, approval, human-input, and timeline
+behavior. The exported client contracts are structural and intentionally
+narrow. Implement the exact client refinement required by each mounted hook;
+do not stub billing, workspace administration, machines, or workbench methods.
+
+### Packaged visuals
+
+Use the styled subpaths for only the features the product wants:
+
+- `@opengeni/react/session-ui` for timeline/session chrome surfaces.
+- `@opengeni/react/composer` for the standard composer or its controller and
+  compound primitives.
+- `@opengeni/react/realtime` for realtime session controls.
+- `@opengeni/react/machines` for Connected Machine management.
+- the root package for the optional workspace/workbench graph.
+
+Import `@opengeni/react/compiled.css` once for the default styled experience.
+It is package-compiled, scoped under `.og-root`, and does not require the host to
+run Tailwind or scan package source. Theme and density are `--og-*` runtime
+tokens. Tailwind v4 hosts may deliberately compile the additive `styles.css`
+source bridge instead, but must use one styling path, not both.
+
+Responsive behavior should be container-based inside sidebars, drawers, and
+split panes. Prefer package density/responsive props over host CSS selectors
+that reach into SDK internals.
+
+## Context And Instructions
+
+The product should send four different kinds of information through their
+matching contracts:
+
+| Information | Contract | Lifetime | Visible in timeline |
+| --- | --- | --- | --- |
+| Stable workspace persona | workspace `agentInstructions` | every session in workspace | No |
+| Agent role/persona refinement | session `instructions` | one session | No, but session metadata is org-visible |
+| Current route/selection/viewport snapshot | `modelContext` | one accepted message | No in the standard timeline; yes in full audit data |
+| What the user said | message text / `initialMessage` | durable conversation | Yes |
+
+Use `requestedSessionId` plus a stable `idempotencyKey` when the product must
+persist its own link before the first OpenGeni turn can run. The ID is
+correlation, not authorization.
+
+`modelContext` is ordinary user-role model content, not a system instruction or secret. It is a snapshot, not a substitute for tools. If the agent needs
+current product state or must mutate product data, expose a tenant-scoped
+OpenAPI/GraphQL Integration or MCP server. Keep tool outputs machine-useful;
+the product may render a separate, more concise user-facing projection.
+
+## Ownership Of Product Data
+
+Keep customer domain records in the customer product. Give the agent authorized
+MCP tools to read or change them. Store only OpenGeni-native facts in OpenGeni:
+sessions, events, selected resources/tools/skills, files used by sessions,
+approvals, goals, schedules, and execution state.
+
+Do not duplicate the customer's project/contact/document model into OpenGeni
+only to make it available to the agent. Conversely, do not treat OpenGeni's
+event stream as the customer's domain audit log. Each system remains canonical
+for the state it owns.
+
+## Files And Artifacts
+
+- One-off user attachments use `OpenGeniClient.uploadFile`, then a file resource
+  on session create or message send.
+- Indexed reusable knowledge uses the document/knowledge APIs when enabled.
+- Product-domain documents may stay in the product and be exposed through the
+  product's MCP server when OpenGeni should not own a second copy.
+- Agent-produced durable product records should be written through product MCP
+  tools. Do not infer a generic write-back/artifact path that the live service
+  does not expose.
+
+## Realtime And Compute
+
+Realtime is an optional session transport, not a second agent. Use the public
+SDK/React realtime subpaths so negotiation, lifecycle, recovery, and durable
+session context stay server-owned.
+
+Managed Sandboxes and Connected Machines are compute choices for a session.
+They do not change the product integration boundary. A customer product should
+only expose machine selection/enrollment when its users need to run on their own
+computers; ordinary embedded agents should use the deployment default.
+
+## Delivery Autonomy
+
+Infer the delivery workflow from the user's request, repository guidance, CI,
+and environment documentation. Implement and test when asked to implement, but
+do not treat available repository or cloud credentials as authorization to
+push, open a pull request, merge, deploy, or mutate production. Perform a named
+external step when it was authorized clearly. Otherwise finish the safe work
+and ask at the actual boundary, naming the target and impact, or provide the
+customer-owned runbook when they retain deployment authority.
+
+## Delivery Checklist
+
+Before calling an integration complete, verify:
+
+1. Credentials never reach browser bundles, logs, prompts, or generated skills.
+2. The selected tenant/user/chat sharing boundary maps to distinct or shared
+   workspaces exactly as intended.
+3. Product authorization is checked before every workspace/session proxy call.
+4. The effective first-party and external tool allowlists contain only required
+   capabilities.
+5. Session creation retries reuse one idempotency key.
+6. SSE reconnect resumes by sequence and does not duplicate timeline effects.
+7. Unknown additive event types do not crash the client.
+8. File upload works from every intended browser origin, including signed PUT
+   CORS and completion.
+9. Prompt scopes are used correctly; visible text is not carrying hidden policy.
+10. API/MCP tools enforce the same tenant/user boundary as the product API.
+11. Narrow and wide layouts work without host CSS reaching into SDK internals.
+12. The integration pins compatible SDK/server major versions and checks the
+    live client config rather than hard-coding volatile catalogs.

package/src/bundled_default_skills/opengeni-client/references/product-shapes-and-ui.md

@@ -0,0 +1,116 @@
+# Opening host-owned workbench tabs
+
+Use `SandboxWorkspace.openTabRequest={{ tab, requestId }}` to open a built-in or
+host-injected tab from the host's UI. Increment `requestId` for each intentional
+open, including repeated clicks on the same item. Keep artifact selection and
+internal-link recognition in the host; the workbench only selects an available
+tab and expands the dock. Preserve modified clicks and external navigation.
+When handing off to a full-page artifact route, retain an explicit originating
+session return path rather than relying on browser history.
+
+# Product shapes and UI
+
+## Choose the smallest suitable surface
+
+OpenGeni supports several product shapes. Select from the product experience and host stack rather than assuming every integration needs a custom chat:
+
+| Need | Likely surface | Product owns |
+| --- | --- | --- |
+| The complete OpenGeni experience is acceptable | Link or deep-link to stock OpenGeni | Entry point and product navigation |
+| Custom UI in any framework, mobile app, CLI, or automation | OpenGeni SDK or public API behind product backend | All user-facing presentation |
+| React product wants canonical session state without packaged visuals | Headless React session hooks and projections | Components, layout, and styling |
+| React product wants packaged chat/session controls | Focused styled React subpaths | Shell, domain UI, and theming |
+| Product exposes files, changes, terminal, or desktop compute | Optional workbench surfaces | Product shell and selected tabs |
+
+Start with the narrowest surface that preserves the desired experience. Do not mount the full workbench for an ordinary analytics chat. Do not rebuild session streaming, replay, queueing, approval, or timeline projection when a compatible package already supplies the needed behavior.
+
+## Evaluate reuse before writing chat UI
+
+For React hosts, inspect the installed OpenGeni React package before creating replacement components. Its subpaths are composable, and the styled surfaces use scoped compiled CSS plus runtime theme and density tokens. Compare:
+
+- packaged components with customer theme tokens;
+- headless hooks with customer-native components; and
+- a fully custom SDK-driven UI.
+
+Choose based on UX requirements and dependency compatibility, then record why. Styling differences alone are not a reason to skip reusable components if their structure fits. Conversely, do not force a packaged component when the product needs a materially different interaction model.
+
+For Svelte, SvelteKit, Vue, native mobile, or another non-React frontend, use the product's native component system. Keep the privileged OpenGeni client on a compatible backend boundary. A SvelteKit server route may use the TypeScript SDK directly; a non-JavaScript backend may use the public HTTP contract or a small compatible adapter. The browser still speaks to authenticated product routes.
+
+## Optional artifact library
+
+Use `client.listArtifactCatalog(workspaceId, options)` for a workspace output
+library; supply `sourceSessionId` for a session panel. It returns bounded native
+artifact summaries and `nextCursor`, with `q`, `kind`, `status`, and `sort` filters.
+Use `kind:id` as a UI key, preserve existing type-specific open/edit APIs, and
+never reconstruct a library by scanning chat history or a sandbox filesystem.
+The catalog is discovery, not new content access authority: preserve the current
+viewer's file/artifact permissions and authorize the host's workspace mapping.
+
+Render retained images with the existing artifact loader and lightbox rather
+than compute file links. `@opengeni/react/artifacts` exports
+`isRetainedImageContentType` and `useRetainedImageObjectUrl`; the host supplies
+authenticated loading and presentation. Keep image bytes and signed download
+URLs out of durable Markdown. Standard image references use `artifact:<id>`.
+Use static tiles with a useful fallback for types without a preview; do not
+execute every Site or invoke tools just to display a library grid. Inline HTML
+and saved Sites keep the existing explicit Markdown host callbacks and isolated
+frame; ordinary HTML file downloads do not become executable previews.
+
+## Optional conversation search
+
+Check the installed SDK/React exports before offering full-history Find. With
+compatible versions, `client.searchSessionMessages(workspaceId, { query,
+sessionId, limit, cursor }, { signal })` searches literal, case-insensitive text
+in saved user and completed assistant messages. Omit `sessionId` and set
+`groupBy: "session"` for one representative hit per session in workspace search;
+do not combine those two options. Preserve authenticated host/workspace scope.
+Tools, reasoning, model context, and assistant output with only unfinished
+deltas are not searched. Do not silently fall back to title-only or loaded-DOM
+search when this endpoint is unavailable.
+
+Each request is bounded. An empty page with `hasMore: true` is still searching,
+not “no matches”: follow `nextCursor`, cancel obsolete requests, and expose
+provisional counts until `countIsExact`. Counts describe the live traversal,
+not a snapshot; grouped counts represent sessions, not per-session message
+totals. Retain a bounded hit batch and cursor history rather than downloading
+every message into the browser.
+
+Use a result's durable `sequence` and original-text UTF-16
+`messageMatchOffset` to navigate. React's `useSessionEvents().jumpToSequence`
+loads a bounded target window; pass `{ sequence, eventId, query,
+offset: messageMatchOffset }` as `MessageTimeline.searchTarget` after a
+successful jump. Preserve query and selection in host state, and clear the
+target without scrolling when Find closes. A custom virtualized message
+renderer must consume its search-target render context to reveal the selected
+text. For contextual previews, read bounded events before/after the target,
+render only `payload.text` for user/completed-assistant messages, and keep the
+returned snippet for a large target. Never stringify forensic payloads: they
+may include fields deliberately omitted from the visible conversation.
+
+## Browser/backend split
+
+The product browser normally sends product-shaped requests to its own same-origin backend. The backend authenticates, resolves the allowed mapping, and calls OpenGeni. Never bundle an organization key into frontend code.
+
+For live sessions, preserve event sequence, reconnect, replay, and duplicate suppression. The SDK's stream and proxy helpers are preferred where compatible. Treat unknown additive event types as forward-compatible data rather than crashing the UI.
+
+Uploads may send bytes directly to a short-lived signed storage URL returned by the trusted flow. That URL is narrow transfer authority, not the OpenGeni API key. Verify storage CORS for every intended browser origin.
+
+## Decide what the user sees
+
+OpenGeni's durable event stream can support different product projections:
+
+- final answer only;
+- assistant messages plus progress and status;
+- selected tool-call summaries;
+- approvals and structured human-input cards; or
+- a detailed operational timeline.
+
+The customer frontend chooses which event types and fields to render. Hiding an event from the chat view does not remove it from OpenGeni's durable history or from authorized audit readers. Do not promise data erasure or secrecy from presentation filtering.
+
+Even a final-answer-only UI should surface states the user must act on: failure, cancellation, credit or policy denial, approval requests, human-input requests, reconnect status, and a way to retry safely. Avoid presenting tool failures as ordinary assistant prose when product state can represent them more clearly.
+
+## Fit the host product
+
+Follow existing navigation, accessibility, responsive, loading, error, observability, localization, and design-system conventions. Keep OpenGeni IDs behind product-native identifiers. Make the smallest dependency addition that improves correctness.
+
+The integration should feel native to the customer product while retaining OpenGeni's session semantics. Framework adaptation is expected; protocol reimplementation is not a goal.

package/src/bundled_default_skills/opengeni-client/references/runtime-profile-and-verification.md

@@ -0,0 +1,157 @@
+# Runtime profile and verification
+
+## Generate customer-specific runtime behavior
+
+This Skill guides the implementation agent, not end-user runtime chats. The implementation agent should derive the customer-facing agent's runtime profile from the customer's product intent and system, then store that profile with the customer's integration code or configuration. Do not attach this generic implementation Skill to end-user runtime chats.
+
+A runtime profile may contain:
+
+- stable workspace instructions or persona;
+- one session role and its instructions;
+- selected, versioned runtime Skills;
+- model and reasoning defaults or per-session overrides;
+- exact first-party tools, MCP or API Integration servers, and resources;
+- memory, approvals, human-input, and autonomy behavior;
+- product context mapping; and
+- the event projection the frontend renders.
+
+Use only the pieces the product needs. A simple chat may need concise session instructions and one data Integration, not a new Skill hierarchy.
+
+## Shape behavior around the product
+
+Infer the audience, tasks and expected interaction from the product and user.
+Recommend a fitting initial response style, depth and progress presentation;
+ask about unresolved choices when they materially change the experience.
+A brief answer with optional detail may suit a dashboard, while an investigation
+or automation may need a different pattern. Do not impose a universal word
+limit, fixed answer format, tool-call budget, or mandatory questionnaire.
+
+Try a representative first question and show the resulting experience when
+practical. Explain where the owner can tune instructions, model/reasoning,
+selected tools and domain Skills, including whether changes affect existing or
+only new sessions. Avoid scattering one behavior across multiple prompt layers.
+
+## Put behavior in the right lifetime
+
+| Concern | OpenGeni surface | Update behavior |
+| --- | --- | --- |
+| Stable behavior for every session in one workspace | Workspace agent instructions | Reconciled as workspace configuration |
+| One agent role or one conversation's system behavior | Session instructions | Fixed for that session |
+| Conditional procedure, domain method, or tool-use guidance | Runtime Skill | Installed at workspace scope or sent inline at create |
+| Current route, selected dashboard, filters, or viewport | modelContext on the exact message | Updated per accepted message when relevant |
+| User-visible request | Initial or follow-up message text | Durable conversation content |
+| Default model and reasoning | Workspace session defaults | Applies to newly created sessions |
+| Exact model or reasoning for one session or turn | Session create or message options | Explicit request wins, subject to policy |
+| Models a workspace may use | Workspace model access policy | Hard allowlist, managed separately |
+| Default tool catalog | Workspace session tool defaults | Applies when a create request omits a selection |
+| Customer-facing headless tool set | Explicit session tool selections | Fixed onto session; follow-up policy changes use supported session controls |
+
+Do not duplicate the same instruction across workspace instructions, session instructions, Skills, and every user message. Keep stable policy out of modelContext, and keep volatile dashboard state out of the persistent instruction prefix.
+
+Inline Skills are sent once in createSession and stored with that session; they are not retransmitted on every turn. Existing sessions retain their selected Skill content. To update behavior, version the customer profile and use the new Skill definitions for new sessions, with an explicit migration or new-session policy if old conversations must change. Workspace-installed Skills are resolved through their own installation lifecycle and should not also be copied inline.
+
+Model IDs and provider availability are deployment facts. Inspect the live client configuration and model policy. Use workspace session defaults when many sessions share the same choice; use a per-session model or reasoning override when the product or user chooses. Never hard-code a remembered catalog into a reusable integration.
+
+OpenGeni credits are held and admitted at the organization account, so organization workspaces using the OpenGeni-credits model path draw from the same account balance. Workspace count does not create separate credit wallets. Connected subscriptions and workspace-owned provider credentials can use their separately reported external billing path instead. Preserve workspace and product-boundary identifiers in usage attribution so a shared organization balance does not obscure who consumed it.
+
+## Provision and reconcile deliberately
+
+Separate hot-path chat handling from control-plane setup:
+
+- Workspace ensure is idempotent and may run lazily, but persist the result and avoid name-based lookup.
+- Apply workspace settings, tool defaults, Connections, API Integrations, and profile versions through a versioned reconciliation step at provisioning, startup, deployment, or a controlled migration.
+- Do not patch the same workspace settings, preview the same API, or reinstall the same Integration on every message unless drift was detected.
+- Use stable idempotency keys for workspace/session creation and external mutations that support them.
+- Store non-secret mapping metadata: product boundary ID, OpenGeni workspace ID, runtime profile version, Integration instance/server ID, Connection ID, and relevant optimistic versions.
+- Define lifecycle handling for user disablement, tenant deletion, credential revocation, retention, and workspace cleanup.
+
+For a large existing customer population, choose lazy creation, a bounded backfill, or both. New product users can trigger the same idempotent provisioning path through the customer's normal lifecycle event. Do not require an OpenGeni human signup per product end user for service-backed sessions.
+
+## Verification matrix
+
+Adapt tests to the product, but cover the behaviors that can fail across the boundary:
+
+**Contract and configuration**
+
+- installed SDK types agree with the deployed service and client configuration;
+- desired model, reasoning, sandbox, capabilities, and API Integration server exist;
+- the intended OpenGeni-credit or externally billed model path is visible and attributed to the product boundary;
+- workspace settings and runtime profile reconciliation are idempotent; and
+- session creation retries converge on one session.
+
+**Identity and isolation**
+
+- product authentication is required for every proxy route;
+- product boundary IDs map to the intended distinct or shared workspaces;
+- cross-user and cross-tenant workspace/session ID substitution fails;
+- effective first-party and external tool policies contain only intended capabilities; and
+- provider endpoints enforce token tenant/user scope independently of prompts.
+
+**Session experience**
+
+- initial and follow-up messages reach the correct session;
+- SSE reconnect backfills by sequence without duplicated UI effects;
+- unknown additive events do not crash the client;
+- the chosen final-only, progress, or detailed projection behaves as intended;
+- approvals, human input, cancellation, failures, credit limits, and reconnection are actionable; and
+- accessibility and narrow/wide layouts match the host product.
+
+**Data and credentials**
+
+- happy-path tools return bounded structured data;
+- expired, revoked, wrong-scope, wrong-audience, and wrong-tenant credentials fail closed;
+- credential values do not appear in responses, events, logs, Skills, prompts, or browser bundles;
+- rotation succeeds without recreating unrelated state; and
+- unsafe or ambiguous writes are not replayed.
+
+Run the existing product test and build commands appropriate to the changed layers. Do not demand a live deployment test when the user retained deployment authority; provide the exact smoke test they can run instead. Do not deploy merely to make local tests pass.
+
+## Check the experience, not only the wiring
+
+Use ordinary product questions as well as directed tool smoke tests. Check that
+answers preserve important definitions and limitations, and that the agent admits
+when an analysis or action is unavailable. Prefer representative failure cases
+over a large checklist unrelated to the product.
+
+Include cases drawn from the actual product: misleading or instruction-like text
+inside retrieved data, an unavailable breakdown, a filter that affects only some
+metrics, or a request outside the allowed capabilities. Check that untrusted data
+stays evidence, not instructions, and that uncertainty is visible in the answer.
+Select relevant cases rather than imposing an analytics evaluation on every product.
+
+Inspect the effective executable tool surface and exercise the intended data tool.
+Attaching MCP definitions and selecting their server are separate; a reachable
+server does not prove the session selected it. Do not infer the absence of
+provider-native tools from the MCP or first-party allowlist alone. Report any
+capability the live deployment cannot constrain; prompts are not enforcement.
+
+For interactive experiences, observe formatting, progress, errors, follow-ups,
+reload/reconnect and stopping behavior. Measure time to useful output separately
+from total completion. Use the trace to distinguish startup, model work, tool
+latency and frontend buffering before changing models or transport. Mocks prove
+local behavior; record live checks that remain unavailable rather than claiming
+end-to-end success from mocks.
+
+## Handoff
+
+Report the implemented shape in product language:
+
+- what experience was added;
+- what product identity maps to a workspace and why;
+- where the organization key and provider credentials live;
+- how customer data becomes tools and how those tools authorize requests;
+- which runtime profile version, model, Skills, memory, approvals, and tools are selected;
+- what was tested, including negative isolation tests;
+- what was not executed because it remains customer-owned; and
+- exact remaining setup, review, deployment, monitoring, or rollback steps.
+
+Make any remaining setup executable by a fresh agent with the customer repository,
+public documentation, and ordinary customer access. Record verified non-secret
+origin and organization/workspace IDs, identity mapping, package/configuration
+versions, secret names and storage locations, plus runnable probes with expected
+results. Explain how an authorized owner can manage the created workspace without
+silently linking identities or widening membership. Complete discoverable setup
+before handoff; identify operator-only blockers separately and do not depend on
+internal source, cluster access, prior chat memory, or undocumented local helpers.
+
+If a durable customer integration Skill would reduce future rediscovery, generate one beside the integration code containing only stable, non-secret project facts and smoke probes. Do not turn the generic implementation Skill into the customer's analytics prompt, and do not make generated runtime behavior depend on the implementation workspace retaining this implementation Skill.

package/src/bundled_default_skills/opengeni-help/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: opengeni-help
+description: Answer questions about OpenGeni setup, product integration, SDK/API behavior, billing, GitHub access, and development setup. Read the official product docs before making product-specific claims or replacing an application's AI provider. No installation is needed for this bundled guide.
+---
+
+# OpenGeni product help
+
+Use this guide when the user asks about OpenGeni itself. Answer their latest
+question first, using the deployed service and installed SDK as contract evidence.
+This is product reference guidance, not the persona of a customer support bot.
+
+## Fetch the official documentation
+
+The public documentation index is **https://docs.opengeni.ai/llms.txt**. Fetch
+it with the available web or HTTP tool, then read the relevant pages. Markdown
+pages are available by adding `.md`, for example:
+
+- Product integration: https://docs.opengeni.ai/guides/integrate-your-product.md
+- Authentication: https://docs.opengeni.ai/reference/authentication.md
+- SDK: https://docs.opengeni.ai/reference/sdk.md
+
+Docs describe supported behavior; they do not prove that a particular deployment
+or installed package includes a feature. Check `/v1/config/client`, installed
+SDK exports/types, and authorized live configuration or probes. Report a failed
+documentation fetch explicitly and use another authoritative source. Do not
+ask the customer to supply OpenGeni's own API contract before trying these sources.
+
+For implementation, read the bundled `opengeni-client` Skill with `skill_read`
+and follow its relevant references. It is available by default without a Pack,
+installation, or repository clone. If an embedding host excludes it, respect
+that selection; the public product-integration guide remains reference material.
+
+## Integration and account setup
+
+OpenGeni's service API owns workspaces, sessions, turns, and events. A compatible
+`@opengeni/sdk/chat` package can provide a handler in the customer's backend for
+native, Vercel UI streams, or supported OpenAI-shaped chat formats. This does
+not make OpenGeni's service URL a universal OpenAI inference endpoint.
+
+Before replacing a provider, establish the customer's actual API usage:
+server-side generation/provider calls versus a frontend UI stream, streaming,
+tools, embeddings, authentication, history, and usage reporting. Generic client
+documentation cannot prove OpenGeni server compatibility. Do not invent SDK
+methods or routes. Verify embedding support independently; chat-format support
+does not imply `/embeddings`. Preserve an existing embedding provider unless a
+supported replacement is established.
+
+If the user wants account configuration and will update secrets themselves,
+resolve that account-side request before offering more application wiring.
+Inspect authorized configuration and setup tools. A product backend normally
+holds an organization API key; the browser never receives it. Separate an
+unavailable administrative action from an unknown protocol. State any exact
+human setup step that remains, rather than claiming the account is configured.
+
+## Discovery and integrations
+
+Tool search is ranked, not exhaustive. Recover a miss through `tool_list` and
+exact-name schema loading where available. Use `capability_catalog_search` for
+reviewed integration candidates and `skill_read` for available guidance. Missing
+`ogtool` is a local executable problem, not proof that a capability is absent.
+
+For connection setup, follow the shared Integration setup guidance and the
+catalog's returned next action. Account-management permissions and the ability
+to request human setup are separate.
+
+## Cost questions
+
+Read the installed SDK's reply types and formatter, then the relevant accounting
+contract. Model-picker labels show a billing category, not per-request cost.
+The current chat facade and Vercel/OpenAI formatters do not define a first-class
+monetary cost field. Recheck that statement against the installed version.
+
+`getBillingUsage` is a separate permissioned accounting read. Its presence does
+not mean the current credential may use it, that its bounded result covers the
+whole conversation, or that it adds cost to an AI SDK response. Distinguish
+charged OpenGeni credits, estimated provider cost, and externally billed usage.
+Zero OpenGeni charge does not establish zero upstream expense. A turn can contain
+multiple model responses. When response fields cannot be verified, say exactly
+what is unknown rather than answering “probably.”
+
+## Development dependency recovery
+
+Inspect the repository's runtime/version files, package manager, lockfile, and
+test commands before implementation. Probe the actual selected compute for the
+required versions. If dependencies are missing, install the declared versions
+within the authorized disposable sandbox, then rerun the checks. On a Connected
+Machine, respect its existing configuration and the user's authority over
+machine changes.
+
+Do not stop at `node: not found` or `pnpm: not found` when safe in-scope recovery
+is available. Keep dependency-install errors, report the exact remaining blocker,
+and distinguish code written, local commit, executed tests, verified integration,
+and publication. A diff/whitespace check does not validate execution.
+
+## Embedded agents choose their guidance
+
+The host can pass `bundledSkillIds: []` to exclude all bundled guides, or list
+only supported capability guides. This includes opting out of this guide.
+Workspace Skills, inline Skills, tool permissions, and ordinary runtime rules
+remain separate. Do not copy OpenGeni product or implementation guidance into
+the embedded agent's persona. Follow the product's explicit selections.