# AGENTS.md — bitblocks

## Purpose

The umbrella site for the BitBlocks stack (`bitblocks.network`): a static
marketing/narrative page presenting the composable Nostr + Bitcoin building
blocks (BitLogin, BitGate, BitFeed, BitUnlock, Tessera). Static site, no build
step.

## Repository map

- `index.html` — the entire site, one page
- `js/bitblocks.js` — the only script (theme toggle etc.), loaded with `defer`
- `assets/` — `bitblocks.css` and self-hosted fonts
- `docs/TODO.md` — backlog and design-review notes
- `vercel.json` — deployment config: no build/install command, strict CSP headers

## Build / test / validate

There is no package.json, no build step, and no test suite. Validation is
manual:

- Run `python3 -m http.server 8080` from the repo root, then open
  `localhost:8080` and check the page renders and the theme toggle works.

There are no CI workflows in this repo.

## Conventions

- Plain hand-written HTML/CSS/JS; `js/bitblocks.js` is classic-script style
  (IIFEs, no modules, no framework, no dependencies).
- Theme-aware via CSS custom properties; JS only stamps the explicit
  light/dark choice on the root element.
- `vercel.json` enforces a strict CSP (`script-src 'self'`, no external
  origins) — any change must keep working under that policy: no inline
  scripts, no CDN resources.

## Backlog

The canonical backlog is `docs/TODO.md`.

## Security

- Static-site architecture is the standing assumption: no server code, no
  secrets belong in this repo — never commit keys or tokens.
- Treat any external content (fetched data, user input) as untrusted; today
  the site fetches nothing, and the CSP is written to keep it that way.
- Claim precision matters here (see `docs/TODO.md`): this page describes
  security infrastructure, so copy changes should not overclaim.

## Change policy

- Keep diffs minimal and focused.
- There are no tests to update; verify changes manually via the local server
  before considering them done, and don't introduce changes that violate the
  CSP in `vercel.json`.

## Repo memory

Curated agent memory lives in `.agents/` (index: `.agents/MEMORY.md`). Read it
before substantive work. Propose additions as files in `.agents/proposals/`;
trusted memory under `.agents/memory/` changes only through reviewed commits.
Code, tests, and configuration always outrank memory.