Specious Coda Bishop

Issue Fixed "Show me how you were built" was using a hardcoded anchor string — fragile as the portfolio grows. Separately, Digital Spec sat at slot 8 of 8 in the builder-technical lane; any new project at the same score tier pushes it off the list. Fixed both: the deeplink now uses a new find-project action that looks up by item id in the portfolio index at runtime. Digital Spec is now pinned to builder-technical via audiencePin in the index so it always appears regardless of how many other projects score the same.

Issue Fixed Panel was still jumping to the bottom even after the 320ms deferral — scrollBottom() scrolls to scrollHeight regardless of where new content starts. Replaced with scrollToElement(bubble): calculates the bubble's position relative to the scroll container and sets scrollTop so the bubble lands at the top of the panel. Added preventScroll: true to all focus() calls so keyboard focus doesn't fight the scroll position. Applies to all node transitions and lane results.

Note Audited the portfolio copy for AI-generated writing. The recent build added a fair amount of LLM-flavoured prose, so I ran a read-only pass against the voice-and-tone guide and wrote the findings up in AI-PROSE-AUDIT.md — 28 flagged passages across five sections, worst in the front-door lane blurbs and this project's own wins and constraints. The pattern that kept recurring was the balanced "X, not Y" phrasing used as a default rhythm, plus filler words like "genuinely" and "robust" and a few tidy uplift closers. The audit recommends only; it changed no copy.

Done Acted on the safe half of the audit — a deletion-only cleanup, no rewriting. Removed filler intensifiers ("genuinely" in three places, a "Crucially" opener on this project's description), two uplift closers, and a duplicated "interesting problems" line in the About cards. The front-door config and this dev log were both in scope: the kh-lore node lost a "genuinely", and the "Charm for those who lean in" sign-off that used to close the "Never trap a busy visitor" decision below came out here. The "X, not Y" and "by design" flags were left alone — those need a real voice edit, not a mechanical cut, so they're staying until they can be reworked by hand.

Issue Fixed The scroll-jump bug that was fixed for lane results was still present across all other conversation paths — every node transition (hiring routes, curious, nosy, contact, etc.) rendered the bubble and options together then scrolled to the bottom, pushing the new question text above the fold. Fixed by applying the same 320ms deferred pattern to goToNode: bubble renders and scrolls into view first; options appear after a short pause.

Issue Fixed Devlog was showing all 11 recent entries visible at once instead of just the most recent. Fixed: only the latest entry is now visible on load; all older entries collapse under the toggle. Updated toggle count to reflect the full history now in the overflow.

Issue Fixed Lane results were jumping straight to the first bucket of cards, skipping the blurb entirely. Root cause: scrollBottom() fired after all cards were rendered, sending the viewport past the blurb. Fixed by rendering the blurb and scrolling to it first, then dropping the cards in 320ms later — matching the natural rhythm of the conversation.

Done Lane results redesigned: flat card list replaced with a framing blurb (Digital Spec sets context before anything shows) followed by items grouped into labelled sections by type — Work, Case Study, Project, Document. Empty buckets are skipped. Denim brand now routes to the lane-specific section anchor via sectionsByLane. Kingdom Hearts path got an expanded synopsis node before the lane.

Done Expanded the Kingdom Hearts curiosity path. Previously "What's with all the Kingdom Hearts?" dropped straight into the creator-lore lane with no context. Now it routes through a new node that introduces LoreBySpec — what it is, why Spec built it, the podcast, the sub count — before branching: see the tools built for the channel, or just curious. The just-curious branch gets a warm dead-end with a restart or skip option.

Issue Fixed No way to go back or start over mid-conversation. Once you chose a path, you were committed. Added a quiet "↺ Start over" button that appears below the options from the second node onwards, and in lane result footers alongside the Back button.

Issue Fixed Ctrl+R resumed the conversation at the last node — the overlay remembered which branch you were on across page reloads via sessionStorage. Unintuitive: a refresh should feel like a fresh start. Removed node caching entirely; collapse state is still remembered so the docked tab stays docked, but the conversation always restarts from the opening.

Issue Fixed "The thing Spec's proudest of building" deeplink was landing mid-case-study (an internal section anchor) rather than at the title. The config was referencing a sub-section ID. Updated to use the top-level entry anchor so the route lands at the heading.

Issue Fixed Project was sitting at the very bottom of the Projects tab — so the deeplink scrolled visually past every other project on the way down. Moved to the top of the section so the route lands cleanly.

Issue Fixed "Show me how you were built" was routing to the builder-technical lane — a curated list of AI tools — rather than this project. Root cause: this entry didn't exist in the portfolio index when that node was written, so the lane was the fallback. Added the index entry and updated the node to deeplink directly here.

Pivot Dismiss-on-click-out replaced with collapse/expand. v1 removed the overlay on dismiss — a visitor navigating away and back lost their place entirely. Refactored: clicking outside, pressing Esc, or hitting the minimise button collapses the overlay to a docked "Ask Digital Spec" tab (bottom-right). It persists through the session and re-expands at the same node. Position preserved, no re-showing on page restore.

Done Language refresh. Naming rules applied across all nodes: Digital Spec = the guide; Spec = the human. "Spec Lite" (early working name) scrubbed entirely. All option labels rewritten in the visitor's voice — "I'm hiring" not "Hiring manager", "I'll poke around myself" not "Browse everything".

Done v1 live. The portfolio's front door — a branching guide that routes visitors by what they came for. Built as an overlay on the static site; reads the tagged portfolio index for content, so it curates by tags rather than hardcoded lists. Because it carries this dev log, it surfaces in its own builder lane — the thing explaining the portfolio is a documented piece of it.

Decision Posture-first, not content-first. The opening sorts by mindset — hiring, curious, nosy — not by topic. A visitor knows which they are instantly; leading with a job-category question forces a hiring frame on someone who's just browsing. Each posture gets its own register.

Decision Digital Spec announces it's a construct, up front. No pretending to be a live assistant. The honesty is the pitch: the first thing a visitor learns is that this was built deliberately and runs on pre-set logic. For a portfolio whose value is transparency, a fake "live AI" would undercut the thing it's selling.

Decision No AI, by design. It would have been easy to wire an LLM in. Pre-programmed branching means zero hallucination risk and nothing it can say that Spec didn't write. Every word is accountable.

Decision Decoupled structure from content. The dialogue lives in front-door-config.json; the content comes from the tagged portfolio index via lane queries. Lanes are queries over facet tags, never hardcoded item lists — so adding a project surfaces it automatically, and the conversation can change without touching content.

Decision Tappable replies only — no text box. An open input promises a brain that isn't there; someone types a real question and hits a wall. Tappable choices keep the illusion honest and render as the visitor's own messages.

Decision Never trap a busy visitor. A persistent skip, and the overlay collapses to a docked tab rather than vanishing — a recruiter with four minutes can dismiss it in one tap and still retrieve it.

Decision Instant responses, no fake typing delays. Personality goes in the words, not artificial latency — especially for a recruiter-adjacent audience.

Note Graceful degradation. If a lane has no matching content yet, the node says so and routes to the full site rather than showing an empty box. The front door could ship before every lane was full.

Decision Accessibility from the start. Full keyboard navigation, focus trapped while open and restored on collapse, Esc to collapse, reduced-motion respected. A guide some visitors can't operate isn't a guide.

Note Origin. This started as a slightly cynical proof of concept — how cheaply you can fake bespoke curation with the right wiring. The honest inversion became the point: a constructed guide that's loud about being constructed, backed by a real tagged index, is more transparent than most "handcrafted" portfolios.

Note Spec pasted the literal Ashby + Greenhouse feed URLs into chat. Provenance is conferred per-conversation, so every subsequent web_fetch in the session then worked — which is what made today's pass possible. It's a manual workaround that has to be repeated each session, not a durable fix.

Decision The 06-24 plan's option #1 (curl the feeds from the sandbox shell behind a domain allowlist) is closed: the content-fetch policy forbids retrieving URLs via shell/curl/python whenever web_fetch is blocked — allowlist or not. Re-confirmed there's no off-the-shelf Ashby/Greenhouse public-board connector in the registry either. The durable fix narrows to two routes: have the scheduler inject the expanded (de-templated) feed URLs so they enter provenance, or build a dedicated connector.

Constraint The exact mechanism is now nailed down. The scheduled task passes templated URLs (…/job-board/<token>), but web_fetch only accepts URLs that appeared literally in a user message — so a templated URL never lands in the provenance set during an unattended run, and every feed is unreachable. The 06-24 constraint wasn't transient; it's structural and will recur every scheduled run until a durable route lands.

Failure Pre-flight fetch of the Remote (remotecom) canary failed with URL not in provenance set; confirmed on a second (Ashby) feed. Per the canary rule, the run aborted rather than grinding all feeds, and posted a "feeds unreachable" digest. No state advanced. Third identical abort (06-24, earlier 06-26, scheduled 06-26).

Failure The morning run gathered 0 roles — a tooling block, not an empty market, so the day is logged as "unknown", not "nothing out there". A guardrail held: last_run advanced but nothing was written to Seen.json or Matches Log.csv, so a failed fetch was never recorded as a clean empty result.

Constraint This is structural, not a flaky feed. Three independent paths to live role data are each closed for a different reason. web_fetch enforces a provenance allowlist — it only retrieves a URL that has already appeared in a message or a prior fetch result, so the agent can't introduce its own feed URLs from Config.md (the one thing a poller must do). The sandbox shell can't compensate: no outbound network by design (even example.com returned HTTP 000). The hosted ATS boards can't compensate either — they're JavaScript shells and web_fetch doesn't execute JS, so only the raw JSON API carries the data, and that's the blocked path. The watcher's own logic is fine: once a Greenhouse URL happened to be in the provenance set, web_fetch returned full live JSON and the parser handled it. The gap is structural — getting our own URLs admitted — which is why it disables the core premise rather than dropping one company.

Decision Search snippets were deliberately not used to fill the gap. The governing rule is "a missed role is cheaper than a wrong one" — cached snippets are stale and partial (they surfaced Ashby Americas roles the location filter would drop anyway) and risk false positives and re-reporting closed roles. Skipping them was a choice, not an oversight.

Decision Ranked, easiest first: (1) grant the sandbox shell network access to the ATS hosts so the watcher curls the JSON directly — most robust, bypasses both blockers; (2) a per-domain provenance allowlist for web_fetch; (3) a dedicated Ashby/Greenhouse jobs connector — cleanest long-term, structured output; (4) a headless render for the JS-only boards, only if still needed. Plan: do #1 now to restore coverage, build toward #3 as the durable solution. Tagged a decision, not a fix — none of this is applied yet.

Decision Going in: a pre-flight canary feed at run start — if a known-good feed fails, abort and post a "feeds unreachable" digest instead of a silent "nothing new"; count only HTTP 200 + parsed JSON as "checked" so a fetch error never advances a feed's seen-state; add a per-feed last_success to Seen.json and surface anything not polled in N days under "manual check needed"; and stop trusting last_run as proof of coverage.

Done Added the full yellow watchlist. Probed ATS tokens in batches: 13 confirmed on Greenhouse (Mercury, GitLab, Datadog, Cloudflare, Dropbox, Airtable, Discord, Figma, Intercom, Wikimedia, HubSpot, Bitwarden, Customer.io) plus Tyk on Workable. Ten more (GitHub, Atlassian, 1Password, Headspace, Circle, Basecamp, DuckDuckGo, Whereby, Cronofy, Spotted Zebra) have no clean public feed and went to the manual list. Scanning the new feeds, the filter immediately did its job: the yellow boards are mostly US-remote, engineering, and sales — all correctly dropped — but it caught one real fit, Bitwarden's Customer Success Specialist (EMEA), tagged 🟡 for reactive-volume risk. Logged so it won't repeat.

Done Every role now carries a one-line reason, and 🟡 tags must say why they're 🟡 and not ✅. This was a deliberate move away from a bare match list. The morning run pulls the relevant matrix note when it helps explain the call.

Note Ran the whole procedure end to end against today's feeds. Result was more current than my own tracker: Ashby's IC/IS roles weren't in the live feed (the tracker still listed them), and Remote surfaced a Germany-based Payroll Implementation Country Lead plus an EMEA Implementation Specialist — both ✅. Confirmed dedup works: the three roles already reported were skipped on the second pass.

Done Mapped each company to its hiring platform. Blind Greenhouse token guesses mostly failed; the pattern is that modern remote-first startups sit on Ashby (Deel, Zapier, n8n, Oyster, Improbable, Help Scout all resolved there). Used web search to identify the non-Ashby ones: Tyk and Adaptavist on Workable, Puzzel on Teamtailor, HiBob on Comeet, Peak PEO on no ATS at all (≈18 people).

Issue Workable's public API timed out repeatedly through the fetch tool, and its apply page is JavaScript-rendered, so a plain fetch returns an empty shell. Teamtailor, by contrast, renders its careers page as clean readable text — Puzzel reads fine with no API needed.

Decision Try the Workable API once, and on timeout fall the company through to manual-check rather than hang the run. One slow ATS shouldn't stall the whole morning.

Issue Two constraints nearly sank the approach. First, the sandbox has no outbound network, so the obvious "write a Python script that curls the feeds" doesn't run there. Second, the fetch tool overflows large feed responses to a file instead of returning them inline, and those files are single JSON lines too long to read normally.

Fixed Parse the saved overflow file with Grep (-o), which handles arbitrarily long lines and pulls title / location / jobUrl straight out. That turned a blocker into the standard parse path — fetch overflows to a file, Grep extracts the fields, the run filters from there.

Done Confirmed the core question before building anything: can I get clean machine-readable role data from these specific companies? Yes. Ashby (/posting-api/job-board/<token>) and Greenhouse (/v1/boards/<token>/jobs) both return structured JSON with exactly the fields the filter needs — including locations like "Remote - European Union", which is what the Germany gate keys on. Empty responses correctly mean "no open roles" (matched a tracker note that said as much). No scraping required.

Note Began with my existing Role Matrix (fit criteria per role type) and Company Tracker (green/yellow/red, with culture and remote-policy notes already done by hand). The watcher is built to sit on top of that work, not replace it: the matrix defines what a fit is, the tracker defines which companies count, and the agent does the daily checking I was doing manually.

Note Decision: kept the must-have=0 rule as a hard cap rather than a heavy weight. A weight alone let a strong transferable case float a screen-out role up into Stretch, which misrepresents how an ATS reads it. The cap holds the verdict at Weak regardless of the rest of the score.

Issue Fixed Verdict logic tested across eight scenarios — gate fail, must-have=0 at high fit, and each band boundary at 0.72 / 0.55 / 0.40. The first pass treated must-have=0 like any other low score and let an 85% role read Strong. Rewrote the verdict formula with two overrides (gate fail → No-go, must-have=0 → capped at Weak) and re-ran: all eight resolved correctly.

Done Built the five-tab engine — Scorecard, Tracker, Profile, Rubric, and the gate. The weighted total recalculates clean with zero formula errors. Input cells are colour-coded so the ones to change on each run are obvious.

Note Chose a weighted scorecard with a dealbreaker gate over a flat yes/no or a single relevance percentage. The established approach for "is this worth applying to" is a decision matrix with anchored scoring; the separate gate carries eligibility, which a weighted average would otherwise wash out.

Note Built the profile baseline from the portfolio repo README — skills, tools, domains, and a project-to-evidence map. Left salary, work authorisation, and seniority as confirm-me placeholders, since those drive the gate and only I can fill them honestly.

Issue Couldn't delete the scratch build and test files from the working folder — sandbox permissions blocked the removal. Minor: they sit outside the three deliverables and don't affect the toolkit.

Decision Added a contextual callout to the "Real Problem" section in the rendered output — a small amber-bordered note that reads "Where an error appears is often not where the bug lives." It's only four words of UI but it primes the reader to hold the root cause section differently. Without the framing, people skim the section as if it's just more explanation of the error.

Decision Set max_tokens to 1,400. Five detailed sections averaging 200–250 tokens each covers the output without leaving room for padding. Tested at 900 (too thin for the coaching section), 1,200 (borderline), 1,400 (consistently complete). Output tokens cost 5× more than input on Haiku — kept the cap tight.

Decision Five sections, not three. First instinct was three (explain, diagnose, fix) but the coaching section earns its weight — it's what separates a translation tool from a teaching tool. The "Where To Look" and "What To Try" split also matters: one answers WHERE to investigate, the other answers HOW. Merging them into a single "next steps" list collapses the distinction between understanding and action.

Decision Color-coded result sections: plain-English explanation in calm blue (informational), root cause in amber (needs attention), where to look in bright amber (investigative), what to try in green (action), coaching in purple (growth). Each color signals a different kind of reading — you scan the results differently knowing which section you're in.

Decision Warm amber/ember color palette — not red. The tool is about errors but the experience should feel constructive, not alarming. Red signals danger and tends to put people on the defensive. Amber signals "pay attention here" without the connotation that something is catastrophically wrong. Important when the audience is beginners who already feel anxious about errors.

Decision Monospace textarea for the error input, serif for context. Errors should look like errors — monospace signals "this is technical output, paste it as-is." The context panel is where you write prose, so serif is appropriate there. Small UX detail that reinforces the mental model of each panel.

Decision The error-surface vs error-origin gap is the tool's core value. Every beginner debugging tutorial says "read the error" — but few explain that the error location and the error cause are structurally different things. A React TypeError at render time almost never means the component is broken; it means something upstream returned the wrong shape. Building that instinct early saves hours of debugging time later. The "Real Problem" section is the reason this tool exists.

Decision Set max_tokens to 1,500. The debugging plan section alone needs 400–500 tokens to be genuinely useful at 5–7 numbered steps with explanations. Testing at 1,200 showed the "What This Teaches" section getting truncated. 1,500 gives consistent full output across all three modes.

Decision The "Where To Add Logging" section specifically mandates the actual log syntax — console.log('label:', variable) — not just "add logging here." Beginners often know they should add logs but don't know where to add them or what to log. Making the suggestion concrete (before the fetch, after the assignment, inside the if branch) is the difference between useful and vague.

Decision Mode selector as full-width styled cards, not a model-bar-style compact row. Three modes is a meaningful choice with a paragraph of explanation each — it deserves more visual weight than a compact radio toggle. The card style also lets each option carry a subtitle explaining when to use it, which reduces the guessing.

Note Silent failures are a genuine beginner trap. When code produces no output and no error, beginners often assume the code didn't run. The actual common causes — a catch block that swallows the error without logging it, an async function called without await, an event listener attached to a null element — are not intuitive. The silent mode was designed specifically to surface these, because no other debugging tool explains the absence of output rather than the presence of an error.

Decision Cool slate/blue palette — deliberately different from the Error Interpreter's amber. Two tools in the same portfolio sharing a color scheme would blur the distinction. More importantly, the emotional register should differ: amber for "here's what's wrong" (attention-drawing), blue for "here's how to find it" (methodical, calm). Color communicates the relationship to the problem.

Decision Structured as a companion to the Error Log Interpreter, not a competitor. The Interpreter answers "what does this mean?" — this tool answers "how do I approach finding and fixing it?" Same audience (beginners), different moment in the debugging process. A developer will often need both: one to understand the error, one to plan the fix. Keeping them as two separate tools with clear roles is cleaner than one multi-purpose tool that tries to do everything.

Decision The prototype is scoped to what can be fully explained and defended in an interview without notes. Every function, every field, every threshold has a reason that can be stated clearly in plain English. If a future iteration warrants more complexity — live API integration, a proper frontend, multi-CSM views — the devlog will record why that complexity was added and what problem it solved. Complexity without documented rationale is technical debt.

Decision It would be easy to build a full health dashboard — React frontend, live PostHog API integration, Stripe webhooks. That would duplicate Vitally, which PostHog already pays for. It also wouldn't be defensible in an interview — the question would shift from "why these decisions?" to "explain your framework choices." Over-engineering is a CS anti-pattern too: a CSM who ships something their team can't understand is creating a liability. The prototype is a JSON model and a short Python script. The complexity lives in the design decisions, not the code.

Decision PostHog's stack uses Vitally's composite score — that's right for a team-wide tool. But composite scores have a failure mode: they hide the shape of a problem. A customer with strong usage, an active Slack channel, and a health score of 78 might have an unanswered renewal conversation from 3 weeks ago. The composite score looks fine. The account is at risk. The prototype surfaces signals individually — each with a plain-English reason and a suggested action. Not a number.

Note A self-serve customer being quiet for 30 days is expected — they chose not to talk to anyone. A sales-assisted customer being quiet for 14 days after a personal onboarding is a flag. The account model includes a customer_type field and all signal thresholds adjust accordingly. This is one of the few places the code makes an explicit behavioural claim — and it's here in the devlog so it's defensible.

Note PostHog's CS automation stack from their handbook: Vitally (composite health scores, synced from Salesforce, PostHog usage, BuildBetter, Stripe), PostHog CDP (usage milestone alerts piped to Vitally/Slack), BuildBetter (call analysis, auto-syncs feature requests), Zapier (renewal reminders, billing events), Pylon (Slack Connect channel management), Salesforce (CRM backbone). The stack covers monitoring. The gap is in prioritisation and action — a CSM opening Vitally to find 12 indicators and 3 Zapier alerts still has to decide where to start. That's where this project lives.

Note The brief contains two distinct problems: the signal problem (leading indicators, never be surprised) and the relationship problem (self-serve vs sales-assisted, Slack-first ICP, different engagement models for each). It also contains an explicit invitation: "If you want to build automations to help you, go for it." At PostHog, where engineers build their own tooling and the culture values autonomy, that line is a signal about what kind of person they're hiring. This project is built from the perspective of a CSM designing the automation layer they'd actually want.

Issue The friction point is real: a CSM opens their morning Slack, has 8 messages across 6 accounts, and to use this tool they need to copy each message, switch tabs, paste, fill in context, hit analyse, read the output, switch back. That's 8 context switches before 9am. The tool was conceived as cognitive load reduction but the interaction adds its own load. The question isn't whether the AI output is good — it is — it's whether the delivery mechanism gets in the way of the work it's supposed to accelerate. A dashboard that watches for signals and surfaces them without manual paste would be structurally better for this workflow.

Pivot Two fundamentally different tools could serve this role. Copilot (current): you bring it a signal, it tells you what to do. Dashboard: it watches your accounts and surfaces signals to you. The copilot is buildable client-side with no backend. The dashboard requires integrations — PostHog's API, Stripe webhooks, Slack message volume — which means a backend, authentication, and ongoing maintenance. V1 proves the prompt engineering and the domain knowledge are sound. V2 needs to decide which architecture actually fits the workflow before adding features. Building more features on a fundamentally friction-heavy interaction model doesn't fix the model.

Note The brief explicitly calls out "owning their feedback and making sure it gets to the wider PostHog team." That's a distinct workflow from triage. A customer mentions a pain point in passing — not a ticket, not a complaint, just a friction they mention while asking about something else. The current tool categorises this as a "Feature Request" signal type but produces no output for the internal side: what do you tell the product team, how do you frame it, who should it go to? Feedback routing is an internal communication task, not a customer response task. It needs its own mode.

Note The brief says the CSM is "the first person to dig into customer issues, often solving them yourself rather than immediately passing to support." The current escalation mode starts from the assumption that escalation is likely — it helps you decide how to escalate, not whether you need to. A first-line debugging mode flips this: given a PostHog error or technical complaint, work through a structured diagnostic first. Common patterns worth encoding: SDK not initialising (autocapture vs. manual event setup), events ingesting but not appearing in dashboards (ingestion lag, property schema mismatch, team data isolation), feature flags not resolving (targeting rule logic, local evaluation vs. remote), session replay gaps (CSP headers blocking the script, sampling rate, rage click thresholds). Solving these before escalating is faster for the customer and builds trust faster than routing.

Decision "Your aim is to never be surprised when a customer tells us they are leaving." That's not a workflow tip — it's an architectural requirement. The red flag list handles the reactive case (the customer signals something). But the proactive case — an account that's been quiet, whose usage has drifted, whose champion hasn't been seen for three weeks — requires scanning across all accounts on a schedule, not waiting for a signal to arrive. The red flag digest (roadmap item 3) is the implementation of this principle. The devlog should name the principle explicitly so it's clear what that roadmap item is actually solving.

Note The current tool is almost entirely reactive: something arrives, you process it. But the brief describes a proactive role — building relationships, watching health data, acting early. A good CSM probably runs 70% reactive and 30% proactive at minimum, and the proactive side is what separates great from average. Proactive outreach that adds value (sharing a relevant PostHog feature update, noting that their funnel conversion has improved since they implemented the flag they asked about) builds the relationship differently than "just checking in" messages. The tool has no playbook for this yet.

Note Self-served customers who've never spoken to anyone at PostHog represent a specific timing problem. Too early (day 2, before they've done anything meaningful) and it feels like surveillance. Too late (day 45, after they've already decided it's not working) and you missed the window. Best practice in PLG CS suggests 14–21 days is the sweet spot: enough time to have done something, not so long that frustration has set in. But the trigger should be activation-based, not time-based — reaching out when they've completed a meaningful action (first dashboard created, first flag deployed) lands better than a calendar-triggered message. The tool has no playbook for this specific flow.

Note The red flag list currently mixes leading and lagging indicators without distinguishing them. Lagging: "evaluating alternatives", billing frustration, explicit complaints — the customer is already partway out the door. Leading: usage drop, contact silence, low feature adoption despite high ARR — the customer hasn't decided to leave but the trajectory points there. The tool's health assessment treats all signals the same. A more sophisticated health model weights leading indicators higher for early intervention, because by the time the lagging indicators appear the window for intervention is narrower. Worth encoding this distinction in V2's health scoring.

Note The brief explicitly invites automation: "If you want to build automations to help you, go for it." At $20k–$100k ARR, the automation stack that would make the biggest difference: (1) PostHog's own API for usage data — query event volumes, feature adoption rates, and DAU per customer on a schedule; (2) Stripe webhooks for billing signals — overages, upcoming renewals, failed payments; (3) Slack message frequency monitoring per customer channel. These three data sources cover the three dimensions of customer health (product, commercial, relationship) and none of them require complex infrastructure. This tool is the first layer — prompt engineering and domain knowledge. The next layer is piping real data into those prompts automatically.

Decision The PostHog CSM role covers 25–40 paying accounts simultaneously. The challenge isn't that any individual account is hard — it's that you have 35 plates spinning at once and you need to know which ones are wobbling. This tool is about cognitive load reduction, not just triage. The output isn't just "here's a draft reply" — it's "here's what this signal means, how urgent it is relative to everything else on your plate, and exactly what to do next."

Decision Support triage is about ticket severity — what urgency level and what's a good first response. CSM work is a different layer. The CSM owns the commercial relationship, not just the technical issue. A billing question from a $100k enterprise customer is a different signal to the same question from a $20k self-serve account — same words, completely different stakes and required response. A generic triage tool can't make that distinction without bespoke encoding. Separate tool, separate prompt architecture.

Decision Sales-known and self-served customers need different handling at every layer. Sales-known: has an established relationship, expects warmth and memory of past context, reads absence of contact as neglect. Self-served: has never spoken to a human at PostHog, high silent churn risk, first contact must feel like a knowledgeable friend not an account manager chasing a renewal. Getting the tone wrong with a self-served customer — especially on first contact — can permanently poison the relationship. This distinction is encoded into every mode's output logic.

Decision A CSM's day involves several distinct cognitive tasks: reading incoming signals and prioritising them, drafting responses, deciding when and how to escalate, and periodically reviewing account health. These share the same input (customer context + a signal) but produce completely different outputs. Rather than four separate tools, one surface with mode tabs keeps the context panel persistent and reduces the "start over" friction. The mode selector changes the system prompt; everything else stays the same.

Decision Priority isn't just severity of the issue — it's severity × relationship weight × commercial stakes. The same billing question rates differently at $20k vs. $100k+ ARR. The same technical issue rates differently at 1 month tenure vs. 2 years — a new customer hitting a bug is more likely to churn than an established one. Encoding this into the triage prompt means the CSM gets recommendations calibrated to the actual account, not just the ticket surface.

Note The base prompt encodes PostHog's six core products with a one-liner on each: Product Analytics, Session Replay, Feature Flags, A/B Testing, Error Monitoring, Data Pipelines. Error Monitoring is flagged as newer and still growing adoption — relevant because customers using it are higher engagement signals, and bugs/limitations there carry more frustration because the product is still maturing. This context lets the model give product-specific recommendations rather than generic SaaS advice.

Note PostHog's billing model is credit-based. Customers buy event/session bundles upfront. This means usage spikes create billing surprises — a customer's usage doubles and suddenly they're out of credits and getting throttled, or they get an unexpected overage invoice. This is a friction pattern specific to PostHog and not common to SaaS broadly. Encoding it means the model recognises "we're running low on credits" signals as commercial moments requiring a specific kind of response (renewal conversation, usage review), not just billing support.

Decision The red flag list in the prompt isn't a generic churn signal list — it's a set of specific behavioural patterns that precede churn in CSM work: usage drop thresholds, silence windows, specific language patterns, renewal proximity combined with any negative signal. These are things an experienced CSM develops instinctively over years. Encoding them explicitly means the tool can surface them even when the CSM is on their 20th message of the day and their pattern-matching is depleted. The goal is to be the fresh pair of eyes that never gets tired.

Note "Maintaining customer integrity" was the explicit brief: responses must feel personal and genuine, not like they came from a template engine. The draft prompt explicitly instructs the model to avoid openers like "Hope you're well!", to calibrate warmth to customer type, and to never use placeholders. This is a quality floor, not a stylistic preference. A CSM who sends template-y responses to 35 accounts will eventually lose relationships because customers notice — and the damage accumulates silently before they say anything.

Decision The escalation mode offers five levels: Solo, Support Engineering, Product Team, Manager/Leadership, Executive. This isn't just taxonomy — each level implies a different internal action and a different external message. Getting the escalation level wrong in either direction is costly: under-escalating a commercial risk leaves a $100k account unprotected; over-escalating a technical question burns internal capital and signals poor judgement. The mode produces both an internal handoff draft and a customer-facing holding message, because both need to happen simultaneously and both need to be calibrated.

Note The health mode is designed for periodic account reviews, not reactive triage. The output includes a Green/Yellow/Red score, a key signals breakdown (positive and concerning), renewal and expansion risk, and 30-day recommended plays. The plays are intentionally specific enough to schedule — not "check in with the customer" but "book a usage review call to address the Session Replay adoption gap from last month". Vague action items don't get done. Specific ones do.

Issue Real customer health monitoring would pull live data: product usage metrics, Stripe billing data, Slack message frequency, ticket open rates. This tool works entirely on what the CSM pastes in. That's a genuine constraint — a health assessment is only as good as the signals the CSM provides. It's a copilot, not a dashboard. The roadmap includes account snapshot cards (localStorage persistence) to reduce context entry friction, and a batch red flag digest to do proactive portfolio scanning — but real data integration would need a backend.

Note The job description calls out multi-threading explicitly: knowing key people at each company, managing escalations across stakeholders. The current tool handles single-signal, single-account responses. Multi-threading intelligence — "you have the technical champion but not the business buyer, and renewal is in 60 days" — requires persistent account state across contacts. That's account snapshot cards in v2. For now, the context notes field is the escape hatch: the CSM can paste relationship context manually and the model will factor it in.

Decision Haiku 4.5 is default. For the majority of signals — a Slack message, a ticket, a quick health check — Haiku is fast and sufficient. The nuance in the output comes primarily from the prompt engineering and the customer context, not model capability. Sonnet is recommended for complex escalation strategy decisions or health assessments where you're weighing multiple signals against each other. Same cost confirmation pattern as the other portfolio tools: no Sonnet request fires without the user seeing a price and acknowledging it.

Decision Anthropic's prompt caching feature lets you mark a prefix of the context (e.g. the system prompt including the full KB) as cacheable. First call is a cache miss — costs 125% of normal input rate. Subsequent calls within 5 minutes are cache hits — cost 10% of normal input rate. For a 60K char KB, that flips the input cost from ~$0.012 per query to ~$0.0012 on cache hits. 10× reduction on KB token cost for free, effectively. Constraint: requires a backend. Prompt caching only works on server-side API calls — you can't send the cache-control headers from a browser. So this step means adding a thin proxy: one serverless function that holds the KB, manages the cache headers, and forwards the user's question. At low volume, serverless costs near nothing. This is the right first step once query volume justifies it.

Decision An option that stays within the current client-side architecture: a one-time preprocessing step where Claude reads the full KB and produces a compressed, Q&A-optimised version. Paste your 60K char policy docs, click Compress — Claude distills them down to the 15K chars of actual answerable facts. Store the compressed version in localStorage. Every subsequent query uses the smaller, cheaper version. Cost: one API call upfront (~$0.013 for a 60K char doc), then ongoing savings on every query. No backend required. The honest trade-off: compression is lossy. A distilled KB won't answer every edge case the original would — it suits a broad FAQ better than a technical manual where exact wording matters. Useful as an intermediate step before adding proper infrastructure.

Note Retrieval-Augmented Generation is the full answer to the re-reading problem: chunk the docs, embed each chunk once using a cheap embedding model (text-embedding-3-small costs ~$0.02/MTok — a 100-page doc embeds for under a cent), store the vectors, and at query time retrieve only the 2–3 most relevant chunks to send alongside the question. Queries go from sending 15,000 tokens to sending ~500. Cost per query drops by ~96% compared to the current full-KB approach. The infrastructure price: you need an embedding model, a vector store, and retrieval logic. That's a real architectural step up. It makes sense when the KB is too large for context-window retrieval to work cleanly, or when you're handling enough volume that even prompt-cached queries add up. Not the right first step — but the right answer at scale.

Done v0.3 live. Debounced KB save + beforeunload safety net. API cost unchanged. Browser overhead reduced significantly on large KBs.

Note To be direct: debouncing has zero effect on Anthropic API spend. localStorage is entirely client-side — Anthropic never sees it. The only things that drive API cost are KB size (input tokens per query), conversation history length (accumulates across turns), and how often someone hits Ask. None of those change. What debouncing does affect is browser resource usage: localStorage.setItem is synchronous and serialises the full KB string on the main thread on every call. With a 60K char KB and 300 keystrokes in an editing session, the old approach meant ~18MB of data serialised to disk in a few minutes — wasteful and jank-inducing on older hardware or mobile. Debouncing turns those ~300 disk writes into roughly one. Right pattern, wrong reason to expect cost savings.

Decision Switched from saving on every keystroke to a debounced save: the write only fires 800ms after the user stops typing. A beforeunload listener acts as a safety net — if the tab closes before the debounce timer fires, the save happens immediately on the way out. The "saved locally" badge still appears as soon as the user types (it's not delayed), so the UX is unchanged.

Done v0.2 live. KB persists via localStorage with saved/clear indicator. Multi-turn conversation thread with per-exchange cost and copy buttons. Session total cost shown in conversation header. New Chat button to reset. QIGO note in KB panel. All constraints documented above rather than hidden.

Decision Added a "quality in, quality out" note at the bottom of the KB panel. It's subtle — small, italic, monospace — but it sets the right expectation before anyone hits Ask. Vague docs produce vague answers. A one-line FAQ that says "we have a refund policy" without explaining what it is will produce an answer that says "we have a refund policy" without explaining what it is. The tool is only as good as what you feed it.

Note Nothing stops someone from editing the KB while a conversation is in progress. If they do, subsequent answers draw from the updated KB, but earlier answers in the same thread used the old one. The conversation thread could silently contain contradictions. The tool doesn't warn about this. For a demo, it's acceptable. For anything real, the KB should be locked for the duration of a session, or the UI should force a new chat when the KB changes.

Issue Conversation history accumulates input tokens on every turn. The KB (~15K tokens for a 60K char doc) dominates cost early on — each exchange adds maybe 100–400 tokens of conversation context, which is 1–3% extra per turn. By exchange 10, the history might add 2,000–4,000 tokens, roughly a 15–25% cost increase per call compared to turn 1. The KB itself doesn't change; it's the conversation that grows. Capped at sending the last 20 messages (10 exchanges) to the API to prevent runaway costs on very long sessions. The full visual history is always shown — only what gets sent to the API is trimmed.

Decision Added a conversationHistory array that accumulates each Q&A pair. Every call to the API now includes the full exchange history alongside the system prompt, so follow-up questions work: "Can I return it?" → "How long will that take?" carries context correctly. A "New Chat" button resets the history and wipes the conversation thread. The question textarea clears after each submission so the next question is always a fresh input.

Issue The stored KB sits in plain text in the browser's localStorage, visible to anyone who opens DevTools → Application → Local Storage. Any JavaScript running on the page can also read it. For a public FAQ this is irrelevant. For a company storing internal pricing, HR policies, or anything sensitive — don't use client-side storage. This is another reason the right production architecture keeps the KB server-side, behind authentication, with the client only ever receiving the answer.

Issue localStorage is browser-and-device-specific. Two people using the same browser on the same machine share the same stored KB — one person's company docs will silently appear for the next user. Conversely, someone who sets up the KB on their desktop opens a blank KB on their laptop. For a single-user demo tool this is acceptable friction. For any kind of team deployment it's a problem that only a server-side KB solves. Also worth noting: "clear browsing data" wipes localStorage with no warning. Users who clear their browser routinely will lose the saved KB and may not immediately realise why.

Issue localStorage doesn't know your docs changed. A company updates its refund policy in January; the stored KB still says December's policy. The tool gives confidently correct answers based on outdated information. There's no version check, no sync, no expiry. For this demo tool, the mitigation is user discipline — clear and re-paste when docs change. In a production deployment, the KB would live server-side and be updated there; client-side storage wouldn't be in the picture at all.

Issue Permanence is a silent cost amplifier. Every query re-sends the full KB regardless of how long it's been sitting in storage. A user who pastes a 60K char KB (~15K tokens) and walks away for a month is still paying ~$0.012 per query in input tokens every time they return — and they might not remember how large their KB is. At low volume this is trivial. At 1,000 queries/month against a large KB, input costs alone run ~$12. It's still cheap, but it's no longer invisible. Production deployments with a backend could cache the system prompt using Anthropic's prompt caching feature, which reduces repeated KB costs by up to 90% — but that requires a server.

Decision Saved the knowledge base to localStorage on every keystroke. It survives page refreshes, tab closes, and browser restarts on the same device — so you set up your docs once and they're there next session. A "saved locally" badge appears in the KB panel header, with a clear link if you want to wipe it. 60K chars = ~60KB, well inside localStorage's ~5MB per-origin limit.

Done v0.1 live. Two inputs (KB + question), one output (answer), cost shown per query. Character counters with soft warnings at 20K chars for the KB and 500 chars for the question. Hard truncation at 60K / 1K with an injected note so the model knows input was cut.

Issue Constraints: Cost scales linearly with KB size — not a problem at small scale, matters at volume. No conversation history: each question is independent, so follow-up questions don't carry context from the previous answer. API key is client-side, so it's visible in the browser's network tab — fine for a demo, not for production. No logging or analytics out of the box. Can't handle non-text content (images, tables in PDFs, charts). Beyond ~60K chars, a proper RAG pipeline is the right answer.

Done Wins: Zero infrastructure for the demo. Works with any plain text KB — no preprocessing required. Claude's semantic understanding handles paraphrased questions that would defeat keyword search. Grounded by design: explicit fallback when the docs don't cover something. Cheap enough to run as a real tool, not just a demo. One file, shareable as a direct link.

Note Production path for a real client deployment: add a thin backend (a single serverless function works) that holds the API key, rate-limits requests, and optionally caches responses for common questions. The KB can be stored server-side so clients never see it. The system prompt, grounding rule, and model call are identical to this demo — the only thing that changes is where the API key lives.

Issue The 60K char hard limit in this tool is a practical ceiling, not a model limit. Claude can technically handle much more. But past ~60K chars, you're paying meaningfully per query and the user experience of pasting 100K chars into a textarea is poor. For larger knowledge bases — multi-section product docs, extensive policy manuals — the right answer is a proper RAG pipeline: chunk the docs, embed them, and retrieve only the relevant chunks per query. This tool demonstrates the concept; that's the production version.

Issue Every query re-sends the full knowledge base. A 5K char FAQ costs ~$0.001 per query. A 60K char KB costs ~$0.01. Still cheap in absolute terms, but if you're handling 10,000 queries a month against a large KB, you're looking at ~$100/month in input tokens alone — before output. For high-volume use, caching common answers or splitting the KB by topic would reduce this significantly.

Tried Considered adding streaming output so the answer appears word-by-word. FAQ answers are 2–4 sentences and Haiku responds in under 2 seconds. Streaming adds code complexity and browser compatibility surface area for a response that's already fast enough to feel instant. Dropped.

Decision Model: Claude Haiku 4.5. Max output: 600 tokens. FAQ answers are 2–4 sentences — even a generous response rarely hits 200 tokens. 600 gives headroom without waste. Haiku handles this pattern easily; Sonnet is overkill and 10× more expensive per query.

Decision The system prompt contains one critical rule: if the question cannot be answered from the knowledge base, respond with a specific "I don't have that in our documentation" message. Without this, Claude will produce a confident, helpful, entirely fabricated answer. The grounding constraint is the whole point of the tool — it's what makes it trustworthy rather than just fluent.

Note Why this works: Claude Haiku has a 200K token context window — roughly 150,000 words, or about 250 pages of text. Most company FAQ docs are well under 10,000 words. The entire knowledge base fits comfortably, and Claude's comprehension across that context is strong enough for straightforward Q&A. This is sometimes called "long-context retrieval" — using the model's context window as the retrieval mechanism instead of a separate search system.

Decision The knowledge base goes directly into Claude's context window as part of the system prompt. No vector database, no embedding model, no similarity search. Claude reads the entire KB and finds the relevant section itself — the same way a human would skim a help doc.

Decision Same architecture as the other tools: single HTML file, no backend, GitHub Pages. The pattern works — a static file with a client-side API call is shareable as a direct link with zero setup. No reason to introduce a server unless we need one.

Note Removed "no session history" from constraints after reviewing whether it was actually a limitation. It isn't — each interaction is self-contained (video + comment → reply, topic → ideas). There's nothing to compare across sessions and nothing that would improve with persistence. It was a reflexive constraint, not a real one.

Decision Added a stage log panel that shows each fetch and API step as it runs, with per-stage ✓/✗ states. Replaces silent failures with visible progress — you can see exactly where a fetch degraded and why, rather than getting an unexpected result with no explanation.

Decision Added a YouTube URL field to Comment Reply. Fetches video title via YouTube's oEmbed endpoint (free, no key, CORS-enabled) and description excerpt via Jina Reader. Both are non-fatal: oEmbed failure = no video context at all, Jina failure = title-only context. The system prompt forks based on what was retrieved. A "video context used" tag appears on the reply panel so it's clear when the context was applied.

Pivot Replaced the Video Ideas text parser with Claude's tool use API. Defining a JSON schema and forcing tool_choice: {type: "tool"} means the model returns structured data regardless of how it phrases the response. No more numbered-list parsing, no fallback needed. Every field is validated individually with a specific error message if missing.

Issue Two constraints from v1 were worth fixing immediately: the text parser for Video Ideas was brittle against model formatting changes, and Comment Reply had no knowledge of which video the comment was on — making it generic lore-nerd rather than video-specific.

Done v1.0 live. Video Ideas renders five idea cards (title in gold, hook in italic). Comment Reply renders a bordered panel with a copy button. Parser falls back to raw pre-formatted text if the model deviates from expected structure. API key validation strips non-ASCII before any header is set — same fix as the Lore Checker.

Decision Stored the last reply text in a lastReplyText module-level variable rather than encoding it into the onclick attribute via JSON.stringify. The attribute approach works but gets fragile with long replies or special characters; a variable is clean and safe.

Decision Comment Reply system prompt explicitly bans sycophantic openers by name ("great question", "love this", "so glad you asked"). Without this, Claude defaults to them. Named the persona as LoreBySpec rather than "a YouTube creator" to anchor the voice more specifically.

Decision Video Ideas prompt specifies exactly 5 ideas in a strict numbered format: N. [Title]\nHook: [sentence]. The renderer parses this into cards. Chose structured plain text over JSON because the output is simple enough and the formatting instruction is clear — JSON mode adds a layer for no gain here.

Decision Fixed model at Haiku 4.5 — no model selector. Both tasks (brainstorming titles, drafting short replies) are well within Haiku's capability. Adding a Sonnet toggle adds UI complexity without a meaningful quality difference for 2–5 sentence outputs.

Decision Used anthropic-dangerous-direct-browser-access: true to call the Anthropic API directly from the browser, skipping the Cloudflare Worker proxy used in the Lore Checker. This tool doesn't need to fetch external URLs (no Jina, no wiki pages), so there's no reason to route through a relay. Simpler and one fewer moving part.

Decision Combined both modes (Video Ideas, Comment Reply) into a single file rather than two separate tools. They're lightweight, share the same API key, and both serve the same pre-production workflow. A toggle is cheaper than a navigation layer.

Decision Same single-file, no-backend pattern as the Lore Checker — static HTML, GitHub Pages, bring-your-own API key. Both tools are for the same channel so they share visual DNA; different enough in layout to feel like their own thing.

Pivot The RNIB's audio rejection was specifically about voice output — "pregnant" or "not pregnant" spoken aloud. The problem is words, not sound. Words carry emotional weight regardless of tone or inflection. A bleep carries none. Additionally: not all pregnancy results are good or wanted. A positive result can be devastating depending entirely on context. Any audio format using language presumes something about the emotional register of the moment. Tones do not. This reframes the RNIB finding: not "no audio" — "no words."

Note SPD/Clearblue holds no patent on audio output from a pregnancy test — a gap in their portfolio, and not a blocker for a partnership conversation. Third-party patent WO2014158850 ("Diagnostic Test Device with Audible Feedback") covers audio output on lateral flow readers and requires freedom-to-operate analysis before any audio hardware is commercialised. FDA regulatory path confirmed: Class II, new 510(k) required for audio addition, 12–24 month timeline, $250K–$1M cost. Manufacturer entry point: Clearblue Innovation Centre, Bedford, UK. The conversation needs a working prototype, market size data, and a regulatory summary. We do not yet have all three.

Pivot The RNIB's 2020 accessible pregnancy test prototype — the most thorough user research in this space — found blind users did not want audio output. Any tone or voice sounds either positive or negative, and users did not want a machine to telegraph the emotional outcome before they were ready. RNIB used tactile output. APT (James Dyson Award 2022) independently reached the same conclusion and used haptic. This directly challenges our audio-first design. Revised position: haptic is a first-class output modality, not a fallback. The design must support haptic-only as a complete, uncompromised experience. Community research now the immediate priority before any UX decisions are locked.

Done Clearblue Digital MCU confirmed as Holtek HT48C06 / HT48R065B — off-the-shelf 8-bit OTP parts with public datasheets, not custom ASICs. Critical finding: the HT48C06 has dedicated buzzer drive pins (PB0/PB1) and a programmable frequency divider built into the silicon. Connecting a piezo element requires no external driver. The hardware to make the stick beep already exists inside it. The reason it makes no sound is a product decision, not a hardware limitation. Enclosure moulding tolerances are the actual constraint — any audio addition requires a new enclosure SKU, not a modification to the existing one. OTP firmware is unreadable; any partner would need to rewrite sensing logic from scratch.

Decision Progressive Web App for Phase 1: no app store, no install required, shareable as a URL, GitHub Pages hosting (free), TensorFlow.js for on-device inference (no API cost), Web Speech API for audio (no API cost), service worker for offline use. Running cost is near-zero — there is no server, no database, nothing to pay for monthly. This is not a compromise: an accessibility tool that eventually needs revenue is one that has failed its primary goal.

Decision "The test shows a positive result" rather than "You are pregnant" — clinical framing is less culturally variable, easier to keep grammatically neutral across gendered languages, and more defensible from a regulatory standpoint. Priority languages: English, Spanish, Arabic, French, Portuguese, Hindi. All result strings professionally translated with medical language awareness — no string ships to production on machine translation alone. RTL layout (Arabic, Urdu, Hebrew) is a layout requirement, not a post-launch fix.

Decision Privacy policies are words. Code is evidence. The codebase is public from day one so any developer can verify that the app does exactly what it claims — no image retention, no analytics, no data leaving the device. Equity testing (model performance across all test brands, lighting, device quality tiers) is a release requirement. The tool is free, permanently. No premium tier, no advertising, no data brokering.

Decision Auto-speaking a result on the phone speaker is never acceptable. A shared bathroom, a public toilet, a partner in the next room — any of these makes unsolicited audio a privacy breach. Default: haptic pulse signals result is ready, audio only on tap. Two optional modes: earphone-only (auto-speaks when headphones detected, silent on speaker) and delay timer (10–60s pause before the haptic fires, letting the user move somewhere private). The auto-speak-on-speaker mode does not exist in the architecture.

Issue A false positive or false negative in this context carries real psychological and medical consequences. The model ships with a confidence threshold — below it, the result is "inconclusive, re-check recommended", never a confident wrong answer. Language is always "the test shows" not "you are." Reliability is a release gate, not a metric to improve post-launch.

Decision Three parallel workstreams: (1) Build a smartphone prototype using ML Kit for on-device line detection — validate whether recognition is reliable enough across different test brands and lighting conditions. (2) Tear down a Clearblue Digital test and document the PCB — identify chipset, output pins, and whether audio addition is feasible without redesign. (3) Reach out to blind and low-vision communities for lived experience input before locking any UX decisions.

Note If the smartphone path has reliability limits and manufacturer partnerships aren't viable, a standalone reader accessory becomes the fallback. Concept: a small clip-on device that holds the test in a fixed position, uses a colour sensor (TCS34725 or similar) to read line intensity, and outputs audio + haptic. Powered by coin cell. Single-use pairing with standard test formats. Estimated BOM: under £5 at volume.

Decision Audio output has real constraints: public spaces, shared housing, headphone availability, hearing impairments among the target group. Designing a haptic fallback: single long pulse = negative, two short pulses = positive, repeating triple pulse = inconclusive / error. Simple enough to learn once, distinctive enough not to misread. Mirrors how screen readers handle notification priority.

Note Most line-based tests are valid to read within a 3–10 minute window. Faint lines fade. A reader that takes 30 seconds to boot or requires multiple repositioning attempts isn't usable in practice. Speed and first-attempt reliability are non-negotiable. Digital tests hold their result for ~6 minutes, which gives more working time.

Issue Anything classified as part of a diagnostic process falls under FDA (US) or MDR (EU) medical device regulation. Critical distinction: a tool that reads the visual output of an already-completed test is an accessibility aid, not a diagnostic device. The test itself is the regulated product; the reader is not. This distinction must be maintained in product design and language throughout.

Note Clearblue Digital tests contain a microcontroller, LCD panel, and battery — all to display two words. The electronic reading stick re-uses the same lateral flow strip underneath but processes the optical result internally. Key question: does the MCU expose any output pins? If it does, adding a piezo buzzer or BLE chip is a hardware addition, not a redesign. Filed as a research thread.

Pivot On-device ML is the answer. Apple's Vision framework and Google's ML Kit both run image classification on-device with no data leaving the phone. For line detection (one line vs. two, or a digital LCD reading "Pregnant") the model complexity is low — well within what a phone can handle offline. Privacy preserved by default.

Issue Cloud vision APIs (Google Vision, Claude vision) would send an image of the test to a remote server. That's a photo tied to a health event — possibly the most sensitive moment in a person's reproductive life. Sending it to any third-party server, even one with strong privacy policies, is an unacceptable default for this use case.

Decision Phase 1 targets the most accessible hardware: the smartphone everyone already owns. Approach: point camera at test → recognise the result → speak it aloud. No new hardware, no app purchase required. Works with standard pregnancy test formats (line tests and digital). This is the fastest path to impact.

Note Clearblue Digital tests (and similar) already show "Pregnant" / "Not Pregnant" as text on an LCD screen. This is the closest existing accessibility accommodation — high-contrast text is easier to read for low-vision users with magnification tools. But it produces zero audio, zero haptic output. The hardware exists; the output modalities don't.

Tried Checked what already exists. Be My Eyes and Aira connect blind users to sighted volunteers or AI descriptions via camera. Technically usable — but both require broadcasting a live video feed of a pregnancy test to a third party (volunteer or company server). Privacy cost is too high for a result this personal. Not a viable general solution.

Decision The problem is narrow and specific: a blind pregnant person taking a home pregnancy test has no independent way to read the result. Every current path requires involving another person. That's not an edge case — it's a structural gap. Starting from that constraint rather than "make pregnancy tests accessible" keeps the scope tractable.

Decision Bulk mode design: accept a batch of tickets (newline-separated or numbered), run them through the existing triage pipeline one at a time in a loop. One API call per ticket — same ~0.2¢ cost model, no change to the prompt, no queue infrastructure. The output becomes a table rather than three panels. Same architecture, bigger input.

Decision CSV export design: pure client-side via the Blob API. After a bulk run, serialise each row (ticket text, category, urgency, suggested response) into a CSV string, wrap in a Blob, create an object URL, trigger a download. No server, no data leaves the browser. The file is generated and consumed entirely in the tab — consistent with the no-backend constraint and no new privacy surface.

Done Confirmation modal live. Pricing displayed uses the current rates ($3.00/M input, $15.00/M output, dated May 2026) so it's transparent about when those figures were last updated. No request fires on Sonnet without acknowledgement. Haiku requests are unaffected — no friction for the common case.

Note The confirmation covers both manual and auto-switched Sonnet use — there's no meaningful distinction from a cost perspective. What matters is that the user sees a number, reads a price, and chooses to proceed. Implemented as a Promise-based overlay: triage() awaits confirmSonnetCost(), which resolves true on confirm and false on cancel, so the async flow is clean and the request is never partially started.

Decision Add a pre-flight confirmation modal that fires whenever a Sonnet request is about to be sent — whether the user manually selected Sonnet or the tool auto-switched. The modal shows the exact character count at click time, recalculates the cost fresh from the current message length, and requires an explicit "Send anyway" before the request fires. Cancel returns to the tool with no side effects.

Issue Follow-up from Rainbow: the live cost estimate in the model bar is useful, but it doesn't force the user to acknowledge the cost before they commit. A user could auto-switch to Sonnet, not notice the estimate update, and send a large request without realising the price difference. The model bar display is passive — it updates, but it doesn't interrupt.

Done Model bar live: Haiku selected by default with a "recommended" badge, Sonnet available for longer or higher-stakes tickets. Truncation bug fixed — total sent is always ≤ hardLimit. Cost estimates update on every keystroke. The lore checker already had this pattern; applying it here was straightforward once the right constants were in place.

Note Cost estimates update live as you type. Formula: input tokens estimated as 250 (prompt overhead) + ceil(messageLength / 4), output fixed at 300 tokens. At empty the display reads ~0.20¢ (Haiku) and ~0.60¢ (Sonnet). A 5,000-char message costs about ~0.28¢ on Haiku; the same at 10,000 chars on Sonnet is about ~1.05¢. The estimates are approximate — actual tokenisation varies — but they give the user a real-time sense of relative cost.

Note Auto-switch logic: if the user types past 5,000 characters while on Haiku, the tool silently switches to Sonnet and shows a small amber badge — "auto-switched — input over 5k". If they delete back below 5,000, it reverts to Haiku. If the user manually picks a model, autoSwitched is cleared and the auto-revert no longer fires — their choice takes over.

Decision Add a Haiku / Sonnet model switcher — borrowed from the lore checker pattern — to solve the truncation bug properly and add cost transparency at the same time. The fix: define TRUNCATION_NOTE as a constant, slice to hardLimit - TRUNCATION_NOTE.length before appending, so the total is always exactly hardLimit. The switcher makes hardLimit model-dependent: 5,000 chars for Haiku, 10,000 for Sonnet.

Issue Rainbow spotted a bug in the character limit: slicing input to exactly 5,000 characters and then appending '\n\n[Input truncated at 5,000 characters]' (36 chars) sends 5,036 characters to the API — silently exceeding the stated limit. A small off-by-one in principle, but it breaks the contract with the user and means the truncation note itself is the overflow.

Done Both tools confirmed working end-to-end — support triage and lore checker tested live with a real API key and real input. The proxy resolves the CORS issue across all browsers. Removed the "best on desktop" browser warning from the tools since it's no longer accurate. Total time from "Load failed" with no context to a working cross-browser solution: one debugging session, one Cloudflare account, 25 lines of Worker code.

Done Cloudflare Worker deployed at anthropic-proxy.work-specious.workers.dev. 25 lines. Handles CORS preflight (OPTIONS → 204 with Access-Control-Allow-Origin: *), forwards POST to Anthropic server-to-server, returns response with CORS headers attached. All three tools updated to call the proxy instead of api.anthropic.com directly. Worker code saved to proxy/worker.js in the repo. Free tier covers 100,000 requests/day — more than enough for a portfolio demo.

Note This affects all three tools — lore checker, support triage, FAQ chatbot — since all use the same fetch pattern and the same header. The anthropic-dangerous-direct-browser-calls approach does not work from iamspecious.github.io. The no-backend architecture has hit its hard limit for this use case. Decision: deploy a Cloudflare Worker as a thin CORS proxy — handles the preflight server-side, free tier (100,000 requests/day), no infrastructure to maintain, works everywhere. A non-working portfolio tool demonstrates nothing; a tool that works and has a documented fix for a real architectural problem demonstrates more than one that never broke.

Note The anthropic-dangerous-direct-browser-calls: true header is supposed to signal Anthropic's server to return Access-Control-Allow-Origin in its preflight response. The mechanism breaks at the preflight stage: the browser sends an OPTIONS request first, the server must include CORS headers in that response, and only then does the browser allow the actual POST through. Anthropic's server is not returning those CORS headers for the iamspecious.github.io origin — so the POST never fires. The header exists in the request the browser intends to send, but the server's OPTIONS response contains no CORS headers at all.

Issue Chrome console test on desktop, fresh install, no extensions, GitHub Pages origin. Exact error: "Access to fetch at 'https://api.anthropic.com/v1/messages' from origin 'https://iamspecious.github.io' has been blocked by CORS policy: Response to preflight request doesn't pass access control check: No 'Access-Control-Allow-Origin' header is present on the requested resource." The domain is reachable (api.anthropic.com returns 404 at root, as expected). The failure is CORS, not DNS, not network, not key format.

Note The fundamental constraint here is the "no backend" architecture. A backend proxy would handle the API call server-side and return the result to the browser — no cross-origin request, no CORS, no preflight, works everywhere including iOS Safari. But adding a backend contradicts the design constraint and the point of the demo: to show what you can build and deploy without infrastructure. That trade-off is real and documented. The right answer for a production tool is a thin backend. The right answer for a portfolio demo is the browser compatibility notice.

Decision Added a browser compatibility notice to both tools — displayed above the API key bar. States clearly: best on desktop, Chrome and Firefox most reliable, mobile Safari may block cross-origin requests. Includes the iOS-specific workarounds: disable Content Blockers (Settings → Safari → Content Blockers), disable iCloud Private Relay, or try Chrome/Firefox for iOS.

Note Mobile Safari also has no accessible developer console on-device. The "open F12 → Console" instruction in our improved error message is useless on iOS — there is no F12. Debugging a network error on mobile Safari requires pairing the device with a Mac running desktop Safari and using Remote Web Inspector, or testing on a desktop browser instead. Two issues surfaced from one test: the CORS restriction and the unreachable console.

Issue Browser confirmed as mobile Safari on iOS. This is the specific environment where direct cross-origin API calls are most restricted. When a request includes custom headers (like x-api-key and anthropic-dangerous-direct-browser-calls), the browser fires a CORS preflight OPTIONS request first. iOS Safari handles this preflight more aggressively than desktop browsers — in some iOS configurations it blocks the request entirely before we get any response.

Note Applied the same error handling improvements to the FAQ chatbot — it had identical single-line catch block with the same gap. Any tool making direct browser API calls needs this treatment. The lesson: a generic catch block is not error handling, it's error hiding. Stage-specific messages let users actually diagnose what went wrong instead of guessing.

Decision Rewrote error handling across three stages. Stage 1 — before the request: validate that the API key starts with sk-ant- and show a specific message if not. Stage 2 — API error response: break down !response.ok by HTTP status. 401 = bad key, 403 = no permission, 429 = rate limited, 400 = bad request, 500+ = server error. Each gets its own message and its own next step. Stage 3 — network failure: catch TypeError separately from other errors and show a specific "network error" message with instructions to open the browser console (F12 → Console) for the actual error. Also added console.error() logging so there is always a full trace available.

Note "Load failed" is what Safari throws when fetch() fails at the network layer before any response is received. Chrome calls it "Failed to fetch", Firefox calls it "NetworkError when attempting to fetch resource". All three are the same thing: the request never reached the API. Possible causes: a browser extension blocking api.anthropic.com, a CORS restriction, a firewall or VPN, or Safari's stricter cross-origin enforcement. The character cap was not the issue — the test message was under 200 characters.

Issue First real test with a live API key failed. Button returned "Load failed" — two words, no context, no HTTP status, no indication of where in the chain it broke. From a debugging standpoint, completely useless.

Note Updated the placeholder and system prompt to explicitly support error snippets, stack traces, and log excerpts. Structured text is actually easier to triage than messy prose — the model reads it cleanly. For log-only inputs the suggested response acknowledges the error and asks for context (steps to reproduce, environment, account details) rather than pretending it's a normal message.

Decision Added a character counter with a soft warning at 3,000 and hard truncation at 5,000 — applied client-side before the API call. Support tickets rarely hit this. Error logs and paste dumps can. Truncation keeps a runaway paste from spiking cost; a note in the payload tells the model what happened. The limit also keeps max_tokens at 1,000 and the system prompt compact — three short sections is all this needs.

Decision Switched model from Sonnet to Haiku. Triage is pattern recognition and professional writing — Haiku handles it comfortably. Cost drops from ~$1.80 to ~$0.42 per 1,000 triages. "Cents not euros" isn't a nice-to-have, it's a design constraint if this is going to be a viable tool rather than just a demo.

Note The prompt is the meaningful part of this tool. Knowing what signals push a ticket from Medium to High, what tone to set, what categories fit a given product — that's the support judgment this tool demonstrates. The code is a vehicle for the prompt.

Decision Added a copy button to the Suggested Response section. Not in the original brief, but practically obvious: in any real support workflow, the next thing you do after reading a suggested response is paste it somewhere. One click.

Tried First prompt draft had Claude return urgency as a 1–5 score. Dropped it. Labels (Low / Medium / High / Critical) are what support teams actually use in tooling, and they read faster at a glance. Mapped each to a colour indicator so urgency is visible before you read a word.

Decision Three outputs: Category, Urgency, Suggested Response. Category and Urgency are the triage layer. The Suggested Response is what turns classification into action — and the output that makes this demonstrable in an interview. "Here's the tool. Here's what it produces."

Decision One input box, one button. The brief was explicit about minimal surface area. Resisted adding dropdowns, severity sliders, ticket history. The AI does the categorisation — that's the whole point. Adding a form would undermine the argument.

Decision Same architecture as the KH Lore Checker: single file, no backend, GitHub Pages. If the pattern works for one tool, it works for two. The whole portfolio stays static and the tools are shareable as direct links.

Note Root cause: pasting an API key from certain sources (email, PDF, browser autofill) can silently introduce Unicode characters — zero-width spaces, smart quotes, non-breaking spaces — that are invisible in the input field but have code points above 255. HTTP headers only accept ISO-8859-1 (0–255), so the browser rejects the whole request.

Issue First real test threw: "Failed to execute 'fetch' on 'Window': Failed to read the 'headers' property from 'RequestInit': String contains non ISO-8859-1 code point." The other two tools passed. Headers are identical across all three tools — the only dynamic header is the API key.

Done v0.3 live. Model selector in UI shows live cost estimate per model. Estimate updates to show tokens, cost, and model name both during and after the call so there's a full paper trail per check.

Decision Reduced max output tokens from 1,500 to 900. Output tokens cost 5× more than input on Anthropic's pricing. The four-section analysis rarely needs more than 600 tokens in practice — 900 gives headroom without waste.

Decision Dropped URL fetch cap from 8,000 to 3,500 characters (~875 words) per page. KH wiki pages after Jina parsing still carry nav remnants and category lists. 875 words of actual article content is enough for the relevant section of any given page, and halves that input cost.

Decision Switched default model to Claude Haiku 4.5 — same Anthropic family, ~$0.001 per typical check (input: $0.80/MTok, output: $4/MTok vs Sonnet's $3/$15). Quality is more than sufficient for lore analysis; Sonnet remains available via toggle for dense multi-game theories.

Issue Goal is cents per check, not euros. v0.2 defaulted to Claude Sonnet (~$0.03/check). Fine occasionally, expensive if you're running it across 10 theories before a video. Needed a cheaper default.

Done v0.2 live. Both lore context and anchors panels now accept URL inputs alongside free-text. Token estimate and approximate cost shown in the UI before the API call completes, so there are no surprise charges.

Decision Each fetched URL is capped at 8,000 characters on the client before it's sent to Claude. Keeps individual page contributions predictable. Users can add multiple URLs — the right workflow is: link the specific wiki pages relevant to your theory, not the entire series.

Pivot Solved CORS without a backend: Jina Reader (r.jina.ai) is a free service that converts any URL to clean plain text and allows browser fetches. Paste a wiki link, it returns readable content. Zero setup, no extra API key.

Tried Considered direct fetch() to KHWiki / Fandom URLs from the browser. Blocked — external sites don't send CORS headers that allow browser requests. Would need a proxy or backend.

Note Real constraint isn't the text box (no cap) — it's Claude's context window (~200,000 tokens ≈ ~150,000 words) and cost. Sending entire wikis is technically possible but expensive and unfocused. A theory about BbS doesn't need all of KH3's lore.

Issue Kingdom Hearts spans 25+ years and 15+ titles. Pasting raw lore into a text box isn't realistic — the series wiki alone would blow past any reasonable input. Raised: is there a cap? What's the actual limit?

Done v0.1 live. Four output sections: Contradictions Found, Potential Weaknesses, Clarifying Questions, Overall Assessment. System prompt instructs Claude to write as a collaborator, not a judge — keeps the output useful for scripting rather than just academic.

Decision Three inputs: Lore Context (free-form canon dump), Hard Anchors (specific facts the theory must not break), and the Theory itself. Splitting context from anchors lets the AI treat them differently — context informs, anchors constrain.

Decision API key lives in the session only (not localStorage) — user pastes it each visit. Trade-off: slight friction, but no credentials ever persisted to disk or sent anywhere. For a personal creative tool this is the right call.

Tried Considered a mock/demo mode with hardcoded example outputs so visitors can see it work without an API key. Rejected — felt dishonest for a portfolio piece. A tool that actually calls the API is more compelling than a simulation.

Decision Approached this as a single-file, no-backend tool that can live on GitHub Pages. No server = no hosting cost, no auth complexity, and the portfolio stays purely static.

Done Verification pass in a sandbox: entity detection fired correctly, 3–5 hashtags returned, backend tags landed at 492/500. Zero errors.

Decision Backend tag generation: auto-generated from the same lore dictionary pass, then trimmed to YouTube's 500-char budget. No user input needed for this step.

Decision Hashtag logic: scan the input text against the lore dictionary, return 3–5. Always anchored by #KingdomHearts and #KingdomHeartsLore; user can add or remove chips before copying.

Decision Rewrite logic: keyword hook in first ~125 chars, 200–300 words of real context, chapter timestamps section, links section, CTA. [bracketed] placeholders for anything that needs a real URL or timestamp swapped in manually.

Decision Built the KH lore dictionary first — characters, worlds, terms, games — as the backbone for both hashtag detection and tag generation. Getting this right before writing rewrite logic meant the entity detection was grounded in actual KH vocabulary, not a generic gaming taxonomy.

Decision Pinned down scope before building: how the tool needs to fit the actual posting workflow, what YouTube's current description structure rewards, and where the lore constraint kicks in. Researched 2026 YouTube SEO best practice — description length, above-the-fold keyword placement, hashtag count, and the tags-vs-hashtags distinction.

Note Root cause confirmed. Diagnostics log: location.href: cowork-file://preview/kh_live_tool.html, iframed: false, typeof window.cowork: undefined, no globals matching cowork/claude/anthropic/mcp (only match was our own getCowork function). The sandboxed preview render doesn't inject the bridge — not a timing race, not a cross-origin frame, not an alternate global name. Zero-paste live generation parked; fallback is the supported path. Poller will pick the bridge up automatically if it's ever mounted.

Done Added a Run diagnostics panel: logs typeof window.cowork and its keys, whether the view is iframed, cross-origin reachability of parent/top, any window globals matching cowork|claude|anthropic|bridge|mcp, location.href, referrer, and userAgent. Output is copyable. Ran it — captured the data that closed the investigation.

Decision Shipped graceful fallback before root cause was known: when the bridge is unavailable, Generate builds the finished prompt in-page and renders it with a one-click Copy button. Flow degrades from 0 pastes to 1 paste. Tool is usable end-to-end regardless of what the runtime investigation finds.

Issue H2 attempt — hypothesis: cross-origin iframe hides the bridge. If the artifact renders in a cross-origin iframe, window.parent.cowork throws a SecurityError before returning. Fix: wrapped parent/top access in try/catch inside the poller. ❌ Still not found — no SecurityError thrown, meaning window.cowork is genuinely undefined in the frame, not obscured by an error.

Issue H1 attempt — hypothesis: bridge injected late (timing race). Wrapped the askClaude call in a getCowork() poller: checks window.cowork, window.parent.cowork, and window.top.cowork every 100ms for up to ~6s. ❌ Poller exhausted and returned null — bridge isn't late, it's absent for the full polling window.

Issue v3 first run threw: "Cannot read properties of undefined (reading 'askClaude')". window.cowork is undefined at call time — the LLM call never fires.

Done Rebuilt as a live Cowork artifact, light-mode themed to match. Same options as v2 (Curiosity/Bold Claim/List-Authority default; Emotional and Contrarian optional), but Generate was intended to produce titles and briefs in-page via window.cowork.askClaude. Persists, so it reopens with state.

Pivot User's reaction to v2: if you have to paste the built prompt back into Claude anyway, the copy-paste step is wasted. Agreed and cut it. The standalone HTML builder was a good intermediary but the friction it introduced negated the convenience. Moved to a live Cowork artifact.

Done Built a single-file offline HTML prompt-builder: paste script, choose variant count and angles, Build prompt, Copy to clipboard. Caught and fixed two stray CSS typos during testing. Limitation stated up front: builds the prompt but can't generate titles itself without an API key.

Decision Needed an actual interactive tool — v1 was a paste-in template, not something you could use repeatedly without opening a fresh chat. Built the offline HTML version as a self-contained prompt-builder.

Done Clarified scope: KH lore channel, reusable template, thumbnails handled by the user's own image tool (outputs briefs and image prompts, not images). Researched YouTube title/thumbnail best practice — key finding: Test & Compare picks winners by watch-time share, not CTR, so a high-CTR/low-retention title can lose. Built the over-promise flag around this. v1 shipped as a paste-in prompt template: drop script into a fresh chat, get 3 A/B/C variants each with title, thumbnail brief, and image prompt.

Issue Fixed Logic check: a few already-strong "Low/keep" videos (e.g. "The Box Held the Answer") slipped into the top 20 on views alone. Flagging those as ★ Yes to redo contradicted their own band score. Changed the flag to mark them "Keep" instead. Flag now self-updates on re-score or re-pull.

Done Added "Worth redoing? (top 20)" column on user feedback — removes the eyeballing step of working out which high-ranked videos are actually worth the time.

Decision Added "redo rank" = weakness × views after building the initial scoring. Pure rubric rank was surfacing low-view videos that happened to score badly. The views multiplier corrects for this: a video with 5 views and a weak thumbnail is still lower priority than one with 900 views and a weak thumbnail.

Done Built 22-point scoring rubric and banding: High ≤10, Medium 11–15, Low/keep 16–22. Scored all 69 videos and verified the ranking.

Issue Fixed Caught a mis-read from an earlier pass: "The Mechanics That Make Kairi Impossible" was logged as a dark atmospheric shot. Wrong — it has a Kairi face and "THE KAIRI PROBLEM" title text. Corrected before final scoring.

Decision Reviewed all 69 thumbnails directly in the browser, batched — no sampling. Wanted eyes on every one before scoring. Logged three patterns during the pass: the recurring purple "Thinking Through the Darkness" podcast template on low-view videos; raw-screenshot-plus-subtitle thumbnails on mid-tier theory videos; and the already-designed-text thumbnails that just need consistent fonts, wordmark, and a fixed palette.

Done Built the full activity type selector: four paths, one flow. Food — existing restaurant path, unchanged. Coffee — Foursquare café search, no booking step, morning/afternoon time slots. Activity — Eventbrite API with Arts, Sports, Music, and Classes categories; skips date/time since events have their own date. Cinema — TMDB now-playing films with genre filtering; skips date/time; "Find Showtimes" deep-links to a Google search. Step architecture changed from numeric IDs to semantic string IDs with a FLOWS routing object — each path is an array of step IDs, progress dots compute from the current path. Config panel expanded from two fields to five (name, message, Foursquare key, Eventbrite key, TMDB key). All three APIs have contextually appropriate demo fallbacks.

Fixed Demo mode was returning the same four restaurants regardless of cuisine or location — a hardcoded list that didn't change between sessions. Fixed by making demo data cuisine-specific: each of the six cuisine types now maps to its own set of four plausible restaurant names, so the cards at least match what was selected. An info banner now tells the user they're seeing sample results and where to add an API key for real ones. Also: changed location field label from "And where are you?" to "Where would you like to go?" — more accurate since it's asking about the destination, not the person's current position.

Fixed Two UX fixes. Name collection is now a fill-in-the-blank embedded in the headline — the input is styled at headline scale with just a bottom border, so "I'm so glad, ______" reads as a sentence rather than a form field. If the sender pre-fills the recipient's name via the config panel, that step is replaced with a fully personalised "I'm so glad, [Name]." headline and the question never appears at all. Restaurant step: "That's the one →" is now a fixed button anchored to the bottom of the viewport, sliding up from below the moment a card is selected — visible on any screen size without scrolling.

Decision The sticky button fix exposed a secondary issue: body { overflow: hidden } was blocking scroll on the restaurant step, clipping the bottom card behind the viewport edge on portrait mobile. Re-enabling scroll on step 5 only, plus an 88px spacer below the grid, means all four cards are reachable — the sticky button is just the faster path, not the only one.

Done v1 complete. Full seven-step wizard: the question, name and location, cuisine, vibe, restaurant selection (Foursquare API or demo), date and time, confirmation. Calendar .ics generation working. OpenTable deep-link booking handoff working. Config panel for sender API key setup — saves to localStorage, invisible to the recipient.

Decision White background and Nunito font. Every other tool in this portfolio is dark — intentionally. This site should look like something built for a person, not a developer. The constraint in the brief was aesthetic before it was technical: bubbly, clean, fluid. Nunito's rounded letterforms suit the tone. One accent colour (rose #E8739A) used across the whole experience, nothing else.

Decision The No button starts as an inline element and switches to position: fixed on the first escape, recording its getBoundingClientRect() coordinates first so the switch is invisible. After that it moves via left/top in fixed space. On mobile, mousemove events don't fire — instead three clicks degrade the button text ("Are you sure?" → "Really...?" → vanish). Same behavioural outcome, different mechanism.

Decision Foursquare over Yelp. Yelp eliminated their free tier mid-2025 with minimal notice — now ~$8–$15 per 1,000 calls. Foursquare's basic tier gives 10,000 free calls/month with cuisine search, price tiers, photos, and addresses. More than adequate. Foursquare v3 also allows CORS from the browser directly — no proxy needed, keeping the no-backend principle intact.

Decision The booking gap. No public API exists for programmatically completing a restaurant reservation — OpenTable, Resy, and Tock are all gated behind partnership agreements or don't exist for outside developers at all. The original viral site was almost certainly constructing a pre-filled OpenTable deep-link. She completed the booking herself. The site made her feel like it happened automatically. The "Book the table" button in this project does the same thing and the README says so clearly.