simple-host: Instructions file for Claude Code

CLAUDE.md

Working rules for any agent (Claude Code, Codex, Cursor, ...) changing this repo. Simple Host is one Go binary that hosts static sites with a small per-site JSON backend; it is live at https://simple-host.app and runs in production for real users.

Before you change anything

1. Read INTENT.md (what it is for, non-goals, decisions with dates), then FEATURES.md (what it does today), then ARCHITECTURE.md (where it lives).
2. git fetch and fast-forward first. Two sessions have overwritten each other in production.
3. Map every surface a change touches before coding: routes, openapi.yaml, llms.txt, the skills, the dashboard and the showcase page, the MCP tools, the Claude and OpenAI plugins.
4. If a request conflicts with INTENT.md, say so in one line and ask. When the owner rules on something, add it to INTENT's decisions with the date and reason.

In the same commit as a feature change

• Update FEATURES.md and add a line to CHANGELOG.md (newest first, plain language).
• Route changed: update internal/handler/static/openapi.yaml (the contract), regenerate openapi.json with python3 -c "import yaml,json;json.dump(yaml.safe_load(open('internal/handler/static/openapi.yaml')),open('internal/handler/static/openapi.json','w'),indent=2)", then llms.txt and the skills if it is user-facing. scripts/check-docs-sync.sh fails on drift.
• Skills changed: bump version in simple-host-website/.claude-plugin/plugin.json (the stale-skill notice reads it from the embedded file), then run bash scripts/sync-claude-plugin.sh. Never hand-edit plugins/simple-host/skills/.
• The plugin repos github.com/vineetu/simple-host-plugin and simple-hack-plugin are published from origin/main by the hourly sh-plugin-repo-sync.timer (it runs both scripts/publish-*claude-plugin-repo.sh); by hand: sudo systemctl start sh-plugin-repo-sync, or DRY_RUN=1 bash scripts/publish-claude-plugin-repo.sh to preview.
• Schema changed: edit db/schema.sql AND add a file under db/migrations/ (hosted batches: <batch>-<what>.sql; lexical order is apply order). The file must be plain SQL, idempotent (ADD COLUMN IF NOT EXISTS, CREATE ... IF NOT EXISTS) and safe on a live database (additive, defaults, no long locks, no CONCURRENTLY): simple-host migrate runs every file not yet recorded in schema_migrations, including on databases built from schema.sql that already have its effect. Full rule: db/migrations/migrations.go. The historical files listed there as baseline are never run. Small boxes migrate from install.sh on every run; the server never migrates on start. Production: apply the file by hand before deploying (the binary refuses to start if a column it reads is missing), then simple-host migrate -mark <file> (or just simple-host migrate); migrate -status lists what is pending.
• Parity with Simple Host Enterprise (PARITY.md, identical in both repos): any security fix in one repo is checked against the other the same day (note it in PARITY.md). A new or changed feature updates PARITY.md in the same commit. scripts/check-parity.sh (in check-docs-sync.sh) fails if a ## N. section of FEATURES.md has no PARITY.md row.
• Design docs in docs/designs/ carry a status line at the top; update it when you ship or drop the thing. Finished plans go to docs/history/.