dckc/captoys

0 Fork 0

Files

T

dckc d0a9b899f2 docs: goal tree and rules track the 1c cache

- checklist: 1c (diigo-dump evolves into a bookmark cache) with its
  create-flow, id-wiring, and verification subgoals
- notes: diigo-cache replaces diigo-dump in What-we-built
- AGENTS: no worker secret since 1c; durable state — be LOUD and
  conservative about breaking changes to stored DB state; pointer to
  the workspace skills for commit trailers

Generated-by: opencode (GLM)
Generated-by: Claude Opus 5.5

2026-10-07 04:19:54 -05:00

2.3 KiB

Raw Blame History

capsite working rules

Applies to AI agents working in capsite/ (goal tree + how-to-run: capsite-checklist.md; background: the capsite notes; workspace-wide policy: AGENTS.md — points to the workspace skills, incl. commit trailers).

Dev servers are the user's job

The assistant never starts, stops, or restarts long-running dev servers (wrangler dev, pnpm dev/astro dev). The user runs them and owns the terminals; the assistant observes via .tmp/capsite.script (the script capture; use watchme). One-shot codegen (wrangler types), linters, typechecks, and tests are fine.

Durable state: be LOUD and conservative about breaking changes

Persistence is a big deal here: DO ids (cache ids, webapp ids, public ids) are headed toward representing real-world assets. A change that leaves existing stored state unreadable, unreachable, or differently interpreted is a breaking change, even in dev.

Before making it, say so, prominently: what stored state breaks, why, and the options (migrate, stay compatible, or reset). Get the user's go-ahead; don't discover it after the fact.
Prefer compatibility: read old shapes, add fields rather than repurpose them, migrate in place (schema steps like SCHEMA_V1 → V2).
No silent resets. "Wipe .wrangler/state" is a last resort the user chooses, never the default advice.
Cover it with a test: old-shape state in, current code reads it.

(Prompted 2026-10-07: making PublicCache fetch through its own wiring left public caches created by the earlier ingest code unwired — a 502, and no way back through publish.)

Secrets discipline

Worker secrets never in source or wrangler config. .dev.vars (gitignored) locally; wrangler secret put deployed. Since the 1c cache evolution, no worker secret is needed at all: the cookie lives only in the webapp DO's storage; the webapp-instance id rides the cache DO's wiring; the cache id is a user-held capability (password manager / per-POST paste). Error messages must not contain header or param values (they cross RPC as exceptions and land in logs); URLs appear query-stripped.

Keep config types generated

Run wrangler types after any wrangler.jsonc change (worker-configuration.d.ts is generated, gitignored; hand-rolled cloudflare:workers shims drift and gave red squiggles).