The migration runner only applied missing embedded migrations and never
detected a DB that was AHEAD of the binary, so a brew/docker downgrade
silently ran old code against a newer schema. It also took no backup
before migrating, and there were zero upgrade docs.
- guardSchemaAhead: refuse to start when schema_migrations contains a
version that sorts after the highest embedded migration (a downgrade).
Escape hatch: 'pad start --force' / PAD_ALLOW_SCHEMA_AHEAD=1. Applied
to both the SQLite and Postgres migration paths.
- snapshotBeforeMigrate (SQLite only): copy the DB file to
<db>.pre-<VERSION> before applying pending migrations, but only when
upgrading an existing DB (pending AND already-applied migrations).
WAL-checkpointed, atomic temp+rename copy, and preserves an existing
snapshot on retry so a failed multi-step upgrade can't clobber the
original rollback point. Postgres is skipped (pg_dump/PITR is the DBA's).
- Docs: 'Upgrading Pad' in README + an 'Upgrading' section in
docs/deployment.md (forward-only rule, guard behavior, snapshot, flow).
* fix(cli): safe SQLite db backup/restore (config path + VACUUM INTO)
pad db backup/restore hardcoded ~/.pad/pad.db, so `docker exec pad db
backup` (container sets PAD_DATA_DIR=/data) and Windows layouts broke,
and the SQLite path did a torn io.Copy of pad.db + separate -wal/-shm
copy that could lose or tear in-flight WAL writes.
- Resolve the SQLite path via the server's config loader (PAD_DB_PATH >
PAD_DATA_DIR/pad.db > ~/.pad/pad.db) instead of os.Getenv("HOME").
Covers backup, restore, and migrate-to-pg's --from default.
- Replace the file copy with an online-safe `VACUUM INTO` through the
embedded modernc.org/sqlite driver: one self-contained file, no
-wal/-shm juggling, safe while the server is live.
- Restore refuses when a live server is detected (a running WAL
checkpoint could clobber the restored file); --force overrides.
- docs/backup.md: `pad db backup -o <file>` is the canonical SQLite
path (+ the `docker exec <container> pad db backup -o /data/backup.db`
form); dropped the "PostgreSQL-only" mislabel.
PostgreSQL pg_dump/psql paths are unchanged.
Fixes BUG-1996.
Claude-Session: https://claude.ai/code/session_01BoPkYhKqMiWPYmxQigeWsA
* fix(cli): fail restore on stale sidecar removal + drop unsafe backup doc
Address Codex review P2s:
- Restore: treat a failure to remove a stale -wal/-shm at the target as
fatal (was silently ignored). With single-file VACUUM INTO backups a
leftover sidecar would replay old WAL state over the restored DB.
- docs/backup.md: the SQLite strategy block still recommended a raw
`cp pad.db` daily; point it at `pad db backup --cron` instead.
Claude-Session: https://claude.ai/code/session_01BoPkYhKqMiWPYmxQigeWsA
Add a loopback-only account-recovery path so a self-hosted operator who
forgot their password (with no email provider configured) can recover
without editing the database by hand.
- POST /api/v1/auth/local-reset: loopback-gated, non-cloud, no auth
required (same trust model as bootstrap). Returns a single-use reset
link, or a temporary password with {"temp_password": true}.
- pad auth reset-password <email> [--temp-password]: talks to the local
server over loopback directly (not the configured public URL), so the
command works on the server host regardless of CLI config. Prints the
server's shareable reset_url when a public base URL is known.
- Web /forgot-password reads email_configured from the session and shows
host-recovery instructions instead of a dead "we emailed you a link"
when no provider is configured.
- forgot-password server log emits the reset path on non-cloud instances
so operators can also recover straight from the logs.
- Docs: CLAUDE.md + docs/deployment.md recovery sections.
Tests cover the loopback/cloud gates, the shareable reset_url, and both
output modes (reset link + temp password).
The README screenshot capture script ran in light mode because
Playwright's headless Chromium reports prefers-color-scheme: light by
default. The Pad layout's onMount logic explicitly forces
data-theme="light" when matchMedia matches 'light' — so the captures
came out light-themed even though Pad defaults to dark when no user
preference exists.
Two effects made this misleading:
1. README screenshots showed a theme most Pad users never see by
default. The first impression in the README didn't match the
first impression of the running app.
2. The screenshots could not be reused in the getpad.dev marketing
site (dark themed) without visible whiplash. TASK-918 (PLAN-911)
needs them on the homepage; light-mode captures would have looked
like screenshots of some other product.
Fix: pass colorScheme: 'dark' via test.use(). Chromium then reports
prefers-color-scheme: dark to the page; the layout's matchMedia check
no longer matches 'light', so it leaves the document on the default
theme — which is dark.
Also fixed a typo in the re-run instruction in the docstring (the
PAD_SCREENSHOTS=1 env var was attached to the wrong command).
Re-captured all three screenshots (dashboard, board, list) under the
new config. Docstring updated to call out the theme rationale so
future maintainers don't accidentally flip it back.
* fix(config): read PUBLIC_URL for emailed link generation (BUG-899)
The Pad Cloud deployment binds pad to 0.0.0.0 (Dockerfile, k8s configmap,
pad-cloud's docker-compose) and never set PAD_URL on the pad service, so
cfg.BaseURL() fell through to "http://0.0.0.0:7777" — that string ended
up in password-reset (and invite + share-link + admin-invitation) emails
and was unreachable to recipients.
Adds a PUBLIC_URL env var read by the server only (does not flip CLI to
remote mode the way PAD_URL does — PUBLIC_URL is a generic env var name
commonly set in unrelated deployment contexts). Stored in a separate
Config.PublicURL field consulted by BaseURL() as a fallback after URL.
Resolution order in BaseURL(): PAD_URL > PUBLIC_URL > host:port.
Also logs a WARN at server startup if the resolved base URL has an
unspecified bind-all host (0.0.0.0, ::, [::]) — a backstop that would
have caught BUG-899 the first time email went out.
Tests cover the precedence ladder, mode-not-flipping, PAD_URL-beats-
PUBLIC_URL, and the BUG-899 repro shape (Host=0.0.0.0 with no URL set
yields the broken http://0.0.0.0 URL).
Companion change in pad-cloud/docker-compose.yml passes PUBLIC_URL
through to the pad service so the Cloud deployment stops shipping
broken email links.
Parent: BUG-899 (TASK-908).
* fix(config): keep PUBLIC_URL out of IsConfigured() per Codex review (round 2)
PUBLIC_URL was setting LoadedFromEnv = true, which IsConfigured() consults
to decide whether the CLI has explicit configuration. A generic PUBLIC_URL
in the environment (very common name) would have made any host appear
"configured" to the CLI and skipped the not-configured / setup branch —
the exact footgun the separate-field design was supposed to avoid.
PUBLIC_URL is purely a server-side fact; LoadedFromEnv is purely a CLI
affordance. Stop conflating them. Adds a focused regression test pinning
the IsConfigured() invariant.
* fix(config): split PublicLinkBaseURL from BaseURL per Codex review (round 3)
Round 2's BaseURL fall-through to PublicURL leaked PUBLIC_URL into ~20
CLI-client call sites (cli.NewClientFromURL(cfg.BaseURL()) patterns
across cmd/pad/main.go, init.go, server_info.go, configure.go) — same
footgun the separate-field design was meant to avoid: a developer with
a host-level PUBLIC_URL set for unrelated reasons would have their CLI
silently route requests to that URL instead of the local server.
Restore BaseURL() to its original CLI-only contract (URL > host:port).
Add PublicLinkBaseURL() with the URL > PublicURL > host:port ladder
that's used at exactly the two server-side call sites that build
emailed-link targets:
- cmd/pad/main.go:279 srv.SetBaseURL(cfg.PublicLinkBaseURL())
- cmd/pad/main.go:464 email.NewSender(..., cfg.PublicLinkBaseURL())
Tests pin both contracts: BaseURL() ignores PublicURL even when set;
PublicLinkBaseURL() honors the precedence ladder. PAD_URL still wins
in both, preserving back-compat.
* fix(config): drop public_url toml tag to prevent CLI persistence per Codex review (round 4)
Round 3 left PublicURL serializable to ~/.pad/config.toml via toml:
"public_url". A CLI user who runs `pad init` or `pad configure` on a
host where PUBLIC_URL is set for unrelated reasons would end up with
that URL persisted into their config file, surviving any later unset
of the env var and contaminating server-side emailed link generation
indefinitely (server reads ~/.pad/config.toml on the next boot).
Switch the field to toml:"-". PUBLIC_URL is a deployment-time fact
(env var / docker-compose / k8s); operators who want a config-file
equivalent already have `url` (the PAD_URL path), which serializes
properly. Adds a regression test pinning that Save() never writes
PublicURL to the file.
Foundation doc for PLAN-900 (Cohesive UX between getpad.dev and Pad
Cloud). Defines the visual contract for surfaces that border between
marketing and product so the two codebases (this repo's web/ and
../pad-web) can converge intentionally rather than drift accidentally.
Central thesis (Section 1): cohesion applies at the SEAMS — auth pages
in Cloud mode, error pages, transactional emails — not in the deep
app. Self-hosted installs stay neutral throughout. Every parity
decision is gated on the existing cloud_mode flag (no new env var).
Concrete decisions baked in:
- Canonical color tokens anchored on pad-web/src/app.css; the app
side moves toward those values for bordering surfaces. Accent
palette (blue/green/amber/purple) is already aligned and stays.
- Type families: Inter + JetBrains Mono on bordering surfaces only;
workspace shell keeps system-ui (intentional — system feel inside
a tool).
- Header pattern (fixed top, blur backdrop, max-w-6xl, hamburger
spec) and footer pattern (link order, copyright format) specified
byte-level so a developer can rebuild either from this doc alone.
- Header link list deliberately differs between marketing and auth
pages (marketing carries Login CTA; auth pages don't); footer link
list and order are identical.
Includes a known-drift note flagging --text-muted: #666666 in
web/src/app.css as failing WCAG AA — pad-web's #8a8a93 passes. Out of
scope for this doc; tracked as a fast-follow.
No code changes — pure documentation. docs/ is not embedded in the Go
binary so this doesn't affect builds.
Migrates from xarmian/pad to PerpetualSoftware/pad across the entire
repo and updates the product subtitle to "Collaborate with your AI
agents".
Go module rename
- go.mod: github.com/xarmian/pad → github.com/PerpetualSoftware/pad
- All Go imports updated across cmd/pad, internal/{cli,server,store,
models,collections,items,events,metrics,webhooks} (~130 files)
- Test fixtures with the literal repo slug ("xarmian/pad" in JSON
shapes, SSH/HTTPS git URL strings, workspace_context fixtures)
also updated, including the secondary repo entry
(xarmian/pad-web → PerpetualSoftware/pad-web — pad-web was also
moved to the org per branch context)
Docs / config
- README badges, install instructions, brew tap, Docker image, source
build path, sponsor link (sponsor link kept as personal @xarmian)
- Subtitle: "Project management for developers and AI agents." →
"Collaborate with your AI agents." (README, manifests, web layout
meta, .goreleaser homebrew description)
- CONTRIBUTING.md, SECURITY.md, skills/INSTALL.md
- .goreleaser.yaml: homebrew_casks owner, GHCR image, release github
owner, cosign cert-identity regex, comments
- .github/workflows/release.yml: tap/release comments
- deploy/k8s/deployment.yaml: container image
- docs/deployment.md: clone URL
- web/static/{site.webmanifest,manifest.json}: description
- web/src/routes/+layout.svelte: meta description + og:description
Brew tap path is PerpetualSoftware/tap/pad (CamelCase, matches
GitHub user case). GHCR image is ghcr.io/perpetualsoftware/pad
(lowercased per GHCR's URL normalization). CODEOWNERS @xarmian and
FUNDING.yml github: xarmian intentionally retained — those are the
personal maintainer / sponsor account, separate from the org repo.
Verification: go build ./..., go test ./... (all pkgs pass), web
build, and make install all clean (TASK-844, TASK-845).
Merging despite Go (PostgreSQL) red — those failures (TestListItems_FTS_HyphenatedSearchTerm/task-five + TestAdminBillingStats_SidecarSidecarError_DegradesToLocalOnly TempDir cleanup race) are pre-existing on main and tracked in BUG-842.
Codex reviewed in 3 rounds (round 1 clean → round 2 found a real semantic bug → fix → round 3 clean). Tests, vet, and lint all green; remaining check failures are documented pre-existing.
The README had two TODO placeholders for screenshots that have been
sitting commented-out since the project started. With the launch
imminent, fill them in.
Captures:
- docs/screenshots/dashboard.png — workspace dashboard with Active
Work cards, Active Plans (v0.2 — Collaboration with progress),
collection summaries, recent activity.
- docs/screenshots/board.png — tasks board view, four columns
(Open / In-Progress / Done / Cancelled) with realistic task cards.
- docs/screenshots/list.png — list view (not currently referenced
from the README, but kept as part of the reproducible asset set).
Reproducibility:
web/e2e/screenshots.spec.ts is a gated Playwright spec (skipped
unless PAD_SCREENSHOTS=1) that uses the existing e2e fixture
infrastructure to:
1. Spin up a fresh pad binary against a clean data dir.
2. Bootstrap an admin + workspace seeded with the startup template.
3. Add a realistic demo dataset (1 active plan, 7 tasks across
open/in-progress/done with mixed priorities, 2 ideas).
4. Navigate + capture three views at 1440x900.
To regenerate:
make build
cd web && PAD_SCREENSHOTS=1 PAD_E2E_PORT=17801 \\
npx playwright test screenshots --project=desktop-chromium
Notes:
- Table view (?view=table) was originally in scope but the URL
parser only accepts list/board today; setting via toggle would
require localStorage manipulation. Three screenshots already
cover the README's needs; revisit if/when table view becomes
URL-reachable.
- Dark/light variants were also in scope but the web UI is dark-
mode-only at present, so the captures are dark-only.
Refs: TASK-673
Grouped nice-to-haves called out in the pre-launch audit.
1. docs/architecture.md — new contributor-focused architecture doc.
CLAUDE.md covers the same ground but is agent-oriented; this is the
human companion. Covers backend layout, request flow, frontend /
data model / CLI↔daemon model / agent integration / testing.
2. .env.example — extended to document every PAD_* variable in
docs/deployment.md (core, database, real-time events, security,
email). Existing Postgres/Redis + encryption secrets kept at the
top; new variables grouped by concern with inline comments and
safe defaults commented out.
3. .gitattributes — normalize LF line endings repo-wide, mark binary
assets, and flag web/build + web/.svelte-kit as generated so they
don't pollute GitHub linguist stats or PR diffs.
4. Makefile — CAUTION comment on `make install` noting that the
`killall -9 pad` step is system-wide; anyone else's pad daemon on
the same machine gets killed too. Designed for single-developer
local setups; not for shared hosts.
Parent: PLAN-644.
The 'pad serve' command does not exist in this binary — its canonical
name has been 'pad server start' for some time. Users following the
systemd example in docs/deployment.md would get a non-starting service
today. Six real references fixed:
- cmd/pad/main.go:5714 — migrate-to-pg help text
- cmd/pad/main.go:5795 — 'Next steps' instruction
- docs/backup.md:81,94 — Postgres migration walkthrough
- docs/deployment.md:116 — binary launch example
- docs/deployment.md:164 — systemd ExecStart
Repo-wide grep is now clean of 'pad serve' outside gitignored
v1-archive/ and .pad/ (local workspace data). README.md was already
correct.
Parent: PLAN-644.
- pad db backup: wraps pg_dump with --output and --cron flags
- pad db restore: wraps psql with confirmation prompt and --force
- pad db migrate-to-pg: one-time SQLite→PostgreSQL migration using
application-level export/import for all workspace data
- docs/backup.md: comprehensive backup strategy guide covering SQLite,
PostgreSQL, cloud snapshots, and disaster recovery
xarmian