penecho-canvas

Use PenEcho Cloud at https://penecho.ai/mcp and its live tool schemas. Prefer an already-connected production server; a verified alias is acceptable. The default connection name is penecho-cloud. A similarly named local desktop bridge is a different service: do not start PenEcho.app, search local ports, or install a local bridge for this workflow. First-time OAuth offers anonymous use; a PenEcho account is needed only for Cloud saving or PenEcho's own AI. Never request tokens or passwords in chat.

Natural-language invocation

Use this production skill for ordinary new canvas demonstrations with no explicit destination. The user need not name the skill. An explicit destination or already-bound workspace takes precedence, followed by an explicit current UAT testing selection. Merely finding an old UAT skill installed does not select UAT. Explicit UAT, local, and saved-Canvas requests retain their actual destination. Examples indicate intent, not mandatory templates or extra tasks. Use actual project evidence for architecture diagrams; do not invent components or progress. Reply in the user's language.

Automatic installation and connection

When the user requests installation of this package or its first canvas use, perform setup for the actual current host. This authorizes installing and enabling this Skill and adding its missing production MCP connection; do not ask an extra conversational permission question or merely suggest commands. Reviewing the package alone does not authorize installation. Native trust/configuration approvals and OAuth consent still apply.

Determine the actual execution surface from host context before installing. Local Claude Code and local Codex (including Codex Desktop on Windows) can use persistent user directories. Claude Chat and Cowork use account plugin/connector installation: a claude or codex binary found in their sandbox does not make that sandbox the user's persistent desktop. Never claim a sandbox copy installs a claude.ai account plugin. In a full plugin package, read root INSTALL.md first. Prefer an already-installed complete host plugin and its verified production connection. Reuse verified aliases/plugin connections, including an alias whose name differs from penecho-cloud.

For a local host without an installed complete plugin, run the bundled installer yourself from the extracted Skill directory (Node's standard library is sufficient):

# Local Codex, including Codex Desktop
node scripts/install.mjs --host codex --surface local
# Local Claude Code
node scripts/install.mjs --host claude --surface local

The installer copies the complete Skill to ~/.agents/skills/penecho-canvas/ for Codex or ~/.claude/skills/penecho-canvas/ for Claude Code, reusing a supported existing Codex ~/.codex/skills/penecho-canvas/ installation. It preserves unrelated files, MCP connections and credentials, preflights conflicts, and reuses setup-mcp.mjs for native HTTP configuration. Repeat installation and running from the installed directory are supported. An incompatible or disabled MCP server is preserved and reported; it is never automatically enabled. On Windows, native executables and official npm CLI launchers are supported without shell command interpolation.

For Codex, verify this exact installed Skill path with native skills/list (forceReload: true). If its entry is disabled, enable only that entry through actual skills/config/write with {path: <the discovered absolute Skill path>, enabled: true}, then rescan. The bundled installer attempts these supported calls through a short-lived local app-server; this verifies persistent Skill state, not the running Desktop conversation. Prefer the current host's exposed native API when available. Do not use name-wide changes, edit unrelated disabled Skills/MCP servers, or rewrite broad TOML sections. An unsupported scan yields activation.status: "unverified"; a failed targeted enable yields "enable-required". Complete that host's supported enable/reload step and verify again before claiming discovery. For Claude Code, use its actual installed Skill discovery/reload capability; copied files alone do not prove activation.

If only this Markdown was supplied, retrieve the matching complete package from the supplied attachment/link when available. If no complete package is accessible, use the host's supported Skill and native HTTP setup, state which components are missing, and never report complete installation from a pasted instruction alone. references/mcp.json is a native HTTP example, not Codex's TOML configuration. For a Claude Chat/Cowork account, use the actual native plugin upload/install capability or install card when exposed; the full plugin package also has a byte-equivalent penecho-cloud.plugin upload artifact. If only the full plugin ZIP was supplied, copy its unchanged bytes to that filename and present it using the host's actual file-delivery capability, or use the original ZIP when native upload supports it. Never relabel a standalone Skill ZIP as a full plugin. The filename does not prove install-card availability or connector authorization. A local CLI command cannot install that account plugin. If native automation is unavailable, identify the specific host-supported Upload/Install or connector Add/Connect action the user must complete with https://penecho.ai/mcp. Do not invent an installation API or unsupported UI path.

The installer always returns readiness: "verification-required". After normal host reload/reconnect, verify that this Skill is enabled and the actual PenEcho tools are visible in the current task, then perform one authenticated read-only profile or Canvas-list call using its live schema (for example penecho_list_canvases, only when exposed). MCP configuration, an OAuth browser closing, or a tool listed in package metadata is insufficient. Report the specific pending step if tools are unavailable; do not promise that the next turn will be ready. Installation alone does not request a demonstration: do not open a Canvas merely to test setup.

Configuration success is not authentication or live-tool proof. If setup saved the connection but returned authorization: "pending", resume normal OAuth rather than re-adding it. Codex may start OAuth during mcp add; keep that command running until authorization completes. Reuse the consent page already opened by the host or CLI. A printed authorization URL does not mean automatic opening failed: do not open that same URL through a second tool. Only when automatic opening is unavailable, use one browser-opening capability once and retain its tab. After OAuth succeeds, continue with live tools and never reopen the old authorization URL. For a connection needing authentication, authenticate the exact verified connection name that was reused or configured (codex mcp login <verified-connection-name> or claude mcp login <verified-connection-name> when supported). Use penecho-cloud only when that is the actual configured name; do not add another connection just to authenticate an alias. If a plugin-managed connection is not addressable by the CLI, use the host's supported connector authorization for that connection. Select anonymous use for a guest preview; do not require registration or a Dashboard token.

Let the host store and refresh OAuth credentials, and reuse valid authorization. Do not mint credentials through a database, copy website cookies/account tokens into agent configuration, or transfer another agent's credentials. Do not weaken host permissions. If a native operation is rejected or unavailable, report that specific blocker. A sandbox network failure alone does not prove Cloud is down: verify through the host's permitted network mechanism.

Continue the same task when tools are available. Prefer supported live reload/reconnect after setup: use Codex config/mcpServer/reload only when the actual app-server integration exposes it, or Claude’s actual plugin/MCP reload capability when supported. Documentation alone does not make an operation available to this agent. If none is available, explain only the host’s required manual reconnect/reload step; do not universally require a new chat. Do not claim the canvas opened before it did. Keep explicit local workflows in older canvas skills; make the production preference clear for new untargeted demonstrations without reconfiguring their local servers.

Open beside the conversation

When the user explicitly names an existing Canvas, continue with that exact target. For a retained Cloud workspace, resolve requests about the current Canvas through workspace_status as described below. Preserve explicit local/desktop MCP choices. Otherwise:

1. Choose one unique, stable sessionKey for this conversation (use the host conversation ID when available, otherwise generate and retain a UUID). Call penecho_open_workspace. This creates or resumes a browser draft, not a saved Cloud document.
2. Retain workspaceId, url, canvasUrl, and the browser tool/tab identity. If alreadyConnected is true, reuse the existing tab and check status. If launchState is opening, nextAction is wait, or url is null, poll this same workspace according to retryAfterMs: a redeemed launch may still be initializing its browser draft. Otherwise open the returned single-use url once through one capability. Prefer the host's embedded browser alongside this chat. In Codex, when exposed, call open_in_codex with {target:{type:"browser",url},placement:"right"}. A queued response means that opening was accepted: inspect and reuse that pending tab instead of invoking an independent second opener. Use a fallback opener only after the first capability explicitly reports failure or is unavailable. On Claude desktop, use preview_start only when the actual toolset exposes it and its schema supports opening an existing URL. Otherwise use the host’s actual native browser opener; do not invent tool names or promise a side pane in CLI-only hosts. If no embedded browser is available, use the supported default-browser opener or show one clickable launch link. Never send the launch URL to an external web-fetch or search tool.
3. Call penecho_workspace_status. When state is ready, call penecho_start_session with its exact startSession arguments, adding the live schema's required client/title if needed. Wait for that call to succeed and retain its sessionId and documentId before drawing, presenting, uploading, or editing. Loading status alone never authorizes a mutation or supplies a usable session.
4. Follow retryAfterMs while the initial launchState is opening, for up to its 30-second initialization window, then use at most five further bounded status checks. Do not reopen a page merely because status is loading. Follow nextAction: launch tickets expire after 120 seconds. For launch_expired, automatically call penecho_open_workspace with the same key and navigate the retained tab, using the same browser tool, to the renewed URL without another user question. Allow at most two launch renewals within this opening attempt, then report the concrete blocker. open_original_draft means the retained document is missing from this browser's storage; use its original browser profile for recovery. Opening the same workspace in another page is supported: the latest connected page takes over, and the older page disconnects. Continue in the latest page with the exact ready binding; do not require a return to the older tab. Do not substitute an unrelated Canvas or open a new tab on every check.

The returned URL selects mode=companion: a narrow tool rail, visible Save action, and a reversible Full Canvas switch in the same tab. Leave the parameter intact through reconnects. Do not ask users to visit the Dashboard, enable an MCP toggle or copy a token for this automatic workflow. A legacy server without workspace tools can use explicit Canvas selection after explaining that automatic opening needs a server update.

Work and continue

Load only the relevant penecho_get_guidance topic. Keep artifact identifiers stable. Read source and contentHash before patching; use the required baseRevision for existing-object edits. Retry uncertain writes with identical arguments and requestId. Follow the live upload schema; Cloud uploads do not need a local desktop bridge.

For handwritten feedback, capture the relevant area when its visual meaning is not already available. Inbox reads do not acknowledge feedback. Preserve unrelated work. Capture rendered output when needed to check readability or interaction, rather than after every operation.

Follow-up requests reuse the existing workspace and browser, retaining a separate session for each selected document. A disconnected browser must reconnect to the same draft before edits continue. Never silently switch documents. Guest grants remain guest grants after the user signs in in the Canvas browser.

A browser reload can invalidate a live session handle while OAuth remains valid and the document is preserved. For canvas_disconnected, session_expired, or session_not_found, check the original workspace and document, start again with that document's original sessionKey and the current exact binding, and replace only its session handle. Read the retained artifact before retrying an edit. Do not create another workspace, duplicate artifacts, or request another OAuth sign-in solely because a Canvas handle expired.

Users can edit through external MCP and annotate without registering. PenEcho's own AI requires website sign-in; guest Suggest is hidden and the pen uses a quiet sign-in hint. When users choose Save, PenEcho stores the recovery draft, signs them in or up in the same browser, then resumes that explicit save once. Ordinary sign-in does not save automatically. Canceling authentication keeps the draft. Website sign-in preserves the companion layout and unlocks website AI/saving independently; it does not migrate the guest MCP grant or require another MCP setup. Cloud saving is a user action; do not create an account or save merely to make an MCP preview.

Keep the result visible beside the conversation and briefly explain how to continue. Canvas previews complement repository implementation when that was requested. Do not publish secrets, full transcripts or private reasoning to the Canvas.

Inspect rendered output when needed for readability and test a meaningful interaction for interactive deliverables. Reconnect through normal host OAuth and the original browser profile. Do not promise that browser drafts survive profile/storage deletion or that long-duration reconnection has been tested.

In Hand mode, double-click a widget to enter interaction, then use its actual controls. Escape returns to canvas navigation. The widget's Interact control is another entry point; do not bypass the drawing surface with forced clicks.

For a Cloud workspace request about the current Canvas, re-read penecho_workspace_status before editing and use its exact startSession arguments. The companion rail can create and select multiple documents in the same tab. Retain one stable session handle per document: selecting a Canvas never retargets an existing session. Explicit requests for an older Canvas keep that document’s handle. Only use penecho_select_workspace_canvas when the user requests a target switch; read the current selection revision first. Ordinary website URLs do not expose the companion Compact/Full Canvas switch.

Anonymous identity and refresh retention must align at ten years in the matching server release; this package cannot change or prove deployed retention. Normal host OAuth refresh and revocation remain authoritative. Preserve the original browser draft and binding during reconnect; do not claim long-duration retention has passed based on an initial connection.