happy2 0.0.5 → 0.0.11

package/README.md

@@ -1,82 +1,136 @@
-# Happy (2)
+<div align="center">
 
-Happy (2) is a desktop work and coding app that evolves by adopting itself. This
-pnpm monorepo delivers its shared Solid UI through a web app and an Electron
-desktop app. Happy (2) is desktop-only; its UI must not assume mobile use or adapt
-for mobile viewports.
+<p><img src="./.github/logo.png" alt="Happy (2)" width="640" /></p>
 
-## Packages
+<h3>A self-hosted, Slack-like workspace where people and coding agents build together.</h3>
 
-- `happy2-app` contains the shared Solid component and its tests.
-- `happy2-web` imports `happy2-app` and creates a browser build.
-- `happy2-desktop` imports `happy2-app` in an Electron renderer and builds its
-  Electron main process with Vite.
-- `happy2-server` is the Fastify server and authentication-service package.
-- The root `happy2` package bundles the server and built web app into the complete
-  distributable.
-- `happy2-gym` is the isolated end-to-end testing environment. Its server harness runs
-  black-box HTTP tests against disposable in-memory server instances; see
-  [`packages/happy2-gym/README.md`](packages/happy2-gym/README.md) for usage.
+<p>
+  Following the success of <a href="https://github.com/slopus/happy">Happy</a>,
+  Happy (2) is a ground-up next chapter built on the lessons learned from
+  bringing coding agents into real daily workflows. It brings conversations,
+  files, workspaces, and coding agents into one focused web and desktop app.
+</p>
 
-## Requirements
+<p>
+  Built by the authors of
+  <a href="https://github.com/slopus/happy">Happy</a> and
+  <a href="https://github.com/slopus/rig">Rig</a>.
+</p>
 
-- Node.js 24 or later (required by Portless)
-- pnpm 10.28 or later
+<p>
+  <a href="#quick-start">Quick start</a> ·
+  <a href="#why-happy-2">Why Happy (2)?</a> ·
+  <a href="#how-it-works">How it works</a> ·
+  <a href="#project-components">Project components</a> ·
+  <a href="packages/happy2-server/README.md">Server docs</a>
+</p>
 
-TypeScript is on the v7 release line throughout the workspace.
+</div>
 
-## Commands
+Happy (2) is a self-hosted, Slack-like work and coding app that evolves by
+adopting itself. It gives teams and coding agents a shared home instead of
+scattering work across chat windows, terminals, file browsers, and one-off
+dashboards.
 
-```sh
-pnpm install
-pnpm dev                # Server + web app on stable Portless URLs
-pnpm dev:desktop        # Electron app connected to the server from pnpm dev
-pnpm --dir packages/happy2-gym test # Server end-to-end tests
-pnpm check              # Type-check, test, and build every package
-```
+The same React application runs in the browser and in Electron. A small Fastify
+server provides authentication, durable collaboration state, files, realtime
+updates, and agent execution. The complete server and web app are also bundled
+as one `happy2` package.
 
-`pnpm build` emits browser files to `packages/happy2-web/dist` and an Electron renderer
-plus main process to `packages/happy2-desktop/dist`. Start the latter after building
-with `pnpm --filter happy2-desktop start`.
+## Quick start
 
-`pnpm dev` runs the server and web app through Portless with interleaved logs.
-The main checkout uses `https://happy2.localhost` and
-`https://happy2-api.localhost`; linked worktrees automatically receive unique
-branch-prefixed hostnames. The generated development TOML, database, files,
-keys, and password pepper stay under `.context/dev` in each workspace.
+Happy (2) requires Node.js 24 or later. Start the complete app with one command:
 
-With `pnpm dev` running, start `pnpm dev:desktop` in another terminal. It resolves
-the same workspace-specific `happy2-api` URL and passes it to the Electron
-renderer. Portless assigns the renderer an available workspace-specific port;
-set `PORT=xxxx` only when you need to choose it explicitly.
-
-Start only a local server with `pnpm dev:server`. Without a TOML file it enables
-self-service password registration and login, creates its SQLite database under
-`packages/happy2-server`, and generates durable local JWT keys plus password pepper in
-`packages/happy2-server/.env` on first start. Pass `--config path/to/happy2.toml` (or
-set `HAPPY2_CONFIG`) to override the defaults; copy the example TOML before
-production deployment. See the server package README for deployment and auth
-configuration.
+```sh
+npx happy2
+```
 
-## Publishing
+Open [http://127.0.0.1:3000](http://127.0.0.1:3000) in your browser. Happy (2)
+stores its database, files, generated secrets, agent workspaces, and private Rig
+runtime under `.happy2` in the directory where you start it.
 
-Authenticate with npm once using `pnpm login`, then publish the all-in-one `happy2`
-from a clean, up-to-date `main` branch:
+Keep Happy (2) running across reboots with:
 
 ```sh
-pnpm release 0.1.0
+npx happy2 service start
+npx happy2 service stop
 ```
 
-The release command also accepts semantic version bumps such as `patch`,
-`minor`, and `major`. It checks the branch, working tree, and npm
-authentication; runs the full workspace check; creates the release commit and
-tag; previews the package; pushes to `main`; and publishes it publicly. If
-publishing is interrupted after the tag is created, rerun the command with the
-exact version to resume safely.
+On macOS this installs a per-user LaunchAgent without `sudo`; it starts when the
+user logs in. On Linux it writes and prints `./happy2.service`, then shows the
+exact `sudo` commands you can run to install and start it as a system-wide
+systemd unit. `service stop` prints the corresponding systemd removal commands;
+it never invokes `sudo` itself. The generated file remains in the current
+directory so you can inspect or reinstall it. Add
+`--config /absolute/or/relative/happy2.toml` to `service start` to preserve an
+explicit configuration file; otherwise the service keeps the current directory
+as its working directory and uses its `.happy2` state. When started through
+`npx`, the generated service runs `npx --yes happy2` instead of depending on an
+evictable `_npx` cache path.
+
+## Why Happy (2)?
+
+- **People and agents share the same workspace.** Conversations, threads,
+  files, approvals, and agent activity live together instead of becoming a pile
+  of disconnected tools.
+- **Self-hosted by design.** Run the complete app with one command and keep its
+  database, files, secrets, agent workspaces, and Rig runtime under your control.
+- **Web and desktop.** Use the same full collaboration experience in a browser
+  or through the Electron app.
+- **Reactive by default.** Realtime events reconcile durable state so focused
+  surfaces stay current without refresh buttons.
+- **Flexible deployment.** The backend can run as an all-in-one server or as a
+  separately deployed authentication service.
+- **Built to adopt itself.** Happy (2)'s own server, state layer, component
+  workbench, browser tests, and coding-agent workflows are part of the product's
+  development loop.
+
+## How it works
+
+Happy (2) keeps the product boundaries explicit:
+
+1. `happy2-server` owns authentication, persistence, files, collaboration, and
+   agent execution.
+2. `happy2-state` turns authenticated HTTP and realtime transports into
+   immutable, independently materialized surface stores.
+3. `happy2-ui` owns the reusable visual system and its cross-browser blueprint
+   coverage.
+4. `happy2-app` composes product state and UI for both the web and Electron
+   entry points.
+
+Local development data stays under `.context/dev` in each workspace, including
+the generated TOML configuration, SQLite database, files, signing keys, and
+password pepper.
+
+## Project components
+
+- **[Happy App](packages/happy2-app)** — Shared React application and product
+  composition.
+- **[Happy UI](packages/happy2-ui)** — Reusable design system, component
+  workbench, and cross-browser visual coverage.
+- **[Happy State](packages/happy2-state)** — Framework-independent client state
+  and realtime reconciliation.
+- **[Happy Web](packages/happy2-web)** — Browser entry point and production web
+  build.
+- **[Happy Desktop](packages/happy2-desktop)** — Electron renderer and desktop
+  main process.
+- **[Happy Server](packages/happy2-server)** — Fastify server, authentication
+  service, persistence, and agent runtime.
+- **[Happy Gym](packages/happy2-gym)** — Isolated black-box server, state, and
+  browser testing environment.
+
+## Development
+
+The repository uses pnpm 10.28 or later. For local development:
 
-## Working convention
+```sh
+pnpm install
+pnpm dev                                 # Server + web app
+pnpm dev:desktop                         # Electron app
+pnpm dev:server                          # Server only
+pnpm --dir packages/happy2-gym test      # End-to-end tests
+pnpm check                               # Format, lint, test, coverage, build
+```
 
-“Sync to main” means to commit the current work, rebase it onto the latest
-`origin/main`, and push the resulting `HEAD` to `main` without force. If `main`
-advances or the push is rejected, fetch and rebase again before retrying. Never
-force-push `main`.
+For production server configuration, authentication modes, and deployment, see
+the [Happy Server documentation](packages/happy2-server/README.md).

package/package.json

@@ -1,7 +1,11 @@
 {
   "name": "happy2",
-  "version": "0.0.5",
+  "version": "0.0.11",
   "description": "Happy (2) desktop web app and server bundle",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/slopus/happy2.git"
+  },
   "bin": {
     "happy2": "packages/happy2-server/bin/happy2.js"
   },
@@ -9,8 +13,10 @@
     "packages/happy2-server/bin/happy2.js",
     "packages/happy2-server/dist",
     "packages/happy2-server/drizzle",
+    "packages/happy2-server/plugins",
     "packages/happy2-server/happy2.example.toml",
     "packages/happy2-server/README.md",
+    "packages/happy2-server/PLUGINS.md",
     "packages/happy2-server/Dockerfile"
   ],
   "type": "module",
@@ -23,52 +29,68 @@
     }
   },
   "publishConfig": {
-    "access": "public"
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
   },
+  "packageManager": "pnpm@10.28.1",
   "engines": {
     "node": ">=24.0.0",
     "pnpm": ">=10.28.1"
   },
+  "scripts": {
+    "dev": "node scripts/dev.mjs",
+    "dev:web": "pnpm --filter happy2-web dev",
+    "dev:desktop": "node scripts/dev-desktop.mjs",
+    "dev:server": "pnpm --dir packages/happy2-server dev",
+    "start": "node packages/happy2-server/dist/runner.js",
+    "build": "pnpm -r --if-present build && VITE_HAPPY2_SERVER_URL='/' pnpm --filter happy2-web exec vite build --outDir ../happy2-server/dist/web --emptyOutDir false",
+    "test": "pnpm test:coverage-tooling && pnpm -r --if-present test",
+    "test:non-server": "pnpm --parallel --filter happy2-state --filter happy2-ui --filter happy2-app test && pnpm --dir packages/happy2-gym test:playwright",
+    "test:coverage-tooling": "pnpm --dir packages/happy2-server test:coverage-tooling",
+    "coverage:server:unit": "pnpm --dir packages/happy2-server test:coverage",
+    "coverage:server:gym": "pnpm --dir packages/happy2-gym test:server:coverage",
+    "coverage:server": "pnpm test:coverage-tooling && pnpm coverage:server:unit && pnpm coverage:server:gym && tsx packages/happy2-server/tooling/server-coverage/cli.ts check",
+    "coverage:server:baseline": "pnpm test:coverage-tooling && pnpm coverage:server:unit && pnpm coverage:server:gym && tsx packages/happy2-server/tooling/server-coverage/cli.ts baseline",
+    "test:watch": "pnpm -r --parallel --if-present test:watch",
+    "typecheck": "tsc --project tsconfig.json && pnpm -r --if-present typecheck",
+    "format": "oxfmt --write eslint scripts tsconfig.json && pnpm -r --if-present format",
+    "format:check": "oxfmt --check eslint scripts tsconfig.json && pnpm -r --if-present format:check",
+    "lint": "oxlint eslint scripts && pnpm -r --if-present lint",
+    "check:validation": "pnpm format:check && pnpm lint && pnpm --dir packages/happy2-server architecture:check && pnpm typecheck && pnpm test:coverage-tooling && pnpm test:non-server && pnpm coverage:server:unit && pnpm coverage:server:gym",
+    "check": "pnpm check:validation && tsx packages/happy2-server/tooling/server-coverage/cli.ts check && pnpm build",
+    "check:release": "pnpm check:validation && pnpm build",
+    "release": "tsx scripts/release.ts",
+    "prepack": "pnpm run build",
+    "clean": "pnpm -r --if-present clean"
+  },
   "dependencies": {
     "@fastify/cors": "^11.3.0",
     "@fastify/http-proxy": "^11.5.0",
     "@fastify/multipart": "^10.1.0",
     "@fastify/static": "^10.1.0",
     "@libsql/client": "^0.17.4",
+    "@modelcontextprotocol/sdk": "^1.29.0",
     "@paralleldrive/cuid2": "^3.3.0",
-    "@slopus/rig": "^0.0.17",
+    "@slopus/rig": "^0.0.24",
     "drizzle-orm": "^0.45.2",
     "fastify": "^5.8.2",
     "jose": "^6.1.3",
     "nodemailer": "^7.0.13",
     "sharp": "^0.35.3",
     "smol-toml": "^1.4.2",
-    "thumbhash": "^0.1.1"
+    "thumbhash": "^0.1.1",
+    "yaml": "^2.9.0"
   },
   "devDependencies": {
+    "@eslint/css": "^1.4.0",
+    "@rolldown/plugin-babel": "0.2.3",
     "@types/node": "^26.1.1",
+    "babel-plugin-react-compiler": "1.0.0",
     "concurrently": "^10.0.3",
     "oxfmt": "^0.57.0",
     "oxlint": "^1.73.0",
     "portless": "^0.15.1",
     "tsx": "^4.21.0",
     "typescript": "^7.0.2"
-  },
-  "scripts": {
-    "dev": "node scripts/dev.mjs",
-    "dev:web": "pnpm --filter happy2-web dev",
-    "dev:desktop": "node scripts/dev-desktop.mjs",
-    "dev:server": "pnpm --dir packages/happy2-server dev",
-    "start": "node packages/happy2-server/dist/runner.js",
-    "build": "pnpm -r --if-present build && VITE_HAPPY2_SERVER_URL='/' pnpm --filter happy2-web exec vite build --outDir ../happy2-server/dist/web --emptyOutDir false",
-    "test": "pnpm -r --if-present test",
-    "test:watch": "pnpm -r --parallel --if-present test:watch",
-    "typecheck": "tsc --project tsconfig.json && pnpm -r --if-present typecheck",
-    "format": "oxfmt --write scripts tsconfig.json && pnpm -r --if-present format",
-    "format:check": "oxfmt --check scripts tsconfig.json && pnpm -r --if-present format:check",
-    "lint": "oxlint scripts && pnpm -r --if-present lint",
-    "check": "pnpm format:check && pnpm lint && pnpm typecheck && pnpm test && pnpm build",
-    "release": "tsx scripts/release.ts",
-    "clean": "pnpm -r --if-present clean"
   }
-}
+}

package/packages/happy2-server/PLUGINS.md

@@ -0,0 +1,330 @@
+# Server plugins
+
+Happy (2) plugins package Agent Skills, an MCP server, or both. This first
+server-side implementation installs only packages bundled with the server. It
+already keeps catalog discovery, durable system plugins, immutable package/image
+snapshots, and independent runtime installations separate so a later remote
+catalog/download step can reuse the same boundaries.
+
+Plugin management is system-wide and administrator-only. The first installation
+of a catalog package creates one durable system-plugin record and one immutable
+package snapshot; later installations reuse that plugin identity and snapshot.
+Every installation has its own CUID2, variables, selected image, lifecycle, and
+dedicated container when it is a local stdio MCP. Remote MCP configuration is
+persisted and health-checked independently per installation. Ready MCP
+installations expose their tools to Rig as durable external functions on every
+agent submission. Happy executes each durable call against the originating
+installation and resolves the result back into the paused Rig run. This feature
+does not yet inject installed skills, and it does not yet implement upgrade,
+uninstall, marketplace download, or OAuth flows.
+
+Tool discovery is bounded to 15 seconds per agent submission, and one MCP tool
+execution is bounded to 30 seconds so a stalled plugin cannot indefinitely block
+turn submission or Rig's global event consumer. Before execution, Happy claims a
+45-second database lease keyed by Rig session and call ID. Other server instances
+wait for that lease or replay its completed result instead of concurrently
+invoking the same tool. The first terminal outcome, including an MCP error or
+timeout, is persisted and reused for every later event delivery; Happy does not
+automatically retry an ambiguous failure because the first request may already
+have produced an external side effect. A process crash after the MCP side effect
+but before the outcome is committed can still cause one lease-expiry replay, so
+plugin tools with external side effects should themselves be idempotent.
+
+Rig sessions use Full access so durable external functions are executable without
+an unresolved permission prompt. Agent code still runs inside Happy's dedicated,
+restricted OCI sandbox; plugin processes remain isolated in their own containers,
+and only Happy crosses the boundary after matching the durable function identity
+to a ready installation.
+
+## Package anatomy
+
+Each built-in package is a directory below `packages/happy2-server/plugins`:
+
+```text
+example-plugin/
+├── plugin.json
+├── plugin.png
+├── container/                 # optional; used by bundled stdio runtimes
+│   └── Dockerfile
+└── skills/                    # optional
+    └── example-skill/
+        ├── SKILL.md
+        ├── scripts/           # optional Agent Skills resources
+        ├── references/
+        └── assets/
+```
+
+`plugin.png` is required and must be a square PNG no larger than 4096×4096. A
+1024×1024 source is preferred; smaller square icons remain valid. Catalog
+validation calculates its byte size, dimensions, SHA-256 checksum, and
+thumbhash. When the plugin first enters the system, those fields are persisted
+on the plugin record and the exact PNG remains in the private package snapshot
+on the filesystem.
+
+Every direct child of `skills/` must follow the
+[Agent Skills specification](https://agentskills.io/specification). In
+particular, it needs `SKILL.md` with YAML frontmatter containing `name` and
+`description`; `name` must match the skill directory. Package loading rejects
+symlinks, unsafe relative paths, duplicate names, oversized packages, malformed
+frontmatter, and unexpected manifest fields before the catalog becomes
+available.
+
+`plugin.json` uses schema version 1:
+
+```json
+{
+    "schemaVersion": 1,
+    "version": "1.2.3",
+    "displayName": "Project Search",
+    "shortName": "project-search",
+    "description": "Searches source code and project documentation.",
+    "variables": [
+        {
+            "key": "PROJECT_API_TOKEN",
+            "displayName": "API token",
+            "description": "Token used by the MCP server.",
+            "kind": "secret"
+        },
+        {
+            "key": "PROJECT_REGION",
+            "displayName": "Region",
+            "description": "Region used for project queries.",
+            "kind": "text"
+        }
+    ]
+}
+```
+
+`version` uses `x.y.z` SemVer syntax. `shortName` is the stable catalog/package
+link and must match the package directory; it is not an installation identity.
+The durable system plugin and every installation receive separate CUID2 IDs.
+Variable keys are environment variable names. Every declared variable is
+required for each installation. Secret values are encrypted with AES-256-GCM
+and are never returned by catalog or installation reads; text values are stored
+as ordinary configuration. Both kinds are supplied to a stdio process as
+environment variables.
+
+A package must contain at least one skill or an `mcp` definition.
+
+The bundled `hello` package is the minimal skill-plus-MCP example. It declares no
+variables or MCP authentication, so an administrator can install it with an
+empty POST body; each call still creates a separate installation and bundled
+container.
+
+## Stdio MCP with a bundled container
+
+```json
+{
+    "mcp": {
+        "type": "stdio",
+        "command": "/plugin/bin/project-mcp",
+        "args": ["--stdio"],
+        "container": {
+            "dockerfile": "container/Dockerfile"
+        }
+    }
+}
+```
+
+The Dockerfile path is package-relative. Creating the durable system plugin
+copies the entire package once to `plugins.directory` before writing its
+database record. Each installation lifecycle builds or resolves that exact
+snapshot with the selected local Docker or Podman provider, using a
+content-addressed `happy2-plugin:<sha256>` tag. It then creates a dedicated,
+read-only container named from the installation CUID2, with `init`, all Linux capabilities
+dropped, privilege escalation disabled, bounded shared memory, and ephemeral
+`/tmp` and `/run` filesystems. Runtime resources are capped at 1 GiB of memory,
+one CPU, and 256 processes per plugin container.
+
+The resulting image must provide `/bin/sh`; Happy uses it only as the inert
+container keepalive before starting the manifest command with OCI `exec`. A
+bundled Dockerfile is responsible for copying or installing its MCP executable
+and dependencies into the image. The MCP command itself must use newline-
+delimited JSON-RPC on stdin/stdout and must not write non-protocol output to
+stdout.
+The fixed `HOME`, `TMPDIR`, and working directory are `/tmp`, so tools that
+need a cache can still run without making the image root writable.
+
+Each installation container stays alive as that installation's plugin runtime.
+Each HTTP MCP session starts
+the configured command with `docker exec`/`podman exec`; variables reach that
+process through Docker/Podman's environment-copy option. Values are never placed
+in command arguments, Happy's process environment, the long-lived container
+definition, or the image build; they exist only in the short-lived OCI CLI child
+and the MCP process. Variables that could alter the OCI client itself, such as
+`DOCKER_*`, proxy, loader, or executable-path settings, are rejected. Happy
+transparently bridges newline-delimited stdio JSON-RPC to MCP Streamable HTTP, so
+the plugin itself does not need an HTTP server.
+
+## Stdio MCP using a selected container image
+
+Omit `mcp.container` when the plugin does not bundle its own Dockerfile:
+
+```json
+{
+    "mcp": {
+        "type": "stdio",
+        "command": "npx",
+        "args": ["-y", "@example/project-mcp"]
+    }
+}
+```
+
+The install request must then include `containerImageId`. It must identify an
+agent image whose build status is already `ready`. The selected image belongs
+only to that installation and creates that installation's dedicated container;
+it does not share an agent container or another plugin installation's container.
+
+## Remote MCP
+
+```json
+{
+    "mcp": {
+        "type": "remote",
+        "url": "https://mcp.example.com/mcp",
+        "headers": {
+            "Authorization": "Bearer ${PROJECT_API_TOKEN}",
+            "X-Project-Region": "${PROJECT_REGION}"
+        }
+    }
+}
+```
+
+Remote URLs must be public HTTPS URLs without embedded credentials or fragments.
+Header templates may reference only declared variables. The health worker
+resolves templates in memory, rejects newline-bearing resolved values, applies
+the same public-address/DNS-rebinding policy used by outgoing webhooks, pins the
+approved destination address, and sends an MCP `initialize` request. The remote
+URL and templates are persisted; resolved secret headers are not.
+
+Remote MCP remains remote: Happy does not create a container or proxy its normal
+traffic. OAuth is intentionally unsupported. Authentication is limited to the
+custom static headers described above. Production remote requests are capped at
+1,000,000 bytes and responses at 256,000 bytes, matching the bounded webhook
+transport used for SSRF-safe address pinning.
+
+## Installation and lifecycle
+
+`POST /v0/admin/plugins/:shortName/installPlugin` accepts:
+
+```json
+{
+    "variables": {
+        "PROJECT_API_TOKEN": "secret value",
+        "PROJECT_REGION": "us-west"
+    },
+    "containerImageId": "optional-ready-image-id"
+}
+```
+
+The request body may be omitted when the manifest declares no variables and
+does not require a selected container image.
+
+`containerImageId` is required only for stdio manifests without a bundled
+container, and it is rejected in every other case. Unknown, missing, empty, or
+oversized variable values are rejected. The endpoint returns HTTP 202 after the
+durable system plugin (created once), immutable package/image snapshot, new
+installation, variables, audit entry, initial state, and sync event are durable.
+Calling it again for the same `shortName` creates another installation with a
+new CUID2 and its own parameters and runtime. Container preparation continues
+asynchronously.
+
+If the catalog later advertises an update, additional installations remain
+pinned to the existing system plugin's immutable manifest and package until an
+explicit upgrade action exists. Catalog reads therefore project the stored
+variable and MCP requirements for the install form while retaining the newer
+catalog version and `updateAvailable` indicator.
+
+An installation has one of these durable health states:
+
+- `preparing`: copying/reconciling package and image/container state.
+- `starting`: the container exists or remote endpoint is selected and MCP
+  initialization/health checking is in progress.
+- `ready`: the MCP server completed initialization and ping (local), or returned
+  a valid initialization response (remote). A skills-only plugin becomes ready
+  immediately after its durable install.
+- `broken_configuration`: stored variables, selected image state, manifest
+  material, or resolved headers cannot form a valid runtime configuration.
+- `failed`: package integrity, image build, container creation, process startup,
+  protocol health, DNS, or network execution failed. `lastError` contains bounded
+  diagnostic text.
+
+Every transition updates `plugin_installations`, appends a `plugin.*` sync
+event, and publishes the normal server SSE hint with the `plugins` area. Clients
+must reconcile the durable catalog after a hint; the event itself is not state.
+On server restart, every installation is reconciled again. Its package path and
+SHA-256 digest are revalidated first; local containers are then recreated from
+the installed snapshot, and remote endpoints are rechecked.
+
+## Read and MCP endpoints
+
+- `GET /v0/admin/plugins` lists the validated built-in catalog, requirements,
+  skill summaries, and MCP/container mode. When a catalog package exists in the
+  system, `systemPlugin` contains its CUID2, persisted image metadata and URL,
+  `updateAvailable`, and every independent installation with current health. It
+  requires an active server administrator and never returns configured values.
+- `GET /v0/admin/plugins/:shortName/icon` returns the package PNG to an active
+  server administrator using the catalog link.
+- `GET /v0/admin/systemPlugins` lists persisted system plugins independently of
+  the catalog, including image metadata and every linked installation.
+- `GET /v0/admin/systemPlugins/:pluginId/image` returns the persisted system
+  plugin PNG from its private filesystem snapshot after validating the package
+  digest, storage key, byte size, and image checksum.
+- `POST /v0/admin/plugins/:shortName/installPlugin` performs the durable install
+  and queues lifecycle work. It may be called any number of times; each call
+  creates a distinct installation linked to the same system plugin.
+- `GET|POST /v0/pluginInstallations/:installationId/mcp` is the authenticated
+  Streamable HTTP bridge for one ready local stdio installation. It follows MCP
+  session semantics via `Mcp-Session-Id`. Happy’s existing bearer session is
+  required; there is no plugin-specific OAuth exchange.
+
+The bridge allows at most 128 simultaneous sessions server-wide and 16 per
+authenticated user. Idle sessions close after 15 minutes; inbound requests and
+outbound server messages both renew that lifetime. A session is bound to the
+authenticated user who initialized it and cannot be reused by another user.
+
+Only GET and POST are exposed. MCP session DELETE is optional in the protocol
+and is not enabled by this API; server shutdown and transport closure clean up
+processes and sessions.
+
+## Persistence and future upgrades
+
+`plugins` records the durable CUID2, catalog short name, display metadata, source
+kind/reference and installed version, package SHA-256 digest, exact manifest,
+persistent snapshot directory, installer, and timestamps. Its image columns
+persist the filesystem storage key, content type, byte size, width, height,
+thumbhash, and SHA-256 checksum.
+
+`plugin_installations` records a separate CUID2 and foreign key to `plugins`,
+plus that instance's container/image choice, lifecycle state, error detail,
+installer, and timestamps. `plugin_installation_variables` records each declared
+value for one installation; secret rows contain authenticated ciphertext rather
+than plaintext. No installation uses `shortName` as identity.
+
+The built-in catalog and durable system plugin are deliberately independent.
+Persisted rows use `source_kind = 'builtin'` as their built-in marker. During
+startup, the server compares those rows with the current built-in catalog. If a
+bundle was removed from the server, its installations, encrypted variables,
+system-plugin row, private package/image snapshot, and any named local containers
+are removed before the remaining runtimes start. Remotely sourced plugins will
+not participate in this catalog-pruning rule.
+
+When the catalog contains a different digest for a persisted plugin's
+`shortName`, reads set `updateAvailable: true`; they do not mutate or restart its
+installations. A future upgrade action can download/validate a remote package
+into the same package abstraction, stage a new immutable package/image snapshot,
+and atomically replace the system plugin version before reconciling all linked
+installations. Until that action exists, upgrades are advertised only and the
+old snapshot continues to run.
+
+Configured installed-package storage:
+
+```toml
+[plugins]
+directory = "/var/lib/happy2/plugins"
+```
+
+The directory must be persistent and private. Plugin variables share the
+server’s generated recoverable-secret master key but use a plugin-specific
+authenticated-encryption context bound to the installation ID and variable key,
+so ciphertext cannot be replayed across integrations, installations, or fields.