hiiro 0.1.367 → 0.1.369

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9f4708a4c90c2b72668cc5f42c6a28ad1b06c5833986e45eb547e8215f6ec64e
-  data.tar.gz: e870242d4e60b6dd633a280733456ade72d0cdf999b733e39223cbf46647dd2f
+  metadata.gz: 3565b794ff2dd7e61d45810479a5bed58621c54ac4e3afa51f12adeb9626c639
+  data.tar.gz: 75073d800fee5ab0185eea6062b39961b7f68c4200a1f428f8ac72f090edabd5
 SHA512:
-  metadata.gz: 184881124f6711f940214c20510527d1790c800ea56e3e3b37b74a7060f71aeb564300b12179419cf0ec0099a041df6189ddb41137f132b5c0e0b4f691742572
-  data.tar.gz: 1372760dfa76e22fe9305c83c826b72fd2f0e2328b2cd6c0c41f0b1f8baf23720460c150aeb66c434bd666a8779a49f40a7d2338482216dc8edc9bf89a2d1b40
+  metadata.gz: 9435184f96a4b71ea43ecb873180411326aaf5ebb866153748be8f9e5fdbe7605d92c71df4506498029772f510374e91034ce74748663a9d1b4de8ff264d5c17
+  data.tar.gz: 8a8a5539086877c051ce05639fdb2c72a626c88d92284981c551fff2a3b6a8d6e048250d969b6fedb4e811c720da0a4c58a1e6aa97dddebeba1a478f1c26194e

data/CHANGELOG.md

@@ -2,9 +2,31 @@
 
 ## [Unreleased]
 
+## [0.1.369] - 2026-09-14
+
+### Added
+- `t switch NAME` matches live Herdr workspaces that belong to no task, and the fuzzy finder for `switch` lists tasks plus those workspaces, numbering duplicate workspace names
+- `t` opens the fuzzy finder instead of failing when a task prefix is ambiguous or no current task can be resolved, when stdin is a terminal
+
+## [0.1.368] - 2026-09-14
+
+### Added
+- `h herdr`: Herdr plugin exposing `t` through keybound popups for fuzzy task switching, todo capture, todo copying, task shell, and nvim access; `h herdr install` copies and links the plugin, `h herdr keys` prints keybindings
+
+### Changed
+- Task CLI grammar converted to command-first: `t COMMAND [TASK] [ARGS...]` matching the legacy `h task` rule where the first positional word is the task when it names one (exact or unique prefix), otherwise the current task is used and the word stays in the payload
+
+### Removed
+- `Hiiro::TaskScope` class; task resolution logic integrated into `Hiiro::TaskCli`
+
 ## [0.1.367] - 2026-09-14
 
 ### Added
+- `t use TASK` (alias `pin`) saves the fallback task; `t current` now only prints
+- `-t TASK` / `-f` task options on every `t` command that acts on a task
+- `h herdr`: a Herdr plugin (`herdr-plugin/herdr-plugin.toml`) with actions `hiiro.switch`, `hiiro.todo-add`, `hiiro.todos`, `hiiro.shell`, and `hiiro.nvim` that open a popup running `t`; `h herdr install` copies and links it, `h herdr keys` prints keybindings
+- `Hiiro::TestHarness` understands `add_cmd`, `add_option`, `add_flag`, and `opts`
+- `t TASK todo show ID` and `tt TASK show ID` print one todo's text; `todo ls --plain` prints text only
 - Add `h env add NAME VALUE` and `h alias add NAME COMMAND...` to append safely quoted shell definitions, preferring existing zsh module files and falling back to the root dotfiles. Use native Hiiro options, including `opts.global` and `--`.
 - Add `h bin add NAME [COMMAND ...]` to generate executable `Hiiro.run` templates with optional empty `add_cmd` blocks. Serialize command names as Ruby symbols and refuse existing files or symlinks.
 - `t ls` and `t list` root commands list tasks like bare `t`
@@ -20,6 +42,8 @@
 - `h task start` and worktree listing failed with "Not a directory" when `~/work/.git` is a gitfile; git now runs in the parent directory
 
 ### Changed
+- `t` grammar is now command-first, `t COMMAND [TASK] [ARGS...]`, matching the old `h task` rule: the first positional word is the task when it names one (exact or unique prefix), otherwise the current task is used and the word stays in the payload. `.` is the current task, `-` selects orphan todos. `tt ...` is `t todo ...`. `Hiiro::TaskScope` is removed
+- `t todo add` no longer creates tasks; only `t new NAME` does
 - Move the task CLI into `lib/hiiro/task_cli.rb` (`Hiiro::TaskCli`); `exe/t` and `exe/tt` are thin `Hiiro.run` launchers and `bin/t`, `bin/tt` are symlinks
 - `t` requires `hiiro` like other bins instead of editing the load path; `task_scope` and `task_sessions` load with `hiiro`
 - `t` errors print without a backtrace; task, scope, and session errors subclass `Hiiro::Error`
@@ -79,4 +103,4 @@
 - Focus the exact Herdr pane through the socket API and read the CLI's plain-text pane output without JSON parsing.
 - Restore the missing `Hiiro::Bins` helper so `require "hiiro"` boots and commands like `h jumplist record` dispatch correctly.
 - Make Hiiro's Ruby requirement explicit as Ruby 3.2+ and have rbenv-wide gem installs skip incompatible Ruby versions.
-- Update the publish script to preserve the Ruby support constant, run only on supported Ruby, and install releases only into compatible rbenv versions.
+- Update the publish script to preserve the Ruby support constant, run only on supported Ruby, and install releases only into compatible rbenv versions.

data/README.md

@@ -64,66 +64,54 @@ h ping
 `t` and `tt` are gem executables in `exe/`, installed alongside `h`. They are thin
 `Hiiro.run` launchers over `Hiiro::TaskCli` in `lib/hiiro/task_cli.rb`, which uses
 the `add_cmd` DSL and existing task records. `bin/t` and `bin/tt` are symlinks to
-the `exe/` files for running from a checkout with `ruby -Ilib bin/t`. `t NAME new`
-creates a task and its notes directory without creating a Git worktree.
-
-Use `t TASK COMMAND...`. Bare `t`, `t ls`, or `t list` lists every task, including
-done and archived tasks, with the count of open todos after each name. `t TASK`
-shows a task. Only exact root `t help` displays generic usage and
-native scoped help without looking up a task. Other first words are task
-references, even `new`, `show`, `edit`, or `he`.
-
-Task references prefer an exact name, then a unique case-sensitive prefix.
-Ambiguous prefixes fail. `t NAME new` creates the exact name instead of resolving
-a prefix. An unknown name is otherwise an error, except that `t NAME todo add`
-can create the task with its first todo.
-
-Use `.` for the current task. Selection checks the calling Herdr workspace,
-then the current directory, then the saved task. Stale or ambiguous context is
-an error. `t TASK current` saves a named selection without focusing a terminal;
-`t . current` only prints it. `t TASK switch` and `t TASK workspace` focus or
-create the task workspace and save a named selection only after success.
-`--show` inspects without changing focus or the saved task.
+the `exe/` files for running from a checkout with `ruby -Ilib bin/t`. `t new NAME`
+creates a task and its notes directory; `t tree new NAME` adds a Git worktree.
+
+Use `t COMMAND [TASK] [ARGS...]`. Bare `t`, `t ls`, or `t list` lists every task,
+including done and archived tasks, with the count of open todos after each name.
+Commands that act on a task take it from the first positional argument when
+that word names a task (exact or unique case-sensitive prefix); otherwise the
+current task is used and the word stays in the payload, exactly like the old
+`h task` commands. `-t TASK` forces a task, `-f` picks one with a fuzzy finder,
+`.` is the current task, and `-` selects orphan todos. On a terminal, an ambiguous
+prefix or a missing current task opens the fuzzy finder; non-interactive runs fail.
+
+The current task is the calling Herdr workspace, then the current directory
+inside a task home, code directory, worktree, or registered directory, then the
+task saved with `t use TASK`. `t switch TASK` focuses or creates the task
+workspace and also saves it. `t current` only prints.
 
 ```sh
-t investigation new
-t investigation next "Inspect the failing request"
-t investigation todo add Compare the retry settings
-tt investigation add Inspect --help output
-t investigation doc new findings
-t investigation doc open findings
-t investigation
-t investigation todo rm 42 # Use an item ID printed by show or todo list.
-t investigation current
-t investigation switch
-t investigation workspace --show
-t . next "Write the handoff"
+t new investigation
+t next investigation "Inspect the failing request"
+t todo add investigation Compare the retry settings
+tt add Inspect --help output          # current task
+t doc new investigation findings
+t show investigation
+t todo rm 42                          # an ID printed by show or todo list
+t use investigation
+t switch investigation
+t switch --show
+t next . "Write the handoff"
+t tree new investigation
 ```
 
-A task has one `next_action` and can have multiple independent todos. `t TASK`
-and `t TASK todo` print todos with their IDs, statuses, and text in ID order.
-`t TASK todo rm ID` deletes only that exact decimal ID in the selected scope.
-`tt TASK ...` delegates to `t TASK todo ...`; bare `tt` means `t . todo`, and
-`tt help` displays todo help. Use `t - todo` or `tt -` for orphan todos, including
-`add` and `rm`. `-` is not a task and is invalid outside todo commands.
+A task has one `next_action` and can have multiple independent todos. `t show`
+and `t todo` print todos with their IDs, statuses, and text in ID order.
+`t todo show ID` prints one todo's text and `t todo rm ID` deletes it.
+`tt ...` is `t todo ...`. Use `t todo -` and `tt add - TEXT` for orphan todos.
 
-Every argument after `todo add` is literal text, including flags and `--`,
-except that leading `add -h` or `add --help` displays help. Empty text fails
-without creating a task.
+Every argument after the task in `todo add` is literal text, including flags and
+`--`, except a leading `-h` or `--help`. Empty text fails. Only `t new NAME`
+creates tasks.
 
 Todos share the existing `todos` table with `h todo`. `t` writes only to the
 database and does not rewrite `todo.yml`. Adding or removing a todo does not
 change the task's next action, status, or saved selection. Task completion and
 archival preserve todos. `h task` is a symlink to `t`, so both share one grammar.
 
-`t TASK omp`, `t TASK codex` or `cdx`, and `t TASK claude` or `cld` start fresh
+`t omp [TASK]`, `t codex` or `cdx`, and `t claude` or `cld` start fresh
 native CLI sessions in new focused Herdr tabs. Claude always runs `claude`.
-Only a nonempty prefix of `resume` as the first tool argument changes mode.
-Bare `resume` focuses the unique running instance of that tool in the task
-workspace, or launches the native resume picker if none is running. Multiple
-running matches are an error. With an ID or any other arguments after `resume`,
-the command always opens a new tab and passes those arguments to the native CLI.
-All other arguments, including `--help`, are tool flags, not `t` flags.
 
 Tasks can share an existing directory, including a worktree. `t` does not change
 Git state or promise task-isolated persisted AI sessions in shared directories.
@@ -141,6 +129,7 @@ See the [task command reference](docs/t.md) for all commands and the [workflow i
 | `h setup` | Install plugins and subcommands to system paths |
 | `h edit` | Open the h script in your editor |
 | `h alert` | macOS desktop notifications via terminal-notifier |
+| `h herdr` | Herdr plugin for `t`: fuzzy task switcher, todo capture, todo copy, task shell and nvim popups (`h herdr install`) |
 | `h task` | Same program as `t`: task records, todos, worktrees (`t NAME tree new`), and Herdr workspaces |
 
 ### External Subcommands

data/bin/h-alias

@@ -0,0 +1,28 @@
+#!/usr/bin/env ruby
+
+require 'hiiro'
+
+Hiiro.run do
+  add_flag :global, short: :g, desc: 'Create a global zsh alias'
+
+  add_cmd :add, args: ['NAME', 'COMMAND...'], opts: [:global] do
+    abort 'Usage: h alias add [--global|-g] NAME COMMAND...' unless opts.args.length >= 2
+    name, *command_args = opts.args
+    abort 'Invalid alias name' unless /\A[A-Za-z0-9_.][A-Za-z0-9_.-]*\z/.match?(name)
+    command = command_args.length == 1 ? command_args.first : Shellwords.join(command_args)
+    quoted = "'" + command.gsub("'") { "'\\''" } + "'"
+
+    home = ENV.fetch('HOME')
+    path = File.join(home, '.zshrc.d', 'aliases.zsh')
+    path = File.join(home, '.zshrc') unless File.file?(path)
+
+    File.open(path, 'a+', 0o600) do |file|
+      unless file.size.zero?
+        file.seek(-1, IO::SEEK_END)
+        file.write("\n") unless file.read(1) == "\n"
+      end
+      file.write("alias #{opts.global ? '-g ' : ''}#{name}=#{quoted}\n")
+    end
+    puts "Added alias to #{path}"
+  end
+end

data/bin/h-env

@@ -0,0 +1,25 @@
+#!/usr/bin/env ruby
+
+require 'hiiro'
+
+Hiiro.run do
+  add_cmd :add, args: %i[NAME VALUE] do
+    abort 'Usage: h env add NAME VALUE' unless opts.args.length == 2
+    name, value = opts.args
+    abort 'Invalid environment variable name' unless /\A[A-Za-z_][A-Za-z0-9_]*\z/.match?(name)
+
+    home = ENV.fetch('HOME')
+    path = File.join(home, '.zshenv.d', 'vars.zsh')
+    path = File.join(home, '.zshenv') unless File.file?(path)
+    escaped = value.gsub(/["\\$`]/) { |char| "\\#{char}" }
+
+    File.open(path, 'a+', 0o600) do |file|
+      unless file.size.zero?
+        file.seek(-1, IO::SEEK_END)
+        file.write("\n") unless file.read(1) == "\n"
+      end
+      file.write("export #{name}=\"#{escaped}\"\n")
+    end
+    puts "Added environment variable to #{path}"
+  end
+end

data/bin/h-herdr

@@ -0,0 +1,156 @@
+#!/usr/bin/env ruby
+
+require 'hiiro'
+require 'fileutils'
+
+# Herdr plugin glue for the t task CLI. The plugin manifest lives in the gem's
+# herdr-plugin/ directory; `h herdr install` copies it to ~/.config/hiiro/herdr-plugin
+# and links it with `herdr plugin link`. Actions run headless behind keybindings and
+# open the plugin popup; `h herdr popup` runs inside that popup with a real TTY.
+
+PLUGIN_ID = 'hiiro'
+ACTIONS = %w[switch todo-add todos shell nvim].freeze
+INSTALL_DIR = Hiiro::Config.config_dir('herdr-plugin')
+SOURCE_DIR = File.expand_path('../herdr-plugin', File.dirname(File.realpath(__FILE__)))
+KEYS_SNIPPET = <<~TOML
+  # Hiiro task actions (h herdr keys)
+  [[keys.command]]
+  key = "prefix+t"
+  type = "plugin_action"
+  command = "hiiro.switch"
+  description = "switch to task"
+
+  [[keys.command]]
+  key = "prefix+shift+a"
+  type = "plugin_action"
+  command = "hiiro.todo-add"
+  description = "add todo"
+
+  [[keys.command]]
+  key = "prefix+shift+y"
+  type = "plugin_action"
+  command = "hiiro.todos"
+  description = "copy a todo"
+
+  [[keys.command]]
+  key = "prefix+shift+s"
+  type = "plugin_action"
+  command = "hiiro.shell"
+  description = "task shell popup"
+
+  [[keys.command]]
+  key = "prefix+shift+e"
+  type = "plugin_action"
+  command = "hiiro.nvim"
+  description = "task notes in nvim"
+TOML
+
+def herdr_bin
+  ENV['HERDR_BIN_PATH'] || 'herdr'
+end
+
+def source_dir
+  return SOURCE_DIR if File.exist?(File.join(SOURCE_DIR, 'herdr-plugin.toml'))
+  gem_root = Gem.loaded_specs['hiiro']&.full_gem_path
+  gem_root && File.join(gem_root, 'herdr-plugin')
+end
+
+Hiiro.run(*ARGV, external_commands: false) do
+  add_cmd(:install) do
+    no_args = opts.args.empty?
+    raise Hiiro::Error, 'h herdr install takes no arguments' unless no_args
+    src = source_dir
+    raise Hiiro::Error, 'Plugin manifest not found; reinstall the hiiro gem' unless src
+    FileUtils.mkdir_p(File.dirname(INSTALL_DIR))
+    FileUtils.rm_rf(INSTALL_DIR)
+    FileUtils.cp_r(src, INSTALL_DIR)
+    puts "Copied plugin to #{INSTALL_DIR}"
+    linked = system(herdr_bin, 'plugin', 'link', INSTALL_DIR)
+    puts(linked ? 'Linked plugin "hiiro" in Herdr' : 'Plugin already linked or link failed; run: herdr plugin list')
+    puts "\nAdd keybindings to ~/.config/herdr/config.toml (h herdr keys prints them), then run:"
+    puts '  herdr server reload-config'
+  end
+
+  add_cmd(:uninstall) do
+    system(herdr_bin, 'plugin', 'unlink', PLUGIN_ID)
+    FileUtils.rm_rf(INSTALL_DIR)
+    puts "Removed #{INSTALL_DIR}"
+  end
+
+  add_cmd(:keys) { puts KEYS_SNIPPET }
+
+  add_cmd(:actions) { ACTIONS.each { |name| puts "hiiro.#{name}" } }
+
+  # Headless: bound to a key, opens the popup with the chosen action.
+  add_cmd(:action, args: %i[name]) do
+    name = opts.args.first
+    raise Hiiro::Error, "Unknown action #{name}; one of #{ACTIONS.join(', ')}" unless ACTIONS.include?(name)
+    size = %w[shell nvim].include?(name) ? %w[--width 90% --height 90%] : []
+    system(herdr_bin, 'plugin', 'pane', 'open', '--plugin', PLUGIN_ID, '--entrypoint', 'popup',
+           '--env', "HIIRO_HERDR_ACTION=#{name}", *size, '--focus')
+  end
+
+  # Runs inside the popup pane (real TTY, HERDR_WORKSPACE_ID set by Herdr).
+  add_cmd(:popup) do
+    name = ENV['HIIRO_HERDR_ACTION'] || opts.args.first
+    raise Hiiro::Error, "Set HIIRO_HERDR_ACTION to one of #{ACTIONS.join(', ')}" unless ACTIONS.include?(name)
+    run_popup(name)
+  end
+
+  def tasks
+    Hiiro::TaskRecord.all_as_list.reject { |task| %w[done archived].include?(task.task_status) }
+  end
+
+  def current_task_name
+    Hiiro::CurrentTask.new(herdr: -> { herdr_client }, pin: true).resolve&.name
+  end
+
+  def pick_task(prompt_current: true)
+    current = prompt_current && current_task_name
+    names = tasks.map(&:name)
+    names = [current, *names.reject { |n| n == current }] if current
+    raise Hiiro::Error, 'No tasks; create one with t NAME new' if names.empty?
+    choice = fuzzyfind(names)
+    raise Hiiro::Error, 'No task selected' if choice.nil? || choice.strip.empty?
+    choice.strip
+  end
+
+  def pause(message)
+    $stderr.puts message
+    sleep 2
+  end
+
+  def run_popup(name)
+    case name
+    when 'switch'
+      task = pick_task(prompt_current: false)
+      system('t', 'switch', task) || pause("t switch #{task} failed")
+    when 'todo-add'
+      task = pick_task
+      print "Todo for #{task}: "
+      text = $stdin.gets.to_s.strip
+      raise Hiiro::Error, 'No todo text' if text.empty?
+      system('t', 'todo', 'add', '-t', task, text) || pause('todo add failed')
+      sleep 1
+    when 'todos'
+      task = current_task_name || pick_task
+      items = Hiiro::TodoItem.where(task_name: task, subtask_name: nil).exclude(status: %w[done skip]).order(:id).all
+      raise Hiiro::Error, "No open todos for #{task}" if items.empty?
+      text = fuzzyfind_from_map(items.to_h { |item| ["#{item.id}  #{item.text}", item.text] })
+      raise Hiiro::Error, 'No todo selected' unless text
+      Hiiro::Shell.pipe(text, 'pbcopy')
+      puts "Copied: #{text}"
+      sleep 1
+    when 'shell'
+      exec('t', 'sh')
+    when 'nvim'
+      task = Hiiro::CurrentTask.new(herdr: -> { herdr_client }, pin: true).resolve!
+      FileUtils.mkdir_p(task.home)
+      Dir.chdir(task.home)
+      exec(ENV['EDITOR'] || 'nvim', '.')
+    end
+  rescue Hiiro::Error => e
+    pause("ERROR: #{e.message}")
+    exit 1
+  end
+end

data/docs/h-herdr.md

@@ -0,0 +1,41 @@
+# h herdr
+
+Expose the `t` task CLI inside Herdr as keybound actions. Each action opens a session-modal popup that runs `h herdr popup`, so fuzzy pickers and editors get a real TTY without disturbing the tiled layout.
+
+## Install
+
+```bash
+h herdr install              # copies herdr-plugin/ to ~/.config/hiiro/herdr-plugin and runs herdr plugin link
+h herdr keys                 # prints [[keys.command]] entries to paste into ~/.config/herdr/config.toml
+herdr server reload-config
+```
+
+`h herdr uninstall` unlinks the plugin and removes the copied directory. Requires Herdr 0.7.4 or newer, and `sk` or `fzf` on `PATH`.
+
+## Actions
+
+| Action | Default key | Popup behavior |
+|---|---|---|
+| `hiiro.switch` | `prefix+t` | Fuzzy-pick an active or waiting task, then `t NAME switch` |
+| `hiiro.todo-add` | `prefix+shift+a` | Fuzzy-pick a task (current task first), type the todo text, then `t NAME todo add TEXT` |
+| `hiiro.todos` | `prefix+shift+y` | Fuzzy-pick an open todo of the current task and copy its text to the clipboard |
+| `hiiro.shell` | `prefix+shift+s` | 90% popup running `t sh` in the current task's start directory |
+| `hiiro.nvim` | `prefix+shift+e` | 90% popup running `$EDITOR` (default `nvim`) in the current task's notes home |
+
+The current task resolves through `Hiiro::CurrentTask`: the popup's Herdr workspace, then the working directory, then the task saved with `t use TASK`. Errors print in the popup for two seconds before it closes.
+
+## Subcommands
+
+| Command | Behavior |
+|---|---|
+| `h herdr install` | Copy the manifest from the gem, link it in Herdr, print next steps |
+| `h herdr uninstall` | Unlink and remove the copy |
+| `h herdr keys` | Print the keybinding snippet |
+| `h herdr actions` | List action ids |
+| `h herdr action NAME` | Headless: open the popup for NAME (what the manifest binds) |
+| `h herdr popup` | Runs inside the popup; reads `HIIRO_HERDR_ACTION` |
+
+## Files
+
+- `herdr-plugin/herdr-plugin.toml` in the gem: manifest with five `[[actions]]` and one `[[panes]]` popup entrypoint
+- `bin/h-herdr`: actions, popup logic, install and keys helpers

data/docs/h-task.md

@@ -8,185 +8,28 @@ Task todos use the existing `todos` table shared with `h todo`. `t` writes to th
 
 ## t
 
-The command implementation is `Hiiro::TaskCli` in `lib/hiiro/task_cli.rb`; `exe/t` and `exe/tt` are gem executables that call `Hiiro::TaskCli.setup` and `Hiiro::TaskCli.setup_todo` from `Hiiro.run`. Installing the gem installs both. `tt` runs the todo scope in-process. `t` does not run `h task` or discover legacy `t-*` executables.
-
-The grammar is `t TASK COMMAND...`. Bare `t`, `t ls`, or `t list` lists all tasks, including done and archived tasks, with open todo counts. `t TASK` shows the task. Only exact root `t help` displays generic usage and native scoped help without looking up a task. First words such as `new`, `show`, `edit`, `pry`, and `he` are task references, not root commands or help abbreviations.
-
-Named references match an exact name first, then a unique case-sensitive prefix. Ambiguous prefixes are errors. Unknown names fail except with `t NAME new` or `t NAME todo add TEXT...`. Explicit `new` creates exactly `NAME` without prefix resolution. `t TASK help` shows task commands, and `t TASK todo help` shows todo commands. Native command abbreviations apply inside these scopes.
-
-Use `.` to select the current task, including when supplying a payload: `t . next 'Compare the export'`. Selection checks the calling Herdr workspace, then the current directory inside a task home, code directory, or registered directory, then the saved task. Workspace context wins over a conflicting directory. Ambiguous matches and invalid, stale, or conflicting Herdr IDs are errors. Outside Herdr, an unrelated focused workspace does not affect selection. An explicit name bypasses context lookup.
-
-`t TASK current` prints the resolved name and saves a named selection without changing terminal focus. `t . current` only prints it. The fallback is a `PinRecord` with `command='t'`, `key='current_task'`, and the task ID as a JSON integer in `value_json`. A missing saved task is an error when selection reaches that fallback. Reads and workspace opens through `.` do not replace it.
-
-### Task records
-
-```text
-t
-t TASK
-t TASK show
-t TASK current
-t NAME new
-t TASK next [TEXT...] [--clear]
-t TASK status [active|waiting|done|archived]
-t TASK waiting [TEXT...] [--clear]
-t TASK done
-t TASK archive
-```
-
-Bare `t`, `t ls`, and `t list` list tasks regardless of context or the saved task, showing each name with its open todo count, e.g. `prez (3)`. There is no root `new` or `show` action. `next`, `waiting`, and `status` without a payload display the selected task's current value.
-
-`t NAME new` creates a record and `~/notes/work/NAME`. It never creates a Git worktree, moves code, or launches Herdr. Repeating `new` keeps the exact existing record and ensures its home exists. Names contain 1-120 ASCII letters, digits, dots, underscores, or hyphens and start with a letter or digit. Existing names that contain other characters remain usable, with those characters percent-encoded in the computed home directory name.
-
-Setting waiting text changes status to `waiting`. Clearing that text changes a waiting task back to `active`. `done` and `archive` change status and record timestamps. They never remove todos, a task home, a file, a directory, a link, or a workspace. `t TASK status active` reopens a task.
-
-```bash
-t audit-invoices new
-t audit-invoices next 'Compare the September export'
-t audit-invoices waiting 'Finance approval'
-t audit-invoices waiting --clear
-t audit-invoices done
-t audit-invoices
-```
-
-### Task todos
-
-```text
-t TASK todo
-t TASK todo list
-t TASK todo ls
-t TASK todo add TEXT...
-t TASK todo rm ID
-tt TASK [COMMAND...]
-tt
-tt help
-```
-
-`tt TASK ...` delegates to `t TASK todo ...`. Bare `tt` means `t . todo`, and `tt help` shows todo help without task lookup. The default todo action is listing. `t - todo` and `tt -` select orphan todos, with `add` and `rm` available in that scope. `-` is invalid outside todo commands and never creates a task.
-
-If a named `todo add` finds no match, it creates the task using `new` validation and home rules, then adds one todo with status `not_started`. Task and todo database writes use one immediate SQLite transaction. Other todo actions never create tasks.
-
-Every token after `add` is literal text, including flags and `--`, except that leading `add -h` or `add --help` displays native option help. The tokens are joined with spaces. Missing, empty, or whitespace-only text fails before task creation.
-
-```bash
-t audit-invoices todo add Compare the September export
-tt audit-invoices add Inspect --help output
-t audit-invoices todo
-t audit-invoices todo rm 42
-tt - add Buy printer paper
-```
-
-Use an ID printed by `show` or todo listing in place of `42`. `rm` accepts exactly one decimal database ID belonging to the selected scope, not a list position or suffix. Missing, invalid, or extra arguments fail.
-
-Task display and todo listing print each matching item's ID, status, and text in ID order. Matching uses the full task name exactly, including legacy rows with both `task_name` and `subtask_name`. A parent task does not include its subtasks' todos. New task todos store the full task name in `task_name` and leave `subtask_name` unset. Orphan rows leave both unset.
-
-Each task still has one independent `next_action`. Adding or removing todos does not change that field, task status, or saved selection. `t` has no todo-completion command or automatic next-action promotion. The separate `h task` and `h todo` commands keep their existing behavior.
-
-### Directory, link, PR, and file references
-
-```text
-t TASK directory add PATH [--primary] [--label LABEL]
-t TASK directory list
-t TASK directory open [ID|PATH|LABEL]
-t TASK link add URL [--kind general|issue|thread] [--label LABEL]
-t TASK link list [--kind general|issue|thread]
-t TASK link open [ID|URL|LABEL]
-t TASK pr add URL [--label LABEL]
-t TASK pr list
-t TASK pr open [ID|URL|LABEL]
-t TASK file add PATH [--label LABEL]
-t TASK file list
-t TASK file open [ID|PATH|LABEL]
-```
-
-Directory and file attachments must already exist. `add` stores their canonical paths without moving or copying anything. Repeating an identical attachment does not create another reference. `--primary` marks an attached directory as the default code directory for new workspace tabs and panes. An existing directory can be a Git worktree. Registering it does not create a worktree or alter sparse checkout.
-
-Links must be absolute HTTP or HTTPS URLs. `link list` includes PR references unless a kind filter is present. PRs use the same resource storage as other links and do not require a Git repository or provider API.
-
-`file list` also discovers files in the task home, including documents, without registration. Home files can be opened by a relative path or an unambiguous basename. An omitted open selector works only when exactly one resource matches. Otherwise, the command requires an ID, path, URL, or unique label.
-
-`open` uses the operating system's default application. Attachments remain references even after task completion. List commands also accept `ls`. Leaf help, such as `t audit-invoices directory add --help`, lists options without running the action.
-
-### Documents
-
-```text
-t TASK doc new NAME [TITLE...]
-t TASK doc list
-t TASK doc open [NAME]
-```
-
-`doc new` creates a Markdown file in the task home with an initial heading. It never overwrites an existing file. Documents have a stable task-ID prefix, such as `task-42-investigation.md`, to avoid collisions in `mdoc`'s shared HTML output directory. `t TASK doc open investigation` accepts the short name and invokes `mdoc`. Existing Markdown files in the task home also appear without registration.
-
-Task creation, metadata, references, and document creation/listing work without Git or Herdr when a named task is supplied. Document reading requires `mdoc` on `PATH` and its existing configuration.
-
-### Herdr workspaces, tabs, and panes
-
-```text
-t TASK workspace [--directory PATH]
-t TASK switch [--directory PATH]
-t TASK workspace --show
-t TASK switch --show
-t TASK tab list
-t TASK tab new [LABEL] [--directory PATH] [--command COMMAND]
-t TASK tab open ID|LABEL
-t TASK pane list
-t TASK pane open ID|LABEL
-t TASK pane read ID|LABEL
-t TASK pane run ID|LABEL -- COMMAND...
-t TASK pane split ID|LABEL [--direction right|down] [--directory PATH] [--command COMMAND]
-```
-
-These commands require a running Herdr server. `t TASK workspace` and its `switch` alias focus the workspace with the task's label or create one. They save a named task only after a successful switch. `t . workspace` leaves the saved fallback unchanged. A new workspace starts in the explicit directory, the primary code directory, the legacy worktree, or the task home, in that order. `--directory` changes that operation's start directory without changing stored attachments.
-
-`--show` queries the current tabs and panes without saving, focusing, or creating a workspace. `workspace` and `switch` are direct commands, not groups. Native Hiiro abbreviation matching accepts `t TASK wor`.
-
-Tab and pane selectors must belong to the selected task's workspace. Duplicate labels require a live ID. No pane or tab ID is stored as durable task identity. Task workspace labels follow Herdr's dot-to-underscore normalization. Colliding task or workspace labels are errors rather than fuzzy matches.
-
-Use `--` before literal command arguments that begin with a dash:
-
-```bash
-t audit-invoices pane run PANE_ID -- printf '%s\n' --example
-```
-
-### Native AI sessions
-
-`t TASK omp`, `t TASK codex` or `cdx`, and `t TASK claude` or `cld` create new focused tabs in the task workspace. They launch the native `omp`, `codex`, and `claude` executables, respectively. The workspace is created if needed. Fresh sessions are the default.
-
-Only the first tool argument can select resume mode. A nonempty prefix of `resume`, such as `r`, `res`, or `resume`, consumes that token. OMP and Claude receive `--resume`; Codex receives its `resume` subcommand.
-
-With no remaining arguments, resume focuses the unique genuinely running tool in that workspace, using Herdr's agent metadata rather than the tab label. Multiple running matches are an error that reports their IDs. If none is running, a new tab launches the native resume picker.
-
-With any remaining arguments, resume always opens a new tab and forwards those arguments unchanged. Session IDs and options belong to the native CLI. Other arguments, including `--help` and `--`, also pass through unchanged. `t` does not inject model, permission, continue, or fresh-session flags.
-
-```bash
-t audit-invoices omp
-t audit-invoices cdx r
-t audit-invoices cld resume SESSION_ID
-t audit-invoices codex resume --help
-t audit-invoices claude --help
-```
-
-The launcher scopes live-pane lookup to the task workspace. Persisted session discovery remains native CLI behavior and is not necessarily task-isolated when tasks share a directory. `t` performs no auth or API requests and makes no automatic Git changes.
+`h task` is a symlink to `t`, so `h task ARGS...` is `t ARGS...`. The grammar is `t COMMAND [TASK] [ARGS...]`: the command comes first, and commands that act on a task take it from the first positional argument when that word names a task (exact or unique prefix); otherwise the current task is used and the word stays in the payload. `-t TASK` forces a task, `-f` picks one with a fuzzy finder, `.` is the current task, and `-` selects orphan todos. See [t](t.md) for every command.
 
 ## h task
 
-`h task` is the same program as `t`: `bin/h-task` is a symlink to `exe/t`, so `h task ARGS...` behaves exactly like `t ARGS...` with the task-first grammar above. `h subtask` is gone; a subtask is a task named `parent/child`, and `t parent/child tree new` creates its worktree under `~/work/parent/child`.
+`h task` is the same program as `t`: `bin/h-task` is a symlink to `exe/t`, so `h task ARGS...` behaves exactly like `t ARGS...` with the task-first grammar above. `h subtask` is gone; a subtask is a task named `parent/child`, and `t tree new parent/child` creates its worktree under `~/work/parent/child`.
 
 Worktree operations that used to live only under `h task` are now task commands:
 
 | Old | Now |
 |---|---|
-| `h task start NAME [APP] [-s GROUP]` | `t NAME tree new [--app APP] [--sparse GROUP]` (creates the task record if needed, then the worktree, then the Herdr workspace) |
-| `h task switch NAME [APP]` | `t NAME switch [--directory DIR]` |
-| `h task stop NAME` | `t NAME tree rm` (detaches the worktree, keeps the directory, registers it as a directory resource) |
-| `h task resume [TREE]` | `t NAME tree resume [TREE]` |
-| `h task path`, `h task branch`, `h task tree` | `t TASK path`, `t TASK branch`, `t TASK tree` |
-| `h task sh [CMD...]` | `t TASK sh [CMD...]` |
-| `h task cd` | `t TASK cd` |
-| `h task todo ...` | `t TASK todo ...` or `tt TASK ...` |
+| `h task start NAME [APP] [-s GROUP]` | `t tree new NAME [--app APP] [--sparse GROUP]` (creates the task record if needed, then the worktree, then the Herdr workspace) |
+| `h task switch NAME [APP]` | `t switch NAME [--directory DIR]` |
+| `h task stop NAME` | `t tree rm NAME` (detaches the worktree, keeps the directory, registers it as a directory resource) |
+| `h task resume [TREE]` | `t tree resume NAME [TREE]` |
+| `h task path`, `h task branch`, `h task tree` | `t path [TASK]`, `t branch [TASK]`, `t tree [TASK]` |
+| `h task sh [CMD...]` | `t sh [TASK] [CMD...]` |
+| `h task cd` | `t cd [TASK]` |
+| `h task todo ...` | `t todo ... [TASK]` or `tt ...` |
 | `h task ls` | `t ls` |
-| `h task current` | `t . current` |
+| `h task current` | `t current` |
 | `h task queue`, `service`, `run`, `file` | `h queue`, `h service`, `h run`, `h file` |
 
-`h task tag`, `untag`, `tags`, `sparse`, `from`, `prune`, `apps`, `save`, `status`, and `prs` were not carried over. Tag branches with `h branch tag`, inspect worktrees with `h wtree`, and register an existing directory with `t TASK directory add PATH --primary`.
+`h task tag`, `untag`, `tags`, `sparse`, `from`, `prune`, `apps`, `save`, `status`, and `prs` were not carried over. Tag branches with `h branch tag`, inspect worktrees with `h wtree`, and register an existing directory with `t directory add [TASK] PATH --primary`.
 
-`Hiiro::TaskManager` still holds the worktree creation code that `t TASK tree new` and the shared `Hiiro::CurrentTask` resolver use; `h service`, `h run`, and `h file` keep using it for the current task through `Environment#task`, which now also recognizes a task by its home, primary directory, or registered directories.
+`Hiiro::TaskManager` still holds the worktree creation code that `t tree new` and the shared `Hiiro::CurrentTask` resolver use; `h service`, `h run`, and `h file` keep using it for the current task through `Environment#task`, which now also recognizes a task by its home, primary directory, or registered directories.

data/docs/h.md

@@ -30,6 +30,7 @@ These subcommands are defined directly in `exe/h` or loaded from `lib/`:
 | [`h service`](h-service.md) | Dev service management with Herdr, env files, and service groups | `lib/hiiro/service_manager.rb` |
 | `h setup` | Install plugins and bin scripts to `~/bin` | `exe/h` |
 | [`h task`](h-task.md) | Symlink to `t`: task records, todos, worktrees, and Herdr workspaces | `lib/hiiro/task_cli.rb` |
+| [`h herdr`](h-herdr.md) | Herdr plugin exposing `t` as keybound popups: switch task, add/copy todos, task shell, nvim | `bin/h-herdr`, `herdr-plugin/` |
 | `h version` | Print installed hiiro version (`-a` for all rbenv versions) | `exe/h` |
 
 ## External subcommands