Redesign the transactional emails, AI push copy and error messages (R20)

[thomasluizon]

Closes thomasluizon/orbit-tickets#75 (R20).

Inventory, counted from the tree

The ticket's counts are all low. I trusted the tree.

surface	ticket says	tree has	where
Email types	6 + layout	7 + layout	src/Orbit.Infrastructure/Email/Templates/
ErrorMessages constants	138	146	src/Orbit.Application/Common/ErrorMessages.cs
DomainErrors constants	74	83	src/Orbit.Domain/Common/DomainErrors.cs
Error codes	not stated	146	src/Orbit.Application/Common/ErrorCodes.cs
AI generators at 0.7 to 0.9	3	3 push/summary, 5 in the band	src/Orbit.Infrastructure/Services/

• The seventh email is ApiKeyCreation (.html + .txt), which no ticket owned. Every type but the layout ships an html and txt pair, and both are updated.
• The two extra services in the temperature band are AiGoalReviewService and AiRetrospectiveService at 0.7. Neither is push copy, so neither is in scope.
• ErrorCopy covers 222 distinct codes, which is every code in ErrorCodes, ErrorMessages and DomainErrors, in EN and pt-BR.

Emails

DESIGN.md put the old templates in breach on six counts, so this is a rebuild rather than a recolour:

1. Accent #7F46F7 violet, against the granted warm orange #C4530F.
2. A gradient header band, against No gradient wash.
3. box-shadow: 0 8px 28px rgba(127, 70, 247, 0.45) on every CTA, against No decorative glow.
4. Rubik and Inter, against Geist Sans / Space Grotesk / Geist Mono.
5. A planet emoji and sparkle glyph bullets, against No sparkle icon; identity is the mark.
6. The accent painted on the verification code, which is not one of the four rationed accent roles. The code is now --fg-1 on a well.

Dark mode, honestly

Email clients are the constraint, so this is stated plainly rather than claimed.

• The templates now author light inline and override dark through @media (prefers-color-scheme: dark), with color-scheme: light dark. That matches "light mode MANDATORY, dark primary".
• The dark block needs !important because an inline style beats a <style> rule everywhere.
• Apple Mail, iOS Mail and Outlook for macOS honour the query. Gmail and Outlook.com do not; they apply their own inversion. Inverting a light document degrades gracefully, which is exactly why the old dark only document was the riskier choice.
• Web fonts do not load in most clients. Geist is named first and the stack falls back to the system UI face, so the mark carries identity rather than the type.
• translate="no" is on the title and the logo alt. It is not inside the body copy, because those strings are shared with the .txt part and cannot carry markup.

LogoUrl is untouched. It is a load bearing URL owned by the web repo.

Voice

BRAND.md is the authority, and the reasoning is short: Orbit sells to adults who cannot keep a routine, so the emails describe a mechanism and name one next action rather than listing features. The welcome email's three feature bullets became three things to do first, and its CTA is a plain verb, "Add your first habit". Every email now says what happened before what to do next. Zero exclamation marks, zero dash characters, both languages edited together. "Orbit" and "Astra" are never translated.

AI push copy

The slip alert and proactive prompts each carried a worked example that demonstrated the two things the voice bans:

- Title: 5-8 words max, personal and warm (e.g., "Stay strong today!" or "You've got this!")
- Be creative and varied -- don't use the same structure every time

At temperature 0.9 the model copies its examples, so the prompt was the slop source. The daily summary prompt had a doubled hyphen in eleven places, including its one GOOD example.

NotificationVoice.Rules is now the single voice contract injected into all three prompts. It states each ban directly and carries no example at all. The fallback strings carried the same two tells and are rewritten in both languages.

Two things I did not do, deliberately:

• No post-processing scrub. The ticket says to pin the register in the prompt, not after it.
• No temperature change. The prompt is the instructed lever. The residual risk is real and belongs on the record: a prompt constraint at 0.9 is probabilistic, not a guarantee.

Tests assert the constraint, never the wording: every prompt carries the contract, and no prompt contains an exclamation mark, an em dash, an en dash or a doubled hyphen.

Error messages, and the leak

The reported bug reproduces exactly. The API returns { error, errorCode } with an English message. The UI translates client side from a 62 code map plus 30 rules that match English message substrings. DAYS_REQUIRE_QUANTITY_ONE is in neither, and the domain guard's wording does not contain the substring the validator's wording matches, so the raw English falls through. Matching on server prose is the defect class, not the one string.

The fix follows the ticket's own instruction that the user facing text is a separate localised constant selected by the error code:

• ErrorCopy maps every code to EN and pt-BR copy. Each entry answers what happened and what to do next.
• LocalizedErrorResultFilter swaps the message at the response boundary, using Accept-Language. One seam, no call site churn: threading a language through the 190 call sites of ToErrorResult and ToPayGateAwareResult would have put the same three lines in 190 places and still depended on each remembering.
• DomainErrors is untouched. Its sentences stay developer facing, as the ticket requires.
• The catalog is total, and ErrorCopyTests proves it by reflection over all three sources. A new constant without copy fails the build, so the raw message fallback is unreachable rather than merely unused.
• ErrorMessages now takes its English from the same catalog, which deletes 145 sentences that were being written in two files and could silently drift.

AppError and Result now carry the arguments behind a {0} placeholder, because Format bakes them into the message and the boundary otherwise cannot format the localised template with the same values.

INVALID_CODE_ATTEMPTS_REMAINING is added. INVALID_VERIFICATION_CODE was shared by constants that differ in how many values they take, and copy selected by code cannot serve both. Adding a code is append only; the old one still serves the no argument case.

Found and fixed on the way

• Five pay gate strings ending in Upgrade to unlock!, a banned word and an exclamation on a sell. They now share one calm sentence, since the screen already names the feature.
• Three chat tools held inlined copies of error sentences.
• UnhandledExceptionHandler hardcoded its own 500 message.
• ConfirmWaitlistCommand returned an uncoded raw string.

Wire compatibility

Shape, status codes and the JSON property names are unchanged. ErrorResponse pins its names and marks Args [JsonIgnore].

One value changed and is now back: the wrong-code failure on the deletion and API key step-up flows keeps INVALID_VERIFICATION_CODE. Round 2 finding C2 caught it moving to a new code, which both shipped clients have no branch for.

Round 2 review, pull request 532 at dd862844

Sixteen findings, four blocking. Every one is answered below. Nothing is left open except the two cross repo items at the end, which are named rather than silently dropped.

C1, CRITICAL. The deletion email promised a wipe the product does not perform

ConfirmAccountDeletionCommandHandler calls user.Deactivate(scheduledDate), AccountDeletionService removes the row at that date, and signing in again calls User.CancelDeactivation. The intro now names the window and the way out of it, and reads the number from AppConstants.MaxDeletionGraceDays rather than typing it.

You asked to delete your Orbit account. Orbit deactivates it first, then removes it for good within 30 days. Sign in again while it is deactivated and the account comes back with everything in it.

The window is written as an upper bound because the send happens before confirmation, so the exact date is not known yet: a free account is scheduled 7 days out and a Pro account at plan expiry plus 7, both capped at the constant.

C2, HIGH. The new error code broke the step up screen on both shipped clients

Taken: keep the existing code. ErrorMessages.InvalidDeletionCode and InvalidApiKeyCreationCode return to ErrorCodes.InvalidVerificationCode, and ErrorCodes.InvalidCodeAttemptsRemaining is deleted.

The count needed a sentence the plain catalog entry cannot carry, so ErrorCopy grew a counted variant selected by the presence of arguments rather than by a second code. Its trailing Remaining attempts: {0} is byte identical in both languages on purpose: packages/shared/src/utils/step-up.ts:117 parses it with /remaining attempts:\s*(\d+)\s*$/i, and a translated token would lose the count for every pt-BR reader the moment C3 makes the reply Portuguese. The sentence never reaches a screen. step-up.tsx:229 and step-up-screen.tsx:194 render stepUp.attemptsOne and stepUp.attemptsMany from their own localized plurals, and the wrong phase shows t('stepUp.wrong'), not the API message.

That also answers C7, the ungrammatical "1 tries": the number is no longer rendered by this API in prose, so no plural form is written here.

Checked by TheAttemptsCountStaysReadableByTheShippedClients and TheAttemptsVariantKeepsTheTokenTheShippedClientsParse, both of which assert the code and match the same regex the clients use.

C3, HIGH. The localized copy never reached the Android app

RequestLanguageResolver reads the signed in account's stored User.Language and keeps Accept-Language as the anonymous fallback, which is what ResendEmailService and ProactiveCheckinSchedulerService already do. The filter became IAsyncResultFilter to allow the lookup, which runs only on a response that already carries an error body.

It is deliberately not cached: a cached language answers in the old one for as long as the entry lives after somebody changes it, and the read is one indexed row on a path that is rare by construction.

D6 is fixed in the same place. LocaleHelper.IsPortugueseAcceptLanguage ranks the header's tags by quality value, so pt;q=0.1,en;q=0.9 resolves to English.

C4, HIGH. The slip alert asserted a time the scheduler contradicts

CalculateAlertTime sends two hours before the peak, and at 08:00 when SlipPattern.PeakHour is null. The prompt now states when the push lands, not only when the pattern is, and adds one rule: never say or imply that it is now the usual time. The fallback branches on the peak hour and makes no time claim without one.

The mediums

• D1. Taken: narrow the doc comment. ValidationExceptionHandler is an IExceptionHandler that writes its own ValidationFailure body and never produces an ObjectResult, so the filter cannot see it. Routing it through ErrorCopy needs an error code on every rule across 139 validator files and 285 WithMessage sites, which is its own ticket rather than a line in this one. Both claims that read wider than the code are now narrowed, in LocalizedErrorResultFilter and in ErrorCopy.
• D2. Not fixed here, and it is the one thing that still needs a paired UI ticket. See Cross repo below.
• C6. The 429 body is built from ErrorMessages.TooManyRequests.ToErrorBody() at both sites in DistributedRateLimitAttribute, so the filter matches it and RATE_LIMITED is reachable. The 429 now carries an error code for the first time. limit, count and retryAfterUtc leave the body; Retry-After and X-Orbit-Request-Id already carry the timing and the request id, and no client reads the three fields.
• C5. The check in fallback counts: one open habit reads as one, and nothing promises automatic logging, because LogHabitTool records only the habit a person names.
• C8. The sync copy states the circumstance and an action that exists, instead of promising a reload and a later send that no caller performs.
• C9. CHALLENGE_CLOSED English reads "This challenge is no longer open to new people."
• C10. RECAP_MONTH_NOT_CLOSED points at coming back rather than at an arrival that only happens for a reader with a PushSubscriptions row.
• D3. AiSummaryService.BuildSummaryPrompt is internal static and joins both voice theory sources, so the guard written for its doubled hyphen leak reaches it in both languages.
• D4. The comment said a missing entry fails at startup. ErrorMessages is a static class of static readonly fields, so it is a TypeInitializationException on the first request that touches the class, and ErrorCopyTests is what keeps it out of production.
• D5. AppError.Equals and GetHashCode walk Args element by element. MaxTagsPerHabit.Format(5).Equals(MaxTagsPerHabit.Format(5)) is true again, covered at equal counts, different counts, and against the unformatted template.

The change detector tests

TheVoiceContractBansEveryCharacterClassTheOldPromptsLeaked, TheVoiceContractBansTheSellingRegister and TheVoiceContractNamesEveryBannedHypeWord are replaced rather than defended. The three assertions now run over every prompt a model actually receives, through EveryGeneratedUserPrompt, so they redden when a generator stops carrying the contract rather than only when somebody edits the constant they were reading.

EveryLocalizedEmailDiffersBetweenTheTwoLanguages pairs by (Email, Field) instead of by list index, and asserts both key sets match, so a copy record that gains a property cannot make it compare mismatched pairs.

Cross repo

D2 needs a ticket in orbit-ui-mobile and this pull request should wait for it. packages/shared/src/utils/error-utils.ts:252-305 maps errors to i18n keys by matching the backend's English sentence, and getFriendlyErrorKey returns the caller's generic fallbackKey when nothing matches. The rewritten copy stops matching, so TITLE_REQUIRED, UNIT_REQUIRED, TARGET_VALUE_INVALID, TAG_NAME_REQUIRED, DUPLICATE_SCHEDULED_REMINDERS, MAX_SCHEDULED_REMINDERS, MAX_HABITS_PER_GOAL, MAX_TAGS_PER_HABIT and GENERAL_HABIT_IS_BAD fall to a generic toast. The ticket adds each to ERROR_CODE_TO_KEY and deletes the text matching rules those codes depend on.

I did not file it. This repository has no tools/create-ticket.mjs; the adapter lives in orbit-ui-mobile, and the brief for this worker forbids touching a second repository. The orchestrator owns filing it, and the paragraph above is the ticket body.

A second ticket covers D1: give every FluentValidation rule an error code so ValidationExceptionHandler can resolve copy through ErrorCopy. 139 validator files, 285 WithMessage or AbstractValidator sites. VerifyCodeCommandValidator.cs:19 ships "Code must be a 6-digit number" verbatim to a pt-BR reader today.

Not closed

• Astra tool results surface Result.Error through IAiTool.cs:34. The ticket assigns that rendering to ORB-17 and ORB-43, so the code to copy mapping is here and the rendering is theirs.
• Screenshots are not attached. Per D13 only a human grants visual completion, and the no screenshot rule stands.

Assumptions

• The deletion email states the grace window as an upper bound read from AppConstants.MaxDeletionGraceDays rather than branching free against Pro. Rejected: adding a plan flag to SendAccountDeletionCodeEmailJob, whose arguments Hangfire persists, for a distinction the reader cannot act on differently.
• The counted attempts copy keeps its English Remaining attempts: token in the pt-BR string. Rejected: translating it, which satisfies the catalog's voice rule and then drops the count for every pt-BR reader, because the shipped clients parse the English token and never display the sentence.
• RequestLanguageResolver reads the row on every error response instead of caching the language. Rejected: a memory cache keyed by user id, which answers in the old language for the life of the entry after somebody changes it.
• C3 is covered by a unit test over the real filter and the real resolver with a substituted repository, not by an integration test. Rejected: a real database harness, which tests/CLAUDE.md forbids.
• The 429 body drops limit, count and retryAfterUtc. Rejected: keeping them by widening ErrorResponse, which would add three fields to every error body in the API.
  Equal quality values retain header order; focused tests passed before and after refactoring.
  Kept redesign/main’s Sunday or Monday recap anchor; current week preference no longer controls it.

Test evidence

Full suite, after the fixes, at 63f77942:

dotnet build Orbit.slnx                        0 Errors
dotnet test Orbit.slnx --no-build
  Orbit.Analyzers.Tests            32 passed, 0 failed
  Orbit.Domain.Tests              585 passed, 0 failed
  Orbit.Application.Tests        4070 passed, 0 failed
  Orbit.Infrastructure.Tests     2404 passed, 0 failed
                                 ----
                                 7091 passed, 0 failed

Red first, for each blocking finding

The four defects were reintroduced together in the working tree on top of 147746ad, the suite was rebuilt, and the new tests were run with the defects present. Command:

dotnet test Orbit.slnx --no-build --filter "FullyQualifiedName~EmailCopyTests|FullyQualifiedName~ErrorCopyTests|FullyQualifiedName~LocalizedErrorResultFilterTests|FullyQualifiedName~AiSlipAlertMessageServiceTests"

Observed with the defects present, exit code 1:

Finding	Test	With the defect	After the fix
C1	EmailCopyTests.TheDeletionEmailNamesTheGraceWindowAndTheWayOutOfIt, both languages	FAIL	PASS
C1	EmailCopyTests.TheDeletionEmailNeverCallsTheRequestIrreversible, both languages	FAIL	PASS
C2	ErrorCopyTests.TheAttemptsVariantKeepsTheTokenTheShippedClientsParse, both languages	FAIL	PASS
C2	LocalizedErrorResultFilterTests.TheAttemptsCountStaysReadableByTheShippedClients, both languages	FAIL	PASS
C3	LocalizedErrorResultFilterTests.APortugueseAccountSendingNoHeader_GetsThePortugueseCopy	FAIL	PASS
C3	LocalizedErrorResultFilterTests.TheStoredLanguageWinsOverTheHeader	FAIL	PASS
C4	AiSlipAlertMessageServiceTests.TheFallbackWithoutAPeakHour_MakesNoTimeClaim, both languages	FAIL	PASS
C4	AiSlipAlertMessageServiceTests.TheFallbackWithAPeakHour_PlacesTheHabitLaterThanTheSend	FAIL	PASS
The unchanged test that did not catch C3 is LocalizedErrorResultFilterTests.MissingAcceptLanguage_FallsBackToEnglish. It passed with the defect present in that same run, and it still passes after the fix: a request with no header and no signed in account is anonymous, which is the one case the header only rule answered correctly.

Gates checked locally

• node tools/check-dashes.mjs --files <changed> exit 0, --check-baseline exit 0.
• ORBIT0001 does not run under the locally installed SDK, so every changed .cs file was scanned for bare // and /* */. Zero hits.
• No new #pragma warning disable or [SuppressMessage], so tools/suppression-allowlist.json is unchanged.
• node tools/arch-map.mjs regenerated architecture.json and architecture.html, committed with the source change.
  Build: 0 errors. Plain dotnet test: 9 culture failures. LC_ALL=en_US.UTF-8 dotnet test: 7,286 passed.
  architecture.html: regenerated twice; output was identical.
  architecture.json: regenerated twice; output was identical.
  ErrorMessages.cs: kept localized mappings for every error added by main.
  Google auth tests: kept the copy assertion and sign-in retry checks. Commits: 65ff5f5d, d0573474. Build: 0 errors; EF: no pending changes. All 7,412 tests pass with LC_ALL=en_US.UTF-8; the default locale fails nine formatting tests.

Manual steps

None. Nothing outside the repository has to change for this pull request to take effect.
None.
None.

[pullfrog]

Run failed. View the logs →

  ^{｜ Rerun failed job ➔ ｜ View workflow run ｜ via Pullfrog ｜ Using GPT Sol ｜ 𝕏}

[pullfrog]

Run failed. View the logs →

  ^{｜ Rerun failed job ➔ ｜ View workflow run ｜ via Pullfrog ｜ Using GPT Sol ｜ 𝕏}

[pullfrog]

Run failed. View the logs →

  ^{｜ Rerun failed job ➔ ｜ View workflow run ｜ via Pullfrog ｜ Using GPT Sol ｜ 𝕏}

[thomasluizon]

Independent review at head dd862844: REQUEST CHANGES. This pull request had never been reviewed by anyone. Four findings are blocking: two ship a user-visible regression to production and one means the headline feature does nothing on Android.

Codex and Pullfrog share one exhausted OpenAI allowance until 2026-09-22, so a separate Claude agent reviewed this against the producing code in orbit-api and the consuming code in orbit-ui-mobile. Stating the substitution rather than hiding it: this is not a Pullfrog verdict, and protected main still needs pullfrog-approval before this can merge.

Copy findings

C1, CRITICAL: the deletion email says deletion is permanent, and the product deactivates

EmailCopy.cs now reads "You asked to delete your Orbit account. This cannot be undone. Your habits, history, conversations and settings are removed for good.", and the pt-BR twin says "Isso não pode ser desfeito. ... são apagados de vez."

The producing rule: ConfirmAccountDeletionCommand.cs:30-37 calls user.Deactivate(scheduledDate), where the date is the EARLIER of plan expiry plus seven days and now + AppConstants.MaxDeletionGraceDays, which is 30 at AppConstants.cs:47. User.cs:443-458 carries Deactivate and CancelDeactivation. Signing in cancels it, at VerifyCodeCommand.cs:105-110, GoogleAuthCommand.cs:140-144 and OAuthController.cs:233-243.

Somebody confirms deletion, reads "this cannot be undone", signs in three days later out of habit, and the account comes back with every habit intact. The mirror case is worse: somebody who wanted a real wipe believes it already happened while the row lives for up to 30 days.

This is the exact defect #71's acceptance criterion carries and that pull request 954 already corrected once in the app's own copy. The email must not reintroduce it. Say the grace window and the sign-in cancel, and read the number from AppConstants.MaxDeletionGraceDays rather than typing it.

C2, HIGH: the new INVALID_CODE_ATTEMPTS_REMAINING code breaks the step-up screen on both shipped clients

ErrorMessages.cs moves InvalidDeletionCode and InvalidApiKeyCreationCode off ErrorCodes.InvalidVerificationCode onto a new code, raised at EmailChallengeService.cs:137-142. Both shipped clients branch on the old value and have no branch for the new one:

• apps/mobile/app/step-up.tsx:197: if (errorCode !== 'INVALID_VERIFICATION_CODE') { setFieldError(t('stepUp.genericError')); setPhase('challenge'); return }
• apps/web/app/step-up/step-up-screen.tsx:162-177: the same shape, falling to t('genericError').
• packages/shared/src/utils/error-utils.ts:398 and auth-login.ts:11 map only INVALID_VERIFICATION_CODE, and the new code is absent from ERROR_CODE_TO_KEY at error-utils.ts:310-382.

The message FORMAT is load-bearing too and it also changed. packages/shared/src/utils/step-up.ts:117-123 parses the count with /remaining attempts:\s*(\d+)\s*$/i. The old string was "Invalid code. Remaining attempts: {0}"; the new one is "That code is not correct. You have {0} tries left." No match, so remaining is null.

So a wrong deletion code shows a generic error instead of "wrong code, 2 tries left", the wrong phase never renders, and the client-side exhaustion counter at step-up.tsx:202-208 never advances. That breaks users on live 1.3.31 the day this deploys, which is what the root CLAUDE.md append-only rule and .claude/rules/core.md rule 5 exist to prevent.

Either keep the existing code and add the attempts copy under it, or file the paired UI ticket that this one blocks and hold the change behind it. Do not ship the rename alone.

C3, HIGH: the localized copy never reaches the Android app at all

LocalizedErrorResultFilter.cs takes the language from the request header only, passing Request.Headers.AcceptLanguage.ToString() into LocaleHelper.IsPortuguese at LocaleHelper.cs:26-32.

Mobile sends no Accept-Language. apps/mobile/lib/api-client.ts:81-104 builds its header set from buildClientTimeZoneHeaders(), which returns only X-Orbit-Time-Zone (packages/shared/src/utils/client-context.ts:14-19), plus buildAppVersionHeaders(), Authorization, Content-Type and Idempotency-Key. So IsPortuguese("") is false and every pt-BR Android user gets English for all 222 codes, which is the exact defect ErrorCopy.cs's own header comment says this work exists to fix.

Web Server Actions send none either (apps/web/lib/server-fetch.ts:34-39), and apps/web/CLAUDE.md routes every mutation through a Server Action, so every create, update and delete error on web is English. Only the BFF catch-all forwards it, through apps/web/app/api/_utils/forwarded-client-context.ts:11-14. Even there the language is wrong for anyone who set the in-app locale, because apps/web/i18n/request.ts:9-14 prefers the i18n_locale cookie over the header.

It also contradicts the rest of the product, which keys off the stored user.Language in ResendEmailService and ProactiveCheckinSchedulerService.cs:146.

Resolve the locale from the authenticated user's Language, with the header as the anonymous-request fallback, and cover it with an integration test that a pt-BR user sending no Accept-Language gets pt-BR copy.

C4, HIGH: the slip-alert copy asserts a time pattern the scheduler contradicts

AiSlipAlertMessageService.cs now titles the push "Your usual time for {habit}" and bodies it "This is around the time it usually comes up."

SlipAlertSchedulerService.cs:136,168-171 computes CalculateAlertTime as Math.Clamp(peakHour.Value - 2, 8, 22), so it sends two hours before the peak. Even with a time pattern, the send time is by construction not the usual time. And SlipPattern.PeakHour is int? (SlipPattern.cs:6); when it is null the doc at SlipAlertSchedulerService.cs:165-167 says the push goes at 08:00, and the prompt the same service builds says literally "They tend to slip on {dayOfWeek}s (no specific time pattern)."

A Friday-only smoker with no hourly pattern gets an 08:00 lock-screen push titled "Your usual time for Smoking". Cover it with a fallback test at peakHour: null asserting the copy makes no time claim.

C5, MEDIUM: the check-in fallback says "A few habits" when one is the common case, and promises Astra will log the rest

AiProactiveCheckinMessageService.GenerateFallback now reads "A few habits are still open today. Pick the easiest one and Astra records the rest." ProactiveCheckinSchedulerService.cs:143-148 sends whenever offTrackTitles.Count != 0, so one open habit is common and the plural is then false. Second defect in the same sentence: nothing auto-logs a habit. LogHabitTool records only what the person names, so "Astra records the rest" promises behaviour that does not exist.

C6, MEDIUM: the new RATE_LIMITED copy is unreachable and the live 429 is still hardcoded English

ErrorMessages.TooManyRequests has zero call sites in src/; the only other reference anywhere is a test mock at OAuthControllerTests.cs:215. The real 429 body is written at DistributedRateLimitAttribute.cs:90-100 and :304-311 as an anonymous object with error = "Too many requests", and the filter only matches ObjectResult { Value: ErrorResponse }, so it cannot rewrite it. That file is not in this diff. Build the body from ErrorMessages.TooManyRequests.ToErrorBody().

C7, MEDIUM: the attempts copy is ungrammatical at exactly the values the code produces

EmailChallengeService.cs:79 computes Math.Max(0, AppConstants.MaxVerificationAttempts - attempts) with MaxVerificationAttempts = 3 at AppConstants.cs:43, so the only values anyone sees are 2, 1 and 0. The string renders "You have 1 tries left.", "You have 0 tries left." and "Você tem mais 1 tentativas." The replaced copy had no agreement to get wrong. At 0 the sentence also offers no next action, against the catalog's own stated rule.

C8, MEDIUM: the sync copy promises client behaviour neither client implements

"This device was offline too long to catch up. Orbit will load everything again." and "Orbit syncs {0} changes at a time. It will send the rest next." A grep for SYNC_WINDOW_EXCEEDED|TOO_MANY_MUTATIONS across all of orbit-ui-mobile returns no matches, and the sync endpoints at packages/shared/src/api/endpoints.ts:174-176 have no app caller. Nothing re-loads and nothing chunks and resends.

C9, LOW: CHALLENGE_CLOSED English is broken

"This challenge is no longer taking part." A challenge does not take part; participants do. The pt-BR beside it is correct and the replaced English was correct.

C10, LOW: the recap promise is conditional on push being on

"That month has not finished yet. Its recap arrives once it does." PeriodCloseNotificationService.cs:51-56 selects only users with a row in PushSubscriptions. With notifications off, nothing arrives.

Code findings

D1, HIGH: "the raw-message fallback stays unreachable" is false

ValidationExceptionHandler.cs:22-42 writes { type, status, requestId, errors } directly to the response as an IExceptionHandler. It never produces an ObjectResult, so the filter never sees it. There are 139 validator files and 285 WithMessage/AbstractValidator occurrences under src/Orbit.Application/**/Validators. Concrete instance: VerifyCodeCommandValidator.cs:19 ships "Code must be a 6-digit number" verbatim to a pt-BR user. Either route the validation handler through ErrorCopy too, or narrow the doc comment to what the code supports.

D2, HIGH: the rewrite silently disables the clients' message-text to i18n-key mapping

packages/shared/src/utils/error-utils.ts:252-282 and :300-305 map errors to i18n keys by matching the backend's ENGLISH SENTENCE, and codes absent from ERROR_CODE_TO_KEY depend on that match entirely.

Create a habit with an empty title: TITLE_REQUIRED plus "Give this a title." The rule at error-utils.ts:300 needs both 'title' and 'required', so no match, and TITLE_REQUIRED is absent from ERROR_CODE_TO_KEY, so a generic toast replaces habits.form.titleRequired. Before this pull request the message was "Title is required." and it matched. The same break hits UNIT_REQUIRED, TARGET_VALUE_INVALID, TAG_NAME_REQUIRED, DUPLICATE_SCHEDULED_REMINDERS, MAX_SCHEDULED_REMINDERS, MAX_HABITS_PER_GOAL, MAX_TAGS_PER_HABIT and GENERAL_HABIT_IS_BAD. And for any client that does receive Portuguese, every one of these rules fails, including those whose English still matches.

The paired UI ticket adds the missing ERROR_CODE_TO_KEY entries and deletes the text-matching rules. File it and block this on it, per the cross-repo rule.

D3, MEDIUM: the one prompt that caused this bug is excluded from the guard written for it

NotificationVoiceTests.EveryPromptSentToAModel covers AiSummaryService.SystemPrompt but not BuildSummaryPrompt, which stays private static. That user prompt is precisely the one this pull request strips doubled hyphens from. Make it internal static and add it to both theory sources.

D4, LOW: the catalog does not fail at startup, as its comment claims

ErrorMessages is a static class of static readonly fields, so its initializer runs lazily on first access. A missing entry becomes a TypeInitializationException on a live request, not a startup failure. ErrorCopyTests catches it in CI, so the risk is low and the comment is still wrong about the mechanism.

D5, LOW: AppError structural equality quietly became reference-based for formatted errors

AppError.cs now stores the params array as Args, and the record's generated Equals compares IReadOnlyList<object?> by reference, so MaxTagsPerHabit.Format(5).Equals(MaxTagsPerHabit.Format(5)) returns false where it used to return true. The new AnErrorWithoutArgumentsStaysEqualToItself covers only the empty case, so the case that broke is untested. No current caller compares whole AppErrors, so this is latent.

D6, LOW: IsPortuguese on a raw header ignores q-values

LocaleHelper.cs:31 is language.StartsWith("pt", OrdinalIgnoreCase) applied to the whole header value, so "pt;q=0.1,en;q=0.9" resolves to Portuguese although English is preferred. Narrow, but it is now the sole language input for all 222 strings.

The totality test, and the vacuous-test sweep

The reflection test exists and is not vacuous. ErrorCopyTests.EveryDeclaredErrorCodeHasCopy reflects over typeof(ErrorCodes).GetFields(Public|Static).Where(f => f.IsLiteral && f.FieldType == typeof(string)) and asserts every value is a key of ErrorCopy.All. It goes red if a new public const string lands without copy. Two siblings do the same over ErrorMessages and DomainErrors. What it proves is TOTALITY over the three catalogs, never reachability, and D1 and C6 are two whole response paths the catalog never touches.

None of the new tests is strictly vacuous, but three are change-detectors rather than defect-detectors: the three NotificationVoice contract tests each assert that a constant contains string literals copied out of that same constant, so only editing NotificationVoice.Rules turns them red. One is fragile rather than weak: EveryLocalizedEmailDiffersBetweenTheTwoLanguages pairs two independent reflection passes by list index, so it holds only while StringsOf returns properties in a stable order and would compare mismatched pairs if a copy record gained a property.

Verified clean, with the evidence

• Bare // comments: none. ^\+\s*//[^/] over the 5,577-line diff returns 0 matches; only /// XML doc was added, which orbit-api/CLAUDE.md:29 permits. This matters because ORBIT0001 does not run under the locally installed SDK.
• DateTime.UtcNow without ORBIT0004: none. ^\+.*DateTime\.UtcNow returns 0 matches.
• Em dash and en dash: none. ^\+.*[—–] returns 0 matches, and the three copy suites assert absence by code point rather than by embedding one. The pull request also removes the doubled hyphens from four prompts and two fallback bodies.
• "Orbit" and "Astra" are never translated. The pt-BR strings use "o Orbit" and "a Astra", an article rather than a translation.
• Locale completeness and placeholder symmetry are both complete. All 14 catalog groups and 222 entries were diffed against the 145 constants in ErrorCodes.cs plus the two this pull request adds; every {n} matches across both languages, and BothLanguagesTakeTheSamePlaceholders enforces it. The reverse hazard was checked too, a template with {0} raised with empty Args, and there is none: MaxDepthReached.Format(maxDepth) at MoveHabitParentCommand.cs:81 and CreateSubHabitCommand.cs:58 passes the limit rather than the current depth, so "Habits nest 5 levels deep" is correct.
• No response field is removed or retyped. ErrorResponse pins [JsonPropertyName("error")] and [JsonPropertyName("errorCode")] and marks Args [JsonIgnore], so the wire shape is byte-identical. The contract break in C2 is the VALUE of errorCode, not the shape.
• Naming, swallowed errors and dead code are all clean, and the pull request deletes some: EmailLayout.GradientHeader and the CanvasColor and GradientTopColor constants go with all six call sites and the two tests that covered them.

[pullfrog]

Run failed. View the logs →

  ^{｜ Rerun failed job ➔ ｜ View workflow run ｜ via Pullfrog ｜ Using GPT Sol ｜ 𝕏}

[pullfrog]

Run failed. View the logs →

  ^{｜ Rerun failed job ➔ ｜ View workflow run ｜ via Pullfrog ｜ Using GPT Sol ｜ 𝕏}

[pullfrog]

✅ No new issues found.

Reviewed changes I reviewed merge commit 642a50ef added after 63f77942 and checked it against the complete PR context.

• Merged current main: Integrated the upstream API key management authorization changes and regenerated architecture artifacts.
• Aligned bilingual challenge copy: Broadened API_KEY_CREATION_CHALLENGE_REQUIRED from creation-only wording to API key management wording, which now accurately covers listing, creating, and revoking keys.
• Verified the error catalog: The focused ErrorCopyTests run passed all 677 generated cases.

  ^{｜ View workflow run ｜ Using GPT Sol ｜ 𝕏}

[pullfrog]

✅ No new issues found.

Reviewed changes I reviewed the two commits added after the prior Pullfrog review at 642a50ef and checked them against the complete PR context.

• Merged current main: Integrated the latest base changes and regenerated the architecture artifacts without introducing feature-specific behavioral drift.
• Refactored locale weighting: Extracted Accept-Language quality parsing while preserving priority and header-order semantics, with focused coverage for weighted, refused, invalid, and parameterized entries.
• Simplified notification fallbacks: Replaced nested locale and state conditionals with tuple switch expressions and added exact coverage for the previously missing slip-alert combinations.
• Verified the delta: Focused runs passed 33 application tests and 22 infrastructure tests.

  ^{｜ View workflow run ｜ Using GPT Sol ｜ 𝕏}

[thomasluizon]

@pullfrog review

[pullfrog]

Important

The latest merge integration needs a workflow correction before merge. Two workflows cannot load, leaving the current PR check set incomplete.

Reviewed changes

I reviewed the commits added after the prior Pullfrog review at ddd45f23, then checked their integration against the complete PR diff.

• Branch integration: Merged current main and redesign/main, including their auth concurrency, recap, calendar projection, profile completion, agent confirmation, onboarding, streak, and support-intent changes.
• Error catalog coverage: Added localized recap, session, validation, and domain errors while retaining totality checks for public error codes.
• Merged test adaptations: Kept copy-specific assertions aligned across auth, calendar, gamification, onboarding, and profile tests.
• Generated architecture artifacts: Refreshed the JSON and HTML architecture views for the merged tree.
• Workflow triggers: Added redesign/main to the affected workflow triggers, with the merge-resolution defect called out inline.

  ^{｜ Fix all ➔ ｜ Fix 👍s ➔ ｜ View workflow run ｜ Using GPT Sol ｜ 𝕏}

[pullfrog]

Important

The current head still contains the duplicate top-level concurrency mappings already identified in the unresolved review thread. .github/workflows/dependency-review.yml and .github/workflows/sonarcloud.yml do not load into the current PR check set, so that workflow blocker remains; I found no additional high-severity application defect.

Reviewed changes I reviewed the complete PR at d0573474, including the latest base integrations and both producing and consuming sides of the localized-error contract.

• Transactional email redesign: Rebuilt seven bilingual email types and the shared layout around the current visual and voice rules.
• Localized API errors: Added a total bilingual error catalog, response-boundary localization, placeholder propagation, and stored-language resolution while preserving wire shape and established error-code values.
• AI notification copy: Centralized the notification voice contract and aligned generated and fallback proactive, slip-alert, and summary copy.
• Cross-repository compatibility: Confirmed orbit-ui-mobile PR #1026 is merged into its matching redesign/main branch and resolves the rewritten form errors by stable code rather than English-message matching.
• Verification: Focused localization and distributed-rate-limit tests exited successfully; all current required checks pass except Pullfrog approval, while Dependency Review and the SonarCloud workflow are absent because of the duplicate workflow keys.

  ^{｜ Fix it ➔ ｜ View workflow run ｜ Using GPT Sol ｜ 𝕏}

[pullfrog]

✅ No new issues found.

Reviewed changes I reviewed commit b44a829d, added after the prior Pullfrog review at d0573474, and checked it against the complete PR context.

• Restored workflow validity: Removed the duplicate top-level concurrency mappings from the Dependency Review and SonarCloud workflows, returning both files to their base versions.
• Confirmed workflow admission: Verified that each workflow now contains one concurrency mapping; Dependency Review passed and SonarCloud started on the current head.

  ^{｜ View workflow run ｜ Using GPT Sol ｜ 𝕏}

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
98.5% Coverage on New Code
0.1% Duplication on New Code

See analysis details on SonarQube Cloud