First action: invoke the host's installed create-canvas skill with
skill({ skill: "create-canvas" }). If already active, continue that invocation.
It is the source of truth for native scaffolding, SDK registration, lifecycle,
scope and activation. Follow its workflow, including its native scaffold step.
Apply this companion at the customization/build step, then return to that
workflow for verification. If unavailable, report that the required app skill
is missing; do not invent a replacement host workflow.
1. Choose the starter and package
For Azure requests, use --template azure-resource-groups. It already includes
auth, explicit subscription selection, a bounded reader, cancellation, shared
UI/agent state and the subscription picker. Do not generate a counter and
rebuild this wiring. Omit the template option for a generic counter.
Confirm one compatible toolkit source: an exact published npm version with
/build, or a local npm-pack tarball. Do not invent a published version, use
tags/ranges, publish a package, or switch sources after a failed installation.
Use the host-created canvas ID and extension.mjs. Its directory must contain
only that file. Choose a separate, new source-app directory under an existing
parent. Resolve symlinks in input/output paths first; setup rejects them and
does not merge existing projects.
2. Generate the source app
From this installed skill's directory, replace the placeholders:
node scripts/setup-toolkit.mjs --name my-canvas \
--scaffold "<native-scaffold>/extension.mjs" \
--output "<existing-parent>/my-canvas-source" \
--toolkit-version "<exact-version>" \
--template azure-resource-groups
Alternatively, replace --toolkit-version with
--toolkit-tarball "<toolkit-package>.tgz". Choose exactly one.
Setup copies the native entry unchanged and creates the app's package, source,
assets and build checks. It performs no install, sign-in or resource read.
It refuses any existing destination, including identical output. Registry mode
is offline until npm install; an incompatible installed package fails build.
The Azure template requires the full exported plugin, including bundled guides.
3. Connect and build
Follow the generated README to import attachToolkit into the copied
src/extension.mjs and wrap the existing createCanvas options. Preserve native
metadata and session wiring. The adapter replaces scaffold demo callbacks and
chains close handling; custom callbacks or shutdown handlers need explicit
integration. Do not create a second provider.
npm install
npm run build
npm test
For Azure, also run npm run smoke with installed Chrome or CANVAS_BROWSER.
Do not download a browser automatically. Keep checks scoped to the generated
app during iteration, and retain its lockfile for later npm ci.
Source generation alone is NOT READY. Build checks the emitted host entry's
registration and toolkit connection using a test SDK adapter. This executes
trusted code; it is not native-host activation. Return to the host skill to
install the whole dist/, reload the provider and verify the actual panel.
4. Customize without changing the contracts
- UI and agent calls use the same validated actions and state. No raw prompt forwarding or separate chat-only Azure implementation.
- Azure mode is lazy: no profile read, login, default subscription selection, resource query or cloud write on open. Each panel owns its scope and results.
- Keep credentials server-side, cancel obsolete work and reject stale results. Empty success, missing scope, errors and cancellation must remain distinct.
- Use labelled
{"mode":"fixture"}data for tests. Do not report it as live Azure. - Use toolkit controls (
ui/dom, withui/styles.cssthenui/base.css) and host type tokens for new UI. Keep body text normal weight and headings modest; avoid hand-styled buttons. The Azure starter adds no product telemetry. - Keep the generated build's dependencies and asset layout. Check decoded images as well as controls; do not replace missing assets with SVG rewrites.
- State is ephemeral. Follow the host skill for persistence and shutdown. A panel refresh is not a provider reload; check the displayed build ID.
When adding product telemetry
Do not add telemetry by default to generated apps. If requested, use the shared toolkit collector and follow Product-usage telemetry. Update Usage data in the public and packaged README, link to the shared disable instructions, and review the emitted notice. Test opt-out behavior, not README phrases.
Use the integration reference for adapter/build details and the Azure quickstart for customization. Toolkit guide links are assembled in the exported plugin, not maintained as copies in the source tree. Installation, publication and cloud mutations remain separate user decisions.