@harborppm/cli 0.1.1 → 0.3.0

package/README.md

@@ -1,13 +1,35 @@
 # Harbor CLI
 
-[Harbor](https://harborppm.com) from the terminal: what's on you, add and finish tasks, comment, check in, log risks.
+[Harbor](https://harborppm.com) in the terminal: a full-screen app with your whole harbor, and commands for scripts and agents.
 
 ```sh
-npx @harborppm/cli login        # opens your browser once
-npx @harborppm/cli mine
+npm install -g @harborppm/cli
+harbor                          # the full-screen app (signs you in the first time)
+harbor mine                     # or one command at a time
 ```
 
-Or install it: `npm install -g @harborppm/cli`, then `harbor mine`. Needs Node 20 or later.
+Needs Node 22 or later.
+
+## The full-screen app
+
+`harbor` on its own takes over the terminal, like `htop` or `lazygit`, and gives it back when you press `q`. It opens on Harbor's mark (the teal tile, the H and three boats, drawn in half blocks) while your harbor loads, then:
+
+1. **Today**: what's on you, late first; who's waiting on you; your risks and issues.
+2. **Inbox**: the same pings as the website: waiting on you, sign-offs, mentions. Enter opens one; it's marked read.
+3. **Projects**: every portfolio, program and project with its health. A project opens on its board (columns side by side), its list, or its budget and spend ledger (`v`); `e` changes its details: lead, dates, budget, health by hand with a note.
+4. **Programs**: a program's projects and milestones side by side (`m` adds a milestone, space ticks one), its next move and health.
+5. **Risks**: the register, worst first. Enter changes one (status, owner, likelihood, impact, mitigation); `n` logs a risk, issue or decision.
+6. **People**: open and late work and the next four weeks against each person's capacity; Enter changes their capacity, role, or the time they're promised to a program.
+7. **Roadmap**: a portfolio's programs and projects across the months, in their health's colour, ◆ for milestones.
+8. **History**: who changed what, for a portfolio, program or project (`s` picks which).
+
+A task changes in place too: title, status, owner, due date (`2026-10-14`, `today`, `+3`), priority, project, notes, checklist steps, comments.
+
+Keys: `↑↓` (or `j k`) and `←→` (or `h l`) move, Enter opens, Esc goes back, `:` finds anything (a screen, "new project", a project or program by name), `/` finds a task by its key or words, `n` makes something new, `e` changes what's open, `[` `]` move a card a column, `x` marks it done, `d` deletes (it asks first), `u` undoes your last change, `H` switches harbor, `?` lists them all.
+
+`harbor help` shows the mark too, in a terminal with colour; piped, or with `NO_COLOR` set, it's plain text. `harbor --version` says which version you have.
+
+It runs on the same engine as the website: health, task keys, limits and undo work the same way, changes save as you go (the header says when, and holds them while you're offline), and changes anyone makes on the website or elsewhere show up within a couple of seconds. It needs full access, which `harbor login` asks for by name; an older sign-in is asked again the first time.
 
 ## Signing in
 
@@ -38,7 +60,7 @@ Every command takes `--harbor NAME` when you're in more than one, and `--json` f
 
 Harbor holds back what it would hold back in the app: finishing a task that still waits on another, or going past a column's limit. The CLI says so and names the flag that goes ahead (`--confirm`, `--over-limit`).
 
-Every change shows in Harbor's History as yours, "via Harbor CLI". Nothing the CLI does deletes anything.
+Every change shows in Harbor's History as yours, "via Harbor CLI". The commands never delete anything; the full-screen app can, as the website can, and asks first.
 
 ## Another server
 
@@ -46,7 +68,7 @@ Every change shows in Harbor's History as yours, "via Harbor CLI". Nothing the C
 
 ## Developing
 
-No dependencies. `npm test` runs the CLI's tests against a stand-in Harbor; `e2e/cli.test.mjs` in the repository drives it against a real one.
+The commands are plain Node with no dependencies. The full-screen app is `src/tui` in the repository (React with Ink), bundled into `dist/app.mjs` by `node cli/build.mjs`; Ink and React are its only dependencies. `npm test` runs the CLI's tests against a stand-in Harbor; `e2e/cli.test.mjs` and `e2e/terminal-app.test.mjs` drive it against a real one.
 
 ## License