docs: route agent guidance by task

docs/agents/background-work.md

@@ -0,0 +1,22 @@
+# Background Work and Memory
+
+Read this file before changing watchers, polling, sync scheduling, or other
+long-running background work. Also read it before investigating memory growth.
+
+- Keep passive daemon memory within a few hundred megabytes on macOS, Linux, and
+  Windows. Treat sustained growth beyond that range as a regression.
+- Bound watcher, polling, and sync work by the changed batch, not the full
+  archive. Do not scan or load every stored session for each filesystem event.
+- Declare costly scheduling inputs as provider capabilities. Compute them only
+  for providers that use them, and default new capabilities to unsupported.
+- Add cardinality-scaling regressions for background paths. Compare small and
+  large archives and prove that unchanged work per event stays bounded. Cover
+  deletion, tombstones, and persistent archives in the same tests.
+- Diagnose long-running memory with allocation and CPU profiles, live heap,
+  forced-GC heap, and operating-system physical or dirty memory. Raw RSS does
+  not prove live memory because it includes clean reclaimable mappings.
+- Profile branch binaries only against isolated, production-scale database and
+  source clones. Never use live archives or agent transcripts.
+- Observe retention long enough to reproduce the reported growth window. On
+  macOS, record `vmmap` physical footprint and dirty memory. Use portable Go
+  allocation and heap metrics on Linux and Windows.

docs/agents/build.md

@@ -0,0 +1,24 @@
+# Build and Dependency Rules
+
+Read this file before changing build commands, toolchain setup, CI build tags,
+or frontend dependencies. Use the `Makefile` as the command reference.
+
+## Go and SQLite
+
+- Build with `CGO_ENABLED=1`; the SQLite driver requires CGO.
+- Use the `fts5` build tag for full-text search.
+- Do not add the `kit_posthog_disabled` tag to `go test`. The telemetry reporter
+  disables itself under `testing.Testing()`. E2E binaries run as real
+  processes, so their build keeps the tag.
+
+## Frontend
+
+- The embedded Svelte frontend requires Node.js and the frontend toolchain. Read
+  `frontend/AGENTS.md` before working in that directory.
+- `@kenn-io/kit-ui` is a public git dependency pinned to a commit in
+  `frontend/package.json`.
+- The lockfile records the GitHub dependency as an SSH URL because npm uses that
+  canonical form. npm still fetches it anonymously over HTTPS. Do not rewrite
+  the lockfile URL.
+- To update kit-ui, change the commit hash in `frontend/package.json` and run
+  `npm install`.

docs/agents/storage.md

@@ -0,0 +1,58 @@
+# Storage Rules
+
+Read this file before changing SQLite, PostgreSQL, CockroachDB, DuckDB, archive
+resync, or storage queries.
+
+## SQLite Archive
+
+SQLite is the persistent archive. Never delete, drop, truncate, or recreate it
+to handle a data-version change.
+
+Use non-destructive schema migrations such as `ALTER TABLE` and `UPDATE`. A
+parser change that needs a full resync must build a fresh database, sync source
+files, copy orphaned sessions from the old database, and swap the files
+atomically. Preserve sessions even when their source files no longer exist.
+
+## Backend Parity
+
+- Keep observable behavior and query shape aligned between SQLite and
+  PostgreSQL/CockroachDB when practical. Match queries, indexes, aggregations,
+  filters, and ordering unless a documented constraint requires a difference.
+- Do not fix correctness or performance in only one primary backend unless the
+  user limits the task to that backend. If implementations must differ,
+  explain why and preserve the same behavior.
+- DuckDB is a derived mirror and is not part of this parity rule.
+
+## DuckDB Mirror
+
+- Treat DuckDB as a disposable read mirror of SQLite, never as a system of
+  record. Deleting the mirror must lose nothing.
+- Do not add in-place mirror migrations. A schema or source-data version change
+  must bump `internal/duckdb.SchemaVersion`, rebuild a fresh file, validate
+  it, and swap it atomically. Do not add `ALTER` migrations, version-bridging
+  reads, or compatibility shims for old mirrors.
+- Store every DuckDB push cursor and version in the mirror's `sync_metadata`.
+  Never store DuckDB sync state in SQLite.
+- Replace whole sessions during incremental updates and gate them with
+  per-session fingerprints. Do not add per-table, per-column, or diff-based
+  updates.
+- Keep Quack read-only. `duckdb push` writes the local mirror; it never writes
+  to a remote DuckDB service.
+- Replace a file only after identifying it as an agentsview DuckDB mirror. Fail
+  closed for unknown files.
+
+## PostgreSQL Integration Tests
+
+Run PostgreSQL integration tests only against a dedicated test database. The
+tests create and drop the `agentsview` schema.
+
+Use `make test-postgres` to start the test container and run the suite. It
+leaves the container running. If you started that container, use
+`make postgres-down` when it is no longer needed.
+
+To use an existing dedicated instance, run:
+
+```bash
+TEST_PG_URL="postgres://user:pass@host:5432/dbname?sslmode=disable" \
+  CGO_ENABLED=1 go test -tags "fts5,pgtest" ./internal/postgres/... -v
+```

docs/agents/testing.md

@@ -0,0 +1,33 @@
+# Testing Rules
+
+Read this file before adding or changing tests.
+
+## Coverage
+
+- Add unit tests for every new feature and bug fix.
+- Run the smallest relevant test set before committing. State which checks you
+  could not run.
+- Keep tests fast and isolated.
+
+## Go Tests
+
+- Prefer table-driven tests.
+- Use `github.com/stretchr/testify` for assertions.
+- Use `require.X` when failure must stop the test, such as setup errors, nil
+  values, or length checks before indexing.
+- Use `assert.X` for independent checks that can continue after failure.
+- Do not add `if got != want { t.Fatalf(...) }` comparisons.
+- Test helpers must use testify for their own assertions.
+- Use the existing `testDB(t)` helper for database tests.
+- Use `t.TempDir()` for temporary directories.
+
+## Frontend and End-to-End Tests
+
+- Keep frontend unit tests beside the code in `*.test.ts` files.
+- Put Playwright tests in `frontend/e2e/`.
+
+## Shell Tests
+
+Run scripts against controlled input and assert their output, exit code, or side
+effects. Do not read a script and assert that it contains an implementation
+line, flag, or snippet.

frontend/AGENTS.md

@@ -33,3 +33,11 @@ https://viteplus.dev/guide/.
   typeahead/combobox components for single-choice selectors unless the native
   control is explicitly justified.
 - Existing native selects are legacy exceptions, not examples to copy.
+
+## Localization
+
+- Keep the message catalogues in `messages/*.json` in sync. When you add,
+  remove, or rename a user-facing key, update every locale listed in
+  `project.inlang/settings.json` and keep their key sets identical.
+- After changing a message catalogue or localized component, run
+  `npm run i18n:compile` and `npm run check` when practical.

internal/duckdb/README.md

@@ -17,7 +17,9 @@ tunnel/proxy.
 The DuckDB schema intentionally avoids `TIMESTAMP DEFAULT current_timestamp`
 columns because current Quack attach rejects catalogs with those dynamic
 defaults. Writers supply `current_timestamp` explicitly where the mirror needs a
-created timestamp. Existing mirrors are additively migrated by `EnsureSchema`.
+created timestamp. A schema-version change builds a fresh mirror, validates it,
+and swaps it into place atomically. `EnsureSchema` initializes fresh mirrors; it
+is not an in-place production migration path.
 
 Search currently keeps substring/regex fallback behavior. The DuckDB FTS
 extension is available locally in the pinned runtime, but BM25 lookup does not