@alphafox/cli 0.1.5 → 0.3.2

package/docs/logo/alphafox-mark.svg

@@ -0,0 +1,4 @@
+<svg width="880" height="1320" viewBox="560 400 880 1320" fill="none" xmlns="http://www.w3.org/2000/svg">
+<path d="M600 859.99V448.467C600 444.343 603.341 440.997 607.455 441.283C633.947 443.127 687.377 454.464 738.326 489.713C790.889 526.08 819.686 577.964 829.376 603.853C830.516 606.899 833.375 608.999 836.627 608.999H974.473C977.797 608.999 980.699 606.816 981.805 603.682C989.573 581.673 1012.28 537.164 1054.85 499.081C1097.95 460.53 1170.23 445.26 1207.73 441.629C1212.01 441.215 1215.61 444.632 1215.61 448.934V860.713C1215.61 864.837 1212.28 868.175 1208.15 868.278C1166.66 869.316 1082.4 878.881 1024.32 911.272C971.303 940.844 930.998 987.234 911.43 1015.2C907.935 1020.2 899.832 1019.72 896.775 1014.44C882.18 989.258 849.547 947.01 795.65 911.272C735.079 871.11 650.192 865.287 608.157 867.588C603.768 867.828 600 864.385 600 859.99Z" fill="#FF991F"/>
+<path d="M600.58 1235.01L600.58 969.867C600.58 965.744 603.924 962.4 608.047 962.458C675.284 963.412 740.225 977.952 799.655 1043.32C866.429 1116.76 897.008 1187.09 1027.44 1187.09L1133.53 1187.09C1290.79 1187.09 1400 1305.96 1400 1452.22L1400 1676.91C1400 1684.08 1391.55 1686.6 1387.59 1680.62C1357.88 1635.76 1286.34 1537.49 1154.22 1537.49L897.008 1537.49C718.527 1537.49 600.58 1420.82 600.58 1235.01Z" fill="#FF991F"/>
+</svg>

package/docs/logo/alphafox-wordmark-black-en.svg

@@ -0,0 +1,17 @@
+<svg width="2060" height="400" viewBox="600 300 2060 400" fill="none" xmlns="http://www.w3.org/2000/svg">
+<rect x="1048.72" y="319" width="278.736" height="43.8751" transform="rotate(90 1048.72 319)" fill="#151515"/>
+<path d="M2406.27 404.172H2461.76L2642.42 599.029H2586.93L2406.27 404.172Z" fill="#151515"/>
+<path d="M2517.25 540.964L2489.83 512.574L2404.98 599.034H2462.42L2517.25 540.964Z" fill="#151515"/>
+<path d="M2535.31 463.541L2567.57 498.383L2642.42 404.18H2584.98L2535.31 463.541Z" fill="#FF991F"/>
+<path d="M786.758 342.22C799.662 342.22 819.019 340.93 837.085 369.32C851.538 392.031 932.579 531.055 971.292 597.728H923.545C884.419 531.915 805.126 398.485 800.953 391.258C795.738 382.225 780.306 383.515 776.435 391.258C773.338 397.452 702.019 531.485 666.747 597.728H619C654.272 529.787 727.656 388.988 739.012 369.32C753.207 344.733 773.853 342.22 786.758 342.22ZM866.765 539.66H718.364L737.721 502.237H844.827L866.765 539.66Z" fill="#151515"/>
+<path d="M2318.52 404.168C2355.94 404.168 2388.2 440.3 2388.2 477.723V528.051C2388.2 570.635 2352.07 600.315 2318.52 600.315H2244.96C2206.25 600.315 2173.99 562.893 2173.99 528.051V477.723C2173.99 442.881 2207.54 404.168 2244.96 404.168H2318.52ZM2258.89 445.463C2235.9 445.463 2215.28 467.876 2215.28 488.048V517.185C2215.28 537.356 2235.1 559.022 2258.89 559.022H2304.09C2324.7 559.022 2346.91 541.839 2346.91 517.185V488.048C2346.91 466.382 2327.08 445.463 2304.09 445.463H2258.89Z" fill="#151515"/>
+<path d="M1846.21 448.056L1878.47 482.898L1942.37 401.788H1884.93L1846.21 448.056Z" fill="#FF991F"/>
+<path d="M1713.3 600.323H1761.04C1779.11 600.323 1797.5 591.005 1810.08 579.678C1822.99 568.064 1832.02 553.869 1842.34 538.384L1810.08 506.123C1807.5 511.284 1800.53 524.447 1793.31 535.803C1784.27 549.998 1763.62 559.029 1753.3 559.029H1724.91C1701.12 559.029 1681.04 537.362 1681.04 517.19V488.055C1681.04 467.883 1704.23 445.47 1727.23 445.47H1757.17C1770.08 445.47 1779.88 450.114 1788.14 458.374C1796.4 466.635 1876.75 555.589 1917.19 600.323H1971.39C1921.49 544.834 1822.73 437.213 1811.37 424.824C1792.45 404.175 1770.08 404.174 1741.69 404.177L1717.17 404.176C1679.75 404.176 1639.74 448.051 1639.74 482.893V525.478C1639.74 560.32 1674.58 600.323 1713.3 600.323Z" fill="#151515"/>
+<path d="M1345.52 475.149C1345.52 437.726 1313.26 401.594 1275.84 401.594H1202.28C1162.28 401.594 1118.4 435.145 1118.4 485.473V681.62H1162.28V485.473C1162.28 462.245 1182.92 442.888 1216.21 442.888H1261.41C1284.4 442.888 1304.23 463.807 1304.23 485.473V514.608C1304.23 539.263 1282.02 556.447 1261.41 556.447H1175.18V597.741H1275.84C1309.39 597.741 1345.52 568.061 1345.52 525.476V475.149Z" fill="#151515"/>
+<path d="M1438.43 414.505C1451.03 406.42 1466.16 401.592 1482.02 401.592H1514.57C1573.93 401.592 1603.61 445.467 1603.61 479.019V599.03H1561.77V494.504C1561.77 468.695 1545.54 442.887 1514.57 442.887H1482.02C1460.1 442.887 1438.5 462.415 1438.43 485.362V597.74H1394.56V319.004H1438.43V414.505Z" fill="#151515"/>
+<path d="M2013.97 413.201L2013.97 600.316L2055.26 600.316L2055.26 479.015L2146.89 479.015L2146.89 435.427L2055.26 435.427L2055.26 413.201C2055.26 382.23 2081.07 365.998 2106.88 365.998L2164.95 365.998L2164.95 324.16L2091.4 324.16C2057.85 324.16 2013.97 353.84 2013.97 413.201Z" fill="#151515"/>
+<path d="M211 426.942V261.467C211 257.343 214.343 254.022 218.433 254.554C230.549 256.131 250.514 261.414 269.653 274.655C290.113 288.811 302.081 308.512 307.084 320.14C308.37 323.127 311.228 325.235 314.48 325.235H366.551C369.875 325.235 372.785 323.037 374.049 319.963C378.161 309.963 387.59 293.188 403.866 278.628C420.524 263.726 447.466 257.028 464.142 254.794C468.406 254.223 472.03 257.632 472.03 261.934V427.665C472.03 431.789 468.694 435.129 464.576 435.338C445.93 436.283 413.682 440.709 390.921 453.404C372.313 463.782 357.399 479.045 348.107 490.722C344.31 495.493 335.784 495.048 332.272 490.063C324.84 479.511 312.305 465.568 293.959 453.404C270.37 437.762 238.082 434.404 219.165 434.717C214.77 434.789 211 431.337 211 426.942Z" fill="#FF991F"/>
+<path d="M211.247 590.674L211.247 482.54C211.247 478.416 214.591 475.066 218.712 475.215C245.69 476.188 271.727 483.073 295.658 509.393C323.971 540.533 336.937 570.354 392.241 570.354L437.225 570.354C503.907 570.354 550.215 620.759 550.215 682.776L550.215 747.65C550.215 754.821 541.259 757.744 536.525 752.358C523.226 737.231 501.546 718.93 471.36 718.93L336.937 718.93C261.258 718.93 211.247 669.463 211.247 590.674Z" fill="#FF991F"/>
+</svg>
+
+

package/docs/logo/alphafox-wordmark-white-en.svg

@@ -0,0 +1,16 @@
+<svg width="2060" height="400" viewBox="600 300 2060 400" fill="none" xmlns="http://www.w3.org/2000/svg">
+<rect x="1048.72" y="317.996" width="278.736" height="43.8751" transform="rotate(90 1048.72 317.996)" fill="white"/>
+<path d="M2406.27 403.168H2461.76L2642.42 598.025H2586.93L2406.27 403.168Z" fill="white"/>
+<path d="M2517.25 539.96L2489.83 511.57L2404.98 598.03H2462.42L2517.25 539.96Z" fill="white"/>
+<path d="M2535.31 462.537L2567.57 497.379L2642.42 403.176H2584.98L2535.31 462.537Z" fill="#FF991F"/>
+<path d="M786.758 341.216C799.662 341.216 819.019 339.926 837.085 368.316C851.538 391.027 932.578 530.052 971.291 596.725H923.545C884.419 530.912 805.125 397.481 800.953 390.254C795.738 381.221 780.306 382.512 776.435 390.254C773.337 396.448 702.018 530.482 666.746 596.725H619C654.272 528.784 727.656 387.985 739.012 368.316C753.207 343.729 773.853 341.216 786.758 341.216ZM866.765 538.656H718.363L737.721 501.234H844.827L866.765 538.656Z" fill="white"/>
+<path d="M2318.52 403.164C2355.94 403.164 2388.2 439.296 2388.2 476.719V527.047C2388.2 569.631 2352.07 599.311 2318.52 599.312H2244.96C2206.25 599.312 2173.99 561.889 2173.99 527.047V476.719C2173.99 441.877 2207.54 403.164 2244.96 403.164H2318.52ZM2258.89 444.459C2235.9 444.459 2215.28 466.872 2215.28 487.044V516.181C2215.28 536.352 2235.1 558.019 2258.89 558.019H2304.09C2324.7 558.019 2346.91 540.835 2346.91 516.181V487.044C2346.91 465.378 2327.08 444.459 2304.09 444.459H2258.89Z" fill="white"/>
+<path d="M1846.21 447.045L1878.47 481.887L1942.37 400.777H1884.93L1846.21 447.045Z" fill="#FF991F"/>
+<path d="M1713.3 599.312H1761.04C1779.11 599.312 1797.5 589.993 1810.08 578.666C1822.99 567.052 1832.02 552.857 1842.34 537.372L1810.08 505.111C1807.5 510.273 1800.53 523.435 1793.31 534.791C1784.27 548.986 1763.62 558.017 1753.3 558.017H1724.91C1701.12 558.017 1681.04 536.35 1681.04 516.179V487.043C1681.04 466.871 1704.23 444.459 1727.23 444.458H1757.17C1770.08 444.458 1779.88 449.102 1788.14 457.363C1796.4 465.623 1876.75 554.577 1917.19 599.312H1971.39C1921.49 543.822 1822.73 436.202 1811.37 423.812C1792.45 403.164 1770.08 403.163 1741.69 403.165L1717.17 403.164C1679.75 403.164 1639.74 447.039 1639.74 481.881V524.466C1639.74 559.308 1674.58 599.312 1713.3 599.312Z" fill="white"/>
+<path d="M1345.52 474.145C1345.52 436.722 1313.26 400.59 1275.84 400.59H1202.28C1162.28 400.59 1118.4 434.141 1118.4 484.469V680.616H1162.28V484.469C1162.28 461.241 1182.92 441.884 1216.21 441.884H1261.41C1284.4 441.884 1304.23 462.803 1304.23 484.469V513.605C1304.23 538.259 1282.02 555.443 1261.41 555.443H1175.18V596.737H1275.84C1309.39 596.737 1345.52 567.057 1345.52 524.473V474.145Z" fill="white"/>
+<path d="M1438.43 413.501C1451.03 405.416 1466.16 400.588 1482.02 400.588H1514.57C1573.93 400.588 1603.61 444.463 1603.61 478.015V598.026H1561.77V493.5C1561.77 467.691 1545.54 441.883 1514.57 441.883H1482.02C1460.09 441.883 1438.47 461.441 1438.43 484.412V596.736H1394.56V318H1438.43L1438.43 413.501Z" fill="white"/>
+<path d="M2013.97 412.197L2013.97 599.313L2055.26 599.313L2055.26 478.011L2146.89 478.011L2146.89 434.423L2055.26 434.423L2055.26 412.197C2055.26 381.226 2081.07 364.994 2106.88 364.994L2164.95 364.994L2164.95 323.156L2091.4 323.156C2057.85 323.156 2013.97 352.836 2013.97 412.197Z" fill="white"/>
+<path d="M211 426.942V261.467C211 257.343 214.343 254.022 218.433 254.554C230.549 256.131 250.514 261.414 269.653 274.655C290.113 288.811 302.081 308.512 307.084 320.14C308.37 323.127 311.228 325.235 314.48 325.235H366.551C369.875 325.235 372.785 323.037 374.049 319.963C378.161 309.963 387.59 293.188 403.866 278.628C420.524 263.726 447.466 257.028 464.142 254.794C468.406 254.223 472.03 257.632 472.03 261.934V427.665C472.03 431.789 468.694 435.129 464.576 435.338C445.93 436.283 413.682 440.709 390.921 453.404C372.313 463.782 357.399 479.045 348.107 490.722C344.31 495.493 335.784 495.048 332.272 490.063C324.84 479.511 312.305 465.568 293.959 453.404C270.37 437.762 238.082 434.404 219.165 434.717C214.77 434.789 211 431.337 211 426.942Z" fill="#FF991F"/>
+<path d="M211.247 590.674L211.247 482.54C211.247 478.416 214.591 475.066 218.712 475.215C245.69 476.188 271.727 483.073 295.658 509.393C323.971 540.533 336.937 570.354 392.241 570.354L437.225 570.354C503.907 570.354 550.215 620.759 550.215 682.776L550.215 747.65C550.215 754.821 541.259 757.744 536.525 752.358C523.226 737.231 501.546 718.93 471.36 718.93L336.937 718.93C261.258 718.93 211.247 669.463 211.247 590.674Z" fill="#FF991F"/>
+</svg>
+

package/docs/release-supply-chain.md

@@ -1,49 +1,130 @@
 # Release: npm, Skills, supply chain (t101375)
 
+**Status:** Frozen (G0)  
+**Date:** 2026-08-13  
+**Canonical package:** `@alphafox/cli` on the public npmjs.org registry.
+
+This document freezes distribution policy. It supersedes the earlier draft that
+named `@alphafoxai/cli` (that name was never published; npmjs returns 404).
+
 ## Package
 
-| Field | Value |
-|-------|--------|
-| Name | `@alphafoxai/cli` |
-| Binary | `alphafox` |
-| Visibility | public npm (org `@alphafoxai`) |
-| Node | LTS ≥ 20 |
-| OS | macOS, Linux, Windows |
+| Field | Frozen value |
+|-------|----------------|
+| Name | `@alphafox/cli` |
+| Binary | `alphafox` (`bin/alphafox.js`) |
+| Registry | `https://registry.npmjs.org/` |
+| Visibility | **public** (`publishConfig.access=public`) |
+| npm org / owner | `@alphafox` scope; maintainer `alphafox <joe@alphafox.app>` |
+| License | MIT |
+| Node | LTS **≥ 20** (`engines.node`) |
+| OS | macOS, Linux, Windows (npm install; no standalone native binary in v1) |
+| Package contents | `bin/`, `dist/`, `skills/`, `README.md`, `docs/`, `LICENSE` |
+
+v1 does **not** ship independent GitHub Release binaries, so there is no extra
+binary signing/checksum channel. Integrity is npm pack integrity plus
+provenance (below).
+
+Do **not** republish under `@alphafoxai/cli` without a new ADR. Skills and docs
+that still mention that name are stale and must follow this freeze.
 
-## Publish rules
+## Publish rules (normative)
 
-- Publish **only** from CI on protected tags (`v*`)
-- Prefer npm **trusted publishing / OIDC provenance** — no long-lived npm tokens
-- 2FA required for org owners
-- Package contents: `dist/`, `skills/`, README, docs — **no** secrets, fixtures, private endpoints, or `.env`
+1. Publish **only** from CI on a protected git tag matching `v*` (example:
+   `v0.2.0`). Humans must not `npm publish` from a laptop for any release
+   after this freeze, except an explicit incident rollback documented in the
+   change ticket.
+2. CI MUST use npm **trusted publishing / OIDC provenance**. Long-lived npm
+   tokens are forbidden for publish.
+3. npm org owners MUST have 2FA. Publish permission is CI identity plus owners;
+   no shared user tokens in git or chat.
+4. Package tarball MUST NOT contain secrets, test fixtures with credentials,
+   `.env`, private endpoints, or internal-only hostnames.
+5. `prepublishOnly` builds from the tagged SHA. The published `CLI_VERSION`
+   (or equivalent) MUST equal the npm version.
+
+### Grandfathered 0.1.x
+
+npmjs currently has `@alphafox/cli@0.1.0`–`0.1.5` (latest `0.1.5`). Those
+tarballs have registry signatures and **no** provenance attestations
+(`dist.attestations` is empty). They were published by the human npm user
+`alphafox`. They remain installable but are **not** the compliance target.
+The next minor/patch that this policy covers MUST be the first
+OIDC-provenance release.
 
 ## Skills distribution
 
-- Co-versioned inside the npm package under `skills/`
-- Compatibility: Skills major aligns with CLI major; `contractVersion` must match API or CLI fails closed
+- Skills ship **inside** the same npm tarball under `skills/` (co-versioned).
+- Skills major aligns with CLI major. There is no separate Skills registry
+  in v1 and no silent download of a different Skills version at runtime.
+- `npm install -g @alphafox/cli` places `skills/` next to the binary only.
+  Agents do not load that directory. `alphafox install` (and the Agent
+  install guide) copy those files into Agent skill dirs via
+  `npx skills add`:
+  1. the globally installed package path (co-versioned with the CLI)
+  2. the running package / checkout `skills/` tree
+  3. GitHub `alphafoxai/alphafox-cli` as a last-resort fallback
+- `contractVersion` on the CLI profile MUST match the Public API
+  `contractVersion` (or the documented compatible range). Mismatch → fail
+  closed; do not download an older contract or degrade quietly.
+
+## Compatibility / channels / deprecation
+
+| Channel | npm dist-tag | Meaning |
+|---------|--------------|---------|
+| stable | `latest` | Supported release |
+| prerelease | `next` | Opt-in only |
 
-## Support matrix
+- Breaking API/contract/minCLI/maxCLI changes: announce ≥ **30 days** before
+  `latest` moves; keep the previous compatible CLI installable on npm.
+- Incompatible CLI ↔ API ↔ contract: CLI exits non-zero with a machine-readable
+  error. No silent skip, no automatic down-version.
+- Emergency unpublish is a last resort (npm unpublish window). Preferred:
+  `npm deprecate @alphafox/cli@<bad> "<reason>; use <good>"` and tell
+  operators to install the last good version.
 
-| Platform | Install | Keychain |
-|----------|---------|----------|
-| macOS | npm global / npx | Keychain Access |
-| Linux | npm global / npx | Secret Service or file fallback 0600 |
-| Windows | npm global / npx | Credential Manager (file fallback until implemented) |
+## Support matrix (install / update / uninstall)
 
-## Channels
+| Platform | Install | Update | Uninstall | Secrets |
+|----------|---------|--------|-----------|---------|
+| macOS | `npm install -g @alphafox/cli` or `npx @alphafox/cli` | `npm update -g @alphafox/cli` or pin `@<version>` | `npm uninstall -g @alphafox/cli` | Keychain Access |
+| Linux | same | same | same | Secret Service, or file fallback mode `0600` |
+| Windows | same | same | same | Credential Manager (`CredWrite`/`CredRead`); file fallback mode `0600` if unavailable |
 
-- `latest` — stable
-- `next` — prerelease
-- Deprecation window: ≥ 30 days for breaking contract changes
+Fresh-machine acceptance (release checklist, not optional):
+
+```bash
+npm install -g @alphafox/cli@<version>
+npm view @alphafox/cli@<version> --json   # attestations present after first OIDC release
+alphafox version
+alphafox doctor
+alphafox schema me.whoami
+```
 
 ## Rollback
 
 ```bash
-npm install -g @alphafoxai/cli@<previous>
+npm install -g @alphafox/cli@<previous-compatible>
 alphafox version
 alphafox doctor
 ```
 
+Failed install leaves the previous global binary in place (npm does not
+half-replace). If `doctor` fails after a successful install, roll back with
+the command above. Do not point the CLI at a different environment to “make
+it work”.
+
 ## SBOM / audit
 
-CI should generate SBOM (e.g. `cyclonedx` / `npm sbom`) and fail on critical vulns in runtime deps.
+CI MUST emit an SBOM (CycloneDX from the pnpm production tree via
+`scripts/generate-sbom.mjs`) from the tagged SHA and fail the release job on
+**critical** vulnerabilities in **runtime** dependencies (`pnpm audit --prod`).
+Dev-only advisories do not block publish. SBOM is an artifact of the release
+workflow, not a file committed to `main` by default.
+
+## Out of scope (v1)
+
+- Private npm / GitHub Packages as the user install path
+- Homebrew / scoop / standalone signed binaries
+- Separate Skills marketplace
+- Automation-token distribution (ADR 0004)

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@alphafox/cli",
-  "version": "0.1.5",
-  "description": "Alphafox CLI \u2014 Agent/Human entry for the public Application API.",
+  "version": "0.3.2",
+  "description": "Alphafox CLI — Agent/Human entry for the public Application API.",
   "type": "commonjs",
   "bin": {
     "alphafox": "bin/alphafox.js"
@@ -12,14 +12,19 @@
     "bin",
     "dist",
     "skills",
+    "vendor",
     "README.md",
     "docs",
     "LICENSE"
   ],
   "scripts": {
     "build": "tsc -p tsconfig.build.json && node scripts/postbuild.cjs",
+    "generate:catalog": "node scripts/generate-catalog.mjs",
+    "check:catalog-drift": "node scripts/generate-catalog.mjs --check",
     "typecheck": "tsc -p tsconfig.json --noEmit",
-    "test": "npm run build && node scripts/build-mvp-web-bundle.mjs && tsc -p tsconfig.test.json && node --test dist-test/**/*.test.js",
+    "test": "npm run check:catalog-drift && npm run build && node scripts/build-mvp-web-bundle.mjs && tsc -p tsconfig.test.json && node --test dist-test/**/*.test.js",
+    "test:release": "npm run build && tsc -p tsconfig.test.json && node scripts/run-release-tests.mjs",
+    "sbom": "node scripts/generate-sbom.mjs",
     "test:mvp": "node scripts/build-mvp-web-bundle.mjs && tsc -p tsconfig.test.json && node --test dist-test/tests/mvp-oauth-web-handlers.test.js",
     "alphafox": "node dist/cli.js",
     "prepublishOnly": "npm run build"
@@ -50,6 +55,8 @@
   "license": "MIT",
   "packageManager": "pnpm@10.33.0",
   "dependencies": {
+    "ajv": "^8.20.0",
+    "ccxt": "^4.5.73",
     "zod": "^4.3.6"
   },
   "devDependencies": {

package/skills/account/SKILL.md

@@ -1,21 +1,23 @@
 ---
 name: alphafox-account
 description: Account, wallet, and subscription read paths.
-version: 0.1.0
+version: 0.3.2
 ---
 
 # Account / wallet
 
+Always `--format json --no-input`. These paths are read-first. Wallet mutations are write/high-risk — `alphafox schema` first (do not invent fields), `--dry-run` then `--yes`; never auto-retry. Large bodies: `--config @file`.
+
 ```bash
-alphafox api GET /api/v1/wallet
-alphafox api GET /api/v1/account/exchange-uids
-alphafox api GET /api/v1/subscriptions/me
-alphafox api GET /api/v1/managed-wallets
+alphafox api GET /api/v1/wallet --format json --no-input
+alphafox api GET /api/v1/account/exchange-uids --format json --no-input
+alphafox api GET /api/v1/subscriptions/me --format json --no-input
+alphafox api GET /api/v1/managed-wallets --format json --no-input
 ```
 
 ## operationIds
 
 - `wallet.get`
 - `account.exchange_uids.list`
-- `subscriptions.me.get`
+- `subscriptions.me.get` (facade `GET /api/v1/subscriptions/me`)
 - `managed_wallets.list`

package/skills/admin/SKILL.md

@@ -1,18 +1,23 @@
 ---
 name: alphafox-admin
 description: Admin-only operations reusing Web role authorization.
-version: 0.1.0
+version: 0.3.2
 ---
 
 # Admin
 
-Requires admin role on the server. CLI confirmation does not grant privilege.
+Requires admin role on the server. CLI confirmation does not grant privilege. Not available to automation (v1 deferred). Always `--format json --no-input`.
 
 ```bash
-alphafox api GET /api/v1/admin/users
+alphafox api GET /api/v1/admin/users --format json --no-input
 ```
 
-High-risk admin writes: `--dry-run` then `--yes`. Not available to automation (v1 deferred).
+High-risk admin writes: `alphafox schema <operationId>` first, then `--dry-run` then `--yes`. Body fields must come from that schema; use `--config @file` for large objects. If the operator is not admin, expect `403` and stop.
+
+## Recovery
+
+- `401`: re-auth. `403`: not admin — do not escalate by switching profiles.
+- Uncataloged admin POST/PATCH/DELETE still require `--yes` (unknown risk).
 
 ## operationIds
 

package/skills/alphafox-shared/SKILL.md

@@ -1,20 +1,29 @@
 ---
 name: alphafox-shared
 description: Shared Alphafox CLI rules for Agents — auth, profiles, envelopes, risk gates, and public operationIds only.
-version: 0.1.0
+version: 0.3.2
 ---
 
 # Alphafox shared Agent contract
 
+Co-versioned with `@alphafox/cli`. Query compatibility with `alphafox version --format json` (`version`, `contractVersion`, `catalogVersion`) and `alphafox catalog`.
+
 ## Install / identity
 
+Prefer the wizard (CLI + Agent Skills) or the Agent install guide. Do not treat
+`npm install -g @alphafox/cli` as enough for Agents — Skills must be registered
+with `npx skills add`.
+
 ```bash
-npx @alphafoxai/cli version
-npx @alphafoxai/cli doctor
+npx @alphafox/cli@latest install
+# Agent playbook:
+# https://github.com/alphafoxai/alphafox-cli/blob/main/docs/alphafox-cli-installation-guide.md
+npx @alphafox/cli version --format json --no-input
+npx @alphafox/cli doctor --format json --no-input
 ```
 
 - Default profile: `production`. Use `--profile staging|local` explicitly.
-- Tokens: OS keychain only. Never pass `--token`. Never read tokens from config JSON.
+- Tokens: OS keychain only (macOS Keychain, Linux Secret Service, Windows Credential Manager). Never pass `--token`. Never read tokens from config JSON.
 - Automation tokens are **not supported in v1** (interactive Device Flow / PKCE only).
 
 ## Output
@@ -25,35 +34,56 @@ Always use:
 alphafox … --format json --no-input
 ```
 
-Parse the JSON envelope: `ok === true` for success. Errors land on **stderr** with `ok: false` and may include HTTP `status` + `requestId`.
+Optional: `--jq '<filter>'` requires the `jq` binary; missing jq fails closed (does not print the unfiltered envelope).
+
+Parse the JSON envelope: `ok === true` for success. Errors land on **stderr** with `ok: false` and may include HTTP `status` + `requestId`. Stream watch uses JSONL. Do not parse human tables.
 
 ## Auth
 
 ```bash
-alphafox auth login --no-wait
-# show verification_uri to the user, then:
-alphafox auth login --device-code <device_code>
-alphafox auth status --verify
-alphafox whoami
+alphafox auth login --no-wait --format json --no-input
+# show verification_uri / user_code to the human, then:
+alphafox auth login --device-code <device_code> --format json --no-input
+alphafox auth status --verify --format json --no-input
+alphafox whoami --format json --no-input
 ```
 
+Local browser: `alphafox auth login --browser --format json --no-input` (loopback 127.0.0.1). If the browser cannot open, copy `authorizeUrl` from the error; do not invent a Device Flow retry unless the operator is headless.
+
+Wrong environment / missing permission / missing `--yes`: stop. Do not retry with a different profile.
+
 ## Commands
 
 1. Prefer typed catalog: `alphafox schema <operationId>` then invoke domain commands.
 2. Raw escape hatch only for allowlisted facade:
 
 ```bash
-alphafox api GET /api/v1/me
+alphafox api GET /api/v1/me --format json --no-input
 ```
 
-Forbidden: `/backend`, `/control-plane`, `/signal-center`, internal secrets, non-`/api/v1` product routes.
+Forbidden: `/backend`, `/control-plane`, `/signal-center`, internal secrets, non-`/api/v1` product routes, `--token`.
+
+## Writes — schema first, never invent fields
+
+Before every write (`POST` / `PUT` / `PATCH` / `DELETE` with a body):
+
+1. Run `alphafox schema <operationId> --format json --no-input`.
+2. Build the body **only** from `request.body` (property names, types, enums, required). Do not guess fields from memory, from another operationId, or from training data.
+3. Small object: typed command + `--body '<json>'`.
+4. Nested / large object: write a JSON file, then `--config @./payload.json`. Do not paste 20+ fields onto argv.
+5. `--dry-run` first when the risk is `write` or `high-risk-write`.
+
+CLI validates `--body` / `--config` against the catalog **before** HTTP. `body_schema` / `body_schema_missing` (exit `64`) means the payload is wrong — re-read `schema`, do not add extra keys to “make it work”. `--body` and `--config` cannot be combined. `--body @file` is also a file (same as `--config @file`).
+
+Uncataloged writes cannot carry a non-empty body. Find the `operationId` first.
 
 ## Risk
 
-- `high-risk-write` requires `--yes` (exit code `10` if missing).
+- `high-risk-write` and uncataloged mutations (`unknown`) require `--yes` (exit code `10` if missing).
 - Prefer `--dry-run` first for trader start/stop, withdrawals, admin writes.
 - Never auto-retry unknown write outcomes.
+- CLI `--yes` is UX only; the server still enforces role, ownership, and scopes.
 
 ## Public operationIds only
 
-Skills must reference registry `operationId`s (see `alphafox schema` / `alphafox catalog`). Do not hardcode internal service URLs.
+Skills must reference registry `operationId`s (see `alphafox schema` / `alphafox catalog`). Shortcuts may only compose those operationIds. Do not hardcode internal service URLs or invent a second catalog.

package/skills/auth/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: alphafox-auth
 description: Login, status, logout, whoami, and environment isolation for Alphafox CLI.
-version: 0.1.0
+version: 0.3.2
 ---
 
 # Auth Skill
@@ -10,24 +10,39 @@ version: 0.1.0
 
 User needs to sign in, verify session, switch profile, or revoke tokens.
 
+Always `--format json --no-input`. Never `--token`.
+
 ## Workflows
 
 ### Device Flow (headless / Agent)
 
-1. `alphafox auth login --no-wait --format json`
+1. `alphafox auth login --no-wait --format json --no-input`
 2. Present `verification_uri` / `user_code` to the human.
-3. After approval: `alphafox auth login --device-code <device_code>`
-4. `alphafox whoami` / `alphafox auth status --verify`
+3. After approval: `alphafox auth login --device-code <device_code> --format json --no-input`
+4. `alphafox whoami --format json --no-input` / `alphafox auth status --verify --format json --no-input`
+
+### Browser loopback (human, local machine)
+
+1. `alphafox auth login --browser --format json --no-input`
+2. CLI binds `127.0.0.1` and opens the system browser. Do not copy codes or verifiers.
+3. After the localhost callback, `alphafox whoami` / `alphafox auth status --verify`
+4. If the browser cannot open, the error includes a copyable `authorizeUrl`. Do not retry as Device Flow unless the human is headless.
 
 ### Status / logout
 
-- `alphafox auth status --verify`
-- `alphafox auth logout` (server revoke + local keychain clear)
+- `alphafox auth status --verify --format json --no-input`
+- `alphafox auth logout --format json --no-input` (server revoke + local keychain clear). If `remoteRevoke` is `failed`, local tokens are still cleared but exit is non-zero — do not claim a full logout.
+
+### Recovery
+
+- `401` / `expired_token`: re-run Device Flow or browser login. Do not reuse a token from another profile.
+- Cross-env: production tokens are rejected on staging/local. Switch `--profile` only with explicit operator intent.
 
 ## Safety
 
 - Fail closed on cross-environment tokens (prod token never hits staging).
 - Do not copy refresh tokens into CI (automation deferred — ADR 0004).
+- Scopes: `openid` `profile` `offline_access` at grant time.
 
 ## operationIds
 

package/skills/engine-backtest/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: alphafox-engine-backtest
+description: Local Engine WASM backtest (alphafox engine-backtest run) vs catalog experiment CRUD vs chat backtests stub.
+version: 0.3.2
+---
+
+# Engine Backtest
+
+Always `--format json --no-input` (or `--format jsonl` when you need progress). Never `--token`. Tokens live in the OS keychain via `alphafox auth login`.
+
+## Which command
+
+| Intent | Use | Do not |
+|---|---|---|
+| Iterate a strategy locally (pull tape + run wasm + optional persist) | `alphafox engine-backtest run` (hyphen, built-in) | Do not treat this as server-side execution of `engine_backtest.experiments.byId.runs.create` |
+| List / get / create / rename / delete experiments and persisted runs | Catalog `engine_backtest.*` (underscore) | Do not invent a second catalog |
+| Chat-attached `/api/v1/backtests` job | `skills/strategy` + `backtests.*` | That stub is **not** the Engine WASM runner |
+
+Read the create-experiment body with `alphafox schema` **before** composing JSON. Do not invent experiment fields. Large create/run payloads use `--config @file`, never a guessed `--body`.
+
+```bash
+alphafox schema engine_backtest.experiments.create --format json --no-input
+alphafox engine_backtest experiments create --config @./experiment.json --format json --no-input
+```
+
+## Local run
+
+The tape runner ships inside the CLI (plus `ccxt` for public-market pulls). The wasm / Node host is downloaded from the public Vercel Blob manifest (`engine-backtest/latest.json`) into `~/.cache/alphafox/engine-backtest/<hash>/` on first run.
+
+Local overrides, in order:
+
+1. `ALPHAFOX_BACKTEST_WASM_DIR` / `ALPHAFOX_BACKTEST_RUNNER_DIR`
+2. `ALPHAFOX_ENGINE_ROOT` + `/npm/backtest-wasm` or `/npm/backtest-runner`
+3. Sibling `../alphafox-engine/npm/...` only when `ALPHAFOX_USE_LOCAL_BACKTEST=1`
+
+Do not install `@alphafoxai/backtest-wasm` or `@alphafoxai/backtest-runner` from GitHub Packages.
+
+```bash
+alphafox engine-backtest run \
+  --experiment <uuid> \
+  --definition grid \
+  --config @./grid.json \
+  --exchange binance \
+  --range 2026-08-01..2026-08-08 \
+  --initial-equity 10000 \
+  --format jsonl --no-input
+```
+
+Also valid: `--from` / `--to` instead of `--range`. `--create-experiment --name "..."` when there is no `--experiment` (needs `strategyDefinitionId` + `strategyDefinitionDisplay` `{zh,en}`; pass `--definition-label-zh` / `--definition-label-en` or the CLI falls back to the definition id). Persisted runs use the account tier from `subscriptions.me.get`; if `--tier` is supplied, it must match. With `--no-persist`, `runs.create` is skipped and `--tier` may simulate `free|pro|pro_max` (default `pro`). `--data-quality` defaults to `strict`. `--replay-timeframe` defaults to `1m` (allowed `1m|3m|5m|15m|30m|1h|4h`); this is the replay/download bar and is merged with plan indicator timeframes so a 4h RSI grid still replays on 1m. `runs.create` is `write`, not `high-risk-write` — do not add `--yes`. Do not update or delete experiments through this command.
+
+`--format jsonl` writes one JSON object per progress line (`{event:"progress",stage,fraction}`), then a final `{ok:true,data:{...}}` envelope.
+
+## Iterate
+
+1. Edit config JSON.
+2. `engine-backtest run` (reuse `--experiment` after the first create).
+3. Read `data.metrics` / `data.engineVersion` / `data.runId` / `data.experimentUrl`.
+4. Adjust parameters and run again. Do not invent a token flag if persist returns 401 — `alphafox auth login`.
+
+## Safety
+
+- Unauthenticated persist/create fails like `whoami` (HTTP 401, exit 77).
+- `strict` data quality: missing/gapped tape **stops**. Do not retry as `basic` unless the operator asks.
+- `planBacktest` unsupported → fail with the plan reason. Do not degrade to a guessed universe.
+- Catalog `engine_backtest.experiments.byId.update` / `.delete` are high-risk-write and are **not** this command.
+
+## operationIds (catalog only)
+
+- `engine_backtest.experiments.create` / `.list` / `.byId.get`
+- `engine_backtest.experiments.byId.runs.create` / `.list`
+- High-risk (not this skill's run path): `engine_backtest.experiments.byId.update` / `.byId.delete` / `.byId.runs.byId.delete`

package/skills/exchange/SKILL.md

@@ -1,16 +1,23 @@
 ---
 name: alphafox-exchange
 description: Exchange connectors list and connection management via Public API.
-version: 0.1.0
+version: 0.3.2
 ---
 
 # Exchange connectors
 
+Always `--format json --no-input`. List is `exchange-connectors:read`.
+
 ```bash
-alphafox api GET /api/v1/exchange-connectors
+alphafox api GET /api/v1/exchange-connectors --format json --no-input
 ```
 
-Writes that create/disable connectors may be `high-risk-write` — use `--dry-run` / `--yes`.
+Writes that create/disable connectors may be `high-risk-write` — `alphafox schema` first, then `--dry-run` / `--yes`. Do not invent connector fields; large bodies use `--config @file`. Uncataloged connector POST cannot carry a non-empty body.
+
+## Recovery
+
+- `403` / wrong resource: stop. Do not retry with production tokens on staging.
+- Never log connector secrets from request bodies.
 
 ## operationIds
 

package/skills/market/SKILL.md

@@ -1,14 +1,19 @@
 ---
 name: alphafox-market
 description: Market data and spread-radar readonly queries.
-version: 0.1.0
+version: 0.3.2
 ---
 
 # Market
 
+Always `--format json --no-input`. Prefer readonly scopes. No mock success if upstream fails.
+
 ```bash
-alphafox api GET /api/v1/market/symbols
-alphafox api GET /api/v1/spread-radar/pairs
+alphafox api GET /api/v1/spread-radar/pairs --format json --no-input
+alphafox api GET /api/v1/market/symbols --format json --no-input
 ```
 
-Prefer readonly scopes. No mock success if upstream fails.
+## operationIds
+
+- `spread_radar.pairs.list`
+- `market.symbols.list`

package/skills/notification/SKILL.md

@@ -1,16 +1,21 @@
 ---
 name: alphafox-notification
 description: Notification channels and subscriptions.
-version: 0.1.0
+version: 0.3.2
 ---
 
 # Notification
 
+Always `--format json --no-input`. List is `notification:read`. Channel create/replace/delete may be write or high-risk — `alphafox schema` first (no invented fields), then `--dry-run` / `--yes`. Large bodies: `--config @file`.
+
 ```bash
-alphafox api GET /api/v1/notification/channels
-alphafox api GET /api/v1/notification/subscriptions
+alphafox api GET /api/v1/notification/channels --format json --no-input
+alphafox api GET /api/v1/notification/subscriptions --format json --no-input
 ```
 
+If a path is not allowlisted, stop with the structured error. Do not call notification internals.
+
 ## operationIds
 
 - `notification.channels.list`
+- `notification.subscriptions.list`