Destiny

---

What it is

Tasseography is a social ritual: you finish the coffee, turn the cup onto the saucer, wait for it to cool, and somebody who claims to know how tells you what is in the grounds. Destiny is that, on a phone, in about thirty seconds.

One screen to start on, then read → reveal → share, plus one in-voice state for when the cup cannot be read at all. The opening screen holds the whole setup: add one to four photographs of the same cup, pick what you are asking about, and say anything else in your own words.

No accounts, no database, no history. You get a reading and a card to send to someone, and that is the whole product.

How the reading works

Five roles in a chain, running as two model calls, and only one of them ever speaks to you.

you → Fortune Teller → The Eye → Searcher → Fortune Teller → you
           (the Fortune Teller's own call does the narrowing and the warmth)
         triage          shapes    meanings    three themes   warmth    the reading

The Fortune Teller is the character, and the only voice. Its first act is not to read the cup but to check on the person holding it: anything you typed is triaged for genuine distress before a fortune is ever built, running alongside the Eye so care costs nothing in wall-clock time. If it fires, the mystic voice stops entirely and you get a plain, warm human instead.

The Eye looks at the photographs and names what is visible, with a confidence for each shape and the region it sits in. Several photographs are read as one cup from several angles, never as several cups. It is the one agent allowed to be uncertain out loud, which is what lets everything downstream lean on a doubtful shape lightly rather than confidently.

The Searcher looks each shape up in a bundled symbol dictionary, 205 entries of traditional kahve falı meaning kept in docs/SYMBOLS.md. It is the one role that is not a model call: the dictionary ships with the app, so the lookup is instant, cannot fail, and every meaning in a reading is one you can point at in a file. A shape the list has never heard of comes back empty rather than stretched to fit a neighbouring entry.

The Context Queen picks exactly three themes from what is left, weighing relevance to your chosen focus, how connected the shapes are to each other, and how sure the Eye was. Three, never four.

The Fairy never writes a word you read. She hands the Fortune Teller a supportive throughline, a reframe per theme, and the closing line, leaning quietly on agency and self-compassion without ever naming them. She runs before the reading rather than after, because warmth applied afterwards reads as an apology.

Splitting them is what keeps the voice stable. A single call that both looks and writes drifts toward describing the photograph instead of reading the cup.

Six focuses: love, career, general, friendships, health and money. They change which way the same shapes are read, never the voice. Two are written defensively. Health is barred from naming a condition, diagnosing, predicting an illness or a recovery, or telling anyone to seek or avoid care. Money is barred from financial advice. A fortune teller can be wrong about a job; it should not be wrong about a diagnosis.

The whole thing is documented in docs/AGENTS.md, and the cards and knowledge base it was built from are vendored in docs/AGENT-CARDS.md and docs/KNOWLEDGE-BASE.md.

Where a shape falls changes what it means, and every agent that touches a shape speaks the same dialect:

Region	Reads as
rim	the present, happening now
middle	the near future, weeks to months
bottom	the past, home, deep feeling
handle	love, family, the people already close
right-of-handle	things entering your life
left-of-handle	things leaving, debts being paid

The Fortune Teller is a warm matriarch, in the lineage of a reader like Melahat: she pours out what she sees rather than analysing it, calls you canım, names the feeling behind a shape and then comforts it, and closes on a blessing. She takes one image and opens it deeply rather than listing five shallowly. canım is the only Turkish word she uses: no proverbs, no sayings, because the warmth has to come from the tone rather than from a foreign phrase dropped in for flavour. Her full spec is in docs/VOICE.md, along with the ten reference readings that serve as demo mode and as the regression bar.

Readers in that tradition also predict illness, inheritance and marriage as fact. Destiny takes the warmth and the rhetoric and leaves that behind: every image stays a possibility, and the prompt says so explicitly rather than hoping the model infers it.

Design

The app is built to a written design system, kept in the repo as docs/DESIGN-SYSTEM.md. It is the source of truth, and the build follows it rather than improvising around it.

The same system is built as a Figma library, so the tokens exist in both places and neither one is a screenshot of the other. Colour, spacing, radius, type and motion are Figma variables matching styles/tokens.css one to one; Colour carries a Light and a Dark mode. The component pages are Icon, Button, Chip, Topic tag, Card, Photo tile, Input bar, Chat bar, Tab bar and Meta & divider, plus the share card as an artefact. Each set carries its description in Figma, including the accessibility contract it has to be built to.

Warm and quiet. One warm neutral family from near-white to near-black plus a single espresso brown, and no accent hue at all. Emphasis comes from weight, size, and ink against espresso. styles/tokens.css is the system's :root block pasted verbatim; nothing downstream hardcodes a colour.

Type carries the personality, and it is split in two. Bricolage Grotesque SemiBold names things: the wordmark and the omen, and nothing else. IM Fell English — a digitisation of a 17th-century Oxford letterpress face — says them: every fortune, italic for the reading itself. A title is a label on a screen and a fortune is somebody talking, and giving both to one face made the app's own furniture sound like it was in character. Familjen Grotesk for interface and body, Fragment Mono for meta labels and the ASCII field.

The background is a coffee cup, drawn as a halftone of characters. It is a canvas, redrawn fifteen times a second, and the cup is not typed out: it is a field, geometry evaluated per cell with lighting, a specular band on the porcelain and crisp seams where two surfaces meet, and a ramp turns that field into characters. The sparse end of the ramp is a real dot sized by area, odd rows sit half a cell across, and the coffee and the steam shimmer between neighbouring glyphs the way a terminal redraw does. The cup itself holds still — a wobbling cup reads as a rendering fault, not atmosphere. On paper it prints like a halftone, lit side sparse and shaded side dense; on the dark theme it inverts, because there the ink is the light.

The technique comes from aquatic-cove and from an AsciiWake sketch. What is deliberately not taken is their interaction: AsciiWake drags a wake under the pointer and aquatic-cove disturbs its fluid on touch. This is decorative and inert — pointer-events: none, aria-hidden, and no pointer, mouse, touch, wheel, scroll or key listener in scripts/ascii.js, so nothing you do starts, stops, steers or speeds it. Under prefers-reduced-motion it draws one frame and stops.

Flat and still. No gradients, no drop shadows, no looping or ambient motion, no animated texture. Depth comes from the surface scale — paper, raised, sunken — not from effects. The optional paper grain ships switched off; set data-grain="on" on <html> to turn it on.

The 4px grid, without exception. Every padding, margin, gap and radius in styles/app.css is a --space-* or --radius-* token, so every one of them is divisible by four. Touch targets are at least 44px.

One calm column, held to 640px on desktop with 24 to 32px of screen padding. The system left-aligns by default; the opening screen is the one place that centres, because the wireframe does.

Motion answers actions. The one orchestrated moment is the reading: a quiet wait over --dur-ritual, in-voice lines replacing one another, a single finite hairline easing toward the edge — then the fortune unfolds block by block on --dur-slow. Nothing on any screen loops or drifts, and prefers-reduced-motion is honoured throughout.

Note on the brief. The product brief called for the reading moment to be a live animation of grounds settling and swirling. The design system rules out looping and ambient motion and says no canvas, so the wait is still: the cup is a flat mark, and the movement is in the language and in the unfolding of the reveal. The design system won, as it says it should.

Run it locally

git clone https://github.com/mymomcallsmeeylul/readmyweecup.git
cd readmyweecup
npm run dev            # http://localhost:3000

No install step and no dependencies — the dev server is a single file of Node standard library, and the app is plain HTML, CSS and ES modules.

It works with no API key. Without one, /api/read serves the reference readings and the reveal is labelled as a sample, which is enough to work on the design, the motion and the flow. For real readings:

cp .env.example .env   # then add your key

Variable	Required	Default
ANTHROPIC_API_KEY	for real readings	— (falls back to demo mode)
DESTINY_MODEL	no	claude-opus-5
EYE_MODEL … FORTUNE_TELLER_MODEL	no	DESTINY_MODEL
PIPELINE_BUDGET_MS	no	50000
PORT	no	3000

The key is only ever read inside api/read.js. The browser talks to that endpoint and nothing else, so nothing sensitive reaches the client — which matters, because this repo is public.

Deploy

Zero-config on Vercel: the root is static and api/read.js becomes a serverless function. Set ANTHROPIC_API_KEY in the project's environment variables.

npx vercel deploy --prod

Any host that serves static files and runs one Node function will do; the handler is a plain (req, res) function with no framework in it.

Layout

index.html               every screen, as markup
styles/tokens.css        the design system's :root, verbatim
styles/app.css           every screen, mobile first, all on the 4px grid
scripts/app.js           state machine, routing, share
scripts/sharecard.js     the 1080x1350 share card renderer
scripts/image.js         client-side resize and recompress before upload
scripts/icons.js         the Lucide icons the interface uses, inlined
scripts/ambient.js       synthesised ambient sound, off by default
scripts/ascii.js         the ASCII coffee cup: the field, the ramp, the halftone
scripts/logo.js          the mark's path data, for whatever draws it in script
logo.svg                 the mark: two dancers, traced to polygons
favicon.svg              one dancer, square, in the app's own colours
api/read.js              the endpoint: the pipeline, end to end
api/_house.js            what every agent inherits: house rules, cup geography
api/_client.js           the transport, the model routing, the wall clock
api/_dictionary.js       the 205 bundled symbols, generated from docs/SYMBOLS.md
api/_agents/             one module per agent, five of them
docs/SYMBOLS.md          the symbol dictionary, A–Z: the source for the above
api/_readings.js         the ten reference readings — demo mode and spec
tools/test-pipeline.mjs  the tests: npm test, no API key needed
docs/DESIGN-SYSTEM.md    the design system this build follows
docs/VOICE.md            the voice spec

Notes

Photos are resized to a 1280px long edge and recompressed in the browser before upload, so a 6MB camera JPEG leaves the phone as roughly 200KB. Four of them still land well inside the request limit.

Icons are Lucide, copied in as raw paths rather than pulled from a package: there is no build step, and four icons do not justify a dependency. An icon is never the accessible name of a control; the glyph is aria-hidden and the name comes from real text or an aria-label.

Every screen except the reveal is a fixed frame, so the action stays in view and the middle scrolls if a small phone runs out of room. Checked at 360×640 through 414×896 and out to desktop.

The system's derived night theme ships as tokens under [data-theme="dark"]. The reference is light-only, so there is no toggle in the UI; setting the attribute switches the whole app.

Licence

MIT — see LICENSE. Bricolage Grotesque, IM Fell English, Familjen Grotesk and Fragment Mono are loaded from Google Fonts and are licensed under the SIL OFL 1.1.