@promptscript/cli 1.17.1 → 1.18.0

package/README.md

@@ -5,7 +5,7 @@
 **Agent platform configuration as code**
 
 Define instructions, skills, agents, MCP servers, hooks, workflows, and policies once. Compile
-native configuration for 48 AI coding platforms.
+native configuration for 49 AI coding platforms.
 
 [![npm version](https://img.shields.io/npm/v/@promptscript/cli.svg)](https://www.npmjs.com/package/@promptscript/cli)
 [![CI](https://github.com/mrwogu/promptscript/actions/workflows/ci.yml/badge.svg)](https://github.com/mrwogu/promptscript/actions/workflows/ci.yml)
@@ -206,7 +206,7 @@ unsupported platform-specific features.
 | Automation              | `@hooks`, `@workflows`                                            | Lifecycle hooks and repeatable workflow files                                    |
 | Monorepo delivery       | `builds` in `promptscript.yaml`                                   | Scoped output for packages and applications                                      |
 
-## 48 Built-In Targets
+## 49 Built-In Targets
 
 | Platform       | Primary and rich output                                          |
 | :------------- | :--------------------------------------------------------------- |
@@ -220,9 +220,9 @@ unsupported platform-specific features.
 | Antigravity    | `.agent/rules/`, workflows and MCP configuration                 |
 | Grok           | `AGENTS.md`, agents, skills, commands and integrations           |
 
-PromptScript also supports 10 AGENTS.md targets and 29 Markdown instruction targets, including
+PromptScript also supports 11 AGENTS.md targets and 29 Markdown instruction targets, including
 Windsurf, Cline, Roo Code, Continue, Aider, Amazon Q, Warp, Zed, OpenHands, Qwen Code, Kimi, Mimo,
-Deep Agents, and ForgeCode.
+Deep Agents, ForgeCode, and Hermes Agent.
 
 See the [complete target and capability matrix](https://getpromptscript.dev/reference/formatters/).
 
@@ -339,8 +339,17 @@ Preview before writing:
 ```bash
 prs compile --dry-run
 prs diff --all
+prs diff --format json
 ```
 
+`prs diff --format json` emits a versioned report with target, path, source provenance, ownership,
+change kind, deterministic content hashes, warnings, and unsupported capability entries. Content is
+omitted by default; add `--include-content` when automation needs canonical output text. Reports
+with changes exit 0; compilation and report errors emit `success: false` and exit 1. See the
+[diff schema](https://getpromptscript.dev/schema/diff/v1.json). Diff uses the complete configured
+target when `--target` selects one, never writes generated files or registry cache metadata, and
+requires Git registries to already exist in vendor mode or a valid local cache.
+
 ## CLI Commands
 
 | Command                                             | Purpose                                                  |
@@ -354,6 +363,7 @@ prs diff --all
 | `prs validate --fix`                                | Upgrade outdated syntax declarations when possible       |
 | `prs diff --all`                                    | Preview compiled output differences                      |
 | `prs inspect <skill>`                               | Show skill layers and property provenance                |
+| `prs explain <path>`                                | Show source and composition provenance                   |
 | `prs hooks install [tool]`                          | Integrate supported AI tools and protect generated files |
 | `prs skills <add\|remove\|list\|update>`            | Manage remote Markdown skills                            |
 | `prs registry <init\|validate\|publish\|list\|add>` | Manage registries and aliases                            |
@@ -364,6 +374,12 @@ prs diff --all
 | `prs upgrade`                                       | Upgrade `.prs` syntax versions                           |
 | `prs serve`                                         | Connect local files to the online playground             |
 
+`prs explain` emits project-relative source paths by default. Pass
+`--absolute-paths` to opt in to host filesystem paths. JSON output contains
+`version`, `path`, `entries`, and `diagnostics`. The command exits nonzero for
+missing paths, resolution failures, or fatal diagnostics; warning-only
+diagnostics keep exit status 0.
+
 See the [complete CLI reference](https://getpromptscript.dev/reference/cli/) for every option.
 
 ## Hooks and Generated-File Protection