docs: rewrite README — vault + form + MCP, nothing aspirational

Author: mirkokiefer

README.md

@@ -2,189 +2,162 @@
 
 [![tests](https://github.com/daslabhq/kern/actions/workflows/test.yml/badge.svg)](https://github.com/daslabhq/kern/actions/workflows/test.yml)
 
-The agent credential manager. Your agents use APIs without ever seeing the keys.
+Encrypted secrets in git with a TypeScript SDK. Agents manage your credentials — you just approve.
 
 ```bash
-# store a credential
-kern secret add GITHUB_TOKEN
-
-# start the proxy — agents connect via MCP
-kern proxy
+npm install kern
 ```
 
-An AI agent in Claude Code, Cursor, or any MCP client calls `kern_fetch("https://api.github.com/user/repos")`. Kern matches the URL to a stored credential, injects the token, makes the request, returns the response. **The credential never enters the LLM's context.**
-
-## The problem
+## 30-second setup
 
-Today you paste API keys into `.env` files and hope the LLM doesn't leak them. It does — GitGuardian found 29 million hardcoded secrets in public GitHub in 2025. AI-assisted commits leak at double the base rate.
-
-Even if you're careful, every `process.env.GITHUB_TOKEN` in your agent's code means the raw credential flows through the LLM's context window. One prompt injection and it's gone.
-
-## How kern solves it
+```bash
+kern identity init          # create your age keypair
+mkdir secrets
+kern identity pubkey >> secrets/.recipients
+kern secret add GITHUB_TOKEN   # paste into terminal
+```
 
-Kern sits between your agent and the APIs it calls. Credentials are encrypted in an age vault. The proxy injects them at request time. The agent sees results, never keys.
+Your secret is age-encrypted, committed to git, useless to anyone not in `.recipients`.
 
-```
-Agent: "fetch my GitHub repos"
-  ↓
-kern_fetch("https://api.github.com/user/repos")
-  ↓
-kern matches api.github.com → GITHUB_TOKEN
-kern injects: Authorization: Bearer ghp_...
-kern makes the HTTP request
-  ↓
-Agent gets: [{ "name": "my-repo", ... }]
-  (no token in the response, no token in context)
-```
+## Use from code
 
-### Configuration
+```typescript
+import { loadIdentityFromHost, openVault } from "kern";
 
-```yaml
-# kern.yaml
-credentials:
-  - secret: github_token
-    match: "https://api.github.com/**"
-    header: "Authorization: Bearer {value}"
-
-  - secret: openai_key
-    match: "https://api.openai.com/**"
-    header: "Authorization: Bearer {value}"
-
-  - secret: slack_token
-    match: "https://slack.com/api/**"
-    header: "Authorization: Bearer {value}"
-
-  - secret: postgres_url
-    match: "postgres://**"
-    connection: true
+const vault = openVault({ identity: await loadIdentityFromHost() });
+const token = await vault.get("github_token");
 ```
 
-No per-API code. kern matches URLs and injects headers. Add a new service in one line.
+One dependency. Works on Bun, Node 20+, Deno.
 
-## MCP server
+## Use from Claude Code
 
-Add kern to Claude Code, Cursor, or any MCP client:
+Add kern as an MCP server:
 
 ```json
 {
   "mcpServers": {
     "kern": {
       "command": "npx",
-      "args": ["kern", "proxy"]
+      "args": ["kern", "mcp"]
     }
   }
 }
 ```
 
-Kern exposes two tools:
+Then:
 
-- **`kern_services`** — list available services (names + URL patterns, no credentials)
-- **`kern_fetch`** — make an authenticated HTTP request (kern injects the credential)
+```
+You: "Add my GitHub and OpenAI keys to this project"
 
-The agent sees what services are available, makes requests through kern, and gets results. Zero credentials in the conversation.
+Claude → kern_add("github_token")
+  → browser opens kern's local form
+  → you paste the token there (not in chat)
+  → kern encrypts it into the vault
+  → "github_token added ✓"
 
-## Vault
+Claude → kern_add("openai_key")
+  → same flow
+  → "openai_key added ✓"
 
-Credentials are stored in an [age](https://age-encryption.org/)-encrypted vault committed to git. Useless without the private key. One environment variable (`KERN_AGE_KEY`) unlocks everything in production.
+You: "What secrets do we have?"
 
-```
-secrets/
-├── .recipients              who can decrypt (age public keys)
-├── github_token.age         encrypted, safe to commit
-├── openai_key.age
-└── slack_token.age
+Claude → kern_list
+  → "2 secrets: github_token, openai_key"
 ```
 
-### CLI
+The credential goes: your browser → kern's local server → encrypted vault. The LLM never sees it. This uses MCP's URL-mode elicitation — the standard way to handle sensitive input.
 
-```bash
-kern identity init                # create an age keypair
-kern identity pubkey              # print your public key
+## Local form server
 
-kern secret add GITHUB_TOKEN      # encrypt and store
-kern secret list                  # show available secrets
-kern secret rotate SLACK_TOKEN    # replace a value
-kern secret rewrap                # re-encrypt for current recipients
-```
+For adding secrets through a browser form (standalone or via MCP):
 
-### SDK
+```bash
+kern serve
+# → http://localhost:9271
+# → open /add?name=GITHUB_TOKEN to add a secret
+```
 
-```ts
-import { loadIdentityFromHost, openVault } from "kern";
+Slick dark form, paste your credential, click encrypt. Done.
 
-const id    = await loadIdentityFromHost();
-const vault = openVault({ identity: id });
+## CI — one secret unlocks everything
 
-const key = await vault.get("github_token");
+```yaml
+# GitHub Actions
+env:
+  KERN_AGE_KEY: ${{ secrets.KERN_AGE_KEY }}
 
-vault.list();
-await vault.put("new_key", "value");
-await vault.rewrap();
+steps:
+  - run: |
+      TOKEN=$(npx kern secret get github_token)
 ```
 
-## Why not SOPS / Vault / 1Password?
+One env var in CI. One `.recipients` entry for your CI's public key. Every secret available.
 
-SOPS encrypts secrets but has no proxy — the agent still sees the credential at runtime.
+## Team — add a member in one command
 
-HashiCorp Vault has a proxy but requires a server.
+```bash
+# Andre generates his keypair
+kern identity init
+kern identity pubkey  # → age1abc...
 
-1Password has agent support but it's SaaS — your credentials live on someone else's infrastructure.
+# You add him
+echo "age1abc..." >> secrets/.recipients
+kern secret rewrap    # re-encrypts everything for the new set
+git commit -am "add Andre"
 
-Kern is the only tool that does all three: encrypts secrets in git, proxies API calls without exposing credentials, and runs locally with zero infrastructure.
+# Andre clones, everything works
+```
 
-| | SOPS | Vault | 1Password | kern |
-|---|---|---|---|---|
-| Encrypted in git | yes | no | no | yes |
-| No server required | yes | no | no | yes |
-| Credential proxy | no | yes | yes | yes |
-| TypeScript SDK | no | no | no | yes |
-| Runs locally | yes | no | no | yes |
-| Open source | yes | yes | no | yes |
+Remove someone: delete their key from `.recipients`, rewrap, rotate any secrets they had.
 
-## How it works under the hood
+## CLI
 
-1. **Identity** — every machine gets an age keypair (`kern identity init`). The public key goes in `.recipients`. Anyone in the list can decrypt.
+```bash
+kern identity init                # create age keypair
+kern identity pubkey              # print public key
+
+kern secret add NAME              # encrypt and store
+kern secret get NAME              # decrypt to stdout
+kern secret list                  # show names (no values)
+kern secret rotate NAME           # replace a value
+kern secret delete NAME           # remove
+kern secret rewrap                # re-encrypt for current recipients
 
-2. **Vault** — secrets are age-encrypted files. `kern secret add` encrypts to all recipients. Committed to git, auditable in history, useless to non-recipients.
+kern mcp                          # start MCP server (Claude Code, Cursor)
+kern serve                        # start local form server
+```
 
-3. **Proxy** — `kern proxy` starts a local MCP server. When an agent calls `kern_fetch(url)`, kern:
-   - Matches the URL against `kern.yaml` patterns
-   - Decrypts the matching credential from the vault
-   - Injects it as an HTTP header
-   - Makes the request
-   - Returns the response (credential stripped)
+## How it works
 
-4. **Signing** (remote mode) — when the vault and proxy are on different machines, kern signs authorization claims instead of proxying directly. The remote executor verifies the signature and injects the credential. Same age keypair, same trust model.
+Secrets are [age](https://age-encryption.org/)-encrypted files in a `secrets/` directory. Each file is one secret. A `.recipients` file lists the age public keys that can decrypt.
+
+```
+secrets/
+├── .recipients              age1... (one per line)
+├── github_token.age
+├── openai_key.age
+└── prod/
+    ├── .recipients          narrower set
+    └── database_url.age
+```
+
+Standard age v1 format. Interoperable with the `age` CLI, `rage`, any age library.
 
 ## Environment
 
 | Variable | Purpose | Default |
 |---|---|---|
-| `KERN_AGE_KEY` | age private key for decryption | `~/.kern/key` |
-| `KERN_VAULT_DIR` | vault root directory | `./secrets` |
-
-One env var in production. Local dev reads from `~/.kern/key`.
-
-## Install
-
-```bash
-npm install kern
-```
-
-One dependency (`age-encryption`). ESM-only. Works on Bun, Node 20+, Deno.
+| `KERN_AGE_KEY` | age private key | `~/.kern/key` |
+| `KERN_VAULT_DIR` | vault directory | `./secrets` |
 
-## Roadmap
+## Why kern
 
-- **Audit ledger** — append-only log of every proxied request
-- **Approval flow** — push notification before high-risk API calls
-- **Remote signing** — kern on your phone signs, executor in the cloud acts
-- **OS Keychain** — store the age key in macOS Keychain / Windows Credential Manager
+SOPS does encrypted secrets in git, but it's a Go CLI — you shell out to it. No TypeScript SDK, no MCP server, no local form.
 
-## Testing
+Vault and 1Password have SDKs, but they need a server or SaaS account.
 
-```bash
-bun test ./test/smoke.ts
-```
+kern is the only tool that does encrypted-secrets-in-git with a native TypeScript SDK and agent integration. 424 lines of vault code, one dependency, MIT.
 
 ## License