hiiro 0.1.365 → 0.1.367

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5cd9e9d71bc395bd2c2595f8087e46f1ba6ea4e5ec80ae9ea9be9942aeddc15a
-  data.tar.gz: 96f39bc0fe91064bb6a7c95371b7d1105be32daad17883e5a75ec565a617783c
+  metadata.gz: 9f4708a4c90c2b72668cc5f42c6a28ad1b06c5833986e45eb547e8215f6ec64e
+  data.tar.gz: e870242d4e60b6dd633a280733456ade72d0cdf999b733e39223cbf46647dd2f
 SHA512:
-  metadata.gz: ff2f56ae6f5c69db4476308c1f52eff96504b8ce52b8fb1d015a4ade478e3000e075ac0e8a737d2fc03b9bb16108ba6408ca7eb22af76965780addf528f94758
-  data.tar.gz: f15c1f626b4c6b7ffccfc62559517a35d75a0f0e10ac1a72601401b7b953231ec2e9df4495946c9724d46d7ce3d2d9d2b26826f4f4119dfadf80041935288c75
+  metadata.gz: 184881124f6711f940214c20510527d1790c800ea56e3e3b37b74a7060f71aeb564300b12179419cf0ec0099a041df6189ddb41137f132b5c0e0b4f691742572
+  data.tar.gz: 1372760dfa76e22fe9305c83c826b72fd2f0e2328b2cd6c0c41f0b1f8baf23720460c150aeb66c434bd666a8779a49f40a7d2338482216dc8edc9bf89a2d1b40

data/CHANGELOG.md

@@ -1,5 +1,58 @@
 # Changelog
 
+## [Unreleased]
+
+## [0.1.367] - 2026-09-14
+
+### Added
+- 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`
+- `Hiiro::Error`: `Hiiro#run` prints only `ERROR: message` for it, no backtrace
+- `builtin_commands: false` option for `Hiiro.run`/`run_child` to skip the automatic `pry` and `edit` commands
+- `Hiiro#open_default(target)` opens a path or URL with `open`/`xdg-open`
+- `t` and `tt` are gem executables (`exe/t`, `exe/tt`) installed with Hiiro
+- `t TASK tree new|rm|resume`, `t TASK tree`, `t TASK path`, `t TASK branch`, `t TASK sh`, and `t TASK cd` bring worktree and shell commands from `h task` into `t`; subtasks are `parent/child` names
+- `Hiiro::CurrentTask`: one resolver for the current task (Herdr workspace, working directory, saved pin) used by `t` and by `Environment#task`
+- `Hiiro::Git.repo_dir` so worktree commands work when `~/work/.git` is a gitfile pointing at the bare repo
+
+### Fixed
+- `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
+- 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`
+- `t` saves the current task through the `PinRecord` model and resolves resources, documents, tabs, and panes with `Hiiro::Matcher`, accepting unique prefixes and offering fuzzyfind when no reference is given
+- `tt` runs the todo scope in-process instead of exec'ing `t`
+- `h task` is now a symlink to `t` (`bin/h-task` -> `exe/t`); the inline `h task` and `h subtask` subcommands are gone, and `h task start|stop|resume|switch|sh|cd|path|branch|todo` map to `t` commands (see docs/h-task.md)
+- `Environment#task` also matches the working directory against task homes, primary directories, and registered directories
+- `TaskManager#start_task` uses the extracted `create_tree`
+- Task listing prints aligned columns with the open todo count after each name, e.g. `prez (3)`, plus `next:`/`waiting:` text
+- `ls` and `list` are now reserved root words in `t`; tasks with those exact names need a unique prefix
+
+## [0.1.366] - 2026-09-14
+
+### Changed
+- Implement task-first CLI syntax: `t TASK COMMAND...` replaces `t COMMAND [TASK]...`
+- Task names now precede commands, appearing immediately after `t` or after a group
+- Task resolution prefers exact names, then unique case-sensitive prefixes; ambiguous prefixes fail
+- Move workspace command from `t workspace TASK` to `t TASK switch` (keep `workspace` as alias)
+- Rename implicit task selection to explicit `.` reference; bare `t` lists all tasks without selecting
+- Update `t current TASK` to `t TASK current`; explicit named selections save fallback after success
+- Context resolution checks calling Herdr workspace, then current directory, then saved task; reject ambiguous matches
+
+### Added
+- Task todo management under `t TASK todo` with `add`, `rm`, `list`/`ls` subcommands; todos share existing database with `h todo`
+- `tt TASK ...` shortcut delegates to `t TASK todo ...`; bare `tt` uses current task via `.` selection
+- Orphan todo scope with `t - todo` and `tt -` for unassigned todos; `-` invalid outside todo commands
+- Native AI session launches via `t TASK omp`, `codex`/`cdx`, and `claude`/`cld` for fresh tool instances
+- Resume mode with first-argument prefix matching (e.g., `r`, `res`, `resume`); focuses unique running instance or launches native picker
+- `Hiiro::TaskScope` library for named/current/orphan task reference resolution with cached context
+- `Hiiro::TaskSessions` library for AI tool launch/resume dispatch with Herdr workspace integration
+- New `lib/hiiro/task_scope.rb` and `lib/hiiro/task_sessions.rb` support libraries
+- New `bin/tt` executable for todo shortcut
+
 ## [0.1.365] - 2026-09-13
 
 ### Added
@@ -27,346 +80,3 @@
 - 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.
-
-## [0.1.364] - 2026-09-13
-
-### Fixed
-- Create the publish response log directory before saving Claude's output, preventing release preparation from failing when the directory is absent.
-- Prevent infinite recursion in help directory grouping when command locations span different filesystem-root directories, such as `/Users` and `/Volumes`.
-
-## [0.1.355] - 2026-05-19
-
-### Added
-- `h task from <worktree-path> <task-name>` registers an existing git worktree from any path as a Hiiro task and switches to it.
-
-### Fixed
-- `h task list` now shows external tasks registered with slash-containing names like `menu/ids`.
-
-## [0.1.353] - 2026-04-26
-
-### Added
-- `Hiiro::Tui::ListScreen` for building keyboard-driven full-screen list interfaces
-- `Hiiro::Config.load_yaml` and `Hiiro::Config.yaml_dig` helpers for YAML file loading with nested key access
-
-## [0.1.352] - 2026-04-24
-
-### Added
-- `h claude all|agents|commands|skills` now support `--absolute/-a` to print absolute tool paths; skill matches resolve to `SKILL.md`
-
-### Fixed
-- `h capture path <num>` now prints the path of the Nth most recent capture (was always printing the captures dir regardless of args)
-- `h capture new` / `h capture file` now record to the DB even when interrupted (Ctrl-C, exception) so partial captures show up in `h capture ls`. Interrupted captures display with the existing `?` glyph and `(exit interrupted)` message.
-- `h pane splitv/splith` subcommand mappings corrected
-- Corrected `REPO_PATH` constant from `.bare` to `.git`
-
-## [0.1.350] - 2026-04-18
-
-### Added
-- `h-capture` command and `Hiiro::Capture` module for clipboard/selection capture
-
-### Changed
-- Optimize `Hiiro::Shell::Result#plain_text` and `#lines` with instance-level caching
-- Refactor `Shell::Result#lines` to use `String#lines(chomp: true)` for improved line handling
-- Reduce Claude API effort to `low` in publish script for faster changelog generation
-
-## [0.1.349] - 2026-04-17
-
-### Removed
-- `h task branches` and `h task wtrees` convenience subcommands; use `h branch` and `h wtree` directly instead
-
-## [0.1.348] - 2026-04-17
-
-### Added
-- `h task path|tree|branch|session` now accept `-a/--all` to print one value per task; trailing positional args act as prefix filters (OR'd together)
-- `h task name` — new subcommand; prints current task name (or selects via fuzzyfind), supports `-a` like the others
-- `h task prune` — drops task records whose worktree dir is missing; dry-run by default, requires `-f` to actually delete
-- `TaskManager#filter_tasks(prefixes)` helper for sorted, prefix-filtered task lists
-
-## [0.1.347] - 2026-04-12
-
-### Added
-- `h pr tags` now supports flags: `--update/-u` (refresh PR status before listing), `--verbose/-v` (multi-line output per PR), `--checks/-C` (show individual check run details)
-
-## [0.1.346] - 2026-04-12
-
-### Added
-- `h pr tags` now accepts optional tag names to filter output to only those tags
-
-## [0.1.345] - 2026-04-12
-
-### Fixed
-- ANSI escape sequence pattern now uses hex escapes (`\x20-\x2f`) instead of literal space-to-slash to avoid ambiguity with the `/` regex delimiter
-
-## [0.1.343] - 2026-04-12
-
-### Added
-- Task subcommands now fall back to `~/proj/*` directories when no task matches
-  - `h task path hiiro` → resolves to `~/proj/hiiro` if no task named "hiiro" exists
-  - Works for: `cd`, `path`, `sh`, `branch`, `tree`, `session`, and any subcommand using `-t` flag
-  - `FallbackTarget` class duck-types as `Task` for seamless integration
-  - Ambiguous project matches print a warning to stderr
-
-### Fixed
-- `Hiiro::Git::Pr.is_link?` is now a class method (was instance method)
-
-## [0.1.342] - 2026-04-08
-
-### Added
-- `h pr review` / `h pr cr` — code review workflow for managing PR sessions in ~/work/codereviews worktree
-- `Hiiro::Git::Pr.from_link(url)` — parse PR number, owner, and repo from GitHub PR links
-- `Hiiro::Git::Pr.from_number(number)` — create PR instances from PR numbers
-- `Hiiro::Git::Pr.is_link?(link)` — validate GitHub PR links
-
-## [0.1.341] - 2026-04-07
-
-### Fixed
-- `h pr view` now defaults to current branch's PR when no PR number is specified
-
-### Changed
-- Update publish script to use `claude-haiku-4-5` model identifier
-
-## [0.1.340] - 2026-04-07
-
-### Fixed
-- `h notify jump` now runs `switch-client` before `select-window`/`select-pane` so jumping to a pane in a different session actually works
-- `h notify ls` and `h notify menu` now auto-prune stale entries for panes that no longer exist
-
-### Added
-- `h notify prune` — explicitly remove all notifications for dead panes
-
-## [0.1.339] - 2026-04-07
-
-### Added
-- `h ps byport <port> [port2 ...]` — find processes listening on specified port(s)
-- `PsProcess.by_port(*ports)` — query processes by listening port numbers
-- `h task switch` now matches ~/proj/* directories by prefix as fallback when task name doesn't match
-
-## [0.1.338] - 2026-04-07
-
-### Changed
-- `h pr watch`, `h pr fwatch`, `h pr check` now default to current branch's PR (use `-s` to select via fuzzyfinder)
-- Renamed `registry_entries` table to `registry` (auto-migrates existing data)
-
-## [0.1.337] - 2026-04-06
-
-### Changed
-- Refactor `PsProcess#files` and `PsProcess#ports` to use `filter_map` instead of `map + compact` for cleaner code
-
-## [0.1.336] - 2026-04-06
-
-### Fixed
-- `PsProcess#ports` now uses `lsof -a` to AND conditions (was showing all system ports)
-
-## [0.1.335] - 2026-04-07
-
-### Added
-- New `Hiiro::PsProcess` class (`lib/hiiro/ps_process.rb`) for encapsulated process info:
-  - `PsProcess.from_line(line)` - parse `ps awwux` output
-  - `PsProcess.all`, `.search(pattern)`, `.find(pid)`, `.in_dirs(*paths)`
-  - Instance methods: `#files`, `#ports`, `#dir`, `#parent`, `#children`
-  - Simple `#to_s` output: PID + CMD
-- New `h ps` subcommands: `info`, `files`, `ports`
-- Smart argument resolution in `h ps`: accepts PID, search pattern, or directory path
-
-### Changed
-- Refactored `h-ps` to use `PsProcess` class instead of raw `ps` parsing
-
-## [0.1.334] - 2026-04-07
-
-### Added
-- New `h-ps` bin file for process utilities:
-  - `search <pattern>` - find processes matching a substring
-  - `indir <path> [path2 ...]` - list processes with files open in specified paths
-  - `getdir <pattern>` - list working directories of processes matching pattern
-
-## [0.1.333] - 2026-04-04
-
-### Changed
-- Display hiiro version in queue watch output for better visibility during task monitoring
-
-## [0.1.332] - 2026-04-04
-
-### Changed
-- Extract `hiiro_version` helper method in queue watcher to reduce duplication and improve version detection reliability
-
-## [0.1.331] - 2026-04-04
-
-### Fixed
-- Strip whitespace from gem version output in queue watcher to prevent version comparison failures
-
-## [0.1.330] - 2026-04-04
-
-### Added
-- `h queue add` now supports tmux session name prefix matching as fallback when task name doesn't match
-- Queue editor now opens from the session's active pane directory when adding tasks via session reference
-
-### Changed
-- Extract `session_info_for()` helper to resolve tmux sessions by prefix in queue prompt resolver
-
-## [0.1.329] - 2026-04-03
-
-### Changed
-- Add debug output and temporary JSON logging to publish script for troubleshooting Claude API responses
-
-## [0.1.328] - 2026-04-02
-
-### Changed
-- Update command documentation
-
-## [0.1.327] - 2026-04-02
-
-### Added
-- `h branch save --tag <tag>` (repeatable) — apply tags to branches during save operation
-
-## [0.1.326] - 2026-04-02
-
-### Changed
-- Improve tag display formatting in link output by mapping individual tags to colored badges
-- Refactor `h link tags` filtering logic to use `Hiiro::Tag` helpers for cleaner code
-- Relocate `taggable` accessor method in `Hiiro::Tag` model
-
-### Added
-- `Hiiro::Tag.tagged_by_type` helper method to query tagged objects by tag name and type
-
-## [0.1.325] - 2026-04-02
-
-### Fixed
-- Allow custom primary keys in `Hiiro::Invocation` model via `unrestrict_primary_key` for SQLite compatibility
-
-## [0.1.324] - 2026-04-02
-
-### Added
-- `h pr status [ref...]` — query multiple PRs or pinned PRs; outputs number, title, state, check summary, and URL for each
-- `h wtree branch [paths...]` — show branch for each worktree, or query specific worktree paths; resolves relative paths using task context
-
-### Changed
-- Pass `cwd` context to `h-wtree` via `Hiiro.run` for proper path resolution in nested environments
-
-## [0.1.323] - 2026-04-01
-
-### Changed
-- Simplify `h pr ls` status refresh logic: always call `refresh_all_status` with `force:` parameter instead of conditional block
-- Add optional `verbose:` parameter to `refresh_all_status` to control "already checked" message output
-- Update `h pr update` to pass `verbose: true` when refreshing active PR status
-
-## [0.1.322] - 2026-04-01
-
-### Changed
-- Refactor `h link tags` filtering logic to use new `Hiiro::Tag.tags_by_type` helper
-- Simplify tag query to use `Hiiro::Link.where(id:)` instead of manual filtering
-- Extract `tags_by_type(type)` singleton method to `Hiiro::Tag` for code reuse
-
-## [0.1.321] - 2026-04-01
-
-### Changed
-- Extract `open_config` to `Hiiro::Config.open` singleton method; simplify parameter order from `dir:, file:` to positional `file, dir: nil`
-- Update all config subcommands to use new `Hiiro::Config.open` interface
-
-## [0.1.320] - 2026-04-01
-
-### Changed
-- Extract `open_config` helper to Hiiro instance method for reuse across config subcommands
-- Refactor `h version --all` to use `Hiiro::Rbenv.capture` with clearer output formatting
-- Add `to_s` method to `Hiiro::Tmux::Session` for string representation; rename existing `display` method for consistency
-- Extract `project_dirs` and `projects_from_config` to singleton methods in Project plugin for testability
-
-## [0.1.319] - 2026-04-01
-
-### Added
-- `h queue ls [STATUS]` — filter by status with prefix matching (e.g. `h queue ls run` → running tasks); composable with existing `-s` flag
-- `h session sh <session> [cmd...]` — open a new window in another tmux session (runs shell or given command there, then switches)
-- `h task sh -s SESSION [cmd...]` — run task shell/command in a new window in a specific tmux session
-- `h link tags` — list all known link tags; `h link tags tag1 tag2...` filters links by tags (prefix matching)
-- `h link ls` now shows tags inline with colored badges
-- `h link rm` / `h link remove` subcommand — remove links by number, shorthand, or fuzzy select
-
-### Fixed
-- `h pr update` and `h pr ls -u` skip closed/merged PRs — only active PRs are refreshed
-- `h link add -h` now shows help instead of adding `-h` as a URL
-- `h db remigrate` no longer imports duplicate links — skips rows with an already-existing URL
-- Add unique constraint on `links.url` to prevent duplicates at database level
-
-## [0.1.318] - 2026-04-01
-
-### Added
-- `registry_pick` helper method for interactive registry entry selection via fuzzyfinder
-
-### Changed
-- Simplify gem installation logic: always use `gem install -u` instead of checking installation state and branching between `gem install` and `gem update`
-- Remove `--clear-sources` and `--source` flags in favor of gem's built-in source cache handling
-- Improve gem version regex in publish script to match only the first (latest) version from `gem list` output
-
-### Fixed
-- Ensure gem installation works reliably across all rbenv Ruby versions by using `-u` flag for consistent update behavior
-
-## [0.1.317] - 2026-04-01
-
-### Changed
-- Parallelize gem installation across all rbenv Ruby versions using thread pool for faster multi-version deployment
-- Refactor publish script to install/update hiiro gem across all Ruby versions instead of just current version
-
-### Fixed
-- Handle both gem install and update cases based on existing installation state
-- Run `h setup` after installation in each Ruby version to initialize version-specific configuration
-- Suppress gem installation output to reduce log noise during parallel installs
-
-## [0.1.316] - 2026-04-01
-
-### Added
-- Parallelize hiiro gem updates across Ruby versions with thread pool for faster multi-version updates
-- Optional `dir:` parameter to `Hiiro::Background.run` for working directory support
-
-### Changed
-- Improve gem version regex pattern in publish script for more reliable version matching
-
-### Fixed
-- Bypass rubygems local cache with `--clear-sources --source https://rubygems.org` flags in `install_gem` to ensure fresh gem installation
-- Add debug output for version polling in publish script
-- Convert `sa` symlink from absolute to relative path
-
-## [0.1.315] - 2026-04-01
-
-### Fixed
-- Remove redundant `exit 0` statement from publish script
-
-## [0.1.314] - 2026-04-01
-
-### Fixed
-- Rename `Gem` class to `RubyGem` in publish script to avoid conflict with Ruby stdlib
-
-## [0.1.313] - 2026-04-01
-
-### Fixed
-- Remove `awesome_print` dependency
-- Do not splice values into subcommand constructor; pass them as keyword arguments to prevent arg leakage
-
-## [0.1.312] - 2026-04-01
-
-### Fixed
-- Separate `bin_name` and `args` initialization in `Hiiro.init` to prevent argument confusion in nested Hiiro instances
-
-## [0.1.311] - 2026-04-01
-
-### Changed
-- Add `ap()` inspection for bin/args initialization in debug mode
-
-## [0.1.310] - 2026-04-01
-
-### Fixed
-- `make_child` now passes `bin_name:` and `args:` as keyword args to `Hiiro.init`, fixing subcommand dispatch for all `h task`, `h queue`, `h service`, and `h run` child hierarchies — previously `child_bin_name` leaked into `oargs` and became the subcmd, so every child hiiro showed help instead of dispatching
-
-## [0.1.309] - 2026-03-31
-
-### Added
-- `h link tag` support for tagging links in the link manager
-
-### Fixed
-- Correct argument passing in `run_child` to prevent arg dropping in nested Hiiro instances
-
-## [0.1.308] - 2026-03-31
-
-### Added
-- `h db cleanup` subcommand to preview and prune duplicate rows from SQLite tables
-
-### Fixed
-- Prevent duplicate pinned_prs during import with `insert_conflict` and per-row rescue

data/CLAUDE.md

@@ -508,6 +508,7 @@ ALWAYS update `README.md` and any files in `docs/` or other markdown files that
 ## Key Files
 
 - `exe/h` - Entry point that loads lib/hiiro.rb
+- `exe/t`, `exe/tt` - Task CLI launchers over `Hiiro::TaskCli` (`lib/hiiro/task_cli.rb`)
 - `bin/h-*` - External subcommands (tmux wrappers, git helpers, jumplist, etc.)
 - `plugins/*.rb` - Reusable plugin modules (Pins, Project, Tasks, Notify)
 - `lib/hiiro.rb` - Main Hiiro class and Runners

data/README.md

@@ -61,20 +61,74 @@ h ping
 
 ### Task CLI
 
-`~/bin/t` contains the task commands and helpers, using Hiiro's `add_cmd` DSL
-and existing task records. `t new NAME` creates a task and its notes directory
-without creating a Git worktree. Select a task with `--task NAME` or `-t NAME`.
-Root and group help are generated by Hiiro; leaf command help lists its selected options.
+`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.
 
 ```sh
-t new investigation
-t next -t investigation "Inspect the failing request"
-t doc new findings -t investigation
-t doc open findings -t investigation
-t show investigation
+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"
 ```
 
-See [Task commands](docs/h-task.md) for the full command reference.
+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.
+
+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.
+
+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
+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.
+
+See the [task command reference](docs/t.md) for all commands and the [workflow introduction](docs/why-t.md) for practical examples.
 
 ## Subcommands
 
@@ -87,18 +141,20 @@ See [Task commands](docs/h-task.md) for the full command reference.
 | `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 task` | Task management across git worktrees, including existing external worktrees (via Tasks plugin) |
-| `h subtask` | Subtask management within tasks (via Tasks plugin) |
+| `h task` | Same program as `t`: task records, todos, worktrees (`t NAME tree new`), and Herdr workspaces |
 
 ### External Subcommands
 
 | Command | Description |
 |---------|-------------|
+| `h alias` | Append safely quoted zsh aliases |
 | `h app` | Manage app directories within tasks/projects |
+| `h bin` | Create, list, and edit Hiiro executables |
 | `h branch` | Git branch management with fuzzy selection and copy |
 | `h claude` | Claude CLI wrapper with Herdr split support |
 | `h commit` | Select commits using fuzzy finder |
 | `h config` | Open config files (vim, git, Herdr, zsh, starship, claude) |
+| `h env` | Append safely quoted environment variables |
 | `h link` | Manage saved links with URL, description, and shorthand |
 | `h pane` | Herdr pane management |
 | `h plugin` | Manage hiiro plugins (list, edit, search) |
@@ -116,6 +172,33 @@ See [Task commands](docs/h-task.md) for the full command reference.
 
 `h claude agents|commands|skills -a` prints the absolute file path for each matching `.claude` tool, including `SKILL.md` for skills.
 
+### Shell helpers
+
+```sh
+h env add exam ple
+h alias add ll 'ls -al'
+h alias add --global PAGER '| less'
+h bin add scratch
+h bin add josh list show
+```
+
+`h env add NAME VALUE` appends a literal `export NAME="VALUE"` to
+`~/.zshenv.d/vars.zsh` when that file exists, otherwise to `~/.zshenv`.
+`h alias add NAME COMMAND...` similarly prefers `~/.zshrc.d/aliases.zsh`,
+falling back to `~/.zshrc`. Existing contents are preserved. A single quoted
+command string preserves shell syntax; separate command arguments retain their
+argument boundaries. Use `--global` or `-g` for a global zsh alias.
+
+These commands use native Hiiro option parsing and help. Use `--` before
+flag-like data, for example `h env add LABEL -- --literal` or
+`h alias add inspect -- tool --help`. Start a new shell or source the relevant
+configuration file to apply additions.
+
+`h bin add NAME [COMMAND ...]` creates an executable `~/bin/h-NAME` using
+`Hiiro.run`. Without commands its block is empty; each command adds an empty
+`add_cmd` block with a Ruby symbol. Existing files and symlinks are never
+overwritten. See the [bin command reference](docs/h-bin.md).
+
 ## Abbreviations
 
 Any subcommand can be abbreviated as long as the prefix uniquely matches:
@@ -135,7 +218,7 @@ Plugins are Ruby modules loaded from `~/.config/hiiro/plugins/`:
 |--------|-------------|
 | Pins | Per-command YAML key-value storage |
 | Project | Project directory navigation with Herdr workspace management |
-| Tasks | Task lifecycle management across git worktrees with external-worktree registration and subtask support |
+| Tasks | `Hiiro::TaskManager` worktree creation and current-task environment used by `t`, `h service`, `h run`, and `h file` |
 | Notify | Herdr desktop notifications |
 
 ## Adding Subcommands
@@ -226,15 +309,29 @@ among the command's automatic flags and does not conflict with a selected
 explicit option or `-h`. Every automatic flag has a long form. Explicit flags
 and value options keep their definitions.
 
-For a command that delegates to `make_child`, use `add_cmd(..., passthrough: true)`.
+For a command that delegates to `run_child`, use `add_cmd(..., passthrough: true)`.
 It forwards control without parsing the parent's arguments or intercepting the
-child's `--help`. The child declares and parses its own options. Generated help
-uses the original command block's source location and declared `args:`, not the
+child's `--help`. The child declares and parses its own options.
+Generated help uses the original command block's source location and declared `args:`, not the
 internal wrapper's signature.
 
+`run_child` is the convenience form of `make_child(...).run`. `make_child`
+returns an unrun child when the caller needs to configure it before dispatch.
+Module-level `build_hiiro` methods are builders that return such a child; callers
+run the result. They are not required for an inline child command group.
+Child commands inherit the parent's resolvers, so a task can be bound once and
+shared with nested groups without consuming its name again.
+
 For a CLI that should dispatch only registered blocks, pass
-`external_commands: false` to `Hiiro.run` and its `make_child` calls. This
+`external_commands: false` to `Hiiro.run` and its `run_child` or `make_child` calls. This
 prevents unrelated same-prefix executables on `PATH` from taking precedence.
+Pass `builtin_commands: false` as well to skip the automatic `pry` and `edit`
+commands, for CLIs whose first word is data rather than a command name.
+
+Raise `Hiiro::Error` (or a subclass) for expected user-facing failures such as
+bad arguments or missing records. `Hiiro#run` prints `ERROR: message` to stderr
+and exits 1 without a backtrace; any other exception still prints its backtrace.
+`open_default(target)` opens a path or URL with the OS handler (`open` or `xdg-open`).
 
 ## Writing Plugins
 

data/bin/h-bin

@@ -3,6 +3,26 @@
 require 'hiiro'
 
 Hiiro.run do
+  add_cmd :add, args: ['NAME', 'COMMAND...'] do
+    name, *commands = opts.args
+    name = name&.delete_prefix('h-')
+    abort 'Use a command name containing letters, digits, underscores, or hyphens' unless name&.match?(/\A[A-Za-z0-9][A-Za-z0-9_-]*\z/)
+    abort 'Subcommand names cannot be empty' if commands.any?(&:empty?)
+
+    path = File.join(Dir.home, 'bin', "h-#{name}")
+    body = commands.map { |command| "  add_cmd #{command.to_sym.inspect} do\n  end" }.join("\n\n")
+    template = "#!/usr/bin/env ruby\n\nrequire 'hiiro'\n\nHiiro.run do\n"
+    template << "#{body}\n" unless body.empty?
+    template << "end\n"
+
+    FileUtils.mkdir_p(File.dirname(path))
+    File.open(path, File::WRONLY | File::CREAT | File::EXCL, 0o755) do |file|
+      file.write(template)
+      file.chmod(0o755)
+    end
+    puts path
+  end
+
   add_subcmd(:list) do |*subcmd_names|
     patterns = subcmd_names.flatten.compact.map { |sc|
       sc.sub(/^(?!h-)/, '{h-,}')

data/bin/h-task

@@ -0,0 +1 @@
+../exe/t

data/bin/t

@@ -0,0 +1 @@
+../exe/t

data/bin/tt

@@ -0,0 +1 @@
+../exe/tt