apache · jackeyfaker77 · Sep 4, 2026
diff --git a/docs/astryx-alignment-inventory.md b/docs/astryx-alignment-inventory.md
@@ -1,3 +1,13 @@
+---
+doc_id: frontend.astryx-alignment-inventory
+title: "Astryx alignment inventory"
+language: en
+source_language: en
+implementation_status: historical
+document_status: historical
+translation_status: source-only
+last_verified: 2026-09-05
+---
 <!--
   Licensed to the Apache Software Foundation (ASF) under one
   or more contributor license agreements.  See the NOTICE file
@@ -17,12 +27,12 @@
   under the License.
 -->
 
-> **Superseded for file-level coverage:** see [astryx-surface-file-inventory.md](./astryx-surface-file-inventory.md) (one row per product surface file). This document remains the family-level wiki map and fix log from the first alignment pass.
+> **Historical family-level fix log.** File-level coverage and current severities are generated in [astryx-surface-file-inventory.md](./astryx-surface-file-inventory.md). This document records the first alignment pass; its status cells and remaining-polish list are not a current backlog. On 2026-09-05, the generated check reported 249 files, 0 blockers, 0 reimplementations, 1 polish item, and 248 aligned files.
 
 # Astryx alignment inventory
 
-Maps [Astryx wiki](https://github.com/facebook/astryx/wiki) conventions onto
-Maka product surfaces. Severity: **blocker** (raw control when an Astryx twin
+This pass mapped [Astryx wiki](https://github.com/facebook/astryx/wiki) conventions onto
+Maka product surfaces. At the time, severity meant **blocker** (raw control when an Astryx twin
 exists / broken hierarchy) · **reimplementation** (a public `@maka/ui` export
 shadows a shipped Astryx component — a review signal, not proof) · **polish**
 (off-scale px, density).
@@ -93,7 +103,9 @@ shadows a shipped Astryx component — a review signal, not proof) · **polish**
 - Plan execution expand → Astryx `Collapsible`.
 - Workbar tool picker → Astryx `List` + `ListItem`; visible descriptions and native row interaction.
 
-## Remaining polish (non-blocker)
+## Remaining polish recorded by the first pass (historical)
 - Quote chips / prompt-rail ticks stay product-shaped hit targets.
 - Workbar tab strip stays custom for dnd-kit + `role=tab`.
 - Nested button prohibition on SideNavItem endContent (documented intentional).
+
+Run `npm run astryx:surface-inventory` for the current file universe and severity result.
diff --git a/docs/astryx-full-surface-audit.md b/docs/astryx-full-surface-audit.md
@@ -1,3 +1,13 @@
+---
+doc_id: frontend.astryx-full-surface-audit-2026-08-09
+title: "Astryx full surface audit"
+language: en
+source_language: en
+implementation_status: historical
+document_status: historical
+translation_status: source-only
+last_verified: 2026-09-05
+---
 <!--
   Licensed to the Apache Software Foundation (ASF) under one
   or more contributor license agreements.  See the NOTICE file
@@ -25,7 +35,9 @@ Scope: every product surface under `apps/desktop/src/renderer/**` and `packages/
 
 This pass **read and analyzed** settings pages/modules, shell/chat/workbar/panels, module hubs, packages/ui compositions, and product CSS — not only inventory scripts.
 
-## Verdict
+> **Historical audit record.** The 183-file totals, status table, fix list, and backlog below belong to the named branch and date. They are not current coverage or an open-work queue. On 2026-09-05, `npm run astryx:surface-inventory` verified the generated [file-level inventory](./astryx-surface-file-inventory.md) at 249 files, 0 blockers, 0 reimplementations, 1 polish item, and 248 aligned files. The remaining polish row is `packages/ui/src/composer-message-queue.tsx`.
+
+## Verdict at the audited commit
 
 | Layer | State |
 |-------|--------|
@@ -76,10 +88,10 @@ Aligned: skills-panel, scheduled-task-*, daily-review-panel, module-pages, compo
 4. **Tool / agent / web-search preview cards** — product transcript content chrome, not generic controls.
 5. **DeepResearchProgressPanel** — product progress composition; kit-ify is a dedicated design task.
 6. **Quote chip / turn footer CSS** — still product-geometry overrides on Astryx controls; shrink chrome gradually.
-7. **Logo 44 / swatch 34 / session-context 40** — decorative or band heights, not control rhythm 28/32/36.
+7. **Logo 44 / swatch 34 / session-context 40** — this pass treated them as decorative or band heights. The follow-up review recorded them as the four concrete inventory polish rows and normalized them to 36/36/32; they are not a current exception.
 8. **ChatReasoning / markdown density contracts** — documented product overrides.
 
-## Remaining backlog (priority)
+## Remaining backlog at the audited commit (historical)
 
 ### P1 — visual system
 
@@ -99,9 +111,9 @@ Aligned: skills-panel, scheduled-task-*, daily-review-panel, module-pages, compo
 
 - shrink `.maka-quote-chip-remove` / `.maka-turn-footer-action` / lineage badge overrides.
 - retire dead tool-terminal CSS if unused.
-- inventory polish false-positives for logo/swatch heights.
+- ~~inventory polish false-positives for logo/swatch heights.~~ Resolved by the follow-up review as real polish rows and normalized to the shared rhythm.
 
-## Method
+## Original method
 
 1. Regenerated path inventory (183 files).
 2. Pattern scan: raw controls, role=button, hand empties, role=alert.

diff --git a/docs/frontend-architecture-astryx-review-2026-08-09.md b/docs/frontend-architecture-astryx-review-2026-08-09.md
@@ -1,3 +1,13 @@
+---
+doc_id: frontend.architecture-astryx-review-2026-08-09
+title: "Frontend architecture and Astryx coverage review"
+language: en
+source_language: en
+implementation_status: historical
+document_status: historical
+translation_status: source-only
+last_verified: 2026-09-05
+---
 <!--
   Licensed to the Apache Software Foundation (ASF) under one
   or more contributor license agreements.  See the NOTICE file
@@ -23,11 +33,24 @@
 **HEAD:** `0ad579d33` (`feat(ui): align high-traffic chrome with Astryx primitives (#2580)` on `main`)  
 **Scope:** `apps/desktop/src/renderer/**`, `packages/ui/src/**`  
 **Method:** file-level inventory regen + pattern scan + deep reads of shell/settings/modules/ui; prior art `docs/astryx-full-surface-audit.md`, `DESIGN.md`, `docs/astryx-surface-file-inventory.md`  
-**Evidence log:** goal scratch `frontend-review-scan.log` (inventory totals, greps, spot-checks, inventory unit tests)
+**Original evidence:** the committed audit at `0ad579d33` and follow-up implementation at `d68e9d775`; the scratch scan log named by the original review was not committed.
 
 ---
 
-## Executive verdict
+> **Historical review record.** The findings, file sizes, inventory counts, and backlog below describe the audited commit and the follow-up branch, not current `main`. Current file-level coverage is generated in [astryx-surface-file-inventory.md](./astryx-surface-file-inventory.md); current renderer ownership is recorded in `apps/desktop/renderer-architecture.json` and the feature README files.
+
+## Current status checked on 2026-09-05
+
+- The generated inventory now covers **249 files: 0 blockers, 0 reimplementations, 1 polish item, and 248 aligned files**. The remaining polish row is the raw draft editor in `packages/ui/src/composer-message-queue.tsx`.
+- `WorkbarController` is now a real boundary at `apps/desktop/src/renderer/features/workbar/controller/use-workbar-controller.ts`, and `WorkbarHost` owns the rendered surface. The A3 direction below therefore landed; its old `session-workbar*` anchors no longer exist.
+- Module Hub, Goals, Task Entry, Session Navigation, Session Collaboration, and Workbar have feature boundaries below `AppShell`. `apps/desktop/renderer-architecture.json` still classifies `app-shell.tsx` as the `app-shell-integration-knot`; at 3,293 lines, the broader A1 concentration remains current.
+- Settings still accepts section requests through `use-settings-modal.ts`, persisted section state, and the `maka:jumpToSettingsSection` event in `settings-surface.tsx`. The A4 convergence remains planned.
+- `packages/ui/src/composer.tsx` is now 2,284 lines, so the A5 concentration remains current. The tool-output implementation named in A6 now lives in `packages/ui/src/tool-activity/tool-result-preview.tsx`.
+- Astryx patches are versioned with the installed dependency. `patches/README.md` is the stable authority; do not use the `0.3.0` filename from the historical table as a current path.
+
+Reproduce the current file-level result with `npm run astryx:surface-inventory`.
+
+## Executive verdict at the audited commit
 
 The product already has a **correct intended layering**:
 
@@ -45,7 +68,7 @@ Remaining risk is not “missing Buttons.” It is:
 
 ---
 
-## 1. Layering map (as shipped)
+## 1. Layering map at the audited commit
 
 ```
 Electron frame
@@ -84,7 +107,7 @@ Electron frame
 
 ---
 
-## 2. Architecture review (simplification / elevation)
+## 2. Architecture review at the audited commit
 
 Severity: **blocker** = structural cost that blocks every feature; **high** = clear multi-surface tax; **polish** = cleanups that can wait.
 
@@ -166,7 +189,7 @@ Severity: **blocker** = structural cost that blocks every feature; **high** = cl
 
 ---
 
-## 3. Astryx style / component coverage gaps
+## 3. Astryx style / component coverage gaps at the audited commit
 
 ### 3.1 Inventory baseline
 
@@ -208,7 +231,6 @@ These were **not** invent-from-whole-cloth “logo false positives” in the abs
 | **medium (P2)** | Keyboard help raw `<h3>` | `keyboard-help.tsx` | **Fixed** → `Heading level={3}` |
 | **medium (P2)** | Web tool result raw `<a>` | `tool-result-preview.tsx` | **Fixed** → Astryx `Link` |
 | **medium (P1/P2)** | Deep Research plate washes | `deep-research.css` | **Fixed** → wash tokens |
-| **medium (P2)** | Keyboard help raw `<h3>` | `keyboard-help.tsx` | `Heading` / `Text` |
 | **low (P3)** | Quote chip / remove / turn footer / lineage re-chrome Astryx Button | `packages/ui/src/styles.css`, `quote-ref-chip.tsx`, `chat-turn.tsx` | shrink overrides; prefer Badge/Token for lineage |
 | **low (P3)** | Workbar tab busy uses `Loader2` | `session-workbar.tsx` | `Spinner` if it means loading |
 
@@ -230,7 +252,7 @@ These were **not** invent-from-whole-cloth “logo false positives” in the abs
 | **intentional** | Tool/agent/web preview card chrome | `primitives/chat.tsx`, `styles.css` tool families | content DS, not form controls |
 | **intentional** | Chat empty heroes | `chat-empty-hero.tsx` | welcome surface ≠ EmptyState |
 | **intentional** | ChatReasoning lab eject | `astryx-chat-reasoning.tsx` | keep until stable peer |
-| **intentional** | Astryx patches | `patches/@astryxdesign+core+0.3.0.patch`, `patches/README.md` | conversationKey / tool row / List aria / UA-CH |
+| **intentional** | Astryx patches | `patches/README.md` and the dependency-versioned Astryx patch named there | conversationKey / tool row / List aria / UA-CH at the audited commit |
 
 ### 3.3 Loading kit sprawl (architecture × Astryx)
 
@@ -249,7 +271,7 @@ Empty/error largely share Astryx. **Loading** still has 6+ dialects:
 
 ---
 
-## 4. Prioritized backlog (actionable)
+## 4. Original prioritized backlog (historical)
 
 ### P0 — Architecture (no visual swap required)
 
@@ -298,7 +320,7 @@ Empty/error largely share Astryx. **Loading** still has 6+ dialects:
 
 ---
 
-## 5. Spot-check log (verification)
+## 5. Original spot-check log
 
 Claims re-checked on disk at review time:
 
@@ -317,7 +339,7 @@ Claims re-checked on disk at review time:
 
 ---
 
-## 6. Summary for decision-makers
+## 6. Summary recorded at the audited commit
 
 | Question | Answer |
 |----------|--------|
@@ -326,6 +348,6 @@ Claims re-checked on disk at review time:
 | Biggest remaining architectural win? | **De-god AppShell** (P0) — multi-week; not done in this pass. |
 | What to leave alone? | ChatReasoning eject, tool preview content cards, providers multi-level IA, residual quote/turn Button geometry until a dedicated chrome pass. |
 
-## 7. Implementation note (follow-up branch)
+## 7. Historical implementation note
 
 P1 elevation/wash, off-rhythm heights, and P2 Toolbar/Kbd/Heading/Link were implemented on branch `fix/astryx-review-debt-2026-08-09` after the analysis-only review. Architecture P0 (AppShell controllers) remains backlog.
diff --git a/docs/frontend-css-governance.md b/docs/frontend-css-governance.md
@@ -1,3 +1,14 @@
+---
+doc_id: frontend.css-governance
+title: "Frontend CSS governance"
+language: en
+source_language: en
+counterpart: ./frontend-css-governance.zh-CN.md
+implementation_status: current
+document_status: stable
+translation_status: synced
+last_verified: 2026-09-05
+---
 <!--
   Licensed to the Apache Software Foundation (ASF) under one
   or more contributor license agreements.  See the NOTICE file
@@ -21,53 +32,59 @@
 
 [中文](./frontend-css-governance.zh-CN.md)
 
-Maka's frontend styling combines Astryx, `@maka/ui` product compositions, and renderer surface CSS. Cascade order is an explicit contract rather than an implementation detail.
+Maka's frontend styling combines Astryx, `@maka/ui` product compositions, and renderer surface CSS. Cascade order is an explicit contract rather than an implementation detail. This document describes the current contract for contributors working in `apps/desktop/src/renderer/**` and `packages/ui/src/**`.
 
 ## 1. Entry file
 
 - `apps/desktop/src/renderer/styles.css` is an entry file only.
 - It may contain `@import` and other top-level orchestration statements.
 - New per-surface selector blocks belong in `apps/desktop/src/renderer/styles/**/*.css`.
-- Historical recipes at the end of `maka-tokens.css` and `reference-shell.css` are transitional exceptions. Do not add new surface rules to them.
+- `cascade-layers.css`, `maka-tokens.css`, and `reference-shell.css` are deliberate root-level exceptions. The first declares cascade order, the second owns shared renderer tokens and legacy recipes, and the third carries transitional shell compatibility. Do not add ordinary surface rules to them.
 
 ### Selector naming
 
-- Shared renderer and `@maka/ui` selectors use the kebab-case `.maka-*` dialect.
+- New selectors shared across renderer surfaces or exported by `@maka/ui` use the kebab-case `.maka-*` dialect.
 - The established `styles/settings/**` surface uses camelCase `.settings*` selectors. Keep that dialect for settings-local selectors instead of mixing both forms within one surface.
+- Feature-local namespaces already exist, including `.workhub-*`. Keep them local to their feature; do not turn them into a second cross-surface dialect. Legacy `.agents-*` and `.detailPane` names are compatibility debt, not examples for new selectors.
 - Moving existing settings selectors between concern files does not require a repository-wide rename; any future naming migration should be handled as an explicit compatibility change.
 
 ## 2. Layers
 
-- Pure presentation rules should use `@layer base` or `@layer components` where practical.
+- `apps/desktop/src/renderer/cascade-layers.css` is the single owner of the order: `reset`, `theme`, `base`, `astryx-components`, `astryx-tokens`, then `components`.
+- `styles.css` imports Astryx's neutral component sheet into `astryx-components`, the generated Maka theme into `astryx-tokens`, and `@maka/ui` plus renderer surfaces into `components`. `maka-tokens.css` declares its own `base` and `components` blocks.
+- Keep ordinary product presentation in `components`. Use another existing layer only when that layer owns the rule's semantics.
 - Use `@import "./file.css" layer(components)` only when the build chain explicitly supports it.
 - Do not place `@import` inside an `@layer` block.
 
-Astryx reset and component layers come first; Maka base tokens and product `components` come later. Keep layer ownership at the closest existing seam instead of adding a higher-priority compatibility layer.
+Keep layer ownership at the closest existing seam instead of adding a higher-priority compatibility layer. Do not reorder the declared layers from a surface stylesheet; a cascade-order change belongs in `cascade-layers.css` and needs rendered regression evidence.
 
-## 4. `!important`
+## 3. `!important`
 
-- `!important` is allowed by default only for accessibility helpers such as `.maka-visually-hidden`, and for reduced-motion or e2e-fixture overrides.
-- Every other use requires an adjacent `Justified:` comment.
+- Default exceptions are accessibility helpers such as `.maka-visually-hidden`, reduced-motion and e2e-fixture overrides, and the centralized native-cursor policy.
+- Narrow compatibility and product overrides remain in `reference-shell.css`, `styles/settings/usage.css`, and `packages/ui/src/styles.css`. They are explicit debt or bounded component fixes, not precedent for another override.
+- Every new use outside the default exceptions needs an adjacent comment that names the competing rule, explains why the normal component or layer seam cannot express the fix, and states when the override can be removed. `Justified:` is the conventional marker.
 - Prefer fixing the primitive API or semantic class when it can express the behavior directly.
 
-## 5. Tokens
+## 4. Tokens
 
-- Shared custom properties belong in `apps/desktop/src/renderer/maka-tokens.css`.
-- Component-local properties are allowed only with a `/* local: ... */` comment.
-- Do not add raw colors, radii, or ungoverned z-index values.
+- Shared renderer custom properties belong in `apps/desktop/src/renderer/maka-tokens.css`.
+- `apps/desktop/src/renderer/astryx-theme/maka.css` is generated by `npm run astryx:theme`; do not edit it by hand.
+- Component-local properties are allowed only near their owner with a `/* local: ... */` comment.
+- Do not add raw colors for semantic roles, one-off radii that duplicate the radius ladder, or ungoverned z-index values. Literal geometry is acceptable only when it describes a local measured constraint rather than a reusable design role.
 
-## 6. How these rules are checked
+## 5. How these rules are checked
 
 These rules are conventions enforced in review. Static correctness belongs to
 Biome, Knip, and typecheck; accessibility keeps its focused check. CSS usage and
 Story prose are not decided by repository-wide regex baselines.
 
+- `npm run astryx:surface-inventory` verifies that the generated surface inventory matches disk and fails on new raw interactive-control blockers. It does not prove the entire CSS governance contract.
 - Renderer CSS behavior is verified where it renders: Storybook, the app, or an
   e2e assertion on the real surface.
 - Remove selectors with the source or surface that owned them instead of
   maintaining an allowlist of strings that may be generated at runtime.
 
-## 7. Change order
+## 6. Change order
 
 When changing renderer CSS:
 
@@ -76,8 +93,9 @@ When changing renderer CSS:
 3. Remove dead selectors.
 4. Remove remaining `!important` only after primitive and layer ownership is stable.
 
-## 8. Governing principles
+## 7. Governing principles
 
+- Keep the CI guardrails credible before using their green result as evidence for structural work.
 - Delete dead CSS before aesthetic refactoring.
 - Resolve shared `Button`, `Textarea`, and `EmptyState` overrides at the component API seam instead of accumulating renderer specificity.
 - Every change to cascade order requires the narrowest relevant regression check on the rendered surface.