@astrale-os/cli 1.0.0-beta.3 → 1.0.0-beta.31

package/README.md

@@ -87,12 +87,12 @@ Install the browser driver once:
 
 ```bash
 npm install -g agent-browser && agent-browser install
-npx skills add astrale-os/cli            # installs both the astrale-cli (ops) and astrale-domain (authoring) skills
+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: `npx skills add astrale-os/cli@astrale-cli` or
-`npx skills add astrale-os/cli@astrale-domain`.
+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`.
 
 ## Updating
 
@@ -101,8 +101,15 @@ astrale update --check
 astrale update
 ```
 
-`astrale update` upgrades official script installs and follows the beta channel by default.
-Use `--check`, `--channel <channel>`, or `--version <version>` to control the target release.
+`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.
 
 ## Commands
 
@@ -127,7 +134,7 @@ Main command groups:
 
 ```
 /domain                        Domain node
-/domain/class.Name             Class node, or /domain/interface.Name
+/domain/class.Name             Class node
 /:domain:class.Name:method     Static method (semantic domain path)
 <nodePath>::method             Instance method dispatch
 @nodeId                        Reference a node by UID
@@ -145,6 +152,62 @@ CLI state lives under `~/.astrale/`:
 - `identities.json`
 - keypairs
 - cached IdP sessions
+- `sessions/` — locally recorded work sessions (see below)
+
+### Session retention
+
+Each invocation appends one line to a local session record under
+`~/.astrale/sessions/`; `astrale session list` shows them. The store is swept
+automatically against two bounds — sessions idle past `maxAgeDays` are dropped,
+then the store is trimmed to `maxBytes`, oldest first. Both are optional:
+
+```jsonc
+// ~/.astrale/config.json
+{
+  "telemetry": {
+    "enabled": true,      // false disables recording (the sweep still runs)
+    "maxAgeDays": 30,     // default
+    "maxBytes": 52428800  // default: 50 MB
+  }
+}
+```
+
+`ASTRALE_TELEMETRY_MAX_AGE_DAYS` and `ASTRALE_TELEMETRY_MAX_BYTES` override the
+config for one invocation. Values that are not positive numbers are ignored in
+favour of the default, so a typo cannot leave the store unbounded.
+
+Once a session has been analyzed it is reduced to its durable artifacts —
+`meta.json`, `events.jsonl`, `report.md`, the marker and a clamped
+`analyzer.log`. The analyzer runs an agent with write access to the session
+directory, so anything else it leaves there is scratch and is removed. The
+prompt is kept only when the analysis failed, which is the one case where what
+the analyzer was asked still matters.
+
+### Browser-profile retention
+
+`astrale browser` keeps one persistent Chromium profile per host under
+`~/.astrale/browser/`, so the sign-in cookie survives between runs. That cookie
+is a few kilobytes; the cache Chromium piles up around it is not, and Chromium
+does not bound it (`--disk-cache-size` is ignored for a profile's HTTP cache).
+
+Every `astrale browser` therefore sweeps the profiles first: one untouched for
+longer than `maxProfileAgeDays` is removed outright — its cookie has expired
+anyway — and one whose cache exceeds `maxCacheBytes` has its cache directories
+emptied. Cookies, Local Storage, Preferences and Local State are never touched,
+so you stay signed in. A profile held by a running browser is skipped.
+
+```jsonc
+// ~/.astrale/config.json
+{
+  "browser": {
+    "maxCacheBytes": 52428800,  // default: 50 MB, per profile, cache only
+    "maxProfileAgeDays": 30     // default
+  }
+}
+```
+
+Overridable per invocation with `ASTRALE_BROWSER_MAX_CACHE_BYTES` and
+`ASTRALE_BROWSER_MAX_PROFILE_AGE_DAYS`.
 
 ## Development
 
@@ -162,3 +225,18 @@ bun cli/bin/astrale.ts <command>
 # Build the CLI
 pnpm -C cli build
 ```
+
+### Testing local changes live: `astrale-dev`
+
+When developing inside the [workspace](https://github.com/astrale-os/workspace),
+`astrale` stays the official released CLI. To run your local CLI source live
+(no build, no global link), use `astrale-dev`:
+
+```bash
+astrale-dev <command>   # execs `bun <workspace>/cli/bin/astrale.ts` of the
+                        # workspace/worktree you are currently in
+```
+
+It resolves the workspace from your current directory, so each worktree runs its
+own source, and outside a workspace it refuses (use `astrale`). It is installed
+by the workspace's `./scripts/init-machine.sh`.