Document Pomodoro configuration and session controls

docs/activities.md

@@ -247,3 +247,39 @@ See [Ownership and lifecycle](development/activities.md#publisher-ownership-and-
 ## Extensions and templates
 
 See [Templates and the IPC schema](development/activities.md#extensions-and-templates).
+
+## Pomodoro
+
+Start a work session with:
+
+```sh
+feresectl pomodoro start
+```
+
+The default session has four 25-minute work intervals, with 5-minute short
+breaks and a 15-minute long break after the fourth work interval. It finishes
+at the end of the long break. Each completed interval sends a silent
+notification, and the next phase waits for you to start it unless you've
+enabled automatic advancement in [Pomodoro settings](configuration/activities.md#pomodoro).
+
+Open the activity list to pause, resume, skip, reset or stop the timer. In Morph,
+the controls are in the Activities tab; other panel styles use the Activities
+popup. You can reach the buttons with Tab and activate them with Enter.
+The paused timer stays visible with its remaining time frozen.
+
+The same controls are available from a terminal or a configured keybinding:
+
+```sh
+feresectl pomodoro pause
+feresectl pomodoro resume
+feresectl pomodoro next
+feresectl pomodoro status
+feresectl pomodoro reset
+feresectl pomodoro stop
+```
+
+`next` skips a running or paused interval without counting it as completed work.
+When the next phase is already ready, `next` starts it. `reset` cancels the
+session and starts again with your current settings, while `stop` removes it.
+Only one session can run at a time, and it survives closing the terminal that
+started it. See the settings reference for suspend and restart behavior.

docs/configuration/activities.md

@@ -150,3 +150,43 @@ and never logged.
 Configuration is validated before application; an invalid reload preserves the
 last valid configuration. Diagnostics include source offsets for activity
 configuration errors.
+
+## Pomodoro
+
+Pomodoro uses the Activities item and works without shell hooks. Add these
+settings inside your existing `activities` block to change the defaults:
+
+```kdl
+activities {
+    pomodoro {
+        work-minutes 25
+        short-break-minutes 5
+        long-break-minutes 15
+        intervals 4
+        auto-advance #false
+        notifications #true
+    }
+}
+```
+
+`work-minutes` accepts 1–180, `short-break-minutes` accepts 1–60 and
+`long-break-minutes` accepts 1–120. `intervals` accepts 1–12 work intervals
+per session. The session ends after its long break; start another when you
+want to continue. These settings apply when you start or reset a session,
+so reloading configuration doesn't change an interval already in progress.
+
+With `auto-advance #false`, a completed interval leaves the next phase ready
+until you start it. Enabling it starts the next phase automatically. A running
+interval includes time spent asleep, but a paused interval does not. If an
+interval expires during suspend, Ferese completes that interval on wake and
+starts any automatic next phase then; it doesn't count more work while the
+machine is asleep.
+
+Completion notifications identify the phase that ended and the next phase.
+They are silent and use the normal notification service, including Do Not
+Disturb and lock-screen privacy. Set `notifications #false` to turn them off.
+Stopping, resetting or skipping an interval doesn't send a completion alert.
+
+The compositor owns the timer, so closing a terminal or restarting the shell
+won't stop it. Restarting the compositor ends the session without restoring its
+timer or replaying completion notifications.

docs/ipc.md

@@ -178,3 +178,24 @@ When there are no subscribers, event publication does not build desktop
 snapshots. With subscribers, it compares logical domain snapshots after each
 dispatch. Ordinary damage, cursor movement, and redraw code do not publish events
 directly.
+
+### Pomodoro controls
+
+The `pomodoro` command uses the activity schema version:
+
+```json
+{"version":1,"type":"command","id":1,"command":"pomodoro","args":{"version":1,"action":"start","session":null}}
+```
+
+Actions are `start`, `pause`, `resume`, `next`, `stop`, `reset` and `status`.
+The result is the current `{id, timer}` record, or `null` when no session exists.
+Activity snapshots include this record in `pomodoro` and its Timer presentation
+in `activities`. Running timers carry a host-authoritative BOOTTIME `deadline`;
+paused timers carry their exact `remaining_ms` and no deadline. The
+`paused-countdown` activity value preserves that duration without ticking.
+
+Popup controls send the displayed activity ID in `session`. The host rejects
+it if a reset or restart replaced that session, so a delayed action can't stop
+a new timer. CLI commands use `null` to address the current session. These
+commands use the same authenticated, same-user socket as other activity calls
+and are unavailable while the desktop is locked.