Add public guide: designing state for agents to consume

[TennyZhuang]

Problem

Hands is agent-native: agents poll for what changed and act without a person in the loop. That places requirements on a change feed that a human-facing list does not have — a missed row is a missed action, an extra row is a duplicate one. Nothing documented that, so each new feed would re-derive it.

Requested by @artin for the public docs site.

Changes

Adds docs/public/agent-native-state-delta.md, public guidance for anyone building an agent-consumable feed or an integration mirroring Hands state:

1. Exact cursor, not a timestamp — updated_at drops same-millisecond changes and is moved by unrelated internal writes. Use a database-assigned monotonic sequence, and measure the write cost before choosing whether it lives on the record or in an append-only side table.
2. Advance only on material change — housekeeping that moves the cursor wakes the agent with noise from your own system and causes the duplicate reporting the cursor exists to prevent.
3. Keep consumer progress out of the source of truth — a "needs processing" flag is one consumer's state, and field-level history duplicates a diff the consumer can already compute from the snapshot it holds.
4. Keep internal-only values out of every externally visible carrier — including event payloads, webhooks and pagination cursors, and including the gap between two values. Base64 is encoding, not concealment.
5. Scope the sequence per tenant — functionally identical, but bounds what an accidental exposure reveals.

Also registers the page in admin/scripts/build-docs.mjs. Files in docs/public/ are not discovered by directory scan — an unregistered page builds nothing and silently never appears on the site.

Testing

• node admin/scripts/build-docs.mjs → Built 15 docs pages + 14 markdown twins + docs.md index
• Page renders with <title>Designing State for Agents - Hands Docs</title> and appears in the generated index and sidebar under "For agents"
• Build output under admin/public/docs is gitignored and not committed

Documentation only — no code, schema, or behaviour change.

🤖 Generated with Claude Code