# PrintToVeraeTimeStamp — Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Ship a "Verae Timestamp" virtual printer for macOS, Linux, and Windows per `docs/superpowers/specs/2026-10-03-print-to-verae-timestamp.md`.

**Tech stack:** Go 1.26 (core + helper + CLI), `pdfcpu` (page split, incremental update, attachments), `skip2/go-qrcode`, Fyne or Wails for cross-platform helper UI (decide in Task 1), CUPS backend in Go (static binary), Windows port monitor in C/C++ (minimal) or IPP service in Go.

## Global constraints

- Digests only to Verae. Never document bytes.
- Backend/port-monitor code does no networking; it only spools.
- Canonical JSON (fixed struct tags) for manifests so digests are reproducible.
- All binaries signed per platform before release.

## Repository layout

| Path | Role |
|---|---|
| `cmd/verae-print/` | CLI: `stamp`, `verify`, `login`, `spool-watch` |
| `cmd/verae-print-helper/` | Per-user helper (tray/menu-bar UI) |
| `cmd/cups-backend-verae/` | CUPS backend (macOS + Linux) |
| `internal/hash/` | Doc + per-page + manifest hashing |
| `internal/veraeapi/` | Client: `/api/timestamp`, `/api/status`, `/api/hash`, `/api/verify` |
| `internal/receipt/` | Receipt JSON, offline queue |
| `internal/pdfout/` | Certificate page render, incremental-update embedding |
| `internal/spool/` | Spool protocol (job.pdf + job.json), watcher |
| `platform/macos/` | PDF Service app, LaunchAgent, pkg scripts, PPD |
| `platform/linux/` | PPD/lpadmin scripts, systemd user unit, deb/rpm |
| `platform/windows/` | Port monitor or IPP service, MSI (WiX) |

---

### Task 1: Spike & decisions
- [ ] Confirm Verae API certificate PDF availability (open question 1); record in spec.
- [ ] Prove incremental update with pdfcpu keeps original byte prefix intact (hash test).
- [ ] Decide helper UI toolkit (Fyne vs Wails) and Windows path (port monitor vs local IPP).
- [ ] Commit `docs: spike results`.

### Task 2: Core library (`internal/hash`, `internal/veraeapi`, `internal/receipt`)
- [ ] Tests: deterministic page hashes; API client against httptest (immediate certificate, existing, job polling, 401); offline queue retry.
- [ ] Implement; reuse request/response shapes from Datacube-Fuse `internal/stamp/global.go`.
- [ ] Commit `feat(core): hashing, Verae client, receipts`.

### Task 3: CLI `verae-print stamp|verify|login`
- [ ] `stamp file.pdf` → `.verae.json` (+ `--embed`, `--cert`).
- [ ] `verify file.pdf|file.stamped.pdf`.
- [ ] Commit `feat(cli): stamp and verify`.

### Task 4: PDF outputs (`internal/pdfout`)
- [ ] Certificate page (name, digest, time UTC + local, id, verify URL, QR, page-hash list).
- [ ] Incremental-update embed + attachment; verify prefix hash in tests.
- [ ] Commit `feat(pdf): certificate page and embedded receipt`.

### Task 5: macOS v0 — PDF Services
- [x] CLI `verae-print stamp` writes `{name}.pdf`, `{name}-verae-timestamp-{RECEIPTID}.pdf`, `{name}.verae.json`.
- [x] Dual channel: `verae` (api.veraetime.net JWT) and `zapier` (zap.verae.ai xVerae- + attachPdf).
- [x] `verae-print install-macos` installs PDF Services apps (Verae + Zapier).
- [ ] Optional Save/Print/Both dialog (v0 auto-saves to `~/Documents/Verae Timestamps`).
- [ ] Commit `feat(macos): PDF Services entry`.

### Task 6: Spool protocol + helper
- [ ] `internal/spool`: job dir format, atomic hand-off, per-user dirs 0700.
- [ ] Helper: watch spool, process, dialog, settings, forward printing (`lp` / Windows print API), keychain token storage.
- [ ] Commit `feat(helper): spool watcher and UI`.

### Task 7: CUPS backend (macOS v1 + Linux)
- [ ] Go backend: read job from stdin/file arg, write to spool for job user, exit 0; `lpadmin` install scripts and PPD.
- [ ] Linux packaging (deb/rpm), systemd user unit; macOS LaunchAgent + signed/notarized pkg.
- [ ] Commit `feat(cups): verae backend and installers`.

### Task 8: Windows
- [ ] Per Task 1 decision: Print-to-PDF driver + port monitor writing to spool, or local IPP service.
- [ ] Tray helper build, WiX MSI, Authenticode signing.
- [ ] Commit `feat(windows): virtual printer and installer`.

### Task 9: Docs + release
- [ ] User guide per OS, verification guide, screenshots.
- [ ] CI builds for all three platforms; release artifacts.
- [ ] Commit `docs: user guide and release`.

## Order

```
Task 1 → Task 2 → Task 3 → Task 4 → Task 5 (macOS quick win)
                         └→ Task 6 → Task 7 (macOS v1 + Linux) → Task 8 (Windows) → Task 9
```