Dev

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

@@ -10,6 +10,10 @@ Use this skill for `apps/phone_flutter/`, `apps/wear_android/`, and `apps/watchf
 ## Surface Responsibilities
 
 - Phone app is the primary dashboard and settings surface.
+- Plan auth: Codex = device-code OAuth; Claude = Claude Code PKCE (browser + pasted
+  `CODE#STATE`); Cursor plan = in-app WebView dashboard sign-in (captures
+  `WorkosCursorSessionToken`; Advanced paste via «?»). Not OAuth. Platform rows stay Admin API
+  keys.
 - Wear OS app is a compact dashboard, not a settings or credential-entry app.
 - WFF watch face is a glanceable status surface and launcher, not a full dashboard.
 
@@ -18,22 +22,62 @@ Use this skill for `apps/phone_flutter/`, `apps/wear_android/`, and `apps/watchf
 - Own provider setup, credential entry, secure storage integration, platform transport, sync scheduling, diagnostics export, and Wear Data Layer send.
 - Consume dashboard snapshots from Rust.
 - Show today, week, month, provider list, provider details, charts, budgets, credits, sync status, 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.
 - Keep analytics UI dense, clear, and operational rather than marketing-like.
 
 ## Wear OS App
 
-- Show today, week, providers, alerts, and last sync.
+- **App Glance (home page)** follows `docs/product/WEAR_GLANCE_DESIGN.md` (**locked 2026-07-26**):
+  text legend (not a face clone) — mini remaining arcs, tightest-first, per-provider credits.
+  Refresh: `OK`/`!OK` inside dual-arrow glyph; cadence = gray `OK`+disabled; provider limit =
+  gray `!OK`+`Rate limited`+disabled; `Stale` = orange `!OK`+enabled. `Alerts: N` when `N > 0`.
+  Phone owns allowance (`manualRefreshAllowed` / `manualRefreshAvailableAt` on schema v7)
+  from the PollCadence hard floor, not the Settings auto-poll slider. Wear must not invent
+  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**
+  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.
+- 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%`)
+  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.
 - 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.
+- Keep screens glanceable; avoid long tables and cheap floating caption stacks.
 
 ## Watch Face Format
 
-- Keep WFF declarative and minimal.
-- Show only today/week/status state where supported.
+- Keep WFF declarative and minimal; follow the same concentric language as Wear (not
+  side-by-side `RING 1` / `RING 2` placeholders).
+- 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()`.
+  `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.
 - Support tap-to-open into the Wear OS app where possible.
-- Keep ambient mode readable.
+- Keep ambient mode readable (dim arcs, strips off).
 
 ## Phone-To-Watch Flow
 
@@ -49,3 +93,8 @@ Phone sync worker
 ```
 
 Do not make the watch responsible for provider sync in the MVP.
+
+## Assets
+
+- Keep runtime images in the owning app's standard asset or resource directory.
+- Export from the owning OpenPencil source; do not make platform builds depend on design tooling.

.agents/skills/docs-gate/SKILL.md

@@ -13,6 +13,9 @@ Use this skill before changing durable project knowledge.
 - Root `AGENTS.md`: short working agreements for agents and humans.
 - Root `LICENSE`, `TRADEMARKS.md`, and `THIRD_PARTY_NOTICES.md`: Apache-2.0 source license, brand usage, and attribution gate.
 - `docs/README.md`: index and gate for project documentation.
+- `docs/DOCUMENTATION.md`: documentation ownership, Vocs tooling, and contributor workflow.
+- `docs/DESIGN_ASSETS.md`: OpenPencil ownership and runtime export workflow.
+- `docs/site/`: Vocs configuration, navigation, and thin presentation pages.
 - `docs/DEVELOPMENT_PLAN.md`: full product and implementation plan.
 - `docs/product/ANDROID_GOALS.md`: Android MVP goals and non-goals.
 - `docs/product/PROVIDER_NOTES.md`: provider integration assumptions and open questions.
@@ -25,6 +28,8 @@ Use this skill before changing durable project knowledge.
 ## Rules
 
 - Link new durable docs from `docs/README.md`.
+- Keep authoritative prose in `docs/` or beside its owning component; Vocs pages should import it instead of copying it.
+- Update `docs/site/vocs.config.ts` when an exposed document is added, removed, or renamed.
 - Keep root docs concise; move detailed requirements into `docs/`.
 - Keep root `AGENTS.md` aligned with `.agents/skills/*` when workflow checks or ownership boundaries change.
 - Keep Apache-2.0 source licensing and WardPulse brand rights separate.
@@ -39,5 +44,6 @@ Use this skill before changing durable project knowledge.
 - Is this information operational, product, security, provider, release, schema, or fixture knowledge?
 - Is it duplicated somewhere else?
 - Will another agent know where to find it from `docs/README.md`?
+- Is the Vocs page and navigation current when this document is exposed on the site?
 - Does this change alter phase scope in `docs/DEVELOPMENT_PLAN.md`?
 - Does this create a public contract that should be represented in `schemas/`?

.agents/skills/finalization/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: finalization
-description: Post-change finalization checklist for WardPulse (Rust core, Flutter phone shell, Kotlin Wear OS shell, WFF watch face, shared schemas, fixtures, docs, and tooling). Use after completing feature, fix, refactor, documentation, or structure work before handoff or commit drafting.
+description: Post-change finalization checklist for WardPulse (Rust core, Flutter phone shell, Kotlin Wear OS shell, WFF watch face, shared schemas, fixtures, Vocs documentation, and tooling). Use after completing feature, fix, refactor, documentation, or structure work before handoff or commit drafting.
 ---
 
 # Finalization — WardPulse
@@ -9,14 +9,15 @@ 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-06-28
+> Last Updated: 2026-07-24
 
 ## 1. Scope Review
 
 - [ ] Changes match the current product phase in `docs/DEVELOPMENT_PLAN.md`.
 - [ ] Root files stay short and operational; durable requirements stay under `docs/`.
 - [ ] No generated platform project noise was added unless the user asked for it.
 - [ ] No unrelated local or user changes were reverted.
+- [ ] Changed OpenPencil sources and their generated runtime exports are staged together.
 - [ ] Changes follow root `AGENTS.md` working agreements.
 
 ## 2. Boundary Review
@@ -31,7 +32,7 @@ description: Post-change finalization checklist for WardPulse (Rust core, Flutte
 
 ## 3. Security Review
 
-- [ ] No provider credentials, authorization headers, raw prompts, or sensitive raw provider payloads were committed.
+- [ ] No provider credentials, authorization headers, raw prompts, or sensitive raw provider payloads entered the change set.
 - [ ] Logs, fixtures, examples, and docs use redacted or mock data.
 - [ ] Credential rules in `docs/product/SECURITY_MODEL.md` still match implementation assumptions.
 - [ ] Wear OS and watch face surfaces do not gain credential entry or credential storage responsibilities.
@@ -55,23 +56,107 @@ cd apps/phone_flutter && flutter analyze && flutter test
 - [ ] 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 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
 
 - [ ] `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.
+- [ ] Vocs pages import authoritative Markdown instead of duplicating it.
 - [ ] `README.md` still describes the current repository shape and commands.
 - [ ] 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. Handoff Summary
+## 6. Staging And Commit Boundary
+
+**Finalization never creates a git commit.**
+
+When the user asks to finalize, finish checks, then stage only the files that belong to
+this change set (`git add` the relevant paths). Stop there.
+
+- Do **not** run `git commit`, `git commit --amend`, or any equivalent.
+- Do **not** treat "finalize", "finalization", "handoff", or "stage" as permission to commit.
+- Create a commit only when the user explicitly asks to commit (for example "commit",
+  "create a commit", "закоммить").
+- 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
+
+Draft commit messages in Conventional Commits form:
+
+```text
+type(scope): imperative summary
+```
+
+Rules:
+
+- Prefer a small single-line message with no body. A subject line alone is the default and the preferred form; do not append details, rationale, or file lists just because they exist.
+- Use `type(scope):` with a lowercase type and a short scope. Do not draft bare subjects such as `docs: …` when a scope applies.
+- Keep the subject imperative, about 72 characters or fewer, and focused on why the change lands.
+- Add a body only when the change is genuinely unclear without it. Treat a body as the exception, not the habit.
+- Do not insert line breaks without a reason. Write each body paragraph as one single line and let the git client wrap it; never hard-wrap a sentence across several lines.
+- Use a line break only to separate the subject from the body, to separate paragraphs, or to list items.
+- Match recent `git log` style. Prefer existing scopes over inventing new ones.
+
+Common types:
+
+| Type | Use for |
+| --- | --- |
+| `feat` | user-visible capability or contract addition |
+| `fix` | bug or incorrect behavior correction |
+| `chore` | planning, maintenance, tooling, or non-user-facing docs/process updates |
+| `docs` | documentation-only product/site prose when `chore(docs)` is too weak a fit |
+| `test` | tests only |
+| `ci` | GitHub Actions or check wiring |
+| `refactor` | internal restructuring without behavior change |
+
+Common scopes:
+
+| Scope | Owns |
+| --- | --- |
+| `docs` | `docs/`, Vocs site, planning, provider/security/release notes |
+| `core` | Rust domain crates |
+| `providers` | provider adapters and contracts spanning providers |
+| `openai` / `codex` / `claude` / `cursor` | one provider family |
+| `phone` | Flutter phone shell |
+| `wear` | Wear OS shell |
+| `watchface` | WFF package |
+| `sync` | phone-to-watch transport |
+| `design` | OpenPencil sources and brand exports |
+| `agents` | `.agents/skills/` and agent workflow |
+| `android` | shared Android harness or toolchain notes |
+
+Preferred examples, single line and no body:
+
+```text
+chore(docs): plan adaptive provider UI, polling, and watch rings
+feat(providers): add on-device Codex usage reporting
+fix(wear): sync live provider data to watch surfaces
+chore(agents): document conventional commit drafting
+```
+
+When a body is genuinely required, keep it on one line:
+
+```text
+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
 
 When finalization completes, report:
 
 1. Relevant checklist sections completed or skipped with reason.
 2. Commands run and pass/fail status.
 3. Important files changed.
 4. Remaining risks or intentionally deferred work.
-5. Git staging status: staged, unstaged, and untracked state.
-6. Idiomatic draft commit message for the staged set.
+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.
 
-Do not create a commit unless the user explicitly asks for one.
+Remind the user that the changes are staged only and that no commit was created.

.agents/skills/project-structure/SKILL.md

@@ -10,6 +10,8 @@ Use this skill before adding or moving project files.
 ## Source Of Truth
 
 - Read `docs/README.md` for the documentation gate.
+- Read `docs/DOCUMENTATION.md` when the change affects the Vocs site or documentation workflow.
+- Read `docs/DESIGN_ASSETS.md` when the change affects editable or exported visual assets.
 - Read `docs/DEVELOPMENT_PLAN.md` when the change affects architecture, product scope, or phase sequencing.
 - Read root `AGENTS.md` for repository-wide working agreements.
 - Keep the root clean: `README.md`, `justfile`, repository config, and short operational files only.
@@ -26,15 +28,18 @@ Use this skill before adding or moving project files.
 - `schemas/`: shared JSON contracts.
 - `fixtures/`: sanitized provider and dashboard examples.
 - `bindings/`: generated bindings and thin platform wrappers.
-- `brand/`: protected product identity assets and store artwork placeholders.
+- `brand/`: protected product identity, shared OpenPencil sources, and store artwork placeholders.
 - `tools/`: repeatable local automation.
 - `docs/product/`: durable product, provider, security, and release guidance.
+- `docs/site/`: Vocs workspace, navigation, and thin pages that present authoritative Markdown.
 
 ## Rules
 
 - Do not make Rust depend on Flutter, Android, Google Play APIs, or platform credential storage.
 - Do not make platform apps own shared product math or provider normalization.
 - Do not put long product requirements in root files.
+- Do not duplicate component or durable documentation in Vocs pages; import the owning Markdown file.
+- Keep app-specific OpenPencil sources under their owning app; keep shared identity sources in `brand/icons/`.
 - Do not treat files in `brand/` as Apache-2.0 licensed unless a file explicitly says so.
 - Do not add cross-platform abstractions until they remove real duplication or encode a stable boundary.
 - Prefer lightweight shells until a phase explicitly requires generated Flutter or Gradle projects.

.github/workflows/docs.yml

@@ -0,0 +1,30 @@
+name: Docs
+
+on:
+  pull_request:
+    branches: [main]
+    paths:
+      - "docs/**"
+      - "apps/**/README.md"
+      - "bindings/**/README.md"
+      - ".npmrc"
+      - ".nvmrc"
+      - "package.json"
+      - "package-lock.json"
+      - ".github/workflows/docs.yml"
+
+permissions:
+  contents: read
+
+jobs:
+  docs:
+    name: Build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-node@v6
+        with:
+          node-version-file: .nvmrc
+          cache: npm
+      - run: npm ci
+      - run: npm run docs:build

.gitignore

@@ -16,6 +16,11 @@ debug/
 __pycache__/
 *.py[cod]
 
+# Node.js / Vocs
+node_modules/
+docs/site/dist/
+docs/site/.vocs/
+
 # Flutter / Dart
 .dart_tool/
 .flutter-plugins

.npmrc

@@ -0,0 +1 @@
+engine-strict=true

.nvmrc

@@ -0,0 +1 @@
+v24.18.0

AGENTS.md

@@ -17,8 +17,10 @@
 - Keep platform shells responsible for UI, transport, storage, background scheduling, and phone-to-watch propagation.
 - Prefer small, focused changes.
 - Do not generate full Flutter or Gradle projects unless the current task explicitly requires it.
+- Do not create a git commit unless the user explicitly asks to commit. Finalization stages relevant files and drafts a message; it does not commit.
 - Do not commit secrets, provider credentials, authorization headers, raw prompts, or sensitive raw provider payloads.
 - Do not treat WardPulse brand assets as covered by Apache-2.0 unless a file explicitly says so.
+- Keep OpenPencil `.fig` sources with their owner and regenerate runtime exports instead of editing them by hand.
 
 ## Required Checks
 
@@ -42,9 +44,17 @@ After local skill changes, run:
 python3 /home/neuroborus/.codex/skills/.system/skill-creator/scripts/quick_validate.py .agents/skills/<skill-name>
 ```
 
+After durable documentation, Vocs page, or navigation changes, run:
+
+```bash
+just check-docs
+```
+
 ## Documentation
 
 - Start from `docs/README.md` for durable project documentation.
 - Keep root `README.md` short and operational.
 - Keep product, provider, security, and release guidance in `docs/product/`.
+- Keep component-specific guidance beside its owner and expose it through thin pages in `docs/site/`.
+- Update `docs/site/vocs.config.ts` when site navigation changes.
 - Update local skills in `.agents/skills/` when repository workflow or ownership boundaries change.