fix: harden legacy host-state migration and documentation

.changeset/clean-cups-help.md

@@ -0,0 +1,6 @@
+---
+"@caplets/core": patch
+"caplets": patch
+---
+
+**Required upgrade migration:** Hosts that ran `caplets@0.25.x` or earlier must stop every Caplets Host Node and run `caplets storage migrate-legacy --dry-run`, then `caplets storage migrate-legacy`, before restarting the daemon, running `caplets setup`, or serving requests. The migration now imports standard legacy auth, Vault, remote security, setup, Operator Activity, and tracked-Caplet state; preserves file-layer Vault grants and shared Vault key access; uses platform paths by default; and reports actionable missing tracked entries.

README.md

@@ -44,6 +44,14 @@ Caplets can wrap:
 
 Full setup and configuration docs are available at [docs.caplets.dev](https://docs.caplets.dev/).
 
+> **Required upgrade migration:** If this host ran `caplets@0.25.x` or earlier, installing
+> `caplets@0.26.0` or later requires a one-time SQL migration **before** you restart the
+> daemon, run `caplets setup`, or serve requests. Stop every Caplets Host Node, then run
+> `caplets storage migrate-legacy --dry-run` followed by
+> `caplets storage migrate-legacy`. Skipping this step leaves legacy auth, Vault, remote
+> security, setup, activity, and tracked-Caplet state outside the authoritative SQL store.
+> See [SQL Authoritative Host State operations](docs/operations/sql-authoritative-host-state.md#offline-legacy-filesystem-migration).
+
 Install the CLI and wire it into your agent:
 
 ```sh

apps/docs/astro.config.mjs

@@ -41,28 +41,42 @@ export default defineConfig({
           items: [
             { label: "Quick Start", link: "/" },
             { label: "Install", link: "/install/" },
-            { label: "Configuration", link: "/configuration/" },
           ],
         },
         {
           label: "Use Caplets",
           items: [
             { label: "Code Mode", link: "/code-mode/" },
             { label: "Add capabilities", link: "/capabilities/" },
+            { label: "Configuration", link: "/configuration/" },
             { label: "Catalog", link: "/catalog/" },
-            { label: "Dashboard", link: "/dashboard/" },
             { label: "Caplets Vault", link: "/vault/" },
+            { label: "Project Binding", link: "/project-binding/" },
+          ],
+        },
+        {
+          label: "Connect Agents",
+          items: [
             { label: "Agent integrations", link: "/agent-integrations/" },
             { label: "Remote attach", link: "/remote-attach/" },
+          ],
+        },
+        {
+          label: "Operate a Host",
+          items: [
+            { label: "Dashboard", link: "/dashboard/" },
+            { label: "Authoritative Host State", link: "/storage/" },
+            { label: "Privacy and network activity", link: "/privacy/" },
             { label: "Troubleshooting", link: "/troubleshooting/" },
           ],
         },
         {
           label: "Reference",
           items: [
+            { label: "CLI", link: "/reference/cli/" },
             { label: "Configuration schema", link: "/reference/config/" },
-            { label: "Code Mode API", link: "/reference/code-mode-api/" },
             { label: "Caplet files", link: "/reference/caplet-files/" },
+            { label: "Code Mode API", link: "/reference/code-mode-api/" },
             { label: "Catalog indexing privacy", link: "/privacy/indexing/" },
             {
               label: "GitHub releases",

apps/docs/src/content/docs/agent-integrations.mdx

@@ -79,6 +79,22 @@ settings still win over those defaults.
 Native integrations use the shared anonymous telemetry controls and do not send telemetry on a
 native-first run until a visible CLI telemetry notice has already been recorded.
 
+### Native runtime selection
+
+OpenCode and Pi accept shared runtime selectors through integration settings or environment:
+
+| Mode     | Selection                                                                                            |
+| -------- | ---------------------------------------------------------------------------------------------------- |
+| `auto`   | Cloud for Cloud URLs, remote for other URLs, setup-written daemon defaults when present, then local. |
+| `local`  | Run Caplets in the agent process with user and project config.                                       |
+| `daemon` | Use the loopback runtime selected by `CAPLETS_DAEMON_URL`.                                           |
+| `remote` | Use the saved Remote Profile selected by `CAPLETS_REMOTE_URL`.                                       |
+| `cloud`  | Use the Cloud runtime selected by `CAPLETS_REMOTE_URL` and optional `CAPLETS_REMOTE_WORKSPACE`.      |
+
+Cloud native sessions and loopback daemon sessions with a project root can open
+[Project Binding](/project-binding/) for required Caplets. Self-hosted HTTPS native remotes do not
+currently establish that managed binding session; required project Caplets remain hidden.
+
 Remote native usage:
 
 ```sh
@@ -122,3 +138,7 @@ caplets serve --transport http --upstream-url https://caplets.example.com/caplet
 Then configure the MCP client with `caplets attach <local-runtime-url>`. If you also need
 host administration, open the same runtime's `/dashboard` path in a browser and complete an
 Operator approval there.
+
+Use the [CLI reference](/reference/cli/) for the complete command-family map and
+[Privacy and network activity](/privacy/) for the independent native telemetry, update-check,
+and catalog-indexing controls.

apps/docs/src/content/docs/catalog.mdx

@@ -6,8 +6,8 @@ description: Search public Caplets and inspect installable catalog entries.
 <a href="https://catalog.caplets.dev" target="_blank" rel="noopener noreferrer">
   catalog.caplets.dev
 </a>
-is the public search surface for Caplets. It lists official Caplets from this repository and public
-community Caplets discovered from successful public external installs.
+is the public search surface for Caplets. It lists official Caplets from this repository and
+community Caplets submitted after eligible GitHub-shaped external installs.
 
 <a
   class="caplets-docs-cta"
@@ -25,10 +25,11 @@ generated install command when the catalog can tie that command to inspected con
 ## Safety model
 
 The catalog is not a scanner, certification program, endorsement list, or moderation
-queue. V1 performs basic public-source eligibility checks, bounded ingestion, sanitized
-Markdown rendering, count bucketing, and operator suppression. It does not claim semantic
-malware review, dependency scanning, vulnerability scanning, secret scanning, or human
-approval.
+queue. V1 validates source syntax but does not verify GitHub repository visibility before
+submission. Catalog ingestion is bounded, renders Markdown through a sanitizer, buckets counts,
+and supports operator suppression. It does not claim semantic malware review, dependency
+scanning, vulnerability scanning, secret scanning, or human approval. Disable catalog indexing
+before installing private repositories or Caplet content that must not become public.
 
 Install counts are popularity and ranking signals only. They are not safety, quality, or
 trust signals.

apps/docs/src/content/docs/configuration.mdx

@@ -58,6 +58,13 @@ particular, `serve.path` changes the dashboard URL prefix, and `serve.publicOrig
 public dashboard origin used for browser-facing request identity and session/cookie behavior. See
 [Dashboard](/dashboard/) if you are exposing host administration through the browser.
 
+### Authoritative Host State
+
+The user config may select the host's SQLite or PostgreSQL `storage` backend and optional
+S3-compatible bundle asset store. Project config cannot override host storage. See
+[Authoritative Host State](/storage/) for schema migration, bootstrap-secret, backup, and
+legacy-upgrade requirements.
+
 ## Project config
 
 Project config lives at:

apps/docs/src/content/docs/dashboard.mdx

@@ -28,21 +28,25 @@ https://caplets.example.com/caplets/dashboard
 ```
 
 The exact URL depends on the host, port, and configured serve path.
+
+The dashboard targets current evergreen browsers with JavaScript enabled. It is served by
+the Caplets HTTP runtime; the stdio-only `caplets attach` adapter has no dashboard.
 If the server is mounted below a base path such as `/caplets`, the dashboard lives under that
 same base path.
 
 ## Approval flow
 
 An unauthenticated browser sees an operator approval screen first.
 Selecting **Authorize this browser** creates a pending login and shows the host-side approval command.
-On the host, approve that operator code from the same environment that owns the remote credential state:
+On the host, approve that operator code from the same user configuration that selects
+Authoritative Host State:
 
 ```sh
 caplets remote host approve <code> --yes
 ```
 
-If the host uses a non-default remote credential state directory, use the matching `--state-path`
-value when approving from the CLI.
+The deprecated `--state-path` option no longer selects credential state. Remote clients,
+pending logins, and dashboard sessions are stored in the host's configured SQL backend.
 
 After approval, the browser receives an operator dashboard session and can administer the Current Host.
 

apps/docs/src/content/docs/index.mdx

@@ -10,6 +10,12 @@ 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.
 
+> **Required upgrade migration:** If this host ran `caplets@0.25.x` or earlier, do not
+> start `caplets@0.26.0` or later until you complete the
+> [one-time legacy-state migration](/install/#required-migration-when-upgrading-to-0260-or-later).
+> Caplets does not automatically migrate or fall back to the old auth, Vault, remote-security,
+> setup, activity, and tracked-Caplet stores.
+
 ## Quick Start
 
 Install the CLI, then run a known-good no-auth setup first. OSV is public, so it is the
@@ -68,4 +74,8 @@ should contain the OSV identifiers the agent found.
 - [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.
+- [Project Binding](/project-binding/) - synchronize local repository context for remote Caplets.
+- [Authoritative Host State](/storage/) - operate SQLite or PostgreSQL host state.
+- [CLI reference](/reference/cli/) - find command families and environment controls.
+- [Privacy and network activity](/privacy/) - control telemetry, update checks, and catalog indexing.
 - [Troubleshooting](/troubleshooting/) - check config, auth, and runtime issues.

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

@@ -5,9 +5,36 @@ description: Install Caplets and wire it into your agent.
 
 Caplets is pre-1.0. Use the latest CLI and latest docs together.
 
+## Required migration when upgrading to 0.26.0 or later
+
+> **Do not start the upgraded host first.** If this host ran `caplets@0.25.x` or earlier,
+> the one-time legacy-state migration is required after installing `caplets@0.26.0` or
+> later and before restarting the daemon, running `caplets setup`, or serving requests.
+
+Caplets 0.26.0 moved Authoritative Host State into SQL. It does not automatically migrate
+or fall back to the old backend auth, Vault, remote-security, setup, Operator Activity, or
+tracked-Caplet stores. Skipping migration can therefore make existing credentials, Vault
+values and grants, remote clients, setup history, activity, and tracked Caplets appear
+missing.
+
+Stop every Caplets Host Node, back up the legacy state roots and configured SQL database,
+then verify and run the migration:
+
+```sh
+caplets storage migrate-legacy --dry-run
+caplets storage migrate-legacy
+caplets storage status --json
+```
+
+Resolve every dry-run error before running the write migration. Record the backup path
+printed by the migration, and restart the host only after storage status reports ready.
+Fresh hosts that never ran a version before 0.26.0 do not need this migration. See
+[Authoritative Host State](/storage/#upgrade-from-025x-or-earlier) for default paths,
+custom-path guidance, backup requirements, and recovery behavior.
+
 ## Requirements
 
-- Node.js 24 or newer for published packages.
+- Node.js 22 or newer for published packages.
 - An agent that can use MCP, such as Codex or Claude, or a native integration such as
   OpenCode or Pi.
 
@@ -72,11 +99,12 @@ 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 public external sources, install, restore, and update also attempt best-effort catalog
-indexing after the local mutation succeeds. Human output prints a short notice when a
-public Caplet source may be indexed. JSON output includes per-entry `catalogIndexing`
-status values. Indexing failures never block install/update/restore, and private or local
-sources are skipped with redacted categorical statuses.
+For eligible GitHub-shaped external sources, install, restore, and update also attempt
+best-effort catalog indexing after the local mutation succeeds. Human output prints a short
+notice when a source may be indexed. JSON output includes per-entry `catalogIndexing` status
+values. Eligibility does not verify GitHub repository visibility, and the payload includes
+the installed `CAPLET.md`; disable indexing for private repositories or non-public content.
+Indexing failures never block install/update/restore.
 
 Set `CAPLETS_DISABLE_CATALOG_INDEXING=1` to skip catalog indexing network requests
 entirely.

apps/docs/src/content/docs/privacy.mdx

@@ -0,0 +1,111 @@
+---
+title: Privacy and Network Activity
+description: Understand and control telemetry, update checks, and catalog indexing.
+---
+
+Caplets has three independent outbound product services: anonymous telemetry, passive npm update
+metadata checks, and best-effort public catalog indexing after eligible lifecycle operations. Each
+has a separate control. Disabling one does not disable the others.
+
+Remote Caplets, downstream APIs, OAuth providers, and user-configured catalog sources naturally add
+the network calls required by those capabilities; those are not product telemetry.
+
+## Anonymous telemetry
+
+Telemetry is opt-out and reports bounded product-usage and reliability categories. The first
+eligible interactive CLI run prints a notice to stderr. Non-CI telemetry remains suppressed until
+that notice has been recorded, so a native-first run does not silently activate collection.
+
+Disable telemetry for one process:
+
+```sh
+CAPLETS_DISABLE_TELEMETRY=1 caplets serve
+```
+
+Disable it in user config and inspect the effective state:
+
+```sh
+caplets telemetry disable
+caplets telemetry status
+```
+
+Re-enable it with `caplets telemetry enable`. The environment variable wins over user config.
+Tests disable telemetry automatically.
+
+Telemetry properties are allowlisted categorical values, integer counts, booleans, duration/timeout
+buckets, package/version metadata, and coarse runtime information such as OS family, architecture,
+and Node major version. Reliability exceptions keep only sanitized package/workspace-relative stack
+frames and an error type.
+
+Caplets telemetry does **not** collect raw config, prompts, Code Mode source, tool arguments, tool
+outputs, resource or prompt contents, logs, raw or absolute local paths, URLs, hostnames, Caplet IDs,
+credentials, tokens, raw environment variables, raw error messages, or unsanitized stack traces.
+Reliability stack frames may retain the sanitized package/workspace-relative paths or safe basenames
+described above.
+
+Inspect the sanitized events a command would produce without delivering them:
+
+```sh
+caplets telemetry debug -- doctor
+caplets telemetry debug -- code-mode 'return 1'
+```
+
+Telemetry debug mode also disables the update check for that invocation. Manage the anonymous local
+identity separately:
+
+```sh
+caplets telemetry rotate-id
+caplets telemetry delete-id
+```
+
+## Passive update checks
+
+Eligible CLI commands may fetch public package metadata from
+`https://registry.npmjs.org/caplets`. The lookup requests only npm's install metadata, has a 250 ms
+fetch timeout and 1 MiB response limit, and keeps successful metadata fresh for 24 hours. If later
+refreshes fail, that metadata may remain usable for a further seven days. An update notice is
+written to stderr at most once per version every seven days.
+
+Update notices avoid help, version, completion, JSON/output-product commands, Code Mode, daemon
+commands, CI, and non-interactive output. Stdio `serve` and `attach` stay quiet by default so MCP
+protocol output is not polluted. Set `CAPLETS_UPDATE_NOTICE_STDERR=1` only for a foreground stdio
+process whose stderr is visible and separate from protocol stdout.
+
+Disable both update notices and metadata lookups:
+
+```sh
+CAPLETS_DISABLE_UPDATE_CHECK=1 caplets doctor
+```
+
+This switch is independent from telemetry.
+
+## Public catalog indexing
+
+After a successful install, restore, or update of an eligible GitHub-shaped external Caplet,
+Caplets may submit normalized source identity, revisions and hashes, the full installed
+`CAPLET.md`, and derived catalog/child metadata to the public catalog. Eligibility checks source
+syntax but do not verify GitHub repository visibility. Disable indexing before operating on a
+private GitHub repository or any Caplet file whose contents must not become public. Indexing is
+best effort and never changes the local lifecycle result.
+
+Disable catalog indexing network requests:
+
+```sh
+CAPLETS_DISABLE_CATALOG_INDEXING=1 caplets install spiritledsoftware/caplets osv
+```
+
+The envelope does not separately add installer identity, local filesystem paths, Vault values,
+agent prompts, tool arguments, tool outputs, or raw environment values. Because it includes the
+full Caplet file, anything authored in that file can be submitted. See
+[Catalog indexing privacy](/privacy/indexing/) for the exact boundary.
+
+## Control matrix
+
+| Activity                | Default                                               | Disable                                                      |
+| ----------------------- | ----------------------------------------------------- | ------------------------------------------------------------ |
+| Anonymous telemetry     | Opt-out after the visible notice gate                 | `CAPLETS_DISABLE_TELEMETRY=1` or `caplets telemetry disable` |
+| Passive update metadata | Eligible foreground CLI commands                      | `CAPLETS_DISABLE_UPDATE_CHECK=1`                             |
+| Public catalog indexing | Eligible GitHub-shaped install/restore/update results | `CAPLETS_DISABLE_CATALOG_INDEXING=1`                         |
+
+For machine-readable automation, prefer `--json` where supported. Caplets keeps update notices and
+telemetry notices on stderr and suppresses them for structured output paths.