taskai-cli 1.6.2__tar.gz → 1.6.5__tar.gz

{taskai_cli-1.6.2 → taskai_cli-1.6.5}/DEVLOG.md

@@ -1,3 +1,87 @@
+# 9-3
+
+Browser session — console-driven navigation and selection, mostly beyond the
+original Phase 1 scope (DEVPLAN 1.7 has the durable version):
+
+- Synthetic invisible root node (`canvas.js`, `rootNode` / `"__root__"`) —
+  never drawn or hit-tested, sits above the real roots as the nav anchor and
+  the "whole tree / nothing specific" selection. `selectedNode` is now never
+  null: defaults to `rootNode`, and an empty-canvas click selects it.
+- `show all` / bare `show` — client-side console command: refetch `/api/tree`,
+  select the root, `fitAll()` (eases the view out until the whole forest fits
+  with padding). `show <id|name>` selects + focuses the resolved node without
+  opening the edit panel (that's `edit <id|name>`).
+- Tree navigation — `navigate(direction)` + `up`/`down`/`left`/`right` console
+  commands. Nodes got a `parent` back-ref; walks up/down/across siblings,
+  wraps on both axes. Each move acts like `show <target>`.
+- `.` as a standalone console token → selected node's id (`resolveDotRefs`),
+  so `update . --priority 3`, `done .`, `edit .` work. Leaves `a.md` / `3.5`
+  alone; errors if nothing real is selected.
+- `hide edit` console command → `closeEditPanel()`, complements `edit <id>`.
+- Up-arrow console history (was the last open Phase 1.6 item) — done earlier
+  (`commandHistory` in `console.js`), just now checked off in DEVPLAN.
+
+CLI (not browser): added `task undone <id>`, and made recursion on
+`complete`/`done` an opt-in `-r` / `-recursive` flag instead of always-on.
+Resynced the docs for it — `help_menu.py` (`help_general` + `help_examples`,
+which is also the AI's command reference) and the hand-written mentions in
+`docs/getting-started.md` / `docs/item-data.md`. `docs/commands.md` is a
+`literalinclude` of generated help text, so it tracks automatically.
+
+Fixed the long-standing `update_item` quirk: it now calls
+`_parse_item_kwargs` before `db.update_item` (like `create_item` does), so
+`update <id> --due_by MM-DD-YYYY` no longer throws. Extended
+`_parse_item_kwargs` in the same pass — maps `depends_on` (`"1,2,3"`) to
+`dependency_ids`, and guarded the `due_by` branch with `isinstance(v, str)`
+so it's idempotent for the recursive re-parse. Edit panel's Due by /
+Depends on fields round-trip now.
+
+---
+
+# 8-29
+
+Worked the TRIAGE backlog, then built out the docs.
+
+TRIAGE fixes:
+- **Critical:** `_find_model_by_stringmatch` inverted `{id: name}` -> `{name:
+  id}`, silently collapsing duplicate names to one arbitrary id (so
+  update/delete-by-name could hit the wrong item). Now collects every
+  fnmatch hit; one resolves, zero -> `None`, 2+ -> `throw_error` listing the
+  ids. Also gave `throw_error` a `verbose` flag so it stops dumping
+  `args=/kwargs=` on every error.
+- Added `task unlink {parent} {item}` (mirrors `add_link`).
+- Stripped the dead `for record_type in [TodoItem, Comment]` loop in
+  `_find_model_by_stringmatch` and the now-unused `Comment` import.
+- `show_examples()` now prints a real `help_examples` string (via `task
+  examples`); removed the redundant `task show examples` branch.
+
+Browser: soft links (`linked_ids`) now render as "shadow" nodes — a ghost
+copy of the linked item as an extra child under the linking node (~0.92
+alpha, flat, dashed grey border, italic, `↗` glyph, real id). Edge to it is
+dashed grey with a gradient stroke that goes transparent inside either node.
+Selecting/editing a shadow acts on the real item (`itemForNode` -> `realId`).
+
+Docs: README synced with `execute_commands` and given a `task setup`
+walkthrough + Web UI section; `help_menu.py` gained `task browser` / `task
+help` and lost its stale "requires id, not name" grouping (everything takes
+id-or-name now). Then turned `docs/` into a real Read the Docs site — Sphinx
++ MyST + Furo, dynamic version, a `builder-inited` hook that dumps
+`help_general` and the provider table to git-ignored `_generated/` files so
+the reference pages can't drift. Pages (all `.md`): index (gif placeholder +
+feature bullets), getting-started, configuration, managing-the-tree,
+item-data, interactive-mode, browser-mode, ai-integration, commands. No
+caveats/notes in user pages — gaps went to TRIAGE (`dependency_ids`
+unreachable from the CLI; interactive-REPL staleness).
+
+DEVPLAN: added Phases 4-7 (browser improvements: comments, big description
+editor, keyboard shortcuts + left panel; CLI view expansion + config keys;
+comprehensive testing; advertising).
+
+Still open in TRIAGE: multi-word unquoted input (design-blocked), `task
+browser` `[port]`, the two gaps above.
+
+---
+
 # 8-22
 
 Found and fixed a real bug from the `litellm` migration earlier today: it

{taskai_cli-1.6.2 → taskai_cli-1.6.5}/DEVPLAN.md

@@ -45,9 +45,11 @@ testing — don't `nuke` it.
 (methods intentionally take no `self` — called as `Controller.foo(...)`, not
 instantiated) holds all the CRUD/business logic. `execute_commands(*args,
 **kwargs)` is one big `match` statement mapping subcommands (`show`,
-`create`, `add`, `update`, `move`, `rename`, `delete`, `complete`/`done`,
-`comment`, `depend`, `link`, `reorder`, `clear`, `status`, `config`, `ai`,
-`pomo`, `repair`, `nuke`, `browser`, ...) to `Controller` calls. There's a
+`create`, `add`, `update`, `move`, `rename`, `delete`,
+`complete`/`done`/`undone`, `comment`, `link`, `reorder`, `clear`,
+`status`, `config`, `ai`, `pomo`, `repair`, `nuke`, `browser`, ...) to
+`Controller` calls. `complete`/`done`/`undone` take an opt-in `-r` /
+`-recursive` flag to apply down the subtree. There's a
 hand-rolled arg/kwarg parser (`_parse_arg_string`, `_parse_remaining`)
 instead of `argparse`. `interactive_program()` is the REPL entered when
 `task` runs with no arguments. The module connects to the database and loads
@@ -57,7 +59,7 @@ is why `taskai/browser.py` reuses `from taskai.cli import db` rather than
 opening a second connection.
 
 **Views.** [taskai/views.py](taskai/views.py): Rich-based tree rendering
-(`view_lists`, `view_item`, `view_items`), display format configurable via
+(`view_lists`, `view_item`), display format configurable via
 `DISPLAY_STRING`/`DISPLAY_COLORS`.
 
 **AI services.** [taskai/services/ai.py](taskai/services/ai.py):
@@ -90,20 +92,26 @@ unless you're told to fix them):**
   name-only-duplicate methods (`show_by_item_name`, `delete_item_by_name`)
   and several inline `_is_int(...)` dispatch branches in `execute_commands`
   were deleted outright rather than kept alongside the id path.
-- `task show <id1>,<id2>,...` is documented in the README but
+- ~~`task show <id1>,<id2>,...` is documented in the README but
   `execute_commands`'s `show` case never dispatches to
-  `Controller.show_items`/`view_items` — there's no wired path to it.
-- `Controller.update_item` never calls `Controller._parse_item_kwargs`
-  (`create_item` does) before handing kwargs to `db.update_item`. Confirmed
-  effects: `update <id> --due_by MM-DD-YYYY` throws a pydantic validation
-  error (the string never gets converted to a `datetime`, unlike on
-  `create`), and `update <id> --depends_on 1,2` silently no-ops (never
-  remapped to the model's real `dependency_ids` field, so pydantic just
-  drops it as an unrecognized extra key — no error, no effect). Every other
-  field (`name`, `description`, `status`, `priority`, `completed`) updates
-  correctly. The edit panel (1.5) and console both go through `update` and
-  will hit this. Likely fix: add the same
-  `kwargs = Controller._parse_item_kwargs(kwargs)` call `create_item` makes.
+  `Controller.show_items`/`view_items` — there's no wired path to it.~~
+  Removed rather than wired up — `Controller.show_items` and `view_items`
+  are gone (CLI audit, see DEVLOG); `task show` only ever takes one target
+  now.
+- ~~`Controller.update_item` never calls `Controller._parse_item_kwargs`
+  (`create_item` does) before handing kwargs to `db.update_item`, so
+  `update <id> --due_by MM-DD-YYYY` threw a pydantic validation error and
+  `update <id> --depends_on 1,2` silently no-op'd.~~ **Fixed.**
+  `update_item` now runs `kwargs = Controller._parse_item_kwargs(kwargs)`
+  before `db.update_item`, same as `create_item`. `_parse_item_kwargs` was
+  extended in the same pass: it now also maps the CLI-facing `depends_on`
+  (a comma-separated id string, `"1,2,3"`) to the model's real
+  `dependency_ids: list[int]` — so `create --depends_on ...` works now too,
+  not just `update` — and its `due_by` branch is guarded with
+  `isinstance(v, str)` so the helper is idempotent (safe for the
+  already-parsed kwargs `update_item`'s `recursive=True` branch passes back
+  down). Edit panel's **Due by** and **Depends on** fields now round-trip
+  end to end.
 - **Sync is one-directional: CLI → browser only, not the reverse.**
   `GET /api/tree` (`browser.py`) reloads from disk (`db.flush()`) on every
   call, and `canvas.js` refetches on window focus, so browser-side views
@@ -250,10 +258,25 @@ stdlib `http.server` — no new dependency, consistent with "less code."
 
 ### 1.4 — DAG view (v2: full graph + interaction)
 
-- [ ] Draw `dependency_ids` and `linked_ids` as a second edge style (dashed
-      / different color) layered on top of the tree edges — this is what
-      makes it a DAG rather than just a tree view. Still open — only
-      parent/child tree edges render today.
+- [~] **`linked_ids` done as "shadow" nodes; `dependency_ids` still
+      deferred to 2.0.** A soft link renders as a lightweight *ghost copy*
+      of the linked item, placed as an extra child under the linking node
+      (`buildShadowNode` in `canvas.js` — non-recursing, carries `realId`
+      back to the true item; `buildTree` appends one per `linked_ids`
+      entry). It's styled subtly apart from a real placement: ~0.92 alpha,
+      no drop shadow, dashed grey border, italic label, an `↗` glyph
+      top-right (the one colour accent), and it shows the linked item's
+      real id rather than the synthetic shadow id. The parent→shadow edge
+      is dashed and uncoloured — grey, the dash pattern alone distinguishes
+      it from the solid tree edges — and drawn with a gradient stroke that
+      goes fully transparent inside either node's square so it never
+      crosses node content (`drawLinkEdges`); solid-edge drawing
+      (`drawLines`) skips shadow children. Selecting or editing a shadow
+      acts on the real item (`itemForNode` resolves `realId`), so the edit
+      panel and `update` commands hit the true record. `dependency_ids` edges are still not drawn — and `task
+      depend` was itself removed from the CLI in an earlier audit pass, so
+      there's no dependency data being created right now anyway; revisit
+      both together in 2.0.
 - [x] Pan (drag) and zoom (wheel) — done via canvas context transforms
       (`ctx.translate`/`ctx.scale` + a `view` state object), not SVG
       `viewBox`, same toolchain reasoning as above. Zoom keeps the point
@@ -268,6 +291,8 @@ stdlib `http.server` — no new dependency, consistent with "less code."
       break after any mutation). Drawn with the same accent-blue
       border/thicker stroke as hover. This is exactly the state 1.5's edit
       menu piggybacks off — not edge highlighting yet, just the node.
+      (Later, in 1.7: `selectedNode` became **never-null** — an empty
+      selection is now the synthetic `rootNode`, not `null`.)
 - [x] Color/style nodes by `completed` — soft green fill + border (see
       `STYLE.colors.nodeFill/BorderDone`), not strike-through/dim like the
       CLI. `status` ended up as a small orange text label in the node's
@@ -316,9 +341,9 @@ add new visual knobs there, not inline in `draw()`.
 
 While wiring this up, confirmed against a throwaway test item (created and
 deleted, not real data): `name`/`description`/`priority`/`completed` all
-update correctly end to end. `due_by` and `depends_on` hit the
-`update_item`/`_parse_item_kwargs` bug documented above — left unfixed on
-purpose, current call.
+update correctly end to end. `due_by` and `depends_on` originally hit the
+`update_item`/`_parse_item_kwargs` bug documented above — **now fixed** (see
+that entry), so all seven fields round-trip.
 
 ### 1.6 — Console
 
@@ -333,13 +358,58 @@ purpose, current call.
       response already carries the fresh tree. Also handles the `focus`
       field `show` commands return: calls `focusOnNode` on that id instead
       of expecting text output.
-- [ ] Up-arrow history — still open, not done.
-
-At the end of Phase 1: dependency/link edges (1.4) and up-arrow console
-history (1.6) are the only pieces left open. The DAG, edit panel, and
-console all funnel through one `/api/command` endpoint and one `/api/tree`
-read, as planned — that's the "less code" payoff of routing everything
-through the existing `Controller`.
+- [x] Up-arrow history — done (`console.js`). `commandHistory` array, every
+      submitted line pushed on; `ArrowUp`/`ArrowDown` walk it, an index at
+      `length` meaning "not currently browsing history", and `ArrowDown`
+      past the end restores an empty input.
+
+At the end of Phase 1: the whole 1.1–1.6 checklist is done
+(dependency/link edges (1.4) deferred to 2.0, see above). The DAG, edit
+panel, and console all funnel through one `/api/command` endpoint and one
+`/api/tree` read, as planned — that's the "less code" payoff of routing
+everything through the existing `Controller`. Console-driven canvas
+navigation then grew past the original Phase 1 scope — see 1.7.
+
+### 1.7 — Console-driven navigation & selection (post-plan, beyond original scope)
+
+Grew out of Phase 1's console + selection machinery; none of this was in
+the original checklist.
+
+- [x] **Synthetic invisible root node** (`canvas.js`, `rootNode` /
+      `"__root__"`). Never added to `nodes`, so never drawn, hit-tested, or
+      bordered. It's the nav anchor above the real root items and the
+      "nothing specific / the whole tree" selection. `selectedNode` is now
+      **never null** — it defaults to `rootNode`, and a click on empty
+      canvas selects `rootNode` rather than clearing the selection.
+      `applyTree` re-parents it over the freshly-built roots and parks it
+      one `ySpacing` above them on every refresh.
+- [x] **`show all` / bare `show`** (console, client-side). Refetches
+      `/api/tree`, selects the synthetic root, and calls `fitAll()` — eases
+      the view out until every real node fits on screen with padding,
+      clamped to `STYLE.zoom` bounds.
+- [x] **`show <id|name>`** (console, client-side). POSTs the command,
+      applies the returned tree, then selects + `focusOnNode`s the resolved
+      node. Deliberately does *not* open the edit panel — that's
+      `edit <id|name>`, mirroring the canvas's single-click vs. double-click
+      split.
+- [x] **Tree navigation** — `navigate(direction)` in `canvas.js`, wired to
+      `up` / `down` / `left` / `right` console commands. Nodes carry a
+      `parent` back-reference (set in `buildTree` / `applyTree`) so the walk
+      goes up as well as down: `down` → first child, `up` → parent,
+      `left`/`right` → previous/next sibling. Wraps on both axes — past the
+      last sibling loops to the first; `down` past the deepest leaf and `up`
+      from `rootNode` loop between the top and the deepest first-child leaf.
+      Each move behaves like a `show <target>` (select + ease/zoom; `fitAll`
+      when the target is `rootNode`).
+- [x] **`.` = the selected node** (`resolveDotRefs` in `console.js`). A bare
+      `.` token in any console command is swapped for `selectedNode.id`
+      before dispatch, so `update . --priority 3`, `done .`, `edit .` act on
+      the current selection. Only matches a standalone `.` (whitespace or
+      string end on both sides), so `a.md` / `3.5` are untouched; errors if
+      `.` is used with nothing real selected.
+- [x] **`hide edit`** (console) → `closeEditPanel()` in `editpanel.js`,
+      collapsing the right panel and restoring canvas width. Complements the
+      existing `edit <id|name>` that opens it.
 
 ---
 
@@ -459,7 +529,10 @@ like Flash-Lite.
 - [x] Updated README's Config section to match the new `AI_MODEL`
       `provider/model` shape and point at `task setup`.
 
-### 2.4 — `task ai agent <prompt>` (later — real tool-calling loop)
+### 2.4 — `task ai agent <prompt>` (deferred to 2.0 — real tool-calling loop)
+
+**Deferred to 2.0.** Out of scope for the current polish pass; revisit as
+part of the larger 2.0 rework rather than squeezing it in here.
 
 A separate entry point, not a replacement for `task ai`. `task ai <prompt>`
 stays the fast, ungated, one-shot-plan-and-execute path from 2.1-2.3;
@@ -501,15 +574,109 @@ Re-scope this section before starting 2.4.
       `editmenu.js`) and delete anything exploratory left over from getting
       the DAG layout working. Still no bundler — just multiple `<script>`
       tags loaded in order.
-- [ ] **Minimalist docs.** A short "Web UI" section in the README (how to
-      run `task web`, one screenshot) covers most of it; only split into a
-      separate `docs/` page if the README starts feeling long. Keep the
-      "less code" principle applied to prose too — this doesn't need to be
-      exhaustive.
+- [~] **Docs.** README is synced with `execute_commands` (command list,
+      `task ai` flags, Web UI section, `task setup` walkthrough);
+      `help_menu.py` lists `task browser` / `task help`, and its stale
+      "requires id, not name" grouping was corrected (every item-taking
+      command resolves id-or-name via `_resolve_item` now). Grew past a
+      README-only scope into a proper Read the Docs site under `docs/`
+      (Sphinx + MyST + Furo).
+      **Built:** `conf.py` rebuilt (dynamic version from pyproject, Furo,
+      copybutton, sphinx-design; a `builder-inited` hook dumps `help_general`
+      and the `PROVIDER_ENV_VARS` table to git-ignored files under
+      `docs/_generated/` so the reference/config content can't drift from
+      source). Pages, all `.md`: `index` (gif placeholder + "what you can
+      do" + toctree), `getting-started`, `configuration`,
+      `managing-the-tree`, `item-data`, `interactive-mode`, `browser-mode`,
+      `ai-integration`, `commands` (`literalinclude` of the generated help
+      text). No "notes"/caveats in any user page — gaps go to TRIAGE
+      instead. README links to the site.
+      **Still open:** replace `docs/_static/demo.gif` placeholder with a real
+      recording; confirm the RTD project slug (assumed `taskai` in `conf.py`
+      `html_baseurl` + README); explanation/architecture pages; polish
+      (screenshots for browser-mode, custom 404, OpenGraph cards, CI
+      `linkcheck`, tested examples, changelog).
+- [x] **`help_menu.py` drift from `execute_commands`.** The CLI gained
+      `task undone <id>` and an opt-in `-r` / `-recursive` flag on
+      `complete` / `done` (recursion used to be unconditional). Resynced:
+      `help_general` and `help_examples` in `help_menu.py` (also the AI's
+      verbatim command reference), plus the two hand-written mentions in
+      `docs/getting-started.md` and `docs/item-data.md`. `docs/commands.md`
+      needs no edit — it `literalinclude`s the `builder-inited`-generated
+      dump of `help_general`.
 - [ ] **UX pass.** Empty/loading state for the DAG when a user has no tasks
       yet (currently the app would just render nothing); a keyboard shortcut
       to toggle the console (e.g. backtick); consistent spacing/typography
-      in `style.css`; visual legend distinguishing tree edges from
-      dependency/link edges.
+      in `style.css`. (Edge legend dropped — depended on 1.4's dependency/
+      link edges, now deferred to 2.0.)
 - [ ] Re-check the Phase 0 fixes are still holding once the web UI is
       exercising more command paths than the CLI alone did.
+
+---
+
+## Phase 4 — Browser view improvements
+
+Builds on Phase 1's canvas / edit panel / console. Still plain HTML/CSS/JS, no
+framework, everything routed through the existing `/api/tree` + `/api/command`
+endpoints.
+
+- [ ] **Show comments.** Items carry `comment_ids` but the browser never
+      surfaces them. Render an item's comments in the edit panel — read-only
+      list at minimum; adding one posts `comment <id> <text>` through
+      `/api/command` like every other field. Consider a comment-count
+      affordance on the canvas node itself.
+- [ ] **Much larger description editor.** The `description` field in the edit
+      panel is a small single-line-ish input today. Make it a real multi-line
+      textarea that dominates the panel (large fixed height or auto-grow), so
+      the panel is usable for actual note-taking — likely widen the panel
+      itself while a node is selected.
+- [ ] **Keyboard shortcuts + a shortcuts panel.** Add real key bindings
+      (toggle console, toggle edit panel, complete / delete the selected
+      node, deselect, focus a search box, zoom/pan, …) and a **left-hand
+      panel listing them**, mirroring the right-hand edit panel and
+      collapsible the same way. Follow the existing `STYLE` object +
+      collapsible-panel machinery (`setRightPanelWidth`); this adds a left
+      equivalent. Supersedes the single console-toggle shortcut noted in
+      Phase 3's UX pass.
+
+---
+
+## Phase 5 — CLI view
+
+- [ ] **Expand what `task show` renders, and its options.** Exact scope TBD —
+      needs a working session with Alex to pin down. Candidates: filter by
+      status / priority / completion, depth limits, flat vs. tree layout,
+      sort order, inline comments / links, format and colour toggles. Prompt
+      before implementing.
+- [ ] **New view-settings config keys.** Extend `CLIConfig` (today just
+      `DISPLAY_STRING` / `DISPLAY_COLORS`) with keys backing whatever the
+      expanded view supports; document them in `docs/configuration.md` and
+      `help_menu.py` alongside the existing ones.
+
+---
+
+## Phase 6 — Comprehensive testing & bugfixing
+
+- [ ] **Broaden the test suite.** Currently 7 tests across `test_cli.py` /
+      `test_execution.py` / `test_json_dir_database.py` / `test_view.py`.
+      Cover every `execute_commands` branch, id/name resolution (including
+      the multi-match error path), `_parse_item_kwargs`, the browser
+      endpoints (`/api/tree`, `/api/command`), and the AI command-execution
+      loop with a mocked LLM.
+- [ ] **Fix what the tests surface**, and clear the still-open TRIAGE items
+      as they come up (multi-word unquoted input, `task browser` `[port]`,
+      `dependency_ids` reachability, interactive-REPL staleness).
+- [ ] **Wire CI.** `pytest` on every PR, plus `sphinx-build -W` +
+      `linkcheck` for the docs.
+
+---
+
+## Phase 7 — Advertising
+
+- [ ] Get the docs site live: confirm the Read the Docs slug, record the
+      `docs/_static/demo.gif` terminal demo.
+- [ ] Polish the PyPI listing — `pyproject.toml` has an empty `description`
+      and no keywords / classifiers / project URLs.
+- [ ] Write a short "show and tell" (what it is, the everything-is-an-item
+      model, the AI layer, the canvas view) built around the gif, and decide
+      on channels (Show HN, r/commandline, r/productivity, GitHub topics).

{taskai_cli-1.6.2 → taskai_cli-1.6.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: taskai-cli
-Version: 1.6.2
+Version: 1.6.5
 Author-email: Alex Paskal <alexcpaskal@gmail.com>
 Requires-Python: >=3.12
 Requires-Dist: fastapi>=0.141.1
@@ -15,6 +15,8 @@ Description-Content-Type: text/markdown
 
 A command-line task manager with AI features.
 
+📖 **Full documentation:** <https://taskai.readthedocs.io>
+
 ```bash
 pip install taskai-cli
 ```
@@ -32,10 +34,11 @@ task setup
 
 ```
 task                              interactive mode
+task help                         show every command
+task examples                     worked command sequences for common workflows
 
 task show all                     show everything
 task show <id|name>               show a specific item
-task show <id1>,<id2>,...         show multiple items
 
 task create <name>                create a top-level item
 task add <parent> <name>          add a child item
@@ -44,27 +47,31 @@ task rename <id> <new name>       rename an item
 task move <item> <new parent>     reparent an item
 task complete <id>                mark complete (recursive)
 task delete <id|name>             delete by id or name
-task delete completed             delete all completed items
+task clear                        delete all completed items
 task clear <parent>               delete completed under a parent
 
 task comment <id> <text>          add a comment
-task depend <src_id> <dst_id>     src depends on dst
-task link <parent> <item>         soft-link two items
+task link <parent> <item>         soft-link an item under a second parent
+task unlink <parent> <item>       remove a soft-link
 task reorder <id1> before|after <id2>
 
 task status <id> <text>           set a status string
 task pomo <on_mins> <off_mins>    pomodoro timer
 
 task ai <prompt>                  natural language → commands
+  --context <path[,path...]>      fold file contents into the prompt
+  --reasoning <level>             model thinking effort: minimal|low|medium|high|disable|none
 task ai headstart <id>            AI suggests next step, saved as comment
 
+task browser                      launch the web UI (see below)
+
 task config show                  list current config
 task config set <key> <value>     set a config value
 task config get <key>             get a config value
 task config pop <key>             remove a config value
 
 task repair                       repair the database
-task nuke                         delete all data
+task nuke                         delete all data (asks to confirm)
 ```
 
 ### Item fields
@@ -78,44 +85,68 @@ Pass any of these as `--field value` to `create`, `add`, or `update`:
 | `priority` | integer | `--priority 2` |
 | `status` | string | `--status "in progress"` |
 | `completed` | bool | `--completed true` |
-| `depends_on` | comma-separated ids | `--depends_on 3,7` |
 
 ---
 
 ## Config
 
-AI features require a model, set as a `provider/model` string (via [litellm](https://github.com/BerriAI/litellm)),
-plus that provider's credentials set as environment variables (e.g. `GEMINI_API_KEY`, `OPENAI_API_KEY`).
-`task setup` will walk you through picking a provider and model and tell you which env vars it needs.
+AI features need a model. `task setup` walks you through choosing a provider
+and model, then tells you which environment variable(s) to set:
+
+```text
+$ task setup
+Beginning setup
+  1. openai
+  2. anthropic
+  3. gemini
+  4. vertex_ai
+  5. groq
+  ...
+  20. ollama
+
+Select a provider (number or name): 3
+  1. gemini-3.7-flash
+  2. gemini-3.1-pro-preview
+  3. gemini-3.6-flash
+  4. gemini-3.5-flash-lite
+  5. gemini-2.5-pro
+
+Select a model for 'gemini' (number or name): 1
+Storing: gemini/gemini-3.7-flash
+Make sure these environment variables are set:
+  GEMINI_API_KEY
+Setup complete! Use 'task config set|get|list' to interact with your configuration options
+```
+
+Either prompt also accepts free-typed text, so you can pick a model newer than
+the built-in menu.
+
+Or set it directly — a `provider/model` string, using
+[litellm](https://github.com/BerriAI/litellm)'s naming:
 
 ```bash
-task config set AI_MODEL gemini/gemini-2.0-flash
+task config set AI_MODEL <provider>/<model>   # e.g. gemini/gemini-3.7-flash
 ```
 
 ---
 
-## Example
+## Web UI
 
-```
-task create "Today"
-task add "Today" "Morning run"
-task add "Today" "Review pull requests" --status "blocked"
-task add "Today" "Call dentist" --due_by 08-02-2026
-task show "Today"
-task complete 4
-task show "Today"
-task exit
+```bash
+task browser
 ```
 
-Or:
+Launches a local web server with a canvas view of your item tree:
 
-```bash
-task ai "add a task called 'Reply to Alex' under Today, and mark the dentist task as done"
-```
+- **pan / zoom** the graph; completed items are tinted green, and soft-links
+  (`task link`) show as dashed "shadow" copies under their host item
+- **click a node** to open an edit panel — each field writes back immediately,
+  there's no save button
+- **console** at the bottom for typing raw `task` commands against the same data
 
 ---
 
-## Another Example
+## Examples
 
 ```bash
 task create "Launch website"
@@ -134,4 +165,12 @@ task ai headstart 3
 # mark something done and clean up
 task complete 2
 task clear "Launch website"
-```
+```
+
+Or drive it entirely from a prompt:
+
+```bash
+task ai "add a task called 'Reply to Alex' under Launch website, and mark the hosting task as done"
+```
+
+Run `task examples` for more worked sequences.