From ec24efd31625c73e3e1100c2c22baf4734a3f1b4 Mon Sep 17 00:00:00 2001
From: Hector Alvarez <alvarez.hectorm@outlook.com>
Date: Sun, 13 Sep 2026 06:29:11 -0500
Subject: [PATCH 1/9] docs(stories): add US-001 multiple alarms user story

---
 docs/stories/US-001-multiple-alarms.md | 65 ++++++++++++++++++++++++++
 1 file changed, 65 insertions(+)
 create mode 100644 docs/stories/US-001-multiple-alarms.md

diff --git a/docs/stories/US-001-multiple-alarms.md b/docs/stories/US-001-multiple-alarms.md
new file mode 100644
index 0000000..02c2adf
--- /dev/null
+++ b/docs/stories/US-001-multiple-alarms.md
@@ -0,0 +1,65 @@
+# User Story: Multiple Alarms
+
+**Story ID:** US-001  
+**Epic:** Alarms  
+**Status:** Draft
+
+---
+
+## 1. Description
+
+**As a** visitor who keeps the clock site open at their desk,  
+**I want to** create and manage several named alarms,  
+**So that** I get reminded of time-sensitive moments (breaks, meetings, cooking) without needing a phone app or an account.
+
+---
+
+## 2. Context & Scope
+
+- **In Scope:**
+  - Create alarms with an optional name (defaults to "Alarm") and a time of day (HH:MM)
+  - A list showing all alarms, each with an enable/disable toggle and a delete action
+  - One-shot behavior: an alarm rings once, then automatically turns itself off
+  - While ringing: a clear visual alert and an audible tone, with **Dismiss** and **Snooze (+9 minutes)** actions
+  - Alarms are saved in the browser on the user's device and survive a page reload
+  - Known limitation, stated in the UI: an alarm only rings while the page is open
+- **Out of Scope:**
+  - Daily-repeat / recurring alarms — v2 story if users ask
+  - Configurable snooze duration or snooze intervals
+  - Custom alarm sounds or sound picker
+  - Ringing when the tab is closed or the device is asleep; OS/browser notifications
+  - Accounts, cross-device sync, or any backend
+
+---
+
+## 3. Acceptance Criteria
+
+_These criteria define "Done." Every criterion must be verified by QA._
+
+- [ ] **AC-1:** Given the alarms panel is empty, When the user creates an alarm named "Standup" for 09:30, Then it appears in the list, enabled, with its name and time shown.
+- [ ] **AC-2:** Given an enabled alarm set for 09:30, When the device clock reaches 09:30 with the page open, Then a visual and audible alert starts, and the alarm is automatically disabled afterward.
+- [ ] **AC-3:** Given an alarm is ringing, When the user chooses Snooze, Then the alert stops and the alarm re-arms for 9 minutes later; When the user chooses Dismiss, Then the alert stops and the alarm stays disabled.
+- [ ] **AC-4:** Given one or more alarms exist, When the page is reloaded, Then all alarms reappear with their names, times, and enabled/disabled states intact.
+- [ ] **AC-5:** Given an alarm is disabled, When its time arrives, Then no alert occurs.
+- [ ] **AC-6 (edge case):** Given the user enables an alarm whose time is earlier than the current time, Then it does not ring today and is scheduled for the next occurrence of that time (tomorrow).
+- [ ] **AC-7:** Given an alarm is deleted, Then it disappears from the list, no longer rings, and no longer reappears after a reload.
+- [ ] **AC-8 (validation):** Given the user creates an alarm, Then an invalid or empty time is rejected with a clear message; a blank name defaults to "Alarm".
+
+---
+
+## 4. Technical Guidance & Architectural Constraints
+
+(Filled in by Architect)
+
+- **Target Files / Boundaries:** TBD
+- **Constraints:** TBD
+
+---
+
+## 5. Definition of Done Checklist
+
+- [ ] Code implemented strictly according to ACs.
+
+- [ ] Unit/Integration tests written and passing.
+- [ ] QA assessment passed.
+- [ ] Code Review approved.

From 26cab4fe5b4fb28e5e2000fdce7c12cf5a9a05ff Mon Sep 17 00:00:00 2001
From: Hector Alvarez <alvarez.hectorm@outlook.com>
Date: Sun, 13 Sep 2026 13:07:10 -0500
Subject: [PATCH 2/9] docs(stories): add architect constraints to US-001

---
 docs/stories/US-001-multiple-alarms.md | 39 +++++++++++++++++++++++---
 1 file changed, 35 insertions(+), 4 deletions(-)

diff --git a/docs/stories/US-001-multiple-alarms.md b/docs/stories/US-001-multiple-alarms.md
index 02c2adf..c733d8b 100644
--- a/docs/stories/US-001-multiple-alarms.md
+++ b/docs/stories/US-001-multiple-alarms.md
@@ -49,10 +49,41 @@ _These criteria define "Done." Every criterion must be verified by QA._
 
 ## 4. Technical Guidance & Architectural Constraints
 
-(Filled in by Architect)
-
-- **Target Files / Boundaries:** TBD
-- **Constraints:** TBD
+(Filled in by Architect. Verdict: **Yes** — the existing stack covers this fully; no new dependency, service, or framework is approved, and no ADR is required because the feature follows the established feature-module pattern without any new architectural decision.)
+
+### Target Files / Boundaries
+
+- New feature module `web/src/features/alarm/`, mirroring the timer feature's structure exactly:
+  - `alarm.core.ts` — pure state machine: alarm data shape, add / remove / enable / disable, next-occurrence computation, the per-tick check (e.g. `checkAlarms(state, now)`), and snooze. **Zero DOM, zero storage.**
+  - `alarm.storage.ts` — localStorage adapter, mirroring `timer.storage.ts`.
+  - `alarm.ui.ts` — DOM wiring, the 1-second scheduler interval, the alarm list rendering, and the ringing overlay. Exposes `initAlarm(rootElement, config)` returning a handle with `destroy()` (same contract as `initTimer`), and degrades gracefully when the container is absent.
+  - `index.ts` — barrel; other modules may only import via `@/features/alarm`.
+
+- `web/src/app/config.ts` — add an `ALARM_STORAGE_KEY` constant.
+- `web/src/app/app.ts` — wire `initAlarm` (composition root is the only place that resolves the container; `main.ts` stays a one-liner).
+- `web/src/index.html` — alarm toggle button + panel markup inside `#clock-container`, mirroring the timer wrapper pattern; every interactive element gets an `aria-label`.
+- `web/src/styles/alarm.css` (new) imported from `main.css`; reuse the design tokens in `variables.css`; any media-query rules go in `responsive.css`.
+- Tests mirror the source one-to-one under `web/tests/unit/features/alarm/` (core, storage parsing; optional UI tests via jsdom as the existing suite does).
+
+### Constraints
+
+- **No new dependencies.** The alert tone reuses `playBeep()` from `@/shared/audio/beep` (inject an `AudioContext` in tests); a repeating beep while ringing follows the timer's existing beep-interval pattern.
+- **Purity boundary:** `alarm.core.ts` must not import the DOM, `localStorage`, or `import.meta.env`; current time is always passed in as a parameter so ticks are deterministic in tests.
+- **Persistence:** a single JSON document under `ALARM_STORAGE_KEY`, read/written only through `alarm.storage.ts`; malformed stored data is discarded safely (fall back to empty list), matching the timer's parser.
+- **IDs:** follow the existing `clock-registry` convention (`alarm-<timestamp>-<rand>`). Do **not** wire `clock-registry.ts` into this story — it belongs to the separate multi-clock epic.
+- **Scheduling:** the alarm feature owns its own 1-second interval, independent of the clock's tick; it must be cleared in `destroy()`. The tick check must be idempotent — an alarm may not ring twice for the same occurrence (including the minute it fires in and after page reload).
+- **One-shot semantics:** firing disables the alarm (persisted immediately); snooze is modeled as a future `snoozedUntil` timestamp on the alarm, never as an edit to the alarm's target time. Snooze duration is the fixed constant 9 minutes.
+- **Next occurrence (AC-6):** today if HH:MM is still ahead of `now`, otherwise tomorrow; computed in the pure core.
+- **CSP:** inline styles and scripts are forbidden — all ringing visuals and dynamically rendered list items are styled via classes in `alarm.css` / `animations.css`.
+- **Accessibility:** toggles are real labeled inputs/buttons; the ringing overlay is keyboard-reachable, and pressing Escape (or Enter) dismisses.
+- The panel must display the "alarms ring only while the page is open" limitation (story In-Scope note).
+- **Forbidden moves:** no Service Workers, Notification API, background timers beyond the page interval, new npm packages, changes to `nginx/`, compose files, cache policies, or the timer/clock features' behavior.
+- **Verification gate:** `npm run typecheck`, `npm run lint`, `npx prettier --check .`, and `npm test` must pass locally before commit; CI additionally validates Docker/compose, which this story must not touch.
+
+### Risks for QA
+
+- Background-tab throttling may delay a ring by up to a minute — acceptable, and the panel copy must communicate the limitation.
+- The double-fire guard across page reloads (reload at 09:30:30 must not re-ring a 09:30 alarm) is the trickiest acceptance criterion and needs explicit QA coverage.
 
 ---
 

From 9197f738a567b8026376cebf258b86196a5d90f8 Mon Sep 17 00:00:00 2001
From: Hector Alvarez <alvarez.hectorm@outlook.com>
Date: Sun, 13 Sep 2026 13:15:20 -0500
Subject: [PATCH 3/9] chore(cline): add committed Cline project rules

---
 .clinerules/01-project.md     | 31 ++++++++++++++++++++++++++++++
 .clinerules/02-standards.md   | 36 +++++++++++++++++++++++++++++++++++
 .clinerules/03-memory-bank.md | 31 ++++++++++++++++++++++++++++++
 3 files changed, 98 insertions(+)
 create mode 100644 .clinerules/01-project.md
 create mode 100644 .clinerules/02-standards.md
 create mode 100644 .clinerules/03-memory-bank.md

diff --git a/.clinerules/01-project.md b/.clinerules/01-project.md
new file mode 100644
index 0000000..51618e2
--- /dev/null
+++ b/.clinerules/01-project.md
@@ -0,0 +1,31 @@
+# Clock Website — Project Rules
+
+Folder-per-artifact monorepo: `web/` (TypeScript + Vite 6 app, vanilla DOM — no framework), `nginx/` (edge reverse proxy), `webhook/` (deploy webhook), `scripts/` (host helpers), `docs/` (ADRs, runbooks, stories). Production ingress is a Cloudflare Tunnel; `main` triggers release.yml → GHCR images → webhook auto-deploy on the host.
+
+## Canonical Commands
+
+`make` targets run from the repo root; `npm` commands **only work inside `web/`** (`cd web && ...`). Node ≥22, pinned in `web/.nvmrc`.
+
+| Purpose | Command |
+| :--- | :--- |
+| Full quality gate — run before declaring done | `make check` (lint + typecheck + test) |
+| Dev stack up/down/health | `make dev-up` / `make dev-down` / `make dev-health` |
+| Fast host-only dev loop | `cd web && npm run dev` |
+| Format check (CI enforces it) | `cd web && npm run format:check` |
+| Coverage | `cd web && npm test -- --coverage` |
+
+- CI (`.github/workflows/ci.yml`) also runs `npm run build`, `nginx -t` on both configs, `docker compose config -q` on both stacks, and hadolint on all four Dockerfiles. Any guard CI enforces must be reproducible locally — if you change pipeline-relevant files (compose, Dockerfiles, `nginx.conf`), run the equivalent local checks and say so.
+- Git hooks: husky pre-commit runs lint-staged on staged `web/` files. **Never bypass with `--no-verify`** (merge commits/conflict resolutions excepted).
+
+## Workflow
+
+- Branch from `dev`, PR into `dev`; `main` is the release branch and only moves forward. Keep history **linear — rebase, don't merge**.
+- Conventional commits, scoped where helpful (`feat(timer):`, `fix(web):`, `docs:`, `ci:`), small and self-contained — each commit must build and pass checks on its own (see global Commit Discipline rule).
+- Any architecture change (container layout, ingress, deploy mechanism) requires adding or updating an ADR in `docs/adr/` in the same PR. New features get a user story in `docs/stories/` (see `US-001` for format).
+
+## Safety
+
+- Never edit `.env` or `.env.prod` (Cloudflare tunnel tokens, webhook token). Never echo or commit their contents. Dev and prod tunnels must use different tokens — never copy one into the other.
+- Production deploys are automatic on `main` (webhook). Never run `make prod-deploy`, `make deploy-remote`, `make prod-*`, or `scripts/deploy.sh` unless explicitly asked.
+- `make dev-reset` and `docker compose down -v` wipe volumes — confirm with the user first.
+- Base images in all Dockerfiles are pinned by digest (ADR 0005). Never drop the pin; update it deliberately.
\ No newline at end of file
diff --git a/.clinerules/02-standards.md b/.clinerules/02-standards.md
new file mode 100644
index 0000000..8f18b7b
--- /dev/null
+++ b/.clinerules/02-standards.md
@@ -0,0 +1,36 @@
+---
+paths:
+  - "web/src/**"
+  - "web/tests/**"
+---
+# Code Standards (TypeScript / Vite)
+
+## Architecture (feature-based, see README "Architecture")
+
+- Business logic lives in **pure cores** (`features/*/*.core.ts`, `shared/`) with zero DOM dependencies — push decisions into pure modules and keep DOM wiring thin.
+- **UI layers** (`*.ui.ts`) query the DOM, bind events, and render from the pure core. **Adapters** (`*.storage.ts`, `shared/audio/beep.ts`) isolate side-effecting platform APIs; make platform dependencies injectable (e.g. optional `AudioContext` parameter) so they can be mocked in tests.
+- The composition root (`src/app/app.ts`) is the **only** place that knows page element IDs; `main.ts` only calls `bootstrap()`.
+- Consume features through their barrel (`@/features/clock`, `@/features/timer`), never by reaching into internal modules. Path alias `@/` → `src/`.
+
+## Structure
+
+- `src/features/<feature>/` — one directory per feature with `index.ts` as its public surface; `src/shared/` — cross-feature primitives (time, audio, dom); `src/styles/` — one CSS file per concern imported via `main.css`; `src/public/` — copied verbatim to the build root.
+- Tests mirror `src/` one-to-one under `web/tests/unit/` (`features/clock/clock.core.test.ts` ↔ `features/clock/clock.core.ts`).
+
+## Hard Constraints
+
+- The edge CSP has **no `unsafe-inline`** (ADR 0002): every page — including error pages — ships its CSS as a separate file linked via `<link>`, never inline `<style>` blocks or style attributes.
+- Site-wide security headers belong in `nginx/nginx.conf` only. The app container is a plain static file server that knows nothing about the outside world.
+- `sitemap.xml` and `robots.txt` are **generated** at build time from `VITE_SITE_URL` (see `vite.config.ts`) — never hand-add them to `src/public/`. All absolute URLs derive from that single env value; there is no second place to edit.
+- Both containers listen on **8080**; host port mappings must target 8080.
+
+## Testing
+
+- Vitest + jsdom. Unit-test pure logic directly (timer state machine, clock tick, time formatting); DOM-facing code is testable with jsdom without a browser.
+- New logic goes in a pure module with tests in the mirrored `web/tests/unit/` path — a behavior change without a matching test is incomplete.
+- Prefer tests that document behavior over tests that re-query the DOM for every assertion.
+
+## Style
+
+- Prettier is authoritative: **tabs**, single quotes, semicolons, print width 80, trailing commas — run `npm run format` if lint-staged or `format:check` flags style.
+- ESLint rules are strict: `consistent-type-imports` (use `import type`), no unused vars (prefix intentional ones with `_`), `no-console` (only `error`/`warn` allowed).
\ No newline at end of file
diff --git a/.clinerules/03-memory-bank.md b/.clinerules/03-memory-bank.md
new file mode 100644
index 0000000..d47170e
--- /dev/null
+++ b/.clinerules/03-memory-bank.md
@@ -0,0 +1,31 @@
+# Memory Bank
+
+I am Cline. My memory resets completely between sessions, so I rely entirely on my Memory Bank to understand this project and continue work effectively. At the start of EVERY task, read ALL memory bank files listed below — this is not optional.
+
+## Memory Bank Structure
+
+All files live in `memory-bank/` and build on each other:
+
+1. `projectbrief.md` — foundation document: core requirements and goals. Source of truth for project scope. Created at project start if missing.
+2. `productContext.md` — why the project exists, the problems it solves, how it should work.
+3. `activeContext.md` — current work focus, recent changes, next steps, active decisions. Updated most frequently.
+4. `systemPatterns.md` — system architecture, key technical decisions, design patterns, component relationships.
+5. `techContext.md` — technologies, development setup, constraints, dependencies.
+6. `progress.md` — what works, what is left, current status, known issues.
+
+Additional files may be added under `memory-bank/` for complex features, integrations, API documentation, or deployment procedures.
+
+## Workflow
+
+- **"initialize memory bank"** — create the structure (starting from `projectbrief.md`) by analyzing the codebase.
+- **"follow your custom instructions"** — read all memory bank files and continue where the last session left off.
+- **"update memory bank"** — review ALL files and update them. Trigger after significant changes or milestones.
+
+## Update Triggers
+
+1. Discovering a new project pattern
+2. After implementing significant changes
+3. On explicit "update memory bank" request (review ALL files)
+4. When context needs clarification to proceed
+
+The Memory Bank is the only link to previous work. Maintain it with precision — effectiveness depends entirely on its accuracy.
\ No newline at end of file

From 1fc9974c7c0d7231395bdd1c6d321f5ab0c090d0 Mon Sep 17 00:00:00 2001
From: Hector Alvarez <alvarez.hectorm@outlook.com>
Date: Sun, 13 Sep 2026 13:16:17 -0500
Subject: [PATCH 4/9] feat(alarm): add pure alarm core and storage adapter

---
 web/src/features/alarm/alarm.core.ts          | 232 ++++++++++++++
 web/src/features/alarm/alarm.storage.ts       |  20 ++
 .../unit/features/alarm/alarm.core.test.ts    | 283 ++++++++++++++++++
 .../unit/features/alarm/alarm.storage.test.ts |  40 +++
 4 files changed, 575 insertions(+)
 create mode 100644 web/src/features/alarm/alarm.core.ts
 create mode 100644 web/src/features/alarm/alarm.storage.ts
 create mode 100644 web/tests/unit/features/alarm/alarm.core.test.ts
 create mode 100644 web/tests/unit/features/alarm/alarm.storage.test.ts

diff --git a/web/src/features/alarm/alarm.core.ts b/web/src/features/alarm/alarm.core.ts
new file mode 100644
index 0000000..b01f205
--- /dev/null
+++ b/web/src/features/alarm/alarm.core.ts
@@ -0,0 +1,232 @@
+/**
+ * Pure alarm state machine.
+ *
+ * Every function takes state in and returns new state out — zero DOM, zero
+ * side effects. Fully unit-testable. The current time is always passed in by
+ * the caller (`now`), so tick behaviour is deterministic in tests.
+ */
+
+// ---------- Types ----------
+
+export interface Alarm {
+	id: string;
+	/** User label; empty string means the default display name. */
+	name: string;
+	hour: number;
+	minute: number;
+	enabled: boolean;
+	/** Epoch ms when a snoozed alarm re-arms; `null` when not snoozed. */
+	snoozedUntil: number | null;
+}
+
+export interface AlarmCore {
+	alarms: Alarm[];
+	/** The alarm currently ringing, if any. One overlay at a time. */
+	ringingId: string | null;
+}
+
+export interface AlarmTime {
+	hour: number;
+	minute: number;
+}
+
+/** Fixed snooze duration (story MVP decision). */
+export const SNOOZE_MINUTES = 9;
+
+const SNOOZE_MS = SNOOZE_MINUTES * 60 * 1000;
+
+// ---------- IDs ----------
+
+/** New unique alarm id. Follows the clock-registry id convention. */
+export function createAlarmId(): string {
+	return `alarm-${Date.now()}-${Math.floor(Math.random() * 1000)}`;
+}
+
+// ---------- Input parsing / validation ----------
+
+/**
+ * Parse an `HH:MM` value as produced by an `<input type="time">`.
+ * Returns `null` for anything that is not a valid 24-hour time.
+ */
+export function parseAlarmTime(value: string): AlarmTime | null {
+	const match = /^(\d{1,2}):(\d{2})$/.exec(value.trim());
+	if (!match) return null;
+	const hour = Number(match[1]);
+	const minute = Number(match[2]);
+	if (hour > 23 || minute > 59) return null;
+	return { hour, minute };
+}
+
+/** Format a time as zero-padded `HH:MM`. */
+export function formatAlarmTime(hour: number, minute: number): string {
+	return `${String(hour).padStart(2, '0')}:${String(minute).padStart(2, '0')}`;
+}
+
+/** Display name for an alarm; blank names default to "Alarm". */
+export function alarmDisplayName(alarm: Alarm): string {
+	return alarm.name.trim() || 'Alarm';
+}
+
+// ---------- Persistence parsing ----------
+
+function isAlarm(value: unknown): value is Alarm {
+	if (typeof value !== 'object' || value === null) return false;
+	const candidate = value as Record<string, unknown>;
+	return (
+		typeof candidate.id === 'string' &&
+		typeof candidate.name === 'string' &&
+		typeof candidate.hour === 'number' &&
+		Number.isInteger(candidate.hour) &&
+		candidate.hour >= 0 &&
+		candidate.hour <= 23 &&
+		typeof candidate.minute === 'number' &&
+		Number.isInteger(candidate.minute) &&
+		candidate.minute >= 0 &&
+		candidate.minute <= 59 &&
+		typeof candidate.enabled === 'boolean' &&
+		(candidate.snoozedUntil === null ||
+			typeof candidate.snoozedUntil === 'number')
+	);
+}
+
+/** Parse persisted JSON into alarms; malformed data is discarded. */
+export function parseAlarms(json: string | null): Alarm[] {
+	if (!json) return [];
+	try {
+		const parsed: unknown = JSON.parse(json);
+		if (!Array.isArray(parsed)) return [];
+		return parsed.filter(isAlarm);
+	} catch {
+		return [];
+	}
+}
+
+// ---------- State machine ----------
+
+/** Create the initial alarm core state, optionally from saved alarms. */
+export function createAlarmCore(alarms?: Alarm[]): AlarmCore {
+	return { alarms: alarms ?? [], ringingId: null };
+}
+
+/** Add a new alarm, enabled by default. */
+export function addAlarm(
+	core: AlarmCore,
+	name: string,
+	time: AlarmTime,
+): AlarmCore {
+	const alarm: Alarm = {
+		id: createAlarmId(),
+		name,
+		hour: time.hour,
+		minute: time.minute,
+		enabled: true,
+		snoozedUntil: null,
+	};
+	return { ...core, alarms: [...core.alarms, alarm] };
+}
+
+/** Delete an alarm by id; cancels ringing if it was the one ringing. */
+export function removeAlarm(core: AlarmCore, id: string): AlarmCore {
+	return {
+		alarms: core.alarms.filter((alarm) => alarm.id !== id),
+		ringingId: core.ringingId === id ? null : core.ringingId,
+	};
+}
+
+/**
+ * Enable or disable an alarm.
+ *
+ * Either transition clears any pending snooze: an alarm that is toggled by
+ * hand is re-armed from its configured time, not from an old snooze.
+ */
+export function setAlarmEnabled(
+	core: AlarmCore,
+	id: string,
+	enabled: boolean,
+): AlarmCore {
+	return {
+		...core,
+		alarms: core.alarms.map((alarm) =>
+			alarm.id === id ? { ...alarm, enabled, snoozedUntil: null } : alarm,
+		),
+	};
+}
+
+/** Epoch ms of today's `HH:MM` (may be in the past or the future). */
+function todayAt(hour: number, minute: number, now: Date): number {
+	const candidate = new Date(now);
+	candidate.setHours(hour, minute, 0, 0);
+	return candidate.getTime();
+}
+
+/**
+ * How long after the target minute a late tick still rings the alarm.
+ *
+ * Ticks land just past the second boundary and background tabs may tick as
+ * rarely as once a minute, so the ring window spans the whole target minute.
+ * A time that is already in the past by more than this window stays silent
+ * until its next occurrence (tomorrow) — see AC-6.
+ */
+const RING_GRACE_MS = 60 * 1000;
+
+function isDue(alarm: Alarm, now: Date): boolean {
+	// A snoozed alarm rings by its snooze timestamp regardless of `enabled`:
+	// firing disabled it, and snoozing is the only thing that re-arms it.
+	if (alarm.snoozedUntil !== null) {
+		return now.getTime() >= alarm.snoozedUntil;
+	}
+	if (!alarm.enabled) return false;
+	const delta = now.getTime() - todayAt(alarm.hour, alarm.minute, now);
+	return delta >= 0 && delta < RING_GRACE_MS;
+}
+
+export interface AlarmTickResult {
+	core: AlarmCore;
+	/** The alarm that started ringing on this tick, if any. */
+	rangId: string | null;
+}
+
+/**
+ * Advance the alarm scheduler by one tick.
+ *
+ * The first due alarm starts ringing; it is disabled (one-shot) so the same
+ * occurrence can never ring twice, including across a page reload. When
+ * something is already ringing, due alarms stay armed and ring on a later
+ * tick — the overlay handles one alarm at a time.
+ */
+export function tickAlarms(core: AlarmCore, now: Date): AlarmTickResult {
+	if (core.ringingId !== null) {
+		return { core, rangId: null };
+	}
+	for (const alarm of core.alarms) {
+		if (!isDue(alarm, now)) continue;
+		return {
+			core: {
+				alarms: core.alarms.map((a) =>
+					a.id === alarm.id ? { ...a, enabled: false, snoozedUntil: null } : a,
+				),
+				ringingId: alarm.id,
+			},
+			rangId: alarm.id,
+		};
+	}
+	return { core, rangId: null };
+}
+
+/** Snooze the given alarm; it re-arms `SNOOZE_MINUTES` from `now`. */
+export function snoozeAlarm(core: AlarmCore, id: string, now: Date): AlarmCore {
+	return {
+		...core,
+		ringingId: null,
+		alarms: core.alarms.map((alarm) =>
+			alarm.id === id
+				? { ...alarm, snoozedUntil: now.getTime() + SNOOZE_MS }
+				: alarm,
+		),
+	};
+}
+
+/** Stop ringing (dismiss). The alarm stays disabled. */
+export function dismissAlarm(core: AlarmCore): AlarmCore {
+	return { ...core, ringingId: null };
+}
diff --git a/web/src/features/alarm/alarm.storage.ts b/web/src/features/alarm/alarm.storage.ts
new file mode 100644
index 0000000..5f3290e
--- /dev/null
+++ b/web/src/features/alarm/alarm.storage.ts
@@ -0,0 +1,20 @@
+/**
+ * localStorage adapter for alarms.
+ *
+ * Keeps `window.localStorage` access in one place so the UI layer stays free
+ * of storage concerns and the persistence strategy can be swapped without
+ * touching the UI.
+ */
+
+import { parseAlarms } from './alarm.core';
+import type { Alarm } from './alarm.core';
+
+/** Load alarms stored under `key`, falling back to an empty list. */
+export function loadAlarms(key: string): Alarm[] {
+	return parseAlarms(localStorage.getItem(key));
+}
+
+/** Persist `alarms` under `key`. */
+export function saveAlarms(key: string, alarms: Alarm[]): void {
+	localStorage.setItem(key, JSON.stringify(alarms));
+}
diff --git a/web/tests/unit/features/alarm/alarm.core.test.ts b/web/tests/unit/features/alarm/alarm.core.test.ts
new file mode 100644
index 0000000..b6e791d
--- /dev/null
+++ b/web/tests/unit/features/alarm/alarm.core.test.ts
@@ -0,0 +1,283 @@
+import { describe, it, expect } from 'vitest';
+import {
+	createAlarmId,
+	parseAlarmTime,
+	formatAlarmTime,
+	alarmDisplayName,
+	parseAlarms,
+	createAlarmCore,
+	addAlarm,
+	removeAlarm,
+	setAlarmEnabled,
+	tickAlarms,
+	snoozeAlarm,
+	dismissAlarm,
+	SNOOZE_MINUTES,
+} from '@/features/alarm/alarm.core';
+import type { Alarm, AlarmCore } from '@/features/alarm/alarm.core';
+
+function makeAlarm(overrides: Partial<Alarm> = {}): Alarm {
+	return {
+		id: 'alarm-1',
+		name: 'Standup',
+		hour: 9,
+		minute: 30,
+		enabled: true,
+		snoozedUntil: null,
+		...overrides,
+	};
+}
+
+function makeCore(alarms: Alarm[], ringingId: string | null = null): AlarmCore {
+	return { alarms, ringingId };
+}
+
+// ---------- IDs ----------
+
+describe('createAlarmId', () => {
+	it('follows the alarm-<ts>-<rand> convention', () => {
+		expect(createAlarmId()).toMatch(/^alarm-\d+-\d+$/);
+	});
+
+	it('produces distinct ids', () => {
+		const ids = new Set(Array.from({ length: 20 }, () => createAlarmId()));
+		expect(ids.size).toBeGreaterThan(1);
+	});
+});
+
+// ---------- Input parsing / validation ----------
+
+describe('parseAlarmTime', () => {
+	it('parses valid HH:MM values', () => {
+		expect(parseAlarmTime('09:30')).toEqual({ hour: 9, minute: 30 });
+		expect(parseAlarmTime('23:59')).toEqual({ hour: 23, minute: 59 });
+		expect(parseAlarmTime('0:00')).toEqual({ hour: 0, minute: 0 });
+	});
+
+	it('rejects empty or malformed values', () => {
+		expect(parseAlarmTime('')).toBeNull();
+		expect(parseAlarmTime('abc')).toBeNull();
+		expect(parseAlarmTime('9')).toBeNull();
+		expect(parseAlarmTime('09:3')).toBeNull();
+	});
+
+	it('rejects out-of-range values', () => {
+		expect(parseAlarmTime('24:00')).toBeNull();
+		expect(parseAlarmTime('12:60')).toBeNull();
+		expect(parseAlarmTime('-1:30')).toBeNull();
+	});
+});
+
+describe('formatAlarmTime', () => {
+	it('zero-pads both parts', () => {
+		expect(formatAlarmTime(9, 30)).toBe('09:30');
+		expect(formatAlarmTime(0, 0)).toBe('00:00');
+		expect(formatAlarmTime(23, 59)).toBe('23:59');
+	});
+});
+
+describe('alarmDisplayName', () => {
+	it('returns the trimmed name', () => {
+		expect(alarmDisplayName(makeAlarm({ name: ' Standup ' }))).toBe('Standup');
+	});
+
+	it('defaults a blank name to Alarm', () => {
+		expect(alarmDisplayName(makeAlarm({ name: '' }))).toBe('Alarm');
+		expect(alarmDisplayName(makeAlarm({ name: '   ' }))).toBe('Alarm');
+	});
+});
+
+// ---------- Persistence parsing ----------
+
+describe('parseAlarms', () => {
+	it('returns an empty list for null/empty input', () => {
+		expect(parseAlarms(null)).toEqual([]);
+		expect(parseAlarms('')).toEqual([]);
+	});
+
+	it('returns an empty list for malformed JSON', () => {
+		expect(parseAlarms('{not json')).toEqual([]);
+	});
+
+	it('returns an empty list for non-array JSON', () => {
+		expect(parseAlarms('{"id": "alarm-1"}')).toEqual([]);
+	});
+
+	it('keeps valid alarm entries', () => {
+		const json = JSON.stringify([makeAlarm()]);
+		expect(parseAlarms(json)).toEqual([makeAlarm()]);
+	});
+
+	it('discards malformed entries but keeps valid ones', () => {
+		const json = JSON.stringify([
+			makeAlarm(),
+			{ id: 'alarm-2' },
+			makeAlarm({ id: 'alarm-3', hour: 25 }),
+			makeAlarm({ id: 'alarm-4', snoozedUntil: 'soon' }),
+		]);
+		const alarms = parseAlarms(json);
+		expect(alarms.map((alarm) => alarm.id)).toEqual(['alarm-1']);
+	});
+});
+
+// ---------- State machine ----------
+
+describe('addAlarm', () => {
+	it('appends a new enabled alarm', () => {
+		const core = addAlarm(createAlarmCore(), 'Standup', {
+			hour: 9,
+			minute: 30,
+		});
+		expect(core.alarms).toHaveLength(1);
+		expect(core.alarms[0]).toMatchObject({
+			name: 'Standup',
+			hour: 9,
+			minute: 30,
+			enabled: true,
+			snoozedUntil: null,
+		});
+		expect(core.alarms[0].id).toMatch(/^alarm-/);
+		expect(core.ringingId).toBeNull();
+	});
+
+	it('does not mutate the previous state', () => {
+		const before = createAlarmCore();
+		addAlarm(before, 'Standup', { hour: 9, minute: 30 });
+		expect(before.alarms).toHaveLength(0);
+	});
+});
+
+describe('removeAlarm', () => {
+	it('removes the alarm by id', () => {
+		const core = makeCore([makeAlarm(), makeAlarm({ id: 'alarm-2' })]);
+		const next = removeAlarm(core, 'alarm-1');
+		expect(next.alarms.map((alarm) => alarm.id)).toEqual(['alarm-2']);
+	});
+
+	it('stops ringing when the ringing alarm is removed', () => {
+		const core = makeCore([makeAlarm()], 'alarm-1');
+		expect(removeAlarm(core, 'alarm-1').ringingId).toBeNull();
+	});
+
+	it('keeps ringing when a different alarm is removed', () => {
+		const core = makeCore(
+			[makeAlarm(), makeAlarm({ id: 'alarm-2' })],
+			'alarm-1',
+		);
+		expect(removeAlarm(core, 'alarm-2').ringingId).toBe('alarm-1');
+	});
+});
+
+describe('setAlarmEnabled', () => {
+	it('disables an alarm', () => {
+		const next = setAlarmEnabled(makeCore([makeAlarm()]), 'alarm-1', false);
+		expect(next.alarms[0].enabled).toBe(false);
+	});
+
+	it('re-enabling clears any pending snooze', () => {
+		const core = makeCore([makeAlarm({ enabled: false, snoozedUntil: 5000 })]);
+		const next = setAlarmEnabled(core, 'alarm-1', true);
+		expect(next.alarms[0].snoozedUntil).toBeNull();
+		expect(next.alarms[0].enabled).toBe(true);
+	});
+
+	it('disabling also clears any pending snooze', () => {
+		const core = makeCore([makeAlarm({ enabled: true, snoozedUntil: 5000 })]);
+		const next = setAlarmEnabled(core, 'alarm-1', false);
+		expect(next.alarms[0].snoozedUntil).toBeNull();
+	});
+});
+
+describe('tickAlarms', () => {
+	const now = new Date(2026, 8, 13, 9, 30, 30); // just past 09:30
+
+	it('rings an alarm exactly at its time', () => {
+		const exact = new Date(2026, 8, 13, 9, 30, 0);
+		const result = tickAlarms(makeCore([makeAlarm()]), exact);
+		expect(result.rangId).toBe('alarm-1');
+	});
+
+	it('does not ring an alarm missed beyond the grace window', () => {
+		const late = new Date(2026, 8, 13, 10, 0, 0);
+		const result = tickAlarms(makeCore([makeAlarm()]), late);
+		expect(result.rangId).toBeNull();
+		expect(result.core.alarms[0].enabled).toBe(true);
+	});
+
+	it('rings a due enabled alarm and disables it (one-shot)', () => {
+		const core = makeCore([makeAlarm({ hour: 9, minute: 30 })]);
+		const result = tickAlarms(core, now);
+		expect(result.rangId).toBe('alarm-1');
+		expect(result.core.ringingId).toBe('alarm-1');
+		expect(result.core.alarms[0].enabled).toBe(false);
+	});
+
+	it('does not ring a disabled alarm', () => {
+		const core = makeCore([makeAlarm({ enabled: false })]);
+		const result = tickAlarms(core, now);
+		expect(result.rangId).toBeNull();
+		expect(result.core).toEqual(core);
+	});
+
+	it('does not ring an alarm whose time is still ahead', () => {
+		const core = makeCore([makeAlarm({ hour: 10, minute: 30 })]);
+		const result = tickAlarms(core, now);
+		expect(result.rangId).toBeNull();
+	});
+
+	it('does not ring an alarm scheduled for a time earlier today twice', () => {
+		// After firing, the alarm is disabled, so a later tick (or a reload
+		// mid-minute) cannot ring the same occurrence again.
+		const fired = makeCore([makeAlarm({ enabled: false })]);
+		const result = tickAlarms(fired, now);
+		expect(result.rangId).toBeNull();
+	});
+
+	it('defers a second due alarm while one is already ringing', () => {
+		const core = makeCore(
+			[makeAlarm({ hour: 9, minute: 29 }), makeAlarm({ id: 'alarm-2' })],
+			'alarm-1',
+		);
+		const result = tickAlarms(core, now);
+		expect(result.rangId).toBeNull();
+		expect(result.core.alarms[1].enabled).toBe(true);
+	});
+
+	it('rings a snoozed alarm once its snooze expires', () => {
+		const snoozedUntil = now.getTime() - 1;
+		const core = makeCore([makeAlarm({ enabled: false, snoozedUntil })]);
+		const result = tickAlarms(core, now);
+		expect(result.rangId).toBe('alarm-1');
+		expect(result.core.alarms[0].snoozedUntil).toBeNull();
+		expect(result.core.alarms[0].enabled).toBe(false);
+	});
+
+	it('does not ring a snoozed alarm before its snooze expires', () => {
+		const snoozedUntil = now.getTime() + 60_000;
+		const core = makeCore([makeAlarm({ enabled: false, snoozedUntil })]);
+		const result = tickAlarms(core, now);
+		expect(result.rangId).toBeNull();
+	});
+});
+
+describe('snoozeAlarm', () => {
+	it('re-arms the alarm SNOOZE_MINUTES from now and stops ringing', () => {
+		const now = new Date(2026, 8, 13, 9, 30, 0);
+		const core = makeCore([makeAlarm({ enabled: false })], 'alarm-1');
+		const next = snoozeAlarm(core, 'alarm-1', now);
+		expect(next.ringingId).toBeNull();
+		expect(next.alarms[0].snoozedUntil).toBe(
+			now.getTime() + SNOOZE_MINUTES * 60_000,
+		);
+	});
+});
+
+describe('dismissAlarm', () => {
+	it('stops ringing without changing the alarm', () => {
+		const alarm = makeAlarm({ enabled: false });
+		const core = makeCore([alarm], 'alarm-1');
+		const next = dismissAlarm(core);
+		expect(next.ringingId).toBeNull();
+		expect(next.alarms[0]).toEqual(alarm);
+	});
+});
diff --git a/web/tests/unit/features/alarm/alarm.storage.test.ts b/web/tests/unit/features/alarm/alarm.storage.test.ts
new file mode 100644
index 0000000..df528ce
--- /dev/null
+++ b/web/tests/unit/features/alarm/alarm.storage.test.ts
@@ -0,0 +1,40 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { loadAlarms, saveAlarms } from '@/features/alarm/alarm.storage';
+import type { Alarm } from '@/features/alarm/alarm.core';
+
+const KEY = 'test-alarms';
+
+const alarm: Alarm = {
+	id: 'alarm-1',
+	name: 'Standup',
+	hour: 9,
+	minute: 30,
+	enabled: true,
+	snoozedUntil: null,
+};
+
+beforeEach(() => {
+	localStorage.clear();
+});
+
+describe('saveAlarms / loadAlarms', () => {
+	it('round-trips alarms through localStorage', () => {
+		saveAlarms(KEY, [alarm]);
+		expect(loadAlarms(KEY)).toEqual([alarm]);
+	});
+
+	it('returns an empty list when the key is missing', () => {
+		expect(loadAlarms(KEY)).toEqual([]);
+	});
+
+	it('returns an empty list when the stored value is corrupted', () => {
+		localStorage.setItem(KEY, '{not json');
+		expect(loadAlarms(KEY)).toEqual([]);
+	});
+
+	it('overwrites previously stored alarms', () => {
+		saveAlarms(KEY, [alarm]);
+		saveAlarms(KEY, []);
+		expect(loadAlarms(KEY)).toEqual([]);
+	});
+});

From 58d0323d15ee4094c69a6e367f3ac139c579c5c0 Mon Sep 17 00:00:00 2001
From: Hector Alvarez <alvarez.hectorm@outlook.com>
Date: Sun, 13 Sep 2026 13:20:20 -0500
Subject: [PATCH 5/9] feat(alarm): add alarm UI, page wiring, and styles

---
 web/src/app/app.ts                 |   8 +-
 web/src/app/config.ts              |   3 +
 web/src/features/alarm/alarm.ui.ts | 396 +++++++++++++++++++++++++++++
 web/src/features/alarm/index.ts    |  10 +
 web/src/index.html                 |  46 ++++
 web/src/styles/alarm.css           | 317 +++++++++++++++++++++++
 web/src/styles/animations.css      |  11 +
 web/src/styles/main.css            |   1 +
 web/src/styles/responsive.css      |  55 +++-
 9 files changed, 839 insertions(+), 8 deletions(-)
 create mode 100644 web/src/features/alarm/alarm.ui.ts
 create mode 100644 web/src/features/alarm/index.ts
 create mode 100644 web/src/styles/alarm.css

diff --git a/web/src/app/app.ts b/web/src/app/app.ts
index 2d6b1ba..6fc0f5a 100644
--- a/web/src/app/app.ts
+++ b/web/src/app/app.ts
@@ -1,6 +1,7 @@
+import { initAlarm } from '@/features/alarm';
 import { initClock } from '@/features/clock';
 import { initTimer } from '@/features/timer';
-import { TIMER_STORAGE_KEY } from './config';
+import { ALARM_STORAGE_KEY, TIMER_STORAGE_KEY } from './config';
 
 /**
  * Composition root: wires the feature modules into the static page.
@@ -18,4 +19,9 @@ export function bootstrap(): void {
 	if (timerWrapper) {
 		initTimer(timerWrapper, { storageKey: TIMER_STORAGE_KEY });
 	}
+
+	const alarmWrapper = document.getElementById('alarm-wrapper');
+	if (alarmWrapper) {
+		initAlarm(alarmWrapper, { storageKey: ALARM_STORAGE_KEY });
+	}
 }
diff --git a/web/src/app/config.ts b/web/src/app/config.ts
index 0129219..d7c4a91 100644
--- a/web/src/app/config.ts
+++ b/web/src/app/config.ts
@@ -14,3 +14,6 @@ export const IS_DEV = APP_ENV === 'development';
 
 /** localStorage key holding the main timer's saved presets. */
 export const TIMER_STORAGE_KEY = 'main-timer-presets';
+
+/** localStorage key holding the user's alarms. */
+export const ALARM_STORAGE_KEY = 'alarms';
diff --git a/web/src/features/alarm/alarm.ui.ts b/web/src/features/alarm/alarm.ui.ts
new file mode 100644
index 0000000..e5fe5e6
--- /dev/null
+++ b/web/src/features/alarm/alarm.ui.ts
@@ -0,0 +1,396 @@
+import { playBeep } from '@/shared/audio/beep';
+import { queryOptional } from '@/shared/dom/query';
+import {
+	addAlarm,
+	alarmDisplayName,
+	createAlarmCore,
+	dismissAlarm,
+	formatAlarmTime,
+	parseAlarmTime,
+	removeAlarm,
+	setAlarmEnabled,
+	snoozeAlarm,
+	tickAlarms,
+} from './alarm.core';
+import type { AlarmCore } from './alarm.core';
+import { loadAlarms, saveAlarms } from './alarm.storage';
+
+/** Handle returned by {@link initAlarm} for driving alarms from outside. */
+export interface AlarmInstance {
+	togglePanel: () => void;
+	getState: () => AlarmCore;
+	destroy: () => void;
+}
+
+export interface AlarmConfig {
+	storageKey?: string;
+}
+
+export function initAlarm(
+	rootElement: HTMLElement,
+	config: AlarmConfig = {},
+): AlarmInstance | undefined {
+	// ---------- DOM lookups (with type narrowing guard) ----------
+
+	const toggleBtn = queryOptional<HTMLButtonElement>(
+		rootElement,
+		'.alarm-toggle',
+	);
+	const panel = queryOptional<HTMLElement>(rootElement, '.alarm-panel');
+	const nameInput = queryOptional<HTMLInputElement>(rootElement, '.alarm-name');
+	const timeInput = queryOptional<HTMLInputElement>(rootElement, '.alarm-time');
+	const addBtn = queryOptional<HTMLButtonElement>(rootElement, '.alarm-add');
+	const errorEl = queryOptional<HTMLElement>(rootElement, '.alarm-error');
+	const list = queryOptional<HTMLElement>(rootElement, '.alarm-list');
+
+	const overlay = queryOptional<HTMLElement>(document, '.alarm-overlay');
+	const overlayName = queryOptional<HTMLElement>(
+		document,
+		'.alarm-overlay-name',
+	);
+	const overlayTime = queryOptional<HTMLElement>(
+		document,
+		'.alarm-overlay-time',
+	);
+	const snoozeBtn = queryOptional<HTMLButtonElement>(document, '.alarm-snooze');
+	const dismissBtn = queryOptional<HTMLButtonElement>(
+		document,
+		'.alarm-dismiss',
+	);
+
+	if (
+		!toggleBtn ||
+		!panel ||
+		!nameInput ||
+		!timeInput ||
+		!addBtn ||
+		!errorEl ||
+		!list ||
+		!overlay ||
+		!overlayName ||
+		!overlayTime ||
+		!snoozeBtn ||
+		!dismissBtn
+	) {
+		console.error('Could not find all required alarm elements.');
+		return;
+	}
+
+	// Narrow once so the closures below capture non-null bindings.
+	const dom = {
+		toggleBtn,
+		panel,
+		nameInput,
+		timeInput,
+		addBtn,
+		errorEl,
+		list,
+		overlay,
+		overlayName,
+		overlayTime,
+		snoozeBtn,
+		dismissBtn,
+	};
+
+	// ---------- Core state ----------
+
+	const storageKey = config.storageKey ?? 'alarms';
+	let core = createAlarmCore(loadAlarms(storageKey));
+	let intervalId: number | null = null;
+	let beepIntervalId: number | null = null;
+	let isPanelOpen = false;
+
+	let sharedAudioCtx: AudioContext | null = null;
+
+	function getAudioCtx() {
+		if (!sharedAudioCtx || sharedAudioCtx.state === 'closed') {
+			sharedAudioCtx = new AudioContext();
+		}
+		return sharedAudioCtx;
+	}
+
+	// ---------- Persistence ----------
+
+	function persist() {
+		saveAlarms(storageKey, core.alarms);
+	}
+
+	// ---------- Render ----------
+
+	function renderAlarmList() {
+		dom.list.textContent = '';
+		for (const alarm of core.alarms) {
+			const row = document.createElement('div');
+			row.className = 'alarm-row';
+			row.dataset.id = alarm.id;
+			const isArmed = alarm.enabled || alarm.snoozedUntil !== null;
+			if (!isArmed) row.classList.add('disabled');
+
+			const name = document.createElement('span');
+			name.className = 'alarm-row-name';
+			name.textContent = alarmDisplayName(alarm);
+
+			const time = document.createElement('span');
+			time.className = 'alarm-row-time';
+			time.textContent = formatAlarmTime(alarm.hour, alarm.minute);
+			if (alarm.snoozedUntil !== null) {
+				time.classList.add('snoozed');
+			}
+
+			const toggle = document.createElement('input');
+			toggle.type = 'checkbox';
+			toggle.className = 'alarm-row-toggle';
+			toggle.checked = isArmed;
+			toggle.setAttribute('aria-label', `Enable ${alarmDisplayName(alarm)}`);
+
+			const removeBtn = document.createElement('button');
+			removeBtn.className = 'alarm-row-remove';
+			removeBtn.textContent = '✕';
+			removeBtn.setAttribute('aria-label', `Delete ${alarmDisplayName(alarm)}`);
+
+			row.append(name, time, toggle, removeBtn);
+			dom.list.append(row);
+		}
+	}
+
+	function renderToggle() {
+		dom.toggleBtn.classList.toggle('active', isPanelOpen);
+		const armed = core.alarms.some(
+			(alarm) => alarm.enabled || alarm.snoozedUntil !== null,
+		);
+		dom.toggleBtn.classList.toggle('armed', armed);
+	}
+
+	// ---------- Ringing ----------
+
+	function stopBeeps() {
+		if (beepIntervalId !== null) {
+			clearInterval(beepIntervalId);
+			beepIntervalId = null;
+		}
+	}
+
+	function ring(id: string) {
+		const alarm = core.alarms.find((a) => a.id === id);
+		if (!alarm) return;
+		dom.overlayName.textContent = alarmDisplayName(alarm);
+		dom.overlayTime.textContent = formatAlarmTime(alarm.hour, alarm.minute);
+		dom.overlay.hidden = false;
+		playBeep(getAudioCtx());
+		beepIntervalId = window.setInterval(() => {
+			playBeep(getAudioCtx());
+		}, 1000);
+	}
+
+	function stopRinging() {
+		stopBeeps();
+		dom.overlay.hidden = true;
+		renderAlarmList();
+	}
+
+	function onSnooze() {
+		const id = core.ringingId;
+		if (id === null) return;
+		core = snoozeAlarm(core, id, new Date());
+		persist();
+		stopRinging();
+		renderToggle();
+	}
+
+	function onDismiss() {
+		if (core.ringingId === null) return;
+		core = dismissAlarm(core);
+		stopRinging();
+		renderToggle();
+	}
+
+	// ---------- Scheduler ----------
+
+	function tick() {
+		const result = tickAlarms(core, new Date());
+		if (result.rangId === null) return;
+		core = result.core;
+		persist();
+		renderAlarmList();
+		renderToggle();
+		ring(result.rangId);
+	}
+
+	// ---------- Create ----------
+
+	function onAdd() {
+		const time = parseAlarmTime(dom.timeInput.value);
+		dom.errorEl.textContent = '';
+		if (!time) {
+			dom.errorEl.textContent = 'Set a valid time (HH:MM).';
+			return;
+		}
+		core = addAlarm(core, dom.nameInput.value, time);
+		persist();
+		dom.nameInput.value = '';
+		dom.timeInput.value = '';
+		renderAlarmList();
+		renderToggle();
+	}
+
+	// ---------- List events (delegation) ----------
+
+	function onListChange(e: Event) {
+		const target = e.target as HTMLElement;
+		if (!target.classList.contains('alarm-row-toggle')) return;
+		const row = target.closest('.alarm-row');
+		const id = row instanceof HTMLElement ? row.dataset.id : undefined;
+		if (!id) return;
+		const checked = target instanceof HTMLInputElement && target.checked;
+		core = setAlarmEnabled(core, id, checked);
+		persist();
+		renderAlarmList();
+		renderToggle();
+	}
+
+	function onListClick(e: MouseEvent) {
+		const target = e.target as HTMLElement;
+		if (!target.classList.contains('alarm-row-remove')) return;
+		const row = target.closest('.alarm-row');
+		const id = row instanceof HTMLElement ? row.dataset.id : undefined;
+		if (!id) return;
+		core = removeAlarm(core, id);
+		persist();
+		renderAlarmList();
+		renderToggle();
+	}
+
+	// ---------- Panel toggle ----------
+
+	// FLIP animation: smoothly animate #clock-container movement when the
+	// panel is added/removed (which re-centers the container in the body).
+	// Mirrors the timer feature's open/close behaviour so both panels feel
+	// the same.
+	function flipAnimateClockContainer(action: () => void) {
+		const container = rootElement.closest(
+			'#clock-container',
+		) as HTMLElement | null;
+		if (!container) {
+			action();
+			return;
+		}
+
+		// Lock body overflow so the page can't scroll while the height changes
+		const prevBodyOverflow = document.body.style.overflow;
+		document.body.style.overflow = 'hidden';
+
+		const firstRect = container.getBoundingClientRect();
+
+		action();
+
+		const lastRect = container.getBoundingClientRect();
+		const deltaY = firstRect.top - lastRect.top;
+		container.style.transition = 'none';
+		container.style.transform = `translateY(${deltaY}px)`;
+
+		requestAnimationFrame(() => {
+			container.style.transition =
+				'transform 0.3s cubic-bezier(0.34, 1.56, 0.64, 1)';
+			container.style.transform = '';
+		});
+
+		const onEnd = () => {
+			container.removeEventListener('transitionend', onEnd);
+			container.style.transition = '';
+			container.style.transform = '';
+			document.body.style.overflow = prevBodyOverflow;
+		};
+		container.addEventListener('transitionend', onEnd);
+
+		// Fallback in case transitionend doesn't fire
+		setTimeout(onEnd, 400);
+	}
+
+	function openPanel() {
+		flipAnimateClockContainer(() => {
+			isPanelOpen = true;
+			dom.panel.removeAttribute('hidden');
+			renderToggle();
+		});
+	}
+
+	function closePanel() {
+		flipAnimateClockContainer(() => {
+			isPanelOpen = false;
+			dom.panel.setAttribute('hidden', '');
+			renderToggle();
+		});
+	}
+
+	function togglePanel() {
+		if (isPanelOpen) closePanel();
+		else openPanel();
+	}
+
+	// ---------- Document-level events ----------
+
+	function onDocumentClick(e: MouseEvent) {
+		const target = e.target as Node;
+		if (isPanelOpen && !rootElement.contains(target)) {
+			closePanel();
+		}
+	}
+
+	function onDocumentKeydown(e: KeyboardEvent) {
+		// While ringing, Escape and Enter dismiss — the overlay takes priority
+		// over the panel-close shortcut.
+		if (core.ringingId !== null && (e.key === 'Escape' || e.key === 'Enter')) {
+			onDismiss();
+			return;
+		}
+		if (e.key === 'Escape' && isPanelOpen) closePanel();
+	}
+
+	// ---------- Init ----------
+
+	function init() {
+		renderAlarmList();
+		renderToggle();
+
+		dom.toggleBtn.addEventListener('click', togglePanel);
+		dom.addBtn.addEventListener('click', onAdd);
+		dom.list.addEventListener('change', onListChange);
+		dom.list.addEventListener('click', onListClick);
+		dom.snoozeBtn.addEventListener('click', onSnooze);
+		dom.dismissBtn.addEventListener('click', onDismiss);
+		dom.nameInput.addEventListener('keydown', (e) => {
+			if (e.key === 'Enter') onAdd();
+		});
+		dom.timeInput.addEventListener('keydown', (e) => {
+			if (e.key === 'Enter') onAdd();
+		});
+		document.addEventListener('click', onDocumentClick);
+		document.addEventListener('keydown', onDocumentKeydown);
+
+		// Catch alarms that came due before this init (e.g. an expired snooze
+		// or an alarm that arrived within the last grace window).
+		tick();
+		intervalId = window.setInterval(tick, 1000);
+	}
+
+	function destroy() {
+		if (intervalId !== null) {
+			clearInterval(intervalId);
+			intervalId = null;
+		}
+		stopBeeps();
+		if (sharedAudioCtx && sharedAudioCtx.state !== 'closed') {
+			sharedAudioCtx.close().catch(console.error);
+		}
+		document.removeEventListener('click', onDocumentClick);
+		document.removeEventListener('keydown', onDocumentKeydown);
+	}
+
+	init();
+
+	return {
+		togglePanel,
+		getState: () => core,
+		destroy,
+	};
+}
diff --git a/web/src/features/alarm/index.ts b/web/src/features/alarm/index.ts
new file mode 100644
index 0000000..ab78c24
--- /dev/null
+++ b/web/src/features/alarm/index.ts
@@ -0,0 +1,10 @@
+/**
+ * Public surface of the alarm feature.
+ *
+ * Consumers should import from `@/features/alarm` rather than reaching into
+ * the individual `alarm.core` / `alarm.storage` / `alarm.ui` modules.
+ */
+export { initAlarm } from './alarm.ui';
+export type { AlarmConfig, AlarmInstance } from './alarm.ui';
+export type { Alarm, AlarmCore, AlarmTime } from './alarm.core';
+export { SNOOZE_MINUTES } from './alarm.core';
diff --git a/web/src/index.html b/web/src/index.html
index edef714..73d1c86 100644
--- a/web/src/index.html
+++ b/web/src/index.html
@@ -86,7 +86,53 @@
 					</div>
 				</div>
 			</div>
+
+			<div id="alarm-wrapper">
+				<button class="alarm-toggle" aria-label="Toggle alarms" title="Alarms">
+					⏰
+				</button>
+				<div class="alarm-panel" hidden>
+					<div class="alarm-create">
+						<input
+							class="alarm-name"
+							type="text"
+							maxlength="30"
+							placeholder="Name (optional)"
+							aria-label="Alarm name"
+						/>
+						<input class="alarm-time" type="time" aria-label="Alarm time" />
+						<button class="alarm-add" aria-label="Add alarm">+ Add</button>
+					</div>
+					<div class="alarm-error" role="alert"></div>
+					<div class="alarm-list">
+						<!-- Alarm rows rendered dynamically -->
+					</div>
+					<p class="alarm-note">Alarms ring only while this page is open.</p>
+				</div>
+			</div>
+		</div>
+
+		<!-- Ringing overlay — lives outside the clock container so it can cover
+		     the whole viewport -->
+		<div class="alarm-overlay" hidden>
+			<div
+				class="alarm-overlay-card"
+				role="alertdialog"
+				aria-label="Alarm ringing"
+			>
+				<div class="alarm-overlay-name"></div>
+				<div class="alarm-overlay-time"></div>
+				<div class="alarm-overlay-actions">
+					<button class="alarm-snooze" aria-label="Snooze alarm for 9 minutes">
+						💤 Snooze 9m
+					</button>
+					<button class="alarm-dismiss" aria-label="Dismiss alarm">
+						✕ Dismiss
+					</button>
+				</div>
+			</div>
 		</div>
+
 		<div class="environment-marker"></div>
 
 		<script type="module" src="./main.ts"></script>
diff --git a/web/src/styles/alarm.css b/web/src/styles/alarm.css
new file mode 100644
index 0000000..b3c297b
--- /dev/null
+++ b/web/src/styles/alarm.css
@@ -0,0 +1,317 @@
+/* ============================================================
+   ALARM COMPONENT
+   Alarm wrapper, toggle, panel, create controls, list, and the
+   ringing overlay. Reuses the design tokens and mirrors the
+   timer component's styling conventions.
+   ============================================================ */
+
+/* ---------- Wrapper & Toggle ---------- */
+
+#alarm-wrapper {
+	display: flex;
+	flex-direction: column;
+	align-items: center;
+	gap: var(--space-md);
+	position: relative;
+}
+
+.alarm-toggle {
+	background: none;
+	border: var(--border-width-strong) solid var(--color-primary);
+	color: var(--color-primary);
+	font-size: var(--font-size-toggle);
+	cursor: pointer;
+	border-radius: var(--border-radius-md);
+	padding: var(--space-xs) var(--space-xl);
+	transition:
+		background-color var(--transition-normal),
+		box-shadow var(--transition-normal);
+	line-height: 1;
+}
+
+.alarm-toggle:hover,
+.alarm-toggle:focus-visible {
+	background-color: var(--color-primary-soft);
+	box-shadow: var(--glow-md);
+}
+
+.alarm-toggle.active {
+	box-shadow: var(--glow-md);
+}
+
+/* Pulse while at least one alarm is armed */
+.alarm-toggle.armed {
+	animation: timer-pulse 1.5s ease-in-out infinite;
+}
+
+/* ---------- Panel ---------- */
+
+.alarm-panel {
+	display: flex;
+	flex-direction: column;
+	align-items: stretch;
+	gap: var(--space-sm);
+	padding: var(--panel-padding-y) var(--panel-padding-x);
+	border: var(--border-width) solid var(--color-primary);
+	border-radius: var(--border-radius-lg);
+	background-color: var(--color-surface);
+	box-sizing: border-box;
+	width: var(--panel-width);
+	box-shadow: var(--glow-subtle);
+	animation: timer-panel-open 0.3s cubic-bezier(0.34, 1.56, 0.64, 1) both;
+}
+
+.alarm-panel[hidden] {
+	display: none;
+}
+
+/* ---------- Create controls ---------- */
+
+.alarm-create {
+	display: flex;
+	align-items: center;
+	gap: var(--space-xs);
+	width: 100%;
+}
+
+.alarm-create input {
+	min-width: 0;
+	flex: 1;
+	padding: var(--space-xs) var(--space-sm);
+	font-size: var(--font-size-timer-input);
+	text-align: center;
+	background-color: var(--color-surface-alt);
+	border: var(--border-width) solid var(--color-primary);
+	border-radius: var(--border-radius-sm);
+	color: var(--color-primary);
+	font-family: var(--font-family);
+}
+
+.alarm-add {
+	background: none;
+	border: var(--border-width) dashed var(--color-primary);
+	color: var(--color-primary);
+	font-size: var(--font-size-xs);
+	cursor: pointer;
+	border-radius: var(--border-radius-sm);
+	padding: var(--space-2xs) var(--space-lg);
+	transition:
+		background-color var(--transition-normal),
+		box-shadow var(--transition-normal);
+	line-height: 1;
+	opacity: 0.7;
+	flex-shrink: 0;
+}
+
+.alarm-add:hover,
+.alarm-add:focus-visible {
+	background-color: var(--color-primary-soft);
+	opacity: 1;
+	box-shadow: var(--glow-sm);
+}
+
+.alarm-error {
+	color: var(--color-danger);
+	font-size: var(--font-size-small);
+	min-height: 1.2em;
+	text-align: center;
+}
+
+/* ---------- List ---------- */
+
+.alarm-list {
+	display: flex;
+	flex-direction: column;
+	gap: var(--space-xs);
+	width: 100%;
+	max-height: 180px;
+	overflow-y: auto;
+}
+
+.alarm-list:empty::after {
+	content: 'No alarms yet';
+	display: block;
+	text-align: center;
+	font-size: var(--font-size-small);
+	opacity: 0.5;
+	padding: var(--space-md) 0;
+}
+
+.alarm-row {
+	display: flex;
+	align-items: center;
+	gap: var(--space-sm);
+	padding: var(--space-xs) var(--space-md);
+	border: var(--border-width) solid var(--color-primary-medium);
+	border-radius: var(--border-radius-sm);
+}
+
+.alarm-row-name {
+	flex: 1;
+	font-size: var(--font-size-small);
+	line-height: 1;
+	overflow: hidden;
+	text-overflow: ellipsis;
+	white-space: nowrap;
+	user-select: none;
+}
+
+.alarm-row-time {
+	font-size: var(--font-size-small);
+	line-height: 1;
+	font-variant-numeric: tabular-nums;
+}
+
+.alarm-row-time.snoozed::after {
+	content: ' · snoozed';
+	opacity: 0.6;
+}
+
+.alarm-row.disabled .alarm-row-name,
+.alarm-row.disabled .alarm-row-time {
+	opacity: 0.4;
+}
+
+.alarm-row-toggle {
+	accent-color: var(--color-primary);
+	cursor: pointer;
+	flex-shrink: 0;
+}
+
+.alarm-row-remove {
+	background: none;
+	border: none;
+	color: var(--color-primary);
+	opacity: 0.5;
+	font-size: 0.9em;
+	line-height: 1;
+	padding: 0 var(--space-2xs);
+	cursor: pointer;
+	transition:
+		opacity var(--transition-fast),
+		color var(--transition-fast);
+	flex-shrink: 0;
+}
+
+.alarm-row-remove:hover {
+	opacity: 1;
+	color: var(--color-danger);
+}
+
+/* ---------- Note ---------- */
+
+.alarm-note {
+	margin: 0;
+	text-align: center;
+	font-size: var(--font-size-xs);
+	opacity: 0.55;
+}
+
+/* ---------- Ringing overlay ---------- */
+
+.alarm-overlay {
+	position: fixed;
+	inset: 0;
+	display: flex;
+	align-items: center;
+	justify-content: center;
+	background-color: rgba(0, 0, 0, 0.7);
+	z-index: 100;
+}
+
+.alarm-overlay[hidden] {
+	display: none;
+}
+
+.alarm-overlay-card {
+	display: flex;
+	flex-direction: column;
+	align-items: center;
+	gap: var(--space-3xl);
+	padding: var(--space-4xl) var(--space-3xl);
+	border: var(--border-width-strong) solid var(--color-primary);
+	border-radius: var(--border-radius-lg);
+	background-color: var(--color-surface);
+	box-shadow: var(--glow-lg);
+	animation: alarm-pulse 1s ease-in-out infinite;
+	min-width: 260px;
+	max-width: calc(100vw - 32px);
+	box-sizing: border-box;
+}
+
+.alarm-overlay-name {
+	font-size: var(--font-size-timer-finish);
+	font-weight: var(--font-weight-bold);
+	text-align: center;
+}
+
+.alarm-overlay-time {
+	font-size: var(--font-size-timer-display);
+	color: var(--color-primary);
+	font-variant-numeric: tabular-nums;
+	letter-spacing: 0.05em;
+	text-align: center;
+}
+
+.alarm-overlay-actions {
+	display: flex;
+	gap: var(--space-md);
+}
+
+.alarm-overlay-actions button {
+	background: none;
+	border: var(--border-width) solid var(--color-primary);
+	color: var(--color-primary);
+	font-size: var(--font-size-body);
+	cursor: pointer;
+	border-radius: var(--border-radius-sm);
+	padding: var(--space-sm) var(--space-xl);
+	transition:
+		background-color var(--transition-normal),
+		box-shadow var(--transition-normal);
+}
+
+.alarm-overlay-actions button:hover,
+.alarm-overlay-actions button:focus-visible {
+	background-color: var(--color-primary-medium);
+	box-shadow: var(--glow-md);
+}
+
+.alarm-overlay-actions .alarm-dismiss {
+	border-color: var(--color-danger);
+	color: var(--color-danger);
+}
+
+/* ---------- Custom scrollbar (list) ---------- */
+
+/* Firefox */
+.alarm-list {
+	scrollbar-width: thin;
+	scrollbar-color: var(--color-primary) transparent;
+}
+
+/* Webkit (Chrome, Safari, Edge) */
+.alarm-list::-webkit-scrollbar {
+	width: 6px;
+	height: 6px;
+}
+
+.alarm-list::-webkit-scrollbar-track {
+	background: transparent;
+	border-radius: 3px;
+}
+
+.alarm-list::-webkit-scrollbar-thumb {
+	background-color: var(--color-primary);
+	border-radius: 3px;
+	box-shadow: var(--glow-sm);
+}
+
+.alarm-list::-webkit-scrollbar-thumb:hover {
+	background-color: var(--color-primary);
+	box-shadow: var(--glow-md);
+}
+
+.alarm-list::-webkit-scrollbar-corner {
+	background: transparent;
+}
diff --git a/web/src/styles/animations.css b/web/src/styles/animations.css
index 9a0629e..218122d 100644
--- a/web/src/styles/animations.css
+++ b/web/src/styles/animations.css
@@ -52,3 +52,14 @@
 body.timer-finished #clock-container {
 	animation: timer-flash 0.5s ease-in-out 4;
 }
+
+/* Alarm pulse — ringing overlay card glow */
+@keyframes alarm-pulse {
+	0%,
+	100% {
+		box-shadow: 0 0 5px var(--color-primary);
+	}
+	50% {
+		box-shadow: 0 0 24px var(--color-primary);
+	}
+}
diff --git a/web/src/styles/main.css b/web/src/styles/main.css
index d185a67..2084720 100644
--- a/web/src/styles/main.css
+++ b/web/src/styles/main.css
@@ -17,6 +17,7 @@
 /* --- Components --- */
 @import './clock.css';
 @import './timer.css';
+@import './alarm.css';
 
 /* --- Animations --- */
 @import './animations.css';
diff --git a/web/src/styles/responsive.css b/web/src/styles/responsive.css
index db5cb64..d7817ae 100644
--- a/web/src/styles/responsive.css
+++ b/web/src/styles/responsive.css
@@ -20,7 +20,8 @@
 		font-size: var(--font-size-body);
 	}
 
-	.timer-toggle {
+	.timer-toggle,
+	.alarm-toggle {
 		font-size: 1.4em;
 		padding: 3px var(--space-lg);
 	}
@@ -39,15 +40,33 @@
 		padding: 3px var(--space-md);
 	}
 
-	.timer-panel {
+	.timer-panel,
+	.alarm-panel {
 		padding: var(--space-lg) var(--space-xl);
 		max-width: calc(100vw - 24px);
 	}
 
+	.alarm-create {
+		flex-wrap: wrap;
+	}
+
+	.alarm-create input {
+		font-size: var(--font-size-body);
+	}
+
+	.alarm-overlay-time {
+		font-size: 2em;
+	}
+
 	.timer-actions button {
 		font-size: 0.9em;
 		padding: 5px var(--space-xl);
 	}
+
+	.alarm-overlay-actions button {
+		font-size: 0.9em;
+		padding: 5px var(--space-xl);
+	}
 }
 
 /* ---------- Small phone (≤400px) ---------- */
@@ -61,9 +80,19 @@
 		font-size: 0.85em;
 	}
 
-	.timer-panel {
+	.timer-panel,
+	.alarm-panel {
 		padding: var(--space-md) var(--space-lg);
 	}
+
+	.alarm-overlay-actions {
+		flex-direction: column;
+		width: 100%;
+	}
+
+	.alarm-overlay-actions button {
+		width: 100%;
+	}
 }
 
 /* ---------- Landscape on phones (short viewport) ---------- */
@@ -87,11 +116,13 @@
 		margin-top: var(--space-xs);
 	}
 
-	#timer-wrapper {
+	#timer-wrapper,
+	#alarm-wrapper {
 		gap: var(--space-xs);
 	}
 
-	.timer-toggle {
+	.timer-toggle,
+	.alarm-toggle {
 		font-size: 1.1em;
 		padding: var(--space-2xs) var(--space-md);
 	}
@@ -100,12 +131,21 @@
 		font-size: 1.4em;
 	}
 
-	.timer-panel {
+	.timer-panel,
+	.alarm-panel {
 		padding: var(--space-sm) var(--space-lg);
 		gap: var(--space-sm);
 		max-width: calc(100vw - 16px);
 	}
 
+	.alarm-list {
+		max-height: 100px;
+	}
+
+	.alarm-overlay-time {
+		font-size: 1.6em;
+	}
+
 	.timer-controls input[type='number'] {
 		width: 1.8em;
 		font-size: 0.85em;
@@ -121,7 +161,8 @@
 		font-size: 0.9em;
 	}
 
-	.timer-actions button {
+	.timer-actions button,
+	.alarm-overlay-actions button {
 		font-size: 0.8em;
 		padding: var(--space-xs) var(--space-lg);
 	}

From fa74f92a3052c9b1c87b72ba6d047fe6244493c2 Mon Sep 17 00:00:00 2001
From: Hector Alvarez <alvarez.hectorm@outlook.com>
Date: Sun, 13 Sep 2026 13:24:11 -0500
Subject: [PATCH 6/9] docs(readme): document the alarm feature

---
 README.md | 21 +++++++++++++++------
 1 file changed, 15 insertions(+), 6 deletions(-)

diff --git a/README.md b/README.md
index c615427..17c7296 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,6 @@
 # Simple Clock
 
-A clean, dark-themed digital clock with a built-in countdown timer. Built with TypeScript and Vite.
+A clean, dark-themed digital clock with a countdown timer and alarms. Built with TypeScript and Vite.
 
 ## Repository Layout
 
@@ -44,11 +44,16 @@ web/                                    # Application workspace
 │   │   │   ├── clock.ui.ts             # Clock DOM wiring — initClock()
 │   │   │   ├── clock-registry.ts       # Multi-clock scaffold (not wired up yet)
 │   │   │   └── index.ts                # Feature public surface
-│   │   └── timer/
-│   │       ├── timer.core.ts           # Pure state machine (no DOM)
-│   │       ├── timer.presets.ts        # Preset helpers (pure)
-│   │       ├── timer.storage.ts        # localStorage adapter
-│   │       ├── timer.ui.ts             # Timer DOM wiring — initTimer()
+│   │   ├── timer/
+│   │   │   ├── timer.core.ts           # Pure state machine (no DOM)
+│   │   │   ├── timer.presets.ts        # Preset helpers (pure)
+│   │   │   ├── timer.storage.ts        # localStorage adapter
+│   │   │   ├── timer.ui.ts             # Timer DOM wiring — initTimer()
+│   │   │   └── index.ts                # Feature public surface
+│   │   └── alarm/
+│   │       ├── alarm.core.ts           # Pure alarm state machine (no DOM)
+│   │       ├── alarm.storage.ts        # localStorage adapter
+│   │       ├── alarm.ui.ts             # Alarm DOM wiring — initAlarm()
 │   │       └── index.ts                # Feature public surface
 │   ├── shared/
 │   │   ├── time/format.ts              # Time formatting (pure functions)
@@ -65,10 +70,12 @@ web/                                    # Application workspace
 │       ├── base.css                    # Reset / body
 │       ├── clock.css                   # Clock styles
 │       ├── timer.css                   # Timer styles
+│       ├── alarm.css                   # Alarm styles
 │       ├── animations.css              # Keyframes
 │       └── responsive.css              # Media queries
 ├── tests/
 │   └── unit/                           # Mirrors src/ one-to-one
+│       ├── features/alarm/alarm.core.test.ts
 │       ├── features/clock/clock.core.test.ts
 │       ├── features/timer/timer.core.test.ts
 │       └── shared/time/format.test.ts
@@ -115,6 +122,8 @@ Tests cover:
 - Time formatting (12h, AM/PM, midnight, noon, duration)
 - Clock tick logic (title updates, timezone display, dev marker, timer-active guard)
 - Timer state machine (start/pause/reset/tick transitions, input validation, presets)
+- Alarm state machine (create/enable/delete, due-tick window, snooze, one-shot firing,
+  persistence parsing, input validation)
 
 ## Container stacks
 

From 16f8d7e387c76f5633efe9f5f041dfdbc7405bee Mon Sep 17 00:00:00 2001
From: Hector Alvarez <alvarez.hectorm@outlook.com>
Date: Sun, 13 Sep 2026 13:24:27 -0500
Subject: [PATCH 7/9] chore(cline): add maintenance policy to memory bank rule

---
 .clinerules/03-memory-bank.md | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/.clinerules/03-memory-bank.md b/.clinerules/03-memory-bank.md
index d47170e..208231e 100644
--- a/.clinerules/03-memory-bank.md
+++ b/.clinerules/03-memory-bank.md
@@ -28,4 +28,13 @@ Additional files may be added under `memory-bank/` for complex features, integra
 3. On explicit "update memory bank" request (review ALL files)
 4. When context needs clarification to proceed
 
+## Maintenance
+
+The memory bank is a cache, not a journal. On every update:
+
+- Prune `activeContext.md` aggressively — completed items are deleted, not archived. It must stay readable in seconds.
+- Graduate stable, lasting knowledge into `systemPatterns.md` / `techContext.md`; session noise dies in `activeContext.md`.
+- Treat edits to `projectbrief.md` as exceptional — it changes rarely.
+- Delete entries that no longer hold; stale context is worse than no context.
+
 The Memory Bank is the only link to previous work. Maintain it with precision — effectiveness depends entirely on its accuracy.
\ No newline at end of file

From 561ea5f19ea2c6dd1e7324cc9e1b174027ae37b4 Mon Sep 17 00:00:00 2001
From: Hector Alvarez <alvarez.hectorm@outlook.com>
Date: Sun, 13 Sep 2026 16:11:10 -0500
Subject: [PATCH 8/9] docs(stories): record US-001 QA pass and code review
 approval

---
 docs/stories/US-001-multiple-alarms.md | 11 ++++++-----
 1 file changed, 6 insertions(+), 5 deletions(-)

diff --git a/docs/stories/US-001-multiple-alarms.md b/docs/stories/US-001-multiple-alarms.md
index c733d8b..1a1e420 100644
--- a/docs/stories/US-001-multiple-alarms.md
+++ b/docs/stories/US-001-multiple-alarms.md
@@ -2,7 +2,7 @@
 
 **Story ID:** US-001  
 **Epic:** Alarms  
-**Status:** Draft
+**Status:** QA (QA assessment passed; code review approved — pending merge)
 
 ---
 
@@ -89,8 +89,9 @@ _These criteria define "Done." Every criterion must be verified by QA._
 
 ## 5. Definition of Done Checklist
 
-- [ ] Code implemented strictly according to ACs.
+- [x] Code implemented strictly according to ACs.
 
-- [ ] Unit/Integration tests written and passing.
-- [ ] QA assessment passed.
-- [ ] Code Review approved.
+- [x] Unit/Integration tests written and passing (135 total, incl. 40 alarm tests
+      plus adversarial reload/snooze/boundary checks run during QA assessment).
+- [x] QA assessment passed.
+- [x] Code Review approved.

From 223d41f13b507eb2386a9705c1a03d33792da202 Mon Sep 17 00:00:00 2001
From: Hector Alvarez <alvarez.hectorm@outlook.com>
Date: Sun, 13 Sep 2026 16:15:58 -0500
Subject: [PATCH 9/9] docs(tasks): stand up backlog and sprint tracking

---
 tasks/backlog.md | 46 ++++++++++++++++++++++++++++++++++++++++++++++
 tasks/sprint.md  | 41 +++++++++++++++++++++++++++++++++++++++++
 2 files changed, 87 insertions(+)
 create mode 100644 tasks/backlog.md
 create mode 100644 tasks/sprint.md

diff --git a/tasks/backlog.md b/tasks/backlog.md
new file mode 100644
index 0000000..7bcd252
--- /dev/null
+++ b/tasks/backlog.md
@@ -0,0 +1,46 @@
+# Backlog
+
+Prioritized candidate work. Items here are NOT committed to a sprint until moved
+to `tasks/sprint.md`. New items enter via the Product Owner (user story) and are
+sized/sequenced by the SDM.
+
+## Epic: Alarms
+
+### US-002 — Recurring (daily-repeat) alarms
+- Status: Candidate — needs a user story from the Product Owner before work.
+- Source: MVP cut recorded in US-001 ("Out of Scope": daily-repeat alarms).
+- Priority: High — most requested natural follow-up to US-001.
+- Dependencies: none (builds directly on the US-001 alarm core).
+
+### US-003 — Alarm ergonomics follow-ups
+- Status: Candidate — small items culled from the US-001 code review (non-blocking).
+- Contents:
+  1. Extract the FLIP panel-open helper duplicated between timer.ui.ts and
+     alarm.ui.ts into `shared/dom/` (refactor; both features keep behavior).
+  2. Guard the document-level outside-click handler so the alarm panel does
+     not close while the ringing overlay is up.
+  3. Overlay focus management: move keyboard focus into the ring overlay
+     when ringing starts (a11y pass).
+- Priority: Medium — bundle with the next alarm-adjacent story or the
+  multi-clock epic to avoid a dedicated PR.
+
+## Epic: Multi-clock
+
+### US-004 — Wire up the multi-clock registry
+- Status: Candidate — `clock-registry.ts` scaffold exists but is not wired.
+- Source: README ("Multi-clock scaffold — not wired up yet"); recommended as
+  the next major epic after the Alarms epic.
+- Dependencies: US-003 (shared FLIP helper) would reduce duplicated wiring.
+- Note: likely requires an ADR if the page layout/composition root changes
+  meaningfully, plus a Product Owner story defining what a "clock" is.
+
+## Housekeeping (backlog, non-story)
+
+- HK-1: README lists `robots.txt`/`sitemap.xml` under `src/public/`; they are
+  build-time generated. One-line docs fix.
+- HK-2: Bump GitHub Actions pinned majors off the deprecated Node 20 runtime
+  (CI warnings observed; low urgency).
+- HK-3: lint-staged "could not find staged files" noise on docs-only commits —
+  verify web/package.json config matches repo-wide staging.
+- HK-4: Memory bank update — capture alarm feature patterns in
+  systemPatterns.md; prune activeContext.md.
diff --git a/tasks/sprint.md b/tasks/sprint.md
new file mode 100644
index 0000000..532b42d
--- /dev/null
+++ b/tasks/sprint.md
@@ -0,0 +1,41 @@
+# Sprint — Current
+
+Sprint window: active (no fixed calendar sprint; pipeline-driven).
+
+## In flight
+
+### US-001 — Multiple Alarms (Epic: Alarms)
+- Status: **COMPLETE — awaiting release approval.**
+- PR #13 (`dev` → `main`): OPEN, MERGEABLE, all 8 CI checks SUCCESS.
+- Story DoD: implementation ✅, tests ✅ (135 passing), QA ✅, code review ✅.
+- Blocker: none technical. **Merge of PR #13 deploys to production
+  automatically** (Release workflow → webhook) — human approval gate, owned by
+  the project owner.
+- Post-merge tasks:
+  1. Verify `https://clock.taylormadetech.net/healthz` (live, `DYNAMIC` — do
+     not judge freshness by the cached homepage; up to 2h edge cache).
+  2. Manual browser check: alarm tone plays (visual overlay is verified;
+     audio cannot be verified in jsdom).
+  3. Story status → Done after production verification.
+
+## Ready (not started)
+
+Nothing yet — next sprint content comes from the backlog once US-001 closes
+and the owner picks the next epic (Alarms follow-ups vs. Multi-clock).
+
+## Dependencies & sequencing
+
+- US-002 (recurring alarms) depends only on US-001 merge — can start any time
+  after, even against `dev` before `main` moves.
+- US-003 (review follow-ups) is independent; best bundled with US-002 or US-004.
+- US-004 (multi-clock) should wait for US-003 item 1 (shared FLIP helper) and
+  needs PO + possibly an ADR.
+
+## Risks
+
+| Risk | Likelihood | Impact | Mitigation |
+|---|---|---|---|
+| PR #13 merge forgotten; work silently stalls | Medium | High (pipeline blocked) | This sprint file; owner decides merge timing explicitly |
+| Two unrelated `chore(cline)` commits ride in PR #13 | Low | Low (cosmetic history) | Owner may strip before merge if desired |
+| Background-tab throttling delays rings up to ~1 min | By design | Low | Documented in-panel; matches story's stated limitation |
+| CI action-runtime deprecation warnings accumulate | Low | Medium later | HK-2 on backlog |