v2.3.9

Highlights

• Documentation and build-artefact tools built in (experimental, off by default: packDocs.enabled, buildInfo.enabled) — the CMSIS Pack Docs extension attached to v2.3.8 is no longer needed; uninstall it, activation warns while both are present.
• PDFs are extracted with a bundled pdf.js; poppler is optional (Open-CMSIS-Pack#28).
• search_target_docs ranks by page heading and expands identifiers from the SVD (Open-CMSIS-Pack#29): R@1 49.5 % → 64.5 % on RM0455.
• Skills can be installed into the workspace — Select Agent Skills asks This workspace only (default, keeps other projects' agent context lean) or This user.
• Arm logo as the icon; VSIX 13.95 → 3.19 MB; architecture diagram with the documentation path.

[2.3.9] - 2026-08-31

Added

• Skills can be installed into the workspace instead of the user profile. Select Agent Skills (and step 2 of the setup) first asks where the AI Skills Pack goes: This workspace only (the default — a personal skill is offered to the agent in every project and its description costs context there whether the project is CMSIS or not; a project skill is loaded only where it applies) — the project's .agents/skills (and .claude/skills when Claude Code is installed or the project already has a .claude directory), next to the sources, to commit with the project or ignore; This user — the personal skills directories as before, for every workspace. The choice is the target of the installedSkills setting, whose scope changes from application to resource: the User value drives the personal directories, a Workspace or Folder value the project's — each folder of a multi-root workspace from its own — so a selection that arrives in a checked-out .vscode/settings.json is applied on activation like one from Settings Sync, and removing it sweeps the project copies (marker-guarded, as everywhere). A project selection installs the selected pack skills and their hidden dependencies only; the extension's own skills stay personal, where every agent already finds them, and a project without a selection never gains an empty .agents/skills. Adding a folder to the workspace syncs it, the picker shows what each scope currently selects, and the install prompt counts a pack skill picked in either.
• Documentation and build-artefact tools, built in — the experimental CMSIS Pack Docs extension moved into the Assistant as-is: src/core/packDocs (target resolution from *.cbuild-run.yml, pdsc <book> walking, Arm document catalogue and download, user and workspace document folders, pdftotext extraction, the page store and BM25 index, peripheral dossiers over the SVD plus 16 shipped Cortex-M core-peripheral SVDs) and src/core/buildInfo (a positioned ELF32 reader, GNU ld / armlink map parser, build-log diagnostics). Ten tools: list_target_docs, search_target_docs, read_doc_pages, fetch_doc, get_peripheral_docs and list_build_artifacts, get_memory_usage, lookup_symbol, get_section_layout, get_build_diagnostics — off by default behind cmsis-developer-assistant.packDocs.enabled and buildInfo.enabled (fixed per window like serial.enabled; the enabled list is 55 tools / ~41 kB against its own 42 000-byte budget, the default list is unchanged). They route like every other op: each window builds the handler pair, the control server dispatches by op name, the router forwards, and the five documentation ops carry the ten-minute forward floor because indexing a manual takes minutes. Commands List / Index Target Documentation, Import Document for Current Target (attribute a PDF to a pack, device family, board or core, with title, category and edition, indexed at once), Open User Documents Folder and Open Pack Docs Panel (target, documents and index state, SVD peripherals, page store, in-place tool runner). Settings packDocs.extractor / pdftotextPath / maxPdfMb / includeUnlisted / workspaceDocDirs / userDocsDir (default ~/.cmsis-pack-docs/user, kept so imported documents stay attributed) and buildInfo.maxSymbols / logGlobs apply live. The cmsis-pack-docs skill ships as a fourth bundled skill; cmsis-debug-live and add-board-layer point at the tools instead of an external MCP; cmsis-help lists them. Extracted text now lives under this extension's global storage, so pages are re-extracted once. The 22 test suites and fixtures came along; the routing test covers the dispatch, the transport test measures the all-on list and the no-build answers, and the packaged-VSIX check verifies the SVDs and the skill ship. If the standalone extension is still installed, activation warns that agents would see the tool names twice.

Changed

• search_target_docs indexes the page heading as a weighted field (Open-CMSIS-Pack#29). A register page's body speaks of bits; only its heading names the register and says what it is, so BM25 over the body alone missed it unless the query happened to use the body's words. The heading is now a second field in the index (version 2; existing indexes are rebuilt from the persisted page text on first use, no re-extraction) scored at weight 5 on top of the body, and the old ×3 post-boost becomes a tie-breaker. Measured with the new opt-in benchmark npm run bench:search -- --pages <doc.pages.jsonl> --svd <device.svd> on RM0455 (2 965 pages, 495 register headings) with queries taken from the STM32H7B3 SVD rather than the manual: description-only queries R@1 49.5 % → 64.5 %, R@3 70.9 % → 81.8 %, MRR 0.621 → 0.741; description plus register name R@1 78.1 % → 98.8 %, MRR 0.873 → 0.994. The benchmark reports R@1 / R@3 / MRR per heading weight and post-boost so future ranking changes are measured, not argued.
• The architecture diagram shows the documentation path and renders on dark themes. The "How It Works" picture gains the documentation retrieval box (pack PDFs, user and workspace documents, fetch_doc downloads → pdf.js → page store → the search tools, with the SVD joined in), is rendered on an opaque background — the previous transparent PNG had black labels, invisible on the dark extension page — and npm run diagram regenerates it from the Mermaid source with a local Chrome. The README explains the window routing and the documentation path in two paragraphs.
• The extension icon is the Arm logo the other Arm extensions (CMSIS Solution, CMSIS Debugger, Keil Studio Pack, Device Manager, …) carry — the same arm.png — instead of the icon inherited from DebugMCP.
• The documentation system is marked experimental. Every packDocs.* and buildInfo.* setting carries VS Code's experimental tag (the Settings UI shows the badge and the "Experimental" filter finds them), the two .enabled descriptions say so up front, and the README and cmsis-help label the two tool groups the same way — the tools, their arguments and output may change between releases.
• The VSIX drops 10 MB of unused media. assets/DebugMCP.webp (9.7 MB, referenced by nothing, shipped in every package since the fork) and assets/DebugMCP.mp4 (15 MB in the repository, never shipped) are removed, assets/architecture.svg (an unused rendering of the diagram the README shows as PNG) too; the extension icon is 256 px instead of 1024 (1.4 MB → a few tens of KB); the design notes under docs/ no longer ship — only docs/agent-resources, which the MCP resources read, does.
• search_target_docs expands identifiers from the SVD (Open-CMSIS-Pack#29 part 2). An identifier-only query — USART1, GPIOAEN — gains the words of its SVD description at half weight: a peripheral instance brings its type synonyms and description ("universal synchronous asynchronous receiver transmitter"), a bare field name brings the register it lives in (RCC_AHB1ENR) and the field's description, so the manual is found even when it never spells the identifier. The result says what was expanded. Prose, quoted phrases and register names are left alone: the benchmark showed expanding register names or the acronyms inside a sentence only dilutes the ranking (−2 points on description queries, −0.3 on bare register names), while the heading field already puts register pages first (R@1 98.2 % for the bare name). With the restriction all three benchmark sets are unchanged; the gain is on the instance and field queries the benchmark cannot score against the manual's headings.
• PDFs are extracted with a bundled pdf.js; poppler is optional (Open-CMSIS-Pack#28). packDocs.extractor gains pdfjs and auto now means pdf.js (legacy build, pure JavaScript, +0.8 MB in the bundle, loaded on first use), so a machine without pdftotext — most Windows hosts — indexes documents too; pdftotext stays selectable, and switching re-extracts a document on its next use rather than mixing text sources. Lines are rebuilt from pdf.js text items by baseline, with wide horizontal gaps kept as double spaces so register-table columns stay separable, and the tokenizer applies NFKC so ligatures and full-width forms from either extractor meet on one term. Gated by the search benchmark on RM0455 with the heading field on: pdf.js R@1 65.0 % / MRR 0.739 (description-only) and 99.1 % / 0.995 (with the register name) against pdftotext's 64.5 % / 0.740 and 98.8 % / 0.994 — within noise; 2 965 pages in 3.9 s. npm run bench:search -- --pdf <file> --extractor pdfjs|pdftotext runs the comparison.
• Agents are told to search the documentation, not to ask for it. The MCP instructions now say, with the documentation tools on, to use them before asking the user for a datasheet or manual and instead of reading a PDF into context — a document the user provides goes into the workspace docs/ folder or through Import Document for Current Target and is searched; with the tools off (the default) they name the packDocs.enabled setting so an agent suggests it rather than asking for documents. The same rule is in the cmsis-pack-docs, cmsis-debug-live and add-board-layer skills, and the build topic of get_debug_instructions replaces its "check the documentation in the CMSIS Solution UI" advice with the tools. The transport test asserts the default instructions carry the pointer. Prompted by a session in which an agent went to the web for an ADC datasheet that was already indexed as a user document: the instructions, the tool descriptions and the skills now say that third-party parts on the board (sensors, ADCs, codecs) are documented the same way — any part-number lookup starts at list_target_docs, a datasheet that is not listed is fetched by URL with fetch_doc (the web finds the URL, the tools read the document), and the user's docs/ folder and the import command are where such documents belong. The same session first hit a Blinky+MPS3 fixture in the workspace: list_target_docs and the build-artefact tools now ask the CMSIS Solution extension which csolution and target-type are active and pick that context when a workspace holds several solutions, noting the choice; the ambiguity error remains when nothing matches, and target still wins (docs/improvement-notes.md §10).

Pre-release (odd minor). Full changelog: https://github.com/MatthiasHertelArm/CMSIS-Developer-Assistant/blob/v2.3.9/CHANGELOG.md — previous pre-release: https://github.com/MatthiasHertelArm/CMSIS-Developer-Assistant/releases/tag/v2.3.8 (add-board-layer skill) — upstream PR for 2.3.5–2.3.9: Open-CMSIS-Pack#30