@contextecf/guardian-cli 0.1.3 → 0.1.5

package/README.md

@@ -16,6 +16,7 @@ Then open the Control Tower in your default browser:
 
 ```bash
 guardian launch
+guardian open
 ```
 
 The same daemon-backed launch path is also available as:
@@ -44,8 +45,8 @@ guardian setup
 guardian doctor
 guardian readiness
 guardian launch
-guardian status
 guardian open
+guardian status
 guardian policy list
 guardian marketplace list
 guardian posture list
@@ -59,11 +60,11 @@ guardian desktop execute --input=/path/to/approved-action.json --yes
 `guardian setup` is the one-command first-run path after `npm install -g` or
 through `npx`. It creates or reuses the local profile, keeps local-first privacy
 defaults, runs doctor/data checks, writes Guardian-owned MCP snippets under the
-Guardian profile directory, starts or reuses the local daemon, opens the Control
-Tower unless `--print` is supplied, and returns browser-extension setup guidance
-without printing the runtime token. It does not install the native host manifest
-or write external AI tool config unless the user runs the explicit follow-up
-commands.
+Guardian profile directory, starts or reuses the local daemon, and returns
+browser-extension setup guidance without printing the runtime token. It opens
+the Control Tower only when `--open` is supplied. It does not install the native
+host manifest or write external AI tool config unless the user runs the explicit
+follow-up commands.
 
 `guardian extension native-host install --extension-id=<id>` writes the
 Guardian browser native messaging helper and manifest. On macOS/Linux it writes
@@ -75,15 +76,15 @@ launcher, and manifest under `GUARDIAN_HOME/native-host`, then prints exact HKCU
 token-free proof that `guardian extension native-host status --json` can verify.
 
 `guardian launch`, `guardian tower`, and `guardian control-tower` start or reuse
-the local daemon and then open the Control Tower in the default browser. During
-the MVP, that daemon exposes a lightweight metadata-only status page at the
-default URL. Re-running `guardian launch`, `guardian tower`,
-`guardian control-tower`, or `guardian start` first checks the requested
-authenticated loopback health endpoint and reuses the existing daemon when it is
-already reachable. Use `guardian daemon serve` when you want the foreground
-developer process instead. Use `guardian launch --print`,
-`guardian tower --print`, or `guardian control-tower --print` to print the URL
-without opening a browser.
+the local daemon and print the Control Tower URL. During the MVP, that daemon
+exposes a lightweight metadata-only status page at the default URL. Re-running
+`guardian launch`, `guardian tower`, `guardian control-tower`, or
+`guardian start` first checks the requested authenticated loopback health
+endpoint and reuses the existing daemon when it is already reachable. Use
+`guardian daemon serve` when you want the foreground developer process instead.
+Use `guardian launch --open`, `guardian tower --open`, or
+`guardian control-tower --open` when you also want to open the URL in the
+default browser.
 
 `guardian open` launches the already configured local Control Tower URL in the
 default browser without starting the daemon. It uses the installed
@@ -185,6 +186,31 @@ Guardian starts local-first:
 - local app autopilot off
 - metadata-only receipts by default
 
+## Troubleshooting
+
+Run `guardian doctor` first for most of these — it reports pass/warn/fail for
+the local profile, runtime token, Node.js version, service supervision, and OS
+key storage in one pass. `guardian status` reports live daemon health,
+including a stale-daemon-version hint.
+
+| Symptom                                                                                                                                      | Likely cause                                                                                                                                                                                     | Fix                                                                                                                                                                                                                                                                                                          |
+| -------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `guardian doctor` reports the `node-runtime` check as `warn`                                                                                 | Node.js is older than the 20.20.0 floor this CLI requires                                                                                                                                        | Upgrade to Node 20.20+ or Node 22 LTS. Node 22 is the runtime used for the Docker demo and CI clean-room install smoke; Node 20.20+ is the supported floor for everyone else. Re-run `guardian doctor` after upgrading.                                                                                      |
+| `guardian launch`/`guardian start` fails with "another daemon or container ... rejected this profile's local runtime token"                  | Something else (often a stale Guardian daemon, or the Docker demo container) already holds port 4317                                                                                             | Guardian already tries the next 7 ports automatically. If it still fails, stop the other process/container and retry, or run `guardian launch --port=4318` (or the port the error message suggests) directly. `guardian status` and `docker ps --filter publish=4317` help identify what's holding the port. |
+| `guardian status` reports daemon status `unauthorized`, or any Guardian admin request returns `401 unauthorized`                             | The runtime token on disk (`GUARDIAN_HOME/runtime-token`) doesn't match the token the running daemon expects — usually a leftover daemon from before a `guardian install`/profile reset          | Run `guardian stop`, then `guardian launch --port=4322` (or another free port), then `guardian status` to confirm it's reachable and authorized again.                                                                                                                                                       |
+| `guardian status` shows a `daemonVersionMismatch` block (or, in text output, "Daemon version: ... (this CLI is ... — versions differ, ...)") | Usually the CLI was upgraded (`npm install -g @contextecf/guardian-cli@latest`) while a daemon started by the previous version was still running — the same applies in reverse after a downgrade | Run `guardian stop && guardian launch` to restart the daemon under the current version. This is informational only — Guardian never auto-restarts a running daemon or auto-trusts a stale token on your behalf.                                                                                              |
+| `npm publish`/release automation fails with an OTP or auth prompt maintainers don't recognize                                                | This is a release-maintainer concern, not an end-user CLI issue — it's about the npm account publishing `@contextecf/guardian-cli`, not the installed CLI                                        | See `scripts/collect-guardian-npm-auth-preflight.mjs` (repo root) and the Release Owner Commands section below. Never paste an OTP or npm token into `guardian` CLI commands or Guardian issues/logs.                                                                                                        |
+| The browser extension shows "not paired" or can't reach the daemon                                                                           | The extension doesn't have the local runtime token yet                                                                                                                                           | Run `guardian daemon pair --json` to print a one-time pairing payload, then `guardian extension open-setup` to walk through connecting it. The token is only ever printed by this explicit command.                                                                                                          |
+| Native messaging fails, or the extension can't launch the native host                                                                        | The native messaging manifest isn't installed for your browser (and on Windows, isn't registered in HKCU)                                                                                        | Run `guardian extension native-host install --extension-id=<id>`. On Windows, add `--write-registry --yes` to also perform the HKCU registration. Verify with `guardian extension native-host status --json`.                                                                                                |
+| The daemon doesn't survive a reboot, or you want it to run without keeping a terminal open                                                   | Guardian isn't registered with your OS's service supervisor                                                                                                                                      | Run `guardian service install` to register a `launchd` (macOS), `systemd` (Linux), or Windows Task Scheduler entry. `guardian doctor`'s `service-supervision` check confirms it's registered.                                                                                                                |
+| `guardian doctor`'s `os-key-storage` check reports `warn` or `fail`                                                                          | No local-data encryption key has been stored via the OS credential vault yet                                                                                                                     | Run `guardian key-store install --yes` and supply the secret via stdin (never as a CLI argument). Check with `guardian key-store status`.                                                                                                                                                                    |
+
+None of the above changes what Guardian trusts by default: raw content
+capture, cloud sync, and local app autopilot stay off until you explicitly
+enable them, and a rejected or stale runtime token is never auto-accepted —
+every fix above requires an explicit `guardian stop`/`guardian launch` or
+install step.
+
 ## Package Boundary
 
 The npm package publishes bundled CLI/runtime JavaScript, TypeScript
@@ -196,6 +222,47 @@ the monorepo. The native SQLite adapter remains a normal
 Source files, source maps, and source-controlled release gates remain in the
 private repository and should be validated before broad distribution.
 
+## Release Owner Commands
+
+Release owners can ask the installed CLI for the same operator flow used in the
+repo:
+
+```bash
+guardian release
+guardian release checklist --version=0.1.4
+guardian release flow --version=0.1.4
+guardian release command --version=0.1.4
+guardian release command --version=0.1.4 --publish
+guardian release verify --version=0.1.4
+guardian release paste --version=0.1.4
+```
+
+`guardian release flow --version=<version>` prints the full release-owner order
+in one screen: checklist, secret setup, dry-run dispatch, guarded publish
+dispatch, post-publish verification, local smoke, and browser-store handoff.
+
+`guardian release command --version=<version> --publish` prints the copy-ready
+GitHub Actions dispatch command, including `dry_run=false` and the docker smoke
+flag. It does not print npm tokens or run the workflow locally.
+
+After npm publication, `guardian release paste --version=<version>` prints only
+the local smoke commands:
+
+```bash
+npm view @contextecf/guardian-cli@0.1.4 version --registry=https://registry.npmjs.org/
+npm install -g @contextecf/guardian-cli@0.1.4
+guardian --version
+guardian stop
+guardian setup
+guardian launch
+guardian open
+guardian status
+```
+
+That paste block proves public npm visibility and first-run usability for the
+preview CLI lane only. It does not close signed-installer, browser-store,
+high-risk desktop action, or autonomous local app production gates.
+
 Release operators can run `npm run guardian:release:doctor` from the repo root
 for the complete protected-release doctor before publishing. For a release
 candidate artifact, set `GUARDIAN_RELEASE_CANDIDATE=/path/to/artifact.zip` and
@@ -216,3 +283,14 @@ When an installed profile contains `release/release-evidence.json`,
 allowlist, source/source-map exclusions, unpublished workspace import boundary,
 and checksum manifest. `guardian status --json` surfaces the same
 metadata-only release-evidence state without printing runtime tokens.
+
+Before deciding whether a release is warranted, run
+`npm run guardian:release:change-summary -- --from=<previous-version-ref> --to=HEAD`
+(repo root, monorepo checkout only — the published CLI has no git history to
+read once installed). It reports the resolved `guardian-cli` version at each
+ref, the Guardian-relevant files and commits between them, any
+`release/evidence/` artifacts that changed, the current not-proven production
+gates, and recommended next steps. It is metadata-only: it never runs
+`npm publish` and never reads or prints npm tokens, OTP values, or `.npmrc`
+contents. Add `--json` for machine-readable output or `--output <path>` to
+write the report to a file.