@wipcomputer/wip-ldm-os 0.4.85-alpha.28 → 0.4.85-alpha.29

package/README.md

@@ -28,14 +28,13 @@ Do not run GitHub commands during this install flow. Do not run or request appro
 
 Check if LDM OS is installed (`which ldm && ldm --version`). Branch.
 
-If installed: run `ldm status` and show me the version table and what's new for each component. Then ask:
+If installed: run `ldm status`, check available npm tracks from the install document, and show me the version table, what's new for each component, and which stable/current, beta, and alpha versions are available. Then ask:
 - Do you have questions?
 - Want to see a dry run?
 
-If yes to dry run, run `ldm install --dry-run`.
+If yes to dry run, use the selected track's dry-run path from the install document.
 
-If I say install, run:
-`npm install -g @wipcomputer/wip-ldm-os@latest && ldm install && ldm doctor`
+If I say install, use the selected track's install path from the install document, then run `ldm doctor`.
 
 If not, walk me through setup and explain:
 
@@ -48,8 +47,7 @@ Then ask:
 - Do you have questions?
 - Want to see a dry run?
 
-If yes to dry run, install the CLI first:
-`npm install -g @wipcomputer/wip-ldm-os`
+If yes to dry run, install the CLI first using the selected track's bootstrap command from the install document.
 
 Then run:
 `ldm init --dry-run`

package/SKILL.md

@@ -35,6 +35,92 @@ Use this install document and live local checks as the source of truth. Do not s
 
 Do not run GitHub commands during the install-state flow. Do not run or request approval for `gh release list`, `gh release view`, `gh api repos/*`, `gh search`, or any other GitHub query unless the user explicitly asks for release notes. Install-state answers should come from local commands, `ldm status`, and npm package metadata.
 
+## Tracks
+
+LDM OS ships on three npm dist-tags. Each tag is just a name pointing at a specific version. Show the user the installed version and the available tracks in plain English. Do not paste raw JSON.
+
+- **stable** (`ldm install`) ... npm `@latest`. Use this only when `@latest` resolves to a non-prerelease version. Default for production releases.
+- **beta** (`ldm install --beta`) ... npm `@beta`. Prerelease track. Stabilization candidates.
+- **alpha** (`ldm install --alpha`) ... npm `@alpha`. Canary track. Earliest access; expect breakage.
+
+### Pick the right track
+
+Run this to get the dist-tags. Read the output and translate it into track names and versions.
+
+```bash
+npm view @wipcomputer/wip-ldm-os dist-tags --json
+```
+
+The npm `latest` tag is the stable/current track for user language. It is not guaranteed to be the newest prerelease. If `latest` points at a prerelease, explain that a stable release is not available yet.
+
+User language maps to tracks like this:
+
+- `stable`, `current`, or `latest` means `ldm install`
+- `beta` or `latest beta` means `ldm install --beta`
+- `alpha` or `latest alpha` means `ldm install --alpha`
+
+Dry-run commands use the same selected track:
+
+- stable/current/latest: `ldm install --dry-run`
+- beta/latest beta: `ldm install --beta --dry-run`
+- alpha/latest alpha: `ldm install --alpha --dry-run`
+
+Install commands use the same selected track:
+
+- stable/current/latest: `ldm install`
+- beta/latest beta: `ldm install --beta`
+- alpha/latest alpha: `ldm install --alpha`
+
+First-time CLI bootstrap commands use the same selected track:
+
+- stable/current/latest: `npm install -g @wipcomputer/wip-ldm-os`
+- beta/latest beta: `npm install -g @wipcomputer/wip-ldm-os@beta`
+- alpha/latest alpha: `npm install -g @wipcomputer/wip-ldm-os@alpha`
+
+If the user already named a track, do not force a generic chooser. Show the exact package, available version, track, and command you will run. Then wait for dry-run or install consent as appropriate.
+
+If the user has not named a track, show what is installed and what is available, then ask which track they want to dry run or install.
+
+Never pin a specific prerelease version in an install command, such as `@wipcomputer/wip-ldm-os@0.4.85-alpha.29`. Use the moving track flags.
+
+### How to phrase the track to the user
+
+The README prompt should stay short. This install document owns the detailed track rules.
+
+When the user asks for install state, say this first:
+
+> You have `<LOCAL>` installed. Available: stable/current `<NPM_LATEST_OR_NONE>`, beta `<NPM_BETA_OR_NONE>`, alpha `<NPM_ALPHA_OR_NONE>`.
+
+If no local install exists, say:
+
+> LDM OS is not installed. Available: stable/current `<NPM_LATEST_OR_NONE>`, beta `<NPM_BETA_OR_NONE>`, alpha `<NPM_ALPHA_OR_NONE>`.
+
+Then continue with the setup explanation and ask whether the user has questions or wants a dry run.
+
+If the user named a track, answer directly:
+
+> You asked for `<TRACK>`. The available `<TRACK>` version is `<VERSION>`. The dry-run command is `<COMMAND>`.
+
+If the user says `stable`, `current`, or `latest` and npm `@latest` is a prerelease, say:
+
+> Stable is not available yet. The stable/current track currently points at prerelease `<NPM_LATEST>`. Available prerelease tracks are beta `<NPM_BETA_OR_NONE>` and alpha `<NPM_ALPHA_OR_NONE>`. Which track do you want?
+
+Do not treat public install docs as beta-only or alpha-only. Alpha, beta, and stable are all public npm tracks. Disclose risk and let the user choose.
+
+Track risk language:
+
+- stable/current/latest: normal public path, once it is a real non-prerelease release.
+- beta: public prerelease path.
+- alpha: canary path, likely rougher, but installable if the user asks for it.
+
+#### Anti-patterns ... do NOT print any of these.
+
+- Do not print raw `npm view ... dist-tags` JSON.
+- Do not use `latest` as a synonym for newest prerelease.
+- Do not give a hardcoded single-track recommendation when the user asked what is available.
+- Do not force a generic chooser after the user already said `latest alpha`, `alpha`, `latest beta`, `beta`, `stable`, `current`, or `latest`.
+- Do not run `gh release list` during install-state detection.
+
 ## Step 1: Check if installed
 
 ```bash
@@ -95,15 +181,23 @@ Show 2-3 bullets per component. Then:
 
 Do you have questions? Want to see a dry run?
 
-```bash
-ldm install --dry-run
-```
+Use the selected track from **Pick the right track**:
+
+- stable/current/latest: `ldm install --dry-run`
+- beta/latest beta: `ldm install --beta --dry-run`
+- alpha/latest alpha: `ldm install --alpha --dry-run`
 
 Don't install until the user says "install".
 
+Use the selected track from **Pick the right track**:
+
+- stable/current/latest: `ldm install`
+- beta/latest beta: `ldm install --beta`
+- alpha/latest alpha: `ldm install --alpha`
+
+Then verify with:
+
 ```bash
-npm install -g @wipcomputer/wip-ldm-os@latest
-ldm install
 ldm doctor
 ```
 
@@ -129,10 +223,11 @@ Read [references/SKILLS-CATALOG.md](references/SKILLS-CATALOG.md). Present the i
 
 Do you have questions? Want to see a dry run?
 
-Install the CLI first:
-```bash
-npm install -g @wipcomputer/wip-ldm-os
-```
+Install the CLI first using the selected track from **Pick the right track**:
+
+- stable/current/latest: `npm install -g @wipcomputer/wip-ldm-os`
+- beta/latest beta: `npm install -g @wipcomputer/wip-ldm-os@beta`
+- alpha/latest alpha: `npm install -g @wipcomputer/wip-ldm-os@alpha`
 
 If npm/node is not installed: Node.js 18+ from https://nodejs.org first.
 
@@ -173,6 +268,14 @@ ldm doctor --fix
 - **Dry-run first.** Always. Only install when the user says "install".
 - **Never touch sacred data.** crystal.db, agent data, secrets, state files are never overwritten.
 
+## Track caveats
+
+Tell the user, scaled to the track they're on:
+
+- **alpha**: canary path, earliest access, breakage possible. Use only when the user explicitly opts in.
+- **beta**: stabilization candidate. Same shape as alpha but feature-frozen for the cut.
+- **stable**: production. The user should be on this unless they've asked otherwise.
+
 ## Reference files
 
 For detailed information, read these on demand (not on every activation):

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wipcomputer/wip-ldm-os",
-  "version": "0.4.85-alpha.28",
+  "version": "0.4.85-alpha.29",
   "type": "module",
   "description": "LDM OS: identity, memory, and sovereignty infrastructure for AI agents",
   "engines": {
@@ -18,10 +18,11 @@
   "scripts": {
     "build:bridge": "cd src/bridge && npm install && npx tsup core.ts mcp-server.ts cli.ts openclaw.ts --format esm --dts --clean --outDir ../../dist/bridge",
     "build": "npm run build:bridge",
-    "prepublishOnly": "npm run build:bridge && npm run validate:bin-manifest && npm run test:install-prompt-policy && npm run test:ldm-status-timeout && npm run test:ldm-status-concurrency && npm run test:legacy-npm-sources-migration",
+    "prepublishOnly": "npm run build:bridge && npm run validate:bin-manifest && npm run test:install-prompt-policy && npm run test:readme-install-prompt && npm run test:ldm-status-timeout && npm run test:ldm-status-concurrency && npm run test:legacy-npm-sources-migration",
     "validate:bin-manifest": "node scripts/validate-bin-manifest.mjs",
     "test:skill-frontmatter": "node scripts/test-skill-frontmatter.mjs",
     "test:install-prompt-policy": "node scripts/test-install-prompt-policy.mjs",
+    "test:readme-install-prompt": "node scripts/test-readme-install-prompt.mjs",
     "test:ldm-status-timeout": "node scripts/test-ldm-status-timeout.mjs",
     "test:ldm-status-concurrency": "node scripts/test-ldm-status-concurrency.mjs",
     "test:legacy-npm-sources-migration": "node scripts/test-legacy-npm-sources-migration.mjs",

package/scripts/test-install-prompt-policy.mjs

@@ -24,8 +24,10 @@ for (const file of ["README.md", "shared/templates/install-prompt.md"]) {
     "Do not run GitHub commands during this install flow. Do not run or request approval for `gh release`, `gh api`, or `gh search`.",
     "If release notes are not available from local or npm metadata, say that and do not fetch them from GitHub.",
     "If installed: run `ldm status`",
-    "If yes to dry run, run `ldm install --dry-run`.",
-    "`npm install -g @wipcomputer/wip-ldm-os@latest && ldm install && ldm doctor`",
+    "check available npm tracks from the install document",
+    "If yes to dry run, use the selected track's dry-run path from the install document.",
+    "If I say install, use the selected track's install path from the install document, then run `ldm doctor`.",
+    "install the CLI first using the selected track's bootstrap command from the install document",
     "Then run:\n`ldm init --dry-run`",
     "If I say install, run:\n`ldm init`",
   ]) {
@@ -45,6 +47,13 @@ for (const phrase of [
   "Read that document and run those commands. Do not pre-load other context.",
   "Do not run GitHub commands during the install-state flow.",
   "Do not run or request approval for `gh release list`, `gh release view`, `gh api repos/*`, `gh search`, or any other GitHub query unless the user explicitly asks for release notes.",
+  "npm view @wipcomputer/wip-ldm-os dist-tags --json",
+  "The README prompt should stay short. This install document owns the detailed track rules.",
+  "stable/current/latest: `ldm install --dry-run`",
+  "beta/latest beta: `ldm install --beta --dry-run`",
+  "alpha/latest alpha: `ldm install --alpha --dry-run`",
+  "beta/latest beta: `npm install -g @wipcomputer/wip-ldm-os@beta`",
+  "alpha/latest alpha: `npm install -g @wipcomputer/wip-ldm-os@alpha`",
   "Use the output of `ldm status`, installed package metadata, and npm metadata.",
   "Do not use GitHub commands here.",
   "If npm metadata for a package does not include release notes:",

package/scripts/test-readme-install-prompt.mjs

@@ -0,0 +1,66 @@
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+
+const readme = readFileSync(new URL("../README.md", import.meta.url), "utf8");
+const promptTemplate = readFileSync(
+  new URL("../shared/templates/install-prompt.md", import.meta.url),
+  "utf8",
+);
+const skill = readFileSync(new URL("../SKILL.md", import.meta.url), "utf8");
+
+const promptStart = readme.indexOf("Read https://wip.computer/install/wip-ldm-os.txt");
+const promptEnd = readme.indexOf("```", promptStart);
+
+assert(promptStart >= 0, "README install prompt must point at the public install document");
+assert(promptEnd > promptStart, "README install prompt must be fenced");
+
+const readmePrompt = readme.slice(promptStart, promptEnd);
+
+for (const [label, prompt] of [
+  ["README install prompt", readmePrompt],
+  ["shared install prompt template", promptTemplate],
+]) {
+  assert(
+    prompt.includes("Read https://wip.computer/install/wip-ldm-os.txt"),
+    `${label} must delegate to the public install document`,
+  );
+
+  assert(
+    prompt.includes("Use the install document and live local checks as the source of truth."),
+    `${label} must name the install document as source of truth`,
+  );
+
+  assert(
+    prompt.includes("use the selected track's dry-run path from the install document"),
+    `${label} must delegate dry-run command mapping to SKILL.md`,
+  );
+
+  assert(
+    prompt.includes("use the selected track's install path from the install document"),
+    `${label} must delegate install command mapping to SKILL.md`,
+  );
+
+  for (const forbidden of [
+    "Track choices:",
+    "ldm install --alpha",
+    "ldm install --beta",
+    "ldm install --dry-run",
+  ]) {
+    assert(!prompt.includes(forbidden), `${label} must not include ${forbidden}`);
+  }
+}
+
+for (const required of [
+  "## Tracks",
+  "npm view @wipcomputer/wip-ldm-os dist-tags --json",
+  "stable/current/latest: `ldm install --dry-run`",
+  "beta/latest beta: `ldm install --beta --dry-run`",
+  "alpha/latest alpha: `ldm install --alpha --dry-run`",
+  "beta/latest beta: `npm install -g @wipcomputer/wip-ldm-os@beta`",
+  "alpha/latest alpha: `npm install -g @wipcomputer/wip-ldm-os@alpha`",
+  "The README prompt should stay short. This install document owns the detailed track rules.",
+]) {
+  assert(skill.includes(required), `SKILL.md must own track-selection logic: ${required}`);
+}
+
+console.log("readme-install-prompt: prompt stays short and delegates track rules to SKILL.md");

package/shared/templates/install-prompt.md

@@ -12,14 +12,13 @@ Do not run GitHub commands during this install flow. Do not run or request appro
 
 Check if LDM OS is installed (`which ldm && ldm --version`). Branch.
 
-If installed: run `ldm status` and show me the version table and what's new for each component. Then ask:
+If installed: run `ldm status`, check available npm tracks from the install document, and show me the version table, what's new for each component, and which stable/current, beta, and alpha versions are available. Then ask:
 - Do you have questions?
 - Want to see a dry run?
 
-If yes to dry run, run `ldm install --dry-run`.
+If yes to dry run, use the selected track's dry-run path from the install document.
 
-If I say install, run:
-`npm install -g @wipcomputer/wip-ldm-os@latest && ldm install && ldm doctor`
+If I say install, use the selected track's install path from the install document, then run `ldm doctor`.
 
 If not, walk me through setup and explain:
 
@@ -32,8 +31,7 @@ Then ask:
 - Do you have questions?
 - Want to see a dry run?
 
-If yes to dry run, install the CLI first:
-`npm install -g @wipcomputer/wip-ldm-os`
+If yes to dry run, install the CLI first using the selected track's bootstrap command from the install document.
 
 Then run:
 `ldm init --dry-run`