@learnaltitude/cli 0.1.0 → 0.3.0

package/README.md

@@ -11,3 +11,82 @@ 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
+marketplace. For Codex or a manual Claude Code copy, install the public skills through the target
+declaration shipped by the relevant adapter:
+
+```sh
+altitude skills install --adapter-config /path/to/adapter/skills-install.json
+```
+
+The first install remembers the resolved target in the CLI data directory (by default,
+`~/.altitude/skills-manifest.json`), including the exact `jasonku09/altitude-skills` commit and a
+SHA-256 content hash for every managed file. Later updates need no adapter flag:
+
+```sh
+altitude update
+```
+
+Use `--ref <commit-sha>` with either command to pin or roll back to a particular public-repository
+commit. Updates change only manifest-managed files plus new upstream paths; unrelated skills in a
+shared target are left alone, while managed files removed upstream are removed locally. An edited
+managed file or colliding pre-CLI copy is backed up in the CLI data directory (by default,
+`~/.altitude/skills-backups/`) before the upstream version replaces or removes it. Backups never
+live in an agent skills directory. If no copied install is configured, the skills step is an
+informative no-op because marketplace or plugin-managed skills update through the agent.
+After the skills step completes or is skipped, `altitude update` asks the detected global package
+manager to update `@learnaltitude/cli`; if detection or execution fails, it prints the exact manual
+command instead. A genuine copied-skills sync failure stops before the CLI self-update.
+
+## Network disclosure
+
+The distributed client uses the user's own agent subscription and no Altitude-held API key.
+Interactive `connect`, `diagnostics`, and `update` commands make anonymous, direct version checks
+to GitHub (the public skills repository's `main` commit) and the npm registry (the CLI's latest
+version). Results are cached in the CLI data directory for about 24 hours. Skills downloads also
+come directly from GitHub. These requests do not pass through the Altitude service and carry no
+Altitude credentials. Hooks, gates, queue flushers, and other non-interactive paths never perform
+the version check; all check failures are silent and cannot change a command's exit code.