wicked-vault 0.2.1 → 0.3.0

package/README.md

@@ -51,14 +51,20 @@ config root (Claude Code, Gemini, Copilot, Codex, Cursor, Kiro, Antigravity):
 npx wicked-vault-install               # detect and install everywhere
 npx wicked-vault-install --cli=claude  # one CLI only (comma-separated for several)
 npx wicked-vault-install --path ~/.claude   # a specific config root
+npx wicked-vault-install --help        # options
 ```
 
 This mirrors the shared wicked-bus / wicked-brain installer: `$CLAUDE_CONFIG_DIR`
 is honored, alt-config layouts are probed, and skills land as
-`wicked-vault-{init,record-evidence,verify-evidence,analyze-evidence,cross-check-evidence}/`
+`wicked-vault-{init,record-evidence,verify-evidence,analyze-evidence,cross-check-evidence,update}/`
 under each CLI's `skills/`. If wicked-bus is installed, the installer also
 registers the vault as a bus provider (see below).
 
+**Updating:** say `wicked-vault:update` to your agent, or run
+`npm install -g wicked-vault@latest && npx wicked-vault-install` — it compares
+your version against npm and refreshes the skills across every CLI. Both
+binaries support `--help`.
+
 ## CLI
 
 ```bash
@@ -177,8 +183,9 @@ bash test/bus-integration.sh  # graceful no-op + schema validity + real-bus emis
 `attestation.sh` and `bus-integration.sh` are the gating proofs and run in CI
 (`.github/workflows/ci.yml`) on ubuntu + macos, with a Windows CLI smoke.
 
-Status: v0.2.1 — deterministic core proven on real repos; criteria-binding +
+Status: v0.3.0 — deterministic core proven on real repos; criteria-binding +
 independent judgment tier (ADR-0002, council 5–0) implemented and proven;
 wicked-bus integration **proven end-to-end against a real bus** (emit → store →
-poll), optional and fire-and-forget. Not yet implemented:
+poll), optional and fire-and-forget; `--help` on both binaries + a
+`wicked-vault:update` skill. Not yet implemented:
 `pr_check_status`/`http_status_eq` and the sqlite query cache.

package/bin/wicked-vault.mjs

@@ -33,7 +33,53 @@ function emit(obj, ok) {
   process.exit(ok ? 0 : 1);
 }
 
+const HELP = `wicked-vault — local-first evidence primitive
+Record evidence with the acceptance criteria it must clear, re-derive integrity
+deterministically, and record independent third-party judgments. Never trusts a
+stored verdict; never lets work self-grade its own "done".
+
+USAGE
+  wicked-vault <command> [options]
+
+COMMANDS
+  init                         Create .wicked-vault/ in the current repo
+  record                       Capture evidence + the criteria it must clear
+                               --scope S --phase P --claim C --kind K --source "<cmd|file>"
+                               --criteria "<text|@file>" (--run | --artifact <file>) [--verifier "kind:arg"]
+  verify   <artifact-id>       Integrity tier: re-derive hashes + verifier (deterministic,
+                               model-free). Exit 0 iff intact AND pass. Surfaces latest opinion.
+  inspect  <artifact-id>       Frozen criteria + evidence + integrity (what a judge evaluates)
+  attest   <artifact-id>       Record an INDEPENDENT judgment (fail-closed; evaluator != creator)
+                               --opinion <pass|reject|unclear> --rationale "..." --evaluator ID
+                               [--model prov/ver] [--prompt-hash H] [--sampling '<json>']
+  attestations <artifact-id>   Show the append-only opinion log
+  cross-check                  Mechanical contract verdict; exit 0 iff PASS
+                               --scope S --phase P [--integrity-only (default) | --with-attestations]
+  declare-contract             Pin a contract  --scope S --phase P --spec <file>
+  supersede <old-id>           Append-only replacement (same flags as record)
+  list                         --scope S [--phase P]
+
+GLOBAL
+  --cwd <dir>     Operate on a vault rooted at <dir> (default: walk up from cwd)
+  --help, -h      Show this help
+
+OUTPUT   JSON on stdout; exit code is the gate signal (0 = PASS / success).
+ENV      WICKED_VAULT_NO_BUS=1   Disable optional wicked-bus event emission
+
+Skills (AI CLIs):  wicked-vault:{init,record-evidence,verify-evidence,analyze-evidence,cross-check-evidence,update}
+Install skills:    npx wicked-vault-install        (run with --help for options)
+Docs:              https://github.com/mikeparcewski/wicked-vault
+`;
+
 const [cmd, ...rest] = process.argv.slice(2);
+
+// Help / no-command: print usage to stdout and exit 0 — before any vault or bus
+// work, so `--help` works outside a repo and never errors.
+if (cmd === undefined || cmd === '--help' || cmd === '-h' || cmd === 'help') {
+  process.stdout.write(HELP);
+  process.exit(0);
+}
+
 const args = parseArgs(rest);
 const cwd = (typeof args.cwd === 'string' && args.cwd) || process.cwd();
 

package/install.mjs

@@ -64,10 +64,41 @@ const CLI_TARGETS = [
   { name: "antigravity", dir: join(home, ".antigravity", "skills"), platform: "antigravity" },
 ];
 
-console.log("wicked-vault installer\n");
-
 const args = argv.slice(2);
 
+// Help: print usage and exit 0 before doing any detection or filesystem work.
+if (args.includes("--help") || args.includes("-h")) {
+  process.stdout.write(`wicked-vault-install — install wicked-vault skills into your AI CLIs/IDEs
+
+Copies the wicked-vault skills into every detected CLI config root so your
+agent knows how to use the vault. Also registers wicked-vault as a wicked-bus
+provider when the bus is available.
+
+USAGE
+  npx wicked-vault-install [options]
+
+OPTIONS
+  (no options)        Detect and install into every supported CLI found
+  --cli=<name>        Install into one CLI only (comma-separated for several),
+                      e.g. --cli=claude  or  --cli=claude,cursor
+  --path=<dir>        Install into a specific config root, e.g. --path=~/.claude
+  --help, -h          Show this help
+
+SUPPORTED CLIs       claude, gemini, copilot, codex, cursor, kiro, antigravity
+                     (\$CLAUDE_CONFIG_DIR is honored; alt-config layouts are probed)
+
+INSTALLS (per CLI, under skills/)
+  wicked-vault-init · -record-evidence · -verify-evidence · -analyze-evidence
+  · -cross-check-evidence · -update
+
+To update later:  npm install -g wicked-vault@latest && npx wicked-vault-install
+                  (or just say "wicked-vault:update" to your agent)
+`);
+  process.exit(0);
+}
+
+console.log("wicked-vault installer\n");
+
 // Flag parser supporting both --flag=value and --flag value forms, plus
 // narrow string-boolean coercion ("true" / "false" → booleans). The ad-hoc
 // parser this replaces silently dropped space-separated values — same bug

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wicked-vault",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "Local-first evidence primitive — record evidence with its acceptance criteria, re-derive integrity deterministically, and record independent third-party judgments. Never trusts a stored verdict, never lets work self-grade its own \"done\".",
   "type": "module",
   "bin": {

package/skills/wicked-vault/update/SKILL.md

@@ -0,0 +1,140 @@
+---
+name: wicked-vault:update
+description: |
+  Check for and install wicked-vault updates. Compares the installed version
+  against the npm registry, updates the published CLI, and refreshes the skills
+  across all detected AI CLIs (Claude Code, Gemini, Copilot, Codex, Cursor,
+  Kiro, Antigravity).
+
+  Use when: "update wicked-vault", "check for vault updates", "wicked-vault update",
+  or periodically to stay current.
+---
+
+# wicked-vault:update
+
+Check for and install updates to wicked-vault and its skills.
+
+## Cross-Platform Notes
+
+Commands work on macOS, Linux, and Windows. Prefer agent-native tools
+(Read, Write, Grep, Glob) over shell where possible. JSON parsing uses
+`python3 … || python …` so it runs on macOS, Linux, WSL, and Git Bash.
+
+## When to use
+
+- User asks to update or check for updates.
+- After unexpected behavior that might be fixed in a newer version.
+- Periodically (suggest checking monthly).
+
+## Process
+
+### Step 1 — Check the installed version
+
+Global install:
+
+```bash
+npm list -g wicked-vault --json 2>/dev/null | python3 -c "
+import json, sys
+try:
+    d = json.load(sys.stdin)
+    print(d.get('dependencies', {}).get('wicked-vault', {}).get('version', 'not installed'))
+except Exception:
+    print('not installed')
+" 2>/dev/null || npm list -g wicked-vault --json 2>/dev/null | python -c "
+import json, sys
+try:
+    d = json.load(sys.stdin)
+    print(d.get('dependencies', {}).get('wicked-vault', {}).get('version', 'not installed'))
+except Exception:
+    print('not installed')
+"
+```
+
+Also check a local (project-level) install:
+
+```bash
+npm list wicked-vault --json 2>/dev/null
+```
+
+If neither is installed, the user may be running via `npx wicked-vault@latest`
+(always current) — note that and skip to Step 5 to (re)install skills.
+
+### Step 2 — Check the latest version on npm
+
+```bash
+npm view wicked-vault version 2>/dev/null
+```
+
+### Step 3 — Compare
+
+- Up to date: "wicked-vault is up to date (v{version})."
+- Update available: "wicked-vault v{new} is available (you have v{current}). Update now?"
+
+If the user only wanted to check, stop here and report current vs. available.
+
+### Step 4 — Update the package (if approved)
+
+Global:
+
+```bash
+npm install -g wicked-vault@latest 2>&1
+```
+
+Local (project):
+
+```bash
+npm install wicked-vault@latest 2>&1
+```
+
+If `EACCES` / permission denied:
+- macOS/Linux: `sudo npm install -g wicked-vault@latest`
+- Windows: re-run the shell as Administrator
+- Report the failure — do NOT silently skip.
+
+### Step 5 — Refresh the skills in all CLIs
+
+After updating the package, re-run the installer to copy the updated skills
+into every detected CLI:
+
+```bash
+npx wicked-vault-install
+```
+
+Or target one CLI:
+
+```bash
+npx wicked-vault-install --cli=claude
+```
+
+(The installer is idempotent — re-running overwrites the installed skills with
+the current version and re-registers the wicked-bus provider if the bus is
+present.)
+
+### Step 6 — Verify
+
+Re-run the Step 1 version check and confirm it matches latest. Also confirm the
+CLI runs:
+
+```bash
+npx wicked-vault --help | head -1
+```
+
+If it still shows the old version:
+1. `which wicked-vault` (macOS/Linux) or `where wicked-vault` (Windows).
+2. `npm cache clean --force`.
+3. Check whether nvm / fnm / volta is pinning a stale copy.
+
+### Step 7 — Report
+
+```
+wicked-vault updated: v{old} → v{new}
+Skills refreshed in {N} CLIs: {list}
+```
+
+## Notes
+
+- wicked-vault has **no background server** to update (unlike wicked-brain) —
+  updating is just the package + the skills.
+- The published package is provenance-signed; `npm view wicked-vault --json`
+  shows the attestation under `dist.attestations` if you want to confirm
+  supply-chain integrity after updating.