Define semantic page archetypes

docs/PAGE_LAYOUT_USAGE_GUIDELINES.md

@@ -7,6 +7,8 @@ wording, authorization, consequences, and data state.
 ## Required Page Frame
 
 - Use `PageLayout` for every headed standalone, workspace, or embedded page.
+- Declare exactly one semantic `archetype`; do not infer page intent from the
+  `mode`, which controls geometry and scroll ownership only.
 - Use `WorkspaceFrame` for a full-height module surface and
   `WorkspaceLayout` only where navigation/content or list/detail panes are
   genuinely part of the interaction.
@@ -16,7 +18,22 @@ wording, authorization, consequences, and data state.
 - Do not reproduce shared page padding, heading, toolbar, form-grid, section,
   table, dialog, or breakpoint CSS in a module.
 
-## Page Action Archetypes
+## Semantic Page Archetypes
+
+| Archetype | Use when |
+| --- | --- |
+| `overview` | The page summarizes health, metrics, or several peer areas without owning one primary collection or draft. |
+| `collection` | The primary object is a searchable/listable collection and Create, when available, applies to that collection. |
+| `detail` | The page primarily presents one record, report, or immutable projection. |
+| `editor` | The page owns one explicit draft with Save and Discard behavior. |
+| `workspace` | The page coordinates several panes, stages, or task-local operations that cannot honestly be reduced to one record or draft. |
+
+The archetype remains stable for the current interaction. A page may switch
+from `overview` to `editor` when the user explicitly enters configuration
+mode. It must not call a page an editor merely because a dialog or an inline
+filter is editable.
+
+## Page Action Rules
 
 Pass one `PageActionBar` to the `PageLayout` `actions` slot. The variant makes
 the page's intent inspectable and preserves the same keyboard and visual order
@@ -24,17 +41,36 @@ across modules.
 
 | Page kind | Leading group | Trailing group |
 | --- | --- | --- |
-| Collection | Reload, then collection context such as export | Help, then Create at the far right |
-| Detail | Reload, then object context | Help, ordinary primary actions, then consequential actions |
-| Editor | Reload, then editor context such as preview | Help, Discard, then Save at the far right |
+| Overview | Reload when refreshable, then context | Help, then ordinary primary actions |
+| Collection | Reload when refreshable, then collection context such as export | Help, then Create at the far right |
+| Detail | Reload when refreshable, then object context | Help, ordinary primary actions, then a separated destructive group |
+| Editor | Reload only when refresh is a distinct safe operation, then context | Dirty state, Help, ordinary primary actions, separated destructive actions, Discard, then Save at the far right |
+| Workspace | Reload when the coordinated projection can become stale, then task context | Help, ordinary primary actions, then a separated destructive group |
 
-Reload means re-fetch or re-evaluate the current surface. It remains present
-when the page can become stale. Create is a collection-wide action and is not
-duplicated in a persistent side panel. Save is present only where the page owns
-an editable draft; a read-only detail page must not display a disabled or inert
-Save merely to fill the slot.
+Reload means re-fetch or re-evaluate the current surface. A page declaring
+`refreshable` must provide it, and a non-refreshable page must not use Reload as
+a synonym for Cancel, Reset, or Discard. Reload never silently destroys a dirty
+draft. Create is a collection-wide action and is not duplicated in a
+persistent side panel. Save is present only where the page owns an editable
+draft; a read-only detail page must not display a disabled or inert Save merely
+to fill the slot.
 
-`PageActionBar` controls placement only. Actions continue to use central
+Editor bars always keep Discard and Save visible. They expose `clean`, `dirty`,
+and `saving` status through a live status label. In the clean or saving state,
+the central component disables both persistence actions and supplies the
+standard explanation. A module may add a more specific validation, policy, or
+permission blocker while the draft is dirty. The editor must register its
+draft with `useUnsavedDraftGuard` (or a shared hook that uses the same
+registration contract), so browser unload, route navigation, section changes,
+and the explicit Discard path cannot silently lose work.
+
+Destructive page actions use `destructiveActions`; never put a danger action in
+`contextActions` or the ordinary primary group. Core renders a persistent
+visual and semantic boundary before this group. In an editor it precedes the
+Discard/Save pair, keeping Save in the final keyboard and visual position.
+
+`PageActionBar` controls non-editor placement and owns the standard editor
+persistence buttons. Other actions continue to use central
 `Button`, `IconButton`, or `TableActionGroup` components. When an action is
 visible but unavailable because of permission, target, policy, state, or
 validation, keep it in its stable slot and supply `disabledReason`. Do not
@@ -65,8 +101,11 @@ silently hide a normally applicable action.
 
 ## Review Evidence
 
-Every new or changed page should have structural evidence for its page frame,
-semantic action archetype and slot order, shared component usage, stable
-disabled actions, and module-owned help identity. Keyboard and narrow-layout
-checks must confirm that all commands remain reachable in DOM order and that
-the trailing group stays visually trailing after wrapping.
+Every new or changed page must have structural evidence for its page frame,
+semantic archetype and slot order, refresh declaration, shared component
+usage, stable disabled actions, dirty guard, destructive boundary, and
+module-owned help identity. Type checks enforce conditional Reload and editor
+persistence props. Product checks reject undeclared archetypes and ad-hoc
+headed action fragments. Browser conformance confirms keyboard order, live
+dirty-state changes, accessibility, destructive separation, narrow wrapping,
+and screenshot geometry.