amxx-builder 1.6.0 → 1.7.0

package/AGENTS.md

@@ -8,7 +8,7 @@ Entry: `index.js` (CLI via `commander`). Action: `action-entry.js` → synthesis
 - Node.js 18+, pure **CommonJS** (`require`), no ESM. Exception: `action-entry.js` uses `import * as core from '@actions/core'` because `@actions/core@3.x` is ESM-only — esbuild transpiles it to CJS in the bundle. Do not "fix" that import back to `require`, it fails to resolve.
 - **Node 18+ is a deliberate, genuinely minimal floor.** Write code that works on Node 18 — do not use newer-version-only APIs (stable `node:test` features, `fetch`, `AbortSignal.timeout`, …) unless they exist in 18. If a feature truly requires a newer Node, propose raising the minimum in the PR/discussion first; right now there is no practical benefit in raising it (no feature pressure, no dependency forcing it), and a raised floor would only cut off users stuck on 18. CI tests the matrix 18/24 (floor + newest) to keep this honest.
 - Only dev dep: `esbuild` for bundling the GitHub Action.
-- Tests: `node --test` (built-in node:test, zero deps; discovers `test/*.test.js` automatically — keep fixtures out of `test/`). No linter or type checker configured.
+- Tests: `node --test` (built-in node:test, zero deps; discovers `test/*.test.js`). Keep fixtures out of `test/`, and do NOT name non-test scripts `*-test.js` — the runner's default glob (`**/*-test.js`) would execute them as tests. The bundler smoke script is `scripts/smoke.js` (needs a bundled `dist/` + compiler cache, so it is run explicitly, never by the test runner). No linter or type checker configured.
 
 ## Architecture: logic lives once in the core
 - All business logic MUST live in `src/` (the core) and be interface-agnostic: no `process.argv`, no `process.stdout` writes, no `commander`, no JSON-RPC/MCP schemas, no CLI rendering.
@@ -21,6 +21,7 @@ Entry: `index.js` (CLI via `commander`). Action: `action-entry.js` → synthesis
   - Include-path candidate lists (`['scripting/include', 'amxmodx/scripting/include', 'include', '.']`) — single source: `src/deps-resolver.js` (`resolveIncludePath`)
   - Dep string parsing (`owner/repo@ref[:include_path]`) — single source: `src/manifest.js` (`parseDepsLines`)
   - GitHub token resolution — `src/manifest.js` (`resolveGithubToken`); repo key / normalization — `src/deps-resolver.js` (`repoKey`, `normalize`)
+  - Local sources — `source: local` resolution and `AMXB_LOCAL_SOURCES` env-override parsing, `_localDir` resolution, `_resolvedRef = 'local'` stamping, `ensureRepoDir` — single source: `src/local-sources.js` (`applyLocalOverrides`, `parseLocalSourcesEnv`, `ensureRepoDir`)
 - When touching an interface layer, check whether the logic already exists in `src/` before writing new code. New core exports are cheap; new duplication is debt.
 
 ## Commands
@@ -37,12 +38,17 @@ Entry: `index.js` (CLI via `commander`). Action: `action-entry.js` → synthesis
 | `amxb init` | Scaffold manifest and optional files |
 | `amxb init --force` | Scaffold, overwriting existing files (default: skip) |
 | `amxb init --script` | Also create `build.bat` / `build.sh` quick-build scripts |
+| `amxb init --vscode` | Also create `.vscode/extensions.json` with recommended extensions (alias `--vsc`; merges into an existing file) |
 | `amxb clean` | Clean build/ and clone cache |
 | `amxb clean --all` | Also clean compiler cache |
 | `amxb cache info` | Show cache contents |
+| `amxb skills-dir` | Print absolute path to the bundled `skills/` dir (used by the opencode bridge plugin) |
+| `amxb opencode-skills` | Print container path(s) of materialized skills (bundled + current project + deps/repos) for the opencode bridge |
 | `amxb serve` | Start JSON-RPC server for editor integration (stdio transport) |
 | `npm start` | Alias for `node index.js` |
 
+The opencode bridge plugin (`.opencode/plugin/amxb-skills.js`, generated by `amxb init --opencode`) registers skills from three sources: the builder's bundled `skills/` (`amxb skills-dir`), the current project's own `skills:`, and all `deps`/`repos` skills read from their manifests (`amxb opencode-skills`; missing ones fetched from the network on demand).
+
 ## Build order (matters)
 1. Parse manifest (deep-merge with `defaults/amxbuild.defaults.yml`)
 2. Fetch compiler (`amxxpc`, auto-resolves latest version)
@@ -58,15 +64,17 @@ Entry: `index.js` (CLI via `commander`). Action: `action-entry.js` → synthesis
 - **Arrays are replaced entirely** (repos, deps, assets.sources) — not merged with defaults.
 - `version` **must be a quoted string** in YAML or parsing fails.
 - `ref: latest` resolves to the latest GitHub release tag automatically.
-- Plugin rules (`plugins:`) apply **only to local** `.sma` files, not repo plugins.
+- `ref_ttl` (optional, git `repos[]`/`deps[]` objects only) sets the TTL of the `ref → SHA` resolution cache: `never`, a duration (`30m`/`1h`/`7d`), or an integer number of seconds. Default: a named ref GitHub confirms as a **tag** is cached forever; a branch (including the default branch when no `ref` is given) revalidates after 1 hour. When a ref name exists as both a tag and a branch, the tag wins and the ref is cached as immutable. Because clones are SHA-keyed, an unchanged SHA is never re-downloaded; a force-pushed tag is only picked up via an explicit `ref_ttl` or `amxb clean`. It does not affect `source: release`/`fungun`/`local`, `latest`, or `null` refs, and the string dep form / `DEPS_LIST` cannot express it.
+- Plugin rules (`plugins.rules:`) apply **only to local** `.sma` files, not repo plugins; `plugins.defaults` and `repos[].plugins` apply to all plugins. An effective non-`false` `ini` enables INI generation.
 - Local `amxmodx/` always wins over repo files (intentional override layer, no conflict warning).
 - `.sma` files ARE copied during collect (like any other file) and are also compiled; exclude them per-repo via `exclude_files` if sources should not ship.
+- `repos:`/`deps:` entries can be satisfied by a **local directory** instead of GitHub: `source: local` + `path` (relative to the manifest dir, or absolute; optional `name` gives the synthetic id `local/<name>`, defaulting to the path basename). A local repo is collected + its `.sma` compiled and may still set `amxmodx_dir` / `plugins` / `exclude` / `exclude_files` / `deps_override` (`repo`/`ref` forbidden; the deprecated `plugins_ini_postfix` is still accepted with a build warning); a local dep contributes `.inc` to `build/_includes/` (`repo`/`ref`/`id`/`url`/`asset` forbidden; object form only, the `owner/repo@ref[:include_path]` string stays git-only). Local sources are unpinned (the working tree is read as-is) so builds are not reproducible, and watch does not follow dirs outside the manifest's `amxmodx/`/`assets/`.
 
 ## GitHub Action release flow
 ```bash
 npm ci
 npm run bundle   # esbuild action-entry.js → dist/index.js + scripts/gen-licenses.js → dist/licenses.txt
-node scripts/smoke-test.js   # runs the bundled action with INPUT_* env, asserts GITHUB_OUTPUT name output
+node scripts/smoke.js   # runs the bundled action with INPUT_* env, asserts GITHUB_OUTPUT name output
 # Commit dist/, update package.json version, push tags, publish to npm (idempotent: re-runs are no-ops)
 ```
 This is automated in `.github/workflows/release.yml` on `v*.*.*` tags.
@@ -97,6 +105,8 @@ This is automated in `.github/workflows/release.yml` on `v*.*.*` tags.
 ## Cache
 - Win: `%LOCALAPPDATA%\amxx-builder`, Unix: `~/.cache/amxx-builder`
 - Override: `AMXX_BUILDER_CACHE`
+- Local source redirects: `AMXB_LOCAL_SOURCES` maps an existing repo/dep id (`owner/repo`) to a path (pairs `id=path` separated by `;`/newlines, or a JSON object), `AMXB_LOCAL_STRICT=1` makes an unmatched id an error (default: warn and ignore). `.env` next to the manifest is honored — see `src/local-sources.js`.
+- Plugin INI debug override: `AMXB_PLUGINS_DEBUG` (read from `.env` next to the manifest, local only — `.env` is gitignored) forces the ` debug` suffix in generated `plugins-*.ini` on/off for every included plugin. `1`/`true`/`yes`/`on` force on, `0`/`false`/`no`/`off` force off, anything else (unset/empty) leaves the manifest in charge. Case-insensitive. Precedence: `AMXB_PLUGINS_DEBUG` > per-rule/per-repo `debug` > `plugins.defaults.debug`; it only affects plugins already in an INI and never enables INI generation by itself.
 - Local per-manifest asset cache: `.amxb-cache/` next to `amxbuild.yml`
 - Separate dirs: `repos/`, `release-deps/`, `amxxpc/` (compiler binaries)
 

package/README.md

@@ -60,6 +60,11 @@ $env:AMXB_VERSION="v1.2.3"; irm https://raw.githubusercontent.com/AmxxModularEco
 
 Расширение для VSCode - [AMXB — AMX Mod X Builder](https://marketplace.visualstudio.com/items?itemName=amxx-modular-ecosystem.amxb-vscode).
 
+Команда `amxb init --vscode` создаёт `.vscode/extensions.json` с рекомендациями расширений
+для AMXX-проекта (`Faktor.amxx-pawn-all-in` + `amxx-modular-ecosystem.amxb-vscode`).
+Существующий файл не перезаписывается: рекомендации проекта сохраняются, недостающие
+добавляются.
+
 ## Использование
 
 ```bash
@@ -80,11 +85,16 @@ amxb init --deploy                  # + создать .env с заготовк
 amxb init --plugin <name>           # + создать amxmodx/scripting/<name>.sma
 amxb init --workflow                # + создать .github/workflows/ci.yml
 amxb init --script                  # + создать build.bat / build.sh для быстрого запуска amxb build
+amxb init --opencode                # + создать .opencode/ (opencode.json с MCP-конфигом + мост скиллов)
+amxb init --vscode                  # + создать .vscode/extensions.json с рекомендациями расширений (алиас: --vsc)
 amxb init --force                   # перезаписать существующие файлы (по умолчанию пропускаются)
+amxb init --force --with-manifest   # + перезаписать и существующий amxbuild.yml (без --with-manifest манифест не трогается)
 
 amxb clean                          # очистить build/ и кэш клонов
 amxb clean --all                    # + кэш компилятора
 amxb cache info                     # показать содержимое кэша
+
+amxb opencode-skills                # пути к материализованным скиллам (bundled + проект + deps/repos) для моста opencode
 ```
 
 Кэш хранится в `%LOCALAPPDATA%\amxx-builder` (Windows) или `~/.cache/amxx-builder` (Unix).  
@@ -145,27 +155,81 @@ my-server/
       weapon.wav
 ```
 
-## Управление локальными плагинами
+## Управление плагинами и INI
 
-Поле `plugins:` позволяет фильтровать и распределять плагины из `amxmodx/scripting/` по INI-файлам. Применяется **только к локальным** плагинам; плагины из репо используют `plugins_ini_postfix` своего репо. Первое совпадение побеждает.
+Секция `plugins:` описывает, какие плагины попадают в INI-файлы, как эти файлы называются и добавлять ли к строке плагина ` debug`. Она состоит из двух частей:
 
-```yaml
-plugins_ini_postfix: myserver   # глобальный постфикс → plugins-myserver.ini
+- `defaults:` — базовый слой, применяется ко **всем** плагинам (локальным и из репо);
+- `rules:` — glob-правила **только для локальных** `.sma` из `amxmodx/scripting/`; первое совпадение побеждает.
 
+```yaml
 plugins:
-  - match: "VipM/*.sma"
-    ini: vipm             # → plugins-vipm.ini
-  - match: "utils/*.sma"
-    ini: false            # компилировать, но не включать ни в один INI
-  - match: "wip/*.sma"
-    enabled: false        # полностью пропустить (не компилировать, не деплоить)
+  defaults:
+    ini: myserver        # базовый INI для всех плагинов → plugins-myserver.ini
+    debug: false         # true → к каждой строке добавляется " debug"
+  rules:
+    - match: "VipM/*.sma"
+      ini: vipm          # → plugins-vipm.ini (переопределяет defaults)
+      debug: true        # vip_core.amxx debug
+    - match: "utils/*.sma"
+      ini: false         # компилировать, но не включать ни в один INI
+    - match: "wip/*.sma"
+      enabled: false     # полностью пропустить (не компилировать, не деплоить)
 ```
 
-| Поле | По умолчанию | Описание |
-| --- | --- | --- |
-| `match` | — | Glob-паттерн относительно `scripting/` |
-| `enabled` | `true` | `false` — пропустить компиляцию и деплой |
-| `ini` | `plugins_ini_postfix` | Постфикс INI, `false` — не включать в INI |
+Плагины из репозитория настраиваются на самом репо:
+
+```yaml
+repos:
+  - repo: Org/VipModular
+    plugins:
+      ini: vip           # → plugins-vip.ini
+      debug: false
+```
+
+**Значения `ini`:**
+
+| Значение | Результат |
+| --- | --- |
+| `false` | Скомпилировать, но не включать ни в один INI |
+| `true` или `""` | Включить в `plugins.ini` |
+| `"<postfix>"` | Включить в `plugins-<postfix>.ini` |
+| не задано | Наследуется у более низкого слоя приоритета |
+
+**Поля:**
+
+| Поле | Где | По умолчанию | Описание |
+| --- | --- | --- | --- |
+| `defaults.ini` | `plugins` | — | Базовый INI для всех плагинов |
+| `defaults.debug` | `plugins` | `false` | `true` — к строке плагина добавляется ` debug` |
+| `rules[].match` | `plugins` | — | Glob-паттерн относительно `scripting/` |
+| `rules[].enabled` | `plugins` | `true` | `false` — пропустить компиляцию и деплой |
+| `rules[].ini` | `plugins` | `defaults.ini` | Значение `ini` для совпавших локальных плагинов |
+| `rules[].debug` | `plugins` | `defaults.debug` | `debug` для совпавших локальных плагинов |
+| `repos[].plugins.ini` | репо | `defaults.ini` | Значение `ini` для плагинов этого репо |
+| `repos[].plugins.debug` | репо | `defaults.debug` | `debug` для плагинов этого репо |
+
+**Приоритет:** `plugins.rules` → `repos[].plugins` → `plugins.defaults` → выключено (без INI). Правила `rules` действуют только на локальные плагины; `defaults` и `repos[].plugins` — на все.
+
+Генерация INI включается сама, как только любое эффективное значение `ini` не `false` (задано в `defaults`, в правиле или на репо). Если `defaults.ini` при этом не задан, а INI включён только правилом или репо, все остальные плагины попадают в `plugins.ini`. Если `ini` не задано нигде — INI-файлы не создаются.
+
+Старая форма `plugins:` — массив правил без `defaults` — ещё принимается. Поля `output.generate_ini`, верхнеуровневый `plugins_ini_postfix` и `repos[].plugins_ini_postfix` устарели: они продолжают работать, но при сборке пишут предупреждение. Используйте вместо них `plugins.defaults.ini` и `repos[].plugins`.
+
+### Локальное переключение `debug` через `.env`
+
+Рядом с манифестом можно положить `.env` (он в `.gitignore` и в репозиторий не попадает). Переменная `AMXB_PLUGINS_DEBUG` в этом файле принудительно включает или выключает суффикс ` debug` **у всех** плагинов в уже сгенерированных `plugins-*.ini`, независимо от манифеста:
+
+```env
+AMXB_PLUGINS_DEBUG=1
+```
+
+| Значение | Результат |
+| --- | --- |
+| `1` / `true` / `yes` / `on` | Принудительно добавить ` debug` каждому плагину в INI |
+| `0` / `false` / `no` / `off` | Принудительно убрать ` debug` |
+| пусто / не задано / другое | Без переопределения, решает манифест |
+
+Значения регистронезависимы. Приоритет: `AMXB_PLUGINS_DEBUG` → `plugins.rules[].debug` / `repos[].plugins.debug` → `plugins.defaults.debug`. Переменная действует только на плагины, которые и так попадают в INI, и **не** включает генерацию INI сама по себе. Удобно для локальной отладки: включите ` debug` в `.env`, не коммитя правку в общий манифест.
 
 ## Удалённые ассеты
 
@@ -246,6 +310,8 @@ AMXB_DEPLOY_RCON_CMD=amxx load {plugin}
 deploy:
   path: /home/user/hlds/cstrike    # корень сервера (где лежат addons/, models/)
   amxmodx_path: addons/amxmodx     # default: addons/amxmodx
+  assets_path: ""                  # default: "" = корень deploy.path (assets/models, assets/sound → models/, sound/)
+                                   # Задайте, например, "{name}", чтобы зеркалировать layout архива
   watch_debounce_ms: 500           # мс стабильности файла перед ребилдом (default: 500)
   exclude:                         # пути от deploy.path, которые не перезаписываются
     - addons/amxmodx/configs/      # сохранить конфиги сервера
@@ -257,6 +323,13 @@ deploy:
     command: "amxx load {plugin}"  # {plugin} = имя без .amxx; пусто = не слать
 ```
 
+> **Деплой аддитивен.** `amxb deploy` только копирует файлы из `build/` в `deploy.path` и
+> никогда не удаляет на сервере то, чего нет в источнике — на сервере могут жить и другие
+> плагины/файлы, не управляемые этим манифестом. Удаление с сервера происходит только в
+> watch-режиме для файлов, удалённых локально во время слежения. Если нужно «вычистить»
+> осиротевшие файлы (например, после переименования плагина) — удалите их вручную или
+> очистите каталог перед `amxb deploy`.
+
 `amxb watch` отслеживает изменения в `amxmodx/` и `assets/`:
 
 - `.sma` → пересобрать плагин, задеплоить `.amxx`, послать RCON
@@ -291,6 +364,72 @@ github:
 
 Мапа применяется ко всему: репозитории из `repos:`, зависимости (`deps`/`DEPS_LIST`/`deps_override`), GitHub release-ассеты в `assets.sources` и команда `amxb deps-tree`. Для транзитивных зависимостей токен подбирается по владельцу автоматически.
 
+## Локальные источники (repos/deps)
+
+Запись в `repos:` или `deps:` можно взять не с GitHub, а из локальной папки. Содержимое читается как есть, как соседние `amxmodx/` и `assets/`: локальный репозиторий собирается вместе с проектом (его `.sma` компилируются), а локальная зависимость отдаёт свои `.inc` в `build/_includes/`.
+
+**Локальный репозиторий** (полноценная часть сборки):
+
+```yaml
+repos:
+  - source: local
+    path: ../ProjectA          # относительно папки манифеста (или абсолютный)
+    name: projecta             # необязательно; по умолчанию basename пути
+    # также поддерживаются amxmodx_dir, plugins (ini/debug),
+    # exclude, exclude_files, deps_override
+    # устаревший plugins_ini_postfix ещё принимается (с предупреждением)
+```
+
+`path` обязателен, `name` необязателен. Внутренний id такой записи: `local/<name>`, по умолчанию `local/<basename пути>`. Поля `repo` и `ref` указывать нельзя. `DEPS_LIST` и `deps_override` локального репо продолжают работать.
+
+**Локальная зависимость** (только `.inc` для компиляции):
+
+```yaml
+deps:
+  - source: local
+    path: ../Shared
+    name: shared                       # необязательно
+    include_path: scripting/include    # необязательно
+```
+
+`path` обязателен, `name` и `include_path` необязательны. Поля `repo`, `ref`, `id`, `url`, `asset` запрещены. Строковая форма `owner/repo@ref[:include_path]` остаётся только для git, локальный dep задаётся объектом.
+
+Все интерфейсы видят локальные источники одинаково: `amxb build`, `--dry-run`, `deps-tree`, `watch`, serve (`build.plan`) и MCP (`build_plan`, `get_dep_tree`, `validate_manifest`).
+
+### Интеграция проектов через AMXB_LOCAL_SOURCES
+
+Чтобы собрать проект B против локального чекаута проекта A (без релиза), манифест править не нужно. Переменная `AMXB_LOCAL_SOURCES` перенаправляет **уже объявленную** запись (`repos` или `deps`) на локальную папку по её логическому id `owner/repo` (регистр не важен). Новые записи она не создаёт.
+
+```bash
+# один источник
+AMXB_LOCAL_SOURCES='AmxxModularEcosystem/VipModular=../VipModular' amxb build
+
+# несколько: через ; или перевод строки
+AMXB_LOCAL_SOURCES=$'Org/A=../A\nOrg/B=/abs/B' amxb build
+
+# JSON-объект (значение начинается с {)
+AMXB_LOCAL_SOURCES='{"Org/A":"../A","Org/B":"/abs/B"}' amxb build
+```
+
+Пути считаются от папки манифеста (абсолютные тоже принимаются). Так как `.env` рядом с манифестом читается до разбора, редирект можно положить туда и держать в `.gitignore`.
+
+**Приоритет источников:**
+
+| Источник | Приоритет (↑ выше) |
+| --- | --- |
+| `AMXB_LOCAL_SOURCES` (env) | 1 |
+| манифест, `source: local` | 2 |
+| манифест, GitHub (`repo`/`ref`) | 3 |
+
+`AMXB_LOCAL_STRICT=1` (или `true`) делает ошибкой id из env, для которого нет репо/dep в манифесте. Без него такой id просто пишет предупреждение и игнорируется. Каждый применённый редирект пишет предупреждение. Кривой синтаксис env тоже предупреждение, не фатальная ошибка.
+
+### Ограничения локальных источников
+
+- Локальные источники **не версионируются**: рабочее дерево читается как есть, поэтому сборка не воспроизводима. Это годится для разработки и интеграции, но не для релизов.
+- `amxb watch` следит только за `amxmodx/` и `assets/` манифеста и **не** следит за папками локальных зависимостей: правки в локальном dep не запускают пересборку автоматически.
+- Папка должна существовать: отсутствующий `path` или опечатка в нём дают жёсткую ошибку, если для этого id не задан редирект в `AMXB_LOCAL_SOURCES` (редирект имеет приоритет и может перекрыть устаревший `path`).
+- Внутренний id локальной записи должен быть уникальным: если два источника дают одинаковый `local/<name>` (например, у папок совпал basename), сборка останавливается с ошибкой. Задайте разные `name`.
+
 ## GitHub Actions
 
 ```yaml
@@ -450,6 +589,54 @@ repos:
     ref: latest   # автоматически берёт тег последнего GitHub release
 ```
 
+## Кэш резолва `ref`: `ref_ttl`
+
+Поле `ref_ttl` управляет временем жизни кэша резолва `ref → SHA` (файл
+`.ref-heads.json` в кэше сборки). Оно относится только к git-записям `repos[]`
+и `deps[]` и не действует на `source: release`, `source: fungun`,
+`source: local`, `ref: latest` и `ref` без значения (default branch).
+
+Допустимые значения:
+
+| Значение | Смысл |
+| --- | --- |
+| `never` | Кэшировать резолв вечно (регистронезависимо) |
+| `Ns` / `Nm` / `Nh` / `Nd` | Длительность с целым N ≥ 1: секунды, минуты, часы, дни (например, `30m`, `1h`, `7d`) |
+| целое число `N` | То же в секундах (например, `3600` = 1 час) |
+
+Если поле не задано, TTL выводится из типа ref:
+
+- именованный ref, который GitHub подтвердил как **тег** → кэш вечный;
+- ветка, а также default branch при отсутствии `ref` → перепроверка раз в **1 час**.
+
+Если одно и то же имя существует и как тег, и как ветка, приоритет у тега: такой
+ref классифицируется как тег и кэшируется как неизменяемый.
+
+Явный `ref_ttl` переопределяет дефолт для конкретной записи. Протухание TTL
+инвалидирует только связку `ref → SHA`: каталог клона ключуется по SHA, поэтому
+неизменённый SHA ничего не перекачивает. Если тег force-push'нули, вечный кэш
+этого не заметит: обновите явный `ref_ttl` или выполните `amxb clean`.
+
+```yaml
+repos:
+  - repo: Org/VipModular
+    ref: main
+    ref_ttl: 30m           # ветку перепроверять раз в 30 минут
+
+  - repo: Org/Stable
+    ref: v2.1.0
+    ref_ttl: never         # тег: закрепить резолв навсегда
+
+deps:
+  - repo: Org/ParamsController
+    ref: 1.4.2
+    ref_ttl: 7d            # git-dep: перепроверка раз в неделю
+```
+
+Строковая форма deps (`owner/repo@ref[:include_path]`) и файл `DEPS_LIST` поле
+`ref_ttl` не поддерживают: у них нет слота для этого поля. Используйте полную
+(объектную) форму записи.
+
 ## deps: fungun.net
 
 [fungun.net](https://fungun.net) — магазин закрытых AMXX-плагинов. Архивов и
@@ -500,9 +687,45 @@ MCP сервер предоставляет агенту opencode информа
 }
 ```
 
-**Все 13 инструментов** — от просмотра `.inc` файлов до построения дерева зависимостей —
-описаны в [`docs/mcp/INDEX.md`](docs/mcp/INDEX.md) с таблицей и ссылками на полную документацию каждого инструмента.
-Плюс `get_dep_docs` / `list_dep_docs` — агент-доки, которые автор зависимости может приложить через поле `docs` у зависимости (или файлы `docs/API.md` / `API.md` в корне репо).
+Автоматически это настраивается командой `amxb init --opencode`: она создаёт
+`.opencode/opencode.json` с этим MCP-конфигом и файл `.opencode/plugin/amxb-skills.js`,
+тонкий мост, который при каждом старте opencode регистрирует скиллы из трёх источников:
+собственные bundled-скиллы сборщика (`amxb skills-dir`), скиллы текущего проекта из его
+`amxbuild.yml` (`skills:`) и скиллы всех `deps`/`repos`, прочитанные из их манифестов
+(`amxb opencode-skills`; отсутствующие зависимости докачиваются из сети по требованию).
+Абсолютных путей в `opencode.json` нет. Повторный запуск пропускает существующие файлы
+(мержит конфиг), `--force` перезаписывает.
+
+> Существующие файлы `.opencode/plugin/amxb-skills.js` автоматически не обновляются:
+> чтобы получить версию с тремя источниками, пересоздайте плагин командой
+> `amxb init --opencode --force` (или создайте файл заново).
+
+**23 инструмента** — от просмотра `.inc` файлов до построения дерева зависимостей —
+доступны через MCP. Каталог задокументированных инструментов (включая агент-доки и
+скиллы) — в [`docs/mcp/INDEX.md`](docs/mcp/INDEX.md).
+
+Агент-доки и скиллы теперь объявляются в самом манифесте: верхнеуровневые `docs:`
+(справочная документация) и `skills:` (инструкции для агента). Они предназначены
+**только агенту** — не попадают в `build/` и архив, и ничего не отдаётся по умолчанию,
+пока автор не объявил запись явно. Пять инструментов обслуживают их: `get_dep_manifest`
+возвращает сырой `amxbuild.yml` зависимости вместе со сводкой её `docs:`/`skills:`;
+`list_agent_docs` / `get_agent_docs` и `list_agent_skills` / `get_agent_skills` читают
+объявления как текущего проекта, так и зависимости (`dep`/`repo`). Содержимое,
+полученное из зависимости, считается предоставленным её автором и непроверенным:
+источник правды по API — `.inc` файлы. Подробнее — в
+[`docs/mcp/INDEX.md`](docs/mcp/INDEX.md).
+
+```yaml
+docs:
+  - file: docs/API.md            # путь внутри репо
+    name: API                     # по умолчанию — имя файла без расширения
+    description: Публичный API плагина
+skills:
+  - file: skills/config.md        # одиночный скилл-файл
+    name: config
+  - dir: skills/deep-config       # скилл-папка (SKILL.md + references)
+    name: deep-config
+```
 
 ## Скилл миграции для ИИ-агентов
 
@@ -510,6 +733,11 @@ MCP сервер предоставляет агенту opencode информа
 он переводит репозиторий AMXX-плагинов на `amxbuild.yml`, подключает `deps`,
 настраивает `.gitignore` / CI / MCP и заменяет старые скрипты сборки.
 
+В проекте, созданном через `amxb init --opencode`, скиллы amxb (включая
+`amxb-migration`) подхватываются opencode автоматически: мост-плагин
+`.opencode/plugin/amxb-skills.js` при каждом старте регистрирует не только
+bundled-скиллы сборщика, но и скиллы текущего проекта и его `deps`/`repos`.
+
 Канонический файл скилла (можно подключать по прямой ссылке до установки самого amxb —
 шаг 0 скилла ставит amxb при необходимости):
 
@@ -574,9 +802,10 @@ curl -fsSL https://raw.githubusercontent.com/AmxxModularEcosystem/amxx-builder/m
 
 | Что | Порядок (↑ выше) |
 | --- | --- |
-| плагины `plugins:` | правила применяются по порядку, первое совпадение побеждает |
-| `plugins_ini_postfix` | правило `plugins:` → репо → глобальный |
+| плагины (`plugins.rules`) | правила применяются по порядку, первое совпадение побеждает |
+| INI плагинов | `plugins.rules` → `repos[].plugins` → `plugins.defaults` → выключено |
 | зависимости | `manifest.deps` → `deps_override` → `DEPS_LIST` файл в репо |
+| локальные источники | `AMXB_LOCAL_SOURCES` (env) → манифест `source: local` → GitHub |
 | ассеты | порядок в `sources:` + `on_conflict` |
 | версия компилятора | `amxmodx.version` → последний релиз |
 | значения манифеста | `--set` → манифест проекта → `defaults/amxbuild.defaults.yml` |
@@ -597,3 +826,30 @@ sudo dpkg --add-architecture i386
 sudo apt update
 sudo apt install libc6:i386 libstdc++6:i386
 ```
+
+### Сборка падает на `/mnt/...` в WSL
+
+`amxxpc` — 32-битный Linux-бинарник, но под WSL он **не читает** файлы на
+Windows-дисках, смонтированных в `/mnt/*` (DrvFs/9p: `/mnt/c`, `/mnt/d`, `/mnt/j`, …).
+Node/bash эти файлы видят, поэтому ошибка выглядит «мистической»:
+
+- локальный `.sma` на `/mnt/*` → `fatal error 100: cannot read from file: ".../plugin.sma"`;
+- локальная папка `include/` на `/mnt/*` (идёт как `-i`) → `std::bad_alloc` / `Aborted` (SIGABRT).
+
+Плагины из `repos:` при этом собираются нормально — их исходники amxb кладёт в
+нативный кэш `~/.cache/amxx-builder`. Запись `.amxx` на `/mnt/*`, наоборот, работает.
+
+**Решение:** собирать из нативной Linux-файловой системы. Скопируйте проект в `~` —
+кэш компилятора и зависимостей общий, заново ничего не скачивается:
+
+```bash
+mkdir -p ~/amxb-build && cp -r amxmodx assets amxbuild.yml ~/amxb-build/
+cd ~/amxb-build && amxb build
+```
+
+Альтернативы: выполнять сборку на Windows (`build.bat` или `amxb build` в PowerShell)
+либо в CI. Команды без запуска компилятора (`amxb validate`, `amxb deps-tree`,
+`amxb build --dry-run`) под `/mnt/*` работают.
+
+> `amxb build --build-dir <нативный путь>` **не** решает проблему: локальные `.sma`
+> компилируются по месту, из папки проекта, а не из `build/`.

package/action.yml

@@ -34,7 +34,7 @@ inputs:
       Override any manifest field. One entry per line:
         version=1.2.3
         output.archive_name={name}-{version}.zip
-        output.generate_ini=false
+        plugins.defaults.ini=myserver
         github.tokens.MyOrg=GITHUB_TOKEN_MYORG
     required: false
   github-token:

package/defaults/amxbuild.defaults.yml

@@ -21,12 +21,14 @@ output:
   amxmodx_path: "{name}/addons/amxmodx"
   assets_path: "{name}"
   readme: true
-  generate_ini: false
   pack: true
   on_conflict: last_wins
 
 plugins: []
 
+docs: []
+skills: []
+
 assets:
   on_conflict: last_wins
   sources:
@@ -34,6 +36,10 @@ assets:
 
 deploy:
   amxmodx_path: addons/amxmodx
+  # Empty assets path = deploy root (server root), matching the schema default:
+  # local assets/ land where the game reads them, NOT under a {name}/ subfolder
+  # (output.assets_path '{name}' only shapes the distribution archive).
+  assets_path: ""
   watch_debounce_ms: 500
   exclude: []
   rcon: