# Website Design — kvsecure.com

> Design document for the kvsecure.com redesign. Plan first, build second.

## What's wrong with the current site

The current site tells a v0.1 story:
- "Encrypted secrets. Safe for AI." — vague, doesn't say HOW it's safe
- Features: "MCP Integration", "Military-grade encryption", "Security profiles" — checkbox marketing
- How it works: Encrypt → Connect → Run — misses the core innovation entirely
- No mention of: kv_api (the crown jewel), daemon model, audit logging, SSRF protection
- No mention of: why kv is different from 1Password, AgentSecrets, .env files
- "Military-grade encryption" — overused phrase that signals nothing

The site doesn't answer the one question that matters:
**"Why should I use kv instead of what I'm doing now?"**

## The core message

**"Your AI agent can use your API keys without ever seeing them."**

That's the hook. Nobody else can say this clearly:
- .env files: agent sees everything
- 1Password SDK: agent gets plaintext via secrets.resolve()
- AgentSecrets: same model as kv but HTTP-proxy, not MCP-native
- kv: daemon makes the HTTP call. Key never enters agent memory. Period.

## The visitor journey

1. **Land** — "What is this?" → One sentence: agent uses keys without seeing them
2. **How** — "How does that work?" → Diagram: agent asks daemon, daemon makes call, key stays
3. **Why** — "Why not just use .env?" → Comparison: .env leaks, 1Password gives plaintext, kv never does
4. **Try** — "Let me try it" → `pip install kv-secrets` + 4 commands
5. **Trust** — "Is this secure?" → Open source, ChaCha20, audit logging, passphrase + 2FA
6. **Go deeper** — "I want to learn more" → Link to docs/GitHub

## Site structure

```
kvsecure.com/
  index.html          Landing page (the full story)
  docs.html           Getting started + reference (single page for now)
  faq.html            FAQ (updated)
  feedback.html       Feedback form (keep as-is)
  CNAME               Domain config
```

Keep it simple. Single landing page tells the whole story. One docs page for
reference. Don't over-structure with /blog /pricing /about until there's content
for them. Future expansion is easy — add pages, add nav links.

## Landing page sections

### 1. Hero
**Headline:** "Your AI agent uses your API keys. It should never see them."
**Subline:** "kv encrypts your secrets and lets AI coding agents make API calls
without possessing the keys. Like ssh-agent, but for API credentials."
**CTA:** `pip install kv-secrets` + "See how it works"

Why this works: states the problem (agent uses keys) and the solution (without
seeing them) in one breath. The ssh-agent comparison gives instant credibility
with developers.

### 2. The problem (short, visual)
Three columns showing the bad patterns:
- ".env file" → agent reads it, key in context window, leaked in logs
- "1Password SDK" → secrets.resolve() returns plaintext to agent memory
- "Paste in chat" → key in conversation history forever

One line: "Every approach gives the agent your key. kv doesn't."

### 3. How kv works (the diagram)
The ssh-agent model, visually:

```
Agent: "Call OpenAI with this prompt"
  ↓
kv daemon: looks up OPENAI_API_KEY, adds auth header, makes HTTP call
  ↓
Agent gets: response body (key never appeared)
```

Show the actual MCP tool call:
```
kv_api(provider="openai", path="/v1/chat/completions", body={...})
```

Key callout: "The API key stays in the daemon's memory. It never enters
the agent's process, context window, logs, or filesystem."

### 4. Get started (4 steps)
```bash
pip install kv-secrets
kv init                    # Create vault (passphrase prompt)
kv set OPENAI_API_KEY      # Store your key (hidden input)
kv unlock                  # Start the daemon
```

"Now your AI agent can use kv_api to make authenticated API calls.
The key stays in the daemon."

### 5. What else it does (feature grid, updated)
- **Dynamic providers** — Add any API: Stripe, Twilio, SendGrid. Not just the built-in five.
- **Tamper-evident audit log** — Every API call logged. Hash-chain integrity. `kv audit --verify`.
- **Passphrase + 2FA** — Interface barrier agents can't bypass. Same model as ssh-agent.
- **kv_run for databases** — Need env vars for Postgres, Redis, AWS? Sandboxed execution with redaction.
- **Client-agnostic** — Claude Code, Cursor, VS Code. Any MCP client. Same security.
- **SSRF protection** — Custom providers validated against private IPs and non-HTTPS.

### 6. Comparison table
| | kv | .env files | 1Password CLI | AgentSecrets |
|---|---|---|---|---|
| Key never enters agent memory | kv_api | No | No | Yes |
| MCP native | Yes | No | No | Added later |
| Subprocess sandbox (databases) | kv_run | No | No | No |
| Tamper-evident audit | Yes | No | Enterprise | No |
| Passphrase + 2FA | Yes | No | Via app | No |
| Free, open source | Yes | Yes | No | Partial |
| Dependencies | 1 | 0 | Many | Go stdlib |

### 7. Security model (brief)
Three layers:
1. Passphrase barrier — agents can't enter interactive prompts
2. Daemon isolation — keys in memory, never exported
3. Defense-in-depth — SSRF protection, redaction, file scanning, hooks

Link to detailed security docs.

### 8. Pricing
"Free for individuals. Team sync coming soon."
Email signup for team tier waitlist. Don't show $15 pricing until
the server is deployed and the tier actually works.

### 9. Footer
GitHub, PyPI, MIT license, version.

## Design principles

- **Dark theme** — current site has a good dark theme, keep it
- **Code-first** — show terminal examples, not marketing copy
- **Fast** — single HTML file, no JS frameworks, no build step
- **Honest** — don't claim things we can't deliver (no "team sync" as a feature)
- **Scannable** — developer attention span is 10 seconds. Hook them in 10 seconds.

## What NOT to do

- Don't use "military-grade encryption" — overused, meaningless
- Don't list features without explaining why they matter
- Don't show pricing for features that don't exist yet
- Don't add a blog section with zero posts
- Don't add JavaScript beyond minimal scroll animations
- Don't use stock photos or illustrations — code examples are the visuals

## Future expansion (not now)

- `/docs` — full documentation site (when there's enough content)
- `/blog` — release notes, security advisories
- `/pricing` — when team tier launches
- `/security` — detailed security model page
- Customer logos / testimonials (when there are customers)
