diff --git a/Dockerfile b/Dockerfile
index f8b7cf04..9eeb7f1f 100644
--- a/Dockerfile
+++ b/Dockerfile
@@ -124,6 +124,20 @@ COPY migrations/ ./migrations/
 COPY scripts/ ./scripts/
 COPY wsgi.py ./
 
+# The two files under docs/ that the APP SERVES at runtime, not documentation.
+# shopdb/core/api/docs.py resolves both relative to the repo root, so without
+# them /api/docs renders the Redoc shell and then 404s fetching its own spec -
+# which is what every Docker deployment did. Copied by name rather than copying
+# docs/ wholesale: the rest of that tree is prose and has no business in a lean
+# runtime image.
+COPY docs/openapi.json docs/llms.txt ./docs/
+
+# Fail the BUILD on a syntax error rather than the pod at runtime. Docker never
+# imports the application, so a broken .py sails through every layer and only
+# surfaces as a crash-looping container: observed, four restarts before anyone
+# noticed. compileall touches nothing at runtime and costs a couple of seconds.
+RUN python -m compileall -q shopdb plugins migrations wsgi.py
+
 # Built SPA from stage 1. Flask serves it via register_frontend_routes.
 COPY --from=frontendbuild /build/frontend/dist ./frontend/dist
 
diff --git a/shopdb/core/api/docs.py b/shopdb/core/api/docs.py
index cbda186b..f2a5be59 100644
--- a/shopdb/core/api/docs.py
+++ b/shopdb/core/api/docs.py
@@ -97,50 +97,162 @@ def docs_index():
         '<meta charset="utf-8">'
         '<meta name="viewport" content="width=device-width, initial-scale=1">'
         '<style>'
-        ':root{color-scheme:light dark}'
+        # color-scheme follows the SAME attribute Redoc is themed from, so the
+        # OS never paints dark scrollbars under a page the user set to light.
+        ':root{color-scheme:light}'
+        ':root[data-theme="dark"]{color-scheme:dark}'
         'body{margin:0;padding:0;background:#fff}'
-        '.docs-note{font:14px/1.4 system-ui,sans-serif;margin:0;'
-        'padding:10px 16px;background:#eef2f7;color:#0f172a;'
-        'border-bottom:1px solid #cbd5e1}'
-        '.docs-note a{color:#1d4ed8}'
-        '@media (prefers-color-scheme: dark){'
-        'body{background:#0f172a}'
-        '.docs-note{background:#1e293b;color:#e2e8f0;'
-        'border-bottom-color:#334155}'
-        '.docs-note a{color:#7dd3fc}'
-        '}'
+        '.docs-note{font:14px/1.6 system-ui,-apple-system,Segoe UI,sans-serif;'
+        'margin:0;padding:10px 16px;background:#f5f5f5;color:#1a1a2e;'
+        'border-bottom:1px solid #dee2e6}'
+        '.docs-note a{color:#2d6ce0}'
+        # The ONLY Redoc elements with no theme key. Each is a colour hard-coded
+        # in the vendored bundle, so it cannot be reached from the theme object:
+        #   h5                        section headings ("query Parameters"),
+        #                             rgba(38,50,56,.5) - fails AA on light too
+        #   td[colspan] > div         nested schema tables at depth 2 are
+        #                             painted #ffffff whatever nestedBackground
+        #                             says, and the response envelopes nest 3
+        #                             deep, so it shows on every operation
+        #   .react-tabs__tab--selected  right-panel tab paints text.primary on
+        #                             rightPanel.textColor; both are light in
+        #                             dark mode, so the selected tab label
+        #                             vanished into its own background
+        # Selectors use Redoc's own DOM - tag, colspan attribute, react-tabs
+        # class - never generated class hashes, which change on every build.
+        '#redoc h5{color:#5c636a;border-bottom-color:#dee2e6}'
+        ':root[data-theme="dark"] body{background:#0a0a1a}'
+        ':root[data-theme="dark"] .docs-note{background:#0d0d2b;color:#e6e6e8;'
+        'border-bottom-color:rgba(65,129,255,0.2)}'
+        ':root[data-theme="dark"] .docs-note a{color:#4181ff}'
+        ':root[data-theme="dark"] #redoc h5{color:#9d9da3;'
+        'border-bottom-color:rgba(255,255,255,0.2)}'
+        ':root[data-theme="dark"] #redoc td[colspan="2"]>div td[colspan="2"]>div'
+        '{background:#0a0a1a}'
+        ':root[data-theme="dark"] #redoc td[colspan="2"]>div td[colspan="2"]>div '
+        'td[colspan="2"]>div{background:#0d0d2b}'
+        ':root[data-theme="dark"] #redoc .react-tabs__tab--selected{color:#0a0a1a}'
+        # The content-type control is a native <select>. Redoc never styles it,
+        # so it keeps the OS default (black text, transparent background) and
+        # reads 1.07:1 on the dark right panel. Name both halves; the border
+        # keeps it looking like a control rather than stray text.
+        # The content-type label ("application/json") is a span INSIDE that
+        # same h5, carrying its own hard-coded black, so theming the h5 alone
+        # left it at 1.07:1 on the dark panel. Inherit rather than restate, so
+        # it tracks whatever the heading colour is.
+        '#redoc h5 span{color:inherit}'
+        # Redoc's footer badge links to redocly.com and its logo was replaced
+        # with a blank GIF so an air-gapped box stops reaching for a CDN, so
+        # what remains is a dead external link on a shop-floor kiosk. The MIT
+        # licence requires the notice be retained in the DISTRIBUTION, which
+        # staticdocs/redoc.standalone.js.LICENSE.txt covers; it does not
+        # require rendering a badge.
+        '#redoc a[href*="redocly.com"]{display:none}'
         '</style></head><body>'
         '%s'
         '<div id="redoc"></div>'
         '<script src="%s"></script>'
         '<script>'
         'var SPEC = %s;'
-        # Redoc computes text and the right-hand sample panel from the
-        # background and gets both wrong on a dark one, so they are named
-        # rather than left to it.
-        'var DARK={colors:{primary:{main:"#7dd3fc"},'
-        'text:{primary:"#e2e8f0",secondary:"#94a3b8"},'
-        'border:{dark:"#334155",light:"#1e293b"}},'
-        'sidebar:{backgroundColor:"#111827",textColor:"#e2e8f0",'
-        'activeTextColor:"#7dd3fc"},'
-        'rightPanel:{backgroundColor:"#020617",textColor:"#e2e8f0"},'
-        'codeBlock:{backgroundColor:"#0b1220"},'
-        'schema:{nestedBackground:"#0b1220"},'
-        'typography:{fontFamily:"system-ui,sans-serif",'
-        'code:{color:"#e2e8f0",backgroundColor:"#0b1220"}}};'
-        'var LIGHT={colors:{primary:{main:"#1d4ed8"}},'
-        'typography:{fontFamily:"system-ui,sans-serif"}};'
+        # Product type: the app's body stack and its mono stack. Inter is
+        # bundled into the SPA under a hashed filename this standalone page
+        # cannot reference, so system-ui is the honest choice (Segoe UI on the
+        # Windows kiosks).
+        'var FONT="system-ui,-apple-system,Segoe UI,sans-serif";'
+        'var MONO="SF Mono,Monaco,Consolas,monospace";'
+        # The product chrome is the same navy with white text in BOTH themes,
+        # so one object serves both. Redoc deep-merges the theme into a fresh
+        # copy of its defaults and snapshots it, so sharing is safe.
+        'var SIDEBAR={backgroundColor:"#00003d",'
+        'textColor:"rgba(255,255,255,0.85)",activeTextColor:"#ffffff",'
+        'groupItems:{activeBackgroundColor:"rgba(255,255,255,0.1)"},'
+        'level1Items:{activeBackgroundColor:"rgba(255,255,255,0.1)"},'
+        'arrow:{color:"rgba(255,255,255,0.85)"}};'
+        # Light. The middle column is the product CARD white. primary is
+        # --primary-dark rather than --primary, because --primary is 3.6:1 on
+        # white and fails AA; success and error are a shade darker than the
+        # product tokens for the same reason - those tokens are designed as
+        # fills, not as text on the nested panels where type names and required
+        # labels live. tabTextColor is pinned because the response tabs sit on
+        # the DARK code block in both themes, and Redoc would otherwise derive
+        # them from the light middle-panel colours.
+        'var LIGHT={colors:{primary:{main:"#2d6ce0",light:"#2d6ce0"},'
+        'success:{main:"#0b7a3b"},'
+        'warning:{main:"#ff9500",contrastText:"#1a1a2e"},'
+        'error:{main:"#c1273a"},'
+        'text:{primary:"#1a1a2e",secondary:"#5c636a"},'
+        'border:{dark:"#dee2e6"},'
+        'gray:{50:"#f5f5f5",100:"#f5f5f5"},'
+        # tabTextColor is deliberately NOT pinned here. It was, on the
+        # assumption that these tabs sit on the dark code block in both
+        # themes; measuring the rendered page showed the light-theme tab list
+        # on the white panel, where the bright green read 1.95:1. Unset, Redoc
+        # derives it from success.main, which is chosen to pass on white.
+        'responses:{}},'
+        'schema:{nestedBackground:"#f5f5f5"},'
+        'typography:{fontSize:"15px",lineHeight:"1.6em",fontFamily:FONT,'
+        'fontWeightBold:"600",headings:{fontFamily:FONT,fontWeight:"600"},'
+        'code:{fontFamily:MONO,color:"#1a1a2e",'
+        'backgroundColor:"rgba(26,26,46,0.06)"},'
+        'links:{hover:"#4181ff"}},'
+        'sidebar:SIDEBAR,'
+        'rightPanel:{backgroundColor:"#00003d",textColor:"#ffffff",'
+        'servers:{overlay:{backgroundColor:"#f5f5f5",textColor:"#1a1a2e"},'
+        'url:{backgroundColor:"#ffffff"}}},'
+        'codeBlock:{backgroundColor:"#0a0a1a"}};'
+        # Dark. Product tokens verbatim, with the two alpha text tokens
+        # flattened onto the page background so Redoc's own lighten and
+        # transparentize derivations stay predictable. The response accordion
+        # tints are named because Redoc derives a 7% tint that is invisible on
+        # a near-black page.
+        'var DARK={colors:{primary:{main:"#4181ff"},'
+        'success:{main:"#0ad64f"},'
+        'warning:{main:"#ff9500",contrastText:"#1a1a2e"},'
+        'error:{main:"#f5365c"},'
+        'text:{primary:"#e6e6e8",secondary:"#9d9da3"},'
+        'border:{dark:"rgba(65,129,255,0.2)"},'
+        'gray:{50:"#0d0d2b",100:"#0d0d2b"},'
+        'responses:{success:{backgroundColor:"rgba(10,214,79,0.12)"},'
+        'error:{backgroundColor:"rgba(245,54,92,0.12)"}}},'
+        'schema:{nestedBackground:"#0d0d2b"},'
+        'typography:{fontSize:"15px",lineHeight:"1.6em",fontFamily:FONT,'
+        'fontWeightBold:"600",headings:{fontFamily:FONT,fontWeight:"600"},'
+        'code:{fontFamily:MONO,color:"#e6e6e8",'
+        'backgroundColor:"rgba(255,255,255,0.08)"},'
+        'links:{hover:"#7aa8ff"}},'
+        'sidebar:SIDEBAR,'
+        'rightPanel:{backgroundColor:"#00003d",textColor:"#ffffff",'
+        'servers:{overlay:{backgroundColor:"#0d0d2b",textColor:"#e6e6e8"},'
+        'url:{backgroundColor:"#0a0a1a"}}},'
+        'codeBlock:{backgroundColor:"#0a0a1a"}};'
+        # THEME SOURCE. The app stores an explicit choice under this key and
+        # stamps <html data-theme>. This page is served from the same origin,
+        # so it reads the same key rather than guessing from the OS - picking
+        # light in the app on a dark-OS kiosk used to give a dark docs page.
+        # The OS scheme is only the fallback, exactly as in the app's store.
+        # localStorage can throw outright on a locked-down kiosk browser.
+        'var KEY="shopdb-theme";'
         'var q=window.matchMedia("(prefers-color-scheme: dark)");'
-        'function draw(){'
-        'document.getElementById("redoc").innerHTML="";'
-        'Redoc.init(SPEC,{theme:q.matches?DARK:LIGHT},'
-        'document.getElementById("redoc"));'
-        '}'
+        'var el=document.getElementById("redoc");'
+        'function pick(){var t=null;'
+        'try{t=window.localStorage.getItem(KEY);}catch(e){}'
+        'if(t!=="dark"&&t!=="light"){t=q.matches?"dark":"light";}'
+        'return t;}'
+        # Re-initialise rather than restyle: Redoc bakes colours into
+        # styled-components at init. data-theme is stamped first so the CSS
+        # above and the Redoc theme can never disagree about which one is live.
+        'function draw(){var t=pick();'
+        'document.documentElement.setAttribute("data-theme",t);'
+        'el.innerHTML="";'
+        'Redoc.init(SPEC,{theme:t==="dark"?DARK:LIGHT},el);}'
         'draw();'
         # addEventListener is missing from MediaQueryList in older WebViews,
         # and a shop-floor kiosk browser is exactly where this gets read.
         'if(q.addEventListener){q.addEventListener("change",draw);}'
         'else if(q.addListener){q.addListener(draw);}'
+        # Fires in THIS tab when the app in another tab toggles the theme.
+        'window.addEventListener("storage",function(e){'
+        'if(e.key===KEY){draw();}});'
         '</script>'
         '</body></html>' % (tryit_note, redoc_url, json.dumps(spec_url))
     )
@@ -224,7 +336,11 @@ def swagger_tryit():
         '<meta name="viewport" content="width=device-width, initial-scale=1">'
         '<link rel="stylesheet" href="%(css)s">'
         '<style>body{margin:0;padding:0}'
-        '.tryit-warn{font:14px/1.4 system-ui,sans-serif;background:#7f1d1d;'
+        # The product's light-theme error colour, not an invented red. Swagger's
+        # stylesheet is light-only, so this page stays light and only the
+        # banner is themed; white on it is 5.8:1.
+        '.tryit-warn{font:14px/1.6 system-ui,-apple-system,Segoe UI,sans-serif;'
+        'background:#c1273a;'
         'color:#fff;margin:0;padding:10px 16px}'
         '.tryit-warn a{color:#fff}</style>'
         '</head><body>'
diff --git a/shopdb/core/api/staticdocs/redoc.standalone.js.LICENSE.txt b/shopdb/core/api/staticdocs/redoc.standalone.js.LICENSE.txt
new file mode 100644
index 00000000..8e040433
--- /dev/null
+++ b/shopdb/core/api/staticdocs/redoc.standalone.js.LICENSE.txt
@@ -0,0 +1,37 @@
+Redoc (redoc.standalone.js) - vendored third-party bundle
+=========================================================
+
+Redoc is distributed under the MIT License.
+
+WHY THIS FILE IS A PLACEHOLDER
+------------------------------
+The vendored bundle opens with:
+
+    /*! For license information please see redoc.standalone.js.LICENSE.txt */
+
+That companion file is produced by webpack and carries the extracted licence
+headers of Redoc AND of every third-party package compiled into the bundle. It
+ships alongside redoc.standalone.js in the upstream dist and was not copied when
+this bundle was vendored, so the pointer above led nowhere.
+
+The contents are NOT reproduced from memory here, because doing so would mean
+inventing attribution for packages whose notices cannot be read back out of a
+minified bundle. Do not treat this file as a substitute for the real one.
+
+WHAT TO DO
+----------
+When next re-vendoring Redoc, copy BOTH files out of the upstream dist:
+
+    redoc.standalone.js
+    redoc.standalone.js.LICENSE.txt      <- replaces this placeholder
+
+and record the version and source URL in the same commit, so the next person
+does not have to work out what is installed by reading the minified source.
+
+The version of the currently vendored bundle could not be determined: it has no
+version string, and no commit or document in this repository records it.
+
+RELATED
+-------
+Swagger UI is vendored in this same directory and DOES carry its upstream
+notice (swagger-ui.LICENSE.txt). That is the pattern this file should follow.
diff --git a/tests/test_core/test_api_docs_tryit.py b/tests/test_core/test_api_docs_tryit.py
index 44b07933..93b7cc3e 100644
--- a/tests/test_core/test_api_docs_tryit.py
+++ b/tests/test_core/test_api_docs_tryit.py
@@ -266,7 +266,13 @@ def test_the_redoc_page_follows_the_system_theme(client):
 
     assert 'Redoc.init' in page
     assert '<redoc spec-url' not in page, 'the element takes no theme'
-    assert '@media (prefers-color-scheme: dark)' in page
+    # The page now follows the app's own stored choice first and only falls
+    # back to the OS, so assert the whole chain rather than the media query
+    # alone: the storage key, the attribute both the CSS and the Redoc theme
+    # key off, and the fallback.
+    assert '"shopdb-theme"' in page
+    assert 'data-theme' in page
+    assert 'prefers-color-scheme: dark' in page
     assert 'var DARK=' in page and 'var LIGHT=' in page
 
     # Re-render on a live scheme change, with the fallback for the older