Feat v0.6.16 usability survey gate

Machine-auditable UI quality gate: four audit scripts, structured survey
prompt, WCAG contrast fixes, mobile touch targets, focus indicators, and
Docker Hub documentation correction.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

docs/DEPLOYMENT.md

@@ -3,14 +3,14 @@
 ## Docker Single-Instance
 
 ```bash
-docker pull ghcr.io/armature/armature:latest
+docker pull gobha/armature:latest
 docker run -p 8080:80 \
   -e ARMATURE_ADMIN_USERNAME=admin \
   -e ARMATURE_ADMIN_PASSWORD=changeme \
   -e JWT_SECRET="$(openssl rand -hex 32)" \
   -e ENCRYPTION_KEY="$(openssl rand -hex 32)" \
   -v armature-data:/data \
-  ghcr.io/armature/armature:latest
+  gobha/armature:latest
 ```
 
 This runs with SQLite and PVC storage. Suitable for evaluation and small teams.
@@ -29,7 +29,7 @@ services:
       - pg_data:/var/lib/postgresql/data
 
   armature:
-    image: ghcr.io/armature/armature:latest
+    image: gobha/armature:latest
     ports:
       - "8080:80"
     environment:

docs/DISTRIBUTION.md

@@ -3,11 +3,11 @@
 ## Quick Start
 
 ```bash
-docker pull ghcr.io/armature/armature:latest
+docker pull gobha/armature:latest
 docker run -p 8080:80 \
   -e ARMATURE_ADMIN_USERNAME=admin \
   -e ARMATURE_ADMIN_PASSWORD=changeme \
-  ghcr.io/armature/armature:latest
+  gobha/armature:latest
 ```
 
 On first run, bundled packages are automatically installed — workflows, surfaces, and extensions are ready to use immediately.
@@ -66,12 +66,12 @@ Set `BUNDLED_PACKAGES` to control which packages are installed:
 # Install ALL packages (everything in the image)
 docker run -p 8080:80 \
   -e BUNDLED_PACKAGES="*" \
-  ghcr.io/armature/armature:latest
+  gobha/armature:latest
 
 # Install specific packages only
 docker run -p 8080:80 \
   -e BUNDLED_PACKAGES="notes,tasks,schedules" \
-  ghcr.io/armature/armature:latest
+  gobha/armature:latest
 ```
 
 Empty (default) installs the curated default set. Use `*` to install all packages. This is useful for Helm charts where different environments need different packages.
@@ -83,7 +83,7 @@ Set `SKIP_BUNDLED_PACKAGES=true` to prevent bundled packages from being installe
 ```bash
 docker run -p 8080:80 \
   -e SKIP_BUNDLED_PACKAGES=true \
-  ghcr.io/armature/armature:latest
+  gobha/armature:latest
 ```
 
 ### Custom Bundle Directory
@@ -94,7 +94,7 @@ Override the default bundled packages location with `BUNDLED_PACKAGES_DIR`:
 docker run -p 8080:80 \
   -e BUNDLED_PACKAGES_DIR=/custom/packages \
   -v /host/packages:/custom/packages \
-  ghcr.io/armature/armature:latest
+  gobha/armature:latest
 ```
 
 ## Builder Image
@@ -102,7 +102,7 @@ docker run -p 8080:80 \
 The builder image pre-caches Go modules and Node dependencies for faster custom builds.
 
 ```bash
-docker pull ghcr.io/armature/builder:latest
+docker pull gobha/armature-builder:latest
 ```
 
 ### What It Caches
@@ -117,7 +117,7 @@ docker pull ghcr.io/armature/builder:latest
 Reference the builder image as a base stage in your Dockerfile:
 
 ```dockerfile
-FROM ghcr.io/armature/builder:latest AS builder
+FROM gobha/armature-builder:latest AS builder
 WORKDIR /app
 COPY server/ .
 RUN go build -ldflags="-s -w" -o /bin/armature .
@@ -148,7 +148,7 @@ To exclude specific packages from the bundle, either:
 ### Forking for Custom Builds
 
 ```bash
-git clone https://github.com/armature/armature.git
+git clone https://github.com/gobha/armature.git
 cd armature
 
 # Add/modify packages
@@ -189,13 +189,13 @@ docker run -p 8080:80 \
   -e DATABASE_URL="postgres://user:pass@host:5432/armature?sslmode=require" \
   -e JWT_SECRET="$(openssl rand -hex 32)" \
   -e ENCRYPTION_KEY="$(openssl rand -hex 32)" \
-  ghcr.io/armature/armature:latest
+  gobha/armature:latest
 
 # SQLite (evaluation only)
 docker run -p 8080:80 \
   -e DB_DRIVER=sqlite \
   -v armature-data:/data \
-  ghcr.io/armature/armature:latest
+  gobha/armature:latest
 ```
 
 ### Storage

docs/USABILITY-SURVEY.md

@@ -0,0 +1,227 @@
+# Armature Usability Survey — Automated Checklist
+
+> **Purpose**: Machine-auditable quality gate for the Armature UI.
+> Run all scripts first, then walk each section. A FAIL in any section blocks release.
+
+---
+
+## Prerequisites
+
+Run these scripts from the project root and save their output:
+
+```bash
+bash scripts/generate-ui-inventory.sh > ui-inventory.json
+bash scripts/check-contrast.sh > contrast-report.txt
+bash scripts/generate-coverage-matrix.sh > coverage-matrix.md
+bash scripts/audit-touch-targets.sh > touch-targets-report.txt
+```
+
+---
+
+## Section 1: Viewport Correctness
+
+**Pass criteria:**
+- No CSS file uses `100vh` (should be `100%` or `100dvh`)
+- `.sw-shell` uses `height: 100%`, not `100vh`
+- All extension surfaces use `height: 100%`
+- No `transform: scale()` for zoom (should use CSS `zoom`)
+
+**Files to inspect:**
+- `src/css/sw-shell.css`
+- `src/css/layout.css`
+- `packages/*/css/main.css`
+
+**How to check:**
+```bash
+grep -rn '100vh' src/css/ packages/*/css/ --include='*.css'
+grep -rn 'transform.*scale' src/css/ packages/*/css/ --include='*.css'
+```
+
+**Result:** PASS if zero matches. FAIL if any `100vh` or `transform: scale()` for layout sizing.
+
+---
+
+## Section 2: Banner Integration
+
+**Pass criteria:**
+- Banners are in-flow (no `position: fixed` on banner elements)
+- `--banner-top-height` and `--banner-bottom-height` are defined in `:root`
+- Shell layout accounts for banner height via CSS variables, not hardcoded px
+- No surface hardcodes `28px` or other banner height values
+
+**Files to inspect:**
+- `src/css/sw-shell.css`
+- `src/css/variables.css` (`:root` block)
+- `src/js/sw/shell/app-shell.js`
+
+**How to check:**
+```bash
+grep -n 'position.*fixed' src/css/sw-shell.css | grep -i banner
+grep -n '28px' src/css/ -r --include='*.css'
+grep -n 'banner-top-height\|banner-bottom-height' src/css/variables.css
+```
+
+**Result:** PASS if banners are in-flow and height is variable-driven. FAIL if fixed positioning or hardcoded heights.
+
+---
+
+## Section 3: Responsive Behavior
+
+**Pass criteria:**
+- Kernel CSS uses `768px` (mobile) and `1024px` (tablet) breakpoints
+- No hardcoded widths that break below 768px (except intentional min-widths on dialogs)
+- Sidebar collapses on mobile
+- Extension surfaces adapt to narrow viewports
+
+**Files to inspect:**
+- `src/css/layout.css`
+- `src/css/surfaces.css`
+- `packages/*/css/main.css`
+
+**How to check:**
+```bash
+# Verify breakpoints used
+grep -rn '@media.*max-width' src/css/ --include='*.css' | grep -v '768\|1024'
+# Check for hardcoded widths
+grep -rn 'width:.*[0-9]\+px' src/css/layout.css | grep -v 'max-width\|min-width\|--'
+```
+
+**Result:** PASS if only 768px and 1024px breakpoints. WARN if other breakpoints exist but are justified. FAIL if layout breaks below 768px.
+
+---
+
+## Section 4: Styling Consistency
+
+**Pass criteria:**
+- All spacing uses `--sp-*` tokens (no raw px for padding/margin/gap > 3px)
+- All `border-radius` uses `--radius-sm`, `--radius`, or `--radius-lg`
+- All `font-family` uses `var(--font)` or `var(--mono)`
+- No external font CDN imports (`@import url(` or Google Fonts references)
+- No stale fallback colors (`#b38a4e` or other non-token hex in property values)
+
+**Files to inspect:**
+- All `src/css/*.css`
+- `packages/*/css/main.css`
+
+**How to check:**
+```bash
+# Raw px spacing (padding/margin/gap > 3px, not inside var())
+grep -rnE '(padding|margin|gap):\s*[0-9]+(px|rem)' src/css/ packages/*/css/ --include='*.css' | grep -v 'var(--' | grep -v '0px\|1px\|2px\|3px'
+# Raw border-radius
+grep -rn 'border-radius:' src/css/ packages/*/css/ --include='*.css' | grep -v 'var(--radius'
+# External fonts
+grep -rn '@import url\|fonts.googleapis' src/css/ --include='*.css'
+# Stale fallback gold color
+grep -rn '#b38a4e' src/css/ packages/*/css/ --include='*.css'
+```
+
+**Result:** PASS if zero non-token values (excluding reset/keyframe contexts). WARN for 1-3 edge cases with justification. FAIL for systematic violations.
+
+---
+
+## Section 5: Accessibility — Contrast
+
+**Pass criteria:**
+- `contrast-report.txt` shows all PASS for normal text (4.5:1 ratio)
+- No FAIL results in either dark or light theme
+
+**Files to inspect:**
+- `contrast-report.txt` (generated above)
+
+**How to check:**
+```bash
+grep 'FAIL' contrast-report.txt
+```
+
+**Result:** PASS if zero FAIL lines. FAIL if any contrast violation.
+
+---
+
+## Section 6: Accessibility — Touch Targets
+
+**Pass criteria:**
+- `touch-targets-report.txt` shows zero violations
+- All close buttons have `min-width: 44px; min-height: 44px` in `@media (max-width: 768px)`
+- Menu items have `min-height: 44px` on mobile (already done in `sw-primitives.css`)
+
+**Files to inspect:**
+- `touch-targets-report.txt` (generated above)
+- `src/css/sw-primitives.css` — close button rules
+
+**How to check:**
+```bash
+grep 'FAIL\|MISSING' touch-targets-report.txt
+```
+
+**Result:** PASS if zero violations. FAIL if any close button lacks mobile touch target.
+
+---
+
+## Section 7: Accessibility — Focus Indicators
+
+**Pass criteria:**
+- All interactive primitives have `:focus-visible` styles
+- No `outline: none` without a replacement focus indicator
+- Focus ring is visible on both dark and light themes
+
+**Files to inspect:**
+- `src/css/sw-primitives.css`
+- `src/css/primitives.css`
+- `src/css/variables.css`
+
+**How to check:**
+```bash
+# Check for focus-visible on key primitives
+for cls in sw-btn sw-input sw-dropdown__trigger sw-menu__item sw-tabs__tab; do
+  echo -n "$cls: "
+  grep -c "\.${cls}.*:focus-visible\|\.${cls}:focus-visible" src/css/sw-primitives.css src/css/primitives.css 2>/dev/null || echo "0"
+done
+# Check for outline:none without replacement
+grep -n 'outline.*none\|outline.*0' src/css/*.css | grep -v 'focus-visible\|focus-within'
+```
+
+**Result:** PASS if all 5 key primitives have `:focus-visible`. WARN if outline:none exists with adequate replacement. FAIL if missing focus indicators.
+
+---
+
+## Section 8: Component Uniformity
+
+**Pass criteria:**
+- `coverage-matrix.md` shows no deprecated component usage (no ⚠ in the deprecated row)
+- All surfaces use `sw-*` primitives, not old `.btn-*`, `.toast`, `.popup-menu`
+
+**Files to inspect:**
+- `coverage-matrix.md` (generated above)
+
+**How to check:**
+```bash
+grep '⚠' coverage-matrix.md
+```
+
+**Result:** PASS if zero ⚠ markers. FAIL if any deprecated component still in use.
+
+---
+
+## Scoring
+
+| Section | Weight | Result |
+|---------|--------|--------|
+| 1. Viewport Correctness | Required | |
+| 2. Banner Integration | Required | |
+| 3. Responsive Behavior | Required | |
+| 4. Styling Consistency | Required | |
+| 5. Contrast | Required | |
+| 6. Touch Targets | Required | |
+| 7. Focus Indicators | Required | |
+| 8. Component Uniformity | Required | |
+
+**Overall:** PASS requires all sections PASS or WARN. Any FAIL blocks the release.
+
+---
+
+## After the Survey
+
+1. Fix all FAIL items
+2. Re-run affected scripts to confirm fixes
+3. Re-run the full survey
+4. Tag `v0.6.16` only after a clean survey pass