@harborppm/cli 0.36.0 → 0.37.0

package/README.md

@@ -61,6 +61,32 @@ Your harbor is the same one at [harborppm.com](https://harborppm.com/today?utm_s
 
 The website has the commands too: turn on **Command line at the bottom** in your menu, press `/`, and type `mine`, `add "Call the mill" #ridge @sam --due fri` or `done RR-12`.
 
+## Your plan in your repository
+
+`harbor init` in a code project writes a `.harbor/` folder at the top of the repository: one plain file per task in a project, with its title, status, owner, due date, priority and what it waits on, and its notes below. Edit them by hand, review them in pull requests, keep them in git like any code.
+
+```sh
+harbor init "Cedar site"         # or its key: harbor init CS
+$EDITOR .harbor/tasks/CS-4.md    # status: doing, owner: Sam, due: 2026-11-07…
+harbor sync                      # sends the edits, brings the website's back
+```
+
+```md
+---
+title: Move checkout to the new API
+status: doing
+owner: Sam Rivera
+due: 2026-11-07
+priority: high
+waits: [CS-2]
+---
+Old endpoints go away on Nov 20.
+```
+
+A new file with any name is a new task: `harbor sync` adds it and renames it to its key. A field changed in a file and not on the website goes to Harbor; one changed in both places keeps the website's and says so. Removing a file doesn't delete the task (mark it done instead). On a fresh clone, run `harbor sync` before editing. `harbor init --hook` adds a git post-commit hook that syncs after each commit.
+
+No account? `harbor init --local` makes a plan that lives only in the folder (the rest of it in `.harbor/plan.json`), and `harbor` in that folder opens it full screen, offline and free. Later, `harbor init PROJECT` moves its tasks into a project on harborppm.com.
+
 ## In your shell prompt
 
 `harbor prompt` prints a few characters for your prompt: `⚓ 2 today · 1 late`, with late work in coral, and nothing at all when you're clear. It never waits on the network: it shows the counts it kept and fetches new ones in the background when they're more than five minutes old, or after you change a task. `harbor prompt --init zsh` (or `bash`, `fish`, `starship`) prints the lines to add to your shell's setup, so `harbor prompt --init starship >> ~/.config/starship.toml` does it in one go:
@@ -130,6 +156,9 @@ harbor premortem PROJECT ["WHAT WENT WRONG"] [--start]
 harbor voyage PROJECT ["YOUR LINE"]
 harbor note PROJECT ["NOTE"] [--opens DATE|--milestone NAME|--off-track]
 harbor limit PROJECT [COLUMN N|none]
+harbor init [PROJECT] [--hook]              a project's tasks as files in this repository
+harbor init --local [NAME]                  a plan in this folder alone, no account
+harbor sync [--quiet]                       the files and the website, in step both ways
 harbor handover PERSON [--to NAME] [--until DATE] [--note TEXT] [--keep ID,ID] [--confirm]
 harbor handback PERSON
 harbor agent [--agent NAME]
@@ -152,7 +181,7 @@ When you belong to more than one harbor, say which: `--harbor NAME` on the comma
 
 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". The commands never delete anything; the full-screen app can, as the website can, and asks first.
+Every change shows in Harbor's History as yours, "via Harbor CLI". The commands never delete anything (`harbor sync` included: removing a task's file brings it back); the full-screen app can, as the website can, and asks first.
 
 ## Another server