@learnaltitude/cli 0.3.0 → 0.4.0

package/README.md

@@ -14,9 +14,17 @@ 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.
+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:
@@ -30,6 +38,8 @@ altitude bind                   # binds directly when exactly one journey is bin
 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
@@ -48,9 +58,28 @@ 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.
+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
 
@@ -86,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.