@peac/cli 0.12.5 → 0.12.6

package/README.md

@@ -1,28 +1,66 @@
 # @peac/cli
 
-PEAC protocol command-line tools.
+PEAC protocol command-line tools for receipt verification, decoding, policy management, conformance testing, and evidence reconciliation.
 
 ## Installation
 
 ```bash
 pnpm add -g @peac/cli
-# or
-npx @peac/cli
 ```
 
-## Commands
+Or run directly without installing:
 
-### `peac verify <receipt>`
+```bash
+npx @peac/cli verify <receipt.jws>
+```
+
+## What It Does
+
+`@peac/cli` provides the `peac` command for working with signed interaction receipts from the terminal. It supports verifying receipt signatures, decoding receipt contents, validating issuer configurations, managing policies, running conformance test suites, generating sample receipts, and reconciling evidence bundles.
+
+## How Do I Use It?
+
+### Verify a receipt
+
+```bash
+peac verify <jws>
+peac verify receipt.jws --verbose
+```
 
-Verify a PEAC receipt (JWS compact serialization).
+Decodes the receipt, displays claims (issuer, audience, amount, payment rail), and verifies the cryptographic signature. Exit code 0 on success, 1 on failure.
+
+### Decode a receipt without verification
 
 ```bash
-peac verify eyJhbGciOiJFZERTQSIs...
+peac decode <jws>
+peac decode receipt.jws --json
 ```
 
-### `peac conformance run`
+Parses and displays the JWS header and claims payload without checking the signature. Use `--json` for machine-readable output.
 
-Run conformance tests against PEAC schema validators.
+### Validate an issuer configuration
+
+```bash
+peac validate-issuer path/to/peac-issuer.json
+peac validate-issuer https://example.com
+```
+
+Validates a `peac-issuer.json` file or fetches and validates one from an issuer URL. Displays issuer metadata including JWKS URI, supported algorithms, and payment rails.
+
+### Policy management
+
+```bash
+peac policy init                  # Create a new policy file
+peac policy validate policy.yaml  # Validate policy syntax
+peac policy explain policy.yaml   # Debug rule matching
+peac policy generate policy.yaml  # Compile to deployment artifacts
+peac policy list-profiles         # List available policy profiles
+peac policy show-profile <name>   # Show profile details
+```
+
+Use `--json` for machine-readable output, `--yes` to skip prompts, `--strict` to exit non-zero on warnings.
+
+### Run conformance tests
 
 ```bash
 peac conformance run                          # Standard level, text output
@@ -33,57 +71,45 @@ peac conformance run --category claims        # Filter by category
 peac conformance run --fixtures ./my-vectors  # Custom fixtures path
 ```
 
-**Options:**
-
-| Option       | Default    | Description                                              |
-| ------------ | ---------- | -------------------------------------------------------- |
-| `--level`    | `standard` | Conformance level: `basic`, `standard`, `full`           |
-| `--output`   | `text`     | Output format: `text`, `json`, `markdown`                |
-| `--category` | all        | Filter by category (e.g., `claims`, `signature`, `time`) |
-| `--fixtures` | built-in   | Path to custom conformance fixtures                      |
-| `--verbose`  | `false`    | Show detailed test output                                |
-
-### `peac conformance list`
-
-List available conformance test fixtures.
+### List conformance fixtures
 
 ```bash
 peac conformance list
 peac conformance list --category claims
 ```
 
-### `peac samples list`
-
-List available sample receipts.
+### Reconcile evidence bundles
 
 ```bash
-peac samples list
-peac samples list --category valid
+peac reconcile <bundle-a.json> <bundle-b.json>
 ```
 
-### `peac samples show <id>`
+Merges two evidence bundles and detects conflicts using composite `(iss, jti)` keys with fallback resolution. Conflicts are surfaced for human decision; no auto-resolution.
 
-Display details of a specific sample receipt.
+### Generate sample receipts
 
 ```bash
-peac samples show basic-receipt
+peac samples list                       # List available samples
+peac samples show basic-receipt         # Show a specific sample
+peac samples generate --output ./out    # Generate sample files
 ```
 
-### `peac samples generate`
+## Integrates With
 
-Generate sample receipt files.
+- `@peac/protocol` (Layer 3): Receipt verification and issuance
+- `@peac/crypto` (Layer 2): JWS decoding and signature operations
+- `@peac/schema` (Layer 1): Receipt schema validation
+- `@peac/audit`: Evidence bundle reading for reconciliation
+- `@peac/disc`: Issuer discovery
+- `@peac/policy-kit`: Policy loading, validation, and compilation
 
-```bash
-peac samples generate --output ./samples
-peac samples generate --format json
-```
+## For Agent Developers
+
+If you are building AI agents that produce or consume signed receipts, the CLI is useful for inspecting receipts during development and debugging. For programmatic integration, use `@peac/protocol` directly. For MCP-based tool integration, use [`@peac/mcp-server`](https://www.npmjs.com/package/@peac/mcp-server).
 
-**Options:**
+## For Operators
 
-| Option     | Default  | Description                          |
-| ---------- | -------- | ------------------------------------ |
-| `--output` | `stdout` | Output directory for generated files |
-| `--format` | `jws`    | Format: `jws`, `json`                |
+The CLI supports operator workflows including policy authoring (`peac policy init`), issuer configuration validation (`peac validate-issuer`), conformance testing (`peac conformance run`), and evidence reconciliation (`peac reconcile`). Use `--json` flags for integration with CI pipelines and monitoring systems.
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@peac/cli",
-  "version": "0.12.5",
+  "version": "0.12.6",
   "description": "PEAC protocol command-line tools",
   "main": "dist/index.cjs",
   "types": "dist/index.d.ts",
@@ -9,10 +9,10 @@
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/peacprotocol/peac.git",
+    "url": "git+https://github.com/peacprotocol/peac.git",
     "directory": "packages/cli"
   },
-  "author": "jithinraj <7850727+jithinraj@users.noreply.github.com>",
+  "author": "PEAC Protocol Contributors",
   "license": "Apache-2.0",
   "bugs": {
     "url": "https://github.com/peacprotocol/peac/issues"
@@ -38,12 +38,12 @@
   "dependencies": {
     "chalk": "^4.1.2",
     "commander": "^11.0.0",
-    "@peac/audit": "0.12.5",
-    "@peac/crypto": "0.12.5",
-    "@peac/disc": "0.12.5",
-    "@peac/policy-kit": "0.12.5",
-    "@peac/protocol": "0.12.5",
-    "@peac/schema": "0.12.5"
+    "@peac/audit": "0.12.6",
+    "@peac/disc": "0.12.6",
+    "@peac/policy-kit": "0.12.6",
+    "@peac/protocol": "0.12.6",
+    "@peac/crypto": "0.12.6",
+    "@peac/schema": "0.12.6"
   },
   "devDependencies": {
     "@types/node": "^22.19.11",
@@ -51,6 +51,19 @@
     "vitest": "^4.0.0",
     "tsup": "^8.0.0"
   },
+  "keywords": [
+    "peac",
+    "peacprotocol",
+    "interaction-records",
+    "signed-records",
+    "receipts",
+    "originary",
+    "cli",
+    "command-line",
+    "verify",
+    "issue",
+    "decode"
+  ],
   "scripts": {
     "prebuild": "rm -rf dist",
     "build": "pnpm run build:js && pnpm run build:types",