> ## Agent Instructions
> Use the current public BYOM documentation and cite the relevant page. Preserve availability, permission and undo limits.
> The public documentation MCP retrieves guides. Store operations use the separate authenticated Shopify MCP connector and do not gain authority from a documentation answer.
> If a contract, capability or price is not documented, say so. Do not invent endpoints, tools, availability or merchant outcomes.

# BYOM, in plain language
Source: https://docs.byom.co/ai

A concise, factual introduction to BYOM, Kina and the controls around commerce work.

**BYOM is the AI operating layer for commerce brands. Kina is its AI operator.** People use Kina to ask questions, analyse connected information and prepare work across their store, customer service and growth tools. BYOM brings the work, approvals and records together.

BYOM is the name of the company and its commerce product. Kina is the operator within it.

## The essential facts

| Question | Answer |
| - | - |
| Who is it for? | People working in commerce brands: founders, customer service, marketing, ecommerce and operations. |
| Does it replace Shopify or the helpdesk? | No. Connected tools continue to hold the underlying business records. BYOM helps the team work across them. |
| What is Kina? | The AI operator people work with inside BYOM. |
| What is an Action? | A proposed change with a defined scope and an approval path. A draft or recommendation is not evidence that a change happened. |
| What is a receipt? | The record of an attempted or completed operation and its outcome. Read the outcome before treating the job as finished. |
| Can every change be undone? | No. Undo depends on the operation, permissions, time limits and the current state of the connected system. |
| What is this site? | Public product and developer documentation. It does not grant access to a store or run actions in the app. |

## Where to find BYOM

* **[byom.co](https://byom.co):** BYOM's public website and current entry point for enquiries.
* **[app.byom.co](https://app.byom.co):** the authenticated product, where a permitted user works with their company.
* **These docs:** explanations, task guides and developer context. Account-specific information stays in the app.

## Start with the right source

Use [What is BYOM?](/start/what-is-byom) for the product definition, [Approvals](/product/approvals) for the decision boundary, and [Availability](/reference/availability) for how access and support are qualified. The [developer overview](/developers/overview) explains the separate Shopify connector.

Screenshots and worked examples marked **demo** or **illustrative** explain an interface or workflow. They do not establish a customer relationship, measured savings or a live integration outcome. A named integration does not imply every read or write is supported.

## Company and contact

BYOM LTD is registered in England and Wales, company number **17040817**. Questions about the product or these docs can go to [hello@byom.co](mailto:hello@byom.co).

Documentation reviewed: **2 October 2026**. Product access and supported operations can change; use the relevant guide and your account's current controls.


# Documentation updates
Source: https://docs.byom.co/changelog

What changed in this guide, and how to distinguish a documentation update from a product release.

This page records changes to the documentation. A documentation date does not mean a feature has been enabled for every account.

<Update label="2026-10-02" description="First edition">
  * Added an introduction to BYOM and Kina, a first-session guide and a glossary.
  * Explained HQ, Workspace, Integrations, Brand Memory, Readouts, Customer Service, Growth Engine and Rails.
  * Added guides for reviewing changes, improving product content, reading evidence and resolving common problems.
  * Separated the Shopify MCP connector from the wider BYOM app and from documentation search.
  * Documented how to interpret availability, permissions, billing and undo limits.

  The product images in this edition show a labelled demo workspace. They illustrate the experience; they are not customer results.
</Update>

## Documentation updates and product releases

A product release note should tell you what changed, who can use it, any action you need to take and any compatibility or behaviour change. A release announcement is separate from a proposed feature or an illustrative example.

For the current access boundary, read [Availability](/reference/availability). For help with an existing account, start with [Troubleshooting](/guides/troubleshooting) or contact [hello@byom.co](mailto:hello@byom.co).


# Authentication and consent
Source: https://docs.byom.co/developers/authentication

Use the OAuth flow and respect the merchant grant, resource binding and revocation.

The Shopify MCP connector uses OAuth authorisation-code authentication with PKCE. The merchant consents to client access; bearer tokens authorise calls only within the bound resource and grant.

This is the authentication flow for the store connector. The
[public documentation MCP](/developers/documentation-mcp) does not require a
merchant grant or a Shopify credential.

## What the client needs

Begin with the connector resource URL supplied by the enabled account, a
supported redirect destination for your client and an OAuth implementation
that supports PKCE `S256`. Keep the intended store visible to the person
connecting it. Do not infer a merchant's choice from a previously used account
or a successful connection to a different resource.

The flow has three distinct decisions: the merchant signs in, chooses the
appropriate store context, and consents to the client's requested access.
Completing sign-in alone is not the complete grant.

## Follow discovery metadata

Read the resource's protected-resource metadata and its advertised authorisation-server metadata. Use the advertised endpoints rather than constructing undocumented routes.

The supported flow uses the `code` response type, `authorization_code` and `refresh_token` grants, and the PKCE `S256` challenge method. Public-client metadata advertises token-endpoint authentication method `none`; store access still requires a valid token and grant.

A request without a valid bearer token receives HTTP 401 and a `WWW-Authenticate` challenge. Follow the supported authentication or reconnect flow instead of retrying the same invalid token indefinitely.

| Metadata | Why it matters |
| - | - |
| Protected resource and advertised authorisation server | Identifies which resource and authority the token is for. |
| `authorization_endpoint` | Opens the supported merchant sign-in and consent flow. |
| `token_endpoint` | Exchanges the code and later performs supported refreshes. |
| `revocation_endpoint` | Provides the advertised token-revocation operation. |
| Client registration or client-ID metadata support | Describes how this client identifies itself and its redirect destinations. |
| Supported response, grant and challenge methods | Prevents the client from assuming an unsupported flow. |

The connector advertises client-ID metadata document support alongside dynamic
client registration. A compatible client can use its stable metadata identity;
otherwise follow the advertised registration mechanism. Register only the
redirect destinations used by the client. An OAuth metadata document
is not a promise of a separate BYOM user-management API.

## Complete the flow

<Steps>
  <Step title="Discover the resource and authorisation server">
    Read the metadata advertised by the intended connector. Preserve the
    resource identity throughout authorisation and token use.
  </Step>

  <Step title="Prepare PKCE and the redirect">
    Use a fresh verifier and its S256 challenge through your OAuth client.
    Preserve the verifier and the client's request state for the return; do
    not put either into the model's prompt.
  </Step>

  <Step title="Let the merchant choose and consent">
    Send the person through the supported authorisation page. Explain the
    requested data access and write-proposal setting. If the person cancels,
    return a cancelled connection state instead of repeatedly opening consent.
  </Step>

  <Step title="Exchange the returned code">
    Use the advertised token endpoint, matching client, redirect, PKCE
    verifier and resource. Treat a refused exchange as an authentication
    failure; never fall back to an unrelated store credential.
  </Step>

  <Step title="Verify the authorised context">
    Initialise MCP, call `about_this_connection` and confirm the store and
    grant before retrieving business information. Then discover the current
    tool list.
  </Step>
</Steps>

## Consent has a scope

A grant is associated with the merchant, company, store and client context. It records consented data classes and whether supported write proposals are enabled. Provider scopes remain a separate requirement: a grant cannot give BYOM a Shopify permission that the store has not granted.

New data classes need appropriate consent. Discover the tools available after authorisation rather than assuming that another merchant's connection exposes the same capabilities.

For example, a merchant may permit product information while withholding
customer-related information. That is a valid, narrower connection. Your
client should explain what it can do with that grant and ask for a separate
consent change only when the person's requested task needs it.

Check each permission boundary:

* **Identity and resource:** is this token valid for this connector resource?
* **Merchant grant:** has this client been allowed the needed data class and tool?
* **Provider permission:** does BYOM hold the required Shopify scope?
* **Effect approval:** has the specific consequential change received the required decision?

Passing one does not bypass the others. Changing a client label or requesting
broader wording in a model prompt changes none of those permissions.

## Token handling

Send bearer tokens in the authorisation header. Keep access and refresh tokens in suitable client storage. Never put them in a model prompt, shared screenshot, source-control file or query-string example.

Tokens can expire or be revoked. Use the supported refresh flow when appropriate; reconnect when the grant is no longer valid. Disconnecting access and asking for stored-data deletion are separate operations.

A refresh grant is part of the original resource-bound authorisation. It is
not a mechanism for moving access to another company or expanding consent.
Handle a refused refresh by showing a clear reconnect state. Avoid a loop in
which every failed data request retries the same rejected token.

If credentials are exposed, remove them from the exposed location and use the
appropriate revocation and reconnect process. Stop using the compromised credential. Contact BYOM using
non-sensitive request details if you need help; never send a token in a support
message or screenshot.

## Diagnose a connection problem

| What you observe | What to check next |
| - | - |
| Sign-in completes but no tools are usable | Confirm the consent flow completed, then check the store and data classes with `about_this_connection`. |
| The code exchange is refused | Check the matching client, redirect, resource and PKCE state; begin a fresh supported flow if the previous one is no longer valid. |
| HTTP 401 during a call | Read the authentication challenge and use refresh or reconnect as appropriate. Do not repeatedly replay the invalid token. |
| A tool returns `not_allowed` | The token may be valid while the grant is too narrow. Inspect current consent. |
| A tool returns `scope_missing` | Fix the store's provider permission through the supported flow; client consent alone cannot supply it. |
| The wrong store is shown | Stop the workflow and reconnect to the intended store before asking for business data. |

## Human confirmation remains separate

A bearer token for a model client does not grant blanket authority to confirm store changes. Use the supported merchant review interface for consequential effects.

A client can retrieve information and prepare a proposal when its grant allows
it. The merchant's decision belongs in the review interface. Preserve the
before-and-after change and the outcome record; do not turn a successful OAuth
connection into a blanket “approve all future actions” setting.

Reviewed 2 October 2026.

## Related guides

* [MCP connector](/developers/mcp)
* [Data and access](/trust/data-and-access)
* [Errors, limits and retries](/developers/errors-and-limits)


# Connect to the documentation MCP
Source: https://docs.byom.co/developers/documentation-mcp

Give your AI assistant access to the BYOM documentation, with source links and a clear separation from your store.

Connect your AI assistant to the BYOM documentation so it can find a workflow,
check a developer contract and link you to the source. The documentation MCP
reads the public guides on this site through Mintlify's hosted service. It has
no access to company or store records and cannot approve Actions.

The public server is available at **`https://docs.byom.co/mcp`**. It was checked
on 2 October 2026 with a real remote HTTP MCP client: connection, tool discovery,
retrieval across all 29 published articles and source-linked searches passed.
Use the articles directly if your client cannot connect, and cite the current
page when applying an answer.

## Choose the right MCP

| You want to… | Use |
| - | - |
| Understand BYOM, a workflow, a supported contract or a limitation | This **public documentation MCP** |
| Read permitted Shopify information or prepare an operation for a store | The **authenticated [Shopify connector](/developers/mcp)**, with the merchant's consent |

The documentation MCP needs no store credentials. Never paste Shopify tokens,
BYOM credentials or customer records into a documentation search or feedback
tool. Access to public docs does not grant access to the product.

## Connect your assistant

Add a remote HTTP MCP server in your client's connector or MCP settings:

```text theme={"dark"}
https://docs.byom.co/mcp
```

Use a client that supports remote MCP over HTTP. The client performs the MCP
initialisation handshake and discovers the tools with `tools/list`. Tool names
are supplied by the server; discover them instead of hard-coding a name from
another Mintlify site.

Mintlify supports hosted-server discovery at
[`/.well-known/mcp`](https://docs.byom.co/.well-known/mcp). Mintlify provides a
JSON alias at `/.well-known/mcp.json` and tool descriptions through
`/.well-known/mcp/server-card.json`. These routes are available. The platform
may advertise an equivalent hosted alias; use **`https://docs.byom.co/mcp`**
when configuring BYOM directly. A discovery card alone does not prove that
your particular client has connected successfully.

The server provides documentation search and a read-only virtual documentation
filesystem. The filesystem is the public article corpus, not BYOM's server or
your computer. A separate feedback tool can submit a documentation-quality
report; it does not perform a store operation. Read each discovered tool's
description before using it.

## Use your preferred client

The **More actions** menu beside **Copy page** offers two different kinds of
handoff. **Open in ChatGPT**, **Open in Claude** and **Open in Perplexity** provide
context about the current page. **Connect to Cursor** and **Connect to VS Code**
prepare the remote documentation MCP connection, which can retrieve across the
public corpus. Review the connection your client proposes before adding it.

| Client | Whole-documentation connection |
| - | - |
| Claude | Add the server URL as a custom remote connector where your account or workspace allows it. Claude Code also supports remote MCP servers. |
| ChatGPT | Use a custom MCP app where developer mode and your workspace policy allow it. The page-handoff button alone does not install the connector. |
| Codex | Add a remote HTTP MCP server using the command below, then check that tools are available in your session. |
| Cursor | Use **Connect to Cursor**, or add the server URL in its MCP settings. |
| VS Code with GitHub Copilot | Use **Connect to VS Code**, or add an HTTP server to the supported MCP configuration. Organisation policies may restrict installation. |
| Gemini CLI | Configure a remote MCP server with `httpUrl` set to the URL above. Gemini's CLI configuration is separate from a browser page handoff. |

For a current Codex CLI, the registration command is:

```bash theme={"dark"}
codex mcp add byom-docs --url https://docs.byom.co/mcp
```

This command changes your local client configuration. It does not log in to
BYOM, connect a store or verify that the remote server is healthy. After adding
the server, ask a question from the examples below and check the returned source.
Client features and account permissions vary; an unsupported client can still
use **Copy page** or the article's Markdown version.

For current client-specific controls, see the official guides for
[Claude connectors](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp),
[Claude Code](https://code.claude.com/docs/en/mcp),
[ChatGPT MCP apps](https://help.openai.com/en/articles/12584461-developer-mode-and-mcp-apps-in-chatgpt),
[Cursor](https://prod.cursor.com/help/customization/mcp),
[VS Code](https://code.visualstudio.com/docs/agent-customization/mcp-servers) and
[Gemini CLI](https://geminicli.com/docs/tools/mcp-server/).

## Read without a connector

Copy an individual page as Markdown, or append `.md` to its article URL. The
hosted site also provides a documentation index at `/llms.txt` and a full-text
export at `/llms-full.txt`. The public `/skill.md` explains the main workflows
and the boundaries an assistant should preserve. These are public reading
formats; they do not require access to your merchant account.

## Ask questions that lead to useful sources

For example:

* “How does BYOM separate approval from execution? Link to the relevant guide.”
* “Which MCP transport does the Shopify connector support, and what does a 202 notification mean?”
* “What should I check when a tool is missing from my connector?”
* “When can an operation be undone? Include the limits.”
* “How do HQ and Workspace differ?”

Ask your assistant to cite the pages it used and preserve the limitations in
those pages. For implementation work, read the linked contract and confirm the
current tools and permissions in your enabled account. A documentation answer
is not evidence that a feature is enabled for a particular company.

## What is included

The public corpus covers the product, task guides, developer documentation,
trust, availability and documentation updates. Private product source, internal
plans and account-specific data are excluded. The public documentation is the
source of truth for this server; it does not inspect BYOM's private repositories.

## If an answer or connection is missing

Check the server URL and your client's remote-HTTP support first. If a recent
page is absent from search, open the page directly and use its **Copy page**
menu; search indexing may lag a documentation update. Do not repeatedly retry
an unchanged failure. Report the page URL and a non-sensitive description to
[hello@byom.co](mailto:hello@byom.co).

If the docs do not answer your question, ask the assistant to say what is
missing. Confirm an undocumented endpoint, permission or availability claim
with BYOM before relying on it.

Reviewed 2 October 2026.

## Related guides

* [Developer overview](/developers/overview)
* [Shopify MCP connector](/developers/mcp)
* [Authentication and consent](/developers/authentication)
* [Availability](/reference/availability)


# Errors, limits and retries
Source: https://docs.byom.co/developers/errors-and-limits

Handle authentication, protocol and tool failures without duplicating store effects.

Handle a connector failure according to its layer: HTTP authentication, JSON-RPC framing or the tool's reported result. An HTTP 200 does not by itself mean a store operation completed.

## Find the layer that failed

| Layer | What to inspect | Example |
| - | - | - |
| HTTP and authentication | Status, authentication challenge and whether a body is expected | HTTP 401 requires authentication; a notification's empty HTTP 202 is normal. |
| JSON-RPC | The top-level `error` or `result`, and matching request `id` | `-32601` means the requested method is unknown. |
| Tool result | `result.isError` and the structured result | A valid tool call can return `not_allowed`. |
| Business operation | Actual proposal, execution and receipt state | A prepared or approved change has not necessarily completed. |

Check these in order. A client that attempts to parse every response as a
successful tool payload will misreport normal notifications and hide useful
authentication or permission failures.

## Tool failures

The connector returns these machine-readable tool codes. Read the accompanying message for the specific next step.

| Code | Meaning and response |
| - | - |
| `not_allowed` | The current grant does not allow the capability. Inspect consent and `about_this_connection`. |
| `scope_missing` | A required provider permission is absent. Address the provider permission separately. |
| `store_disconnected` | The store link is unavailable. Reconnect through the supported flow. |
| `limit_reached` | A usage or rate allowance has been reached. Inspect the allowance and reset information. |
| `expired` | The relevant proposal or authority has expired. Prepare and review a current proposal. |
| `drift` | The reviewed source or proposal state changed. Review the new state. |
| `shopify_error` | The provider operation failed or could not be completed as requested. Read the result before retrying. |

A tool failure is represented inside the JSON-RPC result. This example uses a
fictional message; branch on the stable code, not its exact prose:

```json theme={"dark"}
{
  "jsonrpc": "2.0",
  "id": 8,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "This connection does not allow the requested capability."
      }
    ],
    "structuredContent": {
      "error": {
        "code": "not_allowed",
        "message": "This connection does not allow the requested capability."
      }
    },
    "isError": true
  }
}
```

The client should preserve the code for handling and show an understandable
next step to the user. Do not send the entire credential-bearing request to
logs or to a model in an attempt to explain the error.

## Protocol and authentication

HTTP 401 requires an authentication or reconnect step. Malformed JSON and invalid JSON-RPC requests are different from a valid tool call that returns a failure. Standard JSON-RPC framing errors include parse error `-32700`, invalid request `-32600`, unknown method `-32601` and invalid parameters `-32602`.

Tool results can carry `isError`; handle that field as well as the top-level JSON-RPC error. Keep the request ID so the client can associate a response with the correct request.

An unknown tool and an unknown JSON-RPC method are separate mistakes. Use the
names returned by `tools/list`, then supply arguments matching that tool's
schema. Rewriting an invalid call in a retry loop will not repair a stale
schema unless the client re-discovers and validates the contract.

Notifications have no request ID. The connector answers an accepted
notification with HTTP 202 and an empty body. GET and DELETE on the MCP
transport return HTTP 405; this connector does not require an event stream or
session deletion as part of normal operation.

## Limits

A JSON-RPC batch can contain at most 20 requests. Batching is a transport convenience, not a bulk-store-write permission. Connector rate controls and plan allowances are separate from the general BYOM subscription. Read the active allowance through the connection and account surfaces rather than treating a documentation figure as a permanent entitlement.

An empty batch or a batch above the size limit is invalid. Keep a unique
request ID for every call that expects a response and match results by that
ID. A batch containing a set of requests does not make them an atomic
transaction across Shopify records.

Tools that list business records can have pagination and input limits. Use the returned
schema and paging fields. When a long field is shortened in a list response,
retrieve the specific record before using the missing text in a decision.
Do not silently treat a truncated list as the entire catalogue.

`about_this_connection` reports monthly read/write usage and reset dates.
That context helps explain `limit_reached`; a lower-level provider limit or
temporary rate restriction may still need its own recovery step. The account's
active allowance is authoritative, not an example number in a guide.

## Retry safely

Back off read requests when a transient provider or rate condition warrants it. Do not retry revoked consent, invalid arguments or drift unchanged.

For any uncertain consequential result, inspect the receipt and provider state first. A timeout may follow a successful provider change. Blind retries can duplicate effects.

| Situation | Recovery |
| - | - |
| Temporary failure of a read | Retry a bounded number of times with backoff when the response supports doing so; surface the failure if it persists. |
| Invalid arguments or unknown method | Correct the implementation and validate against the current schema. |
| Expired or revoked authentication | Refresh or reconnect through the supported flow. |
| Missing consent or Shopify scope | Explain the missing permission and use the appropriate consent/provider setup path. |
| Expired proposal | Prepare a current proposal and obtain the required decision again. |
| Source drift | Show what changed and review a fresh proposal. |
| Uncertain write outcome | Stop automatic retries and inspect the actual receipt and provider record. |

For example, a product-title update may have reached Shopify before the client
lost its response. First establish whether that exact change happened. A successful read-back or receipt can resolve
that uncertainty; a second mutation can make it worse.

Do not manufacture an idempotency header or reuse an expired proposal token
for a store write. Use the connector's supported proposal and recovery flow; no arbitrary client-selected idempotency-key contract is documented here.

## Versioning

Negotiate MCP at initialisation and use discovered schemas. Recheck tool discovery after reconnecting or changing consent; do not assume that a saved list remains the current contract.

## Give support enough context

Keep the approximate time, client name/version, negotiated protocol version,
request ID, tool or method name, status/error code and whether the request was
a read or a proposed effect. Describe the observed result and what you expected.
Exclude bearer tokens, refresh tokens, customer records and raw private
payloads. That is enough to start diagnosing most integration failures without
turning a support request into a data disclosure.

Reviewed 2 October 2026.

## Related guides

* [MCP connector](/developers/mcp)
* [Authentication and consent](/developers/authentication)
* [Receipts and undo](/product/receipts-undo)


# MCP connector
Source: https://docs.byom.co/developers/mcp

Discover tools, negotiate the protocol and keep proposal confirmation under merchant control.

The BYOM Shopify connector uses MCP over a stateless Streamable HTTP endpoint. Use the connector URL shown in your enabled account.

This page documents the **store connector**. To let an assistant read these
public guides without store access, use the separate
[documentation MCP](/developers/documentation-mcp).

## Before you start

You need an enabled connector account, the intended merchant's consent and a
client that supports OAuth and remote Streamable HTTP. If you are implementing
a client, keep authentication separate from the model's conversation context.
Use discovery metadata for server URLs and `tools/list` for tool contracts.

## Initialise and discover

Use an MCP client that supports OAuth and Streamable HTTP. Complete authorisation, send `initialize`, then the initialised notification and `tools/list`. The server returns the tool names, descriptions and input schemas visible to the current grant.

The connector supports protocol revisions `2025-11-25`, `2025-06-18` and `2025-03-26`. Use the version returned by negotiation. This connector does not offer the legacy HTTP+SSE endpoint merely because an older protocol revision is recognised.

The transport handles JSON-RPC POST requests. It does not provide a server-initiated event stream or require a session ID. A notification can return HTTP 202 with no response body. Do not parse that empty body as a failed JSON result.

For a client implementation, the opening request has this shape. The client
name and version below are illustrative; the bearer token belongs in the HTTP
authorisation header, not in this JSON body.

```json theme={"dark"}
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-11-25",
    "capabilities": {},
    "clientInfo": {
      "name": "catalogue-review-client",
      "version": "1.0.0"
    }
  }
}
```

Read `result.protocolVersion`, `result.capabilities`, `result.serverInfo` and
the returned server instructions. Use the negotiated version rather than
assuming the requested one was accepted. Then send:

```json theme={"dark"}
{
  "jsonrpc": "2.0",
  "method": "notifications/initialized"
}
```

That notification has no request ID and no JSON-RPC response body. A subsequent
tool-discovery request does have an ID:

```json theme={"dark"}
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/list",
  "params": {}
}
```

The store connector does not accept GET or DELETE on its MCP transport route.
A browser opening that route is not an end-to-end connection test. Discovery
documents and OAuth pages are separate HTTP resources.

## A safe first tool

The read-only `about_this_connection` tool describes the store, consented data classes, whether writes are enabled, provider scopes and monthly usage with its reset date. It is a useful starting point when another tool is missing or refused.

For example, after initialisation a client may send:

```json theme={"dark"}
{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "about_this_connection",
    "arguments": {}
  }
}
```

The tool's structured result includes these fields:

| Field | How to use it |
| - | - |
| `store.domain`, `store.name`, `store.timezone` | Confirm that you are operating in the intended store and interpret dates appropriately. |
| `client_label`, `user` | Explain which connected client and user context is involved; do not expose it in public logs. |
| `data_classes` | Identify what this grant is allowed to read. |
| `writes_enabled` | Determine whether supported store-change proposals are enabled; this is not an approval for a particular change. |
| `plan`, `caps.reads`, `caps.writes` | Inspect active usage and caps. Each cap includes `used`, `limit` and `resets_at`. |
| `scopes_held` | Check the Shopify permissions available to BYOM. |
| `support_url` | Use the support destination returned for this connection. |

`store.name`, `store.timezone` and `user` can be null. Handle an absent label or
timezone explicitly rather than assuming a value from the client or another
store.

For example, a valid grant may allow catalogue reads while
`writes_enabled` is false. A client can still help the merchant understand a
product and prepare wording; it must not present store execution as available.

## Use the discovered contract

Use `tools/list` as the current contract for your grant. A catalogue read, brand-context query and growth query can require different data-class consent. If a tool is missing, check the grant and account capability before continuing.

Tool definitions include an input schema and may include an output schema,
annotations and UI metadata. Validate arguments against the schema you
received. Preserve structured output for the client; do not depend on the
wording of a human-readable summary as a machine contract.

The server advertises tool, resource and prompt discovery at initialisation.
Use `resources/list` and `prompts/list` when those capabilities are useful to
your client. Do not assume that resource subscriptions or list-change
notifications are available: the current connector declares them disabled.
Re-discover after reconnecting or changing consent.

## Proposals and confirmation

A proposal can show before-and-after changes and hand the merchant to the supported review interface. Confirmation and rejection tools are app-only; they are not part of the model-visible tool list. Preserve that separation in client integrations. If the client cannot display the supported review interface, do not invent a model-driven substitute.

Keep the full proposal details in the supported review UI. A summary written
by the model cannot replace the actual target, fields, proposed values and
current state that the merchant is approving. Expiry and drift are meaningful
refusals: obtain a current proposal and a new decision when required.

## Check your first integration

Start with a small read and confirm the returned store, request ID and result.
Then exercise a refused request with a deliberately narrower test grant, not
real customer data. Your client should explain missing consent, provider
permissions and usage limits without leaking tokens or silently changing
stores. Test proposal UI separately from read access.

The examples here describe request shapes. Verify the requests with your own authorised test connection before relying on the integration.

Reviewed 2 October 2026.

## Related guides

* [Authentication and consent](/developers/authentication)
* [Errors, limits and retries](/developers/errors-and-limits)
* [Approvals and Actions](/product/approvals)


# Developer overview
Source: https://docs.byom.co/developers/overview

The supported connector contract, its access model and the boundary around store changes.

BYOM's documented developer integration is its Shopify MCP connector. It lets supported AI clients discover tools and work with a merchant's authorised store context. These docs do not define a general public REST API or webhook subscription service.

## Choose what you are connecting

The BYOM application is the merchant's governed work environment. The Shopify connector exposes consented capabilities to an external AI client. The public documentation MCP lets a compatible client find and read these guides without store access. See [Connect to the documentation MCP](/developers/documentation-mcp) for its URL and current checks.

| Surface | Who uses it | What it can access | Where to begin |
| - | - | - | - |
| BYOM application | An enabled member of a commerce company | The company context and capabilities permitted to that member | [Your first session](/start/first-session) |
| Shopify MCP connector | An AI client authorised by the merchant | Data classes, tools and supported proposals allowed by its grant | [MCP connector](/developers/mcp) |
| Documentation MCP | A compatible AI client reading these docs | Public documentation only | [Connect to the documentation MCP](/developers/documentation-mcp) |

You can configure both MCPs in one client, with distinct names such as **BYOM
docs** and **BYOM store**. Keep their URLs, permissions and data separate. A
successful documentation search does not mean a store is connected.

The Shopify app is coming to the App Store. Contact BYOM about access and confirm that your AI client supports the connector.

## The integration lifecycle

A client discovers the authorised resource and OAuth metadata, completes the merchant consent flow, initialises MCP and lists the tools visible to that grant. It calls the discovered tool with arguments matching the returned schema, then handles both protocol errors and tool-level failures.

Do not hard-code an assumed list of available tools. Visibility depends on the grant's data classes, write enablement and current account capabilities.

<Steps>
  <Step title="Confirm access and the task">
    Obtain the connector URL from the enabled account. Identify which store and
    data classes the integration needs. A client reading a product catalogue
    needs a different grant from one working with customer-service information.
  </Step>

  <Step title="Let the merchant authorise the client">
    Follow the resource and OAuth metadata. Use the supported PKCE flow; keep
    the merchant's consent and resource binding intact. Do not collect a store
    password or put a bearer token into a conversation.
  </Step>

  <Step title="Negotiate and inspect">
    Initialise MCP, discover tools and call `about_this_connection`. Confirm
    the store and returned permissions before making a business-data request.
  </Step>

  <Step title="Prove a small read">
    Choose an advertised read tool, follow its input schema and inspect both
    the structured result and the error flag. Verify the answer against the
    intended record before adding a larger workflow.
  </Step>

  <Step title="Add proposals only where supported">
    If the client and grant support proposals, preserve the merchant-facing
    review interface. Check the eventual result and receipt rather than
    treating proposal creation as execution.
  </Step>
</Steps>

## Keep the effect boundary

A model may read and prepare a proposal. Confirmation authority stays with the merchant-facing review interface. A client must not treat a model's “yes” as a merchant's approval.

Show the returned status clearly. **Prepared** means there
is work to review. **Approved** means the required decision was recorded.
**Executed**, **failed** or **partial** describes the attempt's outcome. Read the
returned state instead of collapsing all three into “done”. The supported
review surface may combine confirmation with execution; do not insert an
invented second confirmation or bypass the one that is required.

## Example: a catalogue-review assistant

Suppose a merchant wants help improving a product description. First confirm
that the grant can read the relevant catalogue information. Retrieve the
specific product through a discovered tool and ask the model to distinguish
source facts from suggested wording. A list result may contain shortened text;
use the specific record's retrieval tool when the full text matters.

Present the draft and its rationale. If a supported proposal tool is visible,
the integration can prepare the change for the merchant's review. If it is
absent, retain the draft as internal work and explain the limitation. Never
invent a direct write endpoint to complete the workflow.

## What a useful integration must handle

* The merchant cancels authorisation or chooses a different store.
* A read is allowed but a proposal capability is not.
* A provider permission is missing despite a valid BYOM grant.
* A tool returns `isError: true` inside an HTTP 200 response.
* Source data changes between a proposal and confirmation.
* A timeout leaves the result uncertain.
* Consent is revoked or the connection is disconnected.

Treat these as normal product states with clear recovery instructions. The
[errors guide](/developers/errors-and-limits) explains which failures need a
user action and which may justify a bounded retry.

## UCP and commerce readiness

The [Universal Commerce Protocol (UCP)](https://ucp.dev/) describes commerce
interactions such as product discovery and checkout. Each implementation
supports its own capabilities. A catalogue assessment or successful product
lookup does not establish checkout or payment support.

For BYOM's documented client integration, use the Shopify MCP contract above.
Confirm any commerce capability against your enabled account and the relevant
provider before building on it. These docs publish no UCP checkout or payment
API. The [product-content guide](/guides/improve-product-content) explains how
to use available AI-shopping readiness evidence to choose a useful catalogue
improvement.

Reviewed 2 October 2026.

## Related guides

* [MCP connector](/developers/mcp)
* [Documentation MCP](/developers/documentation-mcp)
* [Authentication and consent](/developers/authentication)
* [Errors, limits and retries](/developers/errors-and-limits)
* [Availability and access](/reference/availability)


# Improve product content
Source: https://docs.byom.co/guides/improve-product-content

Prepare clearer product information from verified facts and brand guidance.

Use Kina to turn verified product facts into clearer descriptions, care guidance and answers to customer questions. This guide takes one product from its source facts to a reviewed edit, then explains how to check the result.

## Choose a small starting set

Pick one product or a bounded group with a clear problem: missing care instructions, a vague material description or inconsistent tone. Name the product so Kina can use the correct source.

Try:

> Review this product description for clarity. Keep the verified material, dimensions and care facts. Use our brand guidance, flag unsupported claims and show a before-and-after draft. Prepare the change for review.

## Inspect the draft

Check that sizes, composition, compatibility and care instructions match the source. Promotional language can accidentally become a factual promise. Terms such as “certified”, “waterproof” or “guaranteed” need evidence appropriate to the product.

If a fact is missing, ask for the gap to be identified. Do not fill it with plausible wording. A shorter description that preserves the facts can be better than a longer unsupported one.

## Prepare the source pack

You need the correct product record, current brand guidance and evidence for any factual claims. Start with the supported catalogue read. If relevant guidance is missing, identify it before drafting rather than asking Kina to invent a complete specification.

Create a short factual checklist:

* Material or composition, using the product's own source.
* Dimensions, size or compatibility where verified.
* Care, use or safety instructions where applicable.
* A customer question the description should answer.
* Any phrase requiring evidence, such as a certification or performance promise.

Brand tone shapes how you explain these facts. It does not authorise new facts.

## Work through a fictional product

North Coast Goods sells a cotton-blend overshirt. The current description says “A premium everyday essential”. The source gives the blend and a washing instruction but does not substantiate an environmental claim.

Ask Kina:

> Use the connected product facts to explain the material and care more clearly. Keep the wording plain and practical. Show the existing and proposed description, list the source facts you retained and flag anything you could not verify.

A useful draft replaces vague praise with the supported facts. It keeps “cotton blend” rather than converting it to pure cotton, preserves the correct washing instruction and omits unsupported certification language.

Then refine: “Keep the opening to one sentence and make the care instruction easy to find.” This remains preparation. When you are satisfied, ask for the supported product change to be prepared for review.

## Apply only the intended fields

Open the proposed change in Approvals. Check **Before** and **After** for every affected field and product. Confirm that the request did not expand from a description into a title, price or other unrelated change.

Read whether your confirmation also makes the change or whether a separate execution control follows. After the effect, inspect **View receipt**. Verify the individual result and the provider record where appropriate. If one product's source changed, resolve that item without assuming the whole batch completed.

## Evaluate what the edit achieved

A good immediate outcome is accurate, clearer content on the intended record. A commercial outcome requires a separate measurement.

Before judging performance, define the metric, dates and comparable baseline. If a promotion, traffic mix or stock level changed, retain those qualifications. An increase after the edit is not by itself proof that the wording caused it. Use Readouts or the available Results evidence to inspect the calculation and coverage.

## Assess AI-shopping readiness

Where **Growth Engine → Discovery** is enabled, use the AI-shopping readiness information to find a concrete next job. Inspect the current report, its source and the product-level issues before asking for repairs. If a catalogue scan is available to your role, use it to check the current catalogue; a scan reads and assesses information rather than publishing a product change.

Keep two questions separate. **Catalogue readiness** asks whether product information is present and usable: descriptions, images and their alt text, search titles and descriptions, tags, variant SKUs and relevant shop policies. **Shopping or transaction readiness** can assess a different set of protocol and purchase requirements. Improving a description does not establish that a shopping assistant can complete a purchase.

Start with an issue the evidence supports. For example, a linen shirt might have a short description and images without alt text. Ask Kina to draft a factual description from its verified material and care facts, and describe what each photograph shows. Review the product identity and changed fields before applying any supported repair. A product with stock but not published may be deliberately held back; investigate that decision before requesting publication.

A readiness score summarises the checks performed. It is not a guarantee of an AI recommendation, search ranking, checkout compatibility or sales. More words alone do not make content accurate. Missing or unavailable evidence is also different from a failed check: resolve source access before treating an incomplete report as a poor catalogue.

After an approved repair completes, check the receipt and refresh the assessment through the available control. Compare the specific issue before and after, alongside the headline score. A better score demonstrates a change in those checks; measure discovery and commercial results separately.

## Targeted recovery

If the product cannot be found, verify the company, source and product identity. If facts disagree, stop the factual rewrite and ask for the conflict to be shown. If the proposal expires, prepare and review a current version. If the execution result is uncertain, inspect the receipt before repeating the request. If the change was wrong, use the supported reversal when available rather than assuming every content field can be restored.

Reviewed 2 October 2026.

## Related guides

* [Brand Memory](/product/brand-memory)
* [Review a proposed change](/guides/review-a-change)
* [Growth Engine](/product/growth-engine)


# Review a proposed change
Source: https://docs.byom.co/guides/review-a-change

A practical checklist for approving the right version and checking the result.

Review a change by checking the exact target and before-and-after proposal, then inspect its receipt after execution. This helps you approve the right fields and catch an incorrect claim or target before it reaches the connected service.

<Steps>
  <Step title="Open the proposed change">
    Use the decision link from the work record, HQ or Approvals. Confirm that it belongs to the expected company and task.
  </Step>

  <Step title="Check every affected record">
    Read the operation, product or other target, and every field being changed. For a batch, review the whole batch rather than a representative item.
  </Step>

  <Step title="Check the reason and risk">
    Verify source facts and policy. Read the reversal information. Ask for revisions if the proposal contains unsupported claims or an incorrect destination.
  </Step>

  <Step title="Make the decision">
    Approve only the version you have reviewed, or reject it. If your role cannot decide, use the appropriate company approver; do not try to bypass the control through conversation.
  </Step>

  <Step title="Read the receipt">
    Check which operations completed. Treat partial and uncertain outcomes explicitly. Resolve those before repeating work.
  </Step>
</Steps>

## Example

A proposal updates a product's title and description. The description is correct, but the title changes the model number. Reject or revise the proposal before approval; an otherwise useful draft is not a reason to accept an incorrect field.

## If something changed during review

A newer product value or an edited proposal can invalidate the reviewed version. Reopen the current proposal and check it again. Earlier approval is not permission for unseen changes.

## Before you start

Have the correct company, a current proposed change and access to the evidence behind it. You need an account permitted to decide; some changes require a second approver or an additional sign-in check. Do not ask a colleague to approve from a detached screenshot when they can inspect the current proposal itself.

## Check what confirmation will do

The review uses **Approve** and **Reject**. In Kina, a supported confirmation can both approve and make the change. Elsewhere, approval can be followed by a separate **Make the change** control, or **Send to your helpdesk** for an eligible helpdesk operation.

Before confirming, read what that particular step will do. If the proposal is only accepted for editorial review, that does not approve media rights, publication or campaign spend. If the change is approved but not made, the view can state that it has not been made in the provider yet.

Use **View receipt** to inspect the detailed operation and result. If a request has an uncertain outcome, **Check status** can be offered instead of an immediate repeated execution. Follow that recovery path.

## Worked review: three product descriptions

North Coast Goods has a batch covering three products. Two descriptions use verified materials and care facts. The third replaces “cotton blend” with “100% cotton”.

| Review question | Evidence to inspect | Decision |
| - | - | - |
| Are these the intended products? | Product names and target records. | Stop if a similarly named product was selected by mistake. |
| Are all changed fields expected? | Every Before and After value. | Revise an unexpected title, price or field change. |
| Are claims supported? | Each product's own composition and care facts. | Correct the third description before approving. |
| Can this effect be reversed? | The specific reversal information. | Accept the risk deliberately; do not assume universal Undo. |
| What completed? | Individual execution results. | Preserve any partial or unresolved result. |

Retain the blend description unless a verified source proves the exact composition. You can continue refining the draft internally without authorising an incorrect store change.

## Finish the review with a result check

Your expected outcome is a recorded decision about the right version and, if the effect was requested and completed, a receipt for the correct provider operation.

If one item fails after others complete, inspect why before submitting a fresh batch. If the source changed between review and execution, compare the new state. If an undo is offered, it is a separate effect with its own checks; after using it, read its result too.

When sharing completion with a colleague, link the work and receipt rather than saying “approved” when you mean “made in the store”.

Reviewed 2 October 2026.

## Related guides

* [Approvals and proposed changes](/product/approvals)
* [Receipts and undo](/product/receipts-undo)
* [Troubleshooting](/guides/troubleshooting)


# Troubleshooting
Source: https://docs.byom.co/guides/troubleshooting

Identify whether the next step is an access fix, a revised proposal or a result check.

Start troubleshooting by identifying the stage that stopped: source access, preparation, approval or execution. That tells you whether to fix access, revise the work or check a result before trying again.

| What you see | What to check next |
| - | - |
| No store evidence | Correct company, connection state and provider permissions. |
| Unavailable Readout | The named missing source and requested date range. |
| Unsupported draft claim | Source facts and brand guidance; revise before approval. |
| Approval control unavailable | Your role and the proposal's current state. |
| Expired or changed proposal | Prepare or reopen the current version and review again. |
| Partial execution | Individual results in the receipt. |
| Timeout or uncertain result | Receipt and provider state before retrying. |
| MCP authentication failure | Reconnect through the supported consent flow. |

## Example

Kina can read a product but cannot prepare a supported update. Check the change capability and provider permission before treating this as an approval problem. For an approved change, inspect the receipt to establish whether it finished.

## Avoid duplicate effects

Do not repeatedly resubmit a change while its result is uncertain. A request timeout does not prove the provider rejected it. Establish the current result first, then use the supported recovery path.

## Diagnose by the last verified stage

Start with the work reference, the time and the latest visible result. Ask what was last confirmed: the source read, draft preparation, approval, execution or outcome measurement. This narrows the remedy and avoids restarting completed work.

A useful sequence is:

1. Confirm the company and intended record.
2. Check the relevant integration and operation permission.
3. Open the current work or proposed change rather than an old screenshot.
4. Read its latest status and receipt.
5. Resolve the stated cause before another attempt.

## Connection or permission problem

Open Integrations and the relevant service detail. Inspect **What Kina can do** and, where needed, **Access and scopes**. Use **Check connection** for current health and permissions. Use the supported reconnect flow if authorisation is expired.

If products can be read but orders cannot, investigate the order permission separately. Do not disconnect a working catalogue link because another capability is missing. A connection can also be degraded: “connected” and “usable for this operation” are different facts.

## Approval or execution problem

Open the proposed change in Approvals. If no decision control is offered, inspect the role, current proposal state and any need for a second approver. If a source or attached version changed, review the current evidence.

Read whether the recorded approval was followed by making the change. A view saying it has not been made in the provider yet is not an execution failure; the effect may still be a separate step. If the result is uncertain, use **Check status** where offered and inspect **View receipt** before retrying.

## Data or interpretation problem

For an unavailable Readout, inspect the named source and dates. For a partial figure, identify the omitted source or records. A real zero does not need the same recovery as missing evidence. If the calculation seems wrong, inspect the inputs, unit and expression before changing presentation.

For a Brand Memory answer using an old fact, search the supporting passage and check the current source. **Refresh** and **Read everything again** have different scope; a complete reread is not the first remedy for every single missing result.

## Worked example: timeout after a product change

North Coast Goods approves a description update. The response times out. Submitting the same change again immediately would assume that the provider rejected it, which the timeout does not prove.

Open the change and check its status and receipt. If the operation completed, inspect the product rather than repeating it. If it remains unresolved, follow the supported recovery or report the work reference. If a newer edit now exists, compare it before proposing another change.

## Escalate with useful evidence

Include the page, work reference, approximate time, visible message and the last step that completed. Explain what you expected. Redact screenshots. Exclude passwords, bearer tokens, full customer data and provider credentials. A precise work reference lets support investigate without a broad data dump.

Reviewed 2 October 2026.

## Related guides

* [Integrations](/product/connections)
* [Receipts and undo](/product/receipts-undo)
* [Errors, limits and retries](/developers/errors-and-limits)


# Understand a Readout
Source: https://docs.byom.co/guides/understand-a-readout

Check the source, date range, maths and comparison before drawing a conclusion.

Read a Readout by checking what the block measures, where the data came from and how the calculation works. You can then explain the figure to a colleague without losing its dates, units or missing sources.

## A four-part check

1. **Question:** what business question is the block answering?
2. **Coverage:** which systems and records are included, and what could not be read?
3. **Calculation:** how do the inputs produce the figure?
4. **Comparison:** is the previous period or target a meaningful comparison?

Read the date label too. UTC calendar days and a store's local day can cut a reporting period differently.

## Example: contacts per order

A contact count divided by an order count may help you investigate service demand. If only one of two helpdesks supplied data, the rate covers less than the whole business. If the order source is unavailable, there is no complete ratio to interpret.

A previous period should cover the same duration and compatible sources. A promotion, holiday or connection change may explain movement without an operational improvement or deterioration.

## Unavailable, partial and zero

**Unavailable** means the source could not be read. **Partial** means the shown figure has incomplete coverage. **Zero** is a measured or defined zero for the included data. Do not convert either of the first two into zero to make a chart look complete.

## What to do next

Open or ask about the relevant work when a change merits investigation. A Watch can create an item at a threshold crossing where enabled, but it does not authorise a provider write. Check the underlying evidence before acting.

## Inspect a block on the board

Open the relevant Readout and select the period you intend to examine. A block can inherit the Readout's dates or use its own dates, so check both before comparing nearby figures.

Read the source information beneath the block. For a derived figure, the maths shows the input values substituted into the expression. The definition information control explains the metric and its included records or exclusions. A block with one direct input may show its source without a calculation.

If you are allowed to edit the block, open its editor to inspect **Data points**, the expression, **Unit**, **Compare with**, **Bad news is when it goes** and **Dates**. Do not save a change merely to understand the existing calculation. A viewer should use the displayed source and definition information instead.

## Worked interpretation: contact rate moved

Suppose a fictional Readout shows 120 contacts and 1,000 orders for one period. A calculation of contacts divided by orders, multiplied by 100, yields 12 contacts per 100 orders. The previous equal-length period shows 10.

That is a rise of 2 contacts per 100 orders. It is also a 20% relative rise from 10 to 12. Those are different statements; neither should be described vaguely as “up 2%”. Read the unit and comparison before sharing the result.

Now suppose one helpdesk failed to supply data in the earlier period. The numerical movement is still visible, but the periods do not cover the same sources. It cannot establish a company-wide increase in contact demand until the coverage difference is resolved.

Finally, suppose the current order source is unavailable. The system cannot establish the complete ratio. Treat the missing source as an access or data problem, not as evidence that orders fell to zero.

## Check a threshold alert

Where available, a block's Watch is configured under **Tell me when it goes**. Inspect the threshold and whether it is Above or Below. A change in units can change the meaning of the same numerical threshold, so read them together.

A crossing opens work to inspect. Remaining above the line does not need a new alert each time, and unavailable data is not a numerical crossing. Investigate the source and situation before preparing any external response.

## Explain the result to a colleague

Include the figure, unit, dates, sources and material coverage limitations. For example: “The included sources show 12 contacts per 100 orders over these UTC days; the earlier period is incomplete because a helpdesk feed was missing.”

That gives a colleague enough context to use the result without turning it into a stronger claim. If the question concerns money or performance, check that the input definition measures that outcome rather than a forecast or modelled estimate.

Reviewed 2 October 2026.

## Related guides

* [Readouts](/product/readouts)
* [Integrations](/product/connections)
* [HQ and Workspace](/product/hq-workspace)


# The BYOM field guide
Source: https://docs.byom.co/index

Understand your AI operator, work through your first job and see how every change stays under your control.

<div>
  <div>
    <span>BYOM DOCUMENTATION</span>
    <span>THE FIELD GUIDE · 01</span>
  </div>

  <div>
    <section>
      <div>
        <h1>Know the work.<br />Make the call.</h1>
        <p>Your guide to working with <strong>Kina</strong>, the AI operator in BYOM. From the first question to the change you approve.</p>

        <div>
          <a href="/start/first-session">Start with one job <span>↗</span></a>
          <a href="/start/what-is-byom">Meet BYOM <span>→</span></a>
        </div>

        <div><span><i /><i /><i /><i /></span><span>Kina does the work.<br />You stay in control.</span></div>
      </div>

      <a href="/product/hq-workspace">
        <div><span>INSIDE BYOM</span><span>01 / HQ</span></div>

        <div>
          <img alt="Illustrative BYOM HQ: a proposed change, work on the board and the next jobs to pick up." />
        </div>

        <div><span>A place to see what needs you.</span><span>↗</span></div>
      </a>
    </section>

    <p>Product image: demo workspace, illustrative. Examples are not customer results.</p>

    <section>
      <div><span>FIND YOUR WAY</span><h2>What brings you here?</h2></div>

      <div>
        <a href="/start/what-is-byom"><span>01</span><div><h3>I'm getting to know BYOM</h3><p>What it does, how Kina fits in, and where your existing tools belong.</p></div><span>↗</span></a>
        <a href="/start/first-session"><span>02</span><div><h3>I want to get some work done</h3><p>Connect the right source, ask a useful question and review the result.</p></div><span>↗</span></a>
        <a href="/product/approvals"><span>03</span><div><h3>I need to understand the controls</h3><p>What needs approval, what a receipt tells you, and when undo is available.</p></div><span>↗</span></a>
        <a href="/developers/overview"><span>04</span><div><h3>I'm connecting an AI assistant</h3><p>The Shopify connector, MCP, consent and the boundary between a proposal and a write.</p></div><span>↗</span></a>
      </div>
    </section>

    <section>
      <div><span>ONE JOB, END TO END</span><h2>The work has a trail.</h2><p>A product-content change is one example of how BYOM brings the evidence, the decision and the result together.</p></div>

      <ol>
        <li><span>01</span><h3>Ask Kina</h3><p>Give it the job and the context. It reads the sources your account can access.</p></li>
        <li><span>02</span><h3>Check the work</h3><p>Follow the evidence. Read the proposed change and what it will affect.</p></li>
        <li><span>03</span><h3>Make the call</h3><p>An authorised person reviews the Action before the approved change is sent.</p></li>
        <li><span>04</span><h3>Read the receipt</h3><p>Check what happened. Use undo when the operation supports it.</p></li>
      </ol>

      <a href="/guides/review-a-change">Walk through an approval <span>→</span></a>
    </section>

    <section>
      <div><span>THE PRODUCT, EXPLAINED</span><h2>See how it fits together.</h2></div>

      <div>
        <a href="/product/kina"><span>YOUR OPERATOR</span><h3>Kina</h3><p>Ask questions, develop a brief and prepare the next piece of work.</p><span>↗</span></a>
        <a href="/product/hq-workspace"><span>YOUR WORK</span><h3>HQ & Workspace</h3><p>See what needs attention, open the job and follow its progress.</p><span>↗</span></a>
        <a href="/product/readouts"><span>YOUR EVIDENCE</span><h3>Readouts</h3><p>Questions answered with the figures and sources behind them.</p><span>↗</span></a>
        <a href="/product/connections"><span>YOUR TOOLS</span><h3>Integrations</h3><p>Understand access, supported operations and connection health.</p><span>↗</span></a>
        <a href="/product/brand-memory"><span>YOUR CONTEXT</span><h3>Brand Memory</h3><p>Keep useful brand knowledge grounded in its source.</p><span>↗</span></a>
        <a href="/product/rails"><span>YOUR REPEAT WORK</span><h3>Rails</h3><p>Understand recurring jobs, checkpoints and their current limits.</p><span>↗</span></a>
      </div>
    </section>

    <section><span>A GOOD PLACE TO START</span><h2>One useful question.<br />One clear next step.</h2><a href="/start/first-session">Your first session <span>↗</span></a><p>Checking whether BYOM fits your team? <a href="mailto:hello@byom.co">Talk to us.</a></p></section>
  </div>

  <div><span>BYOM LTD · Reviewed 2 October 2026</span><div aria-label="Legal and documentation"><a href="/reference/availability">Availability</a><a href="https://byom.co/legal/privacy">Privacy</a><a href="https://byom.co/legal/terms">Terms</a><a href="/ai">BYOM facts</a></div></div>
</div>


# Approvals and proposed changes
Source: https://docs.byom.co/product/approvals

Review the exact consequential change before authorising it.

Use Approvals to decide whether Kina's prepared work should change your store, send a customer-facing reply or affect another connected system. Each proposed Action sets out the change for review; Kina can research and draft before that decision.

<Frame>
  <img alt="Demo Action review showing the proposed change and decision controls" />
</Frame>

## What to review

Read the target, the exact operation and the proposed before-and-after change. Check the evidence behind it, the relevant risk and whether a reversal is supported. Reject or revise a proposal that changes the wrong record or relies on an unsupported fact.

For a batch, review every edit. An approval should be bound to the version you saw. A later change to the proposal is not covered by your earlier decision.

## Approval and execution are different

Approval records your decision. Execution attempts the authorised effect. The receipt records the result, including partial or failed work. An approval badge alone is not proof that every record changed.

Your role may allow you to inspect a proposal without allowing you to approve it. A missing provider permission is also separate from approval: authorising a change does not grant BYOM an absent Shopify scope.

## Example

Kina drafts five improved product descriptions. You can read and refine all five. Before applying them, check the products and every field change. After execution, inspect the individual results; check any partial result before treating the batch as complete.

## Review a change in the interface

Open **Approvals** or the decision linked from HQ, Workspace or the relevant task. The same proposed change can be reached from several places; the review must still concern the same target and version.

The review shows **Before** and **After** where field changes are available, alongside the reason, risk and reversal information. **Approve** and **Reject** are decisions about that proposal. Read the confirmation text before submitting: some contexts combine approval and making the change, while other contexts record approval and then offer **Make the change**. A supported helpdesk operation can show **Send to your helpdesk** instead.

Do not infer the operation from a button alone. The confirmation should make clear which service is affected and whether the effect happens in that step. After an approval-only step, the view can say the change has not been made in the provider yet.

## Before you can approve

You need a role that can make the decision, a current proposal and the applicable permission. A higher-risk change may require an additional sign-in check. Some proposals require another approver; if the interface says a second approver is required, having drafted the work does not let you approve it yourself.

If the proposed work includes media, the exact attached version and its source must be available for review. An unavailable preview is a reason to stop, not to approve from a filename. Accepting creative work for editorial review is also distinct from approving its rights, publishing it or authorising spend.

## Worked example: approval with a narrower meaning

A fictional merchant reviews a prepared creative pack. Its copy and ordered versions are suitable, so an editorial review is accepted. That acceptance alone does not give permission to use an unlicensed image or publish an advertising campaign.

Before any external use, check the relevant rights and the separate effect being authorised. Check which effect the proposal authorises before accepting it.

For a simpler catalogue batch, suppose five descriptions are prepared but one includes an unsupported material claim. Revise that item before accepting the batch. Approval is not a request for Kina to decide which unseen edits you would probably accept.

## When approval is unavailable

| Situation | Useful next step |
| - | - |
| You can read but cannot decide | Ask the appropriate company approver to review the same proposal. |
| Source or proposal changed | Reopen the current version and check it again. |
| Preview cannot be loaded | Restore reviewable evidence or reject; do not approve unseen content. |
| Provider permission is missing | Resolve access in Integrations; approval cannot create that scope. |
| Result is uncertain | Use **Check status** where shown and inspect the receipt before repeating. |

Use **View receipt** after a recorded decision or result. The receipt keeps the detailed evidence needed to establish what was authorised and what completed.

Reviewed 2 October 2026.

## Related guides

* [Review a proposed change](/guides/review-a-change)
* [Receipts and undo](/product/receipts-undo)
* [Trust and control](/trust/overview)


# Brand Memory
Source: https://docs.byom.co/product/brand-memory

Use source-backed company context to make work more relevant and consistent.

Brand Memory helps Kina use your product facts, policies and brand guidance without you repeating them in every request. Search the underlying material to check where an answer or draft got its facts.

## Useful context

Brand guidance, product facts, policies and explicit company instructions can make a task more precise. For example, a description draft should use the actual material and care guidance, then follow the brand's tone. A voice instruction cannot make an unsupported product claim true.

Use the sources and search results to check where a fact came from. When a source is outdated or wrong, correct the underlying information or use the supported correction control. Ask Kina to identify conflicting evidence rather than silently choosing a convenient version.

## Source context and explicit memory

Brand Memory helps you inspect what the connected sources say. **Memory** is the separate place to save and govern explicit personal or company facts and instructions. For its scope and review controls, see [Choose what Kina should remember](/product/hq-workspace#choose-what-kina-should-remember).

If a company memory conflicts with a source passage, identify the disagreement and check the authoritative policy. Saving a convenient note should not silently replace a published commitment or create a product claim the source does not support.

## Freshness and limits

A source summary is not a guarantee that every connection has been reread continuously. Check the last-read information and availability of the relevant refresh control. Source access, retention and correction remain governed by your company's permissions and supported capabilities.

## Find the source behind a statement

Open Brand Memory and use **Search** to find what Kina has read. Search for a specific product name, policy phrase or company instruction; use the system filter when you know where the source belongs. Search results describe the source and kind of record so you can distinguish a web page from a conversation or approved change.

Open the result and inspect the passage that supports the fact. Several matching passages from one long record are not several independent sources. If a query returns nothing, that means no matching read was found; it does not prove that the business has no such policy or product.

**Summary** groups context by system. Use it for orientation, then return to the underlying source when a decision depends on an exact number, date, promise or product claim. A summary can compress important qualifications.

## Refresh the appropriate way

The main **Refresh** control reads what has changed when the capability is enabled. The more-options menu also offers **Read everything again**, which starts from the beginning and can take much longer. Choose it for a deliberate complete reread rather than routinely using it to investigate one missing passage.

Check the status line and the individual result when a source is skipped or fails. A refresh request and a completed read are different events. If a control is unavailable, read its reason and inspect the source integration instead of assuming the entire memory is empty.

## Worked example: policy changed, old summary remains

North Coast Goods changes its shipping policy from “dispatch within two working days” to a conditional dispatch promise. Kina's draft still uses the older unconditional phrase.

Search for the phrase and inspect the source and read time. Check the current policy, then refresh the relevant source through the supported control. Ask Kina to redraft using the current policy and to flag the earlier wording. Do not approve a customer promise merely because it appeared in an old summary.

If two current sources disagree, preserve the conflict. An owner's instruction can clarify how work should be handled, but it does not make a public policy page or product specification accurate by itself.

## Correct context without broadening access

When saving a company instruction, specify its scope and wording: “Remember for our company that we describe our tone as plain and practical.” Review the wording and evidence before accepting it as company memory.

Do not use company memory as storage for passwords, full customer records or a personal note intended for one colleague. Before sharing a source, consider who can read the company context and which connected client data classes may expose it. Deleting or correcting context is also distinct from disconnecting the original provider.

Reviewed 2 October 2026.

## Related guides

* [Kina](/product/kina)
* [Improve product content](/guides/improve-product-content)
* [Data and access](/trust/data-and-access)


# Integrations
Source: https://docs.byom.co/product/connections

Understand what BYOM can read or change through each authorised service.

Integrations shows the authorised links between your company and supported services. A connection provides access; its current permissions and capabilities determine which work is available.

## Three checks before work

1. Is the expected service connected to the correct company and store?
2. Does the provider grant the permission needed for this task?
3. Is the requested capability available to your account?

A provider logo or a listed integration is not proof that your company has a working connection. Check the connection's current state and the capability needed for your task.

## Reads and changes

Reading product information and changing a product are different permissions. A connected Shopify store may support a catalogue question while a write remains unavailable. Similarly, order and customer data need their own authorised access.

An Action approval authorises a specific change; it does not repair an expired connection or add a missing provider scope. Fix the access issue separately, then review the proposal against the current source data.

## Example

You ask Kina to explain why a product is missing from a collection. A read-only connection may be enough to investigate. Moving the product requires the supported change capability and the appropriate review.

## Inspect a specific integration

<Frame>
  <img alt="Demo Integrations gallery showing connected-service cards and their status" />
</Frame>

Open **Integrations**, then the relevant connected service. Check that it is the expected store or account before troubleshooting capability. The page distinguishes tools already connected from tools available to add; a service shown as coming is not ready to use.

In the detail view, **What Kina can do** translates the available tool permissions into useful operations. Open **Access and scopes** when a task depends on a particular provider permission. Activity and the last-checked information help distinguish an old connection from a recently checked one.

Use **Check connection** to ask for current health and tool permissions. If the connection needs renewed authorisation, use its reconnect control and complete the provider's supported consent flow. Checking a connection and reconnecting it solve different problems: the first inspects the existing link; the second can renew access.

## Read the state before choosing a remedy

| State or symptom | Interpretation | Next step |
| - | - | - |
| Connected and usable | The authorised link is available. | Check that the specific operation appears under What Kina can do. |
| Connected but degraded | The link exists, but health or permissions are impaired. | Read the stated reason and check or reconnect as appropriate. |
| Expired or disconnected | Current provider access is unavailable. | Reconnect if you are authorised to do so. |
| Permission missing | The provider has not granted the required scope. | Complete the appropriate provider permission process. |
| Capability permissions not yet returned | BYOM cannot yet describe the usable tools. | Check connection; do not infer capability from a logo. |

## Worked example: product access without order access

North Coast Goods can ask about descriptions and inventory using its authorised catalogue connection. A later question asks which customers have unfulfilled orders. That request needs different data and permissions.

A refused order question can reflect missing order access while the catalogue connection still works. Check the optional order/customer access required for that work. If it is unavailable, Kina should explain the missing source instead of treating it as a zero-order result.

Likewise, permission to read a product does not grant permission to update it. A supported product change needs provider write access and its own approved proposal.

## Disconnect deliberately

**Disconnect** is a consequential access change. Use it when you intend to end that provider link, not as a general refresh button. Read the confirmation and consider jobs that depend on the service. A later run can lose its source or its ability to complete.

Disconnecting prevents further work through that connection. It does not prove historical records have been erased. Use the applicable privacy process for deletion, and avoid putting provider credentials into support screenshots or company notes.

Reviewed 2 October 2026.

## Related guides

* [Your first session](/start/first-session)
* [Data and access](/trust/data-and-access)
* [Troubleshooting](/guides/troubleshooting)


# Customer Service
Source: https://docs.byom.co/product/customer-service

Investigate customer enquiries with source evidence, policy context and governed next steps.

Use Customer Service to investigate an enquiry and draft a reply from the order evidence and your brand's policy. Kina helps prepare the response; you review supported sends and other consequential changes before they happen.

## Start with the actual enquiry

Establish which order or issue the customer means using the supported source. Check the fulfilment or delivery evidence, its freshness and the relevant policy. A tracking event and a customer's report can disagree; surface the discrepancy instead of presenting a guess as a fact.

A useful request is: “Explain the current status of this enquiry using the connected evidence. Draft a response under our shipping policy and flag what still needs checking.”

## Policy is part of the answer

Returns, refunds, delivery promises and escalation rules should come from the brand's policy. Do not invent a universal refund threshold or offer a promise that the connected evidence cannot support.

Before approving a reply, check the recipient, the facts, the tone and any commitment. Preparing a response does not mean the customer has received it.

## Data and available operations

Use the authorised enquiry and order flow where available. Avoid copying complete customer records into broad company notes or unrelated conversations. Customer-data permissions can be separate from catalogue access.

Available helpdesk operations, order evidence and sending capabilities depend on the connected systems and account enablement. Check which reply, refund and carrier operations are available to your company. Check the actual Action and receipt for completed work.

## Work through an enquiry

<Frame>
  <img alt="Demo Customer Service history showing recorded work and its results" />
</Frame>

Before starting, check that the relevant helpdesk and any required order source are available in Integrations. Catalogue access alone is not enough for customer-order questions. You also need the brand's current policy and an account allowed to perform the intended work.

Open Customer Service and use **Inbox** to choose the conversation. Read the customer's actual message and the conversation context before asking for a response. The conversation view brings together the draft, the decision and the evidence; a customer-facing send remains separate from preparation.

Use **Ask Kina about this conversation** to investigate with the conversation attached. For a supported order or product-question workflow, **Draft the reply with Kina** is offered when eligible. If that control is unavailable, read the reason rather than copying a whole customer record into another chat.

Inspect the evidence alongside the draft. For an order enquiry, check which order the message concerns, the fulfilment and delivery information and the time the source was read. A new customer message or updated order evidence can make an earlier draft stale. Recheck the current context before approving a reply.

## Use the surrounding sections for the right job

| Section | Use it for |
| - | - |
| Inbox | Opening and working through customer conversations. |
| Knowledge | Inspecting the policy and guidance used for replies. |
| Try it | Checking behaviour with supported scenarios before relying on it. |
| Permissions | Reviewing the boundaries of the available service work. |
| History | Inspecting the recorded work and its results. |
| Quality and Results | Reviewing evidence about reply quality and subsequent outcomes. |
| Channels and Set up | Understanding the available source and channel configuration. |

Check the available operation and its decision state before sending or making another provider change.

## Worked example: no delivery promise from a stale event

A fictional customer says their order has not arrived. The latest available carrier event shows dispatch yesterday, but there is no delivery confirmation. The brand's policy explains how late enquiries should be handled.

A suitable draft states the observed status, acknowledges the customer's report and follows the policy's next step. It does not claim “delivered” or promise “tomorrow” without supporting evidence. If the source cannot identify the correct order, the next step is clarification or an authorised evidence check, not a confidently worded reply.

Before approving, check the correct conversation, intended recipient, facts and commitments. The decision view can offer a helpdesk send when supported. Inspect the receipt and provider result afterward; a saved draft is not a sent reply.

## When a workflow stops

A missing order grant requires an access fix. An ambiguous customer match requires clarification. An outdated draft requires revision. Sending blocked by capability cannot be overcome with stronger wording in chat.

Keep sensitive details in the authorised enquiry flow. When escalating a problem, share a conversation reference and a redacted description of the issue rather than exporting all customer messages.

Reviewed 2 October 2026.

## Related guides

* [Brand Memory](/product/brand-memory)
* [Approvals and proposed changes](/product/approvals)
* [Data and access](/trust/data-and-access)


# Growth Engine
Source: https://docs.byom.co/product/growth-engine

Turn commercial evidence into reviewable recommendations, content and next steps.

Use Growth Engine to choose a product to examine, prepare a creative brief and check the results of completed work. Kina can investigate opportunities and draft content or recommendations. Supported publishing, activation and spend need their own review and approval.

## Use a defined question

Start with a product, campaign or commercial question. For example: “Review this product's evidence and current description. Suggest a clearer customer message, explain the assumptions and prepare two alternatives.”

A product recommendation should explain the data it used and the data it lacks. Strong content is not proof that an advertising account is connected, an audience is reachable or a campaign will be profitable.

## Evidence, forecast and outcome

Use the right evidence for the decision:

* **Evidence:** what a connected source reported, with its coverage and period.
* **Forecast:** an estimate based on stated assumptions.
* **Outcome:** what was measured after work happened.

A forecast is not revenue received. A correlation after a change does not by itself establish that the change caused it. Compare compatible periods and be explicit about incomplete data.

## Review the effect

Check product claims and brand guidance before using a draft. Review destinations, rights and any spend before approving external work. An approved content edit is not blanket approval to launch an advertising campaign.

## Availability

Preparation, connected analytics, media and activation capabilities have separate enablement and provider requirements. Check the available controls and connection information for your company before planning work in a channel.

## Move from a commercial question to reviewable work

Growth Engine is organised into **Overview**, **Products**, **Creative**, **Campaigns**, **Discovery** and **Results**. Discovery is shown when that capability is available. Use the sections in the order your task needs; check connection and spending permissions for the operation you need.

Start with the connected store and the evidence needed for the question. If an advertising or analytics source is required, check it in Integrations. A shop with catalogue access can still lack traffic or campaign evidence.

| Section | Question to bring to it |
| - | - |
| Overview | What deserves attention and which source supports that priority? |
| Products | Which product should we examine, and what needs fixing before promotion? |
| Creative | What brief, copy or creative work should we prepare from verified facts? |
| Campaigns | What is the plan and which assumptions govern the forecast? |
| Discovery | What evidence describes the shop's AI-shopping readiness? |
| Results | What happened, over which period and with what coverage? |

## Work one product through the decision

Choose a product in Products and inspect its evidence before deciding it should be promoted. A recommendation can identify an opportunity or a reason to hold and fix the product first. Missing descriptions, incomplete facts or unavailable data need different work from an advertising launch.

Where the product offers **Write a brief**, use it to carry the chosen product into the creative work. Read the brief and source facts before generating or using output. A generated image or polished copy does not settle usage rights or the truth of a claim.

When work reaches review, inspect the exact version and any attached media. Editorial acceptance does not authorise publishing, rights reuse or spend. Use the separate proposed effect and approval for a supported external operation.

## Worked example: a recommendation with incomplete evidence

North Coast Goods wants to promote an overshirt. Its catalogue has good product facts, but a care section is incomplete and the campaign account is not connected.

A useful first step is to fix the care content from verified information and prepare a brief. The campaign's performance needs evidence from the advertising account. A forecast should identify the missing campaign inputs and state its assumptions; it must not invent an account result.

After a content change completes, Results can help inspect the relevant measured period where data is available. Suppose sales rise during the same week as a promotion and a stock replenishment. The rise is an observation; attributing all of it to the description requires more evidence.

## If a recommendation or result is unavailable

Check the reason and which source was read. An incomplete feed should remain partial. A previous-period baseline must match the metric, period and source definition. Changing the chart does not make incomparable data comparable.

If an attached creative version cannot be reviewed, restore that exact version or reject the proposal. Do not approve a different asset based on a preview from an earlier draft.

Reviewed 2 October 2026.

## Related guides

* [Improve product content](/guides/improve-product-content)
* [Readouts](/product/readouts)
* [Availability and access](/reference/availability)


# HQ and Workspace
Source: https://docs.byom.co/product/hq-workspace

Use HQ to orient yourself and Workspace to follow the work.

Start in HQ to see what needs your attention. Open Workspace to follow the job: its subject, progress, evidence and next step stay with the work record, so you or a colleague can pick it up later.

<Frame>
  <img alt="BYOM HQ showing a demo workspace and its attention queue" />
</Frame>

## Use HQ for attention

HQ brings together Kina's brief, items waiting for you, recent activity and supporting information. Open the item that needs a decision rather than treating a summary as the full evidence.

An “Updated” time describes when the page read its sources. It is not a promise that Kina has performed a fresh investigation of every part of the business.

## Use Workspace for continuity

Workspace makes the work inspectable: the subject, current state, activity and next step belong with the record. For example, a product-content review can remain visible while a colleague checks the proposed wording.

A board item and an Action serve different purposes. The board tracks the work; the Action governs a consequential change. Finishing a draft does not authorise its publication.

## Choose what Kina should remember

Where **Memory** is enabled, use it to save and review explicit facts or instructions. It is separate from [Brand Memory](/product/brand-memory), which helps you inspect source-backed company context. Review the wording of a saved instruction and check the original source behind a retrieved passage.

Open Memory and choose **Just me (private)** for a personal note or **Whole company** for context the team should use. Add a clear title and detail, then choose **Remember this**. Personal memory saves for its owner. Company memory enters **Waiting for you** and requires an owner or admin to approve it before it becomes shared context. An approval request is not yet an accepted company instruction.

For example, “Use short summaries for my daily review” can be a personal preference. “Do not promise next-day delivery outside the UK” is a proposed company instruction: check it against the actual shipping policy before an owner or admin approves it. Reviewers can edit the wording before approval or reject a suggestion with a note. Kina does not approve its own suggested company memory.

Use **All**, **Company** or **Mine** to inspect the relevant audience. If a fact has changed, use **Correct** to propose its replacement. Use **Still true** only after checking an entry that needs reconfirmation; confirming freshness does not turn an unsupported assertion into a fact. **Forget** removes an entry through the supported control: you manage your own personal memory, while owners and admins manage shared entries. Forgetting a note does not itself delete the source document, an existing receipt or a copy already held by another service.

Keep passwords, access tokens and unnecessary customer details out of memory. For a colleague's handover, keep the source, decision and next step with the work record; a broad memory note should not replace the job's evidence.

## Read estimates carefully

An estimate of time saved is a model based on completed work, assumed task duration and an hourly rate. It is useful for orientation, but it is not measured sales, cash saved or a guaranteed return.

If a summary and the underlying record appear inconsistent, open the record and receipt before acting. Report the discrepancy with the item and time, without sharing secrets or raw customer data.

## Follow one item from attention to work

<Frame>
  <img alt="Demo Workspace board with work records at different stages" />
</Frame>

Use this flow when HQ shows something waiting for you, or when you want to move a useful Kina answer into work that you can revisit.

<Steps>
  <Step title="Read the brief in context">
    Check the company, the page's Updated time and the time on Kina's brief. Open the relevant item rather than interpreting every headline as a new investigation.
  </Step>

  <Step title="Open the item that needs attention">
    A waiting decision opens the proposed change for review. A work item opens its own record. The board record describes the work; the decision view shows the specific effect for review.
  </Step>

  <Step title="Inspect the record">
    Read the subject, activity and current next step. Check whether the work is awaiting information, prepared for review or already has an execution result. Use the linked source or receipt when you need evidence beyond the summary.
  </Step>

  <Step title="Continue with the right action">
    Ask Kina to investigate or revise internal work. Review a proposed external change in Approvals. If an outcome is uncertain, inspect its receipt before starting another attempt.
  </Step>
</Steps>

## Worked example: the board has a draft, HQ has a decision

North Coast Goods has a Workspace record for “Clarify overshirt care guidance”. The record contains source notes and a revised description. HQ also shows a change waiting for review.

Open the record for the source notes and draft. Open the decision to review the product and before-and-after fields. After the change runs, inspect its receipt. The history can show a finished draft while the product update is still waiting for a decision.

If a colleague asks whether the change reached the shop, send them to the result record rather than quoting Kina's original draft.

## What the home page cannot settle alone

A quiet attention queue does not mean every service is healthy or every business question has been investigated. Integrations is the place to inspect connected-service access. A summary of estimated impact does not replace the underlying assumptions or billing record.

An older failed attempt can remain in history while the current next step has been resolved. Read the current item and its latest evidence; do not treat every historical failure as a fresh decision request.

If a count or status looks stale, note which page and work reference disagree and when you saw it. Avoid repeating a provider change to make a home-page count move.

Reviewed 2 October 2026.

## Related guides

* [Kina](/product/kina)
* [Approvals and proposed changes](/product/approvals)
* [Receipts and undo](/product/receipts-undo)


# Kina
Source: https://docs.byom.co/product/kina

Ask your commerce operator to investigate, explain and prepare work in your company context.

Kina is BYOM's AI operator. Ask it to read available information, investigate a question, calculate, compare options or prepare a draft. Review proposed Actions before consequential external changes are made.

<div>
  <img alt="Kina" />

  <img alt="Kina" />
</div>

## Give the work a clear shape

A useful request names the subject, the desired output and the constraint:

> Review the description of our linen shirt. Use the product facts and our tone of voice. Draft a clearer version, flag unsupported claims and show the sources.

Follow-up questions can refine the work: “Make that shorter”, “Explain why that claim is unsupported”, or “Compare the current and proposed wording”. Keep refining the draft until it is ready to review.

## Check the evidence

Look for the source, the period covered and any missing information. A polished answer can still be limited by an unconnected service, a stale source or a provider's permissions. If the evidence is incomplete, ask what is missing before making a decision.

Kina should explain what it prepared and what remains to be done. An answer in a conversation does not by itself prove that a provider change happened. Use the Action and its receipt for that.

## Use the right company and source

Your company context, account permissions and connected capabilities bound what Kina can read and prepare. Asking in natural language does not expand those permissions. For customer enquiries, avoid pasting unnecessary personal data into a conversation; use the supported, authorised source.

## Complete an investigation, then choose its next step

<Frame>
  <img alt="Demo Kina conversation showing the operator workspace and prepared work" />
</Frame>

Before you begin, confirm that you are working in the right company and that the source you want to use is available. You can ask Kina for a general explanation without a store connection; a question about your own stock, orders or trading needs the relevant authorised evidence.

For an investigation:

1. **Define the subject.** Name the product, work record or enquiry. For a trading question, specify the dates and whether you mean a count, a rate or a monetary amount.
2. **Request an inspectable output.** Ask for the source facts, a conclusion and the uncertainty. If you need a draft, identify the intended audience and constraints.
3. **Check the result before continuing.** Open the cited source where available. Follow up in the conversation to resolve a missing fact or correct a mistaken assumption.

Kina's response can include cited sources and prepared output. The response controls include **What Kina did**, where available, to inspect the work behind the reply. Use **Put this on your board** when you want to carry a reply into Workspace rather than leave the useful result only in the conversation. Attaching a reply to a board creates an internal work record; it does not publish the reply to customers.

## Worked example: an unsupported product claim

The fictional merchant North Coast Goods asks Kina to review a cotton overshirt. The product record says “100% cotton” and gives washing instructions; the draft description also says “certified organic”. No certification source is available.

A useful result identifies the unsupported claim, retains the verified composition and proposes wording without the certification. It also explains what evidence would be needed to include that claim. Your next step can be to supply the missing source or prepare a change using the supported facts.

Ask a follow-up such as “Keep the verified facts and give me the proposed description beside the current one.” If you then choose to apply it, inspect the proposed change in Approvals. Review the exact changed fields before authorising the update.

## Talk through the work

Where calls are enabled for your account, use **Call** in Kina and grant your browser microphone access when prompted. Start with the same subject, desired output and constraints you would put in a written request. The call joins the conversation on screen; use the chat to inspect the answer, sources and any prepared change.

The call controls have separate purposes:

* **Microphone** mutes what you send to the call. It does not cancel work already started.
* **Kina's voice** turns spoken replies off or on. Kina can continue answering in text with its voice off.
* **End** ends the call. Work already started can continue in the chat; check its result there.

For example, ask “Compare the current overshirt description with our care guidance and flag contradictions.” If the investigation takes longer than the conversation, end the call and return to its chat item to check the result. Use the work item's supported stop control when you need to stop that work, then inspect its state.

Live captions help you follow the conversation. Check names, quantities and product references in the resulting work, especially if the audio was unclear. An approval still belongs to the specific proposed external effect; saying “that sounds good” in a conversation is not a substitute for reviewing it.

If Call is absent or fails, continue in text. Check browser microphone permission and the visible notice before retrying. Some accounts can offer a transcript fallback: review the recognised text before using it, or cancel it if it is wrong. Call availability is separate from access to the store information needed for your task.

## When a response needs recovery

If a request is still running, inspect its visible work status before starting the same job again. If the answer lacks a source, ask what was read and what is missing. If a connection is unavailable, resolve that in Integrations rather than repeatedly rephrasing the question.

A downloadable draft is an output for you to inspect. Downloading it does not publish it or prove that a store was updated. Use the proposed change and receipt to confirm an external result.

<span>Reviewed 2 October 2026.</span>

## Related guides

* [Brand Memory](/product/brand-memory)
* [Approvals and proposed changes](/product/approvals)
* [Troubleshooting](/guides/troubleshooting)


# Rails
Source: https://docs.byom.co/product/rails

Understand how repeated work is checked and governed from preparation to receipt.

A Rail is a job Kina does for a merchant on repeat, checked at every stage and signed off before anything touches the store. The stages and run history let you inspect its checks, prepared work and result.

## Repetition does not remove review

A repeatable job needs a clear input, defined checks and a meaningful result. For example, a regular product-content review could identify gaps, prepare proposed wording and present changes for approval. Scheduling the review does not authorise every future product edit.

Each occurrence still depends on valid company membership, available capabilities, current connection access and applicable usage allowances. Check those requirements again when the source or account state changes.

## Read a run in stages

Check what the run read, what it prepared, which checks passed and where it stopped. A completed preparation stage and a completed external change are different results. Follow the Action and receipt for any actual change.

A useful failure identifies the unfinished stage and its reason. If the source was unavailable, fixing access may be the next step. If a proposed edit failed a check, revise the work before asking for approval.

## Availability

A named Rail is usable only when it is enabled and has the checks and provider access for your company. Check the available Rail and scheduling controls in your account before making a job routine.

## Inspect and test an enabled Rail

<Frame>
  <img alt="Demo Rail detail showing stages, manual run controls and run information" />
</Frame>

Use Rails when a defined job has been made available to your company and you want to understand its checks before running it. Start by reading the Rail's description and the source information required for the job.

Open its detail and inspect the stages. An enabled execution capability is required for **Test run** or **Run**; if these controls are unavailable, read the reason. Do not treat seeing a Rail name as permission to run it.

**Test run** is the safe place to inspect the job's prepared work and checks without treating it as a live store result. **Run** begins an available run; a consequential store change still follows its own approval boundary. Afterward, use the run history to open the relevant result and receipt.

Rail details currently mark scheduled starts as coming. These instructions cover the manual controls; check your account's scheduling capability before relying on an automatic start.

## What a stage tells you

A stage can establish that an input was read, a draft was prepared or a check completed. It should also explain where work stopped. If a run prepared a proposal, follow that proposal to Approvals; the Rail's completion summary is not approval to make every external change.

A test or simulation is not evidence that a real provider accepted an operation. A run receipt and a linked change receipt answer different questions: what the job did, and what a particular external effect did.

## Worked example: review before making a job routine

North Coast Goods wants a regular review of missing product-care guidance. Its available job reads a bounded product set, identifies missing guidance and prepares proposed wording from source facts.

The first test finds six gaps. Only four have enough verified care information to draft a change. A useful result preserves the two unresolved products and explains the missing facts. It does not invent instructions so that all six pass.

Review the four drafts and inspect any resulting proposals. A successful preparation run demonstrates that the job produced reviewable work. It does not prove those edits reached the shop or improved trading. Inspect change receipts for execution and use later measurements for outcomes.

## Stop and recover deliberately

Use **Pause** only when it is offered and you intend to pause the Rail. Before rerunning a failed job, inspect its latest history, the unfinished stage and any already-completed effects. Resolve the blocked source or incorrect work first.

An uncertain provider effect must be checked before another run can repeat it. Check already-completed effects so another run does not duplicate a message or change.

Reviewed 2 October 2026.

## Related guides

* [Approvals and proposed changes](/product/approvals)
* [Receipts and undo](/product/receipts-undo)
* [Availability and access](/reference/availability)


# Readouts
Source: https://docs.byom.co/product/readouts

Build questions from your data and inspect the source, calculation and comparison behind each answer.

A Readout is a board of questions answered from your company's data. Each block combines chosen data points, a calculation, a presentation and a comparison so you can check the figure and decide what to investigate.

## Start with a question

“Has our unfulfilled order count increased?” is more useful than adding a number without a purpose. Choose the source data, date range and comparison that answer the question. A template is a starting point; check its assumptions before relying on it.

The block's working should expose the expression and the values used. A figure drawn from two systems needs that distinction, because definitions can differ between providers.

## Missing data stays visible

A real zero is zero. A source that could not be read is unavailable. A figure covering only some of the expected data is partial. These states mean different things and need different next steps.

Read the period label carefully. Readout dates use UTC calendar days; the reporting period may differ from a store's local trading day.

## Sharing and Watches

A new Readout is private to its maker. Sharing moves it into the company context. Check the audience before sharing commercially sensitive information.

Where a Watch is available, it responds to a threshold crossing by opening work to inspect. It does not grant permission to change a store. Unavailable data should not be treated as a numerical crossing.

## Create a Readout from a business question

You need an account that can create or edit Readouts and the data sources required for the question. A viewer can inspect a company-shared Readout; editing controls depend on role.

<Steps>
  <Step title="Make a board">
    Open Readouts and choose **New Readout**. Enter a name and select **Make Readout**. A new board starts private. You can also use a displayed template as a starting point.
  </Step>

  <Step title="Add one meaningful block">
    Choose **Add block**. Give it a title that states the question. Under **Data points**, choose the available inputs; add another only when the calculation requires it.
  </Step>

  <Step title="Check the maths and presentation">
    Use the input references shown by the editor to write the calculation. Choose Unit, Decimals and **Show it as**. Read **Preview** and resolve validation problems before **Save block**.
  </Step>

  <Step title="Set the comparison and dates">
    Under **Compare with**, choose Nothing, The period before or A target you set. Set whether bad news is up, down or neither. Use the Readout dates or give the block its own dates.
  </Step>

  <Step title="Decide who should see it">
    Keep **Private** for your own work or choose **Team** to share with your company. Check the audience before sharing sensitive commercial information.
  </Step>
</Steps>

## Worked example: contacts per 100 orders

Imagine a fictional period with 120 service contacts and 1,000 orders. Contacts divided by orders gives 0.12 contacts per order, or 12 contacts per 100 orders when multiplied by 100. State the unit explicitly; otherwise the same number can be misread as a percentage or a count.

In the editor, use the references assigned to your chosen data points. Do not paste a guessed metric name. Read the preview and the calculation beside the figure. A previous-period comparison is useful only when the sources and duration are compatible.

If the contact data covers one of two helpdesks, the figure is partial. It cannot be treated as the complete company's contact rate. If the order source cannot be read, the complete calculation is unavailable. Neither case should become a zero.

## Set a threshold Watch

Where Watches are enabled, **Tell me when it goes** lets you set an Above or Below threshold. A Watch responds when the figure crosses the line and opens a work item; it does not keep producing new items merely because the number remains beyond it.

An unavailable reading is not a crossing. Check the source problem before changing the threshold. The work item can lead to an investigation or proposal; it cannot itself authorise a store edit.

## If a block will not save or answer

Resolve the editor's validation message first: the expression, input, unit or layout may be invalid. If the block saves but its figure is unavailable, inspect the coverage reason and connected source. A format change cannot repair missing evidence. Use the definition information for the block when you need its included records and exclusions.

Reviewed 2 October 2026.

## Related guides

* [Understand a Readout](/guides/understand-a-readout)
* [HQ and Workspace](/product/hq-workspace)
* [Integrations](/product/connections)


# Receipts and undo
Source: https://docs.byom.co/product/receipts-undo

Understand what happened, what remains uncertain and whether a reversal is available.

A receipt records the result of an operation. Use it to check what was attempted, which records were affected and whether the outcome is complete, partial, failed or uncertain. Undo is available only for changes that support a safe reversal.

## Check the result

A proposal describes intended work. Approval authorises it. A receipt is where you inspect the operation's reported result. If a batch changed four products and one failed, it is a partial result, even if the whole batch was approved.

Check the affected records and timestamps. Where a provider result is uncertain, do not assume either success or failure from an error message alone.

## Why undo is conditional

Some changes have a stored prior value and a supported reversal. Others may be irreversible, time-sensitive or dependent on what happened afterwards. A sent customer message, for example, cannot be made unread by changing a database field.

Read the reversal information on the specific Action. Do not assume that a general “undo” concept applies to every provider operation. A reversal can itself require review and can have its own result.

## An uncertain outcome

A timeout can occur after a provider has accepted a change. Check the receipt and the provider state before retrying. Repeating the command immediately can create duplicate effects.

## Read the receipt as evidence

<Frame>
  <img alt="Demo receipt showing the recorded result of a product-title change" />
</Frame>

Open the proposed change's detail and select **View receipt** when available. Read the target and recorded result before deciding whether you need to do anything else. Use the detailed operation, identifiers and times to locate the exact change.

Use these distinctions when interpreting the result:

| Result | What you can conclude | What remains to check |
| - | - | - |
| Proposed | Work is ready for a decision. | It has not been authorised or completed merely by being prepared. |
| Approved | A decision was recorded for a version. | Whether the authorised effect has run. |
| Executed | The recorded operation has a reported completed result. | Whether it produced the business outcome you intended. |
| Rejected | The proposal was declined. | Whether you want different work prepared. |
| Simulated | The shown work was a test or simulation. | It is not a completed live provider change. |
| Failed or uncertain | The attempt needs interpretation or recovery. | Individual effects and provider state before retrying. |

For a multi-item change, read individual results. A single summary must not erase the fact that some items completed and others did not.

## Use a supported reversal

**Undo** is offered only when BYOM has a supported reversal for the relevant completed execution and it remains within the available window. If Undo is absent, the operation may not support reversal, the window may have passed, a newer state may block it, or a reversal may already be in progress.

The review can instead say **Cannot be undone here**. Read the reason. Some changes can be put back in the provider manually; other effects cannot be reversed. Do not equate “manual reversal” with “BYOM can undo it now”.

When Undo is offered, review the new effect and any additional verification requested. Reversing a high-risk change can need the same kind of sign-in check as making it. Afterward, inspect the reversal's result rather than assuming a click restored everything.

## Worked example: a partial content change

North Coast Goods approves descriptions for three products. Two updates complete; the third encounters a changed source value. The correct interpretation is “two completed, one unresolved”. Preparing an undo for the completed work should not edit the product whose original change never landed.

Suppose another team member has since improved one of the two descriptions. A blind restore could overwrite that improvement. Compare the current state and the proposed reversal before proceeding. If BYOM cannot safely restore a field, keep that limitation visible and resolve it deliberately.

## Measure the business outcome separately

A successful description update confirms the edit. To establish a sales or conversion improvement, inspect the later measurement. To assess impact, use a compatible measurement window and source coverage. Preserve the operation receipt and the later measurement as separate pieces of evidence.

Reviewed 2 October 2026.

## Related guides

* [Approvals and proposed changes](/product/approvals)
* [Review a proposed change](/guides/review-a-change)
* [Errors, limits and retries](/developers/errors-and-limits)


# Availability and access
Source: https://docs.byom.co/reference/availability

What these docs explain, how access differs by surface and what examples do not prove.

BYOM brings commerce work, company context and consequential-change review into one operating environment. Access to the application and its capabilities depends on account enablement, permissions, connections and the current offer.

## Where access applies

| Surface | Purpose | Access position |
| - | - | - |
| [byom.co](https://byom.co) | Public introduction and waitlist. | Public website. |
| [app.byom.co](https://app.byom.co) | Authenticated BYOM application. | An enabled account is required. |
| These docs | Merchant and developer knowledge. | Reading docs grants no application or provider access. |

## Shopify app

The Shopify app is coming to the App Store. Contact BYOM about access. An enabled account and a compatible AI client are required to use the connector.

Use the connector URL provided by an enabled account rather than guessing an address from a brand name.

## Capability availability

A page can explain a capability without that capability being enabled for every company. Customer-data access, external sending, advertising activation, media, scheduled work and specific Rails can have separate permissions and acceptance requirements.

Check the current connection and required scopes for access, the receipt for execution, and later measurements for a commercial outcome.

## Examples and documentation dates

Demo screenshots and worked examples are illustrative. They do not describe a live customer result. Check your account and provider permissions for what you can do now.

Use the public waitlist if you are exploring BYOM without access. If you have an enabled account, start with a small, verifiable task.

## Four checks for any task

Availability is specific to the work you want to do. Before relying on a capability, check the account, company authority, provider access and supported operation. Passing one check does not automatically pass the others.

| Check | What you need | Example of a separate blocker |
| - | - | - |
| Account enablement | An enabled company/account under the applicable invitation or offer. | A public waitlist entry does not give access to the application. |
| Company permission | Authority to read the relevant information and decide the requested effect. | You may inspect a proposal but lack approval authority. |
| Provider connection | The correct service/store, a valid connection and required scopes. | Catalogue access does not imply customer access or a product write. |
| Feature/operation support | The specific capability available in that account and provider path. | A provider may be listed while the requested operation remains unavailable. |

## Match the requirement to the work

| Work you want to complete | Check before starting | Completion evidence |
| - | - | - |
| Read a product | Correct store and catalogue permission. | A source-backed answer about the intended product. |
| Prepare a description | Product facts, brand guidance and supported preparation. | Inspectable draft with missing facts identified. |
| Apply product edits | Supported write, provider permission and authorised review. | Receipt and individual affected-record results. |
| Investigate a customer enquiry | Appropriate order/customer consent and connected evidence. | Facts with freshness and gaps; a draft is not a sent reply. |
| Send or otherwise act externally | Supported provider operation, recipient/target and approval. | Actual provider result; an approval alone is insufficient. |
| Run repeated work | Enabled Rail, checks, source access and applicable scheduling/usage conditions. | That specific run's stages and completed result. |

Use this table for enabled capabilities. If applying a change is unavailable, you can still use the draft or diagnosis, while keeping its unfinished next step clear.

## Inspect the account's actual state

Begin in the authenticated app's Integrations page for provider access, then the relevant work or feature page. Read unavailable or blocked states and any suggested recovery. If a permission cannot currently be requested, reconnecting repeatedly is not a solution. If the source is stale, inspect its last-read information before asking for a new decision.

For a supported external MCP client, use tool discovery and the connection overview to inspect the current grant, scopes and usage. A tool list saved from another company or an earlier consent is not the current contract. See [Developer overview](/developers/overview) before building against the connector.

## Get the right kind of help

For account access, contact BYOM through the current public entry point or your invitation. For a connected-provider problem, identify the company, service and visible connection state. For a stopped operation, include its work reference, approximate time and the stage that failed.

Do not send a password, token or full customer record. If an execution result is uncertain, inspect the receipt and provider state before attempting it again. [Troubleshooting](/guides/troubleshooting) helps distinguish an access problem, a revised proposal and a result check.

Check the current account controls and the specific operation's evidence for what you can complete now.

Reviewed 2 October 2026.

## Related guides

* [What is BYOM?](/start/what-is-byom)
* [Your first session](/start/first-session)
* [Developer overview](/developers/overview)
* [Billing and usage](/reference/billing)


# Billing and usage
Source: https://docs.byom.co/reference/billing

Distinguish the BYOM application subscription, connector allowances and documentation access.

The BYOM application is a paid service. Use your account's offer and Billing information to check its subscription, included usage and limits before planning paid work.

## Application, connector and docs

| Surface | What it is | Where to check the commercial position |
| - | - | - |
| BYOM application | The authenticated commerce operating environment. | Your account's subscription offer and billing surface. |
| Shopify MCP connector | The Shopify app's consented connection to supported AI clients. | The connector's available plan and current usage information. |
| Documentation and any available search | Public guidance about BYOM. | It grants no product access or store authority. |

A connector allowance is not an entitlement to the complete BYOM application. Reading docs does not install the Shopify app, create a subscription or guarantee merchant admission.

## Check usage in context

For the supported connector, `about_this_connection` reports read and write usage against the active caps and the reset date. Rate controls can also apply to bursts of requests. Reaching a per-minute control and exhausting a monthly allowance require different next steps.

For the application, use the current account billing and usage information. Staff access, jobs, provider calls, storage and connected-service costs should not be assumed to be unlimited merely because people can share company access.

## Estimates are not invoices

Time-saved or impact estimates explain a modelled value of work. They are not a refund, cash balance, guaranteed return or invoice amount. Check the assumptions beside the estimate and the separate billing record for charges.

The Shopify app is coming to the App Store. Pricing and access should be verified in the actual offer when it becomes available.

## Read the labels before comparing costs

| Label | What it means | What to verify |
| - | - | - |
| Platform subscription | The company pays for its BYOM service under the agreed offer. | Price, billing period, access conditions and cancellation terms. |
| Managed Kina usage | Usage charged through BYOM for supported managed model work. | The applicable rate, measured usage and whether an allowance applies. |
| Included usage or credits | A monetary allowance against specified eligible charges. | Eligible charges, the service period and actual invoice treatment. |
| Customer-owned provider usage | Model calls made with supported customer-owned credentials. | Charges from that provider separately from the BYOM subscription. |
| Paid media/provider work | Charges for separately metered services such as image or video generation, where available. | The quote, eligibility, provider charge and any disclosed service fee. |
| Connector usage | Reads/writes recorded against the connector's active caps. | The current plan, reset date and burst-rate controls. |

These labels explain different costs; they are not a public price list. A source catalogue or example price does not establish your offer, taxes, eligible allowance or final invoice. Use the account's actual commercial information before committing to work.

## BYOT: customer-owned model credentials

BYOT means bring your own token. Where this option is supported, a company supplies its own model-provider credential through the approved account setup. The provider bills that company's usage under its provider account. BYOM records the model usage for audit, but does not add a BYOM model-usage charge for those supported customer-owned calls. The BYOM platform subscription still applies.

The platform subscription, provider's own usage and other separately paid services still apply. It also does not remove company permissions or the Action boundary around consequential effects. A credential provides provider access; it is not a grant of approval authority.

Use only the supported credential setup supplied with your enabled account. Never paste a provider key into Kina, a documentation search, an MCP query, a screenshot or a support message. Confirm which credential source is active before using the billing distinction to estimate a task.

## Included allowances are scoped

If your offer includes Kina usage, check the eligible charge category and the actual subscription service interval. Do not assume an allowance applies to image/video generation or every connected provider charge. A connector's monthly cap and the application's subscription period are also different concepts.

Check the invoice or account statement to see how the allowance was applied. A displayed usage total may be a gross measurement rather than the amount finally charged after the offer's adjustments. Conversely, a remaining allowance indicator is not evidence that a completed invoice applied it correctly. Ask for clarification if the usage, allowance and invoice cannot be reconciled.

## Check a task's cost before its effect

For a task using a paid provider, identify the provider, proposed work and any available estimate or limit before approval. An estimate should say whether it comes from an actual provider quote or an assumption. A useful commercial decision needs both the expected value and the possible charge.

After work, compare the recorded usage, provider result and billing record. A failed or timed-out response does not automatically mean the provider charged nothing. Establish the result before retrying a costly operation, and keep the work reference if a charge needs investigation.

Unlimited staff access concerns people in the company; it is not unlimited concurrent execution, jobs, storage, support or paid provider use. An unavailable operation may require a connection or capability fix rather than a more expensive plan. Identify the actual limit before deciding what to change.

## Understand the limit on extra usage

Where the application's Billing section shows these controls, **Included usage** describes measured use against the allowance for the current period. **Extra usage so far** describes usage beyond that allowance. Read the stated period and source beside the figures; these are usage records, rather than an upcoming invoice.

The **Limit on extra usage** is a monetary ceiling. **Off** at £0 means extra usage is disabled; it does not mean unlimited use. The limit concerns paid usage covered by that control together, so separate tasks can consume the same remaining headroom. A single-job confirmation threshold is a separate check from the period's total limit.

For example, an account can still have included usage remaining while extra usage is off. Once that included allowance is used, a notice such as **Included usage used, extra usage off** identifies the cost boundary. **Extra usage limit reached** identifies a different boundary: extra usage was permitted and has reached its ceiling. Neither notice means that your provider connection needs to be repaired.

Check the current account offer, remaining usage and available billing controls before planning more paid work. If changing the limit is not offered in your account, ask the authorised account owner or BYOM about the available path. Do not assume that a read-only display is an editable budget control, that a pause erased previous charges, or that a renewal date applies to an access-code account in the same way as a subscription.

## Manage the account and resolve a discrepancy

Use the billing or customer-portal path supplied with the account to inspect invoices and supported payment, billing-address, tax or cancellation controls. Do not assume a self-service plan change is available; ask BYOM about the current offer and transition if the portal does not provide it.

For a disputed or unexplained charge, retain the invoice period, work reference, visible usage category and provider result. Ask which allowance and rate apply. Exclude card details, keys and customer payloads from the support request. Access-code and pilot accounts can have a separate agreed commercial position; check their agreed allowance and service period.

Verify amounts against the current account offer and invoice. Customer terms govern the charges.

Reviewed 2 October 2026.

## Related guides

* [Availability and access](/reference/availability)
* [Errors, limits and retries](/developers/errors-and-limits)
* [HQ and Workspace](/product/hq-workspace)


# Your first session
Source: https://docs.byom.co/start/first-session

Get oriented, check your connection and ask Kina for a small, verifiable piece of work.

Start with one question you can check, such as how to improve a product description. Kina can read the available facts and prepare a draft for you to review.

## Before you start

You need an invited or otherwise enabled BYOM account, access to the correct company, and permission to read the information for your task. For a store question, the relevant provider connection must also be available. An account invitation does not grant every provider permission, and reading these docs does not create an account.

Choose a task you can check yourself. One product description is a good starting point: you can compare the source facts, the original text and Kina's proposed wording. Have the product name or reference and the relevant brand guidance ready. If the guidance is missing, say so instead of asking Kina to invent it.

<Frame>
  <img alt="Demo BYOM HQ showing work that needs attention and links to the work board" />
</Frame>

<Steps>
  <Step title="Check where you are">
    Open the authenticated BYOM application with your invited or enabled account. Confirm the company context before asking about its business. HQ is the home page; Workspace is where work records live.
  </Step>

  <Step title="Check the source">
    Open Integrations and confirm the relevant store or service is connected to the expected company. Inspect its current state and the capability needed for this task. A connection alone does not guarantee every operation is available: the account's permissions and the provider's scopes matter too.
  </Step>

  <Step title="Ask a bounded question">
    Try “Review this product description against our brand guidance. Show the source facts and suggest three improvements.” Name the product and the intended result.
  </Step>

  <Step title="Check the answer">
    Read the sources, missing information and proposed next step. If a store change is prepared, review the actual Action in Approvals before approving it.
  </Step>
</Steps>

## Work through one product

Give Kina a clear brief:

> Review the description of our linen shirt. Use the current product facts and our brand guidance. Identify missing care information, flag claims the source does not support, and draft a clearer description. Show the current and proposed text for review.

This asks for research and preparation. You should be able to inspect the product being discussed, the facts used, the proposed wording and any missing information. If Kina identifies the wrong product, correct that before continuing. If it cannot read the source, restore access or provide appropriate source material before relying on the draft.

Ask a follow-up when the draft needs work: “Keep the material wording exactly as the source says”, or “Remove the claim that is not supported.” A polished draft needs to preserve the facts that matter.

## If you want to apply the change

When the account supports that operation, ask for the reviewed draft to be prepared as a change. Open the Action and compare every affected field with the source. Check that a description task has not also changed a title, price or destination. The person deciding must have the relevant company authority, and the provider must grant the required write permission.

Approval and execution are separate. After the operation, inspect the receipt and the affected product through the supported result view or provider. If several products were included, inspect the individual results. The completed edit proves the description changed; it does not prove better conversion or increased revenue.

For the full decision sequence, use [Review a proposed change](/guides/review-a-change). Stop at a useful draft if applying changes is unavailable; preparation still gives you a concrete result to evaluate.

## Know whether you finished

| Your intended result | What to check |
| - | - |
| Understand a problem | The answer names the right subject, its sources and any gaps. |
| Get a draft | You have usable proposed wording grounded in the product and policy facts. |
| Prepare a change | The Action shows the exact operation and every affected record. |
| Apply a change | The receipt reports individual results; check uncertainty before retrying. |

## Recover from a blocked first task

If the source is missing, check the company, connection state and read permission in Integrations. If you can read but cannot prepare a change, check the supported capability separately. If the approval control is unavailable, ask the appropriate company approver.

A timeout after a change request needs a result check. Do not repeat the request until the receipt and provider state establish what happened. Record the task reference, time and visible status if you need support; leave tokens and full customer records out of the message.

## What to expect from access

Kina can prepare internal work without asking for an approval at each step. A provider permission failure needs a connection or permission fix. An external change needs its own approval.
If you have no enabled account yet, use these docs to understand the workflow and the public BYOM site to register your interest. Contact BYOM about account access.

Reviewed 2 October 2026.

## Related guides

* [HQ and Workspace](/product/hq-workspace)
* [Connections](/product/connections)
* [Review a proposed change](/guides/review-a-change)


# Glossary
Source: https://docs.byom.co/start/glossary

Plain definitions of the names used across BYOM and these docs.

Use these definitions to follow a job from Kina's preparation through approval and its recorded result.

| Term | Meaning |
| - | - |
| BYOM | The application that governs commerce work, access, approvals and evidence. |
| Kina | The AI operator that reads, analyses, drafts and prepares work for you. |
| Company | The business context that owns its work, connections and access. |
| HQ | The home page that helps you see what needs attention. |
| Workspace | The board and records where ongoing work becomes visible. |
| Connection | An authorised link to a store or another supported service. |
| Integrations | The application page where you inspect connected services, their state and supported capabilities. |
| Action | A reviewable proposal for a consequential or external change. |
| Approval | A person's authorisation of the specific change shown for review. |
| Receipt | Evidence of what an operation attempted and what its result was. |
| Undo | A supported reversal of a specific change, where available. |
| Brand Memory | Source-backed company and brand context used in work. |
| Memory | Explicit personal notes or reviewed company facts and instructions saved for Kina. |
| Readout | A board of questions answered from your data, with sources and calculations. |
| Rail | A job Kina does on repeat, checked at each stage and signed off before a store change. |
| MCP | Model Context Protocol: the connector contract supported AI clients use to discover and call tools. |
| Grant | The access a person consents to give a connected MCP client. |
| Scope | A permission granted by a provider, such as permission to read Shopify products. |
| Data class | A category of information consented to for an MCP client, such as catalogue or brand context. |
| Capability | A supported operation available in the current account, source and permission context. |
| Source | The record, document or connected information used to support an answer. |
| Freshness | When information was read or updated; it helps you judge whether the evidence is current enough. |
| Partial | A result with incomplete coverage or only some operations completed. |
| Unavailable | Information or an operation that could not be accessed; it is not a measured zero. |
| Watch | An available threshold check that can open work when a Readout crosses a line; it grants no provider-write authority. |
| BYOT | Bring your own token: customer-owned model-provider credentials for supported usage. Provider charges and the BYOM subscription remain separate. |
| Included usage | An account's allowance against eligible usage charges, governed by its offer and billing period. |

## Words that are not interchangeable

A **draft** has been prepared. An **approved** change has been authorised. A **completed** change has a reported execution result. A **measured outcome** needs evidence after the change.

Similarly, unavailable data is not zero, a forecast is not a sale, and an estimated saving is not money received. Check the relevant source and result before deciding what to do next.

## How the terms fit together

You ask **Kina** a question in a **company** context. It uses an available **connection** and permitted **data classes** to read a **source**. An answer or draft should make the source, **freshness** and any **partial** coverage clear.

If you request a consequential change, it becomes an **Action** for the appropriate person to review. **Approval** authorises the shown version. The **receipt** records execution results. **Undo** is a separate supported reversal, subject to the current provider state and permissions.

An MCP **grant** and a provider **scope** work at different boundaries. The grant says what a connected client may access through BYOM; the provider scope says what the provider allows BYOM to read or change. Both can matter to the same operation. Neither is a substitute for company authority or approval.

## Interpreting statuses

| Phrase | What it tells you | What to do |
| - | - | - |
| Prepared or drafted | Internal work exists for inspection. | Read it and check its facts; do not assume publication. |
| Awaiting approval | The shown effect needs a decision. | Review the target, fields, risk and reversal information. |
| Approved | The reviewed version was authorised. | Inspect the execution result separately. |
| Completed | The operation reports a finished result. | Read the receipt and relevant provider evidence. |
| Partial or uncertain | Some part remains incomplete or unresolved. | Establish the individual result before retrying. |

For numerical evidence, **zero** is an actual or defined zero in the included data. **Unavailable** means it could not be read. **Partial** means the figure covers less than the expected sources or records. Replacing the latter two with zero can change the meaning of a result.

Reviewed 2 October 2026.

## Related guides

* [Approvals and Actions](/product/approvals)
* [Receipts and undo](/product/receipts-undo)
* [MCP connector](/developers/mcp)


# What is BYOM?
Source: https://docs.byom.co/start/what-is-byom

An operating layer for commerce teams, with Kina doing the work and people governing consequential changes.

BYOM gives commerce teams one place to investigate questions, prepare work and review changes across their connected tools. Kina is its AI operator: it reads, analyses, drafts and explains. BYOM keeps the company context, work records, approvals and receipts together.

## How the pieces fit

Start in **HQ** to see what needs attention. Ask **Kina** to investigate or prepare something. Keep ongoing work in **Workspace**. Check access in **Integrations**, review proposed Actions in **Approvals**, and inspect the resulting receipts.

For example, ask: “Find products whose descriptions do not explain the material clearly. Draft better descriptions using our brand guidance.” That is research and preparation. Applying those descriptions to your shop is a separate, reviewable change.

## What you can use it for

Choose a specific job and check that your account has the sources and capabilities it needs. These examples explain the operating model; they do not promise every operation is enabled for every company.

| Job | Useful preparation | What needs separate review or proof |
| - | - | - |
| Improve a product description | Compare current text with product facts and brand guidance; draft a clearer version. | Applying edits requires a supported change and approval; commercial improvement needs later measurement. |
| Investigate a customer enquiry | Bring together available order evidence and the brand's policy; prepare a response. | Sending, refunds and other effects have their own capability and approval requirements. |
| Explain a change in trading | Inspect a Readout's sources, period, calculation and comparison. | Missing data stays visible; an apparent change does not establish its cause. |
| Prepare growth work | Research a defined question and produce evidence-backed alternatives. | Publishing, channel activation and spend need the relevant effect authority. |
| Repeat a useful job | Understand the Rail's inputs, checks and stopped stages where enabled. | Scheduling and a prior successful run do not authorise every future provider change. |

## What stays in your existing tools

Shopify, a helpdesk and other connected services continue to hold their underlying business records. BYOM supplies the operating context around work across those tools: what was asked, what evidence was available, what was proposed, who could decide and what happened afterwards.

Check company access, provider scopes and support for the operation alongside the connection. A readable product catalogue does not imply customer-data access or write authority. Check the particular capability you need rather than assuming a provider logo covers everything.

## Where to use BYOM

| Place | Use it for | Boundary |
| - | - | - |
| [BYOM website](https://byom.co) | Introduction, enquiries and the current public entry point. | A waitlist or enquiry is not product admission. |
| [BYOM application](https://app.byom.co) | Work in an enabled account's company context. | Authentication, account permissions and provider access apply. |
| This documentation | Product explanations, task guides and developer context. | Public guidance does not expose account-specific records or execute store changes. |

## How to judge a useful result

Follow the work from a question to a checkable answer or draft. If you want an effect, inspect the exact Action and its supported reversal before deciding. Then inspect the receipt. A completed provider operation and a measured business outcome need different evidence.

For example, changing a product description is an operational result. Showing that it increased sales needs a defined measurement period, compatible traffic and other relevant context. Documentation examples and demo screens explain the workflow; they are not customer results.

## Who these docs are for

Merchants can learn the operating model and how to review work. Developers can learn the supported Shopify MCP connector contract. Reading this documentation does not require a BYOM account.

BYOM's main application, its Shopify connector and any search offered on these docs have different purposes. Documentation search helps find public guidance; it grants no store access or approval authority. The Shopify app is coming to the App Store. Contact BYOM about access.

## Start with one useful question

Choose something small enough to check: a product, a policy, a date range or a known customer enquiry. Ask for sources and call out what would make an answer useful. Expand the work after checking the result.

Reviewed 2 October 2026.

## Related guides

* [Your first session](/start/first-session)
* [Kina](/product/kina)
* [Availability and access](/reference/availability)


# Data and access
Source: https://docs.byom.co/trust/data-and-access

Understand company access, provider permissions, connector consent and deletion requests.

Access depends on your company membership, provider permissions and any client consent. Connecting a service does not make all its data available to every person or every AI client.

## Keep context appropriate

Confirm the company and store before working. Use supported account roles and sharing controls for commercially sensitive information. A private Readout and a shared company Readout have different audiences.

Brand context should contain information useful for company work. Avoid saving unnecessary personal data or credentials as broad company memory. A source or policy correction should remain distinguishable from an inferred suggestion.

## Shopify connector data

The Shopify connector separates catalogue access from optional order and customer permissions. Order or customer functionality depends on merchant grants and applicable Shopify approval. Check the current grant before requesting customer data.

The supported Shopify connector masks customer email addresses before exposing them to an AI assistant or record and does not read customer phone numbers. This protection applies to that connector path. Check other services and uploaded documents separately for personal data.

## External AI clients

An MCP grant controls the data classes that a connected client can use. Read the consent screen and the client's own data-handling terms. Giving catalogue access does not mean giving brand or analytics access automatically.

Never pass a connection secret through the model. The supported connector uses bearer authentication and grants; a model prompt is not a credential store.

## Check access before an investigation

Open Integrations in the correct company and inspect the relevant connection. Check whether the provider is connected, whether its permissions cover the task and whether the account supports the operation. A catalogue question, an order enquiry and a customer lookup can require different access.

If you are using an external AI client, inspect the client consent as well. For the Shopify connector, [the connection overview tool](/developers/mcp) describes the grant's data classes, write enablement, provider scopes and usage. A missing capability may reflect consent or provider permission; retrying the same request does not add either.

| Boundary | Question to ask | Appropriate next step |
| - | - | - |
| Company | Am I working in the right business context? | Confirm company and task before using its information. |
| Provider | Does this store grant the required read or write permission? | Use the supported consent or reconnect flow when needed. |
| External client | Did the merchant consent to this category of data? | Inspect the current grant rather than assuming catalogue access includes customers or brand context. |
| Shared output | Who will be able to read this result? | Check sharing controls and remove unnecessary sensitive details. |

## Keep source data and broad context distinct

A customer enquiry may need specific order evidence. That does not make a full customer profile useful as a company-wide memory entry. Keep the minimum relevant facts with the supported enquiry and work record, and avoid duplicating personal data in unrelated notes.

Brand policies and explicit instructions can be shared business context. An inferred preference or a source summary is different from an owner-confirmed instruction. If the sources conflict, identify the disagreement and correct the underlying material through the supported control. Do not use a convenient summary to overrule the actual policy.

Before sharing a Readout, check that the intended audience should see its figures and supporting context. A new Readout is private to its maker; sharing moves it into the company audience. Check commercially sensitive figures before sharing them.

## What happens when you revoke access

Revocation or disconnection changes future access through the affected grant or provider link. It does not make a previously sent reply unread, remove copies held by another service, or erase every work record already retained under the applicable policy.

Treat access recovery and deletion as different tasks. To recover access, use the supported account/provider flow and verify the new grant before resuming work. To request deletion, follow the applicable privacy process and identify the account or work concerned without posting raw data into a general conversation.

For an external client, check both BYOM's grant controls and the client's own account and retention terms. For deletion from an independent client's systems, use that client's own process.

## If access is unexpectedly broad or missing

Stop the affected request and record the company, task reference, visible error or grant state and approximate time. Do not include the token or full result payload in a support message. If a provider change has an uncertain result, check the receipt and provider state before retrying. If data access is refused, address that permission boundary rather than trying another company or client to bypass it.

Reviewed 2 October 2026.

## Related guides

* [Authentication and consent](/developers/authentication)
* [Connections](/product/connections)
* [Brand Memory](/product/brand-memory)


# Trust and control
Source: https://docs.byom.co/trust/overview

How company context, approvals and evidence shape the BYOM operating model.

BYOM keeps company access, proposed changes and recorded results together. Check those records to see who could decide, what they authorised and what happened.

## Capability and effect

Research, reading, calculations and draft preparation do not need a separate approval at every step. They still operate within company access and supported capabilities. Approval belongs at the consequential effect, such as changing a store or sending a customer-facing reply.

This gives you room to investigate without turning an investigation into permission to publish or spend. A natural-language request does not remove the review boundary.

## Decisions need context

A useful review shows the intended operation, affected records, exact proposed change, relevant risk and supported reversal information. Approve the version you inspected. Read the receipt afterwards to distinguish completion from partial or uncertain work.

## Evidence needs labels

A source observation, a forecast and an estimated saving are different kinds of information. A screenshot of a demo workspace is illustrative. A provider change needs a completed result; a merchant outcome needs its own measurement.

These docs use examples to explain workflows. Example figures and screenshots are not evidence of a customer result, and a documented capability does not guarantee it is enabled for every account.

## Check the current agreement

The legal terms and privacy information supplied with your enabled account govern that service. This page explains the product model; it is not a certification claim, a service-level agreement or a promise that every operation can be undone.

For personal-data questions, use the applicable privacy process and avoid sending secrets or raw customer records in a general support message.

## Check the controls for one job

Start with the company and the source. A request about one store should not silently use another company's records. Then ask what Kina read and what it prepared. A draft can be useful without authorising an external change.

Before a consequential change, inspect the specific Action. Check the target, every affected field, supporting evidence, the deciding person's authority and the provider's current permission. A valid login, a connected service and an approval solve different parts of this path; none proves the operation completed.

<Frame>
  <img alt="Demo Action panel showing its proposed order change, risk and decision controls" />
</Frame>

Use the receipt after execution. A failure before the provider received a request differs from an uncertain response after the provider may have accepted it. If the result is uncertain, check the provider state and supported recovery path before sending it again. Undo is conditional and may itself need a reviewed operation.

## Different kinds of permission

| Control | What it concerns | What it does not establish |
| - | - | - |
| Company membership and role | Your permitted work and decisions in that company. | A provider's permission to read or write its records. |
| Provider connection and scopes | The service and operations BYOM may access. | Every employee's or AI client's access to every data class. |
| MCP client consent | The information and supported proposals an external client may use. | Blanket model-driven confirmation authority. |
| Action approval | The exact consequential operation reviewed. | Completion, future versions or all later edits. |
| Receipt and provider evidence | What happened during an operation. | A guaranteed business outcome or universal reversal. |

## Match evidence to the decision

For a description edit, check the product facts and changed fields. For a customer reply, check the recipient, order evidence, policy and any promise. For a growth recommendation, check the period, coverage and distinction between observed data and a forecast.
A figure should have enough context to interpret it: source, time period, calculation and missing data. A source can be genuine but out of date; a calculation can be correct but cover only part of the business. Ask what is unavailable rather than treating polished presentation as certainty.

## Handle a concern without spreading data

Stop the affected operation if the company, recipient or record looks wrong. Record the task reference, approximate time, visible state and what you expected. Use the service's supported support or privacy process. Send only the details needed to locate the work; exclude passwords, tokens and complete customer records.

Use the service's legal and account documentation for certifications, hosting location, retention and contractual commitments.

Reviewed 2 October 2026.

## Related guides

* [Data and access](/trust/data-and-access)
* [Approvals and Actions](/product/approvals)
* [Availability and access](/reference/availability)