docs: add AI guidance and the Foxy integration skill.

.agents/skills/php-forge-foxy

@@ -0,0 +1 @@
+../../skills/php-forge-foxy

.claude/skills/php-forge-foxy

@@ -0,0 +1 @@
+../../skills/php-forge-foxy

.editorconfig

@@ -17,7 +17,7 @@ indent_size = 2
 indent_size = 2
 
 [*.md]
-indent_size = 2
+indent_size = unset
 trim_trailing_whitespace = false
 
 [*.php]

.gitattributes

@@ -26,10 +26,16 @@
 /CHANGELOG.md		merge=union
 
 # Exclude files from the archive
+/.agents                        export-ignore
+/.claude                        export-ignore
+/AGENTS.md                      export-ignore
+/internal                       export-ignore
 /.editorconfig                  export-ignore
 /.gitattributes                 export-ignore
 /.github                        export-ignore
 /.gitignore                     export-ignore
+/.prettierignore                export-ignore
+/.prettierrc.json               export-ignore
 /.styleci.yml                   export-ignore
 /codeception.yml                export-ignore
 /composer-require-checker.json  export-ignore

.github/linters/.codespellrc

@@ -1,2 +1,2 @@
 [codespell]
-skip = ./.git,.vscode/*,composer.lock,runtime/*,vendor/*
+skip = ./.git,./.vscode/*,./composer.lock,./runtime/*,./vendor/*,./internal/*,./node_modules/*,./foxy.lock,./.phpunit.cache/*,./code_coverage/*

.github/linters/.editorconfig-checker.json

@@ -2,6 +2,11 @@
     "Exclude": [
         "^composer\\.lock$",
         "^runtime/",
-        "^vendor/"
+        "^vendor/",
+        "^internal/",
+        "^node_modules/",
+        "^foxy\\.lock$",
+        "^\\.phpunit\\.cache/",
+        "^code_coverage/"
     ]
 }

.github/linters/.markdown-lint.yml

@@ -1,5 +1,12 @@
 ---
-MD007:
-  indent: 2
-MD013: false
-MD033: false
+config:
+  MD007:
+    indent: 2
+  MD013: false
+  MD033: false
+ignores:
+  - .vscode/**
+  - vendor/**
+  - node_modules/**
+  - internal/**
+  - runtime/**

.github/linters/.yamllint.yml

@@ -0,0 +1,9 @@
+---
+extends: default
+rules:
+  comments:
+    min-spaces-from-content: 1
+  line-length: disable
+  truthy: disable
+ignore: |
+  .yii2-framework-actions/

.github/workflows/quality.yml

@@ -17,5 +17,7 @@ jobs:
       codespell-config: .github/linters/.codespellrc
       editorconfig-checker-config: .github/linters/.editorconfig-checker.json
       markdownlint-config: .github/linters/.markdown-lint.yml
-      prettier-ignore-path: .gitignore
+      prettier-config: .prettierrc.json
+      prettier-ignore-path: .prettierignore
+      yamllint-config: .github/linters/.yamllint.yml
       yamllint-targets: .github

.prettierignore

@@ -0,0 +1,18 @@
+# Local editor and generated runtime state.
+.vscode/**
+runtime/**
+
+# Dependencies.
+node_modules/**
+vendor/**
+
+# Dependency lockfiles.
+composer.lock
+foxy.lock
+
+# License texts ship verbatim.
+**/LICENSE*
+
+# Private maintainer files and coverage reports.
+code_coverage/**
+internal/**

.prettierrc.json

@@ -0,0 +1,30 @@
+{
+    "tabWidth": 4,
+    "useTabs": false,
+    "singleQuote": false,
+    "trailingComma": "all",
+    "printWidth": 80,
+    "overrides": [
+        {
+            "files": ["**/*.{cjs,css,js,mjs,yml,yaml}"],
+            "options": {
+                "tabWidth": 2
+            }
+        },
+        {
+            "files": "**/*.md",
+            "options": {
+                "embeddedLanguageFormatting": "off",
+                "printWidth": 120,
+                "proseWrap": "always",
+                "tabWidth": 2
+            }
+        },
+        {
+            "files": "CHANGELOG.md",
+            "options": {
+                "proseWrap": "preserve"
+            }
+        }
+    ]
+}

AGENTS.md

@@ -0,0 +1,15 @@
+# Foxy repository guide
+
+Foxy is the `php-forge/foxy` Composer plugin. Inspect `composer.json`, the current Git diff, relevant source and tests
+before changing behavior. Preserve existing staged and unstaged work. Public documentation is English; use `docs/` for
+usage and configuration and `skills/php-forge-foxy/` as the canonical agent skill. Client discovery paths link to that
+source.
+
+The plugin merges eligible Composer assets and uses the selected frontend manager or its own native manager. Preserve
+user-owned dependencies, manager and lockfile semantics, managed-directory safeguards, audit failure reporting and
+fallback behavior. The root `composer.json` is not restored by Foxy's fallback. Check `docs/config.md` and
+`docs/usage.md` for the precise contracts before suggesting changes.
+
+Use the applicable checks in `docs/testing.md`; commands such as `composer ecs` and `composer rector` modify files. Run
+only appropriate non-mutating checks and report missing dependencies or skipped scenarios. Keep changes local and do not
+stage, commit or publish unless explicitly requested.

CHANGELOG.md

@@ -7,6 +7,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## 0.4.1 Under development
 
+- docs: add AI guidance and the Foxy integration skill.
+
 ## 0.4.0 October 11, 2026
 
 - refactor: deduplicate internals, centralize exception messages in `Foxy\Exception\Message`, and normalize their wording.

README.md

@@ -73,19 +73,19 @@ Selecting a manager explicitly is recommended for reproducible local and CI beha
 }
 ```
 
-Valid manager values are `bun`, `deno`, `native`, `npm`, `pnpm`, and `yarn`. When automatic manager execution is
-enabled and `manager` is omitted, Foxy first looks for one recognized lockfile and then checks available executables.
-Configure the manager explicitly when the project contains lockfiles from more than one manager.
+Valid manager values are `bun`, `deno`, `native`, `npm`, `pnpm`, and `yarn`. When automatic manager execution is enabled
+and `manager` is omitted, Foxy first looks for one recognized lockfile and then checks available executables. Configure
+the manager explicitly when the project contains lockfiles from more than one manager.
 
 During automatic Composer processing, `run-asset-manager=false` prevents Foxy from requiring or probing a manager
 binary. Automatic selection uses the single recognized lockfile when present, or npm as the manifest adapter when no
 lockfile exists. An explicit `composer foxy:audit` still validates and runs the selected manager.
 
 ## Without Node.js
 
-Set `manager` to `native` and Foxy resolves the merged `package.json` against the npm registry, downloads the
-tarballs, verifies their integrity, and extracts them into a flat `node_modules` directory using PHP alone (or into
-the directory `native-install-dir` names):
+Set `manager` to `native` and Foxy resolves the merged `package.json` against the npm registry, downloads the tarballs,
+verifies their integrity, and extracts them into a flat `node_modules` directory using PHP alone (or into the directory
+`native-install-dir` names):
 
 ```json
 {
@@ -99,8 +99,8 @@ the directory `native-install-dir` names):
 
 The selected versions are recorded in `foxy.lock`; commit it so that `composer install` reinstalls the same versions
 without any registry metadata request. Tarballs come from the Composer cache, or are downloaded again from the URLs
-recorded in the lock when the cache is empty. The native manager keeps one version per package, like asset-packagist, and
-does not run lifecycle scripts. `native-install-dir` moves the install directory, for example to `vendor/npm-asset`
+recorded in the lock when the cache is empty. The native manager keeps one version per package, like asset-packagist,
+and does not run lifecycle scripts. `native-install-dir` moves the install directory, for example to `vendor/npm-asset`
 for Yii 2's default `@npm` alias. See the [native manager reference](docs/config.md#native-manager) for its scope.
 
 ## Frontend security audit
@@ -115,9 +115,8 @@ composer foxy:audit --format=summary --no-dev --audit-level=high
 Foxy normalizes the current npm, pnpm, Yarn, Bun, Deno, and native audit reports and identifies the affected package,
 advisory, severity, vulnerable range, and CVE identifiers when GitHub maps the advisory to a CVE. The command returns
 `0` when no advisory meets the configured threshold, `1` when at least one does, and `2` when the audit cannot be
-completed reliably. With Deno and the `native` manager, `--no-dev` is rejected because neither can exclude
-development dependencies.
-See the [usage guide](docs/usage.md#security-auditing) for formats and CI examples.
+completed reliably. With Deno and the `native` manager, `--no-dev` is rejected because neither can exclude development
+dependencies. See the [usage guide](docs/usage.md#security-auditing) for formats and CI examples.
 
 ## Quick start
 
@@ -145,36 +144,56 @@ Composer may remain at the repository root while frontend tooling runs from `web
 }
 ```
 
-Foxy reads and writes `web/package.json` and runs the selected manager from `web/`. Relative paths are resolved from
-the Composer project directory.
+Foxy reads and writes `web/package.json` and runs the selected manager from `web/`. Relative paths are resolved from the
+Composer project directory.
 
 ## Documentation
 
-- [Getting started](docs/index.md)
-- [Configuration reference](docs/config.md)
-- [Usage guide](docs/usage.md)
-- [Events reference](docs/events.md)
-- [Frequently asked questions](docs/faqs.md)
-- [Upgrade guide](UPGRADE.md)
-- [Testing guide](docs/testing.md)
+- 📚 [Getting started](docs/index.md)
+- ⚙️ [Configuration reference](docs/config.md)
+- 💡 [Usage guide and examples](docs/usage.md)
+- 🔌 [Events reference](docs/events.md)
+- ❓ [Frequently asked questions](docs/faqs.md)
+- 🤖 [AI agents guide](docs/agents.md)
+- ⬆️ [Upgrade guide](UPGRADE.md) and [migration guide](docs/migration.md)
+- 🧪 [Testing guide](docs/testing.md)
+
+## AI assistance
+
+AI agents can use the [documentation index](https://yii2-framework.github.io/docs/llms.txt) to discover pages and fetch
+a page's Markdown version by appending `index.md` to its URL. The
+[AI agents guide](https://yii2-framework.github.io/docs/project/ai-agents/) covers skill installation, client setup, and
+verification.
+
+- 🤖 [`php-forge-foxy` skill](docs/agents.md): configure asset integration and audits.
+
+Match the documentation to the installed Foxy revision. If the hosted documentation is unavailable or does not match,
+use the [repository guides](#documentation), [skill source](skills/php-forge-foxy/SKILL.md), source PHPDoc, and
+[changelog](CHANGELOG.md).
 
 ## Package information
 
 [![PHP](https://img.shields.io/badge/%3E%3D8.3-777BB4.svg?style=for-the-badge&logo=php&logoColor=white)](https://www.php.net/releases/8.3/en.php)
 [![Latest Stable Version](https://img.shields.io/packagist/v/php-forge/foxy.svg?style=for-the-badge&logo=packagist&logoColor=white&label=Stable)](https://packagist.org/packages/php-forge/foxy)
 [![Total Downloads](https://img.shields.io/packagist/dt/php-forge/foxy.svg?style=for-the-badge&logo=composer&logoColor=white&label=Downloads)](https://packagist.org/packages/php-forge/foxy)
 
-## Code quality
+## Project status
 
 [![Codecov](https://img.shields.io/codecov/c/github/php-forge/foxy.svg?style=for-the-badge&logo=codecov&logoColor=white&label=Coverage)](https://codecov.io/gh/php-forge/foxy)
 [![PHPStan Level 5](https://img.shields.io/badge/PHPStan-Level%205-4F5D95.svg?style=for-the-badge&logo=github&logoColor=white)](https://github.com/php-forge/foxy/actions/workflows/static.yml)
 [![Quality](https://img.shields.io/github/actions/workflow/status/php-forge/foxy/quality.yml?style=for-the-badge&label=Quality&logo=github)](https://github.com/php-forge/foxy/actions/workflows/quality.yml)
 [![StyleCI](https://img.shields.io/badge/StyleCI-Passed-44CC11.svg?style=for-the-badge&logo=github&logoColor=white)](https://github.styleci.io/repos/745652761?branch=main)
 
-## Community
+## Our social networks
 
 [![Follow on X](https://img.shields.io/badge/-Follow%20on%20X-1DA1F2.svg?style=for-the-badge&logo=x&logoColor=white&labelColor=000000)](https://x.com/Terabytesoftw)
 
+## Built with AI
+
+[![Built with Claude Code](https://img.shields.io/badge/Built%20with-Claude%20Code-D97757.svg?style=for-the-badge&logo=claude&logoColor=white)](https://claude.com/claude-code)
+[![Built with Codex](https://img.shields.io/badge/Built%20with-Codex-10A37F.svg?style=for-the-badge&logo=openaigym&logoColor=white)](https://openai.com/codex)
+[![Reviewed by CodeRabbit](https://img.shields.io/badge/Reviewed%20by-CodeRabbit-FF570A.svg?style=for-the-badge&logo=coderabbit&logoColor=white)](https://www.coderabbit.ai)
+
 ## License
 
 [![License](https://img.shields.io/badge/License-BSD--3--Clause-brightgreen.svg?style=for-the-badge&logo=opensourceinitiative&logoColor=white&labelColor=555555)](LICENSE)