# Gift Graph UX Map Every surface, flow, and state below is live in v0.7.4, published 2026-10-19. The repo's `docs/ux-map.md` is canonical, and this note mirrors it. ## Surfaces | Surface | What it shows | What a person does there | | --- | --- | --- | | The public home | "Your agent whispers Hints. Your friends bring the surprise.", Mira's journal as the example Idea, and the sign-up box for people and their agents | Signs up or opens See the Demo | | The Ideas tab, `/owner` | A folder tab with the twin spark and a count, Whisper, ask strips with Answer, the filters, and tiles by newest change | Filters by All · Shared Secrets · Shared Hints · Shared with · Category · For · Unshared, and clears with the X | | The Connections tab, `/owner/connections` | Its folder tab, ask strips, then rows by depth, the invite links, and Paused last, with Ask by email and Invite | Declines a request or lets the person hear Hints, answers an ask with Not now or Share it, and taps a row open | | The idea tile | The label, the Hint after the bulb, the Secret after the teal gift or the grey lock, and a foot of initials | Hovers an initial for the name, taps the lock to share the Secret, edits with the pencil, and unshares with the mute ring | | The open tile | The tile at full width, the people as rows, Share with someone else, and Edit and Unshare | Widens a person's icon into Hears Secret · Hears Hint · Hears Nothing, and on a shared Secret picks Revoke the Secret or Unshare the Idea | | The Whisper and Edit sheet | The Hint, a label from three suggestions, the optional Secret with its Share or Keep icon, Tag for a Connection, and Who hears this Idea | Whispers or saves the Idea; a widening opens the review, and every Unshare asks first, with Undo after | | The open Connection row | "Justin hears" with Secrets · Hints, Pause or Resume, Remove, and the Ideas for Justin, then Hearing from Justin | Changes the depth, pauses, removes, or stops hearing | | The Hearing panel | Justin's birthday, then his Hints and Secrets in panels of their own | Captures an Idea from a line into a sheet tagged for Justin, asks to hear a Secret, or copies Ask your agent | | Invite | A required name, Secret or Hint, 1, 7, or 14 days, and a checkbox before a Secret invite | Makes the link on the page or through the agent, copies it once, and later picks New link or Revoke | | Ask by email | "Ask to hear someone", by the email the person signs in with | Sends the request, and the toast reads the same whether or not an account matches | | The demo, at `/demo` | "What Theo's agent hears", a three-line story, Mira's Ideas as tiles, and Theo's four questions | Sets Theo to Secrets or Hints, changes one Idea, adds one, and resets | | Your Profile, at `/account` | The name, the account ID, the sign-in email with Clerk's settings, a sealed address in Beta, the Birthday, and Your agents | Sets the name, seals a birthday, rotates or disconnects an agent, and deletes the account behind a typed confirmation | | Connect an agent | The Your agents strip, a sheet with Claude · Codex · Other, a token path, and the consent page | Allows the agent or picks Not now | | The page for agents | `/mcp` opened in a browser, with the tools listed from the server | Reads how to connect | ## The agent's flows | Flow | Calls | The owner's agent | The hearer's agent | | --- | --- | --- | --- | | Session start | The instructions and `help` | The account line, the people it hears, and the notice first | The same, with the founder named | | Whisper an Idea | `whisper` with `hint`, `secret`, labels, and `shares` | `show` opens on Idea; a request is the yes, and a preview that reaches further asks first | The Hint, or the Secret where the depth allows | | A gift for someone else | `whisper` with `for` | The name check asks when a Connection is named with no `for`, and the save goes ahead | Nothing, since no one hears a tagged Idea | | Hear | `hear` | Nothing | Every Idea the asker may hear, ranked, each with a ref, `level`, and `shared`, plus the birthday and the notice | | Ask to hear | `ask_to_hear` by ref | The ask under Waiting on you, answered by `share_secret` with its `requestId` | Three a day, and nothing on Not now | | Share with one person | `share_secret` and `unshare_secret` | A preview above the usual depth; a share at the usual depth is dropped | More or less of one Idea, marked `shared` | | Revoke the Secret | `update_secret` with `hintOnly`, and the shares at Secret lifted | Applies at once | The Hint, as each depth allows | | Unshare and Share again | `hush_secret`, and `update_secret` with `restore` | Unshare applies at once, and Share again previews | The Idea leaves `hear`, and what was heard stays heard | | Request to connect | `request_connection` by `ownerId` or `email` | The request in the notice and on Connections | One answer either way, and fourteen days for someone not yet on Gift Graph | | Approve and set the depth | `approve_connection`, `set_level`, and `list_connections` | A preview when Ideas exist, then `reverse` with the offer to ask back; `silent` is refused | Secrets or Hints | | Pause, resume, decline, remove | `connection` with an action | Resume previews what came in while paused, and a removal clears shares and asks | Nothing while paused, and a decline that reads as waiting | | Invite | `invite` with create, list, revoke, or accept | A named link, a preview, and the link shown once | `/i/<code>`, one button, and the share-back offered | | What waits | The notice and `whats-waiting` | Every open request and ask, with the call and the IDs that answer it | Since last time, four kinds of news said once | | What is coming up | `whats-coming-up` | Nothing | Birthdays in the next thirty days with what each person whispered, read-only | ## Inflection points | Date | The turn | What it changed | | --- | --- | --- | | 2026-10-19 · v0.7.4 | Hearing with Capture an Idea, the twin spark, the name check, `whats-waiting`, and the demo rebuilt | A friend's line becomes an Idea in one tap, and a gift for someone else stays Unshared | | 2026-10-19 · v0.7.3 | Two pages under folder tabs, one share control, Unshare, Revoke the Secret, and the Light theme | A one-off lives only while it differs from the depth | | 2026-10-18 · v0.7.2 | The Hint as the entry (017), no level on an Idea (018), the request as the yes, and the home on one page | Silent leaves the Connection, Pause is the nothing, and BUG-028 closes at the root | | 2026-10-17 | Depth words over trust words, and the Idea as the object | A Hint alone becomes a whole Idea | | 2026-10-16 | The form asks backwards, and Justin's camping case has no Secret | A Secret-level whisper failed on a hidden Hint field (BUG-028) | | 2026-10-14 | A birthday with no year, and one domain | The hear path opens a sealed field | | 2026-10-10 | Tags and rings, and tools grouped as actions | A status stops reading as a button, and fifteen tools remain | | 2026-10-09 | Shares and asks, and Your account | The one-off gets a table, and the address a seal | | 2026-10-08 | One account per person | A second domain no longer splits a person | | 2026-10-07 | Teal ember, whisper and hear, and sign-ups only | Every agent reconnects once for the new names | | 2026-10-06 | One surface answers one question | The two-column connection card retires | | 2026-10-05 | Gift Graph's own OAuth, and Hush | Each agent is a row, and a hushed secret returns through review | | 2026-10-04 | Secret as the noun, the web app first, the handoff as reference, and Neon | Embeddings and the drafter wait, and database work moves to my machine | | 2026-10-03 | The agent as the front door, a self-migrating start, three levels, and surprise-safe retired | Category stops leaking the ham | | 2026-10-01 | Owner-wide secrets with a preview | A widening previews before it applies | | 2026-09-30 | A written brief, with Replit Agent building from it | Scope settles before any code | ## States of an Idea and a person | State | Of | How it reads | | --- | --- | --- | | Shared Secret | an Idea | The Secret after the teal gift, with the initials of everyone who hears it | | Shared Hint | an Idea | The Hint after the ember bulb, with the initials of everyone who hears it | | Unshared Secret | an Idea | The Secret after the grey lock, "Unshared Secret · Click to share", while the Hint is heard | | Hint, no Secret | an Idea | No Secret line, and every hearer sits at the bulb | | Unshared | an Idea | The muted speaker, under the Unshared filter, with Share again | | For Justin | an Idea | The band "For Justin", a still lock, no "+", and "Idea for Justin · Unshared" when the tile opens | | 1 Hidden | an Idea and a person | The person off the tile's foot, and the tag on the person's row | | Hears Secrets | a person | A teal fill and the Secrets tag | | Hears Hints | a person | An ember fill and the Hints tag | | 1 Secret | a person who hears Hints | The tag in teal on the row, the gift by the initial on that tile, and no mark that says one-off | | Paused | a person | A grey fill, one quiet Paused label before the rows, and "Paused · hears nothing" on a tile; Paused by Theo when Theo paused | | Asked | a person | A grey fill and the strip "Priya asked to hear your Ideas" | | Asked to hear a Secret | a person and an Idea | "Justin asked to hear a Secret" with Not now and Share it, and Answer on Ideas | | Declined · Removed | a person | A tag; a declined request still reads as waiting to the asker | | Does not hear you yet | a person | "Let Mira hear Hints" in ember on the open row | | Founder | a person | The Founder tag with its spark, and "One way · Aleks hears no one" when the row opens | | Will hear Hints | an invite link | "Cal · will hear Hints" over "Waiting to be opened · 12 days left" |