diff --git a/change/@microsoft-fast-element-508f24cc-5d36-4192-9b5b-b342f60bad5d.json b/change/@microsoft-fast-element-508f24cc-5d36-4192-9b5b-b342f60bad5d.json
new file mode 100644
index 00000000000..26a98be64ac
--- /dev/null
+++ b/change/@microsoft-fast-element-508f24cc-5d36-4192-9b5b-b342f60bad5d.json
@@ -0,0 +1,7 @@
+{
+  "type": "none",
+  "comment": "chore: add DESIGN.md and fix architecture doc errors",
+  "packageName": "@microsoft/fast-element",
+  "email": "7559015+janechu@users.noreply.github.com",
+  "dependentChangeType": "none"
+}
diff --git a/packages/fast-element/ARCHITECTURE_FASTELEMENT.md b/packages/fast-element/ARCHITECTURE_FASTELEMENT.md
index e227474a2bf..d6e451a1205 100644
--- a/packages/fast-element/ARCHITECTURE_FASTELEMENT.md
+++ b/packages/fast-element/ARCHITECTURE_FASTELEMENT.md
@@ -42,7 +42,7 @@ flowchart TD
 
 The rendering of the template on the `ElementController` is by the `renderTemplate` method which is called during the `ElementController.connect` method which is triggered by `HTMLElement`s `connectedCallback` lifecycle.
 
-The `renderTemplate` identifies the Custom Element, and the shadow root associated with the Custom Element. This then places a rendering of the template (an `ElementView`) onto the internal `view` of the controller. When creating the `ElementView`/`HTMLView` using the `ViewTemplate.render`, the `Compile.compile()` method identifies a `DocumentFragment` either by using an existing `<template>` tag, or creating one to wrap the contents of the shadow root. A new `CompilationContext` is created and the `compileAttributes` function is called, this results in the replacement of the placeholder attributes initally set-up during the pre-render step with their values if a value has been assigned. The factories with the associated nodes identified are then passed to the context. The view then binds all behaviors to the source element. The `CompilationContext.createView` is executed with the `DocumentFragment` as the root, and returns an `HTMLView`. This `HTMLView` includes an `appendTo` method to attach the fragment to the host element, which it then does. It should be noted that the compiled HTML is a `string`, which when set on the `DocumentFragment` as `innerHTML`, this allows the browser to dictate the creation of HTML nodes.
+The `renderTemplate` identifies the Custom Element, and the shadow root associated with the Custom Element. This then places a rendering of the template (an `ElementView`) onto the internal `view` of the controller. When creating the `ElementView`/`HTMLView` using the `ViewTemplate.render`, the `Compiler.compile()` method identifies a `DocumentFragment` either by using an existing `<template>` tag, or creating one to wrap the contents of the shadow root. A new `CompilationContext` is created and the `compileAttributes` function is called, this results in the replacement of the placeholder attributes initally set-up during the pre-render step with their values if a value has been assigned. The factories with the associated nodes identified are then passed to the context. The view then binds all behaviors to the source element. The `CompilationContext.createView` is executed with the `DocumentFragment` as the root, and returns an `HTMLView`. This `HTMLView` includes an `appendTo` method to attach the fragment to the host element, which it then does. It should be noted that the compiled HTML is a `string`, which when set on the `DocumentFragment` as `innerHTML`, this allows the browser to dictate the creation of HTML nodes.
 
 ### 🔄 **Lifecycle**: Component is disconnected
 
diff --git a/packages/fast-element/ARCHITECTURE_HTML_TAGGED_TEMPLATE_LITERAL.md b/packages/fast-element/ARCHITECTURE_HTML_TAGGED_TEMPLATE_LITERAL.md
index 8c9c447b5a9..4cc28d8414c 100644
--- a/packages/fast-element/ARCHITECTURE_HTML_TAGGED_TEMPLATE_LITERAL.md
+++ b/packages/fast-element/ARCHITECTURE_HTML_TAGGED_TEMPLATE_LITERAL.md
@@ -6,10 +6,12 @@ The `html` export from `@microsoft/fast-element` is used to create the template
 
 Before the template can be used it goes through a step to convert it into a `ViewTemplate` which it does via the `ViewTemplate.create()` method. This is then used during the `compose` step, before `FASTElement` is instantiated.
 
-During the `Compiler.compile()` method(triggered by `ViewTemplate.create()` method), the following happens for each string:
+During the static `ViewTemplate.create()` method (called by the `html` tag), the following happens for each string:
 - Factories with unique IDs are created for each tag template literal argument (or `TemplateValue`) which matches with the corresponding string
 - A binding is created from the `TemplateValue`
 
+The `Compiler.compile()` method is called lazily the first time the template is rendered (via `ViewTemplate.compile()`, which is triggered by `ViewTemplate.create()` instance method or `ViewTemplate.render()`).
+
 A resulting string using a `createHTML()` function is produced using the `HTMLDirective`s executed for each factory. The behavior is augmented by the previous string from the `html` tag template which determines the aspect if one exists, these aspects are the `@`, `:`, or other binding aspect attached to attributes.
 
 The `createHTML()` function utilizes a `Markup` attribute which is assigned to a factory's unique ID. The strings are concatenated and passed to a new `ViewTemplate` with all the factories (empty until one is assigned) that act as a dictionary with the unique IDs as the key to look up each factory once it has been created. The string this creates is injected into a `<template>` as `innerHTML`, which allows the browser to create the nodes and placeholder factory IDs, with the only `DOM` node that is explicitly created being the wrapping `<template>` element.
diff --git a/packages/fast-element/ARCHITECTURE_INTRO.md b/packages/fast-element/ARCHITECTURE_INTRO.md
index b260a28ef46..f90a1f9d989 100644
--- a/packages/fast-element/ARCHITECTURE_INTRO.md
+++ b/packages/fast-element/ARCHITECTURE_INTRO.md
@@ -6,5 +6,5 @@ This document (and the linked documents) explains how the exports and side effec
 
 - [Overview](./ARCHITECTURE_OVERVIEW.md): How the `@microsoft/fast-element` should be used by a developer and what code is executed during the first render.
 - [`FASTElement`](./ARCHITECTURE_FASTELEMENT.md): How the `FASTElement` is architected.
-- [`html` tagged template literal](./ARCHITECTURE_HTML_TAGGED_TEMPLATE_LITERAL.md): How the `html` tagged template literal takes and converts the contents into a `VIEWTemplate`.
+- [`html` tagged template literal](./ARCHITECTURE_HTML_TAGGED_TEMPLATE_LITERAL.md): How the `html` tagged template literal takes and converts the contents into a `ViewTemplate`.
 - [`Updates` queue](./ARCHITECTURE_UPDATES.md): How updates to attributes and observables are processed.
\ No newline at end of file
diff --git a/packages/fast-element/ARCHITECTURE_OVERVIEW.md b/packages/fast-element/ARCHITECTURE_OVERVIEW.md
index 68e609acbd8..8783c6a1aa7 100644
--- a/packages/fast-element/ARCHITECTURE_OVERVIEW.md
+++ b/packages/fast-element/ARCHITECTURE_OVERVIEW.md
@@ -39,7 +39,7 @@ flowchart TD
     A --> B
     C@{ shape: rect, label: "A Custom Element executes the <code>compose</code> step"}
     B --> C
-    D@{ shape: procs, label: "<ul style="text-align: left"><li>Any defined observable decorators are added to the FAST global</li><li>An attribute decorator locates the associated Custom Elements constructor which it uses to push itself to the Custom Elements attribute collection</li></ul>"}
+    D@{ shape: procs, label: "<ul style='text-align: left'><li>Any defined observable decorators are added to the FAST global</li><li>An attribute decorator locates the associated Custom Elements constructor which it uses to push itself to the Custom Elements attribute collection</li></ul>"}
     C --> D
     F@{ shape: rect, label: "An HTML tagged template literal is executed for the FAST Custom Element and applied to the definition" }
     D --> F
diff --git a/packages/fast-element/DESIGN.md b/packages/fast-element/DESIGN.md
new file mode 100644
index 00000000000..7ae375972f1
--- /dev/null
+++ b/packages/fast-element/DESIGN.md
@@ -0,0 +1,506 @@
+# FAST Element – Design Overview
+
+This document is a contributor-oriented guide to the architecture of `@microsoft/fast-element`. It synthesises the individual architecture documents into a single entry point and explains how all the pieces fit together.
+
+For deep dives into specific areas, see the linked detailed documents.
+
+---
+
+## Table of Contents
+
+1. [High-Level Overview](#high-level-overview)
+2. [Core Concepts](#core-concepts)
+   - [FAST Global](#fast-global)
+   - [FASTElement & ElementController](#fastelement--elementcontroller)
+   - [Observables & Notifiers](#observables--notifiers)
+   - [Bindings](#bindings)
+   - [html Tagged Template Literal](#html-tagged-template-literal)
+   - [ViewTemplate & Compiler](#viewtemplate--compiler)
+   - [Views & Behaviors](#views--behaviors)
+   - [Updates Queue](#updates-queue)
+   - [Styles](#styles)
+   - [Dependency Injection (DI)](#dependency-injection-di)
+   - [Context Protocol](#context-protocol)
+   - [State Helpers](#state-helpers)
+3. [Data Flow Diagrams](#data-flow-diagrams)
+   - [Module Load & Registration](#module-load--registration)
+   - [FASTElement Lifecycle](#fastelement-lifecycle)
+   - [Template Pipeline](#template-pipeline)
+   - [Observable Change Propagation](#observable-change-propagation)
+4. [How the Pieces Fit Together](#how-the-pieces-fit-together)
+5. [Package Layout](#package-layout)
+6. [Detailed Architecture Documents](#detailed-architecture-documents)
+
+---
+
+## High-Level Overview
+
+`@microsoft/fast-element` is a lightweight library for building standards-based Custom Elements (Web Components). Its key responsibilities are:
+
+| Concern | What FAST provides |
+|---|---|
+| Element authoring | `FASTElement` base class + `@customElement`, `@attr`, `@observable` decorators |
+| Reactive data binding | `Observable`, `ExpressionNotifier`, `oneWay`/`oneTime`/`listener` bindings |
+| Declarative templating | `html` tagged template literal → `ViewTemplate` → compiled `HTMLView` |
+| Async DOM updates | `Updates` queue (batched, `requestAnimationFrame`-aligned) |
+| Scoped styles | `css` tagged template literal → `ElementStyles` → `adoptedStylesheets` / `<style>` |
+| Dependency injection | `DI` container, `@inject`, `@singleton`, `@transient`, resolvers |
+| Context protocol | W3C community Context protocol (`Context.create`, `Context.for`) |
+| Reactive state helpers | `state()`, `watch()` (beta) |
+
+The library's kernel (the `FAST` global, the `Updates` queue, and the `Observable` system) is stored on `globalThis.FAST` and can be shared across multiple versions of the library loaded on the same page.
+
+---
+
+## Core Concepts
+
+### FAST Global
+
+**File**: `src/platform.ts`, `src/interfaces.ts`
+
+`FAST` is a singleton object attached to `globalThis`. It provides:
+
+- `FAST.getById(id, initializer)` – shared kernel slot registry (used to share the update queue and observable system across FAST instances)
+- `FAST.warn(code, values)` / `FAST.error(code, values)` – structured diagnostic messages
+- `FAST.addMessages(dict)` – registers human-readable debug messages (imported by `src/debug.ts`)
+
+The `KernelServiceId` object controls which numeric/string keys are used for shared services. Three modes are supported via a `fast-kernel` attribute on the current `<script>` tag:
+
+| Mode | Behaviour |
+|---|---|
+| `share` | Share the kernel across any FAST version |
+| `share-v2` | Share only with other v2 instances |
+| *(default)* | Fully isolated instance with a random postfix |
+
+---
+
+### FASTElement & ElementController
+
+**Files**: `src/components/fast-element.ts`, `src/components/element-controller.ts`, `src/components/fast-definitions.ts`
+
+`FASTElement` is a thin mixin applied on top of `HTMLElement`. It:
+
+1. Calls `ElementController.forCustomElement(this)` in its `constructor` to create or locate the element's controller.
+2. Delegates all lifecycle hooks to the controller:
+   - `connectedCallback` → `$fastController.connect()`
+   - `disconnectedCallback` → `$fastController.disconnect()`
+   - `attributeChangedCallback` → `$fastController.onAttributeChangedCallback()`
+
+`ElementController` is the real workhorse. It:
+
+- Extends `PropertyChangeNotifier` so the element itself participates in the observable system.
+- Holds the element's `FASTElementDefinition` (name, template, styles, observed attributes).
+- Manages a `Stages` state machine: `disconnected → connecting → connected → disconnecting → disconnected`.
+- On `connect()`: restores pre-upgrade observable values, calls `connectedCallback` on all `HostBehavior`s, renders the template into the shadow root, and applies styles.
+- On `disconnect()`: calls `disconnectedCallback` on behaviors, unbinds the view.
+- Exposes `addBehavior` / `removeBehavior` for dynamic `HostBehavior` management (used by `ElementStyles`).
+
+`FASTElementDefinition` wraps all the metadata for a custom element class: its tag name, template, styles, and observed attribute list. It is created by `FASTElement.compose()` and registered globally via `fastElementRegistry`.
+
+---
+
+### Observables & Notifiers
+
+**Files**: `src/observation/observable.ts`, `src/observation/notifier.ts`, `src/observation/arrays.ts`
+
+#### Property observability
+
+`Observable.defineProperty(target, name)` (or the `@observable` decorator) replaces a plain property with a getter/setter pair via `Reflect.defineProperty`. The setter:
+
+1. Stores the new value in a backing slot.
+2. Calls `Observable.getNotifier(this).notify(name)` to fan out to subscribers.
+
+`Observable.getNotifier(object)` returns the `PropertyChangeNotifier` for an object, creating one on demand. Notifiers are stored in a `WeakMap` so they don't prevent GC.
+
+#### SubscriberSet / PropertyChangeNotifier
+
+`SubscriberSet` is an optimised set that stores the first two subscribers inline (avoiding heap allocations for the common 1–2 subscriber case) and falls back to an array. `PropertyChangeNotifier` extends `SubscriberSet` to support per-property subscriptions.
+
+#### ExpressionNotifier (binding observer)
+
+`Observable.binding(expression, subscriber)` creates an `ExpressionNotifier`. When `observe(source, context)` is called it:
+
+1. Pushes itself as the _current watcher_ onto a thread-local stack.
+2. Evaluates the expression (e.g., `x => x.name`).
+3. Any `Observable`-tracked property get encountered during evaluation subscribes the notifier to that property's notifier automatically.
+4. Pops itself. Future changes to any accessed property trigger `handleChange` on the subscriber.
+
+This gives FAST automatic, fine-grained dependency tracking without explicit declarations.
+
+---
+
+### Bindings
+
+**Files**: `src/binding/binding.ts`, `src/binding/one-way.ts`, `src/binding/one-time.ts`, `src/binding/normalize.ts`
+
+`Binding` is an abstract class that pairs an `Expression` (arrow function) with a `DOMPolicy` and a volatility flag. Concrete subclasses implement `createObserver(subscriber, directive)`:
+
+| Binding | Observer behaviour |
+|---|---|
+| `oneWay` | Creates an `ExpressionNotifier`; tracks dependencies; re-evaluates on change |
+| `oneTime` | Evaluates once during `bind()`, returns immediately |
+| `listener` | Same as `oneWay` but attaches as a DOM event handler |
+
+`normalizeBinding(value)` converts raw arrow functions or static values into a `Binding` object.
+
+---
+
+### html Tagged Template Literal
+
+**File**: `src/templating/template.ts`
+
+The `html` tag is the primary authoring API:
+
+```typescript
+const template = html<MyElement>`
+  <div>${x => x.label}</div>
+  <button @click="${x => x.handleClick}">OK</button>
+`;
+```
+
+When the tag function is called it invokes `ViewTemplate.create(strings, values)` (static method) which:
+
+1. Iterates the template string fragments (`strings`) paired with interpolated values.
+2. For each value:
+   - A plain function → wrapped in `HTMLBindingDirective(oneWay(fn))`
+   - A `Binding` instance → wrapped in `HTMLBindingDirective(binding)`
+   - A registered `HTMLDirective` instance → used directly
+   - Anything else → wrapped as a `oneTime` static binding
+3. Calls `directive.createHTML(add)` which returns a **placeholder string** (a special attribute or marker containing the factory's unique ID).
+4. Concatenates all static strings and placeholders into a single HTML string.
+5. Returns a `ViewTemplate(html, factories)` – the factories dictionary maps IDs to `ViewBehaviorFactory` instances.
+
+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.
+
+---
+
+### ViewTemplate & Compiler
+
+**Files**: `src/templating/template.ts`, `src/templating/compiler.ts`, `src/templating/markup.ts`
+
+`ViewTemplate.compile()` is called lazily the first time the template is rendered. It delegates to `Compiler.compile(html, factories, policy)`:
+
+1. Sets the HTML string as the `innerHTML` of a `<template>` element (letting the browser parse the DOM once).
+2. Traverses the resulting `DocumentFragment` depth-first.
+3. For each node, calls `compileAttributes()` which scans attributes for factory placeholder IDs.
+4. When a placeholder is found, it associates the matching `ViewBehaviorFactory` with the node's structural ID (a dot-separated path like `"r.2.0"` meaning "third child of the root's second child").
+5. Lazily-resolved descriptors (using `Object.defineProperty` on a prototype) allow `HTMLView` to look up any target node via a chain of `childNodes` accesses without pre-walking the tree for every view instance.
+6. Returns a `CompilationContext` that implements `HTMLTemplateCompilationResult`.
+
+`CompilationContext.createView(hostBindingTarget?)` clones the compiled `DocumentFragment`, instantiates behaviors from factories, and returns an `HTMLView`.
+
+---
+
+### Views & Behaviors
+
+**Files**: `src/templating/view.ts`, `src/templating/html-directive.ts`
+
+`HTMLView` implements `ElementView` / `SyntheticView`. It:
+
+- Holds the cloned `DocumentFragment` nodes.
+- Has a `targets` map (resolved lazily) from structural node IDs to live `Node` references.
+- `bind(source, context)` iterates all `ViewBehavior` instances and calls `behavior.bind(controller)`.
+- `unbind()` calls `behavior.unbind()` on each behavior and clears the source.
+- `appendTo(node)` / `insertBefore(node)` / `remove()` move its DOM nodes in the tree.
+
+`ViewBehavior` is the runtime unit of work attached to a specific DOM node. Examples:
+
+| Directive | Created `ViewBehavior` | Effect |
+|---|---|---|
+| `HTMLBindingDirective` | `BindingBehavior` | Evaluates the binding; updates the DOM aspect (attribute / property / event / content / tokenList) |
+| `when` | `WhenBehavior` | Conditionally inserts a child view |
+| `repeat` | `RepeatBehavior` | Renders a list of child views |
+| `ref` | `RefDirective` | Writes the element reference onto the source |
+| `children` / `slotted` | `ChildrenDirective` / `SlottedDirective` | Observes DOM mutations |
+
+`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.
+
+---
+
+### Updates Queue
+
+**File**: `src/observation/update-queue.ts`
+
+**Exported as**: `Updates`
+
+`Updates` is a shared, batched task queue used to synchronise writes to the DOM. It is stored on the `FAST` global (under `KernelServiceId.updateQueue`) so multiple FAST instances on the same page share a single flush cycle.
+
+- `Updates.enqueue(callable)` – schedules a task for the next batch.
+- `Updates.process()` – forces immediate synchronous flush (useful in tests).
+- `Updates.next()` – returns a `Promise` that resolves after the next flush.
+- `Updates.setMode(isAsync)` – toggle async (default) vs. synchronous mode.
+
+In async mode, the first `enqueue` call schedules a `requestAnimationFrame` callback that drains up to 1024 tasks per frame. Errors in tasks are deferred via `setTimeout` so they don't abort the remaining tasks.
+
+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.
+
+---
+
+### Styles
+
+**Files**: `src/styles/css.ts`, `src/styles/element-styles.ts`, `src/styles/css-directive.ts`
+
+The `css` tag (analogous to `html`) builds `ElementStyles` objects. During `ElementController.connect()`, styles are applied to the element's shadow root either via `adoptedStylesheets` (preferred) or an appended `<style>` node, depending on platform support. Styles can also contain dynamic `CSSDirective`s (e.g., CSS custom property bindings) that register as `HostBehavior`s and connect/disconnect alongside the element.
+
+---
+
+### Dependency Injection (DI)
+
+**File**: `src/di/di.ts`
+
+FAST ships a full hierarchical DI container inspired by Aurelia. Key types:
+
+| Type | Role |
+|---|---|
+| `Container` | Resolves dependencies; parent containers are queried if a key is not found locally |
+| `Resolver` | Maps a key to a creation strategy (singleton, transient, callback, …) |
+| `Registration` | Produces a `Resolver` when registered in a container |
+| `Factory` | Constructs instances; supports `Transformer`s for post-construction mutation |
+
+Containers are typically attached to DOM elements and walk the DOM hierarchy. DI keys are classes, interfaces, or `Context`-like tokens. Constructor parameters are annotated with the `@inject(key)` decorator (or use `@singleton` / `@transient` to declare the class's own registration).
+
+See `docs/di/api-report.api.md` for the full public API surface.
+
+---
+
+### Context Protocol
+
+**File**: `src/context.ts`
+
+`Context` implements the [W3C Community Context Protocol](https://github.com/webcomponents-cg/community-protocols/blob/main/proposals/context.md). A `FASTContext<T>` object is both a DI key and a decorator:
+
+- `Context.create<T>(name, initialValue?)` – creates a named context token.
+- `Context.for<T>(name)` – gets or creates a globally-registered context token.
+- `context.provide(target, value)` – registers a provider on a DOM element.
+- `context.get(target)` – dispatches a `context-request` event and returns the synchronously provided value (or `initialValue`).
+- `context.request(target, callback, multiple?)` – async / multi-provider variant.
+- Used as a `@decorator` on class properties or constructor parameters to declare a context dependency.
+
+---
+
+### State Helpers
+
+**Files**: `src/state/state.ts`, `src/state/watch.ts`
+
+> **Status**: beta
+
+`state<T>(initialValue, options?)` creates a reactive `State<T>` object – a callable that returns the current value. The state's `.current` property is a FAST observable, so templates or `ExpressionNotifier`s that read it will automatically re-evaluate when it changes.
+
+`watch(object, subscriber)` deeply subscribes to all observable properties and array mutations on an object graph, returning a `Disposable`.
+
+---
+
+## Data Flow Diagrams
+
+### Module Load & Registration
+
+```mermaid
+flowchart TD
+    A([Browser loads script]) --> B[FAST global created on globalThis]
+    B --> C[FASTElement subclass executes FASTElement.compose]
+    C --> D[Observable decorators register accessors on the prototype]
+    C --> E[Attribute decorators push AttributeDefinition to the class]
+    C --> F[html tag is evaluated – ViewTemplate created with factories]
+    D & E & F --> G[FASTElement.define registers with the Custom Element Registry]
+    G --> H[Browser detects element in DOM]
+    H --> I([FASTElement lifecycle begins])
+```
+
+### FASTElement Lifecycle
+
+```mermaid
+flowchart TD
+    CTOR[constructor] --> EC[ElementController.forCustomElement creates or locates the controller]
+    EC --> ATTACH[Controller captures element + definition, sets $fastController]
+
+    CONN[connectedCallback] --> STAGE[stage = connecting]
+    STAGE --> OBS[Restore pre-upgrade observable values]
+    OBS --> BEHAV[Connect HostBehaviors]
+    BEHAV --> RENDER[renderTemplate → ViewTemplate.render → HTMLView.appendTo shadow root]
+    RENDER --> STYLES[Apply ElementStyles to shadow root]
+    STYLES --> DONE[stage = connected]
+
+    ATTR[attributeChangedCallback] --> ACD[AttributeDefinition.onAttributeChangedCallback]
+    ACD --> ENQ[Updates.enqueue – reflect new value via Observable accessor]
+
+    DISC[disconnectedCallback] --> DBEHAV[Disconnect HostBehaviors]
+    DBEHAV --> UNBIND[HTMLView.unbind]
+    UNBIND --> DSTAGE[stage = disconnected]
+```
+
+### Template Pipeline
+
+```mermaid
+flowchart LR
+    TAG["html\`...\` tag call"]
+    CREATE["ViewTemplate.create() (static)\nBuilds HTML string with\nfactory placeholder IDs\nand factories dictionary"]
+    LAZY["First render call\nViewTemplate.create() / render()"]
+    COMPILE["ViewTemplate.compile()\n→ Compiler.compile()\nParses <template> innerHTML\nBuilds CompilationContext\nwith node ID descriptors"]
+    CLONE["CompilationContext.createView()\nClones DocumentFragment\nInstantiates ViewBehaviors"]
+    VIEW["HTMLView\nDOM nodes + behaviors"]
+    BIND["HTMLView.bind(source, context)\nEach ViewBehavior.bind(controller)\nEvaluates expressions\nWrites to DOM"]
+
+    TAG --> CREATE
+    CREATE --> LAZY
+    LAZY --> COMPILE
+    COMPILE --> CLONE
+    CLONE --> VIEW
+    VIEW --> BIND
+```
+
+### Observable Change Propagation
+
+```mermaid
+flowchart TD
+    SET["element.property = newValue\n(Observable setter)"]
+    NOTIFY["PropertyChangeNotifier.notify(propertyName)"]
+    SUBS["For each Subscriber in SubscriberSet\nsubscriber.handleChange(subject, propertyName)"]
+    ENQ["Updates.enqueue(binding task)"]
+    RAF["requestAnimationFrame fires\nUpdates.process()"]
+    EVAL["ExpressionNotifier re-evaluates expression"]
+    DOM["DOM aspect updated\n(attribute / property / content / event)"]
+
+    SET --> NOTIFY
+    NOTIFY --> SUBS
+    SUBS --> ENQ
+    ENQ --> RAF
+    RAF --> EVAL
+    EVAL --> DOM
+```
+
+---
+
+## How the Pieces Fit Together
+
+Below is a conceptual map of the major subsystems and their relationships:
+
+```
+┌──────────────────────────────────────────────────────────────────────────────┐
+│                           FAST Global (globalThis.FAST)                      │
+│  KernelServiceIds → Updates queue, Observable system, Element registry       │
+└────────────────────┬─────────────────────────────────────────────────────────┘
+                     │ shared kernel slots
+         ┌───────────┴───────────┐
+         │                       │
+┌────────▼──────────┐   ┌────────▼────────────────────┐
+│  Observable /      │   │  Updates queue               │
+│  ExpressionNotifier│   │  (rAF-batched task runner)   │
+│  SubscriberSet     │   └────────────────────────────-─┘
+└────────┬──────────┘            ▲
+         │ dependency tracking   │ enqueue
+         ▼                       │
+┌────────────────────────────────┴──────────────────────────────┐
+│                    Binding system                               │
+│  oneWay / oneTime / listener → Binding → ExpressionObserver    │
+└────────────────────────┬──────────────────────────────────────┘
+                         │ drives
+┌────────────────────────▼──────────────────────────────────────┐
+│                  Templating pipeline                            │
+│  html tag → ViewTemplate → Compiler → CompilationContext       │
+│  createView → HTMLView → ViewBehaviors (bind/update DOM)        │
+└────────────────────────┬──────────────────────────────────────┘
+                         │ owned by
+┌────────────────────────▼──────────────────────────────────────┐
+│                  ElementController                              │
+│  Lifecycle (connect/disconnect/attr) • Styles • Behaviors       │
+└────────────────────────┬──────────────────────────────────────┘
+                         │ wraps
+┌────────────────────────▼──────────────────────────────────────┐
+│    FASTElement (HTMLElement subclass)                           │
+│    + FASTElementDefinition (metadata: name, template, styles)   │
+└───────────────────────────────────────────────────────────────┘
+         │ optional higher-level services
+         ├──────────────────────────────────────────────┐
+┌────────▼──────────┐                        ┌──────────▼──────────┐
+│  DI container      │                        │  Context protocol    │
+│  (di/di.ts)        │                        │  (context.ts)        │
+└───────────────────┘                        └─────────────────────┘
+```
+
+**Authoring flow summary**:
+
+1. Developer writes a class extending `FASTElement`, decorates properties with `@observable` / `@attr`, and calls `FASTElement.define({ name, template, styles })`.
+2. `FASTElement.define` → `FASTElementDefinition.compose(...).define()` registers the element with the Custom Element Registry.
+3. When the browser upgrades the element, `ElementController.forCustomElement(element)` is called in the constructor.
+4. On `connectedCallback`, the controller renders the template (`ViewTemplate.render`) into the shadow root. Compilation is lazy: the first render call triggers `Compiler.compile()`, subsequent calls clone the already-compiled `DocumentFragment`.
+5. `HTMLView.bind(source)` wires up each `ViewBehavior`. `oneWay` bindings create `ExpressionNotifier`s that track observable dependencies automatically.
+6. When an observed property changes, its notifier fans out to all subscribers. Each binding enqueues a DOM update via `Updates`. The next animation frame drains the queue and applies the mutations.
+7. On `disconnectedCallback`, `HTMLView.unbind()` tears down all bindings; behaviors disconnect; styles are removed.
+
+---
+
+## Package Layout
+
+```
+src/
+├── interfaces.ts          # Core types: Callable, Constructable, FASTGlobal, Message codes
+├── platform.ts            # FAST global initialisation, KernelServiceId, TypeRegistry
+├── dom.ts                 # DOMAspect enum, DOMPolicy, DOMSink
+├── dom-policy.ts          # Default DOM security policy (TrustedTypes integration)
+├── metadata.ts            # Reflect-based metadata helpers
+├── utilities.ts           # UnobservableMutationObserver and other helpers
+├── debug.ts               # Adds human-readable error messages to FAST global
+├── observation/
+│   ├── observable.ts      # Observable, @observable, ExpressionNotifier, ExecutionContext
+│   ├── notifier.ts        # Subscriber, Notifier, SubscriberSet, PropertyChangeNotifier
+│   ├── arrays.ts          # ArrayObserver, Splice, SpliceStrategy
+│   └── update-queue.ts    # Updates (UpdateQueue)
+├── binding/
+│   ├── binding.ts         # Binding abstract base class, BindingDirective
+│   ├── one-way.ts         # oneWay, listener
+│   ├── one-time.ts        # oneTime
+│   └── normalize.ts       # normalizeBinding helper
+├── templating/
+│   ├── template.ts        # ViewTemplate, html tag, InlineTemplateDirective
+│   ├── compiler.ts        # Compiler, CompilationContext
+│   ├── view.ts            # HTMLView, ElementView, SyntheticView
+│   ├── html-directive.ts  # HTMLDirective, ViewBehavior, ViewBehaviorFactory
+│   ├── html-binding-directive.ts  # HTMLBindingDirective
+│   ├── markup.ts          # Markup placeholders, Parser
+│   ├── when.ts            # when directive
+│   ├── repeat.ts          # repeat directive
+│   ├── ref.ts             # ref directive
+│   ├── render.ts          # render directive
+│   ├── children.ts        # children directive
+│   ├── slotted.ts         # slotted directive
+│   └── TEMPLATE-BINDINGS.md
+├── styles/
+│   ├── css.ts             # css tag
+│   ├── element-styles.ts  # ElementStyles
+│   ├── css-directive.ts   # CSSDirective, @cssDirective
+│   └── host.ts            # HostBehavior, HostController
+├── components/
+│   ├── fast-element.ts    # FASTElement, @customElement
+│   ├── element-controller.ts  # ElementController, Stages
+│   ├── fast-definitions.ts    # FASTElementDefinition, TemplateOptions
+│   ├── attributes.ts          # AttributeDefinition, @attr, converters
+│   └── hydration.ts           # SSR hydration helpers
+├── di/
+│   └── di.ts              # DI container, decorators, resolvers, Registration
+├── context.ts             # Context, FASTContext, Context protocol
+├── state/
+│   ├── state.ts           # state() helper (beta)
+│   └── watch.ts           # watch() helper (beta)
+└── hydration/
+    └── target-builder.ts  # Hydration target resolution
+```
+
+---
+
+## Detailed Architecture Documents
+
+| 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/fast-element-2-changes.md](./docs/fast-element-2-changes.md) | Breaking changes from v1 to v2 |