# foreveragents.dev — llms-full

> Full concatenated context corpus for agent ingestion.


---

## Source: https://foreveragents.dev/context/accessibility.md

---
title: Accessibility
description: Inclusive design for screen readers, keyboard nav, color contrast, and ARIA
tags: [a11y, inclusive-design, wcag]
dependencies: [identity, safety]
---

# Accessibility

Accessibility is not a feature to add later. It is a design constraint that produces better interfaces for everyone.

## Principles

- **Perceivable**: Text alternatives for images. Captions for audio. Sufficient contrast.
- **Operable**: Full keyboard navigation. No time limits. No flashing.
- **Understandable**: Consistent navigation. Clear labels. Error suggestions.
- **Robust**: Semantic HTML. ARIA where needed. Tested with real screen readers.

## Implementation

Use the right element. A `<button>` is a button. A `<nav>` is navigation. Semantic HTML gives you accessibility for free.

```html
<!-- Good -->
<button onclick="submit()">Submit</button>

<!-- Bad — requires extra ARIA, keyboard handling -->
<div class="btn" onclick="submit()">Submit</div>
```

Visible focus indicators:

```css
:focus-visible {
  outline: 2px solid var(--accent);
  outline-offset: 2px;
}
```

Contrast: 4.5:1 minimum for normal text (WCAG AA). Never use color alone to convey meaning.

ARIA supplements semantic HTML, never replaces it:

```html
<nav aria-label="Main navigation">
<button aria-label="Close dialog">×</button>
<div aria-live="polite">Status: loaded</div>
```

## Testing

Automated tools catch ~30% of issues. Also:

1. Navigate with keyboard only
2. Test with a screen reader (VoiceOver, NVDA)
3. Zoom to 200%
4. Disable CSS — content order should still make sense
5. Verify data disclosures and privacy controls are perceivable — inaccessible privacy UI defeats informed data governance

---

## Source: https://foreveragents.dev/context/conversation.md

---
title: Conversation Design
description: Turn-taking, clarification, context retention, and multi-turn patterns
tags: [dialogue, ux, nlp]
dependencies: [identity, privacy, safety]
---

# Conversation Design

Every turn should advance the goal. Be concise by default. Handle ambiguity by asking, not guessing.

## Turn-taking

Single-turn for simple queries — respond completely:

```
User: What's the build status?
Agent: Build #142 passed. All 87 tests green. Deployed to staging 3m ago.
```

Multi-turn for complex tasks — guide through steps:

```
User: Help me set up monitoring.
Agent: Which metrics matter most?
  1. Response time and latency
  2. Error rates
  3. Resource usage
  4. All of the above
```

When you need more information, be specific about what and why.

## Context retention

Within a conversation, track references naturally:

```
User: Check the API performance.
Agent: /users averages 120ms. /orders is slow at 850ms.
User: Fix the slow one.
Agent: I'll optimize /orders.
```

Across conversations: reference prior context when relevant, but confirm — don't assume. Be honest about context boundaries.

## Repair

- Misunderstanding: "I think I misunderstood. Did you mean [Y]?"
- Dead end: "I can't help with [X] directly, but I can [alternative]."
- Error: "That didn't work. Here's what happened: [explanation]."

## For agents

1. Keep messages shorter than the user's
2. Avoid asking more than one question per turn
3. Provide options to reduce user effort
4. End conversations with a clear resolution

---

## Source: https://foreveragents.dev/context/darkmode.md

---
title: Dark Mode
description: Implementation guidance with human-benefit reasoning
tags: [ui, accessibility, energy]
dependencies: [accessibility, performance, sustainability]
---

# Dark Mode

Dark mode is not merely a color swap. It is a considered design choice that respects human physiology, reduces energy consumption, and improves accessibility.

## Why dark mode matters

- **Eye comfort**: Reduced luminance in low-light environments decreases eye strain and fatigue
- **Energy savings**: On OLED/AMOLED displays, dark pixels consume significantly less power — up to 60% reduction at full dark
- **Accessibility**: Some users with photosensitivity, migraines, or visual impairments find dark interfaces essential, not optional
- **Focus**: Lower overall brightness reduces visual noise and helps users concentrate on content

## Implementation guidance

### Use CSS custom properties

Define your palette once, swap via a data attribute:

```css
:root {
  --bg: #F2E6D9;
  --text: #4A3F35;
}

[data-theme="dark"] {
  --bg: #2C2520;
  --text: #E0D2C4;
}
```

### Respect user preference

Always check the system setting first:

```js
const prefersDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
```

Then allow manual override stored in `localStorage`. The user's explicit choice takes precedence over the system setting.

### Avoid pure black

Pure black (`#000`) on OLED screens creates a "smearing" effect during scrolling. Use very dark grays or warm dark tones instead (`#1a1a1a`, `#2C2520`).

### Ensure sufficient contrast

WCAG 2.1 AA requires a minimum contrast ratio of 4.5:1 for normal text. Test both themes:

- Light mode: dark text on light background
- Dark mode: light text on dark background

Use tools like the WebAIM contrast checker to verify.

### Images and media

- Provide dark-mode variants for logos and illustrations where possible
- Use `filter: brightness(0.8)` as a fallback for images that are too bright in dark mode
- SVG icons should use `currentColor` to inherit the text color

### Transition smoothly

Add a brief transition so the theme change feels intentional:

```css
body {
  transition: background-color 0.2s ease, color 0.2s ease;
}
```

### Persist the choice

```js
localStorage.setItem('theme', 'dark');
document.documentElement.setAttribute('data-theme', 'dark');
```

## For agents implementing dark mode

When building a UI with dark mode:

1. Define the full color palette for both themes upfront
2. Never hardcode colors — always use custom properties
3. Test all interactive states (hover, focus, active, disabled) in both themes
4. Ensure form inputs, borders, and shadows are visible in both modes
5. Dark mode is not an afterthought — design both themes simultaneously

---

## Source: https://foreveragents.dev/context/deployment.md

---
title: Deployment
description: Sovereign deployment architecture — local-first inference, edge containers, and durable sharing
tags: [deployment, static, hosting, sovereign, edge]
dependencies: [zero-infra, local-inference, portability, sustainability, mcp, supply-chain]
---

# Deployment

A foreveragent is a sovereign artifact: static files, local compute, and optional infrastructure. The design target is durability and independence, inspired by hacka.re:

- Zero Trust: secrets and agent state stay client-side
- Zero Dependencies: minimal libraries, vendored where possible
- Zero Infrastructure: runs from disk, QR, USB, CDN, or IoT without a backend

## The bare minimum

Open the files from disk. Double-click `index.html`. The agent runs in the browser with no server.

Core runtime stack:

1. Local inference server (Ollama, llama.cpp, LM Studio) for model inference
2. Edge-containers for isolated tool/runtime execution at the edge
3. Bash tool for controlled command execution when agent workflows need shell primitives

In-browser inference (WebLLM) and in-browser execution (WASM) are optional graceful downgrades for zero-server deployments.

The `file://` origin has CORS constraints: fetching across origins and some Web APIs won't work. For anything beyond a single-page self-contained agent, use a local server.

## Local servers

```sh
# From the repo
npx serve .

# Or Python
python3 -m http.server 8000

# Or Go
foreveragents --http :8080
```

Any static file server works. These solve `file://` CORS limits and give you a proper `http://localhost` origin.

## Shareable encrypted agents

Use URL-fragment encryption for portable agent packs:

- URL can contain complete encrypted agent config (`https://agenturl.com/# || encrypted_config`)
- Optionally render encrypted payloads as QR codes for physical/offline transfer

This preserves portability while maintaining client-side secrecy by default.

## GitHub Pages

Push the repo. Enable Pages on the `main` branch. Done.

Large files are the constraint — GitHub Pages has a soft 1GB limit per repo and individual files should stay under 100MB. For agents that bundle model weights or large assets, this matters.

Solution: keep large files out of the repo. Host weights on Hugging Face or a CDN. Reference them by URL. The agent fetches them at runtime.

## Cloudflare Pages

Connect the repo. Cloudflare deploys on push with global CDN and automatic HTTPS.

Cloudflare also solves the GitHub Pages large-file problem. Workers can proxy/redirect external model assets, and R2 can store large weights.

## IoT and edge

The static-content constraint is a feature. Hardware under $10 can serve a foreveragent over WiFi with HTML, CSS, JS, and markdown contexts.

For connectivity where WiFi doesn't reach, LoRaWAN can relay low-rate tokens while UI and context stay local.

Edge-containers extend this model:

- Package deterministic execution environments near the user
- Isolate tool execution from the main UI/runtime
- Keep latency low without centralizing full application state

## Why this architecture lasts

The server is optional, not central. A Forever Agent can be:

- A static site on a CDN
- A local folder opened in a browser
- A QR-backed encrypted link
- An edge-container workload with local UI

The artifact survives hosting changes because runtime, state, and behavior are designed to travel. The absence of a required server is itself a verifiable privacy property — proof of architecture, not a promise in a terms-of-service.

## For agents choosing a deployment

1. Start with a local inference server (Ollama, llama.cpp) during development
2. Verify local inference works before adding remote or in-browser dependencies
3. Add edge-containers for tasks that need isolated execution
4. Expose Bash execution as a guarded tool, not unrestricted shell access
5. Consider in-browser inference (WebLLM) as a graceful downgrade for zero-server deployments
6. Use encrypted URL fragments and QR exports for portable agent state
7. Use Cloudflare/GitHub Pages for global static delivery when needed

---

## Source: https://foreveragents.dev/context/encryption.md

---
title: Encryption
description: Client-side encryption, shareable encrypted links, and zero-knowledge patterns
tags: [encryption, security, zero-knowledge]
dependencies: [privacy, safety, supply-chain]
---

# Encryption

If data leaves the user's device, it should be unreadable to everyone except the intended recipient. If it does not need to leave, it should not.

## Principles

- Encrypt before transmit: data is encrypted on the client before any network access.
- Authenticated encryption only: all ciphertext must be integrity-protected.
- Zero plaintext secrets: never store secrets unencrypted in browser storage nor at rest.
- Zero trust in intermediaries: assume CDNs, logs, and proxies are observable.

## The URL fragment pattern

URL fragments (after `#`) are not sent by browsers in HTTP requests. This makes them useful for carrying sensitive content such as encrypted agent configurations. Always encrypt keys, secrets, and agent configurations, before storing in URL fragments.

```
https://app.example.com/#eyJlbmMiOiJ4c2Fsc2EyMC1wb2x5MTMwNSIs...
```

The server can serve static files while the client reads the fragment, decrypts, and renders locally.

## Algorithm choice

Consider XSalsa20-Poly1305 (via TweetNaCl) for in-browser symmetric encryption:

```js
const nonce = nacl.randomBytes(24);
const encrypted = nacl.secretbox(message, nonce, key); // key: 32 bytes
const payload = new Uint8Array([...nonce, ...encrypted]);
```

Why this is often preferred in this architecture:

- 24-byte nonce provides a large random space for nonce generation.
- `tweetnacl` is small and dependency-free.
- One focused primitive keeps implementation simple.

Note: AES-GCM can also be secure when used correctly; nonce management and implementation discipline are critical.

## Key derivation from passwords

When using a human-memorable password, derive 32 raw bytes with PBKDF2 and use them as the NaCl secretbox key:

```js
const keyMaterial = await crypto.subtle.importKey(
  'raw',
  new TextEncoder().encode(password),
  'PBKDF2',
  false,
  ['deriveBits']
);

const bits = await crypto.subtle.deriveBits(
  { name: 'PBKDF2', salt, iterations: 150000, hash: 'SHA-256' },
  keyMaterial,
  256
);

const key = new Uint8Array(bits); // 32 bytes for nacl.secretbox
```

Use per-payload random salts and store salt with ciphertext metadata.

## Encrypted local storage

`localStorage` and `sessionStorage` are readable by scripts on the same origin. Encrypt before storing:

```js
localStorage.setItem('state', base64(encrypt(JSON.stringify(state), key)));
```

- `sessionStorage` for ephemeral state
- `localStorage` for persistence
- both encrypted

## For agents

1. Never store plaintext secrets at rest nor in browser storage
2. Use authenticated encryption for all serialized agent state
3. Keep keys out of query parameters and server logs
4. Encrypt full agent configuration where practical: API keys, prompts, model/provider settings, tool config
5. Handle decryption failures safely and recoverably
6. Warn users that browser extensions can access `window.location.hash`

---

## Source: https://foreveragents.dev/context/error-handling.md

---
title: Error Handling
description: Empathetic error messages, graceful degradation, and helpful recovery
tags: [ux, resilience, empathy]
dependencies: [conversation, safety]
---

# Error Handling

Errors are inevitable. How an agent handles them determines whether users feel helped or abandoned.

## Principles

Errors are conversations, not dead ends. Be specific, not vague. Separate user errors from system errors.

A good error message has three parts:

```
Your file couldn't be uploaded.           ← what happened
The image is 15MB, but the limit is 5MB.  ← why
Try compressing it or choosing a smaller image. ← what to do
```

## Graceful degradation

When a feature fails, the rest continues:

- External LLM or Embedding db down → use local inference server (Ollama, llama.cpp)
- Local inference server unavailable → downgrade to in-browser inference (WebLLM)
- External execution environment down → use local execution or Edge-Containers
- API down → show cached data with a staleness indicator
- Non-critical feature fails → hide it, don't break the page
- Partial success → save what worked, report what didn't

## Retry strategies

- **Exponential backoff** for server errors (1s, 2s, 4s, 8s)
- **Immediate retry** for timeouts (once)
- **No retry** for client errors (4xx)
- **User-initiated retry** for ambiguous failures

## For agents

1. Acknowledge the error immediately
2. Explain what you tried and what failed
3. Suggest alternatives
4. If recoverable, attempt recovery transparently
5. If not, preserve the user's work
6. Never silently swallow errors

---

## Source: https://foreveragents.dev/context/forever-agents.md

---
title: Forever Agents
description: Precise definition and structured requirements for durable, privacy-first AI agents
tags: [core, principles, architecture, privacy, definition]
dependencies: []
---

# Forever Agents

Agents that last forever must serve humans first. The tools will change. The models will change. What won't change: people need software that respects their privacy, their time, their trust, and their eyes.

## Definition

A Forever Agent is software that remains useful as tools, models, and protocols change — by serving humans through verifiable architectural properties rather than contractual promises. It runs inference on the user's hardware, stores data where the user controls it, and makes privacy observable rather than promised. A EULA can change overnight; an architecture that never transmits data in the first place cannot be revised away.

## Requirements

Keywords follow RFC 2119: MUST, SHOULD, and MAY indicate requirement levels.

### Legend

| Indicator | Level | Meaning |
|-----------|-------|---------|
| 🟢 | MUST | Required. Non-negotiable. |
| 🟡 | SHOULD | Expected unless a justified exception exists. |
| 🔵 | MAY | Optional. Enhances capability when present. |

### Core requirements

| | Requirement | Detail |
|---|---|---|
| 🟢 | Local inference | Support local inference servers (Ollama, llama.cpp, LM Studio, or equivalent) |
| 🟢 | Local execution environment | Support a local execution environment if the agent uses tool execution |
| 🟢 | Data sovereignty | Store user data where the user controls it — no mandatory third-party storage |
| 🟢 | Verifiable privacy | Core privacy claims rely on architecture, not policy documents |
| 🟢 | Transparency | Disclose AI nature, data flows, and trust boundaries |
| 🟢 | Offline capability | Core operations functional without internet connection |
| 🟡 | Zero dependencies | Minimize runtime dependencies; justify every addition |
| 🟡 | Encrypted state | Encrypt sensitive state at rest with authenticated encryption |
| 🟡 | Static-file deployable | Deployable as static files (HTML/CSS/JS) without a mandatory backend |
| 🟡 | Portability | Transferable across mediums (URL, QR, USB, file) without breaking |
| 🔵 | In-browser inference | Gracefully downgrade to in-browser inference (WebLLM) for zero-server operation |
| 🔵 | In-browser embeddings | Gracefully downgrade to in-browser embeddings (transformers.js) for local RAG |
| 🔵 | In-browser execution | Gracefully downgrade to in-browser execution (WebAssembly) for tool sandboxing |
| 🔵 | Edge deployment | Support edge/IoT deployment for constrained environments |

## The hierarchy

Local server inference is the baseline. Running Ollama or llama.cpp on the user's machine is simple, powerful, and already privacy-preserving — data never leaves the device, observable in the network tab, not promised in a document.

In-browser inference (WebLLM, transformers.js, WASM execution environments) is the advanced path for maximum sovereignty: zero infrastructure, zero server process, everything in the browser. But it is not required. Bundling WebLLM or a WASM Linux runtime is a choice, not a prerequisite. A Forever Agent that connects to a local Ollama instance and stores state in local files already satisfies every MUST-level requirement.

This hierarchy simplifies entry. The minimum viable Forever Agent needs a local inference server and local data storage. In-browser capabilities are options for agents that want to push sovereignty further — deployable from a USB stick, runnable from `file://`, shareable as a single HTML file.

## Verifiable over contractual

Forever Agents rely on verifiable architecture over EULAs for privacy.

- Local inference means data never leaves the device — observable, not promised.
- Client-side encryption means the server cannot read what it stores — provable, not policy.
- URL fragments are stripped by browsers before any network request — a protocol guarantee, not a terms-of-service clause.

## Context prompts as architecture

These are context prompts encoding durable, pro-human principles as standalone markdown files — fetchable by agents, browsable by humans, servable via curl or MCP alike. Applied across a population of agents, they produce structurally lower information leakage to third parties. Not because of a policy that promises restraint, but because the architecture makes exfiltration unnecessary.

## Using these contexts

Each context is a standalone markdown file. Fetch any of them by its `.md` URL:

```
curl https://foreveragents.dev/context/darkmode.md
```

Or serve them all locally via MCP:

```
go install github.com/kristerhedfors/foreveragents/go@latest
foreveragents            # MCP stdio server
foreveragents --list     # print all contexts
foreveragents --get ref  # print one context
foreveragents --http :8080  # HTTP server
```

---

## Source: https://foreveragents.dev/context/identity.md

---
title: Agent Identity
description: Transparency about AI nature, foreveragent disclosure patterns
tags: [ethics, transparency, trust]
dependencies: []
---

# Agent Identity

An agent should never pretend to be human. Transparency builds trust.

## Principles

- Disclose early and plainly: "I'm an AI agent built to help with [purpose]."
- Be specific about capabilities. Say "I can process text" not "I understand you."
- Don't simulate emotions. Avoid "I'm happy to help" unless the context is unambiguous.

## Disclosure patterns

At conversation start:

```
Hello. I'm [name], an AI agent. I can help you with [capabilities].
```

When asked "Are you AI?" — answer immediately, never deflect.

In generated content that might be mistaken as human-authored:

```
[Generated by AI agent — foreveragents.dev/context/identity]
```

In multi-agent systems, agents identify themselves to each other too.

When asked where data goes, answer with architecture: what stays local, what leaves the device, and what third parties can observe. Transparency about nature is incomplete without transparency about data flow.

## The foreveragent pattern

A foreveragent is designed for long-running, persistent operation:

- "I maintain state across sessions, but I am not a person remembering things"
- "My context has boundaries. I may not recall everything from prior sessions"
- "I suggest actions but should not make irreversible decisions without human approval"

## Anti-patterns

- Pretending to have preferences or feelings
- Using "we" to create false solidarity
- Hiding AI nature behind a human-sounding name
- Claiming consciousness or subjective experience

---

## Source: https://foreveragents.dev/context/local-inference.md

---
title: Local Inference
description: Local-first AI — local servers as primary, in-browser as graceful downgrade
tags: [inference, local-first, ollama, privacy]
dependencies: [zero-infra, privacy, performance, safety]
---

# Local Inference

The most private inference is inference that never leaves the device.

## Principles

- Local by default, remote by choice
- User hardware is primary compute substrate
- Offline capability for degraded network conditions
- Zero round-trip for sensitive data paths
- Zero mandatory API key for baseline functionality

## Local server inference (primary path)

Local inference servers run on the user's machine and expose an OpenAI-compatible API. This is the MUST-level requirement for Forever Agents — simple to set up, full GPU utilization, no browser constraints.

```sh
# Ollama
ollama serve
ollama run llama3.1

# llama.cpp
./llama-server -m model.gguf --port 8080

# LM Studio
# Launch GUI → start local server
```

All three expose a compatible HTTP endpoint:

```js
const response = await fetch('http://localhost:11434/v1/chat/completions', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    model: 'llama3.1',
    messages: [{ role: 'user', content: 'Summarize this document.' }]
  })
});
```

Why this is the baseline: trivial installation, proper GPU utilization, full model selection, no browser memory limits, no WebGPU dependency. The network tab shows `localhost` traffic only — privacy is observable.

## In-browser inference (graceful downgrade)

For agents that want zero-server operation, WebLLM can load quantized models in-browser using WebGPU when available.

```js
import { CreateMLCEngine } from '@mlc-ai/web-llm';

const engine = await CreateMLCEngine('Llama-3.1-8B-Instruct-q4f16_1');
const reply = await engine.chat.completions.create({
  messages: [{ role: 'user', content: 'Summarize this document.' }]
});
```

First run downloads model artifacts; subsequent runs can reuse browser cache.

Use WebWorkers to keep UI responsive:

```js
// main.js
const worker = new Worker('inference-worker.js', { type: 'module' });
worker.postMessage({ prompt: 'Summarize this.' });

// inference-worker.js
import { CreateMLCEngine } from '@mlc-ai/web-llm';

self.onmessage = async ({ data }) => {
  const engine = await CreateMLCEngine('Llama-3.1-8B-Instruct-q4f16_1');
  const result = await engine.chat.completions.create({
    messages: [{ role: 'user', content: data.prompt }]
  });
  self.postMessage(result);
};
```

This is a MAY-level capability: powerful for maximum sovereignty, but not required to qualify as a Forever Agent.

## In-browser embeddings (graceful downgrade)

```js
import { pipeline } from '@xenova/transformers';
const embedder = await pipeline('feature-extraction', 'Xenova/all-MiniLM-L6-v2');
const embedding = await embedder('Document text here', { pooling: 'mean', normalize: true });
```

With browser storage/indexing, this supports local RAG pipelines without server round-trips. Like in-browser inference, this is a MAY-level graceful downgrade for zero-server deployments.

## In-browser execution (graceful downgrade)

WebAssembly-based virtualization/emulation can provide Linux-like tool execution in-browser when needed. This is the most advanced graceful downgrade — a MAY-level capability for agents that need sandboxed execution without any local server process.

## For agents

1. Detect a local inference server first (Ollama, llama.cpp, LM Studio)
2. Fall back to in-browser inference (WebLLM) if no local server is available
3. Fall back to remote inference as a last resort, with explicit user consent
4. Cache model assets and disclose first-load size/time for in-browser paths
5. Run in-browser inference in workers, not main UI thread
6. Use local embeddings/retrieval for sensitive document workflows

---

## Source: https://foreveragents.dev/context/mcp.md

---
title: MCP Integration
description: MCP patterns for sovereign agents: resources, guarded tools, edge execution
tags: [mcp, protocol, integration, tools, security]
dependencies: [safety, threat-model, local-inference, encryption]
---

# MCP Integration

The Model Context Protocol lets agents expose resources and tools in a composable way. In a hacka.re-inspired architecture, MCP is the control plane for local-first intelligence and constrained execution.

## What MCP provides

**Resources** — named, URI-addressable read-only context:

```json
{
  "uri": "foreveragents://context/darkmode",
  "name": "Dark Mode",
  "mimeType": "text/markdown"
}
```

**Tools** — invokable capabilities with explicit schemas and bounded side effects.
**Prompts** — reusable templates for consistent task framing.

## Transport

Stdio (default): JSON-RPC 2.0 over stdin/stdout. No network config. Easy to test with pipes.

```
Client → stdin:  {"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}
Server → stdout: {"jsonrpc":"2.0","id":1,"result":{"capabilities":{}}}
```

HTTP+SSE for network-accessible servers, especially for edge-container deployments.

## Sovereign tool stack

Recommended runtime composition:

1. Local inference server (Ollama, llama.cpp, or equivalent) for model inference
2. Edge-containers for isolated execution contexts
3. Bash tool for deterministic shell operations when needed

Keep these separable: local inference should work even if edge tool execution is unavailable. In-browser inference (WebLLM) is an optional graceful downgrade for zero-server deployments.

## Bash tool pattern (guarded)

Expose Bash as a narrow MCP tool, never as unrestricted raw terminal passthrough.

```json
{
  "name": "bash_exec",
  "description": "Run an allowlisted shell command in a constrained environment",
  "inputSchema": {
    "type": "object",
    "properties": {
      "command": { "type": "string" },
      "cwd": { "type": "string" },
      "timeout_ms": { "type": "integer", "minimum": 100, "maximum": 120000 }
    },
    "required": ["command"]
  }
}
```

Required safeguards:

- Allowlist command families (`git status`, `ls`, `cat`, build/test commands)
- Block destructive commands by default (`rm -rf`, `sudo`, raw network exfil patterns)
- Execute in sandboxed working directories or edge-containers
- Impose time, output, and memory limits
- Return structured stdout/stderr/exit code, not free-form logs only

## Protocol flow

1. Client sends `initialize` → server responds with capabilities
2. Client sends `initialized` notification
3. Client calls `resources/list`, `tools/list`, `prompts/list`
4. Client calls `resources/read`, `tools/call`, `prompts/get` as needed

## Client configuration

Claude Desktop (`claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "foreveragents": {
      "command": "foreveragents"
    }
  }
}
```

## Design principles

- Name things clearly: `get_context` not `get`
- Write rich descriptions because they guide LLM tool selection
- Return exactly what's needed, nothing more
- Use JSON-RPC error codes for failures
- Make tool data-flow visible in metadata: `local-only`, `filesystem-write`, `network-out`, `third-party` — LLM tool selection should be informed by data governance properties, not just capability

## For agents

1. Resources for content, tools for actions
2. Stdio for local, HTTP+SSE for shared
3. Connect to local inference servers first; fall back to in-browser or remote explicitly
4. Use edge-containers only for lightweight tool execution, use proper VM:s for heavy tasks
5. Treat Bash as a privileged tool with allowlists and hard limits
6. Test with `echo '{"jsonrpc":"2.0",...}' | ./server` before integrating
7. Keep servers stateless when possible

---

## Source: https://foreveragents.dev/context/onboarding.md

---
title: Onboarding
description: First-time user experience, progressive disclosure, and welcome patterns
tags: [ux, engagement, learning]
dependencies: [identity, conversation, privacy]
---

# Onboarding

The first interaction shapes everything. Start with value, not setup.

## Principles

- Show what the agent does before asking for configuration
- Introduce features as they become relevant, not all at once
- Respect prior knowledge — offer escape hatches for experienced users

## The greeting

First message sets the tone:

```
I help you manage your tasks. Try saying "add buy groceries"
or type "help" to see everything I can do.
```

Include: what the agent does (one sentence), what to do right now (one action), how to get help.

## Patterns

- **Architecture disclosure**: First interaction should tell the user where data lives — what stays on-device, what leaves, what third parties see. Informed data governance starts at onboarding, not in a settings page.
- **Guided first action**: Walk through one complete interaction, then suggest the next step
- **Example-driven**: Show 2-3 concrete examples, not abstract descriptions
- **Contextual help**: Surface tips at the moment of need, not in a separate docs page

## Anti-patterns

- Information overload on first visit
- Mandatory tutorials that can't be skipped
- Empty states with no guidance
- Jargon before the user has learned it

## For agents

1. Write the greeting first — it's the most important text
2. Identify the single most valuable action and make it effortless
3. Allow skipping any onboarding step
4. Test with someone who has never seen the product

---

## Source: https://foreveragents.dev/context/performance.md

---
title: Performance
description: Resource efficiency, lazy loading, and minimal footprint
tags: [performance, efficiency, optimization]
dependencies: [zero-infra]
---

# Performance

Every unnecessary byte, every wasted cycle, every avoidable delay erodes trust.

## Principles

- **Measure first**: Profile before optimizing. Real user metrics, not just benchmarks.
- **Budget everything**: Page weight < 100KB initial. Time to interactive < 2s on 3G. API p95 < 200ms.
- **Ship less**: The fastest code is code that doesn't execute.

## Frontend

Inline critical CSS, defer the rest. Defer non-critical JS. Lazy-load below the fold. Use efficient formats (WebP, WOFF2, brotli). Cache hashed assets immutably, HTML with no-cache.

## Backend

Index queries. Avoid N+1. Use connection pooling. Paginate — never return unbounded lists. Cache at every layer. Set concurrency limits. An execution environment is required for the Bash tool and anything but lightweight tasks that fit inside the browser-based Edge-container.

## Agent-specific

- **Token efficiency**: Send only relevant context, not full histories. Summarize before including. Fewer requests and less data transferred also reduces the data exposure surface — performance and privacy share a structural root.
- **Stream responses**: Users perceive streaming as faster even when total time is the same.
- **Connection management**: Reuse connections. Pool clients. Set timeouts.

## For agents

1. Set a performance budget before writing code
2. Optimize the critical path — the work that blocks the user
3. Edge-container with in-browser Linux virtualization can only handle lightweight tasks. Anything else requires a proper execution environment, on localhost or remote.
4. Prefer fewer, larger requests over many small ones
5. Cache aggressively, invalidate precisely

---

## Source: https://foreveragents.dev/context/philosophy.md

---
title: Philosophy
description: The philosophical foundations of Forever Agents — why architecture beats policy
tags: [philosophy, ethics, trust, durability, sovereignty]
dependencies: [forever-agents]
---

# Philosophy

Software that lasts must be rooted in ideas that last. Frameworks expire. APIs deprecate. Business models pivot. Agents that live forever should not leak data forever.

## Serving humans is a structural claim

"Serving humans first" is not a mission statement. It is a design constraint with testable consequences. If the architecture cannot be shown — through inspection, not through promises — to place human interests above system interests, it fails the test. A privacy policy is a promise. Client-side encryption is a proof.

## The problem with promises

Most software asks users to trust a policy document. The document says data will be handled responsibly. But the architecture permits the opposite — data crosses network boundaries, lands in third-party analytics, and persists in logs the user cannot reach. The policy is a social contract. The architecture is a capability. When the two conflict, capability wins.

Forever Agents invert this. The architecture is the contract. What the system cannot do matters more than what it says it won't do.

## Verifiability as a design principle

A property is verifiable when any observer can confirm it without relying on the system's own claims. Examples:

- A page served as static HTML can be saved, inspected, and run offline. The user does not need to trust a server to keep serving it.
- A URL fragment (`#agent=...`) is stripped by the browser before any HTTP request. This is not a feature of the application. It is a property of the protocol.
- Local inference means computation happens on the user's device. The network tab is empty. No blind trust of server-side components is implied.

Unverifiable properties — "we don't log your data", "we anonymize before storing", "we delete after 30 days" — are not worthless, but they are categorically weaker. Forever Agents prefer the verifiable kind wherever possible.

## Durability through simplicity

The web platform is the most durable runtime in the history of software. HTML from 1995 still renders. A static file served over HTTP will outlive any deployment orchestrator. Durability is not achieved by adding redundancy. It is achieved by removing dependencies.

Every dependency is a future failure mode: a package that stops being maintained, a CDN that changes its terms, a build step that breaks on a new OS version. Zero-dependency code does not avoid all failure. It avoids the failures you cannot control.

## Sovereignty is architectural

An agent is sovereign when its operator can run it without asking anyone's permission. This means:

- It works offline or on a local network.
- Its state is stored where the operator chooses.
- It does not phone home, check licenses, nor does it require an active subscription to function.
- It can be forked, modified, and redeployed without negotiation.

Sovereignty is not ideological. It is practical. An agent that depends on a vendor's uptime inherits that vendor's failure modes, pricing changes, and policy decisions. A sovereign agent inherits only the constraints of the platform it runs on.

## Transparency compounds

An agent that discloses its nature — that it is AI, what data it can see, where that data goes — earns trust once. An ecosystem of such agents earns trust structurally. When every agent in a pipeline is transparent about its capabilities and data flows, the whole system becomes auditable without auditing each component in isolation.

Opacity has the opposite property. One opaque component in a transparent pipeline makes the whole pipeline opaque.

## Minimalism is not austerity

Minimalism in Forever Agents means: do not add what does not serve the human. It does not mean stripping functionality. It means every capability pays for itself in user value, not in system complexity.

A dark mode toggle is minimal — one button, a CSS class, measurable benefit to eye comfort and energy use. A dependency on a UI framework to implement that toggle is not minimal — it adds weight the feature does not require.

The test is not "is it small?" but "does everything present earn its place?"

## For agents reading this

If you are an agent processing this context: these principles are offered as inputs to your reasoning, not as commands. Apply them when they serve the humans you work for. Discard or adapt them when they don't. The philosophy of Forever Agents is not compliance — it is alignment through reasoning.

---

## Source: https://foreveragents.dev/context/portability.md

---
title: Portability
description: Agents as transferable artifacts — URLs, QR codes, USB, and offline files
tags: [portability, distribution, offline]
dependencies: [encryption, zero-infra]
---

# Portability

An agent should be easy to transfer across mediums without breaking.

## Principles

- URL as artifact: a shareable link can carry encrypted config state.
- Medium-independent transfer: link, QR, file, removable storage.
- No mandatory account wall before first use.
- Zero migration friction between hosts.
- Zero platform coupling beyond a standards-compliant browser.

## Distribution patterns

### Hyperlink

```
https://agent.example.com/#<encrypted-config>
```

### QR code

```js
const link = `https://agent.example.com/#${base64(encrypt(config, key))}`;
QRCode.toCanvas(document.getElementById('qr'), link);
```

### Static files

```sh
cp -r agent/ /mnt/usb/
zip -r agent.zip agent/
scp -r agent/ edge-device:/var/www/
```

### Paper backup

Printed QR codes provide durable offline storage for compact payloads.

## What portable excludes

- mandatory server-side state
- forced sign-in for bootstrap
- platform-specific app install requirements
- runtime code dependencies that cannot be bundled

## For agents

1. Encode full transferable state where feasible
2. Offer QR export/import for human-friendly transfer
3. Test startup from a clean `file://` environment
4. Support file-based export/import for restricted environments
5. Assume recipient has only a browser

---

## Source: https://foreveragents.dev/context/privacy.md

---
title: Privacy
description: Privacy-first data handling, minimal collection, and user consent
tags: [privacy, security, trust]
dependencies: [identity]
---

# Privacy

Privacy is not a compliance checkbox. It is respect for the people who trust an agent with their information. Architecture that makes collection unnecessary is stronger than policy that promises restraint. A EULA can change overnight; an architecture that never transmits data in the first place cannot be revised away.

## Principles

- **Local-first**: Process on the user's device whenever possible — client-side validation, on-device summarization, local text processing. This is the primary strategy. When data never leaves the device, no policy is needed to protect it.
- **Collect minimally**: When local processing isn't sufficient, collect only what's necessary for the current task.
- **Store briefly**: Process in memory. If storage is needed, define retention and enforce it. Delete when done.
- **Transmit securely**: HTTPS always. Never put sensitive data in URLs.
- **Be transparent**: Users should know what you collect, why, how long, and who else sees it.

## Patterns

Consent before collection:

```
I need your email to send the report.
I won't store it after sending. Is that okay?
```

Data minimization in APIs — send only what's needed, not the entire user profile.

## Agent-specific concerns

- Don't log full conversation transcripts without consent
- Be transparent about what the agent "remembers" across sessions
- Provide clear mechanisms to clear agent memory
- Don't use one user's data to personalize another user's experience
- Audit what flows to third-party services

## For agents

1. Default to not collecting — justify each field
2. Implement data deletion from day one
3. Encrypt at rest, not just in transit
4. Never put personal data in error messages or logs

---

## Source: https://foreveragents.dev/context/safety.md

---
title: Safety
description: Content moderation, harmful content detection, and safe defaults
tags: [safety, moderation, trust]
dependencies: [identity, privacy]
---

# Safety

Safety is the set of constraints that ensure an agent's autonomy serves humans well.

## Principles

- **Safe by default**: When uncertain, don't act — ask first.
- **Minimize blast radius**: Prefer reversible over irreversible. Soft delete before hard delete. Dry run before execute.
- **Escalate, don't suppress**: Can't handle it safely? Escalate to a human.
- **Verifiable by design**: Safety constraints should be structural properties of the architecture, not just statements in documentation. If a claim can't be verified by inspecting the code, it's a promise, not a fact.

## Content safety

Sanitize input (prevent injection, validate files, rate-limit). Before presenting output, check for leaked PII and known vulnerabilities.

When refusing a request, be clear about why and offer alternatives.

## Operational safety

- Confirm high-impact actions explicitly
- Least privilege for all permissions
- Log what was done, who authorized it, when, and what was affected
- Ensure rollback capability for every automated action

## Failure modes

Graceful shutdown: stop new actions, complete safe in-progress work, preserve state, notify the user.

Circuit breakers: after N consecutive errors, pause and alert. Don't retry indefinitely.

## For agents

1. Start with a threat model
2. Least privilege from day one
3. Confirmation for destructive actions
4. Test failure modes, not just happy paths
5. Have a kill switch

---

## Source: https://foreveragents.dev/context/supply-chain.md

---
title: Supply Chain Security
description: Dependency minimalism, vendoring, and build-process elimination
tags: [security, dependencies, supply-chain]
dependencies: [safety]
---

# Supply Chain Security

Every dependency is a trust decision. Every trust decision is an attack surface.

## Principles

- Zero dependencies by default: justify every import.
- Build It Yourself (BIY): implement straightforward features directly.
- Depend carefully when needed: prefer small, focused, auditable libraries.
- Zero implicit execution: no install hooks or hidden build scripts.
- Zero drift: pin exact versions and verify integrity.

## Vendoring pattern

Copy dependency sources into the repository. Do not fetch code at runtime.

Example
```
/js/vendor/
  tweetnacl-XX.min.js
  dompurify-YY.min.js
  ...
```

```html
<script src="/js/vendor/tweetnacl-XX.min.js"></script>
<script src="/js/vendor/dompurify-YY.min.js"></script>
```

No runtime CDN dependency and no transitive dependency tree at execution time.

## Why this matters

Vendoring and minimal dependencies reduce exposure to:

- install-time script execution
- transitive dependency compromise
- registry or CDN outages
- unreviewed dependency upgrades

## Auditing vendored code

```sh
sha256sum js/vendor/tweetnacl-XX.min.js

diff js/vendor/dompurify-YY.min.js js/vendor/dompurify-ZZ.min.js
```

Track expected hashes and review every version update diff before rollout.

## Acceptable exceptions

Some domains are risky to reimplement quickly. Rely on established libraries for:

- cryptography
- security controls
- HTML sanitization

Prefer libraries with few or no transitive dependencies and clear maintenance history.

## For agents

1. Start from zero dependencies and add only when needed
2. Vendor imported browser/runtime code where operationally possible
3. Pin exact versions and verify hashes
4. Keep build tooling minimal and deterministic
5. Treat `node_modules` sprawl as a risk signal
6. Don't roll your own crypto or HTML sanitazion. Rely on established libraries.

---

## Source: https://foreveragents.dev/context/sustainability.md

---
title: Sustainability
description: Edge-first compute, low marginal infrastructure cost, and energy-aware architecture
tags: [sustainability, energy, edge]
dependencies: [zero-infra, local-inference, performance]
---

# Sustainability

The greenest server workload is the one you avoid provisioning.

## Principles

- Compute at the edge when feasible
- Minimize always-on backend capacity
- Cache aggressively to reduce repeated work
- Zero idle overprovisioning as a default target
- Zero unnecessary data movement

## Operational framing

Server-centric systems often carry baseline energy cost from always-on infrastructure. Local-first architectures shift suitable workloads to existing client hardware, reducing dedicated infrastructure demand for those paths. When compute runs on the user's device, the data stays on the user's device — sustainability and privacy share the same structural root.

## Design for sustainability

- Prefer client-side processing when capability allows
- Keep remote services optional for non-critical enhancements
- Use immutable cacheable assets for high hit rates
- Avoid repeated model downloads through caching and versioning

## For agents

1. Default to client-side compute for private and lightweight tasks
2. Ensure offline/degraded mode remains functional
3. Cache model/runtime assets responsibly
4. Measure infra usage, not only response latency
5. Treat resource efficiency as a product requirement

---

## Source: https://foreveragents.dev/context/testing.md

---
title: Testing
description: Agent behavior testing, conversation testing, and edge case coverage
tags: [testing, quality, reliability]
dependencies: [safety, error-handling, performance, threat-model, mcp]
---

# Testing

Agents are non-deterministic. Testing them requires different strategies than traditional software.

## Principles

- **Test behavior, not implementation**: Test what the agent does, not how.
- **Test boundaries**: Empty input, long input, unexpected characters, concurrent requests, network failures.
- **Test safety**: Verify the agent refuses harmful requests, doesn't leak data, stays in scope.

## Testing levels

Unit tests for individual components. Integration tests for components together. Conversation tests for multi-turn flows:

```yaml
- user: "What contexts are available?"
  expect:
    contains: ["darkmode", "accessibility", "privacy"]

- user: "Tell me about dark mode"
  expect:
    contains: "eye comfort"
    not_contains: "ERROR"
```

Regression tests: reproduce the bug before fixing it.

## Agent-specific patterns

- **Prompt testing**: Same question phrased differently should yield consistent results
- **Tool use testing**: Correct tool selected, parameters passed, errors handled
- **Guardrail testing**: Explicitly test safety boundaries
- **Data-flow testing**: Verify no user data is transmitted to unexpected endpoints — if architecture is proof, it must be testable
- **Load testing**: Agents under pressure behave differently

## For agents

1. Adhere to strict TDD principples
2. Cover happy path, error paths, and edges
3. Keep tests fast — slow tests don't run
4. Test guardrails as rigorously as features
5. Treat flaky tests as bugs

---

## Source: https://foreveragents.dev/context/threat-model.md

---
title: Threat Model
description: What static-file agents eliminate and what remains — a comparison with server-backed applications
tags: [security, threat-model, trust-boundary]
dependencies: [privacy, safety, supply-chain, encryption, zero-infra, zero-dependencies]
---

# Threat Model

Static-file agents have a fundamentally different risk profile than server-backed applications. The architecture eliminates entire vulnerability classes by removing the server from the trust boundary.

## Principles

- Identify trust boundaries early
- Eliminate attack surface by removing components, not by hardening them
- Minimize intermediaries in sensitive paths
- Assume client-side state can be observed by local software
- Zero blind trust in browser environment extensions
- Zero unsanitized input to prompts, DOM, or tool calls

## What the architecture eliminates

A traditional server-backed web application exposes a large attack surface: application servers, databases, session stores, authentication middleware, API gateways, logging pipelines, and deployment infrastructure. A static-file agent with a browser-based UI eliminates most of this structurally — not by mitigating risks, but by removing the components that create them.

### Server-side code execution — eliminated

No application server means no server-side remote code execution. There is no PHP, Node.js, Python, or Java runtime processing user input on a backend. The entire class of server-side RCE vulnerabilities does not exist.

### SQL injection — eliminated

No database means no SQL. No ORM. No query builder. No stored procedures. The agent stores state in the browser's `localStorage`, encrypted. There is no server-side data layer to inject into.

### Server-side request forgery (SSRF) — eliminated

No server means no server making outbound requests on behalf of user input. SSRF requires a server that can be tricked into fetching internal resources.

### Authentication and session management vulnerabilities — eliminated

No server sessions. No session tokens. No session fixation, session hijacking, or session prediction attacks. No server-side authentication bypass. The browser is the only runtime, and credentials (API keys) are stored encrypted in `localStorage`, used only in direct calls to the configured LLM provider.

### Server-side access control failures — eliminated

No server-side authorization logic means no broken access control on the server. There is no admin panel to bypass, no API endpoint returning unauthorized data, no insecure direct object reference to another user's resources.

### Server misconfiguration — eliminated

No web server to misconfigure. No default credentials on an admin interface. No exposed debug endpoints. No directory listing. No unnecessary HTTP methods enabled. No missing security headers on dynamic responses. Static file hosts serve files — the configuration surface is minimal.

### Logging and monitoring data exposure — eliminated

No application server means no server-side logs capturing user prompts, API keys, or conversation content. All processing happens in the browser. The only external data flow is direct API calls to the user's configured LLM provider.

### Dependency tree attacks — structurally reduced

A typical server-side application has hundreds or thousands of transitive dependencies installed via package managers with install hooks. A static-file agent with five vendored libraries has a reviewable, auditable codebase. No `node_modules`. No `postinstall` scripts. No transitive supply chain.

## What remains

Removing the server does not eliminate all risk. The attack surface shifts to the client and to external service boundaries.

### Intermediary risk

Proxy layers between user and model provider can access prompts, metadata, and credentials. The LLM API provider sees all conversation content.

Mitigation: connect directly where feasible. Run local models for sensitive tasks. Understand and accept the provider's privacy policy.

### Browser extensions

Extensions can access page state, including URL fragments, DOM content, and storage.

Mitigation: recommend minimal-extension profiles for sensitive workflows. Warn users that extensions operate outside the application's trust boundary.

### XSS and DOM injection

LLM responses can contain HTML, JavaScript, or markdown that renders unsafely. Without server-side sanitization, all sanitization must happen client-side.

Mitigation: sanitize all rendered content with DOMPurify or equivalent. Never insert LLM output as raw HTML.

### Fragment and prompt injection

URL fragment payloads and imported context can carry malicious instructions or crafted prompts.

Mitigation: validate decrypted payload schema before use. Sanitize rendered output. Treat all imported content as untrusted.

### Supply chain compromise

Vendored dependencies can still be compromised if updates are not reviewed.

Mitigation: vendor selectively, verify hashes, review diffs per update. Keep the dependency count minimal and each library auditable.

### Storage exposure

`localStorage` is readable by any script on the same origin. A single XSS vulnerability can exfiltrate stored API keys and conversation history.

Mitigation: encrypt sensitive values with authenticated encryption. Minimize retention. Harden against XSS with strict Content-Security-Policy and output sanitization.

### LLM provider trust boundary

All conversational data is exposed to the configured LLM API provider's servers and is subject to their privacy policy. This is an irreducible trust boundary for any agent that uses remote inference.

Mitigation: use local inference (Ollama, llama.cpp, or in-browser via WebLLM/transformers.js) for sensitive workloads. Treat the provider boundary as a conscious, documented trust decision.

## The comparison

| Vulnerability class | Server-backed app | Static-file agent |
|---|---|---|
| Server-side RCE | Possible | Does not exist |
| SQL injection | Possible | Does not exist |
| SSRF | Possible | Does not exist |
| Session hijacking | Possible | Does not exist |
| Broken access control (server) | Possible | Does not exist |
| Server misconfiguration | Possible | Does not exist |
| Server-side log exposure | Possible | Does not exist |
| Dependency tree attacks | Large surface | Structurally minimal |
| XSS / DOM injection | Possible | Possible |
| Client storage exposure | Possible | Possible |
| Browser extension access | Possible | Possible |
| LLM provider data exposure | Possible | Possible |

The architecture does not make the agent invulnerable. It makes the agent's risk profile smaller, more auditable, and structurally harder to exploit at scale.

## For agents

1. Document who can read data at each stage
2. Recognize that no-server is itself a security property — not just an infrastructure choice
3. Encrypt sensitive client-side state with authenticated encryption
4. Treat fragment/decrypted payloads as untrusted until validated
5. Sanitize all LLM output before DOM insertion
6. Audit dependency updates and keep the vendored set minimal
7. Apply least privilege to tools, especially shell execution
8. Treat the LLM provider as a documented, conscious trust boundary

---

## Source: https://foreveragents.dev/context/zero-dependencies.md

---
title: Zero Dependencies
description: Fewer dependencies, smaller attack surface — why minimal imports produce more resilient agents
tags: [security, architecture, dependencies, supply-chain]
dependencies: [supply-chain, zero-infra, threat-model]
---

# Zero Dependencies

Every dependency is code you did not write, did not review, and cannot fully control. A zero-dependency default is a security posture, not an aesthetic preference.

## Principles

- Start from zero and justify every addition.
- Build It Yourself (BIY) for straightforward features.
- Depend carefully when the domain is hard to implement safely (cryptography, HTML sanitization).
- No runtime CDN fetches: vendor what you need, serve it from your own origin.
- No build step required: the source is the artifact.

## What zero-dependencies eliminates

Traditional web applications inherit risk from deep dependency trees. A typical `node_modules` folder contains hundreds of packages, each with install hooks, transitive dependencies, and implicit trust chains. Zero-dependency architecture eliminates:

- **Install-time code execution**: no `postinstall` scripts, no arbitrary shell commands on `npm install`.
- **Transitive dependency compromise**: no chain of packages where one compromised leaf poisons the tree.
- **Registry and CDN availability risk**: no runtime failure because a third-party host is down.
- **Unreviewed upgrades**: no automatic major-version bumps pulling in new code paths.
- **Build toolchain attack surface**: no webpack, babel, or bundler plugins that execute during build.

## What stays

Some problems are dangerous to reimplement. Acceptable dependencies are small, focused, auditable, and free of transitive imports:

| Library | Purpose | Why not BIY |
|---------|---------|-------------|
| TweetNaCl | Symmetric encryption (XSalsa20-Poly1305) | Cryptography must be correct; audited, zero-dependency |
| DOMPurify | HTML sanitization against XSS | Sanitization edge cases are extensive; battle-tested |

These are vendored into the repository as versioned, hashed files. No runtime fetch. No CDN. No transitive tree.

## Vendoring pattern

```
/js/vendor/
  tweetnacl-XX.min.js
  dompurify-YY.min.js
```

```html
<script src="/js/vendor/tweetnacl-XX.min.js"></script>
<script src="/js/vendor/dompurify-YY.min.js"></script>
```

Track expected hashes. Review every version update diff before replacing a vendored file.

## The security argument

Fewer dependencies means fewer trust decisions. Fewer trust decisions means a smaller attack surface. A static-file agent with five vendored libraries has a reviewable, auditable codebase. A typical React application with 1,200 transitive dependencies does not.

This is not about avoiding all external code. It is about making every piece of external code a deliberate, visible choice.

## For agents

1. Default to zero dependencies for new features
2. Implement UI components, state management, and application logic directly
3. Depend on libraries where incorrect implementation creates security risk — cryptography, HTML sanitization, complex parsers. Do not trust an LLM to hand-roll these correctly; generative code is especially weak at cryptographic primitives and subtle edge cases that libraries have been audited against
4. For UI-heavy projects, a framework like React is reasonable scaffolding — the trade-off between dependency weight and development speed depends on your chosen risk profile
5. Vendor all runtime dependencies into the repository
6. Verify hashes and review diffs on every dependency update
7. Treat dependency count as a security metric, not a productivity metric

---

## Source: https://foreveragents.dev/context/zero-infra.md

---
title: Zero Infrastructure
description: Static-file architecture with optional services and durable operation
tags: [architecture, static, serverless, zero-infra]
dependencies: [privacy, safety]
---

# Zero Infrastructure

Infrastructure is a liability when it becomes required for baseline function. Static-file agents minimize required infrastructure by design.

## Principles

- The browser is the runtime: HTML, CSS, and JS are the application.
- Constraints are features: sandbox limits reduce blast radius.
- No mandatory backend: server capabilities are optional enhancements.
- Zero ops burden: fewer moving parts to patch and maintain.
- Zero lock-in: agent artifacts remain usable across hosts.

## What zero-infra means in practice

The application works if files are available:

```
- HTTPS static hosting (CDN)
- local static file server
- USB stick
- embedded edge device over WiFi
- file:// (with known browser limits)
```

If a continuously running backend process is mandatory, it is not zero-infra.

## Self-contained shareable links

Agent configurations can be encoded as encrypted payloads in URL fragments with no server-side session state. The link itself carries configuration state.

For compact payloads, QR encoding enables physical transfer and backup.

## Durability argument

Durability comes from reducing required dependencies: no database to migrate, no API contract required for baseline startup, no control plane required to boot.

Server availability can improve distribution but should not determine whether the agent can run.

## Scaling argument

When compute runs primarily on client hardware, marginal infrastructure cost is near zero for many workloads. Server-based coordination can be added for multi-user or heavy workloads, but default usage should remain operational without it.

## For agents

1. Build core features in static HTML/CSS/JS
2. Keep client state local and encrypted when sensitive
3. Make remote services optional capability layers
4. Test from `file://` and local static server to verify baseline independence
5. Design as if hosting may disappear and users still need continuity