Release

.agents/skills/android-surfaces/SKILL.md

@@ -20,14 +20,33 @@ Use this skill for `apps/phone_flutter/`, `apps/wear_android/`, and `apps/watchf
 ## Phone App
 
 - Own provider setup, credential entry, secure storage integration, platform transport, sync scheduling, diagnostics export, and Wear Data Layer send.
+- **Dashboard status marks** follow `docs/product/PHONE_DASHBOARD_DESIGN.md` (**rules locked
+  2026-08-13**): `Ok` draws nothing; a rollup counts the problems rendered below it and shows a
+  count where a leaf shows a glyph; family color stays
+  identity; rank from `ProviderStatus::severity`, never a new list.
 - Consume dashboard snapshots from Rust.
-- Show today, week, month, provider list, provider details, charts, budgets, credits, sync status, and settings.
+- Show today, week, month, provider plaques on Dashboard, charts, budgets, credits, sync
+  status, Providers connection hub, and Settings.
 - Phase 14 primary tabs: Dashboard → Watchface → Widget → Providers → Settings. Watchface owns
-  Wear/WFF ring-slot prefs; Widget owns phone home-widget prefs. Do not keep those controls in
-  Settings once the tabs land (Settings “Watch display” is transitional only).
-- Do not add a phone Alerts tab. Active alerts render on the Dashboard; alert rules and budget
-  thresholds belong in Settings on connection rows / a global budget card (editable even when
-  Not connected). Providers consumes status; it does not own rule creation.
+  Wear/WFF ring-slot prefs; Widget owns phone home-widget prefs and the Android App Widget
+  (`PHONE_WIDGET_DESIGN.md` locked). Phone widget **hugs** complete rows/columns inside
+  the resize cell (olive `wrap_content`; hide trailing rows and right-hand columns that
+  would clip — credits → label → `%`; unused cell area is wallpaper until the user shrinks
+  the span), vertical+horizontal resize (default ~3 cells), day/night chrome, overlay face
+  watermark (no header band), expands Claude windows, keeps exhausted plan pools as
+  `0% left`, and appends per-provider purchased credits end-aligned (label centered).
+  Watchface still collapses Claude / omits exhausted. Do not keep
+  those controls in Settings.
+- **Providers** owns the full connection catalog (Connected / Not connected), credentials /
+  auth, and **all user-configured** alert thresholds (plan/purchased per connection;
+  Today/Week/Month budgets on OpenAI Platform). One threshold per meter; UI speaks
+  **% left** (storage/Rust keep used% as `at`). Editable before first sync. Do not keep
+  alert rules under Settings.
+- **Settings** is systemic only: global polling interval, diagnostics, data deletion,
+  legal, debug toggles — not connections, credentials, display surface toggles, or alerts.
+- Do not add a phone Alerts tab. Active alerts render on the Dashboard. Thresholds are
+  **user-configured only** — never invent alerts from hard-coded 80%/100% utilization cutoffs.
+  Provider status chrome (Warning / RateLimited) is separate from the alerts list.
 - Keep analytics UI dense, clear, and operational rather than marketing-like.
 
 ## Wear OS App
@@ -41,41 +60,70 @@ Use this skill for `apps/phone_flutter/`, `apps/wear_android/`, and `apps/watchf
   a local cooldown. Review art: `preview-glance-legend-*.png`. Compose: `GlanceLegendPage`
   (+ watch→phone refresh message).
 - **Watch face / WFF** (and any face-like complication preview) follow
-  `docs/product/WATCH_RING_DESIGN.md` (**locked 2026-07-25**): **inner/center = tightest**
+  `docs/product/WATCH_RING_DESIGN.md` (**locked 2026-07-25**; later revisions are listed in the
+  document header): **inner/center = tightest**
   remaining (plan `%` primary; credit request-runway secondary from internal costs — never show
-  request counts); arc = remaining; large time hero; sunk family strips (equal width; first strip
-  nearest center; stroke tuned so 3 strips clear arcs); family colors. Future multi-profile /
-  hatch / three-ring cap notes there are planning-only until a later phase.
+  request counts); arc = remaining (clockwise melt from 12); large time hero; sunk family strips
+  (equal width; first strip nearest center; stroke tuned so 3 strips clear arcs); family colors.
+  Hard cap: **three** concentric plan/budget rings (`watchRingSlotCount = 3`). Purchased meters
+  (Extra usage, on-demand, Codex credits) are not ring candidates — phone cards only; alerts
+  only via user thresholds on Providers.
+  Future multi-profile / hatch notes there are planning-only until a later phase.
 - Claude plan windows (`5h` / weekly / Opus / Sonnet) collapse to one watch ring on the phone
   (`allowance.claude.plan`); Glance shows the active window label. Phone dashboard still lists all.
-- Prefer concentric percent layers from schema v4+ on the **face** (up to four selected metrics
-  today); never invent `Unknown` filler. Unselected, unavailable, or exhausted (`>= 100%`)
+- Prefer concentric percent layers from schema v4+ on the **face** (up to three selected metrics);
+  never invent `Unknown` filler. Unselected, unavailable, or exhausted (`>= 100%`)
   layers do not render.
-- Face center (first) strip / `creditsGlance` may show a compact remaining-credits aggregate when
-  reported and Settings shows purchased usage (not a ring; never LLM `TOK`). App Glance credits
-  stay **per provider** with an explicit `credits` label.
-- Keep today, week, usage, providers, alerts (active list only — no rule editing), and last sync
-  as secondary detail screens.
+- Face strips show compact remaining credits per provider family from `allowances` (`% · 500`),
+  same matching rule as Glance; accents use the family ColorRamp. `creditsGlance` is for
+  credits-only faces when there are no plan rings.
+- Beside the Glance the app keeps exactly two surfaces: a **plan windows** page saying when each
+  window comes back (rules in `apps/wear_android/README.md`), and **Alerts** from the Glance pill
+  (active list only — no rule editing). The today, week, usage, providers, and last sync screens
+  were removed in Phase 17; do not bring a currency total back to the watch.
 - Store and render the latest successful watch summary.
 - Make stale data explicit.
 - Do not enter, display, or store provider credentials.
 - Keep screens glanceable; avoid long tables and cheap floating caption stacks.
 
 ## Watch Face Format
 
+- `watchface.xml` is written by `tools/render-watchface.mjs` (`just render-watchface`), together
+  with the ring-type drawables it names (`res/drawable-nodpi/`, ImageMagick as `just
+  export-icons` already uses). Change the generator, never the XML or the PNGs;
+  `just check-watchface` fails on drift. Geometry and canvas are both the **450**-unit design
+  language `WATCH_RING_DESIGN.md` locks — the canvas is what WFF renders at before scaling to
+  the screen, so raising it softens every edge on the face. Do not raise it to sharpen type:
+  WFF rounds each glyph of a `TextCircular` to a whole canvas unit, and the answer to that is
+  baking, not resolution.
 - Keep WFF declarative and minimal; follow the same concentric language as Wear (not
   side-by-side `RING 1` / `RING 2` placeholders).
+- **A scene holds at most eight `ComplicationSlot` elements** — the same in format versions 2, 4
+  and 5, so raising the version buys nothing. This face has used all eight since 2026-07-25
+  (four rings, four strips; the fourth of each was undrawn until the split-band revision took
+  the fourth ring). Count before designing anything that needs a new slot — the validator never
+  says "too many slots": a ninth is reported as `Invalid content was found starting with element
+  'ComplicationSlot'`, listing `PartText`, `PartImage`, `Condition` and friends as what it
+  expected instead.
 - WFF format version 2 (Wear OS 5+): concentric `RANGED_VALUE` arcs with `WeightedStroke`
   colors from Wear `ColorRamp` / `[COMPLICATION.RANGED_VALUE_COLORS]`; arc = remaining.
-  Keep track/progress `endAngle` under 360° (scale onto 359.9°) — a closed circle collapses
-  to a ROUND tip at 12 o'clock. Prefer simple Transform arithmetic over `clamp()`.
+  Keep track spans under 360° (scale onto 359.9°) — a closed circle collapses
+  to a ROUND tip. Remaining melts **clockwise from 12**: Transform `startAngle`
+  with `(1 - value/max) * 359.9` and fixed `endAngle` 359.9. Prefer simple
+  Transform arithmetic over `clamp()`.
   `BoundingArc` clips ring-slot content to the arc band — sunk `%` / credits strips must use
-  separate `BoundingBox` SHORT_TEXT slots of **equal width**, stacked inside the clear aperture.
-  Center (first) strip TEXT = full label (`100% · 500`); lower strips TEXT = remaining digits
-  with Template `%%`. Avoid `length(TITLE)` Conditions — they are unreliable on WFF. Draw strips
-  after `DigitalClock` so the clock does not cover them.
-- Prefer live arcs for selected layers, optional `creditsGlance` on the center strip when present,
-  large time. Never LLM `TOK` on the face.
+  separate `BoundingBox` `RANGED_VALUE` slots of **equal width**, stacked inside the clear
+  aperture. Every strip TEXT = full label (`46%` or `100% · 500`); accents use
+  `[COMPLICATION.RANGED_VALUE_COLORS]`. Avoid `length(TITLE)` Conditions — they are unreliable
+  on WFF. Draw strips after `DigitalClock` so the clock does not cover them.
+- A ring slot's TITLE carries the budget period (`D` / `7D` / `M`, empty for plan rings), and the
+  face repeats it around that band as background-colour cut-out type, branching on
+  `[COMPLICATION.TITLE]` equality to pick one baked image per ring and period. The type runs in
+  four sweeps with a bare break on each diagonal, aligned across rings; within a sweep tokens are
+  placed by rotation, and the repeat counts in `tools/render-watchface.mjs` are the fitted
+  constants both that generator and the review-art one read — copy, never hand-tune.
+- Prefer live arcs for selected layers, optional `creditsGlance` on the **matching provider**
+  strip when present, large time. Never LLM `TOK` on the face.
 - Support tap-to-open into the Wear OS app where possible.
 - Keep ambient mode readable (dim arcs, strips off).
 

.agents/skills/finalization/SKILL.md

@@ -9,7 +9,7 @@ description: Post-change finalization checklist for WardPulse (Rust core, Flutte
 >
 > Run this after implementation or documentation work to keep the monorepo coherent.
 >
-> Last Updated: 2026-07-24
+> Last Updated: 2026-08-01
 
 ## 1. Scope Review
 
@@ -44,25 +44,58 @@ description: Post-change finalization checklist for WardPulse (Rust core, Flutte
 ```bash
 cd core && cargo fmt --all -- --check
 cd core && cargo clippy --workspace --all-targets -- -D warnings
+cd core && RUSTDOCFLAGS="-D warnings" cargo doc --workspace --no-deps --document-private-items
 cd core && cargo test --workspace
 ```
 
 - [ ] If Flutter code changed and the project is generated, run:
 
 ```bash
-cd apps/phone_flutter && flutter analyze && flutter test
+just check-phone
 ```
 
+  This runs `dart format --set-exit-if-changed` over `apps/phone_flutter` and `bindings/dart`,
+  then `flutter analyze` and `flutter test`. Use `just fmt-phone` to apply formatting.
+
 - [ ] If Android/Wear/WFF Gradle projects are generated, run the relevant Gradle test/build task.
-- [ ] If schemas or fixtures changed, validate fixture shape manually or with `tools/validate-fixtures/` when available.
+- [ ] If schemas or fixtures changed, run `just validate-fixtures`: it parses every file and checks each golden fixture against its schema.
 - [ ] If GitHub Actions workflows changed, run `actionlint .github/workflows/*.yml`.
 - [ ] If durable docs, Vocs pages, component READMEs, or site navigation changed, run:
 
 ```bash
 just check-docs
 ```
 
-## 5. Documentation Review
+## 5. Emulator Check
+
+Automated gates do not exercise the app. Unit tests use fakes, so they never load
+`libward_pulse_ffi.so`, never resolve an exported symbol, and never render a screen.
+
+Run the app on an emulator when the change could only fail there:
+
+- [ ] FFI surface changed — exported symbol names, argument or return shapes, or the
+      Dart binding. Symbols resolve at **run time**, so a mismatch survives every build.
+- [ ] The serialized snapshot contract changed — a new or renamed field, or a different
+      value shape. Host-side round trips do not prove the Android build agrees.
+- [ ] UI, widget, watch face, or phone-to-watch payload behaviour changed.
+- [ ] Background scheduling, secure storage, or WebView sign-in changed.
+
+Skip it, and say so, for changes that cannot reach a device: pure refactors behind an
+unchanged contract, comments and docs, tests, CI wiring, lockfiles.
+
+```bash
+adb devices -l                     # phone and Wear AVDs are usually already running
+tools/build-android-rust/build.sh  # Rust .so for Android ABIs — slow
+cd apps/phone_flutter && flutter build apk --debug
+adb -s <serial> install -r build/app/outputs/flutter-apk/app-debug.apk
+adb -s <serial> shell am start -n app.wardpulse/.MainActivity
+adb -s <serial> logcat -d | grep -i wardpulse
+```
+
+Report what was exercised on device and what was not. "Tests pass" is not evidence that
+the app runs; only the device is.
+
+## 6. Documentation Review
 
 - [ ] `docs/README.md` links any new durable document.
 - [ ] The Vocs page and `docs/site/vocs.config.ts` navigation are updated for documentation exposed on the site.
@@ -71,7 +104,7 @@ just check-docs
 - [ ] Product, provider, release, or security docs are updated when behavior or boundaries changed.
 - [ ] Placeholder TODOs are acceptable only for intentionally deferred platform generation work.
 
-## 6. Staging And Commit Boundary
+## 7. Staging And Commit Boundary
 
 **Finalization never creates a git commit.**
 
@@ -85,7 +118,7 @@ this change set (`git add` the relevant paths). Stop there.
 - Draft the commit message for the staged set; leave the actual commit to the user or to a
   later explicit request.
 
-## 7. Commit Message Draft
+## 8. Commit Message Draft
 
 Draft commit messages in Conventional Commits form:
 
@@ -148,15 +181,16 @@ chore(docs): plan adaptive provider UI, polling, and watch rings
 Record the dual plan/platform model and phases 9–13, set the global refresh floor to 5–60 minutes, and make finalization stage-only with an explicit no-commit rule.
 ```
 
-## 8. Handoff Summary
+## 9. Handoff Summary
 
 When finalization completes, report:
 
-1. Relevant checklist sections completed or skipped with reason.
+1. Relevant checklist sections completed or skipped with reason, including whether the
+   change was exercised on an emulator.
 2. Commands run and pass/fail status.
 3. Important files changed.
 4. Remaining risks or intentionally deferred work.
 5. Git staging status after staging: what is staged, what remains unstaged or untracked.
-6. Idiomatic draft commit message for the staged set, using section 7.
+6. Idiomatic draft commit message for the staged set, using section 8.
 
 Remind the user that the changes are staged only and that no commit was created.

.agents/skills/rust-core/SKILL.md

@@ -18,6 +18,11 @@ Use this skill for work under `core/` and Rust-owned contracts.
 
 - Provider-specific raw data enters the core; normalized dashboard snapshots leave the core.
 - Rust owns budgets, credits, projections, alerts, model breakdowns, status mapping, and watch summary derivation.
+- Alert evaluation uses **user-configured** rules/thresholds from platform preferences
+  (`calculate_alerts(snapshot, settings)`). Each rule is a single used-% threshold (`at`).
+  Providers owns all alert rules (plan/purchased + OpenAI Platform budgets). Do not invent
+  dashboard alerts from allowance or budget `ProviderStatus` alone; status chrome and the
+  alerts list are separate.
 - Platform code owns HTTP clients, TLS, retries, background execution, secure credential retrieval, encrypted storage, and UI state.
 - Prefer deterministic functions that are easy to fixture-test.
 - Preserve previous successful snapshot semantics when modeling sync failure states.
@@ -40,6 +45,7 @@ After Rust changes, run:
 ```bash
 cd core && cargo fmt --all -- --check
 cd core && cargo clippy --workspace --all-targets -- -D warnings
+cd core && RUSTDOCFLAGS="-D warnings" cargo doc --workspace --no-deps --document-private-items
 cd core && cargo test --workspace
 ```
 

.claude/skills

@@ -0,0 +1 @@
+../.agents/skills

.github/workflows/core.yml

@@ -30,9 +30,12 @@ jobs:
         with:
           toolchain: ${{ matrix.rust }}
           components: rustfmt, clippy
-      - name: Validate JSON syntax
+      - name: Validate shared contracts
         working-directory: .
         run: python3 tools/validate-fixtures/validate_json.py
       - run: cargo fmt --all -- --check
       - run: cargo clippy --workspace --all-targets -- -D warnings
+      - run: cargo doc --workspace --no-deps --document-private-items
+        env:
+          RUSTDOCFLAGS: -D warnings
       - run: cargo test --workspace

.github/workflows/designs.yml

@@ -0,0 +1,36 @@
+name: Review Art
+
+on:
+  pull_request:
+    branches: [main]
+    paths:
+      - "tools/render-watch-ring-designs.mjs"
+      - "tools/render-wear-glance-designs.mjs"
+      - "tools/render-phone-widget-designs.mjs"
+      - "tools/render-brand-icons.mjs"
+      - "tools/design-output.mjs"
+      - "apps/*/design/**"
+      - "brand/icons/**"
+      - ".github/workflows/designs.yml"
+
+permissions:
+  contents: read
+
+jobs:
+  designs:
+    name: Check against generators
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-node@v6
+        with:
+          node-version-file: .nvmrc
+      - name: Install Noto and Pillow
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y --no-install-recommends fonts-noto-core python3-pil
+      - run: node tools/render-watch-ring-designs.mjs --check
+      - run: node tools/render-wear-glance-designs.mjs --check
+      - run: node tools/render-phone-widget-designs.mjs --check
+      - run: node tools/render-brand-icons.mjs --check

.github/workflows/phone-android.yml

@@ -44,7 +44,13 @@ jobs:
           targets: aarch64-linux-android,x86_64-linux-android
       - run: cargo install cargo-ndk --version 4.1.2 --locked
         working-directory: .
+      - name: Validate shared contracts
+        run: python3 tools/validate-fixtures/validate_json.py
+        working-directory: .
       - run: flutter pub get --enforce-lockfile
+      - run: dart format --output=none --set-exit-if-changed lib test
+      - run: dart format --output=none --set-exit-if-changed lib
+        working-directory: bindings/dart
       - run: flutter analyze
       - run: flutter test
       - run: tools/build-android-rust/build.sh

.github/workflows/watchface.yml

@@ -5,6 +5,8 @@ on:
     branches: [main]
     paths:
       - "apps/watchface_wff/**"
+      - "tools/render-watchface.mjs"
+      - "tools/design-output.mjs"
       - "tools/validate-watchface/**"
       - ".github/workflows/watchface.yml"
 
@@ -21,6 +23,9 @@ jobs:
         working-directory: apps/watchface_wff
     steps:
       - uses: actions/checkout@v6
+      - uses: actions/setup-node@v6
+        with:
+          node-version-file: .nvmrc
       - uses: actions/setup-java@v5
         with:
           distribution: temurin
@@ -32,4 +37,6 @@ jobs:
           packages: "platforms;android-37.1 build-tools;36.0.0"
       - run: tools/validate-watchface/validate.sh
         working-directory: .
+      - run: node tools/render-watchface.mjs --check
+        working-directory: .
       - run: ./gradlew --no-daemon lintDebug assembleDebug bundleDebug

.github/workflows/wear-android.yml

@@ -31,4 +31,7 @@ jobs:
         uses: android-actions/setup-android@v4
         with:
           packages: "platforms;android-37.1 build-tools;36.0.0"
+      - name: Validate shared contracts
+        run: python3 tools/validate-fixtures/validate_json.py
+        working-directory: .
       - run: ./gradlew --no-daemon lintDebug testDebugUnitTest assembleDebug assembleDebugAndroidTest

.gitignore

@@ -4,6 +4,8 @@
 !.env.example
 *.local
 *.log
+LOCAL_ARTIFACTS/
+/prepush.sh
 
 # Rust
 target/
@@ -28,6 +30,8 @@ docs/site/.vocs/
 .packages
 build/
 coverage/
+# Library package — consumers resolve deps; app lock lives under apps/phone_flutter/.
+bindings/dart/pubspec.lock
 
 # Android / Gradle
 .gradle/