28 Commits

Author	SHA1	Message	Date
xarmian	94cc2492fc	fix(events): a phase-1 counter restart must not leave a live epoch behind (BUG-2736) ... Codex round 2, on the rollout angle. Four findings; one was a real silent-loss hole and three were claims in the docs and config comment that the code does not support. THE HOLE. Phase 2 mints an epoch and the counter climbs; the deployment rolls back to phase 1; the seq key is then evicted or deleted; phase-1 publishers climb from 1 again; phase 2 is re-enabled and its SET NX finds the OLD epoch still there. A receiver that had adopted it sees no change, and if its high-water mark is below the new sequence -- a replica that just started, or one whose buffers were empty -- the numeric check does not see the reset either. Two ID spaces merge in one buffer silently, which is the outcome this whole unit exists to prevent. Phase 2's rotation cannot cover it: that rotation fires when the SCRIPT's own INCR returns 1, and by then the counter has climbed past 1 under the phase-1 path. So phase 1 now deletes the epoch when its own INCR returns 1. Deleting rather than rotating, because that path publishes no epoch and has none to propose, and an absent key is what phase 2's SET NX expects. The cost is one extra buffer drop if a phase-1 publisher deletes an epoch a flipped publisher just minted during the phase-2 roll -- loud and bounded, which is the direction this family always chooses over a silent merge. THE THREE CLAIMS. - "Rolling back is symmetric: unset the variable and roll" was true only of the roll back to PHASE 1. Downgrading past it is a second step in reverse order, because a pre-phase-1 binary still cannot parse the prefix, and introducing one while any flipped instance publishes drops events on it. - Unsetting the environment variable is not the same as setting the value false: events_publish_epoch can come from config.toml, whose value stands when the variable is absent. - counter_backward was documented as expected during mixed-version rolls and near zero between them. On phase 1 it can be non-zero at any time: that path keeps the two-call INCR-then-PUBLISH, so instances can interleave. The expectation is now stated per phase. Claude-Session: https://claude.ai/code/session_01JVDBKbgn3Xt7ndW1YoYd8X	2026-08-22 18:47:18 +00:00
xarmian	4a6a748c85	feat(events): identify the shared Redis ID space, behind a two-phase flip (BUG-2736) ... The activity event counter lives in Redis and is shared by every instance, so no instance can compute an identity for it the way MemoryBus computes its own incarnation base. If that counter is ever reset -- evicted under maxmemory, deleted by hand, a fresh Redis after a restore -- IDs start again from 1, and a replica buffering the old sequence cannot tell the new 101 from the old 101. It merges two ID spaces into one replay buffer and answers a resume across the boundary as though nothing was missed. Numeric detection alone cannot see it. By the time the new sequence passes the replica's high-water mark it looks like ordinary progress -- which is the case the epoch exists for, and the high-water check is what catches the OTHER case (a publisher that never learned the epoch), so both are kept. So the identity travels WITH each message, as an opaque token in a "<epoch>|<id>|<json>" prefix. A prefix rather than an envelope field: an older instance would unmarshal an envelope object SILENTLY -- no matching keys, no error, a zero-valued Event delivered to its clients -- and fails loudly on the prefix instead. TWO PHASES, because the failure is asymmetric. Every instance ACCEPTS both wire forms from this release; only emission is gated, on PAD_EVENTS_PUBLISH_EPOCH. Phase 1 rolls the binary everywhere publishing the historical bare JSON; phase 2 sets the flag and rolls again. Flipping before every instance is upgraded is the one direction that LOSES events rather than resyncing: a pre-phase-1 binary cannot parse the prefix at all. Rollback is symmetric and safe. docs/deployment.md carries the procedure both ways, what the reset counters should read during each roll, and what remains unfixed. Phase 2 also moves ID assignment into one atomic script. The two-call INCR-then-PUBLISH lets two instances interleave, so a receiving instance can append 6 before 5 -- a window older than this change, and already wrong, but load-bearing here because counter-backwards detection reads a descending ID as a reset. The script carries a dedupe token for the same reason internal/watchevents' does: go-redis retries a command whose REPLY was lost, so a publish can happen AND return an error, and the retry would deliver a second copy that looks perfectly valid. THE COUNTER-BACKWARDS FLOOR STAYS, and the earlier hope that this unit would delete it was wrong. Its trigger is mixed-VERSION ordering -- an older binary assigning and publishing in two calls -- not mixed-FORMAT payloads, so publish-old-until-flip removes the format window only. It lives for as long as a deployment can run two publisher versions at once, which is every rolling upgrade, and the code now says so where it fires. THE ASYMMETRY WITH MemoryBus IS DECLARED IN BOTH BUSES, in both packages: an opaque epoch where the counter is shared, a numeric base where one process owns it. They are not two spellings of one idea and must not be symmetrized. A numeric base for Redis would close more -- it would refuse cross-incarnation cursors, which the epoch cannot -- and is deferred rather than rejected: at the flip, IDs would jump to ~1.8e18 in one step and every un-flipped publisher's message would read as a massive backwards jump, dropping every buffer across the whole roll. It is a candidate follow-on once the flip has soaked. What this does NOT fix is stated in the code and the docs rather than implied: the client cursor is still a bare integer with no epoch, so an old and a new ID of the same value remain indistinguishable TO A RESUME even though the buffers can no longer mix them. The flip is read inside newObservedEventBus, which now takes the whole Config. As a hand-picked argument at the two RunE call sites it was untested wiring: replacing it with `false` compiled, passed the entire tree, and left the deployment silently on phase 1 -- indistinguishable from a correct phase-1 deployment, since phase 1 is the default. Mutation-checked in both directions, because a helper that ignores its config and hardcodes either value would pass a one-directional test. Also: the epoch and dedupe keys join the namespace assertions (an epoch shared between two installations is a cross-feed with teeth -- each would read the other's ID-space changes as its own), and this package's four-key EVAL is now recorded on BUG-2724's cluster deferral, which had one call site and now has two. Claude-Session: https://claude.ai/code/session_01JVDBKbgn3Xt7ndW1YoYd8X	2026-08-22 18:31:02 +00:00
xarmian	f2a037e393	docs: nine claims about other people's code that I had not checked (BUG-2731) ... Codex round 16, aimed at every factual assertion this diff makes about code OUTSIDE it — go-redis, the SSE spec, HTTP header handling, the web client, internal/watchevents, Prometheus. The angle was chosen because this diff had already been caught twice asserting library behaviour that was false, and claims about other people's code are the one class no test in this repo can falsify. It found nine. Every one is mine, and every one claimed more than I had verified. - "no reconnect in 24 seconds of probing" cited an experiment that is not in the tree — the probe was deleted with the test it belonged to. The MECHANISM is checkable from the library source and now says so with the call named; the unretained number is gone. - "the SSE `id:` field has no room for an ID-space identity" is wrong. The spec allows an arbitrary UTF-8 event ID. What excludes it is PAD's own contract — an int64 every deployed client already parses — which is a stronger and more honest statement of the constraint, and it is the one BUG-2736 has to argue against. - "the spec defines an empty header as no position" overstated it. The spec governs what a client SENDS. What a server does with a value it cannot use is our policy, and the test now says so. - "HTTP strips optional whitespace from header values" is too broad: Go trims on the way OUT, while the incoming MIME parser only TrimLefts. What I measured was the round trip, and the comment now claims exactly that. - "every gap is a full resync / full re-fetch" is wrong in three places. The web client answers sync_required with an incremental /changes delta and only falls back to a full refresh after a long absence or a failure. This one matters beyond wording: the load argument for the whole fix rests on what a gap costs a client. - "a wrapper cannot see that a resume gap occurred" — it can see the nil; what it cannot see is WHY. I had already corrected this in the metrics adapter and left the overbroad version in the seam it describes. - internal/watchevents' `since` no longer "mirrors internal/events exactly" — that stopped being true when knownFrom went into the latter's `since`. Now states where the two differ and why. - "the counter returns to baseline" — a Prometheus counter only increases; its RATE returns to baseline. Two places. - "the only case where INCR fails while PUBLISH still reaches subscribers" — an ACL permitting one and denying the other is another. The test now names the SHAPE as what matters and its arrangement as one route to it. No behaviour changes; comments, docs and test prose only. Separately verified while waiting on this round, and now cited rather than asserted: the three WHATWG steps that make the empty `id:` cursor retirement work. That claim was the one thing in the diff I had taken from memory of a spec rather than read, and it is load-bearing — if wrong, the feature is theatre. Refs BUG-2731	2026-08-22 17:09:29 +00:00
xarmian	b4989aa2f0	fix(server): retire a cursor we just refused, and stop trusting one we cannot read (BUG-2731) ... Three handler changes and the documentation the coverage fix made wrong. sync_required NOW RETIRES THE CLIENT'S CURSOR, carrying an empty `id:` which per the EventSource spec clears the last event ID. Without it the client keeps the cursor that was just declared unservable, so every later reconnect on a quiet workspace is answered sync_required again and re-runs a full delta sync — a loop that only ends when a live event happens to arrive. Survivable while the response was rare (buffer eviction only); the coverage check makes it common, so this is a load consequence of that fix and belongs to it. AN UNREADABLE Last-Event-ID IS A GAP, not a fresh connection. Only a parseable positive value reached the replay path, so "-1", "not-a-number", a quoted number, or an integer too large for int64 silently dropped everything published before that subscription. The same lie this fix exists to end, arriving through the parser rather than the buffer. A genuinely fresh client sends no header and is unaffected — asserted, because the fix is one `if` away from resyncing everyone on connect. Not a case, and the test says why rather than omitting it silently: a whitespace-only value. HTTP strips optional whitespace from header values, so the handler sees an empty string, which the spec defines as "no position". Measured, not assumed. HANDLER-LEVEL GAPS ARE COUNTED. A cursor no one can parse never reaches a bus, so without Server.countResumeGap the counters would undercount exactly the resyncs an operator is most likely to be asked about: a client looping on a cursor nobody can read. BOTH SSE HANDLERS GET ALL THREE, because introducing them on one stream is how parallel surfaces silently diverge. The pad CLI masks the cursor difference by clearing its own — verified by reading its parser, which handles the empty-value form — so the consumer this would bite is a generic SSE client, the one nobody tests. DOCS. Two comments described mechanisms that had changed: the handler's own "gap too large — buffer evicted" (eviction is now one of several) and internal/config's claim that the activity stream silently misses a namespace cutover. And docs/deployment.md's cutover note said resync is honest on the watch stream and silent on the activity one; it is now honest on both, with the edge that a cursor exactly one below a replica's first-seen ID is served rather than refused, tracked as BUG-2736. The sync_required reason text changes from "Event buffer exceeded" to what actually happened. Keeping it was defended earlier BECAUSE the client never reads it, which is the same reason correcting it is free. Refs BUG-2731	2026-08-22 14:24:12 +00:00
xarmian	9f88e94832	fix(events): a resume must not be answered from coverage we never had (BUG-2731) ... internal/events answered a Last-Event-ID resume with an empty-but-non-nil slice whenever the workspace's replay buffer could not speak to the span being asked about. The SSE handler reads that as "caught up", so the client sat on a live stream believing it was current while everything between its cursor and now was silently gone. COVERAGE. replayBuffer gains knownFrom: the lowest event ID from which this instance's coverage of a workspace can be vouched for. A resume from below it answers nil, which the handler already turns into sync_required. Covers a buffer that does not exist (cold start, restart, scale-up, or simply the first connection to a workspace on this instance), a buffer that exists but starts above the cursor — NOT full and NOT empty, reachable on any multi-instance deployment with no eviction and no restart — and a non-zero cursor from a previous incarnation of a single process. knownFrom here means RECEIVING-continuity, never ID-contiguity, and the defining comment says so with the measurement attached. internal/watchevents has a field of the same name that ALSO detects holes by noticing a non-consecutive ID; porting that would have been a serious regression, because this bus has a global counter and per-workspace buffers, so a workspace's buffer holds non-consecutive IDs by construction (four publishes alternating across two workspaces measure as W=[1 4], X=[2 3]). An ID-contiguity check would fire on nearly every append and turn every resume into sync_required — the false-positive inversion of this bug. LIFECYCLE. Coverage now ends where it really ends: - a stopped workspace subscription drops its replay buffer. Keeping it "in case they come back" looks like a free win and is the bug: events published elsewhere never enter it while it goes on looking complete. - subscriptions are generation-numbered, so a straggler from an ended subscription cannot re-create a buffer and vouch for coverage that ended with it — including the case where the workspace has already been resubscribed under the stale goroutine. - a pub/sub reconnect ends that workspace's coverage. PubSub.Channel resubscribes transparently, so a Redis failover left a hole the buffer had no idea about; the loop reads pubsub.Receive instead. It must RECOVER rather than exit — returning on a transient error would leave an instance publishing fine and receiving nothing — and it drops ONE workspace's buffer, since a dropped subscription says nothing about any other channel. Subscribers are indexed by workspace because the replay buffers moved under the same mutex (necessary for the straggler race): scanning every local subscriber under that lock would make one hot workspace the serialization point for every other workspace's fan-out and every resume. Also removes Publish's local-counter fallback on a failed INCR, which minted an ID from a process-local space and published it — every receiving instance reads that as the counter having been reset. It bought nothing: this bus has no local fan-out path, so an event that does not reach Redis reaches no subscriber here either. SIBLING. internal/watchevents had the identical cold-resume defect on its MemoryBus — its RedisBus guards it, MemoryBus reached the buffer directly — so a single-process instance answered a post-restart resume as caught up. Found by a cross-artifact review pass; the guard goes in `since` so both implementations inherit it, and is tested through SubscribeAndReplaySince as well as EventsSince because that is the path the handler uses. Refs BUG-2731	2026-08-22 14:23:40 +00:00
xarmian	bb003dd6bb	fix: five claims the final comment-truth round found (BUG-2724, BUG-2726) ... The bounded process the lead set: N rounds, an author prune pass, one final comment-truth round. This is that round's output, and the loop stops here. Two were mechanisms I had wrong, and both are the kind a reader would reuse without re-deriving: - "Different Redis DB numbers do not help" was half true. Ordinary keys ARE DB-scoped, so two installations on different DBs keep separate presence registries; it is pub/sub that ignores DBs entirely, which is why the buses cross-feed regardless. Stating it as "does not help" made the namespace look like the only fix for a problem it only half is. - A namespace cutover's client resync was attributed to the epoch check. That check needs an OLD epoch to compare against and a freshly namespaced bus has none — the resync comes from the cold replay-buffer coverage check instead (knownFrom is zero, so every resume falls below it). Same honest outcome, different mechanism, and the mechanism is what someone reasoning about a cutover would use. Three were stale or over-general after earlier changes: the admission comment still said the global limit is passed to the bus as 0 (that parameter is gone), `pad watch --help` and the plugin monitor description lumped a missing .pad.toml's hourly retry in with the 5s-to-5min backoff, and CLAUDE.md said clients must back off without the browser exception docs/deployment.md spells out. Claude-Session: https://claude.ai/code/session_01JVDBKbgn3Xt7ndW1YoYd8X	2026-08-22 05:21:01 +00:00
xarmian	35e564298b	fix: seven more prose claims, one real metric gap, and a flaky test of my own (codex round 17) ... The prose angle again, and it is still finding things — which is itself the finding: this diff's comment density is generating wrong beliefs faster than the review is removing them, in the one dimension where the defect is a reader's understanding rather than the program's behaviour. Everything below was a claim I wrote. ONE WAS A REAL GAP, not just wording. pad_watchevents_resume_gaps_total was documented as counting every unservable resume, and counted only the half decided by the shared counter. The LOCAL half — a cursor below what this instance can vouch for, from a hole or a cold start — returns nil from replaySince, becomes sync_required for the client, and reported nothing. Now counted, on the deferred path so it fires with the lock released. Its test needed a second pass to be an instrument: the first version arranged a hole and asserted the counter moved, but the shared counter disagreed too, so resumeOutrunsLocalView reported and the mutation survived. It now sets the counter to AGREE with what the instance has seen, which is the only arrangement that isolates the local path. The prose corrections, swept by grep rather than by instance this time: - MemoryBus's comment said a single-process deployment never wires an observer. cmd_server wires one, deliberately — that is what makes the drop counter meaningful there, which is a claim I had just added elsewhere. - "Every write path works with Redis down" was too strong in three places. Push answers 503 for an unresolvable targeted push and 502 push_unconfirmed on publish failure — the paths whose job IS cross-instance delivery. - Presence-failure consequences were stated as certainties in four more places after round 16 fixed one. A failure means an error was REPORTED; Redis can fail a pipeline after applying it. - The deployment metrics table still described pad_eventbus_publish_total as "Events published" after the Help string had been corrected to attempts. - The reserved-namespace rationale called prefix nesting a "collision". It is nesting; an exact collision would need the namespace to match a workspace UUID. Refused anyway, and now for the reason that is true. - A presence cutover was described as stranding one renewal interval of stale entries. It is the full 90s TTL — three intervals. AND A FLAKE OF MY OWN, caught by the full suite rather than by the targeted runs: the activity-bus namespace test asserted subscription state immediately, but that bus subscribes ASYNCHRONOUSLY (the watch bus waits for confirmation; the two differ). It now polls, and the asymmetry is named in both tests so the next reader does not assume symmetry the way I did. Claude-Session: https://claude.ai/code/session_01JVDBKbgn3Xt7ndW1YoYd8X	2026-08-22 05:00:18 +00:00
xarmian	7c8ed3c815	fix: nine false or overstated claims in this diff's own prose (codex round 15) ... An angle worth naming, because it found more than several code-shaped ones did: check the COMMENTS against the CODE. This diff is comment-heavy and its comments make specific factual claims. Nine were wrong. The one that mattered most was a false argument for a correct rule. redisns.Parse rejects colons, and justified it with a collision example that does not happen: ns "a:events" builds pad:a:events:events:<ws>, not pad:a:events:<ws>, because the suffix is appended too. The rule stands on its own grounds (a colon spans segments and makes the keyspace ambiguous to read back) — but a false example is worse than none, because the next reader trusts it. Chasing that turned up a REAL collision needing no colon: a namespace equal to one of Pad's own first segments nests this installation inside the default one's keyspace. Namespace "events" puts every key under pad:events:*, which is the default installation's activity channel space — the exact cross-feed the namespace exists to prevent, arriving through the namespace. Now rejected, with a control leg asserting that names merely CONTAINING a reserved word ("events-eu", "prod-session") stay valid. The other eight: - "The three keyspaces cannot drift" — overstated. Each constructor takes its own Keys; a source-reading test is what enforces it, which is weaker than a compiler and now says so. - Two docs claimed both SSE endpoints incur a presence registration. Only the watch stream registers. - The Redis metrics section said they "stay at zero" without Redis, while pad_redis_up is deliberately unregistered — the section contradicted the field three lines below it. - The presence-failure metric's HELP string still carried the blanket "leaves sessions unlisted and untargetable" that the field comment had already been corrected away from. Two of the four ops fail in the opposite direction. - A nil from MGET was described as proof the process died. Eviction, a restart and a manual DEL produce the same nil, and this file's own doc says eviction is indistinguishable from expiry. - A test comment claimed to cover both corrupt-entry shapes; the second is unreachable and the subtest is deliberately absent, as the note ten lines down already said. - "Enumerates every refusal path" covered per-instance and per-workspace and not per-user — the same undercount as round 13's, one round later. Both per-user paths added. - The Observer contract said a go-redis drop is reported as a sequence gap. Only if a LATER notification arrives to expose the hole: drop the newest message on a bus that then goes quiet and nothing is reported. Claude-Session: https://claude.ai/code/session_01JVDBKbgn3Xt7ndW1YoYd8X	2026-08-22 04:35:57 +00:00
xarmian	3e3170e915	fix(server,cli,docs): the consumer contract, per codex round 12 (BUG-2726) ... An angle no earlier round took: what does a CLIENT see. Two of the five findings were about consumers I had never opened. - `pad project watch` returned "event stream returned 429: {json}" and exited, which sends the reader looking for a bug rather than at a limit. It now says what happened and which knobs govern it, and names the fact that those knobs cover this stream and the agent watch stream together. It still exits rather than backing off — it is interactive, and a human can decide — unlike the unattended monitor, which already folds 429 into its ladder. - Both endpoints now answer a refusal through one helper: same status, same code, same message, plus `Retry-After`. `/api/v1/events` was setting `Content-Type: text/event-stream` BEFORE the admission check, so its 429 carried the JSON error envelope under an SSE content type — a different contract from its sibling's for the same refusal. Admission moved above the headers, which is where it belonged anyway. - The anonymous-caller rule was documented as if it applied to both endpoints. It applies to `/api/v1/events` only; the watch stream requires a resolved user and answers 401 without one. - docs/architecture.md described one SSE endpoint and one bus. It now has the table: two streams, two buses, different scopes and consumers, one shared connection budget, one Redis namespace. FILED, not fixed: the web UI's `EventSource` cannot see a 429 or a `Retry-After` — the spec exposes neither to the page — so a refused browser tab reconnects at a constant rate while the CLI backs off. That asymmetry means reaching the limit sheds load from the population that respects it and not from the one that grows fastest under it. No server-side change closes it; the fix is a client-side reconnect wrapper. BUG-2733, and docs/deployment.md warns operators to size the limit with it in mind. Claude-Session: https://claude.ai/code/session_01JVDBKbgn3Xt7ndW1YoYd8X	2026-08-22 04:10:06 +00:00
xarmian	a790810bd6	docs: close the cross-artifact gaps codex round 6 found (BUG-2724, BUG-2726, BUG-2727) ... The angle no earlier round probed: which artifacts a human or agent CONSUMES should have changed and did not. Five, and the pattern is the one my own record keeps naming — the caveat existed in the artifacts I was editing and not in the ones that get read. - .env.example had neither new variable and still described PAD_SSE_MAX_CONNECTIONS with its old single-endpoint meaning. It is the file an operator copies; docs/deployment.md being right does not help someone who never opens it. - docs/deployment.md called the readiness endpoint /health/ready. The route is /api/v1/health/ready, so every instruction to go read the new redis block pointed at a 404. Corrected there and in four code comments, and the Health Check section now actually shows the three endpoints, the healthy payload, and the degraded one — it previously demonstrated only /api/v1/health, which is the build-info endpoint and says nothing about readiness. - CLAUDE.md listed /api/v1/events and not /api/v1/events/stream at all, so the endpoint this unit bounds was undocumented in the file agents read first. Added, with the limits and the 429 contract. - `pad watch --stream --help` said silence means "no workspace linked or padd unreachable". A capacity refusal now produces the same silence through the same backoff, so the help was enumerating a set that had quietly grown. - The plugin skill told agents "silence means nothing changed" — now false in the same way, and worse, because an agent repeats it to a user as though the quiet were evidence. Rewritten to say what silence does and does not prove. The plugin monitor description had the same enumeration and got the same fix. Checked rather than assumed: there are two SKILL.md files, and only the plugin copy carries a notifications section — the embedded one has no monitor guidance to correct. NOT changed, and raised with the lead instead: deploy/k8s/deployment.yaml points both probes at /api/v1/health, so the readiness endpoint is never consumed. Fixing it is right but it changes rollout behaviour for anyone using the shipped manifest (a database blip would start pulling pods from the load balancer), which is a deployment-posture call rather than part of this unit. Claude-Session: https://claude.ai/code/session_01JVDBKbgn3Xt7ndW1YoYd8X	2026-08-22 02:45:53 +00:00
xarmian	9afedbe1a0	fix(server,metrics,watchevents): seven codex round-4 findings — operator and next-author angle (BUG-2727, BUG-2724) ... Round 4 read the diff as the operator of a running deployment and as the author of the next change. Five findings were claims my own text made that the code does not support, which is the failure mode this angle is for. 1. The degradation list said Redis loss costs "cross-instance activity events". It costs ALL of them: events.RedisBus.Publish logs its failure and returns without a local fan-out, so subscribers on the originating instance stop receiving too. A responder told only about cross-instance delivery would have looked elsewhere. Corrected in the health payload, both prober log lines, and the docs. 2. config.go promised that connected clients resync after a namespace change. True of the watch stream, false of the activity stream, whose cold replay buffer answers a resume as "caught up" (BUG-2731). The docs already carried the asymmetry; the comment did not, and the comment is what the next author reads. 3. Resume-detected gaps were counted nowhere. They are the only gap shape that is always USER-VISIBLE — the client gets sync_required — so an incident reading pad_watchevents_sequence_gaps_total would have missed the failure mode with the clearest symptom. New pad_watchevents_resume_gaps_total, kept separate rather than folded in because the two are diagnosed differently: one is a delivery fault, the other is any cursor this instance cannot vouch for. 4. The presence-failure metric's doc said every failure leaves sessions unlisted and untargetable. Two of the four ops fail in the OPPOSITE direction — a failed deregister leaves a dead session listed, so a push aimed at it is accepted and reaches nobody — and a generic alert on the total would send a responder the wrong way. Now documented per op, in the code and in the docs table. 5. The go-redis log bridge levels everything at WARN, and the comment justified that with "benign reconnect chatter" I had never enumerated. Enumerated now: the stream carries genuine failures, state changes and informational fallbacks with no severity attached. WARN stays — INFO would bury the dropped-message line the bridge exists for, and classifying by message TEXT would make Pad's log levels depend on go-redis's prose — and a component=go-redis field makes it routable instead. 6. internal/redisns centralizes key construction but cannot stop a future contributor wiring one bus with a different Keys than another: every package compiles, every unit test passes, and the deployment runs split across two keyspaces while looking configured. Adds a wiring drift guard that reads cmd_server.go and fails if the three constructors do not share one Parse-produced value. The rule was already written down in a package comment; this is its enforcement step. 7. The limits are per-process and the startup log, log fields and gauge Help called them "global". Renamed to per-instance / per-principal throughout, with the no-shared-counter caveat in the startup line. Claude-Session: https://claude.ai/code/session_01JVDBKbgn3Xt7ndW1YoYd8X	2026-08-22 02:28:50 +00:00
xarmian	c03a4851bd	fix(server,redisns): two codex round-3 findings — DoS via legacy tokens, blank namespace (BUG-2724, BUG-2726) ... 1. Callers with no user id skipped the per-user bound entirely, so one legacy workspace-scoped token could fill the global budget and 429 everyone else — a denial of service through a deprecated auth path. My own comment argued for the skip on the grounds that bucketing every anonymous caller under one empty string would make unrelated callers evict each other. That was right about the empty-string bucket and wrong about the conclusion: the fix is a better key, not no key. They are now bucketed by workspace, the finest granularity actually available — from the token's own workspace id where it has one, from the resolved workspace otherwise. The residual trade (two legacy tokens for one workspace share a bucket) is stated in the code and in the docs rather than left for a reader to discover. 2. PAD_REDIS_NAMESPACE=" " trimmed to Default, so a broken template substitution silently restored the historical keyspace and collided with the installation the namespace was set to separate from — the exact leak, arriving through the mechanism meant to prevent it. Only a genuinely unset value is Default now; whitespace-only is a startup error naming both alternatives. The first fix needed a second instrument. Mutating the handler to pass currentUserID instead of streamPrincipal SURVIVED the unit tests, which drive the helper directly — the same defect shape as day-49's batch-id finding: testing a knob at the layer that consumes it proves the knob, while the caller passing it is a separate claim. The new handler-level test drives the fresh-install no-auth window through HTTP and fails by name when that wiring is reverted. Claude-Session: https://claude.ai/code/session_01JVDBKbgn3Xt7ndW1YoYd8X	2026-08-22 02:15:50 +00:00
xarmian	03518466ab	fix(server,metrics,docs): five codex round-2 findings (BUG-2724, BUG-2726) ... Round 2 probed angles round 1 did not: rolling upgrade and rollback, request cancellation, and whether any operator-facing text now contradicts the code. Four of the five were the latter. 1. The admission slot was held through the Redis presence cleanup. Defers run LIFO, so the acquire-site release ran LAST — after Remove's round trip, bounded by presenceOpTimeout (5s) and a wait on the renewal goroutine. A reconnect arriving inside that window could be refused by a bound the connection had already stopped consuming, and the window is widest during a Redis outage, which is when clients reconnect most. A second deferred release, registered later so it runs first, closes it; the acquire-site defer stays as the safety net for early returns, and release is idempotent so deferring twice releases once. 2. pad_sse_connections_active is written by the events.EventBus wrapper, so it has only ever counted the workspace stream. That was every SSE connection Pad had a limit for until this branch; it no longer is, so an operator watching it against the global limit would be reading one endpoint's share of a two-endpoint budget. Adds pad_stream_connections_active, driven by the admission gate itself, and both Help strings now name their population. Wired from either SetMetrics or SetSSELimits (either can land first) and from the lazily-built gate, each covered by a test — a gauge stuck at zero while streams are held is the same shape of lie as a metric that is not registered at all. 3. The limits are enforced in-process and the docs called them "Global". With the shipped k8s manifest's two replicas, 1000 admits ~2000 and a user can hold 50 per pod. Documented as per-instance, with the multiply-by-replicas note and a pointer at the new gauge. 4. A namespace cutover partitions a rolling upgrade — namespaced and un-namespaced replicas are two installations for the length of the rollout — and rolling back with the variable still set silently restores the split. Both now stated, with the env var and the binary having to move together in both directions. 5. Client resync across that cutover is honest on the watch stream (the epoch key detects the changed id space) and SILENT on the activity stream, whose cold replay buffer answers a resume as "caught up". Documented, and filed as BUG-2731 rather than fixed here: it is pre-existing, fires on any replica restart, and the minimal fix changes reconnect behaviour for every deployment, which wants a ruling rather than a quiet patch. Claude-Session: https://claude.ai/code/session_01JVDBKbgn3Xt7ndW1YoYd8X	2026-08-22 02:05:01 +00:00
xarmian	0877b260c1	feat(redis): namespace every Redis keyspace from one shared config value (BUG-2724) ... Every Redis key and channel Pad uses was flat — pad:events:, pad:event_seq, pad:watchevents*, pad:session:* — so two Pad installations pointed at one Redis endpoint cross-feed each other's notifications and merge each other's session-presence registries. Different logical DB numbers do not help: Redis pub/sub is not namespaced by DB at all. The exposure is narrow but real. Delivery is filtered per caller on user id, and user ids are per-installation UUIDs, so cross-feed needs the same id in both installations — a CLONED database, such as a staging environment restored from a production dump. For that case it is a genuine cross-tenant leak: foreign sessions listed in the picker, and a private push deliverable across installations. Fixed the way internal/watchevents' existing ruling demanded: not by one package growing a prefix the others lack, but through internal/redisns — one value parsed in cmd/pad/cmd_server.go and passed into all three constructors. The three cannot drift because there is nothing to drift from, and the operator rule is stateable in one sentence for every keyspace. PAD_REDIS_NAMESPACE defaults to empty, which reproduces the historical names byte for byte, so an existing deployment keeps addressing its own replay buffers, counters and presence entries across the upgrade. Tests assert both directions per keyspace — present under the namespace AND absent under the historical names — because an implementation that wrote both would still cross-feed while passing a one-directional test. Namespaces are validated at startup, and a colon is rejected specifically: it is Pad's own separator, so namespace "a:events" would build pad:a:events:<ws> and collide with installation "a"'s channel — reintroducing the cross-feed through the mechanism meant to fix it. Names are built through a function rather than assembled from a literal at each site, and redisns' doc says why: "pad:" also begins Pad's OAuth SCOPE values (pad:read / pad:write / pad:admin) in four files, so a grep-driven prefix sweep would break authorization. Not included, deliberately: hash tags for Redis Cluster. BUG-2724's trail recommended shipping them alongside on cost-sharing grounds; that premise is falsified by publishScript, which spans four keys in one EVAL and fails CROSSSLOT exactly as presence's MGET does. There is no cheap half, and no cluster client here to exercise tagged keys against, so they would ship untested by construction. Cluster stays documented as unsupported and the future unit is named on the trail. Renaming is a CUTOVER for the buses (the seq and epoch keys carry Last-Event-ID meaning, so connected clients resync) and free for presence (90s TTL). Both stated in docs/deployment.md and at the constructors. Claude-Session: https://claude.ai/code/session_01JVDBKbgn3Xt7ndW1YoYd8X	2026-08-22 01:41:31 +00:00
xarmian	ea139272ce	fix(server,watchevents): shared session presence + honest push acceptance (BUG-2698, BUG-2699) (#1175) ... Two coupled defects in the push path, fixed as one unit because 2699's honest-acceptance signature is the substrate 2698's fix reports through. BUG-2699 — Bus.Publish reports acceptance. The endpoint returned 200 pushed:true for a publish that was dropped, because Publish returned nothing and swallowed every failure. An error is two outcomes and they are kept apart: ErrBusClosed proves nothing was published (503 unavailable, safe to resend), while any other error means UNCONFIRMED — go-redis retries a command whose reply was lost, which is why the publish script already carries a dedupe token — and gets 502 push_unconfirmed, deliberately off the web client's safe-to-resend list. MemoryBus was the worse case, not the exempt one: neither implementation checked `closed`, and the in-process one dropped silently with no log at all. Seven production call sites, not the six the item named; the six best-effort producers discard through one named helper, and an AST-based test fails when a new producer publishes directly. BUG-2698 — RedisSessionPresence. A session-targeted push was resolved against the answering replica's presence registry, and the handler skips the publish when the target is absent, so a POST landing on A for a session held on B dropped the instruction and answered delivered_sessions:0. Fixed at the REGISTRY rather than the gate: a shared registry makes the snapshot right, which makes the picker complete and restores the gate's original premise, so the existing skip becomes correct for the reason it was written. Entry and index are written atomically under a TTL renewed by a goroutine that lives exactly as long as the connection; a crashed process stops renewing and Redis clears it. Staleness is unchanged and now stated in full: ~30s for a dropped client, ~90s for a dead instance. delivered_sessions becomes nullable — null means published-but-uncountable, never zero — documented as three states at every consumer. 35 Codex review rounds. Notable: a per-user registry cap was added and then removed after three consecutive rounds found defects inside it and a fourth was asked whether it belonged in this PR at all; a context bound was documented, disproved by its own test (go-redis does not apply a command context to connection establishment — 5.0s measured against a 150ms ctx), and rewritten to say what is true. Every fix was mutation-checked; one instrument was deleted for passing on broken code and one for not asserting its own premise. Filed rather than folded in: BUG-2724 (Redis keyspace namespacing + Cluster), BUG-2725 (delivered_sessions is an estimate with error in both directions), BUG-2726 (no concurrent-connection limit on the watch stream), BUG-2727 (Redis absent from readiness/metrics; silent subscriber loss), BUG-2728 (epoch-reset resume lead). Gates: build · make lint 0 issues · go test ./... (25 pkgs) · svelte-check 0 errors · vitest 1738 passed · CI 7/7 including Go (PostgreSQL) and Nix.	2026-08-21 20:43:20 -04:00
xarmian	8c609be2e3	feat(store): guard against schema-ahead downgrade + pre-migration snapshot + upgrade docs (TASK-2006) (#843) ... 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).	2026-07-07 16:32:20 -04:00
xarmian	9be8e96cfd	fix(cli): safe SQLite db backup/restore (config path + VACUUM INTO) (#837) ... * 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	2026-07-07 15:21:20 -04:00
xarmian	616a6d2a0a	feat(auth): localhost password recovery for locked-out self-host admins (#760) ... 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).	2026-06-22 20:58:50 -04:00
xarmian	94ebe5a83d	test(screenshots): capture in dark mode (Pad's default theme) (#319) ... 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.	2026-04-30 13:10:51 -04:00
xarmian	10309fc599	fix(config): read PUBLIC_URL for emailed link generation (BUG-899) (#318) ... * 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.	2026-04-30 08:40:33 -04:00
xarmian	de873d8a01	docs(brand): add brand spec defining cohesion contract (TASK-904) (#312) ... 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.	2026-04-29 22:49:25 -04:00
xarmian	7cda0d7896	feat: rebrand to Perpetual Software + new tagline (IDEA-832) (#273) ... 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).	2026-04-28 12:26:39 -04:00
xarmian	afe721d202	feat(cli): add Cloud mode to pad init, drop Docker option (TASK-837, TASK-838) (#272) ... 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.	2026-04-28 09:41:50 -04:00
xarmian	29f720c996	docs: add real README screenshots (dashboard + board views) (#257) ... 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	2026-04-26 20:12:40 -04:00
xarmian	062eef41b2	docs: architecture guide + full .env.example + gitattributes + Makefile note (TASK-687) (#222) ... 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.	2026-04-22 20:59:15 -04:00
xarmian	ac744fce2b	fix(docs): replace 'pad serve' with 'pad server start' (TASK-675) (#199) ... 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.	2026-04-22 14:50:24 -04:00
xarmian	1d26283752	feat: add PostgreSQL backup, restore, and migration CLI commands ... - 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	2026-04-06 02:01:51 +00:00
xarmian	af2755d5af	docs: add deployment documentation, Docker Compose, and K8s manifests ... Provide production-ready deployment configurations: - docker-compose.yml: Pad + PostgreSQL + Redis single-command setup - docker-compose.prod.yml: production overlay with resource limits - deploy/k8s/: Kubernetes manifests (deployment, service, ingress, HPA) - deploy/Caddyfile: Caddy reverse proxy with auto-TLS - deploy/nginx.conf: nginx config with SSE-friendly proxy settings - docs/deployment.md: environment variable reference, architecture diagram, quick start, production checklist	2026-04-06 01:58:04 +00:00