factory-droid-openai 1.0.0__tar.gz

factory_droid_openai-1.0.0/.claude/skills/promptscript/SKILL.md

@@ -0,0 +1,1039 @@
+---
+# promptscript-generated: true
+name: promptscript
+description: >-
+  PromptScript language expert for reading, writing, modifying, and
+  troubleshooting .prs files. Use when working with PromptScript syntax,
+  creating or editing .prs files, adding blocks like @identity, @standards,
+  @restrictions, @shortcuts, @skills, or @agents, configuring
+  promptscript.yaml, resolving compilation errors, understanding inheritance
+  (@inherit) and composition (@use, @extend), or migrating AI instructions
+  to PromptScript. Also use when asked about the 48 built-in compilation
+  targets, including GitHub Copilot, Claude Code, Cursor, Antigravity,
+  Factory AI, and AGENTS.md-based platforms.
+license: MIT
+metadata:
+  author: PromptScript
+  homepage: https://getpromptscript.dev
+compatibility:
+  - claude-code
+  - github-copilot
+  - cursor
+  - factory-ai
+  - gemini-cli
+  - opencode
+  - windsurf
+  - cline
+  - roo
+  - codex
+  - continue
+  - augment
+  - goose
+  - kilo
+  - amp
+  - trae
+  - junie
+  - kiro-cli
+allowed-tools:
+  - Read
+  - Write
+  - Glob
+  - Grep
+  - Bash
+user-invocable: true
+---
+
+# PromptScript Language Guide
+
+PromptScript 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.
+
+## File Structure
+
+A `.prs` file is made of blocks. Order doesn't matter except `@meta` should come first by convention.
+
+```
+# Comments start with #
+
+@meta { ... }           # Required metadata
+@inherit @path          # Single inheritance (optional)
+@use @path [as alias]   # Imports/mixins (optional, multiple)
+
+@identity { ... }       # AI persona
+@context { ... }        # Project context
+@standards { ... }      # Coding conventions
+@restrictions { ... }   # Hard rules
+@shortcuts { ... }      # Command aliases
+@knowledge { ... }      # Reference documentation
+@skills { ... }         # Reusable skill definitions
+@agents { ... }         # Subagent definitions
+@examples { ... }       # Few-shot input/output examples (syntax 1.2.0+)
+@params { ... }         # Template parameters
+@guards { ... }         # File globs and priorities
+@local { ... }          # Private config (not committed)
+@extend path { ... }    # Modify imported blocks
+@custom-name { ... }    # Arbitrary named blocks
+```
+
+## Content Types
+
+PromptScript has three content types inside blocks:
+
+### Text Content
+
+Use triple quotes (three double-quote characters) to wrap multiline text.
+Text is automatically dedented - leading whitespace from source indentation is stripped.
+Use for prose, markdown, or freeform content.
+
+Example: `@identity` with a text block describing an AI persona starting with "You are..."
+
+### Object Content (key-value pairs)
+
+```
+@context {
+  project: "My App"
+  team: "Frontend"
+  monorepo: {
+    tool: "Nx"
+    packageManager: "pnpm"
+  }
+}
+```
+
+Values can be strings (quoted or unquoted), numbers, booleans, nested objects, or arrays.
+
+### Array Content
+
+```
+@standards {
+  code: [
+    "Use strict TypeScript",
+    "Named exports only"
+  ]
+}
+
+@restrictions {
+  - "Never use any type"
+  - "Never commit secrets"
+}
+```
+
+### Mixed Content
+
+Blocks can contain both object properties and text in the same block.
+Place the triple-quoted text block alongside key-value pairs.
+
+## Block Reference
+
+### @meta (required)
+
+```
+@meta {
+  id: "project-id"        # Required: unique identifier
+  syntax: "1.0.0"         # Required: syntax version (semver)
+  org: "Company Name"     # Optional
+  team: "Frontend"        # Optional
+  tags: [react, ts]       # Optional
+  params: {               # Optional: template parameters
+    projectName: string
+    port: number = 3000
+    debug?: boolean
+    framework: enum("react", "vue") = "react"
+  }
+}
+```
+
+### @identity
+
+Defines AI persona. Start with "You are..." for consistent output across all formatters.
+Contains a triple-quoted text block with the persona description.
+
+### @context
+
+Project context with structured properties (project, team, languages, runtime)
+plus optional triple-quoted text for architecture details, diagrams, etc.
+
+### @standards
+
+Category-based conventions. Any category name is valid:
+
+```
+@standards {
+  typescript: ["Strict mode", "No any type"]
+  naming: ["Files: kebab-case.ts", "Classes: PascalCase"]
+  git: {
+    format: "Conventional Commits"
+    types: [feat, fix, docs, refactor, test, chore]
+  }
+}
+```
+
+### @restrictions
+
+Hard rules as a list of dash-prefixed strings:
+
+```
+@restrictions {
+  - "Never expose API keys"
+  - "Never commit secrets to version control"
+  - "Always validate user input"
+}
+```
+
+### @shortcuts
+
+Simple strings appear as documentation. Objects with `prompt: true` generate
+executable prompt/command files for GitHub Copilot and Cursor:
+
+```
+@shortcuts {
+  "/review": "Review code for quality"
+  "/test": {
+    prompt: true
+    description: "Write unit tests"
+    content: (triple-quoted text with instructions)
+  }
+}
+```
+
+> `@commands` is a backwards-compatible alias for `@shortcuts` — prefer `@shortcuts` in new files.
+
+### @skills
+
+Reusable skill definitions with metadata:
+
+```
+@skills {
+  commit: {
+    description: "Create git commits"
+    trigger: "commit, git commit"
+    disableModelInvocation: true
+    userInvocable: true
+    allowedTools: ["Bash", "Read"]
+    content: (triple-quoted text with skill instructions)
+  }
+}
+```
+
+Properties: description (required), content (required), trigger, disableModelInvocation,
+userInvocable, allowedTools, context ("fork" or "inherit"), agent, requires, references, inputs, outputs.
+
+The `references` property attaches external files to the skill's context:
+
+```
+@skills {
+  architecture-review: {
+    description: "Review architecture decisions"
+    references: [
+      ./references/architecture.md
+      ./references/modules.md
+    ]
+    content: (triple-quoted text)
+  }
+}
+```
+
+Allowed file types: `.md`, `.json`, `.yaml`, `.yml`, `.txt`, `.csv`. Paths are resolved relative
+to the `.prs` file. Formatters emit referenced files alongside SKILL.md in the output directory.
+
+### Parameterized Skills
+
+Skills in `.promptscript/skills/<name>/SKILL.md` support template parameters via
+YAML frontmatter. Define `params` in frontmatter and use `{{variable}}` in content:
+
+```yaml
+---
+name: review
+description: "Review {{language}} code for {{standard}}"
+params:
+  language:
+    type: string
+  standard:
+    type: string
+    default: "best practices"
+references:
+  - references/architecture.md
+---
+Review the code using {{language}} conventions following {{standard}}.
+```
+
+The `references` field in SKILL.md frontmatter lists files to attach to the skill's context.
+Paths are relative to the SKILL.md file.
+
+Pass values in `@skills` block:
+
+```
+@skills {
+  review: {
+    description: "Review code"
+    language: "typescript"
+    standard: "strict mode"
+  }
+}
+```
+
+Non-reserved properties (anything other than description, content, trigger,
+userInvocable, allowedTools, disableModelInvocation, context, agent, requires,
+inputs, outputs) are treated as skill parameter arguments.
+
+### Skill Dependencies
+
+Skills can declare dependencies on other skills via `requires`:
+
+```
+@skills {
+  deploy: {
+    description: "Deploy service"
+    requires: ["lint-check", "test-suite"]
+    content: (triple-quoted text)
+  }
+}
+```
+
+The validator (PS016) checks that required skills exist, detects self-references,
+and catches circular dependency chains.
+
+### Skill Contracts (Inputs/Outputs)
+
+Skills can declare typed inputs and outputs in SKILL.md frontmatter:
+
+```yaml
+---
+name: security-scan
+description: "Scan for vulnerabilities"
+inputs:
+  files:
+    description: "Files to scan"
+    type: string
+  severity:
+    description: "Minimum severity"
+    type: enum
+    options: [low, medium, high]
+    default: medium
+outputs:
+  report:
+    description: "Scan report"
+    type: string
+  passed:
+    description: "Whether scan passed"
+    type: boolean
+---
+```
+
+Field types: `string`, `number`, `boolean`, `enum` (with `options` list).
+The validator (PS017) checks field types, ensures enum fields have options,
+and warns if param names collide with input names.
+
+### Shared Resources
+
+Skills in a folder can share common resources via `.promptscript/shared/`:
+
+```
+.promptscript/
+  shared/
+    templates.md         # Shared across all skills
+    style-guide.md
+  skills/
+    review/
+      SKILL.md           # Gets @shared/templates.md, @shared/style-guide.md
+    deploy/
+      SKILL.md           # Also gets shared resources
+```
+
+Files in `shared/` are automatically included in every skill with `@shared/` prefix.
+
+### @agents
+
+Custom subagent definitions. Compiles to `.claude/agents/` for Claude Code,
+`.github/agents/` for GitHub Copilot, `.factory/droids/` for Factory AI, etc.
+
+```
+@agents {
+  code-reviewer: {
+    description: "Reviews code quality"
+    tools: ["Read", "Grep", "Glob", "Bash"]
+    model: "sonnet"
+    permissionMode: "default"
+    content: (triple-quoted text with agent instructions)
+  }
+}
+```
+
+Supports mixed models per agent: `specModel` sets a different model for
+Specification/planning mode (GitHub, Factory), `specReasoningEffort` sets reasoning
+effort for the spec model (Factory only, values: "low", "medium", "high").
+
+Factory AI droids support additional properties: `model` (any model ID or "inherit"),
+`reasoningEffort` ("low", "medium", "high"), and `tools` (category name like "read-only"
+or array of tool IDs).
+
+### @examples
+
+Structured few-shot examples for AI assistants (requires syntax `1.2.0`):
+
+```
+@meta {
+  id: "commit-style"
+  syntax: "1.2.0"
+}
+
+@examples {
+  feat-commit: {
+    description: "Feature commit with scope"
+    input: "Added user authentication with JWT tokens"
+    output: "feat(auth): add JWT-based user authentication"
+  }
+}
+```
+
+Each entry is a named example with `input` and `output` (both required),
+plus optional `description`. Multi-line content uses triple-quoted strings.
+
+Examples can also be attached to skills via the `examples` property:
+
+```
+@skills {
+  commit: {
+    description: "Create conventional commits"
+    examples: {
+      basic: {
+        input: "Added dark mode toggle"
+        output: "feat(settings): add dark mode toggle"
+      }
+    }
+    content: (triple-quoted text)
+  }
+}
+```
+
+### @knowledge
+
+Reference documentation as triple-quoted text. Used for command references,
+API docs, and other material that should appear in the output.
+
+### @params
+
+Template parameter definitions with types: string, number, boolean, enum("a", "b").
+Optional parameters use `?` suffix. Defaults use `= value`.
+
+### @guards
+
+File glob patterns and priority rules for path-specific instructions.
+
+### @local
+
+Private local configuration. Not included in compiled output or committed to git.
+
+## Inheritance and Composition
+
+### @inherit (single, linear)
+
+One per file. Child blocks merge on top of parent:
+
+```
+@inherit @company/frontend-team
+@inherit ./parent
+@inherit @stacks/react-app(projectName: "my-app", port: 3000)
+```
+
+### @use (multiple, mixins)
+
+Import and merge fragments:
+
+```
+@use @core/security
+@use @core/quality
+@use ./local-config
+@use @core/typescript as ts   # alias enables @extend access
+```
+
+#### URL imports (Go-module style)
+
+Import directly from any Git repository by host path - no alias required:
+
+```
+@use github.com/acme/shared-standards/@fragments/security
+@use gitlab.com/myorg/prompts/@stacks/python
+```
+
+Version pinning with `@`:
+
+```
+@use github.com/acme/shared-standards/@org/base@1.2.0    # exact version
+@use github.com/acme/shared-standards/@org/base@^1.0.0   # semver range
+@use github.com/acme/shared-standards/@org/base@main     # branch
+```
+
+#### Registry aliases
+
+Short names for Git repository URLs, configured in `promptscript.yaml`:
+
+```yaml
+registries:
+  company:
+    url: github.com/acme/promptscript-registry
+```
+
+Then use the alias as scope prefix:
+
+```
+@use @company/security
+@inherit @company/base-config
+```
+
+Merge rules:
+
+- Text: concatenated with deduplication
+- Objects: deep merged (target wins on conflicts)
+- Arrays: unique concatenation
+
+### Block Filtering
+
+Control which blocks are imported using the reserved `only` and `exclude` parameters:
+
+```
+@use ./shared-config(only: ["skills", "context"])
+@use ./shared-config(exclude: ["knowledge"])
+@use ./shared-config(exclude: ["knowledge"], mode: "strict")
+```
+
+Rules:
+
+- `only` and `exclude` are mutually exclusive — using both is a validation error (PS021)
+- Values are block type names: `identity`, `context`, `standards`, `knowledge`, `skills`, `shortcuts`, `agents`, etc.
+- Block filtering does not apply to `@inherit` directives
+
+### Markdown Imports
+
+Import skills directly from `.md` files (v1.8+). No external tools needed:
+
+```
+@use ./skills/frontend-design.md
+@use ./shared/commit.md as commit
+@use github.com/anthropics/skills/commit@1.0.0
+@use github.com/repo/skills/gitnexus         # directory → SKILL.md
+```
+
+Content detection: PromptScript blocks in `.md` are parsed as a `.prs` fragment;
+YAML frontmatter with `name`/`description` is loaded as a skill definition;
+otherwise content is treated as free-form knowledge.
+
+CLI management:
+
+```
+prs skills add github.com/anthropics/skills/commit@1.0.0
+prs skills remove commit
+prs skills list
+prs skills update
+```
+
+### @extend (modify existing or imported blocks)
+
+Use a direct path for inherited or local blocks:
+
+```
+@extend standards.testing {
+  coverage: 95
+}
+```
+
+Use an alias when targeting a specific imported block:
+
+```
+@use @core/typescript as ts
+
+@extend ts.standards {
+  testing: { coverage: 95 }
+}
+```
+
+#### Replacing regular block fields
+
+Syntax `1.3.0` supports explicit replacement of complete regular block field values:
+
+```
+@meta { id: "project" syntax: "1.3.0" }
+
+@inherit ./company-base
+
+@extend standards {
+  testing!: ["Use Vitest"]
+  linting: ["Use ESLint"]
+}
+```
+
+`testing!` replaces the inherited value. Fields without `!` keep normal merge behavior.
+Replacement works after `@inherit` and `@use`, including aliases and nested target paths.
+A missing field is set. The modifier is rejected for `@skills`, which retain their dedicated
+merge and sealing semantics.
+
+#### Skill-aware @extend semantics
+
+When extending a skill definition via `@extend`, individual skill properties follow specific merge
+strategies rather than the generic block merge rules:
+
+| Strategy          | Properties                                                                                         |
+| ----------------- | -------------------------------------------------------------------------------------------------- |
+| **Replace**       | content, description, trigger, userInvocable, allowedTools, disableModelInvocation, context, agent |
+| **Append**        | references, examples, requires                                                                     |
+| **Shallow merge** | params, inputs, outputs                                                                            |
+
+Example — extending a base skill to add references and override content:
+
+```
+@use @company/skills as skills
+
+@extend skills.code-review {
+  content: (triple-quoted text with overridden instructions)
+  references: [
+    ./extra-context.md
+  ]
+}
+```
+
+The `references` array from the base skill and the overlay are combined (append). The `content`
+field from the overlay replaces the base (replace).
+
+#### Reference negation
+
+Use `!` prefix in `@extend` to remove entries from a lower layer's append-strategy arrays:
+
+```
+@extend skills.code-review {
+  references: [
+    "!references/deprecated.md"
+    "references/replacement.md"
+  ]
+}
+```
+
+Path matching is normalized (`"!./foo.md"` matches `"foo.md"`). Only works in `@extend` blocks
+on `references` and `requires`. Validator PS028 warns about `!` in base definitions.
+
+#### Overlay consistency warnings
+
+The resolver emits warnings during compile when an overlay drifts from its base. Always shown
+(not gated by `--verbose`):
+
+- **Orphaned extend** — `@extend target "X" not found — overlay will be ignored.` Triggered when
+  the targeted block doesn't exist (base removed or renamed).
+
+- **Stale skill target** — `@extend creates new skill "X" — base does not define it.` Triggered
+  when an `@extend` inside `@skills` would create a new skill instead of extending an existing one.
+
+- **Negation orphan** — `Negation "!path" did not match any base entry — it may be stale.`
+  Triggered when a `!entry` in references/requires doesn't match anything in the base.
+
+These come from the resolver, not the validator (PS0XX rules). They appear during `prs compile`,
+not `prs validate`.
+
+#### Sealed properties
+
+Prevent `@extend` from overriding specified replace-strategy properties:
+
+```
+@skills {
+  deploy: {
+    content: (triple-quoted text with critical workflow)
+    sealed: ["content", "description"]
+  }
+}
+```
+
+`sealed: true` seals all replace-strategy properties. Attempting to override a sealed
+property is a hard compilation error. Only the base skill author can set `sealed` —
+overlays cannot add or modify it. Append-strategy properties remain extendable.
+Validator PS029 warns about invalid entries in `sealed`.
+
+#### Skill composition (inline @use)
+
+Import sub-skills within a `@skills` block to compose multi-phase workflows:
+
+```
+@skills {
+  ops: {
+    description: "Production triage"
+    content: (triple-quoted text with orchestrator instructions)
+  }
+  @use ./phases/health-scan
+  @use ./phases/triage
+  @use ./phases/code-fix as autofix
+}
+```
+
+Each `@use` resolves the referenced `.prs` file, extracts its skill definition and context
+blocks, and flattens them as numbered phase sections into the parent skill's content. The
+`as alias` form controls the phase display name. Validator PS027 checks composition validity.
+
+### Parameterized Inheritance (Template Variables)
+
+Use `{{variable}}` placeholders in a **parent/template** file, and pass values
+from the **child** file via `@inherit` or `@use` with `(key: value)` syntax.
+
+**IMPORTANT:** Variables are NOT set from `promptscript.yaml` or CLI. They are
+passed from one `.prs` file to another through `@inherit` or `@use`.
+
+**Step 1: Create the template** (parent file with `params` in `@meta`):
+
+```
+# base.prs - reusable template
+@meta {
+  id: "service-template"
+  syntax: "1.0.0"
+  params: {
+    serviceName: string
+    port?: number = 3000
+  }
+}
+
+@identity {
+  """
+  You are working on {{serviceName}} running on port {{port}}.
+  """
+}
+```
+
+**Step 2: Inherit with values** (child file passes params):
+
+```
+# project.prs - concrete project
+@meta { id: "user-api" syntax: "1.0.0" }
+
+@inherit ./base(serviceName: "user-api", port: 8080)
+```
+
+After compilation, `{{serviceName}}` becomes `user-api` and `{{port}}` becomes `8080`.
+
+The same works with `@use`:
+
+```
+@use ./base(serviceName: "auth-service") as auth
+```
+
+**Parameter types:** `string`, `number`, `boolean`, `enum("a", "b")`.
+Optional params use `?` suffix. Defaults use `= value`.
+Missing required params produce a compile error.
+
+**Multi-service pattern** - reuse one template across many projects:
+
+```
+services/
+  base.prs                          # template with params
+  user-api/
+    promptscript.yaml               # source: project.prs
+    project.prs                     # @inherit ../base(serviceName: "user-api")
+  auth-service/
+    promptscript.yaml
+    project.prs                     # @inherit ../base(serviceName: "auth-service")
+```
+
+## Configuration: promptscript.yaml
+
+### Auto-injection
+
+This skill is automatically included when compiling with `prs compile`. No manual copying needed.
+To disable, set `includePromptScriptSkill: false` in your `promptscript.yaml`.
+
+```
+id: my-project
+syntax: "1.1.0"
+description: "My project description"
+input:
+  entry: .promptscript/project.prs
+  include: ['.promptscript/**/*.prs']
+targets:
+  github:
+    version: full      # simple | multifile | full
+  claude:
+    version: full
+  cursor:
+    version: standard
+  antigravity:
+    version: frontmatter
+  factory:
+    version: full
+  windsurf:             # 41 additional targets supported
+    version: simple
+  cline:
+    version: simple
+registry:
+  git: https://github.com/org/registry.git
+  ref: main
+registries:
+  company:
+    url: github.com/acme/promptscript-registry
+  oss:
+    url: github.com/prscrpt/community-registry
+    ref: v2
+policies:
+  - name: adjacent-layers-only
+    kind: layer-boundary
+    severity: error
+    layers: ['@core', '@team', '@project']
+    maxDistance: 1
+```
+
+### Lockfile: `promptscript.lock`
+
+When remote imports are used, `prs compile` automatically generates a lockfile
+recording the exact resolved commit for each dependency. Integrity hashes
+(SHA-256) are included for registry references to detect tampering or drift.
+This enables reproducible builds across machines and CI. Commit `promptscript.lock`
+to version control.
+
+Use `--ignore-hashes` on `prs compile` or `prs validate` to skip integrity
+hash verification when needed.
+
+### Policy Engine
+
+Define organizational policies in `promptscript.yaml` to validate skill extensions:
+
+```yaml
+policies:
+  - name: adjacent-layers-only
+    kind: layer-boundary
+    description: "Only adjacent layers can extend each other"
+    severity: error
+    layers: ["@core", "@team", "@project"]
+    maxDistance: 1
+
+  - name: protect-content
+    kind: property-protection
+    description: "Content override requires explicit approval"
+    severity: warning
+    properties: ["content", "description"]
+
+  - name: approved-registries
+    kind: registry-allowlist
+    description: "Extensions must come from approved registries"
+    severity: error
+    allowed: ["@core", "@team"]
+```
+
+Policy kinds: `layer-boundary` (controls layer distance), `property-protection`
+(prevents overriding specific properties), `registry-allowlist` (restricts extension sources).
+Severity: `error` (fails validation) or `warning` (reported only).
+Skip with `--skip-policies` during development (never in CI).
+
+## Syntax Version Validation
+
+The `syntax` field in `@meta` declares the PromptScript language version (semver).
+
+### Known Versions
+
+| Version | What it adds                                                                                                            |
+| ------- | ----------------------------------------------------------------------------------------------------------------------- |
+| `1.0.0` | Core blocks (identity, context, standards, restrictions, knowledge, shortcuts, commands, guards, params, skills, local) |
+| `1.1.0` | Adds `@agents` and `@workflows`; reserves internal `@prompts`                                                           |
+| `1.2.0` | Adds `@examples` (few-shot input/output pairs)                                                                          |
+| `1.3.0` | Adds explicit regular block field replacement in `@extend`                                                              |
+| `1.4.0` | Adds `@hooks`, `@mcpServers`, and `@plugins`                                                                            |
+
+### Block Version Requirements
+
+| Block         | Minimum Syntax Version |
+| ------------- | ---------------------- |
+| `@agents`     | `1.1.0`                |
+| `@workflows`  | `1.1.0`                |
+| `@examples`   | `1.2.0`                |
+| `@hooks`      | `1.4.0`                |
+| `@mcpServers` | `1.4.0`                |
+| `@plugins`    | `1.4.0`                |
+
+All other built-in blocks are available from `1.0.0`.
+Regular block field replacement with `field!: value` requires syntax `1.3.0`.
+
+### Validation Rules
+
+- **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`.
+- **PS019 (`unknown-block-name`)**: warns when a block name is not a known PromptScript type, with fuzzy-match suggestions for typos.
+- **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).
+- **PS027 (`valid-skill-composition`)**: warns about conflicting phase names or excessive phases in composed skills.
+- **PS028 (`valid-append-negation`)**: warns when negation prefix `!` appears in base skill definitions (only effective in `@extend`).
+- **PS029 (`valid-sealed-property`)**: warns when `sealed` contains non-replace-strategy property names.
+- **PS030 (`policy-compliance`)**: validates skill extensions against organizational policies defined in `promptscript.yaml`.
+
+### Fixing Syntax Versions
+
+```
+prs validate --fix          # Auto-fix syntax versions in .prs files
+prs upgrade                 # Upgrade all .prs files to the latest version
+```
+
+`--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.
+
+`prs upgrade` upgrades all files to the latest known syntax version regardless of what blocks they use.
+
+## CLI Commands
+
+```
+prs init                    # Initialize project (auto-detects existing files)
+prs init --yes --targets claude factory
+prs init --dry-run          # Preview initialization
+prs init --auto-import      # Initialize + static import of existing files
+prs migrate                 # Interactive migration flow
+prs migrate --static        # Non-interactive static import
+prs migrate --llm           # Generate AI-assisted migration prompt
+prs migrate --static --dry-run
+prs compile                 # Compile to all targets
+prs compile --watch         # Watch mode
+prs compile --ignore-hashes # Skip integrity hash verification
+prs build <name>            # Compile a named build profile
+prs validate --strict       # Validate syntax
+prs validate --fix          # Auto-fix syntax version declarations
+prs validate --skip-policies # Skip policy engine evaluation
+prs upgrade                 # Upgrade all .prs files to latest syntax version
+prs import CLAUDE.md        # Import existing AI instructions
+prs import CLAUDE.md --dry-run # Preview import conversion
+prs inspect <skill>         # Show skill composition provenance
+prs inspect <skill> --layers # Show layer-level breakdown
+prs hooks install           # Install auto-compilation hooks for AI tools
+prs hooks install claude    # Install hooks for a specific tool
+prs skills add <source>     # Add a remote skill (@use + lock update + SKILL.md validation)
+prs skills add <source> --strict          # Treat validation warnings as errors
+prs skills add <source> --skip-validation # Bypass Agent Skills spec checks (not recommended)
+prs skills remove <name>    # Remove a skill (@use line + lock entry)
+prs skills list             # List all imported skills
+prs skills update           # Re-resolve markdown-imported skills (re-validates + re-hashes)
+prs pull                    # Update registry
+prs diff --target claude    # Show compilation diff
+prs lock                    # Generate/update promptscript.lock
+prs lock --dry-run          # Preview lockfile changes
+prs update                  # Re-resolve all remote imports to latest
+prs update <url>            # Update a specific registry
+prs vendor sync             # Copy cached deps to .promptscript/vendor/
+prs vendor check            # Verify vendor matches lockfile
+prs resolve @alias/path     # Debug: show how an import resolves
+prs registry list           # Show configured registries and aliases
+prs registry add <alias> <url>  # Add a registry alias
+```
+
+`prs init --yes` requires explicit, detected, or user-configured targets. It does not invent
+default tools. For existing projects, `prs migrate` preserves `promptscript.yaml`, isolates static
+output under `.promptscript/migrated/`, leaves source instructions untouched, and performs no
+writes when no candidates are detected.
+
+## Output Targets
+
+48 supported targets. Key examples:
+
+| Target      | Main File                       | Skills                                             |
+| ----------- | ------------------------------- | -------------------------------------------------- |
+| GitHub      | .github/copilot-instructions.md | .github/skills/\*/SKILL.md                         |
+| Claude      | CLAUDE.md                       | .claude/skills/\*/SKILL.md                         |
+| Cursor      | .cursor/rules/project.mdc       | .agents/skills/\*/SKILL.md                         |
+| Antigravity | .agent/rules/project.md         | -------------------------------------------------- |
+| Factory     | AGENTS.md                       | .factory/skills/\*/SKILL.md, .factory/droids/\*.md |
+| OpenCode    | OPENCODE.md                     | .opencode/skills/\*/SKILL.md                       |
+| Gemini      | GEMINI.md                       | .agents/skills/\*/skill.md                         |
+| Windsurf    | .windsurf/rules/project.md      | .windsurf/skills/\*/SKILL.md                       |
+| Cline       | .clinerules                     | -------------------------------------------------- |
+| Roo Code    | .roorules                       | -------------------------------------------------- |
+| Codex       | AGENTS.md                       | .agents/skills/\*/SKILL.md                         |
+| Continue    | .continue/rules/project.md      | -------------------------------------------------- |
+| + 36 more   |                                 | See full list in documentation                     |
+
+### Formatter Documentation
+
+For detailed information about each formatter's output paths, supported features, quirks, and example outputs:
+
+- **Full formatter reference:** `docs/reference/formatters/` (7 dedicated pages + index of all 48)
+- **llms-full.txt:** Available at the docs site root - contains all documentation in a single file for LLM consumption
+- **Dedicated pages exist for:** Claude Code, GitHub Copilot, Cursor, Antigravity, Factory AI, Gemini CLI, OpenCode
+- **All 48 formatters indexed at:** `docs/reference/formatters/index.md` with output paths, tier, and feature flags
+
+### Auto-Compilation Hooks
+
+Instead of running `prs compile --watch` manually, install hooks so your AI tool
+triggers compilation automatically when you edit `.prs` files:
+
+```
+prs hooks install          # Auto-detect and install for all detected tools
+prs hooks install claude   # Install for a specific tool
+```
+
+Hooks also protect generated files from direct edits — when an AI agent tries
+to edit a compiled output (e.g., CLAUDE.md), the write is blocked with a message
+pointing to the source `.prs` file. Supported tools: Claude Code, Factory AI,
+Cursor, Windsurf, Cline, GitHub Copilot, Gemini CLI.
+
+## Project Organization
+
+Typical modular structure:
+
+```
+.promptscript/
+  project.prs      # Entry: @meta, @inherit, @use, @identity, @agents
+  context.prs      # @context (architecture, tech stack)
+  standards.prs    # @standards (coding conventions)
+  restrictions.prs # @restrictions (hard rules)
+  commands.prs     # @shortcuts and @knowledge
+```
+
+The entry file uses `@use ./context`, `@use ./standards`, etc. to compose them.
+
+## Common Mistakes
+
+1. Missing @meta block - every .prs file needs `@meta` with `id` and `syntax`
+2. Multiple @inherit - only one per file; use `@use` for additional imports
+3. Extending an unknown path - target an inherited or local block, or use an imported alias
+4. Unquoted strings with special chars - quote strings containing `:`, `#`, `{`, `}`
+5. Forgetting to compile - `.prs` changes need `prs compile` to take effect
+6. Triple quotes inside triple quotes - not supported; describe content textually instead
+7. Using `{{var}}` in the root file without `@inherit` - template variables only work
+   in a parent file that defines `params` in `@meta`, with values passed by the child
+   via `@inherit ./parent(key: value)` or `@use ./fragment(key: value)`. They are NOT
+   set from `promptscript.yaml` or CLI flags
+
+8. Using `@examples` with `syntax: "1.0.0"` or `"1.1.0"` - `@examples` requires
+   syntax version `1.2.0`. Run `prs validate --fix` to auto-upgrade
+
+## Migrating Existing AI Instructions to PromptScript
+
+### Automated: `prs import`
+
+The fastest way to convert existing AI instructions to PromptScript:
+
+```
+prs import CLAUDE.md                    # Convert a single file
+prs import .github/copilot-instructions.md
+prs import AGENTS.md --output ./imported.prs
+prs import --dry-run CLAUDE.md          # Preview without writing
+```
+
+`prs import` automatically:
+
+- Detects the source format (Claude, GitHub Copilot, Cursor, Factory, etc.)
+- Maps content to appropriate PromptScript blocks (@identity, @standards, etc.)
+- Generates a valid `.prs` file with `@meta` block
+- Preserves the original intent and structure
+
+Supported source formats:
+
+- `CLAUDE.md` (Claude Code)
+- `.github/copilot-instructions.md` (GitHub Copilot)
+- `.cursorrules` or `.cursor/rules/*.mdc` (Cursor)
+- `AGENTS.md` (Factory AI / Codex)
+- `.clinerules` (Cline), `.roorules` (Roo Code)
+- `.windsurf/rules/*.md` (Windsurf)
+- Any Markdown-based AI instruction file
+
+### Manual Migration
+
+For complex migrations or when `prs import` needs refinement:
+
+| Source Pattern                      | PromptScript Block |
+| ----------------------------------- | ------------------ |
+| "You are..." persona text           | `@identity`        |
+| Project description, tech stack     | `@context`         |
+| Coding conventions, style rules     | `@standards`       |
+| "Never...", "Always...", hard rules | `@restrictions`    |
+| `/command` definitions              | `@shortcuts`       |
+| Skill/tool definitions              | `@skills`          |
+| Agent/subagent configs              | `@agents`          |
+| Reference docs, API specs           | `@knowledge`       |
+
+After import, split into modular files (`context.prs`, `standards.prs`, etc.)
+and compose with `@use` in `project.prs`. Run `prs validate --strict` then
+`prs compile` to verify output matches the original.