tabstax-cli 0.1.6 → 0.1.7

package/README.md

@@ -1,107 +1,310 @@
-# Hey CLI - TabStax Command Line Interface
+# hey — TabStax CLI
 
-A conversational CLI for managing your Next Actions directly from the terminal. Works with the [TabStax](https://tabstax.app) browser extension.
+**Log what you're doing. See what the team is doing. Stay in flow.**
 
-## Installation
+`hey` is the terminal interface for [TabStax](https://tabstax.app) — a lightweight command for individuals and teams to track next actions, breadcrumb decisions, and coordinate work without leaving the tools where the work actually happens: your shell, your editor, Claude Code, or a CI pipeline.
 
 ```bash
 npm install -g tabstax-cli
 ```
 
-## Quick Start
+Requires Node.js 18+ and a [TabStax account](https://tabstax.app).
 
-```bash
-# Login to your TabStax account
-hey login
+---
 
-# Set your default project
-hey use "My Project"
+## The idea
 
-# Add a next action
-hey "Build the login page"
+Most task tools pull you out of flow. You stop, switch to a browser, navigate, type something, switch back. Two minutes gone, context broken.
 
-# Add a breadcrumb (completed action)
-hey -x "Fixed the auth bug"
+`hey` is one command. You're already in the terminal. Log the next thing, see the team board, mark something done — and you're back. Every action is synced to the [TabStax web app](https://dash.tabstax.app) and the browser extension, with your `@handle` attached, so the team always sees who's doing what without a standup.
 
-# List your actions
-hey ls
+**Works wherever you work:**
+
+| Where | How |
+|-------|-----|
+| **Terminal** | `hey "message"` — one command, no context switch |
+| **Claude Code** | Ask Claude to read `hey ls --all` and act on it |
+| **Web app** | `dash.tabstax.app` — attention board with handle pills and filters |
+| **Browser extension** | Start Here page per project, actions synced live |
+| **CI / scripts** | Pipe failures, deploys, or events directly into a shared stax |
 
-# Mark action #1 as done
+---
+
+## Quick start
+
+```bash
+hey login
+hey use "my-project"
+hey "Fix the token refresh race condition"
+hey ls
 hey done 1
 ```
 
+---
+
 ## Commands
 
-### Actions
+### Add and complete actions
+
 | Command | Description |
 |---------|-------------|
-| `hey "message"` | Add a next action |
-| `hey -x "message"` | Add a breadcrumb (past tense, already done) |
-| `hey done [n]` | Mark action #n as complete (default: #1) |
+| `hey "message"` | Add a next action to your current project |
+| `hey -x "message"` | Log a breadcrumb — something you already did |
+| `hey done [n]` | Mark action #n as done (default: first action) |
 | `hey rm <n>` | Remove action #n |
-| `hey edit <n> "text"` | Edit action #n content |
-| `hey mv <from> <to>` | Move action to different position |
+| `hey edit <n> "text"` | Edit action #n |
+| `hey mv <from> <to>` | Reorder: move action to a different position |
+
+### See what's on
 
-### Listing
 | Command | Description |
 |---------|-------------|
-| `hey ls` | List actions for current project |
-| `hey ls stax` | List all your stax with priorities |
-| `hey ls --all` | Expanded view with actions per stax |
-| `hey ls --done` | Show breadcrumbs only |
+| `hey ls` | List actions for the current project |
+| `hey ls stax` | All your projects with priorities |
+| `hey ls --all` | Expanded: top 3 actions per project |
+| `hey ls --done` | Breadcrumbs — what's been completed |
+| `hey ls -c 20` | Show up to 20 items |
+
+### Projects and context
 
-### Projects & Priority
 | Command | Description |
 |---------|-------------|
-| `hey use <project>` | Set default project (fuzzy matched) |
-| `hey pri <project> <level>` | Set priority: `must`, `should`, `good`, `meh` |
-| `hey which` | Show current context |
+| `hey use <project>` | Switch default project (fuzzy matched) |
+| `hey which` | Show current project and logged-in user |
+| `hey pri <project> <level>` | Set priority: `must` `should` `good` `meh` |
+
+### Auth
 
-### Authentication
 | Command | Description |
 |---------|-------------|
-| `hey login` | Log in to TabStax |
+| `hey login` | Log in (interactive, password masked) |
 | `hey logout` | Log out |
-| `hey whoami` | Show current user |
-| `hey status` | Show CLI status |
+| `hey whoami` | Show current user and handle |
+| `hey status` | Session and config summary |
 
-## Features
+---
 
-- **7-action limit** per project to maintain focus (bypass with `--force`)
-- **Fuzzy project matching** - `hey use tab` matches "TabStax"
-- **Priority icons** - ★ must, ◆ should, ○ good, · meh
-- **Breadcrumbs** - Track what you've done, not just what's next
-- **Syncs with extension** - Changes appear in TabStax browser extension instantly
+## For individuals
 
-## Examples
+### Daily dev flow
 
 ```bash
-# Quick workflow
-hey use "insurance"
-hey "Call agent about claim"
-hey "Upload documents"
-hey -x "Submitted form 1099"
-hey done 1
+# Morning: pick up exactly where you left off
+hey use "backend-api"
 hey ls
 
-# See all projects
+# Log as you go — one line, stay in the terminal
+hey "Investigate N+1 query in /dashboard endpoint"
+hey "Write test for edge case in token refresh"
+hey -x "Fixed auth middleware — sessions now persist across restarts"
+
+# End of day
+hey ls --done
+```
+
+### Keeping a decision log
+
+The `-x` flag is for breadcrumbs: things you *already did*, decisions made, or context you want to preserve. They appear in the **Start Here** page on the extension so future-you (or a teammate) can see why the project is in its current state.
+
+```bash
+hey -x "Decided against Redis for session cache — latency was fine without it"
+hey -x "Upgraded to Postgres 16 — no breaking changes, pooler config updated"
+hey -x "Deprioritised dark mode until v2 — product call on 2026-03-03"
+```
+
+---
+
+## For teams — collaborative stax
+
+Set any stax to **Collaborative** mode in the TabStax extension (Share → Collaborative Project). Every team member with access can add actions using `hey`, and every action is tagged with their `@handle`.
+
+### How it works
+
+1. Owner creates the stax in the extension and sets it to Collaborative
+2. Each person runs `hey use <stax-name>` once
+3. Everyone adds actions from wherever they work — terminal, Claude Code, CI scripts
+4. The web app and Start Here page show each person's actions with a colour-coded handle pill
+5. A filter bar lets anyone narrow by contributor in one click
+
+```bash
+# Join a team stax
+hey use "sprint-47"
+
+# Add your actions — they'll show up under your @handle
+hey "Implement OAuth handshake"
+hey "Write migration for invites table"
+
+# Log what you shipped
+hey -x "Deployed API gateway — load balanced across 3 nodes"
+
+# See the full team board
+hey ls
+
+# Check all projects
 hey ls stax
+```
+
+Every action is visible in real time on `dash.tabstax.app` — no standup needed to answer "what's everyone working on?"
+
+### @handle attribution
+
+Every action added via `hey` is tagged with your `@handle` (set when you create your TabStax account). In the web app and the extension Start Here page:
+
+- Each action shows a **pastel @handle pill** to the right of the text
+- Colour is consistent per person across all views and projects
+- A **filter bar** lets you show one or more contributors' actions at a time
+- Done actions can be shown or hidden independently
 
-# Set project as high priority
-hey pri "insurance" must
+Check your handle:
 
-# Force add when at limit
-hey "One more thing" --force
+```bash
+hey whoami
 ```
 
-## Requirements
+---
+
+## Team workflows
+
+### Sprint coordination
+
+```bash
+# Sprint kickoff: team lead creates the stax, everyone joins once
+hey use "sprint-47"
+
+# During the sprint: add as you pick up work
+hey "Implement dark mode toggle"
+hey "Write unit tests for payment service"
+
+# Mark done as you go — updates the board for everyone
+hey done 1
+
+# Sprint review: full breadcrumb trail of what shipped
+hey ls --done
+```
+
+### Incident response
+
+When something breaks, `hey` gives every responder a shared log so nothing gets lost between shifts or calls.
+
+```bash
+# Everyone joins the incident stax
+hey use "incident-2026-03-03"
+
+# Log what you're trying in real time
+hey "Check database connection pool — seeing timeouts"
+hey "Rolling restart of API pods"
+hey -x "Confirmed: root cause was stale connection pool config"
+hey done 1
+
+# Hand off cleanly — full timeline is in the web app
+hey ls --done -c 50
+```
+
+### AI agent governance
+
+When multiple AI agents are running in parallel (Claude Code subagents, CI bots, automated pipelines), `hey` gives you a shared log of what each agent did. Point each agent at a shared stax and every action and decision is recorded with attribution.
+
+```bash
+# Each agent logs to the shared stax before and after major steps
+hey -x "Agent:researcher — analysed 47 files, found 3 auth patterns"
+hey -x "Agent:coder — implemented OAuth flow, 312 lines changed"
+hey "Agent:tester — run contract tests before merge"
+```
+
+The web app shows the full timeline, colour-coded by agent, so a human reviewer can see exactly what happened and what still needs sign-off.
+
+### Open source / research coordination
+
+```bash
+hey use "oss-backlog"
+
+hey "Review PR #412 — new auth provider"
+hey "Triage issues labelled good-first-issue"
+hey -x "Merged PR #389 — storage quota fix"
+```
+
+---
+
+## Claude Code integrations
+
+`hey` + Claude Code turns your stax into a programmable task queue. Because `hey ls` outputs plain text, Claude can read, reason about, and act on it directly.
+
+### Morning standup digest
+
+```
+Read my current stax using `hey ls --all` and write a short standup update
+I can paste into Slack. Group by project, highlight the top action per project,
+and flag anything that's been sitting for more than 3 days.
+```
+
+### Sprint health check
+
+```
+Run `hey ls stax` to see all my projects. For any project at 6+ actions out of 7
+(near the limit), suggest which actions could be combined, deferred, or done first.
+Output a prioritised plan.
+```
+
+### Incident post-mortem
+
+```
+The shared stax "incident-2026-03-03" has a full breadcrumb trail.
+Run `hey ls --done -c 50` to get all completed actions.
+Draft a post-mortem with timeline, root cause, and action items.
+```
+
+### Auto-log CI failures
+
+```bash
+# In your CI script — on test failure:
+hey "CI failed: $(git log -1 --pretty='%s') — $(git rev-parse --short HEAD)"
+```
+
+```
+Watch `hey ls` for actions containing "CI failed". For each one, look up
+the commit, fetch the test output, and suggest a fix.
+```
+
+### End-of-week retrospective
+
+```
+Run `hey ls --done -c 100` across my top 3 stax. Summarise what shipped
+this week, what's still in flight, and suggest 3 focus areas for next week
+based on what's been sitting longest.
+```
+
+---
+
+## Features
+
+- **7-action limit per project** keeps lists focused and forces prioritisation (`--force` to bypass)
+- **Fuzzy project matching** — `hey use tab` matches "TabStax Backend"
+- **Priority icons** — ★ must · ◆ should · ○ good · · meh
+- **Breadcrumbs** (`-x`) — log decisions and completed work, not just what's next
+- **@handle attribution** — every action tagged to you; colour-coded pills in web + extension
+- **Shared stax** — any team member can add to a collaborative stax; syncs in real time
+- **Auto session refresh** — stays logged in across restarts; prompts cleanly on expiry
+- **Works in CI/scripts** — no interactive mode required for adding actions
+
+---
+
+## Session management
+
+Sessions use a long-lived refresh token and auto-refresh 5 minutes before expiry. You won't be interrupted mid-session. If your refresh token expires (7+ days of no use), you'll get a clear prompt to re-login.
+
+```bash
+hey login    # interactive, password masked
+hey whoami   # check session state
+hey status   # full config + auth info
+```
 
-- Node.js 18+
-- TabStax account (free or paid)
+---
 
 ## Links
 
-- [TabStax Extension](https://tabstax.app)
+- [TabStax](https://tabstax.app)
+- [Attention board](https://dash.tabstax.app)
+- [Chrome Web Store](https://chromewebstore.google.com/detail/tabstax-pick-up-where-you/mjplcglfdelgdcoalbgechkeophncjmf)
 - [GitHub](https://github.com/Hulupeep/tabstax)
 - [Issues](https://github.com/Hulupeep/tabstax/issues)
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "tabstax-cli",
-  "version": "0.1.6",
-  "description": "Hey CLI - Manage your Next Actions from the terminal. The CLI companion for TabStax browser extension.",
+  "version": "0.1.7",
+  "description": "Log what you're doing. See what the team is doing. Stay in flow. The terminal interface for TabStax.",
   "type": "module",
   "main": "dist/index.js",
   "bin": {