@squirreljetpack/im-dynamic 0.3.0 → 0.3.1

package/CHANGELOG.md

@@ -1,321 +1,23 @@
-## [0.3.0] - 2026-11-03
-
-### 🚀 Features
-
-- Sync creates are driven by `sync_schema.json`: a push that creates an
-  entity carries every field of its kind, so no peer ever builds a
-  half-filled row.
-- The outbox coalesces per cell (`UNIQUE(entity_id, field)`): repeated
-  offline edits to the same field update the queued row in place instead
-  of queueing a chain of writes.
-- The server pre-validates each create (existence cell, required fields
-  and links, timestamp) and reports the failures as per-event verdicts
-  with a typed reason. `target_deleted` is new; a reason this build does
-  not know deserializes as `unknown` instead of failing the response.
-- Deleting a mood keeps the tracker entries logged against it: their
-  `mood` link is cleared and the rows stay, matching the sync cascade.
-  Deleting a task still deletes its completions.
-- `im :sync` offers to re-create content another device deleted from a
-  snapshot taken before the row was removed, and asks once per entity
-  after every push of the run.
-
-### 🐛 Bug Fixes
-
-- `sync_once` lands the outbox, the domain rows, the cursor and the
-  verdict reconciliation in one transaction, so an interrupted push
-  cannot leave a half-applied batch.
-- The existence cell folds monotonically: a stale create can no longer
-  resurrect an entity another device deleted, and a create the server
-  rejected leaves no cells behind in the log.
-- `clock_ahead` restamps the device forward against the server clock and
-  resets its last emitted stamp, so later edits from that device keep
-  winning last-writer-wins.
-- Editing a mood's body or a tracker's mood link queues only the cells
-  that changed.
-- Pull is bounded and reports `has_more`, so a long log pages instead of
-  arriving in one response.
-
-### 💥 Breaking changes
-
-- `tracker.time` is required: a create without it is rejected as
-  `shape`.
-- `_sync_events` carries its coalescing uniqueness in the table
-  definition and no longer stores `image`. Databases from earlier builds
-  are not migrated: delete the database file and sign in to rebuild from
-  the log.
-
-## [0.2.11] - 2026-11-02
-
-### 🚀 Features
-
-- `im :c mm` opens the matchmaker render config (`mm.toml`) in
-  `$VISUAL`/`$EDITOR`, alongside the config, `moods` and `colors` targets.
-- Log entries (moods, trackers, todo completions) store the UTC offset and
-  the location string (the system IANA name, or empty when it has none) in
-  effect where they were written. The today view groups log entities by their
-  recorded **civil day** and renders their recorded civil time; ordering stays
-  absolute. Mood/tracker previews show the differing location and wall-clock
-  shift under the timestamp; task previews append the same parts inline to
-  `last:` as `prev:`.
-- Tracker interval anchors are unzoned civil datetimes resolved in the current
-  local zone. Replace-mode slots and cumulative sums assign foreign logs by
-  their recorded wall clock, so an entry stays in the same civil slot when
-  viewed from another zone.
-- Replace-mode null trackers store their absolute seconds from the interval
-  start in the entry payload; color and the strict when-zone use that stored
-  position.
-- Explicit todo completions join the today view on their civil completion day.
-  `B` now merges explicitly completed scheduled tasks on that day instead of on
-  an overlapping availability window.
-
-### 💥 Breaking changes
-
-- Sync vocabulary is version 4: `tz_offset` (required int) and `location`
-  (required text; empty when the system has no name) on mood, tracker and
-  completion. Pre-v4 creates lack the
-  location or offset and are intentionally unbuildable; reset the sync log
-  when replaying one.
-- Databases from earlier builds are not migrated. Delete the database file and
-  sign in to rebuild from the log. Tracker configs must drop the `Z`/numeric
-  offset from interval anchors.
-
-## [0.2.10] - 2026-10-31
-
-### 🚀 Features
-
-- `im :sync --reset` asks before it discards local changes the server never
-  received; `--force` skips the question, and an idle database rebuilds without
-  a prompt.
-- Sync is versioned end to end. A cursor names the log it indexes, and the
-  client and worker exchange the envelope `protocol` and cell `version` on
-  every round: a cursor minted by another log, one past the end of this log, or
-  a peer that speaks another version is refused instead of merging unrelated
-  histories or skipping what it cannot read. `im :sync status` prints the log,
-  cursor version and both protocol numbers.
-
-### 🐛 Bug Fixes
-
-- A task's start time is required, and an edit can no longer clear the column
-  that defines a task's kind. A scheduled task's window opens at that start, a
-  recurring task's intervals tile from it, and a oneshot is stamped with it at
-  creation; clearing the duration or interval that goes with it is refused
-  instead of silently reclassifying the task (and with it its availability,
-  view membership and completion scope).
-- An end time is cleared by a blank answer (or `never`/`none`) in both the
-  create and edit menus; a blank previously kept the old value.
-
-### 💥 Breaking changes
-
-- A task create must carry `start_time`, so the cell vocabulary is now version
-  2. A peer that speaks another version refuses the round rather than skip the
-  cell, and v0.2.9 and earlier clients send no version at all: redeploy the
-  worker and upgrade the client together.
-- Databases from earlier builds are not migrated: a schema change means
-  deleting the database file, then signing in to rebuild from the log.
-
-
-## [0.2.9] - 2026-10-30
-
-### 🚀 Features
-
-- The recurring creation menu can edit start time, interval, and available
-  duration, and the scheduled menu start time and available duration, so a
-  value typed on the way in is corrected without cancelling. A duration at or
-  beyond the interval means unbounded availability (`always`) instead of a
-  validation error, editing the interval re-clamps the duration, and a blank
-  answer keeps a scheduled task's current duration.
-
-### 🐛 Bug Fixes
-
-- Today view: completed-on rows merge per interval instead of per task, so a
-  completion logged in an interval without an availability window — before a
-  moved-forward `start_time`, say — is no longer dropped when the task also
-  has window rows. Each row's sum, `last:` and time label are scoped to its
-  own interval.
-
-### 💥 Breaking changes
-
-- Utility commands moved under `:tool` (`:tool config|embed|mood|clear`) and
-  account commands under `:sync` (`:sync register|login|status|logout`).
-
-
-## [0.2.8] - 2026-10-30
-
-### 🐛 Bug Fixes
-
-- *(macos)* Link compiler-rt explicitly under fat LTO, fixing a startup
-  segfault in ONNX Runtime environment creation (`im :embed`, `im :color`).
-
-## [0.2.7] - 2026-10-30
-
-### 🚀 Features
-
-- `im :color` without a mood lists every anchor mood of the moods file with
-  a swatch of its color, one per line; `im :color <mood>` keeps the full
-  pipeline diagnostic.
-- Today view: `[today_view] swap_all_and_due_recurring_task_views` trades the
-  `All` and `Due` recurring-task displays. `Due` is anchored at now (earliest
-  window intersecting the horizon, skipping closed windows), and previews are
-  scoped to the row's window instead of sharing the whole day.
-- No phantom availability windows past a recurring task's expiry, and
-  today-view `ends` shows the task's real expiry again.
-
-### 🐛 Bug Fixes
-
-- *(embedding)* Pin the CPU EP on macOS
-
-## [0.2.6] - 2026-10-29
-
-### 🚀 Features (sync)
-
-- `im :auth register|login|status|logout` and `im :sync` (plus
-  `im :sync --reset`) sync a database against a Cloudflare Worker
-  (`sync-server/`): a per-user Durable Object holds the log, D1 the accounts.
-- Concurrent edits merge per field (last write wins) instead of per entity; a
-  push breaks at entity boundaries, so a create carries all of its cells.
-- Deletes are terminal and slot losers become tombstones, so two devices that
-  edit the same field converge instead of duplicating rows.
-- Entity ids are UUIDv7, so a row created on any device is unique without a
-  round trip; local `short_id`s stay a per-device projection.
-- The server address comes from `[sync] server` in the client config
-  (`IM_SYNC_URL` overrides it for one command); the account is stored apart
-  from the sync state, so `im :sync --reset` does not sign you out.
-- A database from an older version (INTEGER keys) is copied aside and
-  recreated empty instead of being written with the wrong key type; an
-  unreadable file is quarantined the same way.
-
-### 💥 Breaking changes (tracker rework)
-
-- `min`/`max` renamed to `low`/`high`; `kind = "number"` renamed to
-  `"integer"`; new `kind = "duration"` (duration-string values stored as
-  seconds, displayed like `6m 30s`).
-- `interval` now takes a table `{ anchor, span, cumulative = false }`
-- Value and bound forms are strict per kind/mode: `float` takes plain
-  numbers, `integer` plain whole numbers, `duration` duration strings only,
-  `null` no value at all; `low`/`high` mirror the value form of the kind
-  (duration strings for `duration` and `null`+replace, whole numbers for
-  `text` and `null`+cumulative). Invalid bound forms are dropped with a
-  warning at config load.
-- New `strict` setting gates logging/updating: numeric kinds gate the value
-  against the inclusive `low`..`high` span (inverted bounds gate the span
-  between them), `text` gates the message length in characters, `null`
-  trackers gate *when* they may be logged (the circular `low`/`high` time
-  offset zone; requires both bounds, replace mode only).
-- `null` trackers require an interval (dropped with a warning otherwise) and
-  store score 0 in every mode — the payload column is unused and today-view
-  rows show no payload (the count lives in the grid, the timestamp in the
-  entry's own time). Negative durations are rejected at log time.
-- Replace-mode insertion is one shared strategy for all kinds: a CLI log in
-  an occupied slot drops the slot's previous rows (including rows logged
-  with a mood — the mood row itself survives) and inserts the new one.
-- The TUI update action on a `null` row only moves its timestamp to now,
-  within its current interval slot (cross-slot moves are rejected, the
-  strict zone still applies); on value-bearing kinds it runs the same strict
-  pipeline as the CLI.
-- `:db doctor` prunes any nonzero row of a `null` tracker (all modes).
-
-## [0.2.5] - 2026-08-14
-
-### 🚀 Features
-
-- Editor no longer opens automatically for interactive flows.
-- Config adjustments
-- Body templates
-- Adjust today view filters
-- Config.tasks.overdue_color + badge::task_label_color
-- Today-view preview polish + overdue date column + task children
-- Link actions in the today view (Ctrl+L)
-- Improve jiff-english robustness
-- TUI migration to matchmaker
-
-## [0.2.4] - 2026-08-07
-
-### 🚀 Features
-
-- Db :doctor
-- Jiff-english
-- Duration trackers
-- Tui interaction for trackers
-
-## [Unreleased]
-
-### 🚀 Features
-
-- `[badges]` config section: journal badge (glyph and/or color — a bare
-  char, a color string, or `{ badge = '·', color = "red" }`; color defaults
-  to `Reset`), plus `tracker` and `mood` glyph overrides for the today
-  view and previews. `journal_badge` moved from `[today_view]`.
-- Today view task filter: `TasksFilter` (`none` / `all` / `overdue` /
-  `pending` / `horizon`) replaces `config.today_view.include_overdue` as
-  `initial_tasks_filter`, bound to the view variant — `All` uses the
-  configured filter, `A` pins `Horizon`, `B` pins `Overdue`; `none` hides
-  the whole task section (journal-only view). Undated
-  oneshots created before today are no longer dropped from the `All`
-  variant. `CycleShow` renamed `CycleFilter`; TUI headers label the
-  variants per app (`all | journal | tasks` in the today view,
-  `all | oneshot | other` in the tasks view).
-
-- Renamed: the binary is now `im` (previously `feeling`), and the logged
-  mood entries are consistently called moods — DB schema (`mood` table,
-  `tracker.mood`, `task_moods.mood_id`), code identifiers, CLI usage
-  strings, and docs. Data paths moved to `~/.config/im` / `im.db`;
-  existing `feeling` databases and config dirs are not migrated and must
-  be moved/deleted by hand.
-- Task↔mood links: `im <mood> -<short id>` records a link; the task
-  preview shows a `moods:` field with colored badges
-- `:db` command replaces `:prune` — `:db prune` (old behavior) and
-  `:db backfill` (persist missing mood embeddings/scores)
-- `:db doctor` — checks tracker entries against their configured kinds and
-  prunes entries whose storage class no longer matches (orphaned tracker
-  types and stale nonzero time-marker entries included), after an
-  interactive confirm
-- Tracker intervals are calendar-aware (`interval = ["2020-01-01 00:00", "1 day"]`)
-- New `null` tracker kind: valueless timestamp markers with time-of-day
-  coloring (e.g. sleep start) or per-interval counting
-
-### 🐛 Bug Fixes
-
-- Recurring-task and tracker intervals are calendar-based (jiff): DST and
-  variable month lengths no longer drift interval boundaries
-- Interval storage switched from seconds to packed jiff spans
-
-## [0.2.3] - 2026-08-07
-
-### 🐛 Bug Fixes
-
-- Reorganize parse, fix overflow
-
-## [0.2.2] - 2026-08-07
-
-### 🚀 Features
-
-- Show name of attached parent during interactive task creation
-
-## [0.2.1] - 2026-08-06
-
-- Release pipeline updates
-- misc
-
-## [0.2.0] - 2026-08-06
-
-### 🚀 Features
-
-- Nomic embedder, ort runtime
-- Reorganize views
-- Reorganize config
-
-### 💼 Other
-
-- CliOpts flag counts threaded into handlers
-- ColorAxesSettings flattened into MoodConfig; :color verbose axes dump
-- Scheduled task syntax — ':' description, '@' duration markers
-- Lock invalid-timestamp behavior with regression tests
-- Task creation confirmation polish
-- Cliclack intro for task flows; prefill fields logged
-- 'feeling @<date>' — today view anchored to arbitrary days
-- Grid titles + verbose gating; text-tracker entry timestamps
-- Shared Enter-action across both TUIs
-
-## [0.1.0] - 2026-08-01
-
-Initial commit
+## [0.3.1] - 2026-11-07
+
+### 🚀 Features
+
+- `im -V` / `im --version` prints the version.
+- Task creation uses `+`: `im +`, `im + <name>`, `im +<ref> <name>`,
+  `im + %`, and `im + @`; recurring names require the `:<name>` marker.
+- Trackers, at most one task reference, and task updates can be freely mixed
+  in one entry, and `--quiet` works as a long flag.
+- Sessions show a countdown chosen by `[session] countdown` (`timer`, `bar`,
+  `dots`, `percent`, `minimal`); `bar` is the default.
+- Text trackers take a configurable badge color
+  (`badges.default_text_tracker_color`, `dark_grey` by default) instead of
+  inheriting the darkest bin of the default ramp.
+- New `notify` crate and CLI: cross-platform toasts and dialogs with bundled
+  `bell`, `bowl` and `chime` sounds played through rodio.
+- `im :tool datetime [expr]` resolves a date expression and prints it in a
+  chosen format. `--format` accepts presets (`civil`, `utc`, `short`, `unix`,
+  `iso`, `date`, `time`, `dmy`, `mdy`), a time zone (IANA name, unique case-insensitive
+  fragment, or fixed offset such as `+08:00`), or a custom `strftime`
+  pattern. A resolved zone reports its name and offset on stderr unless
+  quiet.
+- Bundled mood palette variants: earth, nordic, jewel, bloom, and pastel.

package/README.md

@@ -2,52 +2,118 @@
 
 `im` is a CLI tool for recording all the small moments, feelings, thoughts and setbacks and accomplishments that make up your day[^1].
 
-```shell
-# record moods and notes
-im playing chess against stockfish and im winning  # mood
-im confused . why did i lose?                      # mood + note
-im . turns out i was playing antichess             # note
-
-im worried about school tomorrow
-im sad that my dog ate my bones
-im sorry that my cat ate my dog
-
-im abe on the next level
-im abe rockin over that base treble
-im aswing it this way
-im aswing it that-a-way
-
-# a trailing . opens your editor for writing the note
-im terrified that someone will see me writing this down .
-
-# add a task
-
-# build habits with recurring tasks
-
-# schedule future events
-
-# show today's agenda
-im @due | cat
-
-# log custom trackers
-im full -food 7
-im going to bed -sleep -acc finished blog post
-im still up -sleep
-im still up -sleep
-
-# visualize your progress
-im :
-
-im :month pet_cat cat_food_spend wins
+```console
+# --- record moods and notes ---
+
+> im worried about school tomorrow         # mood
+> im sad . that my dog ate my bones        # mood with note
+> im . and my cat just ate my dog          # journal entry (pure note)
+
+# --- create tasks ---
+
+> im +                                     # create a task (interactive)
+┌  Create oneshot task
+│
+◇  Task name:
+│  recover bones
+│
+◇  Edit fields:
+│  Times to complete
+│
+◇  Times to complete:
+│  10
+│
+◇  Edit fields:
+│  Finish
+│
+└  Created task #1: recover bones
+
+> im +bones defeat cat @tomorrow noon      # create a subtask (under the last task)
+
+# --- log habits, events and trends ---
+
+> im going to bed first                    # (think before you act)
+> im -sleep                                # log sleep time
+> im -sleep . still up                     # update logged time
+> im a boneless sleepless wretch . \       # (keep up with mental health by 
+> im not ready for tomorrow                # being honest with your feelings)
+> im -sheep 1                              # log a sheep
+> im -sheep 1                              # log another sheep
+> im -sheep 1                              # continue to log sheep
+> im -sheep 1                              # btw: this is a different tracker than the
+>                                          # first, it accumulates entries in an interval.
+>                                          # There 5 types in all. Additionally, specifying whether a tracker has an interval, has bounds, is strict, or is cumulative also changes its behavior. The first tracker can be found in the default configuration file, defined as a null tracker with a bounded interval, while the second can be assumed to be a standard integer tracker.
+> im -sleep .. zzZzz
+
+# --- check agendas & complete tasks ---
+
+> im ready for a new day!
+> im @due | cat                            # give the cat its due (displays tasks due today)
+23:59   ○       defeat cat
+
+> im alive but in pain +cat                # log mood + complete task
+> im become +bones .. destroyer of cat     # update task
+> im +bones 9                              # collect bones (complete task)
+
+> im happy I found all of my bones :)
+  bash: syntax error near unexpected token `)'
+
+> im .                                     # write note in $EDITOR (a trailing . opens it)
+---
+happy i found all of my bones
+10 on my fingers and 10 on my toes :)
+---
+
+> im ...                                   # (the No. of dots can be used to select from configured templates)
+---
+%% Template #3 %%
+that's all of them right?
+---
+  
+> im -thought oh no .                      # text tracker entry
+---
+I got Reese's Puffs in my bowl,
+Now my days on cruise control,
+I got Reese's Puffs in my bowl 
+and just like that Im on a roll, 
+[REDACTED],[REDACTED],[REDACTED],[REDACTED]
+---
+
+# --- set goals ---
+
+> im + %1 day :regrow bones =1             # Create a recurring task with a (exceedable) target
+> im @186 days from now :return to school  # Schedule future events
+> im + shop: bone meal, bonebons, Skele-Gro, 99% milk # Shopping list
+
+> im                                       # Check today's journal
+[UNDER CONSTRUCTION]
+
+# --- visualize your success with a grid --- 
+
+> im :                                        # (the dots are colored according to the aggregate mood of your entries from that day)
+◯  ●  ●  ◯  ●  ●
+
+> im :month bones                             # recurring task progress can also be graphed
+●  ●  ●  ●  ◯  ●  ●
+●  ●  ◯  ●  ◯  ◯  ●                                
+●  ●  ●  ●  ●  ●  ●
+●  ●  ◯  ●  ●  ●
+
+> im :month cats_defeated                     # (5 cats were harmed in the making of this transcript)
+◯  ◯  ◯  ◯  ●  ◯  ◯
+◯  ◯  ●  ◯  ●  ●  ◯                                   
+◯  ◯  ◯  ◯  ◯  ◯  ◯
+◯  ◯  ●  ◯  ◯  ◯
 
 # reflect and repeat
-im still alive . i think
+
+im still alive . im glad
 ```
 
 ## Features
 
 - Log moods and journal entries in simple, natural syntax.
-  - Today view: show a ordered summary of all that you have logged and planned today -- an interactive, auto-generated daily note. 
+  - Today view: show a ordered summary of all that you have logged and planned today -- an interactive, auto-collated daily note. 
 - Grid view: Display your mood, task and tracker histories as dots.
   - Moods are colored by how much they match to various emotions or topics you have configured.
   - Change the topics, timespans, and filters, and watch as interesting patterns emerge.
@@ -58,10 +124,9 @@ im still alive . i think
 
 ## Gallery
 
-![image-20260814134534039](.README.assets/image-20260814134534039.png)
-
+![08-grid-view-mood](.README.assets/08-grid-view-mood.png)
 
-<img src="https://raw.githubusercontent.com/Squirreljetpack/im/main/.README.assets/image-20260814134849943.png" alt="month" style="width:200px;"/>
+![today-view-tui-v1](.README.assets/today-view-tui-v1.png)
 
 ## Usage
 
@@ -71,41 +136,44 @@ im — immediate mood, journal, and task tracker
 
 Usage:
   im <mood> [. [body]]                           log a mood (with an optional body)
-  im %<duration>                                 start a timed session
-  im [-<tracker> [value]]... [mood]              add one or more custom tracker records
-                                                        (optionally attached to a mood)
-
-  im ! [name] [@<time>]                          create a task (interactive without a name)
-  im ! %[interval] [[:]name]                   create a recurring task (interactive)
-  im ! @[time] [:<name>] [%<duration>]         scheduled a task (interactive if partial)
+  im [-<tracker> [value]]..                      add one or more custom tracker records
+  im <mood> [+task] [-trackers..]                log a mood linked with an existing task
+                                                        or new tracker records
+  im %<duration> [purpose..]                     start a timed session
+                                                        (trackers, task & body supported)
+
+  im +                                           create a task
+  im +[parent] <name> [@<time>]                  create a task (non-interactive)
+  im + %[interval] [:<name>]                     create a recurring task (interactive)
+  im + @[time] [:<name>] [%<duration>]           schedule a task (interactive if partial)
   im +[task] [count]                             edit or update a task by its reference
-                                                        (see `im -vh`)
+                                                        (see `im -vh` for reference)
 
 Views:
   im @[date]                                     today view
   im @due[:t|:w]                                 due view
                                                         (today / tomorrow / this week)
   im @[:o|:O]                                    pending tasks
+                                                        (all / oneshot / recurring&scheduled)
   im @done[:o|:O]                                completed tasks
-                                                        (all / oneshot / recurring+scheduled)
+                                                        (all / oneshot / recurring&scheduled)
 
 Trackers and grids:
+  im -                                           browse trackers
   im :[week|month|year] [ids]                    dot-sequence tracker grid
                                                         ids: <tracker> or @<recurring name>
                                                         period defaults to "week"
 
 Other:
-  im :tool embed|mood|clear|..                   (see `im :tool --help`)
-  im :tool config | :c [moods|colors|mm]         open the config in $VISUAL / $EDITOR
-  im -                                           browse trackers
-  im :db prune|backfill|doctor                   database utilities
-
+  im :c [moods|colors|mm]                        open the config in $VISUAL / $EDITOR
+  im :tool db|mood|clear|..                      (see `im :tool --help`)
   im :sync [register|login|status|logout]        setup/authenticate/run sync 
 
 
 Flags:
   im -q | -v <command>                           quiet / verbose; flags go first
   im --help | -h                                 show this help (-v applies)
+  im --version | -V                              show version
 ```
 <!-- HELP_END -->
 
@@ -143,6 +211,18 @@ The default locations are in order:
   - tasks: oneshot, recurring, or scheduled.
   - trackers: defined in your configuration.
 
+
+
+##### Moods
+
+The most basic use of `im` for a kind of offhand journaling where you logging any moods that come to you throughout the day, such as `im happy` or `im cold`, or thoughts such as `im . maybe i should put on some pants`. They are collected in the [Today view](#views) together with other task and tracker entries from the day, and im collates them into a interactive daily journal.
+
+Also, every mood is assigned a color, by determining its weighted semantic alignment to a set of configured _mood anchors_ (color, mood pairs), yielding pretty, meaningful dots on the interface and in the grid view[^4] that provide users with a sense of pride and accomplishment.
+
+Finally, `im %<duration>` starts a Pomodoro session -- idk why. Personally, I find the Pomodoro method a depressing concept. Anyways, start a session, link it to a tracker or task if you want, and when time is up it will prompt you about how it went; don't answer if you don't feel like it. If you just want to create timed notifications, that's available through `im :tool notify`.
+
+[^4]: `im :[week|month|year]`
+
 ##### Trackers
 
 Trackers are defined in your configuration (`im :tool config`); each `[tracker.<name>]`
@@ -150,19 +230,55 @@ section is logged through `im -<name> <value>` (no value for `null` trackers):
 
 - Kinds: `text`, `integer`, `float`, `duration` (strings like `6m 30s`), `null` (timestamp/count markers — requires an interval).
 - `interval = { anchor = "2026-01-01T00:00:00", span = "1 day" }` bins
-  entries into calendar slots. The anchor is an unzoned civil datetime (no `Z`
-  or numeric offset) resolved in your current local zone. By default, a new log
-  in a slot replaces the slot's previous entry; `interval.cumulative = true`
-  keeps every log and the slot's grid dot shows the aggregate. Logs record the
-  UTC offset and location string (the system IANA name, or empty) they were
-  written in, so they stay on their recorded civil day and interval slot when
-  viewed from another zone.
+  entries into calendar slots. The anchor is an unzoned civil datetime resolved
+  in your current local zone. By default, a new log in a slot replaces the slot's previous entry;
+  `interval.cumulative = true` keeps every log and the slot's grid dot shows the aggregate.
+  Logs record the UTC offset and location string they were written in, so that although tracker intervals shift with your zone's offset (keeping the civil time of their availability fixed), logs stay in the same interval slot.
+
+
+
+##### Tasks
+
+The three types of tasks share an underlying data-type, distinguished only by the presence of specific fields. _Recurring_ tasks have an interval, _scheduled_ tasks have a duration but no interval, and _oneshot_ tasks have neither.
+
+- The interval of recurrence is a calendar-aware span (i.e. 1 day or 1 week) anchored at an absolute `start_time` [^3].
+- Scheduled tasks are surfaced on such views as the Today or Due views when they are upcoming, and are completed automatically once their availability window passes. They can also be completed or cancelled early.
+- Oneshot tasks and recurring tasks can both specify a (exceedable) target count.
+- Tasks carry fields such as priority, parent tasks, due dates (for oneshot tasks), & task body etc. They can be specified (or edited) at creation or afterwards, through an interactive menu-style CLI prompt flow.
+
+
+
+##### Views
+
+The app includes 3 [TUI](https://en.wikipedia.org/wiki/Text-based_user_interface)s:
+
+- The _Today view_ (`im`), which aggregates tasks, trackers and mood/journal entries to provide a itinery + recap of the current horizon (Today, Today + Tomorrow, This Week) -- a kind of live journal. It can be filtered to just events or upcoming due tasks.
+- The _Tasks view_ (`im @`), which lists *(drum roll)* all the tasks. It can be filtered to just oneshots, or just recurring/scheduled, or to future/past/completed/incomplete etc.
+- The _Tracker view_ (`im -`), from where you can select a tracker type and log an entry for it.
+
+For a comprehensive SPEC of the rules which determine which entities make it into a specific view, see the [docs](./docs/VIEWS.md).
+
+
+
+##### Sync
+
+`im` stores your data in a local sqlite db. But it also supports cross-device sync by way of a central server that maintains an event log. Updates are per-field conflicts are resolved via LWW, meaning if two edits are made on the same field and afterwards synced, the one whose recorded time *as measured on-device* is later is agreed upon as the field's value. Such conflicts are surfaced in the output when running `im: sync` but *never prompt and thus erase data*. The one exception is *deletes*: deletes are final, meaning that *any* edit to a field made after a deletion of the source has been recorded in the log is ignored. For this reason, when a client contains a field update which would be dropped by pulling this event, they are prompted with the option to *resurrect* the entity as it currently exists in their local database as a safeguard.
+
+To enable syncing, run `im :sync register` on Device A, `im :sync login` on Device B, then `im :sync` on one or both devices. Syncing does not run automatically.
+
+
 
 ## FAQ
 
 ### Why is the binary size so large?
 
-`im` bundles a quant of `nomic-ai/nomic-embed-text-v1.5` to categorize your entries. This was the most effective, reasonably sized approach tested out of several options. The size is a bit abnormal, but was pleasantly surprised with how much better it worked compared to my other attempts. If you have any interesting uses for an embedding model that `im` can help with, `im` open to them!
+`im` bundles a quant of `nomic-ai/nomic-embed-text-v1.5` to categorize your entries. This was the most effective, reasonably sized approach tested out of several options. The size is a bit abnormal, but was pleasantly surprised with how much better it worked compared to my other attempts.
+
+If you are particularly idle, it can be a source of amusement or annoyance depending on your temperament. For example, `im :tool mood` scores `im a consummate wretch` with: `humble: 0.6668, vengeful: 0.2732, disgusted: 0.0281, smitten: 0.0175, frustrated: 0.0144`, while `im a little teapot` gets: `regression weights (rescaled) : hungry: 0.5459, nostalgic: 0.2902, thoughtful: 0.0736, smitten: 0.0490, purposeful: 0.0412`. So yeah, the tiny LM has some pretty good intuition into emotional psychology I'd say (also, the saliency scores are `0.9946` vs `0.0079` so it's wise to that trick too).
+
+
+
+If you have any interesting uses for an embedding model that `im` can help with, `im` open to them!
 
 ### What does im stand for?
 
@@ -171,6 +287,10 @@ What it stands for is immaterial[^2].
 ### How can I contribute?
 Open to suggestions. Helping implement more filters, or a sensible configurable spec for exporting to markdown would be helpful. Documentation, always.
 
+
+
+
+
 ## See also
 
 - https://github.com/qiz-li/im
@@ -184,4 +304,5 @@ Open to suggestions. Helping implement more filters, or a sensible configurable
     - rationalize bad decisions
     - realize that you don't actually have any thoughts interesting enough to write down.
 
-[^2]: important, immense, immaculate, importune, imagine all the people .. immolated♫
+[^2]: important, immense, immaculate, importune, imagine all the people .. immolated♫
+[^3]: This differs from trackers, whose intervals shift to follow your timezone offset: while recurring tasks with intervals in the units of days will be robust to DST, changing time-zones will likely cause their availability windows to shift in time of day. 

package/npm-shrinkwrap.json

@@ -18,7 +18,7 @@
       },
       "hasInstallScript": true,
       "name": "@squirreljetpack/im-dynamic",
-      "version": "0.3.0"
+      "version": "0.3.1"
     },
     "node_modules/detect-libc": {
       "engines": {
@@ -47,5 +47,5 @@
     }
   },
   "requires": true,
-  "version": "0.3.0"
+  "version": "0.3.1"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "artifactDownloadUrls": [
-    "https://github.com/Squirreljetpack/im/releases/download/v0.3.0"
+    "https://github.com/Squirreljetpack/im/releases/download/v0.3.1"
   ],
   "bin": {
     "im-dynamic": "run-im-dynamic.js"
@@ -87,7 +87,7 @@
       "zipExt": ".tar.xz"
     }
   },
-  "version": "0.3.0",
+  "version": "0.3.1",
   "volta": {
     "node": "18.14.1",
     "npm": "9.5.0"