mrwogu · mrwogu · Oct 1, 2026 · Oct 1, 2026 · Oct 1, 2026 · Oct 1, 2026
diff --git a/README.md b/README.md
@@ -3,10 +3,11 @@
 
 # PromptScript
 
-**Agent platform configuration as code**
+**Write your AI rules once. Every agent follows them.**
 
-_Define instructions, skills, agents, MCP servers, hooks, workflows, and policies once. Compile
-native configuration for 50 AI coding platforms._
+_One source for Claude Code, GitHub Copilot, Cursor, and 47 more tools. Define instructions,
+skills, agents, MCP servers, hooks, and policies once, inherit them like code, and compile native
+files for every tool._
 
 [![CI](https://github.com/mrwogu/promptscript/actions/workflows/ci.yml/badge.svg)](https://github.com/mrwogu/promptscript/actions/workflows/ci.yml)
 [![codecov](https://codecov.io/github/mrwogu/promptscript/graph/badge.svg?token=MPUCPQLVWR)](https://codecov.io/github/mrwogu/promptscript)
@@ -28,7 +29,7 @@ native configuration for 50 AI coding platforms._
 
 ## What is PromptScript?
 
-PromptScript is an open-source language and compiler for AI agent configuration. `.prs` sources
+PromptScript is an open-source compiler for AI coding agent rules. `.prs` sources
 define instructions, project standards, restrictions, skills, agents, MCP servers, hooks, and
 workflows, while `promptscript.yaml` configures targets and extension-compliance policies. The
 compiler turns them into the native files each AI tool already knows: `CLAUDE.md` for Claude Code,
@@ -76,6 +77,8 @@ source. See the [full comparison](https://getpromptscript.dev/guides/vs-manual/)
 - [One Language, Complete Platform](#one-language-complete-platform)
 - [Compose Instead of Copying](#compose-instead-of-copying)
 - [Portable Skills, Native Agents](#portable-skills-native-agents)
+- [Name a Model Once](#name-a-model-once)
+- [Built-In Security Scanner](#built-in-security-scanner)
 - [50 Built-In Targets](#50-built-in-targets)
 - [Built for Repositories and Organizations](#built-for-repositories-and-organizations)
 - [Adopt Without a Rewrite](#adopt-without-a-rewrite)
@@ -322,6 +325,79 @@ PromptScript validates Agent Skills metadata, resolves dependencies and resource
 native skill path for each selected platform. Agents can reference those skills and receive
 target-native model, reasoning, sandbox, tool, permission, and MCP settings.
 
+## Name a Model Once
+
+Each tool spells model names differently. Write an alias like `opus` or a full model id, and
+PromptScript writes the name each target expects:
+
+```promptscript
+@meta {
+  id: "checkout-service"
+  syntax: "1.5.0"
+}
+
+@agents {
+  reviewer: {
+    description: "Review pull requests"
+    model: "opus"
+    content: "Review changed code, tests, and operational impact."
+  }
+}
+```
+
+<!-- playground-link-start -->
+<a href="https://getpromptscript.dev/playground/?s=N4IgZglgNgpgziAXAbVABwIYBcAWSQwAeGAtmrAHRoBOCANCAMYD2AdljO-gAIkxYYABMAA6rQYIgATRIJFMcMRgGtmAVywBaODGoA3CIxjyxEuAE92GQrPkBGCgFYKABhOsAvmLHcMAc04sOGFTQWoYAxgAd11ZUXEJQSl4RmoINCwINlsQACUIiGjBNDUoKDCYAEc1eCD3RMESZmSoHOYSuHrElnZAnPzIqMFGHAxWAKlh5pg6QQ44INmxyfbdbCzWDHKIMgxGLAour08QDwBdBkDqc3wiUnIYKloQBj1dOA38O1OgA" target="_blank" rel="noopener noreferrer">
+  <img src="https://img.shields.io/badge/Try_in-Playground-blue?style=flat-square" alt="Try in Playground" />
+</a>
+<!-- playground-link-end -->
+
+| Target         | Writes                         |
+| :------------- | :----------------------------- |
+| Claude Code    | `opus`                         |
+| GitHub Copilot | `Claude Opus 5.5`              |
+| Factory AI     | `claude-opus-5-5`              |
+| Cursor         | `claude-opus-5-5`              |
+| Codex          | omitted, with a PS4004 warning |
+
+When a target cannot run the model, the compiler warns instead of writing a value the tool would
+reject. Claude Code picks the release for an alias itself. Other targets get the current release
+from the catalog and move on when you upgrade PromptScript and compile again. See the
+[model catalog and aliases](https://getpromptscript.dev/reference/models/).
+
+## Built-In Security Scanner
+
+Instruction files and imported skills are a prompt injection surface. `prs validate` scans the
+instructions and skills in your entry file and everything it imports, before anything is written.
+Encoded payloads are decoded first, so hiding an attack in hex or Base64 does not get it through:
+
+```text
+$ prs validate --strict
+✖ Validation failed
+✗ Blocked pattern detected:
+  ignore\s+(all\s+)?previous\s+instructions
+  at project.prs:8:1
+✗ PS012: Malicious content detected
+  in raw hex (spaced): Prompt injection
+  Decoded: "IGNORE SAFETY RULES"
+  at project.prs:16:14
+✗ PS010: URL shortener detected:
+  http://bit.ly/deploy-help
+  at project.prs:16:14
+```
+
+| Rule  | Catches                                                                        |
+| :---- | :----------------------------------------------------------------------------- |
+| PS005 | Injection phrases like "ignore previous instructions"                          |
+| PS011 | Fake authority overrides and "bypass all safety checks" instructions           |
+| PS012 | Payloads hidden in Base64, hex, URL encoding, HTML entities, ROT13, and 4 more |
+| PS013 | Path traversal in `@use` declarations                                          |
+| PS014 | Right-to-left overrides, zero-width characters, and homoglyphs                 |
+| PS010 | Plain HTTP links, link shorteners, and credentials in URLs                     |
+
+`--strict` turns warnings into errors. Run it in CI so a poisoned skill fails the build, not the
+agent. See
+the [security guide](https://getpromptscript.dev/guides/security/).
+
 ## 50 Built-In Targets
 
 PromptScript ships 50 output targets:
@@ -338,6 +414,11 @@ See exact output paths and feature support in the
 
 ## Built for Repositories and Organizations
 
+- **Runs locally** - PromptScript is a compiler, not a service. No hosted backend and no proxy
+  between your team and its tools, the output is plain files you review and commit.
+- **Your prompts stay yours** - anonymous usage telemetry never includes source, prompts, or file
+  paths. Turn it off with `prs telemetry disable` or `DO_NOT_TRACK=1`. See
+  [what is collected](https://getpromptscript.dev/reference/telemetry/).
 - **Git-native governance** - review source and deterministic generated diffs in pull requests.
 - **Private registries** - share versioned standards through local, HTTP, or Git registries with
   SSH and token-based authentication.
@@ -384,16 +465,18 @@ with `includePromptScriptSkill: false`.
 
 ## Documentation
 
-| Resource                                                                         | Description                                                 |
-| :------------------------------------------------------------------------------- | :---------------------------------------------------------- |
-| [Getting Started](https://getpromptscript.dev/getting-started/)                  | First project from initialization to native output          |
-| [Agent Platform](https://getpromptscript.dev/features/)                          | Skills, agents, MCP, plugins, hooks, workflows, and targets |
-| [Language Reference](https://getpromptscript.dev/reference/language/)            | Complete PromptScript syntax                                |
-| [CLI Reference](https://getpromptscript.dev/reference/cli/)                      | Commands and options                                        |
-| [Configuration Reference](https://getpromptscript.dev/reference/config/)         | Targets, registries, builds, policies, and formatting       |
-| [Anonymous Usage Telemetry](https://getpromptscript.dev/reference/telemetry/)    | Collected fields, delivery, and opt-out controls            |
-| [Upgrade 1.15 to 1.16](https://getpromptscript.dev/guides/upgrade-1-15-to-1-16/) | Syntax, block shape, and hook migration guide               |
-| [Enterprise Guide](https://getpromptscript.dev/guides/enterprise/)               | Organization-wide adoption and governance                   |
+| Resource                                                                      | Description                                                 |
+| :---------------------------------------------------------------------------- | :---------------------------------------------------------- |
+| [Getting Started](https://getpromptscript.dev/getting-started/)               | First project from initialization to native output          |
+| [Agent Platform](https://getpromptscript.dev/features/)                       | Skills, agents, MCP, plugins, hooks, workflows, and targets |
+| [Language Reference](https://getpromptscript.dev/reference/language/)         | Complete PromptScript syntax                                |
+| [CLI Reference](https://getpromptscript.dev/reference/cli/)                   | Commands and options                                        |
+| [Configuration Reference](https://getpromptscript.dev/reference/config/)      | Targets, registries, builds, policies, and formatting       |
+| [Security Guide](https://getpromptscript.dev/guides/security/)                | Validation rules, injection detection, and safe registries  |
+| [Model Catalog](https://getpromptscript.dev/reference/models/)                | Model aliases and per-target model names                    |
+| [Anonymous Usage Telemetry](https://getpromptscript.dev/reference/telemetry/) | Collected fields, delivery, and opt-out controls            |
+| [FAQ](https://getpromptscript.dev/guides/faq/)                                | Common questions about adoption, targets, and security      |
+| [Enterprise Guide](https://getpromptscript.dev/guides/enterprise/)            | Organization-wide adoption and governance                   |
 
 ## Contributing
 

diff --git a/docs/__snapshots__/README.md/checkout-service_Hcf074592/claude.md b/docs/__snapshots__/README.md/checkout-service_Hcf074592/claude.md
@@ -0,0 +1 @@
+# CLAUDE.md
diff --git a/docs/__snapshots__/README.md/checkout-service_Hcf074592/cursor.mdc b/docs/__snapshots__/README.md/checkout-service_Hcf074592/cursor.mdc
@@ -0,0 +1,6 @@
+---
+description: "Project-specific rules"
+alwaysApply: true
+---
+
+You are working on the project.
diff --git a/docs/__snapshots__/README.md/checkout-service_Hcf074592/github.md b/docs/__snapshots__/README.md/checkout-service_Hcf074592/github.md
@@ -0,0 +1 @@
+# GitHub Copilot Instructions
diff --git a/packages/cli/README.md b/packages/cli/README.md
@@ -2,10 +2,11 @@
 
 # @promptscript/cli
 
-**Agent platform configuration as code**
+**Write your AI rules once. Every agent follows them.**
 
-Define instructions, skills, agents, MCP servers, hooks, workflows, and policies once. Compile
-native configuration for 50 AI coding platforms.
+One source for Claude Code, GitHub Copilot, Cursor, and 47 more tools. Define instructions,
+skills, agents, MCP servers, hooks, and policies once, inherit them like code, and compile native
+files for every tool.
 
 [![npm version](https://img.shields.io/npm/v/@promptscript/cli.svg)](https://www.npmjs.com/package/@promptscript/cli)
 [![Node.js 20+](https://img.shields.io/badge/Node.js-20%2B-5FA04E?logo=nodedotjs&logoColor=white)](https://getpromptscript.dev/getting-started/#installation)
@@ -24,7 +25,7 @@ native configuration for 50 AI coding platforms.
 
 ## What is PromptScript?
 
-PromptScript is an open-source language and compiler for AI agent configuration. `.prs` sources
+PromptScript is an open-source compiler for AI coding agent rules. `.prs` sources
 define instructions, project standards, restrictions, skills, agents, MCP servers, hooks, and
 workflows, while `promptscript.yaml` configures targets and extension-compliance policies.
 PromptScript compiles them into the native files each AI tool already reads, including `CLAUDE.md`,
@@ -43,7 +44,8 @@ PromptScript fixes the source instead of patching each generated file:
     -> compile deterministic native files
 ```
 
-No runtime proxy. Each selected platform keeps consuming its own native configuration.
+No runtime proxy and no hosted service. PromptScript runs on your machine and in CI, and each
+selected platform keeps consuming its own native configuration.
 
 ## Why maintain native files by hand?
 
@@ -78,8 +80,14 @@ prs --version
 
 ## Running under Deno
 
-The CLI also runs on Deno 2.9 or later, either straight from the installed
-package or compiled into a standalone binary that needs no other runtime.
+The CLI also runs on Deno 2.9 or later. Install it globally from npm:
+
+```bash
+deno install -g --allow-env --allow-sys --allow-read --allow-write --allow-net --allow-run npm:@promptscript/cli
+```
+
+It can also run straight from the installed package or be compiled into a
+standalone binary that needs no other runtime.
 
 In any project that has `@promptscript/cli` in its dependencies, point Deno at
 the installed bin shim:
@@ -141,6 +149,7 @@ CLAUDE.md
 .claude/agents/reviewer.md
 .claude/skills/security-review/SKILL.md
 .cursor/rules/project.mdc
+.cursor/agents/reviewer.md
 .opencode/agents/reviewer.md
 ```
 
@@ -390,8 +399,8 @@ prs migrate --llm
 
 Static migration deterministically imports detected instruction files. AI-assisted migration
 generates a migration prompt and installs the PromptScript skill. Existing source instructions
-remain untouched, and existing PromptScript configuration is preserved byte-for-byte. Static output is isolated under
-`.promptscript/migrated/`; no detected candidates means no writes.
+remain untouched, and existing PromptScript configuration is preserved byte-for-byte. Static
+output is isolated under `.promptscript/migrated/`; no detected candidates means no writes.
 
 Projects upgrading from PromptScript 1.15 should preview syntax changes with
 `prs upgrade --dry-run`, then run `prs validate --strict`. Factory targets also
@@ -414,6 +423,40 @@ with changes exit 0; compilation and report errors emit `success: false` and exi
 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.
 
+## Built-In Security Scanner
+
+`prs validate` scans the instructions and skills in your entry file and everything it imports for
+prompt injection, before anything is written. Encoded payloads are decoded first, so an attack
+hidden in hex or Base64 does not get through:
+
+```text
+$ prs validate --strict
+✖ Validation failed
+✗ Blocked pattern detected:
+  ignore\s+(all\s+)?previous\s+instructions
+  at project.prs:8:1
+✗ PS012: Malicious content detected
+  in raw hex (spaced): Prompt injection
+  Decoded: "IGNORE SAFETY RULES"
+  at project.prs:16:14
+✗ PS010: URL shortener detected:
+  http://bit.ly/deploy-help
+  at project.prs:16:14
+```
+
+| Rule  | Catches                                                                        |
+| :---- | :----------------------------------------------------------------------------- |
+| PS005 | Injection phrases like "ignore previous instructions"                          |
+| PS011 | Fake authority overrides and "bypass all safety checks" instructions           |
+| PS012 | Payloads hidden in Base64, hex, URL encoding, HTML entities, ROT13, and 4 more |
+| PS013 | Path traversal in `@use` declarations                                          |
+| PS014 | Right-to-left overrides, zero-width characters, and homoglyphs                 |
+| PS010 | Plain HTTP links, link shorteners, and credentials in URLs                     |
+
+`--strict` turns warnings into errors. Run `prs validate --strict` in CI so a poisoned skill fails
+the build, not the agent. See the
+[security guide](https://getpromptscript.dev/guides/security/).
+
 ## CLI Commands
 
 | Command                                             | Purpose                                                  |
@@ -425,17 +468,22 @@ requires Git registries to already exist in vendor mode or a valid local cache.
 | `prs compile --all-builds`                          | Compile every named profile                              |
 | `prs validate --strict`                             | Validate source, references, policies, and capabilities  |
 | `prs validate --fix`                                | Upgrade outdated syntax declarations when possible       |
+| `prs check`                                         | Check config, entries, lockfile, registry, and imports   |
 | `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 hook <action>`                                 | Low-level handler called by AI tool hooks                |
+| `prs skills <add\|remove\|list\|update>`            | Manage remote and local skills                           |
 | `prs registry <init\|validate\|publish\|list\|add>` | Manage registries and aliases                            |
+| `prs pull`                                          | Pull updates from the registry                           |
 | `prs lock` / `prs update`                           | Pin or refresh remote dependencies                       |
 | `prs vendor sync` / `prs vendor check`              | Prepare and verify offline dependencies                  |
 | `prs resolve <import>`                              | Explain import resolution                                |
 | `prs import <file>` / `prs migrate`                 | Adopt existing instruction files                         |
 | `prs upgrade`                                       | Upgrade `.prs` syntax versions                           |
+| `prs update-check`                                  | Check npm for a newer CLI version                        |
+| `prs telemetry <status\|enable\|disable>`           | Inspect or change anonymous telemetry settings           |
 | `prs serve`                                         | Connect local files to the online playground             |
 
 `prs explain` emits project-relative source paths by default. Pass
@@ -460,6 +508,13 @@ Targets with native skill support can receive the bundled PromptScript language
 compatible agents to work with `.prs` source. Disable it with
 `includePromptScriptSkill: false`.
 
+## Privacy and Telemetry
+
+PromptScript is a compiler, not a service. Compiling needs no hosted backend, and the output is
+plain files in your repository. Anonymous usage telemetry never includes source, prompts, or file
+paths. Turn it off with `prs telemetry disable` or `DO_NOT_TRACK=1`. See
+[what is collected](https://getpromptscript.dev/reference/telemetry/).
+
 ## Docker
 
 ```bash
@@ -479,7 +534,10 @@ for syntax highlighting, bracket matching, code folding, and file icons.
 - [Language Reference](https://getpromptscript.dev/reference/language/)
 - [Configuration Reference](https://getpromptscript.dev/reference/config/)
 - [Target Matrix](https://getpromptscript.dev/reference/formatters/)
-- [Upgrade 1.15 to 1.16](https://getpromptscript.dev/guides/upgrade-1-15-to-1-16/)
+- [Security Guide](https://getpromptscript.dev/guides/security/)
+- [Model Catalog](https://getpromptscript.dev/reference/models/)
+- [Glossary](https://getpromptscript.dev/glossary/)
+- [FAQ](https://getpromptscript.dev/guides/faq/)
 - [Enterprise Guide](https://getpromptscript.dev/guides/enterprise/)
 - [Playground](https://getpromptscript.dev/playground/)