Rewrite the README as user documentation

The README still described shipped features as planned and had no
installation, configuration, API, or operations documentation. It now
covers the full user surface. The design doc is updated to the plugin
as built: the one-clock time zone decision, the before_save/after_save
sync, issue copy, and the actual test matrix (#19).

Author: dkastl

README.md

@@ -1,31 +1,143 @@
 # redmine_issue_datetime
 
-A Redmine plugin that adds time of day to issue start and due dates,
+A Redmine plugin that adds a time of day to issue start and due dates,
 without changing the Redmine core schema.
 
-Redmine stores `start_date` and `due_date` as plain dates. The ability to
-set a time as well has been requested for a long time
-([redmine.org #5458](https://www.redmine.org/issues/5458)). This plugin
-solves it with parallel storage: times live in a plugin-owned table and
-the date part is mirrored into the core columns, so filters, calendar,
-Gantt, exports, and the REST API keep working exactly as before.
+Redmine stores `start_date` and `due_date` as plain dates. Adding a time
+has been requested for a long time
+([redmine.org #5458](https://www.redmine.org/issues/5458), open since
+2010). This plugin solves it with parallel storage: times live in a
+plugin-owned table, and the date part is mirrored into the core columns.
+Filters, calendar, Gantt, exports, and the REST API keep working exactly
+as before, and an issue without times behaves exactly like stock Redmine.
 
-## Status
+## Features
 
-Early development, no release yet. The core pieces (sidecar storage,
-date mirroring, issue form integration, JSON API) are implemented and
-covered by tests. See [docs/design.md](docs/design.md) for the full
-design document.
-
-## Planned highlights
-
-- Time inputs next to the start and due date fields, with a configurable
-  step (15 minutes by default)
-- Per-tracker enablement; issues without times behave exactly like stock
-  Redmine
-- Times journalized in the issue history
+- Time inputs next to the start and due date fields on the issue form,
+  with a configurable step (15 minutes by default) and an "All day"
+  toggle
+- Enabled per tracker; issues of other trackers are untouched
+- Time changes appear in the issue history (journal)
+- Optional "Start time" / "Due time" columns on the issue list
+- A "Date and time" custom field format, offered alongside the built-in
+  "Date" format
 - JSON API for reading and writing times, including a bulk endpoint for
   external consumers such as schedulers and sync clients
+- Consistency check and repair tasks for operators
+
+## Requirements
+
+- Redmine 6.0 or later (tested against Redmine 6.1 and 7.0, on Ruby 3.4
+  and 4.0)
+- No other plugins and no GIS stack required
+
+## Installation
+
+```bash
+cd /path/to/redmine/plugins
+git clone https://github.com/gtt-project/redmine_issue_datetime.git
+cd /path/to/redmine
+bundle exec rake redmine:plugins:migrate RAILS_ENV=production
+```
+
+Restart Redmine, then open
+**Administration → Plugins → Redmine Issue Datetime → Configure** and
+enable the trackers that should have time fields.
+
+To uninstall, revert the migration and remove the plugin directory:
+
+```bash
+bundle exec rake redmine:plugins:migrate NAME=redmine_issue_datetime VERSION=0 RAILS_ENV=production
+rm -rf plugins/redmine_issue_datetime
+```
+
+Uninstalling drops only the plugin's own table; core issue data is not
+affected.
+
+## Configuration
+
+| Setting | Meaning | Default |
+| --- | --- | --- |
+| Enabled for trackers | Trackers whose issues get time fields | none |
+| Time input step | Interval of the time picker; typed values are snapped to it | 15 min |
+| Reference time zone | The clock all times are entered and shown in (see below) | application default |
+
+## How times are shown: one clock for everyone
+
+Times are stored as instants (UTC in the database) but always entered
+and displayed in one time zone, the configured reference zone. They are
+deliberately **not** converted to each viewer's personal time zone: for
+work that happens at a physical place, a dispatcher and a worker must
+mean the same wall-clock time by "09:15". The zone is labelled in the UI
+so this is never ambiguous.
+
+The reference zone also decides which date is mirrored into
+`start_date`/`due_date`. Changing it after times have been stored can
+make existing rows inconsistent; run the check task below afterwards.
+
+## Custom field format "Date and time"
+
+The plugin also registers a `datetime` custom field format next to the
+built-in `date` one. Values are stored as naive local timestamps in the
+reference zone (for example `2026-08-03T09:15`) and support filtering and
+grouping. Unlike the start/due times, custom field values are not
+snapped to the step: an arbitrary datetime field may legitimately record
+an off-grid moment. Currently offered for issue custom fields
+([#15](https://github.com/gtt-project/redmine_issue_datetime/issues/15)
+tracks widening the scope).
+
+## REST API
+
+All endpoints are JSON and use Redmine's regular API authentication.
+Reading requires issue visibility; writing requires permission to edit
+issue attributes.
+
+```
+GET    /issues/:issue_id/datetime.json
+PUT    /issues/:issue_id/datetime.json
+DELETE /issues/:issue_id/datetime.json
+GET    /projects/:project_id/issue_datetimes.json?updated_since=<iso8601>
+```
+
+Write timestamps must carry an explicit offset (`Z` or `+09:00`), so a
+request means the same thing regardless of the server's local zone:
+
+```bash
+curl -X PUT -H 'Content-Type: application/json' \
+  -H 'X-Redmine-API-Key: <key>' \
+  -d '{"starts_at": "2026-08-03T09:15:00+09:00", "ends_at": null}' \
+  https://redmine.example.org/issues/123/datetime.json
+```
+
+A timestamp sets both the core date and the time; `null` clears the time
+and keeps the date; omitted keys are left untouched. `DELETE` clears all
+times (back to "all day") and keeps the dates.
+
+## Consistency tasks
+
+The date mirror is maintained by ActiveRecord callbacks. Anything that
+bypasses them (raw SQL, `update_column`, a restored database) can put
+the stored times and the core dates out of step:
+
+```bash
+# Report disagreements; exits non-zero when any are found (cron/monitoring friendly)
+bundle exec rake redmine_issue_datetime:check RAILS_ENV=production
+
+# Repair them: the core date is re-derived from the stored timestamp
+bundle exec rake redmine_issue_datetime:repair RAILS_ENV=production
+```
+
+## Development
+
+Tests run inside a Redmine checkout, like any Redmine plugin:
+
+```bash
+bundle exec rails test plugins/redmine_issue_datetime/test RAILS_ENV=test
+```
+
+CI covers Redmine 6.1/7.0 on Ruby 3.4/4.0 with PostgreSQL, plus a
+`zeitwerk:check` eager-loading gate. See
+[docs/design.md](docs/design.md) for the design document.
 
 ## Related projects
 

docs/design.md

@@ -1,6 +1,6 @@
 # redmine_issue_datetime: Design Document
 
-Status: Draft for review
+Status: As built (kept in step with the implementation)
 Scope: Standalone Redmine plugin adding time of day to issue start and due dates
 
 ## 1. Problem
@@ -61,10 +61,14 @@ Rules:
   default for every existing and new issue.
 - `starts_at` / `ends_at` may each be null independently (time set only on
   one side).
-- Times are stored in UTC and rendered in the user's Redmine time zone
-  preference. Since core dates are zone-naive, the mirror into
-  `start_date` / `due_date` uses a per-instance reference zone (plugin
-  setting, default: the application default time zone).
+- Times are stored in UTC but always entered and displayed in one
+  per-instance reference zone (plugin setting, default: the application
+  default time zone), with a visible zone label. They are deliberately
+  not converted to each viewer's personal time zone: for work that
+  happens at a physical place, everyone must mean the same wall-clock
+  time by "09:15". The same reference zone anchors the date mirror into
+  `start_date` / `due_date`, so the date a user sees always matches the
+  time they typed.
 - Duration is intentionally not stored here. Redmine's existing
   `estimated_hours` already expresses effort/service duration and stays
   the single source for that.
@@ -76,8 +80,12 @@ Rules:
 - Setting a time creates or updates the sidecar row and mirrors the date
   part into the core column in the same save.
 - Changing only the core date (via stock UI, bulk edit, or API) keeps the
-  time of day and shifts the timestamp to the new date. The sync runs in an
-  `after_save` patch on `Issue` (module prepend, no alias chaining).
+  time of day and shifts the timestamp to the new date. The sync is an
+  `ActiveSupport::Concern` included into `Issue` and runs in two steps:
+  the new timestamps are computed and journalized in `before_save`
+  (journal details must exist before core's own `create_journal`
+  after_save callback writes the journal), and persisted to the sidecar
+  row in `after_save`.
 - Clearing the date clears the corresponding timestamp.
 - Clearing the time (back to "all day") deletes or nulls the sidecar value;
   the core date stays.
@@ -89,8 +97,11 @@ keys), so issue history reflects them like any other field change.
 
 ### Copy / move
 
-Issue copy duplicates the sidecar row. This must be explicit
-(`after copy` hook); it does not come for free.
+Issue copy duplicates the times: the copy keeps the same times of day,
+re-anchored on its (possibly changed) dates. This is explicit in the
+sync callback (a copied issue inherits the original's sidecar row as its
+source); it does not come for free from Redmine's copy, which only
+carries attributes.
 
 ### Parent/child
 
@@ -157,10 +168,12 @@ code updates dates without going through ActiveRecord callbacks (raw SQL,
 ## 9. Testing
 
 - Model tests for the mirror invariant in both directions, null handling,
-  time zone edges (date boundary around midnight in non-UTC zones).
-- Controller tests for the API endpoints and permissions.
-- Integration test for form submit through the hook.
-- Target matrix: current Redmine 6.x and RedMica, PostgreSQL and MySQL.
+  time zone edges (date boundary around midnight in non-UTC zones), issue
+  copy, and the drift check/repair.
+- API tests for the endpoints, parsing rules, and permissions (including
+  the note-only-permission case, which must not be allowed to write).
+- CI matrix: Redmine 6.1 (Ruby 3.4) and 7.0 (Ruby 3.4 and 4.0) on
+  PostgreSQL, plus a `zeitwerk:check` eager-loading gate.
 
 ## 10. Delivery