[jplhomer]

WHY are these changes introduced?

Each App Security check now has a page on shopify.dev under /docs/apps/build/security/app-security-checks/ (PR open). The CLI output and the agent handoff don't point to them yet, so neither a developer nor their coding agent can get from a finding to the page that explains it and shows the fix.

WHAT is this pull request doing?

• Source of truth: every RULE_CATALOG entry gets a required docsUrl (CHECK_DOCS_BASE_URL + slug). A new catalog.test.ts checks that every entry has a URL under that base, that the slug is the kebab-cased check ID, and that the set of slugs is exactly the 36 pages in the docs PR at head 967e9f9cc5cd25ea6cdb9434caba30121a45abd1. Every check has a page.
• Human output: check links each check ID with cli-kit's link token. Hyperlink-capable terminals get a clickable ID. Other terminals get cli-kit's usual ID [n] footnotes under the box. In review, each per-check box gets a link through the alert's link prop. The summary table stays plain text, because footnote markers would push the ID column out of alignment. In --verbose, the existing per-finding fix.guide link is now labelled Guide (it was Docs), so it can't be confused with the check page.
• JSON / agent handoff: docs_url is added to the check snapshot in deterministic-findings.json and agent-findings.json, so it shows up in check --json. It's also added to each check in review --json and in agent-checks.json, next to id, version and severity. The instructions in agent-checks.json and INSTRUCTIONS.md tell the agent what docs_url is and to link it when explaining a finding. I didn't add a static list of resources to INSTRUCTIONS.md: it would repeat the per-check data and could drift, and the instructions already say agent-checks.json is the source of truth for checks.
• Compatibility: all the new fields are optional and additive, so schema_version stays 1. Results files written by earlier versions still parse; they just don't show the link. Earlier versions strip the unknown key when reading new files. The review --json schema in oclif.manifest.json is regenerated.

Before / after: shopify app security check (non-hyperlink terminal)

Before:

│  High                                                                        │
│    • Configured callback URL is not HTTPS INSECURE_WEBHOOK_URL 1 occurrence  │
│      across 1 file shopify.app.toml                                          │
│                                                                              │
│  Medium                                                                      │
│    • Deprecated ScriptTag capability DEPRECATED_SCRIPT_TAG_SCOPE 1           │
│      occurrence across 1 file shopify.app.toml                               │
...
╰──────────────────────────────────────────────────────────────────────────────╯

After:

│  High                                                                        │
│    • Configured callback URL is not HTTPS INSECURE_WEBHOOK_URL [1] 1         │
│      occurrence across 1 file shopify.app.toml                               │
│                                                                              │
│  Medium                                                                      │
│    • Deprecated ScriptTag capability DEPRECATED_SCRIPT_TAG_SCOPE [2] 1       │
│      occurrence across 1 file shopify.app.toml                               │
...
╰──────────────────────────────────────────────────────────────────────────────╯
[1] https://shopify.dev/docs/apps/build/security/app-security-checks/insecure-webhook-url
[2] https://shopify.dev/docs/apps/build/security/app-security-checks/deprecated-script-tag-scope

In a hyperlink-capable TTY the layout matches "before" and each check ID is an OSC 8 link to its page.

Before / after: shopify app security review

Before:

│  High · INSECURE_WEBHOOK_URL · Configured callback URL is not HTTPS          │
│                                                                              │
│  deterministic · shopify.app.toml                                            │

After:

│  High · INSECURE_WEBHOOK_URL · Configured callback URL is not HTTPS          │
│                                                                              │
│  INSECURE_WEBHOOK_URL on shopify.dev [1]                                     │
│                                                                              │
│  deterministic · shopify.app.toml                                            │
...
╰──────────────────────────────────────────────────────────────────────────────╯
[1] https://shopify.dev/docs/apps/build/security/app-security-checks/insecure-webhook-url

JSON

review --json, checks[]:

{ "id": "EOL_API_VERSION", "title": "End-of-life API version",
  "docs_url": "https://shopify.dev/docs/apps/build/security/app-security-checks/eol-api-version", ... }

agent-checks.json, checks[]:

{ "id": "MISSING_TENANT_ISOLATION", "version": 4, "severity": "high",
  "docs_url": "https://shopify.dev/docs/apps/build/security/app-security-checks/missing-tenant-isolation",
  "prompt": "..." }

How to manually test your changes?

1. Create an app directory with a shopify.app.toml that has scopes = "write_script_tags", [webhooks] api_version = "2023-01" and a webhook subscription with an http:// URI.
2. pnpm shopify app security check --path <dir>: each check ID is a link (or a footnote if your terminal doesn't support hyperlinks).
3. pnpm shopify app security review --path <dir>: each check box has an <ID> on shopify.dev link.
4. pnpm shopify app security check --path <dir> --json and review --json: docs_url is present; .shopify/app-security/agent-checks.json has docs_url on every check.

Post-release steps

The links point at shopify.dev pages from shop/world docs PR 2090077, which isn't merged yet. They'll 404 until it ships.

No changeset: the app security commands are still hidden, and recent App Security PRs follow that convention.

Conflicts to expect: checks/embedded.ts (generated; regenerate), and nearby hunks with 8740 in INSTRUCTIONS.md, checks/index.ts, results/schema.ts, types.ts and security-review-json.ts. 8752 changes a line next to this PR's catalog edits but shouldn't overlap.

Checklist

• I've considered possible cross-platform impacts (Mac, Linux, Windows)
• I've considered possible documentation changes
• I've considered analytics changes to measure impact

---

PR authored by Qlaw

[jplhomer]

/snapit

[github-actions]

🫰✨ Thanks @jplhomer! Your snapshot has been published to npm.

Built from 872d43c23e96b4cdc507aa6914ebf803394d1a24. Workflow run.

Test the snapshot by installing your package globally:

pnpm i -g --@shopify:registry=https://registry.npmjs.org @shopify/cli@0.0.0-snapshot-20261005161904

Caution

After installing, validate the version by running shopify version in your terminal.
If the versions don't match, you might have multiple global instances installed.
Use which shopify to find out which one you are running and uninstall it.

[Copilot]

Copilot review overview

🟡 Changes recommended

Stored documentation URLs must be validated before being rendered as trusted terminal hyperlinks.

Review effort: Balanced
Findings: 1

Open (1)

• Validate docs_url before rendering trusted OSC-8 links · New

What changed in this PR

Adds shopify.dev documentation links throughout App Security output and agent handoff.

Changes:

• Adds catalog-backed documentation URLs for all checks.
• Propagates URLs through artifacts, JSON output, and agent instructions.
• Renders clickable terminal links and expands test coverage.

File	Description
packages/​cli/​oclif.manifest.json	Updates generated review JSON schema.
packages/​app/​src/​cli/​services/​security-review-output.ts	Links review finding boxes.
packages/​app/​src/​cli/​services/​security-review-output.test.ts	Tests review links and compatibility.
packages/​app/​src/​cli/​services/​security-review-json.ts	Exposes docs_url in review JSON.
packages/​app/​src/​cli/​services/​security-output.ts	Links check IDs and renames guide labels.
packages/​app/​src/​cli/​services/​security-output.test.ts	Tests linked and unknown IDs.
packages/​app/​src/​cli/​services/​security-check.test.ts	Updates agent-check fixtures.
packages/​app/​src/​cli/​services/​app-security-engine/​types.ts	Extends stored check snapshots.
packages/​app/​src/​cli/​services/​app-security-engine/​tests/​translate.test.ts	Tests URL translation.
packages/​app/​src/​cli/​services/​app-security-engine/​tests/​scan-artifact.test.ts	Tests deterministic snapshots.
packages/​app/​src/​cli/​services/​app-security-engine/​tests/​record.test.ts	Tests agent snapshots.
packages/​app/​src/​cli/​services/​app-security-engine/​tests/​combine.test.ts	Tests URL combination behavior.
packages/​app/​src/​cli/​services/​app-security-engine/​tests/​checks.test.ts	Tests agent-check URLs and instructions.
packages/​app/​src/​cli/​services/​app-security-engine/​tests/​catalog.test.ts	Validates catalog documentation coverage.
packages/​app/​src/​cli/​services/​app-security-engine/​scan-artifact/​index.ts	Snapshots deterministic documentation URLs.
packages/​app/​src/​cli/​services/​app-security-engine/​rules/​catalog.ts	Defines documentation URLs and lookup.
packages/​app/​src/​cli/​services/​app-security-engine/​results/​schema.ts	Parses optional stored URLs.
packages/​app/​src/​cli/​services/​app-security-engine/​results/​combine.ts	Propagates URLs into combined checks.
packages/​app/​src/​cli/​services/​app-security-engine/​INSTRUCTIONS.md	Documents agent URL usage.
packages/​app/​src/​cli/​services/​app-security-engine/​index.ts	Exports the URL lookup.
packages/​app/​src/​cli/​services/​app-security-engine/​checks/​index.ts	Adds URLs to agent handoff and snapshots.
packages/​app/​src/​cli/​services/​app-security-engine/​checks/​embedded.ts	Regenerates embedded instructions.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[jek]

Smoke test instructions worked under alternate checks (tried EOL_API_VERSION among others)