@astrale-os/cli 1.0.0-beta.32 → 1.0.0-beta.43

package/README.md

@@ -6,13 +6,26 @@
 
 ## Installation
 
+```bash
+npm install -g @astrale-os/cli@beta
+```
+
+The npm package is the primary consumer installation. It requires Node.js 22
+or newer and installs one bundled `astrale` executable without exposing the SDK
+or Kernel package graph at runtime.
+
+The standalone binary remains available when installing Node is undesirable:
+
 ```bash
 curl -fsSL https://raw.githubusercontent.com/astrale-os/cli/main/install.sh | sh
 ```
 
 The installer places a verified standalone binary at
-`~/.astrale/bin/astrale` by default. No local runtime is installed. During the
-prerelease period, it follows the beta channel by default.
+`~/.astrale/bin/astrale` by default. The same executable contains the CLI,
+[Domain Studio](studio/README.md), its Bun 1.4 runtime, the viewer, and the
+Astrale skills. Running the CLI, Studio, viewer, and Astrale skill manager does
+not require Node, npm, npx, or a separate Bun install. During the prerelease
+period, it follows the beta channel by default.
 
 Optional installer environment:
 
@@ -22,31 +35,9 @@ curl -fsSL https://raw.githubusercontent.com/astrale-os/cli/main/install.sh | AS
 curl -fsSL https://raw.githubusercontent.com/astrale-os/cli/main/install.sh | ASTRALE_VERSION=<version> sh
 ```
 
-### npm (CLI + Domain Studio)
-
-Alternatively, install from npm — this runs the CLI under Node and additionally
-ships the [Domain Studio](studio/README.md) (`astrale studio`):
-
-```bash
-npm install -g @astrale-os/cli
-```
-
-During the prerelease period, install the current beta explicitly:
-
-```bash
-npm install -g @astrale-os/cli@beta
-```
-
-The npm build bundles all dependencies, so no private-registry access is needed.
-`astrale studio` launches a local web GUI to author and inspect a domain, with
-local Claude Code and Codex agent harnesses (`--harness claude|codex`); it runs on
-[Bun](https://bun.sh), so install Bun and keep it on `PATH` to use that command
-(the rest of the CLI needs only Node ≥ 22). The curl-installed standalone binary
-above does not include the studio — use the npm install for `astrale studio`.
-
-> Prereleases use their matching npm dist-tag (`alpha`, `beta`, or `rc`); bare
-> `npm install -g @astrale-os/cli` follows the stable `latest` tag. The curl
-> installer has separate binary channels with the same names.
+Keep only one global `astrale` installation on `PATH`. When migrating from the
+standalone installer, remove or move its old `~/.astrale/bin/astrale` executable
+after confirming the npm-installed command with `command -v astrale`.
 
 ## Quickstart
 
@@ -87,12 +78,21 @@ Install the browser driver once:
 
 ```bash
 npm install -g agent-browser && agent-browser install
-npx skills add astrale-os/cli            # installs every Astrale skill published by this repository
 npx skills add vercel-labs/agent-browser
 ```
 
-To install just one, select `astrale-cli`, `astrale-domain`, `astrale-frontend-design`, or
-`astrale-services`, for example: `npx skills add astrale-os/cli@astrale-frontend-design`.
+Astrale manages its own skills without npx. The installer opens an agent picker,
+preselects detected or previously configured agents, installs the canonical copy
+globally under `~/.agents/skills`, and creates only the selected global links.
+
+```bash
+astrale skills configure
+astrale skills status
+astrale skills update
+```
+
+The global `.skill-lock.json` uses the same v3 schema and Git tree hashes as
+`skills@1.5.23`, so it remains interoperable with that ecosystem.
 
 ## Updating
 
@@ -101,15 +101,22 @@ astrale update --check
 astrale update
 ```
 
-`astrale update` upgrades official script installs, ensures every Astrale agent skill published
-from `astrale-os/cli` is installed and healthy, and follows the beta channel by default. It reports
-whether the skill pass was unchanged, installed, updated, or repaired. Use `--check`,
-`--channel <channel>`, or `--version <version>` to control the CLI release target; skills always
-resolve the repository's current `main` once, verify the installed trees against that commit, and
-stamp the exact revision/tree binding into the Astrale-owned receipt. A current
-`astrale update --check --json` result includes the resolved source revision plus every shipped
-skill's Git tree and entrypoint, so runners can retain the actual loadout rather than only
-`status: current`. `--no-skills` is the explicit opt-out.
+`astrale update` atomically upgrades the standalone executable, then invokes the
+new binary to install, update, or repair the skills embedded in that exact
+release. It follows the beta channel by default. Use `--check`,
+`--channel <channel>`, or `--version <version>` to control the release target;
+`--no-skills` is the explicit opt-out.
+
+An npm-installed CLI never overwrites its own package-manager files. It reports
+the exact package-manager command instead:
+
+```bash
+npm install -g @astrale-os/cli@beta
+```
+
+On ordinary interactive launches, Astrale checks for CLI updates at most once
+per 24 hours and offers **Update now**, **Later**, or **Do not offer this version
+again**. It also detects stale local Astrale skills and offers to repair them.
 
 ## Commands
 
@@ -128,7 +135,7 @@ Main command groups:
 | Kernel | `get`, `call`, `query`, `introspect`, `logs`, `view`, `token` |
 | Context | `status`, `whoami`, `use` |
 | Management | `admin`, `instance`, `identity`, `auth`, `idp`, `update` |
-| Agent | `browser` |
+| Agent | `browser`, `skills` |
 
 ## Path Syntax
 
@@ -209,11 +216,14 @@ so you stay signed in. A profile held by a running browser is skipped.
 Overridable per invocation with `ASTRALE_BROWSER_MAX_CACHE_BYTES` and
 `ASTRALE_BROWSER_MAX_PROFILE_AGE_DAYS`.
 
+Global skills live under `~/.agents/skills`. Their ecosystem-compatible lock is
+`$XDG_STATE_HOME/skills/.skill-lock.json` when XDG state is configured, otherwise
+`~/.agents/.skill-lock.json`.
+
 ## Development
 
-Contributors use Node.js 26.7.0 by default; Node.js 24 is also supported. pnpm is
-pinned to 11.13.1. The source-worktree runtime contract is enforced separately
-from the published CLI's Node ≥ 22 contract.
+Contributors use Node.js 26.7.0 by default and pnpm 12.0.0. Release executables
+are compiled and qualified with Bun 1.4.0.
 
 ```bash
 # From the workspace root

package/THIRD-PARTY-NOTICES.md

@@ -2,10 +2,46 @@
 
 `@astrale-os/cli` is licensed under the **Apache License 2.0** (see `LICENSE`).
 
-The published package additionally ships a pre-built web client for the local
+The standalone executable additionally ships a pre-built web client for the local
 Domain Studio (`studio/client/dist`). That bundle embeds third-party open-source
 components. Components whose license requires attribution are listed below.
 
+## skills (agent registry compatibility)
+
+- **Project:** `vercel-labs/skills`
+- **Compatible version:** `skills@1.5.23`
+- **License:** MIT
+- **Copyright:** © 2026 Vercel, Inc.
+- **Source:** https://github.com/vercel-labs/skills
+
+Astrale derives its global agent names, paths, detection conventions, and v3
+lock-file interoperability from this project. Astrale does not embed or execute
+the `skills` package.
+
+```text
+MIT License
+
+Copyright (c) 2026 Vercel, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+```
+
 ## elkjs (Eclipse Layout Kernel for JavaScript)
 
 - **Package:** `elkjs` (used by `@astrale-os/studio`, bundled into `studio/client/dist`)