clawhub AGENTS.md

Repository Guidelines

Project Structure & Module Organization

• src/ — TanStack Start app code (routes, components, styles).
• convex/ — Convex backend (schema, queries/mutations/actions, HTTP routes).
• convex/_generated/ — generated Convex API/types; committed for builds.
• docs/ — publishable public/operator docs for the ClawHub docs tab.
• specs/ — product specs, plans, regression notes, design history (see specs/spec.md).
• public/ — static assets.

Durable Intent & Specs

• Use specs/ to persist system/subsystem intent, invariants, and design rationale that future agents should preserve.
• Keep intended behavior for security-sensitive flows there, especially moderation, upload gating, scanner outcomes, appeals, bans, ownership, package installability, and API trust boundaries.
• If code changes reveal or change how a subsystem is supposed to work, update the relevant spec or add a focused spec note instead of burying the intent only in PR text or public docs.
• Keep docs/ user/operator-facing: explain current behavior and commands there, but put internal “why this must work this way” context in specs/.

Build, Test, and Development Commands

Keep this section as the command map agents normally need, not a full package.json script index.

• bun run dev — foreground local app server at http://localhost:3000.
• bunx convex dev --typecheck=disable — local Convex backend/function watcher for manual setup.
• bunx convex codegen — regenerate convex/_generated after Convex API/schema changes.
• .worktreeinclude — Codex-managed worktrees copy ignored local state (.env.local, .convex/, and node_modules/) from the local checkout at creation time.
• bun run setup:worktree — validate copied .env.local / .convex state, or link missing fallback state from a usable source worktree. Use -- --from <path> or CLAWHUB_WORKTREE_SOURCE=<path> when auto-discovery picks the wrong source.
• bun run dev:worktree — Worktrunk-managed detached worktree server that also seeds local fixtures plus the public corpus once before starting the app when VITE_CONVEX_URL and CONVEX_DEPLOYMENT are local. Requires wt on PATH; from that worktree use wt --yes url to print the branch URL and wt --yes stop to stop it.
• bun run seed:dev — manual reseed path; runs worktree setup, waits for local Convex, seeds local fixtures plus the public corpus, and refreshes stats.
• bun run seed — shared non-production seed pipeline used by local setup and disposable PR previews after their target Convex deployment is ready.
• bun run build — production build (Vite + Nitro).
• bun run ci:static — required pre-handoff static gate: peer checks, audit, formatting, lint, and dead-code checks.
• bun run ci:unit — Vitest coverage gate; required for source/test PRs unless docs/config-only.
• bun run ci:types-build — full TypeScript/build gate for app, Convex, and packages.
• bun run ci:packages — schema, CLI, and moderation package verification.
• bun run ci:e2e-http — secretless HTTP and CLI e2e subset.
• bun run ci:playwright-smoke — chromium smoke against the public read backend.
• bun run test:pw:local-auth — local Convex/dev-auth browser gate for signed-in/write flows.