{"owner":"cloudflare","repo":"cloudflare-os","hasSkills":true,"totalSkillsCount":37,"totalTokensCount":96602,"categories":["anthropic-skill","root-instruction","plugin-manifest"],"hasMcp":false,"mcpConfig":null,"found":[".agents/skills/frontend-conventions/SKILL.md",".agents/skills/write-gatekeeper/SKELETON.md",".agents/skills/write-gatekeeper/SKILL.md","AGENTS.md","packages/bundled-blueprints/README.md","packages/bundled-blueprints/blueprints/workspace-docs/files/README.md","packages/bundled-blueprints/blueprints/workspace-sheets/files/README.md","packages/bundled-blueprints/blueprints/workspace-slides/files/README.md","packages/bundled-blueprints/libraries/README.md","packages/bundled-blueprints/libraries/sync/README.md","packages/bundled-blueprints/libraries/ui/README.md","packages/gatekeeper-cloudflare/README.md","packages/gatekeeper-confluence/README.md","packages/gatekeeper-context/app/skills/README.md","packages/gatekeeper-email/README.md","packages/gatekeeper-github/README.md","packages/gatekeeper-gitlab/README.md","packages/gatekeeper-google/README.md","packages/gatekeeper-homeassistant/README.md","packages/gatekeeper-kit/AGENTS.md","packages/gatekeeper-kit/README.md","packages/gatekeeper-mcp-portal/README.md","packages/gatekeeper-mcp/README.md","packages/gatekeeper-notion/README.md","packages/gatekeeper-scheduler/README.md","packages/gatekeeper-slack/README.md","packages/gatekeeper-spotify/README.md","packages/gatekeeper-supabase/README.md","packages/gatekeeper-websearch/README.md","packages/gatekeeper-x/README.md","packages/gatekeeper-zoominfo/README.md","packages/integration-tests/README.md","packages/mcp-shared/README.md","packages/observability/README.md","packages/ui/AGENTS.md","packages/workshop-frontend/AGENTS.md","packages/workshop-frontend/README.md"],"skills":{".agents/skills/frontend-conventions/SKILL.md":"---\nname: frontend-conventions\ndescription: Use for creating, modifying, moving, or reviewing React frontend code anywhere in packages/*, including Workshop pages, gatekeeper management apps, shared UI, components, hooks, forms, interactions, styling, accessibility, and frontend tests.\n---\n\n# Frontend Conventions\n\nApply these conventions to the Workshop SPA, gatekeeper management SPAs, and `@gadgets/ui`.\nPackage-level `AGENTS.md` files add product-specific rules but do not replace this guidance.\n\n## Ownership And Organization\n\nOrganize code by product ownership before implementation type. Feature directories own product\nbehavior and may contain components, hooks, tests, and utilities that change for the same reason.\n\nStart directories flat. Do not introduce `components/`, `hooks/`, `helpers/`, or `tests/`\nsubdirectories merely to classify files. Introduce a responsibility-named subsystem directory only\nwhen several files form a coherent unit or the flat directory becomes difficult to scan.\n\nUse PascalCase filenames for components and camelCase filenames for hooks and non-component\nmodules. Colocate `*.test.ts(x)` files with their subject. Feature organization does not replace\nthe one-component-per-file model.\n\nKeep product behavior with its product even when another feature consumes it. Promote code only as\nhigh as its ownership requires:\n\n- Code shared within one feature belongs at the nearest common feature directory.\n- Feature-independent code shared across unrelated areas of one app may live in that app's\n `components/` or `hooks/` directory.\n- Runtime UI shared by independent frontends belongs in `@gadgets/ui`.\n- Do not merge components merely because they look similar. Avoid generic prop-heavy abstractions\n that erase domain behavior.\n\n## Components And Hooks\n\nCreate a separate component when it owns meaningful state, effects, interactions, accessibility\nbehavior, or reusable responsibility; represents a distinct UI concern; or obscures its parent's\nmain flow. Keep small stateless render helpers private until they develop an independent concern.\n\nExtract a hook when it owns a coherent behavior or external synchronization lifecycle, not simply\nto shorten a file. Keep code together when an extracted child would mostly forward markup or depend\non the parent's refs, setters, and synchronization callbacks.\n\nPrefer named arrow-function components and hooks. Type props directly rather than using `React.FC`.\nGive wrappers such as `memo` and `forwardRef` stable DevTools names.\n\n## Component APIs\n\nRepresent props that are valid only together as an object or discriminated union. A controlled\nvalue requires a change callback; otherwise expose an uncontrolled initial value. Do not copy a\ncontrolled prop into local state with an Effect.\n\nName callbacks `on` and pass domain values rather than React setters or browser events.\nAdd `children`, slots, variants, `className`, DOM passthrough, and imperative refs only for current\ncallers, not speculative reuse.\n\nUse context for genuinely application-wide values such as authentication, theme, and toasts. Pass\ninstance-specific feature data and actions through props.\n\n## Kumo And Styling\n\nUse Kumo components and semantic tokens by default. Check Kumo and `@gadgets/ui` before creating a\ncontrol or interaction pattern. A shared Gadgets component should compose Kumo behavior, not merely\nrename or restyle a primitive.\n\nDo not add custom color literals, arbitrary Tailwind colors, feature-local token systems, or local\nreplacements for Kumo surfaces, borders, text, status, focus, and interaction tokens unless the user\nexplicitly requests them. Existing legacy colors are not precedent.\n\nTailwind is appropriate for structure, spacing, sizing, positioning, responsive behavior, and\ntypography. Use custom CSS only for technical behavior Kumo and utilities cannot express. Global\nKumo token theming is an application-level decision and must not be changed during ordinary feature\nwork.\n\nWhen Kumo is unsuitable, identify the concrete behavioral or accessibility gap before introducing\na shared abstraction.\n\n## React\n\nTreat Effects as synchronization with external systems, not as derived-state machinery or a way to\nsequence user interactions. Calculate render data during render, keep state near its owner, prefer a\ncomponent `key` for identity resets, and use `useSyncExternalStore` for suitable external stores.\n\nEffects that fetch or subscribe must clean up stale work and remain correct when restarted. Avoid\nchains of Effects and do not synchronize two pieces of React state when one can be derived.\n\nDo not add `useMemo` or `useCallback` without a concrete identity or performance need. Preserve\nkeyboard behavior, focus management, accessible names, announcements, and mouse/touch/hybrid input\nparity. RPC stubs must follow the disposal and React state rules in the root `AGENTS.md`.\n\n## Comments\n\nPrefer names and types that communicate intent. Comments should explain non-obvious constraints,\nsecurity or performance reasons, and deliberate departures from conventions. Do not narrate the\nnext line. Remove or update comments when their constraint changes.\n\n## Tests\n\nTests should protect observable behavior, product rules, accessibility, state transitions, races,\nand failure paths. Do not test React, JavaScript, Kumo, or another framework's own behavior merely\nfor coverage. Avoid assertions coupled only to implementation details or trivial passthrough.\n\nBehavior-preserving moves should keep tests unchanged apart from imports. Add focused coverage only\nwhen an extraction exposes important previously untested logic.\n",".agents/skills/write-gatekeeper/SKELETON.md":"# Gatekeeper Implementation Skeleton\n\nReplace all `My`/`my`/`MY` prefixes with the service name.\n\n## Main implementation (`src/.ts`)\n\n```typescript\nimport { WorkerEntrypoint, DurableObject, RpcTarget, RpcStub } from \"cloudflare:workers\";\nimport {\n GatekeeperUser,\n GatekeeperUserVerifier,\n GatekeeperVendor as GatekeeperVendorIface,\n Gatekeeper,\n HookController, // Remove if no hooks\n HookInitiator, // Remove if no hooks\n HookTargetMetadata, // Remove if no hooks\n ResourceDescription,\n ApprovalQueue,\n ObservationDescription,\n VendorDescription,\n GatekeeperConnectCallback,\n AccountDescription,\n SupportedResource,\n ResourceConfiguratorFrame,\n} from '@gadgets/workshop-shared/gatekeeper';\nimport { MySession, MyHook as MyHookIface } from \"./types\"; // Remove MyHook if no hooks\nimport TYPES_CODE from \"./types.txt\";\nimport MY_CONFIGURATOR_HTML from \"./generated/my-configurator-ui.txt\";\n\nconst NONCE_BYTES = 32;\nconst NONCE_LIFETIME_MS = 10 * 60 * 1000; // 10 minutes\n\nfunction hexEncode(bytes: Uint8Array): string {\n return [...bytes].map(b => b.toString(16).padStart(2, \"0\")).join(\"\");\n}\n\nfunction generateNonce(): string {\n return hexEncode(crypto.getRandomValues(new Uint8Array(NONCE_BYTES)));\n}\n\nfunction constantTimeEqual(a: string, b: string): boolean {\n let encoder = new TextEncoder();\n let bufA = encoder.encode(a);\n let bufB = encoder.encode(b);\n if (bufA.byteLength !== bufB.byteLength) return false;\n return crypto.subtle.timingSafeEqual(bufA, bufB);\n}\n\ntype Env = Cloudflare.Env & {\n BASE_URL?: string,\n};\n\nfunction getBaseUrl(env: Env) {\n return (env.BASE_URL || \"http://localhost:8787/gatekeeper/\").replace(/\\/+$/, \"\");\n}\n\nfunction getBasePath(env: Env) {\n const path = new URL(getBaseUrl(env)).pathname;\n return path === \"/\" ? \"\" : path;\n}\n\nconst SELF_CLOSING_HTML = `\n\n \n \n

Authorization complete. You may close this tab and return to the Gadgets Workshop.\n \n`;\n\nconst MY_RESOURCE: SupportedResource = {\n urlPattern: \"https://example.com/*\",\n title: \"My Resource\",\n description: \"Access a specific resource.\",\n};\n\n// ---------------------------------------------------------------------------\n// HTTP handler — serves the browser-based auth flow.\n// For a complete OAuth example, see gatekeeper-google/src/google.ts.\n\nexport default {\n async fetch(req: Request, env: Env, ctx: ExecutionContext) {\n let url = new URL(req.url);\n let basePath = getBasePath(env);\n if (!url.pathname.startsWith(basePath + \"/\") && url.pathname !== basePath) {\n throw new Error(`Request path ${url.pathname} does not match BASE_URL path ${basePath}`);\n }\n let relPath = url.pathname.slice(basePath.length);\n let path = relPath.slice(1).split(\"/\");\n\n if (path.length === 2 && path[0].length === 64 && path[1].length === NONCE_BYTES * 2) {\n // Auth initiation: the user has visited the connect URL.\n let doId = path[0];\n let nonce = path[1];\n let stub = ctx.exports.UserAccount.get(ctx.exports.UserAccount.idFromString(doId));\n if (!await stub.verifyNonce(nonce)) {\n // Show a friendly error page for expired/replayed links.\n return new Response(\"TODO: error HTML\", {\n headers: { \"Content-Type\": \"text/html; charset=utf-8\" }\n });\n }\n\n // TODO: Redirect to external auth provider, or present an auth form.\n // For OAuth, generate a second nonce for the `state` parameter here —\n // see gatekeeper-google for the full pattern.\n throw new Error(\"TODO: implement auth initiation\");\n } else {\n return new Response(\"Not Found\", {status: 404});\n }\n }\n};\n\n// ---------------------------------------------------------------------------\n// Vendor — top-level API exposed to the Workshop\n\nexport class GatekeeperVendor extends WorkerEntrypoint implements GatekeeperVendorIface {\n async describe(): Promise {\n return {\n displayName: \"My Service\",\n url: \"https://example.com\",\n logo: { url: \"TODO: data URL or hosted image URL\" },\n color: \"#f0f4ff\",\n tagline: \"Short summary of what this connector enables\",\n description:\n \"Explain what Gadgets can do with this connector in plain language.\",\n };\n }\n\n // This skeleton has no independently grantable resources, so it ignores\n // `options.resourceUrlPatterns` and stores an empty requested-resource list. Gatekeepers with\n // grantable resources should follow gatekeeper-google.\n async connectAccount(\n callback: Fetcher,\n _options?: {resourceUrlPatterns?: string[]}): Promise<{url: string}> {\n let userObjectId = this.ctx.exports.UserAccount.newUniqueId();\n let nonce = generateNonce();\n await this.ctx.exports.UserAccount.get(userObjectId).setCallback(callback, nonce, []);\n return { url: `${getBaseUrl(this.env)}/${userObjectId.toString()}/${nonce}` };\n }\n\n async getSupportedResources(): Promise {\n return [MY_RESOURCE];\n }\n\n async getTypeScriptTypes(): Promise {\n return TYPES_CODE;\n }\n}\n\n// ---------------------------------------------------------------------------\n// UserAccount DO — stores per-user credentials (tokens, API keys, etc.).\n// For a full OAuth implementation with two-phase nonces and reconnect support,\n// see gatekeeper-google.\nexport class UserAccount extends DurableObject {\n async setCallback(\n callback: Fetcher,\n nonce: string,\n requestedResourceUrlPatterns: string[]) {\n // Self-destruct if the connect flow is never completed.\n if (!this.ctx.storage.kv.get(\"credentials\")) {\n this.ctx.storage.setAlarm(Date.now() + 3600 * 1000);\n }\n this.ctx.storage.kv.put(\"callback\", callback);\n this.ctx.storage.kv.put(\"nonce\", { value: nonce, expiresAt: Date.now() + NONCE_LIFETIME_MS });\n this.ctx.storage.kv.put(\"requestedResourceUrlPatterns\", requestedResourceUrlPatterns);\n }\n\n // Verify and consume the nonce from the initiation URL. Prevents replay.\n // Returns false if the nonce is invalid or expired.\n async verifyNonce(nonce: string): Promise {\n let stored = this.ctx.storage.kv.get<{value: string, expiresAt: number}>(\"nonce\");\n if (!stored || Date.now() >= stored.expiresAt || !constantTimeEqual(stored.value, nonce)) {\n return false;\n }\n this.ctx.storage.kv.delete(\"nonce\");\n return true;\n }\n\n // Called when the user completes authorization. Store credentials and notify the workshop.\n async completeConnection(/* auth result params */) {\n let callback = this.ctx.storage.kv.get>(\"callback\");\n if (!callback) {\n throw new Error(\"Authorization timed out. Please try again.\");\n }\n\n // TODO: Store credentials obtained from the auth flow\n this.ctx.storage.kv.put(\"credentials\", \"TODO\");\n\n let props: MyUserImplProps = { userObjectId: this.ctx.id.toString() };\n try {\n await callback.complete(this.ctx.exports.MyUserImpl({ props }));\n } catch (err) {\n this.ctx.storage.kv.delete(\"credentials\");\n throw err;\n }\n }\n\n async getAccessToken(): Promise {\n // TODO: Return a cached short-lived token, refreshing credentials if needed.\n let token = this.ctx.storage.kv.get(\"credentials\");\n if (!token) throw new Error(\"No credentials set.\");\n return token;\n }\n\n async alarm() {\n if (!this.ctx.storage.kv.get(\"credentials\")) {\n this.ctx.storage.deleteAll();\n }\n }\n\n async revoke() {\n // TODO: Revoke credentials with the external service\n this.ctx.storage.deleteAlarm();\n this.ctx.storage.deleteAll();\n }\n}\n\n// ---------------------------------------------------------------------------\n// UserImpl — maps resource URLs to gatekeeper DO classes\n\ntype MyUserImplProps = {\n userObjectId: string;\n};\n\nexport class MyUserImpl extends WorkerEntrypoint\n implements GatekeeperUser {\n async describe(): Promise {\n // TODO: Fetch account info from external service using stored credentials\n return {\n displayName: \"TODO\",\n avatar: { url: \"\" },\n };\n }\n\n async getSupportedResources(): Promise {\n return [MY_RESOURCE];\n }\n\n async startResourceConfigurator(resourceUrlPattern: string): Promise {\n if (resourceUrlPattern !== MY_RESOURCE.urlPattern) {\n throw new Error(`Unsupported resource configurator type: ${resourceUrlPattern}`);\n }\n let id = this.ctx.exports.UserAccount.idFromString(this.ctx.props.userObjectId);\n let userAccount = this.ctx.exports.UserAccount.get(id);\n let ui = new MyConfiguratorUI(async () => {\n // TODO: Return a short-lived token or construct a read-only API client.\n // Keep this helper private; do not expose it as an RPC method.\n return await userAccount.getAccessToken();\n });\n return {\n iframeHtml: MY_CONFIGURATOR_HTML,\n ui: new RpcStub(ui),\n };\n }\n\n async getGatekeeperClassFor(url: string): Promise<{\n class: DurableObjectClass>;\n resource: SupportedResource;\n }> {\n // Parse URL to determine resource type and extract identifiers.\n // Return a DO class with props baked in via ctx.exports.({props}).\n // The Overseer will instantiate this class as a facet.\n let props: MyGatekeeperImplProps = {\n userObjectId: this.ctx.props.userObjectId,\n // TODO: resource-specific fields extracted from URL\n };\n return {\n class: this.ctx.exports.MyGatekeeperImpl({ props }),\n resource: MY_RESOURCE,\n };\n }\n\n async revoke(): Promise {\n let id = this.ctx.exports.UserAccount.idFromString(this.ctx.props.userObjectId);\n await this.ctx.exports.UserAccount.get(id).revoke();\n }\n\n async ensureResources(_resourceUrlPatterns: string[]): Promise<{url?: string}> {\n return {};\n }\n\n // Mint a verifier representing this account (see Observers in SKILL.md). The overseer only ever\n // hands it back to a gatekeeper of THIS vendor, so MyGatekeeperImpl.addObserver may trust it.\n // For a strategy-D (low-stakes) gatekeeper, MyVerifier has no methods and this still works.\n async getVerifier(): Promise> {\n let props: MyVerifierProps = { userObjectId: this.ctx.props.userObjectId };\n return this.ctx.exports.MyVerifier({ props });\n }\n}\n\n// ---------------------------------------------------------------------------\n// Verifier — answers \"can this observer access X?\" against the OBSERVER's own credentials.\n// For strategy D, replace this with a no-op public method; an empty WorkerEntrypoint is not registered\n// in ctx.exports. Keep/extend it for strategy B (single-unit ACL) or C (data-set tracking). See SKILL.md.\n\ntype MyVerifierProps = {\n userObjectId: string;\n};\n\n// A vendor-specific interface adding non-standard methods to the opaque GatekeeperUserVerifier.\n// addObserver casts the Fetcher back to this; the overseer's same-vendor guarantee makes that safe.\nexport interface MyVerifierApi extends GatekeeperUserVerifier {\n hasResourceAccess(resourceId: string): Promise;\n}\n\nexport class MyVerifier extends WorkerEntrypoint\n implements MyVerifierApi {\n async hasResourceAccess(resourceId: string): Promise {\n let account = this.ctx.exports.UserAccount.get(\n this.ctx.exports.UserAccount.idFromString(this.ctx.props.userObjectId));\n void account; void resourceId;\n // TODO: query the service with the observer's own token. Return true on success; return false\n // for access errors (e.g. 401/403/404); rethrow anything else so the open fails loudly rather\n // than silently denying.\n return false;\n }\n}\n\n// ---------------------------------------------------------------------------\n// Resource configurator — narrow iframe helper API\n\nconst configuratorTokenGetters = new WeakMap Promise>();\n\nclass MyConfiguratorUI extends RpcTarget {\n constructor(getToken: () => Promise) {\n super();\n configuratorTokenGetters.set(this, getToken);\n }\n\n async listResources(query: string): Promise<{ value: string; title: string }[]> {\n let getToken = configuratorTokenGetters.get(this);\n if (!getToken) throw new Error(\"Configurator is not initialized.\");\n let token = await getToken();\n void token;\n // TODO: Call read-only external APIs and return bounded search results.\n return [{ value: query || \"example\", title: query || \"Example\" }];\n }\n\n}\n\n// ---------------------------------------------------------------------------\n// Hook type — remove this section (and the HookController/HookInitiator/HookTargetMetadata\n// imports, the `subscribe` method, the `hookTsType` field, and MyHookControllerImpl) if the\n// gatekeeper doesn't push events.\n//\n// The hook interface from types.d.ts is implemented by the Gadget as an RpcTarget. Intersect it\n// with RpcTarget so it satisfies the HookController/HookInitiator generic constraints (Hook\n// extends RpcTarget).\n//\n// Note that you can also use a plain function as a hook type, e.g. `RpcStub<() => Promise>`.\n// In that case you would not need to merge the type with `RpcTarget`.\n\ntype MyHook = RpcTarget & MyHookIface;\n\n// ---------------------------------------------------------------------------\n// GatekeeperImpl DO — per-resource instance, runs as a facet of the Overseer\n\ntype MyGatekeeperImplProps = {\n userObjectId: string;\n // ... resource-specific fields (e.g., documentId, repoOwner)\n};\n\nexport class MyGatekeeperImpl extends DurableObject\n implements Gatekeeper {\n\n async describe(): Promise {\n return {\n url: \"TODO: canonical resource URL\",\n title: \"TODO\",\n snippet: \"TODO\",\n suggestedBindingName: \"MY_RESOURCE\", // Based on type, not instance\n tsType: \"MySession\",\n hookTsType: \"MyHook\", // Remove if hooks are not supported\n };\n }\n\n async getTypeScriptTypes(): Promise {\n return TYPES_CODE;\n }\n\n async startSession(approvalQueue: RpcStub): Promise {\n return new MySessionImpl(\n approvalQueue.dup(), // Always dup() before storing\n this.ctx,\n // ... API client, props, etc.\n );\n }\n\n async applyAction(actionId: number): Promise {\n // Look up the action by ID from this gatekeeper's own storage, then perform it\n // against the external service.\n // TODO: Implement action lookup and execution.\n throw new Error(`Unknown action: ${actionId}`);\n }\n\n async rejectAction(actionId: number): Promise {\n // Clean up simulation state for this action.\n // Return { restart: true } if the session can't recover from rejection.\n }\n\n revertAction(actionId: number):\n Promise {\n // TODO: Undo the action (look up what was done from own storage)\n throw new Error(\"Revert not implemented\");\n }\n\n // Observers (see SKILL.md \"Observer verification\"). This skeleton shows strategy B — ACL check on\n // a single atomic resource. The overseer calls addObserver on EVERY open by every observer, so it\n // re-verifies live access; throw to deny.\n // - Strategy A (private-only): `async addObserver() { throw new Error(\"...not shareable...\"); }`\n // - Strategy D (low-stakes): make both methods no-ops.\n // - Strategy C (data-set tracking): record observed sets + store verifiers, and route every read\n // through an authorizeSetObservation helper that sets `excludeObservers` (see SKILL.md).\n async addObserver(_id: string, user: Fetcher): Promise {\n let verifier = user as unknown as Fetcher;\n if (!(await verifier.hasResourceAccess(/* this.ctx.props.resourceId */ \"TODO\"))) {\n throw new Error(\n \"This collaborator does not have access to the bound resource, so they cannot observe \" +\n \"data the Gadget read from it.\");\n }\n }\n\n // Idempotent: ignore unknown ids. A no-op for strategy A/B (nothing is tracked).\n async removeObserver(_id: string): Promise {}\n}\n\n// ---------------------------------------------------------------------------\n// HookController — remove if the gatekeeper doesn't push events.\n//\n// A WorkerEntrypoint the overseer uses to enable/disable the hook after the user approves it.\n// It is constructed with `props` carrying the specifics of that particular registration, so it\n// needs no other state. If your gatekeeper offers several kinds of hooks, give each its own\n// controller class.\n\n// Bind-time details for a single hook registration, baked into the controller's props.\ntype MyHookProps = {\n // TODO: e.g. an event kind, a filter, a sub-resource id, etc. — whatever the registration\n // method received and the controller/event source will need later.\n filter?: string;\n};\n\ntype MyHookControllerImplProps = MyGatekeeperImplProps & MyHookProps;\n\nexport class MyHookControllerImpl extends WorkerEntrypoint\n implements HookController {\n // Called when the user enables the hook. Store `initiator` somewhere it can be reached when an\n // event arrives — typically an event-source DO. Don't store other state until now; everything\n // else is already in `this.ctx.props`. If already enabled, replace the previous initiator.\n //\n // `target` identifies where the hook delivers (workspace, and gadget when pinned to one). Store\n // it too if you display or link to the target; otherwise ignore it, but keep the parameter\n // declared — RPC argument validation rejects arguments the receiver doesn't declare.\n async enable(initiator: Fetcher>, target: HookTargetMetadata): Promise {\n // TODO: persist `initiator` (e.g. forward it to an event-source DO keyed by props).\n }\n\n // Called when the hook is disabled or deleted. Forget the stored initiator and clean up all\n // related state. May never be called again, though the overseer may later call enable() afresh.\n async disable(): Promise {\n // TODO: forget the stored initiator.\n }\n}\n\n// Event delivery (sketch). When the external event arrives — e.g. in the event-source DO that\n// holds the `initiator` — invoke the hook like so:\n//\n// async onEvent(initiator: Fetcher>, event: MyEvent) {\n// // startHook() begins a fresh session and returns the callback (re-bound to it) plus an\n// // ApprovalQueue. `using` disposes the result (and its stubs) at end of scope.\n// using result = initiator.startHook();\n//\n// // A hook event is almost always an observation. (Register actions too if invoking the\n// // callback can cause side effects.) Pipeline through the not-yet-resolved promise.\n// await result.approvalQueue.authorizeObservation({\n// title: \"TODO: short event summary\",\n// description: \"TODO: details about the event being delivered\",\n// });\n//\n// // Deliver the event to the Gadget's callback.\n// await result.callback.onMyEvent(event);\n// }\n\n// ---------------------------------------------------------------------------\n// SessionImpl — the RPC interface exposed to the Gadget\n\nclass MySessionImpl extends RpcTarget implements MySession {\n #approvalQueue: RpcStub;\n #ctx: DurableObjectState;\n\n constructor(\n approvalQueue: RpcStub,\n ctx: DurableObjectState) {\n super();\n this.#approvalQueue = approvalQueue;\n this.#ctx = ctx;\n }\n\n [Symbol.dispose]() {\n this.#approvalQueue[Symbol.dispose]();\n }\n\n // Example: observation (read). Fetch data, then authorize before returning.\n async getData(): Promise {\n let result = \"TODO: fetch from service or cache\";\n\n await this.#approvalQueue.authorizeObservation({\n title: \"Read data\",\n description: \"Fetched data from the service.\",\n });\n\n return result;\n }\n\n // Example: action (side effect). Submit for approval; do NOT perform here.\n // Assign a sequential action ID, store the action details in the gatekeeper's\n // own storage, then submit the ID to the approval queue. If you read current state to build\n // the description or capture revert info, do NOT log it as an observation: nothing is\n // returned to the caller.\n async updateData(newValue: string): Promise {\n let actionId = /* assign next sequential ID and store action details */ 0;\n\n await this.#approvalQueue.submitAction(actionId, {\n title: \"Update data\",\n description: `Update value to: ${newValue}`,\n implementsRevert: true,\n });\n\n // TODO: Update cache/simulation state so subsequent reads reflect this\n }\n\n // Example: hook registration — remove if the gatekeeper doesn't push events.\n // `callback` is a persistent stub the Gadget created with ctx.restore(). Construct a controller\n // whose props capture the specifics of THIS registration (e.g. `filter`), then hand it, the\n // callback, and a user-facing description to the overseer via bindHook(). For multiple hook\n // kinds, pick the appropriate controller class here. Do NOT store the callback yourself — it is\n // bound to this session and would be revoked when the session ends.\n async subscribe(callback: RpcStub, filter?: string): Promise {\n let controller = this.#ctx.exports.MyHookControllerImpl({\n props: { ...this.#ctx.props, filter },\n });\n await this.#approvalQueue.bindHook(controller, callback, {\n title: \"TODO: short hook title\",\n description: `TODO: what events this hook delivers${filter ? ` (filter: ${filter})` : \"\"}`,\n });\n }\n}\n```\n\n## `cloudflare.config.ts`\n\n```typescript\nimport {\n DEFAULT_GATEKEEPER_WRANGLER, OBSERVABILITY, defineGadgetsWorker, type DurableObjectMigration,\n} from \"@gadgets/scripts/worker-config\";\n\nexport default defineGadgetsWorker({\n name: \"gatekeeper-\",\n entrypoint: \".wrangler/validate/src/.ts\",\n compatibilityFlags: [\"allow_irrevocable_stub_storage\"],\n observability: OBSERVABILITY,\n});\n\nexport const wrangler = DEFAULT_GATEKEEPER_WRANGLER;\n\nexport const migrations: DurableObjectMigration[] = [\n { tag: \"v0\", new_sqlite_classes: [\"UserAccount\", \"MyGatekeeperImpl\"] },\n];\n```\n\nRun `pnpm configs:generate`; the generated `wrangler.jsonc` is committed and never edited by hand.\n\nOnly Durable Object classes go in `new_sqlite_classes`. `MyVerifier` and `MyHookControllerImpl` are `WorkerEntrypoint`s, so they need no `migrations` entry — but, like all entrypoints, they must be `export`ed from the worker's main module (so `ctx.exports.MyVerifier(...)` resolves). If your hook uses a dedicated event-source DO to hold the `initiator`, add that DO here too.\n\n## Creating the `types.txt` symlink\n\n```bash\ncd packages/gatekeeper-/src\nln -s types.d.ts types.txt\n```\n\n## Resource configurator files\n\nAdd per-resource configurator types and UI modules:\n\n```\nsrc/configurator/my-configurator-types.d.ts\nsrc/configurator/my-configurator-types.txt -> my-configurator-types.d.ts\nsrc/configurator/my-configurator-ui.tsx\n```\n\n`my-configurator-types.d.ts` should describe the iframe helper API. The UI module's own `resourceUrl()` hook returns the resource URL to Workshop.\n\n```typescript\nexport interface MyConfiguratorUI {\n listResources(query: string): Promise<{ value: string; title: string }[]>;\n}\n```\n\nAdd package scripts:\n\n```json\n{\n \"scripts\": {\n \"deploy\": \"vp run --no-cache build:configurator && wrangler deploy\"\n },\n \"dependencies\": {\n \"@gadgets/configurator-ui\": \"workspace:*\"\n },\n \"devDependencies\": {\n \"@gadgets/scripts\": \"workspace:*\"\n }\n}\n```\n\n`@gadgets/scripts` has to be declared, not just imported. The shared task configs and the\n`gadgets-*` bins that run them belong to that package, and the workspace root depends on it too —\nso its bins are already on `PATH` and a `vite.config.ts` importing it resolves even with no\ndeclaration here. That is a phantom dependency: it works until this package is built somewhere that\ndoes not happen to hoist it.\n\nNo `build` script: `build` is one of the shared Vite+ tasks below, and vp forbids a task and a\nscript sharing a name. Build this one package with `pnpm exec vp run -F build` —\n`pnpm --filter` cannot see a task, so `pnpm --filter build` reports nothing to run;\nthe workspace-wide `pnpm build` picks it up as usual. `deploy` goes through the task rather than\ncalling\n`build-gatekeeper-configurator.ts` itself, so the codegen command lives in one place and cannot\ndrift from the task that declares its env — `wrangler deploy` stays outside vp, since it has side\neffects and needs real credentials.\n\nAlso add a `vite.config.ts` re-exporting the shared `build` and `build:configurator` Vite+ tasks —\nthe latter is what the `pnpm dev-server` pre-flight builds (`vp run -r --cache build:configurator\n--dev`). Both are tasks rather than package.json scripts so `VITE_FRONTEND_ERROR_REPORTING` is\npassed through and cache-fingerprinted; a `build` script running the builder with `&&` would bypass\nthat and silently bake the wrong value into the shipped HTML (do not add either script back):\n\n```typescript\n// Vite+ per-package settings. The build:configurator task definition is shared by all gatekeepers\n// with a configurator UI and ships as an export of `@gadgets/scripts`, alongside the builder it\n// runs.\nexport { default } from '@gadgets/scripts/gatekeeper-configurator'\n\n// ...or, if the gatekeeper has tests, `withTests` instead: the same settings plus the shared vitest\n// `test` task. Add a `\"test:run\": \"vitest run\"` script too, for iterating without the cache.\nexport { withTests as default } from '@gadgets/scripts/gatekeeper-configurator'\n```\n\nKeep tokens and broad API clients out of public `RpcTarget` properties; use closures, `#private`, or `WeakMap` state and expose only narrow read-only helper methods.\n",".agents/skills/write-gatekeeper/SKILL.md":"---\nname: write-gatekeeper\ndescription: Guides implementation of Gatekeeper Workers that bridge Gadgets to external services. Covers auth, capability-based API design, approval queue integration, caching, and action simulation. Load when creating, modifying, or reviewing the implementation of a gatekeeper.\n---\n\n# Writing a Gatekeeper\n\nA Gatekeeper is a Cloudflare Worker that mediates all access between a Gadget and an external service. It implements a three-tier hierarchy:\n\n- **Vendor** (`GatekeeperVendor`, a `WorkerEntrypoint`) — top-level entry for the service. One per service.\n- **User** (`GatekeeperUser`, a `WorkerEntrypoint` with `ctx.props`) — a human user's authenticated connection.\n- **Instance** (`Gatekeeper`, a DO facet of the Overseer) — per-resource, per-Gadget binding that provides the Session API.\n\nRead `packages/workshop-shared/src/gatekeeper.ts` for the canonical interfaces and detailed JSDoc.\n\n## Seven responsibilities\n\n1. **Auth management** — Manage authorization to the external service via OAuth (or similar), on behalf of the human end user. This means managing \"connected accounts\" — token storage, refresh, and revocation in a `UserAccount` Durable Object.\n\n2. **API design** — Provide a TypeScript API wrapper around the service's API, compatible with Cap'n Web RPC. The interface should be designed around capability-based security: object-oriented, with separate interfaces representing logical resources. For example, the Google Docs gatekeeper provides an interface to a *specific* document, rather than a coarse-grained interface where you pass the doc ID to every method. **IMPORTANT:** When writing a new gatekeeper, design a proposed API and then STOP to let the operator review and make changes before proceeding with the rest of the implementation. Getting the API right is the most important and delicate part of creating a new gatekeeper.\n\n3. **Fine-grained resource granting** — Enable the end user to grant access to agents at fine granularities, in addition to coarse-grained access. For example, a user may want to give an agent access to a specific Google Doc or GitHub repo, rather than granting broad access to everything they can do. This should be straightforward given a capability-based API. That said, broad access should also be allowed when it makes sense. Consider carefully which granularities are meaningful — a Jira gatekeeper might support \"whole service\", \"project\", and \"issue\" granularities, but it would be silly to support granting access to a single field of an issue separately.\n\n4. **Logging & approvals** — Every action the agent or gadget performs must be logged via the `ApprovalQueue` API. Every action with an externally-visible side effect must be submitted via `submitAction()`, and must not actually be performed until `applyAction()` has been called. Read-only observations must call `authorizeObservation()` before returning data to the caller. Reads the gatekeeper makes for its own purposes, returning nothing to the caller, are not observations (see [What counts as an observation](#what-counts-as-an-observation)).\n\n5. **Caching** — When it makes sense, cache remote content in the gatekeeper's DO storage to improve performance when agents or gadgets repeatedly read the same data. Caching also enables a better TypeScript API when the service's underlying API has an inconvenient data shape. For example, Gmail's API for listing threads returns only thread IDs without metadata, requiring a callback for each thread; with caching, the gatekeeper can provide an API that returns rich thread summaries directly, reading from local content synchronized with Gmail as needed. See Phase 2 for implementation guidance.\n\n6. **Simulation** — Actions submitted but not yet applied should be simulated as if they already occurred, to the maximum extent reasonable. If the caller reads back data, it should observe the data as if pending actions had been applied, even though they haven't yet. This allows the agent to continue working without waiting for each approval, and allows the end user to batch-approve a lot of work at once. Simulation may leverage caching (updating the cache on submit, clearing or repopulating it on reject), or it may work by storing pending actions separately and adjusting read results at query time — the latter is arguably cleaner but trickier to implement correctly. See Phase 2 for implementation guidance.\n\n7. **Observer verification** — When a Gadget is shared, collaborators may \"observe\" data the Gadget previously read through the gatekeeper. The gatekeeper must ensure each collaborator could access that data themselves, via `getVerifier()` / `addObserver()` / `removeObserver()`. The interface methods are mandatory — a gatekeeper won't type-check without them — so include at least minimal versions in Phase 1; but *choosing and implementing the right strategy* is a Phase 2 security concern, like logging/approvals. See [Observer verification](#observer-verification).\n\n## Phase 1: Core implementation\n\nIn the first phase, focus only on responsibilities 1 - 3, though keeping in mind that 4 - 7 will need to be implemented later. Note the observer methods of responsibility 7 (`getVerifier`/`addObserver`/`removeObserver`) are required for the code to type-check, so the skeleton includes minimal versions; you flesh out the actual strategy in Phase 2.\n\n### Step 1: Understand the external service\n\nStudy the service's API docs. Identify:\n- Auth model (OAuth 2.0, API keys, etc.)\n- Resources to expose and what access granularities make sense\n- Which operations are observations (read-only) vs. actions (side effects)\n\n### Step 2: Design the Session types\n\nCreate `src/types.d.ts` defining the Session interface (and Hook interface if the service pushes events — see [Hooks](#hooks-push-notifications)).\n\nBefore designing, read `packages/workshop-shared/node_modules/capnweb/README.md` to understand what Cap'n Web RPC supports — this determines what types and patterns are expressible in the Session interface.\n\nDesign principles:\n- One interface per logical resource type, not a god-object\n- Methods return structured data, not raw API responses\n- Use capability-based design principles: make it easy to limit authority in useful ways by simply limiting access to specific objects or allowing/blocking specific methods\n- Simplify API complexities that are not likely to matter to agents and gadgets; design for a more novice user and common use cases\n- Consider what URL patterns `getGatekeeperClassFor()` should match — each pattern maps to a resource granularity\n- Include JSDoc comments; these types serve as the agent's API documentation. See [Documenting the API](#documenting-the-api-typesdts) below.\n\n#### Documenting the API (`types.d.ts`)\n\nThis JSDoc is the agent's sole documentation for the API, so keep it **narrowly focused on what the agent needs to use each method**: what it does, its parameters, the returned data shape, and any errors the caller must handle.\n\nDo NOT leak details the caller doesn't need to use the API — the approval queue (never mention `submitAction`/`applyAction`/approvals; correct simulation keeps this invisible), or gatekeeper internals (caching, DO storage, OAuth, syncing). Document those in the `.ts` implementation or PR, never in the agent-facing `.d.ts`.\n\nThe agent receives the `.d.ts` text **verbatim** (via the `types.txt` symlink), and nothing resolves its imports — so it must be **self-contained**. Don't import types from other packages or files (e.g. `Cursor` from `@gadgets/workshop-shared/gatekeeper`); copy the definition into the `.d.ts` instead. TypeScript's structural typing means the implementation can still return the shared type. The only exception is `cloudflare:workers` (e.g. `import type { RpcTarget } from \"cloudflare:workers\"`), which the agent's environment provides. `pnpm lint` enforces this with the `gadgets/self-contained-agent-types` rule on every `packages/gatekeeper-*/src/*types.d.ts`. Also keep the file free of comments aimed at maintainers (such as \"keep in sync with X\"), since the agent reads those too.\n\n### Step 3: STOP — Present API for review\n\n**Do not proceed without operator approval.**\n\nPresent the proposed `types.d.ts` and explain the design: what resource granularities are supported, what Session methods do, and what trade-offs were made. The API is the most important and delicate part of a gatekeeper — getting it wrong means rebuilding. Wait for the operator to review and approve (or request changes) before continuing.\n\nAlso confirm the JSDoc follows [Documenting the API](#documenting-the-api-typesdts) — no approval-queue or implementation details leaked in, and run the [API review](#reviewing-a-gatekeeper) on your own design first.\n\n### Step 4: Implement\n\nSee [SKELETON.md](SKELETON.md) for a complete implementation template.\n\nPackage structure:\n```\npackages/gatekeeper-/\n├── src/\n│ ├── configurator/ # Optional resource-picker UI modules and UI-facing types\n│ ├── .ts # Vendor, UserAccount, UserImpl, GatekeeperImpl, SessionImpl\n│ ├── types.d.ts # Session/Hook types (compile-time)\n│ ├── types.txt -> types.d.ts # Symlink (runtime, for getTypeScriptTypes())\n│ └── -api.ts # (optional) Helper wrapping the service's HTTP API\n├── cloudflare.config.ts # wrangler.jsonc is generated from it\n├── package.json\n└── tsconfig.json\n```\n\n### Step 5: Register\n\nThere is no binding to add. `run-dev-server.ts` binds every `packages/gatekeeper-*` that has a `wrangler.jsonc` to the backend as `GATEKEEPER_`, and the deploy service does the same for installed gatekeepers. The backend auto-discovers vendors from `GATEKEEPER_`-prefixed bindings (see `packages/workshop-backend/src/user.ts`).\n\n### Step 6: Add resource selection UI\n\nAdd a resource selection UI for each connect card. A card is one resource type returned in `getSupportedResources()`, together with any types whose `groupedWith` names it. This will be used by users to select the specific resource.\n\n- Workshop calls `GatekeeperUser.startResourceConfigurator(resourceUrlPattern)` with the `urlPattern` of a type on the card: the card's own type from the connect dialog, or a binding's own type from a blueprint. Return the card's configurator for every type on it.\n- Return `iframeHtml` of the selection UI and `ui` for any RPCs that UI needs.\n- When the user selects \"Add connection\", Workshop asks the iframe for the selected resource URL.\n- Group types (`SupportedResource.groupedWith`) when they are one choice at different granularities, such as a whole drive, a folder or a file. Each type is still granted separately, and a grouped card asks for the missing ones in one consent request, so group only types that need the same authorization. The gatekeeper's `getGatekeeperClassFor` decides which type a returned URL is, while Workshop's grant check takes the first type in declaration order whose pattern matches it, so declare a narrower type before a broader one whose pattern also matches its URLs. A whole-instance `https://*` type is the exception: the check skips it and uses it only for a URL no other type on the card matches, so it can be declared anywhere.\n\nKeep the iframe-facing capability narrow, only what's necessary to provide desired interface to help user find and select the resource.\n\n#### Optional helper: `@gadgets/configurator-ui`\n\nFor configuration UIs, use `@gadgets/configurator-ui`. It provides form components built on Kumo (rendered with Preact standing in for React inside the frame) that look and behave like the rest of the Workshop, and a build that turns `src/configurator/*-ui.tsx` into `iframeHtml`. Gatekeepers whose needs the components cannot meet can produce their own `iframeHtml`.\n\nComponents: `Section`, `Field`, `TextInput`, `RadioCards`, `CheckboxList` (multi-select; refuses more than 200 options rather than truncating), `Autocomplete` (search-as-you-type, one result), `HierarchyPicker` (choose the whole hierarchy from a card above the list, or an open container or a leaf from its own row; as in a file dialog, a choice lasts while it is in view; a container's `choice` says what connecting it grants, since only the gatekeeper knows whether that is its whole subtree; breadcrumbs, optional search, paging and `loadItem`, which pre-filling anything but the root needs; nodes name icons the configurator supplies in `icons`; a location that cannot be listed yet, such as one waiting on a grant, returns a page with `unavailable` set to why, shown with Retry like a failed load but not reported as an error), `Button` (an action in the form; call the render context's `ensureResources` from its click to ask for access the next step needs) and `Notice` (an inline info or error message, announced to screen readers). The runtime strips control and bidi-formatting characters from titles, subtitles and meta it shows, since those come from third parties.\n\nIf you use this:\n\n- UI modules live in `src/configurator/*-ui.tsx`.\n- `resourceUrl()` returns the selected resource URL.\n- A module that can return several types reads `acceptedResourceUrlPatterns` from the context every callback receives (`render`, `isReady`, `resourceUrl`, `initialValuesFromResourceUrl`): the types Workshop will take, which leave out a grouped type the account hasn't granted and anything a blueprint binding doesn't want. Show other types if that helps the user find their way, but don't let them be chosen, and keep `isReady` false while one is. It is `undefined` from an older Workshop, which takes any type. The list is read when the frame starts, and Workshop restarts the frame when it changes.\n- `src/configurator/*-types.d.ts` describes the iframe-facing `ui` API.\n- Each module is compiled on its own: it may import only `@gadgets/configurator-ui` and types. URL grammar it shares with the server is copied, and a test keeps the copies in step.\n- The frame's content security policy allows exactly the scripts the build wrote (by hash) and no network access; anything the UI needs goes through `ui`.\n- `scripts/build-gatekeeper-configurator.ts` generates `src/generated/*.txt`, using the runtime and build in `packages/configurator-ui` (`src/runtime/`, `build/`).\n- Nothing invokes `build-gatekeeper-configurator.ts` by hand. `vite.config.ts` re-exports the\n shared `build` and `build:configurator` Vite+ tasks from\n `scripts/gatekeeper-configurator-vite-config.ts`; `build` is just `tsc` and depends on\n `build:configurator`, which carries `VITE_FRONTEND_ERROR_REPORTING` in its fingerprint, and\n `deploy` runs `vp run --no-cache build:configurator && wrangler deploy` — deploys never replay a\n cached artifact. There is no `build` script\n and no direct builder call, because a script running the builder gets vp's stripped environment\n and bakes the wrong flag into the shipped HTML.\n\n##### Pre-filling the form from a known resource URL\n\nWhen something already knows the exact resource — most importantly an AI agent's `requestConnection` (which passes a concrete `resourceUrl`) — the configurator should open **pre-filled and editable**, not blank. The runtime handles this for you:\n\n- If your value keys already match the `urlPattern`'s named groups (e.g. pattern `.../area/:areaId` with a value key `areaId`), prefill works automatically — no code needed.\n- Otherwise, implement the optional `initialValuesFromResourceUrl({ resourceUrl, resourceUrlPattern, ui })` on your spec to map a concrete URL back to your form values. Keep it pure where possible (parse the URL); it may use `ui` and may be async. Example (GitHub, whose value is `repoFullName` but pattern is `:owner/:repo`):\n\n ```ts\n initialValuesFromResourceUrl({ resourceUrl }) {\n const [owner, repo] = new URL(resourceUrl).pathname.split(\"/\").filter(Boolean);\n return owner && repo ? { repoFullName: `${owner}/${repo}` } : {};\n },\n ```\n\n The runtime seeds these values before first render and reflects them in `Autocomplete`/`TextInput`/`RadioCards`/`HierarchyPicker` inputs. Make sure your `resourceUrl(values)` and `initialValuesFromResourceUrl(url)` are inverses so a prefilled form round-trips to the same URL. **Every gatekeeper with selectable resources should support this** so agents can fully pre-configure a connection.\n\n### Step 7: STOP — Ask operator whether to proceed to phase 2\n\nThe operator may prefer to implement phase 2 later, perhaps in a new context. Stop here and ask the operator whether to proceed.\n\n## Phase 2: Logging, approvals, caching, simulation, and observers\n\nIn this phase, we focus on responsibilities 4-7. These are typically added as a second pass, after the core gatekeeper works. They may be implemented in a separate session.\n\n### Logging and approvals\n\nGo through all the API methods and decide where to insert calls to the `ApprovalQueue`.\n\n- Any operation which reads external data and returns it to the caller (but with no side effects) must call authorizeObservation().\n- Any operation which has visible side effects on the world must call submitAction(), and must not actually apply the action until approved.\n\nStudy the `ApprovalQueue` API in `gatekeeper.ts` for details.\n\n#### What counts as an observation\n\nThe observation log records what the **caller** (agent or gadget) learned, not what the gatekeeper read. Deciding this correctly keeps the log readable for the user. Ask: *what information did this call hand back to the caller?* If the answer is \"nothing\", don't log an observation, however much the gatekeeper fetched internally.\n\nDo **not** call `authorizeObservation()` for:\n\n- **Reads that only prepare an action.** A mutation that fetches current state to build the action description, bind an expected old value, capture revert information, or validate the request, and then calls `submitAction()`, returns `void` (or a provisional stub or a freshly generated ID). The action description the user approves already shows what was read. Don't log \"Read X before mutation\".\n- **Session setup.** `startSession()` resolving the account, a bound label, and so on returns only a session stub.\n- **Creating a cursor or stub that returns no data itself**, provided its later reads (cursor pages, `getDetails()`, …) log their own observations. Log wherever the data actually crosses to the caller; if a cursor logs once up front and not per page, that up-front log is the real one and must stay.\n- **Information that leaks only through a validation error** (\"label already exists\", \"branch is not a fast-forward\").\n\n**Existence checks are a judgment call, but usually not an observation.** A method like `getIssue(id)` that confirms an item exists and returns a stub tells the caller one bit. When the ID is an unguessable, high-entropy value (a Gmail message ID, a commit SHA, a UUID), that bit is no information at all: a caller that already holds the ID knows the item exists, and the ID itself encodes nothing. Sequential numbers and human-readable names are more ambiguous, but an agent leaking information by probing whether titles exist is far-fetched, so the default is not to log. Log the stub's real reads instead. Don't put fetched details (such as the item's title) into a log entry for data the caller never received.\n\nReturning a boolean or count *is* data when that is the answer the caller asked for (`isFollowing()`, `areTracksSaved()`, a `null` from `getArea()` meaning \"no area\"). Log those.\n\n**Exception: observer tracking.** Under observer strategy C (below), `authorizeObservation()` does more than log. Its `excludeObservers` and set-tracking side effects gate which collaborators may see the workspace, and `containsRestrictedData` / `ownerInvitesOnly` change workspace state. A call that carries any of these is a security control, and removing it is a security decision, not a logging cleanup (see the Drive session's \"Check Google Drive folder\" fences).\n\nIt's critically important that you add `ApprovalQueue` to all API operations that interact with the outside world, otherwise the gatekeeper security model is broken.\n\n### Caching\n\nStore fetched data in the gatekeeper's DO storage (`this.ctx.storage`) to avoid redundant API calls. The cache also enables a better API shape when the service's native data model is awkward — e.g., Gmail's list API returns thread IDs without metadata, but with caching the Session can return richer summaries directly.\n\n- Use TTLs or revision IDs to keep the cache fresh.\n- Cache transformed data (e.g., Markdown) rather than raw API responses when the transformation is expensive.\n\nPROTIP: The relatively new API `this.ctx.storage.kv` provides synchronous versions of the traditional Durable Object storage API, e.g. `get` and `put`. Use these instead of the old asynchronous methods. (Note that the synchronous API does not provide \"batch\" versions of `get()` and `put()`, but you don't really need them since simply making multiple calls is efficient.)\n\nPROTIP: `this.ctx.storage.sql` gives you access to a full, private SQLite database. Use this when the full power of SQL is useful, but prefer KV for simple things.\n\nThe full Durable Objects storage API (including synchronous KV and SQLite) is documented at: https://developers.cloudflare.com/durable-objects/api/sqlite-storage-api/\n\n### Simulation\n\nWhen `submitAction()` has been called but `applyAction()` hasn't, reads should reflect the pending action. This allows the calling agent or gadget to be unaware of the approvals mechanism, and proceed with follow-on work immediately. The end user is able to approve a whole batch of changes at once, later on.\n\nTwo possible implementation approaches include:\n\n1. **Mutate the cache** — Apply the action's effects to cached data on submit. On `rejectAction()`, invalidate or rebuild the cache. Simple; works well when the cache is already a transformed view. Don't forget to re-apply any queued actions when updating the cache.\n\n2. **Overlay at read time** — Store pending actions separately; merge them into read results on demand. Cleaner separation; better when the overlay logic is straightforward.\n\nChoose based on the service's data model and the complexity of simulating each action type.\n\nKeep in mind that the agent calling the API (or the agent writing a gadget to call it) is generally not aware that actions do not take place immediately. If the simulation is correct, the agent doesn't need to be aware. If the simulation has gaps, you may want to mention it in your API's doc comments, so that the calling agent knows to work around them — but ideally there are no gaps and the calling agent does not need to think about it.\n\nFor concrete examples, see the Google gatekeeper's Google Docs simulation/cache handling and BigQuery dry-run scope enforcement.\n\n### Observer verification\n\nThis is responsibility 7. When a Gadget is shared, each non-owner collaborator becomes an **observer** of every gatekeeper bound to the Gadget, and may see data the Gadget previously read. The gatekeeper's job is to refuse — or forward-restrict — observers who couldn't access that data themselves.\n\nThree methods implement this (full JSDoc in `gatekeeper.ts`):\n\n- `GatekeeperUser.getVerifier()` — mints a `GatekeeperUserVerifier` (a persistent service stub) representing *this* user's account. The overseer mints one per open and **only ever passes it back to a gatekeeper of the same vendor**, so the gatekeeper may trust whatever it learns from it.\n- `Gatekeeper.addObserver(id, verifier)` — must **throw** if the user represented by `verifier` is not allowed to observe everything read through this gatekeeper so far. The overseer calls it on **every open by every authorized observer** (re-verification, so revoked access is caught at the next open); cache as needed if the check is expensive. `id` is an opaque, stable per-(user,gadget) string.\n- `Gatekeeper.removeObserver(id)` — idempotent; drop a tracked observer.\n\n#### The verifier \"non-standard method\" pattern\n\n`GatekeeperUserVerifier` has no methods of its own — it's an opaque token. To actually answer \"can this observer access X?\", define a vendor-specific interface that **extends `GatekeeperUserVerifier`** with your own methods, implement it on a `WorkerEntrypoint` that queries the service using the **observer's own token**, and cast the `Fetcher` back to that interface inside `addObserver`. The overseer's same-vendor guarantee is what makes the cast safe.\n\n```typescript\n// In types/impl: a verifier interface with non-standard methods.\nexport interface MyVerifierApi extends GatekeeperUserVerifier {\n hasResourceAccess(resourceId: string): Promise;\n}\n\ntype MyVerifierProps = { userObjectId: string };\n\nexport class MyVerifier extends WorkerEntrypoint\n implements MyVerifierApi {\n async hasResourceAccess(resourceId: string): Promise {\n // Query the service with the OBSERVER's own token (this.ctx.props.userObjectId).\n try {\n await myApiForObserver(this.ctx).getResource(resourceId);\n return true;\n } catch (error) {\n // Distinguish \"no access\" from \"transient failure\":\n // - auth/permission/not-found (401/403/404) → false (they can't see it)\n // - anything else → rethrow, so the open fails loudly rather than silently denying\n if (isNoAccessStatus(statusOf(error))) return false;\n throw error;\n }\n }\n}\n\n// In GatekeeperUser:\nasync getVerifier(): Promise> {\n return this.ctx.exports.MyVerifier({ props: { userObjectId: this.ctx.props.userObjectId } });\n}\n```\n\n`MyVerifier` is a `WorkerEntrypoint`, so it needs **no migration entry**, but (like all entrypoints) it must be `export`ed from the worker's main module so `ctx.exports.MyVerifier(...)` resolves.\n\n#### Choosing a strategy (per resource type / binding)\n\nStrategy is chosen **per `Gatekeeper` DO class / binding**, not per package — one package may use several (e.g. Google: Gmail=A, Doc=B, BigQuery=C).\n\n- **A — Private-only.** `addObserver()` always throws; `removeObserver()` is a no-op. `getVerifier()` must still exist (the overseer mints it) but is never consulted. Use when the resource is too sensitive to share and there is no per-observer access oracle (e.g. a personal Gmail mailbox). For truly sensitive data, also mark each observation with `ObservationDescription.containsRestrictedData: true`: because nobody can open the workspace without passing `addObserver()`, and with strategy A nobody ever does, the first such observation makes the workspace effectively unshareable — and it permanently sets the workspace's `containsRestrictedData` flag, whose restricted mode blocks all actions and public web fetches, so the data cannot leak back out through other gatekeepers.\n- **B — ACL check (single unit).** The binding is one atomic resource; sub-resources inherit its ACL. `addObserver()` calls a verifier method to confirm the observer can access it and throws otherwise; `removeObserver()` is a no-op; nothing is tracked and no `excludeObservers` is ever needed. Use for repo / document / page / team / single-project bindings.\n- **C — Data-set tracking.** The binding spans sub-resources with **distinct ACLs**, and there is a **per-observer access oracle** for each. The DO logs the data sets actually observed and the current observers; `addObserver()` verifies the observer against **every** logged set (plus a coarse membership baseline) and **stores their verifier**; each later observation that first touches a **new** set re-checks all stored observers and sets `excludeObservers` for any who fail. Use for workspace / organization / dataset-spanning bindings.\n- **D — Low-stakes.** `addObserver()` / `removeObserver()` are no-ops; `getVerifier()` returns a trivial verifier with a no-op public method such as `verify(): void {}` (an empty `WorkerEntrypoint` is not registered in `ctx.exports`). Use when any collaborator may observe (personal, low-stakes services).\n\nThe **B-vs-C decision** (the \"broad binding\" lens): use C only when **both** (1) the binding spans sub-resources with distinct ACLs *and* (2) there's a per-observer oracle to check each against. If one ACL covers everything → B. If there's no oracle → A or D.\n\n#### Implementing strategy C\n\nRoute **every data-revealing observation** through a helper that takes the set id(s) the observation reveals, instead of calling `authorizeObservation()` directly:\n\n```typescript\n// On the Gatekeeper DO. `setIds` are the data sets this observation reveals.\nasync authorizeSetObservation(\n queue: RpcStub, setIds: string[], description: ObservationDescription) {\n const check = setIds.length > 0\n ? await this.#prepareSetObservation(setIds)\n : { pendingSets: [], excludeObservers: undefined };\n await queue.authorizeObservation({ ...description, excludeObservers: check.excludeObservers });\n for (const setId of check.pendingSets) this.#markSetObserved(setId);\n}\n\nasync #prepareSetObservation(setIds: string[]) {\n const pendingSets = [...new Set(setIds)].filter(id => !this.#isSetObserved(id));\n if (pendingSets.length === 0) return { pendingSets, excludeObservers: undefined };\n // This synchronous state change is visible to addObserver() before verifier RPCs can interleave.\n for (const setId of pendingSets) this.#markSetPendingIfUnknown(setId);\n const excluded = new Set();\n for (const [id, verifier] of this.#listObservers()) {\n for (const setId of pendingSets) {\n if (!(await verifier.hasSetAccess(setId))) { excluded.add(id); break; }\n }\n }\n return {\n pendingSets,\n excludeObservers: excluded.size > 0 ? [...excluded] : undefined,\n };\n}\n```\n\nKey points for C:\n\n- **Use two durable states: pending and observed.** Mark unknown sets pending before the first await, recheck pending sets on every retry, and promote them only after `authorizeObservation()` succeeds. A failed authorization leaves them pending. `addObserver()` must check both states and loop until no unchecked sets remain before synchronously storing the verifier; this also closes admission races in either request ordering.\n- **The session impls must route through this helper**, not `approvalQueue.authorizeObservation()`. If sessions hold the raw queue (not the DO), thread a small prepare hook/callback into each session and any sub-sessions it spawns, and expose a completion step that promotes its pending sets after authorization. For a single broad binding the hook is active; for the narrow (B) sibling binding it is absent (passthrough). See Linear/Notion for the shared-session-impl case and Supabase for the context-object case.\n- **One observation may reveal several sets** (e.g. a workspace-wide list whose rows belong to different sub-resources). Pass all of them; union the exclusions over the newly-seen ones. Reads that reveal *no* set (workspace name, member directory, a bare \"open\") pass an empty list and rely on the membership baseline.\n- **`addObserver` baseline:** verify the coarse membership (e.g. same org/workspace) that gates the set-independent reads, then verify each already-observed set, then store the verifier. Fail closed if a needed identity is unknown (e.g. an account connected before you began persisting the workspace id → force a reconnect).\n\n#### `excludeObservers` semantics (why conservative is safe)\n\nWhen `authorizeObservation()` is given `excludeObservers`, the overseer **blocks the observation** if any named observer is still authorized, and only lets it proceed (tearing down the observer) if they've already lost access. So erring toward listing an observer is never a leak — at worst it blocks an observation that could in principle have been allowed. The leak-relevant gate is always the live sharing graph, so stale observer state self-heals on the next open.\n\n## Hooks (push notifications)\n\nSome services can push events to the Gadget (inbound email, webhooks, chat messages, etc.). A gatekeeper exposes this as a **hook**: the Gadget registers a callback, and the gatekeeper later invokes it when an event arrives. Hooks are persistent — they survive across sessions and server restarts — and are subject to the same observation/action approval model as everything else.\n\n`gatekeeper-email` is the canonical reference implementation. Read it alongside the `HookController`, `HookInitiator`, and `ApprovalQueue.bindHook()` JSDoc in `gatekeeper.ts`.\n\n### The pieces\n\n- **Hook interface** (in `types.d.ts`): the methods the Gadget implements to receive events, e.g. `EmailHook.receiveEmail(email)`. It is implemented by the Gadget as an **`RpcTarget`** (or a plain function), *not* a `WorkerEntrypoint`. Reference it from `describe()` via `hookTsType`.\n- **Session method**: a method like `subscribe(callback)` that the Gadget (or, more commonly, an agent in a one-off `executeCode` call) uses to register interest. The `callback` is a **persistent stub** (created by the Gadget with `ctx.restore()`), so it can be stored and re-invoked long after the session ends.\n- **`HookController`** (a `WorkerEntrypoint` you implement): lets the overseer `enable()` / `disable()` the hook. All the state it needs must live in its `props`, so it is constructed via `this.ctx.exports.MyHookControllerImpl({props})` **at bind time**, immediately before calling `bindHook()` — see below.\n- **`HookInitiator`** (provided to you by the overseer): you call `startHook()` on it when an event arrives.\n\n### Lifecycle\n\n1. **Register.** The Gadget calls your Session method (e.g. `subscribe(callback, filter)`). Inside it, construct a `HookController` whose `props` capture the specifics of *this* registration, then call `approvalQueue.bindHook(controller, callback, description)`. The overseer stores the callback and records the hook (initially **disabled**). Do **not** store the callback yourself — it is bound to the current session and would be revoked when the session ends.\n2. **Enable.** When the user approves the hook in the Workshop UI, the overseer calls `controller.enable(initiator, target)`. Store the `initiator` Fetcher somewhere it can be reached when events arrive (e.g. an event-source DO). `target` identifies where the hook delivers (workspace, plus gadget when the hook is pinned to one); persist it alongside the initiator if you display or link to the target — the IDs are fixed when the hook is bound, so there is nothing to refresh. A gatekeeper that doesn't need it still has to declare the parameter, since RPC argument validation rejects arguments the receiver doesn't declare. Avoid storing any other state until enabled; everything else should already be in the controller's `props`.\n3. **Deliver.** When the event occurs, call `initiator.startHook()`. This returns `{callback, approvalQueue}` bound to a fresh session. Call `authorizeObservation()` (a hook event is almost always an observation; register actions too if the callback's return value triggers side effects), then invoke the `callback` to deliver the event to the Gadget.\n4. **Disable / delete.** The overseer calls `controller.disable()`. Forget the stored `initiator` and clean up all related state — `disable()` may never be called again, though the overseer may later call `enable()` afresh.\n\nBecause the callback is a persistent stub tied to a session, the gatekeeper never stores it directly; the overseer hands it back (re-bound to a new session) each time you call `startHook()`. See the SKELETON for the full code shape.\n\n### Documentation\n\nWhen defining a session interface with hooks, it's important to include comments that clearly state when a method expects to be passed a *persistent* stub created with `ctx.restore()`, as opposed to a regular RpcStub. The caller needs to do extra work to make sure the stub they provide you is persistent.\n\n## Reviewing a gatekeeper\n\nReviews tend to stop at general correctness. The most important review is of the agent-facing API, so pressure-test it:\n\n- **Shape.** Read `types.d.ts` as the agent does, as its only documentation. Does the shape make sense? What would you do differently?\n- **User stories.** List the most common things a user would ask an agent to do with this service and walk each through the API. Flag any that are impossible, need sequential round trips that promise pipelining can't remove, or need knowledge the JSDoc doesn't give. Flag dead ends too: anything the grant includes that the agent can't navigate to, such as child pages it can list but not open.\n- **Seams.** Check that resource types, bindings and sessions partition authority along the lines users actually grant:\n - Each `getSupportedResources()` granularity is a grant a user would make, and together they cover the common ones (broad and narrow).\n - A narrow binding's session reaches nothing outside its resource: sub-resources come from stubs on their parent, and no method or option field (`parentId`, `projectId`) takes an ID that escapes the binding.\n - Each method sits on the object whose authority it needs. A cross-resource operation (move, copy, link) must not quietly require, or grant, a broader binding than the user picked.\n - Each binding's types expose only what that binding can do and stay small, and its observer strategy fits how the binding is partitioned (see [Choosing a strategy](#choosing-a-strategy-per-resource-type--binding)).\n\n## Tips\n\n- `types.txt` must be a **symlink** to `types.d.ts`, never a copy. Because it is delivered verbatim, `types.d.ts` must not import from other modules — inline any shared types (see [Documenting the API](#documenting-the-api-typesdts)).\n- Call `.dup()` on `approvalQueue` stubs before storing in a session, since Cap'n Web automatically disposes all stubs in parameters to an RPC call when the call returns.\n- `suggestedBindingName` in `describe()` reflects the resource **type** (e.g. `\"GMAIL_INBOX\"`), not the specific instance.\n- For read-only or push-only gatekeepers, `applyAction()` / `rejectAction()` / `revertAction()` can simply throw (they'll never be called since the gatekeeper never submits actions).\n- For `WorkerEntrypoint` and `DurableObject` subclasses, pass credentials and resource IDs via `ctx.props`, not constructor arguments. RPC stubs pointing to these types can be stored in long-term storage and restored later, creating a new instance based on the same `props`.\n- If the gatekeeper implements multiple unrelated resource types with disjoint APIs, each may have its own `.d.ts` file, so that the `getTypeScriptTypes()` method of the specific `Gatekeeper` implementation only returns the types that matter for it. The `getTypeScriptTypes()` method on the top-level `GatekeeperVendor` should return the concatenation of all of these.\n- All DO classes must appear in `cloudflare.config.ts`'s `migrations` export under `new_sqlite_classes`.\n- Set a self-destruct alarm in `UserAccount.setCallback()` in case the OAuth flow is never completed.\n- `authorizeObservation()` may be called *after* fetching data (so the description can include details about what was fetched) but must be awaited *before* returning anything to the caller.\n- `getVerifier()` / `addObserver()` / `removeObserver()` are **mandatory** — the gatekeeper won't type-check without them. Even a read-only or push-only gatekeeper needs them (sharing is independent of whether the gatekeeper has actions). Pick a strategy per [Observers](#observer-verification): a low-stakes one can be A or D; otherwise B/C.\n\n## Reference implementations\n\n- `packages/gatekeeper-google/` — OAuth, multiple resource types (Gmail, Google Docs, BigQuery), actions, caching/simulation examples, multiple Session types. **Observers:** all three strategies in one package — Gmail=A (always throw), Doc=B (single-unit ACL via `GoogleVerifier.hasDocAccess`), BigQuery=C (dataset tracking via `hasDatasetAccess`).\n- `packages/gatekeeper-email/` — Hook-based push notifications, no actions, email address claiming. **Observers:** strategy D (low-stakes no-ops + trivial verifier).\n- `packages/gatekeeper-github/` — **Observers:** clean strategy B example — `GitHubVerifier.hasRepoAccess` plus a one-method `addObserver`.\n- `packages/gatekeeper-gitlab/` — A **mirror** of gatekeeper-github for a provider with instance configuration (self-hosted URLs, an optional Cloudflare Access service token on upstream requests) and **rotating credentials** (expiring access tokens, single-use refresh tokens refreshed under a mutex). Reads the same `plans/worktrees.md` §3 git contract through `gatekeeper-kit`'s `git-transport`/`git-objects`/`git-diff`. **Observers:** strategy B with a role-aware probe (`membershipGrantsFullRead`): Reporter membership whatever the visibility, since a public project can still hold confidential issues and internal notes, read from `members/all?user_ids[]=` because the project's `permissions` object omits group-inherited access. Its `plans/gitlab-gatekeeper.md` divergence table is a worked example of porting one gatekeeper's API to another provider's vocabulary.\n- `packages/gatekeeper-supabase/` — **Observers:** strategy C with a per-session context object (`authorizeProjectObservation`) — good when sessions already hold a shared context.\n- `packages/gatekeeper-linear/` & `packages/gatekeeper-notion/` — **Observers:** strategy C where the page/team session impls are shared between the narrow (B) and broad (C) bindings, threading an `observe` hook through sub-sessions; both also handle one observation revealing multiple sets.\n- `packages/workshop-shared/src/gatekeeper.ts` — Canonical interfaces with detailed JSDoc (`getVerifier`, `addObserver`, `removeObserver`, `GatekeeperUserVerifier`, `ObservationDescription.excludeObservers`).\n","AGENTS.md":"This project is building a platform for \"vibe coded\" personal applications and AI agents that run inside a strong sandbox.\n\nThe following files are commonly important to reference:\n\n* packages/workshop-shared/node_modules/capnweb/README.md: Explains how to use Cap'n Web RPC, which is used extensively for client-server communications.\n* packages/workshop-shared/src/api.ts: Defines the RPC API used between the frontend and backend.\n\nThe project structure is:\n\n* packages/workshop-frontend: The Gadgets Workshop UI.\n * This is a pure single-page app, running entirely client-side.\n * It speaks to the backend using an RPC API over a persistent WebSocket connection.\n * Uses React, Kumo UI (https://kumo-ui.com/api/component-registry), Phosphor icons, and Vite.\n* packages/workshop-backend: The Gadgets Workshop server.\n * Runs on Cloudflare Workers.\n * This is the **kernel**: it defines the architecture and is held to a higher bar than UI/gatekeeper code. Reviewers read *every line* of `workshop-backend` and of API changes in `workshop-shared`, so keep diffs here small and elegant. Concretely: doc-comment **every** exported member of the `workshop-shared` public API (types, consts, and functions — not just interfaces); never introduce a hand-written interface that mirrors an RPC interface plus an `as unknown as` cast (derive from the real type instead, or rethink the design); and prefer reusing existing mechanisms over adding parallel ones. Capability-based security note: a resource becomes \"ambient\" (auto-injected) only by user/admin configuration — a gatekeeper must never assert its own ambience. When a change to this package is large, split it by concern into separate PRs (and at minimum group commits so `workshop-backend`/`workshop-shared` can be reviewed apart from UI), since fewer kernel lines = easier review.\n * Installs the **bundled blueprints** from `@gadgets/bundled-blueprints` on a deployment's first `/api` request, and offers them as the deployment's standard output formats. `scripts/build-bundled-blueprints.ts` generates the gitignored `src/generated/bundled-blueprints.ts` they are installed from, which holds each blueprint's manifest and built files (`BUNDLED_BLUEPRINTS_DIR` overrides the source directory), so `build` and `test` both run the generator first; `pnpm import:bundled-blueprint` updates or adds a blueprint from a Workshop export, of either `.gadget` version. Installing one (`src/bundled-blueprints.ts`) stores it as any published blueprint is stored: a git commit of its files, as a packfile at `/` in R2, named by `metadata.commitId` in KV (see `docs/blueprints.md`). The commit is a *snapshot release* (`buildSnapshotRelease` in `src/blueprint-release.ts`): parentless, with a fixed author, date and message, so it depends on the files alone. Every deployment therefore derives the same commit from the same files, and the installer never reads what was installed before. The cost is that a bundled blueprint's versions are not chained to one another as a published blueprint's releases are. A gadget made from one still takes its updates, merged against the release the gadget last took.\n * Agent turns emit the Workers trace spans Cloudflare's Agents dashboard reads (`src/agent-tracing.ts`): `invoke_agent` per turn, `chat` per model request, `execute_tool` per tool call, and `tool_approval` when an agent's action waits for a manual decision and when it is approved or denied. They carry token counts, including cache reads and writes, but never prompts, responses or tool data. A span belongs to the invocation that opened it, and once a Durable Object invocation has returned, the next event the object receives ends its trace. So a turn keeps all its spans only while the request that started it (usually the browser session) stays open.\n* packages/bundled-blueprints: The blueprints the deployment ships with, `blueprints//` holds each blueprint's `blueprint.json` plus its gadget code under `files/`, which may be TypeScript.\n* packages/workshop-shared: Shared API definitions between client and server.\n * This defines the application's RPC interface.\n * The RPC protocol is Cap'n Web, which has similar semantics to Cloudflare's Worker-to-Worker RPC system, while being able to run in a browser over WebSocket. Read the readme for details.\n* packages/configurator-ui: The authoring API (`src/index.ts`, type-only stubs) for optional gatekeeper resource configurator UI modules, the sandbox runtime that renders them (`src/runtime/`: Kumo components on `preact/compat`), and the build that bundles both into each configurator's frame (`build/`).\n * Gatekeeper configurator UI modules are compiled by `scripts/build-gatekeeper-configurator.ts` as part of package builds. Each frame is one self-contained HTML document: the minified runtime, its Tailwind/Kumo CSS, and the module, under a content security policy that admits only those scripts by hash and allows no network access. Kumo and Base UI support only React, so the browser suite (`vitest.browser.config.ts`, Chromium) is what catches an upgrade that stops working on Preact; `build/frame.test.ts` drives a generated frame over the real Cap'n Web host protocol.\n * `pnpm dev-server` rebuilds a gatekeeper's frames when its `src/configurator/` or the runtime's `src/runtime/` changes; restart it after editing `build/`, which the watcher has already loaded.\n* packages/ui: Shared runtime React UI used across the Workshop and gatekeeper management apps.\n * Kumo remains the primitive and token foundation. Reusable Gadgets interaction patterns and composed controls belong here rather than being reimplemented in individual apps.\n* packages/gatekeeper-*: Gatekeeper workers for external service integrations.\n * Each gatekeeper runs as a separate Cloudflare Worker — with one exception the prefix does not capture: a `gatekeeper-*` package with **no `wrangler.jsonc` is a library, not a worker** (`gatekeeper-kit` here; `gatekeeper-shared` in the internal repo). Deployable discovery is config-gated, not name-gated — `readDeployablePackages` in `scripts/release/manifest-lib.ts` keys solely on the presence of `wrangler.jsonc`, and `run-dev-server.ts` requires it too — so adding one to a library package is what would make it deployable, at which point `workerKind` would classify it a gatekeeper by prefix and the deploy wizard would demand `CLIENT_ID`/`CLIENT_SECRET` for it. `manifest-lib.test.ts` fails first if that ever happens.\n * Gatekeepers handle OAuth flows and provide sandboxed access to external APIs. A connect URL is a bearer capability, so every connect/reconnect flow ends on the kit's `connectHandoffPageHtml`, which sends the popup to the Workshop's `/connect/handoff` page, and that page redeems the single-use ticket over the popup's own session together with a per-flow nonce (see `docs/connect-handoff.md`); a reconnect stages its new credentials via `gatekeeper-kit/credential-stage` until the Workshop calls `GatekeeperUser.commitReconnect(stageId)` with the id that completion reported; completion is confirmed through the ticket, never through the URL alone.\n * A gatekeeper may declare `VendorDescription.autoProvisionsAccount`: it can mint a connected account with no OAuth flow (via `GatekeeperVendor.createAccount()`, which takes no user identity). For such gatekeepers the deployment admin picks a per-vendor mode in the admin Gatekeepers panel — **disabled** / **optional** / **enabled** (default **optional**) — resolved in `provisioning-policy.ts`: `enabled` auto-provisions the account for every user (forced, and hidden from the Connectors list), `optional` lets each user opt in from the Connectors page or during onboarding (where each starts switched on and is provisioned when the user finishes), and `disabled` offers it to no one (existing accounts go dormant). The Workshop persists the account in the user DO like any connected account (the account capability — not an asserted identity — is the authority thereafter). The **account** (a `GatekeeperUser`) declares in its `AccountDescription` whether it provides an agent **singleton** (`singleton: { tsType }`) and/or a **management UI** (`providesUi`). The Workshop auto-provides the singleton to the owner's workspaces as an **ambient gatekeeper record**, folded into each chat's env as a **named chat binding** (named by the gatekeeper's `suggestedBindingName`; see `prepareChatBindings` in overseer.ts) that the agent reads in `executeCode` (`getSession`/`getAgentCatalog`), each read recorded as an observation. It is not bound to any gadget by default — most gadgets never call it programmatically — but the agent may wire it into a gadget's binding list with `setGadgetBinding` when the gadget's persistent code needs it. The UI is hosted at `/gatekeepers/$appId` (the gatekeeper's vendor id, e.g. `/gatekeepers/context`) via `startAppUi({ isAdmin })`. The two are orthogonal — an account can declare either, both, or neither.\n* packages/mcp-shared: Shared implementation behind the two MCP gatekeepers — `gatekeeper-mcp` (endpoints a user pastes) and `gatekeeper-mcp-portal` (one admin-configured portal). Not a Worker; a library both import, holding the MCP client, the OAuth chain, the account DO base, the resource-URL scope grammar, and the queued-action store. See `packages/mcp-shared/README.md` and each connector's README.\n * The trust boundary is `tools.ts`, and nothing outside it reads a tool's annotations: a tool the server declares `readOnlyHint: true` runs as an observation, everything else is queued for approval, and auto-*applying* a write additionally requires a `vetted` endpoint — which only the portal can produce, via `MCP_PORTAL_TRUST_ANNOTATIONS`.\n * OAuth uses the official `@modelcontextprotocol/client`; always give SDK OAuth operations `sdkFetch(...)` so every request and redirect retains endpoint and SSRF checks.\n* packages/gatekeeper-context: The Context Library — a gatekeeper whose account provides a singleton read session + a management UI, for authoring collections of context documents that agents read as observations. Collections have one of two visibilities: **private** (created by one account and shareable with others) and **public** (created/edited only by deployment admins, readable by everyone and auto-enabled for all users; not shareable). It owns its state in three Durable Objects (`ContextCollectionDurableObject` for content and a private collection's grants, `UserLibraryDurableObject` for each account's index of collections it created or was given, `LibraryRegistryDurableObject` for the domain's public set) plus a KV namespace. All data is namespaced by a `sharingDomain` (from the binding's props, see `domain.ts`) so multiple workshops sharing one gatekeeper instance stay isolated.\n * Sharing is whole-collection. A private collection's own grants (`viewer` / `editor` / `owner`, keyed by Context account) and its `everyoneCanView` flag are the sole authority, interpreted only by `collection-access.ts`; every listing, agent read, and observer verification re-checks them live, so a library index entry is discovery and never access. A collection always keeps an owner except when its last owner's account is disconnected while others still hold access; its editors then keep editor permissions only (nobody can delete it or grant ownership), and it is deleted once its last grant goes, even if everyone can view it. Everyone-viewable only grants read access (so sharing a workspace that used the collection is not blocked); it never adds the collection to anyone's library. Shares arrive through the Workshop user picker: the management API redeems the ticket and takes the recipient's account IDs from their Context verifiers (`getAccountId`), never from the browser, and grants all of that person's accounts together. Losing write access revokes the git mirror tokens that account minted, and tokens from before sharing count as the creator's; the collection serializes grant changes, token minting, and deletion so none can race another, and retries a failed revocation from an alarm. Disconnecting marks the account's library first, so a share racing it is refused rather than left behind. `plans/context-collection-sharing.md` is the design record.\n * Its `GatekeeperVendor` entrypoint (bound as `GATEKEEPER_CONTEXT`) declares `autoProvisionsAccount` and mints a `ContextAccount` via `createAccount()` (no user identity is passed in; the account keys its private data by its own generated `accountId`). The account exposes the agent read session (`getSession()`), collection discovery metadata (`getAgentCatalog()`), and a management UI (`startAppUi({ isAdmin })`). The UI is a single-file React SPA in `app/` (Vite + Tailwind + Kumo) bundled by `build-app.ts` into `src/generated/app.txt`.\n* packages/gatekeeper-scheduler: Scheduled Tasks — an auto-provisioned gatekeeper whose account provides an ambient singleton for registering persistent workspace callbacks plus a read-only management UI. One account-scoped `ScheduleDriver` Durable Object stores enabled schedules and delivers them from a shared alarm; hook enablement remains in the Workshop Connections UI.\n* packages/gatekeeper-websearch: Web Search — an auto-provisioned gatekeeper whose account provides an ambient `WEB_SEARCH` singleton that searches the public web through its own Workers AI binding (`websearch()`, through the AI Gateway its `CF_AI_GATEWAY` var names, provider pinned to Ceramic). The deploy service sets that var to the instance's gateway, the backend's; anywhere else it defaults to the account's `default` gateway. Each query is recorded as an observation *before* it is sent. A workspace that has observed restricted data can still search: unlike a `webFetch` URL, the query can only go to the pinned provider. Preinstalled on every deploy like Scheduled Tasks; every search spends the account's AI Gateway credits, outside the model spend limits, unless that gateway holds a Ceramic key, which Ceramic then bills. The README is the design record.\n* packages/gatekeeper-gitlab: GitLab, for gitlab.com and self-hosted instances — a mirror of `gatekeeper-github` (project / issue / merge request resources, the same action queue and read-time simulation, the same worktree contract) in GitLab's own terms. `plans/gitlab-gatekeeper.md` is the design record, and its divergence table lists every place GitLab's API forced a different shape; the README covers instance configuration (`GITLAB_URL`, `GITLAB_API_URL`, and an optional Cloudflare Access service token).\n* packages/gatekeeper-x: X (formerly Twitter) — account / post / List / read-only profile resources over plain `fetch` (the `twitter-api-v2` package breaks on Workers). `plans/x-gatekeeper.md` is the design record. X's API is pay-per-use and bills every resource a read returns, so cost is part of the design and easy to undo by accident:\n * Every read goes through the gatekeeper's `#read`, which reserves against the connection's daily read limit (`X_DAILY_READ_LIMIT`, counted per UTC day in the `UserAccount` DO across all of the connection's bindings) and settles with what X returned. Listings use `XCursor`, one X request per `next()`, never the kit's `TokenCursor`, which refills a short page with up to ten more billed requests.\n * Only bookmark, mute and hide are `autoApprovable`: X's developer policy forbids automating likes, follows, reposts and posts. Do not widen that list.\n * A connection is pinned to the X user it was made as (a reconnect as anyone else is refused and its new grant revoked), and actions are fenced on that X user's ID rather than the connection generation, so a same-user reconnect to widen scopes does not strand pending actions.\n * Publishing is `claimBeforeApply`, and a send whose outcome X never reported is reconciled inline on the next apply (an attempt marker, then a look at the account's posts from around the attempt, binding only a unique match on text, links, media and reply parent), because the kit's `ActionOutcomeUnknownError` is terminal. Creating a List is reconciled the same way. Rejecting a publish or List creation that may already be on X is refused.\n * X is renaming \"tweet\" to \"post\" on the wire and both spellings occur; `x-normalize.ts` reads both. The configurators copy URL grammar from `x-urls.ts`, and `__tests__/configurator-url.test.ts` keeps the copies in step.\n* packages/gatekeeper-cloudflare: Cloudflare OAuth, serving three unrelated purposes from one connected account — sign-in (`AUTH_GATEKEEPERS`), AI Gateway billing, and **Workers Observability** read-only telemetry resources. Two resource granularities (whole account, or one Worker) both map to the single indivisible `workers-observability.read` scope, so the capability boundary is the *binding*, not the grant.\n * Layering: `observability-api.ts` is the only place that talks HTTP; `observability-parse.ts` validates every response (no blind casts); `observability-session.ts` is the agent-facing session, where every read funnels through one `#observe` so no path returns data unaudited; `observability-discovery.ts` derives field names/values from a sampled events query.\n * Scopes fail closed to `BILLING_SCOPES`, and an omitted `resourceUrlPatterns` (\"all resource types\") is distinct from `[]` (\"none\"): a billing-only connection must not silently acquire telemetry access, and recording a wider grant than was made would make `ensureResources` short-circuit into a binding that 403s with no way to re-prompt.\n * Three provider behaviours return wrong-but-plausible data with no error, so none is trusted (all verified against a live account): `telemetry/keys`/`values` **ignore** the `filters` they accept, so a constrained discovery call is answered from a filtered `telemetry/query` sample or it would disclose the whole account; an unknown filter key matches nothing, which bites because a log's own fields are returned nested under `source` but indexed under their *bare* name (`{event: \"x\"}` → `source.event`, queried as `event`, hence `observabilityFieldKey` accepting the `source.` alias wherever a caller names a field); and `/accounts` pages at 20 by default, so it must be walked to the end.\n * Worker-scoped bindings prepend an immutable `$metadata.service` filter *and* re-filter the response, since a filter the provider silently ignored would leak another Worker's telemetry. A dropped event proves the filter was not applied, so the provider's own `count` is then withheld rather than reported (it would count the whole account) and the drop is logged at `error`; `statistics` is kept, since it describes what the query cost rather than how much matched. Pagination cursors come from the provider's raw events rather than the surviving ones, so a fully-foreign page can't stall pagination and hide the caller's own older data. Trace *summaries* are account-only (their shape describes the whole cross-service trace); a Worker binding can still fetch its own events for a known trace id. `calculate()` is the one read with no second line of defence — an aggregate can't be un-mixed — so it rests solely on the injected filter; that is accepted and documented on the method, with the group-by fix left as a follow-up.\n * A provider error message can quote a caller-supplied filter value back, so only its numeric `codes` are logged — filter *values* stay out of the audit trail (`summarizeFilter`), and the message travels to the caller who caused it.\n * Tests are two vitest projects: `vitest.config.ts` (Node, pure logic) and `vitest.worker.config.ts` (workerd, for `RpcTarget`/`RpcStub`/Durable Objects). The workerd suite reaches the gatekeeper through a `TestHooks` Durable Object because a `DurableObjectClass` carrying `ctx.props` is only reachable via `ctx.facets` — the way the overseer instantiates it.\n * `src/configurator/*.tsx` duplicate the resource-URL grammar from `resources.ts` and **must**: `build-gatekeeper-configurator.ts` transpiles each per-file, stripping only `@gadgets/configurator-ui` and type-only imports, so they cannot import runtime helpers. `__tests__/configurator-url.test.ts` keeps the copies in step, and `configurator-fields.test.ts` drives `render` against a mocked runtime — the runtime's `clearFields` only drops an autocomplete's typed query, so a dependent field must *also* be nulled through `setValues` or the stale value silently survives into the resource URL.\n* packages/router: The public origin of a deployed gadgets instance. Serves the workshop-frontend assets and routes by path prefix: `/api/*` and `/blueprint-screenshot/*` to the workshop backend, `/gatekeeper//*` to whichever gatekeepers are bound (discovered by scanning its own `GATEKEEPER_*` service bindings, so installing a gatekeeper is purely a binding change). The same worker doubles as the dev router (`pnpm dev-server`): with no `ASSETS` binding it proxies frontend requests to the Vite dev server instead.\n\nFrontend conventions (Workshop, gatekeeper management apps, and shared UI):\n\n* IMPORTANT: Load the `frontend-conventions` skill before creating, materially changing, moving, or reviewing React frontend code anywhere under `packages/`. The bullets below are the mandatory summary; the skill contains the complete conventions and examples.\n\n* Organize code by product ownership before implementation type. Keep feature-owned components, hooks, tests, and utilities together; start directories flat and introduce responsibility-named subdirectories only when a subsystem grows.\n* Use PascalCase filenames for components and camelCase filenames for hooks and non-component modules. Colocate `*.test.ts(x)` files with their subject.\n* Keep small stateless render helpers private. Extract a component or hook when it owns meaningful state, effects, interactions, accessibility behavior, or a reusable responsibility.\n* Cross-application UI belongs in `@gadgets/ui`. An app's local `components/` directory is shared only within that app. Product-specific compositions stay with the product even when they use shared primitives.\n* Use Kumo components and semantic Kumo tokens by default. Check Kumo and `@gadgets/ui` before creating a control or interaction pattern. Do not add custom color literals, feature-local token systems, or wrappers that only restyle Kumo.\n* Consult the installed Kumo API before implementing or changing Kumo UI: run `npx @cloudflare/kumo docs ` (for example, `npx @cloudflare/kumo docs Select`).\n* Tailwind is appropriate for structure, spacing, sizing, positioning, responsive behavior, and typography. Custom CSS is for technical behavior Kumo and utilities cannot express.\n* Represent props that are valid only together as an object or discriminated union. Controlled values require a change callback. Name callbacks `on` and pass domain values rather than React setters or browser events.\n* Add slots, variants, DOM passthrough, imperative refs, and other customization surface only for current callers. Do not generalize based on speculative reuse.\n* Treat Effects as synchronization with external systems, not as derived-state machinery. Keep state close to its owner, calculate render data during render, clean up subscriptions, and avoid chains of Effects.\n* Prefer named arrow-function components and hooks. Do not add `useMemo` or `useCallback` without a concrete identity or performance need.\n* Preserve keyboard behavior, focus management, accessible names, and announcements when building or extracting interactions.\n* Tests should protect observable behavior, product rules, accessibility, state transitions, races, and failure paths. Do not test framework behavior or implementation details merely for coverage.\n* Prefer code that communicates intent through names and types. Comments should explain non-obvious constraints and reasons, not narrate the next line.\n\nDeployment admin settings (the `/admin` panel) follow a few conventions worth knowing when extending them:\n\n* `packages/workshop-backend/src/storage-schema/admin-settings-storage.ts` defines `AdminConfig` (its helpers live in `src/admin-config.ts`) — the deployment's \"soft\" customizations: agent instructions, banners/theme, and which gatekeeper connectors/resources are offered (plus the three-state mode for auto-provisioning gatekeepers, see `provisioning-policy.ts`). Connectors/resources default to enabled and the admin UI opts them *out*; auto-provisioning gatekeepers default to *optional*. **Authentication/authorization config (sign-in providers via `AUTH_GATEKEEPERS`, password login via `DISABLE_PASSWORD_AUTH`) is deliberately NOT here** — it stays env-var driven (`auth/config.ts`) so it can't be changed by a compromised admin session.\n* The `AdminSettings` durable object owns the authoritative `AdminConfig` and mirrors it to a single reserved KV key (`.adminConfig`, see `isReservedBlueprintKey()`), so hot-path code (connect/agent) reads it with one cheap KV get via `readAdminConfig(env)`. The DO is the only writer (`updateAdminConfig(patch)`).\n* Admin operations are exposed as an `AdminApi` capability obtained via `AuthenticatedApi.getAdminApi()` (returns null for non-admins). The `#isAdmin()` check happens once when the capability is minted, so the individual methods don't re-check.\n* `user.ts:#assertResourceEnabled()` is the single core chokepoint where disabled gatekeepers/resources are enforced before a capability is minted. Both mints call it: `getGatekeeperClassFor()` (gadget/agent code can't reach it directly) and `createResourceGatekeeper()` (reached only through the agent's `createExternalResource` tool).\n* In AI Gateway mode the deployment's models are admin settings too (`AdminConfig.modelModes`, `addedModels`, `modelSettings`, `addedProviders`, `userModelsEnabled`). `GatewayModels` in `ai-gateway.ts` is the only place that merges them with `SUGGESTED_MODELS`, and *disabled* is enforced where a model is about to run: `user.ts:getChatContext()` and `LanguageModelGatekeeper.startSession()`.\n\nWorker configs: each Worker's `cloudflare.config.ts` (`@cloudflare/config` format, built from the shared factory in `scripts/worker-config.ts`) is the source of truth. The `wrangler.jsonc` beside it is committed but generated by `pnpm configs:generate` (`scripts/generate-worker-configs.ts`) and never edited by hand, because Wrangler's new-config support cannot drive the multi-worker dev server, `wrangler types`, the vitest pools or the integration harness. Settings `@cloudflare/config` has no field for (`build`, module `rules`, KV `preview_id`, `assets.directory`) go in the config's `wrangler` export, and Durable Object migrations stay tagged in its `migrations` export, because the release manifest ships them to the deploy service verbatim. `pnpm configs:check` (part of `pnpm lint` and CI) fails on a stale or hand-written file; `pnpm dev-server` regenerates before starting.\n\nRelease pipeline (`scripts/release/`) — how customer instances get deployed:\n\n* `build-release.ts` bundles every deployable worker byte-identically (wrangler dry-run with the pinned wrangler), builds the Access-mode frontend asset build, and generates the release manifest — the contract between this repo's CI and the deploy service, produced by `manifest-lib.ts` from each package's wrangler.jsonc with account-specific values replaced by placeholders (`$ACCOUNT_ID`, `$WORKER_NAME(...)`, `$SECRET(...)`, `$PUBLIC_BASE_URL`, ...).\n* `upload-release.ts` mirrors the release to R2 content-addressed, manifest last; with `--candidate` the manifest lands under `candidates//` (invisible to the deploy service) so e2e can verify it, and `promote-release.ts` then copies it to `releases//` — publishing is that single all-or-nothing manifest copy. The copy is not isolated against concurrent promotions, so CI serializes promote runs (a GitLab resource group) and the script's newer-release guard skips candidates that a later release has already superseded.\n* The manifest is covered by a golden-file test; after an intentional manifest change, regenerate with `UPDATE_GOLDEN=1 node --test scripts/release/manifest-lib.test.ts` and review the golden diff.\n* Running the flow by hand (upload and promote need `R2_ENDPOINT`, `R2_BUCKET`, `R2_ACCESS_KEY_ID`, `R2_SECRET_ACCESS_KEY`):\n * `node scripts/release/build-release.ts --out release-out` — build everything into `release-out/` (id defaults to `r-` in CI, `dev-` locally; override with `--release-id `).\n * `node scripts/release/upload-release.ts --release release-out --candidate` — mirror to R2; omit `--candidate` to publish directly (bypasses the gate — CI never does this).\n * `node scripts/release/promote-release.ts --release-id ` — copy the verified candidate's manifest into `releases//`.\n* Deploy-wizard configuration: an installable gatekeeper's user-supplied inputs default to OAuth `CLIENT_ID`/`CLIENT_SECRET` secrets; a per-package `deploy-inputs.json` overrides them, and `NO_DEFAULT_CRED_INPUTS` in `manifest-lib.ts` opts out gatekeepers that take no third-party OAuth app credentials (the wizard blocks Install on unfilled secret inputs, so a spurious default makes a gatekeeper uninstallable). Backend instance-state vars (`ADMINS`, `CLOUDFLARE_OS_DEPLOYMENT`, ...) are injected by the deploy service at PUT time, never manifest-templated.\n\nDevelopment checks:\n\n- Run `pnpm lint` before pushing; it includes script types, generated-config checks, and the workspace build.\n- `pnpm build` runs type-checks and codegen. For one package use `pnpm exec vp run -F build`; most builds are tasks, not package.json scripts.\n- Use `pnpm --filter test:run` while iterating and `pnpm test` for workspace verification. Cached tasks may replay results; cold-checkout tests must generate their own prerequisites on both entrypoints.\n- Cached Vite+ tasks strip undeclared environment variables. Declare output-affecting variables in `cache.env`; a path value does not fingerprint the external files it names.\n- For slow CI/container runs, keep the local watchdog defaults and explicitly choose longer limits. See [testing guidance](docs/testing.md) for commands and timeout policy.\n- Read [build-system guidance](docs/build-system.md) when changing task graphs, codegen, caching, or dev-server startup; [integration testing](docs/integration-testing.md) covers the workerd harness.\n\nIMPORTANT: This repository uses pnpm, not npm. Always use pnpm.\n\nIMPORTANT: Remember when using RPC to use promise pipelining whenever possible. Cap'n Web implements promise pipelining (similar to Cap'n Proto). This means that if an RPC returns a stub, it's not necessary to await the RPC -- the promise itself can be used in place of the stub. Also, Cap'n Web lets you use the promise for a future result (even if it isn't a stub) in the arguments for another call; the promise will be replaced with its resolution on the server side before delivering the arguments. See the Cap'n Web README.md for more details.\n\nIMPORTANT: When using React's useState(), the state value cannot be an RPC stub. At runtime, all stubs appear to be callable (because the system doesn't actually know if the stub points to a function on the server side or not). But the setter returned by useState() has different behavior if passed a function (including any callable object): it calls the function in order to get the state. In order to avoid this problem, whenever a useState() state will contain an RpcStub, it's important to wrap the stub in an object, and set the state to that object instead.\n\nIMPORTANT: RPC stubs must be disposed to prevent resource leaks on the server side. Call `stub[Symbol.dispose]()` when the stub is no longer needed (or use a `using` declaration where possible). In particular, when a React component obtains a stub in a useEffect, the cleanup function should dispose the stub.\n\nIMPORTANT: All RPC interface implementations should use the annotation `@validateRpc()` to apply capnweb-validate, which installs auto-generated runtime type validation matching the interface's TypeScript signatures. Do not write redundant validation code that duplicates the checks capnweb-validate already covers.\n\nIMPORTANT: Server-side logging uses `@gadgets/observability/logger` (frontend browser `console.*` is out of scope):\n- Define a package-owned field type and module-scoped logger with a stable dot-separated `component`\n and, for gatekeepers, `vendorId`:\n `const logger = createLogger({ component: \"gatekeeper.github\", vendorId: VENDOR_ID });`.\n- Emit concrete event names and relevant typed fields, for example:\n `logger.warn(\"failed to notify credential expiry\", { event: \"credentials.expiry.notify.failed\", error: err });`.\n Each call emits one indexed object; module/child fields such as `vendorId` are inherited.\n- Use immutable `logger.with(fields)` for object-owned or nearby context. Prefer module/object loggers\n over logger parameters, and do not replace a shallow child logger with ambient context just to\n remove a local variable.\n- For bounded operation context needed by deep helpers, independent loggers, or other observability\n consumers, use `createObservabilityContext` from `@gadgets/observability/observability-context`.\n Re-establish it per operation;\n it does not cross RPC, hibernation, or restart, and requires `nodejs_als` or `nodejs_compat`.\n- Pass caught values as `error`. The helper stringifies `Error` instances and primitives, uses an\n own string `message` for plain objects, omits `undefined`, and adds stacks to all `Error` logs.\n Keep this normalization deliberately small; do not traverse causes or copy arbitrary properties.\n- Extend field vocabularies locally. Levels: `error` needs attention, `warn` continues best-effort,\n `info` is notable lifecycle, and `debug` is noisy breadcrumbs. Never log secrets, prompts, headers,\n tokens, or request/response bodies.\n- To also dispatch a failure to the optional external issue Reporter (in addition to logging it),\n call `reportIssue(failureSite, caught, options?)` from\n `@gadgets/observability/error-reporting`. Attach ambient fields from the package's observability\n context and augment them with capture-site fields:\n `reportIssue(\"overseer.catalog-fallback\", err, { handled: true, attributes: { ...obsContext.get(), gatekeeperId } });`.\n It is a no-op when the `ERROR_REPORTER` binding is absent (local dev / deployments without an issue\n destination). Only bounded scalars are retained as attributes; reported context obeys the same\n no-secrets rules as log fields.\n- Usage metrics go to the optional `METRICS` Analytics Engine dataset through\n `@gadgets/observability/metrics`, whose column layout (`metrics-schema.ts`) is also what\n dashboards query; Workshop product events reach it through `recordAnalytics`.\n\nIMPORTANT: Frontend error reporting is a separate, opt-in path:\n- `@gadgets/error-reporting` owns the vendor-neutral browser/Worker event contract and tolerant,\n bounded normalization. `VITE_FRONTEND_ERROR_REPORTING=true` enables trusted frontend producers\n and their hidden source maps at build time; deployments without reporting should leave it unset.\n- The Workshop browser sends best-effort reports to the same-origin `POST /api/client-errors`\n endpoint. The backend dispatches only when both `FRONTEND_ERROR_REPORTER` and\n `FRONTEND_ERROR_RATE_LIMITER` are bound; otherwise the endpoint is an intentional no-op.\n- Gatekeeper management/configurator UIs run as Workshop-owned opaque-origin `srcDoc` frames. They\n send bounded reports with `postMessage`; the host accepts them only from the known frame window\n with origin `null`, adds host-owned surface/vendor context, and performs the same-origin POST.\n Do not add direct cross-origin reporting from a gatekeeper Worker domain.\n- Frontend reports never convey authority. `reportedUserId` is supplied by the client and unverified\n — the name records that it is a report, not a finding — so it is a diagnostic label only and must\n never be read to make a decision. `pageLocation` is origin and pathname only, rebuilt by\n `normalizePageLocation` rather than trusted from producers, because a share link's fragment is a\n bearer capability and an `href` also retains credentials; non-`http(s)` URLs are dropped entirely.\n- Install automatic capture only in trusted first-party surfaces, never gadget/user-authored code.\n Exception messages and stacks reach the external Reporter, so never intentionally put secrets,\n prompts, tokens, headers, or request/response bodies in thrown errors or report metadata.\n","packages/bundled-blueprints/README.md":"# Bundled blueprints\n\nThis package holds the blueprints that ship with this repo, the gadget libraries they import, and\nthe build that turns a blueprint directory into the files the Workshop backend installs. A fresh\ndeployment installs the blueprints into BLUEPRINTS KV and BLUEPRINT_CONTENT R2 on its first `/api`\nrequest, after which they are ordinary blueprints, and promotes them as its standard output formats.\n\"Bundled\" is what this package holds; \"format\" is a curation state an admin controls at runtime --\na bundled blueprint can be taken out of the formats menu, and an unbundled one promoted into it.\n\nNothing here is deployed on its own. The Workshop backend's `scripts/build-bundled-blueprints.ts`\nimports `src/` to generate the gitignored `src/generated/bundled-blueprints.ts` it compiles the\nblueprints into, and `pnpm import:bundled-blueprint` (the same package) writes into `blueprints/`.\n\n## Layout\n\n```\nblueprints// one bundled blueprint, committed as reviewable source\n blueprint.json install ID, presentation, provenance, bindings, version, revision\n files/ the gadget's code; may contain nested directories\n README.md\n client.ts import { el } from \"@gadgets/bundled-blueprints/libraries/ui/client\"\n server.ts import { MutationQueue } from \".../libraries/sync/server\"\n lib/protocol.ts the document, operation and RPC types both sides share\n __tests__/ vitest, repo-only; never part of the blueprint\nlibraries// a gadget library: client.ts, server.ts, src/**, __tests__/** (see libraries/README.md)\nsrc/ the build: source and archive reader (files.ts), manifest parser\n (manifest.ts), module generator (generate.ts); index.ts is what the backend imports\n__tests__/ the build's own tests\n```\n\n`files/` is the gadget's code. `blueprint.json` contains its install ID, presentation, provenance,\nbindings, blueprint `version`, and bundled `revision`. The build embeds the manifest and the files,\nas built, in the generated Worker module. No binary archive is committed, and none is built.\n\nInstalling a blueprint makes a git commit of its files, as publishing one from a Workshop does, and\nstores it as a packfile. The commit has no parent and a fixed author, date and message, so it\ndepends on the files and nothing else: every deployment that installs the same files installs the\nsame commit, and a blueprint whose files have not changed is the same commit however often it is\ninstalled. A bundled blueprint's versions are not chained to one another the way a published\nblueprint's releases are: each is a commit on its own.\n\n### Libraries\n\nA blueprint may import the shared **gadget libraries** in `libraries/` (see [its\nREADME](libraries/README.md)) by this package's name and the subpath its `package.json` exports:\n`@gadgets/bundled-blueprints/libraries//client` from its client, `...//server` from its\nserver. The build resolves each to the library's entry and inlines what the entry uses into the\nshipped `client.js` / `server.js`, as it does a `lib/` module, so the blueprint stays\nself-contained and a gadget created from it carries its own copy of the library as of its\ninstantiation. A client may not import a library's server side (it would drag a Durable Object into\nthe iframe), and a library, reached by that subpath, is the one thing an import may reach outside\n`files/` for. The importer has to be TypeScript: a JavaScript module ships as written, with nothing\nat runtime to resolve the package name against, so it cannot import a library, and the build rejects\nthe attempt. The Docs, Sheets and Slides blueprints are built on the `ui` and `sync` libraries, with\ntheir own domain code in `files/`.\n\n### TypeScript sources\n\n`files/` may be written in TypeScript: `client.ts` and `server.ts` are the entry points, and\n`lib/**/*.ts` holds the modules they import (by on-disk name, `./lib/protocol.ts`). The build bundles\neach entry with its imports into the `client.js` / `server.js` the blueprint ships -- readable\nrather than minified -- so the installed gadget, and the agent that later edits it, see exactly one\nJavaScript file per side, the same as for a blueprint written in plain JavaScript. Those `lib/`\nmodules are build input only and are not stored, and `.d.ts` files are dropped. The bundled Docs,\nSheets and Slides blueprints are written this way, each with a `lib/protocol.ts` holding the types\nits client and server share (imported type-only, so nothing of it ships).\n\nEverything else under `files/` (the README, assets) passes through unchanged, and may be imported\nfor its contents where the bundler can inline it: JSON is; a stylesheet is not, and\n`import \"./styles.css\"` fails the build (a gadget carries its CSS in the module that injects it). A file a bundle inlined is still shipped, because\nonly TypeScript is build input. A blueprint is written in TypeScript or in JavaScript, not both: a\n`.js` module in a tree that holds `.ts` is rejected, since it would ship as written beside bundles\nit cannot share code with. Non-module files pass through either way.\n\n`cloudflare:workers` is the only import left for the runtime to resolve, and only on the server:\nthe client is loaded as an ES module in a sandboxed iframe with nothing to resolve a bare import\nagainst, and the server as a Durable Object whose module map holds the gadget's own files and whose\nloader supplies no other `cloudflare:` module. Everything else a blueprint imports must be a file it\nowns or a library, so `import \"yjs\"` is a build error rather than a module that goes missing inside\nthe sandbox, and tree-shaking annotations are ignored, so a `\"sideEffects\": false` in an enclosing\npackage.json cannot drop a side-effect-only import from the bundle.\n\nThe build rejects a tree that would otherwise ship something other than what was written: a\nJavaScript module in a TypeScript blueprint, a `package.json` in a TypeScript blueprint (its `browser`\nfield or `imports` map would steer the bundler's resolution), an import of one of the blueprint's\nmodules that the bundler resolved to something other than the module TypeScript resolves it to (a\n`package.json` above the blueprint steering it, or an extensionless file the bundler takes first), a\n`.ts` file outside the entry/`lib/`\nlayout, TypeScript spelled `.tsx`/`.mts`/`.cts`, declarations included (neither runtime has a loader\nfor it), a `lib/` module\nno entry imports, an import that reaches outside `files/` by any path other than a library's exported\nsubpath (a relative or absolute path into `libraries/`, a `src/` module, the package root, a bare\nspecifier some `node_modules` resolves), a library import of the wrong side or of a library that does\nnot exist, a\ndynamic `import()` or `require()` of anything but a string literal, refused before the bundler runs\n(it would leave a computed path unchecked, and expand a template literal or concatenation into every\nfile the pattern matches, wherever that reaches), a module that binds the name `require` (the scan\nreads a bare `require(...)` as the module loader, as the bundler does only while the name is\nunbound), a generated `client.js`/`server.js` that collides\nwith a file or directory already in the tree, or a shipped JavaScript module that imports a library,\nwhich only the bundle can inline. Imports are read from each module's syntax tree with the\nTypeScript compiler, so a comment or a string can neither masquerade as one nor hide one.\n\n### Type checks and tests\n\n```\npnpm exec vp run -F @gadgets/bundled-blueprints build # the five type-check programs\npnpm --filter @gadgets/bundled-blueprints test:run # the blueprints', libraries' and build's tests\npnpm --filter @gadgets/bundled-blueprints test:watch\n```\n\n`pnpm build` type-checks all of it, through one config per set of globals -- the sets must not see\neach other, since a Durable Object has no `document`, iframe code cannot import\n`cloudflare:workers`, and neither has Node's `fs`:\n\n| config | covers | globals |\n| --- | --- | --- |\n| `tsconfig.client.json` | every `client.ts` (blueprints and libraries) and what it imports | DOM |\n| `tsconfig.server.json` | every `server.ts` and what it imports | Workers |\n| `tsconfig.tests.json` | the blueprints' and libraries' `__tests__/` and what they import | DOM + Node |\n| `tsconfig.server-tests.json` | `__tests__/server.test.ts` and `__tests__/*.server.test.ts`, the tests of a server side | Workers + Node |\n| `tsconfig.node.json` | `src/` and `__tests__/`, the build and its tests | Node |\n\nEach follows its entries' imports, so a `lib/` or `src/` module is checked under the globals of\nwhichever side imports it, and a module both sides import under both -- which is what keeps a\nshared module honest without forcing a server-only one to compile against the DOM. A library import\nis this package referring to itself by name, which tsc resolves through the `exports` in\n`package.json` with no `paths` block, so a blueprint is checked against the real signatures it\nimports.\n\n### What the build does not check\n\nThe bundler and the type check are kept in step by refusing what would let them diverge, not by\nsupporting every way TypeScript can be written. Write a blueprint the plain way -- `.ts` modules\nunder `files/`, relative imports spelled `./name.ts` or `./lib/name.ts`, libraries by the package\nsubpath -- and stay inside these limits, which the build does not enforce:\n\n- A `/// `, `lib=\"…\"` or `path=\"…\"` directive loads types the side's tsconfig\n deliberately leaves out (`types: []`, one `lib` per side), so `Buffer` type-checks in a client and\n ships as a free global that throws in the iframe. Do not write one: a gadget module sees exactly\n the globals its runtime supplies, and the type check is only as honest as that isolation.\n- A tree under `BUNDLED_BLUEPRINTS_DIR` is bundled but not type-checked; the programs above cover\n this package's `blueprints/` and `libraries/` only. Type-check such a tree in its own workspace.\n- The comment naming each inlined library module is rewritten line by line, so the bundle is the\n same wherever it is built; a template literal whose own line spells exactly such a path would be\n rewritten with it.\n\nUnit tests of a blueprint's `lib/` modules, or of its server, live in the blueprint's `__tests__/`\nand run under `pnpm test` (jsdom by default; a pure module's or a server's test declares\n`// @vitest-environment node`). They import the module under test by on-disk name, e.g.\n`../files/lib/protocol.ts`, and load a fixture with `readFileSync`. A test of the server side is\nnamed `server.test.ts` or `.server.test.ts`, which is what puts it under the Workers types\nrather than the DOM's; at run time it gets `cloudflare:workers` as a stub of its base classes\n(`__tests__/stubs/cloudflare-workers.ts`), so a Durable Object can be constructed over in-memory\nstorage. The blueprints the build produces are still installed and inspected inside workerd by the\nWorkshop backend's suite. Only `blueprint.json` and `files/` are read by the build, so `__tests__/`\n(and anything else beside them) is repo-only and never part of the blueprint.\n\n`blueprintId` is the install key. Never change it after deployment: the new ID would install a\nsecond blueprint while the old one remained. (TODO: the bundled IDs keep the historical `format.`\nprefix -- `format.document`, `format.spreadsheet`, `format.slides` -- for that reason; renaming them\nneeds an install-time migration keyed on the old id.) `version` is the blueprint's published content\nversion, a counter for display: the content itself is stored under the commit of its files. The\nbuild fingerprints the files and the rest of the manifest, so direct edits under `files/` reinstall\nautomatically. `revision` remains an explicit reinstall trigger and is bumped by the importer.\n\n## Editing presentation\n\nEdit `blueprint.json` and rebuild. Changes to title, description, output, or author are included in\nthe install fingerprint and do not need a `revision` bump.\n\n## Updating code\n\nBuild the blueprint in a Workshop, export it, then import the export, from `packages/workshop-backend`:\n\n```\npnpm import:bundled-blueprint ~/Downloads/Gadgets-Doc-v4.gadget format.document\n```\n\nThe importer replaces `files/` and leaves anything beside `blueprint.json` and `files/` alone,\nupdates archive-owned metadata (`created`, `version`, `lastUpdated`, and `bindings`), bumps\n`revision`, rebuilds the backend's `src/generated/bundled-blueprints.ts`, and reports changed files\nand bindings. An export the build rejects is refused before it replaces\nanything. Review the resulting source diff normally.\n\nAn export is a `.gadget` archive in one of two versions, and the importer reads both. Version 1\nholds a snapshot of the blueprint's files. Version 2, which a Workshop writes for anything published\nsince blueprints became git commits, holds a git packfile, and the importer has `git` unpack it.\nOnly the files are taken from either: the bundled blueprint's commit is made from them at install,\nnot copied from the export.\n\nAn export contains the bundled JavaScript, so importing one over a TypeScript blueprint replaces its\nsources with the built `client.js` / `server.js`. Edit a TypeScript blueprint in the repo instead,\nand use the Workshop only to try the result.\n\n## Adding a format\n\n```\npnpm import:bundled-blueprint ~/Downloads/Brief.gadget --new acme-brief\n```\n\nThis extracts the files and writes a valid scaffolded `blueprint.json`. Before deploying, replace\nthe scaffold description and review `output`. Prefer a generic `output.id` such as `document`; the\nOutputs page uses it to group related formats.\n\n## Shipping your own formats\n\n`BUNDLED_BLUEPRINTS_DIR` points the build at another directory in this same extracted layout. It is\nresolved against `packages/workshop-backend`, where the build runs (the variable used to be called\n`FORMAT_BLUEPRINTS_DIR`; that name is no longer read, so a deployment setting it builds the bundled\nset instead):\n\n```\nBUNDLED_BLUEPRINTS_DIR=../../acme-formats pnpm exec vp run build\n```\n\nThe named directory replaces this set rather than extending it. It can be empty to ship no bundled\nformats. The import command honors the same variable. Keeping deployment-owned formats outside this\nrepo avoids modifying it when it is consumed as a submodule.\n\nA `BUNDLED_BLUEPRINTS_DIR` tree may be written in TypeScript like the blueprints here, and the build\nbundles it the same way: a syntax error or an import that does not resolve fails the build, and it\nimports the gadget libraries by the same package name, which the build resolves to this package's\n`libraries/` without the tree having installed anything. It is not type-checked, though. This\npackage's `tsconfig.*.json` programs are static and cover only `blueprints/` and `libraries/`, so a\ntree elsewhere needs its own `tsc` run in the repository that owns it, with\n`@gadgets/bundled-blueprints` linked into that workspace the way `@gadgets/scripts` already must\nbe, so its editor and `tsc` resolve the same `exports`; or it can stay JavaScript.\n\nDirectories using the previous `.gadget` plus `.json` layout remain supported, so an\nexisting deployment can update this repo without coordinating a format conversion. Importing a new\nexport into one of those entries migrates that pair to the extracted layout automatically. That is\nalso the only way to update one: the layout holds version 1 archives, and the build refuses a\nversion 2 export dropped in a `.gadget`'s place.\n\nAdministrators can also publish and promote ordinary blueprints at runtime instead of rebuilding a\ndeployment.\n","packages/bundled-blueprints/blueprints/workspace-docs/files/README.md":"# Docs — real-time collaborative rich-text Gadget\n\nA single-document, Google-Docs-style rich-text editor with Durable Object persistence, live block updates, collaborator presence, and conflict-safe concurrent editing.\n\n## Shared libraries\n\nThis blueprint is built on the shared gadget libraries in `packages/bundled-blueprints/libraries`\n(see that directory's README). The build inlines what it imports into the `client.js` and `server.js` it ships,\nso a gadget created from it carries its own copy of the libraries as of its creation.\n\n- `@gadgets/bundled-blueprints/libraries/ui/client` draws the chrome: the `el` element builder, the shared icon table, the\n toolbar's buttons, groups, colour pickers and dropdown, the in-page prompt that stands in for the\n sandbox's blocked `window.prompt`, the save-status dot, and the reading and downscaling of a\n picked, dropped or pasted image.\n- `@gadgets/bundled-blueprints/libraries/sync/client` runs the browser's half of the collaboration loop: the debounced,\n serialized, retrying save scheduler, the presence roster and its throttled reporter, and the\n `RpcTarget` the server calls back.\n- `@gadgets/bundled-blueprints/libraries/sync/server` runs the object's half: the mutation queue, the subscriber registry with its\n presence announcements, and the per-block optimistic concurrency.\n\nEverything on top of them is this gadget's own: the editing commands, the paste sanitizer, the block\nmodel and its ordering rule, where a remote caret is drawn, and the export formats.\n\nIn the repository the source is TypeScript under `blueprints/workspace-docs/files/` (`client.ts`,\n`server.ts`, the shared `lib/protocol.ts` contract and the `lib/markdown.ts` export), which the build\nbundles into the `client.js` and `server.js` this gadget runs.\n\n## Architecture\n\n- **server.js** is the authoritative collaboration coordinator. It stores one atomic `document:v2` snapshot containing the title, global revision, ordered blocks, per-block versions, and modification time.\n- **client.js** builds the entire UI around a `contenteditable` surface. Every top-level document element has a stable `data-block-id`. Local typing is optimistic and changed blocks are sent after a short ~220 ms debounce.\n- Clients subscribe with a Cap'n Web `RpcTarget`. The server broadcasts accepted block operations and ephemeral presence events to every connected client.\n\n## Real-time data model\n\nThe persisted document resembles:\n\n```js\n{\n revision: 42,\n title: \"Project plan\",\n blocks: [\n { id: \"b_…\", html: \"

Project plan

\", version: 3 },\n { id: \"b_…\", html: \"

Draft…

\", version: 8 }\n ],\n lastModified: 1700000000000\n}\n```\n\nClients send compact operation batches containing only changed/upserted blocks, version-checked deletions, the current block order, and title. The Durable Object:\n\n1. checks each changed block's `baseVersion`;\n2. accepts non-conflicting changes;\n3. increments accepted block versions and the document revision;\n4. persists the resulting authoritative snapshot; and\n5. broadcasts only the accepted operation.\n\nA remote operation patches only affected DOM blocks. The whole editor is not replaced, so typing and selection in unrelated paragraphs remain stable. Ordering is last-writer-wins, while content and deletion changes use per-block optimistic concurrency.\n\n### Same-block concurrency\n\nA remote update to the block currently being edited is queued rather than replacing the user's caret and draft. If the local block is clean on blur, the remote version is applied. If it is locally dirty, the draft is rebased onto the latest server block version and saved as the next version. Server conflicts return the authoritative block/version, and the client automatically retries its visible local draft—no local text is silently discarded.\n\nThis is block-granularity collaboration rather than a character-level CRDT. It provides smooth simultaneous editing across paragraphs with much less complexity. A CRDT/OT layer would still be required for merged character-by-character edits by multiple people inside the exact same paragraph.\n\n## Presence\n\nSelection changes are throttled to ~70 ms and sent as ephemeral presence messages containing collaborator ID, name, color, and anchor/focus block-and-text offsets. Presence is never persisted. A collaborator appears as a slim named caret; selected text is shown with a subtle translucent highlight, including selections spanning multiple blocks. Both are rendered in a fixed overlay without modifying document HTML. There are no header avatars or active-block outlines. Page close uses a best-effort leave message, RPC disconnects broadcast leave events, and client heartbeats expire stale cursors when browsers do not complete unload networking.\n\nRemote carets and selection highlights live in a separate overlay, so presence decoration never enters the editable DOM or persisted document HTML. Serialization also strips transient local image-selection decoration.\n\n## Programmatic population and backward compatibility\n\nAgents and importers should call `setDocument({ title, blocks, senderId })` to populate or replace the document atomically. It works whether the editor has already been opened or not, persists the full snapshot, increments the revision, and broadcasts the result to connected clients. This avoids requiring callers to choose between initialization and incremental operations.\n\n`initializeBlocks()` remains the idempotent bootstrap/migration API. It also handles the startup race where a newly opened browser creates an empty revision-1 shell just before generated content arrives: that exact untouched shell can be replaced by a non-empty initialization payload. It will not overwrite later empty documents, which may represent an intentional user edit.\n\nIf only the former `content`, `title`, and `lastModified` KV keys exist, the first v2 client loads that HTML, normalizes its top-level nodes, assigns stable block IDs, and calls `initializeBlocks()`. Existing documents therefore migrate without data loss.\n\n## Formatting and media\n\nThe toolbar supports paragraph styles, font family/size, bold, italic, underline, strikethrough, text/highlight color, alignment, lists, indentation, links, images, horizontal rules, clear formatting, and undo/redo. Font sizes are in points, as in Google Docs and Word: body text is 12 pt, in the editor and in the HTML and PDF exports alike, so a sized run keeps its proportion to the text around it.\n\nPasted Google Docs/Word HTML is rebuilt into clean semantic markup. Images from file selection, drag/drop, and clipboard are downscaled and embedded as data URLs. Because collaboration transmits changed blocks, an embedded image is no longer resent when unrelated paragraphs change. A future asset store could replace data URLs with image IDs if very large media-heavy documents are needed.\n\n## Implementation notes\n\n- Durable Object storage is the source of truth; in-memory subscriber and presence maps are intentionally ephemeral.\n- Structural DOM normalization handles root text and `
` nodes and repairs duplicate/missing block IDs.\n- Remote ordering moves only blocks that are out of place, avoiding unnecessary selection disruption.\n- `execCommand` is deprecated but remains the compact, broadly compatible formatting mechanism for this sandboxed editor.\n\n## Export formats\n\n- **Markdown** exports the persisted rich-text blocks as Markdown, preserving headings, bold,\n italic, strikethrough (whether written as tags or as the inline styles the toolbar applies, with\n an inline style overriding its tag and its ancestors, as on the page), links, images, lists,\n block quotes, code, horizontal rules and line breaks. A paragraph whose emphasis changes inside\n a word, where Markdown's asterisks could pair differently than written, writes its emphasis as\n inline ``, `` and `` tags instead. Markdown has no syntax for underline,\n colour, size, font or alignment, so those runs export as plain text. An image exports with its\n `src`, which for an embedded image is its whole data URL.\n- **HTML** and **PDF** use the editor's print layout and omit editing chrome and presence UI.\n","packages/bundled-blueprints/blueprints/workspace-sheets/files/README.md":"# Sheets\n\nA lightweight, persistent spreadsheet Gadget with a familiar grid interface, formulas, formatting, multiple sheets, and live synchronization.\n\n## Features\n\n- Editable spreadsheet title and multiple sheet tabs\n- Add, rename, duplicate, and delete sheets\n- Cell and range selection with keyboard navigation\n- Formula bar and A1-style references\n- Cross-sheet references such as `Sheet2!A1` and `'Sales Data'!B4`\n- 100+ spreadsheet functions across math, statistics, logic, text, lookup, date/time, and information categories\n- Number, currency, percent, scientific, date, and time formatting\n- Bold, italic, underline, strikethrough, text color, fill color, alignment, and wrapping\n- Row and column insertion, deletion, and resizing\n- Range sorting, AutoSum, copy/paste via TSV, and local undo/redo for cell edits\n- Automatic persistent saving with optimistic per-cell conflict detection\n- Real-time operation and presence synchronization in the server architecture\n- Excel workbook and per-sheet CSV export\n\n## Using the spreadsheet\n\n- Click a cell to select it.\n- Double-click a cell, press **F2**, or begin typing to edit it.\n- Start formulas with `=`, for example:\n - `=SUM(A1:A10)`\n - `=IF(B2>100,\"High\",\"Low\")`\n - `=VLOOKUP(E2,A2:C20,3,FALSE)`\n - `=Sheet2!A1*2`\n- Use the name box to jump to a cell or range such as `D12` or `A1:C8`.\n- Right-click the grid for cut/copy/paste and row or column actions.\n- Double-click a sheet tab to rename it; right-click it to duplicate or delete it.\n\n## Keyboard shortcuts\n\n| Shortcut | Action |\n| --- | --- |\n| Arrow keys | Move the active cell |\n| Shift + Arrow | Extend the selection |\n| Enter / F2 | Edit the active cell |\n| Tab / Shift + Tab | Move right / left |\n| Delete / Backspace | Clear selected cells |\n| Ctrl/Cmd + C, X, V | Copy, cut, paste |\n| Ctrl/Cmd + Z | Undo |\n| Ctrl/Cmd + Y or Ctrl/Cmd + Shift + Z | Redo |\n| Ctrl/Cmd + B | Bold |\n| Ctrl/Cmd + I | Italic |\n| Ctrl/Cmd + U | Underline |\n| Ctrl/Cmd + A | Select the whole sheet |\n| Ctrl/Cmd + Arrow | Jump across populated or empty regions |\n| Alt + Enter | Insert a line break while editing |\n\n## Programmatic population\n\nThe spreadsheet can be read and populated through the Gadget's server RPC methods. This is useful for scripts, agents, migrations, or seeding a workbook without using the grid UI.\n\n### Read the workbook\n\nCall `getDocument()` to retrieve the complete persisted workbook:\n\n```js\nconst doc = await gadget.getDocument();\n```\n\nThe returned object contains `revision`, `title`, `sheetOrder`, `sheets`, `cells`, and `lastModified`. Cells are grouped by sheet ID and keyed by A1 reference:\n\n```js\nconst firstSheetId = doc.sheetOrder[0];\nconst a1 = doc.cells[firstSheetId].A1;\n// { value: \"Revenue\", fmt: { b: true }, version: 1 }\n```\n\n### Write cells\n\nUse `applyOperation()` with per-cell operations. For a new cell, use `baseVersion: 0`; when replacing or deleting an existing cell, use its current `version` from `getDocument()`.\n\n```js\nconst doc = await gadget.getDocument();\nconst sheetId = doc.sheetOrder[0];\nconst cells = doc.cells[sheetId];\n\nconst result = await gadget.applyOperation({\n senderId: \"seed-script\",\n cellOps: [\n {\n sheetId,\n ref: \"A1\",\n value: \"Revenue\",\n fmt: { b: true, bg: \"#fff3a3\" },\n baseVersion: cells.A1?.version ?? 0,\n },\n {\n sheetId,\n ref: \"B1\",\n value: \"=SUM(B2:B10)\",\n fmt: { nf: \"currency\", d: 2 },\n baseVersion: cells.B1?.version ?? 0,\n },\n ],\n});\n```\n\nA cell's `value` is always stored as text. Begin a value with `=` to create a formula. To delete a cell completely, send both `value: null` and `fmt: null` with the current `baseVersion`.\n\nCheck `result.status` after writing. It is `applied`, `unchanged`, or `conflict`. On a conflict, inspect `result.conflicts`, re-read the document, and retry against the latest cell versions rather than overwriting blindly.\n\n### Replace a whole sheet\n\nFor bulk imports, `sheetReplacements` is more efficient than sending many individual cell operations:\n\n```js\nawait gadget.applyOperation({\n senderId: \"csv-import\",\n sheetReplacements: [{\n sheetId,\n cells: {\n A1: { value: \"Name\", fmt: { b: true }, version: 1 },\n B1: { value: \"Total\", fmt: { b: true }, version: 1 },\n A2: { value: \"Example\", fmt: null, version: 1 },\n B2: { value: \"1250\", fmt: { nf: \"currency\", d: 2 }, version: 1 },\n },\n }],\n});\n```\n\nA whole-sheet replacement overwrites that sheet's complete cell map, so merge with existing data first if it must be preserved. It does not use per-cell conflict checks.\n\n### Change workbook structure\n\nPass a complete structure snapshot to change the title, sheet order, names, dimensions, or sizing metadata. Because structure uses last-writer-wins semantics, start with the latest document and preserve every sheet that should remain:\n\n```js\nconst doc = await gadget.getDocument();\nconst sheetId = doc.sheetOrder[0];\n\nawait gadget.applyOperation({\n senderId: \"setup-script\",\n structure: {\n title: \"Quarterly plan\",\n sheetOrder: doc.sheetOrder,\n sheets: {\n ...doc.sheets,\n [sheetId]: {\n ...doc.sheets[sheetId],\n name: \"Summary\",\n colWidths: { ...doc.sheets[sheetId].colWidths, 0: 180 },\n },\n },\n },\n});\n```\n\nOmitting an existing sheet from `sheetOrder` deletes it and its stored cells. Adding a new sheet ID creates empty storage for it. When adding a sheet and its initial data together, include both `structure` and a matching `sheetReplacements` entry in the same operation.\n\nFormatting keys accepted by the server are `b` (bold), `i` (italic), `u` (underline), `s` (strikethrough), `c` (text color), `bg` (fill color), `a` (`l`, `c`, or `r` alignment), `nf` (number format), `d` (decimal places), `fs` (font size), and `wrap`. Colors must be hexadecimal strings such as `#1d1d20`.\n\n## Architecture\n\nBoth sides are built on the shared gadget libraries in `packages/bundled-blueprints/libraries`, which the build\ninlines into the `client.js` and `server.js` it ships.\n\n`@gadgets/bundled-blueprints/libraries/ui/client` draws the chrome: the element builder, the shared\ntoolbar icons and controls (icon and segment buttons, groups, colour pickers, the dropdown behind the\nnumber-format menu), the in-page prompt that stands in for the `window.prompt` the sandbox blocks,\nand the save-status dot. `@gadgets/bundled-blueprints/libraries/sync/client` and `.../sync/server` are the\ncollaboration loop: the debounced, serialized, retrying save scheduler, the presence roster and\nheartbeat, the subscriber object the server calls back on, and in the Durable Object the mutation\nqueue and the subscriber registry with its presence announcements (whose broadcasts are never\nawaited, so a callback may re-enter the queue). `@gadgets/bundled-blueprints/libraries/zip/server`\nprovides the streaming ZIP writer used by XLSX export. The cell model, the formula engine, the grid,\nsheet tabs and the export-specific code are this gadget's own.\n\nIn the repository the source is TypeScript under `blueprints/workspace-sheets/files/`\n(`client.ts`, `server.ts`, `lib/protocol.ts`, `lib/formula.ts`, `lib/xlsx.ts`), which the build bundles\ninto the `client.js` and `server.js` shipped here.\n\n### `client.js`\n\nBuilds the entire browser interface in JavaScript. It contains:\n\n- Grid rendering and selection behavior\n- Cell editing, formatting, sorting, and structural operations\n- Formula tokenization, parsing, evaluation, and display formatting\n- Clipboard and keyboard support\n- A local model whose saves are queued per cell and flushed by the library's scheduler\n- RPC callbacks for live server operations and presence events\n\nFormula evaluation happens in the browser. The engine caches computed cells, detects circular references, supports ranges and cross-sheet references, and displays standard errors including `#DIV/0!`, `#VALUE!`, `#REF!`, `#NAME?`, `#N/A`, `#NUM!`, and `#CYCLE!`.\n\n### `server.js`\n\nExports the Durable Object class `Gadget`, which is the authoritative persistence and synchronization layer. It:\n\n- Stores spreadsheet metadata and each sheet's cells in Durable Object storage\n- Serializes mutations and document snapshots through the library's mutation queue\n- Applies per-cell optimistic concurrency using cell versions\n- Uses last-writer-wins semantics for document structure\n- Broadcasts operations and presence events through the library's subscriber registry after the queue releases, best-effort and without awaiting them, so a callback may itself read or write the document and a hung subscriber holds up only its own client\n- Sanitizes titles, dimensions, cell contents, references, and formatting\n- Advertises and produces the server-side workbook and CSV exports\n\n### XLSX and ZIP modules (bundled into `server.js`)\n\nThe XLSX module converts a complete document snapshot into a streaming XLSX workbook: sparse\nworksheet XML with inline strings, deduplicated styles, and frozen panes. The ZIP module is a\ndependency-free streaming ZIP writer (raw DEFLATE via `CompressionStream`, incremental CRC32, data\ndescriptors). Both are bundled into `server.js`.\n\n## Storage model\n\nThe server stores:\n\n- `meta`: revision, title, sheet order, sheet metadata, and modification time\n- `cells:`: a map of A1 references to `{ value, fmt, version }`\n\nDefault sheets have 100 rows and 26 columns. Server validation permits up to 50,000 rows and 702 columns per sheet. Cell values are limited to 8,192 characters, and titles are limited to 200 characters.\n\n## Collaboration notes\n\nThe server and client synchronization code support multiple connected clients and live updates. Each\ntab introduces itself with the guest name and colour the sync library derives from its client ID, and\nreports its selected range on the library's throttle and heartbeat. Remote collaborator badges and\nselection overlays are currently disabled in the UI, so the app presents as a single-user spreadsheet\neven though remote operations still synchronize.\n\n## Current limitations\n\n- There is no file import workflow; clipboard operations use tab-separated text.\n- Structural edits and sorting clear local undo/redo history.\n- Formula reference adjustment during row/column changes is limited to references on the current sheet.\n- Formula support is broad but is not intended to be fully compatible with Excel or Google Sheets.\n- Frozen row/column metadata exists in the model, but the current UI does not expose controls for it.\n\n## CSV export\n\nUp to 31 worksheets are exposed as individual **CSV** export options, leaving one of the platform's\n32 format slots for XLSX. CSV files contain the stored cell values through the worksheet's used\nrange. Formula cells are exported as their raw formulas (for example, `=SUM(A1:A10)`), not as\nbrowser-computed display values. Fields use standard CSV quoting and CRLF line endings.\n\n## XLSX export\n\n**Excel Workbook** exports one XLSX file with the worksheets in workbook order. Cells keep their\nfont, color, fill, alignment, number format, decimal places and wrapping; sheets keep column widths,\nrow heights and frozen panes. Pixel sizes are converted to points (rows, fonts) or approximate\ncharacter widths (columns), so layout is close but not pixel-identical.\n\nCell values follow the grid's own literal rules: a leading apostrophe forces text, a leading `=` is\na formula (whatever the number format), `TRUE`/`FALSE` are booleans, and numbers may carry a sign,\ncommas, a leading `$` or a trailing `%`. Everything else is text; date-looking text is not parsed.\n\nFormulas are written without cached results and the workbook requests a full recalculation on open,\nso Excel evaluates them itself. To keep them valid there, the exporter rewrites cross-sheet\nreferences to the exported worksheet names, prefixes OOXML \"future functions\" (`IFS`, `CONCAT`, ...)\nwith `_xlfn.`, renames `ERRORTYPE()` to `ERROR.TYPE()`, and drops whitespace between a function\nname and its `(`. A formula that is empty, structurally unbalanced (unterminated string or quoted\nname, mismatched parentheses or brackets — the grid's parser tolerates these) or that would exceed\nExcel's 8,192-character limit after rewriting is exported as text, since one such formula makes\nExcel report the whole workbook as damaged. Formula semantics are otherwise not translated (for\nexample `^` associativity differs, and a reference outside the grid such as `XFE1` is empty here\nbut `#NAME?` in Excel), and compatibility with Excel is not claimed beyond this.\n\nWorksheet names are made Excel-safe: invalid characters become `_`, blank names become `Sheet`,\nnames are cut to 31 characters, and case-insensitive collisions get ` (2)`, ` (3)`, ... suffixes.\nReferences resolve to the first worksheet with a matching source name, as in the grid.\n\nFilters, charts, comments and pivot tables are not exported; cells already materialized from them\nexport as ordinary values.\n","packages/bundled-blueprints/blueprints/workspace-slides/files/README.md":"# Workspace Slides\n\nA composable, multiplayer slide deck builder. The deck itself is data —\nslides are arrays of typed blocks — and the editor lets anyone add, remove,\nreorder, and edit slides in real time. The visual language (tokens,\ncomponents, typography) is shared across every block. Edit mode uses light,\nneutral sidebars so the slide canvas remains the visual focus.\n\n## Files\n\n- `server.js` — Durable Object that owns the deck document and broadcasts\n every mutation to connected viewers. The server is a generic store; it\n doesn't know what any component does.\n- `client.js` — Design tokens, the component registry, slide renderer,\n block interactions (drag, resize, inline text edit), and the builder\n shell (slide list, inspector, palette, control bar, present mode).\n\nIn the repository these two modules are TypeScript (`client.ts`, `server.ts`\nand the shared `lib/protocol.ts` types under\n`blueprints/workspace-slides/files/`), which the build bundles into the\n`client.js` and `server.js` installed here.\n\n## Gadget libraries\n\nThree pieces of this deck are not its own: the element builder, the two\nsteps that read an uploaded image, and the object the Durable Object calls\nback. They are shared with the other document-style gadgets and are\nimported from the libraries in `packages/bundled-blueprints/libraries`, which the build\ninlines into the two files installed here:\n\n```ts\nimport { el, loadImage, readFileAsDataURL } from \"@gadgets/bundled-blueprints/libraries/ui/client\";\nimport { createSubscriber } from \"@gadgets/bundled-blueprints/libraries/sync/client\"; // client.ts\nimport { SubscriberRegistry } from \"@gadgets/bundled-blueprints/libraries/sync/server\"; // server.ts\n```\n\n- **`ui`** — `el(tag, props, children)` builds every element in\n `client.js`; `readFileAsDataURL` and `loadImage` are the two halves of\n `fileToImageDataURL`, whose encoding rule (SVG verbatim, PNG kept as PNG,\n the original on any canvas failure) stays here because it is the deck's.\n The library's own icons, toolbar controls and prompt are for the gadgets\n with a formatting bar; this deck draws its own `ICONS` as complete SVGs\n and has no toolbar of that shape, so it imports none of them.\n- **`sync`** — `createSubscriber(RpcTarget, { deckChanged })` builds the\n callback target (the RPC layer only calls prototype methods, which is\n what the library gets right), and `SubscriberRegistry` holds the\n connected browsers in the Durable Object. A deck has no presence — every\n viewer sees the same slides and no cursors are shared — so the registry\n is built with no presence hooks and is a plain fan-out.\n\nEverything else here — the tokens, the `COMPONENTS` registry, the layout and\nsnapping code, the deck document and its undo history — is this blueprint's.\n\n## Slide formats\n\nThe deck is built in a clean, **branded corporate style** (an orange accent\npalette on white slides) and supports two ready-made slide formats. Both live on the fixed\n`1200 × 675` reference canvas and are made entirely of normal editable\nblocks, so anything a template drops in can be moved, restyled, or deleted\nafterward.\n\n### 1. Title / cover slide (`makeTitleSlide()` in `client.js`)\n\nThe orange opening slide.\n\n- Full-bleed orange cover artwork (`background.coverOrange`).\n- White brand **logo** (a clean editable wordmark with an optional accent\n dot) at `x 36, y 56`, width `267`.\n- **Title** — Inter, white, ~58px, weight 700, at `x 33, y 197`, width\n `687`. Kept in the left portion of the slide, max three lines.\n- **Subtitle** — Inter, white, ~17px, weight 600, at `x 36, y 533`, width\n `553`, max two lines. Delete the block if no subtitle is needed.\n\nThis is also what the seed deck's first slide and the server's\n`newBlankSlide()` produce.\n\n### 2. Basic content slide (`makeContentSlide()` in `client.js`)\n\nThe standard white content shell for every non-cover idea.\n\n- Pure white background, no inset surface, no shadow, no border.\n- **Eyebrow** (`sectionLabel`) — Ruby `#FF6633`, uppercase, SemiBold, at\n `x 36, y 35`. Optional; delete when not useful. Eyebrows are always Ruby.\n- **Headline** (`title`) — black `#000000`, ~28px, weight 600, at\n `x 35, y 76`, width `984`, max two lines, written as an assertion.\n- **Logo** — the brand wordmark (the `logo` component in its `dark`\n variant: black wordmark + orange accent dot), at `x 1013, y 40`, sized\n via `scale: 0.62`.\n- **Content region** — body starts at `x 36, y 204`. The default narrative\n uses a constrained `760px` reading measure at 19px, weight 400,\n line-height 1.6. The add-slide controls also provide exact-grid\n **2-column** (`x 36/609`, `w 553`) and **4-column**\n (`x 34/328/622/916`, `w 260`) compliant structures.\n- **Bottom brand bar** — full-width 12px Tangerine `shape` at `y 663`, touching the bottom edge.\n\n### Creating slides in either format\n\n- **In the editor:** enter edit mode (**E**). The left panel footer has\n two buttons — **Title** and **Content** — that insert the matching\n template after the current slide. Each calls\n `addSlide(makeTitleSlide())` / `addSlide(makeContentSlide())`.\n- **Programmatically (over the `GADGET` binding):** call\n `addSlide(atIndex, slideObject)` with a `{ background, blocks }` object.\n The block/prop shapes in `makeTitleSlide` / `makeContentSlide` are the\n canonical reference for the two styles; the server mints block ids on\n insert.\n\nBrand style tokens worth reusing: Ruby `#FF6633`, Tangerine `#F6821F`,\nMango `#FBAD41`, black `#000000`, muted gray `#747474`, Inter throughout.\nSlide-facing component controls are intentionally limited to this palette\nand the approved 400/500/600/700 weights. Cards and diagram boxes default\nto flat white surfaces, thin `#E5E5E5` rules, minimal corner radii, and no\nshadows. Generic colored tones and the pill component are not offered in\nthe component library. The `bulletList` component implements the corporate\nhanging-indent treatment: one item per source line, 6px Tangerine dots,\n12px dot-to-copy gap, 19px primary or 17px compact Inter Regular text, and\ncontrolled 10px/8px item spacing.\n\n## Initial blueprint\n\nNew Gadget instances start from the current four-slide overview of the\nbuilder: the orange “Compose your deck or build with agent” cover, a six-part\nfeature overview, a connected-charts example showing how an agent can use an\napproved internal system of record as a data source, and a two-path get-started\nslide for editing directly or asking the agent. The complete blueprint\nis defined by `INITIAL_DECK` plus `KEY_TAKEAWAYS_SLIDE` in `server.js`; both\nfirst-time initialization and `resetAll()` clone that blueprint. The immutable default\nobjects in `server.js` are cloned whenever storage is first seeded and by\n`resetAll()`, so later edits cannot mutate the blueprint.\n\n## Data model\n\nThe deck is one JSON document:\n\n```js\n{\n slides: [\n {\n id: \"abcd1234\",\n background: { color: \"#f5f1eb\", inset: true, dotGrid: 0.45 },\n blocks: [\n { id: \"...\", type: \"title\", x: 48, y: 78, w: 1040,\n props: { text: \"Hello\", fontSize: 46, highlight: \"Hello\" } },\n ...\n ],\n },\n ...\n ],\n}\n```\n\nEvery block is `{ id, type, x, y, w?, h?, props }`. Position is in the\nfixed `1200 × 675` slide coordinate system; the stage scales uniformly to\nfit the viewport.\n\n## Component registry\n\n`COMPONENTS` in `client.js` is the catalog. Each entry declares:\n\n| field | purpose |\n| ---------------- | ------------------------------------------------------- |\n| `name` | Display name (palette + inspector header). |\n| `defaultBlock()` | Returns `{ x, y, w?, h?, props }` for a freshly added block. |\n| `fields` | Inspector schema (`text`, `multiline`, `number`, `select`, `checkbox`, `color`, `image`, `svg`). Set `advanced: true` on a field to tuck it under the inspector's \"Advanced\" disclosure (along with position/size). |\n| `resizableW/H` | Whether the corner handle adjusts that dimension. |\n| `fullBleed` | If true (arrow), the block ignores wrapper position and renders an absolutely-positioned overlay. |\n| `render(props, ctx)` | Returns the DOM. `ctx.inlineText(elem, propKey, transform?)` wires up contentEditable in edit mode. |\n\nComponents exposed in the palette (generic, reusable):\n\n`title`, `subtitle`, `text`, `sectionLabel`, `card`, `box`, `tonePill`,\n`image`, `svg`, `divider`, `shape`, `arrow`.\n\nComponents defined in `COMPONENTS` but intentionally **not** in the\npalette — they're brand marks used by the seed deck only:\n\n`gadgetsMark`, `logo`. The `logo` component renders a clean editable\nwordmark (`text` prop, default `Workspace`) with an optional orange accent\ndot (`accentDot` prop); change the wordmark to rebrand the deck. They still\nrender anywhere a block of that type appears; they just aren't offered as\nbuilding blocks.\n\n### Adding a new component\n\n1. Add a new entry to `COMPONENTS` with a `render`, `defaultBlock`, and\n `fields`. Use `ctx.inlineText(elem, \"propKey\")` for any text the user\n should be able to edit directly in the slide.\n2. Add the type to `PALETTE_ORDER` so it shows up in the library.\n3. Add the type to one of the `COMPONENT_CATEGORIES` groups, and add a\n short description to `COMP_DESC` plus a 14×14 currentColor SVG icon\n to `COMP_ICON`. (The library renders the icon + name + description as\n one row per component.)\n\nThat's it — no other code needs to change. The inspector is auto-generated\nfrom `fields`, drag/resize/selection all work automatically.\n\n## Editing\n\nPress **E** (or click the pencil) to enter edit mode. Edit mode reveals:\n\n- **Left panel** — a light, neutral sidebar with a **slide search** (matches\n any string value in any block's props), a scrollable thumbnail list,\n and a split **Add slide** control. The main action inserts the standard\n narrative slide; its caret menu offers title, narrative, 2-column, and\n 4-column layouts (see \"Slide formats\" above). Each row\n shows its slide\n number, the thumbnail, and a one-line label derived from the slide's\n first title (or subtitle / text). Click to jump, drag to reorder\n (disabled while filtering), hover to reveal duplicate/delete. Press\n Enter in the search box to jump to the first match; Escape clears.\n- **Right panel** — three stacked sections, in order:\n 1. **Component library** — a contained, filterable card. The search\n input doubles as the section title; type to filter (matches on\n name, description, and type id), Enter inserts the first match,\n Escape clears. Without a query, components are grouped by category\n (Text / Containers / Decoration / Diagram); with a query, results\n are flat. The list has its own internal scroll so the library\n never grows past ~280px tall.\n 2. **Slide** — compact background settings for the current slide\n (page color, dot grid opacity, inset toggle).\n 3. **Selected block inspector** — icon + name header, schema fields\n (label-on-the-left rows, multiline + color stack vertically),\n a 4-button icon row (duplicate, bring forward, send backward,\n delete), and an \"Advanced\" disclosure that holds position/size\n and any fields tagged `advanced: true`. When nothing is selected\n this is replaced by a quiet \"Nothing selected\" hint.\n- **Stage** — every block is selectable (hover dashes, click to select);\n drag the body to move, the bottom-right handle to resize. Text inside a\n block is contentEditable; press Enter or click away to save. While\n dragging, the block softly snaps when its left / right / center edges\n line up with another block's edges or center, or with the slide bounds\n / center; a thin orange guide line shows which alignment is locked.\n Hold **Alt / Option** while dragging to disable snapping entirely.\n\nPress **F** to enter presentation mode (chrome hidden, stage fills the\nviewport, no rounded corners). **Esc** or **F** exits.\n\n## Realtime\n\nEvery mutation is sent through RPC to the Durable Object and re-broadcast\nas a full deck snapshot via the subscriber callback. The callback signature\nis `deckChanged(deck, meta)` where `meta = { canUndo, canRedo }` reflects\nthe current server-side history state. The client preserves the currently-\nselected slide & block across updates when possible.\n\nThe registry behind `#broadcast` isolates subscribers from each other: one\nwhose call fails is dropped and its stub released rather than failing the\nmutation being broadcast, and so is one whose connection breaks.\n\n## Undo / redo\n\nThe undo stack lives on the server (in `Gadget`, in memory only — lost on\nDO restart, capped at `MAX_UNDO` entries). It's **global**: there's one\nshared history for the deck, and pressing undo rolls back the most recent\nmutation made by any connected client. Every call to `#save` snapshots\nthe previous deck onto the undo stack and clears the redo stack;\n`undo()` / `redo()` bypass `#save` (so they don't recurse) and broadcast\nthe restored deck through `#broadcast`. Clients learn whether undo/redo\nare currently available from the `meta` arg piggy-backed on every\nbroadcast, plus an initial `getUndoState()` call at boot.\n\n## Keyboard\n\n- `←` / `→` / `Space` / `PageUp` / `PageDown` — navigate slides\n- `Home` / `End` — first / last slide\n- `E` — toggle edit mode\n- `F` — toggle present mode\n- `Delete` / `Backspace` (edit mode) — delete the selected block\n- `Ctrl/Cmd + C` / `X` / `V` (edit mode) — copy / cut / paste the selected\n block. The clipboard is in-memory (per tab); paste inserts onto the\n *current* slide with a small position offset so the new block doesn't\n sit perfectly on top of its source, and the new block becomes selected.\n- `Ctrl/Cmd + D` (edit mode) — duplicate the selected block in place\n (same as the inspector's duplicate icon, doesn't touch the clipboard).\n- `Ctrl/Cmd + Z` — undo; `Ctrl/Cmd + Shift + Z` (or `Ctrl + Y`) — redo.\n Also available as two icon buttons in the floating control bar (only\n shown while in edit mode; the keyboard shortcuts work anywhere).\n- `Esc` — close jump menu, then deselect, then exit present mode\n\n## Motion\n\nAll UI motion uses a single `--ease` token\n(`cubic-bezier(0.23, 1, 0.32, 1)` — a strong ease-out) and a small\n`--ease-in-out`. Press feedback on buttons is handled with two CSS\nselectors registered in `mountShell`:\n\n- `[data-press]:active { transform: scale(0.97); }` — generic buttons.\n- `[data-icon-btn]:active { transform: scale(0.92); }` — pill icon\n buttons in the control bar.\n\nAdd either attribute to a button to get the right press feel for free.\nAvoid `transition: all`; always specify the exact properties so unrelated\nproperty changes don't accidentally animate.\n\n## Inspector form controls\n\nAll inspector inputs (text, number, select, textarea, checkbox, color)\nshare a small set of CSS classes defined in `mountShell`:\n\n- `.field-input` — the base look (subtle dark fill, transparent border,\n orange ring on focus). Applied to ``, `