Files
vardkey/ai-note.md
T

45 KiB
Raw Blame History

AI Agent Note — VardKey

Short working handover for the next model. Keep it short.

  • TODO.md (Norwegian) is the requirement specification. Sections 1–18 are the binding spec; 19–31 are history; section 32 is the round in progress. The full reasoning is in the git history.
  • The binding rules live in TODO.md and README.md. This note does not repeat them — it carries the handover, the rules that are easy to get wrong, and the traps that already cost time.
  • HANDOVER.md and ai-thought.md were deleted as outdated. Do not recreate either.

Status

  • Done and verified: sections 1–31 and section 18 steps 1–11, plus section 32.1 (the icon), 32.2 (the UI pass and the retro theme), 32.3 (the alert and page texts), 32.4 (the bug report, rounds 32-A and 32-B) and 32.7 (the top-bar menu and the dashboard clean-up), each with its follow-up round. Schema version 12. 513 green tests. The StartOS package is built, sideloaded and running on a StartOS 0.4.0 box; the package version is still 0.1.0:0.
  • What is left: 32.6 the documentation drift, and then 32.5 the raise to 1.0.0:0 together with section 18 step 12. 32.6 has to come after the rounds it documents, and 32.5 last. One item inside 32.4 is left to the user: BR-003, a manual end-to-end pass — read the note under 32.4 before acting on it, because the report's own wording for it is out of date. The user's manual pass over the finished §32 work is outstanding as well.
  • A round stops when it is done. Do not start the next item unless the user asks.
  • Verified how: the automated suite, the user's manual browser testing, and the install and test round on a StartOS 0.4.0 box. The user runs the suite; the agent has no shell.
  • Tests: python3 -m unittest discover -s tests. They run on a Windows copy at C:\Users\<brukarnamn>\Downloads\helsesjekk, so they must pass there as well as on Linux.
  • Keep this note short. The finished §32 sub-rounds are one short line each in TODO.md §32, and the reasoning is in the git history. A finished round does not need its narrative back, and the two documents should not be rewritten in full every round.

Section 32 — what is left

  • 32.6 The documentation drift. README.md, docs/application.md, instructions.md, UPDATING.md, AGENTS.md and the package's own i18n strings are all behind the code, and TODO.md §32.6 lists what is wrong in each. It answers the rest of BR-004, and it must be done before 32.5, so the documents describe the released state. In one line, what the documents still miss: the login and session endpoints and the gating/CSRF rule, the CSV formula guard, the canonical path comparison, the local secret guard, the two summary fields, the moved field reminder, the added model field in the check detail, the icon link and the two PNGs, the top-bar menu, the removed dashboard cards, the export section and its note on the history page, the #history-detail anchor, and the robots rule.
  • 32.5 The version raise. 0.1.0:0 → 1.0.0:0, once 32.6 is done and the user says so. No schema change, no new endpoint, no new feature. startos/versions/ stays empty, because the app migrates its own schema.

BR-003 — the one open item in 32.4

The report says the manual end-to-end pass is still open, but it quotes a §31 text that no longer exists, and §16 and §17 record that the manual browser pass and the box tests were run and verified through §31. What is outstanding is the new manual work §32 added — the icon, the retro theme on a narrow phone, the alert texts, the top-bar menu, the cleaned dashboard, the export section on the history page, the PWA with the two PNG icons, and the whole box test again after 32.5 — plus the user's confirmation that it has been run. Do not re-verify what §16 and §17 already record as done. The other verdicts are settled: BR-001 is a false positive, BR-004 falls away, BR-005 is verified with no behaviour change, and BR-002, BR-006, BR-007 and BR-008 are fixed with regression tests. The report was written against a different file set and asks for eight documents that do not exist here; do not create them.

The wallet-secret guard (round 32-B)

secret_guard.py is the one place that decides whether a piece of text looks like a wallet secret. It is local (no network call), silent (the text never reaches a log, a message or an exception) and narrow (it matches only the shapes that are unmistakable, so an ordinary note is not refused).

  • What it recognises: a PEM private-key block; an extended private key with any SLIP-132 prefix (xprv, yprv, zprv, tprv, uprv, vprv) at 100 base58 characters or more; a WIF key (51 or 52 base58 characters starting 5, 9, K, L or c); a BIP38 key (6P, 58 characters); and a run of 12 or more consecutive BIP39 words, also in the middle of a sentence. It returns a short English label such as "a seed phrase", never the value, and rejection_message(field, label) never repeats it either.
  • The wordlist is embedded, 2048 words, from bitcoin/bips bip-0039/english.txt. tests/test_secret_guard.py checks it: 2048 words, alphabetical, 3–8 lower-case letters, and no two words sharing their first four letters. That last check is the strong one — the specification guarantees it, so a mistyped or missing word breaks it. Do not edit the list without that test.
  • Where it is wired in: validation.py calls _reject_secret() from the four text helpers _text, _key_name, _model and _required_path, so every free-text field is covered by construction. auth.py checks the admin username the same way; the password is deliberately not checked, because a long passphrase is a legitimate password and refusing one would lock the user out.
  • The refusal is a ValidationError (SecretDetected), so the existing handlers answer 400. app.py needed no change at all — do not add a handler for this. A plain ValueError would have been caught by STORAGE_ERRORS and answered 500.
  • The guard runs before the field's length limit. A seed phrase pasted into a 60-character label field is answered with "looks like a seed phrase", not with "too long" — the other order would invite the user to shorten a seed phrase instead of removing it. The limit is still the outer bound. This order is deliberate and pinned by tests; do not swap it back.
  • The reminder in the UI is one line, in the key setup — a single p.secret-warning above the whole key list in static/setup.html, and nowhere else; the per-field copies were removed in 32.2. The page notice is a different thing and stays on health-check.html, setup.html and settings.html. The server side is unchanged.
  • The limitations are documented in the module docstring and are not to be played down: a bare 64-character hex string is not refused (it is indistinguishable from a transaction id, which is legitimate note content); only the English wordlist is used; a secret split across several fields, or in a shape outside the patterns, is not caught; and a false positive is possible for a note that happens to be twelve or more BIP39 words in a row.

Alerts, closures and key identity — the parts that are easy to get wrong

The rules are in TODO.md §7; these are the traps that have already cost time.

  • The acknowledgement stores the key. alert_acknowledgements.key_id is nullable and holds the key the alert belonged to, or NULL for a software alert raised by the settings list. An alert with a key is acknowledged and hidden by (code, key_id); an alert without one stays on (code, source). This closed a real bug: a rename — or a rotate with keep_name=false — used to reopen a closed alert, because source carries the name the key has now.
  • A key-sourced security alert carries Key N: <name>. build_alerts() reads the key checks into two lookups — key_ids (name → id) and key_sources (name → Key N: <name>, built with _key_source()) — and _security_alerts() takes both. When the provider is the key's own configured name, the key is the source and the alert belongs to it, so it is closed by a rotation; otherwise the source is the plain software name and it is closed by removing that software from the settings. Because the acknowledgement hides a key alert by key_id, not by source, an alert closed before this change stays closed — test_a_key_named_security_alert_is_hidden_by_its_key pins it. rotation_alert_targets(), software_alert_targets() and newest_alert_check_id() all read the same build_alerts(), so they see the same source, which is what keeps an alert closable.
  • The contact alert belongs to the checked key. It gets key_id and source = Key N: <name>, and its message says "this key" and does not repeat the name. The severity stays info and the action stays contact_updated. It blocks its key like every other key alert, because blocking_alert() and the blockingAlerts filter in the form only look at key_id. A record without a key check raises no contact alert at all.
  • software_incompatible has two forms. A software from the settings list keeps source = the software name, key_id = None, actions [remove_software], and carries software. A wallet software that is the name of a configured cloud key can never be removed from the settings, so that form belongs to the checked key instead: key_id = the checked key, source = Key N: <name>, actions [replace_hardware], and no software value, so a settings removal can never close it. Only that form names the software in its message, because its source is the key.
  • alerts.py needs the cloud key names. build_alerts() and collect_alerts() take cloud_names=(), threaded through rotation_alert_targets(), software_alert_targets(), and the four call sites in app.py (_send_alerts, _blocking_alert, _rotate_key, _close_removed_software), plus newest_alert_check_id(). app.cloud_key_names(keys) builds the tuple. If newest_alert_check_id() does not get exactly the same names as collect_alerts(), the alert's source differs, the acknowledgement stores check_id = None, _is_acknowledged() refuses to hide an alert without a check id, and the alert can never be closed. Keep the default () on build_alerts(). _send_health_check_list() passes the same tuple for its needs_follow_up field, for the same reason.
  • The closures that belong to a key are shown. app.closed_alerts() and database._grouped_closures() both filter on key_id IS NOT NULL, so a rotation, a replaced hardware, an updated contact and an ignored key alert are listed, while remove_software and a software-sourced ignore are not. GET /api/health-checks/<id> returns them as closed_alerts, and the CSV has one last column, Follow-up closed, with code: action (YYYY-MM-DD), hanging on the check it closed through check_id. The history table shows Alert, Action and Closed only — the source is not a column.
  • The key card shows the next due date with the alert note. createKeyCard() in static/app.js always renders Next check due and adds the alert note on top. Last checked was dropped in 32.2, but the note still comes in addition to the date, never instead of it — that is what cost the dates once before, for a key whose only alert was the informational contact one.
  • The type is part of a key's identity. The setup locks it, the settings never change it, and only a rotation may pick the other one: POST /api/keys/<id>/rotate takes an optional type, and leaving it out keeps the current type. save_key_settings(..., key_type=None) uses COALESCE(?, type), so the settings and a rotation share one statement.
  • A key that becomes a cloud key must not take a taken name. A cloud key offers its own name as a wallet software choice, and the settings list holds the other choices, so a name the list already holds is refused with 409 through WalletSoftwareNameInUse — a ValidationError subclass, so it has to be caught before the general ValidationError in _rotate_key, or the 409 turns into a 400. validate_rotation() therefore takes the wallet software list as a fourth argument.
  • A rename needs no rotation and no confirmation. In the rotation section the name can be changed on its own through POST /api/settings/keys, for any key, and the address path of a key with no saved check can be changed there the same way. Marking a key with Rotate this key and ticking the confirmation box sends it through the rotate endpoint instead, together with the type and the new path. The single button is Save keys.

Deliberately left out

remove_software is still a dead end in two places: a software-sourced security_vulnerable offers it next to ignore (so the alert stays closable, but one button leads nowhere), and a software-sourced security_compromised offers it as its only action, so an alert whose "software" is a cloud key name can never be closed. Neither is fixed.

Rules that are easy to get wrong — do not re-open

  • One submission records one key. There is no "round" grouping, and each key's next check is its own date plus one calendar year, computed on the server and not editable in the form.
  • A key that could not be checked records nothing else. That covers available = 0 and a recorded address path that does not match. wallet_software and ai_security_checks must be empty; a non-empty value is a 400, not something dropped silently. Nothing is stored for them, and software_compatibility_status becomes NOT_ASSESSED.
  • Availability is required and offers only Yes/No. A cloud key collects only Availability; its compatibility is derived from it, and its own name is the wallet software.
  • A hardware key needs an explicit compatibility status, and Hardware works needs an explicit Yes or No. A missing value, "" and NOT_ASSESSED are all a 400.
  • The contact confirmation is required for every submission, including one for a key that could not be checked, and it has no "not assessed" value.
  • NOT_ASSESSED is not offered or accepted anywhere else. No field but the derived software_compatibility_status accepts it.
  • Address path verified is never a form field again. The server derives it from the comparison.
  • The address path is locked after the first saved check, and no two keys may share one — in the setup, in the settings or in a rotation. The comparison is canonical: m/48h/0h/0h/2h and m/48'/0'/0'/2' are the same path, and the stored spelling is never rewritten.
  • The type is locked by the setup, and only a rotation may change it. The settings never take a type, and a rename alone is not a rotation.
  • An alert is closed by the user, not by a newer check. A newer check that raises nothing does not clear an older alert, and a key with an open alert cannot get a new check at all.
  • An acknowledgement stores the action name, not a free reason, and only the actions the endpoint performs are accepted. rotate has its own endpoint, because it requires a new address path.
  • Every alert message says what is wrong, which key or software, and what closes it, and it does not repeat the name in source — except the cloud-key form of software_incompatible. See TODO.md §7.
  • The export is plain CSV only. XLSX is not built and the app does not promise Excel compatibility. The column names and the column order are an agreement; do not change them. A text cell that a spreadsheet would read as a formula is neutralized with a leading apostrophe, and that is the only change a cell may receive.
  • The PWA cache stores only a valid shell answer. isCacheable() in static/sw.js requires response.ok, response.type === "basic" and !response.redirected, so a login page (or an error page) can never replace the cached shell. The allow-list is the other half: the worker never names /api/*, /health, /login or /robots.txt.
  • No page is meant to be crawled. All six pages carry <meta name="robots" content="noindex, nofollow"> in <head>, _send_security_headers() in app.py adds X-Robots-Tag: noindex, nofollow, and static/robots.txt answers Disallow: /. A new page has to carry the meta, and static/robots.txt must not be added to the service worker's shell list. The header is not sent by send_error(), so a 404 and a 500 answer without it — deliberate, because the round asked for the pages, the JSON, a redirect, the CSV and the static files.
  • The navigation lives in the top bar, not on the page. static/session.js builds the menu, the panel and the .topbar-actions wrapper on the five application pages; /login has none. The dashboard markup therefore carries no href for /health-check, /settings, /history or /api/export, and the export link and its note are on the history page. The page the user is already on is a <span> with aria-current="page", not a link. Do not add a navigation link back to the dashboard markup: tests/test_app.py's test_the_dashboard_carries_no_navigation_link_of_its_own pins it.
  • The Attention card is the only summary card. Its detail line carries the overdue list when something is overdue and the earliest due date otherwise; nextCheckTitle and nextCheckDetail no longer exist, and .overview-grid is one column at every width.
  • An empty alert list renders nothing. The count beside the heading says No alerts; do not put placeholder text back into #alerts-list.
  • The two summary fields are additive and mean what they say. key_names follows key_numbers; needs_follow_up is a property of the saved check, so it does not change when an alert is closed or a key is renamed. Do not "fix" it to follow collect_alerts(), which hides acknowledged alerts and would rewrite history.
  • The prohibition lists in sections 1 and 13 of TODO.md stay unticked. They are standing prohibitions, to be re-confirmed before release — with the one amendment for the installable PWA.
  • Whether a date is overdue is decided in the browser, so /api/key-status stays independent of the current date.
  • /api/previous-values still returns a security map that nothing consumes any more, and its address_path per key is no longer used by the form, which pre-fills the path from keys.address_path. Both are deliberate: removing them would shrink the endpoint, but nothing breaks while they stay.
  • delete_all_data() deletes the checks before the keys. key_checks.key_id is ON DELETE RESTRICT, so the other order fails. The acknowledgements are deleted explicitly, because they have no foreign key at all.

Data model (schema version 12)

  • keys: key_number (1–multisig_key_count), name, type (hardware/cloud), model, address_path, created_at. There is no device column. The name is editable in the settings; the type and the address path are the identity of the key, the path must be unique across the rows, and the type only changes through a rotation. model is optional documentation and is not locked.
  • health_checks: checked_at, next_check_due, wallet_software, software_version, software_compatibility_status, software_comments, contact_info_verified, comments, plus the legacy sparrow_version / nunchuk_version. wallet_software and contact_info_verified are free text.
  • key_checks: one row per submission — available, hardware_works, firmware_version, seed_backup_verified, address_path_verified, address_path, comments. The two cloud columns are gone.
  • ai_security_checks: provider (free text), status, comments, with UNIQUE (health_check_id, provider).
  • wallet_software: name, created_at. Stored whole, seeded with DEFAULT_WALLET_SOFTWARE (Sparrow Wallet) when the list is empty, never emptied through the API. delete_all_data() empties it, and the seed puts the default back.
  • alert_acknowledgements: code, source, key_id, check_id, reason, acknowledged_at. reason holds the action name that closed the alert, and key_id holds the key the alert belonged to, or NULL for a software alert from the settings list.
  • app_settings: name (PRIMARY KEY), value. Holds multisig_threshold, multisig_key_count, admin_username, admin_password_hash and session_secret. delete_all_data() removes the two multisig rows, so the 2-of-3 default applies again, and keeps the three credential rows.
  • tool_checks no longer exists.
  • Startup migration rebuilds keys when it still has device or the old key_number CHECK, key_checks when it uses the old layout or still holds the two cloud columns, and health_checks and key_checks when their CHECK constraints still allow the old values. It then drops tool_checks if it is there, and adds the newer columns through OPTIONAL_COLUMNS.
  • The table definitions are {table} templates, so a rebuild can create the same table under a temporary name. health_checks is a parent table, so the whole migration runs with PRAGMA foreign_keys = OFF, checks PRAGMA foreign_key_check before committing, and rolls back on any failure.
  • tests/test_database.py carries LEGACY_SCHEMA, SCHEMA_VERSION_5, SCHEMA_VERSION_8, SCHEMA_VERSION_9, SCHEMA_VERSION_10 and SCHEMA_VERSION_11 as literal older schemas. Copy that pattern for a new migration test: write the old schema, run initialize_database(), then assert on the migrated rows.
  • There is no data migration for an older test database: the user deletes the data folder and configures the setup again. An acknowledgement written before version 11 has no key, and the older contact alert used the source Contact information, which no longer matches, so the alert it closed is raised again. Section 29 renamed the database file for the same reason, and the old file is discarded with the rest.

API

Pages: /, /setup, /settings, /health-check, /history, /login. Endpoints: GET /health, GET /api/session, POST /api/admin, POST /api/login, POST /api/logout, GET /api/setup, POST /api/setup, GET /api/keys, GET /api/key-status, GET /api/previous-values, GET /api/settings, POST /api/settings/keys, POST /api/settings/wallet-software, POST /api/keys/<id>/rotate, GET /api/health-checks, GET /api/health-checks/<id>, GET /api/alerts, POST /api/alerts/acknowledge, GET /api/export, POST /api/health-checks. Field details are in docs/application.md — which is behind the code, see the gap under Status.

GET /api/health-checks returns each summary with id, checked_at, next_check_due, software_compatibility_status, wallet_software, contact_info_verified, comments, key_numbers, and the two added in 32.2: key_names and needs_follow_up.

Maintenance commands, run inside the container by the StartOS actions and usable by hand: maintenance.py delete-all-data and maintenance.py set-admin-password. Neither is an HTTP endpoint.

The rotate payload is replaced + keep_name + name + type + address_path, and type is optional. GET /api/health-checks/<id> also returns closed_alerts, and each of its key_checks rows carries model as well — the field was added in the follow-up round of 32.1 so the history can show the model and the firmware version on one line, and the fields that were already there keep their names. The settings page has two sections, and POST /api/settings/keys is what a rename alone goes through. The #history-detail anchor and the ?id= query on /history are client-side only: they never reach the server, so no route changed for them.

Five things that are easy to break:

  • New static files must be added to STATIC_FILES in app.py, or they return 404. That includes /settings, /settings.js, /login, /login.js, /session.js, /sw.js, /manifest.webmanifest, /icon.svg, the two raster icons /icon-192.png and /icon-512.png, and /robots.txt, which is text/plain; charset=utf-8 and is deliberately absent from the service worker's shell list.
  • /api/setup, /api/settings, /api/alerts, /api/key-status, /api/previous-values and /api/session are extra endpoints that are not in the minimum list in section 11.
  • STORAGE_ERRORS in app.py includes RuntimeError, because list_keys() raises it for a partial setup. Keep it there, or a broken database answers with a traceback instead of a 500. It also includes ValueError, so validate_admin_credentials() has to be called in its own try and mapped to a 400 before the storage handler — and it is why a refused secret has to be a ValidationError rather than a bare ValueError.
  • The settings, rotation and acknowledgement endpoints keep the same error handling as the existing ones: a bad payload is a 400, an unknown key or alert is a 404, a locked or duplicate address path is a 409, and a broken database is a 500. DuplicateAddressPath and WalletSoftwareNameInUse must be caught before the general ValidationError — in _save_key_settings and _rotate_key respectively — or the 409 turns into a 400. A missing or invalid session is a 401, and a missing CSRF token is a 403.
  • newest_alert_check_id() in app.py derives the check id for the acknowledgement, the rotation and the software removal, so the same comparison rule is used in all three places. blocking_alert() is the module-level helper the 409 is built on, and _blocking_alert() reads the key id straight from the payload, so the rule applies before validation.

The StartOS package — the parts that bite

The package is one service: one daemon, one container, one SQLite database on the persistent main volume, mounted at /data. No Postgres, no Redis, no external backend, no extra container. The decisions are in TODO.md section 30.

  • The application and the package share one repository, at the root. A deliberate deviation from the guide's "a package repo is not a fork of the application": the rule assumes a published upstream image or a git submodule, and VardKey has neither. AGENTS.md states the deviation so nobody adds an upstream-project/ submodule to "fix" it.
  • Anything the Dockerfile does not COPY is not in the image. The modules go in with COPY *.py ./ and the assets with COPY static ./static; .dockerignore keeps tests, data, node_modules, javascript and the build output out of the context. static/ must be copied: app.py answers /health from code, but every page is read from ROOT/static, so an image without it reports a healthy service whose whole UI answers 404. static/robots.txt is served the same way, so it is in the image too.
  • Three things must agree. startos/utils.ts holds uiPort (8080); startos/main.ts passes it as PORT and uses it in the readiness URL; startos/interfaces.ts binds it. Change one alone and the readiness check never goes green. DATABASE_PATH in the same file is what puts the database on the volume. The readiness check is checkWebUrl against http://127.0.0.1:8080/health, and /health must stay open, or StartOS reports the service as unhealthy. A red ECONNREFUSED 127.0.0.1:8080 blip before VardKey listening on port 8080 is just the first poll landing before Python has bound the socket; nothing to fix.
  • Two actions, registered through Actions.of() in startos/actions/index.ts, with their strings in startos/i18n/dictionaries/: deleteAllData.ts (delete-all-data) and setAdminPassword.ts (set-admin-password). Both run maintenance.py in a withTemp subcontainer, behind a confirmation the handler enforces. The generated password never travels into the container: maintenance.py generates it there and prints it, which is the packaging guide's own password-reset pattern.
  • Backups. startos/backups.ts is sdk.Backups.ofVolumes('main'). StartOS stops the service for the duration of a backup, so the database file is quiescent while it is copied — no snapshot hook is needed, and it is not a known limitation.
  • No CI. The guide assumes GitHub Actions; this repository is on Gitea, so there are no .github/workflows/ and there must not be any. The .s9pk is built locally with make.
  • The skeleton was written to match the Start9 template rather than generated by s9pk init-workspace, because that command was not available where it was written. The successful build and install confirm they are equivalent; @start9labs/start-sdk is pinned to 3.0.4.
  • The root icon.svg is the package artwork, read from the repository root by the build. It is the same retro drawing as static/icon.svg, and it must stay under 40 KiB.
  • Documentation layout. README.md is the StartOS package README, with the guide's fixed heading set. The application's own reference is docs/application.md, which instructions.md links to. AGENTS.md is the repo-specific agent context, and CLAUDE.md is the one-line @AGENTS.md import. Both README.md and docs/application.md are behind the code — that is 32.6.

Traps that already cost time — do not repeat

  • with sqlite3.connect(...) does not close the connection. It only commits or rolls back the transaction. On Windows the database file stays locked and TemporaryDirectory.cleanup() fails with WinError 32. Always close explicitly with try/finally; see write_schema() in tests/test_database.py.
  • A module the image is missing is a runtime error, not a build error. auth.py was once left out of the Dockerfile, and both app.py and maintenance.py then died with ModuleNotFoundError inside the container while every test stayed green. The COPY *.py ./ line is what stops that recurring. After any change to the image, check the modules, not just the tests. secret_guard.py is covered by the same line.
  • Every server test module needs a session, and a redirect makes a missing one look like a pass. A page fetched without a session answers 302 → /login, and urllib follows it, so an assertion on page markup reads the login page's HTML instead of failing with 401. Use tests/server_session.py's SessionMixin, and note that the manifest, the icons and /robots.txt are open while the pages are not.
  • urlopen raises HTTPError on a 4xx. A test that expects a 400 has to catch it and read the body from the exception; tests/test_secret_guard.py's post_status() helper is the pattern. A 302 behaves the same way when the opener refuses to follow it, which is how tests/test_app.py reads a redirect's headers.
  • A field has a length limit, and the guard runs before it. A test that pastes an 80-character seed phrase into a 60-character label field gets a secret refusal, not a length refusal. Use a WIF key (52 characters) or a BIP38 key (58) when a test needs a secret that fits a short field, and use the seed phrase where the field has room.
  • A required control inside a display:none container still blocks submission. The browser refuses to submit and logs "An invalid form field is not focusable". Hiding a section is not enough: the required flags must be cleared, or the section must render something other than required fields. That is why renderSecurityChecks() shows an empty note instead of cards when a key could not be checked, why syncUncheckableState() clears the flags on the wallet software and the compatibility select — also for a cloud key, whose grid is hidden — and why syncRequiredFields() clears the flag on hardware_works and seed_backup_verified. The rotation fields follow the same rule: the type is disabled until the key is marked for rotation, the path is disabled when the key has a saved check and is not marked, and the script refuses to send an empty path. The login page sidesteps it with two separate forms, so only the visible one is ever validated.
  • A hidden element has no box, so an anchor cannot jump to it. #history-detail is hidden until a check is opened, so the browser's own :target scroll does nothing. revealDetail() in history.js unhides the section first and only then calls scrollIntoView(). Do not reorder those two lines, and do not drop the anchor from the View link or from the target in saveHealthCheck().
  • A bare substring assertion over page markup also catches comments. test_the_dashboard_has_no_next_check_card_and_no_history_block failed on its first run because it asserted assertNotIn("Next check", html) and the page carried an HTML comment naming the removed card. It now pins the markup that was actually removed — <p class="eyebrow">Next check</p> and the two ids. Assert on the element, not on the phrase; a phrase is also case-sensitive and would trip on any line such as Next check due.
  • A display: grid panel ignores the hidden attribute. .menu-panel is a grid, so the browser's own [hidden] { display: none } loses to it. The sheet carries .menu-panel[hidden] { display: none; } for that reason, the same way .form-stack[hidden], .field-grid[hidden] and .form-section[hidden] already did. Do not drop that rule.
  • The menu's outside-click listener has to allow the button's own click. The button's handler runs first and toggles the panel; the document listener then sees a target inside .menu and does nothing. Reordering them, or replacing menu.contains(event.target) with a check on the panel alone, makes the button close the panel it just opened.
  • The current-page check compares a normalised path, and the current item is a span. currentPath() strips trailing slashes and keeps the root as /, so /health-check/ matches /health-check. The match is rendered as a <span class="menu-item menu-item-current"> with aria-current="page", never an <a> — that is what makes it unclickable. A test asserts the span, the class string and the aria-current attribute, so switching back to a disabled link breaks it.
  • The mismatch confirmation follows its warning. #address-path-confirmed is required only while #address-path-warning is visible, so the browser itself stops the submission and a required control is never hidden.
  • The per-field secret reminder is gone; only the setup keeps one. Since 32.2 it is a single p.secret-warning in setup.html, and setup.js, health-check.js and settings.js no longer build one at all. A test asserts setup.html holds exactly one class="secret-warning" and that the check form and the settings hold none, so re-adding a per-field copy breaks it.
  • static/health-check.js must not use placeholder anywhere. A test asserts the string is absent, because a previous value is a real input value.
  • The key card's line order is pinned by two test modules. tests/test_key_status.py asserts card.append(top, name) → card.append(model) → card.append(path), and tests/test_health_check_form.py asserts that the top line is ${String(entry.key_number).padStart(2, "0")} · ${keyTypeLabel(entry.type)}, that card.append(type) is gone, and that the model line is skipped by sameLabel(entry.model, entry.name). Adding a line, reordering them, or dropping sameLabel() breaks them.
  • The dashboard heading is dynamic and the static description is gone. tests/test_app.py asserts id="setup-shape" and the fallback text on the dashboard and assertNotIn("Bitcoin Multisig Health Monitor") there, while tests/test_pwa.py still asserts that exact description in the manifest. Do not move the one into the other.
  • The stylesheet test asserts on the shape of the theme, not on its wording. test_stylesheet_is_the_retro_theme checks the two bevel colour pairs, the dotted focus outline, the font stack, the absence of box-shadow and gradient, and that every border-radius in the sheet is 0. It reads the values, so a restyled rule that keeps the palette passes, and a rounded corner does not. The only border-radius in the sheet is the explicit reset to 0; do not drop it, and do not add a rounded corner anywhere.
  • The brand mark is an image, and the class name is pinned. IconTests in tests/test_pwa.py asserts that all six pages carry <img class="brand-mark" src="/icon.svg" alt="" aria-hidden="true">, that the old <span class="brand-mark" aria-hidden="true">V</span> is gone, that the sheet holds image-rendering: pixelated, and that place-items: center appears nowhere. It also pins min-height: 100vh, min-height: 100dvh, flex-direction: column and the exact string main { flex: 1 1 auto; }, which is what keeps the footer at the bottom. Do not style the brand mark as a letter again, and do not drop the main rule.
  • The two SVG files must keep the same drawing. The package icon at the repository root is the source of truth, and static/icon.svg is the copy the PWA serves; only the leading comment differs, and test_the_served_icon_carries_the_same_drawing_as_the_package_icon compares them from <svg> onwards. A change to one drawing has to be made in both.
  • The two PNGs are real files, rasterized by the user, because the agent has no rasterizer. IconTests reads each file's IHDR and asserts 192×192 and 512×512, so a PNG made at the wrong size fails the suite instead of silently breaking the install prompt.
  • The manifest lists the SVG first, and the two PNGs after it. test_the_manifest_lists_the_served_icon reads icons[0], so a PNG added in front of the SVG turns the suite red. The PNG entries must carry the real size (192x192 and 512x512) and type: "image/png".
  • The favicon link sits next to the manifest link, and /login has no manifest. IconTests asserts the exact string <link rel="icon" type="image/svg+xml" href="/icon.svg"> on all six pages, so a reworded or reordered link breaks it. /icon.svg, the two PNGs and /robots.txt are open (they are not in PROTECTED_PAGES and do not start with /api/), which is what lets the login page, the browser tab and a crawler read them.
  • make x86 runs prettier --check startos, and the config is the SDK's own. .prettierrc is the single line "@start9labs/start-sdk/prettier.config.json", which is { trailingComma: "all", tabWidth: 2, semi: false, singleQuote: true } — everything else is prettier's default, so printWidth is 80 and quoteProps is "as-needed". That last one silently unquotes a single-word i18n key (Username: 21, not 'Username': 21), and 80 columns decides when an array element or an argument collapses onto one line. Write it the way prettier would, or run npx prettier --config node_modules/@start9labs/start-sdk/prettier.config.json --write startos.
  • The page heading uses class="eyebrow" too. A regex over health-check.html finds Annual security check before the numbered sections. settings.html starts with the h1 Settings, then 01 / Wallet software and 02 / Key rotation. tests/test_health_check_form.py asserts those two lists exactly, so a new eyebrow on either page breaks it, and so does a removed one: update the list in the same change. The 32-B warnings deliberately used class="secret-warning", not an eyebrow.
  • A static help line that the script overwrites is dead text. #software-help in health-check.html was emptied in round 32.3, because lockSoftwareFields() fills it before the user can read it. static/health-check.js must keep setting it — the wording depends on the selected key. A test pins both halves: the empty element in the markup and softwareHelp.textContent in the script.
  • aria-labelledby may point at the eyebrow. login.html's first form has no h2 any more; its aria-labelledby="login-form-title" points at the eyebrow <p> that carries the same id. Do not add a heading back just to have one, and do not drop the id.
  • Do not assert on the quoting style of the JavaScript. static/health-check.js uses single quotes for constant selectors and template literals where a ${...} substitution is needed, and static/settings.js uses double quotes. Assert on the selector text, e.g. [name="address_path"], and on quote-free substrings such as /api/settings and /settings?rotate=.
  • clean_record() in tests/test_alerts.py has a fixed provider list and carries key_id and wallet_software. A test that needs another provider must replace the entry itself, and the recorded software is Sparrow Wallet, which is what a software alert names. A test that exercises the cloud-key form of software_incompatible has to pass cloud_names to build_alerts(). The alert texts are asserted there, and not in tests/test_app.py, which checks the code, the severity, the source, the actions and the key_id only — so a message change touches tests/test_alerts.py alone.
  • sample_payload() / unavailable_payload() are duplicated in tests/test_validation.py, tests/test_database.py, tests/test_app.py, tests/test_maintenance.py and tests/test_secret_guard.py. They build the labels from the key's name and the selected software, they always send contact_info_verified, and for a hardware key hardware_works. They must send the key's own address_path, because the server compares it with the stored one.
  • Every test fixture uses one address path per key (ADDRESS_PATH, SECOND_ADDRESS_PATH, THIRD_ADDRESS_PATH), because the setup refuses duplicates. tests/test_app.py also has ROTATION_PATHS and the rotate() helper, which picks an unused path per key so a test can rotate several keys in one run.
  • validate_health_check() takes a third argument (the wallet software list), and validate_rotation() takes a fourth for the same reason. tests/test_validation.py and tests/test_database.py wrap the first one in a small validate() helper.
  • tests/test_app.py has seven test classes. ServerTestCase starts the server and keeps the session and CSRF cookies a sign-in returns; AppHandlerTests, RenamedSetupTests, SettingsApiTests, RotationApiTests and AcknowledgementApiTests store the default or renamed setup and call authenticate(); AuthApiTests starts from a database with no admin and covers the gating, the first-run admin, the login and logout, the CSRF check and the robots header on a redirect; and KeySetupApiTests creates its admin through POST /api/admin and otherwise starts from an empty database. A new test must go in the class whose setup it needs. Every request helper sends the cookies and the CSRF header, and assert_status() is the one place an error status is expected.
  • The other server test modules share tests/server_session.py. test_export_filename.py, test_key_model.py, test_key_status.py, test_multisig_setup.py, test_pwa.py and test_secret_guard.py mix in SessionMixin, which signs in through the API and carries the cookies; each class calls authenticate() at the end of its own setUp. A test that switches DATABASE_PATH to another file has to call authenticate() again, because the session secret lives in the database, so the old cookie is signed with the wrong secret and every request answers 401. The mixin resolves the path with app.get_database_path(), so the admin lands in the file the server actually reads.
  • The export link and its note live on the history page, and four tests moved with them. tests/test_export_filename.py reads static/history.html and asserts the dashboard has no /api/export link; tests/test_app.py's dashboard test became test_the_dashboard_carries_no_navigation_link_of_its_own; test_the_history_page_offers_the_export_in_its_own_section in tests/test_health_check_form.py pins the Export section, the title bar, the note under the button and the absent .page-heading > .secondary-button rule; and test_the_history_links_to_the_detail_section pins both anchors. A future round that adds a link to the dashboard has to update these, not delete them.
  • #key-count still exists in setup.html, but not on the dashboard. The dashboard's counter span was removed in 32.7; setup.html still has the Key slots input with id="key-count" and name="key_count". The two are on different pages and were never the same element, so assert per file.
  • Section 19 records one key per submission, so a Check id in the export can cover up to three keys only for rows saved before section 19. A legacy record with several key_checks is read through its first one when an alert needs the key it belongs to.
  • The database path default is repeated in sixteen places. database.py carries database_path="data/vardkey.sqlite3" as the default of every storage function (fifteen of them), and app.py carries it in get_database_path(). A missed one makes a single code path read or create the other file, silently. Grep for the old name before and after a rename round.

Product clarification

The key's configured name is its product label, and a cloud key's name is also a wallet-software choice. A hardware key name is never a wallet-software choice, and a cloud key records its own name as its software. A key is identified by its type and its address path, while the name is only a label that the user may change. The address path is unique per key, and a rotation replaces the key with a new one that must carry a new address path and may carry the other type. A rotation creates a new wallet, so the funds have to be moved from the old multisig setup to the new one before the old keys are discarded. An alert is closed by the user with the action that belongs to it, and a key with an open alert cannot be checked until the alert is closed.