Fix/template error status code

.agents/skills/debug-session/SKILL.md

@@ -1,8 +1,16 @@
 ---
 name: debug-session
-description: Start a debugging session with worklog file
+description: Sets up a structured debugging session for a Dynamo bug — pull the report from a Linear ticket, GitHub issue, or pasted text, capture the environment, create a persistent worklog markdown file, and walk through rebuild, reproduction, and investigation steps. Use when starting to investigate a reported Dynamo bug or regression and the investigation should be tracked in a worklog.
+license: Apache-2.0
 user-invocable: true
 disable-model-invocation: true
+metadata:
+  author: NVIDIA
+  tags:
+    - dynamo
+    - debugging
+    - worklog
+    - dev-workflow
 ---
 
 # Start Debug Session

.agents/skills/dep-create/SKILL.md

@@ -1,6 +1,14 @@
 ---
 name: dep-create
-description: Create or update Dynamo Enhancement Proposals as GitHub issues, including lightweight DEPs, implementation plans, and retroactive DEPs for ai-dynamo/dynamo.
+description: Creates or updates Dynamo Enhancement Proposals as GitHub issues, including lightweight DEPs, implementation plans, and retroactive DEPs for ai-dynamo/dynamo. Use when proposing a feature or architecture change, drafting an implementation plan, or filing a retroactive DEP.
+license: Apache-2.0
+metadata:
+  author: NVIDIA
+  tags:
+    - dynamo
+    - dep
+    - enhancement-proposal
+    - github
 ---
 
 # Skill: Create a DEP as a GitHub Issue

.agents/skills/dep-status/SKILL.md

@@ -1,6 +1,14 @@
 ---
 name: dep-status
-description: Check Dynamo Enhancement Proposal issue status, list DEPs by lifecycle state or area, and find related DEP issues in ai-dynamo/dynamo.
+description: Checks Dynamo Enhancement Proposal issue status, lists DEPs by lifecycle state or area, and finds related DEP issues in ai-dynamo/dynamo. Use when asking where a DEP stands or which DEPs exist for an area.
+license: Apache-2.0
+metadata:
+  author: NVIDIA
+  tags:
+    - dynamo
+    - dep
+    - enhancement-proposal
+    - github
 ---
 
 # Skill: Check DEP Status

.agents/skills/dep-update/SKILL.md

@@ -1,6 +1,15 @@
 ---
 name: dep-update
-description: Update Dynamo Enhancement Proposal lifecycle state in GitHub, including triage, PIC assignment, review, approval, and status label changes.
+description: Updates Dynamo Enhancement Proposal lifecycle state in GitHub, including triage, PIC assignment, review, approval, and status label changes. Use when triaging a new DEP, assigning a PIC, or moving a proposal through review and approval.
+license: Apache-2.0
+metadata:
+  author: NVIDIA
+  tags:
+    - dynamo
+    - dep
+    - enhancement-proposal
+    - github
+    - lifecycle
 ---
 
 # Skill: Update DEP Lifecycle

.agents/skills/dynamo-kv-replay-parity/agents/openai.yaml

@@ -0,0 +1,7 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+interface:
+  display_name: "Dynamo KV Replay Parity"
+  short_description: "Validate offline KV replay parity and performance"
+  default_prompt: "Use $dynamo-kv-replay-parity to compare offline KV replay correctness and performance across two revisions."

.agents/skills/dynamo-kv-replay-parity/references/internal-polynomial-golden-points.md

@@ -0,0 +1,153 @@
+# Internal-polynomial replay golden-point seeds
+
+<!--
+SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+SPDX-License-Identifier: CC-BY-4.0
+-->
+
+Use these configurations as starting seeds for offline replay qualification, not as
+universal capacities, parity results, or performance results. They were qualified against
+the contiguous first 5,000 rows of the canonical Mooncake trace:
+
+- slice rule: rows 0 through 4,999 in source arrival order;
+- slice SHA-256:
+  `3892ae19ae480b643155f0c6b9d798591cbe2e73bec6a0fa5ae3d3bc0332fb8a`;
+- model: internal polynomial mocker, without AIC profile arguments;
+- routing: KV-aware;
+- arrival speedup: 4;
+- trace block size: 512; and
+- model and decode speedups: 1.
+
+Requalify on the pinned baseline, then run the candidate with exactly the same
+configuration. Never tune the revisions separately.
+
+## Native G1 seeds
+
+| Engine and topology | Starting configuration | Expected pressure and nearest boundaries |
+| --- | --- | --- |
+| vLLM aggregated | 4 workers; engine block 64; G1 blocks 6,144; max sequences 16; batch tokens 8,192 | 1 preemption; 4,096 produced 21 and 8,192 produced 0 |
+| vLLM disaggregated | 2 prefill + 2 decode; engine block 64; G1 blocks 40,964; max sequences 16; batch tokens 8,192; KV bytes/token 1; 100 GB/s full-prompt transfer | 4 preemptions; exact next integer capacity 40,965 produced 0. This is a documented nearest-feasible exception to the 1–3 target: max sequences 15 produced 9–13 near the edge and max sequences 17 produced 0 |
+| SGLang aggregated | 4 workers; engine/page block 512; G1 blocks 1,536; max sequences 256; batch tokens 32,768 | 1 retraction; 1,024 produced 8 and 2,048 produced 0 |
+| SGLang disaggregated | 2 prefill + 2 decode; engine/page block 512; G1 blocks 17,408; max sequences 256; batch tokens 32,768; KV bytes/token 262,144; 100 GB/s full-prompt transfer | 2 retractions; 16,384 produced 12 and 18,432 produced 0 |
+
+The vLLM configurations rely on native/default G1 selection. An experiment-only
+`--g1-backend` switch is not required to reproduce the native seeds.
+
+### CLI templates
+
+Set the artifact and trace paths, then reuse the common load-generation arguments:
+
+```bash
+BIN=/path/to/offline_replay_bench
+TRACE_5000=/path/to/mooncake_trace_rows_000000_004999.jsonl
+COMMON_ARGS=(
+  --router-mode kv-router
+  --arrival-speedup-ratio 4
+  --trace-block-size 512
+  --speedup-ratio 1
+  --decode-speedup-ratio 1
+  --iterations 1
+)
+```
+
+vLLM aggregated:
+
+```bash
+"$BIN" "$TRACE_5000" \
+  --serving-mode aggregated \
+  --num-workers 4 \
+  --engine-type vllm \
+  --block-size 64 \
+  --num-gpu-blocks 6144 \
+  --max-num-seqs 16 \
+  --max-num-batched-tokens 8192 \
+  "${COMMON_ARGS[@]}"
+```
+
+vLLM disaggregated:
+
+```bash
+"$BIN" "$TRACE_5000" \
+  --serving-mode disagg \
+  --num-prefill-workers 2 \
+  --num-decode-workers 2 \
+  --engine-type vllm \
+  --block-size 64 \
+  --num-gpu-blocks 40964 \
+  --max-num-seqs 16 \
+  --max-num-batched-tokens 8192 \
+  --kv-bytes-per-token 1 \
+  --kv-transfer-bandwidth 100 \
+  --kv-transfer-timing-mode full-prompt \
+  "${COMMON_ARGS[@]}"
+```
+
+SGLang aggregated:
+
+```bash
+"$BIN" "$TRACE_5000" \
+  --serving-mode aggregated \
+  --num-workers 4 \
+  --engine-type sglang \
+  --block-size 512 \
+  --num-gpu-blocks 1536 \
+  --max-num-seqs 256 \
+  --max-num-batched-tokens 32768 \
+  "${COMMON_ARGS[@]}"
+```
+
+SGLang disaggregated:
+
+```bash
+"$BIN" "$TRACE_5000" \
+  --serving-mode disagg \
+  --num-prefill-workers 2 \
+  --num-decode-workers 2 \
+  --engine-type sglang \
+  --block-size 512 \
+  --num-gpu-blocks 17408 \
+  --max-num-seqs 256 \
+  --max-num-batched-tokens 32768 \
+  --kv-bytes-per-token 262144 \
+  --kv-transfer-bandwidth 100 \
+  --kv-transfer-timing-mode full-prompt \
+  "${COMMON_ARGS[@]}"
+```
+
+## Expected behavior
+
+With the exact corpus and internal model above, use these observed values as drift
+detectors:
+
+| Engine and topology | Immediate / queued | Requests with reuse | Worker and handoff evidence |
+| --- | --- | --- | --- |
+| vLLM aggregated | 8 / 4,992 | 4,918 | decode workers 0–3 |
+| vLLM disaggregated | 4 / 4,996 | 4,991 | prefill and decode workers 0–1; 5,000 complete, backend-valid handoffs |
+| SGLang aggregated | 5 / 4,995 | 4,840 | decode workers 0–3 |
+| SGLang disaggregated | 2 / 4,998 | 4,992 | prefill and decode workers 0–1; 5,000 complete, backend-valid handoffs |
+
+Every row must complete all 5,000 requests with no rejected, canceled, failed, or stranded
+requests. A changed counter is not automatically a product failure, but it means the seed
+must be requalified and the cause recorded before freezing the row.
+
+## Derive and sanity-check KVBM rows
+
+Derive each vLLM KVBM row from its corresponding native seed by enabling G2 and modestly
+reducing or limiting G1. Keep the topology fixed; start disaggregated qualification at
+exactly 2 prefill + 2 decode workers. Tune capacity or concurrency identically for both
+revisions.
+
+Require all of the following before freezing a KVBM row:
+
+- all 5,000 requests complete;
+- one to three bounded preemptions, without repeated preempt/re-admit cycling;
+- nonzero G1-to-G2 eviction completion;
+- nonzero G2-to-G1 restoration hits;
+- identical lifecycle counts across repeated baseline and candidate runs;
+- 5,000 complete, backend-valid handoffs for disaggregated replay; and
+- one canonical digest per revision, with baseline and candidate digests matching.
+
+Do not infer offload coverage from successful completion. Do not proceed to performance
+when lifecycle counters match but a revision's canonical repetitions differ; that is an
+internal determinism failure. SGLang KVBM offload is unsupported by the current harness
+and must be reported as `UNSUPPORTED`, not simulated by toggling an ignored G1 option.

.agents/skills/fern-components/SKILL.md

@@ -0,0 +1,159 @@
+---
+name: fern-components
+description: Knowledge of Fern's built-in MDX component library (accordions, callouts, cards, steps, tabs, code blocks, API-reference snippets, and more) for authoring docs pages. Use when writing or editing a Fern `.mdx` page and deciding whether a component would present content better than plain Markdown, when a user asks "what Fern components exist" or "how do I use `<X>`", or when reviewing a page for missed opportunities to use a component. Complements dynamo-docs (which owns page placement, nav, frontmatter, and the style guide).
+license: Apache-2.0
+metadata:
+  author: NVIDIA
+  tags:
+    - fern
+    - docs
+    - mdx
+
+---
+
+# Fern Components
+
+<!--
+SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+SPDX-License-Identifier: CC-BY-4.0
+-->
+
+Fern ships a built-in library of ~27 MDX components you can use in documentation pages without
+importing anything. This skill catalogs them, says **when each is worth reaching for**, and points to
+[`references/components-reference.md`](references/components-reference.md) for exact syntax, every prop,
+and copy-paste examples.
+
+This skill is **component knowledge only**. Page placement, `docs/index.yml` nav, frontmatter, SPDX
+headers, links, terminology, and the style guide belong to the **dynamo-docs** skill — use both
+together when authoring.
+
+## The `.md` vs `.mdx` rule (read this first in this repo)
+
+Fern components are JSX. They render **only in `.mdx` files**. This repo (`ai-dynamo/dynamo`) mixes two
+page formats, and the boundary is a hard must-fix:
+
+| Page type | How to write rich content |
+|---|---|
+| **`.mdx`** (e.g. `getting-started/introduction.mdx`, recipe pages) | Use Fern components **directly** — `<CardGroup>`, `<Steps>`, `<Accordion>`, `<Tabs>`, `<Note>`, etc. |
+| **`.md`** (most docs pages) | **Do not hand-write `<Note>`/`<Tip>`/etc.** Write callouts GitHub-style (`> [!NOTE]`); `fern/convert_callouts.py` converts them at build. Other components (Cards, Steps, Tabs…) are **not** available — restructure with plain Markdown, or convert the page to `.mdx` on purpose. |
+
+Callout conversion map (GitHub → Fern), for `.md` pages:
+
+| `> [!NOTE]` | `> [!TIP]` | `> [!IMPORTANT]` | `> [!WARNING]` | `> [!CAUTION]` |
+|---|---|---|---|---|
+| `<Note>` | `<Tip>` | `<Info>` | `<Warning>` | `<Error>` |
+
+**Before using any component below, confirm the target file is `.mdx`.** If it's `.md` and you need a
+non-callout component, the decision (restructure vs. rename to `.mdx`) is a dynamo-docs / nav concern —
+raise it, don't silently rename.
+
+## When to reach for a component (and when not)
+
+Prefer plain Markdown. A component earns its place only when it does something Markdown can't:
+progressive disclosure, sequencing, branching, live API data, or interactivity. Don't decorate — an
+ordered list is better than `<Steps>` for two trivial steps, and a sentence is better than a `<Card>`
+whose only job is to host a link (see the dynamo-docs / Fern cross-reference guidance).
+
+| You want to… | Component | Notes |
+|---|---|---|
+| Flag a note / warning / tip | **Callout** (`<Note>` `<Tip>` `<Warning>` `<Info>` `<Success>` `<Error>` `<Launch>` `<Check>`) | In `.md`, use `> [!NOTE]` syntax instead (see above). |
+| Collapse FAQs / optional detail | **Accordion** / **AccordionGroup** | Content stays SEO-indexed while collapsed. |
+| Sequence a tutorial / setup | **Steps** / **Step** | Auto-numbered, anchor links. Use `toc` to surface in the TOC. |
+| Show the same thing per-language / per-OS | **Tabs** / **Tab** | `language=` syncs all tabs+code blocks site-wide. |
+| Navigation grid / feature hub | **Card** / **CardGroup** | `cols={n}`, Font Awesome icons, images, `href` makes the whole card clickable. |
+| Rich code (highlight, focus, title, embed a file) | **Code block** / `<Code>` / `<CodeBlocks>` / `<CodeGroup>` | Fenced ``` with attrs; `<Code src>` embeds local/GitHub files. |
+| Multiple install commands (npm/pnpm/yarn) | **CodeGroup** with `for=` | Custom sync group independent of language. |
+| Image with caption / framing | **Frame** | Wraps `<img>`/`<video>`; `background="subtle"`. |
+| Long / searchable / sticky-header table | **StickyTable** / **SearchableTable** / **StickySearchableTable**, or `<table sticky searchable>` | Plain Markdown tables are fine for short data. |
+| Inline status / version chip | **Badge** | For longer notes use a Callout instead. |
+| Small icon inline / in headings | **Icon** | Font Awesome name or `./path.svg`. |
+| Clickable button / CTA / download trigger | **Button** | `intent`, `href`, icons. |
+| Downloadable asset (PDF, ZIP bundle) | **Download** | `src=` single file, `sources={[…]}` zips multiple. |
+| Click-to-copy inline text | **Copy** | Show one value, copy another via `clipboard=`. |
+| Hover explanation for a term or code token | **Tooltip** / `<Template>` | `<Template>` adds tooltips to code-block variables. |
+| Document a param / field / config key | **ParamField** | The standard field-doc row: `path`, `type`, `required`, `default`, `deprecated`. |
+| Indent nested params visually | **Indent** | Wraps any content (unlike `<Folder>`). |
+| Show a project / directory tree | **Files** / **Folder** / **File** | `defaultOpen`, `href`, `highlighted`, `comment`. |
+| Link to non-heading content | **Anchor** | `id=` on paragraphs, tables, code blocks. |
+| Float supplementary content right | **Aside** | Sticky; good for an endpoint snippet beside prose. |
+| Copyable AI prompt (open in Cursor/Claude/ChatGPT) | **Prompt** | `actions={["cursor","claude","chatgpt"]}` or custom URL. |
+| Show/hide by product, version, or role | **If** | `products` / `versions` / `roles`, combinable, `not` to invert. |
+| Inline versioned content with a switcher | **Versions** / **Version** | Distinct from site-wide versioning. |
+| **API reference — request code sample** | **EndpointRequestSnippet** | `endpoint="POST /path"`; `languages`, `payload`, `hideTryItButton`. |
+| **API reference — response sample** | **EndpointResponseSnippet** | Pulls from your API definition. |
+| **API reference — endpoint schema (params/body)** | **EndpointSchemaSnippet** | `selector="request.body"` etc. |
+| **API reference — any named type** | **Schema** / **SchemaSnippet** | `<Schema type="…">` fields; `<SchemaSnippet>` JSON. |
+| **API reference — live "try it" request builder** | **RunnableEndpoint** | Real HTTP calls from the page. |
+| **API reference — webhook payload** | **WebhookPayloadSnippet** | By `operationId`. |
+| Reuse a Markdown fragment in many places | **`<Markdown src>`** (reusable snippets) | Single-source constants/warnings; supports `{{params}}`. |
+| Something bespoke / interactive | **Custom React component** | `.tsx` in a components dir wired via `docs.yml`; SSR'd. |
+
+Full syntax, every prop, variants, and examples for **all** of the above are in
+[`references/components-reference.md`](references/components-reference.md). Read the relevant section
+before writing a component you don't use often — props and exact names (e.g. `<Note>` vs `<Callout
+intent>`, `iconSize` math, `selector` values) are easy to get wrong from memory.
+
+## Authoring workflow
+
+1. **Confirm the file is `.mdx`.** If `.md`, only GitHub-style callouts apply (see the rule above).
+2. **Ask "does Markdown already do this?"** If yes, use Markdown. Only reach for a component when it
+   adds disclosure, sequencing, branching, interactivity, or live API data.
+3. **Open the reference** section for the component and copy the closest example. Match prop names and
+   casing exactly (MDX is `className`, not `class`; attributes are `camelCase` — `autoPlay`, not
+   `autoplay`).
+4. **Nest deliberately.** Most containers accept rich children (a `<Note>` inside a `<Step>`, a
+   `<CardGroup>` inside an `<Accordion>`). `<Folder>` is the exception — it takes only `<File>` /
+   `<Folder>`; use `<Indent>` when you need to indent anything else.
+5. **Anchors:** `##`/`###` headings auto-generate anchors; `title=` props on `<Step>`, `<Tab>`,
+   `<Accordion>`, `<Card>` **do not**. To deep-link one, add a real heading or use `<Anchor id>`.
+6. **MDX gotchas that break the build:** put a blank line after `<div …>` and before `</div>`; keep
+   code fences at column 0; replace bare `<https://…>` with `[text](https://…)`; escape stray `<`/`>`
+   and literal `$` (`\$`) outside code.
+
+## Suggesting components during review
+
+When reviewing or improving an existing `.mdx` page, watch for these high-value swaps:
+
+- A wall of "first… then… next…" prose or a long ordered list of actions → **Steps**.
+- Parallel per-language / per-OS / per-backend blocks repeated back to back → **Tabs** (with
+  `language=` when it's code, so they sync).
+- A long FAQ, or optional deep-dive detail interrupting the main flow → **Accordion**.
+- A cluster of "see also" links at the top or bottom of a page → **CardGroup** of **Card**s.
+- Hand-maintained request/response code that duplicates the API definition → the **Endpoint*Snippet**
+  family (also gives AI agents structured Markdown output).
+- The same constant, warning, or boilerplate copy-pasted across pages → a **reusable snippet**
+  (`<Markdown src>`).
+- A very long reference table users scan → **StickyTable** / **SearchableTable**.
+
+Suggest the lightest option, name the component, and point at the reference section — don't rewrite a
+working page just to add components.
+
+## Staying in sync with Fern (refresh mechanism)
+
+This skill is a **cached snapshot** of Fern's component docs, not a live mirror — so it works offline
+and loads instantly. The trade-off is that it can drift when Fern ships or changes a component.
+[`scripts/refresh_components.py`](scripts/refresh_components.py) tracks that drift, and
+[`manifest.json`](manifest.json) records the upstream git-blob SHA of every source page as of the last
+sync (see `manifest.json`'s `fetched_at` for how old this snapshot is).
+
+Source of truth (GitHub `fern-api/docs@main`): the component-library pages under
+`fern/products/docs/pages/component-library/**` plus `customization/custom-react-components.mdx` and
+`navigation/tabs.mdx`.
+
+**On-load staleness check (do this when the skill loads):** read `manifest.json`'s `fetched_at`. If it
+is more than ~3 months old — or the user asks whether the components are current, or a component
+doesn't behave as the reference claims — tell the user the snapshot's age and offer to refresh. Don't
+refresh unprompted: it needs internet and edits the reference, so surface it and let the user say go.
+Refreshing prefers the `gh` CLI and falls back to the public GitHub API; everything else here is
+offline.
+
+```bash
+# From the skill dir. --check is read-only and safe to run anytime.
+python3 scripts/refresh_components.py --check              # drift vs manifest? exit 2 = drift, 0 = in sync
+python3 scripts/refresh_components.py --fetch --out /tmp/fern-refresh   # download only changed pages
+#   → then update references/components-reference.md and the tables above from those pages,
+python3 scripts/refresh_components.py --sync               # record the new SHAs as current
+```
+
+Only `--sync` writes the manifest; `--check`/`--fetch` never mutate the skill. After editing the
+reference from freshly fetched pages, run `--sync` so the next `--check` is clean.