makiolaj/clockula
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: lock the Clockula spec — PLAN, ROADMAP, docs index

Browse Source 
Third floret after Calendula and Agendula: a Material 3 Expressive clock app
(alarms, timers, stopwatch, world clock).

The family thesis doesn't survive contact with a clock — there is no open
provider behind one — so PLAN opens by saying so plainly and relocates the
open-standards commitment to the three places it can actually live: the full
android.provider.AlarmClock intent contract, IANA tzdata, and a documented
JSON backup format.

Locked: four surfaces and no extras in v1, Room + DataStore + JSON export,
maximum alarm reliability including a self-check diagnostics screen, seed
#6B7A5C (completing the family's Calendula→Agendula colour rotation), four
tabs plus a live running-state pill, Codeberg-canonical from commit one, and
floret-kit from day one with core-prefs + core-di extracted up front.

ROADMAP carries M0–M11 as an ordered work queue with per-milestone done
criteria, written to be executed one milestone per loop iteration.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01L94fydiJC37LtxVusNQBDy
This commit is contained in:
Jean-Luc Makiola
2026-09-11 11:27:57 +02:00
co-authored by Claude Opus 5
commit 052c7b177d
3 changed files with 549 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/README.md
+31
View File
@@ -0,0 +1,31 @@
# Clockula — documentation
Clockula is a Material 3 Expressive **clock** app for Android — alarms, timers,
stopwatch and world clock. Third floret of the bloom, after
[Calendula](https://codeberg.org/jlmakiola/calendula) (calendar) and
[Agendula](https://codeberg.org/jlmakiola/agendula) (tasks). See the top-level
[`../README.md`](../README.md) for the pitch.
Unlike its siblings, Clockula owns its storage — there is no open provider behind
a clock. What that costs and how the open-standards commitment is honoured anyway
is the first section of [`PLAN.md`](PLAN.md).
## Index
| Doc | What it covers |
|---|---|
| [`PLAN.md`](PLAN.md) | **The spec.** Thesis, locked decisions, the alarm engine, data model, system interop, identity, pipeline, and how ClockMaster is used. The "why". |
| [`ROADMAP.md`](ROADMAP.md) | **Status and the work queue** — milestones M0–M11 and post-v1. What the build loop works through. |
| [`ARCHITECTURE.md`](ARCHITECTURE.md) | How Clockula is built **today** — layers, the data seam, the alarm engine, DI, build/tooling, manifest. Written from M2 onward. |
| [`RELEASING.md`](RELEASING.md) | How to cut a release. Written at M0 alongside the pipeline. |
| [`PROVENANCE.md`](PROVENANCE.md) | Any third-party code carried in-tree and under what licence. Created only if we actually lift something (`PLAN.md` §11). |
Also: [`../CHANGELOG.md`](../CHANGELOG.md) (Keep a Changelog format; tag sections
feed the release notes).
## How the docs relate
- **PLAN** is the design decisions (stable; the "why").
- **ARCHITECTURE** is the current shape of the code (kept in sync as it grows).
- **ROADMAP** is the moving status layer (updated as milestones land).
- **RELEASING** is the operational runbook.