Shared, tool-neutral knowledge for agents working in this repository. The root AGENTS.md and scoped AGENTS.md files route here, and skills in .github/skills own task workflows. Read only the documents a task needs; links are navigation, not instructions to load everything they reach.

• Put guidance here when more than one skill, reviewer, scoped AGENTS.md, or evaluation uses it, or when it is general repository knowledge. Keep guidance in a skill when only that workflow uses it.
• Keep product contracts (SPEC.md, spec/, CONTRACT.md), protocols, token maps, and package documentation with their packages, and link to them. Packages listed in the guided package registry own their guidance in their AGENTS.md and references/; for example, design tokens and theming live in the design package references, and agentic component recipes and contract source adapters live in the components package references.
• Follow the package-owned guidance standard when adding or extending a governed package's agent entry point, user README, package references, or skill routing.
• Place a new document in the narrowest existing area. Create a new area only for a distinct domain, and add it to the taxonomy table. Add every new document to the document index with a concrete "Read when" condition.
• When moving a document, keep its id and update every inbound link in the same change. Leave a compatibility-reference at the old path only when known external links depend on it, and link it directly to the new location.

Every Markdown file in this directory, and every Markdown file under a skill's references/ directory, starts with exactly these keys in this order:

---
id: components.v1
kind: instruction-reference
owner_paths:
  - packages/framework/framework
---

• id: lowercase, dot-separated segments of letters, digits, and hyphens. IDs are unique and permanent, including across moves.
• kind: index for directory indexes, instruction-reference for guidance agents follow, evidence-reference for version-bound observations, or compatibility-reference for a redirect left at a retired path.
• owner_paths: one or more existing repository paths whose maintainers own the technical content.

Do not add other keys. Load conditions belong in this index and in routers, not in frontmatter.

• R-<AREA>-<NNN> identifies a consequential, testable obligation, such as R-V1-003. Define it once, in an instruction file, as a list item that begins with the bold ID and a colon. Elsewhere, cite the ID.
• C-<AREA>-<NNN> identifies a version-bound observation. Its definition states the source, inspected version or revision, and date.
• Assign IDs only where an implementation, review, or evaluation needs to cite the obligation. Never renumber or reuse an ID; retire it by removing its definition and every citation.
• These IDs cannot collide with component requirement IDs such as BTN-006, which belong to component contracts.

• State a prerequisite explicitly: "Read common focus authoring first", a sentence such as "Focus work starts with" followed by the linked document, or a Read first section. Prerequisites must not form cycles, and a chain may be at most three reads deep.
• Compatibility references are terminal. Link to the replacement document, never to a compatibility path.
• Routing tables, meaning tables with a Skill or Workflow column, route each task to exactly one skill. A task routed in more than one table must route to the same skill everywhere. Overlays belong in the workflow, not the routing table.
• Route every project skill from the root AGENTS.md routing table.

yarn check-agent-instructions validates frontmatter, links and fragments in instruction files, inbound fragments to instruction files, skill metadata, rule definitions and citations, this index, the routing conventions above, and the evaluation fixtures. It also runs in yarn lage buildci.