AGENTS.md

AI-first desktop app for agents, chats, scheduled tasks, and kanban tickets: Go + SQLite + Wails v3 + React UI. patio mcp exposes AI access over stdio. See README.md for features and usage.

Rules

• Always use pnpm, never npm or npx (use pnpm dlx).
• No CGO except the Wails desktop build on macOS/Linux; Windows and go test stay CGO-free. SQLite driver is modernc.org/sqlite.
• No ORM, no router library, no state or CSS framework. database/sql, net/http ServeMux patterns, React with a tiny pathname router.
• Plans live in docs/plans/.
• UI: no colored accent stripes on box edges (e.g. a primary border-left on callouts or a state-colored top border on cards). Use a plain var(--border) border.
• UI: never use window.alert, confirm, or prompt; the macOS Wails WebView ignores them (confirm returns false). Use confirmDialog from web/src/confirm.tsx.
• UI text: every user-facing string (labels, tooltips, aria labels, placeholders, errors) goes in the component's text.en and text.es via useText. Never hardcode English in JSX.
• New migration → update internal/mcp/schema.md.
• New or changed user-facing feature → add or update its stop in the feature tour (web/src/Tour.tsx): EN + ES text in text.*.steps, a stop in plan() targeting a data-tour attribute, ai: true if it needs a connector. Every feature plan or ticket includes this as a task.

Layout

• main.go: flags (-d, -show-hidden, -open), mcp subcommand, Wails app, OS-specific DB path in dbPath. One process per DB (Wails SingleInstance keyed by DB path); windows holds the main window and one window per popped-out chat (/ai/chats/<id>?window=chat). Closing main keeps chat windows; the last window quits.
• internal/db/: Open applies pragmas (foreign_keys, WAL, busy_timeout) via DSN, runs embedded migrations tracked by PRAGMA user_version, seeds users, and Watch detects external writes.
• internal/db/migrations/: numbered .sql files. Never edit an applied migration; add a new file.
• internal/api/: server.go (routes, JSON helpers, types), boards.go, tickets.go, transfer.go (export/import), calendar.go (calendar items + due tickets).
• internal/mcp/: MCP stdio server; requests act as user ai.
• internal/reminder/: claims due reminders once (notified_at) and fires OS notifications from the desktop app.
• web/src/: App.tsx (router), AIBadge.tsx, BoardList.tsx, BoardView.tsx, TicketDetail.tsx, PrintTicket.tsx, Calendar.tsx, api.ts (types + fetch).
• web/embed.go: //go:embed all:dist. web/public/.gitkeep keeps web/dist/ non-empty so go build works before a frontend build.
• web/src/desktop.ts: @wailsio/runtime wrapper (onEvent, openURL, isDesktop).
• Makefile: app (macOS 13+ .app), exe (Windows), linux; -tags production, VERSION= stamps main.version. Assets: build/darwin/Info.plist + icons.icns, rsrc_windows_amd64.syso (icon, DPI, manifest from build/windows/). No Taskfile/wails3 dev.

Domain invariants

• UI acting user is local; MCP acts as ai (Martin, is_ai=1).
• internal/db.Watch polls PRAGMA data_version; external writes emit Wails event db-changed for UI refresh.
• IDs are UUIDv4 TEXT generated in Go. Timestamps are ISO-8601 UTC TEXT.
• Ticket number comes from board_counter per board; code is <short_name>-<number>. Changing short_name rewrites codes and stores old ones in old_ticket_code.
• Ordering lives in JSON arrays: status_order, ticket_order, ticket_type_order. Corrupt order JSON must return an error, never an empty list.
• Every status change writes one ticket_history row ("Status changed from X to Y") and one ticket_status_transition row. Ticket creation writes a transition with from_status_id NULL. Same-column reorder writes neither.
• Multi-row writes run in one transaction. Never ignore DB or JSON errors.
• Lists with timestamps sort by timestamp, then rowid (insertion order), not random ids.
• -show-hidden only affects the UI (assignee). The API always serves it.
• JSON backup format patio-board version 1 must stay backward compatible. Import validates all references and remaps every id.
• Sanitize every rendered HTML description with DOMPurify. CSV/xlsx cells starting with = + - @ get a leading '.

Verify

gofmt -l internal                 # must be empty
go vet ./... && go test ./... -count=1
pnpm --dir web build              # runs tsc
make app                          # build/bin/patio.app
make release                      # CGO-free Windows compile check

Wails is pinned to v3.1.0 in go.mod and web/package.json (@wailsio/runtime); bump both together. The CLI is only needed to regenerate icons/syso (see docs/branding/README.md): go install github.com/wailsapp/wails/v3/cmd/wails3@v3.1.0.

Dev run: pnpm --dir web build && go run . -d "$(mktemp -d)/dev.db".

Smoke-test with a throwaway data dir: build/bin/patio.app/Contents/MacOS/patio -d "$(mktemp -d)/test.db".