spiritledsoftware · ian-pascoe · Jun 22, 2026 · Jun 22, 2026 · Jun 22, 2026 · Jun 22, 2026
diff --git a/.changeset/caplets-vault.md b/.changeset/caplets-vault.md
@@ -0,0 +1,6 @@
+---
+"@caplets/core": minor
+"caplets": minor
+---
+
+Add Caplets Vault for encrypted runtime-owned string values, `$vault:` config interpolation, access grants, CLI management, and GitHub catalog Vault setup.
diff --git a/.env.example b/.env.example
@@ -1,6 +1,6 @@
 ALCHEMY_PASSWORD=
 ALCHEMY_STATE_TOKEN=
 
-CLOUDFLARE_API_TOKEN=
 CLOUDFLARE_ACCOUNT_ID=
+CLOUDFLARE_API_TOKEN=
 CLOUDFLARE_EMAIL=
diff --git a/CONCEPTS.md b/CONCEPTS.md
@@ -14,6 +14,24 @@ A per-user native service managed by `caplets daemon` that runs local HTTP `capl
 
 The Caplets Daemon is installed and updated through an install-time service contract. Runtime lifecycle commands operate on the installed service rather than changing its persisted serve or environment configuration.
 
+### Caplets Vault
+
+A runtime-owned encrypted string store whose values can be referenced from Caplets config with `$vault:NAME` or `${vault:NAME}`.
+
+Caplets Vault replaces fragile agent-harness environment propagation for secret-like config values. Each runtime owns its own Vault store; local Caplets do not read, mirror, or forward remote or Cloud Vault values.
+
+### Raw Vault Reveal
+
+The explicit human-facing action that prints a Vault value in cleartext.
+
+Raw Vault Reveal is separate from config interpolation and agent-facing runtime execution. Generic remote-control and agent surfaces must not treat caller-provided request fields as proof that a reveal is authorized.
+
+### Vault Access Grant
+
+The authorization record that lets a specific Caplet reference resolve a specific Vault key during runtime config interpolation.
+
+Vault Access Grants are identified by Caplet ID, reference name, and config origin. The stored Vault key is mutable grant data so remapping a reference replaces the target key instead of leaving stale grants behind.
+
 ### Install-Time Service Contract
 
 The persisted daemon agreement that defines what command runs, which environment model applies, which native service identity owns it, and how updates become active.

diff --git a/CONTEXT.md b/CONTEXT.md
@@ -31,3 +31,7 @@ _Avoid_: Discovery backend, discovery document backend, OpenAPI-backed Google AP
 **Media artifact**:
 A file-backed Caplets result for response content that should not be returned inline, such as binary media or oversized textual content.
 _Avoid_: Inline blob, base64 result, download blob
+
+**Caplets Vault**:
+A runtime-owned encrypted string store whose values can be referenced from Caplets config with `$vault:NAME` or `${vault:NAME}`.
+_Avoid_: Caplets Secrets, project secrets, shared encrypted project vault
diff --git a/README.md b/README.md
@@ -156,6 +156,28 @@ caplets remote login https://cloud.caplets.dev
 CAPLETS_MODE=cloud CAPLETS_REMOTE_URL=https://cloud.caplets.dev opencode
 ```
 
+## Caplets Vault
+
+Caplets Vault stores secret-like string values in the runtime that uses them, encrypted at rest for
+local/global Caplets and owned by the selected remote runtime for `--remote` operations. Reference
+Vault values in config with `$vault:NAME` or `${vault:NAME}`.
+
+```sh
+caplets vault set GH_TOKEN --grant github
+caplets vault get GH_TOKEN
+caplets vault get GH_TOKEN --show
+```
+
+Use `--remote` when the Caplet runs in a self-hosted remote or hosted Cloud runtime:
+
+```sh
+caplets vault set GH_TOKEN --remote --grant github
+caplets vault access grant GH_TOKEN github --remote
+```
+
+Vault values are not exposed through Code Mode, progressive tools, or native agent APIs. Unset or
+ungranted Vault references quarantine only the affected Caplet and appear in `caplets doctor`.
+
 ## Benchmark
 
 The deterministic benchmark compares flat MCP exposure with Caplets over the same mock
@@ -173,7 +195,7 @@ tokens than direct vanilla MCP. Live runs are model- and environment-dependent;
 deterministic benchmark is the reproducible claim.
 
 See [docs/benchmarks/coding-agent.md](https://github.com/spiritledsoftware/caplets/blob/main/docs/benchmarks/coding-agent.md) for methodology and reproduction commands.
-See [docs.caplets.dev/changelog](https://docs.caplets.dev/changelog/) for public release notes.
+See [GitHub Releases](https://github.com/spiritledsoftware/caplets/releases) for public release notes.
 
 ## Repository
 
@@ -209,6 +231,7 @@ Package map:
 Long-lived docs:
 
 - [Code Mode PRD](https://github.com/spiritledsoftware/caplets/blob/main/docs/product/caplets-code-mode-prd.md)
+- [Caplets Vault](https://github.com/spiritledsoftware/caplets/blob/main/docs/product/caplets-vault.md)
 - [Architecture](https://github.com/spiritledsoftware/caplets/blob/main/docs/architecture.md)
 - [ADR 0001: Code Mode default exposure](https://github.com/spiritledsoftware/caplets/blob/main/docs/adr/0001-code-mode-default-exposure.md)
 - [Benchmark methodology](https://github.com/spiritledsoftware/caplets/blob/main/docs/benchmarks/coding-agent.md)

diff --git a/apps/docs/README.md b/apps/docs/README.md
@@ -5,12 +5,11 @@ Astro Starlight documentation site for [docs.caplets.dev](https://docs.caplets.d
 Public docs live in `apps/docs/src/content/docs`. Root `docs/` is internal maintainer
 documentation and is not routed into this site.
 
-Generated reference pages and the public changelog come from:
+Generated reference pages come from:
 
 - `schemas/caplets-config.schema.json`
 - `schemas/caplet.schema.json`
 - `packages/core/src/code-mode/runtime-api.d.ts`
-- `CHANGELOG.md`
 
 ## Commands
 

diff --git a/apps/docs/astro.config.mjs b/apps/docs/astro.config.mjs
@@ -32,7 +32,7 @@ export default defineConfig({
         {
           label: "Get Started",
           items: [
-            { label: "Start here", link: "/" },
+            { label: "Quick Start", link: "/" },
             { label: "Install", link: "/install/" },
             { label: "Configuration", link: "/configuration/" },
           ],
@@ -42,6 +42,7 @@ export default defineConfig({
           items: [
             { label: "Code Mode", link: "/code-mode/" },
             { label: "Add capabilities", link: "/capabilities/" },
+            { label: "Caplets Vault", link: "/vault/" },
             { label: "Agent integrations", link: "/agent-integrations/" },
             { label: "Remote attach", link: "/remote-attach/" },
             { label: "Troubleshooting", link: "/troubleshooting/" },
@@ -53,7 +54,10 @@ export default defineConfig({
             { label: "Configuration schema", link: "/reference/config/" },
             { label: "Code Mode API", link: "/reference/code-mode-api/" },
             { label: "Caplet files", link: "/reference/caplet-files/" },
-            { label: "Changelog", link: "/changelog/" },
+            {
+              label: "GitHub releases",
+              link: "https://github.com/spiritledsoftware/caplets/releases",
+            },
           ],
         },
       ],

diff --git a/apps/docs/src/content/docs/changelog.mdx b/apps/docs/src/content/docs/changelog.mdx
diff --git a/apps/docs/src/content/docs/configuration.mdx b/apps/docs/src/content/docs/configuration.mdx
@@ -63,3 +63,28 @@ After changing config, run:
 ```sh
 caplets doctor
 ```
+
+## Secret values
+
+Use [Caplets Vault](/vault/) for tokens, API keys, private URLs, and other values that
+should not live in agent config or depend on agent environment propagation.
+
+```json
+{
+  "mcpServers": {
+    "github": {
+      "command": "github-mcp",
+      "env": {
+        "GH_TOKEN": "$vault:GH_TOKEN"
+      }
+    }
+  }
+}
+```
+
+After adding a `$vault:` reference, set the value and grant it to the configured Caplet:
+
+```sh
+caplets vault set GH_TOKEN --grant github
+caplets doctor
+```
diff --git a/apps/docs/src/content/docs/index.mdx b/apps/docs/src/content/docs/index.mdx
@@ -10,7 +10,7 @@ handle that an agent can inspect, search, call, filter, and summarize in one wor
 Use Caplets with Codex, Claude, OpenCode, Pi, or any MCP client that can launch a local
 stdio server.
 
-## Start here
+## Quick Start
 
 Run a known-good no-auth setup first. OSV is public, so it is the fastest way to prove
 your agent can see and call a Caplet.
@@ -66,6 +66,7 @@ should contain the OSV identifiers the agent found.
 - [Code Mode](/code-mode/) - learn the default agent workflow.
 - [Configuration](/configuration/) - configure user and project Caplets.
 - [Capabilities](/capabilities/) - add MCP, OpenAPI, GraphQL, HTTP, CLI, and shared Caplets.
+- [Caplets Vault](/vault/) - store secret config values without relying on agent environment propagation.
 - [Agent integrations](/agent-integrations/) - use Codex, Claude, OpenCode, and Pi.
 - [Remote attach](/remote-attach/) - connect agents to a remote Caplets runtime.
 - [Troubleshooting](/troubleshooting/) - check config, auth, and runtime issues.
diff --git a/apps/docs/src/content/docs/reference/caplet-files.mdx b/apps/docs/src/content/docs/reference/caplet-files.mdx
@@ -143,6 +143,24 @@ OpenAPI endpoint backend configuration for this Caplet.
 | `projectBinding`      | Optional | object  | Project Binding requirements for Caplets that need an attached project.           |
 | `runtime`             | Optional | object  | Runtime feature and resource requirements for hosted execution.                   |
 
+### `googleDiscoveryApi`
+
+Google Discovery API backend configuration for this Caplet.
+
+| Field                 | Status   | Type    | Description                                                                                |
+| --------------------- | -------- | ------- | ------------------------------------------------------------------------------------------ |
+| `discoveryPath`       | Optional | string  | Local Google Discovery document path.                                                      |
+| `discoveryUrl`        | Optional | string  | Remote Google Discovery document URL.                                                      |
+| `baseUrl`             | Optional | string  | Override base URL for Google API requests.                                                 |
+| `auth`                | Required | object  | Explicit Google API request auth config. Use \{"type":"none"\} for public APIs.            |
+| `requestTimeoutMs`    | Optional | integer | Timeout in milliseconds for Google API HTTP requests.                                      |
+| `operationCacheTtlMs` | Optional | integer | Milliseconds Google Discovery operation metadata stays fresh. Set 0 to refresh every time. |
+| `includeOperations`   | Optional | array   | Optional list of includeOperations.                                                        |
+| `excludeOperations`   | Optional | array   | Optional list of excludeOperations.                                                        |
+| `disabled`            | Optional | boolean | When true, omit this Caplet from discovery.                                                |
+| `projectBinding`      | Optional | object  | Project Binding requirements for Caplets that need an attached project.                    |
+| `runtime`             | Optional | object  | Runtime feature and resource requirements for hosted execution.                            |
+
 ### `graphqlEndpoint`
 
 GraphQL endpoint backend configuration for this Caplet.