diff --git a/.agents/skills/php-forge-debug-core b/.agents/skills/php-forge-debug-core
new file mode 120000
index 0000000..0677e45
--- /dev/null
+++ b/.agents/skills/php-forge-debug-core
@@ -0,0 +1 @@
+../../skills/php-forge-debug-core
\ No newline at end of file
diff --git a/.claude/skills/php-forge-debug-core b/.claude/skills/php-forge-debug-core
new file mode 120000
index 0000000..0677e45
--- /dev/null
+++ b/.claude/skills/php-forge-debug-core
@@ -0,0 +1 @@
+../../skills/php-forge-debug-core
\ No newline at end of file
diff --git a/.gitattributes b/.gitattributes
index cddb187..61170e8 100644
--- a/.gitattributes
+++ b/.gitattributes
@@ -52,3 +52,27 @@
# Avoid merge conflicts in CHANGELOG
# https://about.gitlab.com/2015/02/10/gitlab-reduced-merge-conflicts-by-90-percent-with-changelog-placeholders/
/CHANGELOG.md merge=union
+
+/.agents export-ignore
+
+/.claude export-ignore
+
+/internal export-ignore
+/vendor export-ignore
+/node_modules export-ignore
+/.env export-ignore
+/.env.* export-ignore
+
+/.phpunit.cache export-ignore
+
+/.phpunit.result.cache export-ignore
+
+/.stryker-tmp export-ignore
+
+/.codex export-ignore
+
+/.config export-ignore
+
+/reports/mutation export-ignore
+
+/artifacts export-ignore
diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
index dc810d8..a740535 100644
--- a/.github/workflows/build.yml
+++ b/.github/workflows/build.yml
@@ -17,7 +17,7 @@ permissions:
jobs:
phpunit:
- uses: yii2-framework/actions/.github/workflows/phpunit.yml@a28eb7d4ab03abd53ccd7c79014b3b27d09932ff # v2.0.1
+ uses: php-forge/actions/.github/workflows/phpunit.yml@4aaec87a6fdc921e51a554912ceb07dacf18916f # v3.0.2
secrets:
CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
with:
diff --git a/.github/workflows/dependency-check.yml b/.github/workflows/dependency-check.yml
index c938637..75d0bc0 100644
--- a/.github/workflows/dependency-check.yml
+++ b/.github/workflows/dependency-check.yml
@@ -17,4 +17,4 @@ permissions:
jobs:
composer-require-checker:
- uses: yii2-framework/actions/.github/workflows/composer-require-checker.yml@a28eb7d4ab03abd53ccd7c79014b3b27d09932ff # v2.0.1
+ uses: php-forge/actions/.github/workflows/composer-require-checker.yml@4aaec87a6fdc921e51a554912ceb07dacf18916f # v3.0.2
diff --git a/.github/workflows/ecs.yml b/.github/workflows/ecs.yml
index e4159b4..a2a78fd 100644
--- a/.github/workflows/ecs.yml
+++ b/.github/workflows/ecs.yml
@@ -17,4 +17,4 @@ permissions:
jobs:
easy-coding-standard:
- uses: yii2-framework/actions/.github/workflows/ecs.yml@a28eb7d4ab03abd53ccd7c79014b3b27d09932ff # v2.0.1
+ uses: php-forge/actions/.github/workflows/ecs.yml@4aaec87a6fdc921e51a554912ceb07dacf18916f # v3.0.2
diff --git a/.github/workflows/mutation.yml b/.github/workflows/mutation.yml
index 90dabee..e530829 100644
--- a/.github/workflows/mutation.yml
+++ b/.github/workflows/mutation.yml
@@ -17,7 +17,7 @@ permissions:
jobs:
mutation:
- uses: yii2-framework/actions/.github/workflows/infection.yml@a28eb7d4ab03abd53ccd7c79014b3b27d09932ff # v2.0.1
+ uses: php-forge/actions/.github/workflows/infection.yml@4aaec87a6fdc921e51a554912ceb07dacf18916f # v3.0.2
with:
command-options: --threads=4 --ignore-msi-with-no-mutations
phpstan: true
diff --git a/.github/workflows/quality.yml b/.github/workflows/quality.yml
index 613b0ca..1b5236f 100644
--- a/.github/workflows/quality.yml
+++ b/.github/workflows/quality.yml
@@ -10,7 +10,7 @@ permissions:
jobs:
quality:
- uses: yii2-framework/actions/.github/workflows/quality.yml@a28eb7d4ab03abd53ccd7c79014b3b27d09932ff # v2.0.1
+ uses: php-forge/actions/.github/workflows/quality.yml@4aaec87a6fdc921e51a554912ceb07dacf18916f # v3.0.2
permissions:
contents: read
with:
diff --git a/.github/workflows/scorecard.yml b/.github/workflows/scorecard.yml
new file mode 100644
index 0000000..0640a44
--- /dev/null
+++ b/.github/workflows/scorecard.yml
@@ -0,0 +1,23 @@
+---
+on:
+ branch_protection_rule:
+ push:
+ branches:
+ - main
+ schedule:
+ - cron: "30 1 * * 6"
+
+name: scorecard
+
+permissions:
+ contents: read
+
+jobs:
+ scorecard:
+ uses: php-forge/actions/.github/workflows/scorecard.yml@4aaec87a6fdc921e51a554912ceb07dacf18916f # v3.0.2
+ permissions:
+ contents: read # Required to check out the repository.
+ id-token: write # Required to sign published results with the GitHub OIDC token.
+ security-events: write # Required to upload SARIF results to code scanning.
+ with:
+ publish-results: true
diff --git a/.github/workflows/security.yml b/.github/workflows/security.yml
index 6a771ba..29b8119 100644
--- a/.github/workflows/security.yml
+++ b/.github/workflows/security.yml
@@ -10,7 +10,7 @@ permissions:
jobs:
security:
- uses: yii2-framework/actions/.github/workflows/security.yml@a28eb7d4ab03abd53ccd7c79014b3b27d09932ff # v2.0.1
+ uses: php-forge/actions/.github/workflows/security.yml@4aaec87a6fdc921e51a554912ceb07dacf18916f # v3.0.2
permissions:
contents: read
with:
diff --git a/.github/workflows/static.yml b/.github/workflows/static.yml
index 108f5a6..455657f 100644
--- a/.github/workflows/static.yml
+++ b/.github/workflows/static.yml
@@ -17,4 +17,4 @@ permissions:
jobs:
phpstan:
- uses: yii2-framework/actions/.github/workflows/phpstan.yml@a28eb7d4ab03abd53ccd7c79014b3b27d09932ff # v2.0.1
+ uses: php-forge/actions/.github/workflows/phpstan.yml@4aaec87a6fdc921e51a554912ceb07dacf18916f # v3.0.2
diff --git a/.gitignore b/.gitignore
index b1939a5..73a398c 100644
--- a/.gitignore
+++ b/.gitignore
@@ -48,3 +48,16 @@ vendor
# windows thumbnail cache (if present)
Thumbs.db
+
+# Package skill discovery; keep other local client state private.
+!/.agents/
+/.agents/*
+!/.agents/skills/
+/.agents/skills/*
+!/.agents/skills/php-forge-debug-core
+!/.claude/
+/.claude/*
+!/.claude/skills/
+/.claude/skills/*
+!/.claude/skills/php-forge-debug-core
+/internal/
diff --git a/CHANGELOG.md b/CHANGELOG.md
index e14acef..530a94a 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,6 +7,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
## 0.1.3 Under development
+- docs(skills): add the package skill and AI guide; add `README.md` Security and Built with AI sections and Scorecard badge.
+
## 0.1.2 November 6, 2026
- feat(log): render multi-line log messages with preserved whitespace, `print_r()` dumps as a tree, and `var_export()` values highlighted.
diff --git a/README.md b/README.md
index d782a1e..f0a8feb 100644
--- a/README.md
+++ b/README.md
@@ -12,15 +12,15 @@
+
+
+
-
-
-
@@ -30,8 +30,8 @@
## Features
-
-
+
+
## Installation
@@ -92,6 +92,28 @@ npm run check:icons
`check:icons` compares the toolbar's inline glyphs with `resources/assets/svg`; the toolbar-only chrome glyphs
(`chevron-left`, `chevron-right`, `close`, `external-link`) have no panel file by design and never fail `--strict`.
+## Documentation
+
+This package has no separate guides; its documentation topics live in this README and the source PHPDoc.
+
+- 📦 [Installation](#installation)
+- 🧩 [Adapter boundary](#adapter-boundary)
+- 🎨 [Frontend development](#frontend-development)
+
+## AI assistance
+
+AI agents: read the [documentation index](https://yii2-framework.github.io/docs/llms.txt) and fetch the Markdown version
+of a page by appending `index.md` to its URL. The
+[AI agents guide](https://github.com/yii2-framework/docs/blob/main/src/content/docs/project/ai-agents.md) covers skill
+installation, client setup and verification.
+
+- 🤖 [`php-forge-debug-core` skill](https://github.com/php-forge/debug-core/blob/main/docs/agents.md): building a
+ debugger adapter on the core, with snapshot storage and read diagnostics, log context redaction, the routing
+ contract and the toolbar frontend sources.
+
+See the [repository guides](#documentation), the [skill source](skills/php-forge-debug-core/SKILL.md), the source PHPDoc
+and the [changelog](CHANGELOG.md).
+
## Package information
[](https://www.php.net/releases/8.3/en.php)
@@ -101,10 +123,20 @@ npm run check:icons
## Code quality
-[](https://codecov.io/gh/php-forge/debug-core)
[](https://github.com/php-forge/debug-core/actions/workflows/quality.yml)
[](https://github.com/php-forge/debug-core/actions/workflows/assets.yml)
-[](https://github.styleci.io/repos/php-forge/debug-core?branch=main)
+[](https://github.styleci.io/repos/1334500828?branch=main)
+
+## Security
+
+[](https://scorecard.dev/viewer/?uri=github.com/php-forge/debug-core)
+[](https://github.com/php-forge/debug-core/actions/workflows/security.yml)
+
+## Built with AI
+
+[](https://claude.com/claude-code)
+[](https://openai.com/codex)
+[](https://www.coderabbit.ai)
## Social networks
diff --git a/composer.json b/composer.json
index e5db0d4..459a7ba 100644
--- a/composer.json
+++ b/composer.json
@@ -55,6 +55,9 @@
"extra": {
"branch-alias": {
"dev-main": "0.2.x-dev"
+ },
+ "skills": {
+ "source": "skills"
}
},
"config": {
diff --git a/docs/agents.md b/docs/agents.md
new file mode 100644
index 0000000..820398e
--- /dev/null
+++ b/docs/agents.md
@@ -0,0 +1,63 @@
+# AI assistance
+
+Use the package-owned [php-forge-debug-core](../skills/php-forge-debug-core/SKILL.md) skill for integrating PHP Forge debugger snapshots, storage and adapter boundaries. The canonical source is `skills/`; checkout discovery links in `.agents/skills/` and `.claude/skills/` point to that same source.
+
+## Install in an application
+
+### Automatic Composer installation
+
+Composer is the primary distribution path. `extra.skills.source` declares the bundle; installing the package alone does
+not register its skill at the application root. In a consumer already configured for `llm/skills`, explicitly trust
+`php-forge/debug-core` and use that installed synchronizer's documented setup. Do not enable plugins or broaden trust by
+copying an example.
+
+```bash
+composer install
+composer skills:show
+```
+
+With verified auto-sync enabled, installation/update can synchronize the bundle; otherwise run
+`composer skills:update` and inspect `composer skills:show`. Composer exit zero is not proof of client activation.
+
+### Optional npx installation
+
+An optional pinned installer can use a local checkout or an installed package that contains the bundle:
+
+```bash
+npx skills@1.7.2 add /absolute/path/to/debug-core --list
+npx skills@1.7.2 add /absolute/path/to/debug-core --skill php-forge-debug-core --agent claude-code codex opencode
+```
+
+Keep project scope. Inspect a remote source with `--list` before claiming an unpublished skill is available there.
+After upgrading the package, repeat the `npx skills@1.7.2 add` installation command above to refresh copied and
+symlinked installations. Symlinks point to the installer's canonical copy, which does not update with the package.
+The complete skill directory is the unit of installation.
+
+## Discover and invoke
+
+Open a fresh client session at the checkout or consumer root. Codex discovers `.agents/skills/php-forge-debug-core/` and supports
+`$php-forge-debug-core` or its skill picker. Claude Code uses `.claude/skills/php-forge-debug-core/` and `/php-forge-debug-core`. For OpenCode, verify the
+installed client's native skill tool and shared paths. Do not assume one client's invocation syntax works in another.
+
+## Example prompts
+
+Explicit Codex invocation:
+
+```text
+$php-forge-debug-core
+Outline an adapter using the installed snapshot and routing contracts. Verify missing/corrupt snapshot handling and request isolation without changing production routes or exposing diagnostics.
+```
+
+For natural selection, repeat the task without the first line. Record whether the client loads this skill rather than
+a global same-named copy. As an unrelated negative control, ask it to explain HTTP 301 versus 302 without inspecting the
+repository or loading package skills.
+
+## Verify the result
+
+Capture the native load/tool evidence and selected source path, then execute the generated task checks against the
+installed package. Cover the normal operation, the described boundary case and a failure/unsupported input. Inspect
+generated code before executing it; use disposable fixtures for writes. Run the package's actual non-mutating checks
+and report runtime versions, warnings and unavailable dependencies. Listing, manually reading the skill, or supplying
+its body in a prompt does not prove native activation or functional execution.
+
+[Back to README](../README.md)
diff --git a/skills/php-forge-debug-core/SKILL.md b/skills/php-forge-debug-core/SKILL.md
new file mode 100644
index 0000000..c05a898
--- /dev/null
+++ b/skills/php-forge-debug-core/SKILL.md
@@ -0,0 +1,41 @@
+---
+name: php-forge-debug-core
+description: Use when building or maintaining a debugger adapter on php-forge/debug-core, covering snapshot storage, capture redaction, panel URL generation, toolbar injection and the shared frontend sources. Not for installing the debugger in an application, which goes through yii2-extensions/debug or yii3/debug, nor for framework routes, access policy or asset publishing.
+license: BSD-3-Clause
+---
+
+# Use php-forge/debug-core
+
+## Resolve the package
+
+Inspect the installed package path, actual source and Composer metadata before choosing APIs. The current PHP constraint
+is `>=8.3`. A lockfile or branch alias alone does not prove the installed files match it. Use
+local guides at that revision; if a guide is excluded from the archive, consult the matching repository revision, not
+unverified current documentation. Installing this skill does not install dependencies or authorize mutations.
+
+## Package contracts
+
+Applications normally install a framework adapter; this package owns common storage, snapshots, renderers and
+frontend resources. Adapters own routing, access policy, assets and the decision to inject the toolbar. Collectors
+implement `PHPForge\Debug\CollectorInterface` from `php-forge/debug`. Implement
+`PHPForge\Debug\Routing\DebugUrlGeneratorInterface` rather than importing a framework URL manager into the core.
+
+These behaviors are intended; do not "fix" them as incidental cleanups:
+
+- `Storage\SnapshotStore::readSnapshot()` returns `null` for a missing, corrupt or invalid-tag snapshot and hides the
+ cause. Use `readSnapshotResult()` when the diagnostic matters: a missing snapshot yields no snapshot and no error,
+ while a corrupt file or an invalid tag yields a `StorageException` in `error`.
+- `Panel\Log\LogContext::normalize()` applies the host `Capture\CapturePolicy` to the PSR-3 context only. The core
+ does not redact the log message text; do not add redaction there.
+- `Toolbar\ToolbarInjector::inject()` inserts the markup before the last case-insensitive `