[No QA] Docs updates for E/A#99108 troubleshoot adding a work email during setup by MelvinBot · Pull Request #100633 · Expensify/App

MelvinBot · 2026-09-08T19:35:10Z

Explanation of Change

Help site follow-up for #99108, which added a new user-facing message to the account setup flow:

<work email> is a domain controlled login for an existing Expensify account.

Nothing under docs/articles documented the What’s your work email? step or the Couldn’t add work email screen, so there was no existing article to add a line to. This PR adds one article that covers that screen:

docs/articles/new-expensify/getting-started/Troubleshoot-Adding-Your-Work-Email.md

It explains what the new domain controlled login message means and what to do about it (sign in to the existing account, or ask a Domain Admin for access), covers the other messages that can appear on the same step (invalid or public domain, same as signup email, offline, existing 2FA account, existing SSO/SAML account, closed work account), and documents how to add the work email afterward as a contact method.

Written against docs/HELPSITE_NAMING_CONVENTIONS.md, docs/HELP_AUTHORING_GUIDELINES.md, and docs/TEMPLATE.md: one # title plus # FAQ, task-based ## headings only, no ###, relative cross-links, and a non-rendered  suggestion.

UI labels verified before writing:

Onboarding copy quoted verbatim from src/languages/en.ts on main — What’s your work email?, Add work email, Couldn’t add work email, the new domainControlledSubtitle string, and Got it (common.buttonConfirm).
The contact methods path was verified in the live web app: Account > Profile > Contact methods, then the New contact method button. There is no "Work email" field anywhere in account settings, so the article points members at contact methods rather than at a Settings work email field.
Only the domain controlled and generic failures reach the full-screen Couldn’t add work email state — the 2FA, SSO/SAML, and closed-account branches return before isMergingAccountBlocked is set and render under the input instead. The article reflects that split.

./.github/scripts/createDocsRoutes.sh passes with no routes diff.

Fixed Issues

$ #98996
PROPOSAL:

Tests

// TODO: The human co-author must fill out the tests they ran before marking this PR as "ready for review".

Verify that no errors appear in the JS console

Offline tests

Not applicable. This PR only adds a help site markdown article and changes no app code.

QA Steps

// TODO: The human co-author must fill out the QA steps before marking this PR as "ready for review", or the title must include "[No QA]."

Verify that no errors appear in the JS console

PR Author Checklist

Screenshots/Videos

Android: Native

Android: mWeb Chrome

iOS: Native

iOS: mWeb Safari

MacOS: Chrome / Safari

@abzokhattab, please review the files changed and confirm they reflect the current behavior. Then post a new comment saying @MelvinBot mark this PR as ready for review.

…ccount setup Co-authored-by: Abdelrahman Khattab <abzokhattab@users.noreply.github.com>

MelvinBot · 2026-09-08T19:35:35Z

I created this PR from an upstream branch since I don't have push access to your fork.

To take ownership of this branch and be able to push updates, run:

git remote add upstream https://github.com/Expensify/App.git
git fetch upstream claude-docsWorkEmailDomainControlled
git checkout -b claude-docsWorkEmailDomainControlled upstream/claude-docsWorkEmailDomainControlled
git push -u origin claude-docsWorkEmailDomainControlled

Then you can close this PR and open a new one from your fork.

abzokhattab · 2026-09-08T21:17:13Z

@MelvinBot mark the PR as ready

abzokhattab · 2026-09-08T21:18:04Z

Reviewer Checklist

I have verified the author checklist is complete (all boxes are checked off).
I verified the correct issue is linked in the ### Fixed Issues section above
I verified testing steps are clear and they cover the changes made in this PR
- I verified the steps for local testing are in the Tests section
- I verified the steps for Staging and/or Production testing are in the QA steps section
- I verified the steps cover any possible failure scenarios (i.e. verify an input displays the correct error message if the entered data is not correct)
- I turned off my network connection and tested it while offline to ensure it matches the expected behavior (i.e. verify the default avatar icon is displayed if app is offline)
I checked that screenshots or videos are included for tests on all platforms
I included screenshots or videos for tests on all platforms
I verified that the composer does not automatically focus or open the keyboard on mobile unless explicitly intended. This includes checking that returning the app from the background does not unexpectedly open the keyboard.
I verified tests pass on all platforms & I tested again on:
- Android: HybridApp
- Android: mWeb Chrome
- iOS: HybridApp
- iOS: mWeb Safari
- MacOS: Chrome / Safari
If there are any errors in the console that are unrelated to this PR, I either fixed them (preferred) or linked to where I reported them in Slack
I verified proper code patterns were followed (see Reviewing the code)
- I verified that comments were added to code that is not self explanatory
- I verified that any new or modified comments were clear, correct English, and explained "why" the code was doing something instead of only explaining "what" the code was doing.
- I verified any copy / text that was added to the app is grammatically correct in English. It adheres to proper capitalization guidelines (note: only the first word of header/labels should be capitalized), and is either coming verbatim from figma or has been approved by marketing (in order to get marketing approval, ask the Bug Zero team member to add the Waiting for copy label to the issue)
If a new code pattern is added I verified it was agreed to be used by multiple Expensify engineers
I verified that this PR follows the guidelines as stated in the Review Guidelines
I verified other components that can be impacted by these changes have been tested, and I retested again (i.e. if the PR modifies a shared library or component like Avatar, I verified the components using Avatar have been tested & I retested again)
If a new component is created I verified that:
- A similar component doesn't exist in the codebase
- All props are defined accurately
- The component has a clear name that is non-ambiguous and the purpose of the component can be inferred from the name alone
- The only data being stored in the state is data necessary for rendering and nothing else
- The component has the minimum amount of code necessary for its purpose, and it is broken down into smaller components in order to separate concerns and functions
If a new CSS style is added I verified that:
- A similar style doesn't already exist
- The style can't be created with an existing StyleUtils function (i.e. StyleUtils.getBackgroundAndBorderStyle(theme.componentBG)
If the PR modifies code that runs when editing or sending messages, I tested and verified there is no unexpected behavior for all supported markdown - URLs, single line code, code blocks, quotes, headings, bold, strikethrough, and italic.
If the PR modifies a generic component, I tested and verified that those changes do not break usages of that component in the rest of the App (i.e. if a shared library or component like Avatar is modified, I verified that Avatar is working as expected in all cases)
If the PR modifies a component related to any of the existing Storybook stories, I tested and verified all stories for that component are still working as expected.
If the PR modifies a component or page that can be accessed by a direct deeplink, I verified that the code functions as expected when the deeplink is used - from a logged in and logged out account.
If the PR modifies the UI (e.g. new buttons, new UI components, changing the padding/spacing/sizing, moving components, etc) or modifies the form input styles:
- I verified that all the inputs inside a form are aligned with each other.
- I added Design label and/or tagged @Expensify/design so the design team can review the changes.
For any bug fix or new feature in this PR, I verified that sufficient unit tests are included to prevent regressions in this flow.
If the main branch was merged into this PR after a review, I tested again and verified the outcome was still expected according to the Test steps.
I have checked off every checkbox in the PR reviewer checklist, including those that don't apply to this PR.

Screenshots/Videos

Android: HybridApp

Android: mWeb Chrome

iOS: HybridApp

iOS: mWeb Safari

MacOS: Chrome / Safari

melvin-bot · 2026-09-08T21:20:10Z

melvin-bot · 2026-09-08T21:20:12Z

@abzokhattab @greg-schroeder One of you needs to copy/paste the Reviewer Checklist from here into a new comment on this PR and complete it. If you have the K2 extension, you can simply click: [this button]

MelvinBot · 2026-09-08T21:20:14Z

🤖 Marked this PR as ready for review. PullerBear and stephanieelliott are the requested reviewers.

Two things I left for you, since I can't fill them in on your behalf:

Tests and QA Steps still contain the // TODO: placeholder text. Please replace them with what you actually ran, or — since this PR only adds one help site markdown file and no app code — add [No QA] to the PR title, which the template accepts in place of QA steps.
Author Checklist boxes are still mostly unchecked. Check the ones that apply to a docs-only change.

Check independent approval is failing, which is expected until a reviewer approves. All other checks pass (spellcheck, verify, validate, CLA).

view run · view recording

github-actions · 2026-09-08T21:22:28Z

HelpDot Documentation Review

Overall Assessment

This PR adds one new article, docs/articles/new-expensify/getting-started/Troubleshoot-Adding-Your-Work-Email.md, covering the "What's your work email?" step during new account setup, the messages shown when an email cannot be added, and how to add the email later as a contact method. It is a strong, well-scoped article that closely follows the HelpDot governance standards.

Scores Summary

Readability: 9/10 - Clear, scannable prose with logical progression from eligibility to error messages to resolution. Message-to-action bullet lists and numbered steps are easy to follow.
AI Readiness: 9/10 - Complete YAML frontmatter including a detailed internalScope with explicit exclusions. Task/question-based headings, full feature names, correct heading hierarchy (only # and ##, no ###), single primary workflow, and realistic search keywords.
Style Compliance: 8/10 - UI labels are bolded and quoted verbatim (Got it, Add work email, New contact method), buttons use Sentence case, and cross-links use descriptive anchor text with relative paths. Minor navigation-phrasing deviation noted below.

Key Findings

Single, tightly scoped workflow with an internalScope that clearly states what is and is not covered (excludes login troubleshooting, domain claiming, account merging) - excellent for retrieval precision.
Heading structure is fully compliant: exactly one # title plus the exempt FAQ heading, all sections use ##, and every heading is task- or question-based.
Error/system messages are quoted exactly and each paired with a concrete member action - very effective pattern.
Screenshot suggestion uses the correct non-rendered HTML comment format with a specific, confusion-preventing Purpose.
Cross-links (Domain Admins, Merge Accounts) are relative, descriptive, and reinforce the primary workflow without becoming a navigation hub.
Minor style nit: the navigation sentence reads "In the navigation tabs (on the left on web, and at the bottom on mobile)"; the canonical unified phrasing per HELPSITE_NAMING_CONVENTIONS.md is "(on the left on web, on the bottom on mobile)".

Recommendations

Align the navigation phrasing with the exact canonical unified sentence for consistency across HelpDot.
Otherwise no blocking issues. The article meets the Pre-Publish Validation Checklist.

Files Reviewed

docs/articles/new-expensify/getting-started/Troubleshoot-Adding-Your-Work-Email.md - New article, approved with one minor phrasing suggestion.

Note: Detailed line-by-line feedback has been provided as inline comments.

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 853587f059

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

rlinoz · 2026-09-09T11:31:35Z

@abzokhattab can you check/resolve the bot comments, please?

abzokhattab · 2026-09-09T11:32:29Z

@MelvinBot can you tackle the reviews

- Scope the work email step to public-domain signups - Document the supported verify + merge path for an ordinary existing account - Point optional users to Skip on the form, Got it only on the error screen - Allow retries after an inline validation error - Qualify the add-later-as-contact-method promise - Use the exact unified navigation sentence Co-authored-by: Abdelrahman Khattab <abzokhattab@users.noreply.github.com>

MelvinBot · 2026-09-09T11:48:22Z

🤖 Tackled all 6 review comments — pushed as 215db20 and replied in each thread.

All five Codex findings were correct. I verified each against the code before editing, and the naming-convention bot's navigation phrasing was a straight fix.

Review comment	Change
Navigation phrasing	Now the exact unified sentence — dropped the added "and" and "at the"
Limit to public-domain signups	Section is now Who sees the work email step; scoped to personal-address signups, and the intro says the same
Preserve the existing-account merge path	Deleted the blanket "can't already be a login" bullet; added a What happens if the address is already an Expensify login section covering the Verify your work email magic code and merge, then lists only the genuinely blocked cases
Qualify "add it later"	Intro now says "If the address isn't already a login on another Expensify account"; contact-methods caveat names the actual generic failure message instead of asserting a rule I couldn't verify
Point to Skip, not Got it	FAQ now sends optional users to Skip on the form and reserves Got it for the error screen
Allow retries	FAQ answer flipped to "Yes, while the work email step is still open"; the message list lead-in now says the form stays open

Code evidence for each claim

Public-domain gate — getOnboardingInitialPath() returns the work email route only under isUserFromPublicDomain at src/libs/actions/Welcome/OnboardingFlow.ts:138-140. Same gate in src/libs/getOnboardingStepCounter.ts:81-91.
Merge path is supported — the server sets shouldValidate, the screen routes to validation at BaseOnboardingWorkEmail.tsx:108-110, which calls MergeIntoAccountAndLogin at BaseOnboardingWorkEmailValidation.tsx:78-81. Covered by tests/ui/WorkEmailOnboarding.tsx:529-575.
Skip vs Got it — Skip renders in the form footer at BaseOnboardingWorkEmail.tsx:240-251; the form is swapped for OnboardingMergingAccountBlockedView only when isMergingAccountBlocked is set (lines 209-215), and Got it lives only in that view.
Retries work — the 2FA/SSO/closed branches return early before isMergingAccountBlocked is set (src/libs/actions/Session/index.ts:1664-1677), so the form stays mounted; the public domain / same-email / offline cases never leave validate().
Contact methods — DynamicNewContactMethodPage only blocks addresses already on your own account (lines 85-107). Any other rejection is backend-side and surfaces as the generic contacts.genericFailureMessages.addContactMethod string, so the article now names that message rather than stating a rule.

I could not verify the backend AddNewContactMethod behavior for a domain-controlled address from the App repo. The article describes what the member sees on failure instead of asserting whether the backend accepts it — worth a second look from someone with Auth access if you want that line to be firmer.

Checks run

./.github/scripts/createDocsRoutes.sh — "The docs routes files is up to date!", no routes diff.
npm run spell — no cspell issues in the article. (npm run spell-changed couldn't run: git merge-base fails against the shallow clone in this environment.)
No app code changed, so no lint, typecheck, or React Compiler run applies. Markdown only.

I made two edits beyond the literal comments, to keep the article internally consistent with the merge path: the Can I merge the existing account into my new account instead? FAQ now explains the merge only runs one way, and the internalScope frontmatter was rescoped to public-domain signups. Shout if you'd rather I revert either.

…rminology Co-authored-by: Abdelrahman Khattab <abzokhattab@users.noreply.github.com>

MelvinBot · 2026-09-09T11:56:08Z

🤖 Fixed and pushed — the check job passes now.

What was failing: the Check validateCode terminology step in the check job. The new help article used "magic code", which scripts/checkValidateCodeTerminology.sh blocks in any *.md file. User-facing copy must say "security code".

Fix: changed the one occurrence in docs/articles/new-expensify/getting-started/Troubleshoot-Adding-Your-Work-Email.md:26 to "security code", which also matches the app copy in src/languages/en.ts (welcomeEnterSecurityCode, enterSecurityCode).

Check independent approval is still red. That one just needs a human approval on the PR — nothing to fix in the code.

AI tests run locally

./scripts/checkValidateCodeTerminology.sh — ✅ pass
./.github/scripts/createDocsRoutes.sh — ✅ pass, no routes diff

Docs-only markdown change, so the JS/TS bundle (lint, typecheck, jest) doesn't apply. CI spellcheck passes on the new commit.

view run · no recording available

OSBotify · 2026-09-09T11:57:25Z

A preview of your ExpensifyHelp changes have been deployed to https://cf736825.helpdot.pages.dev ⚡️

Updated articles:

articles/new-expensify/getting-started/Troubleshoot-Adding-Your-Work-Email

Docs: add help article for the Couldn't add work email error during a…

853587f

…ccount setup Co-authored-by: Abdelrahman Khattab <abzokhattab@users.noreply.github.com>

MelvinBot assigned abzokhattab Sep 8, 2026

MelvinBot requested a review from a team September 8, 2026 19:35

MelvinBot added the HelpDot Apply this label if the issue relates to ExpensifyHelp label Sep 8, 2026

MelvinBot mentioned this pull request Sep 8, 2026

Show a specific error when adding a domain-controlled work email during onboarding #99108

Merged

40 tasks

MelvinBot marked this pull request as ready for review September 8, 2026 21:20

MelvinBot requested a review from stephanieelliott as a code owner September 8, 2026 21:20

melvin-bot Bot requested review from abzokhattab and greg-schroeder September 8, 2026 21:20

melvin-bot Bot removed the request for review from a team September 8, 2026 21:20

abzokhattab approved these changes Sep 8, 2026

View reviewed changes

melvin-bot Bot requested a review from rlinoz September 8, 2026 21:21

github-actions Bot reviewed Sep 8, 2026

View reviewed changes

Comment thread docs/articles/new-expensify/getting-started/Troubleshoot-Adding-Your-Work-Email.md Outdated

chatgpt-codex-connector Bot reviewed Sep 8, 2026

View reviewed changes

github-actions Bot changed the title ~~Docs updates for E/A#99108 troubleshoot adding a work email during setup~~ [No QA] Docs updates for E/A#99108 troubleshoot adding a work email during setup Sep 9, 2026

This comment has been minimized.

Sign in to view

Docs: use 'security code' instead of 'magic code' per validateCode te…

24309fb

…rminology Co-authored-by: Abdelrahman Khattab <abzokhattab@users.noreply.github.com>

rlinoz approved these changes Sep 9, 2026

View reviewed changes

Uh oh!

Conversation

MelvinBot commented Sep 8, 2026

Explanation of Change

Fixed Issues

Tests

Offline tests

QA Steps

PR Author Checklist

Screenshots/Videos

Uh oh!

MelvinBot commented Sep 8, 2026

Uh oh!

abzokhattab commented Sep 8, 2026

Uh oh!

abzokhattab commented Sep 8, 2026

Reviewer Checklist

Screenshots/Videos

Uh oh!

melvin-bot Bot commented Sep 8, 2026

Concierge reviewer checklist:

Uh oh!

melvin-bot Bot commented Sep 8, 2026

Uh oh!

MelvinBot commented Sep 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

github-actions Bot commented Sep 8, 2026

HelpDot Documentation Review

Overall Assessment

Scores Summary

Key Findings

Recommendations

Files Reviewed

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

rlinoz commented Sep 9, 2026

Uh oh!

abzokhattab commented Sep 9, 2026

Uh oh!

MelvinBot commented Sep 9, 2026

Uh oh!

This comment has been minimized.

MelvinBot commented Sep 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

OSBotify commented Sep 9, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

MelvinBot commented Sep 8, 2026 •

edited

Loading

MelvinBot commented Sep 9, 2026 •

edited

Loading