@learnaltitude/cli 0.2.0 → 0.4.0

package/README.md

@@ -12,6 +12,75 @@ 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
+
+From a terminal, name the agent this computer will use and complete the browser device flow:
+
+```sh
+altitude connect --agent claude-code
+altitude connect --agent codex
+```
+
+Use one command, not both. Codex requires Codex CLI 0.131.0 or newer; its adapter-native connect
+command enforces that floor, while the raw terminal command does not. 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.
+Binding during a running agent session takes effect on its next learner turn or tool lifecycle;
+you do not need to restart the agent.
+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. Its full shape is the
+[`taskEnvelopeSchema`](../shared/src/workshop.ts) contract. `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.
+
+The envelope also carries `update_available`, a client-local boolean: true when a **copied** skills
+install (or the CLI itself) is behind what the last background version check saw upstream. It is
+read from the local update-check cache only — `altitude task` never makes a version request, so a
+lesson never waits on one — and it is always false for marketplace/plugin-managed skills, which
+update with the agent rather than through `altitude update`.
+
+Tutor flows can attach a graded answer to its canonical concepts so the server can update the
+corresponding mastery cards:
+
+```sh
+altitude emit quiz-moment --session <id> --question <q> --answer <a> \
+  --verdict <correct|partial|incorrect> --concepts <id,...>
+```
+
+`--concepts` accepts comma-separated IDs or repeated flags. The CLI trims empty entries, removes
+duplicates in first-seen order, and omits `concept_ids` when no non-empty ID is supplied.
+
 ## Copied skills installs and updates
 
 Claude Code marketplace installs remain the recommended Claude path and update through that
@@ -46,7 +115,19 @@ command instead. A genuine copied-skills sync failure stops before the CLI self-
 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.
+version). Check attempts are throttled for about 24 hours; the latest usable result remains cached
+until a later successful check replaces it. Skills downloads also come directly from GitHub. These
+requests do not pass through the Altitude service and carry no Altitude credentials.
+
+A bound SessionStart schedules the same anonymous check without awaiting it, and the detached
+flusher daemon keeps doing so in the background. Background checks run only on a device that holds
+a copied skills install — otherwise the answer could never change anything the CLI can act on. The
+SessionStart process exits roughly 250 ms after its command completes, so this scheduling improves
+spawn-fallback coverage only when both version requests settle inside that remaining budget; it
+does not guarantee fallback coverage. An interrupted attempt writes no marker and therefore cannot
+suppress a later daemon or command attempt. Because unbound directories keep hooks dormant, they
+do not start a flusher or receive background refreshes; their cache is refreshed only by
+`connect`, `diagnostics`, or `update`. `altitude task --json` only reads the cache and never makes a
+request itself. Gates and other hooks never perform the version check. Set
+`ALTITUDE_DISABLE_UPDATE_CHECK=1` to turn every version check off. All check failures are silent
+and cannot change a command's exit code or discard a previously usable cache result.