40 KiB
AI Agent Note — VardKey
Short working handover for the next model. Keep it short.
TODO.md(Norwegian) is the requirement specification: §1–§18 are binding and describe the app as it is now, §19–§32 are history as one line each, and §32 holds only what is left. The full reasoning is in the git history.- The binding rules live in
TODO.mdandREADME.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.mdandai-thought.mdwere deleted as outdated. Do not recreate either.
Status
- Done and verified: everything in §1–§32. Schema version 13. 534 green tests. The StartOS package is built, sideloaded and running on a StartOS 0.4.0 box.
- The package version is
2026.10.28:0, and its git tag isv2026.10.28_0. - What is left: nothing. The specification is closed, and a new round starts only when the user asks for one.
- 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 atC:\Users\<brukarnamn>\Downloads\helsesjekk, so they must pass there as well as on Linux. - The version scheme is date based,
YYYY.MM.DD:revision, andUPDATING.mdcarries the rule. ExVer is not SemVer: its numeric portion takes any number of dot-separated components, and it normalizes numeric leading zeros, so a single-digit month or day must be written without one —2026.1.5, never2026.01.05— or the version string and the tag stop matching. The bump editsversionandreleaseNotesinstartos/versions/current.tsin place; the file name, thecurrentexport andstartos/versions/index.tsnever change, andstartos/versions/stays otherwise empty because the application migrates its own schema.
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 starting5,9,K,Lorc); 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, andrejection_message(field, label)never repeats it either. - The wordlist is embedded, 2048 words, from
bitcoin/bipsbip-0039/english.txt.tests/test_secret_guard.pychecks 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. Do not edit the list without that test. - Where it is wired in:
validation.pycalls_reject_secret()from the four text helpers_text,_key_name,_modeland_required_path, so every free-text field is covered by construction.auth.pychecks the admin username the same way; the password is deliberately not checked, because a long passphrase is a legitimate password. - The refusal is a
ValidationError(SecretDetected), so the existing handlers answer400.app.pyneeded no change at all — do not add a handler for this. A plainValueErrorwould have been caught bySTORAGE_ERRORSand answered500. - 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". 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-warningabove the whole key list instatic/setup.html, and nowhere else. The page notice is a different thing and stays onhealth-check.html,setup.htmlandsettings.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); 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_idis nullable and holds the key the alert belonged to, orNULLfor 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 arotatewithkeep_name=false— used to reopen a closed alert, becausesourcecarries the name the key has now. - A key-sourced security alert carries
Key N: <name>, and the row decides.build_alerts()reads the key checks into a lookup by key id, and_security_alerts()looks the row's ownkey_idup in it. When the row carries the checked key, 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. The provider name is never compared with the names that are configured now, so a rename or a rotation cannot turn a key alert into a software one.rotation_alert_targets(),software_alert_targets()andnewest_alert_check_id()all read the samebuild_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_idandsource=Key N: <name>, and its message says "this key". The severity staysinfoand the action stayscontact_updated. It blocks its key like every other key alert, becauseblocking_alert()and theblockingAlertsfilter in the form only look atkey_id. software_incompatiblehas two forms. A software from the settings list keepssource= the software name,key_id=None, actions[remove_software], and carriessoftware. 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 nosoftwarevalue, so a settings removal can never close it. Only that form names the software in its message, because its source is the key.alerts.pystill needs the cloud key names, but only forsoftware_incompatible.build_alerts()andcollect_alerts()takecloud_names=(), threaded throughrotation_alert_targets(),software_alert_targets(), and the four call sites inapp.py(_send_alerts,_blocking_alert,_rotate_key,_close_removed_software), plusnewest_alert_check_id().app.cloud_key_names(keys)builds the tuple. Ifnewest_alert_check_id()does not get exactly the same names ascollect_alerts(), the alert'ssourcediffers, the acknowledgement storescheck_id = None,_is_acknowledged()refuses to hide an alert without a check id, and the alert can never be closed. Keep the default()onbuild_alerts()._send_health_check_list()passes the same tuple for itsneeds_follow_upandfollow_up_openfields.- Every closure of a check is shown, key-sourced or not.
app.closed_alerts()anddatabase._grouped_closures()list every acknowledgement that carries acheck_id, so a rotation, a replaced hardware, an updated contact, an ignored key alert, and a software alert closed by removing it are all shown.GET /api/health-checks/<id>returns them asclosed_alerts, and the CSV has one last column,Follow-up closed, hanging on the check it closed throughcheck_id. A closure carries its source, because the two forms of a security code are otherwise indistinguishable: the CSV writes<source> — <code>: <action> (YYYY-MM-DD)into that cell, and the history table showsSource,Alert,ActionandClosed. The CSV column names and the column order are unchanged — only the value grew. - The key card shows the next due date with the alert note.
createKeyCard()instatic/app.jsalways rendersNext check dueand adds the alert note on top. The note comes in addition to the date, never instead of it. - 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>/rotatetakes an optionaltype, and leaving it out keeps the current type. Since schema 13 a rotation does not write the key row: it inserts a new row and retires the old one. - 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, so a name the list already holds is refused with
409throughWalletSoftwareNameInUse— aValidationErrorsubclass, so it has to be caught before the generalValidationErrorin_rotate_key, or the409turns into a400.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. The single button isSave 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=0and a recorded address path that does not match.wallet_softwareandai_security_checksmust be empty; a non-empty value is a400, not something dropped silently. Nothing is stored for them, andsoftware_compatibility_statusbecomesNOT_ASSESSED. Availabilityis required and offers only Yes/No. A cloud key collects onlyAvailability; its compatibility is derived from it, and its own name is the wallet software.- A hardware key needs an explicit compatibility status, and
Hardware worksneeds an explicitYesorNo. A missing value,""andNOT_ASSESSEDare all a400. - 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_ASSESSEDis not offered or accepted anywhere else.Address path verifiedis 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/2handm/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. 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.
rotatehas 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 ofsoftware_incompatible. See §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()instatic/sw.jsrequiresresponse.ok,response.type === "basic"and!response.redirected. The allow-list is the other half: the worker never names/api/*,/health,/loginor/robots.txt. - No page is meant to be crawled. All six pages carry
<meta name="robots" content="noindex, nofollow">in<head>,_send_security_headers()inapp.pyaddsX-Robots-Tag: noindex, nofollow, andstatic/robots.txtanswersDisallow: /.static/robots.txtmust not be added to the service worker's shell list. - The navigation lives in the top bar, not on the page.
static/session.jsbuilds the menu, the panel and the.topbar-actionswrapper on the five application pages;/loginhas none. The dashboard markup carries nohreffor/health-check,/settings,/historyor/api/export, and the export link and its note are on the history page. The page the user is already on is a<span>witharia-current="page", not a link. - 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;
.overview-gridis one column at every width. - An empty alert list renders nothing. The count beside the heading says
No alerts. - The three summary fields are additive and mean what they say.
key_namesfollowskey_numbersand carries the name the check was recorded with, read from the snapshot on the check.needs_follow_upis 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 followcollect_alerts(), which hides acknowledged alerts and would rewrite history.follow_up_openis the current state, computed from the merged, unacknowledged alerts the dashboard shows, so an alert that a newer check re-raises belongs to the newer check and the older check reads as closed. The history card reads its three states (All OK,Needs follow-up,Follow-up closed) from these two fields. - The prohibition lists in sections 1 and 13 of
TODO.mdstay 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-statusstays independent of the current date. /api/previous-valuesstill returns asecuritymap that nothing consumes any more, and itsaddress_pathper key is no longer used by the form, which pre-fills the path fromkeys.address_path. Both are deliberate.delete_all_data()deletes the checks before the keys.key_checks.key_idisON DELETE RESTRICT, so the other order fails. The acknowledgements are deleted explicitly, because they have no foreign key at all. The delete has to clear every row ofkeys, active and retired alike.
Data model (schema version 13)
keys:key_number(1–multisig_key_count),name,type(hardware/cloud),model,address_path,active,rotated_at,created_at. There is nodevicecolumn. 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 active rows, and the type only changes through a rotation.modelis 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 legacysparrow_version/nunchuk_version.key_checks: one row per submission —key_id,key_name,key_type,key_model,available,hardware_works,firmware_version,seed_backup_verified,address_path_verified,address_path,comments. The three snapshot columns are a frozen copy of the key the check was recorded for.ai_security_checks:provider(free text),key_id(nullable),status,comments, withUNIQUE (health_check_id, provider).wallet_software:name,created_at. Seeded withDEFAULT_WALLET_SOFTWARE(Sparrow Wallet) when the list is empty, never emptied through the API.alert_acknowledgements:code,source,key_id,check_id,reason,acknowledged_at.app_settings:name(PRIMARY KEY),value. Holdsmultisig_threshold,multisig_key_count,admin_username,admin_password_hash,session_secret,failed_login_countandfailed_login_until.tool_checksno longer exists.- Startup migration rebuilds
keyswhen it still hasdevice, the oldkey_numberCHECK, or noactiveflag;key_checkswhen it uses the old layout or still holds the two cloud columns; andhealth_checkswhen itsCHECKconstraints still allow the old values. It then dropstool_checksif it is there, adds the newer columns throughOPTIONAL_COLUMNS, backfills the snapshot on every check from the key it belongs to, and creates the partial unique index over the active row. TheUNIQUEonkeys.key_numberis now a partial unique index over the active row (idx_keys_active_key_number … WHERE active = 1). - The table definitions are
{table}templates, so a rebuild can create the same table under a temporary name.health_checksis a parent table, so the whole migration runs withPRAGMA foreign_keys = OFF, checksPRAGMA foreign_key_checkbefore committing, and rolls back on any failure. tests/test_database.pycarriesLEGACY_SCHEMA,SCHEMA_VERSION_5,SCHEMA_VERSION_8,SCHEMA_VERSION_9,SCHEMA_VERSION_10,SCHEMA_VERSION_11andSCHEMA_VERSION_12as literal older schemas. Copy that pattern for a new migration test: write the old schema, runinitialize_database(), then assert on the migrated rows.- There is no data migration for an older test database: the user deletes the
datafolder and configures the setup again. An acknowledgement written before version 11 has no key, and the older contact alert used the sourceContact information, which no longer matches, so the alert it closed is raised again.
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 now in step with the code.
GET /api/health-checks carries key_names, needs_follow_up and follow_up_open.
GET /api/health-checks/<id> carries closed_alerts and model on each key check.
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.
Five things that are easy to break:
- New static files must be added to
STATIC_FILESinapp.py, or they return404. That includes/settings,/settings.js,/login,/login.js,/session.js,/sw.js,/manifest.webmanifest,/icon.svg, the two raster icons/icon-192.pngand/icon-512.png, and/robots.txt, which istext/plain; charset=utf-8and is deliberately absent from the service worker's shell list. /api/setup,/api/settings,/api/alerts,/api/key-status,/api/previous-valuesand/api/sessionare extra endpoints that are not in the minimum list in section 11.STORAGE_ERRORSinapp.pyincludesRuntimeError, becauselist_keys()raises it for a partial setup. Keep it there, or a broken database answers with a traceback instead of a500. It also includesValueError, sovalidate_admin_credentials()has to be called in its owntryand mapped to a400before the storage handler — and it is why a refused secret has to be aValidationErrorrather than a bareValueError.- 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 a404, a locked or duplicate address path is a409, and a broken database is a500.DuplicateAddressPathandWalletSoftwareNameInUsemust be caught before the generalValidationError— in_save_key_settingsand_rotate_keyrespectively — or the409turns into a400. A missing or invalid session is a401, a missing CSRF token is a403, and a locked login is a429. newest_alert_check_id()inapp.pyderives 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 the409is built on, and_blocking_alert()reads the key id straight from the payload, so the rule applies before validation.
The rotate payload is replaced + keep_name + name + type + address_path, and type is
optional. A rotation inserts a new row and retires the old one, and the acknowledgements are written
against the old key id. 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.
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 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.mdstates the deviation so nobody adds anupstream-project/submodule to "fix" it. - Anything the
Dockerfiledoes notCOPYis not in the image. The modules go in withCOPY *.py ./and the assets withCOPY static ./static;.dockerignorekeepstests,data,node_modules,javascriptand the build output out of the context.static/must be copied:app.pyanswers/healthfrom code, but every page is read fromROOT/static, so an image without it reports a healthy service whose whole UI answers404. - Three things must agree.
startos/utils.tsholdsuiPort(8080);startos/main.tspasses it asPORTand uses it in the readiness URL;startos/interfaces.tsbinds it. The readiness check ischeckWebUrlagainsthttp://127.0.0.1:8080/health, and/healthmust stay open. A redECONNREFUSED 127.0.0.1:8080blip beforeVardKey listening on port 8080is just the first poll landing before Python has bound the socket; nothing to fix. - Two actions, registered through
Actions.of()instartos/actions/index.ts, with their strings instartos/i18n/dictionaries/:deleteAllData.ts(delete-all-data) andsetAdminPassword.ts(set-admin-password). Both runmaintenance.pyin awithTempsubcontainer, behind a confirmation the handler enforces. The generated password never travels into the container:maintenance.pygenerates it there and prints it. - The admin task from §32.8 lives in
startos/init/requireAdmin.tsand keeps the same property: no password travels from the host into the container. It raises and clears the task itself, because SDK 3.0.4 has no condition for "the admin password is unset", and the probe fails open. On the box the task is raised and shows on Tasks as recommended, and it does not hold the service back — the user can start the app without an admin.README.mddocuments that behaviour. - Backups.
startos/backups.tsissdk.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. - 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.s9pkis built locally withmake. - 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-sdkis pinned to3.0.4.node_modules/is not in the repository. - The root
icon.svgis the package artwork, read from the repository root by the build. It is the same retro drawing asstatic/icon.svg, and it must stay under 40 KiB. - Documentation layout.
README.mdis the StartOS package README, with the guide's fixed heading set. The application's own reference isdocs/application.md, whichinstructions.mdlinks to.AGENTS.mdis the repo-specific agent context, andCLAUDE.mdis the one-line@AGENTS.mdimport. All of them, plusUPDATING.mdand the package i18n strings, were brought in step with the code in §32.6; keep them there. The repository ishttps://gitea.sondreolav.com/ai-bot/vardkey, and the oldhelsesjekkname must not come back in a URL.
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 andTemporaryDirectory.cleanup()fails withWinError 32. Always close explicitly withtry/finally; seewrite_schema()intests/test_database.py.- A module the image is missing is a runtime error, not a build error.
auth.pywas once left out of theDockerfile, and bothapp.pyandmaintenance.pythen died withModuleNotFoundErrorinside the container while every test stayed green. TheCOPY *.py ./line is what stops that recurring.secret_guard.pyis 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, andurllibfollows it, so an assertion on page markup reads the login page's HTML instead of failing with401. Usetests/server_session.py'sSessionMixin. The manifest, the icons and/robots.txtare open while the pages are not. urlopenraisesHTTPErroron a 4xx. A test that expects a400has to catch it and read the body from the exception;tests/test_secret_guard.py'spost_status()helper is the pattern. A429is read the same way.- A field has a length limit, and the guard runs before it. Use a WIF key (52 characters) or a BIP38 key (58) when a test needs a secret that fits a short field, and the seed phrase where the field has room.
- A
requiredcontrol inside adisplay:nonecontainer still blocks submission. Hiding a section is not enough: the required flags must be cleared. That is whyrenderSecurityChecks()shows an empty note instead of cards when a key could not be checked, whysyncUncheckableState()clears the flags on the wallet software and the compatibility select, and whysyncRequiredFields()clears the flag onhardware_worksandseed_backup_verified. The rotation fields follow the same rule: the type isdisableduntil the key is marked for rotation, the path isdisabledwhen 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. - A hidden element has no box, so an anchor cannot jump to it.
#history-detailis hidden until a check is opened, sorevealDetail()inhistory.jsunhides the section first and only then callsscrollIntoView(). Do not reorder those two lines. - A bare substring assertion over page markup also catches comments. Assert on the element, not on the phrase.
- A
display: gridpanel ignores thehiddenattribute..menu-panel[hidden] { display: none; }is in the sheet for that reason, the same way.form-stack[hidden],.field-grid[hidden]and.form-section[hidden]already were. - 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
.menuand does nothing. - The current-page check compares a normalised path, and the current item is a span.
currentPath()strips trailing slashes and keeps the root as/. The match is rendered as a<span class="menu-item menu-item-current">witharia-current="page", never an<a>. - A sticky top bar needs a scroll container that is the viewport.
.topbaris a flex child ofbody, andbodysets nooverflow, soposition: sticky; top: 0works — but it stops working the moment an ancestor getsoverflow: hiddenorauto. The menu panel isposition: absoluteinside the bar, so it travels with it. - The mismatch confirmation follows its warning.
#address-path-confirmedisrequiredonly while#address-path-warningis visible, so the browser itself stops the submission. - The per-field secret reminder is gone; only the setup keeps one. A test asserts
setup.htmlholds exactly oneclass="secret-warning"and that the check form and the settings hold none. static/health-check.jsmust not useplaceholderanywhere. 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.pyassertscard.append(top, name)→card.append(model)→card.append(path), andtests/test_health_check_form.pyasserts the top line, thatcard.append(type)is gone, and that the model line is skipped bysameLabel(entry.model, entry.name). - The dashboard heading is dynamic and the static description is gone.
tests/test_app.pyassertsid="setup-shape"and the fallback text on the dashboard, whiletests/test_pwa.pystill asserts the manifest description. Do not move the one into the other. - The stylesheet test asserts on the shape of the theme, not on its wording. It checks the two
bevel colour pairs, the dotted focus outline, the font stack, the absence of
box-shadowandgradient, and that everyborder-radiusin the sheet is0. - The brand mark is an image, and the class name is pinned.
IconTestsintests/test_pwa.pyasserts that all six pages carry<img class="brand-mark" src="/icon.svg" alt="" aria-hidden="true">, that the sheet holdsimage-rendering: pixelated, and thatplace-items: centerappears nowhere. It also pinsmin-height: 100vh,min-height: 100dvh,flex-direction: columnand the exact stringmain { flex: 1 1 auto; }. Do not style the brand mark as a letter again. - The two SVG files must keep the same drawing. The package icon at the repository root is the
source of truth, and
test_the_served_icon_carries_the_same_drawing_as_the_package_iconcompares 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.
IconTestsreads each file's IHDR and asserts 192×192 and 512×512. - The manifest lists the SVG first, and the two PNGs after it.
test_the_manifest_lists_the_served_iconreadsicons[0]. The PNG entries must carry the real size (192x192and512x512) andtype: "image/png". - The favicon link sits next to the manifest link, and
/loginhas no manifest.IconTestsasserts the exact string<link rel="icon" type="image/svg+xml" href="/icon.svg">on all six pages. - The prettier config is the SDK's own, and
make x86does not run the check..prettierrcis 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, soprintWidthis 80 andquotePropsis"as-needed". The SDK makefile defines the check asFORMAT_CHECK, butmake x86packs without it, so write the TypeScript the way prettier would and runnpx prettier --config node_modules/@start9labs/start-sdk/prettier.config.json --check startosbefore you hand the round back;--writefixes the files. Instartos/manifest/i18n.tsa value that does not fit the line breaks after the colon, and a string with an apostrophe uses double quotes. A property is measured together with its trailing comma, so the limit isprintWidth − indent— 78 columns for a top-level property, not 80.es_ESat 79 columns must break;en_USat 74 andpl_PLat 76 stay inline. - The page heading uses
class="eyebrow"too.tests/test_health_check_form.pyasserts the eyebrow lists ofhealth-check.htmlandsettings.htmlexactly, so a new eyebrow breaks it, and so does a removed one. The secret warnings deliberately useclass="secret-warning", not an eyebrow. - A static help line that the script overwrites is dead text.
#software-helpinhealth-check.htmlis empty, becauselockSoftwareFields()fills it before the user can read it. A test pins both halves: the empty element in the markup andsoftwareHelp.textContentin the script. aria-labelledbymay point at the eyebrow.login.html's first form has noh2; itsaria-labelledby="login-form-title"points at the eyebrow<p>that carries the sameid.- Do not assert on the quoting style of the JavaScript.
static/health-check.jsuses single quotes for constant selectors and template literals where a${...}substitution is needed, andstatic/settings.jsuses double quotes. Assert on the selector text and on quote-free substrings. - A test string that spans a line break needs the escape, not a literal backslash. Two assertions
in
tests/test_health_check_form.pyonce carried\\nwhere the script has a real newline, so they looked for a backslash and a letter and failed. Prefer an assertion that names the two halves on either side of the break, or normalise with" ".join(script.split()). clean_record()intests/test_alerts.pyhas a fixed provider list and carries the key on the security rows. Eachai_security_checksentry is a dict withprovider,key_idandstatus: the entry whose provider is the key's own name carries the key number, and the others carryNone. The alert texts are asserted there, and not intests/test_app.py, which checks the code, the severity, the source, the actions and thekey_idonly.sample_payload()/unavailable_payload()are duplicated intests/test_validation.py,tests/test_database.py,tests/test_app.py,tests/test_maintenance.pyandtests/test_secret_guard.py. They must send the key's ownaddress_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).tests/test_app.pyalso hasROTATION_PATHSand therotate()helper. With schema 13 a rotation retires the key row, so a test that rotates and then records a check has to use the new key id —rotate()hands it back underkey_id. validate_health_check()takes a third argument (the wallet software list), andvalidate_rotation()takes a fourth for the same reason.tests/test_app.pyhas seven test classes. A new test must go in the class whose setup it needs:ServerTestCase,AppHandlerTests,RenamedSetupTests,SettingsApiTests,RotationApiTests,AcknowledgementApiTests,AuthApiTestsandKeySetupApiTests. Every request helper sends the cookies and the CSRF header, andassert_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.pyandtest_secret_guard.pymix inSessionMixin, which signs in through the API; each class callsauthenticate()at the end of its ownsetUp. A test that switchesDATABASE_PATHto another file has to callauthenticate()again, because the session secret lives in the database. - A login lockout test has to clear the counter.
AuthApiTestsshares one database per test, and the lockout lives inapp_settings, so a test that trips it leaves the account locked for the tests that follow unless it resets the two rows or uses its own database file. - The export link and its note live on the history page, and four tests moved with them.
tests/test_export_filename.pyasserts the dashboard has no/api/exportlink;tests/test_app.py'stest_the_dashboard_carries_no_navigation_link_of_its_own;test_the_history_page_offers_the_export_in_its_own_sectionintests/test_health_check_form.pypins theExportsection, the title bar, the note under the button and the absent.page-heading > .secondary-buttonrule; andtest_the_history_links_to_the_detail_sectionpins both anchors. #key-countstill exists insetup.html, but not on the dashboard. 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 idin the export can cover up to three keys only for rows saved before section 19. - The database path default is repeated in sixteen places.
database.pycarriesdatabase_path="data/vardkey.sqlite3"as the default of every storage function (fifteen of them), andapp.pycarries it inget_database_path(). A missed one makes a single code path read or create the other file, silently.
Tooling — what the agent can and cannot do
- The Gitea tools write a whole file at a time (
gitea_update_file, auto-SHA, one file per call), and there is no preview step and no shell. There is no branch delete either. - The agent therefore cannot run the suite,
make x86,tsc --noEmitorprettier --check. The user runs them, and the user is the one who rasterizes an image or deletes a branch by hand. - Keep the documents short.
TODO.mdand this note are read by every future model, and their size is context the next round cannot spend.
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. Since §32.8 point 5, a rotation also retires the old key row: the multisig slot number stays, the old checks keep the name and type they were recorded with, and the new row starts with an empty history.