meridian: Instructions file for Claude Code

Meridian — Claude Code Instructions

Meridian is a single-process Rust daemon that normalises raw screen-capture frames into structured, app-based activity sessions stored in its own SQLite database at ~/.meridian/meridian.db. A Next.js dashboard and a TypeScript MCP server sit alongside the daemon. (Capture source: historically screenpipe's SQLite DB; since the Bucket-2 cutover on feat/in-process-capture the frames are produced in-process by the tray and the daemon reads meridian.db's own capture tables — see "Capture source — in-process" below.)

Hard Rules

• Do what has been asked; nothing more, nothing less
• Meridian has real users running it in production right now — this is not a sandbox, and a bug here can silently destroy someone's data. Weigh every change by its blast radius, not just whether it compiles and the existing tests pass: a change with even a small chance of corrupting data, losing a signed-in session, or crash-looping the daemon/tray must not ship until you've actually reasoned through the failure paths (concurrent writers, a process dying mid-operation, a network drop, an empty/malformed payload) and, where practical, written a test that would have caught it — "it built and the happy path worked" is not the bar. This is not hypothetical: a race where the tray held a meridian.db connection open across a daemon restart, with no WAL checkpoint on either side, shipped to production and left a real alpha tester (issue #851) with a database so corrupted that even raw SQLCipher page reads with the correct key failed — unrecoverable, days of tracked activity gone. Nothing in CI caught it; only live use did. When you're not sure a change is safe, say so and ask, rather than pushing it and hoping — "does it currently pass" and "is it actually safe" are different questions, and only the second one is the one that matters here.
• NEVER create files unless absolutely necessary — prefer editing existing files
• NEVER create documentation files unless explicitly requested
• ALWAYS read a file before editing it
• NEVER commit secrets, credentials, or .env files
• Keep files under 500 lines; split when a file grows beyond that
• Validate all input at system boundaries (config load, DB open, frame parsing)
• NEVER run git reset, git push --force, or delete local code — other agents may be working on the codebase in parallel
• NEVER merge a PR automatically — open/update PRs as needed, but leave the actual merge to a human reviewer
• NEVER push directly to main or pre-main — always create a separate feature branch, commit there, and raise a PR to pre-main. All features, fixes, and other changes target pre-main (the staging branch), not main — only a maintainer opens the pre-main → main release PR, and only after everything on pre-main has been tested end-to-end on staging
• ALWAYS use a separate branch per feature/fix — branch name format: type/short-description (e.g. feat/trello-oauth, fix/ui-disconnect)
• In all user-facing app text — window titles, wizard/UI copy, button and menu labels, notification bodies, tray tooltips, any string the user reads — use a plain hyphen - only. NEVER an em-dash (—), en-dash (–), or double hyphen (--). Use it spaced (-) where a dash separates clauses. (This rule is about displayed strings; code comments and docs are exempt.)
• Any publicly reachable service we deploy must authenticate every request, validate its origin, allowlist the paths it serves, and rate-limit — and it gets deleted the day its last caller does. "Authenticate" is separate from "validate the origin" on purpose: an origin check alone is a header a caller controls, and reading the two as one requirement is what permits an unauthenticated public service. An unauthenticated request must be rejected outright with a 401, and verifying that is currently a MANUAL step — scripts/deploy-gateway.sh only prints "should 401 without a Bearer token" as a reminder at the end of a deploy; it sends no request and fails on nothing, so a gateway that started answering 200 unauthenticated would deploy green. infra/hf-proxy (hf.meridiona.com) was an unauthenticated reverse proxy to huggingface.co. Its header carried a thoughtful SECURITY: block about cache-key poisoning and auth headers leaking into a shared cache; it never asked who may call this. When the MLX stack that used it was deleted it kept running with no callers and a public DNS record — and Cloudflare publishes every hostname to the Certificate Transparency logs the moment it issues the cert, so scanners find it whether or not you advertise it. It reached 173,088 requests in a day against a 100k/day account-wide cap and took meridiona.com down with Error 1027 for traffic the site did not generate. Assume every hostname you provision is public knowledge immediately.