Guide

Integrate with application-owned actions

Guide combines product-authored help, optional onboarding, tours and declared workflows. It can explain how your app works without a model, and can call bounded actions registered by that application when a workflow needs to do something.

Use window.capp.guide; window.capp.ftue remains a compatibility alias. The package ID remains uk.capp.sidecar.ftue and the help document protocol remains capp.ftue-manifest.v1. Do not rename those identifiers simply because the user-facing name is Guide.

Guide owns help and workflow presentation. Your application owns state, validation, permissions and business effects. A workflow completion message, local-model answer or Guide confirmation is not a replacement for the product's own authorisation and postcondition checks.

Before you integrate

Select Guide for the application and target, author a small help document or workflow, then choose the appropriate release/mode. Windows and Android are declared package targets; a public Showcase uses a separately projected user-mode browser composition. Do not infer that every native feature is available in a browser demo.

Use stable data-capp-guide-id attributes on targets instead of layout-dependent selectors. Keep action registration in the active application document; the outer shell and the app frame are not interchangeable owners. An authored workflow must reference a registered action ID and a resolvable target before it can run.

Use Guide and knowledge for authoring, project drafts and immutable user releases. This page describes the application integration. A production user release should contain public product help, not an internal project knowledge dump or authoring endpoints.

Register one bounded action

This complete example fills a search field and reports that narrow postcondition. It does not pretend to execute a search. For a real search, call the application's existing validated search operation inside the handler and return only the result it actually observed.

<label for="guide-search">Search this app</label>
<input id="guide-search" data-capp-guide-id="search.query" maxlength="120">
<p id="guide-search-result" role="status"></p>

function registerSearchGuide(input, output) {
  if (!input || !output) throw new Error('Search elements are missing');
  const guide = window.capp?.guide;
  if (typeof guide?.registerAction !== 'function') {
    output.textContent = 'Guide is unavailable; the search field still works.';
    return () => {};
  }
  return guide.registerAction({
    id: 'example.search.fill',
    title: 'Fill the search field',
    description: 'Set the query without submitting a search.',
    arguments: { query: { type: 'string', maxLength: 120, required: true } }
  }, async ({ query }) => {
    const clean = String(query ?? '').trim();
    if (!clean || clean.length > 120) throw new Error('Enter a query of 1–120 characters');
    input.value = clean;
    input.dispatchEvent(new Event('input', { bubbles: true }));
    output.textContent = `Search field prepared: ${clean}`;
    return { query: clean, fieldUpdated: input.value === clean };
  });
}
const unregisterSearchGuide = registerSearchGuide(
  document.querySelector('#guide-search'), document.querySelector('#guide-search-result')
);

Call unregisterSearchGuide() when its owning view is permanently removed. Registration itself does not run the handler. Guide's declared workflow controller invokes it; there is no public arbitrary runAction() shortcut.

Keep one owner per action ID. Registering the same ID replaces its handler; dispose the old registration before registering a new one. A stale disposer identifies that ID, not a separately versioned callback.

Action arguments are a small descriptor map, not a complete JSON Schema interpreter. The current normaliser supports declared string, number and boolean arguments, required flags, string length/enumeration and numeric bounds; it ignores undeclared inputs. Strings may be bounded and numbers clamped. Validate product-specific meaning again inside your handler rather than assuming Guide's normalisation proves it is safe to act.

Application API

Methods that cross the shell boundary are asynchronous. Use await for calls such as opening help, starting workflows, target registration and status; a same-document owner may also provide synchronous implementations.

Runtime manifest registration is a build-authority decision, not a universal user-mode API. The package may expose a method while refusing a call under the compiled mode. Do not use runtime registration as a back door to replace a published user release.

Keep a workflow step open until it is complete

An ordinary handler result completes that action invocation. When the product still needs review, another foreground action or a later status check, return a guide property containing validated progress instead of reporting success too early.

Feature-detect guide.supports.actionProgress. For a pending result, the value under guide has this shape:

{
  "protocol": "capp.guide-action-progress.v1",
  "complete": false,
  "title": "Review the next item",
  "body": "The application has prepared the item but has not applied it.",
  "label": "Review this item",
  "checkpoint": "example-review-1"
}

Return { guide: { protocol: 'capp.guide-action-progress.v1', complete: true } } only after the app verifies the postcondition. Pending progress can change the current step's title, body and button label; it cannot introduce another route, target or action. Invalid progress fails on that step rather than advancing it. Download the action-progress schema.

The next invocation receives context.checkpoint. It is a bounded opaque string held in the active workflow, not a durable operation record or an authentication token. Back, a replacement workflow or reload requires the application to reconstruct a fresh review from its own state. Bind any real operation, inputs and idempotence rules in the application.

For actions that require a fresh human confirmation, feature-detect guide.supports.userConfirmation and register requiresUserConfirmation: true. Check context.userConfirmed and your own product authority in the handler. A synthetic Test Runner click or automatic/brokered action cannot satisfy Guide's trusted-click requirement. This UI boundary does not protect an app from arbitrary hostile scripts already controlling that same document.

Controller and inference

Guide works with authored help without Local AI. Local AI can provide inference and MCP Context can provide explicit retrieval when selected, configured and available. Opening help does not itself constitute permission to download a model or perform a project operation.

Guided, auto-safe and auto-all modes control progression inside the authored target/action set. They do not give the model a general selector, network or filesystem tool. Pending action checkpoints still wait for a fresh click; a product must keep its own confirmation and permission rules even in an automatic mode.

Set ftueEnabled to false to keep help/workflows while disabling first-run onboarding. Help availability, first-run tours, action execution, speech and authoring mode are separate choices. Speech support depends on the target/provider and follows the same workflow boundaries; do not advertise a privileged OS hotword service.

A trusted knowledge provider supplies search, read and sources together. Register it through the direct app API, preserve its citation/provenance fields and remove it when its owner leaves. The general message bridge is not a grant for remote frames to retrieve private knowledge.

Website handoff and return

With guide.supports.handoff and a usable Links companion, a pending action can include an HTTPS website handoff and explicitly supplied public text. Guide holds the current checkpoint while the user reads the site, copies the supplied value and returns.

A handoff opens once per active workflow step/ID. Returning or closing the tab does not rerun the action and does not prove the external task succeeded. Recheck the postcondition on the next deliberate action. A missing Links capability, unavailable native tabs or a full tab strip skips only the handoff; keep the current app checkpoint and ordinary user-operated copy/link controls useful.

Do not include passwords, private keys, session tokens or private documents in companion text. No handoff reads the clipboard, auto-pastes, clicks a remote page or grants that page the app bridge.

Cancellation and troubleshooting

Configuration reference

These are the selected package's configuration fields. String credential values and installation-specific defaults are never published here. A field's presence does not bypass its runtime policy.

Agent interfaces

These names are declared by the package for host/Agent integration, not JavaScript methods to invoke directly. The host must register a tool, grant its scope and enforce its approval policy. A manifest declaration alone does not prove availability in every Agent catalogue. Prefer the application API above when integrating your own app.