MicJot 0.4.0

Released 2026-10-30.

GUI v2: setup that signs in first and checks the key on one screen, a main window with a Dock icon and every transcript on Home, Settings in six tabs, a floating bar that shows the app the text is going to and a landed moment, and plans v2 (3,000 free words, the 7-day trial after them, the paywall). The account server is not deployed yet; builds without an account service complete setup and dictate without an account.

Plans v2: free words, the trial after them, and the paywall

Free is every feature, MicJot AI included, for the account's first 3,000 words (site/data/plans.json v2), counted per account across its Macs and never reset. The app counts the words of every landed dictation or Command result (pasted or on the clipboard; not cancelled, failed or a Polish) with the owner History and the stats use, and reports each once by the dictation's id (POST /v1/usage/words, idempotent). The report is queued first in the account's local state file (word-reports.json, never the Keychain): a Mac that is offline reports at its next launch, refresh or landing. Server totals win; words the server has not confirmed yet show as "+N not yet synced" on Home and the Account tab, only when there are any. Builds without an account layer count nothing and block nothing.
Dictations kept while the speech model downloads or loads (the first dictations of a new install) and dictations finished from disk at a later launch count too: the batch that finishes them to the clipboard and History reports each one by its History id through the same path as a dictation typed into the app. Kept Command instructions (stored as spoken, never run) and dictations into secure fields (never stored) are not counted, as the stats do not count them.
The 7-day Pro trial is no longer granted at sign-in. At the cap the dictation that crosses 3,000 still lands; from then on dictation pauses until the trial starts or Pro is bought (owner decision, 2026-10-29): the key records nothing, the bar shows the yellow-ring "Free words used" state with the hint "Free words used · Start the Pro trial or upgrade to keep dictating" (clicking it opens the plans), and one sheet opens over the main window: "You've used your 3,000 free words" with "Start a 7-day Pro trial, no card" (one call, the record refreshes, the sheet closes and the key works again), "Upgrade to Pro" (the existing upgrade page) and "Not now" (the sheet closes, the key stays paused). It opens on its own once per app session, never while a dictation is being recorded or is in flight (it brings MicJot's window forward, which would send a paste in progress to the clipboard; it waits for the pipeline to drain instead), and again at will from the bar, Home's words bar and card ("Start a 7-day Pro trial") and the Account tab's "Start trial", over whatever page is open. Home says "Pro trial · 5 days left" while it runs (the ceiling of the server's end date).
After the trial, dictation pauses again until Pro: the same paused bar with "Free words used · Upgrade to keep dictating", and the upgrade sheet offers Pro monthly / yearly only, once on its own, then a one-line reminder on later presses. The decision is one pure gate (DictationGate: allowed · allowed, last words · offer trial · blocked) read at key-down, after every landing, by the bar, Home's words bar and card, the Status card ("Dictation key · Paused"), the menu bar's first line and the Account tab, and every paused sentence comes from one owner (FreeWordsCopy), so no surface says "Ready" or "Hold fn to dictate" while the plan pauses the key. MicJot AI stays off at the cap (PlanEntitlement.freeWordsUsed); the proxy's 402 codes (plan_required, the new free_words_used) both refresh the record and drive the same gate.
Account Worker: migration 0003_free_words.sql (accounts.free_words_used, the word_reports table); /v1/me adds free_words {used, limit} (Free only), trial {state, ends_at} (not_yet · available · active · ended) and micjot_ai; POST /v1/usage/words; POST /v1/trial/start (once, only at the cap; 409 trial_unavailable with the reason otherwise). The proxy serves Free on the Free budgets while words remain, answers 402 free_words_used (with trial_available) at the cap and 402 plan_required after the trial; Pro is unchanged. The account page, the sign-in page and the trial reminder say the same; /__mock/free-words forces the states from a shell and qa/journey-localhost.sh walks the whole path. 145 Worker tests.
Snapshots: Home at the cap (main-home-free-cap), on the trial (main-home-trial) and paused (main-home-blocked), both sheets (paywall-trial-offer, paywall-upgrade), the Account tab at the cap and paused, and the bar's two paused "free words used" cases (pill-22 after the trial, pill-23 with the trial on offer).
Release review (P6): closing the setup window on "Your key" (or leaving it behind another app) no longer leaves the dictation key dead until relaunch: the key screen's check suppresses real dictations only while the setup window is the key window, and closing the window releases it and its session. Removed the retired pro_max plan code (an unknown code grants nothing locally), the unused top-apps statistic and a dead key-check helper; the menu bar's plan line reads "Plan: …"; the Plan screen's primary reads "Finish" in a build without an account service; the sign-in waiting line no longer names a provider button the page may not offer.

Floating bar: the app you are dictating into, and a landed moment

While listening, hands-free and processing, the capsule carries the icon of the app the text is going to (18 pt, at the left end), read once when the dictation key goes down (the same frontmost lookup the privacy gate uses) and never re-read, so it is the destination even when another app comes to the front before the text is ready. Nothing in front, or MicJot's own window, shows a generic glyph in the same slot; the bar never names the app. Widths: listening 97, hands-free 128, processing 122; the other states keep theirs.
The destination belongs to the job, not to the last dictation (review round 1): Polish shows the app in front when ⌃⌘P was pressed, a batch of dictations kept for the speech model (or finished from disk at launch) has no app to go to and shows the slotless 98 pt processing capsule, and the slot empties once nothing is in flight. BarState.processing carries destination; FlowBar draws the slot only where BarState.showsAppIcon says so.
When the text has a home the capsule flashes a ring and a check replaces the waveform with the word count for 900 ms ("14 words", green) before the bar settles; text that went to the clipboard instead (the app went away, the screen locked, the paste grew stale, Accessibility missing) gets the amber "on clipboard · 14 words" variant. Failed, cancelled and unobserved outcomes keep their notices and show no moment. The moment's width follows the digits of the count (a 1,234-word dictation does not truncate), and a new key-down ends the previous moment at once. The decisions (BarLanding, BarState.showsAppIcon, the capsule widths) live in MicJotCore with tests; the controller publishes the job's destination and the moment, and seam tests cover the capture at key-down and at ⌃⌘P, the batch, the outcome and the sounds.
One sound per completion, behind Settings → General → Sounds: MicJot's own chime (Resources/Sounds/landed.wav: two sine partials, 160 ms, normalised to −6 dBFS, generated by scripts/make-chime.py, copied into the bundle by scripts/build-app.sh) when the text reached the app, the pop when it went to the clipboard instead (the same sound a kept batch makes), the alert when it could not be typed. The v1 stop pop at the key release is gone: it would have been a second sound for every completion. The start sound stays; the self-test and the snapshot renders stay silent.
Onboarding's key screen shows the same bar decision as the real bar (icon slot and landed moment included) instead of its own reading of the phase.

Settings v2: six tabs, Advanced folds and the Free/Pro upgrade sheet

Settings is a tab list — General · Dictation · Writing · Privacy · Account · About — with one short form per tab (720×540 on its own; it fills the main window's content area). The sidebar gear, the menu bar's Settings… and the Dock all open it; the account chip and a micjot:// nudge open the Account tab, the bar's "needs Accessibility" link the Privacy tab. Account exists only when the build has an account service; a request for it lands on General otherwise.
General: Open at login · Show MicJot in the Dock (new; the activation policy follows it live) · Show the bar when idle · Sounds (one switch for every sound: the start sound, the completion chime, the clipboard pop and the alert) · Language · Run setup again.
Dictation: the four key tiles with the live check from onboarding (the tile lights while the key is held, "Detected · held 1.2 s ✓" after a press; one KeyPressRecord interprets presses for both screens) and the Fn conflict fixes; Hands-free double-tap; Microphone picker and level; Mute other audio; the speech model's download/retry row. Advanced (closed by default): keep the microphone ready + standby window, boost quiet speech, the ⌃⌘V paste-last shortcut and ⌃⌘P, maximum length.
Writing: Smart formatting · AI cleanup · Styles per app (summary + Open Style) · Use text near the cursor, and one line that says where AI requests go right now (MicJot AI / your own key / paused / offline rule-based, each true for the state). QA builds (MICJOT_DEV_TOOLS) add an Advanced fold with the Anthropic key field (Keychain-refusal status kept), the model id and "Prefer my own key"; customer builds have no own-key UI anywhere.
Privacy: Save history + retention · Private dictation · Clear history… · Excluded apps · the Permissions checklist, now with an Input Monitoring row that tells "granted · starting the key monitor…" from "granted · reopen MicJot to apply" (PermissionStatus.hidStartAttempted; onboarding's card reads the same decision) · Privacy Policy and Terms.
Account: Email · Plan and status · Words (used of 3,000 with a bar on Free; Unlimited on Pro) · Macs with Sign out of this Mac · Upgrade to Pro… (a Free/Pro sheet with the Monthly/Yearly toggle from the plan constants and "Continue to secure checkout", which opens the existing upgrade page) · Manage billing… · Refresh · Delete account… (on the account page). The 14-day-trial sign-in copy, the own-key toggle and the daily token budget lines are gone.
About: version · Check for Updates (one sentence shared with the About window) · Save Diagnostics · Privacy Policy, Terms of Use, Acknowledgements.
Removed from the UI, defaults kept in AppSettings so old settings files decode and the self-test/bench still run: engine choice, cloud providers and their key fields, the model picker, the data folder button. Notices that pointed at "Settings → AI", "→ Permissions" or "→ Transcription" now name the tab, and none offers "add your own key".
Snapshot renders no longer read this Mac's login item or Globe-key setting (ShellStatus.liveReadsEnabled), so the key-screen and Settings baselines do not depend on the rendering Mac.
Review round 1: the Settings → Dictation key check no longer runs a real dictation. While the Dictation tab is in front on the key window a hold only lights the keycap (nothing is recorded, typed or put on the clipboard); a tab change, another app coming to the front or the window closing makes the key a real dictation again. The controller now owns "who suppresses" as a set of reasons (onboarding's key screen, the Settings check) so the two cannot fight. The signed-out Account tab says "Not signed in on this Mac." instead of a free-forever claim; the trial and plan lines say that Pro is needed to keep dictating after the free words and the trial; builds without an account service say that free words are not counted. Inside the main window the tabs are a strip across the top (one sidebar, not two); the standalone 720×540 page keeps its tab list. The Advanced folds are rendered from SettingsTab.advancedRows (one owner; "4 settings" beside the label while closed), the Sounds caption names the chime and the alert, Settings → About offers Move to Applications, and no customer-build sentence names an Anthropic key.

Setup is a 900×620 window with five stages: Sign in › Permissions › Your key › Try it › Plan. Sign in is the first screen and the only thing on it (Apple, Google or email, each through the existing browser sign-in; builds without an account service show one line and Continue). The speech model downloads in the background after it; a slim strip from screen 2 on shows bytes, time left, "ready", "paused: offline" or the failure with Retry.
Permissions are three cards with one truthful line each and a drawn likeness of the macOS prompt; Continue needs Microphone and Accessibility, Input Monitoring can wait.
Your key: pick one of four keycap tiles and hold it; an oversized keycap lights violet while held and green with "Detected · held N s ✓" on a real press, the floating bar shows under it at real size, and the chosen tile gets a "Detected ✓" badge. The screen says when the check needs Input Monitoring or Accessibility.
Two practice screens (a mock Messages reply, a mock Mail compose) use the exact key you chose in every sentence, show "Landed in 1.8 s · 14 words ✓", and, while the model is still loading, keep the dictation and type it into the field when the model is ready.
Plan: your speaking figure when the tries were long enough (at least 5 s and 8 words), otherwise typical figures labelled as such, with the baselines cited; Free and Pro cards from the plan constants under a Monthly / Yearly toggle; "Continue with Free"; "Upgrade to Pro" only when an account service exists; "Open MicJot at login" (on).
Removed: the welcome disclosures, the "How should MicJot write?" step, the model download consent step and the own-key field in onboarding. "Run setup again" opens on Permissions when a grant was revoked and marks the stages your Mac already satisfies as done so they can be skipped.
Review round 1: the key screen never records (a hold only lights the keycap; the controller suppresses the dictation while the screen is open), a practice landing is only text that reached this app's own practice field after the screen opened (a dictation into Notes, or one from an earlier screen, never counts), a denied or restricted microphone grant gets its own chip with "Open Settings…", Esc on a practice screen no longer jumps back, the download strip fits one line ("Speech model · 212 of 629 MB · about 2 min left"), "Run setup again" after a revoked grant lands on Permissions in builds without an account service too, and the Sign in and Plan screens say nothing about Settings → Account where there is none. The microphone card's disk sentence, the device-flow disclosure (which now names the MicJot version it sends) and the revoked-Accessibility hint each have one owner shared with Settings.

Main window v2 and a Dock icon

MicJot has a Dock icon; clicking it opens the main window. showInDock (on by default) switches the app back to a menu-bar-only accessory without hiding an open window; the Settings toggle arrives with Settings v2.
Sidebar: Home · Dictionary · Snippets · Style, with Settings (gear) and an account chip (email, plan) at the bottom. The status footer is gone; its facts live in a Status card on Home (Dictation key · Speech model · MicJot AI, one word each, the full sentence as a tooltip).
Home: "Hold ⟨key⟩ to dictate anywhere" with your key as a keycap, a compact stats row, and every transcript in one searchable list grouped by day. Rows are time · text · Copy · "…" (Insert again, Retry transcript, Show what you said, Delete). No app initials or outcome badges: a dictation that did not reach its app shows a small glyph with a tooltip. The search also matches the app name and the outcome words the old filters used.
"Retry transcript" re-runs the writing step (formatting, then AI cleanup when a route resolves) on the words that were recognised and copies the result; audio is never kept, and the menu says so.
Free accounts see a free-words bar and a words card with "Upgrade to Pro" once the account server reports free_words; nothing shows until it does.
Removed: the 30-day activity chart and "Most used in".
Review round 1: each History entry keeps the language the engine detected (detectedLanguage; older files read nil), so "Retry transcript" cleans the words in their language; a retry's AI errors reach the account layer and the circuit breaker like a dictation's, and a retry waits while a dictation is in flight. "Delete transcript" asks once ("MicJot keeps no audio, so the text can't be recovered."). One owner for the dictation key's status words (Status card, menu header, checklist); the empty list distinguishes searching, collecting, history off and Private dictation; a day title outside the current year shows the year; the headless entry points never show a Dock icon.

Release checks (QA builds; nothing here ships to customers)

The snapshot gate compares each screen per 32 px tile over RGB (SnapshotComparison): any tile whose normalized RMS is above 0.10 fails the pair, with the whole-image RMS (≤ 0.02) kept as a second signal. A one-word change ("Off" → "On" on Home, "at" → "on" in a Settings caption) passed the old whole-image check twice during the GUI v2 loop (P1 and P4 review rounds) and now fails with the tile named; a re-render of the same tree peaks at a tile RMS of 0.043 (text anti-aliasing on the device-flow sheet), so encoder noise still passes. The log lists every matched screen's figures.
qa/run-checks.sh --update-snapshots (MicJot --snapshot-update) adopts only the light renders that differ or are new, removes baselines no longer rendered, prints each decision and leaves every matching baseline byte-identical, so git status afterwards lists exactly the screens that changed (the old rewrite-everything left fixers restoring unchanged files by hand).
The self-test's account check follows plans v2: a first sign-in must be a Free account with 0 of 3,000 words, the trial not yet offered and the dictation gate open; after the cleanup through the proxy it reports one dictation's 14 words, repeats the report (which must add nothing) and reads the count back from /v1/me.

The Anthropic key is read from the Keychain once per launch

Each dictation read the key twice (the AI client and the circuit-breaker fingerprint). On a Mac where the build is signed without a Team ID, every newly installed build is a new app to the login keychain's partition list, so each read raised the password dialog; the dialog took focus from the target app and the dictation ended on the clipboard ("not pasting: targetNotFrontmost / tooOld", 2026-10-29). Keys are now read once per process (at launch, when the key presence is checked) and remembered in memory; Save and Remove update the memory, and a change made in Keychain Access while MicJot runs is seen after a relaunch. A cancelled or denied dialog is remembered too, so no later dictation raises it; the Settings key field says what happened and how to clear it. After installing a new build on such a Mac the dialog appears once, at launch: choose "Always Allow". Developer ID builds carry a Team ID and do not re-prompt per build.

Capture engines are parked before they are freed

Stopped capture engines (the recorder's and the Settings level meter's) are kept alive for five seconds before deallocation. AVFoundation's device-property listener fired after an engine had been freed and crashed the app (EXC_BAD_ACCESS in AVAudioIOUnit, 2026-10-29, while a Bluetooth headset switched profiles right after a meter closed).

After onboarding, MicJot registers itself to open at login once per install (the toggle in Settings → General still turns it off, and a user who turned it off is never re-registered). The speech model then loads at login, so a cold Neural Engine compile (about a minute after an install, a macOS update or a purged cache) does not land on the first dictation. Never applied in a hermetic QA run.
Measured and rejected: running the encoder on the GPU to avoid the compile (cold load 17 s instead of 58 s, but p50 latency 2.1 s instead of 1.1 s and 2.9 GB instead of 200 MB resident). A measurement-only environment hook (MICJOT_COMPUTE_ENCODER / MICJOT_COMPUTE_DECODER = gpu | ane | cpu) stays in SpeechTuning.computeOptions().

Speech model stays loaded

A memory-pressure warning no longer releases the speech model; only critical pressure does, and only when idle. On the owner's 16 GB Mac the warnings arrived every half hour, macOS purged the compiled-model cache at the same time, and the reload then recompiled the model for the Neural Engine (58-62 s measured) while the dictation waited. Normal launches load the model from the cache in about a second; that was never the slow part.
While a load runs longer than 10 s, Settings and the main window say it is compiling for the Neural Engine, show the elapsed seconds and the reason; the model-ready log line now says "cached" or "compiled for the Neural Engine".

MicJot account and MicJot AI (app side; docs/GO-TO-MARKET.md section 8, action item 8)

(Superseded within this release by Onboarding v2, Settings v2 and Plans v2 above: the onboarding "Writing" step, the 14-day trial granted at sign-in, Pro Max and the own-key UI for customers never shipped. Kept as the record of how the account layer arrived.)

Settings gains an Account section (first) and the onboarding "Writing" step offers three equal choices: try MicJot AI free for 14 days (sign in), use your own Anthropic key, or keep it on-device. Signing in is a browser device flow: the app shows an eight-letter code, opens the account site's /activate page and waits for the approval; the sheet says when the code expires (10 minutes) or the sign-in was declined. The device token lives in the login Keychain (session item); the cached plan record (account.json, no secrets) is refreshed at launch, every six hours, after a plan refusal, and every 5 s for two minutes after an upgrade hand-off; micjot:// links only nudge a refresh.
AI requests take one of three routes, resolved before each call: MicJot AI (signed in and entitled: trial, Pro, Pro Max, or within the 14-day grace of the last confirmed period), the user's own key, or none (rule-based text). With both, a "Prefer my own Anthropic key" switch keeps requests on the key. The proxy's answers never trip the key circuit breaker: a 402 inserts the formatted transcript with one notice and refreshes the plan; a 429 daily-budget answer pauses MicJot AI until Retry-After (your own key takes over if set); a proxy 401 is confirmed against /v1/me before this Mac is signed out. An unreachable account server is "AI unavailable" with one notice, never "signed out". Trial days left are the ceiling of the remaining time ("14 days left" right after sign-in).
Command mode and Polish need "an AI route" rather than a key; their notices name what would provide one, true for the build and the account state. The menu bar shows the plan while signed in. Account features are hidden in builds without MicJotAccountAPIBase / MicJotAccountSiteURL (written by scripts/build-app.sh from MICJOT_ACCOUNT_API_BASE / MICJOT_ACCOUNT_SITE_URL; QA builds also honour the same environment variables at run time and accept http://localhost:<port>, which --customer builds ignore).
The snapshot renderer and the unit tests never touch the login Keychain any more: a fresh debug binary reading the owner's key item waited on the keychain's permission dialog forever (the key fields render as "Paste key").

Website v2 (`site/`, `scripts/lib/sitegen/`; nothing here ships inside the app)

The home page is rebuilt around the product (SPEC §5; structure informed by the Lume research, original copy, icons and motion throughout): a drawn Mac screen whose app chooser and held keycap play an app-specific dictation demo, rows of floating app icons for "works where you type", a live spoken → written demo with both columns on screen, the features told with motion, a four-step "How it works" row whose one figure is the self-test's latency labelled typical, a setup section mirroring the five onboarding stages, a privacy section and the FAQ; nav = Home · Pricing · Download for macOS; the typing test is gone. Pricing shows the two plans from site/data/plans.json v2 under a Monthly / Yearly toggle with the 7-day trial after the free words; every plan sentence carries the "not on sale yet" prefix while accounts_live is false, and the pages that describe the app's screens are generated from one owner each (sitegen/setup.py mirrors OnboardingFlow.swift, sitegen/settings.py mirrors SettingsTabs.swift), with drift tests that parse the Swift sources so a renamed tab or stage fails the site gate. Reduced-motion and no-JS fallbacks, zero third-party requests, Lighthouse 100/100/100/100 on the home page; qa/site-tests/ grew to 67 tests (phrase sweeps for stale v1 claims on every authored page, contrast pairs, both release states).
site/release.json may trail VERSION by a release (the record names the last shipped build; VERSION the one being built), so the site renders between a version bump and its notarized build; a record ahead of VERSION is refused.

Launch stack (repository tooling and documents; nothing here ships inside the app)

Website: scripts/make-site.sh renders 30 pages into the git-ignored site/public/ from the Markdown in site/content/, site/data/plans.json (prices, budgets, trial and device constants; the single source for the site and the backend), site/data/site.json (owner placeholders, accounts_live), the new site/release.json (version, DMG URL, hash, size, notarized, update_feed_signed) and the repository documents (CHANGELOG.md, the legal drafts, ACKNOWLEDGEMENTS.md). While notarized is false no page offers a download and _redirects carries no /download/latest rule; while accounts_live is false the pricing page says the paid plans are not on sale yet and links no account host. The hand-written HTML pages under site/ are gone; _redirects keeps their old paths as 301s. qa/site-tests/ (67 tests at 0.4.0, contrast, html-validate, Lighthouse) checks both release states; site/dev.sh serves the output on port 8788.
Backend: workers/account/, one Cloudflare Worker behind three hosts (api., account., pay.) with D1, a nightly Cron Trigger and rate-limit bindings: passwordless accounts (email code and link; Google and Apple implemented, unconfigured), RFC 8628 device sign-in for the Mac app, the free words and the 7-day Pro trial after them (plans v2, above; the 14-day trial at sign-in never shipped), effective_plan as one pure function over the subscription row, Paddle webhooks with dedupe, ordering and shuffled-replay tests, the two-step refund (cancel immediately, then adjust), chargeback hold, account deletion as a tombstone, server-rendered account and pay pages, and the AI proxy (POST /v1/messages: per-plan daily request and token budgets, Sonnet-then-Haiku routing by task, 64 KB and max_tokens caps, pass-through responses, token counts recorded, no body ever logged). Mock adapters (email outbox, in-memory Paddle, Anthropic-shaped upstream, identity page, Turnstile stub) run everything on localhost; each real adapter switches on with a secret. 145 tests at 0.4.0; qa/journey-localhost.sh walks the whole journey with curl and prints PASS. Nothing is deployed.
Documents: docs/PRIVACY.md brought to 0.3.1 and extended with accounts, MicJot AI, payments, processors, the website and your rights; docs/TERMS.md §1 and §3 rewritten for a free app with an optional paid service; docs/REFUNDS.md and docs/DISCLOSURE-MICJOT-AI.md new; all marked drafts for legal review with bracketed owner blanks. docs/BACKEND.md, docs/INCIDENTS.md and docs/runbooks/ (one page per owner-held account) are the operator pages; docs/HOSTING.md and docs/RELEASING.md carry the Pages build command and the site/release.json step. scripts/ai-usage-report.py summarises the app's token-count log lines per task so the plan's cost estimate can be replaced by measurements. qa/launch/ holds the records of the night and the owner's one-page summary.
GUI v2 documents (P6): README.md describes the shipped setup (OnboardingStage / OnboardingScreen), the main window and the six Settings tabs; docs/PRIVACY.md says that setup begins with a sign-in, that the account counts the words of landed dictations (a random id and a number, never text) and that builds without an account service continue without one, with the sentence flagged for legal review; docs/TERMS.md §4 scopes the own-key route to QA builds; docs/HOSTING.md and docs/PRODUCTION-READINESS.md no longer describe the Download click, Pro Max or the 14-day trial. The website's Settings-path drift test now covers the verbatim legal pages too.