Plugin check: Run node "${CLAUDE_PLUGIN_ROOT}/scripts/check-version.js" — if it outputs a message, show it to the user before proceeding.

Manage Headers

Inspect and configure the HTTP security headers for a Power Pages site. Headers are configured as HTTP/* site settings stored in .powerpages-site/site-settings/ YAML files.

Initial request: $ARGUMENTS

Gotchas

• Site settings are YAML files. Each header is a separate .yml file in .powerpages-site/site-settings/. The file name uses - instead of / (e.g., HTTP/X-Frame-Options → http-x-frame-options.sitesetting.yml).
• Absent = no header. When a site setting is absent, the runtime omits that header entirely (except CSP on new sites — see headers-reference.md).
• HSTS and Cache-Control are platform-managed. Do not try to set HTTP/Strict-Transport-Security — the runtime does not recognize it and the setting has no effect.
• Maker-mode bypasses headers. Requests from Power Pages Studio skip all HTTP/* header emission. Verify headers in an incognito tab, not the studio preview.
• CSP is pass-through. The runtime emits the value verbatim — it does NOT merge runtime sources automatically. The CSP MUST include Power Pages runtime hosts or the site breaks.
• CSP nonce. When script-src contains 'nonce', the runtime replaces it per-request with 'nonce-<random>' and auto-hashes inline event handlers. Scripts created dynamically via document.createElement do NOT receive the nonce.
• SameSite=None requires HTTPS. The runtime sets Secure on every cookie over HTTPS automatically.
• CORS * is auto-specialized. The runtime replaces * per-request with the specific requesting Origin — the browser sees a single-origin header, not a wildcard.

Workflow

1. Prerequisites — Locate project, confirm site-settings directory exists
2. Inspect current headers — Read site-setting YAML files, identify configured and missing headers
3. Assess and plan — Identify gaps, present recommendations
4. Apply changes — Edit existing settings or create new ones
5. Summarize — Present results, record usage, offer follow-ups

Task Tracking

Create tasks in four groups. Mark each in_progress when starting, completed when done.

1. Prerequisites

1.1 Locate the project, detect review mode

Use Glob to find **/powerpages.config.json. If $ARGUMENTS contains --review <out-dir>, remember the output directory — Steps 3–4 are skipped and Step 5 writes JSON only.

1.2 Verify site-settings directory

Check that .powerpages-site/site-settings/ exists. If not, the site has not been deployed yet — tell the user and recommend /deploy-site. Stop.

2. Inspect current headers

Use Glob to find all *.yml files in .powerpages-site/site-settings/. Use Read to read each file and extract the name and value fields. Identify all settings with an HTTP/ prefix — these are the configured headers.

Compare against the recognized header catalogue in references/headers-reference.md. For each header in the catalogue:

• Present — record its current value.
• Missing — record it as absent and note the recommended value from headers-reference.md.

For CSP specifically: if HTTP/Content-Security-Policy is present, scan the project's source files using Glob + Read to find external URLs and check whether they are covered by the policy. Identify the site's cloud environment via pac auth who to determine the correct Power Pages runtime host (see headers-reference.md § "Power-Pages-runtime sources a CSP must allow").

3. Assess and plan

Skip in review mode.

MUST use plain language only. Never lead with words like CSP, CORS, HSTS, or MIME sniffing — explain using everyday language:

Default approach

Read references/headers-reference.md for recommended values and guidance. Present the most important gaps first — headers that are missing or misconfigured relative to the recommended values.

For each finding, present via AskUserQuestion:

• A plain-language explanation of why the change matters
• The recommended value
• Options: accept the recommendation, customize, or skip

Do NOT present all headers at once — present the important gaps first. For headers already set to recommended values, mention them in the summary without requiring action.

CSP composition

When the user needs a CSP (missing or incomplete), compose one using:

1. The starter template from headers-reference.md
2. The correct cloud-specific runtime host
3. External URLs discovered from the project's source files — scan ALL source files, templates, scripts, etc.
4. The 'nonce' keyword for inline scripts

When reviewing an existing CSP, validate:

• All external URLs actually loaded by the site are covered in the policy
• Runtime hosts are included for the site's cloud

Present the composed or corrected CSP for review. Recommend starting in report-only mode (HTTP/Content-Security-Policy-Report-Only) before enforcing.

4. Apply changes

Skip in review mode.

For existing settings: use Edit on the YAML file directly — change the value field.

For new settings: use the shared create script:

node "${CLAUDE_PLUGIN_ROOT}/scripts/create-site-setting.js" \
  --projectRoot "<PROJECT_ROOT>" \
  --name "<setting-name>" \
  --value "<value>" \
  --description "<description>"

See references/commands.md for details.

After all changes are applied, offer to deploy: "Ready to deploy these changes? They take effect after the next deploy." If yes, invoke /deploy-site.

5. Summarize

5.1 Review mode

First, read the configured HTTP/* site settings (from Step 2 — you already have them). Then write <REVIEW_DIR>/header-annotations.json with a plain-language description for each header and, when the configured value has a genuine issue (missing critical directive, weak value), a suggested fix. The transform script no longer hardcodes header descriptions — they come from you.

{
  "headers": {
    "HTTP/<HeaderName>": { "description": "What this header does, in plain language.", "fix": "Optional fix if the configured value has a genuine issue." }
  }
}

Use references/headers-reference.md for authoritative descriptions and validation rules. Surface a fix only when the value has a real problem — do not editorialize on every header.

Then run the transform:

node "${CLAUDE_PLUGIN_ROOT}/skills/manage-headers/scripts/transform-headers.js" \
  --projectRoot "<PROJECT_ROOT>" \
  --annotations "<REVIEW_DIR>/header-annotations.json"

Write the stdout to <REVIEW_DIR>/manage-headers.json and stop. The transform emits { status, findings, details }; the orchestrating skill handles presentation.

5.2 Present summary

Skip in review mode.

Plain-language summary: what was changed, what gaps remain, and what is already well-configured.

5.3 Record skill usage

Reference: ${CLAUDE_PLUGIN_ROOT}/references/skill-tracking-reference.md

Use --skillName "ManageHeaders".

5.4 Offer follow-