1 files changed, 16 insertions, 1 deletions
diff --git a/docs/apps.md b/docs/apps.md
index 85b39da..8054802 100644
--- a/docs/apps.md
+++ b/docs/apps.md
@@ -236,6 +236,19 @@ registry, so a newly-registered app gets a checkbox for free.
    through `saveDirectories`; anything only this app has, it does itself with
    the transport. **Do not import `group-settings.js`** — that is a cycle, and
    it fails as a component that silently does not render.
+2c. **The toolbar pins.** If the app has a toolbar — a row of controls above
+   whatever it is the app shows — give it `position: sticky` on the pattern
+   `style.css`'s "Sticky chrome" section holds, so that scrolling a library
+   does not take its own controls off the screen. Two conditions come with it,
+   and both are structural rather than cosmetic: the toolbar must be a
+   **direct child of the page root** (an app renders a fragment, so it already
+   is — do not wrap it in a container of your own), and it must be **opaque**,
+   or the content scrolls visibly through it. If anything of the app's pins
+   *below* that toolbar, as Files' column heads do, the toolbar has to publish
+   its own height with `useStickyBand` from `sticky.js` — its height is never
+   a constant, since it wraps on a phone. An app with no toolbar renders none:
+   an empty band still holds a strip of the page open, which is why Photos
+   draws no toolbar on the Search page.
 3. **Node-side allow-list**: add the key to `ALLOWED_APPS` in
    `webrtc_server.py`. Without this the node refuses `apps_enabled` for any
    set naming it (`"Unknown app(s): ..."`), so an operator can never turn it
@@ -252,7 +265,9 @@ registry, so a newly-registered app gets a checkbox for free.
    to every `.js` in `static/` (`sw.js` excepted, unversioned on purpose).
    Written after `source-merge.js` shipped missing from the list.
 6. **Test coverage that scans the file set**: `test_hook_ordering.py`
-   (`STATIC_FILES`) and `test_transport_contracts.py`
+   (`STATIC_FILES`), `test_sticky_header.py` (add a case to its probe if the
+   app has a toolbar — a band that stopped pinning looks exactly like one that
+   never did) and `test_transport_contracts.py`
    (`test_no_setter_survives_the_state_it_belonged_to`, `SPLIT_FILES`) walk a
    fixed list of files looking for a whole class of bug each — add the new
    file to both lists, or it is simply never checked, which fails silently