E.D.I.T.H.
A deterministic-first companion that answers from published facts, tours the OS and acts on it.

E.D.I.T.H. is the pixel-art companion inside Portfolio OS 2026: grounded answers with sources, Mind reasoning over published projects, guided tours, screen awareness, music control, safe OS control with one-use tickets and Undo, a Hands-on mode where she walks to an icon and clicks it, a detached chat and a character with a life of her own.
- TypeScript
- React
- Next.js
- Zod
- Express
- Playwright
- AI
Overview
What she is
E.D.I.T.H. is the companion character that lives inside Portfolio OS 2026. She is a pixel-art figure who can be summoned from the menu bar or with Alt/Option+Shift+E, who drops in unannounced now and then, and who answers questions about Rishit's published work, gives guided tours, explains the screen you are looking at, plays music, changes OS settings and, in Hands-on mode, walks to an app icon on the screen and clicks it herself.
She is deliberately not a chatbot wrapped around a language model. Her answers come from a deterministic pipeline over published portfolio facts, every claim cites a source, and the one optional language-model fallback is off by default. The character is fan-inspired (the name nods to a Marvel AI); the art is drawn from the owner's own supplied files and the code is original.
Why she exists
- A portfolio full of apps needs a guide: a way to ask 'what has he built?' or 'show me the Kafka work' without reading everything.
- And she is a character. Owner-supplied reference material (a character bible, lore, personality, voice and relationships documents) defines who she is, so even her idle moments (coffee, reading, headphones, a gamepad, a bed at night) follow a written personality.
Where she lives
- packages/edith (@repo/edith): contracts, a transport-neutral API handler, the deterministic conversation engine, the Mind reasoning layer, the fuzzy matcher, the guide engine, the presence state machine and the sprite data.
- apps/desktop: the Messages app, the lazy companion host, hands-on mode, the guided-tour UI, the detached chat, the Settings pane, and the capability kernel that lets her change settings.
- A separate CMS global, the E.D.I.T.H. Studio, where the owner edits her extra lines and entrance mix.
Research and design effort
How the character, the pipeline and the safety model were researched and decided.
A paper trail before the code
The work started with a written plan rather than a prototype. The repository holds an architecture decision register, an architecture plan, a phases plan, a cost-and-risks note, an open-items list, nine specifications and an owner-supplied reference set.
- Decision register: packages/edith/plans/DECISIONS.md records 91 numbered decisions (D01 to D89 plus DA1 and DA2) and was edited in 15 commits between 2026-11-15 and 2026-11-17.
- Plans (5 files): ARCHITECTURE, COST_AND_RISKS, DECISIONS, OPEN_ITEMS, PHASES.
- Specs (9 files): API and data contracts, Arcade E.D.I.T.H. Picks, conversation and memory, knowledge and guides, OS integration, QA and acceptance, safety and permissions, UX settings and Studio, visual and entrances.
- Reference originals (13 files): the owner's character bible, lore, personality, voice, relationships, core and agent documents, the 8-bit PNG and a layered editable pixel SVG, and a states JSON.
- Architecture docs: edith.md (388 lines), edith-agent.md (100) and edith-call.md (45) in docs/architecture.
- In total about 25,700 words of plans, specs, reference text and architecture documentation (wc -w over those files).
Themes in the decision log
- Grounding and determinism: deterministic-first answers over published facts, a language model last (D05, D29 to D31, D41 to D43).
- Safety and consent: an allowlisted action contract, ticketed one-use authorization, never trust the client, and DOM-only knowledge of the UI for hands-on mode (D03, D38, D43, D58, D59, D85, D86).
- Privacy: session-only by default, saved chat local-only with moderation before persisting, no tracking of capability data (D04, D13, D57 to D60, D80).
- Presence and performance: a lazy host chunk, no assets in public/, CSS-only movement, bounded timers (D24 to D26, D47, D77, D87).
- Owner tooling and platform: a CMS Studio global, an Express 5 and Next adapter over one handler, in-memory rate limits with honest caveats (D09, D15 to D21, D62 to D69).
- Games and character: Phaser behind a single lazy door, original pixel art only (D08, D20, D70 to D73, DA1, DA2).
Models and providers considered
- Needle (via Orivyn / cactus-needle): A small tool-calling model from Cactus Compute running in browser WebAssembly.
- Whistle (via Orivyn): A small speech-to-text model for the browser.
- Cactus server inference: Orivyn's optional server-side provider using the cactus-compute package.
- Gemini fallback: A hosted model behind a server-only, grounded, budgeted guard.
Verdict: The design rule that falls out of the evaluation: the cheapest reliable path wins.
Everything she can do
Generated from the ability catalogue, the capability registry and the architecture docs.
Answer, reason and show her working
- Answers questions about Rishit's work, career, skills and awards from the published portfolio only, citing the fact behind every claim. The committed index holds 170 facts across 16 catalogued apps.
- Mind reasoning: counts, newest-first lists, side-by-side comparisons that say what two projects share, 'what should I look at?' recommendations ranked by technology match then featured status and recency, role recency from stated date ranges, and technology filters ('which projects use Kafka?').
- Follow-ups: 'what about its stack?', 'when was that?' and 'tell me more' resolve against the newest project, study or role named in the last six turns, and defer if none is named.
- A visible trace on non-trivial answers ('How I got this: ...') plus tappable suggested next questions; in the detached chat the trace collapses into a disclosure.
Know the screen
- 'What is this screen about?' resolves the current canonical route to a plain-language description from published data: a Lens project and section, a Lens tab (with the cluster counts), or another app via its help guide, plus what to try there. It reads the route only, never the DOM or window state.
Open things
- Open any registered app or a specific Lens project or section by name; ambiguous project phrases produce 'Which one should I open?' with up to three buttons.
- Navigate Lens tabs and filter Workloads by a published technology.
- Open a Settings section ('open privacy settings'), matched with the shared fuzzy matcher.
- 'Play' is disambiguated between Music and the Arcade using the published catalog and recent context, and asks when it cannot tell.
Change the OS (23 registered capabilities)
- Accent colour across nine themes (orange, amber, red, pink, purple, blue, teal, green, graphite), including 'change the accent from orange to green'.
- Light and dark mode; stepped text size.
- Dock: show or hide, size, position, labels, magnification, auto-hide, icons; system bar and clock visibility.
- Glass, icon appearance, wallpaper, motion mode, window opening animation and high contrast.
- Lens: open a project, search by technology, switch tab. Settings: open any section.
- Explicit, reversible commands typed by the visitor run immediately and offer Undo; model proposals and anything else wait for a button press.
Do it for you: Hands-on mode
- With Hands-on mode on (the default, switchable in Settings), a short imperative like 'open Lens' makes her walk to the Dock or launcher icon, click it and pull the window open with a dedicated motion variant.
- Setting changes are acted out: a brush for the accent, a light switch for the theme, a magnifier for text size, with several funny line variants. The change is committed exactly once whatever happens.
- She knows the UI only through the DOM landmarks and window title bars she can actually find, never through window state, and never clicks anything she did not find.
- On phones and under reduced motion she teleports and acts at once.
Music
- 'What songs are there?' lists the real published tracks and releases.
Tours and help
- Guided tours that point at landmarks with a ring and a card: an OS tour of 12 steps and help guides for 10 apps (Messages, Mail, Arcade, Lens, Code, Career, Browser, Gallery, Music, Settings), 68 steps across 11 published guides.
- A guide may only point at landmarks it owns and never contains a selector; a unit test fails if a guide points at a landmark that no longer exists in source.
- The tour never starts by itself; the ring is an outline, not a click-blocking overlay; a missing landmark is skipped or explained honestly.
Chat where you are
- A Messages app with a full conversation UI on desktop, tablet and a separate iOS-style phone layout.
- A detached chat panel (Alt/Option+Shift+C) that floats over any app, shares one conversation store with Messages and is not modal.
- Saved chat, local to the device and on by default: at most 50 messages and 14 days, with moderation before persisting, a delete button and a JSON download.
Presence, sprite and character
- A sprite built from the owner's layered SVG: a 23 by 39 cell grid in 8 named parts, shipped as bundled data with no image files in public/.
- Eight entrances (peek, walk, teleport, sitcom, parachute, drone, drop, hop) and matching exits; reduced motion and data saver collapse to one quiet fade.
- A life of her own: coffee and reading, meals by the visitor's local time of day, caught asleep in a pixel bed at night, an armchair and headphones when music plays, a handheld game, typing at a laptop while Code is open, landing on title bars, tidying Dock icons. All rate-limited, bounded and visual-only.
- Synthesised WebAudio sound cues, on by default but gesture-gated, never on a serious reply.
- A lock-screen pop-in once per tab session, and owner-authored extra lines and entrance weights from the CMS Studio.
Self-knowledge
- A hand-written catalogue of 12 abilities (answer, search, screen, open, accent, theme, text, settings, settings-open, music, tour, chat) matched with the fuzzy matcher answers 'what can you do?' and 'can you change accent colours?'.
- A test runs every advertised command through the real capability registry, so she cannot claim something that does not work. She also lists what she cannot do: send messages, change anything outside the portfolio, or answer from private information.
She plays too
- Two E.D.I.T.H. Picks in the Arcade built on Phaser 3 behind one lazy door: Parachute Glide and Drone Protocol. She is drawn from her own sprite recoloured as a test pilot, with story text, pure unit-tested rules and no new art files.
export function isLocalNavigationCandidate(message: string): boolean {
const text = message.trim();
if (text.length < 4 || text.length > 500 || checkPolicy(text) !== "ok")
return false;
if (/\b(?:don['’]?t|do not|never|without|instead of)\b/i.test(text))
return false;
if (/https?:\/\/|www\./i.test(text)) return false;
return /^(?:please[, ]+|edith[, ]+)?(?:open|launch|navigate to|go to|take me to|bring up)\b/i.test(
text,
);
}Architecture
Conversation pipeline
What happens to a visitor's message, in order. Each stage can answer and stop.
- Visitor message: Bounded text; unknown fields dropped by schema
- Origin + rate limit: Same-host Origin, salted HMAC client key, sliding window
- Policy gate: Distress first, then injection, explicit, private, abuse
- Small talk + abilities: Greeting, identity, 'what can you do?'
- Open / perform: Only a true open verb; chip or hands-on act
- Mind: Counts, filters, compare, recommend, follow-ups
- Retrieval: TF-IDF-style over the fact index with synonyms
- Gemini (off): Grounded rephrase if enabled and facts match
- Honest fallback
Client-side architecture
Everything heavy is lazy; the shell holds only a gate and an avatar.
- EdithGate (eager): Summon listener, warms the host once
- Head avatar: Hat and face layers only
- Messages / detached chat: Shared conversation store
- EdithHost (lazy): Store, sprite, CSS, timers; about 5.8 KB gzip JS
- Hands-on actor: CSS-only movement via DOM landmarks
- Guide layer (lazy): Ring and card from published guides
- Capability kernel: Registry, tickets, receipts, undo
- OS ports: OSPreferences, theme port, routes, media session
- CMS Studio: Owner lines and entrance mix, fail-soft
Package boundaries
- @repo/edith is source-only with five entry points: . and ./contracts (browser-safe zod contracts), ./server (services, handler, limiter), ./next (App Router adapter) and ./express (an Express 5 router over the same handler, not imported by the Next app).
- One catch-all route, /api/edith/[...path], on the Node runtime delegates to a single transport-neutral handler with limits, origin check and routing.
- All tuning lives in a typed config file (apps/desktop/config/edith.config.ts) with no environment variables; the only runtime secret is GEMINI_API_KEY, inert while Gemini is disabled.
Key decisions
Decision: Deterministic first, language model last
accepted
Problem: How do answers stay truthful and cheap?
Chosen: A deterministic pipeline over published facts, with a gated model last
Why: Answers are produced by policy, small talk, abilities, hands-on open, Mind and retrieval in that order. Only if all decline and at least one published fact matches can Gemini phrase an answer, and only if gemini.enabled is true and a key exists.
Decision: Needle is a router, not her personality
accepted
Problem: What job does Needle get?
Chosen: Use it only to propose one allowlisted app navigation for explicit open commands
Why: The tool schema enumerates the registered app ids and rejects additional properties. Zero, multiple or invalid proposals fall back to the existing handler. Closing Messages aborts inference.
Decision: Her only knowledge of the UI is the DOM
accepted
Problem: How does she locate things to click?
Chosen: Find landmarks and title bars in the DOM
Why: Landmarks are generic data-landmark attributes (dock, launcher, menu bar) and title bars are found by their context-menu attribute. If nothing is found she says so.
Decision: No E.D.I.T.H. assets in public/
accepted
Problem: How is the character art shipped?
Chosen: Bundled pixel data from the owner's layered SVG
Why: The sprite is quantised from edith-pixel-editable.svg to its true 23 by 39 grid into generated TypeScript, drawn as inline SVG rects.
Execution quality: safety, privacy and performance
Safety
- The server never trusts client intent, role, tools, system text or selectors; unknown chat fields are dropped by the schema and guide ids must match a strict pattern.
- Rate limiting runs before the pipeline with salted HMAC keys and a hard-bounded in-memory limiter; client IP is the Nth hop from the right of X-Forwarded-For, and a header shorter than the configured hops is never trusted. Within the first day a security review found a phone-redaction bypass (fixed with regression tests) and the client-IP resolution and limiter were hardened.
- Policy gate order: distress first, then injection, explicit, private and abuse. Flagged and serious turns are never stored.
Privacy
- Session-only by default in the original design; saved chat is now on by default by an explicit owner decision (D80) but local-only, capped at 50 messages and 14 days, with a visible switch, a delete button and an export.
- Sound defaults on but never plays before a real user gesture.
- No microphone, no voice and no webcam; capability data is never sent to analytics.
Performance and accessibility
- Lazy by construction: an eager gate and avatar in the shell; the host is a separate chunk of about 5.8 KB gzip JS and 2 KB gzip CSS; the guide UI, detached chat, executor and local model are separate lazy chunks; Phaser is a single 1.08 MB chunk only the games fetch.
- No global polling, no recurring inference loops, one timer slot for her idle life, CSS-only movement and nothing running while the tab is hidden.
- Reduced motion collapses entrances to one fade, hands-on to an instant act and games skip particle bursts; tour buttons grow to 44 px on coarse pointers.
- A pre-change Lighthouse baseline was captured before touching the shell (mobile 77, desktop 99) and the lock-screen pop-in is flagged for a Lighthouse check on every change.
Honest limitations
- Answers are extractive: they quote and list published text and do not reason across records beyond Mind's counts, filters and comparisons.
- The fact index changes only when the sync script runs, so a CMS change needs a rebuild.
- Rate limits are per Node process; behind several instances the limits multiply.
- The tour is English only and apps without a guide get an honest summary instead of a walkthrough.
Iteration history
From 'Init Edith' to Mind and agentic control
2026-11-15T00:00:00.000Z
Init, package and API bridge (P0/P1)
Commits aec8879 and a5ba7b1: the @repo/edith package and the /api/edith bridge; a hardening fix for client-IP and the limiter the same day.
2026-11-15T00:00:00.000Z
Sprite and presence (P2)
fcdba1b: pixel sprite from the owner's SVG, summon, state machine and entrances.
2026-11-15T00:00:00.000Z
Deterministic conversation, grounding and Messages (P3)
483179c, 4cab76c, e7ce339; a phone-redaction bypass fixed in 11a5faf.
2026-11-15T00:00:00.000Z
Guide Mode (P4)
c72d41f, acea399: landmarks, published guides, the tour UI.
2026-11-15T00:00:00.000Z
Gemini fallback, polish, saved history, Settings pane, Studio (P5, P6)
5827fd8, 2a216aa, a8dcbbd, d41890c, 90f6c61, 7e0f3c1.
2026-11-15T00:00:00.000Z
Arcade E.D.I.T.H. Picks (P7)
ab1ea71 Parachute Glide and b42cb1a Drone Protocol on Phaser 3.
2026-11-16T00:00:00.000Z
Wow pass, phone home, test-pilot Picks; Hands-on mode
336d06e, then 1d93c10 and follow-ups: she walks to the icon and pulls the window open.
2026-11-17T00:00:00.000Z
Orivyn local intelligence and music grounding
a71d7c1, 4dd58a1, 34339de, dcce83e: optional Needle navigation, live-catalog music commands, Music versus Arcade disambiguation.
2026-11-17T00:00:00.000Z
Capability kernel and grounded Lens intelligence
f8a714c: tickets, receipts, undo and registered capabilities.
2026-11-17T00:00:00.000Z
Mind, detached chat, fuzzy matcher, screen awareness
222f168, 45298c4, 65d6e3a, 5f67dc5.
2026-11-17T00:00:00.000Z
Agentic OS control, hands-on acts and self-knowledge
c717a70 with a StrictMode fix in 425dd7a.
2026-11-18T00:00:00.000Z
E2E reads preferences from IndexedDB
3dcc66b after the storage migration.
Evidence
- 49
- Commits touching E.D.I.T.H. paths
- ), ), ), 2026-11-18 (1). Paths: packages/edith, lib/edith, components/edith, components/messages, e2e/edith.
- 91
- Recorded decisions
- D01 to D89 plus DA1 and DA2
- 177 tests
- Package tests (@repo/edith)
- 13 files, all passing: conversation 47, mind 12, fuzzy 6, plus knowledge, guide, security, presence, sprite, gemini, handler, express, studio
- 53
- E.D.I.T.H.-related unit test files
- Across packages/edith/src/__tests__, lib/edith, components/edith, lib/messages and components/messages; the desktop suite as a whole is 1,845 tests
- 69 tests
- E.D.I.T.H. Playwright tests
- 10 spec files in apps/desktop/e2e/edith (agentic, detached, edith, guide, hands, history, messages, presence, settings, studio). Static count of test( blocks.
- 11 guides / 68 steps
- Published guides
- OS tour 12 steps plus 10 app help guides
- 170
- Indexed facts
- Committed knowledge snapshot
- 23
- Registered capabilities
- 22 os.* and lens.* capability ids plus settings.open, counted in capabilities/*.ts
- 12
- Catalogued abilities
- Each advertised command is tested against the real registry
- 8
- Entrances
- peek, walk, teleport, sitcom, parachute, drone, drop, hop
- about 3,200 lines
- Source size, @repo/edith
- TypeScript excluding tests and generated sprite data
- about 8,000 lines
- Source size, app side
- lib/edith, components/edith and components/messages excluding tests
Measured footprints recorded in the docs
- about 5.8 KB gzip JS + 2 KB gzip CSS
- Companion host chunk
- Lazy; the shell holds only the gate and head avatar
- 1.08 MB
- Phaser chunk
- One lazy chunk downloaded only by the games
- mobile 77 / desktop 99 Lighthouse
- Baseline before shell changes
- LCP 6.3 s mobile; CLS 0
Future: E.D.I.T.H. Call
Planned, not built
A call app where visitors talk to E.D.I.T.H. about Rishit and she answers playfully. Phone mode is voice only (call sheet, caller state, level meter, captions toggle, hang up). FaceTime mode adds a stylised, clearly non-human AI figure that reacts to speaking, listening and thinking. Both share one conversation engine.
The planned pipeline
- Listen: Whistle through @orivyn/browser for local speech-to-text, push-to-talk first, 16 kHz mono, 20 second cap, microphone only after a gesture, tracks released after use.
- Think: answers about Rishit come from the published knowledge with source references; a separate reasoning provider needs explicit consent for any remote transfer.
- Speak: a text-to-speech provider, no audio without a gesture, first audio under about 1.2 seconds, barge-in within 200 ms.
- Honesty: disclosed as an AI, a clearly synthetic adult female-presenting voice, no cloning of Rishit's voice, captions on by default in FaceTime mode, reduced-motion fallback.
Constraints
- An ordinary window-agnostic app with a canonical route (for example /call) and a server-rendered explainer page.
- Heavy code lazy and loaded only after the call starts; WebGL, if used, claims the single context.
- Music pauses while a call is live; analytics carry no transcripts or audio.
- Open questions: the TTS provider and whether a local model is fast enough on phones, the avatar style direction, and the retrieval source for 'about me' answers.