docs: route agent guidance by task (#1213)

mariusvniekerk · web-flow · commit b0318ad201df · 2026-07-31T11:41:29.000-05:00
The root `AGENTS.md` had grown into an always-loaded mix of repository policy, subsystem contracts, command reference, and troubleshooting history. That made the rules that apply to every task harder to find and allowed copied documentation to drift.

This change keeps safety, delivery, completion, and publishing rules in the root file, then routes storage, testing, frontend, build, and background-work tasks to focused guides. It also corrects the stale DuckDB schema-lifecycle note found during the split. The main tradeoff is that agents must follow the routing table before editing a matching part of the repository; the root keeps the critical SQLite preservation warning as a safeguard.

&lt;sup&gt;generated by a clanker&lt;/sup&gt;

Co-authored-by: Marius van Niekerk &lt;mariusvniekerk@users.noreply.github.com&gt;
diff --git a/AGENTS.md b/AGENTS.md
diff --git a/docs/agents/background-work.md b/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.
diff --git a/docs/agents/build.md b/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`.
diff --git a/docs/agents/storage.md b/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
+```
diff --git a/docs/agents/testing.md b/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.
diff --git a/frontend/AGENTS.md b/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.
diff --git a/internal/duckdb/README.md b/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
