From d7c194a9f2e1d57ade31dc3ac28ce85cd0ca58ff Mon Sep 17 00:00:00 2001 From: Rob Zolkos Date: Sun, 8 Mar 2026 21:26:48 -0400 Subject: [PATCH 1/3] =?UTF-8?q?Fix=20skill=20docs:=20topic=20=E2=86=92=20t?= =?UTF-8?q?hreads,=20box=20names,=20habit=20IDs,=20recordings=20format?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- skills/hey/SKILL.md | 36 +++++++++++++++++++++--------------- 1 file changed, 21 insertions(+), 15 deletions(-) diff --git a/skills/hey/SKILL.md b/skills/hey/SKILL.md index 882c2e8..033e9e9 100644 --- a/skills/hey/SKILL.md +++ b/skills/hey/SKILL.md @@ -11,7 +11,7 @@ triggers: # Email actions - hey boxes - hey box - - hey topic + - hey threads - hey reply - hey compose - hey drafts @@ -77,7 +77,7 @@ CLI for HEY email: mailboxes, email threads, replies, compose, calendars, todos, |------|---------| | List mailboxes | `hey boxes --json` | | List emails in a box | `hey box imbox --json` | -| Read email thread | `hey topic 123 --json` | +| Read email thread | `hey threads 123 --json` | | Reply to email | `hey reply 123 -m "Thanks!"` | | Compose email | `hey compose --to user@example.com --subject "Hello"` | | List drafts | `hey drafts --json` | @@ -88,8 +88,8 @@ CLI for HEY email: mailboxes, email threads, replies, compose, calendars, todos, | Complete todo | `hey todo complete 123` | | Uncomplete todo | `hey todo uncomplete 123` | | Delete todo | `hey todo delete 123` | -| Complete habit | `hey habit complete` | -| Uncomplete habit | `hey habit uncomplete` | +| Complete habit | `hey habit complete 123` | +| Uncomplete habit | `hey habit uncomplete 123` | | Start time tracking | `hey timetrack start` | | Stop time tracking | `hey timetrack stop` | | Current timer | `hey timetrack current --json` | @@ -109,7 +109,7 @@ CLI for HEY email: mailboxes, email threads, replies, compose, calendars, todos, Want to read email? ├── Which mailbox? → hey boxes --json ├── List emails in box? → hey box --json -├── Read full thread? → hey topic --json +├── Read full thread? → hey threads --json └── Launch interactive UI? → hey (no args, launches TUI) ``` @@ -145,24 +145,27 @@ hey box imbox --json # List emails in Imbox (by name) hey box 123 --json # List emails in box (by ID) ``` -Box names: `imbox`, `the_feed`, `paper_trail`, `set_aside`, `reply_later`, `screened_out` +Box names: `imbox`, `feedbox`, `trailbox`, `asidebox`, `laterbox`, `bubblebox` -**Response format:** `hey box` returns `{"box": {...}, "postings": [...]}`. Each posting has: `id`, `name` (subject), `seen` (read status), `created_at`, `contacts`, `summary`, `app_url`. +**Response format:** `hey box` returns `{"box": {...}, "postings": [...]}`. Each posting has: `id` (posting ID), `name` (subject), `seen` (read status), `created_at`, `contacts`, `summary`, `app_url` (contains topic ID). Use the posting `id` with `hey seen`/`hey unseen`. Extract the topic ID from `app_url` for `hey threads` and `hey reply`. -### Email - Topics +### Email - Threads ```bash -hey topic 123 --json # Read full email thread -hey topic 123 --html # Read with raw HTML content +hey threads 123 --json # Read full email thread +hey threads 123 --html # Read with raw HTML content ``` +**ID note:** `hey box` returns postings with an `id` (posting ID) and an `app_url` containing the topic ID. `hey threads` expects the **topic ID** (the numeric ID from `app_url`, e.g. `https://app.hey.com/topics/123` → use `123`). `hey reply` also uses the topic ID. + ### Email - Reply & Compose ```bash hey reply 123 -m "Thanks!" # Reply with inline message hey reply 123 # Reply via $EDITOR -hey compose --to user@example.com --subject "Hello" # Compose new -hey compose --to user@example.com --subject "Hi" -m "Body" # With body +hey compose --to user@example.com --subject "Hello" # Compose new (opens $EDITOR) +hey compose --to user@example.com --subject "Hi" -m "Body" # With inline body +hey compose --subject "Update" --thread-id 12345 -m "msg" # Post to existing thread ``` ### Drafts @@ -178,7 +181,7 @@ hey calendars --json # List calendars (returns array of hey recordings 123 --json # List events in calendar ``` -**Response format:** `hey recordings` returns `{"Calendar::Event": [...]}`. Each event has: `id`, `title`, `starts_at`, `ends_at`, `all_day`, `recurring`, `starts_at_time_zone`. Access events via `.["Calendar::Event"]` in jq. +**Response format:** `hey recordings` returns recordings grouped by type (e.g. `{"Calendar::Event": [...], "Calendar::Habit": [...], "Calendar::Todo": [...]}`). Each recording has: `id`, `title`, `starts_at`, `ends_at`, `all_day`, `recurring`, `starts_at_time_zone`. Access by type key in jq, e.g. `.["Calendar::Event"]`. ### Todos @@ -193,10 +196,13 @@ hey todo delete 123 # Delete a todo ### Habits ```bash -hey habit complete # Mark habit complete for today -hey habit uncomplete # Unmark habit for today +hey habit complete 123 # Mark habit complete for today +hey habit complete 123 --date 2024-01-15 # Mark complete for specific date +hey habit uncomplete 123 # Unmark habit for today ``` +Habit IDs can be found via `hey recordings --json`. + ### Time Tracking ```bash From 5d6ff04adbb0db19d4d7468710298289ad7ea096 Mon Sep 17 00:00:00 2001 From: Rob Zolkos Date: Sun, 8 Mar 2026 21:33:53 -0400 Subject: [PATCH 2/3] Address PR review: use topic_id field, fix Quick Reference placeholders - Remove nonexistent hey seen/unseen references - Document topic_id as primary source instead of app_url parsing - Use placeholders in Quick Reference table --- skills/hey/SKILL.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/skills/hey/SKILL.md b/skills/hey/SKILL.md index 033e9e9..5082e02 100644 --- a/skills/hey/SKILL.md +++ b/skills/hey/SKILL.md @@ -77,8 +77,8 @@ CLI for HEY email: mailboxes, email threads, replies, compose, calendars, todos, |------|---------| | List mailboxes | `hey boxes --json` | | List emails in a box | `hey box imbox --json` | -| Read email thread | `hey threads 123 --json` | -| Reply to email | `hey reply 123 -m "Thanks!"` | +| Read email thread | `hey threads --json` | +| Reply to email | `hey reply -m "Thanks!"` | | Compose email | `hey compose --to user@example.com --subject "Hello"` | | List drafts | `hey drafts --json` | | List calendars | `hey calendars --json` | @@ -147,7 +147,7 @@ hey box 123 --json # List emails in box (by ID) Box names: `imbox`, `feedbox`, `trailbox`, `asidebox`, `laterbox`, `bubblebox` -**Response format:** `hey box` returns `{"box": {...}, "postings": [...]}`. Each posting has: `id` (posting ID), `name` (subject), `seen` (read status), `created_at`, `contacts`, `summary`, `app_url` (contains topic ID). Use the posting `id` with `hey seen`/`hey unseen`. Extract the topic ID from `app_url` for `hey threads` and `hey reply`. +**Response format:** `hey box` returns `{"box": {...}, "postings": [...]}`. Each posting has: `id` (posting ID), `topic_id` (topic ID), `name` (subject), `seen` (read status), `created_at`, `contacts`, `summary`, `app_url`. Use `topic_id` for `hey threads` and `hey reply`. ### Email - Threads @@ -156,7 +156,7 @@ hey threads 123 --json # Read full email thread hey threads 123 --html # Read with raw HTML content ``` -**ID note:** `hey box` returns postings with an `id` (posting ID) and an `app_url` containing the topic ID. `hey threads` expects the **topic ID** (the numeric ID from `app_url`, e.g. `https://app.hey.com/topics/123` → use `123`). `hey reply` also uses the topic ID. +**ID note:** `hey box` returns postings with an `id` (posting ID) and a `topic_id` (topic ID). `hey threads` and `hey reply` expect the **topic ID** — use `topic_id` directly. The `app_url` field also contains the topic ID as a fallback (e.g. `https://app.hey.com/topics/123` → `123`). ### Email - Reply & Compose From 81b2573608235cce845064a367e0a0d46dd38bdb Mon Sep 17 00:00:00 2001 From: Rob Zolkos Date: Sun, 8 Mar 2026 21:45:46 -0400 Subject: [PATCH 3/3] Use placeholders consistently in decision tree and examples --- skills/hey/SKILL.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/skills/hey/SKILL.md b/skills/hey/SKILL.md index 5082e02..7fccdd9 100644 --- a/skills/hey/SKILL.md +++ b/skills/hey/SKILL.md @@ -109,7 +109,7 @@ CLI for HEY email: mailboxes, email threads, replies, compose, calendars, todos, Want to read email? ├── Which mailbox? → hey boxes --json ├── List emails in box? → hey box --json -├── Read full thread? → hey threads --json +├── Read full thread? → hey threads --json └── Launch interactive UI? → hey (no args, launches TUI) ``` @@ -152,8 +152,8 @@ Box names: `imbox`, `feedbox`, `trailbox`, `asidebox`, `laterbox`, `bubblebox` ### Email - Threads ```bash -hey threads 123 --json # Read full email thread -hey threads 123 --html # Read with raw HTML content +hey threads --json # Read full email thread +hey threads --html # Read with raw HTML content ``` **ID note:** `hey box` returns postings with an `id` (posting ID) and a `topic_id` (topic ID). `hey threads` and `hey reply` expect the **topic ID** — use `topic_id` directly. The `app_url` field also contains the topic ID as a fallback (e.g. `https://app.hey.com/topics/123` → `123`). @@ -161,8 +161,8 @@ hey threads 123 --html # Read with raw HTML content ### Email - Reply & Compose ```bash -hey reply 123 -m "Thanks!" # Reply with inline message -hey reply 123 # Reply via $EDITOR +hey reply -m "Thanks!" # Reply with inline message +hey reply # Reply via $EDITOR hey compose --to user@example.com --subject "Hello" # Compose new (opens $EDITOR) hey compose --to user@example.com --subject "Hi" -m "Body" # With inline body hey compose --subject "Update" --thread-id 12345 -m "msg" # Post to existing thread