fa-mcp-sdk 0.4.93 → 0.4.96

package/cli-template/.claude/skills/upgrade-guide/SKILL.md

@@ -1,456 +0,0 @@
----
-name: upgrade-guide
-description: "Generate a migration guide for upgrading fa-mcp-sdk to the latest version. Use when user asks to upgrade/update fa-mcp-sdk, mentions 'обновить sdk', 'upgrade sdk', 'migration guide', 'обновление fa-mcp-sdk', or wants to see what changed between SDK versions."
-disable-model-invocation: true
-allowed-tools: Bash(yarn *) Bash(npm *) Bash(node *) Bash(git *) Bash(cat *) Bash(diff *) Bash(ls *) Bash(find *) Bash(mkdir *) Read Write Glob Grep WebFetch Agent
-argument-hint: "[from-version] [to-version] [language hint]"
----
-
-# FA-MCP-SDK Upgrade Guide Generator
-
-Generate a comprehensive migration guide for upgrading the fa-mcp-sdk dependency in the current project.
-
-## Overview
-
-This skill analyzes the differences between the currently installed version of `fa-mcp-sdk` and the latest (or specified) version, then produces a detailed migration guide as a markdown file.
-
-## Argument Parsing
-
-Parse `$ARGUMENTS` to extract a target version and an optional language hint.
-
-### Language detection
-
-Look for a natural-language phrase anywhere in the arguments that indicates the desired output language. Examples:
-- "на русском", "по-русски", "in Russian", "ru" → Russian
-- "in English", "en" → English
-- Any similar phrase or ISO 639-1 code
-
-Remove the language hint from the arguments before parsing the target version.
-
-**Default: English** if no language hint is found.
-
-The detected language determines ALL human-readable text in the generated guide (headings, descriptions, recommendations).
-Technical content (file paths, YAML keys, code snippets, commands) stays as-is regardless of language.
-
-### Version/commit references
-
-After stripping the language hint, the remaining arguments are version or commit references.
-
-An argument is a **commit hash** if it contains 7+ hex characters and does not match semver pattern.
-Otherwise it is treated as a **version** (with or without `v` prefix — `0.4.30` and `v0.4.30` are equivalent).
-
-#### Scope of references: PROJECT (default) vs SDK
-
-**By default, all versions and commit hashes refer to THIS project** (the repository where the skill is invoked), NOT to fa-mcp-sdk.
-
-A reference is treated as referring to **fa-mcp-sdk** ONLY if the user's phrasing explicitly says so. Trigger phrases for SDK scope (case-insensitive, English or Russian):
-- "sdk", "fa-mcp-sdk", "of sdk", "sdk commit", "sdk version"
-- "sdk", "fa-mcp-sdk", "версия sdk", "комит sdk", "коммит sdk", "хеш sdk"
-
-Examples:
-- `/upgrade-guide 1.2.3 1.2.7` → project versions (look up which SDK version was used in each)
-- `/upgrade-guide от версии 0.2.3 SDK до 0.4.5 SDK` → SDK versions directly
-- `/upgrade-guide от комита sdk abc1234 до комита sdk def5678` → SDK commits directly
-- `/upgrade-guide abc1234 def5678` → project commits (look up which SDK version was pinned in each)
-
-#### Resolving PROJECT references to SDK versions
-
-When a reference is PROJECT-scoped (the default), resolve it to an SDK version/commit before computing the diff:
-
-1. **Project commit hash** — run `git show <hash>:package.json` and extract the `fa-mcp-sdk` dependency value.
-2. **Project version** (e.g. `1.2.3`) — find the project git tag (`v1.2.3` or `1.2.3`), then `git show <tag>:package.json` and extract the `fa-mcp-sdk` value.
-3. If the dependency value is a semver (e.g. `^0.4.30`, `~0.4.30`, `0.4.30`), strip range operators to get the exact SDK version.
-4. If the dependency value is a git URL with a commit hash (e.g. `github:Bazilio-san/fa-mcp-sdk#abc1234`), extract the commit hash as the SDK ref.
-5. If the project tag/commit cannot be found, report an error and stop.
-
-Show the user the resolution result before proceeding:
-```
-Resolved project references to SDK:
-  FROM: project <ref> → SDK <version-or-commit>
-  TO:   project <ref> → SDK <version-or-commit>
-```
-
-#### Argument count
-
-**Two arguments** — explicit FROM and TO (resolved per scope rules above).
-
-**One argument** — it is treated as **FROM**; TO defaults to the **latest published fa-mcp-sdk version** (fetched via `yarn info fa-mcp-sdk version` / `npm view fa-mcp-sdk version`). The point is to upgrade to the newest existing SDK release.
-
-**Alternative TO=HEAD mode.** If the user explicitly says "to HEAD", "до HEAD", "до последнего коммита SDK", "to latest commit", "до master", or supplies the literal `HEAD`/`master` as the second argument, TO becomes the **tip of `master` on `Bazilio-san/fa-mcp-sdk`** (resolved via `https://api.github.com/repos/Bazilio-san/fa-mcp-sdk/commits/master`), not the latest **published** version. This is useful for diffing against unreleased commits. In this mode `yarn add` must use the git-URL form with the resolved commit hash (see Step 2).
-
-**No arguments** — FROM is the current installed SDK version (from the project's current `package.json`); TO is the latest published SDK version.
-
-## Step 1: Determine SDK Versions
-
-1. Read the current project's `package.json` and extract the installed `fa-mcp-sdk` version — this is the **default FROM (SDK)**.
-2. Run `yarn info fa-mcp-sdk version` (or `npm view fa-mcp-sdk version`) to get the latest published version — this is the **default TO (SDK)**.
-3. Apply argument parsing rules above (scope, count) to determine FROM and TO.
-4. If any argument is PROJECT-scoped, resolve it to an SDK version/commit by reading the project's git history (see "Resolving PROJECT references to SDK versions").
-5. **Validate that both SDK refs actually exist** before doing any diff work — fail fast with a clear message instead of letting a later GitHub API call return 404. For each of FROM-SDK and TO-SDK:
-   - If it's a **version** (e.g. `0.4.30` / `v0.4.30`) — probe the GitHub tag endpoint:
-     `https://api.github.com/repos/Bazilio-san/fa-mcp-sdk/git/refs/tags/v<version>` (also try without
-     the `v` prefix). Fall back to `yarn info fa-mcp-sdk@<version> version` — if that also fails,
-     report `Cannot resolve SDK version <X>: not found on GitHub or npm` and stop.
-   - If it's a **commit hash** — probe `https://api.github.com/repos/Bazilio-san/fa-mcp-sdk/commits/<hash>`.
-     If it returns 404, report `Cannot resolve SDK commit <hash>: not found in repo` and stop.
-   - If GitHub API is rate-limited, fall back to `git ls-remote https://github.com/Bazilio-san/fa-mcp-sdk.git`
-     for tag/branch existence, and skip commit-hash validation with a warning.
-6. If FROM-SDK equals TO-SDK — inform the user (e.g. "Both project commits pin the same SDK version X.Y.Z — nothing to diff") and stop.
-
-Display to the user:
-```
-From: <project or SDK ref> → SDK <version-or-commit>  ✓ validated
-To:   <project or SDK ref> → SDK <version-or-commit>  ✓ validated
-```
-
-## Step 2: Upgrade the Dependency
-
-If TO is a published version (not a commit hash), run:
-```bash
-yarn add fa-mcp-sdk@<TO-version>
-```
-
-If TO is a commit hash, run:
-```bash
-yarn add fa-mcp-sdk@https://github.com/Bazilio-san/fa-mcp-sdk#<TO-commit>
-```
-
-Wait for completion. If it fails, report the error and stop.
-
-## Step 3: Update SDK Documentation
-
-Run:
-```bash
-node ./node_modules/fa-mcp-sdk/scripts/update-sdk.js
-```
-
-This copies the latest `FA-MCP-SDK-DOC/` and `.claude/` from the SDK into the project.
-
-**Pinned folders.** Any folder under the project's `.claude/` that contains a direct file named
-`pin` is preserved as-is — the script neither deletes it nor overwrites it with template content.
-Drop a `pin` file into `.claude/skills/<your-skill>/` (or any other `.claude/` subdirectory) to
-protect local customizations from being reset on upgrade.
-
-## Step 4: Analyze Changes in SDK Between Versions
-
-Use the public GitHub repository `https://github.com/Bazilio-san/fa-mcp-sdk` to analyze what changed.
-
-### 4.1 Get the commit log between versions
-
-Fetch the GitHub compare URL to understand what changed:
-
-```
-https://api.github.com/repos/Bazilio-san/fa-mcp-sdk/compare/<FROM-ref>...<TO-ref>
-```
-
-Where `<FROM-ref>` and `<TO-ref>` are version tags (try both `v0.4.30` and `0.4.30` formats) or commit hashes.
-
-If version tags don't exist, use the commits API to find commits between versions, or search `git log` for version bump commit messages.
-
-Alternative approach — use the npm registry to get git metadata, or simply read the changelog if available.
-
-**Explicit commit-message review.** The compare endpoint returns a `commits[]` array — extract `commit.message` (subject + body) for **every** commit in the range, not just the file diffs. Commit messages capture the **why** of each change (motivation, fixed issue, design rationale) which is invisible from file diffs alone. In the generated guide, include a "Changelog" subsection that lists each commit's short hash + first line of its message in chronological order. Use these messages to:
-- Spot intent (e.g. "fix: ...", "BREAKING CHANGE: ...", "refactor: ...") — flag any conventional-commit BREAKING markers prominently in the Breaking Changes section.
-- Group related file changes under a single narrative ("These three files changed because of <reason from commit>").
-- Reach out for missing context: if a file diff is non-obvious and the commit message is terse, note it in the guide as "rationale unclear — check commit `<hash>` directly".
-
-If the compare API is rate-limited, fall back to fetching commits one page at a time via
-`https://api.github.com/repos/Bazilio-san/fa-mcp-sdk/commits?sha=<TO>&until=<TO-date>&since=<FROM-date>`.
-
-### 4.2 Analyze changes in config files
-
-These config files in the SDK may have changed and require corresponding updates in the project:
-
-- `config/default.yaml` — main configuration defaults
-- `config/_local.yaml` — local config template (the CLI scaffolder copies this to the project's `config/_local.yaml` and derives `config/local.yaml` from it with `{{param}}` substitutions)
-- `config/custom-environment-variables.yaml` — env var mappings
-- `config/development.yaml` — dev overrides
-- `config/production.yaml` — production overrides
-- `config/local.yaml` (SDK's own) — reference only, not shipped to projects
-
-For each config file, compare the SDK's version (at `node_modules/fa-mcp-sdk/config/<file>`) with the project's version (at `config/<file>`).
-
-Identify:
-- **New keys** added in the SDK that are missing in the project
-- **Removed keys** that existed in the old SDK but are gone now
-- **Changed defaults** where the SDK's default value has changed
-- **New sections** that represent new features
-
-**Correlate changes across config files.** When `config/default.yaml` has changes (new keys, restructured sections, changed defaults), you MUST also check `config/_local.yaml` for analogous changes. The `_local.yaml` file mirrors the structure of `default.yaml` but contains local-override values — if a section was added or restructured in `default.yaml`, the same section likely needs updating in `_local.yaml`.
-
-Compare both files in the SDK's `node_modules/fa-mcp-sdk/config/`:
-- `node_modules/fa-mcp-sdk/config/default.yaml` — the canonical defaults
-- `node_modules/fa-mcp-sdk/config/_local.yaml` — the template that was used to generate the project's `config/local.yaml`
-
-If `default.yaml` changed but `_local.yaml` did NOT, explicitly note this in the guide: the project's `config/_local.yaml` may still need manual updates to stay consistent with the new `default.yaml` structure.
-
-**Config file mapping (SDK source → project destination):**
-
-| SDK source (in `config/`)            | Project destination             | Action |
-|--------------------------------------|---------------------------------|--------|
-| `config/default.yaml`                | `config/default.yaml`           | Add new keys; do NOT remove existing keys the project may have customized |
-| `config/_local.yaml`                 | `config/_local.yaml`            | Update to match SDK — this is the template users derive their `local.yaml` from |
-| `config/_local.yaml` (via CLI)       | `config/local.yaml`             | Derived by CLI from `_local.yaml` with `{{param}}` substitutions — check for needed adjustments |
-| `config/custom-environment-variables.yaml` | `config/custom-environment-variables.yaml` | Add new env var mappings |
-| `config/local.yaml` (SDK's own)      | *(not shipped — reference only)* | Use as reference for what the SDK itself overrides locally |
-
-### 4.3 Analyze changes in cli-template files
-
-The SDK ships a project template at `node_modules/fa-mcp-sdk/cli-template/` (after `yarn add fa-mcp-sdk@<TO>`). This is the **canonical source** for any template files in the project — when generating instructions for the user, always point to this path as the place to copy the latest version from.
-
-Map of template file → project file (the CLI `bin/fa-mcp.js` applies these transformations when creating new projects — upgrades must respect the same mapping):
-
-| Template (source of truth)                                        | Project (destination)                       | Notes |
-|-------------------------------------------------------------------|---------------------------------------------|-------|
-| `node_modules/fa-mcp-sdk/cli-template/package.json`               | `package.json`                              | **Merge carefully** — see rule below |
-| `node_modules/fa-mcp-sdk/cli-template/tsconfig.json`              | `tsconfig.json`                             | overwrite (unless customized) |
-| `node_modules/fa-mcp-sdk/cli-template/.oxlintrc.json`             | `.oxlintrc.json`                            | overwrite (unless customized) |
-| `node_modules/fa-mcp-sdk/cli-template/.oxfmtrc.json`              | `.oxfmtrc.json`                             | overwrite (unless customized) |
-| `node_modules/fa-mcp-sdk/cli-template/CLAUDE.md`                  | `CLAUDE.md`                                 | merge — project may add custom sections |
-| `node_modules/fa-mcp-sdk/cli-template/jest.config.js`             | `jest.config.js`                            | overwrite (unless customized) |
-| `node_modules/fa-mcp-sdk/cli-template/deploy/`                    | `deploy/`                                   | merge per file |
-| `node_modules/fa-mcp-sdk/cli-template/.claude/skills/<skill>/`    | `.claude/skills/<skill>/`                   | overwrite unless locally customized |
-| `node_modules/fa-mcp-sdk/cli-template/r/<name>.xml`               | `.run/<name>.run.xml`                       | **Renamed** — see rule below |
-| `node_modules/fa-mcp-sdk/cli-template/gitignore`                  | `.gitignore`                                | source has no leading dot |
-| `node_modules/fa-mcp-sdk/cli-template/FA-MCP-SDK-DOC/`            | `FA-MCP-SDK-DOC/`                           | auto-updated by `update-sdk.js` |
-
-#### Rule: package.json — ADD ONLY new dependencies, do NOT touch anything else
-
-The project's `package.json` has evolved since generation (project-specific name, version, scripts, dependencies the team has added). When the SDK's template `package.json` changes:
-
-1. Diff `node_modules/fa-mcp-sdk/cli-template/package.json` (TO) against the same file at the FROM version.
-2. Identify ONLY dependencies/devDependencies that were **added** (not changed versions of existing ones, not removed).
-3. The generated guide must instruct the user: "Add these NEW entries to your `package.json` `dependencies`/`devDependencies` sections. Do NOT touch any other field — name, version, scripts, existing deps stay as they are."
-4. If a dep was **removed** from the template, mention it as informational only — do not instruct deletion from the project (it may still be in use).
-5. Do NOT suggest overwriting `scripts`, `engines`, `type`, or any other field.
-
-Provide a copy-pasteable JSON snippet with only the new keys:
-```json
-{
-  "dependencies": {
-    "<new-dep>": "<version>"
-  }
-}
-```
-
-#### Rule: `r/` → `.run/` with filename transformation
-
-The project has no `r/` directory — it was renamed to `.run/` at project generation, and each `<name>.xml` inside was 
-renamed to `<name>.run.xml`. When the SDK template ships new or changed files in `cli-template/r/`:
-
-- Source: `node_modules/fa-mcp-sdk/cli-template/r/<name>.xml`
-- Destination: `.run/<name>.run.xml`
-- Action for NEW files: copy `<name>.xml` → `.run/<name>.run.xml`
-- Action for CHANGED files: copy with the same rename, overwriting the existing `.run.xml` file (warn the user to back up any customizations)
-- Action for REMOVED files: informational only — do not delete the project's `.run/<name>.run.xml` automatically
-
-The generated guide must show the exact source → destination mapping for each changed file, with the filename transformation applied.
-
-#### Rule: `.claude/skills/<skill>/SKILL.md`
-
-This is a Claude Code skill that the project owns a copy of. If the SDK ships an updated version, instruct the user to 
-overwrite their local copy from `node_modules/fa-mcp-sdk/cli-template/.claude/skills/<skill>/SKILL.md` — unless they've 
-customized it locally, in which case manual merge.
-
-For any other changed template file, the generated guide must include:
-- The exact source path under `node_modules/fa-mcp-sdk/cli-template/...`
-- The exact destination path in the project
-- Whether to **overwrite** or **merge carefully** (because the project may have local customizations)
-
-### 4.4 Analyze changes in scripts
-
-The CLI copies scripts from `node_modules/fa-mcp-sdk/scripts/` (NOT from `cli-template/scripts/`) into the project's 
-`scripts/` directory, and then removes `copy-static.js`, `publish.js`, `scripts/publish-README.md` (SDK-internal, not needed in downstream projects).
-
-- Canonical source: `node_modules/fa-mcp-sdk/scripts/<name>.js`
-- Project destination: `scripts/<name>.js`
-- Exclude from upgrade suggestions: `copy-static.js`, `publish.js`, `scripts/publish-README.md` (SDK-only)
-
-The generated guide must specify the exact source path under `node_modules/fa-mcp-sdk/scripts/...` for any script the 
-user should copy into their project's `scripts/` directory, and skip the excluded SDK-only scripts.
-
-### 4.5 Analyze changes in core library exports
-
-**Prefer the TypeScript source over the compiled output.** Fetch `src/core/index.ts` (and any
-re-exported `_types_/` files it references) at both FROM and TO via GitHub raw:
-
-```
-https://raw.githubusercontent.com/Bazilio-san/fa-mcp-sdk/<FROM-ref>/src/core/index.ts
-https://raw.githubusercontent.com/Bazilio-san/fa-mcp-sdk/<TO-ref>/src/core/index.ts
-```
-
-Compare them to identify:
-- New exports that may be useful
-- Removed/renamed exports that may break existing code
-- Changed type signatures
-- Type-level changes (generics, conditional types, union narrowing) that don't survive `.d.ts`
-  emission cleanly
-
-Why source over `dist/`:
-- Original JSDoc comments and inline rationale are preserved in `.ts` but stripped/compressed in `dist/*.js`.
-- Renames are visible as renames in the source diff; in `dist/` they may appear as unrelated
-  add+remove pairs because of import-order shuffling or minification.
-- TS `export *` chains resolve naturally in source; in `.d.ts` they may be flattened, hiding which
-  module a symbol came from originally.
-
-**Fallback** — if GitHub raw is unavailable (rate-limited, network blocked), use
-`node_modules/fa-mcp-sdk/dist/core/index.js` and the matching `.d.ts`. State explicitly in the
-generated guide that the analysis was made from the compiled artifacts and recommend that the user
-double-check via the GitHub source viewer for any flagged change.
-
-### 4.6 Check project code for breaking changes
-
-Scan the project's `src/` directory for:
-- Imports from `fa-mcp-sdk` that reference removed/renamed exports
-- Usage of deprecated APIs
-- Config keys that have been renamed or restructured
-
-## Step 5: Generate Migration Guide
-
-Write ALL headings, descriptions, and prose in the detected language (default: English).
-Technical content (file paths, YAML keys, code blocks, shell commands) is always in English.
-
-Create a file `upgrade-guide-<old>-to-<new>.md` in the project root with the following structure:
-
-```markdown
-# FA-MCP-SDK Migration Guide: v<old> -> v<new>
-
-Generated: <timestamp>
-
-## Summary
-
-<Brief overview of what changed and the scope of required updates>
-
-## Breaking Changes
-
-<List any breaking changes that MUST be addressed. For each:>
-- What changed
-- What code/config is affected
-- Exact fix with code snippets
-
-## Config Changes
-
-### New Configuration Keys
-
-<For each new key, provide:>
-- Key path (e.g., `webServer.auth.enabled`)
-- Default value
-- Description
-- Whether it needs to be added to the project's config
-
-### Changed Defaults
-
-<Keys where default values changed>
-
-### Removed Keys
-
-<Keys that were removed>
-
-### Recommended config/default.yaml additions
-
-    ```yaml
-    # Add these sections to your config/default.yaml:
-    <actual YAML snippets to add>
-    ```
-
-### config/_local.yaml
-
-<If `default.yaml` changed, check whether `_local.yaml` in the SDK also changed. If it did: describe what changed. If it did NOT but the `default.yaml` changes affect keys that also exist in `_local.yaml` (because `_local.yaml` overrides those keys), explicitly warn that the project's `config/_local.yaml` may need manual updates to stay consistent with the new `default.yaml` structure.>
-
-### config/local.yaml (project-local overrides)
-
-<Check whether the project's `config/local.yaml` overrides keys that changed in `default.yaml` or `_local.yaml`. This is especially important when: a new key is added to `default.yaml` that the project's `local.yaml` doesn't override (user just needs to know it exists); a key's meaning or structure changed and `local.yaml` has a stale override; `local.yaml` was derived from the old `_local.yaml` and needs re-derivation from the updated template.>
-
-### Recommended config/custom-environment-variables.yaml additions
-
-    ```yaml
-    # Add these mappings:
-    <actual YAML snippets>
-    ```
-
-## Template File Changes
-
-> **Source of truth**: all updated template files live under `node_modules/fa-mcp-sdk/cli-template/` (after `yarn add fa-mcp-sdk@<TO>`). Copy from there into the project.
-
-### package.json
-
-> **Only ADD new dependencies. Do NOT touch anything else** (name, version, scripts, existing deps — all stay untouched). Source: `node_modules/fa-mcp-sdk/cli-template/package.json`.
-
-<List only dependencies/devDependencies that were newly added in the SDK template. Provide a copy-pasteable JSON snippet 
-with only the new keys. Mention removed deps as informational only — do not instruct deletion.>
-
-### `.run/` (from `cli-template/r/`)
-
-<For each changed `cli-template/r/<name>.xml`, show the mapping:>
-- Source: `node_modules/fa-mcp-sdk/cli-template/r/<name>.xml`
-- Destination: `.run/<name>.run.xml` (note the rename)
-- Action: copy + rename (overwrite, warn about local customizations)
-
-### Claude Code Skills (`.claude/skills/`)
-
-<For each updated skill, e.g. `upgrade-guide`:>
-- Source: `node_modules/fa-mcp-sdk/cli-template/.claude/skills/<skill-name>/SKILL.md`
-- Destination: `.claude/skills/<skill-name>/SKILL.md`
-- Action: overwrite (unless locally customized — then manual merge)
-
-### Other Template Files
-
-<For each: source path under `node_modules/fa-mcp-sdk/cli-template/...`, destination, overwrite or merge.>
-
-## New Features
-
-<New SDK features that the project can now use>
-
-## New/Updated Scripts
-
-<Scripts that should be copied or updated>
-
-## Code Changes Required
-
-<Specific code changes needed in the project's src/ files, with before/after examples>
-
-## Recommended Actions
-
-<Ordered checklist of actions to complete the upgrade>
-
-1. [ ] ...
-2. [ ] ...
-```
-
-## Step 6: Assess Impact on the Project
-
-After generating the guide, scan the current project's source code (`src/`, `config/`, `tests/`) to evaluate how the 
-changes specifically affect THIS project. Add a section to the guide:
-
-```markdown
-## Impact Assessment for This Project
-
-### Affected Files
-
-<List of project files that need modification, with specific changes>
-
-### Risk Level
-
-<Low / Medium / High — based on the number and nature of breaking changes>
-
-### Estimated Effort
-
-<Brief assessment of the work required>
-```
-
-## Step 7: Present Results
-
-1. Display a summary of the key findings to the user.
-2. Tell the user the full guide has been saved to `upgrade-guide-<old>-to-<new>.md`.
-3. Ask if they want you to apply any of the recommended changes automatically.
-
-## Important Rules
-
-- ALWAYS read the actual files to compare — do not guess or assume what changed.
-- When comparing YAML configs, preserve comments and structure.
-- **Correlate config file changes**: when `config/default.yaml` changes, ALWAYS also check `config/_local.yaml` in the SDK. Report whether `_local.yaml` has analogous changes or needs manual updates. Also advise checking the project's `config/local.yaml` for stale overrides that may conflict with the new defaults.
-- **Do not forget `config/local.yaml` in the project**: the project's `config/local.yaml` overrides `config/default.yaml`. When new keys are added or sections restructured in `default.yaml`, explicitly instruct the user to verify that their `config/local.yaml` doesn't have stale overrides that conflict with the new structure, and to add any new keys there too if they want non-default values.
-- Do not modify project files other than `package.json` (via yarn add) and `FA-MCP-SDK-DOC/` (via update-sdk.js) unless the user explicitly asks.
-- The migration guide must contain ACTIONABLE instructions with exact code/config snippets — not vague recommendations.
-- If GitHub API is unavailable or rate-limited, fall back to comparing files directly from `node_modules/fa-mcp-sdk/` against project files.
-- Write the guide in the language detected from the user's arguments (default: **English**). Translate all headings, prose, and descriptions. Keep file paths, YAML keys, code blocks, and shell commands in English.