@learnaltitude/cli 0.3.0 → 0.5.0

package/README.md

@@ -14,9 +14,21 @@ 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 must meet the current compatibility floor documented on the
+[W2 card](../../docs/BUILD-PLAN.md#w2--codex-adapter-config-only-by-mandate). Adapter-native
+connect declares the detected version; the server refuses a parseable version below its floor
+with server-authored remediation. The raw terminal command stamps the version as `"unknown"`,
+which deliberately remains pairable. Other JSON connection failures likewise print the server's
+message; non-JSON failures retain the HTTP status line. 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 +42,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,45 +62,74 @@ 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.
 
-## Copied skills installs and updates
+The envelope also carries `update_available`, a client-local boolean that is true when the CLI is
+behind the latest npm version seen by the last background version check. It is read from the local
+update-check cache only — `altitude task` never makes a version request, so a lesson never waits on
+one. Skills update separately through the agent's plugin system.
+
+Tutor flows can attach the learner's verbatim answer to its canonical concepts. The tutor does
+not grade the answer; grading and any resulting mastery update are server-side:
+
+```sh
+altitude emit quiz-moment --session <id> --question <q> --answer <a> \
+  --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.
+
+## Plugin marketplace installs and updates
+
+Install the Altitude plugin exclusively through the marketplace built into your coding agent. In
+Claude Code, run:
+
+```text
+/plugin marketplace add jasonku09/altitude-skills
+/plugin install altitude@altitude
+```
 
-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:
+For Codex, run these commands in a terminal:
 
 ```sh
-altitude skills install --adapter-config /path/to/adapter/skills-install.json
+codex plugin marketplace add jasonku09/altitude-skills
+codex plugin add altitude@altitude
 ```
 
-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:
+On the first Codex launch after installation, accept the one-time
+`Hooks need review -> Trust all and continue` prompt. Skills update with the agent's plugin system.
+To update only the globally installed Altitude CLI, run:
 
 ```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.
+The command prints a one-line reminder that skills update with the agent, then asks the detected
+global package manager to update `@learnaltitude/cli`. If detection or execution fails, it prints
+the exact manual command instead.
 
 ## 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.
+with a single request to `registry.npmjs.org` for the CLI's latest version. Check attempts are
+throttled for 24 hours; the latest usable result remains cached until a later successful check
+replaces it. The request does not pass through the Altitude service and carries 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. The SessionStart process exits roughly 250 ms
+after its command completes, so this scheduling improves spawn-fallback coverage only when the npm
+request settles 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 disable every version
+check. All check failures are silent and cannot change a command's exit code or discard a
+previously usable cache result.