Controlled Execution.
Analyze repository health with Continuous Maintenance. Start new missions in New Mission. Iterate, review the PRD & Engineering Design, and progress existing projects in Replicant before deploying to production.
https://api.stripe.com/v1
https://api.openai.com/v1
https://auth.internal.karya.sh
https://api.sendgrid.com/v3
https://billing.internal.karya.sh
debug
default: info
postgres://app@db-staging.karya.sh:5432/platform
Karya is reading the replica conversation and producing a structured PRD and Engineering Design with milestones, CUJs, and approval gates. This usually takes 20–40 seconds.
Editable account settings
| Field | Value |
|---|---|
| ID | BuildPRD-07 |
| Owner | Accounts |
| Created | 2026-08-19 |
| Last updated | 2026-08-27 |
1Problem
The Account Settings drawer is read-only. A broker who changes firm, takes a new title, or moves to a new email address cannot fix it themselves — they contact support, who edits the record by hand. That was 214 tickets last quarter, each averaging 26 hours to resolution, and each one a person with production access changing someone else's details.
It matters now because the profile is what clients see. A broker whose title is stale on every listing card and outbound email is misrepresented to their own customers for as long as the ticket sits in the queue.
2Users
- Broker: keeping their own details current. Done means the change is saved and visible everywhere their profile appears, without asking anyone.
- Broker on an SSO-managed account: the same, except some details are not theirs to change. Done means knowing which, and why, without trying and failing.
- Support operator: resolving the tickets that remain. Done means not being the mechanism by which routine details get changed.
3Scope
In scope
- A user SHALL be able to change their own name, title and phone number and see it take effect.
- A user SHALL be able to change their email address, with the new address proven to be theirs before it takes over.
- A user SHALL be told when a save fails, and SHALL NOT be left believing a failed change was saved.
- A user SHALL see their change reflected everywhere their profile is shown, not only in the drawer.
- A user on an SSO-managed account SHALL be told which details their organization controls.
- Every change SHALL be attributable, so support can answer what changed and when.
Out of scope
- This change SHALL NOT add avatar upload. Profile photos follow with the media work.
- This change SHALL NOT touch passwords or multi-factor settings — those already live in the security tab.
- This change SHALL NOT let anyone edit another user's profile, including support and admins.
- This change SHALL NOT make organization-level details editable — firm name and licence number are owned by billing.
- This change SHALL NOT rewrite the sender name on emails already sent.
4Terminology
- Profile: the details in the Account Settings drawer that identify a person to colleagues and clients — name, title, email, phone.
- Managed field: a profile detail an SSO organization controls, which the user cannot change here.
- Pending email: a new address the user has entered but not yet proven is theirs. Not yet in use.
- Surface: anywhere the profile is shown to someone — the header, listing cards, client emails, signature blocks, the directory.
5User stories
US1 — Correct my own details (P1)
As a broker, I want to change my name, title or phone number myself, so that clients and colleagues see who I actually am today.
Independent test: a reviewer opens the drawer, changes a title, saves, reloads, and finds the new title in the drawer, in the header and in the directory — with no other story shipped.
US2 — Move to a new email address (P1)
As a broker, I want to change the address I sign in with, so that I keep access after changing firm.
Independent test: a reviewer enters a new address, confirms the old one still signs in and still receives mail, proves ownership of the new one, and then confirms the new one signs in and the old one does not.
US3 — Know when a save did not happen (P1)
As a broker, I want to be told plainly if my change was not saved, so that I do not walk away believing a stale profile is correct.
Independent test: a reviewer saves while the write cannot complete, and sees the drawer return to its previous values with an error and their typing intact.
US4 — Understand what I cannot change (P2)
As a broker on an SSO-managed account, I want to see which details my organization controls, so that I ask the right person instead of trying repeatedly.
Independent test: a reviewer on a managed account opens the drawer and finds those details not editable, naming who controls them.
US5 — Answer what changed (P2)
As a support operator, I want to see a user's change history, so that I can answer "who changed my title" without production access.
Independent test: a reviewer makes two changes as a user, then finds both — with who and when — from the support view.
6Requirements
REQ-ACC-001: Self-service profile change
User story: US1
Statement: A user SHALL be able to change their own name, title and phone number without assistance.
Acceptance criteria
- AC-ACC-001.1: When a user saves a valid change, the system SHALL confirm it on screen and show the new value after a reload.
- AC-ACC-001.2: If a value is not usable — an empty name, an unusable phone number — the system SHALL reject the save, say which detail and why, and keep what the user typed.
- AC-ACC-001.3: While a user has unsaved changes, the system SHALL NOT discard them without telling them.
REQ-ACC-002: Email change is proven before it takes effect
User story: US2
Statement: A new email address SHALL NOT take over the account until the user has proven it is theirs.
Acceptance criteria
- AC-ACC-002.1: When a user enters a new address, the system SHALL show it as pending and state that nothing has changed yet.
- AC-ACC-002.2: While an address is pending, the system SHALL continue to accept the existing address for sign-in and continue sending to it.
- AC-ACC-002.3: When the user proves ownership, the system SHALL move the account to the new address and tell the old one that it happened.
- AC-ACC-002.4: If the address is already in use by another account, the system SHALL reject it without revealing whose it is.
- AC-ACC-002.5: If ownership is not proven within the stated window, the system SHALL discard the pending address and leave the account untouched.
- Given a user with a pending email address
- When they open the drawer again
- Then they see which address is pending, that it is not yet active, and how to resend or cancel it
REQ-ACC-003: A failed save is never mistaken for a successful one
User story: US3
Statement: The system SHALL NOT present an unsaved change as saved.
Acceptance criteria
- AC-ACC-003.1: If a save cannot complete, the system SHALL restore the previously saved values on screen and say the change was not saved.
- AC-ACC-003.2: If a save cannot complete, the system SHALL keep the user's entry so they can retry without retyping.
- AC-ACC-003.3: If the profile changed elsewhere since the user opened it, the system SHALL say so rather than silently overwriting the newer values.
- AC-ACC-003.4: The system SHALL NOT save some details of a change and not others.
REQ-ACC-004: A change is visible everywhere the profile is
User story: US1
Statement: A saved change SHALL be reflected on every surface that shows the profile.
Acceptance criteria
- AC-ACC-004.1: When a change is saved, the system SHALL show the new value in the header, on listing cards, in signature blocks and in the company directory without the user reloading or signing out.
- AC-ACC-004.2: The system SHALL NOT leave one surface showing the old value while another shows the new one.
REQ-ACC-005: Managed details are visibly not editable
User story: US4
Statement: Where an organization controls a detail, the system SHALL say so rather than offering an edit that will not hold.
Acceptance criteria
- AC-ACC-005.1: When a managed account opens the drawer, the system SHALL present the managed details as not editable and name who controls them.
- AC-ACC-005.2: The system SHALL NOT accept a change to a managed detail through any route in this experience.
- AC-ACC-005.3: The system SHALL still allow the user to change the details their organization does not control.
REQ-ACC-006: Every change is attributable
User story: US5
Statement: Each change to a profile detail SHALL be recorded with who made it and when, and SHALL be readable by support.
Acceptance criteria
- AC-ACC-006.1: When a change is saved, the system SHALL record which detail changed, its previous and new value, who changed it and when.
- AC-ACC-006.2: When support opens a user's history, the system SHALL show those records most recent first.
- AC-ACC-006.3: The system SHALL NOT allow that history to be edited or deleted from this experience.
7Edge cases
- If a user requests a second email change while one is pending, the system SHALL replace the pending address rather than hold two.
- If a user's account becomes SSO-managed while they have unsaved changes to a now-managed detail, the system SHALL discard those changes and explain why.
- If a user changes their name while a client email is being composed, the system SHALL use whichever name is current when it sends.
- If a user proves ownership of a pending address from a different device or browser, the change SHALL still take effect.
- If the same profile is open in two places, the second save SHALL be told the profile changed rather than winning silently.
8Success criteria
- SC-001: Profile-edit support tickets fall below 20 a quarter, from 214.
- SC-002: A user completes a profile change in under a minute, unaided, in 9 of 10 observed attempts.
- SC-003: Fewer than 1 in 200 attempted saves end without the user knowing whether it worked.
- SC-004: No user reports losing access to their account through an email change in the first quarter.
- SC-005: No support ticket in the first quarter reports a stale profile on one surface after a successful save.
9Product constraints
- The experience SHALL meet WCAG 2.2 AA, including error messages and the pending-email state.
- The user SHALL see confirmation that a change was saved, or that it was not, before they leave the page.
- The system SHALL notify the previous email address whenever the account's address changes.
- The system SHALL keep no profile values beyond what the change history requires to answer what changed and when.
- Support SHALL be able to read a user's change history without being able to change the profile.
10Assumptions
- Users change these details rarely — a handful of times a year — if wrong, the case for rate-limiting and cooling-off periods gets much stronger.
- Name, title, email and phone are the whole set worth making editable now — if wrong, we ship a drawer that still sends people to support.
- An email change does not need to sign the user out elsewhere — if wrong, this becomes a security change as much as a convenience one, and Q1 answers it.
- Support keeps its manual edit as a fallback until this is fully rolled out — if wrong, there is no path for the cases this does not cover.
- Clients care about the current profile, not the one at the time of sending — if wrong, historical emails need to keep the old name.
11Open questions
Every question here must be answered before this can go to build. Karya will not guess a product decision.
| ID | Question | |
|---|---|---|
| Q1 | Does an email change end the user's other sessions, or only require re-verification? Security prefers ending them. |
|
| Q2 | Do we need a waiting period before a second email change, to blunt account takeover? |
|
| Q3 | Should a name change appear on emails already sent, or only future ones? |
|
| Q4 | How long may a pending email address stay pending before it is discarded? |
Editable account settings — Engineering Design
How the edit path is built: the write endpoint, the optimistic lock on the user record, the propagation fan-out, and the audit trail.
1Architecture Overview
The web client owns a draft copy of the profile. On save it applies the draft locally, calls PATCH /v1/account, and either confirms with the row the server returns or rolls back to the snapshot it took. user-svc performs the write, refreshes session claims, and upserts the directory inside one transaction, then emits profile.updated.
- LightBox Live (web) — editable drawer, dirty-state guard, optimistic store mutation, cross-tab broadcast.
- user-svc — validation, optimistic lock on
users.rev, session claim refresh, directory upsert, audit record. - auth-gateway — re-issues claims so the header and API tokens carry the new name and email.
- directory-tq — fans out cache invalidation to the six read paths that render a profile.
2Write Path & Concurrency
Every profile row carries a monotonic rev. The client sends the rev it read; the update matches on it. A mismatch means someone else saved first, so the write is rejected rather than silently overwriting — surfaced to the user as "this profile changed elsewhere" with a reload action.
3Save Sequence
The order matters: the local store moves first so the UI never feels laggy, and the rollback path restores the exact snapshot rather than re-fetching. Everything between BEGIN and COMMIT is one transaction — a failure at any step leaves no partial profile.
- Field edit marks the draft dirty; the header, avatar and profile block re-render from the draft immediately.
- Save snapshots the committed profile, applies the draft, then issues the PATCH with the snapshot's rev.
- On success: the returned row replaces the draft, a success toast confirms the write, and the drawer closes.
- On failure: the snapshot is restored, the drawer stays open and dirty, and the error names the field at fault.
- A
profile.updatedbroadcast keeps other open tabs in step without a refetch.
4Client State Machine
The drawer is a five-state machine held in the client store. Only saving holds a request in flight, and only pristine allows the drawer to close without a confirm — the dirty-state guard reads directly off this state rather than diffing fields.
rejected returns to dirty with the offending field named, and conflict reloads the server row before returning to pristine. There is no state in which the drawer is closed with unsaved edits.5Data Model
One forward migration on users, plus an append-only audit table. The backfill copies the legacy job_title column into title and runs on the replica first — 4,218 rows, 3.4s.
6Permissions & Verification
Editing your own profile needs the account:write scope, which every session already carries. Two cases narrow it:
- SSO-managed accounts — name and email are owned by the identity provider. user-svc rejects writes to those fields, and the client renders them locked with the provider named, rather than letting a save fail.
- Email changes — the new address is stored as pending and only becomes the login identity once the verification token is redeemed. The old address keeps working until then, and repeat changes are rate-limited.
Everything else — title, phone — commits directly. Each committed field writes a profile_audit row naming the actor, so an admin acting on a user's behalf is distinguishable from the user acting on their own.
Software Capitalization.
Classify development spend against ASC 350-40 / IAS 38. Karya maps Build milestones and Linear issues to GAAP phases — preliminary (expense), application development (capitalize), and post-implementation (expense) — and syncs the treatment back to Linear for your accountants.
| Issue / milestone | Source | GAAP phase | Treatment | Hours | Amount |
|---|---|---|---|---|---|
| KAR-412Account Settings · M2 Delivery | Build | Application dev | Capitalize | 284h | $42,600 |
| KAR-398Billing v2 · Schema & contracts | Linear | Application dev | Capitalize | 196h | $29,400 |
| KAR-441Auth platform · SSO + magic-link | Linear | Application dev | Capitalize | 178h | $26,700 |
| KAR-381Market research · push channel providers | Linear | Preliminary | Expense | 92h | $13,800 |
| KAR-455Account Settings · M1 Schema | Build | Application dev | Capitalize | 168h | $25,200 |
| KAR-402Bug fixes · post-launch notifications | Linear | Post-implementation | Expense | 144h | $21,600 |
| KAR-419Team training · Temporal workflows | Linear | Post-implementation | Expense | 88h | $13,200 |
| KAR-467Data pipeline · stream processing | Build | Application dev | Capitalize | 224h | $33,600 |
| KAR-374Feasibility study · real-time analytics | Linear | Preliminary | Expense | 136h | $20,400 |
User Journeys.
Every traversable flow Karya has discovered in your application — recorded from real sessions, replayed as canonical step sequences. Expand any journey to inspect the screens, the user actions, and the captured frame at each step.
Progress this replica to a Blueprint?
Karya will distill the replica conversation into a structured PRD + Engineering Design with milestones, CUJs, and approval gates. The replica stays available for further iteration — progression creates a new Blueprint version.
Hand Auth Flow off to Build?
The Build agent will compile the Blueprint into a milestone DAG and stage it in the project workspace. Nothing executes until you press Start. You'll review the plan, select a model, and see estimated timelines and cost before execution.