@learnaltitude/cli 0.5.2 → 0.6.0

package/README.md

@@ -68,10 +68,14 @@ that includes the nearest binding plus the bound journey's cached working-set su
 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 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.
+The envelope also carries two update signals, both derived from the server's `client_releases`
+answer on the settings down-sync (the server owns "what's current"; there is no npm registry
+check). `update_available` is true when the CLI is behind the server's latest — its meaning is
+unchanged for older plugin markdown. `update_notices` is the successor surface: zero, one, or two
+server-authored lines (CLI and/or plugin), compared live against the installed versions on every
+read. Routine notices are offered at most once per session; urgent notices repeat within the
+session. `altitude task` adds no version request of its own — 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:
@@ -86,15 +90,32 @@ duplicates in first-seen order, and omits `concept_ids` when no non-empty ID is
 
 ## Plugin marketplace installs and updates
 
-Install the Altitude plugin exclusively through the marketplace built into your coding agent. In
-Claude Code, run:
+Install the Altitude plugin exclusively through the marketplace built into your coding agent. For
+Claude Code, open a terminal and start Claude Code:
+
+```sh
+claude
+```
+
+Then run these commands inside that terminal session:
 
 ```text
 /plugin marketplace add jasonku09/altitude-skills
 /plugin install altitude@altitude
 ```
 
-For Codex, run these commands in a terminal:
+When the installer asks for a scope, choose the user scope so the plugin is available across all
+projects, including the new project folder created by your first lesson. If the install summary
+asks you to run `/reload-plugins`, run it; newer Claude Code versions activate the plugin in place.
+The VS Code built-in terminal works for this flow. The extension chat panel uses its separate
+`/plugins` manager instead.
+
+Start the lesson from a terminal with `claude --permission-mode auto`, then enter
+`/altitude:begin`. Auto mode clears routine approval prompts while Claude Code's separate safety
+checks screen every action and block risky ones; it is a safeguard, not a guarantee.
+
+For Codex, update Codex to the latest version first, then run these commands in a terminal. Older
+Codex CLI releases do not recognize the plugin commands.
 
 ```sh
 codex plugin marketplace add jasonku09/altitude-skills
@@ -102,7 +123,9 @@ codex plugin add altitude@altitude
 ```
 
 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.
+`Hooks need review -> Trust all and continue` prompt. To start the first lesson, type `$begin` and
+press Enter twice; the second press expands the command in Codex's composer. Skills update with the
+agent's plugin system.
 
 **Neither half updates on its own by default.** Claude Code enables marketplace auto-update only
 for official Anthropic marketplaces; `altitude` is third-party, so its auto-update starts off.
@@ -126,21 +149,12 @@ auto-update toggle. The floor is server-owned — raising it needs no client rel
 
 ## 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
-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.
+The distributed client uses the user's own agent subscription and no Altitude-held API key. The
+CLI makes no third-party requests: the old anonymous `registry.npmjs.org` version check is gone.
+Freshness now rides the existing authenticated settings down-sync — the request reports the
+installed CLI and plugin versions as query parameters, and the response's `client_releases` block
+carries the server's latest versions plus the notice copy. No new request is added anywhere:
+`connect`, `diagnostics`, and `update` read the cached down-sync answer only; `altitude task
+--json` compares against its existing network-first down-sync or cache fallback; and hooks compare
+against the SessionStart pull or its cache. Gates never perform any version work. Every comparison
+failure is silent and cannot change a command's exit code.