hiiro 0.1.327 → 0.1.328

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5b59bf7d57b8661136281afe559d7fb3afd1e7fa090483f556074be405aa69a4
-  data.tar.gz: '08e9ff25437d1991c0f75007cabeb0bc993fb8e8a98225538fbd39b9e0baf71d'
+  metadata.gz: 5679acf6319a905ff51f797d7eaf1468a54d1ddf2f888b6c54d290c1a00320ac
+  data.tar.gz: 4da3a5fc611b5904d22ba3d1233185ed133d985583422d85a5846827a333c346
 SHA512:
-  metadata.gz: 2e4cc0a15c2216ebd6f4a3159b72b1a9cb9b2beda9fb47f0aede821c4024f8f95743838df19d0068edd5e0b1ec37001e5d4f68bbce4f3aa09fa15383376b9066
-  data.tar.gz: 103b722f78dbd84c6680ba171f3c60c69cf3848017b79ccb42a1e30f6eab10645cc1ace1e6edbec1280199dad00e1f55dc22f0e4f19f20990ff3723fcbe233fd
+  metadata.gz: ec87bdeeb6697c9e82d938219dccccb035575e1903ab2760d8e72fd8467b4779186ca9747cf1eeeee2e172facb796240a451f0c8a7ada6d6dfc51d3a30e72b23
+  data.tar.gz: 5afcff09237311bcf77570dcfde910a57504edddd93fbbd493b70fcb9e647227e986e554e0e5fc3527ee3dceeb5e270e1d7cdfea2f3aa77679fc02600cba848d

data/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## [0.1.328] - 2026-04-02
+
+### Changed
+- Update command documentation
+
 ## [0.1.327] - 2026-04-02
 
 ### Added
@@ -314,4 +319,4 @@
 ## [0.1.295]
 
 ### Changed
-- Filter logic changes for PR management
+- Filter logic changes for PR management

data/docs/README.md

@@ -1,52 +1,78 @@
-# Hiiro Documentation
+# Hiiro Bin Reference
 
-This directory contains detailed documentation for all Hiiro subcommands.
+Quick-reference index of all `h-*` executables and the main `h` entry point.
 
-[← Back to main README](../README.md)
+## Main entry point
 
-## Subcommands
+| Command | Description |
+|---------|-------------|
+| [h](h.md) | Install, update, setup, and dispatch to all subcommands |
+
+## Git
+
+| Command | Description |
+|---------|-------------|
+| [h-branch](h-branch.md) | Manage, tag, search, and inspect git branches with task and PR associations |
+| [h-commit](h-commit.md) | Fuzzy-select a git commit SHA from the recent log |
+| [h-sha](h-sha.md) | Fuzzy-select, show, and copy git commit SHAs |
+| [h-sparse](h-sparse.md) | Manage named git sparse-checkout path groups |
+| [h-wtree](h-wtree.md) | Manage git worktrees with fuzzy selection and tmux session switching |
+
+## GitHub
+
+| Command | Description |
+|---------|-------------|
+| [h-cpr](h-cpr.md) | Proxy `h pr` subcommands to the PR for the current branch |
+| [h-pr](h-pr.md) | Track, update, view, and act on GitHub pull requests |
+| [h-pr-monitor](h-pr-monitor.md) | Poll `gh pr status` and send notifications on status changes |
+
+## Tmux
+
+| Command | Description |
+|---------|-------------|
+| [h-buffer](h-buffer.md) | Manage tmux paste buffers |
+| [h-jumplist](h-jumplist.md) | Vim-style tmux navigation history (back/forward through pane focus) |
+| [h-notify](h-notify.md) | Push and manage in-pane notifications with tmux menu |
+| [h-pane](h-pane.md) | Manage tmux panes — split, kill, zoom, resize, home panes |
+| [h-session](h-session.md) | Manage tmux sessions — create, kill, attach, rename, orphan detection |
+| [h-title](h-title.md) | Update terminal tab title from the current hiiro task name |
+| [h-window](h-window.md) | Manage tmux windows — list, create, kill, navigate, layout |
+
+## Claude / AI
 
 | Command | Description |
 |---------|-------------|
-| h-app | Manage app directories within tasks/projects |
-| h-branch | Git branch management with fuzzy selection and copy |
-| [h-buffer](h-buffer.md) | Tmux paste buffer management |
-| h-claude | Claude CLI wrapper with tmux split support |
-| h-commit | Select commits using fuzzy finder |
-| h-config | Open config files (vim, git, tmux, zsh, starship, claude) |
-| h-link | Manage saved links with URL, description, and shorthand |
-| [h-pane](h-pane.md) | Tmux pane management |
-| [h-plugin](h-plugin.md) | Manage hiiro plugins (list, edit, search) |
-| h-pr | GitHub PR management via gh CLI |
-| h-project | Project navigation with tmux session management |
-| [h-session](h-session.md) | Tmux session management |
-| h-sha | Extract short SHA from git log |
-| h-todo | Todo list management with tags and task association |
-| [h-window](h-window.md) | Tmux window management |
-| h-wtree | Git worktree management |
+| [h-claude](h-claude.md) | Launch Claude sessions in tmux splits, search `.claude` dirs, run inline prompts |
+| [h-pm](h-pm.md) | Queue `/project-manager` skill prompts via `h queue add` |
 
-## Base Commands
+## App / Project Management
 
-The main `h` command includes these built-in subcommands:
+| Command | Description |
+|---------|-------------|
+| [h-app](h-app.md) | Manage named application subdirectories within a git repo |
+| [h-project](h-project.md) | Manage project directories and start tmux sessions |
+
+## Data / Config
 
 | Command | Description |
 |---------|-------------|
-| `h version` | Display the Hiiro version |
-| `h ping` | Simple test command (returns "pong") |
-| `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 (via Tasks plugin) |
-| `h subtask` | Subtask management within tasks (via Tasks plugin) |
+| [h-bin](h-bin.md) | List and edit hiiro bin scripts in PATH |
+| [h-config](h-config.md) | Open common configuration files in your editor |
+| [h-db](h-db.md) | Inspect and manage the hiiro SQLite database |
+| [h-link](h-link.md) | Store, search, tag, and open saved URLs |
+| [h-plugin](h-plugin.md) | List, edit, and search hiiro plugin files |
+| [h-registry](h-registry.md) | Store and look up named resources by type with short aliases |
+| [h-tags](h-tags.md) | Query tags grouped by taggable type |
+| [h-todo](h-todo.md) | Manage a personal todo list with statuses, tags, and task associations |
 
-## Plugins
+## Utilities
 
-| Plugin | Description |
-|--------|-------------|
-| Pins | Per-command YAML key-value storage |
-| Project | Project directory navigation with tmux session management |
-| Tasks | Task lifecycle management across git worktrees with subtask support |
-| Notify | macOS desktop notifications via terminal-notifier |
+| Command | Description |
+|---------|-------------|
+| [h-bg](h-bg.md) | Run commands in background tmux windows with history tracking |
+| [h-img](h-img.md) | Save or base64-encode images from clipboard or file |
+| [h-misc](h-misc.md) | Miscellaneous utilities (symlink destination reporting) |
+| [h-sha](h-sha.md) | Fuzzy-select, show, and copy git commit SHAs |
 
 ## Abbreviations
 
@@ -55,5 +81,6 @@ All commands support prefix abbreviation:
 ```sh
 h buf ls      # h buffer ls
 h ses ls      # h session ls
-h win         # h window
+h win new     # h window new
+h br save     # h branch save
 ```

data/docs/h-app.md

@@ -0,0 +1,85 @@
+# h-app
+
+Manage named application subdirectories within a git repo, with shortcuts to cd, search, and run tools scoped to each app.
+
+## Usage
+
+```
+h app <subcommand> [args]
+```
+
+## Subcommands
+
+### `config`
+
+Open `~/.config/hiiro/apps.yml` in your editor.
+
+### `cd` [alias: none]
+
+Send a `cd` command to the current tmux pane to switch into an app directory (or the repo root if no name given).
+
+**Args:** `[app_name]`
+
+### `ls`
+
+List all configured apps and their relative paths from the repo root.
+
+### `path`
+
+Print the relative path from the current directory to the app (or repo root).
+
+**Args:** `[app_name]`
+
+### `abspath`
+
+Print the absolute filesystem path of the app directory (or repo root).
+
+**Args:** `[app_name]`
+
+### `add`
+
+Register a new app name with a path relative to the repo root.
+
+**Args:** `<app_name>` `<relative_path>`
+
+### `rm` [alias: `remove`]
+
+Remove a registered app by name.
+
+**Args:** `<app_name>`
+
+### `fd`
+
+Run `fd` inside the named app's directory, passing all extra arguments to `fd`.
+
+**Args:** `<app_name>` `[fd_args...]`
+
+### `rg`
+
+Run `rg` (ripgrep) inside the named app's directory.
+
+**Args:** `<app_name>` `[rg_args...]`
+
+### `vim`
+
+Open vim inside the named app's directory.
+
+**Args:** `<app_name>` `[vim_args...]`
+
+### `sh`
+
+Open a shell (or run a command) inside the named app's directory.
+
+**Args:** `<app_name>` `[cmd...]`
+
+### `service`
+
+Delegate to `Hiiro::ServiceManager` subcommands scoped to the current app context. See `h service` for subcommand details.
+
+### `run`
+
+Delegate to `Hiiro::RunnerTool` subcommands. See `h run` for subcommand details.
+
+### `file`
+
+Delegate to `Hiiro::AppFiles` subcommands. See `h file` for subcommand details.

data/docs/h-bg.md

@@ -0,0 +1,33 @@
+# h-bg
+
+Run commands in background tmux windows with history tracking.
+
+## Usage
+
+```
+h bg <subcommand> [args]
+```
+
+## Subcommands
+
+### `popup`
+
+Open your `$EDITOR` with recent command history as comments, then run whatever you type in a background tmux window. History is stored in `~/.config/hiiro/bg-history.txt` (max 50 entries).
+
+### `run`
+
+Run a command immediately in a new background tmux window.
+
+**Args:** `<cmd...>`
+
+### `attach` [alias: `a`]
+
+Switch the current tmux client to the background session.
+
+### `history` [alias: `hist`]
+
+Print the recent background command history (up to 50 entries), newest last.
+
+### `setup`
+
+Print the tmux.conf line needed to bind `prefix + b` to open the popup. Does not modify any config files automatically.

data/docs/h-bin.md

@@ -0,0 +1,23 @@
+# h-bin
+
+List and edit hiiro bin scripts (`h-*` executables found in PATH).
+
+## Usage
+
+```
+h bin <subcommand> [filters...]
+```
+
+## Subcommands
+
+### `list`
+
+Print the paths of all `h-*` executables found in PATH. Optionally filter by name patterns; each pattern is matched as `h-<pattern>` or `<pattern>`.
+
+**Args:** `[subcmd_name...]`
+
+### `edit`
+
+Open matching `h-*` executables in your editor. Patterns work the same as `list`.
+
+**Args:** `[subcmd_name...]`

data/docs/h-branch.md

@@ -0,0 +1,253 @@
+# h-branch
+
+Manage, tag, search, and inspect git branches with task and PR associations stored in SQLite.
+
+## Usage
+
+```
+h branch <subcommand> [options] [args]
+```
+
+## Subcommands
+
+### `save`
+
+Save the current (or named) branch to the branch store with current task, worktree, and tmux context.
+
+**Args:** `[branch_name]`
+
+**Options:**
+| Flag | Short | Description | Default |
+|---|---|---|---|
+| `--tag` | `-t` | Tag to apply (repeatable) | — |
+
+### `saved`
+
+List saved branches, with optional filter string.
+
+**Args:** `[filter]`
+
+### `current`
+
+Print the current git branch name.
+
+### `info`
+
+Show detailed info about the current branch: SHA, task, worktree, tmux context, ahead/behind vs main, associated PR, and note.
+
+### `ls`
+
+List branches (saved by default, or all local with `-a`).
+
+**Options:**
+| Flag | Short | Description | Default |
+|---|---|---|---|
+| `--tag` | `-t` | Filter by tag (OR when multiple, repeatable) | — |
+| `--all` | `-a` | Show all local branches instead of just saved | false |
+
+### `search`
+
+Search saved (or all) branches by name or tag substring.
+
+**Args:** `<term> [term2...]`
+
+**Options:**
+| Flag | Short | Description | Default |
+|---|---|---|---|
+| `--all` | `-a` | Search all local branches | false |
+
+### `tag`
+
+Add tags to a branch. With `-e`, opens a YAML editor for bulk tagging.
+
+**Args:** `[branch] <tag> [tag2...]`
+
+**Options:**
+| Flag | Short | Description | Default |
+|---|---|---|---|
+| `--edit` | `-e` | Open YAML editor for bulk tagging | false |
+
+### `untag`
+
+Remove one or more tags from a branch, or clear all tags if none specified.
+
+**Args:** `[branch] [tag...]`
+
+### `tags`
+
+Show all tagged branches grouped by tag.
+
+### `select`
+
+Fuzzy-select a branch name from saved (or all) branches and print it.
+
+**Options:**
+| Flag | Short | Description | Default |
+|---|---|---|---|
+| `--all` | `-a` | Select from all local branches | false |
+
+### `copy`
+
+Fuzzy-select a branch and copy its name to clipboard.
+
+**Options:**
+| Flag | Short | Description | Default |
+|---|---|---|---|
+| `--all` | `-a` | Select from all local branches | false |
+
+### `co` [alias: `checkout`]
+
+Checkout a branch, fuzzy-selecting if no name given.
+
+**Args:** `[branch]`
+
+**Options:**
+| Flag | Short | Description | Default |
+|---|---|---|---|
+| `--all` | `-a` | Select from all local branches | false |
+
+### `rm` [alias: `remove`]
+
+Delete a branch (`git branch -d`), fuzzy-selecting if no name given.
+
+**Args:** `[branch]`
+
+**Options:**
+| Flag | Short | Description | Default |
+|---|---|---|---|
+| `--all` | `-a` | Select from all local branches | false |
+
+### `rename`
+
+Rename a branch locally and on the remote, then update the saved record.
+
+**Args:** `<new_name> [old_name]`
+
+### `status`
+
+Show ahead/behind counts and associated PR state for each branch.
+
+**Options:**
+| Flag | Short | Description | Default |
+|---|---|---|---|
+| `--all` | `-a` | Show all local branches | false |
+
+### `merged`
+
+List branches that have been merged into main/master.
+
+**Options:**
+| Flag | Short | Description | Default |
+|---|---|---|---|
+| `--all` | `-a` | Show all merged branches, not just saved | false |
+
+### `clean`
+
+Interactively delete merged branches. With `-f`, delete all without prompting.
+
+**Options:**
+| Flag | Short | Description | Default |
+|---|---|---|---|
+| `--all` | `-a` | Include all merged branches | false |
+| `--force` | `-f` | Delete all without confirmation | false |
+
+### `recent`
+
+Show the N most recently visited branches from reflog.
+
+**Args:** `[n]` (default: 10)
+
+### `note`
+
+Get or set a freeform note on a branch.
+
+**Args:** `[text...]`
+
+**Options:**
+| Flag | Short | Description | Default |
+|---|---|---|---|
+| `--clear` | — | Clear the note | false |
+
+### `for-task`
+
+List saved branches associated with a given task name (or current task).
+
+**Args:** `[task_name]`
+
+### `for-pr` [alias: `pr`]
+
+Print the head branch name for a tracked PR (fuzzy-select if no arg).
+
+**Args:** `[pr_number_or_url]`
+
+### `duplicate`
+
+Create a new branch as a copy of the current (or specified) branch.
+
+**Args:** `<new_name> [source_branch]`
+
+### `push`
+
+Push a branch to a remote with optional force and upstream tracking.
+
+**Options:**
+| Flag | Short | Description | Default |
+|---|---|---|---|
+| `--remote` | `-r` | Remote name | `origin` |
+| `--from` | `-f` | Local branch or commit | current branch |
+| `--to` | `-t` | Remote branch name | same as from |
+| `--force` | `-F` | Force push | false |
+| `--set-upstream` | `-u` | Set upstream tracking | false |
+
+### `diff`
+
+Show commit log between two refs (defaults to `main..HEAD`).
+
+**Args:** `[from] [to]`
+
+### `changed`
+
+List files changed between the current branch and its upstream fork point.
+
+**Args:** `[upstream]`
+
+### `ahead`
+
+Show how many commits the branch is ahead of a base.
+
+**Args:** `[base] [branch]`
+
+### `behind`
+
+Show how many commits the branch is behind a base.
+
+**Args:** `[base] [branch]`
+
+### `log`
+
+Show the commit log for changes since the upstream fork point.
+
+**Args:** `[upstream]`
+
+### `q` [alias: `query`]
+
+Query the branches SQLite table directly. Pass a table name, `key=value` filters, or raw SQL.
+
+**Args:** `[table|sql|key=value...]`
+
+**Options:**
+| Flag | Short | Description | Default |
+|---|---|---|---|
+| `--all` | `-a` | Show all rows (no 50-row limit) | false |
+
+### `forkpoint`
+
+Print the merge-base SHA between the current branch and an upstream.
+
+**Args:** `[upstream] [branch]`
+
+### `ancestor`
+
+Check whether one ref is an ancestor of another.
+
+**Args:** `[ancestor] [descendant]`

data/docs/h-buffer.md

@@ -1,61 +1,73 @@
 # h-buffer
 
-Tmux paste buffer management.
-
-[← Back to docs](README.md) | [← Back to main README](../README.md)
+Manage tmux paste buffers — list, show, copy to clipboard, save, load, paste, and delete.
 
 ## Usage
 
-```sh
-h buffer <subcommand> [args...]
+```
+h buffer <subcommand> [args]
 ```
 
 ## Subcommands
 
-| Command | Description | Tmux equivalent |
-|---------|-------------|-----------------|
-| `ls` | List all paste buffers | `tmux list-buffers` |
-| `show` | Display buffer contents | `tmux show-buffer` |
-| `save` | Save buffer to file | `tmux save-buffer` |
-| `load` | Load buffer from file | `tmux load-buffer` |
-| `set` | Set buffer contents | `tmux set-buffer` |
-| `paste` | Paste buffer into pane | `tmux paste-buffer` |
-| `delete` | Delete a buffer | `tmux delete-buffer` |
-| `choose` | Interactive buffer selection | `tmux choose-buffer` |
-| `clear` | Delete all buffers | (loops through all buffers) |
-| `select` | Select a buffer with fuzzy finder | - |
-| `copy` | Copy buffer contents to clipboard | `pbcopy` |
+### `ls`
 
-## Examples
+List all tmux buffers. Extra args are passed directly to `tmux list-buffers`.
 
-```sh
-# List all buffers
-h buffer ls
+**Args:** `[tmux_args...]`
 
-# Show the most recent buffer (or select one)
-h buffer show
+### `show`
 
-# Copy buffer to system clipboard
-h buffer copy
+Print the contents of a buffer (fuzzy-select if no name given).
 
-# Save buffer to a file
-h buffer save ~/clipboard.txt
+**Args:** `[buffer_name] [tmux_args...]`
 
-# Load file into buffer
-h buffer load ~/mytext.txt
+### `copy`
 
-# Paste buffer into current pane
-h buffer paste
+Copy a buffer's contents to the macOS clipboard via `pbcopy` (fuzzy-select if no name).
 
-# Select a buffer interactively
-h buffer select
+**Args:** `[buffer_name]`
 
-# Clear all buffers
-h buffer clear
-```
+### `save`
+
+Save a buffer's contents to a file (fuzzy-select buffer if name not given).
+
+**Args:** `<path> [buffer_name] [tmux_args...]`
+
+### `load`
+
+Load a file into the tmux buffer stack.
+
+**Args:** `<path> [tmux_args...]`
+
+### `set`
+
+Set buffer contents; all args passed directly to `tmux set-buffer`.
+
+**Args:** `[tmux_args...]`
+
+### `paste`
+
+Paste a buffer into the current pane.
+
+**Args:** `[buffer_name] [tmux_args...]`
+
+### `delete`
+
+Delete a buffer (fuzzy-select if no name given).
+
+**Args:** `[buffer_name]`
+
+### `choose`
+
+Open the tmux buffer chooser UI.
+
+**Args:** `[tmux_args...]`
+
+### `clear`
+
+Delete all tmux buffers.
 
-## Notes
+### `select`
 
-- All subcommands pass additional arguments directly to the underlying tmux command
-- The `select` and `copy` commands use fuzzy finding (`sk` or `fzf`) when no buffer is specified
-- Use `tmux list-buffers -F '#{buffer_name}: #{buffer_sample}'` for more detailed output
+Fuzzy-select a buffer name and print it.