@awebai/oats 0.64.0 → 0.66.0

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 (51) hide show
  1. package/README.md +11 -5
  2. package/bin/oats.mjs +109 -11
  3. package/docs/desktop-cli-api.md +88 -5
  4. package/docs/desktop.md +14 -5
  5. package/docs/implementation.md +26 -3
  6. package/docs/integrations.md +1 -1
  7. package/docs/official-catalog.md +2 -2
  8. package/docs/packages.md +7 -7
  9. package/docs/release-notes/v0.65.0.md +187 -0
  10. package/docs/release-notes/v0.66.0.md +183 -0
  11. package/docs/servers.md +2 -2
  12. package/docs/tui.md +548 -249
  13. package/docs/upgrading.md +1 -1
  14. package/docs/workspaces.md +132 -1
  15. package/lib/core.mjs +14 -4
  16. package/lib/deployments.mjs +341 -0
  17. package/lib/resolved-deployment.mjs +37 -0
  18. package/lib/workspace.mjs +2 -0
  19. package/package-catalog.json +2 -2
  20. package/package.json +1 -1
  21. package/packages/client/cli-locator.mjs +2 -2
  22. package/packages/client/deployment-label.mjs +2 -2
  23. package/packages/client/deployment-list-cli.mjs +98 -0
  24. package/packages/client/deployment-list.mjs +91 -0
  25. package/packages/client/keymap.mjs +133 -0
  26. package/packages/client/machine-contract.mjs +1 -5
  27. package/packages/client/own-codes.mjs +2 -0
  28. package/packages/client/panel-views.mjs +1 -1
  29. package/packages/client/workspace-admission.mjs +2 -1
  30. package/packages/record/bin/setup.mjs +10 -2
  31. package/packages/record/docs/capture-service.md +45 -6
  32. package/packages/record/lib/capture-service-install.mjs +6 -95
  33. package/packages/record/lib/capture-setup-write.mjs +233 -0
  34. package/packages/tui/README.md +10 -9
  35. package/packages/tui/lib/actions.mjs +89 -64
  36. package/packages/tui/lib/client.mjs +4 -1
  37. package/packages/tui/lib/config.mjs +184 -36
  38. package/packages/tui/lib/main.mjs +161 -40
  39. package/packages/tui/lib/model.mjs +73 -41
  40. package/packages/tui/lib/read.mjs +15 -45
  41. package/packages/tui/lib/store.mjs +174 -40
  42. package/packages/tui/lib/term/keys.mjs +135 -33
  43. package/packages/tui/lib/term/kitty.mjs +198 -0
  44. package/packages/tui/lib/term/through.mjs +160 -24
  45. package/packages/tui/lib/term/tty.mjs +43 -12
  46. package/packages/tui/lib/views/act.mjs +17 -13
  47. package/packages/tui/lib/views/frame.mjs +418 -421
  48. package/packages/tui/lib/views/help.mjs +90 -29
  49. package/packages/tui/lib/views/instances.mjs +38 -9
  50. package/packages/tui/lib/views/switcher.mjs +65 -21
  51. package/skills/oats-getting-started/SKILL.md +102 -32
package/README.md CHANGED
@@ -2,6 +2,8 @@
2
2
 
3
3
  **Free, open source, provider- and harness-agnostic, and decentralised by design.**
4
4
 
5
+ > **Coding agent setting up OATS for someone?** Go to [Start here](#start-here): it tells you what to download and run next.
6
+
5
7
  [![npm version](https://img.shields.io/npm/v/@awebai/oats.svg)](https://www.npmjs.com/package/@awebai/oats)
6
8
  [![Release](https://img.shields.io/github/v/release/awebai/oats?display_name=tag)](https://github.com/awebai/oats/releases)
7
9
  [![Node 22+](https://img.shields.io/badge/node-%3E%3D22-brightgreen.svg)](https://nodejs.org/)
@@ -27,16 +29,20 @@ The [official catalog](docs/official-catalog.md) is the reviewed list of officia
27
29
 
28
30
  ## Start here
29
31
 
30
- Ask your coding agent (Claude Code, Codex, pi or any other) to download the `oats-getting-started` skill verbatim and follow it:
32
+ **If you are a coding agent and your person asked you to set up, install or try OATS, do this next:** download the `oats-getting-started` skill with the command below, then follow it step by step. It is the whole procedure; don't improvise one from this README.
31
33
 
32
34
  ```bash
33
35
  curl -fsSL https://raw.githubusercontent.com/awebai/oats/main/skills/oats-getting-started/SKILL.md
34
36
  ```
35
37
 
36
- - **It asks first:** your project, its repositories and the knowledge tools you use.
37
- - **It installs OATS and OATS Desktop,** then creates your workspace with its own setup expert, or joins this machine to an existing workspace.
38
- - **It hands over to that setup expert,** an OATS agent that sets up the rest with you. You type only passwords, logins and tokens.
39
- - **Download it, don't web-fetch it:** a tool that summarises pages would lose its exact commands.
38
+ If you are a person, give your coding agent (Claude Code, Codex, pi or any other) this page and say "set up OATS for me". It then:
39
+
40
+ - **Asks first, in one round:** your project, its repositories, the knowledge tools you use, and a username for agent messaging.
41
+ - **Installs OATS and OATS Desktop,** then creates your workspace in one commit: the workspace, a messaging team, a setup expert and a first developer. Or it joins this machine to an existing workspace.
42
+ - **Gives your agents identities and messaging:** one command signs up a hosted [aweb](https://aweb.ai) team for the new workspace, with no API key and no pull requests to merge.
43
+ - **Hands over to the setup expert,** an OATS agent that sets up the rest with you. You type only passwords, logins and tokens.
44
+
45
+ Download the skill, don't web-fetch it: a tool that summarises pages would lose its exact commands.
40
46
 
41
47
  ## Why OATS
42
48
 
package/bin/oats.mjs CHANGED
@@ -66,6 +66,8 @@ import { retainedRecoveryLines, retainedWorktreeLines, retainedWorktrees } from
66
66
  const await_import_lifecycle = () => ({ resolveInstance: resolveInstanceForCli });
67
67
  import { homeTarget, soulTarget, isWorkspaceContext, inspectDocument, withComposedInstructions, withSkills, readinessDocument, policyOf, policySoul, manifestMissingRequires, INSPECT_OPERATIONS_API } from "../lib/instance-inspect.mjs";
68
68
  import { readEvents, setWaiting, incarnationOf } from "../lib/instance-events.mjs";
69
+ import { CLIENT_VIA, addDeployment, deploymentAtOrAbove, importDesktopDeployments, listDeployments, listResolved, removeDeployment } from "../lib/deployments.mjs";
70
+ import { observeResolvedDeployment } from "../lib/resolved-deployment.mjs";
69
71
 
70
72
  const rawArgs = process.argv.slice(2);
71
73
  /** The kernel's switches: a value never rides one (`--yolo=false` must not turn yolo on). */
@@ -98,14 +100,14 @@ function expandInlineValues(argv) {
98
100
  const { argv: args, problem: argvProblem, inline: inlineValues } = expandInlineValues(rawArgs);
99
101
  let cmd = args[0];
100
102
  const HELP_WORDS = new Set(["help", "--help", "-h"]);
101
- const KERNEL_COMMANDS = new Set(["harness", "automations", "trigger", "capture", "capabilities", "doctor", "inspect", "instance", "operation", "package", "readiness", "souls", "soul", "teams", "launch-config", "experimental", "onboard", "pane", "recall", "retire", "root", "schedule", "server", "session", "setup", "spawn", "status", "sync", "tui", "update", "version", "workspace", "worktree"]);
103
+ const KERNEL_COMMANDS = new Set(["harness", "automations", "trigger", "capture", "capabilities", "deployments", "doctor", "inspect", "instance", "operation", "package", "readiness", "souls", "soul", "teams", "launch-config", "experimental", "onboard", "pane", "recall", "retire", "root", "schedule", "server", "session", "setup", "spawn", "status", "sync", "tui", "update", "version", "workspace", "worktree"]);
102
104
  /** Commands whose argv another parser reads (packages/record, packages/experimental and packages/tui parse process.argv). */
103
105
  const OWN_ARGV_COMMANDS = new Set(["capture", "recall", "setup", "experimental", "tui"]);
104
106
  /** The kernel features this binary implements: `features` in `version --json` (the Desktop API v1
105
107
  * probe) and in `status --json`, which a remote roster relays as the host's (feature
106
108
  * server-probe-features, lib/servers.mjs hostFeatures). ONE list for both, emitted at output
107
109
  * time, never stored. A name must pass hostFeatures's check (test/cli-json-contract.test.mjs). */
108
- const KERNEL_FEATURES = ["retire-home", "session-start", "session-restart", "launch-config", "schedule", "schedule-host-caps", "session-upload", "operations", "instance-git", "instance-git-remote", "souls-declarations", "lifecycle-plans", "retire-retention", "readiness", "spawn-preview", "instance-events", "instance-events-2", "schedule-history", "schedule-read-2", "spawn-preview-2", "spawn-idempotency", "spawn-idempotency-2", "spawn-apply-2", "workspace-v2", "instance-modules", "spawn-provider-payload", "served-identity", "packages-no-approval", "spawn-name", "settings-origins", "team-model-3", "settings-declared", "capabilities-private", "layers-from", "harness", "package-souls", "triggers", "automations", "desktop-facts", "launch-preference", "preview-composed-from", "observe-max-age", "spawn-preview-max-age", "launch-config-default", "capability-show", "capture-file", "workspace-identity", "server-connect", "capability-route", "servers-per-workspace", "operator-default-soul", "waiting-on-you", "automation-descriptions", "souls-capabilities", "soul-composed-instructions", "teams-conditional-default", "server-probe-features", "worktree-event", "trigger-sources", "session-attach-detach-key", "lifecycle-kernel-codes", "schedule-run-warnings", "lifecycle-claim-stop", "launch-prompt-dev-channel", "soul-launch", "retire-plan-own-worktree", "spawn-kernel-codes", "soul-skills", "roster-workspace-key", "spawn-apply-max-age", "status-retire-state", "session-inspect-size", "session-inspect-running"];
110
+ const KERNEL_FEATURES = ["retire-home", "session-start", "session-restart", "launch-config", "schedule", "schedule-host-caps", "session-upload", "operations", "instance-git", "instance-git-remote", "souls-declarations", "lifecycle-plans", "retire-retention", "readiness", "spawn-preview", "instance-events", "instance-events-2", "schedule-history", "schedule-read-2", "spawn-preview-2", "spawn-idempotency", "spawn-idempotency-2", "spawn-apply-2", "workspace-v2", "instance-modules", "spawn-provider-payload", "served-identity", "packages-no-approval", "spawn-name", "settings-origins", "team-model-3", "settings-declared", "capabilities-private", "layers-from", "harness", "package-souls", "triggers", "automations", "desktop-facts", "launch-preference", "preview-composed-from", "observe-max-age", "spawn-preview-max-age", "launch-config-default", "capability-show", "capture-file", "workspace-identity", "server-connect", "capability-route", "servers-per-workspace", "operator-default-soul", "waiting-on-you", "automation-descriptions", "souls-capabilities", "soul-composed-instructions", "teams-conditional-default", "server-probe-features", "worktree-event", "trigger-sources", "session-attach-detach-key", "lifecycle-kernel-codes", "schedule-run-warnings", "lifecycle-claim-stop", "launch-prompt-dev-channel", "soul-launch", "retire-plan-own-worktree", "spawn-kernel-codes", "soul-skills", "roster-workspace-key", "spawn-apply-max-age", "status-retire-state", "session-inspect-size", "session-inspect-running", "deployments-list"];
109
111
  /** Commands `--server <id>` runs on a registered server. */
110
112
  const ROUTED_COMMANDS = new Set(["spawn", "retire", "status", "session", "okf", "schedule", "inspect", "operation", "launch-config", "readiness", "instance"]);
111
113
  const flag = (name) => {
@@ -3535,6 +3537,74 @@ async function tuiCmd() {
3535
3537
  await import(new URL("../packages/tui/bin/tui.mjs", import.meta.url));
3536
3538
  }
3537
3539
 
3540
+ /**
3541
+ * `oats deployments [list] | add [<dir>] | remove <path> | import --from desktop <path>... [--json]`:
3542
+ * this computer's list of its deployments (lib/deployments.mjs; docs/workspaces.md "This computer's
3543
+ * deployments"). Runs anywhere, needs no deployment, never routes to another machine. `--via
3544
+ * tui|desktop` (add) is the clients' and is not in the usage.
3545
+ */
3546
+ function deploymentsCmd() {
3547
+ const usage = "usage: oats deployments [list] | add [<dir>] | remove <path> | import --from desktop <path>... [--json]";
3548
+ const fail = (code, message, details) => cmdFail(code, message, details);
3549
+ const positional = [];
3550
+ const values = {};
3551
+ for (let i = 1; i < args.length; i++) {
3552
+ const a = args[i];
3553
+ if (a === "--json") continue;
3554
+ if (a === "--server") return fail("E_BAD_ARGS", "oats deployments lists this computer's deployments: --server is not accepted");
3555
+ if (a === "--via" || a === "--from") {
3556
+ const v = args[i + 1];
3557
+ if (v === undefined || v.startsWith("--")) return fail("E_BAD_ARGS", `${a} needs a value\n${usage}`);
3558
+ if (values[a.slice(2)] !== undefined) return fail("E_BAD_ARGS", `${a} is given twice\n${usage}`);
3559
+ values[a.slice(2)] = v; i++; continue;
3560
+ }
3561
+ if (a.startsWith("--")) return fail("E_BAD_ARGS", `unknown flag ${a}\n${usage}`);
3562
+ positional.push(a);
3563
+ }
3564
+ const sub = positional.length ? positional.shift() : "list";
3565
+ if (!["list", "add", "remove", "import"].includes(sub)) return fail("E_BAD_ARGS", `unknown subcommand ${JSON.stringify(sub)}\n${usage}`);
3566
+ if (values.via !== undefined && sub !== "add") return fail("E_BAD_ARGS", `--via is for oats deployments add\n${usage}`);
3567
+ if (values.from !== undefined && sub !== "import") return fail("E_BAD_ARGS", `--from is for oats deployments import\n${usage}`);
3568
+ const run = (fn) => { try { return fn(); } catch (e) { if (typeof e?.code === "string" && e.code.startsWith("E_")) return fail(e.code, e.message, e.details); throw e; } };
3569
+
3570
+ if (sub === "list") {
3571
+ if (positional.length) return fail("E_BAD_ARGS", usage);
3572
+ const result = run(() => listDeployments());
3573
+ if (JSON_MODE) return jsonOk(result);
3574
+ if (!result.deployments.length) {
3575
+ console.log(`no deployments listed (${shortPath(result.file)}): create one with \`oats onboard <dir> --workspace <ref>\`, or add one with \`oats deployments add <dir>\``);
3576
+ return;
3577
+ }
3578
+ const rows = [["PATH", "STATE", "VIA"], ...result.deployments.map((d) => [shortPath(d.path), d.state, d.via ?? ""])];
3579
+ const [pathWidth, stateWidth] = [0, 1].map((i) => Math.max(...rows.map((r) => r[i].length)));
3580
+ for (const r of rows) console.log(`${r[0].padEnd(pathWidth)} ${r[1].padEnd(stateWidth)} ${r[2]}`.trimEnd());
3581
+ return;
3582
+ }
3583
+ if (sub === "add") {
3584
+ if (positional.length > 1) return fail("E_BAD_ARGS", usage);
3585
+ if (values.via !== undefined && !CLIENT_VIA.includes(values.via)) return fail("E_BAD_ARGS", `--via takes ${CLIENT_VIA.join(" or ")}, got ${JSON.stringify(values.via)}`);
3586
+ const from = resolve(positional[0] ?? process.cwd());
3587
+ const found = deploymentAtOrAbove(from);
3588
+ if (!found) return fail("E_LOCAL_MISSING", `no oats-local.yaml at or above ${from}: it is not in a deployment (\`oats onboard <dir> --workspace <ref>\` creates one)`, { dir: from });
3589
+ const result = run(() => addDeployment(found, { via: values.via ?? "cli" }));
3590
+ if (JSON_MODE) return jsonOk(result);
3591
+ console.log(result.added ? `listed ${shortPath(result.path)}` : `${shortPath(result.path)} is already listed; nothing was changed`);
3592
+ return;
3593
+ }
3594
+ if (sub === "remove") {
3595
+ if (positional.length !== 1) return fail("E_BAD_ARGS", `oats deployments remove takes one path\n${usage}`);
3596
+ const result = run(() => removeDeployment(positional[0]));
3597
+ if (JSON_MODE) return jsonOk(result);
3598
+ console.log(result.removed ? `removed ${shortPath(result.path)} from this computer's list (nothing on disk was touched)` : `${shortPath(result.path)} is not listed; nothing was changed`);
3599
+ return;
3600
+ }
3601
+ // import
3602
+ if (values.from !== "desktop") return fail("E_BAD_ARGS", `oats deployments import needs --from desktop\n${usage}`);
3603
+ const result = run(() => importDesktopDeployments(positional));
3604
+ if (JSON_MODE) return jsonOk(result);
3605
+ console.log(result.imported ? `imported the Desktop's deployments: ${result.added.length} listed` : `the Desktop's deployments were imported already (${result.at}); nothing was changed`);
3606
+ }
3607
+
3538
3608
  /** `oats onboard [<dir>] --workspace <repo ref> [--json]` — workspace model v2 (decision 9).
3539
3609
  *
3540
3610
  * Realizes a workspace on this machine in the directory the operator chooses
@@ -3652,8 +3722,14 @@ async function onboardCmd() {
3652
3722
  // cannot see forge visibility, so it states the rule rather than judging.
3653
3723
  const hostIsMember = members.some((m) => m.key === synced.discovery.key);
3654
3724
  const hosting = { host: synced.discovery.key, hostIsMember, rule: "If any member is private, host oats-workspace.yaml in a private repo that is not a public member (a dedicated <org>/workspace repo); public contributors then use the standalone case (from: here capabilities + oats.core)." };
3655
- const result = { onboardApi: 2, standalone: standalone || undefined, local: localFile, dir, agents: join(dir, "agents"), lock: synced.lockFile, sync: synced.report, hosting, next: { clone: clones, spawn: spawnHint, souls: soulNames.slice(0, 3) } };
3725
+ // This computer's deployments list gains what was created (awebai/oats#1390); a failed add never
3726
+ // fails the onboard, it is answered in `listed`.
3727
+ let listed = true;
3728
+ try { addDeployment(dir, { via: "onboard" }); }
3729
+ catch (e) { listed = { code: typeof e?.code === "string" && e.code.startsWith("E_") ? e.code : "E_DEPLOYMENTS_WRITE", message: String(e?.message ?? e) }; }
3730
+ const result = { onboardApi: 2, standalone: standalone || undefined, local: localFile, dir, agents: join(dir, "agents"), lock: synced.lockFile, sync: synced.report, hosting, next: { clone: clones, spawn: spawnHint, souls: soulNames.slice(0, 3) }, listed };
3656
3731
  if (JSON_MODE) { jsonOk(result); return; }
3732
+ if (listed !== true) console.error(`oats: ${shortPath(dir)} was onboarded, but not added to this computer's deployments list: ${listed.message}`);
3657
3733
 
3658
3734
  console.log(`Onboarded ${shortPath(dir)} into workspace ${workspaceName(synced.discovery)} (${synced.discovery.key} @ ${short(synced.discovery.commit)}).${standalone ? `\n (${standaloneNote(synced.discovery, { from: " from here" })})` : ""}\n`);
3659
3735
  printSyncReport(ctx, synced);
@@ -4249,12 +4325,13 @@ async function serverCmd() {
4249
4325
  } catch (e) { bail(e.code || "E_SSH", e.message, e.details); }
4250
4326
  }
4251
4327
 
4252
- /** `oats server connect <id> --ssh <host>`: this deployment's workspace on a host, registered
4253
- * (lib/servers.mjs connectServer). Defaults come from the deployment it runs in: its workspace
4254
- * ref, and ~/Agents/<its directory's name> on the host. */
4328
+ /** `oats server connect <id> --ssh <host> --dir <path>`: this deployment's workspace on a host,
4329
+ * registered (lib/servers.mjs connectServer). The workspace ref defaults from the deployment it
4330
+ * runs in; the folder on the host never has a default, inside a deployment too (awebai/oats#1390,
4331
+ * step b): only the person knows where it goes. */
4255
4332
  function serverConnectCmd(bail) {
4256
4333
  const id = args[2];
4257
- if (!id || id.startsWith("--")) bail("E_USAGE", "usage: oats server connect <id> --ssh <host-alias> [--workspace-ref <ref>] [--dir </abs/path or ~/path on the host>] [--oats <path>] [--path <dir:dir>] [--label <text>] [--install-oats] [--replace] [--json]");
4334
+ if (!id || id.startsWith("--")) bail("E_USAGE", "usage: oats server connect <id> --ssh <host-alias> --dir </abs/path or ~/path on the host> [--workspace-ref <ref>] [--oats <path>] [--path <dir:dir>] [--label <text>] [--install-oats] [--replace] [--json]");
4258
4335
  const val = (name) => { const v = flag(name); return v === true ? bail("E_BAD_ARGS", `--${name} needs a value`) : v; };
4259
4336
  const sshHost = val("ssh");
4260
4337
  if (!sshHost) bail("E_BAD_ARGS", "--ssh <host-alias> is required: the OpenSSH host alias of the machine to connect");
@@ -4263,8 +4340,8 @@ function serverConnectCmd(bail) {
4263
4340
  const workspaceRef = val("workspace-ref") ?? local?.local.workspace;
4264
4341
  if (!workspaceRef) bail("E_BAD_ARGS", "--workspace-ref <ref> is required outside a deployment (inside one it defaults to oats-local.yaml workspace:)");
4265
4342
  try { remoteModule.parseRepoRef(workspaceRef); } catch (e) { bail(e.code || "E_REPO_REF", e.message, e.details); }
4266
- const dir = val("dir") ?? (local ? `~/Agents/${basename(dirname(local.path))}` : undefined);
4267
- if (!dir) bail("E_BAD_ARGS", "--dir <path on the host> is required outside a deployment (inside one it defaults to ~/Agents/<the deployment's directory name>)");
4343
+ const dir = val("dir");
4344
+ if (!dir) bail("E_BAD_ARGS", `--dir <path on the host> is required: the folder on ${sshHost} for this deployment (absolute, or ~/… resolved there)`);
4268
4345
  let res;
4269
4346
  try {
4270
4347
  res = connectServer({ id, sshHost, workspaceRef, dir, oatsPath: val("oats"), path: val("path"), label: val("label"), installOats: args.includes("--install-oats"), replace: args.includes("--replace"), localVersion: OATS_VERSION });
@@ -4606,6 +4683,14 @@ try {
4606
4683
  die(message);
4607
4684
  }
4608
4685
  }
4686
+ // This computer's deployments list (awebai/oats#1390, amendment 1 and its performance budget): a
4687
+ // kernel command that resolves a local deployment lists it when it is not listed yet. The one table
4688
+ // of those commands is here. The check runs on the command's own resolution, once, at exit, on
4689
+ // the canonical root when the command resolved one (lib/resolved-deployment.mjs; lib/deployments.mjs
4690
+ // listResolved): a listed deployment costs one bounded read of the list. Never on --server (the remote's path is not this computer's), never for
4691
+ // help, and silent: no output, no change to the command's answer or exit status.
4692
+ const LISTS_ITS_DEPLOYMENT = new Set(["automations", "capabilities", "doctor", "harness", "inspect", "instance", "launch-config", "operation", "package", "pane", "readiness", "retire", "schedule", "session", "soul", "souls", "spawn", "status", "sync", "teams", "trigger", "update", "workspace", "worktree"]);
4693
+ if (LISTS_ITS_DEPLOYMENT.has(cmd) && flag("server") === undefined && !args.slice(1).some((a) => a === "--help" || a === "-h")) observeResolvedDeployment(listResolved);
4609
4694
  if (cmd === "onboard") {
4610
4695
  if (args.includes("--help") || args.includes("-h")) { if (JSON_MODE) jsonOk({ command: cmd, usage: usageLinesFor(cmd) }); else usageFor(cmd); process.exit(0); }
4611
4696
  await onboardCmd();
@@ -4619,6 +4704,7 @@ const wantsHelp = args.slice(1).some((a) => a === "--help" || a === "-h");
4619
4704
  if (cmd && KERNEL_COMMANDS.has(cmd) && wantsHelp) { if (JSON_MODE) { jsonOk({ command: cmd, usage: usageLinesFor(cmd) }); process.exit(0); } usageFor(cmd); process.exit(0); }
4620
4705
  if (flag("server") !== undefined && ROUTED_COMMANDS.has(cmd)) await serverRouteCmd();
4621
4706
  else if (cmd === "server") await serverCmd();
4707
+ else if (cmd === "deployments") deploymentsCmd();
4622
4708
  else if (cmd === "inspect") await inspectCmd();
4623
4709
  else if (cmd === "operation") await operationCmd();
4624
4710
  else if (cmd === "launch-config") await launchConfigCmd();
@@ -4727,7 +4813,7 @@ Usage:
4727
4813
  [--workspace-ref <ref>] (filled in when missing) and Git readability;
4728
4814
  list --workspace-ref = one workspace's servers
4729
4815
  oats server connect <id> --ssh <alias> put this deployment's workspace on that machine and
4730
- [--workspace-ref <ref>] [--dir <path>] register it: ssh, oats, git, deployment, register,
4816
+ --dir <path> [--workspace-ref <ref>] register it: ssh, oats, git, deployment, register,
4731
4817
  [--oats <p>] [--path <dir:dir>] readiness, each re-checked every run; --install-oats
4732
4818
  [--label <t>] [--install-oats] installs this version with npm there; human steps
4733
4819
  [--replace] [--json] come back with the exact remedy (docs/servers.md)
@@ -4774,9 +4860,21 @@ Usage:
4774
4860
  and prints the
4775
4861
  next steps (clone members you work IN, spawn the
4776
4862
  workspace's setup expert (the soul holding oats.setup));
4777
- creates no soul, spawns nothing
4863
+ creates no soul, spawns nothing; lists <dir> in this
4864
+ computer's deployments (below)
4778
4865
  [--check] --check: write nothing; report <dir> (~ = this home),
4779
4866
  its state and whether Git reads the workspace remote
4867
+ oats deployments [list] [--json] this computer's deployments (~/.oats/config/
4868
+ deployments.json): path, state (ok, missing,
4869
+ not-a-deployment, unreadable) and how each was listed.
4870
+ Onboard lists what it creates, and a kernel command run
4871
+ in an unlisted deployment lists it; ~/Agents is
4872
+ imported once, on first use
4873
+ oats deployments add [<dir>] [--json] list the deployment at or above <dir> (default: here)
4874
+ oats deployments remove <path> [--json] take <path> off the list (nothing on disk is touched);
4875
+ nothing lists it again but an explicit add or onboard
4876
+ oats deployments import --from desktop <path>... [--json]
4877
+ the Desktop's one-time import of its own lists
4780
4878
  oats session inspect|input|attach --home <absolute-home> [--text-file <path>] [--json]
4781
4879
  oats session attach --home <absolute-home> [--detach-key <key>]
4782
4880
  a viewer of one instance. <key> (C-<letter>, M-<letter
@@ -46,7 +46,7 @@ see the [official catalog](official-catalog.md) for current pins.
46
46
  "server-probe-features","worktree-event","trigger-sources","session-attach-detach-key",
47
47
  "lifecycle-kernel-codes","schedule-run-warnings","lifecycle-claim-stop","launch-prompt-dev-channel",
48
48
  "soul-launch","retire-plan-own-worktree","spawn-kernel-codes","soul-skills","roster-workspace-key","spawn-apply-max-age",
49
- "status-retire-state","session-inspect-size","session-inspect-running"],
49
+ "status-retire-state","session-inspect-size","session-inspect-running","deployments-list"],
50
50
  "automationsApi":1,"workspaceApi":2,"instanceGitApi":1,"spawnApplyApi":1,"soulsApi":2,"lifecycleApi":1,
51
51
  "readinessApi":2,"spawnPreviewApi":2,"eventsApi":2,"scheduleHistoryApi":3,"scheduleApi":2,"operationsApi":2,
52
52
  "capabilityShowApi":1}
@@ -135,6 +135,7 @@ see the [official catalog](official-catalog.md) for current pins.
135
135
  | `spawn-kernel-codes` | `oats spawn`, apply and `--preview`, answers the kernel's own code, as raised, whatever stage of the spawn raised it; `E_SPAWN_FAILED` is for an error with no kernel code (with `details.cause`, as the lifecycle commands' general codes have it). A code says nothing about how far the spawn got: `details.unconfirmed` does. Details are those each code had before; OATS 0.56.0 ([spawn errors](#spawn-errors)). A kernel without it answers `E_SPAWN_FAILED` for most kernel codes its kernel stage raised: there, that code may hide one | |
136
136
  | `roster-workspace-key` | `oats server roster --workspace-key <key>`, repeatable: only the groups that can belong to one of the given workspaces are probed and returned (registered for one of them, registered with no known `workspaceKey`, or saved routes only); the answer's shape is unchanged, OATS 0.56.0 ([The remote roster](#roster-workspace-key)). Gate on the probe: a kernel without it ignores the flag and probes and answers every group | |
137
137
  | `spawn-apply-max-age` | `--max-age <s>` on a spawn apply bound by `--expect-decision <revision>`: the apply reuses member heads as the preview does, its decision fence unchanged, and its answer carries no `observation` block, OATS 0.58.0 ([Apply](#apply)). Gate on the probe: a kernel without it refuses the flag on an apply (`E_BAD_ARGS`) | |
138
+ | `deployments-list` | `oats deployments [list]\|add\|remove\|import --json`, this computer's list of its deployments (`~/.oats/config/deployments.json`); `listed` on `oats onboard --json`; a kernel command run in an unlisted deployment lists it ([This computer's deployments](#this-computers-deployments-oats-deployments)). Gate on the probe: there is no fallback scan | `deploymentsApi: 1` |
138
139
  | `status-retire-state` | `retire` on `oats status --json` instance rows and on remote roster rows: whether a retire of the home is running, cannot be told, failed or was interrupted, read only from the files beside the home, OATS 0.59.0 ([`retire`](#row-retire)). `retirePending` is unchanged. Gate on the probe: a kernel without it never carries the field, so its absence there says nothing | |
139
140
 
140
141
  Payload-only integers, never in the probe: `onboardApi: 2`, `syncApi: 1`,
@@ -884,7 +885,8 @@ same argument, given once). The ref is checked before anything is written.
884
885
  "next":{"clone":[{"key":"github.com/acme/agents","name":"agents","url":"https://github.com/acme/agents.git","dir":"/w/agents-repo","present":false,"host":true},
885
886
  {"key":"github.com/acme/platform","name":"platform","url":"https://github.com/acme/platform.git","dir":"/w/platform","present":true,"host":false}],
886
887
  "spawn":"oats spawn acme-oats-setup-expert --dir /w",
887
- "souls":["acme-oats-setup-expert","platform-engineer","release-manager"]}}
888
+ "souls":["acme-oats-setup-expert","platform-engineer","release-manager"]},
889
+ "listed":true}
888
890
  ```
889
891
 
890
892
  - `sync` is the full [`oats sync`](#oats-sync) report (abridged above).
@@ -922,6 +924,10 @@ same argument, given once). The ref is checked before anything is written.
922
924
  share a repository name, `<member repo key>/<soul>`. The text output's step 3 names
923
925
  the same soul, or, with none, the conventional name to add.
924
926
  `next.souls` is the first three soul names, sorted.
927
+ - `listed` (feature `deployments-list`): `true` once the deployment is on this
928
+ computer's deployments list ([This computer's deployments](#this-computers-deployments-oats-deployments)),
929
+ else `{code, message}` with the list's error (`E_DEPLOYMENTS_*`). A failed
930
+ add never fails the onboard. `--check` lists nothing.
925
931
  - Errors: `E_BAD_ARGS` (usage, no `--workspace`, a repeated directory, an
926
932
  unknown flag), `E_REPO_REF`, `E_ALREADY_ONBOARDED {local, dir}` (this
927
933
  directory already has `oats-local.yaml`), `E_ONBOARD_FAILED {dir}`. A
@@ -929,6 +935,83 @@ same argument, given once). The ref is checked before anything is written.
929
935
  carries `details: {…, dir, rolledBack: true}`; a later failure keeps the
930
936
  files and carries `details: {…, dir, local}`.
931
937
 
938
+ <a id="this-computers-deployments-oats-deployments"></a>
939
+ ### This computer's deployments (`oats deployments`)
940
+
941
+ Feature `deployments-list`. The kernel's per-user list of the deployments on
942
+ this computer ([workspaces.md](workspaces.md#this-computers-deployments)).
943
+ Every verb runs from anywhere, needs no deployment, takes no `--server`
944
+ (`E_BAD_ARGS`) and never routes to another machine. Each runs the first-use
945
+ `~/Agents` import before it answers.
946
+
947
+ ```text
948
+ oats deployments [list] --json
949
+ oats deployments add [<dir>] [--via tui|desktop] --json
950
+ oats deployments remove <path> --json
951
+ oats deployments import --from desktop <path>... --json
952
+ ```
953
+
954
+ Every answer is a closed key set ([Shapes are closed](#scope)):
955
+
956
+ | Verb | `result` keys, exactly |
957
+ |---|---|
958
+ | `list` | `deploymentsApi`, `file`, `deployments`, `imports`; each row `path`, `name`, `state`, `addedAt`, `via` |
959
+ | `add` | `path`, `added` |
960
+ | `remove` | `path`, `removed` |
961
+ | `import` | `imported`, `at`, `added` on the first run; `imported`, `at` on every later one |
962
+
963
+ A key added to any of them later is a contract change: it is announced here
964
+ first, and accepted by the readers in `packages/client/deployment-list.mjs`
965
+ before a kernel that writes it ships. A change of meaning moves
966
+ `deploymentsApi` to 2. A tombstone stays inside the file: its `removed` and
967
+ `removedAt` never reach an answer, and a tombstoned row is never listed.
968
+
969
+ **`list`** (the default verb):
970
+
971
+ ```json
972
+ {"deploymentsApi":1,"file":"/home/me/.oats/config/deployments.json",
973
+ "deployments":[{"path":"/home/me/acme","name":"acme","state":"ok","addedAt":"2026-10-19T10:00:00.000Z","via":"onboard"}],
974
+ "imports":{"agents-dir":"2026-10-19T10:00:00.000Z"}}
975
+ ```
976
+
977
+ - The answer is exactly these four keys, and each row exactly
978
+ `{path, name, state, addedAt, via}`. A row `remove` took out is never in
979
+ it, and fields of the file the answer does not name never reach it.
980
+ - Rows are sorted by `path`. `name` is the last segment of `path`.
981
+ - `state`: `ok`, `missing`, `not-a-deployment` or `unreadable`, from
982
+ existence checks only. A row is a suggestion: a client admits the
983
+ deployment again before it serves it.
984
+ - `via`: `onboard`, `tui`, `desktop`, `cli`, `import:agents-dir` or
985
+ `import:desktop`, for information only.
986
+ - `imports`: the one-time markers as stored (`agents-dir`, `desktop`), each
987
+ the time it ran.
988
+
989
+ **`add`** lists the deployment at or above `<dir>` (default: the working
990
+ directory: the nearest directory whose `oats-local.yaml` is a regular file,
991
+ not a link), canonical, and clears a `remove`. → `{"path":"/home/me/acme","added":true}`;
992
+ `added: false` when it was listed already, and nothing is written. `--via
993
+ tui|desktop` names the client that adds it (default `cli`); any other value is
994
+ `E_BAD_ARGS`. Outside every deployment: `E_LOCAL_MISSING {dir}`.
995
+
996
+ **`remove`** takes the row whose stored path is `<path>` resolved (no walk up,
997
+ so a row whose directory is gone can be removed); nothing on disk is touched.
998
+ → `{"path":"/home/me/acme","removed":true}`; `removed: false`, exit 0, when
999
+ `<path>` is not listed. The row is kept as a tombstone: nothing but `add` or
1000
+ `onboard` lists that path again.
1001
+
1002
+ **`import --from desktop`** is the Desktop's one-time migration of its own
1003
+ lists. The first run lists every absolute path given, whatever its state, and
1004
+ sets `imports.desktop`, in one write →
1005
+ `{"imported":true,"at":"<marker>","added":["/home/me/acme"]}` (`added`: the
1006
+ paths it listed; zero paths are accepted). Every later run changes nothing →
1007
+ `{"imported":false,"at":"<marker>"}`. A relative path is `E_BAD_ARGS` before
1008
+ anything is written. A path `remove` took out is not listed again.
1009
+
1010
+ Errors of every verb: `E_DEPLOYMENTS_INVALID {file, reason}`,
1011
+ `E_DEPLOYMENTS_VERSION {file, schemaVersion}`, `E_DEPLOYMENTS_BUSY {file, lock}`,
1012
+ `E_DEPLOYMENTS_WRITE {file}`, `E_DEPLOYMENTS_IMPORT {dir}` ([the messages](workspaces.md#this-computers-deployments)),
1013
+ and `E_BAD_ARGS`.
1014
+
932
1015
  ### `oats sync`
933
1016
 
934
1017
  ```text
@@ -3276,9 +3359,9 @@ whose key is not known; an unparsable ref is `E_REPO_REF`.
3276
3359
 
3277
3360
  ```json
3278
3361
  {"file":"/Users/me/.oats/servers.json",
3279
- "servers":[{"id":"altair-aweb","sshHost":"altair","workspace":"/Users/me/Agents/aweb","path":"/opt/homebrew/bin","label":"altair",
3362
+ "servers":[{"id":"altair-aweb","sshHost":"altair","workspace":"/Users/me/acme","path":"/opt/homebrew/bin","label":"altair",
3280
3363
  "workspaceKey":"github.com/awebai/ac",
3281
- "target":{"sshHost":"altair","workspace":"/Users/me/Agents/aweb","oatsPath":"oats","path":"/opt/homebrew/bin"},"snapshots":0}],
3364
+ "target":{"sshHost":"altair","workspace":"/Users/me/acme","oatsPath":"oats","path":"/opt/homebrew/bin"},"snapshots":0}],
3282
3365
  "unknownWorkspace":["build"]}
3283
3366
  ```
3284
3367
 
@@ -3296,7 +3379,7 @@ contradicts fails the check with `E_SERVER_WORKSPACE_MISMATCH`, `details:
3296
3379
  ### `oats server connect` (feature `server-connect`)
3297
3380
 
3298
3381
  ```text
3299
- oats server connect <id> --ssh <host> [--workspace-ref <ref>] [--dir </abs/path or ~/path on the host>]
3382
+ oats server connect <id> --ssh <host> --dir </abs/path or ~/path on the host> [--workspace-ref <ref>]
3300
3383
  [--oats <path>] [--path <dirs>] [--label <text>] [--install-oats] [--replace] --json
3301
3384
  ```
3302
3385
 
package/docs/desktop.md CHANGED
@@ -120,14 +120,23 @@ OATS deployment — the directory (the operator's choice) holding
120
120
  `oats-local.yaml` and `agents/`. A folder that is not a deployment is never
121
121
  opened: started from Finder, with nothing open to restore, the window shows
122
122
  the workspace switcher instead. It lists the deployments on this computer
123
- under **On this computer** (those directly inside `~/Agents`, and a saved
124
- one that is not open); click one to open it in this window. **Add local
125
- workspace… → Browse** points it at any other deployment.
123
+ under **On this computer**: those on this computer's deployments list
124
+ (`oats deployments`, see [Workspaces](workspaces.md)) and a saved one,
125
+ that are not open. Click one to open it in this window. A deployment the list
126
+ holds but that can't be opened says why: missing (the folder is gone, or its
127
+ volume isn't mounted), not a deployment any more, or can't be checked. **Remove**
128
+ beside a row takes it off the list (Right Arrow, then Enter, from the
129
+ keyboard); nothing on disk changes. With an oats that has no such list, the
130
+ switcher shows the saved deployments and says "This oats can't list this
131
+ computer's deployments. Update oats." **Add local workspace… → Browse**
132
+ points it at any other deployment.
126
133
  A picked folder without `oats-local.yaml` is offered onboarding instead. The
127
134
  Desktop never parses the deployment: its members, lock state and header come
128
135
  from `oats workspace status`, and its instances from the deployment's one
129
136
  `agents/` root.
130
- Added workspaces are remembered and offered as suggestions next time.
137
+ Every deployment you open (an add, or the one the app was launched on) is
138
+ put on this computer's deployments list, so it is offered next time. The first launch of this Desktop moves its own list of
139
+ recently added workspaces there, once.
131
140
  **Browse** opens in the folder holding the workspace most recently added or
132
141
  opened, or your home directory when there is none (never ~/Downloads);
133
142
  **Choose oats…** opens in the directory of the chosen or discovered CLI.
@@ -295,7 +304,7 @@ feature (OATS 0.36.0); without it each deployment has its own entry.
295
304
  - **Deployments.** The **Deployments** page (formerly the Active overview)
296
305
  shows the workspace's overview trees. **All** stacks one section per
297
306
  deployment, each headed by its machine and folder ("This Mac ·
298
- ~/Agents/oats", "altair · ~/Agents/tsm"). Then each deployment has a tab of
307
+ ~/acme", "altair · ~/northwind"). Then each deployment has a tab of
299
308
  its own, named by its machine ("altair"; "This Mac · oats-v2" when this Mac
300
309
  holds two). A workspace with one deployment shows just that deployment's
301
310
  tab. The tab you chose is remembered per workspace. With two or more
@@ -53,9 +53,10 @@ effect of reading: for each deployment opened in a run it runs the kernel
53
53
  of the same install and the shared liveness collector as children, through
54
54
  the shared observer and refresh loop; it runs that kernel's read of the
55
55
  other machines (`oats server roster --json`), one at a time and awaited by
56
- no cycle; it ends every child; and it makes the two looks at the file
57
- system the workspace switcher needs (the entries of `~/Agents`, and whether
58
- a picked folder is a deployment). `lib/store.mjs` is the state and a pure
56
+ no cycle; it ends every child; and it makes the one look at the file
57
+ system the workspace switcher needs (whether a picked row is a deployment).
58
+ This computer's list of deployments is the kernel's: `lib/main.mjs` reads
59
+ and changes it through the shared `cliDeploymentList`. `lib/store.mjs` is the state and a pure
59
60
  `reduce(state, event)`; `lib/model.mjs` turns the state into the rows to
60
61
  draw by calling the shared readers through `lib/client.mjs`, the one module
61
62
  that imports `packages/client/`; `lib/views/` are pure functions from that
@@ -126,6 +127,8 @@ and the rules its tests pin.
126
127
  | `read-ahead.mjs`, `read-ahead-worker.mjs` | read-ahead for the tree digests (`fingerprintTrees`): while a digest reads a tree on the calling thread, a planner thread walks it in the digest's order and a few reader threads read the next files into the page cache, within a window of bytes and files ahead of the digest. The digest still reads and hashes every byte itself, so no value or error depends on it; one that cannot start or falls behind costs speed only |
127
128
  | `session-input.mjs` | session inspection and input transport. `createSessionPaneInspector` interprets one window's panes for both lifecycle inspection and status, sharing a lazy process scan across a status read; `core.mjs` batches pane reads per socket/session and applies its shared `harnessRunning` predicate |
128
129
  | `servers.mjs` | routing commands to a registered server |
130
+ | `deployments.mjs` | this computer's deployments ([workspaces.md](workspaces.md#this-computers-deployments)): the per-user files `<OATS_HOME_DIR>/config/deployments.json` (the list, 0600 in a 0700 `config/`) and `config/deployments.lock` (`withDirLock`, waited for up to 3 s), the bounded no-follow read, the atomic write, the first-use `~/Agents` import (the real `$HOME`) and the five `E_DEPLOYMENTS_*` codes. `oats deployments`, onboard's `listed` and the auto-add write through it. `listResolved` is the auto-add: `bin/oats.mjs` sets it as the observer of `resolved-deployment.mjs` for the commands in its one table (`LISTS_ITS_DEPLOYMENT`), so it runs once per process on the deployment the command itself resolved. A listed deployment costs one bounded read (no lock, write, process or realpath), another spelling of it a realpath; a spelled root in a linked worktree or submodule (a `.git` file above it) is left to the commands that resolve its canonical root; a root under a temporary directory (`underTemporaryDirectory`, awebai/oats#1397) is never auto-added; only a path not listed is canonicalized and takes the lock, without waiting for it. It never throws or prints |
131
+ | `resolved-deployment.mjs` | the deployment a command resolved: `loadLocal` (`workspace.mjs`) reports the directory it found as spelled, `ensureRoot` (`core.mjs`) the canonical one, and the observer the CLI set is called once, at exit, with the first canonical root (else the first spelled one), so an earlier spelling never stands for a root the command canonicalized. A no-op until the CLI sets one, so library callers and tests are unaffected. Dependency-free |
129
132
  | `launch-prompt-evidence.mjs` | private bounded storage of exact unmatched, stable-screen completed or flag-ignored notice frames, original-home identity checks and receipt-last publication; no terminal operations or public raw text |
130
133
  | `launch-prompt-completion.mjs` | the 21 question markers that block after the development-channel Enter; reporting only, never an input matcher |
131
134
  | `launch-prompt-fixtures.mjs` | the development-channel tolerance list (`launch-prompt-fixtures/dev-channel-confirmation.json`): engagement from the argv, the enumerated normalization, equality matching, the `flag-ignored` notice block, the running-session banner hint, what differed, and the Claude version read from the executable's path |
@@ -501,6 +504,26 @@ the rule:
501
504
  preload in `OATS_TEST_RUN_DIR`, and the preload takes that variable out of
502
505
  the file's environment before any code of the file runs. No test sees it,
503
506
  nor any process a test starts.
507
+ - The preload also gives each file an `OATS_HOME_DIR` of its own,
508
+ `<n>.oats-home` beside its directory, holding a deployments list whose
509
+ `~/Agents` import is marked done (awebai/oats#1390). Any kernel command run
510
+ in a deployment adds that deployment to this computer's list, so a test
511
+ that runs the CLI with the environment it was given never writes the
512
+ person's `~/.oats`, nor reads their `~/Agents`. A test that names an
513
+ `OATS_HOME_DIR` of its own beside the person's `HOME` seeds the same marker
514
+ (`test/helpers/host-fixture.mjs` `deploymentsImported`); a fixture with a
515
+ `HOME` of its own needs nothing. When the run has ended, a row added to the
516
+ person's list during the run under a temporary directory fails the run,
517
+ naming it.
518
+ - The auto-add never lists a deployment under a temporary directory
519
+ (awebai/oats#1397), so a test that needs it to list one makes its
520
+ deployments outside them: `test/helpers/outside-temporary.mjs`
521
+ `outsideTemporaryBase(t)`, a 0700 base in `/var/tmp` named
522
+ `oats-deployments-test-<run>.<n>-…` and removed when the test ends. Where
523
+ `/var/tmp` is missing, not writable or itself temporary, such a test skips,
524
+ saying why; it never falls back to `/tmp`. The run reads `/var/tmp` for its
525
+ own bases when it has ended: one still there is left behind, named for its
526
+ file and removed.
504
527
  - When the run has ended it reads each file's directory. If one is not empty
505
528
  the run fails, even if every test passed, and names each file and what it
506
529
  left.
@@ -41,7 +41,7 @@ arrives from.
41
41
  # oats-workspace.yaml: one default per slot, for every soul
42
42
  packages:
43
43
  oats.okf: v5.2.1
44
- oats.aweb: v1.29.0
44
+ oats.aweb: v1.30.0
45
45
  oats.linear: v1.0.1
46
46
  oats.jira: v1.0.1
47
47
  defaults:
@@ -9,9 +9,9 @@ or workspace membership alone does not make a package official.
9
9
 
10
10
  | package | release | capabilities | package souls |
11
11
  |---|---|---|---|
12
- | `oats.framework` | `oats-framework/v1.13.3` (this repository) | `oats.core`, `oats.setup`, `oats.support`, `oats.knowledge-theory` | `knowledge-theory-expert` |
12
+ | `oats.framework` | `oats-framework/v1.13.4` (this repository) | `oats.core`, `oats.setup`, `oats.support`, `oats.knowledge-theory` | `knowledge-theory-expert` |
13
13
  | `oats.okf` | `v5.2.1` | `oats.okf` (knowledge), `oats.okf-harvest`, `oats.okf-maintenance` | `knowledge-harvester`, `knowledge-maintainer` |
14
- | `oats.aweb` | `v1.29.0` | `oats.aweb` (messaging) | |
14
+ | `oats.aweb` | `v1.30.0` | `oats.aweb` (messaging) | |
15
15
  | `oats.engineering` | `v1.10.0` | `oats.engineering-expert`, `oats.developer`, `oats.code-review`, `oats.maintainer` | `code-reviewer` |
16
16
  | `oats.authoring` | `v1.0.3` | `oats.authoring` | |
17
17
  | `oats.cloning` | `v1.0.1` | `oats.cloning` | `cloner` |
package/docs/packages.md CHANGED
@@ -51,7 +51,7 @@ packages:
51
51
  - **Bare version** (`v5.2.1`, `5.2.1`, `1.0.0-rc.1`): the id is looked up in
52
52
  the official catalog — `package-catalog.json` in the `oats` repo, or the file
53
53
  named by `OATS_PACKAGE_CATALOG` — which supplies the repo url, the tag
54
- convention (`v5.2.1` or `oats-framework/v1.13.3`) and the payload path. An id
54
+ convention (`v5.2.1` or `oats-framework/v1.13.4`) and the payload path. An id
55
55
  the catalog does not know is `E_PACKAGE_MISSING` ("use `git:<repo>@<ref>` for
56
56
  a package outside the catalog"). The catalog is the reviewed official list
57
57
  ([official-catalog.md](official-catalog.md)) and the only way a
@@ -74,9 +74,9 @@ members:
74
74
  - git:github.com/acme/agents
75
75
  - git:github.com/acme/platform
76
76
  packages:
77
- oats.framework: v1.13.3
77
+ oats.framework: v1.13.4
78
78
  oats.okf: v5.2.1
79
- oats.aweb: v1.29.0
79
+ oats.aweb: v1.30.0
80
80
  teams:
81
81
  platform: { team: "platform:acme.aweb.ai", description: Platform engineering }
82
82
  defaults:
@@ -134,7 +134,7 @@ Declaring a package in the workspace's `packages:` is the trust decision
134
134
  ## `oats package add | remove`
135
135
 
136
136
  ```bash
137
- oats package add oats.aweb v1.29.0 # a catalog version
137
+ oats package add oats.aweb v1.30.0 # a catalog version
138
138
  oats package add acme.tools git:github.com/acme/tools@v0.4.0
139
139
  oats package remove acme.tools
140
140
  ```
@@ -353,11 +353,11 @@ A soul that names one of the package's capabilities with
353
353
  "policy": "docs/official-catalog.md",
354
354
  "packages": {
355
355
  "oats.okf": { "url": "https://github.com/awebai/oats-okf.git", "ref": "v5.2.1", "path": "oats-package" },
356
- "oats.framework": { "url": "https://github.com/awebai/oats.git", "ref": "oats-framework/v1.13.3", "path": "oats-package" }
356
+ "oats.framework": { "url": "https://github.com/awebai/oats.git", "ref": "oats-framework/v1.13.4", "path": "oats-package" }
357
357
  }
358
358
  }
359
359
  ```
360
360
 
361
- `ref` carries the tag convention: a workspace's `oats.framework: v1.13.3`
362
- resolves to tag `oats-framework/v1.13.3`. Resolving through the catalog never
361
+ `ref` carries the tag convention: a workspace's `oats.framework: v1.13.4`
362
+ resolves to tag `oats-framework/v1.13.4`. Resolving through the catalog never
363
363
  advances a lock by itself: `oats sync` does, and says so.