Use these docs with your AI assistant

pgxsinkit is easy to misunderstand from the source alone — the read and write paths are asymmetric, the write path is deliberately a single in-database function, and local pgwasm schema is not a full mirror of Postgres. These docs publish machine-readable summaries so an assistant can load the correct model without re-deriving it from the whole repository.

The llms.txt files

File	What it is
/llms.txt	Index of the docs with short descriptions.
/llms-full.txt	The entire documentation as one file.
/llms-small.txt	A compressed variant for tighter context windows.

How to use them

• Working in a consuming codebase: fetch https://pgxsinkit.github.io/llms-full.txt into your assistant’s context before asking it to wire sync, or link it from your own agent guide.
• Contributing to pgxsinkit itself: the canonical vocabulary lives in the repository’s CONTEXT.md, and the agent guide is AGENTS.md — read those first.

Agent Skills shipped in the packages

The @pgxsinkit/* packages also ship TanStack Intent Agent Skills — task-scoped SKILL.md guidance bundled inside the npm package, so it is pinned to the exact version you installed. They complement llms.txt rather than replace it: llms.txt is the broad model you pull by URL; a skill is a focused checklist your assistant loads at the moment it reaches for that task, and it travels with the dependency.

Skill	Package	Load it before…
core	@pgxsinkit/client	wiring sync at all — the two asymmetric paths, the single in-database write path, how the read path fails closed (401 at the control plane, 403 at the edge), and why the local pgwasm schema is not full DDL parity.
registry-authoring	@pgxsinkit/contracts	defining a registry — the writable-table rules (a server-version field and a conflict policy), server-managed fields, authoring row filters with the p.* predicate builders, and deriving the read filter and RLS from one predicate.
operating	@pgxsinkit/client	shipping to production — runtime latency, capability-driven worker placement (Safari SW-direct; Chromium/Firefox elected), OPFS-vs-idb durability, relocation outcomes, backend permanence and destruction, diagnostics, and the forwarded debug rail.
deploying	@pgxsinkit/server	deploying the write API, the read path’s control plane, and the stream edge on Bun / Deno / Supabase Edge / Workers — bundling for Deno, the function-name path rewrite, and resolving claims from the platform JWT.
react	@pgxsinkit/react	building React components — createSyncClientHooks, the live read hooks, the snake_case→field-key remap, and that writes go through client.tables.<t>, not the hooks.
opfs	@pgxsinkit/pgwasm	constructing the constant-handle OPFS-repacked store (@pgxsinkit/pgwasm/opfs) in a capability-proven worker scope — dedicated workers on Chromium/Firefox, SharedWorkers on real Safari — plus factory-owned durability, extent identity, complete-directory recreation, and stable error remedies.

Discover and load them with the TanStack Intent CLI, from a project that has @pgxsinkit/* installed:

bunx @tanstack/intent@latest list                          # every skill the installed packages ship
bunx @tanstack/intent@latest load @pgxsinkit/client#core   # print one skill
bunx @tanstack/intent@latest install                       # add "load a matching skill first" guidance to AGENTS.md / CLAUDE.md

The six things assistants get wrong

1. It is a toolkit, not a demo or a data layer. The @pgxsinkit/* packages are the product.
2. The two paths are separate and asymmetric. Writes do not travel back down the read path.
3. There is one write path. No selectable backend; one in-database apply function.
4. The engine’s table list is explicit, never *. CIRCUITS_PG_TABLES names bare table names; * sweeps in every public table with a primary key. A schema-qualified registry is refused outright — the engine keys tables by bare name end to end.
5. The local pgwasm schema is not full DDL parity with Postgres.
6. Browser storage is capability-selected, not browser-named. Capability worker mode prefers OPFS-repacked: real Safari runs SW-direct, Chromium/Firefox elect a dedicated worker, and idb is the fallback. Read BootReport.storageBackend/engineHome; do not infer from WebKitGTK or user-agent text.

Each is covered in Core concepts.

Operational gotchas that aren’t visible in the code

These do not show up when reading the toolkit source — they are properties of the runtime around it, and each silently makes a live app feel slow or flaky. An assistant wiring a real deployment should load Operating in production and apply them up front:

• Writes flush on enqueue, not on the interval. The convergence interval is a fallback; keep it long (idle CPU), do not shorten it to chase write latency.
• The stream edge belongs on its own origin, with cache-control: no-store on the control plane beside it and the stream token excluded from the cache key. The edge is the only cacheable read surface, and it can only be fronted if it is addressable apart from the private one.
• Every createStreamGate mount must set Access-Control-Expose-Headers from the exported STREAM_READ_EXPOSED_HEADERS. Without it a cross-origin browser cannot read the stream headers the client steers its read loop off, and every read fails (older clients, built on @durable-streams/client, instead re-request from the start of the stream in a hot loop, with no error raised on either side).
• A browser opens one long-poll connection per stream. With several streams the HTTP/1.1 ~6-per-origin cap starves writes — serve the gateway over HTTP/2.
• Serverless edges cold-start. The first write after idle lags; warm the worker and set its wall-clock timeout above the durable-streams long-poll hold.
• Debug latency with globalThis.__pgxsinkitDebug, and measure at the network boundary — polling the local store in a loop inflates the number it reports.
• In a browser, attach through a SharedWorker (defineSyncWorker + attachSyncClient) to take the local store off the main thread. Capability placement is automatic — there is no placement option; pass the SharedWorker as a factory (worker: () => SharedWorker) and the elected engine is auto-derived from the SharedWorker’s own script URL (supply createEngineWorker only for non-module/underivable entries). Storage is declared on the registry (storage.backend/storage.durability/storage.build, defaulting to opfs/relaxed/c); force idb with storage.backend: "idbfs". Safari runs in that SharedWorker; Chromium/Firefox elect a dedicated engine behind it. Always pass extendedLifetime: true, and branch on EngineRelocatedError.outcome rather than blindly retrying a mutation. See Worker mode.