@detergent-software/atk 8.7.0-dev.11 → 8.7.0-dev.12

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/CHANGELOG.md +6 -0
  2. package/README.md +44 -12
  3. package/package.json +1 -1
package/CHANGELOG.md CHANGED
@@ -1,3 +1,9 @@
1
+ ## [8.7.0-dev.12](https://emergentcode.visualstudio.com/Emergent%20Software/_git/Emergent.AgenticToolkit/branchCompare?baseVersion=GTv8.7.0-dev.11&targetVersion=GTv8.7.0-dev.12) (2026-10-15)
2
+
3
+ ### Documentation
4
+
5
+ * **cli:** document user-level installs in the README (ATK-332) ([ec7ccd6](https://emergentcode.visualstudio.com/Emergent%20Software/_git/Emergent.AgenticToolkit/commit/ec7ccd640d630b29cb8b9cabafc388c528ce56fc))
6
+
1
7
  ## [8.7.0-dev.11](https://emergentcode.visualstudio.com/Emergent%20Software/_git/Emergent.AgenticToolkit/branchCompare?baseVersion=GTv8.7.0-dev.10&targetVersion=GTv8.7.0-dev.11) (2026-10-15)
2
8
 
3
9
  ### Bug Fixes
package/README.md CHANGED
@@ -79,6 +79,7 @@ atk update
79
79
  | `atk list` | List all installed assets |
80
80
  | `atk login` | Sign in with your Emergent (Microsoft Entra) account |
81
81
  | `atk logout` | Sign out of your Emergent account |
82
+ | `atk move <asset>` | Move an installed asset between the project and the user scope |
82
83
  | `atk outdated` | Show assets with available updates |
83
84
  | `atk pin <asset>` | Pin an asset to its current version |
84
85
  | `atk promote <name>` | Promote an org-scoped asset or bundle to global via PR |
@@ -257,6 +258,35 @@ This lets teams override global assets with org-specific versions while still in
257
258
 
258
259
  There is no separate "create org" step. Publishing the first asset with an `org` value creates the namespace automatically. Org assets are stored under `assets/<type>s/@<org>/<name>/` in the registry.
259
260
 
261
+ ## User Scope
262
+
263
+ Assets you want in every project, such as a skill you always use, go in your **user scope** instead of a project. Add `--user` to a command to work there from any directory:
264
+
265
+ ```bash
266
+ # Once: pick the tools for your user scope
267
+ atk setup --user
268
+
269
+ # Install for yourself (~/.claude/skills/my-skill/ for Claude Code)
270
+ atk install my-skill --user
271
+
272
+ # Your user installs, and their updates
273
+ atk list --user
274
+ atk outdated --user
275
+ atk update --user
276
+
277
+ # Move a project install to your user scope, or back
278
+ atk move my-skill --to user
279
+ atk move my-skill --to project
280
+ ```
281
+
282
+ - The user scope has its own lockfile, `~/.atk-lock.json`, and keeps its tools in the `user` section of `~/.atkrc.json`. Each tool's assets go in its own user directory (`~/.claude/`, `~/.codex/`, `~/.copilot/`), which follows `CLAUDE_CONFIG_DIR`, `CODEX_HOME` and `XDG_CONFIG_HOME` when they are set.
283
+ - **Read both, write one.** In a project, `atk list` and `atk outdated` show your user installs beside the project's, each with its scope (`--project` hides them). Commands that change installs touch one scope: a project `atk update` never changes your user installs. `atk install` warns when the other scope already has the asset, and says which copy each tool uses.
284
+ - **The user root** is your home directory unless the `userRoot` config key or the `ATK_USER_ROOT` environment variable says otherwise. A command run in the user root works in the user scope even without `--user`.
285
+ - **A new machine:** commit `~/.atk-lock.json` to your dotfiles, then run `atk setup --user` and `atk sync --user`; or publish a personal bundle and run `atk install <bundle> --user`.
286
+ - An existing home-directory install (`atk setup` run in `~` before CLI 8.6.0) is adopted by the first `atk setup --user`.
287
+
288
+ `--user` arrived in CLI 8.6.0; user-level placements, the both-scope views, the cross-scope warning and `atk move` in 8.7.0. The full reference is the `atk-guide` skill's `references/user-scope.md` (`atk install atk-guide`).
289
+
260
290
  ## Configuration
261
291
 
262
292
  Manage user-level settings stored in `~/.atkrc.json`:
@@ -277,21 +307,23 @@ atk config org --reset
277
307
 
278
308
  ### Available Keys
279
309
 
280
- | Key | Default | Description |
281
- | ----------------- | ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
282
- | `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). |
283
- | `cacheDir` | `~/.atk/cache/` | Override cache directory |
284
- | `cacheTtlMinutes` | `5` | Cache TTL in minutes for registry data |
285
- | `checkUpdates` | `true` | Show a banner when a newer ATK version is available (in `--json` output, an `update-available` entry in `notices`) |
286
- | `org` | _(not set)_ | Default organization scope for asset resolution |
310
+ | Key | Default | Description |
311
+ | ----------------- | ----------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
312
+ | `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). |
313
+ | `cacheDir` | `~/.atk/cache/` | Override cache directory |
314
+ | `cacheTtlMinutes` | `5` | Cache TTL in minutes for registry data |
315
+ | `checkUpdates` | `true` | Show a banner when a newer ATK version is available (in `--json` output, an `update-available` entry in `notices`) |
316
+ | `org` | _(not set)_ | Default organization scope for asset resolution |
317
+ | `userRoot` | _(home directory)_ | Root of the user scope (`--user`). A relative or `~/` path is under the home directory. `ATK_USER_ROOT` overrides it. |
287
318
 
288
319
  ### Environment Variables
289
320
 
290
- | Variable | Description |
291
- | -------------- | ------------------------------------------------------------------------------------------------------------ |
292
- | `ATK_API_URL` | Overrides `apiUrl` (e.g. `https://func-atk-dev.azurewebsites.net` to target the dev API). |
293
- | `ATK_WEB_URL` | Overrides the ATK web app base URL used for the `Web:` links in `info`, `browse`, `list` and `search`. |
294
- | `ATK_TOKEN` | A raw Entra access token for the ATK API, for CI and agents. Wins over the `atk login` session. |
321
+ | Variable | Description |
322
+ | --------------- | ------------------------------------------------------------------------------------------------------ |
323
+ | `ATK_API_URL` | Overrides `apiUrl` (e.g. `https://func-atk-dev.azurewebsites.net` to target the dev API). |
324
+ | `ATK_WEB_URL` | Overrides the ATK web app base URL used for the `Web:` links in `info`, `browse`, `list` and `search`. |
325
+ | `ATK_TOKEN` | A raw Entra access token for the ATK API, for CI and agents. Wins over the `atk login` session. |
326
+ | `ATK_USER_ROOT` | Overrides `userRoot`: the root of the user scope, where `--user` puts its lockfile and placements. |
295
327
 
296
328
  ## Development
297
329
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@detergent-software/atk",
3
- "version": "8.7.0-dev.11",
3
+ "version": "8.7.0-dev.12",
4
4
  "description": "Agentic Tool Kit — CLI for managing AI coding tool assets.",
5
5
  "type": "module",
6
6
  "bin": {