pyworklog 0.5.0__tar.gz → 0.6.0__tar.gz

{pyworklog-0.5.0 → pyworklog-0.6.0}/CHANGELOG.md

@@ -6,6 +6,222 @@ The autogenerated `Commits since vX.Y.Z` block on each GitHub Release captures e
 
 ## [Unreleased]
 
+## [0.6.0] - 2026-06-07
+
+### Added
+- **`wl show` annotates a recurring schedule with its next occurrence.** The `schedule:` line
+  now reads e.g. `recur weekly:Mon,Fri (next 2026-06-08 Mon); on 2026-06-20, 2026-06-25` — the
+  `(next …)` is computed by the same `_sched_fires` predicate `wl day` / `agenda` use, so it's
+  exactly when the task will reappear (the actionable bit, the way TaskWarrior / calendars surface
+  a recurrence's next due). One-off-only schedules list their dates as before (no `(next …)`).
+- **`wl help` — an info-style topic browser (DESIGN §25).** `wl help` shows an index of
+  topics by category; `wl help <topic>` renders a fuller explanation of a command / concept /
+  parameter / workflow than `<command> -h` gives, with a "See also" footer linking related
+  topics. Topics are **repo-managed Markdown docs** under `src/worklog/help/<lang>/<topic>.md`
+  (shipped in the wheel, **i18n-ready** — language resolves `--lang` > `$WORKLOG_LANG` >
+  `$LANG` > `en`, falling back to `en` per-topic). Seeded with index + node / status /
+  priority / para / planning / add / day; `--help` stays the quick per-command reference and
+  now points into `wl help` for the deeper read (a doc-integrity test enforces no dangling
+  see-also links). Runs without a DB (safe before `wl init`). Each command's `--help`
+  **auto-gains a `More: wl help <cmd>` pointer** when a topic doc exists for it (no per-command
+  epilog edits), `wl help <topic>` is **tab-completable** (fish/bash/zsh), and the bare-`wl`
+  splash now points to it. Topic set expanded to 18 — added log / tag / sched / done / defer /
+  tree / ls / find / link / meta / prop alongside the seed concepts/guides.
+- **`wl node` entity group — `node add / ls / show / edit / rm / reparent`.** The start of
+  reshaping the command surface to the metric-style `<entity> <verb>` form (WL#486). The
+  high-frequency `add` / `ls` / `show` are reachable both as `wl node <verb>` and as the
+  existing top-level shortcut (`wl add` == `wl node add`), one handler each, args defined
+  once so the two forms can't drift. Three new primitives close node's CRUD to the metric
+  bar: `node edit <id>` (edit a node's own fields — title / priority / kind / body /
+  scheduled / deadline; rejects an empty title), `node reparent <id> <parent|none|0>`
+  (change the real `parent_id`, with cycle / self-parent guards — WL#485), and `node rm <id>`
+  (soft-delete a node + subtree, reversible). Every current command keeps working unchanged.
+- **`wl prop` and `wl clock` entity groups (WL#486), filling two CRUD gaps.** `wl prop
+  set / ls / rm` — `set` keeps its top-level shortcut and `rm` gains the new shortcut
+  `wl unset <id> <key>` (you can finally *remove* a custom prop, not just overwrite it).
+  `wl clock ls / edit / rm` — list / fix (edit start-end, recomputing the duration) /
+  remove a time interval; intervals are still created by `wl start` / `stop` / `spent`.
+- **`wl link` entity group + a default-verb mechanism for name-collision entities (WL#486).**
+  `wl link add / ls / rm` — `link add` keeps the top-level shortcut, `rm` gains the
+  `wl unlink <id> <doc>` shortcut, and `link ls` is a new primitive (list a node's links).
+  Because the entity name `link` is itself the everyday verb, the parser learned a
+  default-verb rule: when the token after `link` isn't one of its verbs it's taken as an id,
+  so `wl link 42 doc` still means `wl link add 42 doc` while `wl link ls / rm / -h` route to
+  the group. Leaf ids are always integers, so id-vs-verb is unambiguous. This unblocks the
+  same treatment for the other collision entities (`log` / `tag` / `sched`).
+- **`wl tag` reshaped into a metric-style group (WL#486), the second default-verb entity.**
+  `wl tag add / ls / rm`. `add` is the default verb, so the everyday `wl tag <id> +work
+  -planned` keeps working unchanged (full +add / -remove / bare-add / empty-list grammar);
+  `tag ls` lists, `tag rm` removes by plain name. `tag` joins `link` in the default-verb
+  table — `wl tag 42 +work` → `wl tag add 42 +work`, while `wl tag ls / rm / -h` route to
+  the group; id-first disambiguation means `wl tag 1 ls` adds the tag `ls` whereas `wl tag
+  ls 1` lists. Tag update stays atomic (no `edit` verb).
+- **`wl log` reshaped into a metric-style group (WL#486), the third default-verb entity.**
+  `wl log add / ls / edit / rm`. `add` is the default verb, so the everyday `wl log <id>
+  "body"` keeps working unchanged (auto TODO→DOING, `--date` / `--time` / `--metric` /
+  `--keep-status`). `log edit` and `log rm` reuse the `relog` / `unlog` handlers — both keep
+  their top-level shortcuts — and `log ls <id>` is a new node-scoped lister (the full
+  filterable / windowed stream view stays at `wl logs`). id-first disambiguation: `wl log 1
+  ls` adds a log bodied `ls`, whereas `wl log ls 1` lists.
+- **`wl sched` reshaped into a metric-style group (WL#486), the fourth (and final collision)
+  default-verb entity.** `wl sched add / ls / rm`. `add` is the default verb, so `wl sched
+  <id> <when>` / `wl sched <id> --recur …` / `wl sched <id> --clear` all keep working
+  unchanged (full when / `--recur` / `--clear` / list-when-empty grammar). `sched ls` lists,
+  `sched rm` clears; `wl defer` (status=LATER + rough hint) stays its own command. With this,
+  every collision entity (`link` / `tag` / `log` / `sched`) is reshaped.
+- **`date_meta` reshaped into a clean `wl date` group (WL#486) — completing the reshape.**
+  `wl date set / ls / rm / import`. Unlike the collision entities this is a *clean* group
+  (no default verb — `date` doesn't collide with any leaf); `wl dateinfo` stays as the
+  polymorphic everyday shortcut (sets when given a label, lists when not, `--clear` /
+  `--import` variants) over the same table. **With this, every entity now has a full
+  `<entity> <verb>` group.**
+- **`wl meta` group for the history-preserving typed-log fields (WL#486).** `wl meta set / ls
+  / rm <node> <field>` for `goal` / `summary` / `overview` / `top5` (each edit appends a typed
+  log, latest = current — distinct from props, which are static single-value). `wl set` / `wl
+  unset` are now *key-routed* shortcuts: a meta key routes to `wl meta set` / `wl meta rm`,
+  any other key to `wl prop set` / `wl prop rm` (the same way `wl add` is `wl node add`). `wl
+  goal` / `wl recap` stay as the today-auto shortcuts. Behavior of `wl set <node>
+  overview/top5/goal/summary` is unchanged — it's just documented and now has a canonical
+  group form. (Known limitation: a prop literally named goal/summary/overview/top5 can't be
+  set via `wl set` since the key routes to meta — a future `--prop`/`--meta` disambiguator.)
+- **`wl alias add / ls / rm`** manages `~/.config/worklog/aliases.ini` (e.g. `wl alias add d
+  day` → `wl d` == `wl day`). The target must be a real command and an alias can't shadow one;
+  changes take effect on the next invocation. Alias names are now case-preserving.
+- **Newcomer-friendlier `--help`.** Top-level `wl -h` now opens with a one-line what-it-is +
+  a `wl init → add → log → day` quickstart, replaces the unreadable 50-command brace blob in
+  the usage line with `<command>`, and ends with a **commands-grouped-by-purpose** map (track
+  work / time / see it / organize / plan-reflect / bulk-setup), a **Concepts** glossary
+  (node / log / tag / prop / meta / metric / link / sched / clock in one line each), and a
+  "good to know" tips block (id forms, fuzzy dates, planned/DOING behavior, completion,
+  shortcuts, **PARA** area▸project▸task). `wl add -h` gained help text on every option
+  (`title`, `-p` = A/B/C priority, …), a PARA organizing explainer, and leads with simple
+  relatable examples instead of work-jargon. Every user-facing arg now has help text (no more
+  blank options). `wl day -h` gained an (explicitly optional) "Time levels" section explaining
+  the year▸quarter▸month▸week▸day skeleton + a suggested planning cadence; `wl goal -h` / `wl
+  recap -h` now show the morning→evening→weekly→monthly planning rhythm — and their stale
+  pre-reshape wording ("prop 'goal'", "summary_at") was corrected (they're history-preserving
+  meta fields, not props).
+- **Single-letter short flags for the daily-workflow args (WL#487):** `-d` for `--date`
+  (`wl log 1 "…" -d yesterday`, also on `logs` / `recap` / `unlog`) and `-n` for `--note`
+  (`wl tick 1 -n "6 pullups"`, also on `wait` / `metric`).
+- **Help cross-references the shortcut ↔ canonical pair both ways** (now a documented
+  convention, DESIGN §1.2): e.g. `wl node -h` lists its shortcuts, `wl node add -h` names
+  the `wl add` shortcut, `wl add -h` names the canonical `wl node add` (same for set ↔
+  prop set, unset ↔ prop rm).
+
+### Changed
+- **`wl -h` / `wl <command> -h` now colorize to match `wl help`.** argparse's `--help` output
+  is post-processed into the same 3-tier scheme: dim-grey body prose, bright-cyan references
+  (option flags, `wl <command>` invocations, subcommand-choice names, inline `code`), bold
+  bright-white section headings + the `usage:` label, and status/priority markers (`[x]`/`[/]`/
+  `[#A]`…) in their real `wl ls` colors. It's a no-op when color is off (non-TTY, `--color never`,
+  `$NO_COLOR`, mono theme), and runs *after* argparse's column math so the zero-width ANSI never
+  shifts alignment. `--help` fires before the console is built, so color/theme are re-resolved
+  from `--color`/`--theme`/env at format time. Epilogs/descriptions may use the **same restricted
+  Markdown as `wl help` topics** (`` `code` `` / `**bold**` / `*italic*` / `[text](url)`) for
+  explicit styling — markers render with color on and are *stripped* with color off (so piped
+  `-h` stays clean). The top-level `wl -h` now styles the Concepts glossary names and the
+  Commands-by-purpose lists this way (command names like `set`/`log`/`show` collide with English,
+  so explicit backticks beat any heuristic). Per-command `help=` one-line summaries stay plain
+  text — argparse line-wraps them, which would split a Markdown span across lines.
+- **`wl help <topic>` slimming of `--help` epilogs.** With the topic browser holding the full
+  detail, verbose per-command epilogs are trimmed to a summary + key examples + a `wl help <cmd>`
+  pointer; anything cut is first verified present in (or added to) the matching topic. Covered
+  ~23 commands (add / ls / day / logs / sched / tree / node / summary / log / tag / show / active /
+  link / unset / projects / changes / find / defer / set / prop / import / apply); multi-line
+  Differences / Shortcuts / format-spec blocks moved into topics, concise one-line notes kept.
+- **`--help` now wraps the raw epilog/description with a hanging indent + caps its width.**
+  Previously the hand-formatted epilog (Concepts glossary, Commands-by-purpose) hard-wrapped at
+  the terminal edge with no indent on a narrow window. A `_WlHelpFormatter` (subclass of
+  `RawDescriptionHelpFormatter`) overrides `_fill_text` to wrap the description/epilog argparse-
+  style — a two-column `label   description` row hangs its continuations under the description
+  column, bullets under their text — measured on *visible* width so a markdown span
+  (`` `wl day` ``) is never split across the boundary. Option/choice help is left to argparse's
+  own `_split_lines` (we never re-wrap it), and the formatter caps the wrap width on wide
+  terminals (`render.HELP_MAX_WIDTH`, 100 cols) so help stays readable; everything shares the one
+  `render.help_width()`, so columns line up.
+- **Removals are now reversible — soft-delete tombstones instead of `DELETE`, foreign keys
+  off (WL#501).** Every table gained a `deleted_at` tombstone; deleting a tag / link / log /
+  node sets it instead of removing the row, and reads filter it out, so an accidental
+  `wl unlog` / `wl tag -x` / `wl apply '- #id'` is recoverable (clear `deleted_at`). FK
+  enforcement is turned off and the app maintains consistency (app-level cascade), decoupling
+  the tables — preparation for multi-end / CRDT sync (#57). Re-adding a removed tag / link
+  revives its tombstone (a new `upsert` replaces `INSERT OR IGNORE/REPLACE`). Migration 0008
+  is additive (nullable column, no data touched); 0009 makes the `v_node_path` view
+  tombstone-aware. Internally this also moved ~19 single-table reads still on raw SQL onto
+  the `db_table` helper, so they filter tombstones for free.
+
+### Fixed
+- **Help/timeline width handling, hardened via a GPT-5.5 / Kimi / Codex cross-model review.**
+  (1) Width is now measured in real display columns everywhere (one `east_asian_width`-based
+  `_cw`, shared by `_display_width` / `_truncate_log_body` / the help wrapper's `_vis`): CJK = 2,
+  but the narrow `·`/`→`/`…`/`—` separators = 1 (a crude non-ASCII→2 rule wrongly doubled them).
+  (2) The help wrapper hard-breaks a spaceless over-long token (CJK run / long URL) by character.
+  (3) `--theme mono` no longer leaks `\x1b[3m` — `*italic*` / links route through the palette.
+  (4) `_truncate_log_body`'s available-width floor was `max(20, …)`, which *forced* the `wl show`
+  timeline line to overflow on any terminal < ~61 cols (prefix ~39 + 20); floored at 1 now, so it
+  fits narrow terminals (body degrades to `…`). (5) The help wrapper falls back to a base-indent
+  wrap when the hanging (description) column would be wider than a very narrow terminal.
+- **`wl show` timeline log lines no longer overflow to a second line.** The one-line truncation
+  budgeted against a hardcoded indent guess (32) while the real prefix (`    <ts>  #L<id>  ✎ log  `)
+  is ~39 cols, so a long body spilled past the terminal width by exactly the prefix gap. It now
+  measures the actual prefix via `_display_width`. (Audited the other `_truncate_log_body` callers
+  — `wl logs --by-task` / `--id` / `wl log ls` already budget correctly.)
+- **`wl help <topic>` rendered a small Markdown subset + stopped crashing on literal brackets.**
+  A dependency-free renderer now styles ATX headings, ```fenced``` code, and inline `**bold**` /
+  `*italic*` / `` `code` `` / `[text](url)` / bare URLs; with color off the markers are stripped.
+  Crucially it escapes literal text first, so topic bodies containing `[ ]` / `[x]` / `[/]` / `#L42`
+  (e.g. `wl help status`) no longer crash rich markup parsing under `--color always`. The supported
+  subset is documented for topic authors in CONTRIBUTING.md. `wl help para` also gained a PARA
+  concept intro + a link to Tiago Forte's canonical article. The renderer now uses a 3-tier
+  contrast scheme (Claude-Code-style): dim-grey body prose, bright-cyan references (inline
+  `code`, `[links]`, See-also entries, the index's topic names, and `wl <subcommand>`
+  invocations — colored as commands only when the verb is real), and bold bright-white
+  headings/`**strong**`. Status markers in backticks (`` `[x]` `` etc.) render in their real
+  `wl ls` / `day` status colors, so the `wl help status` legend matches the rest of wl. The topic
+  title is now underlined (bold bright-white) instead of spending a whole row on a `───` rule, and
+  the index's topic-name column is padded to the longest name + 2 so a long id (`print-completion`)
+  keeps a gap before its description instead of running into it.
+- **`wl tree --root <month>` / `wl focus <month>` now show tasks fuzzy-pinned at that time
+  node** (#436). A task pinned at `@2026-06` (via `scheduled_date`) hangs under its project,
+  not the month node, so the tree/focus parent_id walk missed it — which made a "what's
+  already scheduled this month?" check come up empty and a duplicate get created. They now
+  surface such pins (the filtered `--tag`/`--kind` path too); #413 had fixed only day nodes.
+- **Shell completion for default-verb group leaf args.** When a top-level command became a
+  metric-style group (`log` / `sched`), its everyday args moved under the `add` subparser,
+  which the fish / bash / zsh completion walk skipped — so `wl sched <id> --recur` lost its
+  suggestions and `wl log <id> --date` its date completion. The generators now descend into
+  a default-verb group's leaf (`_default_verb_leaf`) and emit those completions under the
+  bare group name.
+- **`parent_id` cycle safety (FK-off hardening).** With foreign-key enforcement off
+  (WL#501), `parent_id` integrity isn't DB-guaranteed and the bulk `wl apply` / `wl import`
+  update path set a parent with only an existence check (the interactive `wl reparent` had a
+  cycle guard; the bulk path didn't) — a cycle would then make the ancestor/descendant
+  walks loop forever and hang the CLI. The bulk path now refuses a self/descendant parent
+  (parity with `reparent`), and `_collect_descendants` / `_ancestors_chain` are visited-set
+  guarded so any pre-existing cycle degrades gracefully instead of hanging.
+- **`wl link` strips an outer `[[ ]]` wrapper on input (WL#462).** `[[X]]` and `X` now store
+  identically (no more `[[[[X]]]]` double-wrap), re-linking either form dedups via the natural
+  key, and `wl unlink`/`apply -link` match regardless of wrapping. All link writes go through a
+  single normalizing chokepoint (`_upsert_link`/`_delete_link`). (Dedup + `unlink` already
+  existed; this closes the last part of #462.)
+- **`wl day` drops the redundant per-row `«planned·not-done»` hint under the default `--by
+  plan` (WL#500).** The `▸ planned` group header + the `[ ]` status marker already say it; the
+  hint stays under `--by project`/`priority`, and the footer count is unchanged.
+
+### Internal
+- **Command taxonomy documented (DESIGN §1.1):** every command is a primitive entity CRUD
+  (the `metric add/ls/edit/rm` subsystem is the template), a composite helper, or a read-only
+  view; with the per-entity CRUD matrix and remaining gaps (`prop` unset, `clock` edit/rm).
+- **Further raw-SQL reduction (DESIGN G3).** `_insert_log` returns the new log id (dropping 6
+  `SELECT last_insert_rowid()` follow-ups — also more correct than the connection-global
+  lastrowid), and 5 more single-table reads/writes moved onto `db_table`. Remaining raw SQL is
+  all genuinely complex (JOIN / time-window / aggregate / OR-LIKE / conditional / dynamic).
+- **Raw-SQL 余债 cleared (WL#526):** `_get_or_make`'s 4 time-skeleton lookups (single-table
+  `LIKE`/`=` probes) and `_node_clock_min`'s all-time clock-SUM + log-span-DISTINCT moved onto
+  `db_table` (`cols=` carries the aggregate). Only the *day-scoped* aggregates (SUM/DISTINCT +
+  `local_day_sql` in WHERE) stay raw — genuinely complex.
+
 ## [0.5.0] — 2026-06-05
 
 ### Added

{pyworklog-0.5.0 → pyworklog-0.6.0}/CONTRIBUTING.md

@@ -48,6 +48,47 @@ wl --db /tmp/scratch.db add "experiment"
 
 `AGENTS.md` is the operating guide for AI coding agents (Claude Code, Cursor, Aider). Skim it once even if you code by hand; it concentrates the hard-rules into one page.
 
+## Writing `wl help` topics
+
+`wl help <topic>` is an info-style browser over Markdown docs in `src/worklog/help/<lang>/<topic>.md` (architecture: DESIGN §25). `en` is the source language and the per-topic fallback; other languages mirror the same topic ids. To add or edit a topic, just add/edit a `.md` file — the loader, the index, shell completion, and each command's `--help` pointer pick it up automatically.
+
+**File format** — minimal frontmatter between `---` fences, then a Markdown body:
+
+```
+---
+title: tag — labels on a node          # "<name> — <one-line description>"; the index shows the part after the dash
+category: command                       # one of: guide | concept | command | param
+see_also: node, day, ls, add            # comma/space-separated topic ids
+---
+<body>
+```
+
+- The **topic id is the filename stem** (`tag.md` → `wl help tag`). For a command topic, name it after the command so its `--help` auto-gains a `More: wl help <cmd>` pointer (commands without a same-named topic fall back to a family topic via `_HELP_FAMILY` in `cli.py`).
+- Every `see_also` id **must resolve to a real topic** — a test (`test_all_see_also_targets_resolve`) fails on a dangling link, since a "See also" is meant to be runnable as `wl help <x>`.
+
+**Supported Markdown is a small, fixed subset** (rendered by a dependency-free renderer in `commands/help.py` — no Markdown/`rich.markdown` engine):
+
+| Syntax | Renders as |
+|---|---|
+| `# Heading` … `###### ` | a styled heading (the `#`s are stripped) |
+| ` ```fence ` … ` ``` ` | a code block (dimmed; the fence lines are dropped; no inline parsing inside) |
+| `**bold**` | bold |
+| `*italic*` | italic |
+| `` `code` `` | inline code (cyan) |
+| `[text](url)` | underlined text + the url |
+| `http://…` / `https://…` (bare) | underlined link |
+
+Everything else is printed verbatim, so **lay the body out as readable plain text** (it must read fine with color off, where the markers above are simply stripped). Notes:
+
+- **`_italic_` is intentionally NOT supported** — bare underscores are too common in identifiers (`node_id`, `closed_at`, `$WORKLOG_LANG`). Use `*italic*`.
+- Literal brackets (`[ ]`, `[x]`, `[#A]`, `#L42`) are safe — the renderer escapes them; don't avoid them.
+- Preview both ways before committing: `wl help <topic>` and `wl help <topic> --color always`.
+
+**The same subset also styles `--help`** — `argparse` epilogs and `description=` strings are colorized by `colorize_help` (in `commands/help.py`) into the identical scheme, so you may use `` `code` `` / `**bold**` / `*italic*` / `[text](url)` there too. Two rules:
+
+- **Markdown only in `epilog=` / `description=`** (which argparse prints raw/un-wrapped). **Never in a per-command `help=` one-line summary** — argparse line-wraps those, which splits a Markdown span across lines (the marker then leaks instead of styling). Keep `help=` plain prose; `wl <command>` references in it still get colored by the heuristic.
+- A `wl <command>` reference colors itself (the heuristic recognizes real subcommand names) — reserve backticks for the cases the heuristic can't catch: bare command names that collide with English (`` `set` `` / `` `log` `` / `` `show` ``), key=value bits, flags-in-prose.
+
 ## TDD: red → green → refactor
 
 Every change touching behavior follows the [Red-Green-Refactor cycle](https://brennanbrown.github.io/notes/programming/python-tdd/):

{pyworklog-0.5.0 → pyworklog-0.6.0}/DESIGN.md

@@ -41,6 +41,117 @@ worklog deliberately stays **dependency-light and low-abstraction**: runtime is
 - Long flags `--xxx`; short flags only for the highest-frequency ones (`-k` kind / `-p` priority / `-t` tag)
 - Missing node: always `sys.exit(f"✗ ... #{id} not found")` with non-zero exit code
 
+### 1.1 Command taxonomy (primitive CRUD / composite helper / view)
+
+Every command falls into exactly one of three buckets. Knowing which keeps the
+surface coherent and tells you where a new command belongs.
+
+**A. Primitive entity CRUD** — directly create/read/update/delete one underlying
+table row. The **`metric` subsystem is the template**: `metric add / ls / edit / rm`,
+a complete, consistently-named CRUD set. Every entity should reach that completeness;
+naming/behaviour stays uniform across entities. Current state:
+
+| entity | create | read | update | delete |
+|---|---|---|---|---|
+| **metric** | `metric add` | `metric ls` | `metric edit` | `metric rm` |
+| **node** | `node add` | `node ls` / `node show` | `node edit` / `reparent` | `node rm` |
+| **prop** | `prop set` (= `set` w/ a non-meta key) | `prop ls` / `show` | `prop set` | `prop rm` (= `unset`) |
+| **meta** (typed-log fields) | `meta set` (= `set` w/ a meta key; `goal`/`recap` for today) | `meta ls` / `show` | `meta set` (appends; latest = current) | `meta rm` (= `unset` w/ a meta key) |
+| **clock** | `start` / `spent` | `clock ls` / `active` | `clock edit` | `clock rm` |
+| **link** | `link add` (= `link`) | `link ls` / `show` | — (atomic) | `link rm` (= `unlink`) |
+| **log** | `log add` (= `log`) | `log ls` / `logs` / `show` | `log edit` (= `relog`) | `log rm` (= `unlog`) |
+| **sched** | `sched add` (= `sched`) | `sched ls` / `show` | `sched add` / `defer` | `sched rm` (= `sched --clear`) |
+| **tag** | `tag add` (= `tag +x`) | `tag ls` / `show` | — (atomic) | `tag rm` (= `tag -x`) |
+| **date_meta** | `date set` (= `dateinfo`) | `date ls` / `dateinfo` | `date set` | `date rm` (= `dateinfo --clear`); `date import` |
+
+Every entity now has a full metric-style `<entity> <verb>` group. Entities reshaped: **metric**
+(template), **node**, **prop**, **meta**, **clock**, **link**, **tag**, **log**, **sched**, **date** (the `date_meta` table). High-frequency verbs keep a top-level
+shortcut onto the same handler (`wl add` == `wl node add`, `wl unlink` == `wl link rm`,
+`wl relog` == `wl log edit`, `wl unlog` == `wl log rm`, `wl dateinfo` == polymorphic over
+`wl date set/ls/rm/import`), args defined once via a shared adder so the two forms can't
+drift. `clock` intervals are CREATED by the composite helpers (`start`/`stop`/`spent`).
+Removal is soft-delete (reversible tombstone, § soft-delete).
+
+**`wl set` / `wl unset` are *key-routed* shortcuts** (the same way `wl add` is `node add`):
+a meta key (`goal`/`summary`/`overview`/`top5`) routes to `wl meta set` / `wl meta rm`
+(history-preserving typed log); any other key routes to `wl prop set` / `wl prop rm`
+(static single-value UDA prop). So one `set`/`unset` surface fronts two group-set verbs by
+key — `prop` and `meta` are distinct stores (prop = overwrite single-value; meta = append
+typed log, latest = current), but share the everyday `set`/`unset` entry. `wl goal` / `wl
+recap` additionally auto-target today's day node for the goal / summary fields.
+
+> Known limitation: the four meta keys are reserved, so a *prop* literally named
+> `goal`/`summary`/`overview`/`top5` can't be set through `wl set` (the key routes to meta).
+> Acceptable for now (nobody needs a prop with those names); a future fix would be a
+> `--prop`/`--meta` disambiguator flag on `set`, or `wl prop set` (which is unambiguous) as
+> the escape hatch.
+
+**`wl alias add/ls/rm`** manages `~/.config/worklog/aliases.ini` (maps a short name to a
+command, e.g. `wl d` == `wl day`); aliases are wired into the parser at startup, so a change
+takes effect on the next invocation. The target must be a real command and an alias may not
+shadow one.
+
+**Default-verb dispatch (collision entities).** When the group name equals the old leaf
+command (`link` / `tag` / `log` / `sched`), a custom parser (`_WlParser` /
+`_expand_default_verb`) inserts the group's *default verb* when the token after the entity
+isn't a known verb — so the legacy leaf keeps working: `wl link 42 doc` → `wl link add 42
+doc`, `wl tag 42 +work` → `wl tag add 42 +work`, `wl log 42 "body"` → `wl log add 42
+"body"`, `wl sched 42 2026-06-15` → `wl sched add 42 2026-06-15`, while `wl sched ls 42` /
+`wl sched -h` are left alone. The leaf's first positional is always an int id, never a verb
+word, so the test is unambiguous. For `tag` the `add` default verb keeps the full `+add` /
+`-remove` / bare-add / empty-list grammar (`cmd_tag`); `tag ls` / `tag rm` are
+single-purpose convenience verbs. For `log`, `log edit` / `log rm` reuse the `relog` /
+`unlog` handlers (which keep their shortcuts), and `log ls` is a node-scoped lister (the
+full filterable stream view stays at `wl logs`). For `sched`, the `add` default verb keeps
+the full when / `--recur` / `--clear` / list-when-empty grammar (`cmd_sched`); `sched ls`
+lists and `sched rm` clears, while `wl defer` (status=LATER + rough hint) stays its own
+composite command.
+
+A note for the completion generators: a default-verb group's leaf args (`sched`'s
+`--recur` / `when`, `log`'s `--date`) live under the nested `add` subparser, so the
+per-subcommand walk (which skips `_SubParsersAction`) must also descend into the
+default-verb leaf (`_default_verb_leaf`) and emit those completions under the bare group
+condition — otherwise `wl sched <id> --recur<TAB>` silently loses its suggestions.
+
+The one **clean group** (no collision, so no default verb) is **`date`** (the `date_meta`
+table): `date set / ls / rm / import`, with `wl dateinfo` as the polymorphic everyday
+shortcut (sets when given a label, lists when not, `--clear` / `--import` variants).
+
+The `<entity> <verb>` reshape (WL#486) is now **complete** for every entity.
+
+**B. Composite helper** — a one-step shortcut that wraps one or more primitives for
+the common path; never the *only* way to do something (the primitive stays). Status
+verbs `done` / `cancel` / `reopen` / `wait` (set `node.status` + side effects),
+`defer` (sched + LATER), `start` / `stop` (clock + DOING), `tick` (habit check-in
+metric + done), and the compound `add --log/--done/--at/--link/--sched/--metric`
+(add + several primitives in one transaction).
+
+**C. View** — read-only cross-entity rendering, no single-row CRUD: `ls` / `tree` /
+`day` / `agenda` / `projects` / `changes` / `summary` / `focus` / `ancestors` /
+`descendants` / `find` / `logs` / `show`. These share the unified filter (§ shared
+`--tag/--kind/--status`), time-window (§8) and `--by` (§9) conventions.
+
+System commands (`migrate` / `config` / `init` / `import` / `apply` / `themes` /
+`print-completion`) sit outside the three buckets.
+
+### 1.2 Help system (battery-included + shortcut ↔ canonical cross-reference)
+
+Every command's `--help` is self-sufficient (§35 "battery-included"): a one-line intro,
+a few scenario examples, and a "Differences from related commands" block. On top of that,
+**wherever a shortcut and its canonical entity-verb both exist, both helps must name the
+relationship — this is mandatory, never omitted**, so a reader landing on either form
+learns the other:
+
+- The **canonical entity-verb** help (e.g. `wl node add -h`) states it's also reachable as
+  the shortcut (`also: wl add`).
+- The **shortcut** help (e.g. `wl add -h`) states it's the shortcut for the canonical form
+  (`canonical: wl node add`).
+- The **entity group** help (e.g. `wl node -h`) carries a dedicated **Shortcuts** section
+  mapping each shortcut-able verb to its top-level name (`add → wl add`, `ls → wl ls`, …).
+
+This applies to every entity as the `<entity> <verb>` + shortcut rollout proceeds, so the
+two ways to invoke the same operation never drift in discoverability, only in keystrokes.
+
 ## 2. Data model (`src/worklog/migrations/`)
 
 A single `node` table carries everything; the `kind` field discriminates type; `parent_id` self-reference builds the tree. The schema is delivered as numbered SQL migrations under `src/worklog/migrations/NNNN_*.sql`; `PRAGMA user_version` tracks the highest applied migration. `ensure_db()` auto-applies pending migrations on every command; `wl migrate` is the explicit form. See `src/worklog/migrations/0001_initial_schema.sql` for the initial layout and `README.md` for the high-level picture.
@@ -51,7 +162,7 @@ A single `node` table carries everything; the `kind` field discriminates type; `
 - **status only applies to task / habit / meetlog**; time-hierarchy kinds (year/month/...) and project kind leave status NULL
 - Tables: `node / tag / log / metric / clock / prop / link / sched / date_meta` + derived view `v_node_path`
 - **`node → log → metric` spine** (the log-centric core): a `node` has many `log`s; a `log` (carrying a `tag` — `note`/`goal`/`summary`/`overview`/`top5`/`clock`(carrier)/… , NULL = plain note) has 0..N `metric`s. A `metric` is a structured datapoint (`tag` = what it is e.g. `glucose`/`pullups`/`checkin`; `value_num`/`value_text`/`unit`/`note`/`at`). **`tag` is the uniform classification field across all three** — node (a multi-value label set), log (its role, single-value), metric (its kind, single-value); same word, different scopes, SQL-unambiguous. A metric **must hang off a log** (`metric.log_id` NOT NULL) — so every datapoint has a log carrier; a `CHECK` requires a value (pure markers store `value_num=1`). `metric.node_id` is denormalized for join-free per-node queries (no FK; triggers keep it equal to the carrier log's node). CRUD surface: `wl metric add/ls/edit/rm` (`add` without `--on-log` creates a carrier log; a value-less marker is stored as `value_num=1`); `--metric` on `wl log`/`wl add` and `metrics` in `wl import` attach datapoints inline. Habit "done today" = a `tag=checkin` metric that day (written by `wl tick`/`wl checkin`), not "any log exists".
-- **Meta fields are history-preserving typed logs**: day `goal`/`summary`, week `overview`, month `top5` are `log.tag` logs (latest = current; each edit appends), written by `wl goal`/`wl recap`/`wl set <node> <key>`. (`prop` is back to truly-static single-value attributes.)
+- **Meta fields are history-preserving typed logs**: day `goal`/`summary`, week `overview`, month `top5` are `log.tag` logs (latest = current; each edit appends), with their own `wl meta set/ls/rm` CRUD group; also written by `wl goal`/`wl recap` (today-auto) and the key-routed `wl set <node> <key>` shortcut. (`prop` is back to truly-static single-value attributes — a separate store.)
 - **`clock` is structured time tracking**: `clock(node_id, start_at, end_at, elapsed_sec)`, written by `wl start`/`stop`/`spent`/`wait` — replaces the old `CLOCK_IN`/`CLOCK_OUT` log-body convention. Durations are summed from `elapsed_sec`, not parsed from text.
 - **Two parallel trees, both hung under lifetime**:
   - **Responsibility line**: `lifetime → area → project → task` (PARA model: area is a cross-time responsibility domain, projects belong to areas, tasks belong to projects)
@@ -431,6 +542,75 @@ The decision model: **schedule (forward planning, calendar-like) and log (retros
 
 When changing sched / day derivation, keep `_sched_fires` / `_scheduled_node_ids` / `_node_plan` / `_sec_group` / `_render_day_group` / `cmd_day` / `cmd_logs(--group)` / `cmd_sched` in sync.
 
+## 25. Help topic system (`wl help` — info-style)
+
+Beyond per-command `--help` (§1.2), `wl help` is a standalone, **info-style topic browser**:
+a repo-managed set of docs — one per command / concept / common-param / guide — navigable by
+"see also" links. This keeps `--help` short (summary + a pointer) while giving each topic room
+for a full explanation, and makes the help content **i18n-able and reviewable as plain files**.
+
+### Docs live in the repo (packaged, i18n-ready)
+- Location: `src/worklog/help/<lang>/<topic>.md`, shipped in the wheel like `migrations/`.
+  `en` is the source language and the fallback; other langs mirror the same topic ids.
+- One Markdown file per topic; topic id = filename stem (`node.md` → `wl help node`).
+- Minimal frontmatter (no YAML dep), `key: value` lines between `---` fences:
+  ```
+  ---
+  title: node — the single unit of everything
+  category: concept        # concept | command | param | guide
+  see_also: log, tag, status, add
+  ---
+  <markdown body>
+  ```
+- `index.md` is the root (`wl help` with no topic): the overview + topic list grouped by category.
+
+### `wl help` behavior
+- `wl help` → render `index.md` + list topics by category.
+- `wl help <topic>` → title, body, then a "See also: …" footer resolved from `see_also`.
+- Unknown topic → closest-match suggestions (never a stack trace).
+- Language: `--lang` > `$WORKLOG_LANG` > `$LANG` prefix > `en`; a missing translation falls back
+  to `en` per-topic, never a hard error.
+- Rendering: a **dependency-free renderer** (`commands/help.py`) handles a small fixed Markdown
+  subset — ATX headings, ```fenced``` code blocks, and inline `**bold**` / `*italic*` /
+  `` `code` `` / `[text](url)` / bare URLs (no `_italic_` — underscores collide with identifiers;
+  no Markdown engine, no `rich.markdown`). It **escapes literal text** before injecting style
+  markup, so bodies with `[ ]` / `[x]` / `[/]` / `#L42` render safely (a raw `[/]` previously
+  crashed rich); with color off the markers are simply stripped. The exact subset + frontmatter
+  spec for topic authors lives in **CONTRIBUTING.md** ("Writing `wl help` topics").
+
+### Relationship to `--help` (the slimming policy)
+- `--help` stays the *quick reference at the point of use*: usage, one-line intro, a couple of
+  examples, and — when a fuller topic exists — a closing `More: wl help <topic>`.
+- `wl help <topic>` is the *teaching* layer: concepts, rationale, cross-links, the planning
+  rhythm, PARA, etc. Content that would bloat `--help` lives here, keeping `--help` scannable.
+- The top-level `wl -h` Concepts glossary stays a one-line teaser per concept, pointing to
+  `wl help <concept>` for the full entry.
+
+### `--help` rendering: color, Markdown, wrapping (shared with `wl help`)
+- **Color is post-processed, not native.** argparse has no color before Py 3.14 (and 3.14's uses
+  its own palette), so `colorize_help` injects ANSI into argparse's *already-formatted* output.
+  The ANSI is zero-width, so argparse's column math is untouched. Color/theme are re-resolved from
+  `--color`/`--theme`/env at format time, because `--help` fires inside `parse_args`, before
+  `main()` builds the console. It's the same 3-tier scheme as `wl help` (dim body / bright-cyan
+  references / bold-white headings).
+- **`--help` may use the topic Markdown subset — but only in `epilog`/`description`.** Markers
+  render with color on and are stripped with color off. `help=` one-line summaries stay **plain
+  text**: argparse line-wraps them, which would split a Markdown span across lines. The point of
+  Markdown here is explicit styling where a heuristic can't help — a command name like `set` /
+  `log` / `show` collides with the English word, so it's backticked to mark it as code.
+- **Wrapping lives in the formatter, not the post-processor.** A `RawDescriptionHelpFormatter`
+  subclass overrides `_fill_text` (the hook argparse calls *only* for epilog/description) to wrap
+  the raw epilog with a hanging indent; option/choice help is still wrapped by argparse's own
+  `_split_lines`. Re-wrapping argparse's whole formatted output as a post-process was the wrong
+  layer — it re-wraps already-wrapped rows and misaligns them. The formatter caps the width on
+  wide terminals (`HELP_MAX_WIDTH`) and shares one `render.help_width()` with the `wl help`
+  topic-body wrapper, so every help surface lines up to a single width.
+
+### Rollout (incremental)
+Land the loader + `wl help` command + a handful of seed topics first; then author one topic per
+command / concept / param and trim each `--help` to summary + pointer. Topics land piecemeal —
+a missing topic simply isn't offered; nothing breaks.
+
 ## 24+. Additional sections (24–37)
 
 Sections 24 onward cover finer-grained extensions: metadata at the top of `wl day` (goal / summary / top5 / overview blockquote), date context (`date_meta` for holidays / makeups), `--by-task` per-task aggregation in `wl logs`, `wl active` (active CLOCKs with elapsed), the `compound flag` semantics on `add` / `done` / `cancel` (`--log` / `--at` / `--link` / `--sched` / `--done` in one shot), `unlog` / `relog` (log editing through `#L<id>` references), time backfill (`start --at` / `stop --at` / `spent`), the multi-habit interactive `wl checkin`, recurrence rules including `-1` for "last day of period", the `wl ls` multi-dimension query model, default-tail-N to prevent screen-blast, shell completion via `print-completion` init-load (matching the starship / direnv / zoxide pattern), and the **battery-included command help design philosophy** (every `--help` carries a one-line intro + scenario + diff-from-neighbors).

{pyworklog-0.5.0 → pyworklog-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyworklog
-Version: 0.5.0
+Version: 0.6.0
 Summary: SQLite-backed worklog tool with a todo.sh-style CLI
 Project-URL: Homepage, https://github.com/xyb/worklog
 Project-URL: Repository, https://github.com/xyb/worklog

{pyworklog-0.5.0 → pyworklog-0.6.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "pyworklog"
-version = "0.5.0"
+version = "0.6.0"
 description = "SQLite-backed worklog tool with a todo.sh-style CLI"
 readme = "README.md"
 license = "MIT"

{pyworklog-0.5.0 → pyworklog-0.6.0}/skills/worklog-cli/SKILL.md

@@ -30,7 +30,8 @@ Likewise, before adding a dev todo under a project, check that project's existin
 | Record a number / measurement / check-in | `wl metric add <id> glucose 5.4 --unit mmol/L` / `wl metric ls <id>` / `wl metric edit #M7` / `wl metric rm #M7`; inline: `wl log <id> "..." --metric 'pullups 8'`. Habit done-today = a `checkin` metric (`wl tick`/`wl checkin`) |
 | Mark done / defer (fuzzy time ok) / start clock | `wl done <id>` / `wl defer <id> next-month` (also accepts `2026-Q3` / `someday` / precise date) / `wl start <id>` `wl stop <id>` |
 | Schedule task to a date / repeat (drives "planned") | `wl sched <id> 2026-06-15` (also accepts `tomorrow` / `day-after-tomorrow`) / `--clear`. `--recur` supports period start / end: `daily` / `weekly:Mon,Fri` (also 1-7 / -1..-7) / `monthly:1` (month start) · `monthly:-1` (month end) / `quarterly:1-1` (quarter start) · `quarterly:-1` (quarter end) / `yearly:01-01` (year start) · `yearly:-1` (year end); `-1` always means period end. A task scheduled to a day shows up in `wl day` as "planned · not yet logged" even with no log |
-| Meta info (end-of-day summary / Top5 / today's goal) | History-preserving typed logs (`log.tag`), not props: `wl goal "..."` (day) / `wl recap "..."` (day summary) / `wl set <month> top5 "..."` / `wl set <week> overview "..."`. Each write appends; the latest is current. `wl day` shows them at the top as a blockquote. Prefer `wl recap`/`wl goal` over `wl set` for day fields (read-back + stale-warning) |
+| Meta info (end-of-day summary / Top5 / today's goal) | History-preserving typed logs (`log.tag`), **a distinct store from props** — own group `wl meta set/ls/rm <node> <field>` (`field` ∈ goal/summary/overview/top5; each write appends, latest = current). Shortcuts onto it: `wl goal "..."` / `wl recap "..."` (auto-target today's day; preferred — read-back + stale-warning), and the key-routed `wl set <node> <field>` (= `wl meta set`; `wl unset <node> <field>` = `wl meta rm`). e.g. `wl meta set <week> overview "..."` / `wl meta set <month> top5 "..."`. `wl day` shows them at the top as a blockquote |
+| Command aliases | `wl alias add d day` (→ `wl d` == `wl day`) / `wl alias ls` / `wl alias rm d`. Stored in `~/.config/worklog/aliases.ini`; target must be a real command, can't shadow one; takes effect next run |
 | Date context (holidays / vacation / makeup days) | `wl dateinfo 2026-05-01 Labor-Day-holiday` / `wl dateinfo --import holidays.json` (`{"YYYY-MM-DD":"label"}`) / `wl dateinfo <date> --clear`. Weekday auto-computed; `wl day` header shows "date weekday · label" |
 | Reproduce a day's progress (like markdown worklog) | `wl day [YYYY-MM-DD]` (log-date based: work/personal split → secondary group → task → indented logs + stats). **Default `--by plan`** (planned / unplanned). **Planned = has a `sched`/recur entry firing that day (source of truth, set via `wl sched`); everything else = unplanned.** The legacy `:planned:` tag is honored only as a transitional fallback — do NOT add it to new tasks, use `wl sched`. Switch dimensions with `--by project` / `--by priority` (P0/P1/P2) |
 | List all active projects | `wl projects` |
@@ -154,9 +155,12 @@ wl checkin --all-kinds                # not limited to habit kind
 
 ### Meta fields keep history (typed logs, not props)
 
-`wl goal` / `wl recap` (day), `wl set <week> overview` / `wl set <month> top5` are
-stored as `log.tag` logs — each write appends, the latest is current, so edit
-history is kept (`prop` is only for truly-static single-value attributes).
+The four meta fields (goal/summary/overview/top5) have their own group `wl meta
+set/ls/rm <node> <field>`, stored as `log.tag` logs — each write appends, the latest is
+current, so edit history is kept (`prop` is a separate store, only for truly-static
+single-value attributes). `wl goal` / `wl recap` are today-auto shortcuts; `wl set <node>
+<field>` / `wl unset <node> <field>` are key-routed shortcuts onto `wl meta set` / `wl meta
+rm` (so `wl set` fronts both `prop set` and `meta set` by key, like `wl add` is `node add`).
 
 ### Recurrence rules (`--recur`), every variant supports `-1` for "last day of period"