Guide and knowledge

Guide is the application's help and declared-task interface. Use it to understand the current page, follow an authored tour or run a supported workflow. It is separate from Agent's general project work and from the Local AI engine that can supply inference.

Before you begin

For packaged application help, include the Guide Sidecar in that application's build. Authored help and tours do not require a loaded model. Natural-language task selection can use an available inference provider, but a model does not create missing help, actions or permissions.

For project-specific help authoring, open the intended project in cApp. Keep end-user help separate from source notes, incident logs and private project knowledge. The public Developer Docs site explains cApp; it does not automatically become your application's authored Guide release.

Find help or run a supported task

Guide combines three views: Tour introduces the product; This page shows articles relevant to the current route; Ask & tasks searches help and offers declared workflows.

1. Open Guide in the application you are using. Use This page for a control or screen you are already looking at.
2. Ask a concrete question, such as “How do I build a Windows installer?” Include the platform and action instead of asking only “How do I build?”
3. Open the cited article and check that it applies to your platform and selected app. A search result is reference material, not evidence that an action ran.
4. For an offered task, inspect the workflow, supplied values and mode before starting. Watch the application's actual result and cancel pending progression when the task is no longer wanted.

Use Agent when you need broader project inspection or source work. Use Guide when the answer or action belongs to the application's authored help and declared tasks.

Product help and project evidence

There are separate collections with different purposes:

The reviewed cApp Guide corpus and this website have separate publication paths. Editing a public website article does not automatically revise every installed Guide bundle. Check the cited source rather than assuming two similarly named articles are the same version.

Broker-backed retrieval citations identify the source, line range and content hash. Re-read a changed or removed source rather than relying on a stale citation. A document's public rating describes whether it may ship; it does not authorise a command contained in the text.

Search settings

Agent's gear opens retrieval settings for result limits, project Guide, public cApp help and optional semantic retrieval. In its Workflows menu, knowledge options manage the selected project's evidence. Search the correct collection before increasing result counts.

Keyword search works without an embedding model and is useful for exact controls, tool names and errors. Hybrid search combines keyword results with local embedding similarity. The UI reports the mode actually used, including keyword fallback when semantic retrieval is unavailable.

To enable hybrid search, explicitly choose Set up embedding model, then enable semantic retrieval and save. This uses a separate small embedding model, not merely the chat model already loaded in Local AI. Ordinary questions do not download embedding models or send the indexed documents to a hosted embedding service. The local index can be rebuilt from its original sources.

Project search excludes old history and legacy/rework documents by default. Enable Include historical project docs only for an investigation of earlier behaviour. This changes visibility; it does not delete retained snapshots. Review imported or added knowledge for scope and privacy before making it available to a workflow.

No matches means the selected evidence is missing or retrieval did not find it. Restate the query with platform and task, verify the collection and source, and do not treat a model's plausible completion as a substitute for a citation. Retrieval can select an irrelevant article; platform/task wording and source inspection remain important.

Guided tasks

A workflow declares its actions, targets and valid inputs. Guide cannot safely improvise a new app operation merely because the model can describe one.

All modes remain cancellable. Cancelling stops pending progression, not an operation already completed. Application validation, wallet confirmation, permissions and business rules still apply. A task that needs funds, a network connection or a registered handler does not gain those prerequisites from Guide.

For a failed task, inspect its last completed action and current application state before starting again. A completed click is not proof of a completed payment or generated report.

Author help for your application

Projects includes a project Guide workspace. Use Guide authoring for the development draft and Guide release for an immutable user-facing version.

1. Open the project and establish its application source/release in Build. Select the Guide Sidecar for the application.
2. In Projects, use Open Guide folder or the Project draft manifest editor to work on the draft. Guide authoring links the selected application's Guide to that project draft.
3. Author articles, experiences and workflows using the existing capp.ftue-manifest.v1 format and Guide API reference. Keep target IDs stable and make descriptions useful to end users.
4. Choose Save project draft, then test the help and declared tasks against the actual application.
5. Enter a new release version and release notes, then choose Publish immutable version. Publishing here writes a local Guide release; it does not upload a website or Showroom listing.
6. Select that version under Current release, choose Use selected version when switching releases, then Guide release to package the user mode. Build and test an updated application.

The existing compatibility folder is named FTUE; the product-facing name is Guide. Published versions are retained rather than overwritten. A later draft edit does not change the help shipped in an older package.

Review the public release before packaging: exclude private documents, owner-only authoring controls, credentials and unsupported tasks. If attaching help to Showcase, select the immutable user release, not the mutable authoring draft.

Start with a help-only manifest

For the Settings test fixture in the testing guide, this is a small authored-help starting point. Paste it into Project draft manifest only in a new example project; it replaces that draft rather than appending to an existing collection of help.

{
  "protocol": "capp.ftue-manifest.v1",
  "experienceId": "main",
  "revision": 1,
  "title": "Settings help",
  "settings": {
    "autoStart": false,
    "ftueEnabled": false,
    "showHelpButton": true
  },
  "targets": [],
  "steps": [],
  "docs": [
    {
      "id": "save-display-name",
      "title": "Save a display name",
      "body": "Open Settings, enter a display name and choose Save. The example shows a confirmation on screen. Reloading the example resets it; it does not save your name to a server.",
      "routes": ["*"],
      "tags": ["settings", "name", "save"]
    }
  ],
  "workflows": []
}

This declares one help article, no tour targets and no automated actions. Keep Show the floating help button enabled and first-run onboarding disabled in the selected Guide configuration too. Test it in authoring mode, then publish and select a user release. Add tours and workflows only after their targets and handlers exist in the application. The stable manifest protocol retains ftue for compatibility; a similarly named knowledge-index document is not a substitute.

Connect declared application actions

Use window.capp.guide; window.capp.ftue remains a compatibility alias. Add stable data-capp-guide-id targets and register namespaced handlers through registerAction. The application owns validation and authorization inside each handler. A label or selector is not a security boundary.

Start with one low-risk workflow, such as filling and running the application's existing search. Verify its inputs, target resolution, cancel behaviour and visible result before adding more consequential actions. See the Guide application API for registration, task, search and status interfaces. A disabled first-run tour can coexist with help and workflows; it does not require removing Guide entirely.

Troubleshooting

What success looks like

Help points to the intended source, the selected workflow uses only declared actions, and the app's result matches the user's request. A distributed app includes a reviewed user Guide version rather than private authoring state. Continue with Working with Agent or Test an application surface.