Wave 9 #117: Repo hygiene — state field + tier rebrand

[bernardc6]

Wave 9 #117: Repo hygiene — state field + tier rebrand

Implements the 2026-08-03 Product Build Directive's first outstanding
follow-up (memory/roamcore/2026-08-03-directive.md §"Outstanding
follow-ups aligned with directive" item #1) — standardise connection
states + rephrase the tier-letter UI to the new vocabulary (RoamCore
Certified / Community Verified / Experimental).

Two coordinated sub-changes shipped:

1. state: field in every connections/<slug>/connection.yml
   (32 manifests) at the same YAML-indent level as tier: /
   status:, drawn from the 10 standard states in the directive
   ("Available / Detected / Ready to connect / Connecting /
   Connected / Needs information / Needs attention / Unsupported /
   Offline / Update available"). Most carries a one-line
   state_reason: plain-English explanation.

2. User-facing tier rebrand in the three in-scope legacy
   SUPERSEDED stubs (docs/catalog/{fans,nfc-tags,remote-access}/
   index.md), the home page tier-section + chips (docs/index.md),
   and the chip CSS (docs/styles/rc.css). The YAML tier: a/b/c
   letter is preserved as the programmer-facing sort key.

The 30+ sister catalog pages that still render legacy single-letter
chips (e.g. docs/catalog/lighting/index.md) are deliberately OUT OF
SCOPE for this slice — that's a separate, larger rebrand (would
touch 20+ pages and break hundreds of cross-references).

State assignment snapshot

state	count	connections
Connected	10	advanced-mode, agent-actions-allowlist, demo-mode, leveling, map-dashboard, mock-location-and-tracks, mode, openclaw-api, time-atomic, timezone-geolocator
Ready to connect	20	amenities-overlay, approach-lights, bluetooth-wifi-presence, deadbolts, dns-blocker, electronic-valves, fans, happijac, heated-floors, hvac-basics, motion-based-lighting, music-assistant, nas, peplink, remote-access, smart-automations, smoke-co-gas-sensors, starlink, teltonika, water-tanks
Available	2	in-cab-tablet-dashboard, nfc-tags

(Total: 32 = all 32 connection folders.)

The "Connected" decisions are grounded in homeassistant/packages/*.yaml
contract-tile presence (verified on this host): each tier-a integration
ships its rc_* contract entities baked into the HA package so the
tile is a real HA entity, not just a YAML manifest promise.

The "Ready to connect" recipes ship the recipe.md + manifest-honesty
tests but the operator wires the upstream integration to expose the
rc_* tiles (e.g. fan / Peplink / Teltonika / Starlink).

The "Available" tier-c recipes are DIY / community inspiration —
no HACS or vendor wiring; the upstream HA core helpers form the
contract layer.

Acceptance checklist

• Code change is minimal + additive (no rewrite of unrelated files)
• bash scripts/check.sh --core-only is GREEN (exit 0)
• Verification step is real (not a stub) — 8 new pytest tests
  in homeassistant/packages/tests/test_connection_state.py
  assert every connection.yml has a state: field, the value
  is one of the 10 standard states, the user-facing docs
  render the new vocabulary, the CSS supports the new chip
  classes, and no legacy single-letter chips leak into
  docs/index.md
• User-facing doc rebrand applies to the 3 in-scope legacy
  SUPERSEDED stubs + the home page support-level section +
  the chip CSS (IKEA-style 5 steps preserved on individual
  recipe pages — those were already cleaned up in Wave 9
  Wave 9 #119c — Phase 2 canonical vehicle model dashboard generator #124)
• Tier discipline honored (tier: a/b/c letters preserved
  for programmatic sorting; user-facing vocabulary in the
  new prose; no tier-letter chip in docs/index.md)
• Idempotent installer / config_flow: the state: insertion
  script is idempotent (skips files that already declare
  state:); the check.sh wiring is additive (no existing
  smoke check modified)
• No secrets in repo (manual grep; no .token / password /
  api_key / secret introduced anywhere)
• Commit message: Context / Changes / Verification / Rollback
• Branch subagent/repo-hygiene-state-and-tier-rebrand
  targeted from main (d3d596b); pushed to origin
• Direct-to-main push philosophy preserved (no force-push;
  clean rebase off main); PR is open with this body

Tier discipline note

• tier: a RoamCore Certified — RoamCore ships + maintains the
  integration code (e.g. openclaw-api custom component + map-dashboard
  • mock-location-and-tracks), and is bench-tested (Wave 9 Wave 9 #123.d.i — Phase 7 Acceptance Tests foundation + Gate A (clean install) #115
    power Victron bench rig added in PR Wave 9 #115: Power Victron bench integration tests #97). Three connections
    earn tier-a today (openclaw-api + map-dashboard +
    mock-location-and-tracks).
• tier: b Community Verified — well-understood recipe over upstream
  HA core + HACS add-ons. Operator wires the upstream integration
  to expose the rc_* contract tiles. 27 connections are at
  tier-b today.
• tier: c Experimental — DIY / community inspiration only. The
  upstream HA core helpers (input_boolean / input_text / input_select
  / scene / tag / automation UI) form the contract layer; no HACS
  code is required. 2 connections are at tier-c today
  (in-cab-tablet-dashboard + nfc-tags).

Doctrine (Bernard, 2026-08-04) application

• Verification is mandatory (runtime check, not just manifest-honesty):
  8 pytest tests assert the cross-cutting invariants; previously the
  directive's 10-state list existed in prose only.
• Idempotent installers: the Python insert script skips files that
  already declare state: so re-running produces the same end state.
• Tier discipline: tier: a/b/c letters unchanged — only the
  user-facing vocabulary was rephrased.
• User-facing repo hygiene: the rebrand is narrow (3 SUPERSEDED
  pages + the home page chip section + rc.css); sister catalog pages
  that still render <span class="rc-tier a">A</span> chips are
  deferred to a separate, larger rebrand slice (out of scope per
  the slice spec).

Diff stat

39 files changed, 588 insertions(+), 10 deletions(-)

Breakdown:

• 32 connections/<slug>/connection.yml (each gains state: +
  state_reason: lines)
• 3 legacy SUPERSEDED stub pages (docs/catalog/{fans,nfc-tags,
  remote-access}/index.md)
• docs/index.md (home page support-level section + chip rebrand)
• docs/styles/rc.css (chip CSS extension)
• scripts/check.sh (new smoke check wired into the chain — additive,
  no existing smoke modified)
• 1 NEW homeassistant/packages/tests/test_connection_state.py
  (8 new pytest tests covering the cross-cutting invariants)

Verification output

$ python3 -m pytest homeassistant/packages/tests/test_connection_state.py -v
... 8 passed in 0.49s

$ bash scripts/check.sh --core-only
[... all 30+ connection manifest honesty tests + ha-beta-smoke +
    roamcore-inventory + rclone-drive-health + victron-{checks,
    mapping-plan, rc-contract} + new state-field smoke PASS ...]
✓ all requested smoke checks passed.   (exit 0)

$ python3 scripts/build_catalog.py
[build_catalog] discovered 32 connection.yml files (0 skipped)
[build_catalog] user-facing: 27, excluded: 5
[build_catalog] wrote 27 catalog pages
[build_catalog] wrote 32-entry user-facing inventory (unchanged —
    inventory reflects YAML `tier:`, not `state:`)

Rollback

git revert 40b414b (or git reset --hard origin/main if the PR is
not yet merged). No infrastructure touched — pure repo-hygiene.

---

Verifier: bernardc6
Branch: subagent/repo-hygiene-state-and-tier-rebrand
Source of truth: memory/roamcore/2026-08-03-directive.md + Wave 9
unified-backlog.md row #117.