IgniteUI · gmurray81 · Aug 8, 2026 · Aug 8, 2026 · Aug 8, 2026 · Aug 8, 2026
diff --git a/.ai/skills/CHANGELOG.md b/.ai/skills/CHANGELOG.md
@@ -1,5 +1,37 @@
 # igniteui doc-skill set · changelog
 
+## v4 · 2026-08-31
+
+Teaches the set two xplat contracts it did not know, both of which an author following v3 would get
+wrong. No rule was removed or reworded; two were added and one bullet was scoped. Whole set bumped to
+v4 per the uniform version-line convention.
+
+### Changed
+
+| Change | File(s) |
+|---|---|
+| `apiTerms` added to the normative frontmatter contract: required for xplat, no default, `full` / `passthrough` / `none`, with what each does to a backticked name. A page written to v3's contract has no `apiTerms` and **does not build** — generation throws on a missing or unknown value. `docs/xplat/API-TERMS.md` named as normative. | igniteui-doc-topics/references/house-style.md |
+| `json-snippet` added ahead of the inline-code-snippet bullet: an xplat DV topic states its component once as JSON and generation emits every platform's code from the product's description metadata, so hand written per-platform blocks are the exception now rather than the default. Discouraged rather than banned — a definition cannot carry a data shape, a namespace declaration or a package install, and a block is the right tool there. The existing bullet is scoped to the blocks a topic still authors by hand. `docs/xplat/JSON-SNIPPETS.md` named as normative. | igniteui-doc-topics/references/house-style.md |
+| The populations of the xplat content tree written down, because both rules above are scoped to one of them, and each page now declares which it is in `platformType`. **xplat** owes full API term resolution and a `json-snippet`-first habit; **xplat-unmapped** is the same set where that cannot be applied yet (the Excel library, and the data grid's accessibility topic); **web-only** owes neither and is not to be reworked to match. Identity is not publication: a topic can be xplat and not reach the desktop platforms yet. `platformType` replaces `apiTerms` in the required-fields list, since the mode now follows from the population. | igniteui-doc-topics/references/house-style.md |
+| house-style's version note corrected: it claimed "content unchanged from v2", which v4 makes false. | igniteui-doc-topics/references/house-style.md |
+| Create step 4 now begins with `platformType` for an xplat topic, since it is required, has no default, and decides which standard the rest of the work is held to. | igniteui-doc-topics/references/create-workflow.md |
+| Audit check D0 added (Blocker, xplat): no `platformType`, or one that does not match the topic. Names the two traps — identity is not publication, and a per-platform block or a non-`full` `apiTerms` is a finding on an xplat topic and fine on a web-only one. | igniteui-doc-topics/references/audit-rubric.md |
+| Set-wide version line bumped to `v4 · 2026-08-31`, including the content-unchanged files. | all files |
+
+### Unchanged
+
+Both routers, both skills' `description` fields (so the `.claude/` and `.codex/` adapters still
+byte-match and needed no edit), every audit check and severity, every blueprint and section table,
+and the whole frontmatter skill.
+
+### Where the substance lives
+
+The working guides for these two contracts are repository skills rather than references in this set,
+because they are xplat build machinery rather than house style: `.github/skills/xplat-docs-api-links`
+(modes, `ApiLink` props, `pkg=` disambiguation, the build-time ambiguity trap) and
+`.github/skills/xplat-docs-json-snippets` (fence attributes, channels, the five traps, the checks).
+This set points at them; it does not restate them.
+
 ## v3 · 2026-08-14
 
 Restructures both skills to the routing-hub + references architecture used by the

diff --git a/.ai/skills/README.md b/.ai/skills/README.md
@@ -1,6 +1,6 @@
 # Ignite UI doc-skill set — architecture and maintenance guide
 
-Version: v3 · 2026-08-14 · igniteui doc-skill set. This file is for humans; agents load the
+Version: v4 · 2026-08-31 · igniteui doc-skill set. This file is for humans; agents load the
 SKILL.md files. Change history: `CHANGELOG.md`.
 
 ## What this is
@@ -59,6 +59,14 @@ change over time lives in `references/`. Three reasons:
 └── igniteui-topic-frontmatter/SKILL.md   ← adapter (description byte-matches canonical)
 ```
 
+**Where xplat build machinery lives instead.** Two contracts an xplat author needs are not house
+style but build behaviour, so their working guides are repository skills and this set only points at
+them: `.github/skills/xplat-docs-api-links` (the `apiTerms` modes, `ApiLink` props, `pkg=`
+disambiguation) and `.github/skills/xplat-docs-json-snippets` (fence attributes, channels, the
+checks). house-style names both, and `docs/xplat/API-TERMS.md` and `docs/xplat/JSON-SNIPPETS.md` are
+normative for them. Do not restate their rules here — that is the drift this set was restructured to
+stop.
+
 **Authority chain:** where any two files differ, `house-style.md` wins on content rules (it is the
 single normative field contract and template source); each skill's own references win on its
 operational procedure (severities, report shapes, workflow order). The frontmatter skill reads

diff --git a/.ai/skills/igniteui-doc-topics/SKILL.md b/.ai/skills/igniteui-doc-topics/SKILL.md
@@ -17,7 +17,7 @@ description: >-
 
 # Ignite UI doc topics
 
-Version: v3 · 2026-08-14 · igniteui doc-skill set. All set files carry this version line; before
+Version: v4 · 2026-08-31 · igniteui doc-skill set. All set files carry this version line; before
 editing any file, confirm the lines match across the set. The `.claude` adapter's `description` must
 byte-match this file's `description`. Change log: `.ai/skills/CHANGELOG.md` · human-readable intent:
 `.ai/skills/README.md`.

diff --git a/.ai/skills/igniteui-doc-topics/references/audit-rubric.md b/.ai/skills/igniteui-doc-topics/references/audit-rubric.md
@@ -1,6 +1,6 @@
 # Audit rubric
 
-Version: v3 · 2026-08-14 · igniteui doc-skill set. Before editing, confirm this version line against
+Version: v4 · 2026-08-31 · igniteui doc-skill set. Before editing, confirm this version line against
 `.ai/skills/CHANGELOG.md`.
 
 The audit workflow, the checkable rules for **audit mode**, and the report format to produce. Every
@@ -129,6 +129,13 @@ Run the compass on each section; flag content that has drifted out of the sectio
   Styling instead of Usage.
 
 ### D. Metadata & AI-readiness
+- D0 (Blocker, xplat) No `platformType`, or one that does not match the topic. The field is required
+  and has no default, so a topic without it does not build; and it decides which standard the topic is
+  held to, so the wrong value quietly applies the wrong rules. `xplat` for the DV set,
+  `xplat-unmapped` where its API cannot be resolved, `web-only` for the web platforms and no further.
+  Two traps: identity is not publication, so a topic can be `xplat` and reach no desktop platform; and
+  a per-platform code block or a non-`full` `apiTerms` is a finding on an xplat topic and perfectly
+  fine on a web-only one. `check-doc-scope.mjs` reports both, and house-style carries the contract.
 - D1 (Warning) `relatedComponents` is set but **Usage**'s **Do/Don't** guidance doesn't name the
   specific sibling(s) by name and link them — or vice-versa, it names a sibling that isn't listed in
   `relatedComponents`.

diff --git a/.ai/skills/igniteui-doc-topics/references/create-workflow.md b/.ai/skills/igniteui-doc-topics/references/create-workflow.md
@@ -1,6 +1,6 @@
 # Create workflow
 
-Version: v3 · 2026-08-14 · igniteui doc-skill set. Content carried from SKILL.md v2 unchanged;
+Version: v4 · 2026-08-31 · igniteui doc-skill set. Content carried from SKILL.md v2 unchanged;
 restructured into this reference so the workflow can evolve without touching the router. Blueprints,
 mechanics, and the frontmatter contract live in `house-style.md`; run the rubric self-check from
 `audit-rubric.md` before delivering.
@@ -25,6 +25,11 @@ mechanics, and the frontmatter contract live in `house-style.md`; run the rubric
 4. **Scaffold frontmatter** — the metadata contract lives in `house-style.md` → "File format &
    frontmatter"; this step orders the work, it does not restate the rules. Apply the contract to
    every topic type, including category/index topics.
+   - **First, for an xplat topic:** `platformType`, which is required and has no default — a topic
+     without it does not build, and it decides the standard the rest of the work is held to. `xplat`
+     for the DV set, `xplat-unmapped` where its API cannot be resolved, `web-only` for a topic that
+     ships for the web platforms and no further. It also settles `apiTerms`, which is then stated only
+     to differ. See house-style → "File format & frontmatter".
    - **Before the body (fixed by convention):** `title` (xplat component topics use the
      `{ComponentTitle}` token; xplat category/index topics use a concise, framework-neutral category
      name without `{Platform}` or `{ProductName}` tokens, for example `title: "Grids and Tables"`;

diff --git a/.ai/skills/igniteui-doc-topics/references/diataxis-cheatsheet.md b/.ai/skills/igniteui-doc-topics/references/diataxis-cheatsheet.md
@@ -1,6 +1,6 @@
 # Diátaxis cheat-sheet
 
-Version: v3 · 2026-08-14 · igniteui doc-skill set (content unchanged; version line added for the
+Version: v4 · 2026-08-31 · igniteui doc-skill set (content unchanged; version line added for the
 set-wide match check). Before editing, confirm this version line against `.ai/skills/CHANGELOG.md`.
 
 Condensed from https://diataxis.fr (tutorials, how-to, reference, explanation, compass).

diff --git a/.ai/skills/igniteui-doc-topics/references/house-style.md b/.ai/skills/igniteui-doc-topics/references/house-style.md
@@ -1,7 +1,7 @@
 # Ignite UI house style
 
-Version: v3 · 2026-08-14 · igniteui doc-skill set (content unchanged from v2; set-wide version
-bump). Before editing, confirm this version line against `.ai/skills/CHANGELOG.md`. The "File format & frontmatter" section below is the **single normative
+Version: v4 · 2026-08-31 · igniteui doc-skill set (v4 adds the xplat `apiTerms` contract and the
+`json-snippet` rule; content was unchanged from v2 through v3). Before editing, confirm this version line against `.ai/skills/CHANGELOG.md`. The "File format & frontmatter" section below is the **single normative
 field contract** for the doc-skill set; the two SKILL.md files reference it rather than restating it.
 
 The Ignite UI documentation conventions an authored or audited topic must follow. Pair this with
@@ -63,9 +63,31 @@ llms:
   description: "…"         # AI-facing one-liner; defines the component, not the page — the exact text an assistant quotes
 last_updated: "YYYY-MM-DD" # required for every topic; rendered by the site layout
 relatedComponents: [Toast, Banner]   # TARGET field — drives the Usage Do/Don't trigger (see below)
+platformType: xplat        # xplat: REQUIRED, no default — xplat | xplat-unmapped | web-only
 ---
 ```
 
+- **`platformType` (xplat) is required and has no default.** A missing or unknown value stops the
+  build. It also decides `apiTerms`, which a page then states only to differ: `xplat` implies `full`
+  (names in backticks resolved through the api maps), `xplat-unmapped` implies `passthrough` (resolved
+  by rule, for an API no generator describes), `web-only` implies `none` (left as written, no
+  `ApiLink`). An xplat page may not state `none`; a topic that genuinely cannot resolve its names is
+  `xplat-unmapped`. `docs/xplat/API-TERMS.md` is normative; the `xplat-docs-api-links` skill is the
+  working guide.
+
+- **Three populations share the xplat content tree, held to different standards, and each page says
+  which it is.** The **DV set** — charts, gauges, maps, dashboard tile, data grid, spreadsheet,
+  toolbar, zoom slider — is `platformType: xplat`: canonical names in backticks resolved in full, and
+  a component stated as a `json-snippet` unless a platform-specific snippet is genuinely necessary.
+  `xplat-unmapped` is the same set where that treatment cannot be applied yet — the Excel library,
+  whose API no generator describes, and the data grid's accessibility topic, whose XAML shape is
+  undecided. **Web-only** topics — inputs, layouts, notifications, scheduling, themes, the web grid
+  families, grid lite — carry no such obligation: they may hand write a block per platform and declare
+  any mode, and reworking them to match the DV set is out of scope rather than an improvement.
+  **Identity is not publication:** a topic can be xplat and not reach the desktop platforms yet, so
+  where a page publishes never settles which population it is in. `check-doc-scope.mjs` enforces the
+  declaration and reports the disagreements; the `xplat-docs-json-snippets` skill is the working guide.
+
 - **`llms.description`** already exists in both sets and is high-value — write it as a crisp,
   self-contained answer sentence that **defines the component (or concept), never the page**: subject
   noun names the product and component, no pronouns, no "This topic shows…". It is *not* optional
@@ -466,6 +488,15 @@ audits the body side.
   document a difference that doesn't exist; replace them with **one two-column table:
   variable · what it changes**. Don't add a defaults column either — defaults vary per theme and
   belong to the generated API reference, and the durable content is the variable's name and effect.
+- **An xplat (DV) topic states its component as a `json-snippet` by default.** Generation emits each
+  platform's own code from the product's description metadata, so the four to six copies cannot drift
+  apart and a property that does not exist cannot be published. A platform-specific snippet is
+  discouraged rather than banned: it stays the right tool where a definition genuinely cannot carry the
+  lesson — a data shape with no component in it, a namespace declaration, a package install, a step
+  only one platform family has — and the reason belongs wherever the change is recorded. **Web-only
+  topics are exempt**; a per-platform block there is not a defect. `docs/xplat/JSON-SNIPPETS.md` is normative and the
+  `xplat-docs-json-snippets` skill is the working guide. The rest of this bullet applies to the blocks
+  a topic still authors by hand — Angular's own topics, and the xplat sections a fence cannot state.
 - **Audit & modernize inline code snippets — not the samples.** Fenced code blocks (` ```… ```
   `) are authored in the topic, so verify and update them: no deprecated APIs or outdated framework
   idioms (drop `standalone: true`; prefer Angular's built-in control flow `@if`/`@for` over

diff --git a/.ai/skills/igniteui-topic-frontmatter/SKILL.md b/.ai/skills/igniteui-topic-frontmatter/SKILL.md
@@ -13,7 +13,7 @@ description: >-
 
 # Ignite UI topic frontmatter
 
-Version: v3 · 2026-08-14 · igniteui doc-skill set. All set files carry this version line; before
+Version: v4 · 2026-08-31 · igniteui doc-skill set. All set files carry this version line; before
 editing any file, confirm the lines match across the set. The `.claude` adapter's `description` must
 byte-match this file's `description`. Change log: `.ai/skills/CHANGELOG.md` · human-readable intent:
 `.ai/skills/README.md`.

diff --git a/.ai/skills/igniteui-topic-frontmatter/references/audit-rules.md b/.ai/skills/igniteui-topic-frontmatter/references/audit-rules.md
@@ -1,6 +1,6 @@
 # Frontmatter audit rules
 
-Version: v3 · 2026-08-14 · igniteui doc-skill set. Content carried from SKILL.md v2 unchanged;
+Version: v4 · 2026-08-31 · igniteui doc-skill set. Content carried from SKILL.md v2 unchanged;
 restructured into this reference so rules can evolve without touching the router. The normative
 field contract lives in `../../igniteui-doc-topics/references/house-style.md` → "File format &
 frontmatter"; where wording differs, house-style wins.

diff --git a/.ai/skills/igniteui-topic-frontmatter/references/report-format.md b/.ai/skills/igniteui-topic-frontmatter/references/report-format.md
@@ -1,6 +1,6 @@
 # Audit report format and apply procedure
 
-Version: v3 · 2026-08-14 · igniteui doc-skill set. Content carried from SKILL.md v2 unchanged.
+Version: v4 · 2026-08-31 · igniteui doc-skill set. Content carried from SKILL.md v2 unchanged.
 
 ## Report format
 

diff --git a/.github/AGENTS-README.md b/.github/AGENTS-README.md
@@ -6,21 +6,28 @@ This document describes the AI skills available in this repository, what each on
 
 ## Context
 
-The MDX files under `docs/xplat/src/content/en/` are **shared across four platforms**: Angular, React, WebComponents, and Blazor. A single source file is built once per platform to produce four separate documentation sites. Two recurring tasks require specific knowledge to do correctly:
+The MDX files under `docs/xplat/src/content/en/` are **shared across six platforms**: Angular, React, WebComponents, Blazor, WinUI, and Uno. A single source file is built once per platform to produce a separate documentation site each time, and `docs/xplat/src/content/jp/` mirrors the set.
 
-1. **ApiLink** — inline API hyperlinks that resolve to the correct platform-specific TypeDoc URL at build time.
+**Three populations live in that tree, and every page declares which it is** in its `platformType` frontmatter, which is required and has no default. **`xplat`** is the DV set — charts, gauges, maps, dashboard tile, data grid, spreadsheet, toolbar, zoom slider — where names in backticks resolve in full and a component is stated as a `json-snippet` unless a platform-specific snippet is genuinely necessary. **`xplat-unmapped`** is the same set where that treatment cannot be applied yet: the Excel library, whose API no generator describes, and the data grid's accessibility topic, whose XAML shape is undecided. **`web-only`** — inputs, layouts, notifications, scheduling, themes, the web grid families, grid lite — carries neither obligation and may do as it likes; reworking one to match the DV set is out of scope, not an improvement. Identity is not publication: a topic can be xplat and not reach the desktop platforms yet.
+
+Three recurring tasks require specific knowledge to do correctly:
+
+1. **ApiLink** — inline API hyperlinks that resolve to the correct platform-specific TypeDoc URL at build time, under the processing mode the page's `apiTerms` frontmatter declares.
 2. **PlatformBlock** — a wrapper component that shows content only for the specified platform(s).
+3. **json-snippet** — a component stated once as JSON, which generation turns into each platform's own code rather than a hand written block per platform.
 
-The skills below are the canonical reference for both.
+The skills below are the canonical reference for all three.
 
 ---
 
 ## Skills
 
 | Skill | Use it for |
 |---|---|
-| [`xplat-docs-api-links`](./skills/xplat-docs-api-links/SKILL.md) | Adding, fixing, or auditing `<ApiLink>` calls in MDX files |
+| [`xplat-docs-api-links`](./skills/xplat-docs-api-links/SKILL.md) | Adding, fixing, or auditing `<ApiLink>` calls in MDX files, and the `apiTerms` mode a page declares |
+| [`xplat-docs-json-snippets`](./skills/xplat-docs-json-snippets/SKILL.md) | Writing or validating `json-snippet` fences — the JSON a component is stated in, and the checks over it |
 | [`xplat-docs-platform-block`](./skills/xplat-docs-platform-block/SKILL.md) | Adding, fixing, or auditing `<PlatformBlock>` usage in MDX files |
+| [`xplat-docs-api-map-sync`](./skills/xplat-docs-api-map-sync/SKILL.md) | Keeping the api maps in step with a product release |
 | [`docfx-sync`](./skills/docfx-sync/SKILL.md) | Merging upstream igniteui-docfx changes and fixing MDX regressions |
 
 ---
@@ -34,6 +41,13 @@ The skills below are the canonical reference for both.
 | Adding or updating the `## API References` section at the bottom of a page | `xplat-docs-api-links` |
 | Working with excel library API links (`pkg="excel"`) | `xplat-docs-api-links` |
 | Working with dock manager slot API links | `xplat-docs-api-links` |
+| Showing a component's code on a page, or changing what a snippet shows | `xplat-docs-json-snippets` |
+| Choosing between markup, code, a handler, or `channel="auto"` for a fence | `xplat-docs-json-snippets` |
+| A platform showing a heading and prose with no code under it | `xplat-docs-json-snippets` |
+| Running the schema, emission, casing or live-load checks before pushing | `xplat-docs-json-snippets` |
+| A page that will not build for want of `apiTerms` | `xplat-docs-api-links` |
+| An "Ambiguous API symbol" build failure asking for `pkg=` | `xplat-docs-api-links` |
+| Updating the api maps after a product release | `xplat-docs-api-map-sync` |
 | Wrapping a code block or prose section so it only appears on specific platforms | `xplat-docs-platform-block` |
 | Checking that a file has no bare platform-specific code blocks | `xplat-docs-platform-block` |
 | Investigating a PlatformBlock balance error (unmatched open/close tags) | `xplat-docs-platform-block` |