pad: Instructions file for Claude Code

Pad — Development Guide

What This Is

Pad is a project management tool for developers and AI agents. Single Go binary with embedded SvelteKit web UI, SQLite storage, and multi-agent skill support (Claude Code, Cursor, Windsurf, Codex, OpenCode, Copilot, Amazon Q, Junie).

Related repo: The marketing website (getpad.dev) lives at ../pad-web — a separate SvelteKit site deployed to Vercel.

Architecture

• Backend: Go (cmd/pad/main.go) → REST API (internal/server/) → SQLite (internal/store/)
• Frontend: SvelteKit 2 + Svelte 5 (web/src/) → static build embedded in Go binary
• Data model: Workspaces → Collections (typed with JSON schemas) → Items (structured fields + rich content)
• CLI: Cobra commands in cmd/pad/main.go, HTTP client in internal/cli/
• Agent skill: Single natural-language /pad skill in skills/pad/SKILL.md

Build & Install

make build      # Build web UI + Go binary (./pad)
make install    # Build, kill server, install to ~/.local/bin/pad, restart
make build-go   # Build Go only (skip web — faster when only backend changes)
make test       # Run Go tests
make web        # Build web UI only
make dev-web    # Run SvelteKit dev server (hot reload on :5173)

After making changes, always run make install to rebuild the binary, install it, and restart the server. The web UI at http://localhost:7777 will reflect the changes.

Quick iteration loop

• Backend only: make install (skips web rebuild if no frontend changes — edit Makefile to use build-go instead of build in the install target)
• Frontend only: make web && make install or use make dev-web for hot reload during development
• Full rebuild: make install

Working in a git worktree

Agent sessions take a git worktree per task rather than sharing the main checkout (a shared checkout means a shared stash stack, branch state, and dirty files across sessions). Three rules keep web tooling working there:

• Give each worktree its own web/node_modules: run npm ci in its web/. Do not symlink the main checkout's copy. It installs from the npm cache in about 5s warm, costs about 470 MB of disk per live worktree, and runs svelte-kit sync as a side effect. A symlink tests the worktree against whatever the MAIN checkout last installed. web/package-lock.json changes every few days, and the main checkout is not kept current, so that is routinely the wrong dependency set: on day 86 (2026-10-05), worktrees borrowed Tiptap 3.31.3 after main had moved to 3.31.4, plus a materializer bundle built from it, and the corpus tests failed for reasons that had nothing to do with the change. SvelteKit 3 also writes its generated tsconfig inside node_modules with relative paths, so through a symlink a worktree's type check would silently check the main checkout's tree (TASK-3423). (Dave's ruling, 2026-10-06. A pnpm-style shared store is the follow-up if disk becomes the constraint.)
• A fresh worktree has no web/.svelte-kit (gitignored, generated). Run npx svelte-kit sync in web/ before any vitest/vite command — or npm run check, which syncs first. Without it, vitest fails with Failed to load tsconfig '.svelte-kit/tsconfig.json': Tsconfig not found regardless of how node_modules was set up. (This missing generated dir was historically misdiagnosed as a symlink problem — npm ci "fixed" it only because its prepare script runs svelte-kit sync.)
• A fresh worktree has no web/build either, and that one breaks the GO gates rather than the web ones. embed.go does //go:embed all:web/build, so make test and make lint fail with pattern all:web/build: no matching files found before a single test runs — go build ./... dies first, two packages report [setup failed], and it reads as a broken tree rather than a missing generated directory. npx vite build in web/ fixes it (make web would too, and is FORBIDDEN here — see the next rule). It also has no web/build-materializer (TASK-2198, gitignored, generated): embed.go does //go:embed web/build-materializer/materializer.js, and a missing file fails go build ./... the same way, with pattern web/build-materializer/materializer.js: no matching files found. Run node scripts/build-materializer.mjs in web/ after npx vite build (npm run build does both). It is built with esbuild, which is a devDependency of its own (vite 8 does not bring it), so a web/node_modules older than the lock file that added it cannot build the bundle. Unlike web/build, a placeholder file here is not enough for make test: internal/materialize's tests run the real bundle.