Key decisions
Decision
Deterministic first, language model last
AcceptedA deterministic pipeline over published facts, with a gated model last · chosen over 1 other
Context
A portfolio companion must never invent facts about a real person, and a free-tier model is quota-limited.
Problem
How do answers stay truthful and cheap?
Options considered
A general chat model answering from a prompt
Advantages
- Fluent, flexible
Disadvantages
- Can invent facts about the owner
- Cost, quota and data transfer
- Hard to test
A deterministic pipeline over published facts, with a gated model last Chosen
Advantages
- Every claim cites a fact
- Testable and free
- No network for most answers
Disadvantages
- Answers are extractive and can fall back honestly
Rationale
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.
Consequences
Gemini is off in the committed config. Output is schema-validated, grounded against the facts sent, link-stripped and never carries actions.
Decision
Model proposes, registry validates, visitor confirms
AcceptedTyped capabilities with arguments validated by the app, one-use tickets and Undo · chosen over 1 other
Context
Agentic control of an interface is risky if model output can execute.
Problem
How can she change settings without an omnipotent executeCommand?
Options considered
One broad executeCommand function
Advantages
- Fast to build
Disadvantages
- Unbounded blast radius
Typed capabilities with arguments validated by the app, one-use tickets and Undo Chosen
Advantages
- Bounded and testable
- Reversible
- Forged or restored ids cannot execute
Disadvantages
- Each capability needs a spec, preview and compensating undo
Rationale
Tickets are random, browser-local, one-use and expire after two minutes; they are consumed before execution. No model score triggers an automatic change. Only an explicit, deterministically matched, reversible command typed by the visitor runs at once.
Consequences
Arbitrary URLs, DOM selectors, network writes, account actions and credentials are never capabilities.
Decision
Needle is a router, not her personality
AcceptedUse it only to propose one allowlisted app navigation for explicit open commands · chosen over 1 other
Context
Orivyn's strategy note concludes a small tool-calling model cannot also converse and reason.
Problem
What job does Needle get?
Options considered
Use Needle for everything
Advantages
- One component
Disadvantages
- Poor grounding
- Uncalibrated scores
Use it only to propose one allowlisted app navigation for explicit open commands Chosen
Advantages
- Cheap admission gate
- Downloaded only when needed
- Output restricted to registered app ids
Disadvantages
- Limited scope
Rationale
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.
Consequences
Questions, distress, private asks and speech never wake the model.
Decision
Her only knowledge of the UI is the DOM
AcceptedFind landmarks and title bars in the DOM · chosen over 1 other
Context
Hands-on mode needs to find icons without breaking the window-agnostic app rule.
Problem
How does she locate things to click?
Options considered
Read window manager state
Advantages
- Precise
Disadvantages
- Violates the app contract
- Couples her to internals
Find landmarks and title bars in the DOM Chosen
Advantages
- No new state channel
- She never clicks what she cannot see
Disadvantages
- Missing elements must be handled honestly
Rationale
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.
Consequences
No window state enters windowRef, React context or the manager.
Decision
No E.D.I.T.H. assets in public/
AcceptedBundled pixel data from the owner's layered SVG · chosen over 1 other
Context
Another app should be able to reuse her without copying files.
Problem
How is the character art shipped?
Options considered
PNG and image files in public/
Advantages
- Simple
Disadvantages
- The audited PNG is 572 KB with an irregular grid
- Needs hosting paths
Bundled pixel data from the owner's layered SVG Chosen
Advantages
- Zero requests
- Reusable by any app that imports the package
Disadvantages
- Built by a generation script
Rationale
The sprite is quantised from edith-pixel-editable.svg to its true 23 by 39 grid into generated TypeScript, drawn as inline SVG rects.
Consequences
The summon avatar imports only the hat and face layers; a unit test asserts the hand cannot appear.