Improve npm alpha publishing readiness

.github/workflows/ci.yml

@@ -46,5 +46,8 @@ jobs:
       - name: Check package contents
         run: pnpm pack:codex-claw
 
+      - name: Smoke packed CLI
+        run: pnpm smoke:codex-claw:pack
+
       - name: Audit dependencies
         run: pnpm audit --audit-level low

.github/workflows/release-package.yml

@@ -44,6 +44,9 @@ jobs:
       - name: Build package archive
         run: pnpm package:codex-claw
 
+      - name: Smoke packed CLI
+        run: pnpm smoke:codex-claw:pack
+
       - name: Write SHA256 checksums
         shell: bash
         run: |

README.md

@@ -26,6 +26,7 @@ CodexClaw turns your installed <code>codex</code> command into a local web clien
 - [Terminal Demo](#terminal-demo)
 - [Configuration](#configuration)
 - [Common Commands](#common-commands)
+- [Troubleshooting](#troubleshooting)
 - [How It Works](#how-it-works)
 - [Beta Track](#beta-track)
 - [Contributing](#contributing)
@@ -75,13 +76,35 @@ codex exec "Reply with: ready"
 
 The public npm package target is <code>codex-claw@0.1.0-alpha.0</code>.
 
-After the first npm alpha publish, the install path will be:
+After the first npm alpha publish, start without a global install:
+
+~~~powershell
+# Windows PowerShell
+npx codex-claw@alpha
+npm exec codex-claw@alpha -- doctor
+~~~
 
 ~~~bash
+# macOS and Linux
 npx codex-claw@alpha
+npm exec codex-claw@alpha -- doctor
+~~~
+
+For a pinned global CLI during alpha:
+
+~~~bash
+npm install -g codex-claw@alpha
+codex-claw doctor
+codex-claw --help
+~~~
+
+Update by re-running <code>npx codex-claw@alpha</code> or reinstalling the alpha tag:
+
+~~~bash
+npm install -g codex-claw@alpha
 ~~~
 
-Until then, use the source checkout above. The package is intentionally tagged as alpha so early releases do not claim a stable <code>latest</code> workflow.
+Until the first alpha package exists on npm, use the source checkout above. The package is intentionally tagged as alpha so early releases do not claim a stable <code>latest</code> workflow.
 
 ## Terminal Demo
 
@@ -102,7 +125,16 @@ Local source readiness check:
 
 ~~~console
 $ node packages/codex-claw/bin/codex-claw.js doctor
-Environment looks good.
+[ok] Node.js: Node.js 20.19.5
+[ok] npm: 10.8.2
+[warn] npm auth: npm auth unavailable. Run `npm login` before publishing codex-claw@alpha.
+[ok] pnpm: 9.15.4
+[ok] git: git version 2.51.0.windows.1
+[ok] git worktree: Current directory is a git worktree.
+[ok] Codex CLI: codex-cli 0.61.0
+[ok] state directory: .codex-claw can be created on first run.
+[ok] port: Port 3000 is available.
+Environment is usable with 1 warning(s).
 ~~~
 
 Manual source workflow:
@@ -141,9 +173,27 @@ pnpm lint                # run ESLint
 pnpm landing:dev         # start the landing page
 pnpm landing:build       # build the landing page
 pnpm pack:codex-claw     # inspect npm package contents
+pnpm smoke:codex-claw    # run npx against the packed local tarball
+pnpm smoke:codex-claw:npm # run npx against codex-claw@alpha once published
 pnpm release:codex-claw  # publish alpha package with the alpha dist-tag
 ~~~
 
+## Troubleshooting
+
+| Symptom | What to run |
+| --- | --- |
+| <code>npm auth unavailable</code> | Run <code>npm login</code>, then <code>npm whoami</code> before publishing |
+| <code>codex-claw@alpha was not found on npm</code> | The alpha package has not been published yet; use the source checkout or publish with <code>pnpm release:codex-claw</code> |
+| <code>Port 3000 is already in use</code> | Stop the process using the port or run <code>codex-claw doctor --port 3001</code> |
+| <code>Codex CLI was not found</code> | Install Codex CLI, run <code>codex login</code>, or pass <code>--codex-command &lt;cmd&gt;</code> |
+
+Package readiness checks:
+
+~~~bash
+pnpm smoke:codex-claw:pack
+pnpm smoke:codex-claw:npm
+~~~
+
 ## How It Works
 
 ~~~text

package.json

@@ -15,6 +15,9 @@
     "format": "pnpm -C apps/codex-claw format",
     "check": "pnpm -C apps/codex-claw check",
     "pack:codex-claw": "pnpm -C packages/codex-claw exec npm pack --dry-run",
+    "smoke:codex-claw": "node packages/codex-claw/scripts/install-smoke.mjs --source pack",
+    "smoke:codex-claw:pack": "node packages/codex-claw/scripts/install-smoke.mjs --source pack",
+    "smoke:codex-claw:npm": "node packages/codex-claw/scripts/install-smoke.mjs --source npm",
     "package:codex-claw": "node -e \"require('node:fs').mkdirSync('dist/release',{recursive:true})\" && pnpm -C packages/codex-claw exec npm pack --pack-destination ../../dist/release",
     "release:codex-claw": "pnpm -C packages/codex-claw exec npm publish --tag alpha --access public",
     "bump:codex-claw:patch": "pnpm -C packages/codex-claw version patch --no-git-tag-version",

packages/codex-claw/README.md

@@ -20,10 +20,25 @@ The package is designed for an <code>npx codex-claw@alpha</code> first-run workf
 
 ## Alpha Install
 
-After the first public npm publish:
+After the first public npm publish, use <code>npx</code> for the cleanest alpha path:
+
+~~~powershell
+# Windows PowerShell
+npx codex-claw@alpha
+npm exec codex-claw@alpha -- doctor
+~~~
 
 ~~~bash
+# macOS and Linux
 npx codex-claw@alpha
+npm exec codex-claw@alpha -- doctor
+~~~
+
+Global alpha install:
+
+~~~bash
+npm install -g codex-claw@alpha
+codex-claw doctor
 ~~~
 
 Useful non-interactive bootstrap:
@@ -35,6 +50,12 @@ pnpm install
 pnpm dev
 ~~~
 
+Update by re-running <code>npx codex-claw@alpha</code> or reinstalling the alpha tag:
+
+~~~bash
+npm install -g codex-claw@alpha
+~~~
+
 ## Local Development Usage
 
 From this repository:
@@ -55,7 +76,7 @@ node packages/codex-claw/bin/codex-claw.js doctor
 | <code>codex-claw preview</code> | Preview the production build |
 | <code>codex-claw test</code> | Run tests |
 | <code>codex-claw lint</code> | Run lint |
-| <code>codex-claw doctor</code> | Validate Node.js, pnpm, and Codex CLI |
+| <code>codex-claw doctor</code> | Validate Node.js, npm auth, pnpm, Git, Codex CLI, state directory, and dev port availability |
 
 ## Prompts
 
@@ -84,7 +105,20 @@ Then it creates the project folder, installs dependencies, and starts CodexClaw
 npm whoami
 npm view codex-claw version dist-tags --json
 pnpm pack:codex-claw
+pnpm smoke:codex-claw:pack
+pnpm smoke:codex-claw:npm
 pnpm release:codex-claw
 ~~~
 
 The release script publishes with the <code>alpha</code> dist-tag so early builds stay clearly separated from a future stable channel.
+
+## Troubleshooting
+
+| Symptom | Action |
+| --- | --- |
+| <code>npm auth unavailable</code> | Run <code>npm login</code>, then <code>npm whoami</code> before publishing |
+| <code>codex-claw@alpha was not found on npm</code> | The alpha package is not published yet; use the source checkout or publish with <code>pnpm release:codex-claw</code> |
+| <code>Port 3000 is already in use</code> | Stop the existing process or run <code>codex-claw doctor --port 3001</code> |
+| <code>Codex CLI was not found</code> | Install Codex CLI, run <code>codex login</code>, or pass <code>--codex-command &lt;cmd&gt;</code> |
+
+The npm smoke test intentionally fails with a package-not-found message until the alpha package is available on npm.