@learnaltitude/cli 0.2.0 → 0.3.0

package/README.md

@@ -12,6 +12,46 @@ npm install -g @learnaltitude/cli
 Pair the CLI with your account at [app.learnaltitude.com](https://app.learnaltitude.com).
 Supported agents are Claude Code and Codex.
 
+## Connect, bind, and inspect a project
+
+Use the installed agent adapter's connect command to complete the browser device flow. Connecting
+stores a scoped bearer token in the CLI data directory (by default, `~/.altitude/token.json`) with
+owner-only permissions; it does not activate hooks in every directory.
+
+A directory declares WHICH journey it works. From the root of the project, pick from your
+journey list:
+
+```sh
+altitude bind --list            # show your journeys and their statuses
+altitude bind --journey <id>    # bind this directory to one of them
+altitude bind                   # binds directly when exactly one journey is bindable
+```
+
+Binding writes a `.altitude` marker in that directory. Hooks discover the nearest marker while
+walking upward, so the project and its subdirectories are active; invocations without a working
+directory or valid marker are dormant and produce no capture, down-sync, context, or gate work.
+Gate failures in a bound project still fail open. Several directories may bind the same journey
+(git worktrees are the normal case); each directory holds exactly one journey, and its down-synced
+working set is cached per journey in an owner-only file for offline sessions. An abandoned journey
+stays visible in the list but cannot be bound; a paused journey can. When the refreshed or cached
+journey list marks it paused, session start prints the server's paused notice when present and
+keeps gates dormant until a later list refresh observes that you resumed it on Altitude (never
+automatically from the terminal). Older responses without a notice stay silent. When the server
+refuses a binding's journey (deleted, abandoned, or not entitled), the session prints the server's
+explanation instead of silently substituting another project.
+`altitude diagnostics` records these misses and stale bindings; the precise hook behavior is
+defined in the [workshop/server
+protocol](../../docs/mvp-plan.md#workshop--server-protocol-packagesshared).
+If the project is already bound to another journey, inspect the IDs before deliberately replacing
+the marker with `altitude bind --force`.
+
+Use `altitude task --json` for a network-first snapshot of the BOUND journey with local-cache
+fallback; its `source` field says which was used, `journey_status` carries the journey's
+last-known status, and `journey_miss` carries the server's refusal when the bound journey was not
+served. `altitude status` is a local snapshot that includes the nearest binding plus the bound
+journey's cached working-set summaries. Binding requires a connected device token; the command
+tells unconnected users to connect and directs users without a bindable journey back to Altitude.
+
 ## Copied skills installs and updates
 
 Claude Code marketplace installs remain the recommended Claude path and update through that