@hegemonart/get-design-done 1.42.0 → 1.44.0

package/reference/platforms.md

@@ -1,60 +1,60 @@
-# Platforms — Reference Guide
+# Platforms - Reference Guide
 
-Platform conventions are not arbitrary constraints — they are the accumulated result of billions of user interactions on each operating system. When a designer deviates from a platform convention, they are implicitly asking their user to unlearn a trained reflex and replace it with a novel one specific to this product. That is expensive. This reference establishes the canonical interaction patterns, layout rules, gesture vocabularies, and component conventions for each platform the get-design-done framework targets, along with the governing rule for when brand expression should yield to platform habit and when it should not.
+Platform conventions are not arbitrary constraints - they are the accumulated result of billions of user interactions on each operating system. When a designer deviates from a platform convention, they are implicitly asking their user to unlearn a trained reflex and replace it with a novel one specific to this product. That is expensive. This reference establishes the canonical interaction patterns, layout rules, gesture vocabularies, and component conventions for each platform the get-design-done framework targets, along with the governing rule for when brand expression should yield to platform habit and when it should not.
 
 ---
 
 ## 1. Navigation Patterns by Platform
 
-Navigation is the skeleton of a product. Getting it wrong does not just inconvenience users — it makes the entire product feel alien on its own operating system. Each platform has developed a navigation idiom that users practice dozens of times per day across every app on the device. A product that violates that idiom creates friction on every single screen transition.
+Navigation is the skeleton of a product. Getting it wrong does not just inconvenience users - it makes the entire product feel alien on its own operating system. Each platform has developed a navigation idiom that users practice dozens of times per day across every app on the device. A product that violates that idiom creates friction on every single screen transition.
 
 ### iOS
 
-iOS navigation is built on a two-axis model: vertical hierarchy (drilling into content via a navigation stack managed by `UINavigationController` or SwiftUI's `NavigationStack`) and lateral switching (jumping between top-level sections via a `UITabBarController` or SwiftUI's `TabView`). The tab bar lives at the bottom of the screen and should contain between two and five destinations. Apple's Human Interface Guidelines are explicit that five tabs is the maximum — adding a sixth requires a "More" overflow pattern, which is a recognized user experience penalty.
+iOS navigation is built on a two-axis model: vertical hierarchy (drilling into content via a navigation stack managed by `UINavigationController` or SwiftUI's `NavigationStack`) and lateral switching (jumping between top-level sections via a `UITabBarController` or SwiftUI's `TabView`). The tab bar lives at the bottom of the screen and should contain between two and five destinations. Apple's Human Interface Guidelines are explicit that five tabs is the maximum - adding a sixth requires a "More" overflow pattern, which is a recognized user experience penalty.
 
-The navigation bar at the top of the screen carries the current screen title and back button. The back button is automatically generated by the navigation stack with the title of the previous screen as its label when space permits, falling back to the word "Back." Never replace the system back button with a custom left-side icon that performs a different action — this violates user expectation so severely that it creates support tickets.
+The navigation bar at the top of the screen carries the current screen title and back button. The back button is automatically generated by the navigation stack with the title of the previous screen as its label when space permits, falling back to the word "Back." Never replace the system back button with a custom left-side icon that performs a different action - this violates user expectation so severely that it creates support tickets.
 
 Hamburger menus (three-line "sandwich" icons triggering a side drawer) are a web and Android import. They are not idiomatic iOS and should not appear in native iOS apps. If a product has more destinations than five tabs can accommodate, the correct iOS solution is to reconsider the information architecture, not to add a drawer. Drawers exist in some iOS apps, but they are third-party patterns tolerated for legacy reasons, not blessed conventions.
 
 ### Android
 
-Android follows Material 3's navigation component system. The bottom navigation bar serves the same function as iOS's tab bar — lateral switching between top-level destinations — and should contain three to five destinations. Material 3 introduced the navigation rail as the preferred navigation surface on medium-width screens (tablets, foldables in unfolded state), where it appears as a vertical column of icons and labels on the leading edge of the layout. On large screens (desktop-class Android, Chromebook), a navigation drawer — either modal or persistent — replaces the rail.
+Android follows Material 3's navigation component system. The bottom navigation bar serves the same function as iOS's tab bar - lateral switching between top-level destinations - and should contain three to five destinations. Material 3 introduced the navigation rail as the preferred navigation surface on medium-width screens (tablets, foldables in unfolded state), where it appears as a vertical column of icons and labels on the leading edge of the layout. On large screens (desktop-class Android, Chromebook), a navigation drawer - either modal or persistent - replaces the rail.
 
 The system back gesture on Android is an edge swipe from either the left or right side of the screen. Since Android 10 this is the system default, replacing the software back button in gesture navigation mode. Designs must never shadow this gesture with in-app behavior, because the OS intercepts it before the app's gesture recognizers fire. The back gesture always navigates up in the activity/fragment back stack or returns to the launcher; no design override is possible or appropriate.
 
 ### Web
 
-Web navigation has three dominant patterns, each suited to a different information architecture scale. Top navigation bars work for sites with five to eight primary sections whose names fit comfortably in a single horizontal row. Sidebars are the standard for application-density products (dashboards, admin tools, documentation sites) because they accommodate ten to thirty labeled destinations without cognitive overload, and they scale with the viewport rather than breaking. Mega-menus — large overlay panels triggered by hovering or clicking a top-nav item — suit e-commerce and marketing sites where category hierarchies are deep but users need cross-category discovery on every page.
+Web navigation has three dominant patterns, each suited to a different information architecture scale. Top navigation bars work for sites with five to eight primary sections whose names fit comfortably in a single horizontal row. Sidebars are the standard for application-density products (dashboards, admin tools, documentation sites) because they accommodate ten to thirty labeled destinations without cognitive overload, and they scale with the viewport rather than breaking. Mega-menus - large overlay panels triggered by hovering or clicking a top-nav item - suit e-commerce and marketing sites where category hierarchies are deep but users need cross-category discovery on every page.
 
-The command palette, triggered by `Cmd+K` (macOS) or `Ctrl+K` (Windows/Linux), has become the power-user navigation layer for application-dense web products. It is not a replacement for structural navigation — it is an accelerator for users who already know where they want to go. Implementing a command palette without maintaining the sidebar or top nav for discoverability is a mistake; command palettes serve learners and experts differently, and both populations need to be served simultaneously.
+The command palette, triggered by `Cmd+K` (macOS) or `Ctrl+K` (Windows/Linux), has become the power-user navigation layer for application-dense web products. It is not a replacement for structural navigation - it is an accelerator for users who already know where they want to go. Implementing a command palette without maintaining the sidebar or top nav for discoverability is a mistake; command palettes serve learners and experts differently, and both populations need to be served simultaneously.
 
 ### visionOS
 
-visionOS inhabits three-dimensional space, and its navigation conventions emerge from the affordances of spatial UI. Users look around and glance at windows rather than tapping a nav bar, so the concept of a persistent bottom bar — physically below the user's comfortable resting gaze — is inappropriate. Apple's spatial design guidelines introduce orbital menus: radial arrangements of controls that anchor to content and appear at the periphery of a window when activated, keeping the central content area unobstructed.
+visionOS inhabits three-dimensional space, and its navigation conventions emerge from the affordances of spatial UI. Users look around and glance at windows rather than tapping a nav bar, so the concept of a persistent bottom bar - physically below the user's comfortable resting gaze - is inappropriate. Apple's spatial design guidelines introduce orbital menus: radial arrangements of controls that anchor to content and appear at the periphery of a window when activated, keeping the central content area unobstructed.
 
-Window grouping is the visionOS analog of tab groups. Related windows can be positioned in the user's space as a coherent cluster, and the user navigates between them by glancing and reaching. The design implication is that each window should be self-sufficient and not require persistent navigation chrome — navigation is spatial rather than embedded in a UI surface. Because users can position windows anywhere in their environment, designers cannot rely on spatial relationships that were composed in the design tool; design for each window independently, not for a composed layout.
+Window grouping is the visionOS analog of tab groups. Related windows can be positioned in the user's space as a coherent cluster, and the user navigates between them by glancing and reaching. The design implication is that each window should be self-sufficient and not require persistent navigation chrome - navigation is spatial rather than embedded in a UI surface. Because users can position windows anywhere in their environment, designers cannot rely on spatial relationships that were composed in the design tool; design for each window independently, not for a composed layout.
 
 ### watchOS
 
-watchOS navigation is scroll-first. The primary navigation surface is a scrollable list — the watch equivalent of a `UITableView` — optimized for the Digital Crown, which provides physical momentum scrolling. Users expect to scroll down to see more content on the current screen and to use the Digital Crown as the primary navigation gesture for list content. Tapping the Digital Crown navigates to the watch face; this gesture is reserved by the OS and cannot be shadowed.
+watchOS navigation is scroll-first. The primary navigation surface is a scrollable list - the watch equivalent of a `UITableView` - optimized for the Digital Crown, which provides physical momentum scrolling. Users expect to scroll down to see more content on the current screen and to use the Digital Crown as the primary navigation gesture for list content. Tapping the Digital Crown navigates to the watch face; this gesture is reserved by the OS and cannot be shadowed.
 
-Nested navigation should never exceed two levels on watchOS. The small screen area and the awkward input model (small touch targets, no text input without Siri) mean that deep navigation hierarchies become traps — users lose orientation and cannot easily escape. If a feature cannot be expressed in two navigation levels or fewer, it is too complex for watchOS and should be redesigned or moved to the companion iOS app.
+Nested navigation should never exceed two levels on watchOS. The small screen area and the awkward input model (small touch targets, no text input without Siri) mean that deep navigation hierarchies become traps - users lose orientation and cannot easily escape. If a feature cannot be expressed in two navigation levels or fewer, it is too complex for watchOS and should be redesigned or moved to the companion iOS app.
 
 ### Cross-Platform Consistency: Convention vs. Brand
 
 The governing rule for resolving the tension between platform convention and brand identity is this: **follow the platform for navigation, interaction patterns, and component behavior; apply the brand to color, typography scale, iconography, and illustration.** A user who encounters a bottom tab bar on iOS and a bottom navigation bar on Android is experiencing appropriate platform adaptation, not inconsistent branding. A user who encounters a custom gesture that conflicts with the OS back gesture is experiencing a design error, regardless of how on-brand the interaction felt in the design tool.
 
-Brand consistency lives in the visual layer — your colors, type choices, illustration style, and motion language should be recognizable across platforms without requiring you to break platform idioms to achieve them. When a component does not exist in your design system for a given platform (for example, a native alert dialog on iOS vs. Android), the correct approach is to adapt the component to the platform's idiom while keeping the copy, color, and brand voice consistent.
+Brand consistency lives in the visual layer - your colors, type choices, illustration style, and motion language should be recognizable across platforms without requiring you to break platform idioms to achieve them. When a component does not exist in your design system for a given platform (for example, a native alert dialog on iOS vs. Android), the correct approach is to adapt the component to the platform's idiom while keeping the copy, color, and brand voice consistent.
 
 ---
 
 ## 2. Safe Areas and Layout Margins
 
-Every modern mobile platform introduces areas of the display where UI elements should not appear: behind the status bar, under the home indicator, behind the camera cutout, or outside the circular mask of a watch. Ignoring safe areas does not merely produce visual bugs — it can make controls unreachable or occluded in ways that break the product for large segments of users.
+Every modern mobile platform introduces areas of the display where UI elements should not appear: behind the status bar, under the home indicator, behind the camera cutout, or outside the circular mask of a watch. Ignoring safe areas does not merely produce visual bugs - it can make controls unreachable or occluded in ways that break the product for large segments of users.
 
 ### iOS: Notch, Dynamic Island, and Home Indicator
 
-Since the iPhone X, iOS devices have a camera housing at the top of the display — originally the notch, now the Dynamic Island on newer devices — and a home indicator bar at the bottom. iOS exposes these as safe area insets, accessible in CSS via the environment function:
+Since the iPhone X, iOS devices have a camera housing at the top of the display - originally the notch, now the Dynamic Island on newer devices - and a home indicator bar at the bottom. iOS exposes these as safe area insets, accessible in CSS via the environment function:
 
 ```css
 padding-top: env(safe-area-inset-top);
@@ -69,7 +69,7 @@ For web content rendered in a WKWebView or Safari on iOS, the viewport meta tag
 <meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover">
 ```
 
-The home indicator at the bottom of the display on Face ID devices occupies approximately 34 points. Any interactive controls placed at the very bottom of the screen — primary action buttons, persistent toolbars, bottom sheets — must clear the home indicator. The system automatically applies the inset for native UIKit and SwiftUI layouts, but web-in-WebView requires the CSS above. Failing to handle the bottom inset is the single most common iOS layout bug in hybrid apps.
+The home indicator at the bottom of the display on Face ID devices occupies approximately 34 points. Any interactive controls placed at the very bottom of the screen - primary action buttons, persistent toolbars, bottom sheets - must clear the home indicator. The system automatically applies the inset for native UIKit and SwiftUI layouts, but web-in-WebView requires the CSS above. Failing to handle the bottom inset is the single most common iOS layout bug in hybrid apps.
 
 ### Android: Status Bar, Navigation Bar, and Edge-to-Edge
 
@@ -77,7 +77,7 @@ Android has enforced edge-to-edge rendering as the default since Android 15. Pri
 
 Android exposes insets through `WindowInsetsCompat` in the Jetpack library. In Jetpack Compose, the `safeDrawing` inset padding modifier handles the most common cases. For React Native and Flutter apps targeting Android, the platform bridge handles inset forwarding, but custom navigation bars or bottom sheets still require explicit inset consumption.
 
-The system gesture navigation bar at the bottom of the screen is transparent by default on Android 10 and later, showing the app content beneath it. This means a white bottom sheet on a white background will appear to have no bottom boundary — the bar blends in. The design solution is to draw content under the bar (which Android encourages) while ensuring the bottommost interactive control is above the gesture exclusion zone, which is approximately 30dp from the bottom edge.
+The system gesture navigation bar at the bottom of the screen is transparent by default on Android 10 and later, showing the app content beneath it. This means a white bottom sheet on a white background will appear to have no bottom boundary - the bar blends in. The design solution is to draw content under the bar (which Android encourages) while ensuring the bottommost interactive control is above the gesture exclusion zone, which is approximately 30dp from the bottom edge.
 
 ### Web: Viewport Units and Browser Chrome Behavior
 
@@ -87,10 +87,10 @@ The correct unit is `dvh` (dynamic viewport height), introduced in the CSS Value
 
 | Unit | Resolves to | Use case |
 |------|-------------|----------|
-| `100vh` | Static — initial viewport height, ignores chrome | Avoid on mobile; use for desktop |
-| `100dvh` | Dynamic — updates as browser chrome shows/hides | Default choice for full-height mobile layouts |
-| `100svh` | Static — smallest possible viewport (chrome fully visible) | Fixed bottom bars that should never resize |
-| `100lvh` | Static — largest possible viewport (chrome fully hidden) | Hero sections that expand when chrome hides |
+| `100vh` | Static - initial viewport height, ignores chrome | Avoid on mobile; use for desktop |
+| `100dvh` | Dynamic - updates as browser chrome shows/hides | Default choice for full-height mobile layouts |
+| `100svh` | Static - smallest possible viewport (chrome fully visible) | Fixed bottom bars that should never resize |
+| `100lvh` | Static - largest possible viewport (chrome fully hidden) | Hero sections that expand when chrome hides |
 
 ### watchOS: Circular Display Mask
 
@@ -100,7 +100,7 @@ The Apple Watch display has rounded corners and a circular mask that clips conte
 
 ## 3. Gesture Vocabularies
 
-Gestures are the physical language of a platform. Each operating system has reserved certain gestures for system-level navigation, and these reservations cannot be overridden by applications — the OS claims them before the app's gesture recognizers run. Shadowing a reserved gesture does not produce a conflict; it produces a silent failure where the user's intended in-app action triggers the system behavior instead, and the app gesture is never received.
+Gestures are the physical language of a platform. Each operating system has reserved certain gestures for system-level navigation, and these reservations cannot be overridden by applications - the OS claims them before the app's gesture recognizers run. Shadowing a reserved gesture does not produce a conflict; it produces a silent failure where the user's intended in-app action triggers the system behavior instead, and the app gesture is never received.
 
 ### iOS Gesture Reservations
 
@@ -108,31 +108,31 @@ The most critical reserved gesture on iOS is the **swipe from the left edge of t
 
 **Swipe down from the top of the screen** opens Notification Center. On Face ID devices, swiping down from the upper-left opens Notification Center and swiping down from the upper-right opens Control Center. Custom pull-to-refresh gestures that begin at the very top of the screen work because they begin from within the scrollable content area, not from the status bar region.
 
-**Long press** on iOS surfaces context menus (UIContextMenu) or enters wiggle mode on home screen icons. In-app long press for custom behavior is acceptable as long as it is not the primary or only affordance for a critical action — users cannot discover long-press affordances without experimentation, so any feature requiring long press must also be reachable through a visible control.
+**Long press** on iOS surfaces context menus (UIContextMenu) or enters wiggle mode on home screen icons. In-app long press for custom behavior is acceptable as long as it is not the primary or only affordance for a critical action - users cannot discover long-press affordances without experimentation, so any feature requiring long press must also be reachable through a visible control.
 
 **Pinch** zooms content in maps, images, and text. Applications can use pinch for custom scaling behaviors within a content view, but pinch should not be used as a navigation trigger (e.g., pinch to go back) because it conflicts with system-level zoom accessibility features.
 
-**Force Touch / Haptic Touch** (long press with haptic response) is the iOS mechanism for quick actions and peek. It is available on all modern iOS devices. Use UIContextMenuInteraction for this behavior rather than attempting to detect touch pressure manually — the system API handles the haptic response and the visual presentation.
+**Force Touch / Haptic Touch** (long press with haptic response) is the iOS mechanism for quick actions and peek. It is available on all modern iOS devices. Use UIContextMenuInteraction for this behavior rather than attempting to detect touch pressure manually - the system API handles the haptic response and the visual presentation.
 
 ### Android Gesture Reservations
 
-The **edge swipe from either the left or right side of the screen** navigates back in the activity stack. This is identical in function to iOS's left-edge swipe but applies to both edges on Android. Applications can declare gesture exclusion rectangles — specific screen regions where the app claims swipe gestures — but these are limited to a maximum height of 200dp per region and cannot occupy the full screen height. Use gesture exclusion only for essential in-app swipe interactions like sliders and carousels that are positioned near the screen edge.
+The **edge swipe from either the left or right side of the screen** navigates back in the activity stack. This is identical in function to iOS's left-edge swipe but applies to both edges on Android. Applications can declare gesture exclusion rectangles - specific screen regions where the app claims swipe gestures - but these are limited to a maximum height of 200dp per region and cannot occupy the full screen height. Use gesture exclusion only for essential in-app swipe interactions like sliders and carousels that are positioned near the screen edge.
 
 **Swipe up from the bottom** opens the app launcher/home screen or enters recents mode, depending on how far the swipe extends. This gesture cannot be intercepted or overridden by applications. Bottom sheets that need to be dragged upward must begin from a handle or content area clearly above the system gesture zone.
 
-**Long press** on Android surfaces the contextual action menu and is widely used for multi-select patterns. Applications using long press for multi-select should follow Material Design's contextual action bar pattern — replacing the top app bar with an action bar that shows selection actions and a count of selected items.
+**Long press** on Android surfaces the contextual action menu and is widely used for multi-select patterns. Applications using long press for multi-select should follow Material Design's contextual action bar pattern - replacing the top app bar with an action bar that shows selection actions and a count of selected items.
 
 ### Web Gesture Considerations
 
 Web applications run inside a browser, which itself manages scroll, zoom, and navigation gestures. The `touch-action` CSS property allows web applications to declare which gestures they handle natively, preventing the browser from consuming those gestures. For a swipeable carousel, setting `touch-action: pan-y` tells the browser to handle vertical scrolling and pass horizontal swipes to the app's event listeners.
 
-**Two-finger scroll** on trackpads and touchscreens is reserved for page scrolling and cannot be reliably shadowed for in-app use. Horizontal two-finger swipe in browsers navigates browser history (back/forward). Applications that use horizontal swipe for in-content navigation should be aware that this gesture will also trigger history navigation on some browser/OS combinations — a usability bug that is difficult to resolve without harming native browser back behavior.
+**Two-finger scroll** on trackpads and touchscreens is reserved for page scrolling and cannot be reliably shadowed for in-app use. Horizontal two-finger swipe in browsers navigates browser history (back/forward). Applications that use horizontal swipe for in-content navigation should be aware that this gesture will also trigger history navigation on some browser/OS combinations - a usability bug that is difficult to resolve without harming native browser back behavior.
 
 ### visionOS Gesture Vocabulary
 
-visionOS uses eye tracking combined with hand gestures. The primary interaction is look-and-tap: the user looks at a control (which highlights with a hover effect driven by eye tracking) and then performs a pinch gesture with thumb and index finger to activate it. Spatial pinch is the visionOS equivalent of a mouse click and should be treated as such — buttons and interactive controls designed for iOS translate directly.
+visionOS uses eye tracking combined with hand gestures. The primary interaction is look-and-tap: the user looks at a control (which highlights with a hover effect driven by eye tracking) and then performs a pinch gesture with thumb and index finger to activate it. Spatial pinch is the visionOS equivalent of a mouse click and should be treated as such - buttons and interactive controls designed for iOS translate directly.
 
-**Drag** is performed by looking at a draggable element, pinching to grab, and moving the hand. Applications should not create drag interactions that require precise or sustained hand movement — the physical effort is significantly higher than a mouse drag, and prolonged gestures cause arm fatigue.
+**Drag** is performed by looking at a draggable element, pinching to grab, and moving the hand. Applications should not create drag interactions that require precise or sustained hand movement - the physical effort is significantly higher than a mouse drag, and prolonged gestures cause arm fatigue.
 
 ### watchOS Gesture Vocabulary
 
@@ -146,17 +146,17 @@ The **Digital Crown** rotation is the signature watchOS input. It scrolls lists,
 
 ## 4. Platform-Specific Component Conventions
 
-Components carry platform affordances encoded in their shape, behavior, and position. Using the wrong component variant on a given platform is not merely a visual inconsistency — it communicates a different action or intent to the user because the component's meaning is partially derived from its platform context.
+Components carry platform affordances encoded in their shape, behavior, and position. Using the wrong component variant on a given platform is not merely a visual inconsistency - it communicates a different action or intent to the user because the component's meaning is partially derived from its platform context.
 
 ### Action Sheet vs. Bottom Sheet
 
-On iOS, the action sheet (`UIActionSheet`, or `actionSheet` in SwiftUI) presents a set of choices related to the current context, anchored to the bottom of the screen on iPhone and presented as a popover on iPad. Action sheets are for choosing between a set of actions — they are not for arbitrary content. The Cancel button is always present at the bottom of the sheet and is the escape route.
+On iOS, the action sheet (`UIActionSheet`, or `actionSheet` in SwiftUI) presents a set of choices related to the current context, anchored to the bottom of the screen on iPhone and presented as a popover on iPad. Action sheets are for choosing between a set of actions - they are not for arbitrary content. The Cancel button is always present at the bottom of the sheet and is the escape route.
 
-On Android, the equivalent is the modal bottom sheet from Material Design. It serves a broader role than the iOS action sheet: it can contain lists of actions, but also form fields, detail content, or navigation. The Android bottom sheet does not have a mandatory Cancel button in the same position; instead, it is dismissed by tapping the scrim outside or by dragging it down. This behavioral difference means designs cannot be directly translated — an iOS action sheet with a prominent Cancel button will look wrong on Android because the dismiss convention differs.
+On Android, the equivalent is the modal bottom sheet from Material Design. It serves a broader role than the iOS action sheet: it can contain lists of actions, but also form fields, detail content, or navigation. The Android bottom sheet does not have a mandatory Cancel button in the same position; instead, it is dismissed by tapping the scrim outside or by dragging it down. This behavioral difference means designs cannot be directly translated - an iOS action sheet with a prominent Cancel button will look wrong on Android because the dismiss convention differs.
 
 ### Alert Dialog vs. Dialog
 
-An iOS `UIAlertController` in alert style is a small centered dialog with a title, message, and up to two action buttons. When there are more than two actions, use the action sheet instead — the iOS alert is intentionally constrained to binary decisions. Alert dialogs block all interaction until dismissed.
+An iOS `UIAlertController` in alert style is a small centered dialog with a title, message, and up to two action buttons. When there are more than two actions, use the action sheet instead - the iOS alert is intentionally constrained to binary decisions. Alert dialogs block all interaction until dismissed.
 
 Android's AlertDialog from Material Design is visually similar but accepts up to three buttons (positive, negative, neutral) and supports more complex layouts including dividers and scrollable content. The Android dialog also uses stronger typographic hierarchy than iOS alerts, following Material's `Title/Body/Actions` pattern explicitly.
 
@@ -164,7 +164,7 @@ Neither platform's alert dialog is appropriate for complex content, form input,
 
 ### iOS Segmented Control vs. Android Tab Row
 
-The iOS segmented control is a compact selector for switching between two to five mutually exclusive views or modes. It appears inline in the content area or in navigation bars, and its selection is reflected immediately — it is not a submit-style control. The segmented control is visually contained within a pill shape and does not have separate tab indicator lines.
+The iOS segmented control is a compact selector for switching between two to five mutually exclusive views or modes. It appears inline in the content area or in navigation bars, and its selection is reflected immediately - it is not a submit-style control. The segmented control is visually contained within a pill shape and does not have separate tab indicator lines.
 
 Android's equivalent is the Tab layout from Material Design, which uses underline indicators on a row of text labels. Material 3 distinguishes between primary tabs (page-level navigation) and secondary tabs (content filtering within a page). The visual language is different enough that using an iOS segmented control design on Android will read as foreign. Design platform-specific variants for each; share only the component's logic and data model.
 
@@ -178,11 +178,11 @@ Android's Material Design switch uses the same horizontal sliding metaphor but h
 
 A web modal dialog (the HTML `<dialog>` element, or a custom overlay) blocks page interaction behind a scrim and centers a card in the viewport. It is the correct choice for confirmations, forms that require focus, and content previews when the user needs to complete or dismiss a task before continuing. Web modals work on both mouse and touch interfaces because they do not depend on the physical affordance of dragging a sheet from a panel edge.
 
-Native bottom sheets (half-modal sheets in iOS, bottom sheets in Android) are appropriate for mobile-width layouts where the card anchored to the screen bottom provides a tactile affordance — users can drag the sheet down to dismiss it. On web, native sheet behavior can be approximated with CSS transitions and touch event handling, but it requires explicit engineering to match the physics of the native implementation. Reserve the sheet pattern for mobile web experiences; use centered modals for desktop web where sheets feel out of place.
+Native bottom sheets (half-modal sheets in iOS, bottom sheets in Android) are appropriate for mobile-width layouts where the card anchored to the screen bottom provides a tactile affordance - users can drag the sheet down to dismiss it. On web, native sheet behavior can be approximated with CSS transitions and touch event handling, but it requires explicit engineering to match the physics of the native implementation. Reserve the sheet pattern for mobile web experiences; use centered modals for desktop web where sheets feel out of place.
 
 ### visionOS: Ornaments vs. Toolbars
 
-visionOS introduces the concept of ornaments — UI elements that appear to float outside the boundary of a window, anchored to its edge. The primary toolbar of a visionOS window should be placed in an ornament rather than inside the window's content area. This keeps the window's content area clean and takes advantage of the spatial depth available in visionOS to create a sense of UI layering. Toolbars inside windows flatten the spatial affordance of the platform and feel like web content rather than native visionOS design.
+visionOS introduces the concept of ornaments - UI elements that appear to float outside the boundary of a window, anchored to its edge. The primary toolbar of a visionOS window should be placed in an ornament rather than inside the window's content area. This keeps the window's content area clean and takes advantage of the spatial depth available in visionOS to create a sense of UI layering. Toolbars inside windows flatten the spatial affordance of the platform and feel like web content rather than native visionOS design.
 
 SwiftUI surfaces ornaments through the `.ornament` modifier, which anchors to a specified edge of the window at a specified offset. The recommended pattern is to place navigation controls (back, close, minimize) and contextual actions (edit, share, refresh) in an ornament anchored to the bottom or leading edge of the content window.
 
@@ -190,15 +190,15 @@ SwiftUI surfaces ornaments through the `.ornament` modifier, which anchors to a
 
 ## 5. Native Typography
 
-Platform typography is not merely a default font choice — it is a system of optical sizes, weights, tracking values, and dynamic scaling behaviors that the platform vendor has spent years calibrating for their display hardware. Using the native type system correctly means the product's text will look and respond identically to text in the OS and every other native app, which is the baseline users calibrate their reading experience against.
+Platform typography is not merely a default font choice - it is a system of optical sizes, weights, tracking values, and dynamic scaling behaviors that the platform vendor has spent years calibrating for their display hardware. Using the native type system correctly means the product's text will look and respond identically to text in the OS and every other native app, which is the baseline users calibrate their reading experience against.
 
 ### iOS: SF Pro, SF Rounded, and SF Compact
 
-San Francisco (SF Pro) is the system typeface on iOS, macOS, and visionOS. It is a variable-weight sans-serif with separate Display (for text above approximately 20pt) and Text (for text at and below 20pt) optical sizes. The Display variant has tighter tracking optimized for large sizes; the Text variant has slightly looser tracking optimized for readability at small sizes. The transition between them happens automatically when using Apple's dynamic text styles — it does not happen automatically for custom font sizes, which is why specifying `UIFont.systemFont(ofSize:)` with sizes above 20pt while in a small-text context will produce tracking that looks subtly wrong.
+San Francisco (SF Pro) is the system typeface on iOS, macOS, and visionOS. It is a variable-weight sans-serif with separate Display (for text above approximately 20pt) and Text (for text at and below 20pt) optical sizes. The Display variant has tighter tracking optimized for large sizes; the Text variant has slightly looser tracking optimized for readability at small sizes. The transition between them happens automatically when using Apple's dynamic text styles - it does not happen automatically for custom font sizes, which is why specifying `UIFont.systemFont(ofSize:)` with sizes above 20pt while in a small-text context will produce tracking that looks subtly wrong.
 
 SF Rounded is an alternate variant with softened terminals, appropriate for friendly or playful product tones. SF Mono is the monospaced variant, intended for code display, terminal output, and data values that must align in columns.
 
-Dynamic Type is Apple's system for user-controlled text scaling. Users can set their preferred text size in Settings > Accessibility, which scales all text using the Dynamic Type styles up to a maximum multiplier of approximately 3×. Every text style in an iOS app should use a named Dynamic Type style (`UIFont.TextStyle` or SwiftUI's `.font(.body)`, `.font(.headline)`) to participate in this scaling. Never use text below 11pt at any Dynamic Type setting — below 11pt, letters collapse to the point of illegibility even on Retina displays. The minimum label size to target under standard accessibility settings is 13pt for body text, growing to as much as 53pt under the largest accessibility text size.
+Dynamic Type is Apple's system for user-controlled text scaling. Users can set their preferred text size in Settings > Accessibility, which scales all text using the Dynamic Type styles up to a maximum multiplier of approximately 3×. Every text style in an iOS app should use a named Dynamic Type style (`UIFont.TextStyle` or SwiftUI's `.font(.body)`, `.font(.headline)`) to participate in this scaling. Never use text below 11pt at any Dynamic Type setting - below 11pt, letters collapse to the point of illegibility even on Retina displays. The minimum label size to target under standard accessibility settings is 13pt for body text, growing to as much as 53pt under the largest accessibility text size.
 
 The canonical Dynamic Type scale for iOS, at the default (large) system text size:
 
@@ -271,23 +271,23 @@ watchOS uses SF Compact, a narrower optical variant of San Francisco designed fo
 
 ## 6. Haptic Feedback
 
-Haptics are the tactile confirmation layer of mobile interfaces. They are the difference between an interface that feels alive under the finger and one that feels like touching a pane of glass. Used correctly, haptics confirm actions, communicate state transitions, and orient the user within a physical gesture. Used incorrectly — too frequently, too intensely, or for decorative purposes — they become noise that users disable in Settings, removing an entire feedback channel.
+Haptics are the tactile confirmation layer of mobile interfaces. They are the difference between an interface that feels alive under the finger and one that feels like touching a pane of glass. Used correctly, haptics confirm actions, communicate state transitions, and orient the user within a physical gesture. Used incorrectly - too frequently, too intensely, or for decorative purposes - they become noise that users disable in Settings, removing an entire feedback channel.
 
 ### iOS: Taptic Engine
 
 Apple's Taptic Engine is the haptic actuator present in all iPhones from iPhone 6s onward. iOS exposes three distinct haptic feedback APIs, each for a different use case.
 
-`UIImpactFeedbackGenerator` communicates the physical metaphor of an impact — two objects colliding. It offers three styles: `.light`, `.medium`, and `.heavy`, corresponding to the perceived mass of the collision. Light is appropriate for small UI events like toggles and minor selections; medium for confirmations and modal presentations; heavy for destructive actions and notifications that demand attention. Use this generator when the user's action has a direct, immediate effect and you want to confirm the moment of contact.
+`UIImpactFeedbackGenerator` communicates the physical metaphor of an impact - two objects colliding. It offers three styles: `.light`, `.medium`, and `.heavy`, corresponding to the perceived mass of the collision. Light is appropriate for small UI events like toggles and minor selections; medium for confirmations and modal presentations; heavy for destructive actions and notifications that demand attention. Use this generator when the user's action has a direct, immediate effect and you want to confirm the moment of contact.
 
-`UINotificationFeedbackGenerator` communicates the outcome of a completed process. It has three types: `.success`, `.warning`, and `.error`. These should always be paired with their corresponding visual state change — a haptic success without a visible success state is confusing, and a haptic error without a visible error state is alarming without explanation. Do not use notification feedback for routine actions; reserve it for operations with binary outcomes that the user needs to know about.
+`UINotificationFeedbackGenerator` communicates the outcome of a completed process. It has three types: `.success`, `.warning`, and `.error`. These should always be paired with their corresponding visual state change - a haptic success without a visible success state is confusing, and a haptic error without a visible error state is alarming without explanation. Do not use notification feedback for routine actions; reserve it for operations with binary outcomes that the user needs to know about.
 
-`UISelectionFeedbackGenerator` communicates movement through a series of items — a picker wheel advancing one position, a slider snapping to a value. It produces a subtle rhythmic tick that matches the cadence of physical detents on a mechanical dial. Use it only for continuous selection gestures, not for discrete button taps.
+`UISelectionFeedbackGenerator` communicates movement through a series of items - a picker wheel advancing one position, a slider snapping to a value. It produces a subtle rhythmic tick that matches the cadence of physical detents on a mechanical dial. Use it only for continuous selection gestures, not for discrete button taps.
 
 The governing rule for iOS haptics is to trigger them from changes the user caused, not from changes the system initiated. Asynchronous events (incoming notifications, background data sync) should not trigger impact or selection haptics; they may use notification haptics only if the outcome is directly relevant to an action the user recently took.
 
 ### Android: VibrationEffect and HapticFeedbackConstants
 
-Android provides haptic feedback through two mechanisms depending on the use case. `HapticFeedbackConstants` is the high-level API accessed through `View.performHapticFeedback()` — it uses semantic constants that the system maps to hardware-appropriate vibration patterns. Relevant constants and their iOS equivalents:
+Android provides haptic feedback through two mechanisms depending on the use case. `HapticFeedbackConstants` is the high-level API accessed through `View.performHapticFeedback()` - it uses semantic constants that the system maps to hardware-appropriate vibration patterns. Relevant constants and their iOS equivalents:
 
 | Android constant | iOS equivalent | Semantics |
 |------------------|----------------|-----------|
@@ -299,15 +299,15 @@ Android provides haptic feedback through two mechanisms depending on the use cas
 | `GESTURE_START` | `.light` impact | Beginning of a drag gesture |
 | `GESTURE_END` | `.medium` impact | Completion of a drag gesture |
 
-`VibrationEffect` (accessed via `Vibrator.vibrate(VibrationEffect)`) provides lower-level control for custom patterns, intensities, and compositions. For most application use cases, `HapticFeedbackConstants` is sufficient and preferable — it delegates pattern selection to the platform, which accounts for differences in actuator hardware across Android devices. A pattern tuned for a Pixel's linear resonant actuator will feel wrong on a budget device with an eccentric rotating mass vibrator.
+`VibrationEffect` (accessed via `Vibrator.vibrate(VibrationEffect)`) provides lower-level control for custom patterns, intensities, and compositions. For most application use cases, `HapticFeedbackConstants` is sufficient and preferable - it delegates pattern selection to the platform, which accounts for differences in actuator hardware across Android devices. A pattern tuned for a Pixel's linear resonant actuator will feel wrong on a budget device with an eccentric rotating mass vibrator.
 
 Android 12 introduced `VibrationEffect.Composition`, which allows sequencing haptic primitives (ticks, clicks, thuds, spins) with custom durations and amplitudes. This is appropriate for games and rich interactive experiences; for standard application UI, prefer the semantic constants.
 
 ### Web: navigator.vibrate()
 
-The Web Vibration API (`navigator.vibrate(pattern)`) is supported primarily on Android Chrome. iOS Safari does not implement the Vibration API, and desktop browsers ignore it. This severely limits its utility as a universal web haptic strategy — any feature that depends on `navigator.vibrate()` will silently do nothing on half the target audience.
+The Web Vibration API (`navigator.vibrate(pattern)`) is supported primarily on Android Chrome. iOS Safari does not implement the Vibration API, and desktop browsers ignore it. This severely limits its utility as a universal web haptic strategy - any feature that depends on `navigator.vibrate()` will silently do nothing on half the target audience.
 
-The appropriate use of `navigator.vibrate()` on web is limited to a single, clearly defined scenario: **critical confirmations on mobile web experiences where the user is performing an action with significant consequences**, such as confirming a payment or an irreversible deletion. In this narrow case, the haptic provides an additional confirmation signal on devices that support it, while the experience degrades gracefully to visual-only confirmation on devices that do not. Decorative haptics, haptic rhythm patterns, and haptics on every button tap are inappropriate for web — the unreliable cross-device support makes them an inconsistency rather than an enhancement.
+The appropriate use of `navigator.vibrate()` on web is limited to a single, clearly defined scenario: **critical confirmations on mobile web experiences where the user is performing an action with significant consequences**, such as confirming a payment or an irreversible deletion. In this narrow case, the haptic provides an additional confirmation signal on devices that support it, while the experience degrades gracefully to visual-only confirmation on devices that do not. Decorative haptics, haptic rhythm patterns, and haptics on every button tap are inappropriate for web - the unreliable cross-device support makes them an inconsistency rather than an enhancement.
 
 Before triggering any haptic, always check for API availability:
 
@@ -323,11 +323,11 @@ Never use vibration patterns longer than 20ms for UI feedback; longer patterns f
 
 ## 7. Brand Consistency vs. Platform Convention
 
-Every product that ships on multiple platforms faces the same tension: the brand wants visual and behavioral unity across surfaces, while each platform has its own conventions that users expect. Resolving this tension incorrectly in either direction produces problems. Over-platforming — designing each version so differently that the product feels like separate products — creates brand confusion and multiplies design and engineering cost. Over-branding — enforcing visual and behavioral uniformity at the cost of platform conventions — produces products that feel foreign on every platform they ship to.
+Every product that ships on multiple platforms faces the same tension: the brand wants visual and behavioral unity across surfaces, while each platform has its own conventions that users expect. Resolving this tension incorrectly in either direction produces problems. Over-platforming - designing each version so differently that the product feels like separate products - creates brand confusion and multiplies design and engineering cost. Over-branding - enforcing visual and behavioral uniformity at the cost of platform conventions - produces products that feel foreign on every platform they ship to.
 
 The resolution requires distinguishing between two categories of design decisions: **structural decisions** and **expressive decisions**.
 
-Structural decisions define how the user navigates, interacts, and recovers from errors. Navigation patterns, gesture vocabularies, component behaviors, safe area handling, and accessibility features all live in this category. For structural decisions, always follow the platform convention. The cost of deviating is real user confusion — trained reflexes fire and produce the wrong outcome. No brand benefit is worth that cost.
+Structural decisions define how the user navigates, interacts, and recovers from errors. Navigation patterns, gesture vocabularies, component behaviors, safe area handling, and accessibility features all live in this category. For structural decisions, always follow the platform convention. The cost of deviating is real user confusion - trained reflexes fire and produce the wrong outcome. No brand benefit is worth that cost.
 
 Expressive decisions define what the product looks and feels like at a perceptual level. Color palette, typography selection and scale, iconography style, illustration character, motion personality, and copy voice all live in this category. For expressive decisions, always follow the brand. Users recognize the product as "the same product" because these decisions are consistent, not because the tab bar appears at the same Y position on every platform.
 
@@ -336,10 +336,10 @@ The practical application is as follows:
 - Use the correct navigation component for each platform (tab bar on iOS, bottom nav bar on Android) but fill it with the brand's colors, icons, and typography.
 - Use platform-native dialogs and action sheets with the brand's color for accent buttons, not custom-shaped containers that shadow the OS dialog.
 - Never implement a custom gesture that conflicts with an OS-reserved gesture. Design the interaction within the gesture space the platform makes available.
-- Never override platform safe area handling. If a design requires content to appear in an unsafe zone, the design is wrong — not the safe area.
+- Never override platform safe area handling. If a design requires content to appear in an unsafe zone, the design is wrong - not the safe area.
 - Always respect the platform's minimum touch target and accessibility text scaling requirements. These are not platform conventions; they are accessibility requirements, and meeting them is a baseline, not an aspiration.
 
-The iOS Human Interface Guidelines, Material Design 3 documentation, and Microsoft Fluent 2 guidelines are the authoritative sources for platform structural decisions. When any detail in this reference conflicts with those sources, those sources take precedence — they are updated continuously and reflect current platform capabilities and requirements. This reference synthesizes those sources for the purposes of the get-design-done framework but does not replace them.
+The iOS Human Interface Guidelines, Material Design 3 documentation, and Microsoft Fluent 2 guidelines are the authoritative sources for platform structural decisions. When any detail in this reference conflicts with those sources, those sources take precedence - they are updated continuously and reflect current platform capabilities and requirements. This reference synthesizes those sources for the purposes of the get-design-done framework but does not replace them.
 
 ---
 

package/reference/pr-review-integration.md

@@ -1,4 +1,4 @@
-# PR Review Integration — the gh-based contract for `agents/pr-commenter.md`
+# PR Review Integration - the gh-based contract for `agents/pr-commenter.md`
 
 How GDD surfaces verify/audit output **inline on a pull request** and as a **status check**, using the `gh` CLI only (no GitHub SDK, no network library). `agents/pr-commenter.md` posts against this contract after `/gdd:ship` creates the PR. Every outbound string is redacted first; every failure mode degrades to a noop (never fails the ship).
 
@@ -23,8 +23,8 @@ gh api repos/{owner}/{repo}/pulls/{number}/comments \
   -F line=42 -f side=RIGHT
 ```
 
-- `body` — **redacted** finding text: the rule/pillar (`WCAG 1.4.3` / `audit:color`), the observation, a one-line suggested fix.
-- `path` + `line` + `side=RIGHT` — the changed line locus (RIGHT = the new version).
+- `body` - **redacted** finding text: the rule/pillar (`WCAG 1.4.3` / `audit:color`), the observation, a one-line suggested fix.
+- `path` + `line` + `side=RIGHT` - the changed line locus (RIGHT = the new version).
 - One comment per located finding. Findings with **no** changed-line locus go into a single summary review (below), not scattered.
 
 ## Summary review (findings without a line locus)
@@ -34,7 +34,7 @@ gh api repos/{owner}/{repo}/pulls/{number}/reviews \
   -f body="$SAFE_SUMMARY" -f event=COMMENT
 ```
 
-`event=COMMENT` (never `REQUEST_CHANGES`/`APPROVE` — GDD does not gate human approval). The summary lists verify pass/fail counts + the unlocated findings.
+`event=COMMENT` (never `REQUEST_CHANGES`/`APPROVE` - GDD does not gate human approval). The summary lists verify pass/fail counts + the unlocated findings.
 
 ## The `gdd/design-review` check-run (the team gate)
 
@@ -48,7 +48,7 @@ gh api repos/{owner}/{repo}/check-runs \
 - `conclusion`: **`success`** = verify passed AND no blocker-level pillar AND a11y-gate not failed; **`failure`** = verify failed OR a11y-gate failed; **`neutral`** = verify incomplete / degraded.
 - `output.summary` (redacted) carries: per-pillar audit scores (from `.design/DESIGN-AUDIT.md`), verify pass/fail (from `.design/DESIGN-VERIFICATION.md`), and the a11y-gate result.
 
-**Making it a required check (the team step — GDD never force-edits branch protection):** a maintainer enables `gdd/design-review` as a required status check via repo Settings → Branches, or via the bundled helper:
+**Making it a required check (the team step - GDD never force-edits branch protection):** a maintainer enables `gdd/design-review` as a required status check via repo Settings → Branches, or via the bundled helper:
 
 ```bash
 scripts/apply-branch-protection.sh --require-check "gdd/design-review"
@@ -89,8 +89,8 @@ No raw artifact excerpt reaches `gh` un-redacted.
 | no PR number (manual/failed creation) | noop + one-line note |
 | a single `gh api` call fails (≤3 attempts) | print that body; continue with the rest |
 
-In all cases pr-commenter exits cleanly — it **never** fails the `/gdd:ship` success path.
+In all cases pr-commenter exits cleanly - it **never** fails the `/gdd:ship` success path.
 
 ## Out of scope (per Phase 35 split)
 
-Slack/Discord notifications (Phase 35.2); Linear/Jira ticket-sync (Phase 35.3); `pseudonymize.cjs` (Phase 30 — wired for third-party channels); video walkthroughs (still images only); a GDD-side approver list (branch protection owns approvals).
+Slack/Discord notifications (Phase 35.2); Linear/Jira ticket-sync (Phase 35.3); `pseudonymize.cjs` (Phase 30 - wired for third-party channels); video walkthroughs (still images only); a GDD-side approver list (branch protection owns approvals).

package/reference/prices/antigravity.md

@@ -1,9 +1,9 @@
-# Antigravity — Price Table (stub)
+# Antigravity - Price Table (stub)
 
 **Runtime:** `antigravity` (Antigravity)
-**Phase 26 D-08 sub-table — STUB.** Placeholder so the price-table router (`reference/model-prices.md`) has a complete link list for all 14 runtimes. Runtime adapter authors fill this in with provenance citations in a later cycle.
+**Phase 26 D-08 sub-table - STUB.** Placeholder so the price-table router (`reference/model-prices.md`) has a complete link list for all 14 runtimes. Runtime adapter authors fill this in with provenance citations in a later cycle.
 
-**Provenance:** `<TODO: confirm at https://antigravity.google/docs>` — pending.
+**Provenance:** `<TODO: confirm at https://antigravity.google/docs>` - pending.
 
 ## Pricing (USD per 1M tokens)
 

package/reference/prices/augment.md

@@ -1,9 +1,9 @@
-# Augment Code — Price Table (stub)
+# Augment Code - Price Table (stub)
 
 **Runtime:** `augment` (Augment Code)
-**Phase 26 D-08 sub-table — STUB.** Placeholder so the price-table router (`reference/model-prices.md`) has a complete link list for all 14 runtimes. Runtime adapter authors fill this in with provenance citations in a later cycle.
+**Phase 26 D-08 sub-table - STUB.** Placeholder so the price-table router (`reference/model-prices.md`) has a complete link list for all 14 runtimes. Runtime adapter authors fill this in with provenance citations in a later cycle.
 
-**Provenance:** `<TODO: confirm at https://docs.augmentcode.com>` — pending.
+**Provenance:** `<TODO: confirm at https://docs.augmentcode.com>` - pending.
 
 ## Pricing (USD per 1M tokens)
 

package/reference/prices/claude.md

@@ -1,9 +1,9 @@
-# Anthropic — Claude Code Price Table
+# Anthropic - Claude Code Price Table
 
 **Runtime:** `claude` (Claude Code)
 **Phase 26 D-08 sub-table.** Authoritative pricing for the Anthropic models referenced in `reference/runtime-models.md` under `id: "claude"`. Read by `scripts/lib/budget-enforcer.cjs` (and indirectly by `hooks/budget-enforcer.ts`) to compute `est_cost_usd` per spawn.
 
-**Provenance:** https://docs.anthropic.com/en/docs/about-claude/pricing — retrieved 2026-04-29, cycle `2026-04-29-v1.26`.
+**Provenance:** https://docs.anthropic.com/en/docs/about-claude/pricing - retrieved 2026-04-29, cycle `2026-04-29-v1.26`.
 
 ## Pricing (USD per 1M tokens)
 

package/reference/prices/cline.md

@@ -1,11 +1,11 @@
-# Cline — Price Table (stub)
+# Cline - Price Table (stub)
 
 **Runtime:** `cline` (Cline)
-**Phase 26 D-08 sub-table — STUB.** Placeholder so the price-table router (`reference/model-prices.md`) has a complete link list for all 14 runtimes. Runtime adapter authors fill this in with provenance citations in a later cycle.
+**Phase 26 D-08 sub-table - STUB.** Placeholder so the price-table router (`reference/model-prices.md`) has a complete link list for all 14 runtimes. Runtime adapter authors fill this in with provenance citations in a later cycle.
 
-**Provenance:** `<TODO: confirm at https://docs.cline.bot>` — pending.
+**Provenance:** `<TODO: confirm at https://docs.cline.bot>` - pending.
 
-**Note:** Cline is a BYO-API-key runtime — actual pricing is determined by whichever provider key the user supplies. The `tier_to_model` row in `reference/runtime-models.md` chooses a default model per tier; this table prices that default. Users of other providers should override locally.
+**Note:** Cline is a BYO-API-key runtime - actual pricing is determined by whichever provider key the user supplies. The `tier_to_model` row in `reference/runtime-models.md` chooses a default model per tier; this table prices that default. Users of other providers should override locally.
 
 ## Pricing (USD per 1M tokens)
 

package/reference/prices/codebuddy.md

@@ -1,9 +1,9 @@
-# CodeBuddy — Price Table (stub)
+# CodeBuddy - Price Table (stub)
 
 **Runtime:** `codebuddy` (Tencent CodeBuddy)
-**Phase 26 D-08 sub-table — STUB.** Placeholder so the price-table router (`reference/model-prices.md`) has a complete link list for all 14 runtimes. Runtime adapter authors fill this in with provenance citations in a later cycle.
+**Phase 26 D-08 sub-table - STUB.** Placeholder so the price-table router (`reference/model-prices.md`) has a complete link list for all 14 runtimes. Runtime adapter authors fill this in with provenance citations in a later cycle.
 
-**Provenance:** `<TODO: confirm at https://copilot.tencent.com>` — pending.
+**Provenance:** `<TODO: confirm at https://copilot.tencent.com>` - pending.
 
 ## Pricing (USD per 1M tokens)
 

package/reference/prices/codex.md

@@ -1,9 +1,9 @@
-# OpenAI — Codex CLI Price Table
+# OpenAI - Codex CLI Price Table
 
 **Runtime:** `codex` (OpenAI Codex CLI)
 **Phase 26 D-08 sub-table.** Pricing for the OpenAI Codex tier referenced in `reference/runtime-models.md` under `id: "codex"`.
 
-**Provenance:** `<TODO: confirm at https://openai.com/api/pricing/>` — retrieved 2026-04-29 (placeholder — v1.26.0 ships with seed numbers; runtime adapter authors confirm and PR before v1.27).
+**Provenance:** `<TODO: confirm at https://openai.com/api/pricing/>` - retrieved 2026-04-29 (placeholder - v1.26.0 ships with seed numbers; runtime adapter authors confirm and PR before v1.27).
 
 **Status:** placeholder values are taken from public OpenAI tier-positioning at the time of v1.26.0 ship. The cost-aggregator will surface drift if measured spend per spawn diverges from these figures by more than 20% after 10+ cycles.
 

package/reference/prices/copilot.md

@@ -1,9 +1,9 @@
-# GitHub Copilot — Price Table (stub)
+# GitHub Copilot - Price Table (stub)
 
 **Runtime:** `copilot` (GitHub Copilot CLI)
-**Phase 26 D-08 sub-table — STUB.** Placeholder so the price-table router (`reference/model-prices.md`) has a complete link list for all 14 runtimes. Runtime adapter authors fill this in with provenance citations in a later cycle.
+**Phase 26 D-08 sub-table - STUB.** Placeholder so the price-table router (`reference/model-prices.md`) has a complete link list for all 14 runtimes. Runtime adapter authors fill this in with provenance citations in a later cycle.
 
-**Provenance:** `<TODO: confirm at https://docs.github.com/en/copilot/about-github-copilot/plans-for-github-copilot>` — pending.
+**Provenance:** `<TODO: confirm at https://docs.github.com/en/copilot/about-github-copilot/plans-for-github-copilot>` - pending.
 
 ## Pricing (USD per 1M tokens)
 

package/reference/prices/cursor.md

@@ -1,9 +1,9 @@
-# Cursor — Price Table (stub)
+# Cursor - Price Table (stub)
 
 **Runtime:** `cursor` (Cursor IDE / CLI)
-**Phase 26 D-08 sub-table — STUB.** Placeholder so the price-table router (`reference/model-prices.md`) has a complete link list for all 14 runtimes. Runtime adapter authors fill this in with provenance citations in a later cycle.
+**Phase 26 D-08 sub-table - STUB.** Placeholder so the price-table router (`reference/model-prices.md`) has a complete link list for all 14 runtimes. Runtime adapter authors fill this in with provenance citations in a later cycle.
 
-**Provenance:** `<TODO: confirm at https://docs.cursor.com/account/pricing>` — pending.
+**Provenance:** `<TODO: confirm at https://docs.cursor.com/account/pricing>` - pending.
 
 ## Pricing (USD per 1M tokens)
 

package/reference/prices/gemini.md

@@ -1,9 +1,9 @@
-# Google — Gemini CLI Price Table
+# Google - Gemini CLI Price Table
 
 **Runtime:** `gemini` (Google Gemini CLI)
 **Phase 26 D-08 sub-table.** Pricing for the Gemini 2.5 tier referenced in `reference/runtime-models.md` under `id: "gemini"`.
 
-**Provenance:** `<TODO: confirm at https://ai.google.dev/pricing>` — retrieved 2026-04-29 (placeholder — v1.26.0 ships with seed numbers; runtime adapter authors confirm and PR before v1.27).
+**Provenance:** `<TODO: confirm at https://ai.google.dev/pricing>` - retrieved 2026-04-29 (placeholder - v1.26.0 ships with seed numbers; runtime adapter authors confirm and PR before v1.27).
 
 **Status:** placeholder values reflect public Gemini 2.5 tier positioning at v1.26.0 ship time. Cost-aggregator will surface drift if measured spend deviates from these figures by more than 20% after 10+ cycles.
 

package/reference/prices/kilo.md

@@ -1,9 +1,9 @@
-# Kilo Code — Price Table (stub)
+# Kilo Code - Price Table (stub)
 
 **Runtime:** `kilo` (Kilo Code)
-**Phase 26 D-08 sub-table — STUB.** Placeholder so the price-table router (`reference/model-prices.md`) has a complete link list for all 14 runtimes. Runtime adapter authors fill this in with provenance citations in a later cycle.
+**Phase 26 D-08 sub-table - STUB.** Placeholder so the price-table router (`reference/model-prices.md`) has a complete link list for all 14 runtimes. Runtime adapter authors fill this in with provenance citations in a later cycle.
 
-**Provenance:** `<TODO: confirm at https://kilocode.ai/docs>` — pending.
+**Provenance:** `<TODO: confirm at https://kilocode.ai/docs>` - pending.
 
 ## Pricing (USD per 1M tokens)
 

package/reference/prices/opencode.md

@@ -1,11 +1,11 @@
-# OpenCode — Price Table (stub)
+# OpenCode - Price Table (stub)
 
 **Runtime:** `opencode` (OpenCode)
-**Phase 26 D-08 sub-table — STUB.** Placeholder so the price-table router (`reference/model-prices.md`) has a complete link list for all 14 runtimes. Runtime adapter authors fill this in with provenance citations in a later cycle.
+**Phase 26 D-08 sub-table - STUB.** Placeholder so the price-table router (`reference/model-prices.md`) has a complete link list for all 14 runtimes. Runtime adapter authors fill this in with provenance citations in a later cycle.
 
-**Provenance:** `<TODO: confirm at https://opencode.ai/docs>` — pending.
+**Provenance:** `<TODO: confirm at https://opencode.ai/docs>` - pending.
 
-**Note:** OpenCode is a BYO-API-key runtime — actual pricing is determined by whichever provider key the user supplies. The `tier_to_model` row in `reference/runtime-models.md` chooses a default model per tier; this table prices that default. Users of other providers should override locally.
+**Note:** OpenCode is a BYO-API-key runtime - actual pricing is determined by whichever provider key the user supplies. The `tier_to_model` row in `reference/runtime-models.md` chooses a default model per tier; this table prices that default. Users of other providers should override locally.
 
 ## Pricing (USD per 1M tokens)
 

package/reference/prices/qwen.md

@@ -1,9 +1,9 @@
-# Alibaba — Qwen CLI Price Table
+# Alibaba - Qwen CLI Price Table
 
 **Runtime:** `qwen` (Alibaba Qwen CLI)
 **Phase 26 D-08 sub-table.** Pricing for the Qwen 3 tier referenced in `reference/runtime-models.md` under `id: "qwen"`.
 
-**Provenance:** `<TODO: confirm at https://www.alibabacloud.com/help/en/model-studio/billing-for-models>` — retrieved 2026-04-29 (placeholder — v1.26.0 ships with seed numbers; runtime adapter authors confirm and PR before v1.27).
+**Provenance:** `<TODO: confirm at https://www.alibabacloud.com/help/en/model-studio/billing-for-models>` - retrieved 2026-04-29 (placeholder - v1.26.0 ships with seed numbers; runtime adapter authors confirm and PR before v1.27).
 
 **Status:** placeholder values reflect public Model Studio tier positioning at v1.26.0 ship time. Cost-aggregator will surface drift if measured spend deviates from these figures by more than 20% after 10+ cycles.
 

package/reference/prices/trae.md

@@ -1,9 +1,9 @@
-# Trae — Price Table (stub)
+# Trae - Price Table (stub)
 
 **Runtime:** `trae` (Trae)
-**Phase 26 D-08 sub-table — STUB.** Placeholder so the price-table router (`reference/model-prices.md`) has a complete link list for all 14 runtimes. Runtime adapter authors fill this in with provenance citations in a later cycle.
+**Phase 26 D-08 sub-table - STUB.** Placeholder so the price-table router (`reference/model-prices.md`) has a complete link list for all 14 runtimes. Runtime adapter authors fill this in with provenance citations in a later cycle.
 
-**Provenance:** `<TODO: confirm at https://trae.ai/docs>` — pending.
+**Provenance:** `<TODO: confirm at https://trae.ai/docs>` - pending.
 
 **Note:** Trae may be a `single_tier` runtime (one model maps to all three tiers). When confirming pricing, populate all three rows with the same numbers and the same model name; mark `single_tier: true` in the corresponding `reference/runtime-models.md` row.