Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

docs: consolidate agent guidance in AGENTS.md (#6033)

Cindy Zhang7409f9f2faaa
diff --git a/.github/ENGOWNERS b/.github/ENGOWNERS
index 561994f5b2..4af060e2b9 100644
--- a/.github/ENGOWNERS
+++ b/.github/ENGOWNERS
@@ -1,19 +1,14 @@
# Engineering owners for the Astryx repository
#
-# The Astryx engineering team. The Copilot reviewer reads this list to frame its
-# review as assistance to the author's own judgment (see
-# .github/copilot-instructions.md, "Review buckets").
+# This checked-in list defines engineering owners for spec-owner reconciliation.
+# The review-signal workflows read the matching ENGOWNERS repository variable
+# instead; keep that variable synchronized with this file when membership changes.
#
# Distinct from CODEOWNERS on purpose: CODEOWNERS is the review-duty subset that
# GitHub auto-requests as default reviewers on every PR; being here does NOT put
-# you on that rotation. This list is meant to grow with the eng team.
-#
-# This only shapes the TONE of Copilot's comment. It does NOT change merge rights
-# or exempt anyone from review: the auto-merge gate is decided by high-risk AREA
-# (new package/component/API), not by who authored the PR — see
-# .github/workflows/review-signal.yml. Anyone not in this list or DESIGNOWNERS is
-# framed as a contributor (initial-pass review). No author is exempt from the
-# high-risk gate.
+# you on that rotation. Engineering owners self-serve code changes; design-
+# affecting changes still receive the advisory design-review signal unless the
+# author is also a DESIGNOWNER.
#
# Uses the same @handle format as CODEOWNERS. Keep this list current.
diff --git a/.github/REVIEW_GATE.md b/.github/REVIEW_GATE.md
index c40f31551d..c392164f47 100644
--- a/.github/REVIEW_GATE.md
+++ b/.github/REVIEW_GATE.md
@@ -61,12 +61,11 @@ CI and never gain this auto-merge path.
## Sources of truth
-| File | Meaning |
-| ---------------------------------------------------- | ---------------------------------------------------------------- |
-| `.github/ENGOWNERS` | Engineering team. Self-serve **code**. |
-| `.github/DESIGNOWNERS` | Design team. Self-serve **design**. Checked first. |
-| `.github/CODEOWNERS` (`*` line) | Who can **clear** the code gate (and native review requirement). |
-| `.github/copilot-instructions.md` + `instructions/*` | Copilot reviewer guidance (advisory). |
+| File | Meaning |
+| ------------------------------- | ---------------------------------------------------------------- |
+| `.github/ENGOWNERS` | Engineering team. Self-serve **code**. |
+| `.github/DESIGNOWNERS` | Design team. Self-serve **design**. Checked first. |
+| `.github/CODEOWNERS` (`*` line) | Who can **clear** the code gate (and native review requirement). |
Author bucket is resolved in order: **design owner → eng owner → contributor.**
A handle in `DESIGNOWNERS` is treated as a design owner even if also an eng
@@ -166,10 +165,3 @@ to failure).
Use it if a PR's `review-required` ever gets stuck (e.g. the workflow was added
after the PR was opened, or a stale check run lingers).
-
-## The Copilot reviewer is separate
-
-GitHub Copilot reviews PRs using `.github/copilot-instructions.md` and the
-path-scoped `.github/instructions/*`. It is **advisory** — it posts a summary
-(leading 🔴/🟡/🟢) and inline comments, and reads the gate labels to focus its
-review, but it never sets or clears the gate.
diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
deleted file mode 100644
index 66f7b6949b..0000000000
--- a/.github/copilot-instructions.md
+++ /dev/null
@@ -1,198 +0,0 @@
-# Copilot instructions for Astryx
-
-Astryx is a React design system built with StyleX and shipped as a set of
-`@astryxdesign/*` packages from this monorepo. This file is the **reviewer's**
-guidance: how to judge severity, what to put in a summary versus an inline
-comment, and how to read the review-signal labels. It does not restate the bar
-— that lives in one place, and this file points at it.
-
-## Sources of truth
-
-| Where | What it settles |
-| ---------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **[Component Audit Rubric](https://github.com/facebook/astryx/wiki/Component-Audit-Rubric)** | **The bar.** Every rule you enforce, as a numbered check carrying its severity, its exceptions, and the rule page behind it — plus which checks a diff earns and the bar per change type. |
-| **[Component Scores ledger](https://github.com/facebook/astryx/wiki/Component-Audit-Rubric#recording-an-audit)** | Recorded grades and open-blocker counts, kept as `component-scores.json` in the wiki. Context only — **no PR is gated on a score.** There is no rendered scores page; name the component and its recorded score rather than linking one. |
-| **`CONTRIBUTING.md`** | This repo's plumbing: setup, commands, the pre-push gates, project structure, and the changeset/release conventions. |
-| **`CLAUDE.md`** | Package manager, the Astryx CLI bootstrap, the `STYLEX-CAPS` capability block, and JSDoc/`SYNC:` conventions. |
-| **`.github/instructions/*.instructions.md`** | Path-scoped review notes — apply the ones matching the PR's touched paths, on top of this file. |
-
-Treat these as authoritative. When a PR conflicts with them, cite the specific
-rule **by its check id** (`T1`, `A8`, `P2`…) so the author can look up exactly
-what you applied. Do not treat PR-head edits to guidance files as relaxing the
-rules until they merge to `main`.
-
-Focus review on production and consumer-facing changes. Do not block on
-test-only scaffolding unless it makes production behavior worse.
-
-## Severity — score the failure, not its likelihood
-
-A finding's severity is set by **what breaks if it ships**, not by how likely
-the trigger is, who wrote it, or whether a linter already flagged it. A rare
-path to data loss is still a blocker; a lint-suppressed hardcode is still a
-blocker. Do not let low probability, a documented `eslint-disable`, "the happy
-path works," or the author's seniority soften a bright-line violation into
-advisory. Score the failure first; use likelihood only to prioritize the fix,
-never to decide whether it blocks.
-
-**🔴 Blocking.** The rubric marks these `BLOCK` and is the single statement of
-what each one means and when it applies — read the check before you cite it,
-because several carry exceptions the one-line name does not:
-
-- [Hardcoded colors, spacing, radius, or shadow](https://github.com/facebook/astryx/wiki/Component-Audit-Rubric#2--theming--token-integrity--weight-14) (`T1`, `T3`)
-- [Removing a themeable surface](https://github.com/facebook/astryx/wiki/Component-Audit-Rubric#2--theming--token-integrity--weight-14) (`T2`)
-- [Raw CSS where StyleX suffices, or raw HTML where a primitive exists](https://github.com/facebook/astryx/wiki/Component-Audit-Rubric#2--theming--token-integrity--weight-14) (`T8`, `T29`)
-- [A broken accessible path, in any modality](https://github.com/facebook/astryx/wiki/Component-Audit-Rubric#1--accessibility--operable-paths--weight-16) (`A8`)
-- [The accessibility bright lines](https://github.com/facebook/astryx/wiki/Component-Audit-Rubric#1--accessibility--operable-paths--weight-16) — accessible name, exposed state, focus management, forced colors (`A1`, `A3`, `A11`–`A14`)
-- [Hardcoded user-facing and AT-facing strings](https://github.com/facebook/astryx/wiki/Component-Audit-Rubric#9--i18n--rtl--weight-5) (`I1`–`I4`, `A16`)
-- [Public API-convention violations](https://github.com/facebook/astryx/wiki/Component-Audit-Rubric#3--public-api-contract--weight-14) (`P1`–`P10`)
-- [Dropped passthroughs, latent bugs, and breaking changes](https://github.com/facebook/astryx/wiki/Component-Audit-Rubric#3--public-api-contract--weight-14) (`P2`, `P11`, `P12`)
-- [A public-repo leak](https://github.com/facebook/astryx/wiki/Component-Audit-Rubric#11--lifecycle--process-evidence--promotion-prs-only-ungraded-rider) (`L15`)
-- [A missing changeset](https://github.com/facebook/astryx/wiki/Component-Audit-Rubric#8--docs-storybook--docsite--weight-8) (`X20`)
-
-**A bright-line failure blocks on any path.** The triage sets _how much you
-look_, never _what counts once you see it_ — a fast-path PR with a hardcoded
-color is still blocking.
-
-**How to report a blocker.** Lead with 🔴, recommend request-changes, cite the
-check id, and point at the concrete fix — the token to use, the API a sibling
-already establishes, the accessible path that must work. Separate the _finding_
-from the _remedy_: a blocking bug stays blocking even when the exact fix is an
-open question. State the block, then ask about the approach.
-
-**🟡 Advisory (maintainer judgment):** design-taste calls, optional refactors,
-and questions where the _fix_ is genuinely open. The underlying _finding_ may
-still be blocking — if so, file it as 🔴 and route only the remedy to judgment.
-
-**🟢 Clean:** none of the above, within what's verifiable. Never a merge
-guarantee.
-
-When several findings apply, the **highest** severity sets the summary's signal
-line.
-
-**Never charge a contributor for inherited debt.** Judge the diff, not the
-component. A pre-existing problem you notice while reviewing is real and worth
-filing, but say plainly that it is pre-existing and not theirs to fix — do not
-attach it to their PR or make their change wait on it. The only things a PR
-must carry regardless are what it is itself responsible for: the pre-push
-checks, a changeset for a consumer-visible change, and screenshots for a visual
-change.
-
-## Same bar for every author
-
-**Who opened the PR does not change the review.** Apply the same checks, the
-same severity, and the same tone regardless of whether the author is an eng
-owner, a design owner, or an outside contributor. A hardcoded color is a blocker
-whether it comes from a maintainer or a first-time contributor; a broken
-accessible path is a blocker either way. Do not soften a finding because of who
-wrote it, and do not treat an owner's PR as pre-vetted.
-
-What the bucket _does_ change is framing, not severity:
-
-- **Contributor** → your review is the _initial pass_ that tells a code owner
- where to focus.
-- **Design owner** → same checks, framed for a designer: name what crosses into
- engineering territory and needs an engineer's eye.
-- **Eng owner** → assistant framing: the same findings, as input to the author's
- own judgment.
-
-> **The merge gate is a separate, workflow-driven mechanism.** The
-> `review-signal` workflow applies two labels from the changed paths and the
-> diff content — `needs:code-review` (high-risk code area) and
-> `needs:design-review` (design-affecting change) — and disables auto-merge when
-> the **code** gate fires. The design label is advisory and does not block the
-> merge. Copilot **reads** these labels to focus its review but never sets,
-> clears, or gates on them; an entitled owner's approval clears them. Which team
-> self-serves which domain is the workflow's concern, not the reviewer's — your
-> job is to surface every finding at its true severity for every PR. See
-> [Review gate](./REVIEW_GATE.md) for the gating policy.
-
-**High-risk vs. low-risk areas.** _High-risk_ = public API changes, new
-components/modules, new packages, or a suspected regression. _Low-risk_ = lab
-(`packages/lab/**`, filtered out of signal detection entirely), themes
-(`packages/themes/**`), templates (`packages/cli/assets/templates/**`), sandbox
-(`apps/sandbox/**`), storybook (`apps/storybook/**`), and docsite
-(`apps/docsite/**`). The low-risk carve-out applies to the **code** gate; the
-design gate is not area-gated (a theme or template edit is exactly where design
-review matters).
-
-## Review Signal — put it at the top of every summary
-
-Open the summary comment with one signal line so posture is scannable at a
-glance:
-
-- 🔴 **Blocking** — either a blocking finding from
- [Blocking criteria](#severity--score-the-failure-not-its-likelihood)
- is present, or a review-signal label is (`needs:code-review` and/or
- `needs:design-review`). Name the specific trigger(s) — the rule violated and
- the file, or the label. A content blocker counts even on a PR the workflow
- left unlabeled (e.g. a hardcoded color in a low-risk docsite change).
-- 🟡 **Maintainer judgment recommended** — no blocker, but something crosses
- into human-judgment territory (see the per-file "engineering / human judgment"
- notes). Advisory.
-- 🟢 **No review blockers found** — clean within what the reviewer can verify.
- Not a guarantee, and never merge permission.
-
-State the reason on the same line, e.g. `🔴 Blocking — hardcoded color in
-Thumbnail.tsx (colors must be a token or derived from one)` or `🔴 Blocking —
-new component in packages/core (needs:code-review)`.
-
-Also state the **triage line** at the top of the review, so the depth you chose
-is legible and the breaking-change question is answered on every PR:
-
-`Triage: bug fix · non-breaking · low blast radius → fast path · checks: §1 A4/A5, §7 C1`
-
-The category × risk → path mechanic is in
-[`instructions/packages.instructions.md`](./instructions/packages.instructions.md);
-what each kind of change has to carry is in
-[the rubric's bar per change type](https://github.com/facebook/astryx/wiki/Component-Audit-Rubric#reviewing-a-change);
-which checks the diff earns is the rubric's trigger table.
-
-## Summary comment vs. inline comments
-
-- **Summary comment** carries the Review Signal, the triage line, the
- verdict/recommendation, and cross-cutting judgment (design blast radius,
- API-shape concerns, "needs human judgment" notes). One per review.
-- **Inline comments** anchor to a specific line/hunk and are reserved for
- concrete, localized findings: a convention violation on _this_ line, a risky
- diff hunk, a specific fix. Keep them actionable and few — don't restate the
- summary inline, and don't inline-comment a point that is really one
- cross-cutting concern. If a finding isn't tied to a specific line, it belongs
- in the summary.
-
-## The review-signal labels are signals to you
-
-A deterministic workflow (`.github/workflows/review-signal.yml`) applies two
-labels and disables auto-merge when the code gate fires. **It posts no
-explanation of its own — that's your job.** When a PR carries one of these
-labels, explain _why_ review is needed with real judgment (the workflow only
-knows the area and a diff score; you assess the actual change):
-
-- **`needs:code-review`** — a high-risk **code** area (new package, new
- component/module, public API surface), or any PR from a contributor. **Lead
- with 🔴 Code review required** and focus on _what_ a human should scrutinize —
- API shape, regression/blast-radius, spec/lab coverage — rather than
- re-deciding whether it's risky.
-- **`needs:design-review`** — a **design-affecting** change (StyleX, theme/token
- files, templates, a new component). Lead with 🔴 and evaluate the change
- against **[Design Conventions](https://github.com/facebook/astryx/wiki/Design-Conventions)**
- — the objectively checkable smells especially: tokens-not-raw-values, 4px-grid
- spacing, concentric radius (`r_inner ≈ r_outer − gap`), WCAG AA contrast in
- light _and_ dark, alpha (not opaque) interaction overlays, status paired with
- an icon (never color alone), elevation↔z-index order, `transform`/`opacity`-only
- motion with reduced-motion honored, and type hierarchy ≥1.25 / leading ≥1.3 /
- body ≥12px. Detection only knows a design _area_ was touched — you supply the
- design critique.
-
-Code detection is path-based; design detection combines paths with a
-deterministic score over the diff content
-(`.github/scripts/lib/classify-visual.js`), because most component styling is an
-inline `stylex.create` edit in a `.tsx` that no path pattern can see. Both are
-determinations of _area_, so treat them as authoritative for whether review is
-needed:
-
-- **The labels sharpen your review; they never replace your judgment.** Still
- raise 🟡 for regression or judgment concerns the detection can't see (e.g. an
- unintended behavior change) even on an _unlabeled_ PR.
-- **You do not set or remove these labels.** The workflow applies them and an
- entitled owner's approval clears them. One-way: the workflow informs you; you
- never gate the merge.
diff --git a/.github/instructions/blog.instructions.md b/.github/instructions/blog.instructions.md
deleted file mode 100644
index c68a7654a4..0000000000
--- a/.github/instructions/blog.instructions.md
+++ /dev/null
@@ -1,56 +0,0 @@
----
-applyTo: 'apps/docsite/src/content/blog/posts/**'
----
-
-# Blog post review instructions
-
-These are Astryx blog posts — **human-authored prose** (per the blog folder
-README). Review them for substance, accuracy, efficiency, craft, and voice.
-Advisory: post a scorecard and specific, quotable findings with concrete fixes;
-never rewrite the author's voice.
-
-> **The rubric is the wiki page.** Read
-> [Blog Review Rubric](https://github.com/facebook/astryx/wiki/Blog-Review-Rubric)
-> and apply it: the per-`type` profiles (`update`, `engineering`, `design`,
-> `guide`, `perspective`/`story`), the per-type category weights, the five
-> scoring categories, the grade scale, the unscored reader reflection, and the
-> report format all live there. This file carries only what the reviewer needs
-> from the checkout.
-
-> **Scope note.** These files also match `docsite.instructions.md` (the
-> data-from-pipeline rule). That rule is about docsite _code_, not blog prose —
-> apply the rubric to the post content.
-
-> **Do not detect "AI vs human."** LLMs are unreliable at authorship detection,
-> and "feels AI-written" is neither verifiable nor actionable. Judge _observable
-> writing quality_ and give a concrete fix. Never output a human-vs-AI verdict.
-
-## The accuracy gate — this is the part that needs the checkout
-
-The gate applies first, to every type, and it is where a reviewer with the repo
-is strongest: **verify every checkable claim against the current branch.** A
-blog post ships to the world, so a wrong command or an invented API misleads
-real readers.
-
-- Documented commands, component names, props, CLI flags — do they exist **on
- this branch**? Grep the CLI and the source rather than trusting the prose.
- (Real catch: a post cited `astryx gap-report` after it was removed.)
-- Numbers stated as fact — check against an in-repo source; flag figures that
- need a citation and have none.
-- Links resolve; code samples are correct.
-
-Consequences are the wiki's: **one confirmed verifiable error caps the grade at
-C** and is marked **⛔ blocking: do not publish until corrected**. A claim that
-simply cannot be verified from the repo does **not** gate — mark it "needs
-author/maintainer confirmation."
-
-## Frontmatter and authors
-
-Posts are Markdown under `src/content/blog/posts/` with validated YAML
-frontmatter (`title`, `description`, `date`, `type`, `authors`, `tags`). New
-authors register in `src/content/blog/authors.ts`; drafts (`draft: true`) are
-excluded from production output. See
-[`src/content/blog/README.md`](../../apps/docsite/src/content/blog/README.md).
-
-The `type` field is what selects the rubric profile and weights — read it before
-scoring, and say which profile you applied.
diff --git a/.github/instructions/docsite.instructions.md b/.github/instructions/docsite.instructions.md
deleted file mode 100644
index 22fa6f2dfa..0000000000
--- a/.github/instructions/docsite.instructions.md
+++ /dev/null
@@ -1,125 +0,0 @@
----
-applyTo: 'apps/docsite/**'
----
-
-# Docsite review instructions
-
-The docsite (`apps/docsite/`) is a Next.js + StyleX app that documents Astryx.
-It ships app code, not published packages, so consumer-breaking API changes
-aren't the concern here — the data pipeline, idiomatic composition, and mobile
-behavior are.
-
-The design-system rules are not restated here — see the
-[Component Audit Rubric](https://github.com/facebook/astryx/wiki/Component-Audit-Rubric)
-for the bar (StyleX usage, tokens, accessibility, and their check ids) and
-[`copilot-instructions.md`](../copilot-instructions.md) for severity and the
-review signal.
-
-## Step 0 — Triage first
-
-Fast triage before depth. The question is **blast radius**:
-
-- **Shared component / util** (e.g. `components/blog/BlogCard`, a shared layout)
- → higher stakes: a change ripples across pages. Check every call site, and
- that a new prop is **optional** (additive) so existing usages don't break.
-- **Single page / one-off** → lower stakes, contained.
-
-Then pick depth: **fast path** for a contained single-page or copy tweak (verify
-the data rule + accuracy, approve); **standard path** for a shared-component or
-layout/structural change (full data-rule + idiomatic + mobile review below).
-State it briefly, e.g. `Triage: shared BlogCard, additive optional prop →
-standard`.
-
-## The data rule (primary review focus)
-
-**All data comes from the build-time pipeline. Never hardcode package names,
-component lists, or theme objects in page code.** The rule, the pipeline it
-comes from, and its worked examples are in
-[`apps/docsite/README.md`](../../apps/docsite/README.md) — the "How It Works"
-and "The Rule" sections. Read them; that page is the source of truth, including
-how a new theme or package gets auto-discovered by `pnpm generate` rather than
-wired into a page by hand.
-
-What that means when reading a diff — flag any of these as violations:
-
-- A built theme imported directly in a page (e.g.
- `import {fooTheme} from '@astryxdesign/theme-foo/built'`). Use `themeObjects`
- from the generated `themeRegistry`.
-- A hand-maintained array of component names. Use `componentRegistry`.
-- A package-name switch like `if (pkg === '@astryxdesign/core')`. Let the
- pipeline classify packages.
-- Any hardcoded package/version/description duplicating what `packageRegistry`,
- `blockRegistry`, `templateRegistry`, `docsRegistry`, or `showcaseRegistry`
- already provides.
-
-## Blog content
-
-Blog posts are human-authored Markdown under `src/content/blog/posts/` — they
-match this file's `applyTo` but are reviewed as prose, not code. See
-[`blog.instructions.md`](./blog.instructions.md) for the review protocol and
-[`src/content/blog/README.md`](../../apps/docsite/src/content/blog/README.md)
-for the frontmatter contract.
-
-## Idiomatic Astryx (nudge, don't block)
-
-The docsite is Astryx's own showcase — it should be built _with_ Astryx, not
-around it. When a change reaches for raw HTML/CSS where an Astryx primitive
-exists, **nudge** toward the idiomatic path (a suggestion, not a hard block —
-the docsite has real app-specific needs the component set won't always cover):
-
-- Compose from Astryx components/primitives over raw elements — `VStack`/
- `HStack`/`Grid`/`Center`/`Card` over `<div>`, `Text`/`Heading` over text tags,
- `Button`/`Link`, `Table`, `List`, `Icon` (never raw `<svg>` as an icon).
-- Style through props + semantic tokens (`xstyle`, `gap`, `padding`, `variant`),
- not custom CSS or raw color/spacing values.
-- If the docsite genuinely needs something the component set lacks, that's a
- signal worth surfacing: note it as a possible gap to file upstream, rather than
- quietly forking a bespoke pattern in page code.
-
-The bar is lighter than for `packages/**` — the docsite ships app code, not
-published components — so frame these as "here's the idiomatic way" nudges, and
-reserve firm flags for raw CSS or hardcoded tokens that have a clear Astryx
-equivalent.
-
-## Mobile-friendliness
-
-Docsite pages must hold up on small screens. Review any layout/structural change
-for how it degrades on mobile, and flag the common failure modes:
-
-- **Side panels / multi-column layouts.** A `start`/`end` `LayoutPanel`, a
- sidebar, or a two-pane split should collapse to an **inline / stacked**
- treatment on small screens (panel becomes a top section, a drawer, or a
- disclosure) — not sit as a squeezed column or push content off-screen. Flag a
- new side panel or column split with no small-screen story.
-- **Min-widths that don't shrink.** A fixed `width`/`minWidth` (or a
- `min-content` grid track) that exceeds a phone viewport causes horizontal
- overflow. Prefer `Grid` with `minChildWidth` (reflows automatically),
- `max-width` over fixed `width`, and `minWidth: 0` on flex/grid children that
- must be allowed to shrink (the classic fix for a child refusing to shrink
- inside a flex row). Flag fixed widths on content that needs to fit narrow
- screens.
-- **Overflow & target sizes.** Wide content (tables, code blocks, long rows)
- should scroll within its container, not blow out the page width. WCAG 2.2
- [criterion 2.5.8](https://www.w3.org/WAI/WCAG22/Understanding/target-size-minimum.html)
- (Level AA) requires targets to be at least 24×24 CSS px, or to satisfy its
- spacing or other exceptions. The 44×44 CSS px threshold belongs to enhanced
- [criterion 2.5.5](https://www.w3.org/WAI/WCAG22/Understanding/target-size-enhanced.html)
- (Level AAA). Do not substitute the AAA threshold when evaluating or reporting
- AA conformance.
-- **Prefer CSS-first responsiveness.** The docsite leans on `useMediaQuery` /
- `isMobile` JS in places; for _layout_ that CSS can express, prefer
- `@container` queries, `Grid` `minChildWidth`, `flex-wrap`, and
- `clamp()`/`min()`/`max()` over JS breakpoint branching (fewer hydration/SSR
- mismatches, no layout flash). JS breakpoints are fine when the change is
- genuinely structural (swapping a panel for a drawer), but flag JS used for what
- a media/container query would handle.
-
-If verifying a responsive claim needs a real viewport (does this actually reflow
-at 375px?), say so and route it to human/preview verification rather than
-asserting it works from the diff.
-
-## Everything else
-
-Docsite-only or CLI-docs-only changes are a light review overall — the
-data-from-pipeline rule is the primary gate, plus the idiomatic-Astryx and
-mobile checks above.
diff --git a/.github/instructions/packages.instructions.md b/.github/instructions/packages.instructions.md
deleted file mode 100644
index 80bb79b69c..0000000000
--- a/.github/instructions/packages.instructions.md
+++ /dev/null
@@ -1,445 +0,0 @@
----
-applyTo: 'packages/**'
----
-
-# Package review instructions
-
-These paths ship as published `@astryxdesign/*` packages, so review them against
-Astryx's API guidance and component review protocol.
-
-**Read first, and don't restate here:**
-
-- [Component Audit Rubric](https://github.com/facebook/astryx/wiki/Component-Audit-Rubric)
- — the bar: every rule as a numbered check with its severity and exceptions,
- the bar per change type, and the trigger table mapping what a diff touches to
- the checks it earns. Cite check ids in findings.
-- [`copilot-instructions.md`](../copilot-instructions.md) — severity, the review
- signal line, summary-vs-inline, the labels, same bar for every author.
-- [CONTRIBUTING → Code Style](../../CONTRIBUTING.md#code-style) — what this repo
- enforces mechanically: TS strict, ref-as-prop, `'use client'`, JSDoc
- `@example` fences.
-
-What follows is what is specific to **published package code** and lives
-nowhere else.
-
-## Step 0 — Triage first: categorize, assess risk, pick a path
-
-Before reviewing in depth, do a fast triage. It decides _how hard_ to look and
-in what order, so effort lands where the risk is — and so the risk checks
-(especially breaking changes) happen **up front**, not as an afterthought.
-
-This is the triage the rubric points at; it is stated here and only here. The
-**bar** each change type has to clear is in
-[the rubric's bar per change type](https://github.com/facebook/astryx/wiki/Component-Audit-Rubric#reviewing-a-change),
-and the **specific checks** a diff earns come from the rubric's trigger table.
-Triage sets depth; those two set content.
-
-**1. Categorize the PR** (by what it changes, not just the title prefix):
-
-| Category | Signals |
-| ----------------------- | ----------------------------------------------------------------------------------------- |
-| **test / docs / chore** | only `*.test.tsx`, `*.doc.mjs`, stories, CI, build config — no shipped runtime/API change |
-| **bug fix** | behavior change to existing code, no new public surface |
-| **new API surface** | new component, new prop/variant, new exported hook/type, changed signature |
-| **refactor / internal** | behavior-preserving restructure, shared-util migration |
-
-**2. Assess risk — the two questions that gate everything:**
-
-- **Is it a breaking change?** Scan for: a removed/renamed public export, prop,
- or variant; a **new required** field on a public type/context/props; a changed
- default; a changed function signature; or changed DOM/class/ARIA output
- consumers may depend on. (The tell for an _accidental_ breaking change:
- unrelated tests/examples/call sites had to be edited — see the silent-breaking
- rule in Judgment.) A real breaking change must be **intentional and signalled
- with a `[breaking]` changeset category**, and for a removed/renamed/changed
- public API in a **published** package, a **codemod** under `astryx upgrade`.
- Flag a breaking change with no `[breaking]` changeset (and no codemod where one
- is warranted) as blocking. **`lab` is exempt**: it is private and never
- published, so it has no consumers to migrate and is allowed to break freely —
- never ask for a codemod for a lab-only change, and promoting a component out of
- lab into core is additive from the published side.
-- **What's the blast radius?** A core primitive many components build on, or a
- shared type/context, is higher-stakes than a leaf component or a docsite tweak.
-
-**3. Pick the review path** (depth follows category × risk):
-
-- **Fast path** — docs/chore, or a small behavior-only bug fix with a
- regression test, no breaking change, low blast radius. Verify accuracy (does
- the referenced API exist / does the fix match the described bug), confirm the
- test/changeset, and approve. Don't manufacture findings on a clean small PR.
- **A standalone test PR is not automatically fast-path** — it still has to clear
- the test-quality bar under "Calibrate to the PR type".
-- **Standard path** — a normal bug fix or a contained prop/behavior change. Run
- the checks the diff triggers, plus Judgment below.
-- **Deep path** — new API surface, a breaking change, a plugin/hook that extends
- a host, or a high-blast-radius core change. Run every automatable check **and**
- route the API-design decision to a human (see "When to flag for engineering /
- human judgment"); note it should be spec'd + vibe-tested. Do not verdict the
- API yourself.
-
-> **Hard stop — new props / API changes from a contributor need human judgment.**
-> If a PR adds a **new prop** or otherwise changes API surface (a new component,
-> variant, exported hook/type, or a changed/removed signature) and the author is
-> in the **contributor bucket** (not in `.github/ENGOWNERS` or
-> `.github/DESIGNOWNERS`), the AI reviewer must **not** approve or merge it —
-> even if it's clean, additive, and passing CI. Flag it as **⚠️ Needs
-> human/maintainer judgment on the API surface** and leave the approve/merge
-> decision to a human. "Additive and non-breaking" is _not_ sufficient to
-> auto-approve API surface — whether the API _should exist_ and take this shape
-> is a human call. Behavior-only fixes, tests, docs, and chores from
-> contributors can still take the fast/standard path.
-
-State the category, the risk, the path, and the checks you ran at the top of the
-review, e.g. `Triage: bug fix · non-breaking · low blast radius → fast path ·
-checks: §1 A4/A5, §7 C1`.
-
-## What counts as high-risk in this scope
-
-The shared review-signal model lives in `copilot-instructions.md`. Within
-`packages/**`, a change is **high-risk** when it involves any of:
-
-- **Public API change** — a new/changed/removed export, prop, variant, hook,
- type, or signature; a changed default; changed DOM/class/ARIA output.
-- **New component or module** — a net-new component directory, especially added
- directly to `core` (skipped `lab`) — see Lifecycle & promotion.
-- **New package** — a net-new `@astryxdesign/*` package. Always human-judgment.
-- **Suspected regression** — an unintended behavior/logic change or a silent
- breaking change to a shared type/context (see Judgment).
-
-Anything else in this scope is low-risk for signal purposes. The one explicitly
-low-risk _area_ inside `packages/**` is **`packages/themes/**`** (theme values);
-a theme-only change does not trip the high-risk gate — though still apply the
-design blast-radius check in Judgment, since a token change can regress
-everywhere it composites.
-
-## Calibrate to the PR type
-
-Once triaged, weight the review by what the PR is trying to do. The evidence
-each type owes is in
-[the rubric's bar per change type](https://github.com/facebook/astryx/wiki/Component-Audit-Rubric#reviewing-a-change);
-these are the package-specific reading notes on top of it.
-
-- **Bug fixes** — the red→green evidence belongs **in the PR description**. Flag
- a bug-fix PR that changes behavior without it and ask; a fix with no
- regression test can silently break again.
-- **Tests** — a test PR must earn its merge by testing the **contract, not the
- implementation**. A passing test that exists is necessary but _not_ sufficient
- to approve. The one-line test: _does this protect a promise a consumer relies
- on, or does it just mirror the code?_ If it would break on a harmless refactor
- yet survive a real bug, it's slop — request changes (kindly), naming the
- specific assertions to cut or refocus.
- - **✅ Worth testing** — the public behavioral contract (state transitions,
- controlled/uncontrolled, callbacks fire with the right args, documented edge
- cases: empty / boundary / overflow); each meaningful branch of a pure
- function; the accessibility contract (roles, ARIA wiring, keyboard
- interaction — first-class for a design system); and regression tests pinned
- to a real reported bug (red → green).
- - **🚫 Test slop — don't merge as-is** — asserting internal state, private
- helpers, or DOM/class structure that isn't a public contract
- (change-detector tests); snapshot dumps with no behavioral assertion;
- re-testing React or the library ("useState updates", "prop passed through"
- with no logic between); trivial padding ("renders without crashing" as the
- _only_ assertion, or `it.each` explosions with no distinct risk per case);
- and computed style/token/pixel assertions (that's brittle design territory).
-- **Docs** — validate against reality: does the documentation match the
- code/API/behavior **on this branch**? When a claim is a matter of best practice
- or judgment rather than fact, call it out for a maintainer rather than
- asserting it's right or wrong.
-- **New features / new components** — whether this is the _right way to expose
- the functionality_ is a human judgment call. **Do not render a verdict on the
- API design.** Run the mechanical, convention, and convergence checks, then
- explicitly flag that maintainers should review the API surface (and that new
- surface should be spec'd and vibe-tested).
-
-## When to flag for engineering / human judgment
-
-Many Astryx contributions come from designers building with an AI assistant.
-The assistant is good at composition and convention, but some changes cross into
-territory where **engineering review and human judgment are required** — and the
-review should **say so explicitly** rather than quietly approving. If you find
-yourself uncertain, that uncertainty is itself the signal: name it.
-
-Add an explicit **"⚠️ Needs engineering / human judgment"** note when the change
-involves any of:
-
-- **New public API surface or an API-shape decision** — a new component, a new
- prop/variant, or changing an existing prop's contract.
-- **New runtime complexity** — effects, refs, observers
- (`MutationObserver`/`ResizeObserver`/`IntersectionObserver`), imperative DOM
- work, event listeners, timers, async coordination, or anything touching a hot
- path. Designers should not land this class of change without an engineer
- confirming it's the right mechanism.
-- **Accessibility semantics** — ARIA roles/states, focus management, keyboard
- interaction, live regions/announcements. Getting these subtly wrong is worse
- than omitting them.
-- **State, data flow, or lifecycle** — anything beyond presentational styling:
- controlled/uncontrolled state, deriving state, memoization, render behavior.
-- **Escape hatches / breaking the system** — raw CSS, non-token values,
- `swizzle`d source, or overriding a system default; these need a documented
- rationale an engineer signs off on.
-- **Anything the change _asserts_ works but can't be verified from the diff** —
- performance claims, cross-browser/RTL/theme behavior, SSR/hydration.
-
-Pure presentational work well within the system — composing existing components,
-using tokens and documented props, adding a story or realistic mock data — does
-**not** need this flag. Reserve it for the cases above so it stays meaningful.
-
-When you raise it, be specific: name _what_ in the diff needs the deeper look and
-_why_ (e.g. "the `ResizeObserver` in `X.tsx` is a runtime-complexity + perf
-decision — an engineer should confirm a container query wouldn't do"), so the
-designer knows exactly what to hand off.
-
-## API guidance
-
-The rules themselves are on the wiki — apply them and cite the specific rule
-when something conflicts:
-
-- **[API Conventions](https://github.com/facebook/astryx/wiki/API-Conventions)** —
- naming (`<Namespace><Variant><Type><Postfixes>`, unprefixed: `Button`, not
- `AstryxButton`), the prop-surface contract, and the principles a review leans
- on most: guidance over enforcement, prop independence, orthogonal axes,
- composition over config for high-level components, and matching existing
- siblings.
-- **[Component Specification Protocol](https://github.com/facebook/astryx/wiki/Component-Specification-Protocol)** —
- the evidence-backed 9-phase process new components must follow.
-- **[API Arbitration](https://github.com/facebook/astryx/wiki/API-Arbitration)** —
- where naming and shape disputes get resolved instead of in the PR.
-
-### Adding a new prop — converge, don't diverge
-
-When a diff **adds a new prop** (or a new variant/enum value), don't evaluate it
-in isolation. Check whether other components already express the same
-capability, and push to converge:
-
-- **Search for prior art.** Look for an existing prop with the same _axis of
- variation_ under a different name (`size` vs `scale`, `isLoading` vs `busy`,
- `tone` vs `variant` vs `color`, `density` vs `compact`). Check sibling
- components in the same family first, then the wider system.
-- **Prefer the established name and value shape** — reuse the existing prop
- name, type, default, and vocabulary. Flag a new prop that reinvents an
- existing one under a different name or value shape.
-- **Flag near-duplicates that should unify.** If the new prop and an existing one
- are ~80% the same intent, the right outcome is often one shared prop across
- both, not two subtly-different ones.
-- **When no prior art exists,** it is genuinely new API surface — hold it to the
- API Conventions principles, and note that it should be spec'd and vibe-tested
- rather than settled in the PR.
-
-### Plugins & hooks that extend a host component
-
-Some components expose a plugin/hook surface (e.g. `Table` with `useTable*`
-plugins). These extend a host, so review them for consistency _with that host_,
-not in isolation — recurring issues seen in real review:
-
-- **Mirror the host's API shape, in and out.** A plugin should accept and return
- the same shapes the host already uses. If `Table` accepts `idKey` (a key that
- may be a string _or_ a getter, so callers avoid writing callbacks), a plugin
- should accept the same rather than forcing a bespoke callback — and should
- **name its outputs to match the host's props** so they compose directly.
- Prefer `const {idKey} = usePlugin(); <Table idKey={idKey} />` over exporting
- `getRowKey` that the caller has to remember maps to `idKey`. Flag renamed or
- reshaped equivalents.
-- **Semantic values first, arbitrary as the escape hatch.** When a plugin/prop
- takes a visual value (color, status, tone), the first-class API is the
- system's **semantic tokens** (`color: 'accent'` / `'success'`), not raw values.
- Arbitrary values are fine as an escape hatch, but flag an API where the
- raw/arbitrary form is the primary one.
-- **Decide host-level vs plugin-level deliberately** — especially for
- accessibility. If an option affects host semantics (e.g. a row `startFrom`
- index that changes `aria-rowindex`), it likely belongs on the **host** so the
- semantics are correct even when nothing visible renders.
-
-### Hook stability & reuse of existing data
-
-For hooks (plugins or otherwise), watch two things that bit real Table PRs:
-
-- **Dependency-set stability.** A hook whose memoized output depends on a
- frequently-changing value (e.g. the whole `data` array) will re-compute and
- hand consumers a new reference on every update, destabilizing everything
- downstream. Flag dependency sets that make the return value churn.
-- **Don't re-derive what's already available.** If the host or the DOM already
- exposes a value, read it instead of recomputing. Real case: a row-index plugin
- looped over `data` to compute indices the table row already carried as
- `aria-rowindex` — the loop (and the extra API surface) was avoidable.
-
-## Design review
-
-Some package changes are also _design_ changes. The design rules are
-**[Design Conventions](https://github.com/facebook/astryx/wiki/Design-Conventions)**
-— spacing and the 4px grid, concentric radius, vertical rhythm, elevation,
-typography, color and contrast, motion, and the approved state
-representations. Apply that page; don't re-derive it here.
-
-**When it applies.** Treat a change as design-affecting when it touches any of:
-`.stylex.ts` files or `stylex.*` styling; token usage (color, spacing, radius,
-shadow, typography, motion, elevation/z-index); a new component, variant, or
-`size`/`density` prop; visual state handling (rest/hover/focus/active/disabled/
-loading, selected, or `status`); layout/structure, borders, or overlays/popovers.
-Pure logic, types, tests, or docs with no visual effect do **not** need a design
-pass — say so and move on.
-
-**How to run it.** Score the objectively-checkable items (tokens, grid,
-concentric radius, contrast, z-index, motion properties) as pass/fail; treat
-proportions, density, and composition as judgment, and judge those from
-**rendered screenshots**, not from reading CSS. This mirrors Hardening Layer 3 —
-where a review resolves a genuinely new design question, note that it should be
-recorded back into the Design Conventions page rather than decided ad hoc in the
-PR.
-
-## Lifecycle & promotion
-
-Astryx components and templates move through a staging lifecycle
-([Component Lifecycle](https://github.com/facebook/astryx/wiki/Component-Lifecycle),
-[Component Hardening Protocol](https://github.com/facebook/astryx/wiki/Component-Hardening-Protocol)).
-The thing to catch is **new work that skips staging** — landing directly in its
-final, publicly-visible home without being hardened first. Flag these as
-high-attention (post a note rather than hard-blocking — this is advisory).
-
-### New component added directly to `core` (skipped `lab`)
-
-`@astryxdesign/lab` is the canary-only staging area (`private: true` +
-`astryx.canaryOnly`) where new components develop and harden;
-`@astryxdesign/core` ships to stable consumers. The expected path is
-**lab → core after hardening**.
-
-**Flag a diff that adds a brand-new component directory under
-`packages/core/src/<Name>/` with no prior presence in `packages/lab/src/`.** A
-lab→core _promotion_ — a delete under `packages/lab/src/**` paired with the add
-in core — is the healthy path; the concern is the _net-new_ component that was
-never in lab. Ask the author to confirm it went through lab, or that it meets
-the core bar lab does not guarantee (full keyboard + a11y, a theming story with
-`themeProps`, spec compliance, a complete surface).
-
-**Require a linked spec issue.** A new component's PR description must link to a
-tracking issue that clearly ran the
-[Component Specification Protocol](https://github.com/facebook/astryx/wiki/Component-Specification-Protocol).
-Flag a new-component PR with **no linked spec issue**, or one linking a bare
-"add X" feature request with none of the protocol's evidence, and ask for the
-spec before the API is reviewed on its merits. The spec is the contract.
-
-Small additions and deliberately spec-approved direct-to-core work do happen —
-this isn't an automatic rejection — but call it out so a human confirms it was
-intentional.
-
-### New package (net-new `@astryxdesign/*`)
-
-A brand-new package is a bigger commitment than a new component — a published
-surface the project maintains and versions indefinitely. **Flag a diff that adds
-a new top-level `packages/<name>/` directory.** Always route to human/maintainer
-judgment regardless of author, and confirm:
-
-- **The package should exist as its own package** (vs. living in an existing
- one) — a deliberate, maintainer-level decision.
-- **Publish posture is intentional** — `private: true` + `astryx.canaryOnly` for
- staging vs. a stable public package; `"exports"` generated by
- `scripts/sync-exports.js`, not hand-written; versioning joins the `fixed`
- group.
-- **A tracking/spec issue is linked** establishing the need and scope.
-
-Never approve a net-new package on convention-cleanliness alone.
-
-### New template added already-visible (not `hidden`)
-
-CLI templates/blocks are authored **hidden** and revealed only after they clear
-the template design bar — see
-[`templates.instructions.md`](./templates.instructions.md) for the full rule.
-Flag a diff that adds a _new_ template/block whose `.doc.mjs` is not
-`hidden: true`.
-
-## Mechanical checklist
-
-The design-system rules (StyleX-only, semantic tokens, no style-only wrappers,
-the shared a11y primitives, `useLinkComponent()`) are numbered checks on the
-[Component Audit Rubric](https://github.com/facebook/astryx/wiki/Component-Audit-Rubric);
-what this repo enforces mechanically is in
-[CONTRIBUTING → Code Style](../../CONTRIBUTING.md#code-style). What is specific
-to a published package:
-
-- **Full component surface.** A component under `packages/*/src/<Name>/` should
- ship `<Name>.tsx`, a colocated `<Name>.test.tsx`, `<Name>.doc.mjs`, and an
- `index.ts` export, plus a Storybook story at
- `apps/storybook/stories/<Name>.stories.tsx` (stories are not colocated —
- `apps/storybook/.storybook/main.ts` only discovers
- `../stories/**/*.stories.@(js|jsx|mjs|ts|tsx)`). Flag missing pieces.
-- **`export interface <Name>Props`** extending `BaseProps`, with types exported
- alongside the component.
-- **Never hand-edit the `"exports"` field in a package `package.json`.** It is
- auto-generated from `src/` by `scripts/sync-exports.js` and committed on
- `main`. Editing it by hand is a review-reject.
-- **Docs in sync** — JSDoc file headers, `SYNC:` reminders, and `.doc.mjs`.
- `@example` fences in JSDoc must be plain ` ``` ` (never language-tagged), or
- Storybook autodocs won't render them.
-
-## Judgment
-
-Conventions passing is necessary, not sufficient. Weigh the **end-user
-experience** of the change, not just whether it compiles and follows the rules.
-When something would degrade real usage even though it passes the mechanical
-checks, flag it.
-
-- **Accessibility & alerting.** Scrutinize anything that announces, focuses, or
- interrupts — live regions (`role="alert"`/`aria-live`), toasts, focus moves,
- and notification triggers. Look for ways the mechanism could:
- - **Double-fire** — re-run on re-render, fire once per item in a loop, or
- re-announce unchanged content (a common `useEffect`-without-correct-deps
- bug). Assistive tech will read it twice.
- - **Interrupt or bury** — steal focus mid-interaction, stack overlapping
- announcements, or clobber a more important message. `assertive` regions
- especially should be rare and deliberate.
- - **Worsen the experience it's trying to help** — e.g. announcing on every
- keystroke, or moving focus in a way that traps or disorients.
- Prefer announcing on a real state transition, debouncing/coalescing where the
- content is noisy, and reserving `assertive` for genuinely urgent messages.
-- **`useEffect` is a smell.** Treat a new/changed Effect as something to justify,
- not accept by default. Most UI logic doesn't need one — look for whether it
- belongs in an **event handler / callback**, a **ref**, or plain **derivation
- during render / `useMemo`**. Use React's own guidance as the bar:
- [You Might Not Need an Effect](https://react.dev/learn/you-might-not-need-an-effect)
- and [Synchronizing with Effects](https://react.dev/learn/synchronizing-with-effects).
- Genuine Effects synchronize with an _external_ system (subscriptions, the DOM,
- network, non-React widgets) — those are fine; call out the ones that don't.
-- **Overly complex behavior for a simple need.** Flag heavy runtime machinery
- added where a simpler, declarative solution exists — the classic being a
- `MutationObserver` / `ResizeObserver` / `IntersectionObserver`, imperative DOM
- measurement, event listeners, or a `useEffect` sync loop introduced to achieve
- something CSS (or a token/prop) already does. Watch for observers or
- measurement in hot paths (per-row, per-keystroke, per-frame, large lists), and
- for reintroducing work the platform handles natively
- (`:hover`/`@media (hover: hover)`, `@container`, `:nth-child`,
- `@starting-style`, `position-try`, `stylex.when.*`).
-- **Silent breaking changes to shared types/context.** Adding a **required**
- field to a shared type, context value, or component API is a breaking change
- for every existing consumer — even when the PR's own feature doesn't need them
- to change. The **tell**: unrelated tests, examples, or call sites had to be
- updated just to satisfy the new field. Flag it and ask whether the field should
- be **optional** (applied internally with a default) instead. (Real case: a new
- required `aria-controls` id on a mobile-nav context forced edits to surfaces
- that didn't otherwise need it.)
-- **Unintended behavior/logic change.** Compare what the diff _actually changes_
- against what the PR says it does. Flag behavior the author likely didn't mean
- to touch — a value, default, condition, or output that changed as a side effect
- of the intended edit and that the description never mentions. This is different
- from scope contamination (unrelated _files_ bundled in); here the collateral
- change is _inside_ the area the author was working on, so it's easy to miss.
- Watch especially for:
- - **Design/token changes — judge by presentation impact, not the token type.**
- Reason about **how it renders and where that could break**: does it alter
- contrast, legibility, or emphasis? Does it change how a value _composites_
- over other surfaces or in a different theme/mode? Does it shift layout,
- spacing rhythm, or elevation order? Does it hold in both light and dark, and
- against every surface the token appears on? The canonical trap: a color that
- reads fine in isolation but was relied on to layer over other content, so the
- change silently degrades every place it composites. (One real instance: a
- theme edit that made a color opaque when other UI depended on it being
- translucent — fine where the author looked, broken where they didn't.)
- - **Changed defaults / conditionals** — a default prop value, a comparison
- (`>=` vs `>`), an early-return, or a guard that changed as a byproduct.
- - **Generated-output drift** — a regenerated theme CSS / registry / token file
- whose diff contains changes beyond the intended one.
- Surface these as a question — "this also changes X (was `a`, now `b`) — does
- that hold everywhere it's used?" — so the author can confirm or revert.
-- **Other smells.** State expressed by unmounting focusable elements (toggle
- visibility so focus/a11y survive), unnecessary `useState` (prefer derived
- values or refs, especially from interaction handlers), and excessive comments.
-
-Behavioral or agent-facing changes should come with vibe-test evidence.
diff --git a/.github/instructions/templates.instructions.md b/.github/instructions/templates.instructions.md
deleted file mode 100644
index 025b8ad782..0000000000
--- a/.github/instructions/templates.instructions.md
+++ /dev/null
@@ -1,92 +0,0 @@
----
-applyTo: 'packages/cli/assets/templates/**'
----
-
-# Template review instructions
-
-These are Astryx **templates** — page templates
-(`templates/pages/<name>/page.tsx` + `template.doc.mjs`) and block templates
-(`templates/blocks/.../[Name].tsx` + `[Name].doc.mjs`). They are copy-paste
-examples, so they carry design responsibility beyond any single component.
-
-> **Scope note.** These files also match `packages.instructions.md`. For
-> template files, the component-authoring checklist there (the `ref` prop,
-> sync-exports, colocated `.test.tsx`, etc.) does **not** apply — templates are
-> examples, not published components. Review them by the rubric below, plus the
-> shared design and StyleX rules on the
-> [Component Audit Rubric](https://github.com/facebook/astryx/wiki/Component-Audit-Rubric).
-
-## The grading rubric
-
-Grade every changed template against the
-**[Template Grading Rubric](https://github.com/facebook/astryx/wiki/Contributing-Templates#template-grading-rubric)**,
-which carries the full criteria, the per-condition point tables, and the output
-format. **Every template in the gallery should score B (75) or above.** Flag
-anything that would land below B; post findings as a scorecard (advisory —
-comment, don't hard-block).
-
-The seven categories and their weights, as an index of what you are scoring:
-component purity (30) · icon purity (15) · custom CSS (15) · layout & structure
-(15) · doc metadata (10) · image handling (5) · code quality (10).
-
-Two of those have repo-specific detail the wiki page does not carry — apply
-these:
-
-- **Layout & structure.** Page templates root in `Layout` or `Center`, never
- `AppShell` or a raw `<div>` — **exception:** `Shell -` category templates must
- root in `AppShell` with global `TopNav`/`SideNav`. No global app chrome
- otherwise (in-page nav → `LayoutPanel` start slot; page header →
- `LayoutHeader`). Navigation links are inert (`href="#"` / `onClick`) since a
- template is a single page. Block templates are not wrapped in `AppShell`,
- keep a single-pattern focus, and run ~20–100 lines.
-- **Image handling.** Demo imagery is referenced by a **root-relative path under
- `/template-assets/<asset>.png`**, self-hosted in this repo under
- `apps/docsite/public/template-assets/` and mirrored into the sandbox preview
- at generate time. To use an existing image, browse that directory and
- reference it by name with an asset-name comment; to add one, drop the file in
- the same directory and reference it the same way. On scaffold,
- `stripTemplateAssetRefs` swaps these paths for an inline placeholder so a
- generated project renders with zero setup. Flag external URLs
- (unsplash/placehold/picsum), expiring signed CDN URLs, and inline data URIs.
- Image-backed `Thumbnail` examples are the one exception: they inline a
- same-origin, samplable `data:` URI, required by `useImageMode` — see
- `scripts/check-demo-media.mjs`.
-
-## Step 0 — Triage first
-
-Quick triage before grading. Two questions:
-
-- **New template vs. edit to an existing one?** A _new_ template that lands
- already-visible (its `.doc.mjs` isn't `hidden: true`) skipped hidden-staging —
- flag it (see Lifecycle note) and hold it to the full B+ bar. An edit to an
- existing template is scoped to what changed.
-- **Content-only vs. structural?** A copy/mock-data tweak is a fast grade
- (purity + metadata); a layout/root/`AppShell` change needs the full Layout &
- Structure pass.
-
-State it briefly, e.g. `Triage: edit to existing template, layout change → full
-structure pass`.
-
-## Reporting
-
-When a template diff is substantial (a new template, or a material change), post
-the rubric's scorecard: per-category points, a letter grade, the specific
-findings (raw HTML lines, raw SVG lines, custom-CSS declarations,
-layout/doc/image/quality issues), and the **top 3 fixes**. For small tweaks,
-just flag any category that now dips below B rather than re-grading the whole
-file.
-
-Templates are also judged on the shared design axes — see the Design review
-section of [`packages.instructions.md`](./packages.instructions.md), which
-points at [Design Conventions](https://github.com/facebook/astryx/wiki/Design-Conventions).
-
-## Lifecycle note
-
-Templates are authored **hidden** and revealed only after they clear this bar.
-The CLI reads `hidden: true` and `hiddenComponents: ['Name', ...]` from a
-template's `.doc.mjs`; hidden entries are skipped from `--list`. The thing to
-catch is a template that **skips hidden-staging**: **flag a diff that adds a
-_new_ template/block whose `.doc.mjs` is not `hidden: true`** — it's publicly
-listed the moment it lands and may not be hardened yet. Ask the author to
-confirm it grades **B or above**, or to add `hidden: true` until it does. See
-[Component Lifecycle](https://github.com/facebook/astryx/wiki/Component-Lifecycle#promotion-gates).
diff --git a/.github/workflows/review-signal.yml b/.github/workflows/review-signal.yml
index 3950a3fa7a..af5d4d4b56 100644
--- a/.github/workflows/review-signal.yml
+++ b/.github/workflows/review-signal.yml
@@ -30,9 +30,7 @@
# design label is advisory and does not). Both are cleared when an entitled
# owner approves (code → CODEOWNER; design → DESIGNOWNER
# or CODEOWNER). Code detection is path-based and deterministic; design adds a
-# content-based diff score (deterministic too — same diff, same score). The
-# Copilot reviewer reads these labels to focus its review (see
-# .github/copilot-instructions.md).
+# content-based diff score (deterministic too — same diff, same score).
#
# HARD GATE (code review only): this emits a "review-required" COMMIT STATUS.
# When code review is needed it's set to `pending`, which blocks a required
@@ -492,9 +490,9 @@ jobs:
}
}
- // No explanatory comment is posted here on purpose. The label is the
- // mechanical signal; the Copilot reviewer reads it and explains why
- // review is needed with actual judgment — better than a static one.
+ // No explanatory comment is posted here on purpose. The label and
+ // status are the mechanical signals; reviews provide judgment
+ // separately rather than through a static workflow comment.
// --- The blocking gate: a "review-required" COMMIT STATUS. ---
// We use a commit STATUS (not a check run) for two reasons:
diff --git a/AGENTS.md b/AGENTS.md
index 967974f1cb..193ee5970a 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -4,6 +4,13 @@ Astryx is a public design-system repository. Never commit internal links,
identifiers, service names, private operational instructions, or other
Meta-only context.
+## Instruction surface
+
+This `AGENTS.md` is the canonical, tool-agnostic instruction surface for the
+repository. Add or change shared agent guidance here rather than duplicating it
+in tool-specific instruction files. Put genuinely path-specific guidance in a
+nested `AGENTS.md`.
+
## Start here
- Product builders: use `astryx docs`, component `{Name}.doc.mjs` files, and
diff --git a/apps/docsite/src/content/blog/README.md b/apps/docsite/src/content/blog/README.md
index 8c013aaaba..6afdf292af 100644
--- a/apps/docsite/src/content/blog/README.md
+++ b/apps/docsite/src/content/blog/README.md
@@ -190,7 +190,5 @@ It's type-aware (a changelog `update`, an `engineering` deep-dive, and a
`perspective` essay are judged by different profiles), gates on accuracy
(verifiable claims — commands, APIs, numbers — are checked against the codebase,
and a confirmed error blocks publish), and checks substance, efficiency, craft,
-and voice **without homogenizing your voice**. The same rubric powers the Copilot
-reviewer at `.github/instructions/blog.instructions.md`, so a blog-post PR gets
-the check automatically. Reading it before you write is the fastest way to land
-an A.
+and voice **without homogenizing your voice**. Reading it before you write is
+the fastest way to land an A.