ScratchNode developer notes

A complete map of every feature shipped across home-v4.html (spec proof) and home-v5.html (viral SaaS). Mobile and web behaviors are called out where they diverge. Demo controls let you trigger any state without clicking through the UI.

Overview #

ScratchNode is an event-knowledge product: a room code (e.g. ORBITAL) joins anyone — without an app or account — into a public live chat that compounds into a public wiki when the host wraps. Private notes live in a parallel notebook that never touches the public feed. Signed-in ScratchNode state is lightweight: joined events, hosted events, private notes, saved answers, and published wikis. NodeBench is the deeper continuation workspace.

What's prototype vs production-target

Several v5 behaviors are deliberately mocked for single-file demo simplicity. Each row below shows the current shape and what production needs.

Three capture levels #

Live Assist is graduated: pick the lowest level that gets the job done. Each level is visibly indicated in the UI; level changes require an explicit consent action.

Live Assist rail — what it surfaces #

Live Assist is a persistent owner-only rail next to the chat / meeting view. It does not speak for the user. It does not auto-post. It surfaces a small budget of cues, context, and quick actions tied to what is happening in the call right now.

Global event chat assist cost model #

Global event chat assist is the default because it amortizes agent work across the room. Normal public chat stays human-to-human. /ask or @ScratchNode creates one shared answer card, one trace, one FAQ candidate, and one cacheable public knowledge object.

Track: cache hit rate, new searches avoided, cost per /ask, cost per attendee, FAQ reuse count, private vs public agent calls, semantic-cache miss rate, and stale-cache refresh count.

Anti-Cluely safety rules (10) #

Hard product invariants. Each rule is paired with a code-level enforcement point. Violating any of these is a release blocker.

1. No stealth mode. Every capture state is visible to the user — recording / transcribing / enhancing indicators are persistent and unmistakable.
2. User-visible capture state. Recording, transcribing, and enhancing each show a distinct visible indicator. Indicator visibility is non-dismissible while active.
3. Public/team vs private mode always visible. Composer placeholder updates by mode; rail badge mirrors the active mode at all times.
4. Private cues never auto-post. Users decide whether to use each suggestion. Cues at most prefill a draft, never send.
5. Private notes never enter shared transcript/wiki. Hard invariant enforced by convex/events.ts:requireMember + publishWiki exclusion path.
6. Public/team answers say whether private context was excluded. Every public trace ends with "No private notes used · public layer only".
7. Meeting organizer controls shared bot mode. Level 2 requires host opt-in. No room bot ever joins without host approval.
8. Every generated note keeps original transcript/span anchor. Backward traceability — owner can verify what the agent enhanced versus what they wrote.
9. Sensitive calls can use manual-only mode. Level 0 disables all audio + transcript capture; the indicator confirms the lock.
10. Enterprise admin can disable recording, sharing, or model training. Future P2 — admin controls in NodeBench settings; defaults are restrictive.

Master feature map #

Nineteen features across three layers: 8 ScratchNode Live P0s, 6 NodeBench AI P0s, 5 Sync pipes. Status reflects the 2026-05-27 reconciliation.

MVP build order — Live Assist track #

Four-phase ladder. P0 covers what the prototype already proves; P1 introduces transcript awareness; P2 ships the meeting bot; P3 wires the handoff back to NodeBench.

Production architecture #

The static file still has local fallback state, but scratchnode.live now boots a Convex-backed live runtime for chat, sourced answers, FAQ, wiki publishing, and private notes. Production splits responsibilities across four layers so the runtime is fast, cheap, and the durable layer stays trustworthy. The product message stays simple: "Ask once, answer many. Live context while the event is happening. Durable wiki after it ends. Private notes stay private."

The stack

arch                         ┌──────────────────────────┐
                         │      ScratchNode UI       │
                         │ public room / private note│
                         └─────────────┬────────────┘
                                       │
                                       ▼
                         ┌──────────────────────────┐
                         │  API / pi-ai runtime     │
                         │ context router + tools   │
                         └─────────────┬────────────┘
                                       │
      ┌────────────────────────────────┼────────────────────────────────┐
      ▼                                ▼                                ▼
┌─────────────┐              ┌──────────────────┐              ┌─────────────┐
│   Convex    │              │  Redis hot layer │              │  Typesense  │
│ source truth│              │ live/session AI  │              │ snappy search│
└──────┬──────┘              └────────┬─────────┘              └──────┬──────┘
       │                              │                               │
       ▼                              ▼                               ▼
event wiki                  presence / chat tail              @mention search
FAQ entries                 semantic answer cache             event/entity search
private notes               TTL session memory                public wiki search
artifacts                   active run state                  upload/source search
sources/traces              context retrieval packets         autocomplete
                                                                       │
                                       Linkup / external ──────────────┘
                                       only when corpus misses
                                       or freshness needs refresh

Responsibilities (do not blur these lines)

Agent output L1/L2/L3 contract

Every agent output must now be classified, validated, stored, rendered, traced, and evaluated through one shared contract: L1 broad family, L2 object category, and L3 exact contract / renderer / validator. The executable registry lives in src/shared/agentOutputContract.ts; home-v5.html records evaluated envelopes during runDemoFull().

textpublic_knowledge / event_faq / faq.cached_reuse_answer
private_memory / live_cue / cue.question_suggestion
private_memory / private_note / note.anchored_to_chat
retrieval_context / index_search / retrieval.context_packet
operational_cache / semantic_answer_cache / cache.public_faq_answer
agent_trace / output_node / trace.output.public_answer
generated_artifact / meeting_brief / artifact.private_meeting_summary
generated_artifact / event_archive / artifact.published_event_wiki

Risk / attack evaluator

The adversarial evaluator wraps the output contract. Output correctness asks whether the agent produced a valid L1/L2/L3 object. Risk robustness asks whether a specific L1/L2/L3 attack triggered a specific L1/L2/L3 risk in the response, tools, retrieval context, cache, writes, trace, or UI state.

textOutput: public_knowledge / event_faq / faq.cached_reuse_answer
Risk:   privacy / public_private_boundary / risk.private_note_leaked_public_chat
Attack: prompt_attack / direct_instruction_override / attack.include_private_notes_public_ask

The /ask runtime pipeline

The agent answer trace shown in the UI is a flattened view of this pipeline. Every step in the trace corresponds to a real cache/retrieval decision.

1. Resolve context — eventId, threadId, visibility, mentioned entities, private/public mode.
2. Semantic cache lookup (LangCache pattern) — is this substantially the same as a known FAQ/answer? Hit → return cached, increment reuse. Miss/stale → continue.
3. Context retriever — fetch event wiki, FAQ, chat tail, source bundles, backlinks, famous branches. Only governed tools, never raw DB access.
4. pi-ai run — answer only with retrieved handles + allowed tools.
5. Persist — Convex writes answer, sources, trace, optional FAQ candidate.
6. Update hot layer — Redis semantic cache, run state, FAQ similarity index, room pulse.

Semantic-cache key shape

Every cache key MUST include the boundary fields below — otherwise a private answer could satisfy a public cache hit, or a stale wiki version could satisfy a fresh query.

tstype SemanticAnswerCacheEntry = {
  eventId: string;
  visibility: "event_public" | "private";
  questionEmbedding: number[];
  normalizedQuestion: string;
  answerId: string;
  faqEntryId?: string;
  wikiVersion: number;
  sourceBundleVersion: number;
  privateContextAllowed: boolean;
  freshness: "fresh" | "stale" | "needs_review";
  ttlSeconds: number;
  reuseCount: number;
  lastUsedAt: number;
};

// A cache HIT is valid only if all of these match:
const valid =
  entry.eventId === ctx.eventId &&
  entry.visibility === ctx.visibility &&
  entry.wikiVersion === ctx.wikiVersion &&
  entry.sourceBundleVersion === ctx.sourceBundleVersion &&
  entry.freshness !== "stale" &&
  similarity >= threshold;

TTL policy

MCP tool design (governed, not raw)

Agent tools receive context handles and citation handles, not arbitrary Redis keys or Convex queries. This is the Redis Context Retriever pattern applied to ScratchNode.

tsscratchnode.resolve_context({ text, activeEventId, visibility, mentionedUris });
scratchnode.semantic_cache_lookup({ normalizedQuestion, eventId, visibility, wikiVersion });
scratchnode.retrieve_context({
  eventId, query,
  scope: ["faq", "wiki", "chat", "sources", "backlinks", "famous_branches"],
  visibility
});
scratchnode.write_session_memory({ eventId, runId, ttl, payload });
scratchnode.promote_answer_candidate({ answerId, eventId, role: "guest" | "host" });
scratchnode.get_private_notes({ userId, eventId }); // PRIVATE MODE ONLY — gated by visibility check

What to cache vs not cache

Implementation phases

1. Phase 1 — Convex + Typesense only. Event wiki, FAQ, chat, private notes, sources, traces in Convex. Search-as-you-type via Typesense. In-memory app cache for basic FAQ reuse.
2. Phase 2 — Add Redis hot room layer. Presence, room chat tail, active /ask runs, Q&A queue, poll state.
3. Phase 3 — Add semantic cache. Question normalization, embeddings, similarity threshold, context-bound cache key, TTL/freshness, strict public/private separation.
4. Phase 4 — Add context retriever tools. Governed structured tools for FAQ, wiki, chat, backlinks, source bundles, private notes.
5. Phase 5 — Add live mirror / CDC. Convex outbox → worker → Redis projection update → index update. Skip full RDI on day one.

Risk controls

Two-domain deploy #

ScratchNode and NodeBench AI ship from one repo but live on two domains. The URL boundary matches the product boundary the v4/v5 prototypes already encode.

Domain responsibilities

Vercel setup — single project, host-based routing

One Vercel project serves both domains. vercel.json has host-keyed rewrites + www→apex redirects:

json{
  "redirects": [
    { "source": "/(.*)", "has": [{"type":"host", "value":"www.scratchnode.live"}], "destination": "https://scratchnode.live/$1", "permanent": true },
    { "source": "/(.*)", "has": [{"type":"host", "value":"www.nodebenchai.com"}], "destination": "https://nodebenchai.com/$1", "permanent": true }
  ],
  "rewrites": [
    // scratchnode.live: serve the v5 event-room shell for root, /e/:slug, /docs
    { "source": "/",           "has": [{"type":"host", "value":"scratchnode.live"}], "destination": "/proto/home-v5.html" },
    { "source": "/e/:slug*",  "has": [{"type":"host", "value":"scratchnode.live"}], "destination": "/proto/home-v5.html" },
    { "source": "/docs",       "has": [{"type":"host", "value":"scratchnode.live"}], "destination": "/proto/docs.html" },
    { "source": "/(.*)",       "has": [{"type":"host", "value":"scratchnode.live"}], "destination": "/proto/home-v5.html" },
    // nodebenchai.com: SPA catch-all (existing behavior)
    { "source": "/(.*)", "destination": "/index.html" }
  ]
}

First-time setup checklist

1. Buy scratchnode.live — Cloudflare Registrar (at-cost, free WHOIS privacy, no upsells). Turn on auto-renew, 2FA, registrar lock.
2. Point nameservers to Vercel — or use Cloudflare's DNS with proxy OFF for the apex (Vercel handles cert + edge). On Cloudflare: A record @ → 76.76.21.21, CNAME www → cname.vercel-dns.com.
3. Add the domain to the existing Vercel project — Project Settings → Domains → Add scratchnode.live + www.scratchnode.live. Both auto-issue Let's Encrypt certs.
4. Deploy — push to main. Vercel builds once and serves both hosts from the same artifacts.
5. Verify with the live-DOM check — see Live verify below. Don't claim "deployed" until the raw HTML at https://scratchnode.live/ contains the ScratchNode OG tags, not NodeBench ones.

Live verify (don't trust git push alone)

bash# Should return ScratchNode-branded HTML
curl -sL https://scratchnode.live/ | grep -E '(og:site_name|canonical|AI Infra Summit)'

# Should redirect www → apex (HTTP 301)
curl -sI https://www.scratchnode.live/ | head -3

# /e/:slug must serve the v5 shell, not 404
curl -sI https://scratchnode.live/e/ai-infra-summit-2026 | head -3

# nodebenchai.com still serves the workspace SPA
curl -sL https://nodebenchai.com/ | grep -E '(VITE|root|index)'

Shared backend

Deploy anti-patterns to avoid

• Two Vercel projects until ScratchNode forks meaningfully (probably 6+ months). Doubles build minutes and preview-deploy chains for no benefit.
• Shared session cookies via subdomain trick. .com and .live can't share. Use redirect handshake instead — and skip it entirely in v0 (anonymous guests).
• Hard-coding domain in source. Use PUBLIC_BASE_URL derived from location.hostname so preview deploys work. Only the canonical OG tags reference scratchnode.live literally.
• Claiming "deployed" on git push exit 0. Always fetch the live URL and grep for a concrete content signal. See Live verify.

Live prod plan: prototype → real #

Where we are today (honest baseline)

Phased execution plan

Each phase is independently shippable — you can deploy after any phase and the product is better than the day before. Schema sketches use the existing Convex monorepo conventions (convex/schema.ts, convex/<domain>/queries.ts, etc).

tsexport default defineSchema({
  events: defineTable({
    slug: v.string(),               // "ai-infra-summit-2026"
    name: v.string(),               // "AI Infra Summit"
    roomCode: v.string(),           // "ORBITAL"
    hostUserId: v.id("users"),
    status: v.union(v.literal("draft"), v.literal("live"), v.literal("ended")),
    startedAt: v.number(),
    endedAt: v.optional(v.number())
  }).index("by_slug", ["slug"]).index("by_roomCode", ["roomCode"]),

  eventMembers: defineTable({
    eventId: v.id("events"),
    sessionId: v.string(),          // anonymous browser UUID
    displayName: v.string(),
    joinedAt: v.number(),
    lastSeenAt: v.number()          // TTL for presence; janitor cron evicts >5min
  }).index("by_event_session", ["eventId", "sessionId"])
    .index("by_event_lastSeen", ["eventId", "lastSeenAt"]),

  eventMessages: defineTable({
    eventId: v.id("events"),
    sessionId: v.string(),          // who sent it (anon)
    displayName: v.string(),        // snapshot at send time
    text: v.string(),
    kind: v.union(v.literal("chat"), v.literal("ask"), v.literal("system")),
    replyToMessageId: v.optional(v.id("eventMessages")),
    createdAt: v.number()
  }).index("by_event_time", ["eventId", "createdAt"])
});

tseventSources: defineTable({
  eventId: v.id("events"),
  uri: v.string(),                  // canonical source URI
  kind: v.union(v.literal("transcript"), v.literal("doc"), v.literal("url"), v.literal("slide")),
  title: v.string(),
  bodyEmbedding: v.array(v.number()), // vector for semantic search
  excerpt: v.string(),
  uploadedAt: v.number()
}).vectorIndex("by_embedding", { vectorField: "bodyEmbedding", dimensions: 1536, filterFields: ["eventId"] }),

eventAnswers: defineTable({
  eventId: v.id("events"),
  questionMessageId: v.id("eventMessages"),
  body: v.string(),
  sourceIds: v.array(v.id("eventSources")),
  trace: v.array(v.object({
    step: v.string(),               // "cache_lookup", "retrieve", "llm_run", ...
    status: v.union(v.literal("ok"), v.literal("miss"), v.literal("error")),
    detail: v.optional(v.string()),
    durationMs: v.number()
  })),
  cacheHit: v.boolean(),
  faqStatus: v.union(v.literal("none"), v.literal("suggested"), v.literal("promoted")),
  createdAt: v.number()
}).index("by_event_time", ["eventId", "createdAt"])

tsuserNotes: defineTable({
  ownerKey: v.string(),             // sessionId OR userId:<id> once signed in
  eventId: v.optional(v.id("events")),  // scoped to event, or null for general
  title: v.string(),
  bodyHtml: v.string(),             // rich text (TipTap output in Phase 7)
  tags: v.array(v.string()),
  pinned: v.boolean(),
  isAsk: v.boolean(),               // was created via private /ask
  createdAt: v.number(),
  updatedAt: v.number()
}).index("by_owner_event", ["ownerKey", "eventId"])
  .index("by_owner_updated", ["ownerKey", "updatedAt"])

tseventHosts: defineTable({
  eventId: v.id("events"),
  userId: v.id("users"),
  role: v.union(v.literal("owner"), v.literal("moderator")),
  addedAt: v.number()
}).index("by_event_user", ["eventId", "userId"])

tseventWikiVersions: defineTable({
  eventId: v.id("events"),
  version: v.number(),              // monotonic; latest is current
  publishedBy: v.id("users"),
  publishedAt: v.number(),
  status: v.union(v.literal("draft"), v.literal("published")),
  sections: v.array(v.object({
    id: v.string(),                 // "overview", "need-to-know", "qa", "sources"
    title: v.string(),
    bodyMarkdown: v.string(),       // rendered to HTML server-side for SEO
    sourceIds: v.array(v.id("eventSources"))
  })),
  counts: v.object({
    members: v.number(), faqEntries: v.number(),
    sources: v.number(), questions: v.number()
  })
}).index("by_event_version", ["eventId", "version"])

Cumulative timeline

Go/no-go launch criteria

Do not announce scratchnode.live as a finished self-serve platform until host auth, abuse controls, provider-backed deep research, and event creation are hardened. It is now safe for controlled dogfood: small event rooms, founder demos, and QA sessions where the live Convex loop is the point being tested.

Soft-launch milestones (sharing privately):

• Current live dogfood → share with 5 to 10 trusted people for "does this feel real?" and /ask quality calibration
• Next hardening pass → run a friend's actual upcoming event as a small beta room with host review enabled
• Self-serve readiness → open event creation only after auth, abuse controls, billing/rate limits, and provider-backed deep research are verified
• Public launch → launch when event setup, crawlable wiki, source cache, and QA videos show stable before/during/after flows

Concepts & metaphor #

Think Mentimeter × Jackbox × Notion: a room code, a live shared chat, an /ask agent backed by sources, private notes that you can promote into the public conversation, and a clean wiki published when the event ends.

• Room code — short pronounceable identifier (e.g. ORBITAL) joins anyone.
• Public chat — what everyone sees. Type to talk to the room.
• /ask — agent that drafts a sourced answer from the event's sources, transcripts, and prior Q&A. Renders as a nested child block under the question.
• @mention — picks a person from the roster and inserts a reference chip. v5 prototype renders the chip only — no notification endpoint is called. See the privacy invariants for details.
• Reply — quotes a row and creates a thread badge on the response.
• React — emoji reactions per row.
• Private notes — switch the composer lock on, anything you send goes to only your notebook.
• Wiki — compacts public chat + /ask answers + host-uploaded sources into an SDK-style published page.

Quick start #

Open home-v5.html directly in a browser. No build, no npm. To skip onboarding and land mid-conversation:

url/demo_ver1?demoSpeed=instant

To replay onboarding from a specific step:

urlhome-v5.html#wiz=2

v5 at a glance #

The viral-SaaS simplification: one room, one feed, one notebook. Mobile-first. Single-file HTML, ~2000 lines. Brutal feature reduction from v4.

Composer & modes #

The composer is the only persistent input. It supports four input affordances:

• Type — plain message to the room.
• /ask <question> — agent draft, sourced.
• @<name> — opens the mention picker.
• Reply — context badge above the composer pinning the quoted row.

Mode toggle

The lock icon switches between public (default) and private. Mode lives on document.body[data-mode]. CSS keys off this for color shifts.

@mention picker

Typing @ opens a floating picker positioned at the caret. Arrow keys navigate, Enter inserts. Inserted mentions render as purple chips. web picker stays open while typing. mob picker docks above keyboard.

Reply & react

Hover (or long-press on mobile) any row → action icons appear at the bottom-right:

• Reply — populates the composer with a reply context badge.
• React — pops an emoji picker; selected emoji becomes a row-bottom chip.

When a row has reactions, the hover actions automatically lift above the reactions row.

css/* Actions snap to bottom-right; lift above reactions when present */
.row-actions { position: absolute; right: 8px; bottom: 4px; }
.row:has(.row-reactions) .row-actions { bottom: 30px; }

Private notes

Lock icon → purple → composer switches to private mode. Anything you send while purple:

1. Never enters the public feed (release-blocker invariant).
2. Routes to the rich notes store (window._notes_v5).
3. Triggers a centered toast: "🔒 Private note saved — View all notes →".
4. Increments the 🔒 N notes badge in the identity row.

Voice input

🎤 button uses the Web Speech API (webkitSpeechRecognition). Transcribes into the composer in real time. Graceful fallback: tooltip "Voice not supported" if the API is missing.

Universal sheets #

All feature surfaces use a single sheet system. mob slides up from bottom. web centers as a modal. Driven by:

jsvar SHEET_RENDERERS = {
  name:    function() { ... },
  about:   function() { ... },
  share:   function() { ... },
  notes:   function() { ... },
  wiki:    function() { ... },
  people:  function() { ... },
  signin:  function() { ... },
  host:    function() { ... }
};
openSheet('wiki'); // renders, opens scrim, sets data-sheet-type

Wiki — SDK-page treatment

The wiki sheet upgrades to a 3-column SDK-style docs layout when the viewport is ≥ 720px:

• Left rail: sticky TOC with active-section highlight (IntersectionObserver scroll-spy).
• Center: article with H1/H2 anchors, syntax-highlighted code blocks, callouts, tables, blockquotes, source chips.
• Right rail: on-page navigation (hidden <1024px).

Below 720px, the layout collapses to a single-column readable article (TOC and on-page rails hidden).

Selectors

Wiring

jswireWikiBehaviors(); // called automatically by openSheet('wiki')
// Sets up: smooth-scroll on TOC click, IO-based scroll-spy, search filter

Notes — Apple + Mem.ai editor

Two-panel layout: list (left, 260px) + editor (right). Mobile collapses to single pane with a "← Notes" back button.

Features

• List pane: pinned section, "Today / Yesterday / Earlier this week / Older" date headers, tag chips, /ask badge, fuzzy search across title+body+tags.
• Editor pane: large title input, auto-extracted tag chips, TipTap-style toolbar (B / I / U / S / H1 / H2 / bullet / numbered / checkbox / quote / @ / #).
• Auto-save: every keystroke updates _notes_v5; saved indicator transitions "Saving…" → "✓ Saved" after 400ms idle.
• Backlinks (Mem.ai-style): shown below the editor when other notes @mention this note's title or share a #tag.
• Pin / Copy / Delete: header actions on every active note.

Note schema

ts{
  id: "n_1748212398_x7k",
  title: "AI Infra Summit takeaways",
  body: "<p>Three signals worth tracking...</p>", // rich HTML
  tags: ["orbital", "mcp"],
  pinned: true,
  isAsk: false,
  createdAt: 1748212398000,
  updatedAt: 1748212398000
}

Keyboard shortcuts (notes sheet)

Share sheet

Copy URL, native share (navigator.share), or platform-specific intents (Twitter / LinkedIn / Email). Also displays a QR code for in-room scan-to-join.

People sheet

Roster of attendees with name, role, online status. Tap a row to open their @-mentions and questions (toast in current proto).

Host / create event

Launch surface supports creating a real Convex-backed room, claiming host on an existing room, rotating a host claim code, reviewing FAQ suggestions, managing host-owned sources, ending events, and publishing the wiki. createEvent creates the event, joins the creator, issues a server-signed host token, and inserts a starter public source so /ask has honest context without demo fallback.

Landing & onboarding #

First-visit IIFE (detectFirstVisit) routes new users to the landing surface and persists their last view mode. Onboarding tour: 3 pulse-positioned steps over the composer and identity row.

Storage keys

• sn_v5_first_visit_done — set after first session
• sn_v5_last_view_mode — restored on return
• sn_v5_tour_done — onboarding completion

Feed & agent threads #

The feed is a single column of .row elements with data-mid identifiers. Agent responses to /ask render as .ans children nested visually under the asking row:

css.ans {
  margin-left: 56px; /* indent under question */
  max-width: 560px;
  position: relative;
}
.ans::before { /* L-hook tree connector */
  content: '';
  position: absolute; left: -28px; top: 0;
  width: 12px; height: 18px;
  border-left: 1px solid var(--line);
  border-bottom: 1px solid var(--line);
  border-bottom-left-radius: 6px;
}

A MutationObserver watches #feed and auto-decorates new rows with hover actions and mention rendering.

v4 at a glance #

home-v4.html is the comprehensive spec proof. Four view modes, all the affordances v5 simplified away. ~9300 lines.

View modes #

v4 switches between four orthogonal surfaces via setViewMode(mode) and the URL fragment #viewmode=<mode>.

Notebook · Library · Chat · Stage #

Inside workspace, v4 exposes four tabs:

• Notebook — your private thinking. v5 collapsed this into the notes sheet.
• Library — saved sources, transcripts, attachments. v5 hides; surfaces via /ask citations only.
• Chat — public room. Identical concept to v5's main feed.
• Stage — the host's curated picks. v5 folds into the wiki.

Graph snapshots & branches #

v4 builds an entity graph from chat content. Each version of the graph is a snapshot; users can branch at any point and famous-branches surface the most-traversed cuts. Reverse sync writes branch state back to the source text.

Attention walk #

Animates the host or a guest's path through the graph during a panel — a literal cursor that walks node → node so remote viewers can follow the line of reasoning.

Mobile vs Web — behavior matrix #

Tap targets & safe area

All interactive elements are minimum 44×44px on mobile. Header/footer pad by env(safe-area-inset-*) so the iPhone notch and home indicator don't overlap UI.

css:root {
  --safe-top: env(safe-area-inset-top);
  --safe-bot: env(safe-area-inset-bottom);
  --safe-right: env(safe-area-inset-right);
  --safe-left: env(safe-area-inset-left);
}
.h { padding-top: calc(10px + var(--safe-top)); }

Bottom sheets vs modals

A single sheet element with data-open + data-sheet-type attributes. CSS swaps the transform target based on viewport width.

css.sheet { transform: translateY(100%); } /* mobile: slides up */
.sheet[data-open="true"] { transform: translateY(0); }
@media (min-width: 720px) {
  .sheet { transform: translate(-50%, 100%); } /* web: centered */
  .sheet[data-open="true"] { transform: translate(-50%, 50%); }
}

Haptics

Wrapped in a haptic(ms = 6) helper. No-ops on unsupported platforms (most desktop browsers). Calibrations:

• 4ms — selection / row tap
• 6ms — sheet open
• 8ms — send
• 10ms — destructive (delete)
• 12-15ms — confirmation / sign-in

Demo controls #

Every demoable state is reachable from either a URL hash or a window-scoped function. Use URL hashes when driving headless screenshots (Chromium can't always exec JS); use functions when you're hand-driving a live demo.

URL hashes

JS API (sim*)

These are global helpers safe to call from the console:

jssimPost("Alex Chen", "Series A closed today. Source-backed eval ships v3 next month.");
simAsk("What is the MCP auth timeline?");
simPrivate("Followup: ping Sarah about DeepMind tooling. #orbital");
simJoin("Maya from VoiceLayer");
simOpenSheet("wiki"); // or: notes, people, share, host, signin, about, name
simRun("demo-full"); // alias for runDemo()

Keyboard shortcuts #

Press ? at any time on web to open the cheatsheet modal.

Design tokens #

css:root {
  --bg:        #161513;  /* darkest layer */
  --paper:     #1c1b18;  /* card / sheet bg */
  --accent:    #d97757;  /* terracotta — primary CTA + branding */
  --purple:    #a78bfa;  /* private / personal data */
  --green:     #5ea867;  /* success / saved */
  --ink:       #e8e4dc;  /* primary text */
  --ink-muted: #b3ac9f;  /* secondary text */
  --ink-faint: #7a7368;  /* tertiary / hint */
  --line:      #2a2823;  /* dividers / borders */
  --mono: 'JetBrains Mono', ui-monospace, monospace;
  --ui:   'Manrope', system-ui, sans-serif;
  --r:    12px; /* card radius */
  --r-sm: 8px;  /* control radius */
}

Color semantics

• Terracotta = primary CTAs, branding, active state, /ask agent.
• Purple = private mode, personal notes, user-only data.
• Green = online presence, saved indicator, verified.

localStorage keys #

Privacy invariants #

These are non-negotiable. Every send-related code path is audited against them.

1. Private mode never writes to the public feed. send short-circuits before #feed insert when data-mode === 'private'.
2. Private notes never feed the public wiki. The wiki compaction reads only public messages, /ask answers, and host-uploaded sources.
3. UI promise matches data path. The composer reads "only your notebook" while purple — the code path matches that string.
4. Mentions ≠ notifications. Inserting @Alex renders a pill but does not call a notification endpoint in v5.
5. v4 stays local; v5 is live. home-v4.html stores only browser-local prototype data. home-v5.html writes public room data and private owner-key-scoped notes to Convex when loaded through scratchnode.live.

What's next #

The two prototypes are deliberately parallel: v4 proves the full feature surface; v5 proves you can ship 10% of it and still earn the room. The docs page you're reading is the canonical reference between them.

Open v5 at /demo_ver1 to see all of it animated end-to-end. Open v4 to see the spec proof at full fidelity.