@detergent-software/atk 8.9.0-dev.3 → 8.9.0-dev.30

package/CHANGELOG.md

@@ -1,3 +1,207 @@
+## [8.9.0-dev.30](https://emergentcode.visualstudio.com/Emergent%20Software/_git/Emergent.AgenticToolkit/branchCompare?baseVersion=GTv8.9.0-dev.29&targetVersion=GTv8.9.0-dev.30) (2026-10-19)
+
+### Bug Fixes
+
+* **cli:** hold the lock over setup's .atkrc.json write too ([8ae955a](https://emergentcode.visualstudio.com/Emergent%20Software/_git/Emergent.AgenticToolkit/commit/8ae955a2e9575f53e71d002a02cb9e3f1142c5c6))
+* **cli:** take the lockfile lock in atk setup and setup --user ([557ec69](https://emergentcode.visualstudio.com/Emergent%20Software/_git/Emergent.AgenticToolkit/commit/557ec695efa1a6d42e67e3495d3cbf54236a3469))
+
+## [8.9.0-dev.29](https://emergentcode.visualstudio.com/Emergent%20Software/_git/Emergent.AgenticToolkit/branchCompare?baseVersion=GTv8.9.0-dev.28&targetVersion=GTv8.9.0-dev.29) (2026-10-19)
+
+### Bug Fixes
+
+* **cli:** check every config entry's file before removing anything ([57f7cb9](https://emergentcode.visualstudio.com/Emergent%20Software/_git/Emergent.AgenticToolkit/commit/57f7cb95e1fe0f263bb20f8b7a535522183a2c9d))
+* **cli:** keep lockfile config entry files inside their scope ([6909872](https://emergentcode.visualstudio.com/Emergent%20Software/_git/Emergent.AgenticToolkit/commit/6909872f0250b6c92420f1bf9ab406d97639b6db))
+
+## [8.9.0-dev.28](https://emergentcode.visualstudio.com/Emergent%20Software/_git/Emergent.AgenticToolkit/branchCompare?baseVersion=GTv8.9.0-dev.27&targetVersion=GTv8.9.0-dev.28) (2026-10-19)
+
+### Bug Fixes
+
+* **cli:** remove publish staging once, in order, after an abort (ATK-627) ([c00839b](https://emergentcode.visualstudio.com/Emergent%20Software/_git/Emergent.AgenticToolkit/commit/c00839bf189043db0d82ecaaf4c491bda989dc45))
+
+## [8.9.0-dev.27](https://emergentcode.visualstudio.com/Emergent%20Software/_git/Emergent.AgenticToolkit/branchCompare?baseVersion=GTv8.9.0-dev.26&targetVersion=GTv8.9.0-dev.27) (2026-10-19)
+
+### Bug Fixes
+
+* **cli:** exit 1 when prune can't remove an orphan (ATK-608) ([6ab0f7f](https://emergentcode.visualstudio.com/Emergent%20Software/_git/Emergent.AgenticToolkit/commit/6ab0f7f6c41706aa1b8d331784cbfb7a0d7d5a11))
+
+### Refactoring
+
+* **cli:** list bare atk's commands from the command manifest (ATK-608) ([f28604c](https://emergentcode.visualstudio.com/Emergent%20Software/_git/Emergent.AgenticToolkit/commit/f28604c0e8c11f3059ec96caf3cc224fe6d02a0b))
+* **cli:** run prune's removal loop once, from lib/pruner.ts (ATK-608) ([7c2fc6d](https://emergentcode.visualstudio.com/Emergent%20Software/_git/Emergent.AgenticToolkit/commit/7c2fc6dfe5b7c31056e5b579354a006e1a595fcf))
+* **cli:** tidy prune after review (ATK-608) ([16cdfb6](https://emergentcode.visualstudio.com/Emergent%20Software/_git/Emergent.AgenticToolkit/commit/16cdfb634e21f924501a4a6b30c0981c886df492))
+
+## [8.9.0-dev.26](https://emergentcode.visualstudio.com/Emergent%20Software/_git/Emergent.AgenticToolkit/branchCompare?baseVersion=GTv8.9.0-dev.25&targetVersion=GTv8.9.0-dev.26) (2026-10-18)
+
+### Performance
+
+* **cli:** download a multi-tool install's assets once, 4 at a time (ATK-606) ([eb23bcb](https://emergentcode.visualstudio.com/Emergent%20Software/_git/Emergent.AgenticToolkit/commit/eb23bcb0dc54454e23a4d33a4e280fba17b36191))
+* **cli:** start no plan download after one has failed (ATK-606) ([2cff0e2](https://emergentcode.visualstudio.com/Emergent%20Software/_git/Emergent.AgenticToolkit/commit/2cff0e2f6ef755afdaf8993c804bafd73df0724a))
+
+## [8.9.0-dev.25](https://emergentcode.visualstudio.com/Emergent%20Software/_git/Emergent.AgenticToolkit/branchCompare?baseVersion=GTv8.9.0-dev.24&targetVersion=GTv8.9.0-dev.25) (2026-10-18)
+
+### Performance
+
+* **cli:** check npm dist-tags once a day for the update banner (ATK-604) ([2406327](https://emergentcode.visualstudio.com/Emergent%20Software/_git/Emergent.AgenticToolkit/commit/24063270c67aa915b2d48b306facf09f28b1750a))
+
+## [8.9.0-dev.24](https://emergentcode.visualstudio.com/Emergent%20Software/_git/Emergent.AgenticToolkit/branchCompare?baseVersion=GTv8.9.0-dev.23&targetVersion=GTv8.9.0-dev.24) (2026-10-18)
+
+### Bug Fixes
+
+* **cli:** name the failing field in validation errors (ATK-602) ([7e58c56](https://emergentcode.visualstudio.com/Emergent%20Software/_git/Emergent.AgenticToolkit/commit/7e58c56387eac4f8304799d7b5b491decf942b56))
+
+## [8.9.0-dev.23](https://emergentcode.visualstudio.com/Emergent%20Software/_git/Emergent.AgenticToolkit/branchCompare?baseVersion=GTv8.9.0-dev.22&targetVersion=GTv8.9.0-dev.23) (2026-10-18)
+
+### Bug Fixes
+
+* **cli:** cover older lockfile entries in publish --from-installed (ATK-601) ([cfa7ea9](https://emergentcode.visualstudio.com/Emergent%20Software/_git/Emergent.AgenticToolkit/commit/cfa7ea9fa4b910c9e6210c3f4ea06940649d64e7))
+* **cli:** give publish --from-installed real metadata (ATK-601) ([25e8552](https://emergentcode.visualstudio.com/Emergent%20Software/_git/Emergent.AgenticToolkit/commit/25e8552caa0643fd4c634fec3a3ac21e806f11f6))
+* **cli:** keep --with folders on publish --from-installed (ATK-601) ([50a4333](https://emergentcode.visualstudio.com/Emergent%20Software/_git/Emergent.AgenticToolkit/commit/50a4333a8ccf2f82e8c66a82fdd23b3d54acfa67))
+
+## [8.9.0-dev.22](https://emergentcode.visualstudio.com/Emergent%20Software/_git/Emergent.AgenticToolkit/branchCompare?baseVersion=GTv8.9.0-dev.21&targetVersion=GTv8.9.0-dev.22) (2026-10-18)
+
+### Bug Fixes
+
+* **cli:** apply publish --bump in a terminal without a prompt (ATK-599) ([2cc3015](https://emergentcode.visualstudio.com/Emergent%20Software/_git/Emergent.AgenticToolkit/commit/2cc301509cfca79990d13620cf9909214d2053b1))
+
+### Documentation
+
+* **cli:** say publish applies --bump before it prompts (ATK-599) ([102ab5c](https://emergentcode.visualstudio.com/Emergent%20Software/_git/Emergent.AgenticToolkit/commit/102ab5c522b82d10f603b69768abe4d3a3e2aa12))
+
+## [8.9.0-dev.21](https://emergentcode.visualstudio.com/Emergent%20Software/_git/Emergent.AgenticToolkit/branchCompare?baseVersion=GTv8.9.0-dev.20&targetVersion=GTv8.9.0-dev.21) (2026-10-18)
+
+### Bug Fixes
+
+* **cli:** don't repeat a failed refresh's reason in doctor (ATK-598) ([bd7479f](https://emergentcode.visualstudio.com/Emergent%20Software/_git/Emergent.AgenticToolkit/commit/bd7479fd7e4e5845a0be7b736b90279c95236107))
+* **cli:** give the right fix for sign-in errors under ATK_TOKEN (ATK-598) ([0c929ae](https://emergentcode.visualstudio.com/Emergent%20Software/_git/Emergent.AgenticToolkit/commit/0c929aec047d8a4153ae8ffbc7409eeab82960ae))
+* **cli:** say a session renews the token whoami shows (ATK-598) ([516727d](https://emergentcode.visualstudio.com/Emergent%20Software/_git/Emergent.AgenticToolkit/commit/516727d1f8c4f697a09725682be57e55bdc61570))
+
+## [8.9.0-dev.20](https://emergentcode.visualstudio.com/Emergent%20Software/_git/Emergent.AgenticToolkit/branchCompare?baseVersion=GTv8.9.0-dev.19&targetVersion=GTv8.9.0-dev.20) (2026-10-18)
+
+### Bug Fixes
+
+* **cli:** leave help, version and option values to commander (ATK-594) ([da88538](https://emergentcode.visualstudio.com/Emergent%20Software/_git/Emergent.AgenticToolkit/commit/da8853890f2ae945b920e92d1e5d93fc3d4798d6))
+* **cli:** report an unknown command with a suggestion (ATK-594) ([dd37320](https://emergentcode.visualstudio.com/Emergent%20Software/_git/Emergent.AgenticToolkit/commit/dd373200a68f08405831fd96ea01f840af56ff27))
+
+## [8.9.0-dev.19](https://emergentcode.visualstudio.com/Emergent%20Software/_git/Emergent.AgenticToolkit/branchCompare?baseVersion=GTv8.9.0-dev.18&targetVersion=GTv8.9.0-dev.19) (2026-10-18)
+
+### Bug Fixes
+
+* **cli:** keep unmerged publish versions out of the lockfile (ATK-592) ([b1c510b](https://emergentcode.visualstudio.com/Emergent%20Software/_git/Emergent.AgenticToolkit/commit/b1c510bf5d5ce51087f8305261fc1925d89c4d5b))
+* **cli:** leave the lockfile untouched by a publish (ATK-592) ([76f5f79](https://emergentcode.visualstudio.com/Emergent%20Software/_git/Emergent.AgenticToolkit/commit/76f5f791f27bea4445e36b3dc5df0773ff4894d5))
+
+## [8.9.0-dev.18](https://emergentcode.visualstudio.com/Emergent%20Software/_git/Emergent.AgenticToolkit/branchCompare?baseVersion=GTv8.9.0-dev.17&targetVersion=GTv8.9.0-dev.18) (2026-10-18)
+
+### Bug Fixes
+
+* **cli:** keep the command manifest honest (ATK-605) ([b5b08df](https://emergentcode.visualstudio.com/Emergent%20Software/_git/Emergent.AgenticToolkit/commit/b5b08dfd02a67b647e8aad76d6d5e85cc166c222))
+
+### Performance
+
+* **cli:** start without loading Ink or every command (ATK-605) ([47c5c4c](https://emergentcode.visualstudio.com/Emergent%20Software/_git/Emergent.AgenticToolkit/commit/47c5c4cd79684872503f0f8de9f14dca09fd197c))
+
+## [8.9.0-dev.17](https://emergentcode.visualstudio.com/Emergent%20Software/_git/Emergent.AgenticToolkit/branchCompare?baseVersion=GTv8.9.0-dev.16&targetVersion=GTv8.9.0-dev.17) (2026-10-18)
+
+### Bug Fixes
+
+* **cli:** keep --offline out of writes, init's flag and doctor's sign-in (ATK-603) ([a234ca5](https://emergentcode.visualstudio.com/Emergent%20Software/_git/Emergent.AgenticToolkit/commit/a234ca505bb1f7d8cb4373c44d998c93bbc35eec))
+* **cli:** read commands use the stale registry cache when the API fails (ATK-603) ([5b17d93](https://emergentcode.visualstudio.com/Emergent%20Software/_git/Emergent.AgenticToolkit/commit/5b17d93324f68b29db5d6a26defd886c26716650))
+
+## [8.9.0-dev.16](https://emergentcode.visualstudio.com/Emergent%20Software/_git/Emergent.AgenticToolkit/branchCompare?baseVersion=GTv8.9.0-dev.15&targetVersion=GTv8.9.0-dev.16) (2026-10-18)
+
+### Bug Fixes
+
+* **cli:** publish --dry-run always asks the API for its plan (ATK-600) ([4ea9c07](https://emergentcode.visualstudio.com/Emergent%20Software/_git/Emergent.AgenticToolkit/commit/4ea9c07169989f2e37123579650b65a72ea32440))
+
+### Refactoring
+
+* **cli:** format the plan's reviewers in one place (ATK-600) ([ddec407](https://emergentcode.visualstudio.com/Emergent%20Software/_git/Emergent.AgenticToolkit/commit/ddec40753cb51386bb617214aa52d4c4fcf4b2db))
+
+## [8.9.0-dev.15](https://emergentcode.visualstudio.com/Emergent%20Software/_git/Emergent.AgenticToolkit/branchCompare?baseVersion=GTv8.9.0-dev.14&targetVersion=GTv8.9.0-dev.15) (2026-10-18)
+
+### Bug Fixes
+
+* **cli:** info checks the opened asset's type and names the org it tried (ATK-597) ([97e8da6](https://emergentcode.visualstudio.com/Emergent%20Software/_git/Emergent.AgenticToolkit/commit/97e8da67ffdea6dad7b3f82a6fbc249a1e75c142))
+* **cli:** info resolves the active org and opens a single org match (ATK-597) ([a9bdd09](https://emergentcode.visualstudio.com/Emergent%20Software/_git/Emergent.AgenticToolkit/commit/a9bdd093dddd8ed758fe4ef5533058275c4ca33f))
+
+## [8.9.0-dev.14](https://emergentcode.visualstudio.com/Emergent%20Software/_git/Emergent.AgenticToolkit/branchCompare?baseVersion=GTv8.9.0-dev.13&targetVersion=GTv8.9.0-dev.14) (2026-10-18)
+
+### Bug Fixes
+
+* **cli:** one JSON contract for usage errors, outcomes and exits (ATK-595) ([817a243](https://emergentcode.visualstudio.com/Emergent%20Software/_git/Emergent.AgenticToolkit/commit/817a2436029df8d18c5ebf7c48042d3a8591316e))
+* **cli:** usage errors read grouped -j, carry notices, write synchronously (ATK-595) ([1b326fe](https://emergentcode.visualstudio.com/Emergent%20Software/_git/Emergent.AgenticToolkit/commit/1b326fe2599bb3db6c2efe4b8111d4d333f05b33))
+
+## [8.9.0-dev.13](https://emergentcode.visualstudio.com/Emergent%20Software/_git/Emergent.AgenticToolkit/branchCompare?baseVersion=GTv8.9.0-dev.12&targetVersion=GTv8.9.0-dev.13) (2026-10-18)
+
+### Bug Fixes
+
+* **cli:** let atk config set booleans and reject bad numbers (ATK-593) ([77500ba](https://emergentcode.visualstudio.com/Emergent%20Software/_git/Emergent.AgenticToolkit/commit/77500ba20fc4e3ba456c5a87b6457ea04c15d9cc))
+
+## [8.9.0-dev.12](https://emergentcode.visualstudio.com/Emergent%20Software/_git/Emergent.AgenticToolkit/branchCompare?baseVersion=GTv8.9.0-dev.11&targetVersion=GTv8.9.0-dev.12) (2026-10-18)
+
+### Bug Fixes
+
+* **cli:** keep the run's flags on install [@org](https://emergentcode.visualstudio.com/org)'s --all suggestion (ATK-591) ([20563ff](https://emergentcode.visualstudio.com/Emergent%20Software/_git/Emergent.AgenticToolkit/commit/20563ffd3a61b32ac07460143d73cef83facd550))
+* **cli:** refuse install [@org](https://emergentcode.visualstudio.com/org) with no terminal unless --all (ATK-591) ([6befbd4](https://emergentcode.visualstudio.com/Emergent%20Software/_git/Emergent.AgenticToolkit/commit/6befbd40a5fbd05980a0f2b6b58739c8b0be2277))
+
+## [8.9.0-dev.11](https://emergentcode.visualstudio.com/Emergent%20Software/_git/Emergent.AgenticToolkit/branchCompare?baseVersion=GTv8.9.0-dev.10&targetVersion=GTv8.9.0-dev.11) (2026-10-18)
+
+### Bug Fixes
+
+* **cli:** harden the published-version check for local edits ([18c4134](https://emergentcode.visualstudio.com/Emergent%20Software/_git/Emergent.AgenticToolkit/commit/18c413488b2be095f68b39a8d55ce2682680699b))
+* **cli:** keep locally edited asset files on sync and update ([32fdc17](https://emergentcode.visualstudio.com/Emergent%20Software/_git/Emergent.AgenticToolkit/commit/32fdc174bec7bedac004ef0f13e78cc2ef50d8ba))
+* **cli:** re-place stale asset files, keeping only real local edits ([676c2bc](https://emergentcode.visualstudio.com/Emergent%20Software/_git/Emergent.AgenticToolkit/commit/676c2bcc16f9a90a1dd29c541dd18c61342dcd96))
+
+## [8.9.0-dev.10](https://emergentcode.visualstudio.com/Emergent%20Software/_git/Emergent.AgenticToolkit/branchCompare?baseVersion=GTv8.9.0-dev.9&targetVersion=GTv8.9.0-dev.10) (2026-10-18)
+
+### Bug Fixes
+
+* **cli:** fetch the update's manifest from the asset it resolved (ATK-589) ([ee5eb3a](https://emergentcode.visualstudio.com/Emergent%20Software/_git/Emergent.AgenticToolkit/commit/ee5eb3a54ee84b5d5253d1b2980fe2a076e8fc6b))
+* **cli:** refuse publish --update from an older installed copy (ATK-589) ([3a853b3](https://emergentcode.visualstudio.com/Emergent%20Software/_git/Emergent.AgenticToolkit/commit/3a853b390e099e4b1d3e3f4bdddfc60f879a019e))
+
+## [8.9.0-dev.9](https://emergentcode.visualstudio.com/Emergent%20Software/_git/Emergent.AgenticToolkit/branchCompare?baseVersion=GTv8.9.0-dev.8&targetVersion=GTv8.9.0-dev.9) (2026-10-18)
+
+### Bug Fixes
+
+* **cli:** judge an unreadable lock by its refreshes (ATK-588) ([8ba6f59](https://emergentcode.visualstudio.com/Emergent%20Software/_git/Emergent.AgenticToolkit/commit/8ba6f596fa56e4511c108c2e39bbf5f6c2b90c25))
+* **cli:** keep the lockfile lock with its live holder (ATK-588) ([e39f581](https://emergentcode.visualstudio.com/Emergent%20Software/_git/Emergent.AgenticToolkit/commit/e39f5816db6fcfffbd2a6ffc8d21d7bff693edf5))
+* **cli:** release only this run's lockfile lock (ATK-588) ([0d33b9a](https://emergentcode.visualstudio.com/Emergent%20Software/_git/Emergent.AgenticToolkit/commit/0d33b9ab3f70b58de097d2a9b4dae1e11a0bff76))
+
+## [8.9.0-dev.8](https://emergentcode.visualstudio.com/Emergent%20Software/_git/Emergent.AgenticToolkit/branchCompare?baseVersion=GTv8.9.0-dev.7&targetVersion=GTv8.9.0-dev.8) (2026-10-18)
+
+### Bug Fixes
+
+* **cli:** keep lockfile keys this CLI doesn't know (ATK-587) ([7ac52a6](https://emergentcode.visualstudio.com/Emergent%20Software/_git/Emergent.AgenticToolkit/commit/7ac52a6ec20cc04738563539c037a2896a8f506b))
+* **cli:** refuse to overwrite a newer lockVersion too (ATK-587) ([67b8335](https://emergentcode.visualstudio.com/Emergent%20Software/_git/Emergent.AgenticToolkit/commit/67b8335fbb01cf2235e5a0dbde8959fd507e657e))
+
+## [8.9.0-dev.7](https://emergentcode.visualstudio.com/Emergent%20Software/_git/Emergent.AgenticToolkit/branchCompare?baseVersion=GTv8.9.0-dev.6&targetVersion=GTv8.9.0-dev.7) (2026-10-18)
+
+### Bug Fixes
+
+* **cli:** write the lockfile atomically ([89f0251](https://emergentcode.visualstudio.com/Emergent%20Software/_git/Emergent.AgenticToolkit/commit/89f02515946091c5b7a5669dcd6e3d6409d7c71d))
+
+## [8.9.0-dev.6](https://emergentcode.visualstudio.com/Emergent%20Software/_git/Emergent.AgenticToolkit/branchCompare?baseVersion=GTv8.9.0-dev.5&targetVersion=GTv8.9.0-dev.6) (2026-10-18)
+
+### Bug Fixes
+
+* **cli:** check the entrypoint's path and refuse paths naming no file ([3df406e](https://emergentcode.visualstudio.com/Emergent%20Software/_git/Emergent.AgenticToolkit/commit/3df406e4b92c865ab50f44c7d46040d4c75126db))
+* **cli:** keep lockfile names and source paths inside their placement ([56979b2](https://emergentcode.visualstudio.com/Emergent%20Software/_git/Emergent.AgenticToolkit/commit/56979b25fc14f6361f834d7ad5b5292c3d7bf30d))
+
+## [8.9.0-dev.5](https://emergentcode.visualstudio.com/Emergent%20Software/_git/Emergent.AgenticToolkit/branchCompare?baseVersion=GTv8.9.0-dev.4&targetVersion=GTv8.9.0-dev.5) (2026-10-18)
+
+### Bug Fixes
+
+* **cli:** checksum MCP config entries at every depth (ATK-584) ([b0c55f8](https://emergentcode.visualstudio.com/Emergent%20Software/_git/Emergent.AgenticToolkit/commit/b0c55f865c3c729486bfe33d82f7823484078837))
+
+## [8.9.0-dev.4](https://emergentcode.visualstudio.com/Emergent%20Software/_git/Emergent.AgenticToolkit/branchCompare?baseVersion=GTv8.9.0-dev.3&targetVersion=GTv8.9.0-dev.4) (2026-10-17)
+
+### Refactoring
+
+* **cli:** add planPublish and runPublish behind a PublishPrompter (ATK-607) ([2f9cc95](https://emergentcode.visualstudio.com/Emergent%20Software/_git/Emergent.AgenticToolkit/commit/2f9cc955276e6f202e1628f30e1a33f1b1d538da))
+* **cli:** keep the publish runner's behavior to the old hook's (ATK-607) ([62a52b3](https://emergentcode.visualstudio.com/Emergent%20Software/_git/Emergent.AgenticToolkit/commit/62a52b3984fff903dc32bccf76f54c6ac9ade689))
+* **cli:** keep the publish tools picker's cursor in the hook (ATK-607) ([2b401df](https://emergentcode.visualstudio.com/Emergent%20Software/_git/Emergent.AgenticToolkit/commit/2b401df5452dd2b078add9e781ccac68dbdead19))
+* **cli:** move the publish reducer into lib (ATK-607) ([9d46be9](https://emergentcode.visualstudio.com/Emergent%20Software/_git/Emergent.AgenticToolkit/commit/9d46be92c018520b9d4a0cbfd5124f33d01cffe6))
+* **cli:** run atk publish's UI through runPublish (ATK-607) ([f28cbf4](https://emergentcode.visualstudio.com/Emergent%20Software/_git/Emergent.AgenticToolkit/commit/f28cbf4e40fb7f87e72bd8470615da7167a0b369))
+
 ## [8.9.0-dev.3](https://emergentcode.visualstudio.com/Emergent%20Software/_git/Emergent.AgenticToolkit/branchCompare?baseVersion=GTv8.9.0-dev.2&targetVersion=GTv8.9.0-dev.3) (2026-10-17)
 
 ### Bug Fixes

package/README.md

@@ -96,6 +96,16 @@ atk update
 | `atk whoami`            | Show who you are signed in as and where the credential came from  |
 | `atk why <asset>`       | Explain why an asset is installed (direct, dependency, or orphan) |
 
+### Offline and a stale cache
+
+The CLI keeps the last registry it read in `~/.atk/cache/registry.json` and re-reads it from the ATK API once it is older than `cacheTtlMinutes`. When the API can't be read (no network, a 5xx, a rate limit, or a failed sign-in), the read commands (`search`, `info`, `list`, `outdated`, `diff`, `browse`) use the cached copy, whatever its age, and say how old it is (in `--json` output, a `stale-registry` entry in `notices`). Commands that install, update or publish never use an old copy.
+
+`--offline`, before or after any command, never calls the API. The read commands take the registry from the cache of any age; anything else the API serves (a README, asset files) and every command that needs the current registry (`install`, `update`, `publish`, …) fails at once instead of retrying. `atk diff` needs the API for the latest files, so it doesn't work offline.
+
+```bash
+atk search commit --offline
+```
+
 ## Authentication
 
 Every registry read, `atk checkout`, `atk publish`, `atk unpublish`, `atk promote`, `atk deprecate` and `atk release-notes` go through the ATK API with a bearer token for your Emergent Software (Microsoft Entra) account.
@@ -107,9 +117,9 @@ ATK resolves the credential in this order and uses the first hit for the whole r
 1. `ATK_TOKEN` environment variable — a raw Entra access token for the ATK API, for CI and agents (for example `az account get-access-token --scope api://8da5aa72-0565-4ae8-bf5a-db89d8bd3186/access_as_user --query accessToken -o tsv`).
 2. The `atk login` session.
 
-When neither is there, commands fail with "Not signed in" (or "Your Emergent sign-in has expired") and name `atk login`. `atk whoami` shows who you are signed in as, which scheme the API applied, and which source supplied the credential; `atk doctor` reports the same in its **Authentication** check.
+When neither is there, commands fail with "Not signed in" (or "Your Emergent sign-in has expired") and name `atk login`. When the session couldn't be renewed for another reason, such as no network or an unreadable session file, they fail with "Couldn't refresh your Emergent sign-in" and the reason, and name `atk login --force`. When the API refuses the token in `ATK_TOKEN`, the error says to refresh `ATK_TOKEN` or unset it, since `atk login` can't replace it; `atk login` and `atk logout` also say so when `ATK_TOKEN` is set. `atk whoami` shows who you are signed in as, which scheme the API applied, and which source supplied the credential; `atk doctor` reports the same in its **Authentication** check. `atk whoami` also shows when the token expires (`expiresAt` in `--json`); a session's token lasts about an hour and is renewed on its own.
 
-GitHub sign-in to ATK has ended. GitHub tokens are no longer read from `gh`, `GITHUB_TOKEN` or config; one passed in `ATK_TOKEN` is refused by the API with a message naming `atk login`.
+GitHub sign-in to ATK has ended. GitHub tokens are no longer read from `gh`, `GITHUB_TOKEN` or config; one passed in `ATK_TOKEN` is refused by the API, and the error says to replace `ATK_TOKEN` with an Entra access token or unset it.
 
 ## Asset Types
 
@@ -154,7 +164,7 @@ atk init skill --from plan-feature --name my-planner
 atk init rule --offline
 ```
 
-The `--offline` flag is `init`-only — it skips the registry name-availability check during scaffolding and has no effect on other commands.
+For `init`, the global `--offline` skips the registry name-availability check and the dependency prompt during scaffolding.
 
 Supported types: `skill`, `agent`, `rule`, `hook`, `memory-template`, `mcp-config`, `bundle`.
 
@@ -192,7 +202,7 @@ The publish workflow:
 1. **Detects** whether the directory contains a `manifest.json` (asset) or `bundle.json` (bundle)
 2. **Validates** the manifest — checks required fields, file existence, name format, and semver version
 3. **Checks the registry** — determines if this is a new asset or an update to an existing one
-4. **Version bump** — if updating and the manifest version hasn't been bumped, prompts for `patch`, `minor`, or `major`
+4. **Version bump** — if updating and the manifest version hasn't been bumped, applies `--bump <patch|minor|major>` when given, or else prompts for one (a run with `--yes`, `--json`, `--dry-run` or no terminal needs `--bump`)
 5. **Builds a plan** — lists files, target registry path, branch name, and PR metadata
 6. **Executes** — clones the registry repo, creates a branch, copies files, commits, pushes, and opens a PR against the `main` branch
 
@@ -307,14 +317,14 @@ atk config org --reset
 
 ### Available Keys
 
-| Key               | Default                                   | Description                                                                                                           |
-| ----------------- | ----------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
-| `apiUrl`          | `https://func-atk-prod.azurewebsites.net` | ATK API base URL. The `ATK_API_URL` environment variable overrides it (e.g. to point at dev).                         |
-| `cacheDir`        | `~/.atk/cache/`                           | Override cache directory                                                                                              |
-| `cacheTtlMinutes` | `5`                                       | Cache TTL in minutes for registry data                                                                                |
-| `checkUpdates`    | `true`                                    | Show a banner when a newer ATK version is available (in `--json` output, an `update-available` entry in `notices`)    |
-| `org`             | _(not set)_                               | Default organization scope for asset resolution                                                                       |
-| `userRoot`        | _(home directory)_                        | Root of the user scope (`--user`). A relative or `~/` path is under the home directory. `ATK_USER_ROOT` overrides it. |
+| Key               | Default                                   | Description                                                                                                                                       |
+| ----------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `apiUrl`          | `https://func-atk-prod.azurewebsites.net` | ATK API base URL. The `ATK_API_URL` environment variable overrides it (e.g. to point at dev).                                                     |
+| `cacheDir`        | `~/.atk/cache/`                           | Override cache directory                                                                                                                          |
+| `cacheTtlMinutes` | `5`                                       | Cache TTL in minutes for registry data                                                                                                            |
+| `checkUpdates`    | `true`                                    | Show a banner when a newer ATK version is available, asking npm at most once a day (in `--json` output, an `update-available` entry in `notices`) |
+| `org`             | _(not set)_                               | Default organization scope for asset resolution                                                                                                   |
+| `userRoot`        | _(home directory)_                        | Root of the user scope (`--user`). A relative or `~/` path is under the home directory. `ATK_USER_ROOT` overrides it.                             |
 
 ### Environment Variables
 

package/build/cli.js

@@ -3,9 +3,11 @@ import chalk from 'chalk';
 import { readFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { ASCII_ART, GRADIENT } from './components/Header.js';
+import commandManifest from './command-manifest.json' with { type: 'json' };
+import { ASCII_ART, GRADIENT } from './components/header-art.js';
+import { GLOBAL_OPTIONS, isOfflineRun, setOffline } from './lib/offline.js';
 import Pastel from './lib/pastel/index.js';
-import { noteCachedUpdate } from './lib/update-check.js';
+import { isJsonRun, reportUsageError } from './lib/usage-error.js';
 import { holdCookedTtyReads } from './lib/windows-tty-stdin.js';
 holdCookedTtyReads(process.stdin);
 const __dirname = dirname(fileURLToPath(import.meta.url));
@@ -24,16 +26,26 @@ function buildHelpHeader(version) {
     });
     return `\n${lines.join('\n')}\n`;
 }
+// JSON mode (`--json`, or no TTY, as in _app.tsx), decided before any command parses.
+const json = isJsonRun(process.argv);
+// Offline mode, decided as early, so the JSON update check below skips npm too.
+setOffline(isOfflineRun(process.argv));
 const app = new Pastel({
+    // `pnpm manifest` writes it from src/commands, and command-manifest.test.ts holds it to them, so a run imports
+    // only the command it runs (ATK-605). JSON's types are wider than the spec's literal unions.
+    commands: commandManifest,
+    globalOptions: GLOBAL_OPTIONS,
     helpHeader: buildHelpHeader(pkg.version),
     importMeta: import.meta,
     name: 'atk',
+    onUsageError: (message) => reportUsageError(message, json),
     version: pkg.version,
 });
-// JSON mode (`--json`, or no TTY, as in _app.tsx) shows no update banner, so a newer
-// cached npm version becomes a notice in the payload instead. It is read before the
-// command runs so the notice is there when the command prints.
-if (process.argv.includes('--json') || !process.stdin.isTTY) {
+// JSON mode shows no update banner, so a newer cached npm version becomes a notice in
+// the payload instead. It is read before the command runs so the notice is there when
+// the command prints. Imported here, not at the top: it loads the config and Zod (ATK-605).
+if (json) {
+    const { noteCachedUpdate } = await import('./lib/update-check.js');
     await noteCachedUpdate();
 }
 await app.run();

package/build/cli.js.map

@@ -1 +1 @@
-{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.tsx"],"names":[],"mappings":";AACA,OAAO,KAAK,MAAM,OAAO,CAAC;AAC1B,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAC7D,OAAO,MAAM,MAAM,uBAAuB,CAAC;AAC3C,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AAEhE,kBAAkB,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;AAElC,MAAM,SAAS,GAAG,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;AAC1D,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,CAAC,SAAS,EAAE,IAAI,EAAE,cAAc,CAAC,EAAE,MAAM,CAAC,CAEjF,CAAC;AAEF,SAAS,eAAe,CAAC,OAAe;IACtC,MAAM,SAAS,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,iBAAiB,CAAC,CAAC;IACrD,MAAM,WAAW,GAAG,KAAK,CAAC,GAAG,CAAC,IAAI,OAAO,EAAE,CAAC,GAAG,CAAC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IAC7G,MAAM,OAAO,GAAG,KAAK,CAAC;IAEtB,MAAM,KAAK,GAAG,SAAS,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,CAAC,EAAE,EAAE;QACrC,MAAM,UAAU,GAAG,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAE,CAAC,CAAC,GAAG,CAAC,CAAC;QACrD,IAAI,CAAC,KAAK,CAAC;YAAE,OAAO,GAAG,UAAU,GAAG,OAAO,GAAG,SAAS,EAAE,CAAC;QAC1D,IAAI,CAAC,KAAK,CAAC;YAAE,OAAO,GAAG,UAAU,GAAG,OAAO,GAAG,WAAW,EAAE,CAAC;QAC5D,OAAO,UAAU,CAAC;IACpB,CAAC,CAAC,CAAC;IAEH,OAAO,KAAK,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC;AACnC,CAAC;AAED,MAAM,GAAG,GAAG,IAAI,MAAM,CAAC;IACrB,UAAU,EAAE,eAAe,CAAC,GAAG,CAAC,OAAO,CAAC;IACxC,UAAU,EAAE,MAAM,CAAC,IAAI;IACvB,IAAI,EAAE,KAAK;IACX,OAAO,EAAE,GAAG,CAAC,OAAO;CACrB,CAAC,CAAC;AAEH,qFAAqF;AACrF,oFAAoF;AACpF,+DAA+D;AAC/D,IAAI,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;IAC5D,MAAM,gBAAgB,EAAE,CAAC;AAC3B,CAAC;AAED,MAAM,GAAG,CAAC,GAAG,EAAE,CAAC"}
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.tsx"],"names":[],"mappings":"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"}