hcifootprint-adoption

Use the application's existing routes, controls, handlers and permissions.

Before coding, inspect the installed package version and exports. Read the maintained API guide. Its version and import inventory are generated from the repository's package.json; installed declarations take precedence when the application uses an older release. Do not upgrade the application's dependencies unless the task calls for it.

Start with the quick start and adoption ladder.

Connect the app

Reuse route, journey and live-action sources where available. For Session serving, connect existing handlers with registerActions or fromLiveStore. Report actual page and state changes through sync and updateState.

Callable defineAction/ActionRuntime bindings are a separate surface: they do not automatically become Session affordances or served tools. Read the action-binding guide when the task needs those bindings.

Retain each native invocation immediately and return its broker handle with the observed state. Deliver actual progress and settlement events through the host; keep transport cancellation/deadlines outside business settlement. Do not hide the handle behind an indefinite effect wait or infer completion from a timer.

For a continuing task, choose the existing layer:

• Session journeys describe named flows across pages and model turns. Use the served ready/later steps, human pauses and settlement results to choose the next move; a journey is not an automatic batch executor.
• Callable walks use beginWalk(runtime, 'agent') for a known sequential plan. Each step rechecks its live offer; explicit carry uses an earlier declared produces. Render onRow manifests and retain interruption reasons. Replan or ask a person when a new decision is needed.
• For progress within one callable action, declare settle.progress, report actual stages with reportProgress, and subscribe through invocation.progress. Progress is not effect verification. A walk's completed means its invocations performed, not that every effect was verified. Callable walks are not automatically served through Session/MCP/WebMCP.

Parallel actions require 3.2.0 or newer: use walk.parallel(steps, { concurrency, onRow }) for independently available actions/background work, with no carry between parallel items. Its concurrency limit bounds running invocations; completion does not await every effect. Read the parallel guide for ordering, failures and interruption.

Keep navigation-dependent page-1 → page-2 work sequential. node is a binding label; neither it nor different node names prove visibility or independence. The app must disconnect unmounted controls, or report enabledness for the active page when hidden controls remain mounted. Separate browser contexts exist only if the host provides them. Browser automation can also batch: choose based on declared semantics and actual evidence, not an assumed model turn per click.

Choose the host boundary the application needs:

• Direct integration: serveToAgent(session), then tools() and call().
• MCP: mcpServer from hcifootprint/mcp; the MCP SDK is an optional peer.
• Browser WebMCP: registerWebMcpTools from hcifootprint/webmcp, with an explicitly supplied host context and owner AbortSignal. Read the compatibility and lifecycle guidance before registering tools, especially from a React effect.