Pad v0.5.0

v0.5.0 — Release Highlights

Onboarding overhaul — the /pad onboard flow (PLAN-1496)

Workspace setup is now driven entirely by the canonical /pad onboard invokable library playbook, auto-seeded into every new workspace (including a new blank template that ships only the onboard playbook). The pre-existing IDEA-1 / BACK-1 / FEAT-1 first-person seed pattern is retired across all software templates. A new needs_onboarding flag in the agent bootstrap response lets the skill render a one-line nudge until the first user-created item appears. Collection/role rename + delete now ship as agent-callable surfaces (pad collection update|delete, pad role update, plus matching MCP actions) so the onboarding agent can adapt seeded scaffolding to the actual project.

Invokable playbooks v1 (PLAN-1377 + PLAN-1397)

Playbooks are now first-class invocable procedures. New schema fields invocation_slug (workspace-unique kebab-case) and structured arguments make /pad ship, /pad plan, /pad decompose, /pad onboard dispatch directly from Claude Code, the CLI (pad playbook run …), and MCP (pad_playbook tool with list/get/run actions). The agent bootstrap response embeds per-playbook metadata so routing happens with zero extra tool calls. A dedicated web editor at /[ws]/playbooks/[slug] handles slug validation, args builder, and live test-invocation preview. The library was overhauled to surface invokable workflows first; nine pre-PLAN-1377 trigger-only bodies were archived (compiled but not surfaced) pending per-entry promote/retire decisions.

URL import (TASK-1469–1474)

Pull external content directly into items: new POST /api/v1/import/url endpoint with an SSRF-guarded fetcher, generic HTML→Markdown conversion, and a dedicated OpenAPI 3.x→Markdown converter. The TipTap editor gets an "Insert from URL" toolbar button and modal. Imported items carry a source_url ghost-field with a one-click "Refresh from source" affordance.

OAuth connections + unified Connect-to-agent modal (TASK-1520–1528)

Connected apps now live in per-connection state tables (with dual-read introspection during the cutover), a rewritten consent screen, full CRUD mutation endpoints, and an edit UI. The new Connect-to-agent modal unifies what was previously several disjoint flows into a single claim-code experience; pad_workspace.create and pad_workspace.claim MCP actions let agents bootstrap a new workspace without leaving the assistant. Post-workspace-create, the Connect modal opens automatically to guide users to their first agent install.

MCP bootstrap v0.4 — ~40% lighter payload (PLAN-1410)

The bootstrap envelope returned by pad_set_workspace, pad_meta.action: bootstrap, and pad://workspace/{ws}/bootstrap is substantially slimmer: BootstrapCollection and BootstrapRole projections drop UUIDs/timestamps/settings, recent_activity duplication is removed, dashboard sub-arrays are capped at 5 with parallel overflow counts, and redundant schema labels are omitted. One breaking shape change for MCP clients: collections[].schema is now a nested JSON object instead of a JSON-encoded string — clients that previously JSON.parse()'d the value must consume it directly. ToolSurfaceVersion is bumped to 0.4 to advertise the contract.

Store hardening (IDEA-1479–1489)

Migrations now run inside atomic transactions. collections.settings is enforced NOT NULL with end-to-end normalization and a corrective backfill for legacy shape violations. JSONB NOT NULL hardening extended to items and views, with handler-level shape validation closing the loop. Workspace freshness ordering now reflects item activity, not just workspace mtime.

Bug fixes

open_children 409 surfaced in the web UI with a force-override path (BUG-1538); SSE write errors no longer silently drop (BUG-1532) and keepalive is linked to IdleTimeout; search palette no longer hangs on numeric queries (BUG-1531); scroll restoration uses SvelteKit's snapshot API (BUG-1425); Y.Doc seed waits for workspace items so wiki-links don't bake in as plain text (BUG-1461); MCP per-token burst raised and 429s correctly classified as ErrRateLimited (BUG-1430); MCP item create accepts flexible field-JSON shapes (BUG-1431/1432); slash-menu matches against id + keywords (BUG-1419); typed-input field saves debounced and same-field activity runs collapsed (BUG-1466); CLI pins server URL in .pad.toml for remote workspaces (BUG-1535); plus the --sort-order flag on pad item update (BUG-1536).

Other notable

• Cross-workspace wiki-link resolution (IDEA-1492)
• pad session shape CLI for Claude Code context-window telemetry (IDEA-1491)
• Refusal to mark an item terminal while it has open children (IDEA-1494)
• Generic ship playbook seeded in the startup template
• Single-roundtrip /pad context-load via GET /api/v1/workspaces/{ws}/agent/bootstrap

Install

# Homebrew (macOS / Linux)
brew install perpetualsoftware/tap/pad

# Docker (multi-arch)
docker pull ghcr.io/perpetualsoftware/pad:0.5.0

# Direct download
# https://github.com/PerpetualSoftware/pad/releases/tag/v0.5.0

Verifying

All artifacts are signed via Sigstore keyless OIDC. To verify the checksums:

cosign verify-blob \
  --certificate-identity-regexp "^https://github.com/PerpetualSoftware/pad/.github/workflows/release.yml@.*" \
  --certificate-oidc-issuer "https://token.actions.githubusercontent.com" \
  --certificate checksums.txt.pem \
  --signature  checksums.txt.sig \
  checksums.txt

The container image manifests are likewise cosign-signed; SBOMs (SPDX) ship alongside each archive, and SLSA v1 build provenance is attested per-archive (verify with gh attestation verify <archive> --repo PerpetualSoftware/pad).

---

Changelog

Features

• 9ebdfb5: Revert "feat(cli): pad session shape — Claude Code context-window telemetry (IDEA-1491) (#569)" (#570) (@xarmian)
• 24f0445: feat(bootstrap): single-roundtrip /pad context-load endpoint (TASK-1379) (#518) (@xarmian)
• 96a32aa: feat(bootstrap,skill): add needs_onboarding flag + retire legacy Onboarding workflow (TASK-1504,1505) (#578) (@xarmian)
• a3799a1: feat(cli): add --sort-order flag to pad item update (BUG-1536) (#596) (@xarmian)
• 351f83a: feat(cli): pad session shape — Claude Code context-window telemetry (IDEA-1491) (#569) (@xarmian)
• f76520f: feat(cli,mcp): expose 'collection delete' via CLI and MCP catalog (TASK-1511) (#573) (@xarmian)
• f557930: feat(cli,mcp): expose 'collection update' via CLI and MCP catalog (TASK-1510) (#572) (@xarmian)
• 8c9974f: feat(cli,mcp): expose 'role update' via CLI and MCP catalog (TASK-1512) (#574) (@xarmian)
• 7c663a3: feat(collections): add blank workspace template + retire auto-upgrade hook (IDEA-1479) (#560) (@xarmian)
• 936145c: feat(collections): seed generic ship playbook in startup template (TASK-1386) (#523) (@xarmian)
• 4bbd0a2: feat(collections): widen LibraryPlaybook with InvocationSlug + Arguments (TASK-1398) (#527) (@xarmian)
• fc6afd0: feat(connect): unified Connect-to-agent modal + claim-code endpoint (TASK-1525) (#586) (@xarmian)
• 8efcc21: feat(library): add ship playbook to library, shared body with startup seed (TASK-1400) (#529) (@xarmian)
• 8eb927c: feat(library): author the decompose invokable playbook (TASK-1402) (#531) (@xarmian)
• ad3926f: feat(library): author the plan invokable playbook (TASK-1401) (#530) (@xarmian)
• 8094883: feat(links): cross-workspace wiki-link resolution (IDEA-1492) (#568) (@xarmian)
• 9607139: feat(mcp): add pad_playbook tool (list/get/run) (TASK-1381) (#521) (@xarmian)
• 73208bf: feat(mcp): expose AgentBootstrap via three MCP surfaces (TASK-1380) (#519) (@xarmian)
• aec67e2: feat(mcp): workspace.create + workspace.claim actions + claim-code mechanics (TASK-1521) (#582) (@xarmian)
• 905baaa: feat(oauth): backfill session.Extra into oauth_connections + switch read path (TASK-1522) (#583) (@xarmian)
• 26aa800: feat(oauth): connected-apps mutation endpoints + edit UI (TASK-1524) (#585) (@xarmian)
• 93b9590: feat(oauth): consent screen rewrite + new-tables write path (TASK-1523) (#584) (@xarmian)
• 3f6bcc0: feat(oauth): per-connection state tables + dual-read introspection gate (TASK-1520) (#581) (@xarmian)
• fed4b60: feat(playbook): add pad playbook CLI (list/show/run) + endpoints (TASK-1382) (#520) (@xarmian)
• c38b3bf: feat(playbooks): add invocation_slug + arguments schema fields (TASK-1378) (#517) (@xarmian)
• 507793e: feat(playbooks): author canonical /pad onboard library playbook (TASK-1499) (#576) (@xarmian)
• e621eac: feat(server): POST /api/v1/import/url endpoint + integration tests (TASK-1472) (#556) (@xarmian)
• e59d390: feat(server): refuse to mark item terminal while it has open children (IDEA-1494) (#571) (@xarmian)
• ec71903: feat(store): JSONB NOT NULL hardening on items/views + handler shape validation (IDEA-1486+1488) (#566) (@xarmian)
• 7134216: feat(store): corrective backfill for collections.settings shape violations (IDEA-1489) (#567) (@xarmian)
• 0766d7e: feat(store): enforce NOT NULL on collections.settings (IDEA-1484) (#562) (@xarmian)
• 853a7cd: feat(store): wrap migrations in atomic transactions (IDEA-1485) (#565) (@xarmian)
• cc0b1c0: feat(templates): finalize 'blank' template with minimal-vocab seeds for /pad onboard (TASK-1498) (#575) (@xarmian)
• 8771f95: feat(urlimport): OpenAPI 3.x → Markdown converter (TASK-1471) (#555) (@xarmian)
• 0aa3988: feat(urlimport): URL fetcher with SSRF guard + content-type detection (TASK-1469) (#552) (@xarmian)
• d156060: feat(urlimport): generic HTML→Markdown converter (TASK-1470) (#553) (@xarmian)
• 403cf6b: feat(web): Blank-first picker + post-create /pad onboard guidance (TASK-1506) (#579) (@xarmian)
• 3a2ee6a: feat(web): Insert from URL — TipTap toolbar button + modal (TASK-1473) (#557) (@xarmian)
• f8af6cb: feat(web): blank-as-default workspace modal + auto-open Connect modal post-create (TASK-1528, TASK-1526) (#592) (@xarmian)
• b969dd7: feat(web): consolidate workspace-create surfaces — redirect /console/new to modal (#593) (@xarmian)
• 1d3b1a5: feat(web): first-class playbook editor — slug validation, args builder, test invocation (TASK-1384) (#524) (@xarmian)
• d3bd195: feat(web): source_url ghost-field + Refresh from source affordance (TASK-1474) (#558) (@xarmian)
• 2a5b011: feat(web): surface invocation_slug + arg count on library playbook cards (TASK-1399) (#528) (@xarmian)
• e27f805: feat(web): unify dashboard onboarding banners around needs_onboarding signal (TASK-1530) (#594) (@xarmian)
• 0930743: feat: retire IDEA-1 seed pattern + 'pad onboard' cobra + surface blank in init (TASK-1501/1502/1503) (#577) (@xarmian)

Bug fixes

• db87b47: fix(cli): pin server URL in .pad.toml for remote workspaces (BUG-1535) (#595) (@xarmian)
• 3508a83: fix(cli): reject NaN/Inf in --field number parsing per Codex review (round 1) (@xarmian)
• c2014fa: fix(cli): schema-aware --field parsing for non-string typed fields (BUG-1125) (@xarmian)
• ab5b68c: fix(connect): correct self-host copy in claim-code disabled state (TASK-1525 follow-up) (#587) (@xarmian)
• b1fcedd: fix(editor): match slash menu against id + keywords (BUG-1419) (#551) (@xarmian)
• 38aa872: fix(fields,activity): debounce typed-input field saves + collapse same-field activity runs (BUG-1466) (#549) (@xarmian)
• 438cb61: fix(mcp): flexible JSON shapes on item create + clearer field surface (BUG-1431, BUG-1432) (#547) (@xarmian)
• 088ba2f: fix(mcp): raise MCP per-token burst + classify 429 as ErrRateLimited (BUG-1430) (#546) (@xarmian)
• 8041b46: fix(sse): surface write errors and link keepalive to IdleTimeout (BUG-1532) (#590) (@xarmian)
• 714da48: fix(store): handle nullable collections.settings end-to-end (BUG-1482) (#561) (@xarmian)
• be68292: fix(store): workspace list freshness reflects item activity (BUG-1481) (#559) (@xarmian)
• d7b99de: fix(web): await workspace items before Y.Doc seed so wiki-links don't bake in as text (BUG-1461) (#548) (@xarmian)
• 312cf06: fix(web): merge defaults in parseSettings/parseSchema (IDEA-1487) (#564) (@xarmian)
• 9fb6ac0: fix(web): scroll restoration via SvelteKit snapshot API (BUG-1425) (#545) (@xarmian)
• 8fb46ca: fix(web): surface open_children 409 + offer force override (BUG-1538) (#597) (@xarmian)
• bfce069: fix(web,build): search palette hang on numeric query + graceful SSE shutdown (BUG-1531) (#588) (@xarmian)

Refactors

• 638a456: refactor(bootstrap): dedup recent_activity, drop convention slug, cap dashboard arrays (TASK-1413) (#536) (@xarmian)
• aaa581b: refactor(bootstrap): extend dashboard caps to active_items/active_plans/by_role (TASK-1422) (#541) (@xarmian)
• d18a5d8: refactor(bootstrap): omit redundant schema labels + omitempty sort_order (TASK-1424) (#543) (@xarmian)
• 8da0473: refactor(bootstrap): slim Collections projection — drop id/timestamps/settings, parse schema inline (TASK-1412) (#535) (@xarmian)
• ad87b96: refactor(bootstrap): slim Roles projection (BootstrapRole struct) (TASK-1423) (#542) (@xarmian)
• 8fa1dd3: refactor(library): archive 9 pre-PLAN-1377 playbook bodies, rebuild library as invokable-first (TASK-1403) (#532) (@xarmian)
• 7e37dfc: refactor(store): collections.settings boundary normalization + scan revert (IDEA-1484 follow-up) (#563) (@xarmian)

Other changes

• 957582e: build: untrack regenerated .agents skill copy (gitignored, install-time output) (@xarmian)
• 9c9aac3: chore(bootstrap): tighten size budget 8 KiB → 7 KiB to lock in PLAN-1410's win (TASK-1417) (#540) (@xarmian)
• de8679f: chore(mcp): bump ToolSurfaceVersion 0.3 → 0.4; document v0.4 envelope (TASK-1418) (#544) (@xarmian)
• b801867: chore(web): npm audit fix — svelte 5.55.8, devalue 5.8.1, mermaid 11.15.0 (#589) (@xarmian)
• efccea6: docs(skill): compress CLI Reference to patterns the skill drives (TASK-1414) (#537) (@xarmian)
• 6a981e7: docs(skill): compress NL Routing examples, trim playbook authoring, drop MCP note (TASK-1416) (#539) (@xarmian)
• 335b145: docs(skill): replace Planning/Decomposition workflow fallbacks with one-liner playbook pointers (TASK-1415) (#538) (@xarmian)
• 955553b: docs(skill): rewrite /pad skill for bootstrap + slug routing (TASK-1383) (#522) (@xarmian)
• 1db0e6a: docs+test: closes the PLAN-1397 library overhaul loop (TASK-1404) (#533) (@xarmian)
• 91f1c0a: test(bootstrap): add size-budget benchmark for the agent bootstrap response (TASK-1411) (#534) (@xarmian)
• 2a1a00e: test,docs: blank+onboard+needs_onboarding integration test + CLAUDE.md update (TASK-1507,1508) (#580) (@xarmian)