docs: update the documentation for agents and move relevant code docs into a per-package docs folder (#7503)

# Pull Request

## 📖 Description

This change updates agent skills for Rust and Documentation and moves the architectural docs for `@microsoft/fast-element` into a `docs/` folder.

## ✅ Checklist

### General

- [ ] I have included a change request file using `$ npm run change`
- [ ] I have added tests for my changes.
- [ ] I have tested my changes.
- [x] I have updated the project documentation to reflect my changes.
- [x] I have read the [CONTRIBUTING](https://github.com/microsoft/fast/blob/main/CONTRIBUTING.md) documentation and followed the [standards](https://github.com/microsoft/fast/blob/main/CODE_OF_CONDUCT.md#our-standards) for this project.

Author: janechu

.github/copilot-instructions.md

@@ -42,11 +42,13 @@ Each package includes a DESIGN.md file, read that to gain a general understandin
 These contain domain-specific guidance. Read when performing related tasks:
 
 - [TypeScript](./skills/typescript/SKILL.md) — compiler constraints, import/export conventions, decorator usage, testing patterns.
+- [Rust](./skills/rust/SKILL.md) — general guidance on performing updates between the crate and package.
 - [Shipping](./skills/shipping/SKILL.md) — pull request format, change file generation, documentation updates.
 - [Pull Request](./skills/fast-pull-request/SKILL.md) — generate a pull request description from the branch diff.
 - [Bug Report](./skills/fast-bug-report/SKILL.md) — generate a bug report issue from conversation context.
 - [Feature Request](./skills/fast-feature-request/SKILL.md) — generate a feature request issue from conversation context.
 - [Testing](./skills/testing/SKILL.md) — running tests locally and in CI, writing Playwright fixture tests.
+- [Documentation](./skills/documentation/SKILL.md) — adding documentation in code, markdown files in each package/crate, and the website.
 
 ## Commands
 

.github/skills/documentation/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: documentation
+description: Add documentation for contributors and developers.
+---
+
+Documentation exists in 3 forms, code comments, design/architectural documentation that is made up of markdown files describing code flow and core concepts (such as DESIGN.md), and the documentation website.
+
+Design/architectural documentation such as DESIGN.md should always be kept up-to-date.
+
+The website captures the documentation primarily for the `@microsoft/fast-element` package. Other packages are treated as tangential, so testing packages or other utilities should have their own sections.
+
+The website has been written in 11ty and primarily consists of markdown files. When making changes, ensure that the website has been scanned on whichever latest major version is available. These are organized by folder, so if 1.x/2.x/3.x folders are available, you will update the documentation in the 3.x folder.
+
+If you are making a breaking change, ensure the migration document has been updated.
+
+All markdown documentation aside from the package/crate level DESIGN.md files are in that package/crates docs folder.
+
+Any documentation created for the website should be written with the developer implementing the package in mind, it is not intended for other audiences.

.github/skills/rust/SKILL.md

@@ -0,0 +1,12 @@
+---
+description: Use this guide when working on Rust changes in the FAST monorepo.
+name: rust
+---
+
+# Working with the Rust crate and the Rust NodeJS CLI
+
+The primary location for the Rust logic should exist within a crate. If the logic is made accessible in the NodeJS environment via wrapping the crate and using a wasm bindgen, as much as possible any logic that exists in Rust should not be duplicated in JavaScript/TypeScript.
+
+## Breaking changes
+
+Understand [semver](https://semver.org/) and check the crate and package version. If the version is currently in a prerelease state, update the APIs with breaking changes as necessary and ensure that any generated pull request descriptions capture this.

change/@microsoft-fast-element-158aeac2-32cf-4dfb-9166-0cf6ab1fb196.json

@@ -0,0 +1,7 @@
+{
+  "type": "none",
+  "comment": "docs: update the documentation for agents and move relevant code docs into a per-package docs folder",
+  "packageName": "@microsoft/fast-element",
+  "email": "7559015+janechu@users.noreply.github.com",
+  "dependentChangeType": "none"
+}

packages/fast-element/ARCHITECTURE_INTRO.md

@@ -172,7 +172,7 @@ When the tag function is called it invokes `ViewTemplate.create(strings, values)
 
 No DOM nodes are created at this point; compilation is deferred.
 
-See [ARCHITECTURE_HTML_TAGGED_TEMPLATE_LITERAL.md](./ARCHITECTURE_HTML_TAGGED_TEMPLATE_LITERAL.md) for more detail on directives and the `Markup`/`Parser` helpers.
+See [docs/architecture/html-tagged-template-literal.md](./docs/architecture/html-tagged-template-literal.md) for more detail on directives and the `Markup`/`Parser` helpers.
 
 ---
 
@@ -217,7 +217,7 @@ See [ARCHITECTURE_HTML_TAGGED_TEMPLATE_LITERAL.md](./ARCHITECTURE_HTML_TAGGED_TE
 
 `ViewBehaviorFactory` (created at template-authoring time) is the blueprint; `ViewBehavior` (created per `HTMLView` instance) is the live runtime object.
 
-See [src/templating/TEMPLATE-BINDINGS.md](./src/templating/TEMPLATE-BINDINGS.md) for the full binding pipeline including `DOMAspect` routing and two-way binding.
+See [docs/template-bindings.md](./docs/template-bindings.md) for the full binding pipeline including `DOMAspect` routing and two-way binding.
 
 ---
 
@@ -238,7 +238,7 @@ In async mode, the first `enqueue` call schedules a `requestAnimationFrame` call
 
 Observable setters and `attributeChangedCallback` enqueue their DOM mutations through `Updates`, ensuring that multiple synchronous property changes result in only one DOM update per frame.
 
-See [ARCHITECTURE_UPDATES.md](./ARCHITECTURE_UPDATES.md) for more detail.
+See [docs/architecture/updates.md](./docs/architecture/updates.md) for more detail.
 
 ---
 
@@ -472,8 +472,7 @@ src/
 │   ├── ref.ts             # ref directive
 │   ├── render.ts          # render directive
 │   ├── children.ts        # children directive
-│   ├── slotted.ts         # slotted directive
-│   └── TEMPLATE-BINDINGS.md
+│   └── slotted.ts         # slotted directive
 ├── styles/
 │   ├── css.ts             # css tag
 │   ├── element-styles.ts  # ElementStyles
@@ -501,12 +500,12 @@ src/
 
 | Document | What it covers |
 |---|---|
-| [ARCHITECTURE_INTRO.md](./ARCHITECTURE_INTRO.md) | Glossary / index for all architecture docs |
-| [ARCHITECTURE_OVERVIEW.md](./ARCHITECTURE_OVERVIEW.md) | General FAST usage, compose/define flow, module load sequence |
-| [ARCHITECTURE_FASTELEMENT.md](./ARCHITECTURE_FASTELEMENT.md) | FASTElement & ElementController lifecycle in detail |
-| [ARCHITECTURE_HTML_TAGGED_TEMPLATE_LITERAL.md](./ARCHITECTURE_HTML_TAGGED_TEMPLATE_LITERAL.md) | `html` tag, directives, binding pre-processing |
-| [ARCHITECTURE_UPDATES.md](./ARCHITECTURE_UPDATES.md) | Updates queue, attribute and observable change batching |
-| [src/templating/TEMPLATE-BINDINGS.md](./src/templating/TEMPLATE-BINDINGS.md) | Full template binding pipeline: authoring → compilation → binding → DOM updates |
+| [docs/architecture/intro.md](./docs/architecture/intro.md) | Glossary / index for all architecture docs |
+| [docs/architecture/overview.md](./docs/architecture/overview.md) | General FAST usage, compose/define flow, module load sequence |
+| [docs/architecture/fastelement.md](./docs/architecture/fastelement.md) | FASTElement & ElementController lifecycle in detail |
+| [docs/architecture/html-tagged-template-literal.md](./docs/architecture/html-tagged-template-literal.md) | `html` tag, directives, binding pre-processing |
+| [docs/architecture/updates.md](./docs/architecture/updates.md) | Updates queue, attribute and observable change batching |
+| [docs/template-bindings.md](./docs/template-bindings.md) | Full template binding pipeline: authoring → compilation → binding → DOM updates |
 | [docs/fast-element-2-changes.md](./docs/fast-element-2-changes.md) | Breaking changes from v1 to v2 |
 
 ---

packages/fast-element/DESIGN.md

@@ -1,6 +1,6 @@
 # FASTElement
 
-The `FASTElement` is our extension of the `HTMLElement`. As such it leverages the lifecycles but also requires additional setup before before the class `constructor` or the `connectedCallback` method is executed which are explained in the [overview](./ARCHITECTURE_OVERVIEW.md). This document explains specifically what `FASTElement` leverages inside the `HTMLElement`s lifecycle hooks.
+The `FASTElement` is our extension of the `HTMLElement`. As such it leverages the lifecycles but also requires additional setup before before the class `constructor` or the `connectedCallback` method is executed which are explained in the [overview](./overview.md). This document explains specifically what `FASTElement` leverages inside the `HTMLElement`s lifecycle hooks.
 
 For an explanation into `HTMLElement` lifecycle hooks refer to the [MDN documentation](https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_custom_elements#custom_element_lifecycle_callbacks).
 

…fast-element/ARCHITECTURE_FASTELEMENT.md …element/docs/architecture/fastelement.mdpackages/fast-element/ARCHITECTURE_FASTELEMENT.md renamed to packages/fast-element/docs/architecture/fastelement.md packages/fast-element/ARCHITECTURE_FASTELEMENT.md renamed to packages/fast-element/docs/architecture/fastelement.md

@@ -0,0 +1,10 @@
+# Introduction
+
+This document (and the linked documents) explains how the exports and side effects of `@microsoft/fast-element` are used to create custom elements.
+
+## Glossary
+
+- [Overview](./overview.md): How the `@microsoft/fast-element` should be used by a developer and what code is executed during the first render.
+- [`FASTElement`](./fastelement.md): How the `FASTElement` is architected.
+- [`html` tagged template literal](./html-tagged-template-literal.md): How the `html` tagged template literal takes and converts the contents into a `ViewTemplate`.
+- [`Updates` queue](./updates.md): How updates to attributes and observables are processed.