@promptscript/cli 1.20.0 → 1.21.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@promptscript/cli",
-  "version": "1.20.0",
+  "version": "1.21.0",
   "description": "CLI for PromptScript - standardize AI instructions across GitHub Copilot, Claude, Cursor and other AI tools",
   "keywords": [
     "cli",
@@ -47,13 +47,13 @@
     "commander": "^15.0.0",
     "minimatch": "^10.2.6",
     "ora": "^9.4.1",
-    "prettier": "^3.9.8",
+    "prettier": "^3.9.9",
     "yaml": "^2.9.1",
     "simple-git": "3.36.0",
     "fastify": "^5.12.5",
     "@fastify/cors": "^11.3.0",
     "@fastify/rate-limit": "^11.2.0",
-    "@fastify/websocket": "^11.3.0",
+    "@fastify/websocket": "^11.3.1",
     "ws": "^8.21.3",
     "fast-glob": "^3.3.0"
   }

package/skills/promptscript/SKILL.md

@@ -248,7 +248,8 @@ Reusable skill definitions with metadata:
 ```
 
 Properties: description (required), content (required), trigger, disableModelInvocation,
-userInvocable, allowedTools, context ("fork" or "inherit"), agent, requires, references, inputs, outputs.
+userInvocable, allowedTools, context ("fork" or "inherit"), agent, model (Claude Code and Grok
+Build, mapped through the model catalog), requires, references, inputs, outputs.
 
 The `references` property attaches external files to the skill's context:
 
@@ -310,7 +311,7 @@ Pass values in `@skills` block:
 
 Non-reserved properties (anything other than description, content, trigger,
 userInvocable, allowedTools, disableModelInvocation, context, agent, requires,
-inputs, outputs) are treated as skill parameter arguments.
+inputs, outputs, model) are treated as skill parameter arguments.
 
 ### Skill Dependencies
 
@@ -416,6 +417,18 @@ Factory AI droids support additional properties: `model` (any model ID or "inher
 `reasoningEffort` ("low", "medium", "high"), and `tools` (category name like "read-only"
 or array of tool IDs).
 
+Agent `model`/`specModel` and skill `model` values resolve against the model catalog
+(built-in profiles plus `models.profiles` in promptscript.yaml). Write a floating alias
+(`sonnet`, `opus`, `haiku`, `fable` - newest Claude release), a pinned model (profile id,
+alias, API id, or display name such as `claude-opus-5-5` or `Claude Opus 5.5`), or
+`inherit`. Each target gets its native name: Claude Code keeps aliases and uses API ids
+for pinned Claude models, GitHub Copilot gets display names (`Claude Sonnet 5`), Factory
+AI and Codex get API ids, and Cursor gets dateless ids. Names outside the catalog pass
+through unchanged, unless the target has its own spelling for them (GitHub Copilot writes
+`auto` as `Auto`). A model from a provider the target cannot run (a GPT model on Claude
+Code, a Claude model on Codex), or a name with a line break or control character, is
+omitted with a PS4004 warning.
+
 ### @workflows
 
 Repeatable multi-step agent procedures. Requires syntax `1.1.0`.
@@ -1006,6 +1019,16 @@ policies:
     severity: error
     layers: ['@core', '@team', '@project']
     maxDistance: 1
+models:
+  supported: [opus, sonnet, gpt-5.3-codex]  # PS041 reports models outside this set
+  profiles:                                 # add models or override built-in profiles
+    claude-opus-9:
+      provider: anthropic
+      family: claude-opus                   # joins the family, so `opus` now resolves here
+      version: '9'
+      displayName: Claude Opus 9
+      targets:
+        github: Claude Opus 9 (Preview)     # per-target name always wins
 ```
 
 ### Lockfile: `promptscript.lock`
@@ -1114,6 +1137,7 @@ sections without changing filenames, frontmatter, XML tags, or structured keys:
 - **PS038 (`valid-block-shape`)**: rejects unsupported built-in block shapes and warns about formatter-sensitive legacy shapes or multiline shortcut scalars.
 - **PS039 (`agent-namespaces`)**: validates qualified agent name segments and checks them against recorded import provenance.
 - **PS040 (`import-excludes`)**: errors when a `validation.excludes` entry for an import does not record the commit pinned in promptscript.lock, so consumers re-review imports whose pinned commit changed.
+- **PS041 (`valid-model-reference`)**: warns when an agent `model`/`specModel` or skill `model` resolves to a deprecated or retired model, suggesting the successor. With `models.supported` set, it also warns about models outside the set, models missing from the catalog, and unknown `models.supported` entries. It also reports `models.profiles` problems: a name shared by two profiles or taken from a floating alias or `inherit`, unknown or looping successors, dates not in `YYYY-MM-DD`, and `targets` keys for targets that write no model names.
 - **PS021 (`use-block-filter`)**: errors when `only` and `exclude` are both specified in `@use` parameters.
 - **PS025 (`valid-skill-references`)**: errors when a `references` entry points to a file with a disallowed extension or a path that cannot be resolved.
 - **PS026 (`safe-reference-content`)**: warns when a referenced file contains potentially sensitive content (e.g., secrets, credentials).
@@ -1125,7 +1149,9 @@ sections without changing filenames, frontmatter, XML tags, or structured keys:
 
 Target formatters report **PS4002** when a hook event or field has no native equivalent,
 when a target cannot guarantee project-root execution, or when output mode cannot emit
-the additional hook file.
+the additional hook file. They report **PS4004** when an agent or skill model comes from
+a provider the target cannot run, or when its name has a line break or control character;
+the model field is omitted for that target.
 
 ### Fixing Syntax Versions
 

package/src/commands/check.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"check.d.ts","sourceRoot":"","sources":["../../../../../packages/cli/src/commands/check.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAsEhD;;;;;;;GAOG;AACH,wBAAsB,YAAY,CAAC,QAAQ,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAsZxE"}
+{"version":3,"file":"check.d.ts","sourceRoot":"","sources":["../../../../../packages/cli/src/commands/check.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAsEhD;;;;;;;GAOG;AACH,wBAAsB,YAAY,CAAC,QAAQ,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAuZxE"}

package/src/commands/compile.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"compile.d.ts","sourceRoot":"","sources":["../../../../../packages/cli/src/commands/compile.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAgBlD,OAAO,EAAE,KAAK,WAAW,EAAyB,MAAM,gBAAgB,CAAC;AAitBzE;;GAEG;AACH,wBAAsB,cAAc,CAClC,OAAO,EAAE,cAAc,EACvB,QAAQ,GAAE,WAAqC,GAC9C,OAAO,CAAC,IAAI,CAAC,CAEf"}
+{"version":3,"file":"compile.d.ts","sourceRoot":"","sources":["../../../../../packages/cli/src/commands/compile.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAgBlD,OAAO,EAAE,KAAK,WAAW,EAAyB,MAAM,gBAAgB,CAAC;AAotBzE;;GAEG;AACH,wBAAsB,cAAc,CAClC,OAAO,EAAE,cAAc,EACvB,QAAQ,GAAE,WAAqC,GAC9C,OAAO,CAAC,IAAI,CAAC,CAEf"}

package/src/commands/diff.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"diff.d.ts","sourceRoot":"","sources":["../../../../../packages/cli/src/commands/diff.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,EAAkC,KAAK,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAmCjF;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,eAAe,UAAQ,GAAG,MAAM,CAwBhE;AAqFD;;GAEG;AACH,wBAAsB,WAAW,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CA+OrE"}
+{"version":3,"file":"diff.d.ts","sourceRoot":"","sources":["../../../../../packages/cli/src/commands/diff.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,EAAkC,KAAK,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAmCjF;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,eAAe,UAAQ,GAAG,MAAM,CAwBhE;AAqFD;;GAEG;AACH,wBAAsB,WAAW,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAgPrE"}

package/src/commands/validate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../../../../packages/cli/src/commands/validate.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAiLnD;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,MAAM,EACf,cAAc,EAAE,MAAM,EACtB,aAAa,EAAE,MAAM,EACrB,UAAU,CAAC,EAAE,MAAM,GAClB,MAAM,GAAG,IAAI,CAgFf;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAC9B,GAAG,EAAE,MAAM,EACX,MAAM,GAAE,OAAe,EACvB,oBAAoB,GAAE,OAAe,GACpC,MAAM,EAAE,CAoBV;AAcD;;GAEG;AACH,wBAAsB,eAAe,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CAyF7E"}
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../../../../packages/cli/src/commands/validate.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAiLnD;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,MAAM,EACf,cAAc,EAAE,MAAM,EACtB,aAAa,EAAE,MAAM,EACrB,UAAU,CAAC,EAAE,MAAM,GAClB,MAAM,GAAG,IAAI,CAgFf;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAC9B,GAAG,EAAE,MAAM,EACX,MAAM,GAAE,OAAe,EACvB,oBAAoB,GAAE,OAAe,GACpC,MAAM,EAAE,CAoBV;AAcD;;GAEG;AACH,wBAAsB,eAAe,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CA0F7E"}

package/src/generated/promptscript-skill.d.ts

@@ -3,5 +3,5 @@
  * Embedded PromptScript skill content, so the CLI works without
  * filesystem skill discovery (including deno compile binaries).
  */
-export declare const PROMPTSCRIPT_SKILL_CONTENT = "---\nname: promptscript\ndescription: >-\n  PromptScript language expert for reading, writing, modifying, and\n  troubleshooting .prs files. Use when working with PromptScript syntax,\n  creating or editing .prs files, adding blocks like @identity, @standards,\n  @restrictions, @shortcuts, @skills, or @agents, configuring\n  promptscript.yaml, resolving compilation errors, understanding inheritance\n  (@inherit), composition (@use, @extend, @override), contextual @header\n  metadata, or migrating AI instructions\n  to PromptScript. Also use when asked about the 50 built-in compilation\n  targets, including GitHub Copilot, Claude Code, Cursor, Antigravity,\n  Factory AI, and AGENTS.md-based platforms.\nlicense: MIT\nmetadata:\n  author: PromptScript\n  homepage: https://getpromptscript.dev\ncompatibility:\n  - claude-code\n  - github-copilot\n  - cursor\n  - factory-ai\n  - gemini-cli\n  - opencode\n  - windsurf\n  - cline\n  - roo\n  - codex\n  - continue\n  - augment\n  - goose\n  - kilo\n  - amp\n  - trae\n  - junie\n  - kiro-cli\nallowed-tools:\n  - Read\n  - Write\n  - Glob\n  - Grep\n  - Bash\nuser-invocable: true\n---\n\n# PromptScript Language Guide\n\nPromptScript is a domain-specific language that compiles `.prs` files into native instruction formats for AI coding assistants (GitHub Copilot, Claude Code, Cursor, Antigravity, Factory AI, OpenCode, Gemini CLI). One source of truth, multiple outputs.\n\n## File Structure\n\nA `.prs` file contains ordered declarations. Syntax `1.5.0` applies `@inherit`,\n`@use`, local blocks, `@extend`, and `@override` in source order. Put `@meta`\nfirst.\n\n```\n# Comments start with #\n\n@meta { ... }           # Required metadata\n@inherit @path          # Single inheritance (optional)\n@use @path [as alias]   # Imports/mixins (optional, multiple)\n\n@identity { ... }       # AI persona\n@context { ... }        # Project context\n@standards { ... }      # Coding conventions\n@restrictions { ... }   # Hard rules\n@shortcuts { ... }      # Command aliases\n@knowledge { ... }      # Reference documentation\n@skills { ... }         # Reusable skill definitions\n@agents { ... }         # Subagent definitions\n@workflows { ... }      # Repeatable agent procedures\n@examples { ... }       # Few-shot input/output examples (syntax 1.2.0+)\n@params { ... }         # Template parameters\n@guards { ... }         # File globs and priorities\n@hooks { ... }          # Portable lifecycle hooks (syntax 1.4.0+)\n@mcpServers { ... }     # MCP server configurations (syntax 1.4.0+)\n@plugins { ... }        # Capability bundles (syntax 1.4.0+)\n@local { ... }          # Private config (not committed)\n@extend path { ... }    # Modify imported blocks\n@override path { ... }  # Replace one complete existing target (syntax 1.5.0+)\n@custom-name { ... }    # Arbitrary named blocks\n```\n\nContextual `@header` entries appear inside supported owner blocks, not at the\ntop level.\n\n## Content Types\n\nPromptScript has four canonical content shapes inside blocks:\n\n### Text Content\n\nUse triple quotes (three double-quote characters) to wrap multiline text.\nText is automatically dedented - leading whitespace from source indentation is stripped.\nUse for prose, markdown, or freeform content.\n\nExample: `@identity` with a text block describing an AI persona starting with \"You are...\"\n\n### Object Content (key-value pairs)\n\n```\n@context {\n  project: \"My App\"\n  team: \"Frontend\"\n  monorepo: {\n    tool: \"Nx\"\n    packageManager: \"pnpm\"\n  }\n}\n```\n\nValues can be strings (quoted or unquoted), numbers, booleans, nested objects, or arrays.\n\n### Array Content\n\n```\n@standards {\n  code: [\n    \"Use strict TypeScript\",\n    \"Named exports only\"\n  ]\n}\n\n@restrictions {\n  - \"Never use any type\"\n  - \"Never commit secrets\"\n}\n```\n\n### Mixed Content\n\nBlocks can contain both object properties and text in the same block.\nPlace the triple-quoted text block alongside key-value pairs.\n\n## Block Reference\n\n### @meta (required)\n\n```\n@meta {\n  id: \"project-id\"        # Required: unique identifier\n  syntax: \"1.0.0\"         # Required: syntax version (semver)\n  org: \"Company Name\"     # Optional\n  team: \"Frontend\"        # Optional\n  tags: [react, ts]       # Optional\n  params: {               # Optional: template parameters\n    projectName: string\n    port: number = 3000\n    debug?: boolean\n    framework: enum(\"react\", \"vue\") = \"react\"\n  }\n}\n```\n\n### @identity\n\nDefines AI persona. Start with \"You are...\" for consistent output across all formatters.\nContains a triple-quoted text block with the persona description.\n\n### @context\n\nProject context with structured properties (project, team, languages, runtime)\nplus optional triple-quoted text for architecture details, diagrams, etc.\n\n### @standards\n\nCategory-based conventions. Any category name is valid:\n\n```\n@standards {\n  typescript: [\"Strict mode\", \"No any type\"]\n  naming: [\"Files: kebab-case.ts\", \"Classes: PascalCase\"]\n  git: {\n    format: \"Conventional Commits\"\n    types: [feat, fix, docs, refactor, test, chore]\n  }\n}\n```\n\nCategory names are arbitrary. `@standards` can also contain free-form text:\n\n```\n@standards {\n  \"\"\"\n  ## Formatting\n  Preserve heading structure and use four-space indentation.\n\n  ## Testing\n  Add regression coverage for every behavior change.\n  \"\"\"\n  typescript: [\"Strict mode\", \"Named exports only\"]\n  git: {\n    format: \"Conventional Commits\"\n  }\n}\n```\n\nFree-form text is dedented and rendered with its Markdown heading structure. Factory\nmonolith output nests it under `Conventions & Patterns`; split Factory rules adjust\nheading levels relative to the generated section. Custom structured categories remain\navailable to formatters that support them.\n\n### @restrictions\n\nHard rules as a list of dash-prefixed strings:\n\n```\n@restrictions {\n  - \"Never expose API keys\"\n  - \"Never commit secrets to version control\"\n  - \"Always validate user input\"\n}\n```\n\n### @shortcuts\n\nSimple strings appear as documentation. Objects with `prompt: true` generate\nexecutable prompt/command files for GitHub Copilot and Cursor:\n\n```\n@shortcuts {\n  \"/review\": \"Review code for quality\"\n  \"/test\": {\n    prompt: true\n    description: \"Write unit tests\"\n    content: (triple-quoted text with instructions)\n  }\n}\n```\n\n> `@commands` is a backwards-compatible alias for `@shortcuts` \u2014 prefer `@shortcuts` in new files.\n\n### @skills\n\nReusable skill definitions with metadata:\n\n```\n@skills {\n  commit: {\n    description: \"Create git commits\"\n    trigger: \"commit, git commit\"\n    disableModelInvocation: true\n    userInvocable: true\n    allowedTools: [\"Bash\", \"Read\"]\n    content: (triple-quoted text with skill instructions)\n  }\n}\n```\n\nProperties: description (required), content (required), trigger, disableModelInvocation,\nuserInvocable, allowedTools, context (\"fork\" or \"inherit\"), agent, requires, references, inputs, outputs.\n\nThe `references` property attaches external files to the skill's context:\n\n```\n@skills {\n  architecture-review: {\n    description: \"Review architecture decisions\"\n    references: [\n      ./references/architecture.md\n      ./references/modules.md\n    ]\n    content: (triple-quoted text)\n  }\n}\n```\n\nAllowed file types: `.md`, `.json`, `.yaml`, `.yml`, `.txt`, `.csv`. Paths are resolved relative\nto the `.prs` file. Formatters emit referenced files alongside SKILL.md in the output directory.\n\n### Parameterized Skills\n\nSkills in `.promptscript/skills/<name>/SKILL.md` support template parameters via\nYAML frontmatter. Define `params` in frontmatter and use `{{variable}}` in content:\n\n```yaml\n---\nname: review\ndescription: 'Review {{language}} code for {{standard}}'\nparams:\n  language:\n    type: string\n  standard:\n    type: string\n    default: 'best practices'\nreferences:\n  - references/architecture.md\n---\nReview the code using {{language}} conventions following {{standard}}.\n```\n\nThe `references` field in SKILL.md frontmatter lists files to attach to the skill's context.\nPaths are relative to the SKILL.md file.\n\nImported SKILL.md frontmatter is bounded: 256 KiB per document, 10,000 YAML nodes, 32 nesting\nlevels, 2,000 entries per mapping or sequence, and 64 KiB per string value. Documents over any\nlimit are rejected before their YAML values are converted.\n\nPass values in `@skills` block:\n\n```\n@skills {\n  review: {\n    description: \"Review code\"\n    language: \"typescript\"\n    standard: \"strict mode\"\n  }\n}\n```\n\nNon-reserved properties (anything other than description, content, trigger,\nuserInvocable, allowedTools, disableModelInvocation, context, agent, requires,\ninputs, outputs) are treated as skill parameter arguments.\n\n### Skill Dependencies\n\nSkills can declare dependencies on other skills via `requires`:\n\n```\n@skills {\n  deploy: {\n    description: \"Deploy service\"\n    requires: [\"lint-check\", \"test-suite\"]\n    content: (triple-quoted text)\n  }\n}\n```\n\nThe validator (PS016) checks that required skills exist, detects self-references,\nand catches circular dependency chains.\n\n### Skill Contracts (Inputs/Outputs)\n\nSkills can declare typed inputs and outputs in SKILL.md frontmatter:\n\n```yaml\n---\nname: security-scan\ndescription: 'Scan for vulnerabilities'\ninputs:\n  files:\n    description: 'Files to scan'\n    type: string\n  severity:\n    description: 'Minimum severity'\n    type: enum\n    options: [low, medium, high]\n    default: medium\noutputs:\n  report:\n    description: 'Scan report'\n    type: string\n  passed:\n    description: 'Whether scan passed'\n    type: boolean\n---\n```\n\nField types: `string`, `number`, `boolean`, `enum` (with `options` list).\nThe validator (PS017) checks field types, ensures enum fields have options,\nand warns if param names collide with input names.\n\n### Shared Resources\n\nSkills in a folder can share common resources via `.promptscript/shared/`:\n\n```\n.promptscript/\n  shared/\n    templates.md         # Shared across all skills\n    style-guide.md\n  skills/\n    review/\n      SKILL.md           # Gets @shared/templates.md, @shared/style-guide.md\n    deploy/\n      SKILL.md           # Also gets shared resources\n```\n\nFiles in `shared/` are automatically included in every skill with `@shared/` prefix.\n\n### @agents\n\nCustom subagent definitions. Compiles to `.claude/agents/` for Claude Code,\n`.github/agents/` for GitHub Copilot, `.factory/droids/` for Factory AI, etc.\n\n```\n@agents {\n  code-reviewer: {\n    description: \"Reviews code quality\"\n    tools: [\"Read\", \"Grep\", \"Glob\", \"Bash\"]\n    model: \"sonnet\"\n    permissionMode: \"default\"\n    content: (triple-quoted text with agent instructions)\n  }\n}\n```\n\nImported agent definitions are qualified by an aliased `@use`:\n\n```\n@use ./frontend-team as frontend\n@use ./backend-team as backend\n```\n\nIf both imports define `reviewer`, the resolved names are `frontend.reviewer` and\n`backend.reviewer`. Unique unaliased imports keep their original names. Conflicting unaliased\ndefinitions stop compilation with source and import diagnostics instead of silently overwriting\none another. Native targets map dots to hyphens, so `frontend.reviewer` becomes\n`frontend-reviewer`.\n\nSupports mixed models per agent: `specModel` sets a different model for\nSpecification/planning mode (GitHub, Factory), `specReasoningEffort` sets reasoning\neffort for the spec model (Factory only, values: \"low\", \"medium\", \"high\").\n\nFactory AI droids support additional properties: `model` (any model ID or \"inherit\"),\n`reasoningEffort` (\"low\", \"medium\", \"high\"), and `tools` (category name like \"read-only\"\nor array of tool IDs).\n\n### @workflows\n\nRepeatable multi-step agent procedures. Requires syntax `1.1.0`.\n\n```\n@workflows {\n  release: {\n    description: \"Prepare a validated release\"\n    content: \"\"\"\n      1. Run formatting, linting, type checks, and tests.\n      2. Validate compiled output.\n      3. Stop before publishing and request approval.\n    \"\"\"\n  }\n}\n```\n\nTargets with native workflow discovery emit dedicated workflow files. Other targets\nretain workflow instructions in their main output when supported.\n\n### @examples\n\nStructured few-shot examples for AI assistants (requires syntax `1.2.0`):\n\n```\n@meta {\n  id: \"commit-style\"\n  syntax: \"1.2.0\"\n}\n\n@examples {\n  feat-commit: {\n    description: \"Feature commit with scope\"\n    input: \"Added user authentication with JWT tokens\"\n    output: \"feat(auth): add JWT-based user authentication\"\n  }\n}\n```\n\nEach entry is a named example with `input` and `output` (both required),\nplus optional `description`. Multi-line content uses triple-quoted strings.\n\nExamples can also be attached to skills via the `examples` property:\n\n```\n@skills {\n  commit: {\n    description: \"Create conventional commits\"\n    examples: {\n      basic: {\n        input: \"Added dark mode toggle\"\n        output: \"feat(settings): add dark mode toggle\"\n      }\n    }\n    content: (triple-quoted text)\n  }\n}\n```\n\n### @knowledge\n\nReference documentation as triple-quoted text. Used for command references,\nAPI docs, and other material that should appear in the output.\n\n### @params\n\nTemplate parameter definitions with types: string, number, boolean, enum(\"a\", \"b\").\nOptional parameters use `?` suffix. Defaults use `= value`.\n\n### @guards\n\nFile glob patterns and priority rules for path-specific instructions.\n\n### @hooks\n\nPortable lifecycle hooks. Requires syntax `1.4.0`. Each hook needs exactly one of\n`command` or `script`.\n\n```\n@hooks {\n  validate-types: {\n    event: \"post-tool-use\"\n    matcher: \"Edit|Write\"\n    script: {\n      path: \".promptscript/scripts/validate.py\"\n      interpreter: \"python3\"\n      args: [\"--strict\"]\n    }\n    cwd: \"project\"\n    timeoutMs: 120000\n    statusMessage: \"Checking TypeScript\"\n    continueOnFailure: false\n    enabled: true\n    targets: {\n      factory: { matcher: \"Execute\" }\n      vscode: { matcher: \"run_in_terminal\" }\n      github: { enabled: false }\n    }\n  }\n}\n```\n\nPortable events:\n\n| Event                  | Meaning                   |\n| ---------------------- | ------------------------- |\n| `pre-terminal-command` | Before a terminal command |\n| `pre-tool-use`         | Before a tool invocation  |\n| `post-tool-use`        | After a tool invocation   |\n| `session-start`        | Agent session start       |\n| `setup`                | Session setup             |\n| `subagent-start`       | Subagent start            |\n| `notification`         | Agent notification        |\n| `stop`                 | Agent stop                |\n\n`command` is a non-empty string array. Shell interpolation (`$()`, backticks,\n`${...}`) is forbidden. `script` requires:\n\n- `path` under `.promptscript/scripts/`, using forward slashes.\n- Existing regular file at compile time.\n- No traversal, absolute path, invalid segment, or symlink escape.\n- Explicit interpreter: `python3`, `python`, `node`, `deno`, `bun`, `ruby`, `php`,\n  `perl`, `bash`, `sh`, `zsh`, `pwsh`, or `powershell`.\n- Optional `args` string array; each argument remains one argument.\n\n`cwd: \"project\"` runs from project root. Other values are portable forward-slash\npaths relative to project root. Hook config file location does not set command cwd.\nEnvironment-root and Git-root wrappers exit before script or command execution when\nthe required root is unavailable. Native-cwd and workspace-cwd targets retain host\ncwd fields and report `PS4002` when PromptScript cannot verify that cwd.\n`timeoutMs` range is 100-600000. `matcher` uses target-native tool names, so a\nmatcher valid for one target may match nothing on another.\n\n`pre-terminal-command` supplies native defaults: Factory `Execute`, Claude and\nCodex `Bash`, Windsurf `pre_run_command`, Cursor `run_terminal_cmd`, Gemini\n`run_shell_command`, and VS Code `run_in_terminal`. Override a native tool name\nwith `targets.<name>.matcher`. Cursor, Gemini, and VS Code report best-effort\n`PS4002` warnings. GitHub and Grok omit the event with `PS4002`.\n\nTarget overrides may change `event`, `matcher`, `timeoutMs`, `statusMessage`,\n`continueOnFailure`, `enabled`, or `cwd`. Native hook files are emitted only in\ntarget modes that support additional files:\n\n| Target         | Hook output                                                            | Mode                |\n| -------------- | ---------------------------------------------------------------------- | ------------------- |\n| Claude Code    | `.claude/settings.json`                                                | `full`              |\n| Factory AI     | `.factory/hooks.json`                                                  | `multifile`, `full` |\n| GitHub Copilot | `.github/hooks/promptscript.json`                                      | `multifile`, `full` |\n| Cursor         | `.cursor/hooks.json`                                                   | `full`              |\n| Codex          | `.codex/hooks.json`                                                    | `multifile`, `full` |\n| Gemini CLI     | `.gemini/settings.json`                                                | `multifile`, `full` |\n| Windsurf       | `.windsurf/hooks.json`                                                 | `multifile`, `full` |\n| Grok Build     | `.grok/hooks/promptscript.json`                                        | `full`              |\n| OpenCode       | `.opencode/plugins/promptscript.ts` (generated plugin)                 | `multifile`, `full` |\n| VS Code Agent  | `.github/hooks/promptscript-vscode.json` when `vscode` override exists | target-specific     |\n\nOpenCode starts generated hook commands asynchronously. It enforces authored\ntimeouts or a 30-second default, then escalates from `SIGTERM` to `SIGKILL`.\nPayloads are bounded by UTF-8 byte length. OpenCode tool hooks expose tool\narguments, session ID, and call ID, but no model or agent context; compilation\nreports that limitation with `PS4002`.\n\nSimple mode and targets without native project hooks report `PS4002` instead of\nsilently dropping hooks. Use `prs compile --watch` as fallback. Plugin-only and\nagent-scoped integrations are not emitted as universal project hooks.\n\nEach generated command carries a PromptScript ownership marker. CLI cleanup removes\nonly marked entries and preserves user hooks/settings. Removing `@hooks` removes a\nfully owned generated hook file and prunes directories left empty. `prs hooks install factory`\nmigrates unambiguous legacy hooks from `.factory/settings.json`; ambiguous\nentries remain for manual review.\n\nFactory compilation performs the same migration when `.factory/hooks.json` is\nabsent. Use `prs compile --dry-run` to preview the changes or\n`--no-migrate-factory-hooks` to keep warning-only behavior. Unknown events,\nmalformed entries, and mixed ownership abort without a partial migration.\n\n`@hooks` compilation is separate from `prs hooks install`. The latter installs\nauto-compilation and generated-output protection for supported AI tools. Copilot VS\nCode Agent hooks use `promptscript-vscode.json`; GitHub Copilot repository hooks use\n`promptscript.json`.\n\n### @mcpServers\n\nProject-local Model Context Protocol servers. Requires syntax `1.4.0`.\n\n```\n@mcpServers {\n  issue-tracker: {\n    transport: \"stdio\"\n    command: [\"node\", \"./tools/issues.mjs\"]\n    env: { LOG_LEVEL: \"info\" }\n  }\n}\n```\n\nUse `stdio` with `command`, or `http`/`sse` with `url`. Keep credentials out of\n`.prs` files and provide them through target-native secret management.\n\n### @plugins\n\nPortable capability bundles. Requires syntax `1.4.0`.\n\n```\n@plugins {\n  security-suite: {\n    description: \"Security review tooling\"\n    version: \"1.0.0\"\n    skills: [\"security-review\"]\n    hooks: [\"validate-types\"]\n    mcpServers: [\"issue-tracker\"]\n  }\n}\n```\n\n### @local\n\nPrivate local configuration. Not included in compiled output or committed to git.\n\n## Inheritance and Composition\n\n### @inherit (single, linear)\n\nOne per file. Child blocks merge on top of parent:\n\n```\n@inherit @company/frontend-team\n@inherit ./parent\n@inherit @stacks/react-app(projectName: \"my-app\", port: 3000)\n```\n\n### @use (multiple, mixins)\n\nImport and merge fragments:\n\n```\n@use @core/security\n@use @core/quality\n@use ./local-config\n@use @core/typescript as ts   # alias enables @extend access\n```\n\n#### URL imports (Go-module style)\n\nImport directly from any Git repository by host path - no alias required:\n\n```\n@use github.com/acme/shared-standards/@fragments/security\n@use gitlab.com/myorg/prompts/@stacks/python\n```\n\nVersion pinning with `@`:\n\n```\n@use github.com/acme/shared-standards/@org/base@1.2.0    # exact version\n@use github.com/acme/shared-standards/@org/base@^1.0.0   # semver range\n@use github.com/acme/shared-standards/@org/base@main     # branch\n```\n\n#### Registry aliases\n\nShort names for Git repository URLs, configured in `promptscript.yaml`:\n\n```yaml\nregistries:\n  company:\n    url: github.com/acme/promptscript-registry\n```\n\nThen use the alias as scope prefix:\n\n```\n@use @company/security\n@inherit @company/base-config\n```\n\nMerge rules:\n\n- Text: concatenated with deduplication\n- Objects: deep merged (imported source wins same-shape conflicts)\n- Arrays: unique concatenation\n- Shape mismatch: existing target body wins\n\nUnder syntax `1.5.0`, later local blocks, `@extend`, and `@override`\noperations apply to the accumulated import result in declaration order.\n\n### Block Filtering\n\nControl which blocks are imported using the reserved `only` and `exclude` parameters:\n\n```\n@use ./shared-config(only: [\"skills\", \"context\"])\n@use ./shared-config(exclude: [\"knowledge\"])\n@use ./shared-config(exclude: [\"knowledge\"], mode: \"strict\")\n```\n\nRules:\n\n- `only` and `exclude` are mutually exclusive \u2014 using both is a validation error (PS021)\n- Values are block type names: `identity`, `context`, `standards`, `knowledge`, `skills`, `shortcuts`, `agents`, etc.\n- Block filtering does not apply to `@inherit` directives\n\n### Markdown Imports\n\nImport skills directly from `.md` files (v1.8+). No external tools needed:\n\n```\n@use ./skills/frontend-design.md\n@use ./shared/commit.md as commit\n@use github.com/anthropics/skills/commit@1.0.0\n@use github.com/repo/skills/gitnexus         # directory \u2192 SKILL.md\n```\n\nContent detection: PromptScript blocks in `.md` are parsed as a `.prs` fragment;\nYAML frontmatter with `name`/`description` is loaded as a skill definition;\notherwise content is treated as free-form knowledge.\n\nCLI management:\n\n```\nprs skills add github.com/anthropics/skills/commit@1.0.0\nprs skills remove commit\nprs skills list\nprs skills update\n```\n\n### @extend (modify existing or imported blocks)\n\nUse a direct path for inherited or local blocks:\n\n```\n@extend standards.testing {\n  coverage: 95\n}\n```\n\nUse an alias when targeting a specific imported block:\n\n```\n@use @core/typescript as ts\n\n@extend ts.standards {\n  testing: { coverage: 95 }\n}\n```\n\n#### Replacing regular block fields\n\nSyntax `1.3.0` supports explicit replacement of complete regular block field values:\n\n```\n@meta { id: \"project\" syntax: \"1.3.0\" }\n\n@inherit ./company-base\n\n@extend standards {\n  testing!: [\"Use Vitest\"]\n  linting: [\"Use ESLint\"]\n}\n```\n\n`testing!` replaces the inherited value. Fields without `!` keep normal merge behavior.\nReplacement works after `@inherit` and `@use`, including aliases and nested target paths.\nA missing field is set. The modifier is rejected for `@skills`, which retain their dedicated\nmerge and sealing semantics.\n\n#### Replacing complete targets with @override\n\nSyntax `1.5.0` adds atomic replacement for an existing block or nested value:\n\n```\n@meta { id: \"project\" syntax: \"1.5.0\" }\n\n@standards {\n  testing: [\"Use Jest\", \"Use Mocha\"]\n}\n\n@override standards.testing {\n  [\"Use Vitest\"]\n}\n```\n\n`@override` requires the complete target path to exist, applies in declaration\norder, and cannot bypass sealed skill properties. Later `@extend` declarations\nmerge into the replacement. Use `@extend` for additive changes, `field!` for\ncompatibility replacement of one direct regular field, and `@override` for\nintentional complete replacement.\n\n#### Skill-aware @extend semantics\n\nWhen extending a skill definition via `@extend`, individual skill properties follow specific merge\nstrategies rather than the generic block merge rules:\n\n| Strategy          | Properties                                                                                                  |\n| ----------------- | ----------------------------------------------------------------------------------------------------------- |\n| **Replace**       | content, description, trigger, userInvocable, allowedTools, disableModelInvocation, context, agent, license |\n| **Append**        | references, examples, requires                                                                              |\n| **Shallow merge** | params, inputs, outputs                                                                                     |\n\nExample \u2014 extending a base skill to add references and override content:\n\n```\n@use @company/skills as skills\n\n@extend skills.code-review {\n  content: (triple-quoted text with overridden instructions)\n  references: [\n    ./extra-context.md\n  ]\n}\n```\n\nThe `references` array from the base skill and the overlay are combined (append). The `content`\nfield from the overlay replaces the base (replace).\n\n#### Reference negation\n\nUse `!` prefix in `@extend` to remove entries from a lower layer's append-strategy arrays:\n\n```\n@extend skills.code-review {\n  references: [\n    \"!references/deprecated.md\"\n    \"references/replacement.md\"\n  ]\n}\n```\n\nPath matching is normalized (`\"!./foo.md\"` matches `\"foo.md\"`). Only works in `@extend` blocks\non `references` and `requires`. Validator PS028 warns about `!` in base definitions.\n\n#### Overlay consistency warnings\n\nThe resolver emits warnings during compile when an overlay drifts from its base. Always shown\n(not gated by `--verbose`):\n\n- **Orphaned extend** \u2014 `@extend target \"X\" not found \u2014 overlay will be ignored.` Triggered when\n  the targeted block doesn't exist (base removed or renamed).\n- **Stale skill target** \u2014 `@extend creates new skill \"X\" \u2014 base does not define it.` Triggered\n  when an `@extend` inside `@skills` would create a new skill instead of extending an existing one.\n- **Negation orphan** \u2014 `Negation \"!path\" did not match any base entry \u2014 it may be stale.`\n  Triggered when a `!entry` in references/requires doesn't match anything in the base.\n\nThese come from the resolver, not the validator (PS0XX rules). They appear during `prs compile`,\nnot `prs validate`.\n\n#### Sealed properties\n\nPrevent `@extend` from overriding specified replace-strategy properties:\n\n```\n@skills {\n  deploy: {\n    content: (triple-quoted text with critical workflow)\n    sealed: [\"content\", \"description\"]\n  }\n}\n```\n\n`sealed: true` seals all replace-strategy properties. Attempting to override a sealed\nproperty is a hard compilation error. Only the base skill author can set `sealed` \u2014\noverlays cannot add or modify it. Append-strategy properties remain extendable.\nValidator PS029 warns about invalid entries in `sealed`.\n\n#### Skill composition (inline @use)\n\nImport sub-skills within a `@skills` block to compose multi-phase workflows:\n\n```\n@skills {\n  ops: {\n    description: \"Production triage\"\n    content: (triple-quoted text with orchestrator instructions)\n  }\n  @use ./phases/health-scan\n  @use ./phases/triage\n  @use ./phases/code-fix as autofix\n}\n```\n\nEach `@use` resolves the referenced `.prs` file, extracts its skill definition and context\nblocks, and flattens them as numbered phase sections into the parent skill's content. The\n`as alias` form controls the phase display name. Validator PS027 checks composition validity.\n\n### Parameterized Inheritance (Template Variables)\n\nUse `{{variable}}` placeholders in a **parent/template** file, and pass values\nfrom the **child** file via `@inherit` or `@use` with `(key: value)` syntax.\n\n**IMPORTANT:** Variables are NOT set from `promptscript.yaml` or CLI. They are\npassed from one `.prs` file to another through `@inherit` or `@use`.\n\n**Step 1: Create the template** (parent file with `params` in `@meta`):\n\n```\n# base.prs - reusable template\n@meta {\n  id: \"service-template\"\n  syntax: \"1.0.0\"\n  params: {\n    serviceName: string\n    port?: number = 3000\n  }\n}\n\n@identity {\n  \"\"\"\n  You are working on {{serviceName}} running on port {{port}}.\n  \"\"\"\n}\n```\n\n**Step 2: Inherit with values** (child file passes params):\n\n```\n# project.prs - concrete project\n@meta { id: \"user-api\" syntax: \"1.0.0\" }\n\n@inherit ./base(serviceName: \"user-api\", port: 8080)\n```\n\nAfter compilation, `{{serviceName}}` becomes `user-api` and `{{port}}` becomes `8080`.\n\nThe same works with `@use`:\n\n```\n@use ./base(serviceName: \"auth-service\") as auth\n```\n\n**Parameter types:** `string`, `number`, `boolean`, `enum(\"a\", \"b\")`.\nOptional params use `?` suffix. Defaults use `= value`.\nMissing required params produce a compile error.\n\n**Multi-service pattern** - reuse one template across many projects:\n\n```\nservices/\n  base.prs                          # template with params\n  user-api/\n    promptscript.yaml               # source: project.prs\n    project.prs                     # @inherit ../base(serviceName: \"user-api\")\n  auth-service/\n    promptscript.yaml\n    project.prs                     # @inherit ../base(serviceName: \"auth-service\")\n```\n\n## Configuration: promptscript.yaml\n\n### Auto-injection\n\nThis skill is automatically included when compiling with `prs compile`. No manual copying needed.\nTo disable, set `includePromptScriptSkill: false` in your `promptscript.yaml`.\n\n```\nid: my-project\nsyntax: \"1.1.0\"\ndescription: \"My project description\"\ninput:\n  entry: .promptscript/project.prs\n  include: ['.promptscript/**/*.prs']\ntargets:\n  github:\n    version: full      # simple | multifile | full\n  claude:\n    version: full\n  cursor:\n    version: standard\n  antigravity:\n    version: frontmatter\n  factory:\n    version: full\n  windsurf:             # 41 additional targets supported\n    version: simple\n  cline:\n    version: simple\nregistry:\n  git: https://github.com/org/registry.git\n  ref: main\nregistries:\n  company:\n    url: github.com/acme/promptscript-registry\n  oss:\n    url: github.com/prscrpt/community-registry\n    ref: v2\npolicies:\n  - name: adjacent-layers-only\n    kind: layer-boundary\n    severity: error\n    layers: ['@core', '@team', '@project']\n    maxDistance: 1\n```\n\n### Lockfile: `promptscript.lock`\n\nWhen remote imports are used, run `prs lock` to generate or update the lockfile\nbefore compilation. It records the exact resolved commit for each dependency.\nIntegrity hashes (SHA-256) are included for registry references to detect\ntampering or drift. This enables reproducible builds across machines and CI.\nCommit `promptscript.lock` to version control.\n\nUse `--ignore-hashes` on `prs compile` or `prs validate` to skip integrity\nhash verification when needed.\n\n### Policy Engine\n\nDefine organizational policies in `promptscript.yaml` to validate skill extensions:\n\n```yaml\npolicies:\n  - name: adjacent-layers-only\n    kind: layer-boundary\n    description: 'Only adjacent layers can extend each other'\n    severity: error\n    layers: ['@core', '@team', '@project']\n    maxDistance: 1\n\n  - name: protect-content\n    kind: property-protection\n    description: 'Content override requires explicit approval'\n    severity: warning\n    properties: ['content', 'description']\n\n  - name: approved-registries\n    kind: registry-allowlist\n    description: 'Extensions must come from approved registries'\n    severity: error\n    allowed: ['@core', '@team']\n```\n\nPolicy kinds: `layer-boundary` (controls layer distance), `property-protection`\n(prevents overriding specific properties), `registry-allowlist` (restricts extension sources).\nSeverity: `error` (fails validation) or `warning` (reported only).\nSkip with `--skip-policies` during development (never in CI).\n\n## Syntax Version Validation\n\nThe `syntax` field in `@meta` declares the PromptScript language version (semver).\n\n### Known Versions\n\n| Version | What it adds                                                                                                            |\n| ------- | ----------------------------------------------------------------------------------------------------------------------- |\n| `1.0.0` | Core blocks (identity, context, standards, restrictions, knowledge, shortcuts, commands, guards, params, skills, local) |\n| `1.1.0` | Adds `@agents` and `@workflows`; reserves internal `@prompts`                                                           |\n| `1.2.0` | Adds `@examples` (few-shot input/output pairs)                                                                          |\n| `1.3.0` | Adds explicit regular block field replacement in `@extend`                                                              |\n| `1.4.0` | Adds `@hooks`, `@mcpServers`, and `@plugins`                                                                            |\n| `1.5.0` | Adds `@header` section titles, `@override` replacement, and unquoted `${VAR}` values                                    |\n\n### Block Version Requirements\n\n| Block         | Minimum Syntax Version |\n| ------------- | ---------------------- |\n| `@agents`     | `1.1.0`                |\n| `@workflows`  | `1.1.0`                |\n| `@examples`   | `1.2.0`                |\n| `@hooks`      | `1.4.0`                |\n| `@mcpServers` | `1.4.0`                |\n| `@plugins`    | `1.4.0`                |\n\nAll other built-in blocks are available from `1.0.0`.\nRegular block field replacement with `field!: value` requires syntax `1.3.0`.\nGenerated section title overrides with `@header` require syntax `1.5.0`.\nAtomic replacement with `@override` requires syntax `1.5.0`.\nUnquoted `${VAR}` references as values require syntax `1.5.0`.\n\n### Generated Section Headers\n\nUse `@header` inside a registered owner block to rename human-readable output\nsections without changing filenames, frontmatter, XML tags, or structured keys:\n\n```promptscript\n@meta { id: \"localized\" syntax: \"1.5.0\" }\n\n@standards {\n  @header \"Coding Rules\"\n  @header git-commits \"Commit Rules\"\n  code: [\"Use strict TypeScript\"]\n}\n```\n\n- `@header \"Title\"` targets the block's primary section.\n- `@header <section-key> \"Title\"` targets an owned derived section.\n- Titles must be non-empty, single-line strings.\n- Source overrides take precedence over formatter configuration and target defaults.\n- Child inheritance, imported source, and the latest root extension take precedence.\n- An initial `## Heading` in a registered text-only primary owner is a syntax\n  `1.5.0` compatibility fallback. Explicit `@header` metadata wins.\n- Ordinary `header` and `headers` fields remain domain data.\n\n### Validation Rules\n\n- **PS018 (`syntax-version-compat`)**: warns when resolved blocks or syntax features require a higher version than declared. Requirements from inheritance, imports, and skill composition are included. Suggestion: run `prs validate --fix`.\n- **PS019 (`unknown-block-name`)**: warns when a block name is not a known PromptScript type, with fuzzy-match suggestions for typos.\n- **PS037 (`valid-section-headers`)**: rejects invalid titles, unknown or unowned section keys, duplicate overrides, and nested extension overrides.\n- **PS038 (`valid-block-shape`)**: rejects unsupported built-in block shapes and warns about formatter-sensitive legacy shapes or multiline shortcut scalars.\n- **PS039 (`agent-namespaces`)**: validates qualified agent name segments and checks them against recorded import provenance.\n- **PS040 (`import-excludes`)**: errors when a `validation.excludes` entry for an import does not record the commit pinned in promptscript.lock, so consumers re-review imports whose pinned commit changed.\n- **PS021 (`use-block-filter`)**: errors when `only` and `exclude` are both specified in `@use` parameters.\n- **PS025 (`valid-skill-references`)**: errors when a `references` entry points to a file with a disallowed extension or a path that cannot be resolved.\n- **PS026 (`safe-reference-content`)**: warns when a referenced file contains potentially sensitive content (e.g., secrets, credentials).\n- **PS027 (`valid-skill-composition`)**: warns about conflicting phase names or excessive phases in composed skills.\n- **PS028 (`valid-append-negation`)**: warns when negation prefix `!` appears in base skill definitions (only effective in `@extend`).\n- **PS029 (`valid-sealed-property`)**: warns when `sealed` contains non-replace-strategy property names.\n- **PS030 (`policy-compliance`)**: validates skill extensions against organizational policies defined in `promptscript.yaml`.\n- **PS034 (`valid-hooks`)**: validates portable hook events, commands/scripts, paths, interpreters, timeouts, cwd, and target overrides.\n\nTarget formatters report **PS4002** when a hook event or field has no native equivalent,\nwhen a target cannot guarantee project-root execution, or when output mode cannot emit\nthe additional hook file.\n\n### Fixing Syntax Versions\n\n```\nprs validate --fix          # Auto-fix syntax versions in .prs files\nprs upgrade                 # Upgrade all .prs files to the latest version\n```\n\n`--fix` rewrites the `syntax: \"...\"` line in each file's `@meta` block to match the minimum version required by resolved blocks and syntax features. It follows inheritance, imports, and skill composition. It only upgrades, never downgrades.\n\n`prs upgrade` upgrades all files to the latest known syntax version regardless of what blocks they use.\n\n## CLI Commands\n\n```\nprs init                    # Initialize project (auto-detects existing files)\nprs init --yes --targets claude factory\nprs init --dry-run          # Preview initialization\nprs init --auto-import      # Initialize + static import of existing files\nprs migrate                 # Interactive migration flow\nprs migrate --static        # Non-interactive static import\nprs migrate --llm           # Generate AI-assisted migration prompt\nprs migrate --static --dry-run\nprs compile                 # Compile to all targets\nprs compile --watch         # Watch mode\nprs compile --ignore-hashes # Skip integrity hash verification\nprs build <name>            # Compile a named build profile\nprs validate --strict       # Validate syntax\nprs validate --fix          # Auto-fix syntax version declarations\nprs validate --skip-policies # Skip policy engine evaluation\nprs upgrade                 # Upgrade all .prs files to latest syntax version\nprs import CLAUDE.md        # Import existing AI instructions\nprs import CLAUDE.md --dry-run # Preview import conversion\nprs inspect <skill>         # Show skill composition provenance\nprs inspect <skill> --layers # Show layer-level breakdown\nprs explain <path>          # Explain source and composition provenance\nprs explain <path> --format json # Machine-readable provenance history\nprs hooks install           # Install auto-compilation hooks for AI tools\nprs hooks install claude    # Install hooks for a specific tool\nprs hooks uninstall         # Remove installed auto-compilation hooks\nprs hooks uninstall claude  # Remove hooks for a specific tool\nprs skills add <source>     # Add a remote skill (@use + lock update + SKILL.md validation)\nprs skills add <source> --strict          # Treat validation warnings as errors\nprs skills add <source> --skip-validation # Bypass Agent Skills spec checks (not recommended)\nprs skills remove <name>    # Remove a skill (@use line + lock entry)\nprs skills list             # List all imported skills\nprs skills update           # Re-resolve markdown-imported skills (re-validates + re-hashes)\nprs pull                    # Update registry\nprs diff --target claude    # Show compilation diff\nprs diff --all --format json # Machine-readable diff report for CI\nprs diff --format json --include-content # Include generated content in the report\nprs lock                    # Generate/update promptscript.lock\nprs lock --dry-run          # Preview lockfile changes\nprs update                  # Re-resolve all remote imports to latest\nprs update <url>            # Update a specific registry\nprs vendor sync             # Copy cached deps to .promptscript/vendor/\nprs vendor check            # Verify vendor matches lockfile\nprs resolve @alias/path     # Debug: show how an import resolves\nprs registry list           # Show configured registries and aliases\nprs registry add <alias> <url>  # Add a registry alias\n```\n\n`prs init --yes` requires explicit, detected, or user-configured targets. It does not invent\ndefault tools. For existing projects, `prs migrate` preserves `promptscript.yaml`, isolates static\noutput under `.promptscript/migrated/`, leaves source instructions untouched, and performs no\nwrites when no candidates are detected.\n\n## Output Targets\n\n50 supported targets. Key examples:\n\n| Target      | Main File                       | Skills                                             |\n| ----------- | ------------------------------- | -------------------------------------------------- |\n| GitHub      | .github/copilot-instructions.md | .github/skills/\\*/SKILL.md                         |\n| Claude      | CLAUDE.md                       | .claude/skills/\\*/SKILL.md                         |\n| Cursor      | .cursor/rules/project.mdc       | .agents/skills/\\*/SKILL.md                         |\n| Antigravity | .agent/rules/project.md         | -                                                  |\n| Factory     | AGENTS.md                       | .factory/skills/\\*/SKILL.md, .factory/droids/\\*.md |\n| OpenCode    | OPENCODE.md                     | .opencode/skills/\\*/SKILL.md                       |\n| Gemini      | GEMINI.md                       | .agents/skills/\\*/skill.md                         |\n| Windsurf    | .windsurf/rules/project.md      | .windsurf/skills/\\*/SKILL.md                       |\n| Cline       | .clinerules                     | -                                                  |\n| Roo Code    | .roorules                       | -                                                  |\n| Codex       | AGENTS.md                       | .agents/skills/\\*/SKILL.md                         |\n| Continue    | .continue/rules/project.md      | -                                                  |\n| Hermes      | AGENTS.md                       | -                                                  |\n| + 37 more   |                                 | See full list in documentation                     |\n\nTargets that share an output path (for example Factory, Codex, and every AGENTS.md target) are\nreconciled in one output plan before anything is written. Identical content merges silently;\ndiffering content reports `PS4001`, where a formatter output replaces an earlier one and a\nresource or the auto-injected PromptScript skill keeps the file already planned. Paths are compared\ncase-insensitively and NFC-normalized on every platform.\n\n### Formatter Documentation\n\nFor detailed information about each formatter's output paths, supported features, quirks, and example outputs:\n\n- **Full formatter reference:** `docs/reference/formatters/` (7 dedicated pages + index of all 50)\n- **llms-full.txt:** Available at the docs site root - contains all documentation in a single file for LLM consumption\n- **Dedicated pages exist for:** Claude Code, GitHub Copilot, Cursor, Antigravity, Factory AI, Gemini CLI, OpenCode\n- **All 50 formatters indexed at:** `docs/reference/formatters/index.md` with output paths, tier, and feature flags\n\n### Auto-Compilation Hooks\n\nInstead of running `prs compile --watch` manually, install hooks so your AI tool\ntriggers compilation automatically when you edit `.prs` files:\n\n```\nprs hooks install          # Auto-detect and install for all detected tools\nprs hooks install claude   # Install for a specific tool\n```\n\nHooks also protect generated files from direct edits \u2014 when an AI agent tries\nto edit a compiled output (e.g., CLAUDE.md), the write is blocked with a message\npointing to the source `.prs` file. Supported tools: Claude Code, Factory AI,\nCursor, Windsurf, Cline, GitHub Copilot, Gemini CLI.\n\n## Project Organization\n\nTypical modular structure:\n\n```\n.promptscript/\n  project.prs      # Entry: @meta, @inherit, @use, @identity, @agents\n  context.prs      # @context (architecture, tech stack)\n  standards.prs    # @standards (coding conventions)\n  restrictions.prs # @restrictions (hard rules)\n  commands.prs     # @shortcuts and @knowledge\n```\n\nThe entry file uses `@use ./context`, `@use ./standards`, etc. to compose them.\n\n## Common Mistakes\n\n1. Missing @meta block - every .prs file needs `@meta` with `id` and `syntax`\n2. Multiple @inherit - only one per file; use `@use` for additional imports\n3. Extending an unknown path - target an inherited or local block, or use an imported alias\n4. Unquoted strings with special chars - quote strings containing `:`, `#`, `{`, `}`\n5. Forgetting to compile - `.prs` changes need `prs compile` to take effect\n6. Triple quotes inside triple quotes - not supported; describe content textually instead\n7. Using `{{var}}` in the root file without `@inherit` - template variables only work\n   in a parent file that defines `params` in `@meta`, with values passed by the child\n   via `@inherit ./parent(key: value)` or `@use ./fragment(key: value)`. They are NOT\n   set from `promptscript.yaml` or CLI flags\n8. Using `@examples` with `syntax: \"1.0.0\"` or `\"1.1.0\"` - `@examples` requires\n   syntax version `1.2.0`. Run `prs validate --fix` to auto-upgrade\n\n## Migrating Existing AI Instructions to PromptScript\n\n### Automated: `prs import`\n\nThe fastest way to convert existing AI instructions to PromptScript:\n\n```\nprs import CLAUDE.md                    # Convert a single file\nprs import .github/copilot-instructions.md\nprs import AGENTS.md --output ./imported\nprs import --dry-run CLAUDE.md          # Preview without writing\n```\n\n`prs import` automatically:\n\n- Detects the source format (Claude, GitHub Copilot, Cursor, Factory, etc.)\n- Maps content to appropriate PromptScript blocks (@identity, @standards, etc.)\n- Generates a valid `.prs` file with `@meta` block\n- Preserves the original intent and structure\n\nSupported source formats:\n\n- `CLAUDE.md` (Claude Code)\n- `.github/copilot-instructions.md` (GitHub Copilot)\n- `.cursorrules` or `.cursor/rules/*.mdc` (Cursor)\n- `AGENTS.md` (Factory AI / Codex)\n- `.clinerules` (Cline), `.roorules` (Roo Code)\n- `.windsurf/rules/*.md` (Windsurf)\n- Any Markdown-based AI instruction file\n\n### Manual Migration\n\nFor complex migrations or when `prs import` needs refinement:\n\n| Source Pattern                      | PromptScript Block |\n| ----------------------------------- | ------------------ |\n| \"You are...\" persona text           | `@identity`        |\n| Project description, tech stack     | `@context`         |\n| Coding conventions, style rules     | `@standards`       |\n| \"Never...\", \"Always...\", hard rules | `@restrictions`    |\n| `/command` definitions              | `@shortcuts`       |\n| Skill/tool definitions              | `@skills`          |\n| Agent/subagent configs              | `@agents`          |\n| Reference docs, API specs           | `@knowledge`       |\n\nAfter import, split into modular files (`context.prs`, `standards.prs`, etc.)\nand compose with `@use` in `project.prs`. Run `prs validate --strict` then\n`prs compile` to verify output matches the original.\n";
+export declare const PROMPTSCRIPT_SKILL_CONTENT = "---\nname: promptscript\ndescription: >-\n  PromptScript language expert for reading, writing, modifying, and\n  troubleshooting .prs files. Use when working with PromptScript syntax,\n  creating or editing .prs files, adding blocks like @identity, @standards,\n  @restrictions, @shortcuts, @skills, or @agents, configuring\n  promptscript.yaml, resolving compilation errors, understanding inheritance\n  (@inherit), composition (@use, @extend, @override), contextual @header\n  metadata, or migrating AI instructions\n  to PromptScript. Also use when asked about the 50 built-in compilation\n  targets, including GitHub Copilot, Claude Code, Cursor, Antigravity,\n  Factory AI, and AGENTS.md-based platforms.\nlicense: MIT\nmetadata:\n  author: PromptScript\n  homepage: https://getpromptscript.dev\ncompatibility:\n  - claude-code\n  - github-copilot\n  - cursor\n  - factory-ai\n  - gemini-cli\n  - opencode\n  - windsurf\n  - cline\n  - roo\n  - codex\n  - continue\n  - augment\n  - goose\n  - kilo\n  - amp\n  - trae\n  - junie\n  - kiro-cli\nallowed-tools:\n  - Read\n  - Write\n  - Glob\n  - Grep\n  - Bash\nuser-invocable: true\n---\n\n# PromptScript Language Guide\n\nPromptScript is a domain-specific language that compiles `.prs` files into native instruction formats for AI coding assistants (GitHub Copilot, Claude Code, Cursor, Antigravity, Factory AI, OpenCode, Gemini CLI). One source of truth, multiple outputs.\n\n## File Structure\n\nA `.prs` file contains ordered declarations. Syntax `1.5.0` applies `@inherit`,\n`@use`, local blocks, `@extend`, and `@override` in source order. Put `@meta`\nfirst.\n\n```\n# Comments start with #\n\n@meta { ... }           # Required metadata\n@inherit @path          # Single inheritance (optional)\n@use @path [as alias]   # Imports/mixins (optional, multiple)\n\n@identity { ... }       # AI persona\n@context { ... }        # Project context\n@standards { ... }      # Coding conventions\n@restrictions { ... }   # Hard rules\n@shortcuts { ... }      # Command aliases\n@knowledge { ... }      # Reference documentation\n@skills { ... }         # Reusable skill definitions\n@agents { ... }         # Subagent definitions\n@workflows { ... }      # Repeatable agent procedures\n@examples { ... }       # Few-shot input/output examples (syntax 1.2.0+)\n@params { ... }         # Template parameters\n@guards { ... }         # File globs and priorities\n@hooks { ... }          # Portable lifecycle hooks (syntax 1.4.0+)\n@mcpServers { ... }     # MCP server configurations (syntax 1.4.0+)\n@plugins { ... }        # Capability bundles (syntax 1.4.0+)\n@local { ... }          # Private config (not committed)\n@extend path { ... }    # Modify imported blocks\n@override path { ... }  # Replace one complete existing target (syntax 1.5.0+)\n@custom-name { ... }    # Arbitrary named blocks\n```\n\nContextual `@header` entries appear inside supported owner blocks, not at the\ntop level.\n\n## Content Types\n\nPromptScript has four canonical content shapes inside blocks:\n\n### Text Content\n\nUse triple quotes (three double-quote characters) to wrap multiline text.\nText is automatically dedented - leading whitespace from source indentation is stripped.\nUse for prose, markdown, or freeform content.\n\nExample: `@identity` with a text block describing an AI persona starting with \"You are...\"\n\n### Object Content (key-value pairs)\n\n```\n@context {\n  project: \"My App\"\n  team: \"Frontend\"\n  monorepo: {\n    tool: \"Nx\"\n    packageManager: \"pnpm\"\n  }\n}\n```\n\nValues can be strings (quoted or unquoted), numbers, booleans, nested objects, or arrays.\n\n### Array Content\n\n```\n@standards {\n  code: [\n    \"Use strict TypeScript\",\n    \"Named exports only\"\n  ]\n}\n\n@restrictions {\n  - \"Never use any type\"\n  - \"Never commit secrets\"\n}\n```\n\n### Mixed Content\n\nBlocks can contain both object properties and text in the same block.\nPlace the triple-quoted text block alongside key-value pairs.\n\n## Block Reference\n\n### @meta (required)\n\n```\n@meta {\n  id: \"project-id\"        # Required: unique identifier\n  syntax: \"1.0.0\"         # Required: syntax version (semver)\n  org: \"Company Name\"     # Optional\n  team: \"Frontend\"        # Optional\n  tags: [react, ts]       # Optional\n  params: {               # Optional: template parameters\n    projectName: string\n    port: number = 3000\n    debug?: boolean\n    framework: enum(\"react\", \"vue\") = \"react\"\n  }\n}\n```\n\n### @identity\n\nDefines AI persona. Start with \"You are...\" for consistent output across all formatters.\nContains a triple-quoted text block with the persona description.\n\n### @context\n\nProject context with structured properties (project, team, languages, runtime)\nplus optional triple-quoted text for architecture details, diagrams, etc.\n\n### @standards\n\nCategory-based conventions. Any category name is valid:\n\n```\n@standards {\n  typescript: [\"Strict mode\", \"No any type\"]\n  naming: [\"Files: kebab-case.ts\", \"Classes: PascalCase\"]\n  git: {\n    format: \"Conventional Commits\"\n    types: [feat, fix, docs, refactor, test, chore]\n  }\n}\n```\n\nCategory names are arbitrary. `@standards` can also contain free-form text:\n\n```\n@standards {\n  \"\"\"\n  ## Formatting\n  Preserve heading structure and use four-space indentation.\n\n  ## Testing\n  Add regression coverage for every behavior change.\n  \"\"\"\n  typescript: [\"Strict mode\", \"Named exports only\"]\n  git: {\n    format: \"Conventional Commits\"\n  }\n}\n```\n\nFree-form text is dedented and rendered with its Markdown heading structure. Factory\nmonolith output nests it under `Conventions & Patterns`; split Factory rules adjust\nheading levels relative to the generated section. Custom structured categories remain\navailable to formatters that support them.\n\n### @restrictions\n\nHard rules as a list of dash-prefixed strings:\n\n```\n@restrictions {\n  - \"Never expose API keys\"\n  - \"Never commit secrets to version control\"\n  - \"Always validate user input\"\n}\n```\n\n### @shortcuts\n\nSimple strings appear as documentation. Objects with `prompt: true` generate\nexecutable prompt/command files for GitHub Copilot and Cursor:\n\n```\n@shortcuts {\n  \"/review\": \"Review code for quality\"\n  \"/test\": {\n    prompt: true\n    description: \"Write unit tests\"\n    content: (triple-quoted text with instructions)\n  }\n}\n```\n\n> `@commands` is a backwards-compatible alias for `@shortcuts` \u2014 prefer `@shortcuts` in new files.\n\n### @skills\n\nReusable skill definitions with metadata:\n\n```\n@skills {\n  commit: {\n    description: \"Create git commits\"\n    trigger: \"commit, git commit\"\n    disableModelInvocation: true\n    userInvocable: true\n    allowedTools: [\"Bash\", \"Read\"]\n    content: (triple-quoted text with skill instructions)\n  }\n}\n```\n\nProperties: description (required), content (required), trigger, disableModelInvocation,\nuserInvocable, allowedTools, context (\"fork\" or \"inherit\"), agent, model (Claude Code and Grok\nBuild, mapped through the model catalog), requires, references, inputs, outputs.\n\nThe `references` property attaches external files to the skill's context:\n\n```\n@skills {\n  architecture-review: {\n    description: \"Review architecture decisions\"\n    references: [\n      ./references/architecture.md\n      ./references/modules.md\n    ]\n    content: (triple-quoted text)\n  }\n}\n```\n\nAllowed file types: `.md`, `.json`, `.yaml`, `.yml`, `.txt`, `.csv`. Paths are resolved relative\nto the `.prs` file. Formatters emit referenced files alongside SKILL.md in the output directory.\n\n### Parameterized Skills\n\nSkills in `.promptscript/skills/<name>/SKILL.md` support template parameters via\nYAML frontmatter. Define `params` in frontmatter and use `{{variable}}` in content:\n\n```yaml\n---\nname: review\ndescription: 'Review {{language}} code for {{standard}}'\nparams:\n  language:\n    type: string\n  standard:\n    type: string\n    default: 'best practices'\nreferences:\n  - references/architecture.md\n---\nReview the code using {{language}} conventions following {{standard}}.\n```\n\nThe `references` field in SKILL.md frontmatter lists files to attach to the skill's context.\nPaths are relative to the SKILL.md file.\n\nImported SKILL.md frontmatter is bounded: 256 KiB per document, 10,000 YAML nodes, 32 nesting\nlevels, 2,000 entries per mapping or sequence, and 64 KiB per string value. Documents over any\nlimit are rejected before their YAML values are converted.\n\nPass values in `@skills` block:\n\n```\n@skills {\n  review: {\n    description: \"Review code\"\n    language: \"typescript\"\n    standard: \"strict mode\"\n  }\n}\n```\n\nNon-reserved properties (anything other than description, content, trigger,\nuserInvocable, allowedTools, disableModelInvocation, context, agent, requires,\ninputs, outputs, model) are treated as skill parameter arguments.\n\n### Skill Dependencies\n\nSkills can declare dependencies on other skills via `requires`:\n\n```\n@skills {\n  deploy: {\n    description: \"Deploy service\"\n    requires: [\"lint-check\", \"test-suite\"]\n    content: (triple-quoted text)\n  }\n}\n```\n\nThe validator (PS016) checks that required skills exist, detects self-references,\nand catches circular dependency chains.\n\n### Skill Contracts (Inputs/Outputs)\n\nSkills can declare typed inputs and outputs in SKILL.md frontmatter:\n\n```yaml\n---\nname: security-scan\ndescription: 'Scan for vulnerabilities'\ninputs:\n  files:\n    description: 'Files to scan'\n    type: string\n  severity:\n    description: 'Minimum severity'\n    type: enum\n    options: [low, medium, high]\n    default: medium\noutputs:\n  report:\n    description: 'Scan report'\n    type: string\n  passed:\n    description: 'Whether scan passed'\n    type: boolean\n---\n```\n\nField types: `string`, `number`, `boolean`, `enum` (with `options` list).\nThe validator (PS017) checks field types, ensures enum fields have options,\nand warns if param names collide with input names.\n\n### Shared Resources\n\nSkills in a folder can share common resources via `.promptscript/shared/`:\n\n```\n.promptscript/\n  shared/\n    templates.md         # Shared across all skills\n    style-guide.md\n  skills/\n    review/\n      SKILL.md           # Gets @shared/templates.md, @shared/style-guide.md\n    deploy/\n      SKILL.md           # Also gets shared resources\n```\n\nFiles in `shared/` are automatically included in every skill with `@shared/` prefix.\n\n### @agents\n\nCustom subagent definitions. Compiles to `.claude/agents/` for Claude Code,\n`.github/agents/` for GitHub Copilot, `.factory/droids/` for Factory AI, etc.\n\n```\n@agents {\n  code-reviewer: {\n    description: \"Reviews code quality\"\n    tools: [\"Read\", \"Grep\", \"Glob\", \"Bash\"]\n    model: \"sonnet\"\n    permissionMode: \"default\"\n    content: (triple-quoted text with agent instructions)\n  }\n}\n```\n\nImported agent definitions are qualified by an aliased `@use`:\n\n```\n@use ./frontend-team as frontend\n@use ./backend-team as backend\n```\n\nIf both imports define `reviewer`, the resolved names are `frontend.reviewer` and\n`backend.reviewer`. Unique unaliased imports keep their original names. Conflicting unaliased\ndefinitions stop compilation with source and import diagnostics instead of silently overwriting\none another. Native targets map dots to hyphens, so `frontend.reviewer` becomes\n`frontend-reviewer`.\n\nSupports mixed models per agent: `specModel` sets a different model for\nSpecification/planning mode (GitHub, Factory), `specReasoningEffort` sets reasoning\neffort for the spec model (Factory only, values: \"low\", \"medium\", \"high\").\n\nFactory AI droids support additional properties: `model` (any model ID or \"inherit\"),\n`reasoningEffort` (\"low\", \"medium\", \"high\"), and `tools` (category name like \"read-only\"\nor array of tool IDs).\n\nAgent `model`/`specModel` and skill `model` values resolve against the model catalog\n(built-in profiles plus `models.profiles` in promptscript.yaml). Write a floating alias\n(`sonnet`, `opus`, `haiku`, `fable` - newest Claude release), a pinned model (profile id,\nalias, API id, or display name such as `claude-opus-5-5` or `Claude Opus 5.5`), or\n`inherit`. Each target gets its native name: Claude Code keeps aliases and uses API ids\nfor pinned Claude models, GitHub Copilot gets display names (`Claude Sonnet 5`), Factory\nAI and Codex get API ids, and Cursor gets dateless ids. Names outside the catalog pass\nthrough unchanged, unless the target has its own spelling for them (GitHub Copilot writes\n`auto` as `Auto`). A model from a provider the target cannot run (a GPT model on Claude\nCode, a Claude model on Codex), or a name with a line break or control character, is\nomitted with a PS4004 warning.\n\n### @workflows\n\nRepeatable multi-step agent procedures. Requires syntax `1.1.0`.\n\n```\n@workflows {\n  release: {\n    description: \"Prepare a validated release\"\n    content: \"\"\"\n      1. Run formatting, linting, type checks, and tests.\n      2. Validate compiled output.\n      3. Stop before publishing and request approval.\n    \"\"\"\n  }\n}\n```\n\nTargets with native workflow discovery emit dedicated workflow files. Other targets\nretain workflow instructions in their main output when supported.\n\n### @examples\n\nStructured few-shot examples for AI assistants (requires syntax `1.2.0`):\n\n```\n@meta {\n  id: \"commit-style\"\n  syntax: \"1.2.0\"\n}\n\n@examples {\n  feat-commit: {\n    description: \"Feature commit with scope\"\n    input: \"Added user authentication with JWT tokens\"\n    output: \"feat(auth): add JWT-based user authentication\"\n  }\n}\n```\n\nEach entry is a named example with `input` and `output` (both required),\nplus optional `description`. Multi-line content uses triple-quoted strings.\n\nExamples can also be attached to skills via the `examples` property:\n\n```\n@skills {\n  commit: {\n    description: \"Create conventional commits\"\n    examples: {\n      basic: {\n        input: \"Added dark mode toggle\"\n        output: \"feat(settings): add dark mode toggle\"\n      }\n    }\n    content: (triple-quoted text)\n  }\n}\n```\n\n### @knowledge\n\nReference documentation as triple-quoted text. Used for command references,\nAPI docs, and other material that should appear in the output.\n\n### @params\n\nTemplate parameter definitions with types: string, number, boolean, enum(\"a\", \"b\").\nOptional parameters use `?` suffix. Defaults use `= value`.\n\n### @guards\n\nFile glob patterns and priority rules for path-specific instructions.\n\n### @hooks\n\nPortable lifecycle hooks. Requires syntax `1.4.0`. Each hook needs exactly one of\n`command` or `script`.\n\n```\n@hooks {\n  validate-types: {\n    event: \"post-tool-use\"\n    matcher: \"Edit|Write\"\n    script: {\n      path: \".promptscript/scripts/validate.py\"\n      interpreter: \"python3\"\n      args: [\"--strict\"]\n    }\n    cwd: \"project\"\n    timeoutMs: 120000\n    statusMessage: \"Checking TypeScript\"\n    continueOnFailure: false\n    enabled: true\n    targets: {\n      factory: { matcher: \"Execute\" }\n      vscode: { matcher: \"run_in_terminal\" }\n      github: { enabled: false }\n    }\n  }\n}\n```\n\nPortable events:\n\n| Event                  | Meaning                   |\n| ---------------------- | ------------------------- |\n| `pre-terminal-command` | Before a terminal command |\n| `pre-tool-use`         | Before a tool invocation  |\n| `post-tool-use`        | After a tool invocation   |\n| `session-start`        | Agent session start       |\n| `setup`                | Session setup             |\n| `subagent-start`       | Subagent start            |\n| `notification`         | Agent notification        |\n| `stop`                 | Agent stop                |\n\n`command` is a non-empty string array. Shell interpolation (`$()`, backticks,\n`${...}`) is forbidden. `script` requires:\n\n- `path` under `.promptscript/scripts/`, using forward slashes.\n- Existing regular file at compile time.\n- No traversal, absolute path, invalid segment, or symlink escape.\n- Explicit interpreter: `python3`, `python`, `node`, `deno`, `bun`, `ruby`, `php`,\n  `perl`, `bash`, `sh`, `zsh`, `pwsh`, or `powershell`.\n- Optional `args` string array; each argument remains one argument.\n\n`cwd: \"project\"` runs from project root. Other values are portable forward-slash\npaths relative to project root. Hook config file location does not set command cwd.\nEnvironment-root and Git-root wrappers exit before script or command execution when\nthe required root is unavailable. Native-cwd and workspace-cwd targets retain host\ncwd fields and report `PS4002` when PromptScript cannot verify that cwd.\n`timeoutMs` range is 100-600000. `matcher` uses target-native tool names, so a\nmatcher valid for one target may match nothing on another.\n\n`pre-terminal-command` supplies native defaults: Factory `Execute`, Claude and\nCodex `Bash`, Windsurf `pre_run_command`, Cursor `run_terminal_cmd`, Gemini\n`run_shell_command`, and VS Code `run_in_terminal`. Override a native tool name\nwith `targets.<name>.matcher`. Cursor, Gemini, and VS Code report best-effort\n`PS4002` warnings. GitHub and Grok omit the event with `PS4002`.\n\nTarget overrides may change `event`, `matcher`, `timeoutMs`, `statusMessage`,\n`continueOnFailure`, `enabled`, or `cwd`. Native hook files are emitted only in\ntarget modes that support additional files:\n\n| Target         | Hook output                                                            | Mode                |\n| -------------- | ---------------------------------------------------------------------- | ------------------- |\n| Claude Code    | `.claude/settings.json`                                                | `full`              |\n| Factory AI     | `.factory/hooks.json`                                                  | `multifile`, `full` |\n| GitHub Copilot | `.github/hooks/promptscript.json`                                      | `multifile`, `full` |\n| Cursor         | `.cursor/hooks.json`                                                   | `full`              |\n| Codex          | `.codex/hooks.json`                                                    | `multifile`, `full` |\n| Gemini CLI     | `.gemini/settings.json`                                                | `multifile`, `full` |\n| Windsurf       | `.windsurf/hooks.json`                                                 | `multifile`, `full` |\n| Grok Build     | `.grok/hooks/promptscript.json`                                        | `full`              |\n| OpenCode       | `.opencode/plugins/promptscript.ts` (generated plugin)                 | `multifile`, `full` |\n| VS Code Agent  | `.github/hooks/promptscript-vscode.json` when `vscode` override exists | target-specific     |\n\nOpenCode starts generated hook commands asynchronously. It enforces authored\ntimeouts or a 30-second default, then escalates from `SIGTERM` to `SIGKILL`.\nPayloads are bounded by UTF-8 byte length. OpenCode tool hooks expose tool\narguments, session ID, and call ID, but no model or agent context; compilation\nreports that limitation with `PS4002`.\n\nSimple mode and targets without native project hooks report `PS4002` instead of\nsilently dropping hooks. Use `prs compile --watch` as fallback. Plugin-only and\nagent-scoped integrations are not emitted as universal project hooks.\n\nEach generated command carries a PromptScript ownership marker. CLI cleanup removes\nonly marked entries and preserves user hooks/settings. Removing `@hooks` removes a\nfully owned generated hook file and prunes directories left empty. `prs hooks install factory`\nmigrates unambiguous legacy hooks from `.factory/settings.json`; ambiguous\nentries remain for manual review.\n\nFactory compilation performs the same migration when `.factory/hooks.json` is\nabsent. Use `prs compile --dry-run` to preview the changes or\n`--no-migrate-factory-hooks` to keep warning-only behavior. Unknown events,\nmalformed entries, and mixed ownership abort without a partial migration.\n\n`@hooks` compilation is separate from `prs hooks install`. The latter installs\nauto-compilation and generated-output protection for supported AI tools. Copilot VS\nCode Agent hooks use `promptscript-vscode.json`; GitHub Copilot repository hooks use\n`promptscript.json`.\n\n### @mcpServers\n\nProject-local Model Context Protocol servers. Requires syntax `1.4.0`.\n\n```\n@mcpServers {\n  issue-tracker: {\n    transport: \"stdio\"\n    command: [\"node\", \"./tools/issues.mjs\"]\n    env: { LOG_LEVEL: \"info\" }\n  }\n}\n```\n\nUse `stdio` with `command`, or `http`/`sse` with `url`. Keep credentials out of\n`.prs` files and provide them through target-native secret management.\n\n### @plugins\n\nPortable capability bundles. Requires syntax `1.4.0`.\n\n```\n@plugins {\n  security-suite: {\n    description: \"Security review tooling\"\n    version: \"1.0.0\"\n    skills: [\"security-review\"]\n    hooks: [\"validate-types\"]\n    mcpServers: [\"issue-tracker\"]\n  }\n}\n```\n\n### @local\n\nPrivate local configuration. Not included in compiled output or committed to git.\n\n## Inheritance and Composition\n\n### @inherit (single, linear)\n\nOne per file. Child blocks merge on top of parent:\n\n```\n@inherit @company/frontend-team\n@inherit ./parent\n@inherit @stacks/react-app(projectName: \"my-app\", port: 3000)\n```\n\n### @use (multiple, mixins)\n\nImport and merge fragments:\n\n```\n@use @core/security\n@use @core/quality\n@use ./local-config\n@use @core/typescript as ts   # alias enables @extend access\n```\n\n#### URL imports (Go-module style)\n\nImport directly from any Git repository by host path - no alias required:\n\n```\n@use github.com/acme/shared-standards/@fragments/security\n@use gitlab.com/myorg/prompts/@stacks/python\n```\n\nVersion pinning with `@`:\n\n```\n@use github.com/acme/shared-standards/@org/base@1.2.0    # exact version\n@use github.com/acme/shared-standards/@org/base@^1.0.0   # semver range\n@use github.com/acme/shared-standards/@org/base@main     # branch\n```\n\n#### Registry aliases\n\nShort names for Git repository URLs, configured in `promptscript.yaml`:\n\n```yaml\nregistries:\n  company:\n    url: github.com/acme/promptscript-registry\n```\n\nThen use the alias as scope prefix:\n\n```\n@use @company/security\n@inherit @company/base-config\n```\n\nMerge rules:\n\n- Text: concatenated with deduplication\n- Objects: deep merged (imported source wins same-shape conflicts)\n- Arrays: unique concatenation\n- Shape mismatch: existing target body wins\n\nUnder syntax `1.5.0`, later local blocks, `@extend`, and `@override`\noperations apply to the accumulated import result in declaration order.\n\n### Block Filtering\n\nControl which blocks are imported using the reserved `only` and `exclude` parameters:\n\n```\n@use ./shared-config(only: [\"skills\", \"context\"])\n@use ./shared-config(exclude: [\"knowledge\"])\n@use ./shared-config(exclude: [\"knowledge\"], mode: \"strict\")\n```\n\nRules:\n\n- `only` and `exclude` are mutually exclusive \u2014 using both is a validation error (PS021)\n- Values are block type names: `identity`, `context`, `standards`, `knowledge`, `skills`, `shortcuts`, `agents`, etc.\n- Block filtering does not apply to `@inherit` directives\n\n### Markdown Imports\n\nImport skills directly from `.md` files (v1.8+). No external tools needed:\n\n```\n@use ./skills/frontend-design.md\n@use ./shared/commit.md as commit\n@use github.com/anthropics/skills/commit@1.0.0\n@use github.com/repo/skills/gitnexus         # directory \u2192 SKILL.md\n```\n\nContent detection: PromptScript blocks in `.md` are parsed as a `.prs` fragment;\nYAML frontmatter with `name`/`description` is loaded as a skill definition;\notherwise content is treated as free-form knowledge.\n\nCLI management:\n\n```\nprs skills add github.com/anthropics/skills/commit@1.0.0\nprs skills remove commit\nprs skills list\nprs skills update\n```\n\n### @extend (modify existing or imported blocks)\n\nUse a direct path for inherited or local blocks:\n\n```\n@extend standards.testing {\n  coverage: 95\n}\n```\n\nUse an alias when targeting a specific imported block:\n\n```\n@use @core/typescript as ts\n\n@extend ts.standards {\n  testing: { coverage: 95 }\n}\n```\n\n#### Replacing regular block fields\n\nSyntax `1.3.0` supports explicit replacement of complete regular block field values:\n\n```\n@meta { id: \"project\" syntax: \"1.3.0\" }\n\n@inherit ./company-base\n\n@extend standards {\n  testing!: [\"Use Vitest\"]\n  linting: [\"Use ESLint\"]\n}\n```\n\n`testing!` replaces the inherited value. Fields without `!` keep normal merge behavior.\nReplacement works after `@inherit` and `@use`, including aliases and nested target paths.\nA missing field is set. The modifier is rejected for `@skills`, which retain their dedicated\nmerge and sealing semantics.\n\n#### Replacing complete targets with @override\n\nSyntax `1.5.0` adds atomic replacement for an existing block or nested value:\n\n```\n@meta { id: \"project\" syntax: \"1.5.0\" }\n\n@standards {\n  testing: [\"Use Jest\", \"Use Mocha\"]\n}\n\n@override standards.testing {\n  [\"Use Vitest\"]\n}\n```\n\n`@override` requires the complete target path to exist, applies in declaration\norder, and cannot bypass sealed skill properties. Later `@extend` declarations\nmerge into the replacement. Use `@extend` for additive changes, `field!` for\ncompatibility replacement of one direct regular field, and `@override` for\nintentional complete replacement.\n\n#### Skill-aware @extend semantics\n\nWhen extending a skill definition via `@extend`, individual skill properties follow specific merge\nstrategies rather than the generic block merge rules:\n\n| Strategy          | Properties                                                                                                  |\n| ----------------- | ----------------------------------------------------------------------------------------------------------- |\n| **Replace**       | content, description, trigger, userInvocable, allowedTools, disableModelInvocation, context, agent, license |\n| **Append**        | references, examples, requires                                                                              |\n| **Shallow merge** | params, inputs, outputs                                                                                     |\n\nExample \u2014 extending a base skill to add references and override content:\n\n```\n@use @company/skills as skills\n\n@extend skills.code-review {\n  content: (triple-quoted text with overridden instructions)\n  references: [\n    ./extra-context.md\n  ]\n}\n```\n\nThe `references` array from the base skill and the overlay are combined (append). The `content`\nfield from the overlay replaces the base (replace).\n\n#### Reference negation\n\nUse `!` prefix in `@extend` to remove entries from a lower layer's append-strategy arrays:\n\n```\n@extend skills.code-review {\n  references: [\n    \"!references/deprecated.md\"\n    \"references/replacement.md\"\n  ]\n}\n```\n\nPath matching is normalized (`\"!./foo.md\"` matches `\"foo.md\"`). Only works in `@extend` blocks\non `references` and `requires`. Validator PS028 warns about `!` in base definitions.\n\n#### Overlay consistency warnings\n\nThe resolver emits warnings during compile when an overlay drifts from its base. Always shown\n(not gated by `--verbose`):\n\n- **Orphaned extend** \u2014 `@extend target \"X\" not found \u2014 overlay will be ignored.` Triggered when\n  the targeted block doesn't exist (base removed or renamed).\n- **Stale skill target** \u2014 `@extend creates new skill \"X\" \u2014 base does not define it.` Triggered\n  when an `@extend` inside `@skills` would create a new skill instead of extending an existing one.\n- **Negation orphan** \u2014 `Negation \"!path\" did not match any base entry \u2014 it may be stale.`\n  Triggered when a `!entry` in references/requires doesn't match anything in the base.\n\nThese come from the resolver, not the validator (PS0XX rules). They appear during `prs compile`,\nnot `prs validate`.\n\n#### Sealed properties\n\nPrevent `@extend` from overriding specified replace-strategy properties:\n\n```\n@skills {\n  deploy: {\n    content: (triple-quoted text with critical workflow)\n    sealed: [\"content\", \"description\"]\n  }\n}\n```\n\n`sealed: true` seals all replace-strategy properties. Attempting to override a sealed\nproperty is a hard compilation error. Only the base skill author can set `sealed` \u2014\noverlays cannot add or modify it. Append-strategy properties remain extendable.\nValidator PS029 warns about invalid entries in `sealed`.\n\n#### Skill composition (inline @use)\n\nImport sub-skills within a `@skills` block to compose multi-phase workflows:\n\n```\n@skills {\n  ops: {\n    description: \"Production triage\"\n    content: (triple-quoted text with orchestrator instructions)\n  }\n  @use ./phases/health-scan\n  @use ./phases/triage\n  @use ./phases/code-fix as autofix\n}\n```\n\nEach `@use` resolves the referenced `.prs` file, extracts its skill definition and context\nblocks, and flattens them as numbered phase sections into the parent skill's content. The\n`as alias` form controls the phase display name. Validator PS027 checks composition validity.\n\n### Parameterized Inheritance (Template Variables)\n\nUse `{{variable}}` placeholders in a **parent/template** file, and pass values\nfrom the **child** file via `@inherit` or `@use` with `(key: value)` syntax.\n\n**IMPORTANT:** Variables are NOT set from `promptscript.yaml` or CLI. They are\npassed from one `.prs` file to another through `@inherit` or `@use`.\n\n**Step 1: Create the template** (parent file with `params` in `@meta`):\n\n```\n# base.prs - reusable template\n@meta {\n  id: \"service-template\"\n  syntax: \"1.0.0\"\n  params: {\n    serviceName: string\n    port?: number = 3000\n  }\n}\n\n@identity {\n  \"\"\"\n  You are working on {{serviceName}} running on port {{port}}.\n  \"\"\"\n}\n```\n\n**Step 2: Inherit with values** (child file passes params):\n\n```\n# project.prs - concrete project\n@meta { id: \"user-api\" syntax: \"1.0.0\" }\n\n@inherit ./base(serviceName: \"user-api\", port: 8080)\n```\n\nAfter compilation, `{{serviceName}}` becomes `user-api` and `{{port}}` becomes `8080`.\n\nThe same works with `@use`:\n\n```\n@use ./base(serviceName: \"auth-service\") as auth\n```\n\n**Parameter types:** `string`, `number`, `boolean`, `enum(\"a\", \"b\")`.\nOptional params use `?` suffix. Defaults use `= value`.\nMissing required params produce a compile error.\n\n**Multi-service pattern** - reuse one template across many projects:\n\n```\nservices/\n  base.prs                          # template with params\n  user-api/\n    promptscript.yaml               # source: project.prs\n    project.prs                     # @inherit ../base(serviceName: \"user-api\")\n  auth-service/\n    promptscript.yaml\n    project.prs                     # @inherit ../base(serviceName: \"auth-service\")\n```\n\n## Configuration: promptscript.yaml\n\n### Auto-injection\n\nThis skill is automatically included when compiling with `prs compile`. No manual copying needed.\nTo disable, set `includePromptScriptSkill: false` in your `promptscript.yaml`.\n\n```\nid: my-project\nsyntax: \"1.1.0\"\ndescription: \"My project description\"\ninput:\n  entry: .promptscript/project.prs\n  include: ['.promptscript/**/*.prs']\ntargets:\n  github:\n    version: full      # simple | multifile | full\n  claude:\n    version: full\n  cursor:\n    version: standard\n  antigravity:\n    version: frontmatter\n  factory:\n    version: full\n  windsurf:             # 41 additional targets supported\n    version: simple\n  cline:\n    version: simple\nregistry:\n  git: https://github.com/org/registry.git\n  ref: main\nregistries:\n  company:\n    url: github.com/acme/promptscript-registry\n  oss:\n    url: github.com/prscrpt/community-registry\n    ref: v2\npolicies:\n  - name: adjacent-layers-only\n    kind: layer-boundary\n    severity: error\n    layers: ['@core', '@team', '@project']\n    maxDistance: 1\nmodels:\n  supported: [opus, sonnet, gpt-5.3-codex]  # PS041 reports models outside this set\n  profiles:                                 # add models or override built-in profiles\n    claude-opus-9:\n      provider: anthropic\n      family: claude-opus                   # joins the family, so `opus` now resolves here\n      version: '9'\n      displayName: Claude Opus 9\n      targets:\n        github: Claude Opus 9 (Preview)     # per-target name always wins\n```\n\n### Lockfile: `promptscript.lock`\n\nWhen remote imports are used, run `prs lock` to generate or update the lockfile\nbefore compilation. It records the exact resolved commit for each dependency.\nIntegrity hashes (SHA-256) are included for registry references to detect\ntampering or drift. This enables reproducible builds across machines and CI.\nCommit `promptscript.lock` to version control.\n\nUse `--ignore-hashes` on `prs compile` or `prs validate` to skip integrity\nhash verification when needed.\n\n### Policy Engine\n\nDefine organizational policies in `promptscript.yaml` to validate skill extensions:\n\n```yaml\npolicies:\n  - name: adjacent-layers-only\n    kind: layer-boundary\n    description: 'Only adjacent layers can extend each other'\n    severity: error\n    layers: ['@core', '@team', '@project']\n    maxDistance: 1\n\n  - name: protect-content\n    kind: property-protection\n    description: 'Content override requires explicit approval'\n    severity: warning\n    properties: ['content', 'description']\n\n  - name: approved-registries\n    kind: registry-allowlist\n    description: 'Extensions must come from approved registries'\n    severity: error\n    allowed: ['@core', '@team']\n```\n\nPolicy kinds: `layer-boundary` (controls layer distance), `property-protection`\n(prevents overriding specific properties), `registry-allowlist` (restricts extension sources).\nSeverity: `error` (fails validation) or `warning` (reported only).\nSkip with `--skip-policies` during development (never in CI).\n\n## Syntax Version Validation\n\nThe `syntax` field in `@meta` declares the PromptScript language version (semver).\n\n### Known Versions\n\n| Version | What it adds                                                                                                            |\n| ------- | ----------------------------------------------------------------------------------------------------------------------- |\n| `1.0.0` | Core blocks (identity, context, standards, restrictions, knowledge, shortcuts, commands, guards, params, skills, local) |\n| `1.1.0` | Adds `@agents` and `@workflows`; reserves internal `@prompts`                                                           |\n| `1.2.0` | Adds `@examples` (few-shot input/output pairs)                                                                          |\n| `1.3.0` | Adds explicit regular block field replacement in `@extend`                                                              |\n| `1.4.0` | Adds `@hooks`, `@mcpServers`, and `@plugins`                                                                            |\n| `1.5.0` | Adds `@header` section titles, `@override` replacement, and unquoted `${VAR}` values                                    |\n\n### Block Version Requirements\n\n| Block         | Minimum Syntax Version |\n| ------------- | ---------------------- |\n| `@agents`     | `1.1.0`                |\n| `@workflows`  | `1.1.0`                |\n| `@examples`   | `1.2.0`                |\n| `@hooks`      | `1.4.0`                |\n| `@mcpServers` | `1.4.0`                |\n| `@plugins`    | `1.4.0`                |\n\nAll other built-in blocks are available from `1.0.0`.\nRegular block field replacement with `field!: value` requires syntax `1.3.0`.\nGenerated section title overrides with `@header` require syntax `1.5.0`.\nAtomic replacement with `@override` requires syntax `1.5.0`.\nUnquoted `${VAR}` references as values require syntax `1.5.0`.\n\n### Generated Section Headers\n\nUse `@header` inside a registered owner block to rename human-readable output\nsections without changing filenames, frontmatter, XML tags, or structured keys:\n\n```promptscript\n@meta { id: \"localized\" syntax: \"1.5.0\" }\n\n@standards {\n  @header \"Coding Rules\"\n  @header git-commits \"Commit Rules\"\n  code: [\"Use strict TypeScript\"]\n}\n```\n\n- `@header \"Title\"` targets the block's primary section.\n- `@header <section-key> \"Title\"` targets an owned derived section.\n- Titles must be non-empty, single-line strings.\n- Source overrides take precedence over formatter configuration and target defaults.\n- Child inheritance, imported source, and the latest root extension take precedence.\n- An initial `## Heading` in a registered text-only primary owner is a syntax\n  `1.5.0` compatibility fallback. Explicit `@header` metadata wins.\n- Ordinary `header` and `headers` fields remain domain data.\n\n### Validation Rules\n\n- **PS018 (`syntax-version-compat`)**: warns when resolved blocks or syntax features require a higher version than declared. Requirements from inheritance, imports, and skill composition are included. Suggestion: run `prs validate --fix`.\n- **PS019 (`unknown-block-name`)**: warns when a block name is not a known PromptScript type, with fuzzy-match suggestions for typos.\n- **PS037 (`valid-section-headers`)**: rejects invalid titles, unknown or unowned section keys, duplicate overrides, and nested extension overrides.\n- **PS038 (`valid-block-shape`)**: rejects unsupported built-in block shapes and warns about formatter-sensitive legacy shapes or multiline shortcut scalars.\n- **PS039 (`agent-namespaces`)**: validates qualified agent name segments and checks them against recorded import provenance.\n- **PS040 (`import-excludes`)**: errors when a `validation.excludes` entry for an import does not record the commit pinned in promptscript.lock, so consumers re-review imports whose pinned commit changed.\n- **PS041 (`valid-model-reference`)**: warns when an agent `model`/`specModel` or skill `model` resolves to a deprecated or retired model, suggesting the successor. With `models.supported` set, it also warns about models outside the set, models missing from the catalog, and unknown `models.supported` entries. It also reports `models.profiles` problems: a name shared by two profiles or taken from a floating alias or `inherit`, unknown or looping successors, dates not in `YYYY-MM-DD`, and `targets` keys for targets that write no model names.\n- **PS021 (`use-block-filter`)**: errors when `only` and `exclude` are both specified in `@use` parameters.\n- **PS025 (`valid-skill-references`)**: errors when a `references` entry points to a file with a disallowed extension or a path that cannot be resolved.\n- **PS026 (`safe-reference-content`)**: warns when a referenced file contains potentially sensitive content (e.g., secrets, credentials).\n- **PS027 (`valid-skill-composition`)**: warns about conflicting phase names or excessive phases in composed skills.\n- **PS028 (`valid-append-negation`)**: warns when negation prefix `!` appears in base skill definitions (only effective in `@extend`).\n- **PS029 (`valid-sealed-property`)**: warns when `sealed` contains non-replace-strategy property names.\n- **PS030 (`policy-compliance`)**: validates skill extensions against organizational policies defined in `promptscript.yaml`.\n- **PS034 (`valid-hooks`)**: validates portable hook events, commands/scripts, paths, interpreters, timeouts, cwd, and target overrides.\n\nTarget formatters report **PS4002** when a hook event or field has no native equivalent,\nwhen a target cannot guarantee project-root execution, or when output mode cannot emit\nthe additional hook file. They report **PS4004** when an agent or skill model comes from\na provider the target cannot run, or when its name has a line break or control character;\nthe model field is omitted for that target.\n\n### Fixing Syntax Versions\n\n```\nprs validate --fix          # Auto-fix syntax versions in .prs files\nprs upgrade                 # Upgrade all .prs files to the latest version\n```\n\n`--fix` rewrites the `syntax: \"...\"` line in each file's `@meta` block to match the minimum version required by resolved blocks and syntax features. It follows inheritance, imports, and skill composition. It only upgrades, never downgrades.\n\n`prs upgrade` upgrades all files to the latest known syntax version regardless of what blocks they use.\n\n## CLI Commands\n\n```\nprs init                    # Initialize project (auto-detects existing files)\nprs init --yes --targets claude factory\nprs init --dry-run          # Preview initialization\nprs init --auto-import      # Initialize + static import of existing files\nprs migrate                 # Interactive migration flow\nprs migrate --static        # Non-interactive static import\nprs migrate --llm           # Generate AI-assisted migration prompt\nprs migrate --static --dry-run\nprs compile                 # Compile to all targets\nprs compile --watch         # Watch mode\nprs compile --ignore-hashes # Skip integrity hash verification\nprs build <name>            # Compile a named build profile\nprs validate --strict       # Validate syntax\nprs validate --fix          # Auto-fix syntax version declarations\nprs validate --skip-policies # Skip policy engine evaluation\nprs upgrade                 # Upgrade all .prs files to latest syntax version\nprs import CLAUDE.md        # Import existing AI instructions\nprs import CLAUDE.md --dry-run # Preview import conversion\nprs inspect <skill>         # Show skill composition provenance\nprs inspect <skill> --layers # Show layer-level breakdown\nprs explain <path>          # Explain source and composition provenance\nprs explain <path> --format json # Machine-readable provenance history\nprs hooks install           # Install auto-compilation hooks for AI tools\nprs hooks install claude    # Install hooks for a specific tool\nprs hooks uninstall         # Remove installed auto-compilation hooks\nprs hooks uninstall claude  # Remove hooks for a specific tool\nprs skills add <source>     # Add a remote skill (@use + lock update + SKILL.md validation)\nprs skills add <source> --strict          # Treat validation warnings as errors\nprs skills add <source> --skip-validation # Bypass Agent Skills spec checks (not recommended)\nprs skills remove <name>    # Remove a skill (@use line + lock entry)\nprs skills list             # List all imported skills\nprs skills update           # Re-resolve markdown-imported skills (re-validates + re-hashes)\nprs pull                    # Update registry\nprs diff --target claude    # Show compilation diff\nprs diff --all --format json # Machine-readable diff report for CI\nprs diff --format json --include-content # Include generated content in the report\nprs lock                    # Generate/update promptscript.lock\nprs lock --dry-run          # Preview lockfile changes\nprs update                  # Re-resolve all remote imports to latest\nprs update <url>            # Update a specific registry\nprs vendor sync             # Copy cached deps to .promptscript/vendor/\nprs vendor check            # Verify vendor matches lockfile\nprs resolve @alias/path     # Debug: show how an import resolves\nprs registry list           # Show configured registries and aliases\nprs registry add <alias> <url>  # Add a registry alias\n```\n\n`prs init --yes` requires explicit, detected, or user-configured targets. It does not invent\ndefault tools. For existing projects, `prs migrate` preserves `promptscript.yaml`, isolates static\noutput under `.promptscript/migrated/`, leaves source instructions untouched, and performs no\nwrites when no candidates are detected.\n\n## Output Targets\n\n50 supported targets. Key examples:\n\n| Target      | Main File                       | Skills                                             |\n| ----------- | ------------------------------- | -------------------------------------------------- |\n| GitHub      | .github/copilot-instructions.md | .github/skills/\\*/SKILL.md                         |\n| Claude      | CLAUDE.md                       | .claude/skills/\\*/SKILL.md                         |\n| Cursor      | .cursor/rules/project.mdc       | .agents/skills/\\*/SKILL.md                         |\n| Antigravity | .agent/rules/project.md         | -                                                  |\n| Factory     | AGENTS.md                       | .factory/skills/\\*/SKILL.md, .factory/droids/\\*.md |\n| OpenCode    | OPENCODE.md                     | .opencode/skills/\\*/SKILL.md                       |\n| Gemini      | GEMINI.md                       | .agents/skills/\\*/skill.md                         |\n| Windsurf    | .windsurf/rules/project.md      | .windsurf/skills/\\*/SKILL.md                       |\n| Cline       | .clinerules                     | -                                                  |\n| Roo Code    | .roorules                       | -                                                  |\n| Codex       | AGENTS.md                       | .agents/skills/\\*/SKILL.md                         |\n| Continue    | .continue/rules/project.md      | -                                                  |\n| Hermes      | AGENTS.md                       | -                                                  |\n| + 37 more   |                                 | See full list in documentation                     |\n\nTargets that share an output path (for example Factory, Codex, and every AGENTS.md target) are\nreconciled in one output plan before anything is written. Identical content merges silently;\ndiffering content reports `PS4001`, where a formatter output replaces an earlier one and a\nresource or the auto-injected PromptScript skill keeps the file already planned. Paths are compared\ncase-insensitively and NFC-normalized on every platform.\n\n### Formatter Documentation\n\nFor detailed information about each formatter's output paths, supported features, quirks, and example outputs:\n\n- **Full formatter reference:** `docs/reference/formatters/` (7 dedicated pages + index of all 50)\n- **llms-full.txt:** Available at the docs site root - contains all documentation in a single file for LLM consumption\n- **Dedicated pages exist for:** Claude Code, GitHub Copilot, Cursor, Antigravity, Factory AI, Gemini CLI, OpenCode\n- **All 50 formatters indexed at:** `docs/reference/formatters/index.md` with output paths, tier, and feature flags\n\n### Auto-Compilation Hooks\n\nInstead of running `prs compile --watch` manually, install hooks so your AI tool\ntriggers compilation automatically when you edit `.prs` files:\n\n```\nprs hooks install          # Auto-detect and install for all detected tools\nprs hooks install claude   # Install for a specific tool\n```\n\nHooks also protect generated files from direct edits \u2014 when an AI agent tries\nto edit a compiled output (e.g., CLAUDE.md), the write is blocked with a message\npointing to the source `.prs` file. Supported tools: Claude Code, Factory AI,\nCursor, Windsurf, Cline, GitHub Copilot, Gemini CLI.\n\n## Project Organization\n\nTypical modular structure:\n\n```\n.promptscript/\n  project.prs      # Entry: @meta, @inherit, @use, @identity, @agents\n  context.prs      # @context (architecture, tech stack)\n  standards.prs    # @standards (coding conventions)\n  restrictions.prs # @restrictions (hard rules)\n  commands.prs     # @shortcuts and @knowledge\n```\n\nThe entry file uses `@use ./context`, `@use ./standards`, etc. to compose them.\n\n## Common Mistakes\n\n1. Missing @meta block - every .prs file needs `@meta` with `id` and `syntax`\n2. Multiple @inherit - only one per file; use `@use` for additional imports\n3. Extending an unknown path - target an inherited or local block, or use an imported alias\n4. Unquoted strings with special chars - quote strings containing `:`, `#`, `{`, `}`\n5. Forgetting to compile - `.prs` changes need `prs compile` to take effect\n6. Triple quotes inside triple quotes - not supported; describe content textually instead\n7. Using `{{var}}` in the root file without `@inherit` - template variables only work\n   in a parent file that defines `params` in `@meta`, with values passed by the child\n   via `@inherit ./parent(key: value)` or `@use ./fragment(key: value)`. They are NOT\n   set from `promptscript.yaml` or CLI flags\n8. Using `@examples` with `syntax: \"1.0.0\"` or `\"1.1.0\"` - `@examples` requires\n   syntax version `1.2.0`. Run `prs validate --fix` to auto-upgrade\n\n## Migrating Existing AI Instructions to PromptScript\n\n### Automated: `prs import`\n\nThe fastest way to convert existing AI instructions to PromptScript:\n\n```\nprs import CLAUDE.md                    # Convert a single file\nprs import .github/copilot-instructions.md\nprs import AGENTS.md --output ./imported\nprs import --dry-run CLAUDE.md          # Preview without writing\n```\n\n`prs import` automatically:\n\n- Detects the source format (Claude, GitHub Copilot, Cursor, Factory, etc.)\n- Maps content to appropriate PromptScript blocks (@identity, @standards, etc.)\n- Generates a valid `.prs` file with `@meta` block\n- Preserves the original intent and structure\n\nSupported source formats:\n\n- `CLAUDE.md` (Claude Code)\n- `.github/copilot-instructions.md` (GitHub Copilot)\n- `.cursorrules` or `.cursor/rules/*.mdc` (Cursor)\n- `AGENTS.md` (Factory AI / Codex)\n- `.clinerules` (Cline), `.roorules` (Roo Code)\n- `.windsurf/rules/*.md` (Windsurf)\n- Any Markdown-based AI instruction file\n\n### Manual Migration\n\nFor complex migrations or when `prs import` needs refinement:\n\n| Source Pattern                      | PromptScript Block |\n| ----------------------------------- | ------------------ |\n| \"You are...\" persona text           | `@identity`        |\n| Project description, tech stack     | `@context`         |\n| Coding conventions, style rules     | `@standards`       |\n| \"Never...\", \"Always...\", hard rules | `@restrictions`    |\n| `/command` definitions              | `@shortcuts`       |\n| Skill/tool definitions              | `@skills`          |\n| Agent/subagent configs              | `@agents`          |\n| Reference docs, API specs           | `@knowledge`       |\n\nAfter import, split into modular files (`context.prs`, `standards.prs`, etc.)\nand compose with `@use` in `project.prs`. Run `prs validate --strict` then\n`prs compile` to verify output matches the original.\n";
 //# sourceMappingURL=promptscript-skill.d.ts.map

package/src/generated/promptscript-skill.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"promptscript-skill.d.ts","sourceRoot":"","sources":["../../../../../packages/cli/src/generated/promptscript-skill.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,eAAO,MAAM,0BAA0B,ml/CACwv+C,CAAC"}
+{"version":3,"file":"promptscript-skill.d.ts","sourceRoot":"","sources":["../../../../../packages/cli/src/generated/promptscript-skill.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,eAAO,MAAM,0BAA0B,mvjDAC05iD,CAAC"}

package/src/services.d.ts

@@ -9,8 +9,8 @@ export interface FileSystem {
     readdir: typeof readdir;
     existsSync: typeof existsSync;
     readFileSync: typeof readFileSync;
-    rename?: typeof import('fs/promises').rename;
-    rm?: typeof import('fs/promises').rm;
+    rename?: typeof import('node:fs/promises').rename;
+    rm?: typeof import('node:fs/promises').rm;
     lstat?: (path: PathLike) => Promise<Stats>;
     realpath?: (path: PathLike) => Promise<string>;
 }

package/src/services.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"services.d.ts","sourceRoot":"","sources":["../../../../packages/cli/src/services.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC;AACvE,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAC/C,OAAO,KAAK,OAAO,MAAM,mBAAmB,CAAC;AAE7C,MAAM,WAAW,UAAU;IACzB,SAAS,EAAE,OAAO,SAAS,CAAC;IAC5B,KAAK,EAAE,OAAO,KAAK,CAAC;IACpB,QAAQ,EAAE,OAAO,QAAQ,CAAC;IAC1B,OAAO,EAAE,OAAO,OAAO,CAAC;IACxB,UAAU,EAAE,OAAO,UAAU,CAAC;IAC9B,YAAY,EAAE,OAAO,YAAY,CAAC;IAClC,MAAM,CAAC,EAAE,cAAc,aAAa,EAAE,MAAM,CAAC;IAC7C,EAAE,CAAC,EAAE,cAAc,aAAa,EAAE,EAAE,CAAC;IACrC,KAAK,CAAC,EAAE,CAAC,IAAI,EAAE,QAAQ,KAAK,OAAO,CAAC,KAAK,CAAC,CAAC;IAC3C,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,QAAQ,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;CAChD;AAED,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,OAAO,OAAO,CAAC,KAAK,CAAC;IAC5B,OAAO,EAAE,OAAO,OAAO,CAAC,OAAO,CAAC;IAChC,QAAQ,EAAE,OAAO,OAAO,CAAC,QAAQ,CAAC;IAClC,MAAM,EAAE,OAAO,OAAO,CAAC,MAAM,CAAC;CAC/B;AAED,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,UAAU,CAAC;IACf,OAAO,EAAE,YAAY,CAAC;IACtB,GAAG,EAAE,MAAM,CAAC;CACb;AAED,eAAO,MAAM,iBAAiB,EAAE,UAuB/B,CAAC;AAEF,eAAO,MAAM,cAAc,EAAE,YAS5B,CAAC;AAEF,eAAO,MAAM,qBAAqB,QAAO,WAIvC,CAAC"}
+{"version":3,"file":"services.d.ts","sourceRoot":"","sources":["../../../../packages/cli/src/services.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC;AACvE,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAC/C,OAAO,KAAK,OAAO,MAAM,mBAAmB,CAAC;AAE7C,MAAM,WAAW,UAAU;IACzB,SAAS,EAAE,OAAO,SAAS,CAAC;IAC5B,KAAK,EAAE,OAAO,KAAK,CAAC;IACpB,QAAQ,EAAE,OAAO,QAAQ,CAAC;IAC1B,OAAO,EAAE,OAAO,OAAO,CAAC;IACxB,UAAU,EAAE,OAAO,UAAU,CAAC;IAC9B,YAAY,EAAE,OAAO,YAAY,CAAC;IAClC,MAAM,CAAC,EAAE,cAAc,kBAAkB,EAAE,MAAM,CAAC;IAClD,EAAE,CAAC,EAAE,cAAc,kBAAkB,EAAE,EAAE,CAAC;IAC1C,KAAK,CAAC,EAAE,CAAC,IAAI,EAAE,QAAQ,KAAK,OAAO,CAAC,KAAK,CAAC,CAAC;IAC3C,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,QAAQ,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;CAChD;AAED,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,OAAO,OAAO,CAAC,KAAK,CAAC;IAC5B,OAAO,EAAE,OAAO,OAAO,CAAC,OAAO,CAAC;IAChC,QAAQ,EAAE,OAAO,OAAO,CAAC,QAAQ,CAAC;IAClC,MAAM,EAAE,OAAO,OAAO,CAAC,MAAM,CAAC;CAC/B;AAED,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,UAAU,CAAC;IACf,OAAO,EAAE,YAAY,CAAC;IACtB,GAAG,EAAE,MAAM,CAAC;CACb;AAED,eAAO,MAAM,iBAAiB,EAAE,UAuB/B,CAAC;AAEF,eAAO,MAAM,cAAc,EAAE,YAS5B,CAAC;AAEF,eAAO,MAAM,qBAAqB,QAAO,WAIvC,CAAC"}