docs: clarify rail startup and foldable split-pane widths

packages/capacitor-native-ui/docs/ionic-vertical-bars.md

@@ -14,7 +14,7 @@ Read [how projection works](../README.md#how-projection-works) for the relations
 | ------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
 | Ionic components with your own theme, Ionic's default styles, or another theme | [Ionic setup below](#try-it-in-your-existing-ionic-app)                                                                           | Foldable device placement, standalone rail CSS and the Ionic Native UI adapter. Keep your existing theme. |
 | No Ionic components (plain HTML, React, Vue, Angular, etc.)                    | [HTML setup](framework-independent.md), then its [device rail setup](framework-independent.md#device-placement-for-vertical-bars) | `@rdlabo/capacitor-native-ui/core` and Foldable. Your app supplies the rail layout; no theme package.     |
-| Already using the iOS 27 theme and Native UI                                   | [Connect device placement](../../capacitor-native-ui/docs/vertical-bars.md#use-with-capacitor-foldable)                           | Reuse your existing runtime. Do not start another one.                                                    |
+| Already using the iOS 27 theme and Native UI                                   | [Connect device placement](vertical-bars.md#use-with-capacitor-foldable)                                                          | Reuse your existing runtime. Do not start another one.                                                    |
 
 **Without Ionic, follow the HTML guide instead of the steps below.** You do not need `@rdlabo/ionic-theme-ios27`, `vertical-bars.css`, `ion-app`, or Ionic navigation animations. Explicitly marked HTML buttons and back buttons are supported; arbitrary HTML tabs are not automatically converted. A browser preview requires an application-styled `webHost`; native rail presentation also requires supported iOS hardware and software.
 
@@ -125,6 +125,12 @@ await rail.destroy();
 
 If Native UI is already active, keep that runtime and add only the placement subscription. Do not start a second runtime. For shared configuration and application-owned CSS, see [Foldable integration](vertical-bars.md#use-with-capacitor-foldable).
 
+### Initial layout timing
+
+Run step 3 from your application root as soon as `ion-app` is mounted; do not wait for a routed page's data requests. `setVerticalBarsLayout()` needs that element to exist and does not save placement supplied before mounting. Keep startup and cleanup with the same application owner, as described in [the framework lifecycle examples](setup.md#place-startup-in-your-frameworks-app-root).
+
+Native startup, device placement and control rendering are asynchronous. Resolving `enableNativeUI()` gives you the runtime handle, not a guarantee that controls have already been projected. Starting promptly avoids application-added waiting, but the initial Web layout may still be visible before native projection.
+
 ### 4. Build, sync and run on iPhone Duo
 
 Build your application's Web assets, then sync the native project:

packages/capacitor-native-ui/docs/vertical-bars.md

@@ -10,7 +10,7 @@ Choose your setup before using this reference:
 
 - **Ionic with a custom or default theme:** [Ionic rail setup](ionic-vertical-bars.md#try-it-in-your-existing-ionic-app).
 - **No Ionic:** [HTML setup](framework-independent.md) and its [device rail setup](framework-independent.md#device-placement-for-vertical-bars). Use `/core` and your own layout; the Ionic setup below does not apply.
-- **Existing iOS 27 theme and Native UI:** [Connect device placement](../../capacitor-native-ui/docs/vertical-bars.md#use-with-capacitor-foldable) using your existing runtime.
+- **Existing iOS 27 theme and Native UI:** [Connect device placement](#use-with-capacitor-foldable) using your existing runtime.
 
 This page covers device-plugin integration, control eligibility, native appearance and runtime options. For posture-driven Ionic split panes, see [Device layout and split panes](../../theme-ios27/docs/vertical-bars-layout.md).
 

packages/theme-ios27/docs/vertical-bars-layout.md

@@ -108,7 +108,7 @@ Only one of the first three classes is retained. The helper does not subscribe t
 
 ## Adapt the split pane
 
-For a side-by-side menu on iPhone Duo, opt the `ion-split-pane` into the separately measured Settings layout. The sidebar is 320pt when fully unfolded and reaches the display midpoint when half-opened (50vw). The application supplies the posture; both states have the same viewport width, so a width media query cannot distinguish them:
+For a side-by-side menu on iPhone Duo, opt the `ion-split-pane` into the theme's posture-based layout. This stylesheet defaults to `320px` when fully unfolded and `50vw` when half-opened. These are theme defaults, not a guarantee of the widths chosen by the system Settings app. The application supplies the posture; both states can have the same viewport width, so a width media query cannot distinguish them:
 
 ```html
 <ion-split-pane class="split-pane-fold-layout" contentId="main-content" when="(min-width: 900px)">
@@ -117,7 +117,7 @@ For a side-by-side menu on iPhone Duo, opt the `ion-split-pane` into the separat
 </ion-split-pane>
 ```
 
-Set the ordinary split-pane width to 320pt in the application's stylesheet, and let the half-open class change only the width value:
+Connect the split-pane width to the theme variable in the application's stylesheet, and let the half-open class change only the width value:
 
 ```css
 ion-split-pane.split-pane-fold-layout {
@@ -130,6 +130,8 @@ ion-split-pane.split-pane-fold-layout {
 
 The registered `--ios-theme-split-pane-width` defaults to `320px`. `applyFoldStateClasses` sets `ios-theme-fold-half-opened` on `ion-app`; the stylesheet then sets only descendant split panes with `split-pane-fold-layout` to `50vw`. Add this opt-in class once; no state-dependent class binding is needed. Other split panes retain their existing width.
 
+`ios-theme-fold-expanded` describes use of the inner display; it does not select the sidebar width. A fully unfolded display keeps the ordinary width. Only `ios-theme-fold-half-opened` selects `50vw` for opted-in split panes.
+
 Ionic's `when` still controls whether the menu is persistent. The example chooses a fixed 900px breakpoint. If your app needs different breakpoints for folded and ordinary displays, use the `ios-theme-fold-expanded` class applied by the helper to select that policy in your application's layout code. The helper only updates state classes, not `when`. This layout does not enable Vertical Bars or move an overlay menu.
 
 ## Migration