TaskNotes rc.19: tasknotes.task rc.6 and the TaskNotes settings record

README.md

@@ -196,6 +196,29 @@ hidden. A customised task type whose lock records no origin is preserved, and
 because it still implements the replaced contract the upgrade is blocked for
 review rather than merged against a guessed starter.
 
+## TaskNotes settings record
+
+rc.19 provides `tasknotes.task` 0.3.0-rc.6, `tasknotes.settings` 1.0.0 and the
+generic `mdbase.app-settings` 1.0.0 (copied byte for byte from mdbase Reader, so
+both apps install the same contract). rc.6 moves app behaviour out of the task
+binding: NLP triggers, templating, archive moves, time tracking, checkbox
+resets on recurrence, the link write format, and per-status `next_status`,
+`exclude_from_cycle`, `auto_archive` and `auto_archive_delay_minutes`. TaskNotes
+keeps them in one record, `_settings/dev.tasknotes.md`, of the seeded
+`tasknotes-settings` type (unique on `app`). The pack seeds the type only; the
+record is written by TaskNotes, which reads each setting from the record, then
+from an rc.5 binding that still holds it, then its default.
+
+The rc.6 contract is installed at `_contracts/tasknotes.task/0.3.0-rc.6.md`.
+The rc.5 contract stays managed at `_contracts/tasknotes.task.md`, not
+provided, so task types that still implement it (edited types the pack
+preserves, and types the TaskNotes plugin wrote) stay valid until TaskNotes
+upgrades them. Starter revision 6 (type v5) is revision 5 with the moved
+settings removed and the contract version raised; it lists revisions 5 to 1 as
+baselines, and rc.18 is hidden. A collection that edited its status
+definitions (for example their colours) conflicts on that list and the
+upgrade is blocked for review; TaskNotes upgrades such a type itself.
+
 Starter files are named by revision (`types/tasknotes-task/<revision>.md`); a
 revision that does not change the task data keeps the type `version`, so
 collections already at that version upgrade without a version conflict.

contracts/mdbase.app-settings/1.0.0.md

@@ -0,0 +1,55 @@
+---
+kind: mdbase.contract
+contract_type: record
+id: mdbase.app-settings
+version: 1.0.0
+name: App settings
+description: One record per app holding the policy that app's clients honour in this collection.
+record_schema:
+  dialect: json-schema-2020-12
+  ref: ../../schemas/mdbase.app-settings/1.0.0.schema.json
+---
+
+# App settings
+
+An app settings record holds values that every client of one app honours in this
+collection, such as how new files are named. The values change client behaviour,
+never what another record means.
+
+## Location and identity
+
+A collection-scope record lives at `_settings/<app>.md`, where `<app>` is the
+record's `app` field. Clients read it by that path, without a query. Each
+implementing type declares `collection.unique` on `app` with `scope: type`, so a
+collection holds at most one collection-scope record per app.
+
+The record's `type` field names the app's own settings type, not a shared value.
+Generic tools find every settings record through this contract.
+
+## Reserved fields
+
+- `app`: the app id.
+- `scope`: `collection`, or `user` for one person's overrides.
+- `user`: a link to an `mdbase.person` record, present only when `scope` is
+  `user`.
+- `settings_version`: the version of the app's settings schema that last wrote
+  the record.
+
+Every other frontmatter field belongs to the app and is described by the app's
+own settings contract. The body is free Markdown for people; apps never parse it.
+
+## Client behaviour
+
+- A missing record means every setting has its default. Clients never create the
+  record on read.
+- A missing or invalid field takes its default; valid fields are used as
+  written. The record is not rewritten until someone saves.
+- A save creates the record at its fixed path the first time, and otherwise
+  patches only the fields it changes, guarded by the record's revision.
+- A client that finds a `settings_version` newer than it understands treats the
+  settings as read-only and uses them as written.
+
+## Authority
+
+This artifact is passive. A settings record grants nothing and must never hold
+secrets: anyone who can read or write records can read or edit it.

contracts/tasknotes.settings/1.0.0.md

@@ -0,0 +1,48 @@
+---
+kind: mdbase.contract
+contract_type: record
+id: tasknotes.settings
+version: 1.0.0
+name: TaskNotes settings
+description: Collection-wide TaskNotes behaviour, such as templates, archive moves and status cycling.
+record_schema:
+  dialect: json-schema-2020-12
+  ref: ../../schemas/tasknotes.settings/1.0.0.schema.json
+---
+
+# TaskNotes settings
+
+The collection's settings record for TaskNotes, at `_settings/dev.tasknotes.md`.
+It also implements `mdbase.app-settings`, whose reserved fields (`app`, `scope`,
+`settings_version`) it shares.
+
+These settings change what TaskNotes clients do, never what a task record
+means: that stays in the `tasknotes.task` binding of each task type.
+`tasknotes.task` 0.3.0-rc.6 moved them here from the binding. A client reads
+each setting from this record, then from an earlier binding that still holds
+it, then uses its default, so a collection whose task type is still on rc.5
+keeps its behaviour until it is upgraded.
+
+## Fields
+
+- `nlp_triggers`: natural-language capture triggers. Without it, each client
+  uses its own defaults.
+- `template_enabled`, `template_path`, `occurrence_template_enabled`,
+  `occurrence_template_path`, `template_failure_mode`,
+  `template_unknown_variable_policy`: body templates for new tasks and
+  materialized occurrences.
+- `move_on_archive`, `archive_folder`: whether archiving moves the file, and
+  where to.
+- `auto_stop_time_tracking_on_complete`: stop a running timer on completion.
+- `reset_body_checkboxes_on_recurrence`: uncheck body checkboxes when a
+  recurring task advances.
+- `link_write_format`: `wikilink` or `markdown` for links written to task
+  frontmatter.
+- `status_behavior`: per status value, `next_status`, `exclude_from_cycle`,
+  `auto_archive` and `auto_archive_delay_minutes`. A status without an entry
+  has no next status and no auto-archive (5 minute delay), and is out of the
+  cycle exactly when it is a skipped status.
+
+## Authority
+
+This artifact is passive and grants nothing.