@divergeai/cli 0.1.24 → 0.1.25

package/README.md

@@ -140,27 +140,43 @@ claude mcp add --scope user divergent -- diverge tools bridge --tools search_onl
 ## Skills
 
 A skill is a procedure over the tools it names, in the Agent Skills format
-every harness reads (`<name>/SKILL.md`). The organization authors its skills
-on the platform; you get the ones whose every named tool you can run, plus
-the CLI's own `diverge` skill, which tells an agent how to reach the platform's
-tools from a shell.
+every harness reads (`<folder>/SKILL.md`). Each organization authors its
+skills on the platform; the login gets, in every organization it can act
+in, the ones whose every named tool the person can run, plus the CLI's own
+`diverge` skill, which tells an agent how to reach the platform's tools from
+a shell.
 
 ```bash
-diverge skills list       # what the platform serves you
+diverge skills list       # what the platform serves you, per organization
 diverge skills install    # into ~/.claude/skills, ~/.codex/skills and $DSH_HOME/skills
+diverge skills refresh    # the same, best effort and quiet: what sign-in and a session start run
 diverge skills status     # what each folder holds against the platform
 ```
 
-Each SKILL.md is rendered from the skill's record on the platform on every
-install, so what lands in the folder is the skill as it stands now.
-
-`agents setup claude|codex|dsh` and `agents run dsh` install them as well, so
-a harness the CLI set up has the skills from its first session. A refresh
-replaces the CLI's own folders, retires the ones the organization retired, and
-never touches a skill you authored beside them. The skills are the tool
-surface: an agent reaches every platform tool from its shell with `diverge
-tools`, which costs nothing until a tool is called, and the `diverge` skill
-shows it how, arguments piped through stdin and batches included.
+The set is derived from the login, never chosen on the machine: who is
+signed in, where they may act, and what they can run there. A skill's
+identity is its organization and its name, so every organization's skills
+sit side by side in one folder, each under the organization's prefix — its
+short code, lowercased, or a slug of its name: `dvx-consultar-inventario`,
+`red-team-triage-cloud-run`. Each SKILL.md is rendered from the skill's
+record on every install, named after its folder, and opens with the
+organization its tools run in, so an agent passes `--organization-id` on
+every call instead of depending on the machine's default organization.
+
+Nobody runs the install by hand after the first time: `diverge login`
+installs, and a session start refreshes — `agents setup claude` writes a
+SessionStart hook into Claude Code's user settings, a Divergent checkout
+refreshes from its worktree setup for every harness, and `agents run dsh`
+refreshes before dsh starts. A refresh is per organization: it
+replaces that organization's folders, retires the ones it stopped serving,
+and never touches another organization's or a skill you authored beside
+them. A whole-login refresh also retires an organization the login no longer
+lists; `--organization-id` refreshes one and leaves the rest. A session on a
+token file (`DIVERGENT_TOKEN_FILE`) holds that token's one organization. The
+skills are the tool surface: an agent reaches every platform tool from its
+shell with `diverge tools`, which costs nothing until a tool is called, and
+the `diverge` skill shows it how, arguments piped through stdin and batches
+included.
 
 dsh also gets the browser. The overlay mounts Chrome DevTools MCP, attached
 to a Chrome the person starts in debug mode (`--remote-debugging-port=9222`,