project migration enhancement, migration guide collateral usage

docs/skills/c2000-idea/references/device-migration.md

@@ -40,6 +40,7 @@ Call `list_migration_devices()` from IDEA MCP immediately after collecting input
 **idea-mcp** (required):
 - `get_projects()` — detect projects, current device, configured migration devices
 - `list_migration_devices()` — supported migration device families
+- `set_project_migration_folder_exceptions()` — set folder/file exclusions for the project migration report. Called once in Phase 4 before `get_project_migration_report()` to exclude the build output folder. Paths are relative to the project root.
 - `get_project_migration_report()` — run migration analysis across the whole project in one
   call. Called **once** at the start of Phase 4 to size the work and report total scope.
 - `get_device_migration_report()` — run migration analysis on a single source file. Called

docs/skills/c2000-idea/references/device-migration/phase-1-import.md

@@ -113,6 +113,12 @@ The starter project location depends on the target device:
   (e.g., `myApp_f28003x` → `myApp_f28p55x`, not `myApp_f28003x_f28p55x`).
 - This gives the target project a stable, unique name. 
 
+## 1.7a Copy target configuration files
+
+- If the renamed project has no `targetConfigs` folder: create it, then copy all `.ccxml` files from `<c2000ware_path>/device_support/<target-device-lowercase>/common/targetConfigs/` into it.
+- If `targetConfigs` already exists: check if any `.ccxml` file inside it has the target device name in its filename. If yes, skip. If no such file exists, copy all `.ccxml` files from `<c2000ware_path>/device_support/<target-device-lowercase>/common/targetConfigs/` into it.
+Do not ask the user — perform both cases automatically.
+
 ## 1.8 Rebuild after rename
 
 - Call `buildProject` again on the **renamed** project.

docs/skills/c2000-idea/references/device-migration/phase-2-settings.md

@@ -66,6 +66,12 @@ found (source value vs. target value) and what you plan to apply.
   that component with the target device name and verify the resulting path exists on disk.
 - Apply settings from the source to the target, after confirmation.
 
+**After applying include paths — macro resolution check (required):**
+
+For every `${MACRO_NAME}` referenced in the applied include paths, check if that macro is defined in the target project. If missing, copy its definition from the source project, replace the source device name in the value with the target device name, and add it to **all build configurations** in the target project. Record each added macro in `c2000-migration.md`.
+
+> **Example:** Source defines `C2000WARE_DLIB_ROOT = ${COM_TI_C2000WARE_INSTALL_DIR}/driverlib/f28003x/driverlib/`. The universal target starter does not have this macro, so the include path `--include_path="${C2000WARE_DLIB_ROOT}"` would expand to nothing. Add it to the target project as `C2000WARE_DLIB_ROOT = ${COM_TI_C2000WARE_INSTALL_DIR}/driverlib/f28p551x/driverlib/`.
+
 ## 2.4 Linker flags
 
 - Use `getToolFlags` with toolType of `linker` to  get all of the linker settings.
@@ -139,7 +145,12 @@ Port user customizations from the source cmd onto the target device's cmd file:
 
 **Write the final CMD file:**
 
-After all decisions are made, write one linker cmd file to the target project:
+After all decisions are made, write exactly one linker cmd file to the target project —
+the one matching the active build configuration from step 2.0. Do NOT write a second cmd
+file for the other configuration; reading both reference files for context does not mean
+writing both. Delete any other `_generic_ram_lnk.cmd` or `_generic_flash_lnk.cmd` files
+already present in the target project directory — the imported starter ships with both,
+and leaving them causes duplicate MEMORY region errors at link time.
 - For the name of the cmd file created in the target project, match the name with the source 
   project's linker cmd file name (replace any device name mentions with the target device 
   name).

docs/skills/c2000-idea/references/device-migration/phase-4-migrate-code.md

@@ -15,8 +15,93 @@ skip the step.
 
 Precondition: user application files are already copied into the target project (Step 2.7).
 
+---
+
+## Step 4.pre — Download migration guide collateral HTML
+
+Download the full driverlib diff-report HTML for this migration pair to the **target
+project directory** once, so every sub-agent (4A, 4B, 4C) can read it from disk instead
+of making a separate network request per symbol.
+
+### 4.pre.1 — Compute URL and local path
+
+Read `c2000-migration.md` to get `sourceDevice` and `targetDevice` in **lowercase**
+(e.g. `f28003x`, `f28p65x`). Compute SDK version labels based on device families using
+the same logic as the IDEA extension:
+
+| Migration type | `FROM_SDK` | `TO_SDK` | Base URL version |
+|---|---|---|---|
+| F28x → F28x | `C2000Ware_26_01_00_00` | `C2000Ware_26_01_00_00` | `C2000Ware_26_01_00_00` |
+| F28x → F29x | `C2000Ware_26_01_00_00` | `F29H85X-SDK_26_00_00` | `C2000Ware_26_01_00_00` |
+
+Construct the values:
+```
+BASE_URL  = https://dev.ti.com/tirex/content/<Base URL version>/docs/<Base URL version>_Migration_Guides/html_pages/
+FILENAME  = <FROM_SDK>_<sourceDevice>_vs_<TO_SDK>_<targetDevice>_driverlib.html
+FULL_URL  = <BASE_URL>diff_reports/<FILENAME>
+LOCAL_OUT = <targetProjectPath>/<FILENAME>
+```
+
+**Example** (F28003x → F28P65x):
+```
+FILENAME  = C2000Ware_26_01_00_00_f28003x_vs_C2000Ware_26_01_00_00_f28p65x_driverlib.html
+FULL_URL  = https://dev.ti.com/tirex/content/C2000Ware_26_01_00_00/docs/C2000Ware_26_01_00_00_Migration_Guides/html_pages/diff_reports/C2000Ware_26_01_00_00_f28003x_vs_C2000Ware_26_01_00_00_f28p65x_driverlib.html
+LOCAL_OUT = <targetProjectPath>/C2000Ware_26_01_00_00_f28003x_vs_C2000Ware_26_01_00_00_f28p65x_driverlib.html
+```
+
+### 4.pre.2 — Run the download
+
+Run this PowerShell command with the computed values substituted:
+
+```powershell
+powershell -Command "
+\$url = '<FULL_URL>'
+\$out = '<LOCAL_OUT>'
+if (-not (Test-Path \$out)) {
+    Invoke-WebRequest -Uri \$url -OutFile \$out -UseDefaultCredentials -TimeoutSec 60
+    Write-Host 'Downloaded'
+} else { Write-Host 'Already cached' }"
+```
+
+`-UseDefaultCredentials` passes the current Windows user's credentials to TI's server
+(required when on a corporate network / VPN). `-TimeoutSec 60` aborts on a slow response.
+
+### 4.pre.3 — Record in c2000-migration.md
+
+**On success** (prints `Downloaded` or `Already cached`): add this line to `c2000-migration.md`:
+```
+Migration guide HTML: <LOCAL_OUT>
+```
+
+**On failure** (network error, 404, timeout): the automated download was blocked
+(common on corporate networks). Ask the user to download it manually:
+
+> "The migration guide HTML could not be downloaded automatically. Please open the
+> following URL in Chrome or Edge, save the page as:
+>
+> **URL:** `<FULL_URL>`
+>
+> **Save as (exact filename and location):** `<LOCAL_OUT>`
+>
+> Once saved, type **done** to continue."
+
+Wait for the user's confirmation, then verify the file exists at `<LOCAL_OUT>`.
+
+- **File found:** record `Migration guide HTML: <LOCAL_OUT>` in `c2000-migration.md` and proceed.
+- **File not found or user skips:** record `Migration guide HTML: DOWNLOAD FAILED — URL: <FULL_URL>`
+  in `c2000-migration.md`. Sub-agents will fall back to fetching the URL directly.
+
+Pass the recorded line verbatim in the `Migration guide HTML` field of every sub-agent briefing
+(4A, 4B, 4C). Sub-agents use the local file when available and fall back to the URL when not.
+
+---
+
 ## Step 4.0 — Strategy and pre-migration report
 
+> **Prerequisite:** Step 4.pre must be complete and `Migration guide HTML` must be
+> recorded in `c2000-migration.md` before asking for the migration approach. Every
+> sub-agent briefing requires this path.
+
 ### 4.0a Ask the user for migration strategy
 
 **Before modifying any files, ask the user:**
@@ -59,8 +144,7 @@ branch**, not the source device branch. Do not remove or alter existing markers.
 all argument reordering, added/removed parameters, and type changes. Do not re-derive
 arguments.
 
-Record the choice in `c2000-migration.md` **under a dedicated section immediately after the
-Phase 4 file list**, formatted exactly as follows — the sub-agents read this exact string:
+Record the choice in `c2000-migration.md` in a dedicated section. This section MUST be placed BEFORE the Phase 4 file list section. Formatted exactly as follows — the sub-agents read this exact string:
 ```
 ## Phase 4 — Migration Strategy
 Strategy: Approach 1 (shared #ifdef)

docs/skills/c2000-idea/references/device-migration/phase-4-sub-agent-briefing.md

@@ -39,6 +39,7 @@ Briefing:
   SDK version              : <e.g. C2000Ware_5_04_00_00>
   Active build config      : <e.g. CPU1_FLASH>             ← copy verbatim from c2000-migration.md
   sysConfigOutputLocation  : <path — from getProjectDescriptors; do not edit files here>
+  Migration guide HTML     : <value from c2000-migration.md>    ← copy verbatim (path or "DOWNLOAD FAILED — URL: <url>")
 
   Files to migrate (in order):
     1. <absolute path to first .h file>
@@ -78,6 +79,7 @@ Briefing:
   SDK version              : <e.g. C2000Ware_5_04_00_00>
   Active build config      : <e.g. CPU1_FLASH>             ← copy verbatim from c2000-migration.md
   sysConfigOutputLocation  : <path — from getProjectDescriptors; do not edit files here>
+  Migration guide HTML     : <value from c2000-migration.md>
 
   Deferred-errors context  : <paste any deferred-errors from prior .c file dispatches
                                that point to THIS file, or write "None">
@@ -112,6 +114,7 @@ Briefing:
   SDK version              : <e.g. C2000Ware_5_04_00_00>
   Active build config      : <e.g. CPU1_FLASH>
   sysConfigOutputLocation  : <path — from getProjectDescriptors; do not edit files here>
+  Migration guide HTML     : <value from c2000-migration.md>
 
   All migrated files (from 4A and 4B):
     .h files: <list>

docs/skills/c2000-idea/references/device-migration/phase-4a-headers.md

@@ -98,22 +98,22 @@ The agent must fix **every** issue — easy or complex:
 ## Reading Migration Collateral links
 
 Each issue may include a `Migration Collateral` URL with a `#<symbol>` anchor. When
-no `Suggested fix` is provided, retrieve and parse it:
-
-1. Fetch the URL directly.
-2. If that fails, try `curl`, then `wget`, then download to a temp file.
-3. Save the content locally — do not stream large HTML pages.
-4. Strip `<style>` and `<script>` tags; extract text.
-5. Navigate to the exact `#<symbol>` anchor — do not stop at a partial match.
-6. Read the full table row or function block at the anchor plus the surrounding entries.
-7. Follow referenced structs, enums, typedefs, and macros if the diff references them.
-8. Summarize: old signature → new signature, added/removed parameters, type changes.
-9. Apply the fix using only data from the collateral. No inferred parameters.
-
-If all retrieval methods fail: try ti-asm-mcp → try local SDK at
-`<c2000ware_path>/driverlib/<target-device>/` → if still unavailable, stop and report
-to the user: *"Cannot confidently fix `{symbol}` — collateral inaccessible and SDK
-source not found."* Never fabricate.
+no `Suggested fix` is provided, call:
+
+```
+get_migration_guide_section(
+  htmlPath = <Migration guide HTML from briefing>,
+  anchor   = <symbol name from the #fragment of the Migration Collateral URL>
+)
+```
+
+The tool returns a Markdown block with the old/new signatures, argument changes, and
+diff body. Apply the fix using only that data. No inferred parameters.
+
+If `Migration guide HTML` is `DOWNLOAD FAILED` or the tool returns an error: ask the
+user *"Collateral not available for `{symbol}`. Should I try ti-asm-mcp or the local
+SDK header at `<c2000ware_path>/driverlib/<target-device>/driverlib/<module>.h`?"*
+and wait for confirmation before proceeding. Never fabricate.
 
 ---
 

docs/skills/c2000-idea/references/device-migration/phase-4b-sources.md

@@ -105,21 +105,22 @@ The agent must fix **every** issue — easy or complex:
 ## Reading Migration Collateral links
 
 Each issue may include a `Migration Collateral` URL with a `#<symbol>` anchor. When
-no `Suggested fix` is provided:
-
-1. Fetch the URL directly.
-2. If that fails, try `curl`, then `wget`, then download to a temp file.
-3. Save locally — do not stream large HTML pages.
-4. Strip `<style>` and `<script>` tags; extract text.
-5. Navigate to the exact `#<symbol>` anchor — do not stop at a partial match.
-6. Read the full table row or function block at the anchor plus surrounding entries.
-7. Follow referenced structs, enums, typedefs, macros if referenced.
-8. Summarize: old signature → new signature, added/removed parameters, type changes.
-9. Apply the fix using only data from the collateral. No inferred parameters.
-
-If all retrieval fails: try ti-asm-mcp → try local SDK at
-`<c2000ware_path>/driverlib/<target-device>/` → if unavailable, stop and report:
-*"Cannot confidently fix `{symbol}` — collateral inaccessible."* Never fabricate.
+no `Suggested fix` is provided, call:
+
+```
+get_migration_guide_section(
+  htmlPath = <Migration guide HTML from briefing>,
+  anchor   = <symbol name from the #fragment of the Migration Collateral URL>
+)
+```
+
+The tool returns a Markdown block with the old/new signatures, argument changes, and
+diff body. Apply the fix using only that data. No inferred parameters.
+
+If `Migration guide HTML` is `DOWNLOAD FAILED` or the tool returns an error: ask the
+user *"Collateral not available for `{symbol}`. Should I try ti-asm-mcp or the local
+SDK header at `<c2000ware_path>/driverlib/<target-device>/driverlib/<module>.h`?"*
+and wait for confirmation before proceeding. Never fabricate.
 
 ---
 
@@ -293,6 +294,7 @@ Continue until:
 - Migration report returns zero issues for this file, **AND**
 - `buildProject` returns no errors attributable to this file.
 
+
 ---
 
 ## Large-file batching (required when issue count > 30)

docs/skills/c2000-idea/references/device-migration/phase-4c-sweep.md

@@ -29,6 +29,27 @@ issues, then execute a clean rebuild to confirm the full project compiles with n
 
 ---
 
+## Reading Migration Collateral links
+
+When fixing a reported issue that has no `Suggested fix`, call:
+
+```
+get_migration_guide_section(
+  htmlPath = <Migration guide HTML from briefing>,
+  anchor   = <symbol name from the #fragment of the Migration Collateral URL>
+)
+```
+
+The tool returns a Markdown block with the old/new signatures and diff body. Apply
+the fix using only that data.
+
+If `Migration guide HTML` is `DOWNLOAD FAILED` or the tool returns an error: ask the
+user *"Collateral not available for `{symbol}`. Should I try ti-asm-mcp or the local
+SDK header at `<c2000ware_path>/driverlib/<target-device>/driverlib/<module>.h`?"*
+and wait for confirmation before proceeding. Never fabricate.
+
+---
+
 ## Step 1 — Re-run migration report on all files
 
 Run `get_device_migration_report` (with the absolute file path, source device, and target

src/mcp/idea-mcp.ts

@@ -20,6 +20,7 @@ import {
 } from './idea-mcp-config';
 import { deployIdeaSkills } from '../skills/idea-skills';
 import { isDeviceF29x } from '../deviceData';
+import { renderMigrationGuideMarkdown } from '../migrationGuide';
 import { normalizeMigrationExceptionPath } from '../utilities/utils';
 
 let httpServer: http.Server | null = null;
@@ -71,7 +72,7 @@ export function checkMcp() {
 const SERVER_INSTRUCTIONS = `${IDEA_MCP_PLATFORM} development assistant. Provides project discovery, device-to-device migration analysis, and bitfield-to-driverlib migration analysis for ${IDEA_MCP_PLATFORM} MCU projects.
 
 AVAILABLE TOOLS:
-- get_projects() — Discover projects in the workspace with their device info and paths.
+- get_projects() — Discover projects in the workspace with their device info, paths, and current folder exclusions (migrationFolderExceptions).
 - set_project_current_device() — Manually set a project's current (source) device for migration when the auto-detected device is wrong.
 - set_project_migration_devices() — Set a project's target (migration) device list for device-to-device migration.
 - update_project_file_folder_exceptions() — Read, add, remove, or replace a project's list of file/folder paths excluded from migration checks.
@@ -81,12 +82,13 @@ AVAILABLE TOOLS:
 - get_bitfield_to_driverlib_migration_report() — Run a bitfield-to-driverlib migration check on a source file. Scans for legacy bitfield register accesses and suggests driverlib function replacements.
 
 RECOMMENDED FLOW:
-1. Call get_projects() to discover projects, their current devices, and migration targets. If the list is empty or the project you are looking for is missing, call get_projects(rescan: true) once to re-scan the workspace.
+1. Call get_projects() to discover projects, their current devices, migration targets, and current folder exclusions (migrationFolderExceptions).
 2. For device-to-device migration (project level — preferred):
    a. Call list_migration_devices() if you need to verify or select device names.
-   b. Call get_project_migration_report() with the project name to analyze all files at once.
-   c. Issues marked "Auto-fixable" have a concrete code replacement you can apply directly. Issues marked "Needs manual review" require reading the linked migration guide.
-   d. After fixing files, call get_device_migration_report() on individual files to verify the fixes are clean.
+   b. Check migrationFolderExceptions from get_projects(). If the build output folder and SysConfig-generated folder are not already excluded, call update_project_file_folder_exceptions() with operation "add" and those relative paths before running the report.
+   c. Call get_project_migration_report() with the project name to analyze all files at once.
+   d. Issues marked "Auto-fixable" have a concrete code replacement you can apply directly. Issues marked "Needs manual review" require reading the linked migration guide.
+   e. After fixing files, call get_device_migration_report() on individual files to verify the fixes are clean.
 3. For bitfield-to-driverlib migration:
    a. Use get_projects() to get the project's currentDevice.
    b. Call get_bitfield_to_driverlib_migration_report() with the file path and sourceDevice.
@@ -154,6 +156,7 @@ function createMcpServerInstance(): McpServer {
 						deviceVariant: p.deviceVariant,
 						currentDevice: p.migrationState.currentDevice,
 						migrationDevices: p.migrationState.migrationDevices,
+						migrationFolderExceptions: p.migrationState.migrationCheckFolderExceptions || [],
 						hasResumeLog: fs.existsSync(resumeLogPath),
 					};
 				});
@@ -444,6 +447,35 @@ Pass the sourceDevice from get_projects() to identify the device family for regi
 		);
 	}
 
+	server.registerTool(
+		'get_migration_guide_section',
+		{
+			description: `Get a section of a downloaded TI driverlib migration-guide HTML report as Markdown.
+
+Given the local path to the HTML file (downloaded in the migration workflow) and a symbol anchor (the fragment from a Migration Collateral URL, e.g. "CMPSS_configFilterHigh"), returns a structured Markdown block describing the change: old/new function signatures, argument changes, removed/added parameters, and the full diff body.
+
+Use this instead of reading the raw HTML — the tool navigates the anchor, strips difflib markup, and reconstructs function bodies automatically.
+
+If the anchor is not found in the report, the result contains "_ERROR: section not found._" — treat this as a fallback signal and try ti-asm-mcp or the local SDK header instead.`,
+			inputSchema: {
+				htmlPath: z.string().describe('Absolute path to the downloaded migration-guide HTML file (the Migration guide HTML value from c2000-migration.md).'),
+				anchor: z.string().describe('Symbol name to look up (e.g. "CMPSS_configFilterHigh"). Matches the #fragment in the Migration Collateral URL.'),
+			} as any,
+		},
+		async ({ htmlPath, anchor }: any) => {
+			if (!fs.existsSync(htmlPath)) {
+				return { content: [{ type: 'text' as const, text: `Error: File not found: ${htmlPath}` }] };
+			}
+			try {
+				const md = renderMigrationGuideMarkdown(htmlPath, anchor);
+				return { content: [{ type: 'text' as const, text: md }] };
+			} catch (err) {
+				const msg = err instanceof Error ? err.message : String(err);
+				return { content: [{ type: 'text' as const, text: `Error getting migration guide section: ${msg}` }] };
+			}
+		}
+	);
+
 	return server;
 }