Skip to content

Releases and Workflows

Wijanarko Putra Rajeb edited this page Nov 12, 2026 · 9 revisions

Releases and workflows

Agent Operational Workflows

Diagnostic Protocol on Build Failures

  1. Log Scrape: Scrape build output from bun runner (matching exit 1 conditions).
  2. Error Isolation: Target the root failure point (e.g., missing package imports, type mismatch, or invalid asset clipping).
  3. Patch Generation: Formulate a runnable bun terminal command (e.g., bun add @superdesign/svg-geometry@latest && bun run build).
  4. Execution in Kabmo: The user or agent triggers execution directly in the right sidebar panel.

Code Style & Persistence Guidelines

  • Use the CSS variable system defined in src/client/tailwind.css (var(--theme-ink), var(--theme-paper), etc.) and standard Tailwind classes mapped to them (bg-paper, text-ink, border-ink/20).
  • The application supports multiple themes (e.g., E-Ink Paper Monochrome, One Dark Pro Soft). DO NOT hardcode raw hex colors like #141310 or #faf8f3 in component files.
  • Semantic states are expressed purely through these theme variables.
  • Every theme write goes through applyDocumentTheme (src/client/hooks/ui/theme.ts): it sets <html data-theme> and dispatches omp:theme-changed. Writing document.documentElement.dataset.theme directly leaves runtime consumers that cannot see CSS (the mermaid hydrator repaints diagrams per theme) on the previous palette.
  • The only allowable chroma (outside of dark theme) is the signal red variable var(--theme-error) (text-error, bg-error) reserved for failures and error messages. Syntax highlighting is an explicit, user-approved exception: it is provided by Shiki with the dual-theme pair one-light (light themes) + one-dark-pro (dark themes). Token colors arrive as --shiki-light / --shiki-dark CSS variables on .shiki spans — consume them in src/client/tailwind.css under [data-theme], never hardcode token hex, and never reintroduce --syntax-* variables or .token.* classes.

Changelog Policy (Release-Only)

  • NEVER edit CHANGELOG.md during normal work — not for a feature, a fix, a refactor, a typo, or a version-less "unreleased" note. A task ends at code plus the gates in rule 8; the changelog is not part of it.
  • CHANGELOG.md is written only when cutting a release, and releases are cut by .github/workflows/release.yml on every push to main — so since 0.6.0 the file is written by the pipeline, never by hand: release.config.mjs derives each ## [x.y.z] — YYYY-MM-DD section from the Conventional Commits since the last tag, above the previous release (newest first), carrying the [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) categories that apply (### Added, ### Changed, ### Fixed, ### Removed). The section order, the header and the leading ### BREAKING CHANGES group are that config's commitTypes and writerOpts; a new category means editing both.
  • New sections link their compare range inline (## [0.6.0](…/compare/v0.5.0...v0.6.0) — …) and their bullets are commit subjects, not the hand-written prose the sections before 0.6.0 use, so the [x.y.z]: reference block at the file's tail stops at the last hand-written release. Never add to, reword or reformat a section that already shipped — it describes what shipped, not what a later change adjusted.
  • Write entries as released behavior: a bullet is the commit subject, so the subject carries the changelog — name the behavior that changed, never a restatement of the diff. A type marked hidden in release.config.mjs (chore, style, test, build, ci) appears nowhere, and a type carrying release: false in release/release-rules.js cannot cut a version on its own — not even with a ! on it, because the rules there shadow the analyzer's own { breaking: true } fallback for every type this repository uses.
  • A bullet credits its author — … ([c148bc5](…)) (thanks [@octocat](https://github.com/octocat)) — unless that author is the repository owner, whose own commits carry the bulk of every release. release/contributors.js resolves the handle offline from GitHub privacy addresses (NNN+login@users.noreply.github.com) and asks the API about every other author, which is why the release job's GITHUB_TOKEN is what credits a contributor who commits with a real mailbox; bots ([bot] logins, type: 'Bot') and unverified addresses get nothing, and a failed lookup never fails the release.

Conventional Commit Type Selection

Every commit uses Conventional Commits — pick the type from what the diff actually does to observable behavior, not from how big it is:

  • feat — new user-visible behavior: a feature, endpoint, setting option, or capability that did not exist before. A change that only reorganizes internals while the UI/API output stays identical is NOT a feat.
  • fix — corrects existing behavior that was wrong: a bug, regression, wrong result, crash, or broken edge case. There must be a demonstrable "before was wrong" state; a behavior change that is merely a decision is not a fix.
  • refactor — restructures code with zero external behavior change: renames, file moves/extractions, deduplication, type tightening, performance work with no visible effect.
  • perf — the primary intent is a measurable performance improvement, with behavior unchanged.
  • style — formatting/whitespace/import order only; no logic change. (hidden in release.config.mjs.)
  • test — adds or repairs tests only; no production code change. (hidden.)
  • build — toolchain, dependencies, build scripts (package.json, bunfig.toml, scripts/build-client.ts, bun.lock). (hidden.)
  • ci — pipeline config only (.github/workflows/, release.config.mjs). (hidden.)
  • chore — maintenance that fits none of the above (ignore files, secondary scripts). (hidden.)
  • docs — documentation only (README, AGENTS.md, comments).
  • BREAKING CHANGE — append ! and a footer when a change requires callers/users to act: removed/renamed API, route, setting, or a changed contract. The changelog's ### BREAKING CHANGES group comes from this footer. Two limits are enforced by release/release-rules.js, not by convention: ! releases a major version only on feat, feature, fix, perf and refactor — on chore, docs, ci and the rest it releases nothing at all, so a breaking change to the build or the pipeline belongs in the type that carries it — and the footer is read case-sensitively, so it is written BREAKING CHANGE: … (or BREAKING-CHANGE:) at the start of a line. A lowercase breaking-change mention in prose is not a footer; before the pattern was pinned, one such line in a docs body cut a major release by itself. | Mixed change in one commit: split into separate commits when the files are separable; if not, use the dominant type and note the rest in the body. The subject names the behavior that changed (it becomes a changelog bullet verbatim), the body explains the why/how — never restate the diff. release/bump.test.js asserts the whole table, and .github/workflows/ci.yml runs it (with the other three gates) on every pull request — and release.yml runs the same reusable workflow on every push to main.

Package Releases (kabmo-sdk / kabmo-ui)

  • The npm names carry the kabmo- prefix because the org does. The scope is @kabmo-labs and every package in it is a Kabmo package, so @kabmo-labs/kabmo-sdk / @kabmo-labs/kabmo-ui state which product they belong to instead of leaving a bare plugin-sdk/ui to be read as the org's generic library. The directories follow the names (packages/kabmo-sdk, packages/kabmo-ui), and so do the release tag prefixes (kabmo-sdk/v1.2.3) — a tag is the package's identity in the workflow, and a tag that disagrees with the manifest name publishes a version under a name nobody wrote down.

  • Every manifest starts at 0.0.1, and a seed tag is what keeps the line there. The app, both packages and all three bundled plugins declare 0.0.1. semantic-release has no option for a first version: get-next-version.js returns the hardcoded FIRST_RELEASE (1.0.0) whenever the branch has no tag matching tagFormat. Verified against a throwaway repository: no tag → 1.0.0; a v0.0.1 tag present → the next feat cuts 0.1.0 and stays on the 0.x line. So the 0.0.1 lineage begins with a v0.0.1 tag (and kabmo-sdk/v0.0.1, kabmo-ui/v0.0.1 for the packages) on the release commit; without it the first pipeline run publishes 1.0.0 while package.json says 0.0.1, and publish.yml refuses that mismatch. The retired local tags v1.0.0 / plugin-sdk/v1.0.0 / ui/v1.0.0 point at a commit that is not an ancestor of HEAD and were never pushed — they match no tagFormat in use, so they neither seed nor block anything.

  • The pre-rename specifiers still resolve, and they must. @kabmo-labs/plugin-sdk and @kabmo-labs/ui are already baked into every plugin bundle on disk, so RUNTIME_SLOT_BY_SPECIFIER (panels/shim.ts), kabmoPackageDirs (panels/link.server.ts) and runningVersions (panels/compat.server.ts) all name them beside the new ones. Removing them would fail an installed plugin at load with Cannot load … must be loaded by Kabmo, which is a rename breaking the thing the rename was for.

  • The published packages are versioned from commits too — never bump them by hand. They are released by the SAME workflow as the app, .github/workflows/release.yml, whose packages job runs node release/release-packages.mjs. The version rules, the changelog shape and the contributor credit are the app's, reused rather than restated: release/packages.mjs reads commitTypes, parserOpts and releaseRules out of release.config.mjs.

  • Every package that releases in one run shares ONE commit, one atomic push and one tag each. semantic-release still decides — analyzeCommits (path-scoped) and generateNotes, run with dryRun: true, which in semantic-release 25 runs verifyConditions/analyzeCommits/verifyRelease/generateNotes and SKIPS prepare/publish — but its git side effects are gone: @semantic-release/git committed AND pushed each package on its own, core tagged that commit, and @semantic-release/github created a page for it, so one decision to release both packages left two commits and two pushes. release/packages-commit.js now stages both manifests, both changelogs and the shared bun.lock, commits ONCE (chore(release): kabmo-sdk/v0.1.1, kabmo-ui/v0.2.1 [skip ci]), creates both lightweight tags at that commit, and pushes the branch with its tags --atomic; createGithubReleases then makes one release page per tag from the notes semantic-release generated (a 422 already_exists is success, so a re-run can finish the job). Two facts are load-bearing and each was measured: packageReleaseConfig must pass plugins: [] EXPLICITLY — semantic-release merges the repository's release.config.mjs under the options and then falls back to its DEFAULT list (npm + github) for a nil key, so omitting it ran the APP's release plugins for a package and its first dry run refused on @semantic-release/github's verifyConditions; and the writes are explicit (writePackageRelease: the local version plugin, which also refreshes bun.lock and verifies the record, then @semantic-release/changelog's own prepare), because prepare does not run in a dry run and calling the changelog plugin is what keeps the file byte-identical. commitRelease and the release-page call are pinned by release/packages.test.js (one git add, one git commit, both tags at HEAD, one atomic push, 422 tolerated, a real scratch workspace for the write), and the whole path was rehearsed end to end in a clone: both packages moving to 1.1.0 produced exactly one commit carrying both manifests, both changelogs and the lock, with both tags on it and both pushed.

  • The app releases AFTER the packages, in one chained run, and the order is load-bearing. The app does not ship packages/ (see its files list) — at runtime it resolves @kabmo-labs/* from its own node_modules, which is the version bun.lock records for those workspace packages, and a workspace: spec is substituted from the LOCK rather than the manifest. Releasing the app first therefore publishes stale pins: measured, kabmo@4.1.1 on npm declares both packages at 1.0.0 while they are at 2.0.0 (and @kabmo-labs/kabmo-ui@2.0.0 declared the SDK at 1.0.0 while the SDK was 2.0.0). The packages job commits the refreshed bun.lock, and the app job needs: packages and fast-forwards to that commit before it installs and releases. The workflow is four jobs: packages → packages-publish, and packages → app → app-publish; a failed package release stops the app's, because the pin state would be unknown.

  • One workflow means one concurrency group, and that is the point. A concurrency group is not a lock: it is a queue that DROPS pending members as it grows. An earlier revision split the releases across two workflows and shared one group between them so they could not race on their release commits; measured, two pushes in quick succession put four runs in the one group and GitHub cancelled the app's runs to keep the queue bounded, so the app stopped releasing entirely. With both releases in one workflow there is no second group to collide with, and each job's git fetch origin main && git merge --ff-only FETCH_HEAD covers the intra-run ordering.

  • Both release jobs fast-forward their checkout before installing, and that is not optional. semantic-release refuses to release when the local branch is behind the remote — "The local branch main is behind the remote one, therefore a new version won't be published." — and it exits 0, so the run reports success while releasing nothing. Measured on this pipeline's first real run: the app's release had landed first and the packages run silently cut no release.

  • A release cuts the tag and the GitHub Release; the publish is dispatched. The release commits are pushed with GITHUB_TOKEN, which raises no workflow run (only workflow_dispatch/repository_dispatch are exempt), so the packages-publish job calls gh workflow run publish-plugins.yml -f packages=… for exactly the packages that released, and app-publish calls gh workflow run publish.yml -f tag=…. Both publish workflows stay separate and keep the npm environment's approval gate, the gates and the tarball check.

  • The two release jobs repeat their setup steps rather than sharing them through YAML anchors. GitHub does support anchors, but an alias carrying an entire step into a DIFFERENT job is not a shape the documented examples cover, and a parser that rejects it means no release at all, silently, on the push that needed one. Six short steps duplicated is the cheaper failure mode.

  • A rehearsal still writes to PRODUCTION unless it is --dry-run. The runner commits and then pushes to origin — a real branch move and real tags — and creates the GitHub release pages; assertReleaseEnvironment in release/packages.js refuses to run outside CI unless KABMO_RELEASE_ALLOW_NON_CI=1. (The per-package runs this replaced were worse: @semantic-release/git pushed to repositoryUrl, read from package.json's repository field rather than the clone's origin, so a "scratch" run pushed to github.com/kabmo-labs/kabmo and had to be reverted by hand.) Rehearse with --dry-run: it writes nothing at all — no version, no changelog, no lockfile — because writePackageRelease is not called and semantic-release's prepare is skipped in a dry run.

  • @semantic-release/npm cannot write the version here, and that was found by rehearsing. It shells out to npm version, and npm does not support the workspace: protocol this workspace declares its SDK dependency with: the run dies with EUNSUPPORTEDPROTOCOL Unsupported URL Type "workspace:" on a sibling package's manifest, after npm reifies the tree (it removed node_modules outright in the first attempt). release/version-package.mjs is a local plugin that writes the one field instead, with no package manager in the loop — which is safe precisely because this pipeline does not publish. bun publish in publish-plugins.yml is what packs the protocol correctly (verified: the published 1.0.0 tarball carries the exact SDK version).

  • Three mechanisms narrow one repository's history to one package, and all three are needed. (1) A per-package tagFormat (kabmo-sdk/v${version}) makes the range start at that package's own last tag. (2) A path filter in front of the analyzer and the notes generator keeps only commits that touched the package directory — a tag range still contains every app commit made in between, and a feat(panels) there would bump the package's minor version while its own code did not change (measured on this repo: 12 commits in kabmo-sdk/v1.0.0..HEAD, 2 of them touching the SDK). (3) The local version plugin writes the new version into the package's own package.json, and its verifyConditions refuses a private package rather than cutting a release with nothing to publish.

  • The filter is applied by WRAPPING the two plugins, not by a shareable config. context.commits is what both read and semantic-release hands the same context to every plugin in a step, so the only place a subset can be introduced is inside the plugin call. The wrappers are step keys (analyzeCommits/generateNotes), never entries in plugins: validatePlugin requires a plugins array's first element to be a string or plain object, while validateStep accepts a function — a function in plugins fails with EPLUGINSCONF, and the step keys are also the only place a function can carry options.

  • release/commits.js is the path lookup, because nothing upstream has it. semantic-release's own collector (git-log-parser) reads a fixed field set — hash, author, committer, subject, body — and no paths. Two whole-range calls: git log once for messages and identities, and git diff-tree --stdin --name-only -r --root once for every hash (one process, and measured identical paths to git log --name-only). --root is what makes the repository's first commit list its paths at all. The scratch-repo test in release/packages.test.js is what pins it.

  • scopeCommits takes the repository as an argument (context.cwd), not a path derived from the module. They are the same in the pipeline, but a caller whose commits came from elsewhere would otherwise have its hashes looked up in the wrong tree, where every commit reads as path-less — and a path-less commit is deliberately kept (a merge or an empty commit carries no change of its own, and dropping it would drop a revert git recorded that way). That "keep everything" failure is silent; the test caught it.

  • Catalog order is load-bearing and a failure STOPS the run. @kabmo-labs/kabmo-ui declares "@kabmo-labs/kabmo-sdk": "workspace:*", and release/packages.js is the one place a package's directory, tag prefix and manifest name are stated (release/packages.test.js asserts them against the tree). .github/scripts/publish-plugin-packages.sh exits on the first failure rather than publishing a kabmo-ui after a failed SDK release.

  • A workspace: spec is substituted from bun.lock, NOT from the manifest — so bumping a version without refreshing the lock publishes a stale dependency. bun.lock records a version for every workspace package, and bun publish reads that record. Measured in production: the version plugin bumped packages/kabmo-sdk to 2.0.0 and committed it, but the lock still said 1.0.0, so the next release published @kabmo-labs/kabmo-ui@2.0.0 declaring "@kabmo-labs/kabmo-sdk": "1.0.0" while the SDK was 2.0.0 on the registry — an install resolving the old SDK, which is exactly the incompatibility the 2.0.0 release existed to announce. Reproduced in isolation: bump packages/a/package.json without bun install and bun pm pack in a dependent packages/b still writes the old version. release/version-package.mjs therefore runs bun install --lockfile-only after each version write (--lockfile-only because the job has already installed and only the lock's record needs to change), and @semantic-release/git commits bun.lock beside the manifest — without the commit the refresh would be discarded and the next release would re-publish the stale pin. release/packages.test.js builds a two-package fixture and asserts the dependent package packs the NEW version.

  • A manual release still works and is still the escape hatch: bump the version in the package's package.json, push kabmo-sdk/vX.Y.Z (or kabmo-ui/vX.Y.Z), and publish-plugins.yml publishes it. That workflow also takes packages (what the release workflow dispatches), tag (re-run one release whose publish failed, without re-creating it) and package (a hand-run fallback) — resolved in that order, and the tag/version match is checked for the tag input as well as for a tag push.

  • The bundled marketplace plugins are released by a version BUMP, not a publish — and the marketplace job in release.yml does it. The job is named marketplace rather than plugins on purpose: publish-plugins.yml already means the npm packages @kabmo-labs/kabmo-sdk and @kabmo-labs/kabmo-ui, and a job called plugins beside a workflow called "Publish Plugin Packages" reads as the same thing. Nothing here is published. All three (marketplace/plugins/{command-runner,session-info,stats}) are private: true and reach a user inside the app's own tarball (getBundledMarketplaceDir() is <package>/marketplace; bun pm pack carries marketplace/plugins/*). There is no registry for them, so the version their manifest declares is the entire delivery mechanism: syncBundledPlugins compares the installed manifest's version against the store's and applies the new copy only when the store's is strictly NEWER (isNewer). A fix whose version did not move is therefore skipped by every existing install, forever — measured in this repository before the job existed: the stats sticky-header fix (09e097f) and the session-info icon fix (283802b) both shipped with their versions untouched, and git log -L shows their watermarks still at the original 1.0.0.

  • The job sits BETWEEN packages and the shell bumps, and that position is the design. The chain is packages → marketplace → shells → {apk-build, ipa-build, win-build, macos-build, linux-build} → shell-commit → app; the app job fast-forwards to the commits these jobs make (Sync to the current remote) and only then runs bun pm pack, so the bumped manifest is inside the tarball a user installs. A bump landing after the app packed would reach existing installs one release late. tests/ci-gates.test.ts pins every hop, because the transitive gate check cannot see ordering.

  • The Android shell is released the same way, and for the same reason — release/android.js + the shared release/release-shells.mjs, run by the shells job (ONE commit for all five shells). packages/android/version.properties is the ONE place the shell's versionName is declared: the build reads it at configuration time, the shell appends it to its WebView User-Agent as KabmoAndroid/<versionName>, and publish-android.yml names the asset Kabmo-<versionName>-android.apk from it — so the version the console compares (versionFromAssetName against shellVersion) is the same number by construction. It used to be the app's release TAG, which tied two independent cadences together: a shell-only fix could not reach an installed app unless the server also cut a version, and a server release shipped an APK whose version said nothing about whether the shell had changed. The bump level comes from the same analyzer, the write is surgical on the one versionName= line, and a chore/docs/test-only change asks for none. version.properties rather than build.gradle.kts is deliberate: the watermark is git log -L on the version LINE, and the Gradle file is rewritten for reasons that release nothing, so the range would start at the wrong commit. 0.3.0 is not arbitrary — the last shipped APK (kabmo-android-v0.2.0.apk, whose versionName was the app tag) makes every installed shell report KabmoAndroid/0.2.0, so starting below it would make isNewer answer false for the first independent release and no installed app would ever be offered it. versionCode is still the workflow run number (-PkabmoVersionCode), because it is a monotonic counter rather than a version. release/android.test.js asserts the file, the build's use of it, the asset naming, the read/rewrite, and the watermark and range against a throwaway repository.

  • The bump must be COMMITTED by this job, not left for the app's release commit. semantic-release's @semantic-release/git carries only its own assets (CHANGELOG.md, package.json, bun.lock), so a plugin bump left uncommitted is discarded when that job resets to its checkout — and the tarball would pack the OLD version. The commit is a chore (which release/release-rules.js gives release: false, so it cannot cut a version by itself) and carries [skip ci].

  • release/marketplace.js holds the catalog; release/watermark.js holds the watermark itself (shared with the Android shell); release/release-marketplace.mjs is the runner. The watermark is git log -L on the version LINE, and a tag cannot serve. These plugins are released by the APP's release, so a bump rides inside a chore(release): vX.Y.Z commit and there is no per-plugin tag to range from. versionWatermark(dir, cwd) asks git which commit last changed "version" in the manifest, and commitsSinceWatermark ranges from it — everything a plugin's history has to offer is either before the version it currently declares (already out) or after it (not yet). -L is what makes it correct: a git log -p | grep would report every commit that rewrote the file. An unresolvable watermark (shallow clone, no version line) reports every commit the caller collected rather than none, because "cannot tell" must never read as "nothing to do".

  • The bump LEVEL comes from the same rules as everything else. release/release-marketplace.mjs runs the real @semantic-release/commit-analyzer with the config looked up by name from release.config.mjs, so a fix is a patch, a feat a minor and a BREAKING CHANGE: footer a major — verified on this tree: session-info computed 2.0.0 (its range contains 5018640, whose body carries a real breaking footer) and stats 1.1.0. A range of chore/docs/test commits asks for nothing and the version is left alone, so a plugin whose only change was a test file does not ship a no-op update to every user.

  • Only the bump is derived — no changelog, no tag, no GitHub release. None of those reach an installed plugin, and @semantic-release/changelog would commit a file per plugin that nothing reads.

  • The write is surgical: two version LINES, never a JSON.stringify round-trip. replaceVersionLines rewrites "version" (2-space indent) and kabmo.version (4-space) by anchoring on their indentation and the previous value, and throws unless it rewrote exactly two. A JSON.stringify(manifest, null, 2) round-trip is what release/version-package.mjs does for the packages and is wrong here: these manifests are hand-formatted, and re-serializing expanded every inline object — measured, a two-line bump came out as a 16-line diff rewriting peerDependenciesMeta.

  • Both version spellings must agree, and the gate says so. package.json carries version and kabmo.version; the registry reads the SECOND (toManifest reads pkg.kabmo) and the sync compares it, so bumping only the first is a no-op that looks like a release. release/marketplace.test.js asserts they match in every manifest, that every directory under marketplace/plugins/ has a BUNDLED_PLUGINS row (a plugin no row names is never bumped), that each row's id is the manifest's own id, and that every plugin stays private — plus the watermark and range against a throwaway repository, since a watermark is a fact about history and a test reading this repo's would break the moment a commit landed.

  • The gates and the browser specs are a REQUIREMENT of every release, and that is why they live in reusable workflows. .github/workflows/gates.yml (the four gates, bun test, the generated settings schema) and .github/workflows/e2e-specs.yml (the Playwright suite) are workflow_call files; ci.yml and e2e.yml are PULL REQUEST triggers that call them, and release.yml, publish.yml and publish-plugins.yml each have two jobs that call them and needs: them. A release job is therefore unreachable until both have passed. Re-running the commands inside release.yml would be a second copy that drifts from what a pull request runs, and reading another run's conclusion over the API races the run it is waiting for — a release run would have to tell "no run found yet" apart from "no run exists", and a red main read as a missing run is precisely the failure this shape prevents. ./.github/workflows/<file>.yml is the reference form (same commit as the caller); $/… says the same thing but is newer, and actionlint rejects it — a parser that refuses the spelling fails the whole workflow, which on a release pipeline means no release at all, silently.

  • Each releasing workflow gates the commit it actually acts on, and the three are not the same commit. release.yml gates the pushed commit (empty ref: input = the caller's github.sha); publish-plugins.yml gates github.sha too, but for a different reason — a tag push is a bare git push of a ref nobody gated, and these tags are pushed by release.yml onto the release commit, which is a LATER commit than the one release.yml itself gated; publish.yml passes ref: = the tag, because a release: published run is not a push to main (no e2e.yml run exists for that event to wait on at all) and a dispatch re-run must verify the published bytes rather than main's tip. release.yml deliberately runs its gate jobs BEFORE each release job's Sync to the current remote: the sync can only fast-forward onto a release commit this same workflow produced, and that commit's own run gated its own starting point, so nothing ungated reaches a tag through it.

  • A reusable workflow RENAMES the checks a commit receives, and nothing can prevent it. A called workflow's checks are namespaced by the CALLER's job name, so <caller job> / <callee job> is what reports: measured on this repository, the single job Gates in ci.yml now reports Gates / Checks and Gates / Settings schema, where it used to report Gates and Settings schema. That is inert HERE only because main's ruleset requires no status checks (verified: its rules are deletion and non_fast_forward). A repository whose branch protection DID require those names would need the ruleset updated in the same change, or every pull request would wait forever on a check that no longer reports — and the callee's job name is not configurable from the caller, so there is no spelling that avoids it.

  • A rejected push of the release's NOTES ref strands the release AFTER the tag is pushed, and re-running the job repairs nothing. Release the app runs semantic-release, whose order is commit → tag → git push --tags → git push refs/notes/semantic-release-<tag> → publish. On the release run of 2026-11-11 (43120058573) the fourth step was rejected — ! [remote rejected] refs/notes/semantic-release-v0.28.0 … (failed) — with no rule behind it (the repository's only ruleset targets branches with deletion/non_fast_forward, and the identical push from a developer machine succeeded minutes later), so it was a server-side rejection that has not recurred in 37 earlier releases. The first three steps had landed: main carried chore(release): v0.28.0 and the tag existed, while npm still served 0.27.0 and NO GitHub release existed. A re-run of that job is not the repair, and it is not harmless either. The job re-executes on the run's original sha, but its own Sync to the current remote step fast-forwards to main's tip first, so what semantic-release analyzes is whatever main is NOW: with no commits after the tag it logs "There are no relevant changes" and exits 0 without publishing, and with commits after it, it cuts a NEW release from a commit this run never gated. Measured on 2026-11-12: re-running 43120058573 to clear its red status cut v0.29.0 from 62e7ca21 — 22 commits later, whose own gates were red — and published a GitHub release for it. publish.yml cannot fire for the stranded tag either, because its trigger is release: published and there is no release to publish. Re-run that job only when git log <tag>..origin/main is empty. The repair is three moves: (1) push the notes ref by hand (git notes --ref semantic-release-<tag> add -f -m '{"channels":[null]}' <tag>, the exact content addNote writes, then push that ref); (2) create the release on the tag with the CHANGELOG section as its body, which is what fires publish.yml — gates and browser specs against the tag, then bun publish; (3) dispatch each shell body (publish-android/-ios/-macos/-windows/-linux.yml) with tag:, because their attach phase downloads an artifact uploaded by an earlier call in the SAME run and an attach-only dispatch has nothing to download — so every dispatch BUILDS from the tag. Release the app's released=false keeps its own attach jobs skipped on any re-run, which is why (3) is the owning path. Android's dispatch also requires version-code: pass the run number of the stranded release, the value its skipped apk-build would have used.

  • A push to main raises exactly ONE workflow, and tests/ci-gates.test.ts asserts it. GitHub starts one run per workflow FILE whose on.push matches, and the files do not know about each other: ci.yml and e2e.yml used to carry push: branches: [main] beside release.yml, so every merge ran the gates and the browser matrix twice on the same commit. Measured on 26333b1: CI 6m33s and E2E 25m17s beside the identical Gates / … and E2E specs / … jobs inside the Release run, and the duplicate pair had already DISAGREED — that CI run's Gates / Checks (Windows) went red on an EBUSY temp-directory rmdir in applyStash while the Release leg of the same job passed, which is a red main with no code change behind it. Those triggers are gone: the gates are a job of release.yml (which is what needs: makes binding anyway), ci.yml/e2e.yml keep only their pull-request triggers, and label-merge-conflict.yml sweeps every four hours instead of on the push that caused the conflict — a 26s label mirror is not worth a second run per merge. The test walks every workflow file and fails if any other file's on.push covers every push to main (a paths:-filtered push, like pr-intake.yml re-validating its own scripts, is not every push).

  • A gate job never carries an if:. A gate with a condition is one that can be skipped, which is not a gate — the e2e label condition therefore stays on e2e.yml's own caller job (the one context where a label exists) and a release always runs the browser layer. That matters because e2e.yml skips the browser suite on a pull request without the label, so the merge that produced a release commit may never have run one.

  • The iOS shell is the same product on the other mobile platform, and it shares the console's contract rather than restating it. packages/ios is a SwiftPM package (Swift 6 + UIKit + WebKit, no SwiftUI, no third-party deps, no .xcodeproj) with the same two-target split packages/macos uses: KabmoShell holds every rule that can be tested without a screen (URLNormalizer, ShellSettings incl. the zoom mapping, LoadingState, HealthProbe, ShellUpdate, ShellUserAgent, SVGPath/Wordmark/WordmarkRenderer) and kabmo-shell is the UIKit app. The app target is guarded by #if canImport(UIKit) so swift build stays meaningful on a Mac with only the Command Line Tools — the logic suite (swift run kabmo-shell-tests, a plain executable because XCTest ships with Xcode) runs there and in CI, and the application only compiles against the iOS SDK. Where the platform genuinely differs, the shell says so instead of imitating Android: an IPA cannot be installed by an app (no PackageInstaller equivalent, no sideload-by-URL), so ShellUpdate.action recognises an IPA download and opens the release page with a reason instead of writing a file nothing can use; and WKWebView.pageZoom is already page-relative, so ShellSettings.pageZoom is a plain ratio — the Android twin's density multiply would render a 100% setting at 2.6× on a 3× phone, which ShellSettingsTests pins. The launch overlay's rules are the Android ones, including the two that fail silently: a progress frame after done/failed is ignored, and didFinish never clears a failure (a failed load still finishes on WebKit's error page). Progress arrives by KVO on estimatedProgress — WKNavigationDelegate reports started/finished/failed and nothing in between, so a delegate-only shell draws a bar that jumps from indeterminate to gone. The app is named Kabmo, and the name is ENFORCED because nothing fails when it drifts. CFBundleDisplayName and CFBundleName are both Kabmo (the Home Screen, the app switcher and Settings read the first), the bundle is Kabmo.app, and CFBundleExecutable is Kabmo — the FILE inside the bundle, which scripts/build-ipa.sh copies the SwiftPM product to, because the product stays kabmo-shell (SwiftPM derives it from the target, and a lower-case binary name is the platform's convention). Three files state it and each can be changed alone, so all three are checked: the build script refuses a bundle whose display name is not Kabmo and refuses an executable the bundle does not carry, publish-ios.yml re-checks both on the ARTIFACT (a stale checkout, or a later step rewriting the plist, passes the script's check and fails here), and release/ios-name.test.js pins the plist, the script, the workflow and the console's own … for iOS label. The quick action's title is deliberately NOT the app name: it reads Server settings, because a shortcut titled Kabmo would be the icon's label twice. The Android shell's app_name, the macOS/Linux/Windows shells' Kabmo window and executable names, and the PWA manifest's name/short_name are the same word — one product, one name. A download keeps the session cookie, which is why it is a WKDownload and not a URL handed to Safari (ShellDownloads.swift): the editor's file lives on the console's own origin and is authenticated by an HttpOnly cookie, so handing the URL to the system browser fetches the LOGIN PAGE — a corrupt-looking file rather than an authorization failure, the exact bug KabmoDownloads prevents on Android. WKDownload transfers with the web view's own cookie store and the finished file goes to the system share sheet; ShellUpdate.safeFileName makes a server-supplied name one path segment (a Content-Disposition with ../../etc/passwd would otherwise resolve outside the download directory). An IPA is refused here too, by the same ShellUpdate decision. The wordmark is public/kabmo-wordmark.svg as path data (Wordmark.swift, generated, never hand-edited) and WordmarkTests re-derives every number from the SVG plus rasterizes it to assert ink where the artwork has ink — the same guard packages/android's WordmarkDrawableTest applies to its VectorDrawable. The server chip is the same control the Android shell draws, one row down from the drawer's title bar: ShellServerHost answers servers_state/servers_add/servers_remove/servers_activate over window.webkit.messageHandlers.kabmo, and the page adapts it into __kabmoCall — the same four commands, the same startable: false (no child process on a phone), and the same drawer placement, because the chat header has no room at 390px. ServerList lives in the LOGIC target with the wire and the migration from the old single server_url, so swift run kabmo-shell-tests pins the rules without a simulator. The switch itself never touches WKWebsiteDataStore: ShellServerHost hops to the main actor before onActivate, so switchServer needs no second dispatch, and the cookie delete the first version performed is gone for the same reason as Android's — it signed the user out of BOTH servers. onSaved no longer clears loadedURL either, so reopening Settings on an unchanged address (the zoom slider lives there) stops throwing away the live document, tab state and composer draft; a real address change is still caught by viewDidAppear.

  • One console contract for both shells, and the prefix is the only per-shell fact. src/shared/lib/updates/shell-ua.ts parses KabmoAndroid/ and KabmoIOS/ through ONE grammar (shellVersion(ua, kind), SHELL_UA_PREFIXES), src/server/lib/updates/shell-release.ts resolves either artifact from the same release LIST (fetchShellRelease(kind), per-shell cache on globalThis, resetShellReleaseCache), and src/client/hooks/ui/updates/shell-download.ts holds the one offer table both sidebars call (useShellOffer). The routes stay separate (/api/updates/android, /api/updates/ios) because one endpoint answering "the newest shell" would need a query parameter whose absence silently means Android. There is no iOS INSTALL offer: iOS has no sideload-by-URL path, so shouldOfferShellDownload('ios', null, …) returns null even on an iPhone — only an installed iOS shell is ever offered an update, and the Android browser offer is unchanged. The bootstrap carries two fields (shellVersion, iosShellVersion) rather than one "shell version", because the two artifacts are on separate release tracks and folding them would compare one shell's version against the other's published asset.

  • The Windows shell is released the same way, and for the same reason — release/windows.js + the shared release/release-shells.mjs, run by the shells job. packages/windows/version.properties is the ONE place its versionName is declared: KabmoDesktop.App.csproj reads it at build time through the ReadShellVersion target (into the assembly's Version, which is what the shell reports to the page as shellVersion), and publish-windows.yml names the asset from it. The version is never written in the .csproj — a literal there is a second source that drifts the first time either is bumped, and the failure is silent (the app reports a version the pipeline never published); release/windows.test.js fails on it. The target reads the file through Regex rather than ReadLinesFromFile + a StartsWith filter, because the item-metadata form evaluates to the LITERAL text @(_VersionLine) when the item is empty and the SDK rejects that with NETSDK1018 (measured). The artifact is an INSTALLER — Kabmo-<v>-win-<arch>-setup.exe, compiled from packages/windows/installer/kabmo.iss by Inno Setup 6, which is preinstalled on windows-latest AND on windows-11-arm (verified against actions/runner-images: 6.7.1 on Windows 2022, 2025 and Windows 11 Arm64), so the build needs no third-party action and no download at run time. A ZIP would leave no Add/remove-programs entry, no Start-menu entry and no uninstaller, so "which version is this" and "how do I remove it" would both have no answer — the same reason packages/macos ships a .app and packages/linux a .tar.gz (each platform's own convention). Four properties are load-bearing and release/windows.test.js asserts each: a STABLE AppId (a generated one installs a second copy beside the first, with two Start-menu entries and two uninstallers), PrivilegesRequired=lowest (the app writes only to %APPDATA%\Kabmo and %LOCALAPPDATA%\Kabmo\webview, so the ordinary install shows no UAC prompt; /ALLUSERS overrides), a WebView2 check in [Code] before anything is copied (a missing runtime is why the window paints nothing, and saying so up front beats a blank window), and MinVersion=10.0.17763 (the Evergreen Runtime's floor). The version arrives as /DAppVersion=<v> and the workflow re-reads it off the built file's own ProductVersion before uploading. It is NOT an MSIX: MSIX requires a certificate bound to a publisher identity and refuses to install without one, so the installer is unsigned and SmartScreen warns until it has reputation. There is no User-Agent token, but the console DOES offer this app an update — over the bridge, the same contract macOS uses (__kabmoDesktop.shellVersion, read from the assembly's own Version). Unlike the two mobile shells, nothing is downloaded FROM the console: those two are, so the server parses their published version on every request, while a desktop app is installed by hand and only needs to be TOLD it is behind.

  • The Linux shell is the fourth port of the same shell, and its two real differences from macOS are forced by the platform, not chosen. packages/linux is a Rust crate (gtk 0.18 + webkit2gtk 2.0 with the v2_22 feature floor, so Ubuntu 22.04 and Debian 12 are supported) split the way the Swift package is: src/store.rs holds the rules (server list, ownership by recorded pid, normalise_url refusing a base path), src/system.rs the side effects (probe, per-port record discovery, a process_group(0) spawn killed with kill(-pgid)), src/main.rs the window's app and wiring, with src/chrome.rs holding the window's own behaviour (shortcut table, window.txt, the webview's data directories, the page's drag/double-click/contextmenu intents) and src/commands.rs the commands the page may issue. The rules suite is a plain executable split by domain under rules/ (cargo run --bin kabmo-desktop-tests, 78 checks, no display), because a rule that can only be checked by opening a window is a rule that is not checked. The binary is named Kabmo, not the crate's name — GTK derives the process name, WM_CLASS and the taskbar label from the executable's file name, so kabmo-desktop put that string in the window list while the window's own title said Kabmo (the same drift packages/macos fixed by naming its SwiftPM product Kabmo); main sets prgname/application_name from one APP_NAME constant before GTK starts, and release/linux.test.js asserts the title, the About panel, the launcher template's Name=/StartupWMClass and the binary's own file name together. The installer is a real script, not a heredoc inside build-app.sh, and the .desktop is a TEMPLATE it fills in (scripts/install.sh + scripts/kabmo.desktop.in): Exec takes an absolute path while a tarball unpacks anywhere, and the shipped-ready entry this replaced used Exec=sh -c '…' sh %k, which desktop-file-validate rejects outright (the spec has no single quotes, and $ must be escaped inside a quoted argument) — an invalid entry fails SILENTLY, with the menu listing an app that does nothing when clicked. The Exec value is always QUOTED because a space is a reserved character there and the validator does NOT catch an unquoted one (measured: Exec=/tmp/my prefix/bin/Kabmo validates, and a launcher then splits it into two arguments), while TryExec stays a bare path for the inverse reason. The installer refuses to write an entry with an unresolved @TOKEN@, validates what it wrote, and has --uninstall; publish-linux.yml RUNS it into a throwaway prefix on every release and checks what it placed, so a token the script stopped filling in fails the build rather than the user's menu. Verified end to end: the workflow's own verify step run verbatim, a tarball unpacked into a random directory and installed from there, and gtk-launch kabmo starting the app from the generated entry. The release wiring is the other three shells' — release/linux.js + the shared release/release-shells.mjs, run by the shells job of release.yml, publish-linux.yml builds before the tag (app needs: linux-build) and only attaches after it (linux-app), and packages/linux/version.properties is the ONE place versionName is declared (build.rs bakes it in as KABMO_SHELL_VERSION; never CARGO_PKG_VERSION, because the crate is never published).

  • The three DESKTOP shells ship two architectures each, built NATIVELY, and every artifact is checked against its own header. macos → arm64 (macos-15) + x64 (macos-15-intel); windows → x64 (windows-latest) + arm64 (windows-11-arm); linux → x86_64 (ubuntu-latest) + arm64 (ubuntu-24.04-arm) — every label verified in the GitHub-hosted runner reference, and each row compiles, runs its rules suite and verifies on the machine it targets. A cross-build is not an option: all three link native libraries (AppKit/WebKit, WPF/WebView2, GTK/WebKitGTK), so it would need a sysroot and would ship a binary nothing in the job ever executed. The asset name carries the architecture, in one scheme for all three — <App>-<version>-<platform>-<arch>: Kabmo-<v>-mac-<arch>.zip + .dmg, Kabmo-<v>-win-<arch>-setup.exe, and on Linux Kabmo-<v>-linux-<arch>.tar.gz / .deb / .rpm / .AppImage (+ .zsync). Kabmo is capitalised because it is the product's NAME (the word the window title, the installer and the .desktop entry carry), not a package slug; the two MOBILE shells keep kabmo-android-v<v>.apk / kabmo-ios-v<v>.ipa because versionFromAssetName PARSES those to answer "is a newer shell published", and renaming one would silently stop offering updates. Nothing parses a desktop name, which is why those three were free to change. Each build asserts the architecture of the file it produced, from the file's own header — lipo -archs (Mach-O), the PE machine field (0x8664 x64 / 0xAA64 Arm64), the ELF e_machine field (62 x86-64 / 183 AArch64) — because a runtime pack or SDK that silently resolved to the host architecture would publish an arm64-named file carrying an x64 binary, which fails on the user's machine and nowhere in the pipeline. The macOS matrix carries a separate macho field (x86_64) because lipo prints a different spelling from the asset label (x64). The Windows installer's ArchitecturesAllowed comes from the same /DAppArch value that names the file — x64os for x64, arm64 for Arm64 — so the Arm64 installer refuses an x64 machine and the x64 one refuses Arm64; x64compatible would have matched both via emulation, which is now the wrong file for an Arm machine to pick. Each build phase uploads one artifact PER architecture and the attach phase downloads them with pattern: + merge-multiple: true, then refuses to upload unless exactly two files arrived — a shared artifact name would let the second row overwrite the first, and a one-architecture release installs on one machine family and not the other. Each desktop shell ships every package format its platform actually uses, and the Linux three are built by scripts beside build-app.sh. macOS ships a .zip (what a script or updater consumes — ditto, so the signature and extended attributes survive) AND a .dmg (hdiutil create with the bundle beside an Applications alias, which is what a person expects to drag); hdiutil warns that it is deprecated in favour of diskutil image create from, and that alternative is unusable here because it takes no -fs — a folder source becomes an APFS volume, while HFS+ is what every macOS from 10.x up mounts. Linux ships .tar.gz (no root, install.sh → ~/.local), .deb (dpkg-deb), .rpm (rpmbuild) and .AppImage (appimagetool, pinned, run with APPIMAGE_EXTRACT_AND_RUN=1 because a container has no /dev/fuse) — four answers to "how do I install this", none of which replaces another. Two rules fail only on the user's machine and are therefore stated in the scripts: the .deb depends on libgtk-3-0t64, not libgtk-3-0 (Ubuntu 24.04 renamed GTK 3's runtime package in the 64-bit time_t transition, and the old name makes the package UNINSTALLABLE — apt answers "no installation candidate"), and the .rpm requires gtk3 / webkit2gtk4.1, the Fedora-family names, because the build host is Ubuntu and its own names resolve nowhere. appimagetool writes its .zsync into the CURRENT DIRECTORY, so the script runs it from inside the output directory — an absolute destination put the AppImage in the output dir and the delta metadata in the caller's cwd (measured). The .deb names its architecture amd64/arm64 while RPM and AppImage say x86_64/aarch64, which is why the Linux matrix carries deb and host beside the asset label arch; the attach phase then requires TWO of EVERY format (shopt -s nullglob, because an unmatched pattern stays literal and would count 1) and treats the .zsync as optional. Release artifacts go to artifacts/ — never dist/ (the client bundle's own output, which a later build can delete) and never release/ (tracked source: the bump scripts and their tests). ALL FIVE shells now share one naming scheme — <App>-<version>-<platform>[-<arch>].<ext>: Kabmo-<v>-android.apk, Kabmo-<v>-ios.ipa, Kabmo-<v>-mac-<arch>.zip/.dmg, Kabmo-<v>-win-<arch>-setup.exe, Kabmo-<v>-linux-<arch>.tar.gz/.deb/.rpm/.AppImage. The mobile pair has NO architecture segment because neither artifact is per-arch: the APK is one universal build (the shell is pure Kotlin, no native libraries — verified: no .so, no jniLibs, no abiFilters) and the IPA contains only the device slice (arm64-apple-ios). The mobile rename needs a compatibility path and the desktop one does not, because the console PARSES those two names to answer "is a newer shell published": SHELL_ASSETS carries legacyPrefix/legacyExtension (kabmo-android-v, kabmo-ios-v) and versionFromAssetName tries the current scheme first, then the legacy one. Without it an installed shell would read as "no update" from the moment this shipped — silently, since a name that does not match is indistinguishable from a release carrying no artifact. The two mobile prefixes are now both Kabmo-, so the EXTENSION is what keeps a desktop asset from being read as a mobile one; shell-release.test.ts pins every desktop filename as null for both kinds.

  • The IPA is released the same way the APK is — release/ios.js + the shared release/release-shells.mjs, run by the shells job — and publish-ios.yml builds it on macOS. packages/ios/version.properties is the ONE place the shell's versionName is declared: scripts/build-ipa.sh fills CFBundleShortVersionString from it through release/ios-version.mjs, the shell appends KabmoIOS/<versionName> to its WebView User-Agent through applicationNameForUserAgent (set on the CONFIGURATION — a value assigned to a live web view is ignored with no error, so the token would be missing from the very request that renders the shell), and the asset is named Kabmo-<versionName>-ios.ipa from the same file. The two-phase shape is the APK's: ipa-build runs BEFORE the tag and app needs: ipa-build, so a Swift error or an unavailable macOS runner stops the release before anything is tagged; ipa only attaches the run artifact. The bundle is assembled by hand (scripts/build-ipa.sh: no xcodebuild, icon rendered from geometry by scripts/make-icon.swift, icons verified against the plist's own list) and is unsigned — signing needs an Apple-issued certificate bound to a team and a device set, so the artifact is for a developer who re-signs it, for Xcode/TestFlight, and for CI verification. release/ios.test.js asserts the file, the build's use of it, the asset naming, the read/rewrite, the watermark and range against a throwaway repository, AND that the Swift prefix, the TypeScript prefix and the asset naming agree — three files stating two strings, where a change to one alone makes the console read the shell as a browser.

  • A shell version bump reaches main only AFTER every shell build passed, and the staging branch is what makes both possible. The order is bump → build → COMMIT → tag → attach. shells writes the five version.properties, commits them as ONE chore and publishes that commit on release/shell-bump; the five builds compile that sha; shell-commit fast-forwards main onto it once all five are green; app then tags from main and the attach jobs upload the artifacts. Committing first was the bug: a build that failed (a Kotlin compiler that moved, a missing keystore, a Rust crate that stopped building) left main declaring a shell version no artifact exists for, so the next release bumped again and the version file became a record of attempts rather than of builds — the failure this order removes, not just a reordering. ref: cannot be main any more (it would compile the PRE-bump tree and every artifact would declare the previous version, an update no installed app is offered), and it is a COMMIT rather than the branch name so a later run cannot move the tree under a 30-minute build. shell-commit carries no job-level if: — a skipped job skips every dependent, and app must still run to report that a chore-only push has nothing to release — and it refuses to push unless the staged commit is a descendant of main's tip, because main moving during the build window invalidates the artifacts rather than being something a merge could paper over. The staging ref is deleted only after the commit landed: while a run is stopped at a build it is the only ref holding the tree those artifacts were built from, which is what makes re-running the failed build job possible. tests/ci-gates.test.ts pins all of it (no HEAD:main in shells, one needs: edge per build on shell-commit, and the same staged ref: in all five builds).

  • The Android APK is a RELEASE artifact, not an npm package — and BUILDING it is a GATE on the app release. packages/android is a private Kotlin application, so there is no registry for it: .github/workflows/publish-android.yml is a reusable body (the same shape as publish-app.yml) whose only output is the .apk attached to the GitHub release. It runs in two phases, and the split is the point. build compiles, verifies and uploads the APK as a run artifact; release.yml's apk-build job calls it with mode: build, ref: ${{ needs.shells.outputs.ref }} (the staged bump commit) and version-code: ${{ github.run_number }}, and app needs: apk-build — so a toolchain that moved, a missing keystore, a Kotlin error or a signature mismatch stops the release BEFORE a tag exists. attach downloads that artifact and uploads it to the release app created; release.yml's apk job calls it with mode: attach, needs: [app, apk-build] and the same if: needs.app.outputs.released == 'true' as app-publish. Artifacts are scoped to the workflow RUN, so the two calls are one pipeline: the attach uploads the exact bytes the checks passed and cannot rebuild them. The old shape built the APK after the tag, so a failure there left a release already tagged and published with no shell attached — measured: the SDK's tools package was removed and the job died in setup, so the console kept offering the previous APK and the only repair was a hand-run dispatch. Building before the tag inverts that. ref: main rather than the trigger commit is load-bearing: the android bump job just pushed the shell version, and building the starting commit would declare the PREVIOUS one — an update no installed app is ever offered. A manual workflow_dispatch builds the TAG it names (so a repair matches the release it repairs) and attaches when given one; there is no mode input on that path, because a dispatch has no earlier call in its own run to have uploaded an artifact. It does NOT call the gate workflows: it is reachable only from release.yml, whose app job already depends transitively on both, and re-running the browser matrix for a packaging step adds minutes without coverage. That is why tests/ci-gates.test.ts treats it as a body that is NOT a gate provider and asserts the needs: chain instead. permissions: contents: write must be on the CALLER of the attach — a reusable workflow can only downgrade what it inherits, so read in release.yml turns the body's write into read and the upload fails with 403 after a full build; the build call needs only contents: read. version-code is ${{ github.run_number }}, typed string, stated at BUILD time and nowhere else: Android refuses an install whose versionCode does not increase, so a fixed value makes every release after the first uninstallable over the previous one — and github.run_number is a STRING context value, so a number input rejects it (actionlint: "string value cannot be assigned"). The versionName comes from packages/android/version.properties — the shell's OWN version, bumped by the shared release/release-shells.mjs in the shells job of release.yml — and only versionCode reaches Gradle as a property (-PkabmoVersionCode), because it is a monotonic counter rather than a version. The built APK is verified with aapt2 dump badging against both, and the asset is named kabmo-android-v<versionName>.apk from the same file, because versionFromAssetName reads the published version out of the asset NAME. Signing material is REQUIRED: without ANDROID_KEYSTORE_BASE64 the build step FAILS the job rather than falling back to a debug key (a different key on every runner, so no APK it produced could install over the previous one), and the built certificate is checked against the keystore's own fingerprint; the emptiness check lives in the SHELL because the secrets context is not available in a step if:. The keystore and keystore.properties are removed in an always() step.

  • The shell button is TWO offers from TWO facts, and conflating them hides one of them. It sits in the sidebar footer directly after About (both layouts). update: the page is running inside the APK and a newer one is published. install: the page is an Android BROWSER (Chrome, Brave, Firefox) and an APK is published — the reader may not know the native shell exists, which is the whole point of the offer, and there is no installed version to compare against so it names the newest published one. A desktop browser and an iPad get neither: an APK cannot be installed there, and the app's own update badge already covers the server. ShellDownload.kind carries which one it is, and shellDownloadLabel is the single place the wording lives (Install … vs Update …) because both footers draw the control — the phone's visible word is Get APK / Update APK rather than the old APK, which named the file type instead of the action. Both facts travel on the User-Agent, and they are different questions: KabmoWebView.configure appends KabmoAndroid/<versionName> and androidShellVersion parses it into the bootstrap's shellVersion (the app), while isAndroidDevice matches the platform token into isAndroid (the device). The UA is the only channel that crosses the very request which renders the shell, so the page is served already knowing and no bridge or extra round trip is needed. isAndroidDevice matches Android, never Mobile: an Android tablet sends Android without Mobile and is a device the APK installs on, while an iPad sends Mobile and has no APK at all — a Mobile test would drop the first and admit the second. Measured in the browser across six user agents: Chrome-Android and Brave-Android → Install Kabmo 0.3.5 for Android (Get APK), shell 0.3.0 against a published 0.3.5 → Update Kabmo 0.3.5 for Android (Update APK), shell 0.3.5 → nothing, desktop Chrome → nothing, iPad → nothing. The second comes from GET /api/updates/android → fetchAndroidRelease (src/server/lib/updates/android-release.ts), one unauthenticated GitHub read of the release LIST — not /releases/latest, which answers the newest release of ANY kind and this repository publishes THREE artifacts from one push. The packages are released FIRST (packages → marketplace → android → apk-build → app), and @semantic-release/github runs in both pipelines, so a kabmo-sdk/v* release is newer than the app release that carries the APK; measured against a stub answering exactly that shape, /releases/latest produced {url: null, latest: null} and the button vanished while the APK sat one entry below. The probe therefore scans the list (20 entries, drafts and prereleases skipped) and takes the first one whose ASSET LIST names an APK, cached 5 minutes on globalThis (the bun --hot rule) with resetShellReleaseCache() as the test seam. The version is read from the asset NAME, never the release tag — the APK rides on the app's release, whose tag names the SERVER version, so a tag comparison would compare an APK against a server. An up-to-date app shows nothing, and so does one AHEAD of the published asset (a sideloaded newer build): the update branch requires isNewer(latest, shellVersion), while the install branch needs no comparison at all because nothing is installed. The shell token alone is enough for the update offer even when isAndroid is absent — both come from the same UA, so a bootstrap served by an older build must not silently drop the update. A failed probe answers {url: null, latest: null} and never a 500, because a button the console cannot back with a link must not appear. Measured end to end in the real APK against a stub: shellVersion: 0.1.0 + release 9.9.9 → button after About with the right href; release 0.1.0 → no button, footer reads Settings · About · Desktop; a plain browser → no button at all.

  • The DESKTOP trio installs its own update too, and the whole path exists because the shell now reports its ARCHITECTURE. Every desktop artifact is per-architecture (Kabmo-0.2.0-mac-arm64.zip, Kabmo-0.2.0-win-x64-setup.exe, Kabmo-0.2.0-linux-x86_64.AppImage), so the console used to answer a desktop probe with the RELEASE PAGE — correct for a link, useless for a self-update, because naming one arch's file hands half the readers a build that will not launch. The shell injects arch beside shellVersion in __kabmoDesktop (a COMPILE-TIME fact in all three: #if arch(arm64), RuntimeInformation.ProcessArchitecture, cfg!(target_arch), which is also the right answer for a Rosetta/emulated launch), useShellDownload sends it as ?arch= to /api/updates/desktop?kind=…, and fetchShellRelease(kind, fetch, arch) resolves that ONE file. direct is a FIELD on the release payload, not something the client infers: it is true for the mobile pair (one file for every device) and for a desktop shell that named its arch, and false for a desktop probe without one — which is exactly the link-versus-button decision. SHELL_ASSETS[kind].selfUpdate is the one table stating WHICH file a shell can install by itself: the .zip for macOS (ditto -x -k extracts it with its signature; a .dmg cannot be extracted without mounting), the Inno -setup.exe for Windows (a stable AppId is what makes an install an UPGRADE), the .AppImage for Linux (the only one of its four formats a shell can replace — .deb/.rpm need root). An arch the release does not publish keeps the PAGE rather than falling back to the sibling build, and the arch is part of the CACHE KEY (shell-cache.ts, kind:arch), because one console is routinely shared by machines that differ only by architecture. ShellUpdateButton (common/shell-update-button/) is one control on both layouts, and the footer carries NO status text — every word a run has to say is a dialog. canSelfUpdate is the one predicate: a FILE, in a DESKTOP shell, inside the shell — Android installs through PackageInstaller (its own path, untouched) and iOS cannot install at all, so neither belongs here, and a shell that cannot install it draws a LINK to the release page instead. The LINK draws the glyph too, in both variants — that branch is the mobile pair's ONLY branch. canSelfUpdate refuses Android and iOS (each installs through its own path, or cannot install at all), so every APK/IPA offer is a link, and the link used to render variant === 'label' as the word alone: the phone's footer showed Get APK with no mark beside it while Settings, About and Desktop all had one. The label variant's glyph is 14px and its class is LABEL_CLASS — the footer's own bare row, no p-1 and no hover plate — because the desktop's 16px padded glyph plate reads as a different kind of control in a row of bare glyph-and-word entries; the icon-only variant keeps ICON_CLASS at 16. index.test.tsx pins the link case (an <svg> inside the <a>, the word beside it, no p-1) and mobile.e2e.ts measures the rendered box against the About glyph's own width, because a DOM query would pass on an <svg> with no box. The button opens Modal.tsx in a createPortal to document.body, and the portal is load-bearing twice: the footer is a 24px flex row of glyphs, so a dialog nested in it put its whole sentence into the ROW's own text content (measured in the browser — the row read as the dialog body), and any overflow/transform later added to that row would clip a fixed overlay. Four phases live in the dialog and nowhere else — confirm (what the platform will do: macOS replaces the bundle, Windows runs the installer silently, Linux swaps the AppImage and says a .deb/.rpm install cannot; plus what is NOT lost, since only this window restarts), working, and the shell's own sentence for done / error with a Try again that re-runs the same offer. A run is never started by the footer control — the confirmation is what asks the shell, which is why a 24px glyph cannot replace the app on a single press with no words. reset() runs when the dialog OPENS, so a dismissed failure does not greet the next press with its old refusal; reset refuses while a run is in flight, because the shell is already replacing itself and reporting idle would re-arm a control whose second press starts a second installer. Closing mid-run hides the dialog without cancelling anything — the shell has already begun, and a Cancel that could not stop it would be a button that lies — so the control stays disabled until the run answers. The shell does the work, and the reply is sent BEFORE it quits — a page whose shell vanished mid-request would keep a spinner over an update that worked: macOS downloads, ditto-extracts, checks codesign --verify --deep --strict plus the bundle's identifier and a STRICTLY higher version, renames the old bundle aside (undoing it on failure so the user is never left with no app) and restarts via a detached waiter that waits for its own pid; Windows downloads, checks MZ, runs the installer /SILENT /SUPPRESSMSGBOXES /NORESTART /CLOSEAPPLICATIONS /SP- and closes 600 ms later so the reply lands; Linux requires $APPIMAGE (a .deb/.rpm install says so and offers the page), checks the ELF e_machine, stages BESIDE the image so the rename stays on one filesystem, and schedules the relaunch one second later. What none of them can promise, and each module says so: authenticity. The macOS build is signed AD-HOC and the Windows/Linux artifacts are unsigned, so these checks catch a truncated download, an HTML error page saved as a binary and the other architecture's build — they do NOT prove provenance. HTTPS from an allowlisted GitHub host is what bounds the damage meanwhile; Developer ID + notarisation and Authenticode are the pipeline changes that would make it a real check. Rules live in testable modules (packages/macos/Sources/KabmoDesktop/ShellUpdate.swift, packages/windows/src/KabmoDesktop/ShellUpdate.cs, packages/linux/src/update.rs) and are pinned by swift run kabmo-desktop-tests (157 checks), dotnet run --project packages/windows/tests (124) and the Linux rules suite — all three suites assert the same host allowlist, the same version comparison and the same refusal sentences, so the four implementations cannot drift about whether an update exists.

  • Tapping that button inside the APK finishes the install itself — one system dialog, no file manager — and the keystore is what makes it possible at all. ApkInstaller downloads the APK into the app's cache, verifies it (getPackageArchiveInfo: the package must be dev.kabmo.shell and its versionCode must be strictly HIGHER than the installed one, because Android refuses an equal code with INSTALL_FAILED_VERSION_DOWNGRADE), then commits one PackageInstaller session; InstallResultReceiver launches the system's own "Do you want to update this app?" from STATUS_PENDING_USER_ACTION and reports every terminal status back through the same vocabulary. Silent install is impossible for a sideloaded app — only a device-owner or Play-managed one replaces itself without consent — so the confirmation stays, and REQUEST_INSTALL_PACKAGES plus the per-app "Allow from this source" toggle is what removes the four-step Downloads dance. The rules that fail silently live in ApkUpdate and are JVM-tested: what counts as an APK (URL path, MIME, or a Content-Disposition that NAMES a file — never the fallback name, or every download would match), which installer status is which failure, and that a download name is sanitized to one path segment. MainActivity.onDestroy releases the flow's static dialog and the installer callback, or an install that outlives the Activity crashes a successful update with BadTokenException.

  • The update path only works because every release is signed by the SAME keystore, and CI now refuses to ship one that is not. v0.2.0, v0.3.0 and v0.4.0 each carried a different certificate — apksigner verify --print-certs on the published assets shows three distinct SHA-256 digests — because ANDROID_KEYSTORE_BASE64 was unset and build.gradle.kts falls back to ~/.android/debug.keystore, which a runner regenerates per job. Measured on an emulator with the real assets: adb install kabmo-android-v0.4.0.apk over 0.3.0 answers INSTALL_FAILED_UPDATE_INCOMPATIBLE: Existing package dev.kabmo.shell signatures do not match newer version, and the same pair built with one keystore installs cleanly (versionCode 17 → 18, Success), while a downgrade is refused (INSTALL_FAILED_VERSION_DOWNGRADE). publish-android.yml therefore FAILS when the secret is absent (the fallback remains for a contributor's local build, never for a release) and verifies the built APK's certificate against the keystore's own fingerprint — keytool prints it uppercase and apksigner lowercase, so both are folded before comparing. version.properties carries 0.5.0 for the migration: one uninstall is still needed to get onto a device holding an older build, and every release after that updates in place.

  • The WebView's pinch zoom and the Settings → Page zoom slider are DIFFERENT zooms, and the first build had pinch switched off. setSupportZoom(true) + builtInZoomControls(true) + displayZoomControls(false) is the browser-shaped combination: the gesture works, no +/- buttons appear. The shell shipped with the first two false, so a two-finger spread did nothing while Chrome zoomed — the reported "kenapa gak ngezoom kayak Chrome". The slider (setInitialScale, re-applied on every onResume) is the page's STARTING scale and does NOT block a pinch: measured on Android 15 with a real two-finger gesture (a sendevent sequence on /dev/input/event1, since adb input cannot do multitouch), the viewport went 1 → 2.883 with setInitialScale(100) in force, and a cold start returned it to 1. Two traps cost the most time here and both are about the test, not the code: the emulator still zoomed with setSupportZoom(false) compiled in (verified with dexdump), so the setting is not the only path into the gesture there and an A/B on it proves nothing; and every early "pinch does nothing" measurement was taken against a page that had not loaded (the server was down, so the WebView showed chrome-error://), where no gesture zooms. Reproduce against a loaded page before concluding anything.

  • The shell draws a launch overlay from the tap until the console paints, and it is a SIBLING of the WebView — never a view inside the page. The page cannot report its own readiness (its bundle is what renders the app), and a page-drawn overlay would vanish exactly when the page fails to load. LoadingOverlay (platform views, like the settings screen) is added to a FrameLayout above the WebView; LoadingState holds the rules and is JVM-tested, because every one of them is an ordering the platform actually produces and each fails as a stuck or missing overlay rather than as an exception. The bar is indeterminate until real progress arrives: a determinate bar at 0 is indistinguishable from a stuck one, and the first seconds of a cold start are when the user decides whether the app is broken — so Chromium's 0% tick is ignored. 100% is not a finish (onPageFinished is, and the shell is still fetching the bundle at 100%), and progress never moves backwards within a load (a redirect reports 100 then 10, which made the bar snap back and read as a stall). A failed main-frame load keeps the overlay up with a reason and Retry / Server settings — host, connect, timeout, SSL, catch-all — and onReceivedError is gated on request.isForMainFrame, because a page that loads but cannot reach one of its assets reports an error too and treating that as a failed page would cover a working console. onPageFinished never clears a failure: a failed load still finishes on the error page Chromium renders, and hiding the overlay there is exactly the blank paper screen with no explanation the overlay exists to remove; Retry reloads the saved address because that error page is not a document the console can recover from. startLoad (cold start, saved-URL change, Retry) and a RELOAD re-open the overlay — a plain in-app navigation does not, or the login submit would flash it like a reload. The page's own Reload control is a different thing and was the bug: location.reload() fetches the SAME address again, which from the shell's side is a cold start in miniature (the console is replaced by a blank document while the bundle is re-fetched), and the overlay stayed hidden so the header's button looked like it did nothing. The only signal a reload gives is that the url is the one already on screen — measured on Android 15: onPageStarted reports no reload flag, doUpdateVisitedHistory says isReload=false, and a location.href = '/other' navigation reports a different url, while location.reload() and location.replace(location.href) both report the same one. LoadingState.isDocumentReload(startedUrl, shownUrl, phase) is that test, and it requires phase DONE because startLoad arms the overlay itself before loadUrl, so the first onPageStarted of a cold start would otherwise restart its own arm; the shown url is LATCHED in onPageFinished, never read from view.url, which already points at the incoming document by the time the next load starts. Verified end to end against a real console behind a 20s-delayed bundle: clicking the header's Reload put the wordmark and Loading the console… 51% on screen, and the same click without the delay completed too fast to see. Verified on a real emulator against a 4s-stalling stub and a dead port: the wordmark + Loading the console… 10% mid-load, no progress node once painted, and Could not connect… + Retry over the dead port with a tap recovering to the live page. The wordmark is the ARTWORK README.md embeds, not the app's name in a TextView: res/drawable/kabmo_wordmark.xml is a port of public/kabmo-wordmark.svg (same plate, same three K strokes, same outlined word, same colours) because the overlay is platform views and has no SVG renderer, and the three differences are forced by the format — every y shifted +128.12 (the SVG is authored around a baseline at 0 and a viewport cannot start below the origin), the plate a path rather than a <rect>, and the gradient inline in viewport space. A copy of one drawing is exactly what drifts silently (the overlay still renders, just not the mark), so WordmarkDrawableTest re-derives the drawable from the SVG — every path with only y shifted, the plate against the rect, the gradient span and both stops, the stroke weight and per-stroke colours — and fails on a nudged hex. app_name stays as the ImageView's contentDescription.

  • ALL FIVE shells draw one launch overlay, and the wordmark in it is GENERATED from the README artwork. Android and iOS had it from the start (a sibling of the web view, four phases, a wordmark, a bar, Retry, a failure that didFinish cannot clear); the three desktop shells each drew a Kabmo TEXT FIELD and a spinner instead, which is a different product for the same few seconds. They now share the contract: SplashState (packages/macos/Sources/KabmoDesktop/SplashState.swift, packages/windows/src/KabmoDesktop/SplashState.cs), LoadingState (Android, iOS) and Progress (packages/linux/src/splash.rs, drawn by splash_view.rs) are the same four phases (connecting/loading/done/failed), the same three progress rules (a frame after the end is ignored, progress never moves backwards, a zero frame stays indeterminate), the same five failure reasons with one sentence each, and the same reload test. The artwork is the reason this is one bullet rather than five: public/kabmo-wordmark.svg is the ONE copy, scripts/shell-wordmark.mjs GENERATES Wordmark.swift, Wordmark.cs and wordmark_data.rs from it, and each shell's rules suite re-derives every number from that same file (the iOS WordmarkTests, packages/macos/Tests/SplashTests.swift, packages/windows/tests/Program.cs, packages/linux/rules/wordmark.rs) — a hand-typed copy is the shape that drifts silently, because the splash still renders, just not the mark. bun run scripts/shell-wordmark.mjs --check is a CI gate in gates.yml. A platform that cannot do what the others do says so rather than imitating it: WebView2 exposes NO progress estimate (NavigationStarting/ContentLoading/DOMContentLoaded/NavigationCompleted and nothing between), so the Windows bar sweeps for the whole load instead of inventing a percentage, while WebKit and WebKitGTK give one through KVO/estimated-load-progress; UIProgressView has no indeterminate state, so iOS slides a SweepBar segment along the same 180pt track (two bars sharing one barRow, or the hidden one collapses and the sentence jumps every phase change); and the reload signal differs per platform — WebView2 reports CoreWebView2NavigationKind.Reload explicitly, while WKNavigationDelegate and WebKitGTK's load_changed have no flag at all, so macOS, iOS and Linux compare the started URL against the one LATCHED when a document finished (isDocumentReload, and only from done, or a cold start would restart its own arm). The macOS splash was in the app target and could not be tested, which is how it shipped as a text field: SplashView moved into KabmoDesktop so TestsWindow renders it in a real window and asserts the assembled view — the mark present and in the artwork's aspect, the bar determinate only once a real percentage arrives, the sentence the state's, Retry only on a failure — because a splash that drew the wrong phase passed every state-machine case.

  • The Android shell has TWO ways to change servers: the console's own chip, and the launcher shortcut. Long-press the Kabmo icon → Server settings still edits the ACTIVE address, and it is still the only entry point that works when that address no longer answers — a console that cannot load renders no drawer to switch from. The chip lives in the DRAWER's title bar rather than the chat header, measured: at 390px with a password set the chat header leaves the session title 89px and a 32px chip costs 40 of them, while the drawer row has ~158px spare. It is a chip, not a labelled button, for the same reason. Still no edge tab and no floating button: the WebView fills the display and every edge belongs to Kabmo's own chrome. What makes the chip exist at all is window.kabmoHost (ServerHost.kt), adapted by the page into the same __kabmoCall the desktop trio installs (src/client/lib/shell/transport.ts) — and the split between hasShellBridge() and isDesktopShell() is load-bearing, because titlebarInsetLeft reads "a shell with no identity" as a macOS window and would reserve 5rem for traffic lights a phone does not have. Commands: servers_state, servers_add, servers_remove, servers_activate; no servers_start/servers_stop, because a phone has no child process to own, and the state says startable: false so the panel never draws one. Params cross FORM-ENCODED and the state comes back as JSON TEXT (ServerWire) because org.json is a stub in the JVM unit suite — the same reason ShellPalette uses a line wire. The shortcut intent targets MainActivity, never SettingsActivity: a shortcut is launched with the LAUNCHER's identity, so a non-exported target is refused with Permission Denial: … not exported from uid (measured on a real APK — the shortcut silently did nothing). SettingsActivity therefore stays unexported and MainActivity opens it, handling the action in BOTH onCreate and onNewIntent because singleTask delivers a re-launch to the running instance. That is also why window.KabmoNative and its DeviceSettings category were removed rather than left as a second door: a control that opens a screen the shell already owns is a second thing to keep in sync, and the shell-side entry is the only one that survives a saved address that no longer answers. Two faults in that bridge were shipped in the first version and both are measured. (1) ServerHost answers every command on serverWork, so onActivate arrived on a pool thread and switchServer called LoadingOverlay.render/WebView.loadUrl inline — ViewRootImpl$CalledFromWrongThreadException on the tap, process dead (adb logcat: FATAL EXCEPTION: pool-3-thread-1 … at MainActivity.startLoad, reproducible on an Android 35 emulator against two real password-protected servers). A runOnUiThread hop is the fix, and the latch moved into startLoad so an address recorded but never loaded cannot make onResume skip the retry (that was the reported "it does not restart the page and stays on the old server"). (2) Both phones called the cookie wipe on a switch, which is what lost the session: cookies are keyed by host and the session cookie is NAMED per port (omp_session_<port> in src/server/lib/auth/token.ts), so a different origin can neither receive nor collide with the previous one's cookie — the wipe only signed the user out of every server in the list. Verified on the emulator: signing into both 4400 and 4500, then switching 4400 → 4500 → 4400 → 4500, reopens each console with no login screen and no crash. The desktop trio never cleared the jar on servers_activate; a cookie a server no longer accepts is a 302 /login from the auth gate, not a 401 loop.

  • A shell's launch overlay paints the CONSOLE's palette, which it can only learn from the page it is covering. Every overlay shipped a literal #FAF8F3/#141310 — the default LIGHT palette's paper and ink — so a dark install opened on a paper-white rectangle and jumped to a near-black console, and the macOS splash drew NSColor.windowBackgroundColor, which follows the OS appearance rather than the theme at all. The shell cannot read CSS (it draws before the page exists, which is the point), and it must not grow a second copy of a 45-palette catalog, so the palette crosses as VALUES: shellPaletteFor (src/shared/lib/theme/shell-palette.ts) projects one palette onto six literal-hex slots — canvas (the page's own ground, NOT paper: body paints canvas, so paper is a step lighter at the exact seam), paper, ink, muted and hairline (the document's own --ink-secondary/--ink-hairline mixes, composited over canvas), error — and normalizes every value to six-digit hex because the ported palettes are not uniform (jetbrains-light carries #FFF) and four parsers reading a shorthand is four places to get it wrong. The page publishes it as window.__kabmoPalette() (src/client/lib/native/palette.ts, installed before the first render, read at CALL time so a theme picked in Settings reaches the next launch with no reload), and each shell stores the answer for the NEXT cold start — the one launch where nothing is running to ask — then applies it to the live overlay too, because a theme changed in Settings is exactly the case where the stored palette is stale and the overlay it describes is still on screen. The wire is a pipe-separated line, not JSON: variant|canvas|paper|ink|muted|hairline|error, because Android's org.json is a stub in a JVM unit test (Method ... not mocked), so a JSON wire would leave the parser that most needs pinning as the only one that cannot have a test. Each shell parses it with a rule that REFUSES rather than half-fills (ShellPalette.parse in Kotlin/Swift/C#/Rust) — a field that could not be read would paint #000000 where the console paints paper, and keeping the previous palette is the only answer that cannot be wrong. Every shell's suite pins its default against the shared string (shellPaletteWire(shellPalette(null))), so a change on one side has to be made on both: ShellPaletteTest.kt (6), ShellPaletteTests.swift on iOS and macOS, ShellPalette.cs in the Windows runner, packages/linux/rules/palette.rs, plus shell-palette.test.ts and palette.test.ts for the projection and the publisher. The three native surfaces each needed their own "apply again" entry point, because a CALayer/UIButton.Configuration/ProgressBar copies the colour at assignment and nothing follows the palette on its own: LoadingOverlay.applyPalette (Android, iOS), SplashView.applyPalette (macOS), SplashView.ApplyPalette (Windows) and Splash::apply_palette (Linux, one reloaded CssProvider — and the stylesheet became palette::splash_css(&palette), since the constant it replaced hardcoded the light theme). The web surfaces that paint before the bundle are the same fix: firstFrameStyle inlines html,body{background-color:<canvas>} into the shell (unlayered, so it cannot lose to the bundle it stands in for — measured a white flash on a dark install for the length of the CSS request), and the PWA manifest's background_color shipped the brand tile's GREEN (#0B5D3B), so the manifest is now served from /manifest.webmanifest with the request's palette baked in (themedManifest, no-store) and the shell's link is rewritten to it — a hashed bundled copy's body cannot be varied by any route. Verified in a real browser against a live server: with one-dark-pro-soft stored, the served HTML carried <style>html,body{background-color:#21252b;}, meta theme-color #282c34 and manifest background_color #21252b, and __kabmoPalette() answered dark|#21252b|#282c34|#abb2bf|#777c87|#343940|#e06c75 — moving to light|#f4f1ea|… on a live theme flip with no reload.

  • The WINDOWS shell cannot resize at all, and WindowChrome is why the code looks like it can. WindowChrome { CaptionHeight = 0, ResizeBorderThickness = 6 } answers WM_NCHITTEST for the PARENT window, but the WebView2 is a child HWND covering the whole client area, so the mouse never reaches the parent's hit test and the page gets the mousedown instead. Every edge and corner is therefore un-resizable and the 6px band is a reservation nothing can grab — the same shape MicrosoftEdge/WebView2Feedback#4538 reports (a full-window WebView2 under WindowChrome cannot be resized; a Margin around the control is the only thing that makes the border live again), closed as a tracked feature request and folded into #2243, which asks for app-region to grow a resize meaning and is still open. #2243 also confirms app-region: drag is the ONLY non-client behaviour WebView2 exposes, which is why the drag works here and the resize does not. The fix is Gantry's ResizeFrame: the PAGE renders eight thin edge/corner strips with the right cursors and calls a bridge command, and the shell posts WM_NCLBUTTONDOWN with the matching HT* code after ReleaseCapture so Windows runs its own interactive resize. NOT done — it is a shared-client change (a strip per edge on every layout) and this shell cannot be RUN on a macOS host, only compiled. packages/windows/README.md states the defect rather than claiming the border works; do not restore that claim without the strips.

  • The macOS shell is a native Swift package, and its window chrome is the one part a webview host cannot inherit. packages/macos (Swift 6 + AppKit + WKWebView, no Xcode project, no third-party deps) is split the way packages/ios is: Sources/KabmoDesktop holds every rule that can be tested without a screen (Persisted, Store, System, ShellWindow's pure draggedOrigin), and Sources/kabmo-desktop is the AppKit app. The SwiftPM product is named Kabmo, not kabmo-desktop, because a process with no bundle reports its executable's file name — swift run kabmo-desktop put kabmo-desktop in the menu bar (measured with NSRunningApplication), and scripts/build-app.sh copies the product to Contents/MacOS/Kabmo so the plist, the binary and the menu bar agree. The data directory is ~/Library/Application Support/Kabmo, with migrateLegacyStateDir() moving kabmo-desktop's state on the first launch after the rename (only when the new directory is absent). The drag hook lives in sendEvent, not mouseDown — measured: a press inside a WKWebView never reaches NSWindow.mouseDown, so a mouseDown override is dead code that looks correct. sendEvent asks the page whether the press landed on [data-drag-region] through dragRegionSelector, and the follow is manual arithmetic (beginDrag → draggedOrigin(windowOrigin:startMouse:pointer:), a pure function) rather than performWindowDragWithEvent:: the native loop reads the physical pointer through an event tap and cannot be driven or tested (AXIsProcessTrusted: false on a normal machine — measured before, during and after, all identical), while the manual form is asserted by TestsWindow against a real ShellWindow. Double-click obeys AppleActionOnDoubleClick (DoubleClickAction.current()), the bar carries the system's own right-click menu (barMenu()), and validateUserInterfaceItem claims only close/minimise/zoom/full-screen so an unrelated action cannot be swallowed. The frame's RESIZE BAND is claimed before the page too, and that is why diagonal resizing did nothing. fullSizeContentView puts the page under the bar, so the page marks its whole top 40px [data-drag-region] — including the 3px strip along the top edge and the band around both top corners that NSThemeFrame reserves for dragging the window's SIZE. Measured through the real ShellWindow: a press at (1, H-1), (6, H-6), (W-1, H-1) and (W/2, H-1) all answered "the page says drag handle" and started a window MOVE, so every diagonal resize (both top corners, and the top edge itself) moved the window instead of resizing it. The bottom, left and right edges kept working because the page marks nothing there — which is exactly the reported shape, "diagonal resize does nothing" while the plain edges are fine. frameOwnsPress(at:) is the predicate: contentView.superview.hitTest at the press point, and the answer is the FRAME's when the hit is neither the content view nor inside it. It is deliberately not a hard-coded band thickness — measured on macOS 27 the band is 3px along the top edge, 4px along the bottom and the sides, and 8px into the top-left corner because the close button's own margin is reserved there, so a fixed probe point passes on one macOS and lands in the page on the next. sendEvent breaks out of the claim for a frame press (so super.sendEvent starts AppKit's own resize loop), the right-click menu refuses the band the same way, and claimsBarPress carries both so the window suite asserts the decision rather than restating its inputs. runResizeBandCases measures where the band ENDS and asserts the header is a drag handle again past it, in both directions — a fix that simply refused every press in the top strip would pass a one-sided case. Pinned by TestsWindow against a real ShellWindow; the fix was A/B'd, with the three "not claimed as a window drag" cases failing when frameOwnsPress was removed. The traffic lights are claimed by the SYSTEM before the page is asked, and that ordering was the bug that made close / minimise / zoom dead. The page marks its whole header [data-drag-region] and reserves its leftmost 76px for the buttons (trafficLightInset), so elementFromPoint at a traffic light answers "a drag handle" — the window claimed the press, super.sendEvent never ran, and the button never saw the click, while the same strip still moved the window. sendEvent now tests hitsStandardButton(at:) FIRST and breaks out of the claim (so the press passes through to the button). That predicate is standardWindowButton(_:) for .closeButton / .miniaturizeButton / .zoomButton, converted to window coordinates — the only way to reach them, since they live in the private titlebar container and not in contentView, and their frames are AppKit's to decide. A hidden button is skipped so a window without .closable reserves no dead strip. TestsWindow pins both directions: a press inside each button's own frame is not a drag and reaches the button, and the gap just past trafficLightInset is still a drag (the fix must not turn the reserved strip into dead window). Its own harness had to move: the "blank header" case pressed at x=60, which is INSIDE the close button's frame, so it was asserting the bug as correct behaviour — the page-owned point is trafficLightInset + 24. The Edit menu is what gives the page its clipboard chords, and without it the composer ignores ⌘V. A WKWebView receives NO ⌘C/⌘V/⌘X/⌘Z/⌘A unless the app's menu bar declares those key equivalents — the web view is the first responder and does see the keydown (a page reads metaKey and key === 'v'), but the edit COMMANDS travel through the menu system, so with no item claiming the chord AppKit never asks the responder chain, paste: never runs and the page's own paste event never fires either. The shell built App, File, View and Window and nothing else, which is why the macOS app's composer silently ignored the keyboard's clipboard chords. Measured A/B on a bare WKWebView against the same window with the menu: ⌘V left the field unchanged with no paste event versus paste-proof; ⌘A left the selection 4-4 versus 0-11; ⌘C left the pasteboard nil versus the selected text; ⌘X left alpha in the field versus an emptied field with the text on the pasteboard; ⌘Z/⌘⇧Z did nothing versus hi → empty → hi. EditMenu.swift holds the row table (editMenuItems) and the gate (editMenuHandles), and four details are load-bearing because each fails silently: undo:/redo: have no AppKit-declared selector (they are NSResponder's informal protocol, absent from every public header) so they are spelled as strings while NSText's cut:/copy:/paste:/delete:/selectAll: are used as selectors so a typo is a compile error rather than a dead row; Redo carries ⌘⇧Z EXPLICITLY, because a menu item's default mask is .command and keyEquivalent: "z" alone collides with Undo and makes the row unreachable; ShellWindow.validateUserInterfaceItem must allow the rows — it answered false for every action it did not name itself, and undo:/redo: resolve against the WINDOW (measured: NSApp.target(forAction:) answers NSWindow for those two and WKWebView for the other five) whose own default answer is false, so the menu was built, the chords were declared, and ⌘Z still did nothing; and the chords need a KEY window, so a suite driving them must NSApp.activate first or the key-equivalent pass never runs. TestsWindow/main.swift drives all of it into a real WKWebView, and its undo case runs FIRST because WebKit keeps ONE undo stack per document — run after the cut case, ⌘Z undid the cut and the field came back as cut-me (measured), which reads as "undo is broken" when the ordering was what was wrong. With the menu removed, 8 of those checks fail. Quit was slow for three independent reasons, and each was measured rather than guessed. (1) applicationWillTerminate ran a Task and then DispatchSemaphore.waited on the MAIN thread — and NSApplicationDelegate methods are @MainActor, so the task that would signal needed the very actor blocked in the wait: the app beachballed for the full 6 s timeout on EVERY quit. It is now applicationShouldTerminate + .terminateLater, AppKit's own deferral, with the work detached and reply(toApplicationShouldTerminate:) ending the quit. (2) The spawned child inherited a BLOCKED SIGTERM: posix_spawn copies the caller's signal MASK, and POSIX_SPAWN_SETSIGDEF resets only the DISPOSITION — the app blocks SIGTERM, so kill(-group, SIGTERM) left it pending, the child never died, and killGroup always ran its full 40 × 50 ms budget. Verified A/B: with only SETSIGDEF the child "died from SIGTERM? false"; adding POSIX_SPAWN_SETSIGMASK with an empty set, "true". 2.27 s → 0.058 s per server. (3) A zombie answered "alive": isAlive polled kill(pid, 0), which still answers 0 for an exited-but-unreaped child, so the grace loop never saw it go. It now uses waitpid(WNOHANG) (which also reaps) and falls back to the signal probe on ECHILD for an adopted pid. The escalation is also COLLECTED now, not just sent — returning straight after SIGKILL left the child a zombie for the next caller. Tests/main.swift measures all three (an exited child is not alive; a well-behaved child is released in under 0.5 s; a SIGTERM-ignoring child is still killed) and each case fails with its fix reverted. Linux had the same two shutdown faults, and one more. is_alive polled kill(pid, 0) (same zombie bug, same fix — waitpid(WNOHANG)); and stop_all() ran on the GTK main loop, freezing the window for the whole grace budget, so it now runs on its own thread with MainContext::invoke posting the quit back (the Supervisor moved from Rc to Arc for that). It does NOT have the mask bug: Rust's Command resets the signal mask for the child itself. Windows was already correct on both counts — its Closed handler is on the UI thread but every await in the library is ConfigureAwait(false), so the continuation cannot queue behind the wait. A bridge command runs ON the GTK loop, so anything that blocks there freezes the window — and a frozen loop cannot run delete_event, which reads as "the app will not quit". connect_script_message_received is delivered on the main thread, and update_apply used to do a ureq download (its own read timeout is 120 s) plus the ELF check and the rename inline: the shell was unresponsive for the whole download and uncloseable while it ran, the same end state macOS reached for a different reason. It is now answered by start_update (main.rs): everything cheap — the AppImage check, the one-job guard, every refusal — is decided in the same tick so the page is never left waiting on a job that never started, only the blocking half goes to a thread, and the answer returns through timeout_add_local because the reply script and the window are GTK objects (reply_now is the one place that evaluates one). A worker that dies without answering still answers the page, and the restart is scheduled from the loop, and ONLY on success: update::plan refuses a build that is not an AppImage before anything is downloaded, and update::outcome carries the reply and the relaunch decision together, because a refused install that restarted would come back as the image this process already runs while the page reports the failure — both pure and pinned in rules/update.rs. The __relaunch marker and its strip in the bridge reply are gone with the old path. servers_start and the start half of servers_activate carry the same budget and are deferred the same way: Deps::start now SPAWNS (Supervisor::spawn) and the wait is system::wait_until_ready — address and pid only, which is what makes it safe on a worker thread. ServerStore::start therefore answers the StartResult (id, address, pid) instead of a (id, url) pair, and activate answers (url, Option<pid>): a server that already answered has nothing to wait for, while one this call spawned must be waited for before the window moves. The __await marker carries the worker's inputs (address, pid, port for the log line, and the record to stop), the reply is held until it lands, and a server that never answered is STOPPED before the page is told — it is still a child of this process, and leaving it would make the next Start answer "already starting on that port". rules/store.rs pins that a switch needing no start hands back no pid. The reply has to reach AppKit through the main RUN LOOP, not the main actor — and that is why 0.4.2 could not be quit at all. applicationShouldTerminate returning .terminateLater puts -[NSApplication _shouldTerminate] into a nested event loop that services CFRunLoopPerformBlock but not the main dispatch queue, which is where Swift's main-actor executor lives: the deferred reply (await MainActor.run { sender.reply(…) }) therefore never ran, the app kept a window it would not close, and every later Quit was answered cancel against a latch that could never be cleared — the reported "after updating the macOS DMG the app does not quit, it has to be killed from Activity Monitor". Measured on the installed 0.4.2: a Quit request was accepted, the process stayed idle, and sample showed the main thread parked in _shouldTerminate → nextEventMatchingMask → mach_msg with no concurrency thread holding a Kabmo frame. TerminateCoordinator (Sources/KabmoDesktop/Terminate.swift) now delivers the answer through CFRunLoopPerformBlock(CFRunLoopGetMain(), .commonModes) — which that nested loop DOES service — and sends replyToApplicationShouldTerminate: through the ObjC runtime, because NSApplication marks it @MainActor while a run-loop block is not and perform(_:with:) cannot carry a BOOL (it passes an object pointer whose low byte read as false; measured, and it canceled the quit it was meant to complete). The rebuilt bundle quits in 20–40 ms, three runs. Two further traps are stated in that file because each one silently re-breaks it: the shutdown work must be an actor method, never an injected @escaping () async -> Void (a closure created in the @MainActor delegate is main-actor-isolated, so awaiting it from the detached task hops back to the starved main thread — measured in the window suite: the child task entered, the empty closure never returned, and the task group waited out its whole ceiling), and a second Quit must answer .terminateNow rather than .terminateCancel, because cancel aborts the pending reply and leaves the latch set for the life of the process. runQuitCases in the window suite drives the real path — NSApp.terminate with the coordinator answering, an 8 s watchdog as the assertion, and reply: false so the suite itself survives. Both test suites are plain executables that exit non-zero, because XCTest ships with Xcode and this package builds with the Command Line Tools alone: swift run kabmo-desktop-tests (204 checks, no window) and swift run kabmo-desktop-window-tests (a real window and webview). The window suite loads its page ONCE, at top level, and every case drives that document. A load started from inside runCases never finishes on the x64 release runner: measured on run #128, the navigation case's loadHTMLString(_:baseURL:) sat at estimatedProgress = 0.1 with isLoading = true for its whole 30 s budget while the identical load at top level commits in 0.3 s, so five checks failed on a working web view (the arm64 leg passed with the same code). The same measurement is why DroppedPathsWindowTests drives the page already on screen instead of a second WKWebView. The suite page therefore carries the navigation case's own elements (#panel, #blank) and is loaded with loadSimulatedRequest at http://console.test/ — a real http origin, because the rule under test compares origins and an about:blank page would answer .inside for a cross-origin subframe even with the delegate that ignores targetFrame. proveClickCloses() runs LAST for the same reason: it closes the window, and a web view whose window is closed is one WebKit may suspend. Settings › asks the PAGE for its modal, and a reload is not that. Every settings screen is a client-rendered modal, so the shell has nothing native to show — the row's job is to dispatch the one event both layouts already listen for, omp:open-settings (PageEvents.swift, openSettings(in:)). What it used to do was append ?settings=1 and load the URL again, and nothing on the client reads that parameter: the modal never opened while the live document was thrown away — a running turn, the composer draft and the timeline's scroll position with it. The Linux shell had already sent the event, so the contract was known and this shell simply was not using it. The case in the window suite dispatches the SHIPPED script into a real page and asserts the listener fired once, the detail is empty, and the document SURVIVED (documentElement.dataset.probe kept), which is the half that fails if the row ever reloads again — verified by restoring the reload, which fails 4 cases including the later typing ones because the page was replaced. release/macos.test.js pins the two silent halves: the row goes through the helper rather than a query parameter, and the name the Swift constant declares is the name settings/Modal.tsx listens for (a typo either side is a dispatch into the void).

  • The macOS shell is released by a version BUMP, not a publish — and packages/macos/version.properties is the ONE place its version is declared. release/macos.js holds the table (MACOS_SHELL), readVersionName, replaceVersionLine and the watermark; the shared release/release-shells.mjs bumps it (with the other four shells, in one commit) from the same Conventional Commits rules the app uses; release/macos-version.mjs prints it for scripts/build-app.sh, which fills CFBundleShortVersionString and CFBundleVersion. .github/workflows/publish-macos.yml is a two-phase reusable body: build compiles the package on BOTH architectures (arm64 on macos-15, x64 on macos-15-intel), runs both Swift suites, verifies the version the plist declares, the ad-hoc signature and the binary's own lipo -archs slice, and uploads one Kabmo-<version>-mac-<arch>.zip per row — and release.yml calls it as macos-build BEFORE app tags, so a Swift error or a plist that disagrees with the properties file stops the release instead of shipping a tag whose release carries no app. macos-app attaches that artifact after the release exists and builds nothing. app needs: macos-build, so the build is a gate rather than a consequence. The archive is made with ditto, never zip. zip -r strips the bundle's extended attributes and code signature, and macOS then refuses to launch the extracted app ("damaged") with nothing in the archive to say why; verified by extracting the published shape and re-running codesign --verify --deep --strict. There is deliberately no User-Agent token, unlike the Android and iOS shells — but the console DOES offer this app an update. The version comes over the BRIDGE instead: the shell injects __kabmoDesktop before the page's first script, and desktopShellFromIdentity reads shellVersion from it, so the sidebar's offer is decided on the first paint. A UA token would mean every asset request carried a string the bridge already supplies. The reported version must come from the BUNDLE (ShellVersion.current() → CFBundleShortVersionString, which scripts/build-app.sh fills from version.properties): App.swift used to declare shellVersion: "0.1.0" as a literal, so the pipeline bumped the properties file to 0.2.0 while the running app went on telling the console 0.1.0 — a comparison against a version that did not exist. release/macos.test.js asserts both halves (no KabmoMacOS token, and no literal version in App.swift).

  • tests/ci-gates.test.ts is the contract, asserted on the YAML graph rather than on file text. Every job in a releasing workflow must reach both gate jobs TRANSITIVELY (so a publish job added without needs fails the test rather than shipping), every local uses: must resolve to a file that declares workflow_call, every with: key must be declared by the callee, no gate job may carry an if:, the chain packages → marketplace → shells must hold and every shell build must needs: shells (the lockfile and bump ordering, which the transitive check cannot see; the five per-shell bump jobs must be gone and the one commit must stage all five version files), the shell bumps must run and commit BEFORE apk-build compiles and BEFORE app tags, the APK must be built before the tag and only attached after it, and publish.yml's gate jobs must pin the ref they check. Two traps are pinned by its own implementation: needs is a STRING for one dependency and an array for several (spreading the string yields its characters), and the array must be COPIED before stack.pop() — handing out the parsed array drains the job's own needs as the walk consumes it, so the second job through the closure reports a gate it does reach as missing (measured).


GitHub Bot & Review Automation

@kabmo-labs-bot is a GitHub App plus the workflows in .github/workflows/; it triages every new issue and reviews every pull request. CONTRIBUTING.md is the contributor-facing half of this contract — read it before changing any of these files, because the two must tell the same story.

  • Writes go through the App, never GITHUB_TOKEN. Every bot job mints an installation token from BOT_APP_ID + BOT_APP_PRIVATE_KEY (actions/create-github-app-token), so comments and labels come from @kabmo-labs-bot and cannot re-trigger a workflow that matches bot comments. Jobs are skipped outside kabmo-labs/kabmo: a fork run has no App secret.
  • Command surface, first line of a comment, exact match: @<BOT_MENTION> help|review|summarize|triage|reproduce [focus] (plus the /oc-review alias). help is answered without a model — it is a fixed string. The mention comes from the repository variable BOT_MENTION (default kabmo-bot) rather than a literal, so an App whose slug differs still triggers: bot-config-check.yml is the one place that reads the App's real slug from its own installation token and reports the value to set.
  • The agent is the pinned omp CLI, run headless. .github/scripts/install-omp.sh owns the version pin (OMP_VERSION); .github/scripts/run-omp-bot.sh runs omp -p with a persona file, a policy overlay, and the prompt on stdin. The runner needs oven-sh/setup-bun; omp is a Bun program.
  • Two provider modes, picked by whether BOT_API_BASEURL is set. Unset: BOT_MODEL is a provider omp already knows and BOT_API_KEY is exported as the env var that provider reads (BOT_API_KEY_ENV, e.g. DEEPSEEK_API_KEY). Set: the model lives behind an OpenAI-compatible gateway, so the script declares a provider for the run from .github/bot/provider-models.yml and passes the key with --api-key. The second mode exists because omp ships no provider for an arbitrary base URL, and because --api-key overrides the file's value while a models.yml apiKey cannot reference an environment variable ($VAR and ${VAR} are both literally true strings — verified against a local OpenAI-compatible stub) — so the template carries a placeholder and the real secret never touches the runner's disk. A thinking level (BOT_THINKING) only reaches the provider when the model entry declares reasoning: true — verified against the stub: without that line --thinking is accepted and silently dropped, with it a --thinking high run arrives as reasoning_effort: "high". The template carries the line; a model's declared efforts may never include off (the schema rejects it, and omp clamps off up to the lowest listed effort). Repository settings: secret BOT_API_KEY; variables BOT_MODEL, BOT_API_BASEURL (optional), BOT_API_KEY_ENV (required only when BOT_API_BASEURL is unset), BOT_THINKING (optional, default high), BOT_MENTION (optional, default kabmo-bot). The three provider settings are read from either store (vars.X || secrets.X), so a value placed in Secrets still works. BOT_MENTION must be a variable: every command trigger is a job condition, and a job condition may read github, needs, vars and inputs — never secrets — so a secret of that name is silently ignored and the default is used instead (bot-config-check.yml reports exactly that).
  • Policy is data, in the .github/bot/*.yml policy overlays. tools.approval.<tool>: deny plus a bash.patterns allowlist ending in - match: "*" / deny gives a deny-by-default session; the reviewer cannot edit a file or run anything but gh, git, rg, ls, cat. Never write approval: prompt: there is no UI on a runner, so a prompt is a rejected call that reads to the model as a broken tool.
  • Procedure is versioned with the repository, in .omp/skills/{pr-review,issue-intake}/SKILL.md, read by the agent through skill://. The persona files (.github/bot/*.persona.md) hold identity, guardrails and the exact output contract; the skills hold the steps. A 25 KB prompt never lives in a workflow.
  • Nothing downstream trusts the model. verify-review-verdict.sh re-reads the posted comment from the API, requires the final line to be the marker <!-- omc-review-meta {"head":"…","verdict":"…"} -->, checks that the marker's HEAD equals the requested HEAD and is still the current one, that the human-readable verdict and reviewed-HEAD lines agree, and only then writes one review:* label. A mismatch fails the job and marks review:automation-failed; the verdict itself never fails a check. The human-readable checks read values, not decoration (backticks, bold, whitespace): a live run posted a correct review with every backtick stripped on the way to the API, and a gate stricter than the generator turns a finished review into a wasted run — the HEAD must still be named as a complete token, so tolerance applies to formatting and never to content.
  • Readiness is a label, not a comment: review:pending|ready|needs-evidence|blocked|human-required|automation-failed. Exactly one at a time — set-review-status.sh is the only writer. Drafts carry none.
  • Trust boundary: pull_request_target runs with secrets, so the base is what is checked out and the head is fetched as passive git data — never installed, built, or executed. A diff touching AGENTS.md, CONTRIBUTING.md, .github/{workflows,scripts,bot,ISSUE_TEMPLATE}/**, .github/PULL_REQUEST_TEMPLATE.md or .omp/skills/** is refused (review:human-required): automation must not clear a change to its own policy.
  • Logic lives in .github/scripts/*.sh, not in YAML. Each script takes arguments and reads its state through gh, so it can be exercised locally against a stubbed gh; the workflow steps stay thin glue. When adding a gate, add it as a script.
  • Never put user content into a run: block through ${{ }} — title, body, comment text and focus go through env: and are read as shell variables. run-omp-bot.sh pipes the assembled prompt to omp on stdin for the same reason: no interpolation into shell text, no argument-quoting hazard.
  • Editing any of these files is a ci-type change; the review-policy paths above mean the pull request that changes them will be marked review:human-required and must be read by a human.

Clone this wiki locally