feat(core): add lockfile-backed caplet catalog installs

.changeset/prebuilt-caplets-lockfile-update.md

@@ -0,0 +1,6 @@
+---
+"@caplets/core": minor
+"caplets": minor
+---
+
+Add lockfile-aware Caplet install, restore, and update workflows, including `caplets update`, JSON lifecycle output, remote-global catalog mutations, derived update risk checks, and new public catalog entries for browser, desktop, observability, and Google Workspace integrations.

CONCEPTS.md

@@ -8,6 +8,28 @@ Shared domain vocabulary for this project -- entities, named processes, and stat
 
 A configured capability surface that exposes a backend to agents through a stable handle, progressive wrapper tools, or direct tool operations.
 
+### Prebuilt Caplets Catalog
+
+The repo-owned collection of installable Caplet files under `caplets/`.
+
+The Prebuilt Caplets Catalog is curated as a Code Mode-first capability catalog, not a generic marketplace. Catalog entries should be install-ready when promoted, with setup, auth, validation, safety, and Project Binding metadata appropriate to the backend.
+
+Install-ready catalog entries have an explicit verification status, a reproducible validation path, and a named primary Code Mode workflow. Unverified entries may exist as drafts or recipes, but they do not count as install-ready catalog coverage.
+
+### Catalog-Grade Caplet
+
+A Caplet that is ready to live in the Prebuilt Caplets Catalog.
+
+Catalog-Grade Caplets include enough frontmatter, setup or verification guidance, auth handling, least-privilege scope notes, safety notes, Code Mode workflow guidance, and local/project/runtime metadata for agents to use them without rediscovering private assumptions from the author's environment.
+
+### Caplets Lockfile
+
+A `caplets.lock.json` file that records installed catalog Caplets, their source repository, source path, destination, tracked source channel, resolved revision when available, content hash, and portability status.
+
+Caplets Lockfiles let `caplets install`, no-argument install restore, and `caplets update` manage installed Caplets from recorded provenance rather than from copied files alone. Project installs use `./.caplets.lock.json`; global installs use the target machine's Caplets state directory.
+
+Caplets Lockfiles are share-safe and integrity-aware. They strip credential-bearing source URLs, prefer project-relative paths where possible, verify recorded content before restore, and fail closed when local-source entries are unavailable or marked non-portable.
+
 ### Namespace Shadowing Policy
 
 A Caplet shadowing policy where a local/upstream ID collision exposes both Caplets under qualified namespace IDs and removes the ambiguous bare ID.

README.md

@@ -55,6 +55,14 @@ Install a no-auth example Caplet and try it from your agent:
 caplets install spiritledsoftware/caplets osv
 ```
 
+Installs write a lockfile. Run `caplets install` with no source argument to restore the
+selected project or global lockfile, and run `caplets update` to refresh tracked Caplets:
+
+```sh
+caplets install
+caplets update osv
+```
+
 Or add Caplets manually to any MCP client:
 
 ```json

apps/docs/src/content/docs/install.mdx

@@ -31,6 +31,41 @@ caplets install spiritledsoftware/caplets osv
 `caplets setup` configures supported agent harnesses. The OSV Caplet is the recommended
 first install because it is public and does not require credentials.
 
+## Install lockfiles and updates
+
+Successful installs write a lockfile so the same Caplets can be restored or updated later.
+Project installs write `./.caplets.lock.json`. Global installs write
+`caplets.lock.json` under the Caplets state directory, such as
+`~/.local/state/caplets/caplets.lock.json` on Linux.
+
+Restore the Caplets recorded in the selected lockfile with no source argument:
+
+```sh
+caplets install
+caplets install --global
+```
+
+Update every tracked Caplet, or only named Caplets:
+
+```sh
+caplets update
+caplets update sentry github
+```
+
+Install, restore, and update refuse to overwrite local edits unless you pass `--force`.
+Use `--json` when a script needs per-entry statuses and machine-readable errors.
+
+For explicit remote catalog lifecycle operations, `--remote` targets the remote machine's
+global Caplets root and global lockfile:
+
+```sh
+caplets install --remote spiritledsoftware/caplets sentry
+caplets install --remote
+caplets update --remote sentry
+```
+
+Remote project install and update semantics are intentionally separate from this workflow.
+
 ## Manual MCP setup
 
 If your client does not support `caplets setup`, or if you are avoiding a global install,

caplets/ast-grep/CAPLET.md

@@ -6,6 +6,8 @@ tags:
   - mcp
   - code
   - search
+projectBinding:
+  required: true
 setup:
   commands:
     - label: Install ast-grep MCP
@@ -29,6 +31,8 @@ Use this Caplet to expose ast-grep's structural search, scan, rule testing, rewr
 
 The manifest uses the full `ast-grep-mcp` MCP server.
 
+Project Binding is required because ast-grep reads and may rewrite files in the attached repository. The bound root defines the workspace that search and rewrite operations are allowed to target.
+
 ## Setup
 
 This Caplet installs `ast-grep-mcp` globally with npm, then verifies the installed binary with

caplets/browser-use/CAPLET.md

@@ -0,0 +1,27 @@
+---
+# yaml-language-server: $schema=https://caplets.dev/caplet.schema.json
+name: Browser Use
+description: Drive a local Playwright browser through the Playwright MCP server for web inspection and browser workflows.
+tags:
+  - browser
+  - playwright
+  - mcp
+mcpServer:
+  command: npx
+  args:
+    - -y
+    - "@playwright/mcp@latest"
+    - --browser=chromium
+---
+
+# Browser Use
+
+Use this Caplet when an agent needs a local browser to inspect pages, gather current web context, or exercise browser-based workflows.
+
+## Setup
+
+Install Playwright browser dependencies for the runtime where this Caplet runs. If you need a specific browser executable or profile, create a private variant that uses environment variables such as `DEFAULT_BROWSER_EXECUTABLE_PATH` and `DEFAULT_BROWSER_USER_DATA_DIR`.
+
+## Safety
+
+This is a local-control Caplet. Browser actions can sign in, submit forms, trigger purchases, or change account data. Prefer navigation, reading, and screenshots first; review mutating interactions before execution.

caplets/computer-use/CAPLET.md

@@ -0,0 +1,24 @@
+---
+# yaml-language-server: $schema=https://caplets.dev/caplet.schema.json
+name: Computer Use
+description: Control local desktop applications and windows through open-computer-use for explicit desktop automation workflows.
+tags:
+  - computer-use
+  - desktop
+  - local-control
+shadowing: namespace
+mcpServer:
+  command: npx
+  args:
+    - -y
+    - open-computer-use@latest
+    - mcp
+---
+
+# Computer Use
+
+Use this Caplet only when an agent needs explicit access to the local desktop, application windows, or GUI workflows that cannot be completed through APIs or CLI tools.
+
+## Safety
+
+This is a high-risk local-control Caplet. It can operate real applications and may expose private screen content. Keep tasks narrow, identify the target application before acting, and do not use it for credential entry, payment flows, or irreversible actions without direct user instruction.

caplets/gmail/CAPLET.md

@@ -0,0 +1,32 @@
+---
+# yaml-language-server: $schema=https://caplets.dev/caplet.schema.json
+name: Gmail
+description: Search, read, label, draft, and send Gmail messages through the Gmail API Discovery document.
+tags:
+  - google
+  - gmail
+  - email
+googleDiscoveryApi:
+  discoveryUrl: https://gmail.googleapis.com/$discovery/rest?version=v1
+  auth:
+    type: oauth2
+    issuer: https://accounts.google.com
+    clientId: $vault:GOOGLE_CLIENT_ID
+    clientSecret: $vault:GOOGLE_CLIENT_SECRET
+    scopes:
+      - https://www.googleapis.com/auth/gmail.metadata
+      - https://www.googleapis.com/auth/gmail.readonly
+      - https://www.googleapis.com/auth/gmail.modify
+---
+
+# Gmail
+
+Use this Caplet when an agent needs Gmail context for support, scheduling, customer communication, or inbox triage.
+
+## Scope Guidance
+
+Start with metadata or readonly access when possible. Add `gmail.modify` only when the workflow needs labels, archive, trash, drafts, or sending. Avoid the broad `https://mail.google.com/` scope unless a separate reviewed local Caplet genuinely needs permanent delete access.
+
+## Use Carefully
+
+Email often contains private or regulated content. Keep queries narrow, summarize minimally, and require explicit user intent before sending, modifying, trashing, or deleting messages.

caplets/google-drive/CAPLET.md

@@ -0,0 +1,31 @@
+---
+# yaml-language-server: $schema=https://caplets.dev/caplet.schema.json
+name: Google Drive
+description: Search, read, download, upload, and manage Google Drive files through the Drive API Discovery document.
+tags:
+  - google
+  - drive
+  - files
+googleDiscoveryApi:
+  discoveryUrl: https://www.googleapis.com/discovery/v1/apis/drive/v3/rest
+  auth:
+    type: oauth2
+    issuer: https://accounts.google.com
+    clientId: $vault:GOOGLE_CLIENT_ID
+    clientSecret: $vault:GOOGLE_CLIENT_SECRET
+    scopes:
+      - https://www.googleapis.com/auth/drive.file
+      - https://www.googleapis.com/auth/drive.metadata.readonly
+---
+
+# Google Drive
+
+Use this Caplet when an agent needs Drive files as context or needs to create/update files with explicit user direction.
+
+## Scope Guidance
+
+Prefer `drive.file` and `drive.metadata.readonly` for public-safe use. Google recommends narrow scopes where possible; broad Drive scopes such as `drive` and `drive.readonly` are restricted and should be added only in a reviewed private Caplet.
+
+## Use Carefully
+
+Search metadata before reading content. Confirm file IDs and names before upload, update, trash, or delete operations, especially on shared drives.

caplets/google-tasks/CAPLET.md

@@ -0,0 +1,30 @@
+---
+# yaml-language-server: $schema=https://caplets.dev/caplet.schema.json
+name: Google Tasks
+description: Read, create, update, organize, and complete Google Tasks through the Google Tasks API Discovery document.
+tags:
+  - google
+  - tasks
+  - productivity
+googleDiscoveryApi:
+  discoveryUrl: https://www.googleapis.com/discovery/v1/apis/tasks/v1/rest
+  auth:
+    type: oauth2
+    issuer: https://accounts.google.com
+    clientId: $vault:GOOGLE_CLIENT_ID
+    clientSecret: $vault:GOOGLE_CLIENT_SECRET
+    scopes:
+      - https://www.googleapis.com/auth/tasks
+---
+
+# Google Tasks
+
+Use this Caplet when an agent needs to inspect or manage Google Tasks during planning, follow-up, or personal workflow coordination.
+
+## Scope Guidance
+
+Google Tasks offers `tasks.readonly` for read-only workflows and `tasks` for creating, editing, organizing, and deleting tasks. This install-ready Caplet includes the mutating `tasks` scope because normal task management requires it; use a private read-only variant if the agent should never mutate task state.
+
+## Use Carefully
+
+List existing tasklists and tasks before mutating. Confirm task names, due dates, and tasklist IDs before creating, completing, moving, or deleting tasks.

caplets/lsp/CAPLET.md

@@ -8,6 +8,8 @@ tags:
   - lsp
   - language-server
   - diagnostics
+projectBinding:
+  required: true
 mcpServer:
   command: npx
   args: [-y, language-server-mcp]
@@ -19,6 +21,8 @@ Use this Caplet to expose Language Server Protocol capabilities through `languag
 
 The server runs over stdio, starts local language servers lazily, and gives agents project-aware code intelligence for repositories that have LSP configuration or supported built-in language servers.
 
+Project Binding is required because all useful LSP operations need a trustworthy bound project root for workspace-relative files, language-server startup, diagnostics, and edit containment.
+
 ## Good Fits
 
 - Inspect hover/type information before editing unfamiliar code.

caplets/posthog/CAPLET.md

@@ -0,0 +1,29 @@
+---
+# yaml-language-server: $schema=https://caplets.dev/caplet.schema.json
+name: PostHog
+description: Inspect PostHog analytics, feature flags, experiments, session replay, and product telemetry through PostHog's hosted MCP server.
+tags:
+  - analytics
+  - posthog
+  - product
+  - feature-flags
+mcpServer:
+  transport: http
+  url: https://mcp.posthog.com/mcp
+  auth:
+    type: oauth2
+---
+
+# PostHog
+
+Use this Caplet when an agent needs product analytics or feature-flag context from PostHog before planning, debugging, or validating a change.
+
+## Good Fits
+
+- Query trends, funnels, retention, or HogQL for a product question.
+- Inspect feature flags, experiments, or rollout state before changing code.
+- Search session replays and event data while investigating user-reported behavior.
+
+## Use Carefully
+
+PostHog MCP includes mutating tools for flags, insights, dashboards, and other project state. Prefer read-only inspection first, review planned mutations, and keep OAuth access scoped to the PostHog organization and project you intend to expose.

caplets/repo-cli/CAPLET.md

@@ -5,6 +5,8 @@ description: Inspect and run common local repository workflows through curated C
 tags:
   - cli
   - code
+projectBinding:
+  required: true
 cliTools:
   actions:
     git_status:
@@ -35,3 +37,5 @@ cliTools:
 # Repository CLI
 
 Use this Caplet to expose a small, typed set of local repository commands without giving an agent arbitrary shell access.
+
+Project Binding is required because every command is meant to run against the attached repository. The bound root prevents the agent from accidentally treating an unrelated working directory as the target project.

caplets/sentry/CAPLET.md

@@ -0,0 +1,29 @@
+---
+# yaml-language-server: $schema=https://caplets.dev/caplet.schema.json
+name: Sentry
+description: Inspect Sentry issues, events, traces, releases, and AI debugging context through Sentry's hosted MCP server.
+tags:
+  - observability
+  - sentry
+  - errors
+  - tracing
+mcpServer:
+  transport: http
+  url: https://mcp.sentry.dev/mcp
+  auth:
+    type: oauth2
+---
+
+# Sentry
+
+Use this Caplet when an agent needs live Sentry context while debugging production errors, investigating traces, or checking release health.
+
+## Good Fits
+
+- Find the highest-impact issues for a project and time range.
+- Inspect event details, stack traces, tags, breadcrumbs, and suspect commits.
+- Correlate deploys or releases with new errors before changing code.
+
+## Use Carefully
+
+Sentry data can contain user, request, and environment details. Ask for narrow projects and time windows, summarize only the needed debugging context, and review any mutating tool calls before applying changes to Sentry state.

caplets/stealth-browser-use/CAPLET.md

@@ -0,0 +1,38 @@
+---
+# yaml-language-server: $schema=https://caplets.dev/caplet.schema.json
+name: Stealth Browser Use
+description: Drive a stealth-configured local Playwright browser for web workflows that need a non-default browser profile.
+tags:
+  - browser
+  - playwright
+  - stealth
+  - local-control
+mcpServer:
+  command: npx
+  args:
+    - -y
+    - "@playwright/mcp@latest"
+    - "--config=$env:CAPLETS_STEALTH_PLAYWRIGHT_CONFIG"
+    - --browser=firefox
+    - "--executable-path=$env:CAPLETS_STEALTH_BROWSER_EXECUTABLE"
+    - "--user-data-dir=$env:CAPLETS_STEALTH_BROWSER_USER_DATA_DIR"
+    - --headless
+---
+
+# Stealth Browser Use
+
+Use this Caplet when a workflow needs a dedicated local browser profile and the ordinary Browser Use Caplet is not suitable.
+
+## Setup
+
+Create a local Playwright MCP config file and set:
+
+- `CAPLETS_STEALTH_PLAYWRIGHT_CONFIG`
+- `CAPLETS_STEALTH_BROWSER_EXECUTABLE`
+- `CAPLETS_STEALTH_BROWSER_USER_DATA_DIR`
+
+Do not check browser profiles, cookies, or machine-specific paths into a public Caplet.
+
+## Safety
+
+This is a local-control Caplet. Follow site terms, avoid credential entry, and review any mutating browser interaction before it runs.