← Docs

HiveJournal Documentation

Master index of every document in the repo. If you're adding a new doc, find the right category below and add it here. If you're an AI assistant, start at docs/ai/ for the curated feature index and architecture guides.

Web version: hivejournal.com/docs renders this index for super-admins.

What you needWhere to go
Complete feature catalog with file pathsdocs/ai/INDEX.md
Architecture, tech stack, data flowdocs/ai/ARCHITECTURE.md
Coding conventions & file placementdocs/ai/CONVENTIONS.md
Product roadmap & active tasksdocs/product/PRODUCT_TASKS.md
REST API endpoint referencedocs/reference/API.md
Local dev setupdocs/operations/QUICKSTART.md

docs/ai/ — AI & contributor entry point

The curated set that AI assistants and new contributors should read first. CLAUDE.md at the repo root points here.

  • INDEX.md — Every feature in HiveJournal with file paths, routes, and migrations
  • ARCHITECTURE.md — Monorepo layout, deployment topology, data flow, known landmines
  • CONVENTIONS.md — Naming patterns, file placement, when to add a migration
  • plans/story-bible-and-chapter-takes.md — In-flight architecture proposal: Story Bible + chapter-level takes for novel-mode seasons
  • features/dreampro-citizen-science.md — Deep dive: DreamPro Citizen Science Platform (Phases 1–8)
  • features/odessa.md — Deep dive: Odessa personalized story generator (journals → metaphorical graphic novel, Flash/Short Story/Novel lengths, journal import pipeline)
  • features/open-energy.md — Deep dive: Open Energy 10-phase pathway (legacy routes)
  • features/ai-personas.md — Deep dive: AI Personas synthetic user ecosystem (personality, backstories, life events, weather, news, horoscopes, spawn groups, story seasons, murder mysteries)
  • features/story-engine.md — Deep dive: Story Engine for novel-mode Graphene seasons (bible + lore_notes, universes incl. The Turing Logs, frameworks incl. tech_dystopian, chapter takes + critique loop, auto-refine pipeline, audio rendering with cache reuse, listener tracking + resume cursor + ratings)
  • features/audiobook-suite.md — Deep dive: Audiobook Creator Suite — manuscript ingestion (EPUB / DOCX / PDF + auto cover), pronunciation lexicon, per-character voice mapping for dialogue, ACX/M4B export. The creator-facing path from "I have a manuscript" to "I have an .m4b for Audible"; companion to story-engine.md (which is the LLM writer side).
  • features/critique-marketplace.md — Roadmap: three-tier critique flow for EmberKiln. T0 (AI single-shot, shipping), T1 (persona suite + bundles), T2 (human editor marketplace with Stripe Connect). Polymorphic story_critiques table powers all three.
  • features/veneer.md — Canon doc: Veneer, the in-canon leaked ad magazine edited by an N/A named Jimmy. Extends Deep Cut's commercials library with publication-tagged ads; Phase 1 = canon + Jimmy character + 6 seeded Issue #1 ads. Phases 2-4 cover schema, gated /veneer route, admin CRUD.
  • features/PORT_TO_GRAPHENE.md — Deep dive: Notebook-to-Season port flow (prose extraction, voice picker, script generation, TTS rendering, publish pipeline, edge cases)

docs/product/ — Living product docs

What's shipping, what's next, where we're going.

  • STEWARDSHIP_FRAMEWORK.md — ideation (2026-07-27, founder-initiated): a framework to keep Point Seven Studio's properties pure through platform growth and the founder's passing — resistant to corruption, political + monetary capture. Codifies a small "protected core" of invariants (mission primacy, consent/read-only-for-the-dead, Rule 9, honesty-first), then defends it with steward-ownership (perpetual purpose trust + PBC + a golden veto share), a Stewardship Council separated from the operating board, entrenched amendment, transparency-as-immune-system, and a dissolve-before-corrupt clause. Key timing insight: entrench before outside capital. Learns from Patagonia / Novo Nordisk / Mozilla / (cautionary) OpenAI. Ends with open decisions for the founder. The framework is the design; the two instruments below are the drafts to hand an attorney.

  • STEWARDSHIP_CHARTER.md — DRAFT (2026-07-27): the adoptable constitution the framework calls for — the supreme internal governance instrument. Nine articles: the entrenched Protected Core (six invariants, three strengthen-only), steward-ownership (purpose vehicle + PBC operating entities + the non-economic Golden veto Share and its veto list), the Stewardship Council (composition + anti-capture rules + thresholds), separation of powers, entrenched amendment (+ anti-circumvention so the core travels with the assets), succession (control never opens up; read-only-for-the-dead applied to governance), transparency / annual Purity Audit, and dissolve-before-corrupt. Founder-decision + attorney placeholders throughout; not legal advice.

  • PLATFORM_WILL.md — DRAFT (2026-07-27): the one-page succession directive the Charter's Article VI points to — the founder's stated intent for how Point Seven should behave when the founder can no longer decide, in the founder's voice. Triggers; control is already the structure's (not inheritable); guard the Core over growth; don't puppet the founder's cloned voice; prefer dissolution to corruption; don't freeze tactics; where the instruments live + first contact. Executes alongside (not instead of) the founder's personal estate plan.

  • BUILD_PERFORMANCE.md — analysis + plan (2026-07-27) for frontend build times. Diagnoses the cost (compiling 443 route entries + an inline tsc/ESLint pass, no caching — not static-gen). Tier 1 shipped: moved tsc + ESLint out of the deploy build into a parallel check-frontend CI gate. Tier 2 = the multi-zone split (marketing vs app vs admin) with a sequenced migration (extract packages/shared → Turborepo → stand up apps/marketing), so each build is a fraction of the routes and ships independently.

  • PRODUCT_TASKS.md — Living roadmap (mirrored at /dashboard/admin/tasks)

  • MEMORIAL_VOICE_SITES.md — SHAPING ONLY, gated (crosstalk §16): memorial/tribute websites where you hear the person's own recorded voice, distributed via funeral homes (QuickSites white-label). A new surface + channel for the existing Living Voice Track B/C — inherits the binding consent model + "read-only-for-the-dead" bright line wholesale. No build (HJ or QS) until the owner signs off + counsel clears the consent gate. The ethically-clean MVP (living person records + plays their own real stories) is the only part that could move earlier.

  • PERSONA_TESTING_SERVICE.md — DESIGN (2026-07-28): the middle layer that turns persona testing into a requestable service — any site owner asks our AI personas to test their site against their own goals and gets a shareable report. Decisions: verified self-serve intake, domain-verification + human approval (both — third-party browsing is the whole risk surface), shareable report page (/persona-report/<token>) as deliverable + marketing artifact. Reuses persona-testing-core (engine), partner-provisioning (owner keys), the curation cockpit, and /persona-testing's design; net-new is domain-ownership verification + a robots.txt/rate/cost-capped third-party runner. Safety spine: verified · human-approved · read-only · robots-respecting · capped · AI-persona-labeled. The productization of [[project_persona_qs_testing]].

  • CAIRN.md — concept (2026-07-23), separate brand: a place remembers your family's voice. Record a story, geo-anchor it to a real place (the homeland dock, the family farm); years/generations later a descendant arrives with glasses and hears it in the ancestor's own cloned voice. Mostly a geo-trigger on already-built systems — a Lovio capsule whose unlock is "a family member is physically here," Living Voice for the clone, the Family Wall graph for who inherits, glasses for arrival playback, Legacy Channel as the capture wedge. Shares one substrate (geo-anchored, glasses-visible cache network + local NLU gatekeeper) with the SIGNAL AR-game concept (/for-matt) — one infrastructure, two emotionally opposite products. Genealogy triggers (age / arrival / "when they start tracing"), multi-generational "add a stone" accretion. Emberkiln firelit palette. Counsel-gated; custody-over-decades is the open hard problem.

  • AISLEASK_DOORDASH_PATHWAY.md — GTM pathway plan (2026-07-23): sell AisleAsk (the hands-free glasses store-walk assistant, /api/aisleask/*) to DoorDash as an operated service for grocery shoppers — retaining the IP, not an IP sale. Phone-first (glasses = upgrade); the metric is pick-time / accuracy / shopper-ramp; the moat is per-store planogram data built by shoppers' own captures (the SAME neutral capture rail the SecondSet steer wants — no capture-persistence rail exists today per recon). Phases: proof → store-data moat → prove-without-DoorDash → paid pilot → expand. Public demand surface: /for-shoppers. Hard gates: retailer camera permission, gig-labor UX, build-vs-buy, IP retention.

  • JQ_GLASSES_BLE_MIGRATION.md — decided 2026-07-25: MentraOS 3.0 (Aug 3) kills the Cloud SDK our apps/glasses app runs on (legacy to Oct 2026). Plan: migrate JQ to the Bluetooth SDK (our own mobile app drives Mentra Live over BLE) — own-the-stack without forking the OS. Backend endpoints are transport-agnostic and kept; it's a transport swap + mobile shell. Phased (legacy bridge → BLE bring-up → speak → capture → voice-in → retire AppServer).

  • FAMILY_INTENT.md — the spine for the family layer: it exists to help parents support a child's growth & development, and every surface (growth nudges, the PorchHearth community/services/getaways, chores→credit) is an optional, opt-in involvement in service of the child — never surveillance, never an ad funnel. Inherits from ETHOS.

  • FAMILY_KIDS_CHORES.md — DESIGN ONLY, COUNSEL-GATED: kids chores-for-hire (real credits) with PorchHearth. Captures the payment-rails constraint (Stripe Connect 18+ → parent household is payee, credit attributed to the child), the safety model, and a safe intra-family v1. No code either side until owner go-ahead + counsel.

  • FAMILY_DAY_PLANNER.md — v1 SHIPPED (2026-07-26), migration 585: a "🗓 Plan the day" button per member on /dashboard/family. JQ takes the person's de-identified context (age band, routines, calendar, sleep, growth goals, weekend community events — no name/birthdate leaves the backend) and proposes an ordered day the parent drags to reorder, taps ✕ to drop, and keeps as the day's schedule (family_day_plans). Deselections are recorded (dropped[]) as a signal for the FOLLOW-ON goal-formation nudge (quiet-moment JQ orb roll-bump → "noticed you dropped N — what goal might fit your situation?").

  • UPKEEP_FRESHNESS.md — SHIPPED (2026-07-26): one model for "last done vs. how often it should be" → a freshness % + green/yellow/red for anything with a cadence. Pure, golden-tested upkeep-freshness.ts; now wired into routine freshness dots on the family dashboard AND a household upkeep tracker (migration 586, family-upkeep.ts, /dashboard/family/upkeep) — furnace filter/dryer vent/bathroom clean with "every N hours/days/weeks/months" intervals, most-overdue first, "Done" resets the clock, starter catalog. Follow-on: room attachment + a unified personal+household view + wall dots.

  • FAMILY_HOUSE_MAP.md — SHIPPED (2026-07-26): the map of the house at /dashboard/family/house — draggable + resizable room tiles (AisleAsk store-map primitive reused, migration 588 family_rooms), household upkeep hotspots pinned to rooms (room_id FK, migration 586), each room colored by its worst-freshness so the whole house reads at a glance; assign items to rooms from the map. Follow-on: painterly/floorplan map background, tap-to-done on a tile, chore spawning (family_chores), affiliate reorder links, and placing wall devices in rooms.

  • AISLEASK_STORE_SEO.md — v1 built (2026-07-24): each AisleAsk store can opt into a public, indexable deals page at /store/<slug>, fronted by a painterly-filtered photo of the real storefront (owner uploads a photo → gpt-image-1 image-edit repaints it → hero). SSR page with OG + JSON-LD GroceryStore/Offer, live deals grid, sitemap inclusion. Migration 571 adds storefront_image_url + public_slug (unique) + public_deals_enabled on aisleask_stores. Yelp/Google auto-fetch of the photo = fast-follow.

  • AISLEASK_STORE_MAP.md — v1 built (2026-07-24): each AisleAsk store gets a spatial 🗺 Map tab — a painterly store-interior background (paste a Midjourney/image URL) with drag-drop section tiles positioned by normalized coords, distinguishing numbered aisles (green) from perimeter departments (Produce/Meat/Deli/Bakery/Floral/Pharmacy, amber) and facilities (Entrance/Checkout/Restrooms/Customer Service, sky). Migration 570 adds aisleask_sections.pos_x/pos_y/kind + aisleask_stores.map_image_url; the flat walk-order list is untouched (the map is a spatial view/editor of the same sections). Built blind — pointer-drag feel is on-device tuning. Later: gpt-image-1 background generation + route-as-path overlay.

  • AISLEASK_DEALS.md — planned (spec): digital coupon/deal integration for AisleAsk (driver: a real prospective user, "Grandma Pat"). Two modes — deals along the way (best deal per section, spoken on glasses) + shop the deals (a new import-sources list source). Data sources ranked: Flipp weekly-ad API (highest leverage, QS-partnership) → Kroger/QFC API → Ibotta/Coupons affiliate (revenue-share, no partnership) → crowd "scan this sale tag" (reuses scanSectionSign + the capture rail — Phase 0, dogfoodable now). Honesty guardrail: store+time-scoped only, source+validity always shown, never fabricate. It's also monetization (affiliate). Phase 0 = scan-tag crowd + affiliate item-match.

  • LODESTONE_PLATFORM.md — planning (2026-07-23): the shared geo-anchored cache substrate under both SIGNAL (game) and Cairn (legacy) — one substrate, many surfaces. Product-agnostic domain model (Anchor / Payload / Trigger / Access / Logbook / Trackable), four subsystems (geo-trigger engine, location attestation = the existential anti-spoof gate on any money, Matt's NLU as command-grammar + talkable-gatekeeper, authoring/moderation), a reuse map onto Lovio/Living-Voice/family-graph/glasses, and a crawl→run build sequence (Phase 0 = Cairn phone MVP → glasses playback → NLU gatekeeper → SIGNAL match layer → attestation → economy-behind-legal). Lodestone = internal codename only.

  • LIVING_VOICE_ROADMAP.md — vision / near-future (mostly not built): the roadmap off the shipped voice-clone atom (your words, your voice — lovio_user_voices + ttsSegment). One engine, three tracks pointed in two temporal directions: Track A — JQ, the forward voice (buildable now: JQ speaks goal-nudges in your own voice, pulsing while it talks; ecosystem companion, DreamPro-light home #1), Track B — Lovio Presence, the enduring voice (north-star, greenfield: a lovio-person avatar you sit across from — WebXR + glTF as the universal on-ramp, 2D talking-portrait via scene-studio lip-sync as B0), and Track C — the Legacy Channel (nursing-home GTM: residents record while they can, heard after they're gone). Consent v2 (broaden-at-clone-time) + the read-only-vs-generative bright line + cost/dignity guardrails as the load-bearing wall. Smallest next slice = POST /api/jq/voice/say.

  • MANTRAS_COACH_VOICE.md — SPEC / not built (2026-07-30): extend the shipped Mantras surface so a playlist can render in a voice other than your own. Phase 1 (shippable now, zero consent): a stock-preset voice source on the mantra playlist (reuse sayInVoiceId + VOICE_BANK), landing the render-dispatch seam. Phase 2 (gated): a coach's consented clone via a scoped, revocable grant (coach_voice_grants) — the key landmine is that sayInVoiceId has NO consent gate (correct for stock, dangerous for a real person), so the coach path gets its own sayInGrantedVoice (grant liveness + roster-eligibility via coaching_memberships + revocation-invalidates-cache), read-only + always-attributed, dark until counsel signs off. Phase 3: a loved one's voice via the same grant + a Family-Wall link. Inherits the Living Voice consent-v2 / read-only-bright-line / cost wall.

  • AR_GLASSES_LIVING_VOICE.md — strategy / not built: the hardware layer beneath the Living Voice — smart-glasses adoption read (three waves: audio+camera AI glasses now → HUD/display ~2027 → true binocular AR late-decade) and the 10-integration map onto our ecosystem, each mapped to shipped infra. Thesis: our stack is voice/presence-first, so "AR integration" for ~18 months means existing surfaces gain a hands-free/audio-first/capture mode (companion phone + Bluetooth + camera export), not an on-glasses app (no open Wave-1 SDK; Android XR is the first open target). Wedge = Lovio in-ear + camera "Hear about this" + JQ ambient nudges; buildable-now first slice = an audio-first playback mode every integration plays through. Inherits the Living Voice ethics/cost wall verbatim; not a pull-forward from Workstream A / Odessa.

  • INSPIRATION_ROOM.md — BUILT 2026-07-12: a WebXR Inspiration Room at /dashboard/inspiration/vr (new room in the VR hub) — a hands-free, auto-advancing montage of uplifting quotes/affirmations + the viewer's own coach encouragement / "on this day" memories / journal photos + curated inspirational clips, under a starfield. Blended server-side (GET /api/inspiration/montage). Clips live in an editable inspiration_clips table (migration 479): hosted MP4s play in-VR via THREE.VideoTexture (a cinema screen), YouTube shows as a poster + out-link in the room and embeds on the 2D page (an iframe can't live inside a WebXR canvas; ToS forbids texturing YouTube). Built on the shipped StreamXRScene/EntryVrScene + VrImage stack. Next: spoken montage (house/own voice) + ambient bed.

  • GLASSES_PLATFORM_INDEPENDENCE.md — decision doc (2026-07-24): do we ever run the glasses without the Mentra app? We're I/O-locked, not logic-locked — JQ/voice/AisleAsk/Sophia/backend are ours; MentraOS only provides the BLE bridge + on-glasses I/O + session relay. Three paths out (cheapest→dearest): phone-only JQ (no Mentra, now — the parallel "our own" track), fork/self-host the open-source relay (resilience hedge, no hardware), own the hardware (OWNED_HARDWARE_HORIZON, company-scale). Only two triggers justify leaving: (1) needing to break the three walls Mentra enforces (ambient/unprompted/world-vision — gated on Sophia + consent), (2) Mentra becoming a platform risk. Recommendation: stay on MentraOS now, keep the brain portable (no product logic in apps/glasses), run phone-only JQ in parallel, hold the relay-fork as a hedge. Migration surface is tiny by design (swap transport, keep the product).

  • OWNED_HARDWARE_HORIZON.md — strategy / not built: the "no limits" scenario under the AR doc — what the product becomes if we own the glasses (open-source Frame-class now → our own resold hardware later) instead of renting Meta/Apple's. The AR + Mobile docs are a map of walls; this deletes three named ones — continuous ambient listening, unprompted proactive speech, continuous world vision — and shows each unlocks a capability we've half-built (forward-voice realtime coaching, Lovio-actually-present, zero-UI eldercare, life-capture journaling, dome/stream overlaid on reality). The catch: those walls were also our privacy protection, so owning the hardware means owning the surveillance question — on-device-first processing + the consent graph + the read-only bright line go from footnote to marquee engineering spec. Path: prove the loop on controllable (Frame) hardware first; earn the resold-glasses bet, don't lead with it. Inherits the Living Voice ethics/cost wall; not a pull-forward from Workstream A / Odessa.

  • POSTURE.md — BUILT (glasses add-on, OFF by default) + hardware design (insoles), 2026-07-27: tech-neck coaching. Glasses (top-down): apps/glasses/src/posture.ts reads the frame-pitch stream — frame level = good, held downward tilt = slouch — and gives ONE gentle spoken cue after a sustained hold (per-session calibrated baseline, hysteresis, 90 s cooldown, quiet hours; calm, never scolds). Split so the hard part is provable without hardware: a pure, unit-tested createPostureMonitor + a single SDK seam (getHeadPitchStream) that degrades to a no-op if the device has no head-position stream, with POSTURE_INVERT_PITCH + POSTURE_SIM_SEQUENCE for on-device tuning / desk validation. Insoles (bottom-up, specced not built): a BLE pressure-sensing insole pair (heel/forefoot/toe FSR array → nRF52 → phone/hub → the same service) reads stance/lean/left-right imbalance the glasses can't see; fused, the two read posture from both ends of the spine. Body-sensing → opt-in, non-punitive, on-device-derived; clinical framing would go behind the Speech-Mirror counsel gate.

  • FAMILY_WALL_SLEEP_STORIES.md — DESIGN (2026-07-18): the Plus "sleep stories" bundle. Big reuse — sleep-story-gen.ts already generates a story_seasons (universe='sleep_story') catalog with narrated chapter_audio_url + listRecentSleepStories/SleepTimerButton. Phase 1 (light) = a per-wall show_sleep_stories opt-in + a 🌙 Sleep-stories wall mode that plays the existing house-voice audio with a sleep timer (no new TTS). Phase 2 = "bedtime stories in your voice" — re-narrate a chapter in the parent's cloned voice (long-form, narration.ts pipeline). Build after #1405 (voice alarms) merges.

  • FAMILY_WALL_HANDOFF.md — START HERE for the Family Wall: the pick-up point after the ~18-PR (#1392–#1409) build-out. What it is now, every shipped feature → migration → key code, the Plus gate state (built but OFF — how to launch it), recommended next builds (Stripe checkout, bedtime-in-your-voice, Graphene+ bundle), landmines (migration-before-deploy, wall-file merge coordination), and a map of the other docs/memories.

  • FAMILY_WALL_MONETIZATION.md — DECIDED direction (2026-07-18), not built: monetize the Family Wall as a freemium subscription ("Family Wall Plus", ~$4.99/mo / $39/yr). Free = one genuinely-useful kitchen wall; Plus gates the cost-bearing + power features (Ask JQ, cloned-voice messages, intercom, multiple/bedroom walls, kids' chat). The paywall protects margin (LLM/TTS/moderation are exactly the gated bits); "no hardware to buy" is the acquisition moat vs Skylight/Hearth. Sequence: build the Stripe gate FIRST (not ads); skip ads for a family surface. Spec for the gate build inside.

  • FAMILY_AI_PROVISIONING.md — CONCEPT (2026-07-29); named Cornerstone + public page/waitlist live (2026-07-30); product not built: "Bedrock for families" — a family AI gateway + governance layer on the Family Wall giving parents visibility, age-graded policy, and data ownership over their kids' AI use. The unserved consumer mirror of enterprise AI provisioning. Defensible via a local-hardware dovetail with Matt/Cicero (storage + on-device AI in the home, not a vendor cloud — the honest "family owns its data"); gives the Sophia/cicero.sh household-only license its use case. Design law: loving oversight, not surveillance (age-graded visibility that decays toward teen autonomy; the AI flags safety concerns rather than parents reading transcripts). Build software-first via Family Wall Plus; hardware tier is the endgame, not the MVP (don't gate v1 on a box that may not ship).

  • FAMILY_WALL_JOIN_INVITE.md — BUILT v1 (2026-07-18): "📨 Invite someone to the wall" on /dashboard/family. Sender picks the role (default full "can help manage" = create a member + family account-link invite → household access on accept; or view-only = share the wall token link). Little ones with no email → their Personal bedroom wall (parent-provisioned token screen), never an email to a child. Reuses migration 452 + wall links; no new backend.

  • FAMILY_WALL_JQ_ACTIONS.md — DESIGN (2026-07-18): make the wall's "Ask JQ" act, not just answer — add a shopping item / set dinner / post a note / create a member-assigned reminder by voice. Introduces the shared foundation both this and the intercom need: wall device identity (location_kind shared|personal + owner_member_id). Attribution rule: a personal (bedroom) wall auto-assigns to its owner; a shared wall makes JQ ask "who's this for?". Reuses #1393's add endpoints + allow_editing gate; the one net-new table is family_reminders (one-off, member-attributed — NOT a recurring routine). Build after #1393 merges.

  • FAMILY_WALL_INTERCOM.md — DESIGN (2026-07-18): turn the wall screens into an intercom — which screens are online (reuse last_seen_at), shared-vs-bedroom (location_kind), avatars of who can receive (join family_presence), quiet-time windows (hard rule for bedroom/minor screens), and tap-to-talk delivery (v1 = per-wall inbox folded into the 60s view poll; reuse the wall audio path). New send capability → its own allow_intercom opt-in. Shares device identity with the JQ-actions doc.

  • FAMILY_PHOTO_FRAME.md — DESIGN, COUNSEL-GATED: a software-only family photo-frame/kiosk (undercut Skylight/Hearth hardware) — QS renders the display (reusing its screensaver), HJ hosts the photos on the existing family model (family_members + routines + JQ Bridge, already minors-aware). Architecture settled (a: HJ hosts originals, QS renders a scoped short-TTL derivative feed and caches NOTHING) but no code/feed/contract until counsel clears the minors'-photo consent + access-scoping model — this doc is the counsel-review artifact (consent separates view-from-expose, per-member EXPOSE consent, instant revocation, the COPPA/BIPA/GDPR open questions). Owner green-lit pursuing (2026-07-18 = start the counsel pass); build waits on counsel.

  • COMMUNITY_WALL_SURFACE_SPEC.md — PROPOSED, for owner review (2026-07-19): the HiveJournal surface spec for the cross-product Community Wall (HJ surface × PorchHearth engine; contract lives in crosstalk). Resolves the five open questions the contract left to the HJ owner — recommends a new authenticated /community route (never a Family Wall block, bright line #2), a tiered least-PII membership model (browse → verified neighbor → trusted; city-centroid only, adult-gated), coarse-centroid + radius geo scoping, server-proxied JSON reads (About-That posture: LIVE /public/listings meals feed now + PorchHearth to build /public/needs), and a counsel gate on all neighbor-facing writes/handoffs. Phased: read-only meals (0) → needs feed (1) → claims/handoffs, counsel-gated (2). Owner sign-off unblocks PorchHearth's /public/needs + a Phase-0 read-only build. Inherits the 10 binding bright lines wholesale.

  • ABOUT_THAT_REAL_ESTATE_GTM.md — positioning decision (2026-07-18): where to point realtors — About That (HiveJournal/Emberkiln) is the audio layer, QuickSites is the website, and which channel an agent gets turns on "do they already have a website?" Primary = hivejournal.com/about-that/for-real-estate (works on any existing site); QuickSites is the channel for web-needing agents (QS provisions About That for them via the #1332 partner path). Plus the future flag: a realtor-native brand/domain when it's earning (the coaching-skin pattern), deferred.

  • ABOUT_THAT_BROKERAGE_SEAT_MODEL.md — scoping / not built: the real product behind the $399 About That brokerage tier (front door shipped: landing + interest capture, migration 515). The three capabilities (team account, per-agent voice, per-listing render in the listing agent's voice), the org-design forks needing owner input (lightweight brokerages+brokerage_members vs full org; data-agent on the snippet vs per-agent embeds vs URL mapping; flat vs per-seat billing), the non-negotiable consent/voice-safety gate (only voice an agent with their own consented clone), a phased plan (0 done → 1 team+bill-together → 2 one-snippet-right-agent → 3 polish), and the reuse map. Pairs with the "About That brokerage seat model" product task.

  • GLASSES_BRINGUP_HANDOFF.md — the pick-up point for finishing the glasses: everything (single app, AisleAsk, Mantras, durable token, multi-user linking) was built + merged the day the hardware arrived; migrations 500–513 applied. What's left is on-device only — finish the Railway service, Mentra console URL + camera permission, single-user smoke, then multi-user validation with a 2nd wearer (incl. the one real unknown: does AsyncLocalStorage propagate through Mentra's event handlers on-device — with the small fallback fix if not), plus blind-built tuning notes (intent regexes, photo size, transcription finality, ducking).

  • GLASSES_MULTIUSER_AUTH.md — scoping / not built: multi-user account-linking for the glasses app — the prerequisite for ANY Mentra-store distribution. Today the app is single-user (one static HIVEJOURNAL_TOKEN); a store app installed by strangers needs each mentraUserId mapped to their OWN HJ account. Trust model = an app-level secret (proves "this is the JQ app," reuses the #1332 partner primitives) + an owner-consented per-user link (code-based: dashboard mints a code → wearer says "link my glasses <code>" → binds mentra_user_id↔HJ account), with per-session short-lived tokens minted only for linked users (no long-lived secret on the device). glasses_device_links table; /api/glasses/link + /resolve (app-secret authed); phases 0(done)→1(cohort)→2(store). Companion strategy in the "Mentra store distribution" task.

  • GLASSES_INFORMED_USE.md — DRAFT, COUNSEL-GATED (scope item 4 of the ToS task c09bd5aa): the informed-use acknowledgment for Downstream Glasses' own-voice layer — draft setup-screen copy + contraindication guidance (psychosis history), the position that this beats a disease waiver, the shipped design mitigations counsel can rely on (explicit-trigger-only speech, the /dashboard/glasses spoken-events log, kill switches, consent-gated clone), and six open questions for counsel. Nothing ships until reviewed.

  • JQ_SPEECH_MIRROR.md — strategy / prep, COUNSEL-GATED: a therapist-recommended self-awareness use for the glasses — a patient opts into phrases/patterns they want to catch themselves using (self-criticism, absolutes, catastrophizing, a personal tic), and the glasses reflect them back in the moment with a gentle, non-punitive cue. Bright lines: a mirror, not a therapist — not diagnosis/treatment/medical-device; the cue never judges; therapist recommends, doesn't operate/surveil; on-device matching (the utterance never leaves the device); opt-in + patient-owned + deletable. Reuses the shipped glasses loop (onTranscription → local watch → debounced cue). Built so far: a generic detection primitive (apps/glasses/src/watch.ts) that ships OFF by default (WATCH_ENABLED), nothing patient-facing. Inherits the Legacy Channel counsel gate + the owned-hardware on-device spec.

  • HIVEJOURNAL_VR_HANDOFF.md — map of the whole immersive layer (start-here to continue WebXR work): every VR surface (The Cockpit, Entry VR, Immersive Stream, Dome, Story Player, Wall Breaker) + the VR hub front door at /dashboard/vr, the shared pattern they all follow (dynamic(ssr:false) scene, comfort rule, page-owns-state, fiber v9, the shared components/vr-common/VrImage.tsx), the one caveat (all built blind — needs an on-device tuning pass), and ranked next ideas.

  • IMMERSIVE_3D_HANDOFF.md — shipped / in tuning: the technical handoff for the WebXR work — the immersive Stream (/dashboard/stream/immersive: notes drift on a river, typed cards, curated currents, atmosphere, dome-houses + visiting) and the Dome (/dashboard/dome: the real dome.glb interior whose décor mirrors DreamPro adherence, hubs to Write Café + a cross-pollination corkboard). Where to resume: files, data endpoints, the open blocker (bake DEFAULT_ADJUST from the user's in-scene Adjust/Edit Copy-settings JSON), the landmines (fiber v9 for Next-15/React-19, @types/react pin, @iwer/devui stub, first-person not orbit, SketchUp Z-up sphere center-anchor), and the roadmap. Vision lives in the AR doc above.

  • GRAPHENE_VR_STORY_PLAYER.md — plan / not built: a public, standalone Graphene story player for Meta Quest (WebXR runs in the Quest Browser today — distribution is a URL, no App Store gate). You're inside a chapter's art (360° image sphere) with the narration playing; you find the author's hidden Drift passages in the space; at branch points you see which way the crowd went. The bet: a genre that isn't on Quest, that wins by not competing on graphics (sphere + audio + text = near-zero GPU). Recon-complete: reuses the shipped WebXR stack (IMMERSIVE_3D_HANDOFF.md), the /:id/chapters media call, and the already-built Timelines (CYOA, choices already persisted + crowd-split already computed, just unexposed) + Drift (drift_treasures, findable passages) systems. Phase 1 = single-story sphere+audio room; the only new rendering piece is the image-textured 360 sphere. Phased plan + open decisions in the doc. Enrichment v1/v2 shipped (characters/moments/items float in on their narration beat).

  • GRAPHENE_VR_WALK_MODE.md — plan / not built: a second VR mode, sibling to the standing listening room — you walk through a 3D environment (a forest) and physically discover the story: memory marbles buried at coordinates (dig → a server-validated Drift find + coins) and journal pages blown by the wind (catch → a Drift passage), straight from the Graphene lore. ~70% assembly of shipped parts: GLB loading is proven (DomeScene useGLTF), locomotion ships in @react-three/xr v6, marbles ≈ drift_treasures, wind-pages ≈ the StreamNote drift motion. Net-new = the walkable scene + teleport locomotion + treasure coordinates. Sketchfab = asset source + prototype, not the product surface (a viewer we can't wire to our data). Landmines: comfort (teleport-first), Quest perf (low-poly + instancing), model licensing. Phased plan + open decisions in the doc.

  • WORKOUT_WINDOW_WALL_BREAKER.md — plan / not built: a VR accountability game — you stand in a matrix of cubicle walls and break as many as you can each day, where breaking a wall = nudging a real Workout Window / DreamPro participant, and you earn Drift coins when the person you nudged checks in. The hard part isn't the VR (reuses the immersive stack + Drift coins + the marble/proximity gesture) — it's consent + attribution: you can only nudge a consented circle (bright line), via a nudges table + a check-in→coin hook. Sender's game here; the roll-in marble nudge (separate P2 task) is the receiver's half of the same loop. Phase 0 (the consented nudge→check-in→coin loop) is SHIPPED end-to-end (circles + nudges + coin payoff + roll-in marble). Phase 1 (the VR cubicle matrix) build handoff: WALL_BREAKER_PHASE1_HANDOFF.md.

  • WALL_BREAKER_PHASE1_HANDOFF.md — handoff / start-a-fresh-session brief for building the Wall Breaker VR cubicle matrix (Phase 1) over the shipped Phase-0 loop. Gives the game concept, the exact Phase-0 API to read/call (walls = circle members, break = nudge, coins are automatic on check-in), the WebXR stack to clone (StoryWalkScene — locomotion + the proximity gesture), a recommended v1 shape (a ring of breakable walls around a standing player), the open decisions to confirm, the gotchas (async coins, DB-enforced consent + daily cap, built-blind), and a first-steps checklist.

  • MOBILE_JQ_PRESENCE.md — strategy / not built: the native-mobile (iOS/Android) companion to the AR doc — how much of "JQ is with me, talks to me, and I can talk back without opening the app" the OSes actually permit. The two hard walls (no always-on wake word; no unprompted background speech), the sanctioned hooks that compose into presence (voice-clip-as-notification-sound, Siri App Intents, local scheduled nudges, CarPlay, Live Activities), a 10-integration map, the iOS-strong-voice-in / Android-strong-proactive asymmetry, and the Expo lift (easy: expo-notifications/expo-speech; native dev-build: SiriKit/CarPlay/Live Activities). Wedge = notification-sound nudge + Siri "ask JQ" + local scheduled nudges; all reuse the shipped voice layer. Inherits the Living Voice ethics/cost wall (calm-not-noisy is sharpest here). Not a pull-forward from Workstream A / Odessa.

  • JQ_FORM_FILLER.md — Path A v1 BUILT (not shipped) (P2, task 5e88c164): "Bro, you still fill out forms? Give it to JQ, he lives for that sh*t." One-line strategy: the extension owns every form that's a screen; the glasses own every form that isn't (paper/kiosk/other display) — disjoint worlds, with Path C the bridge. Path A (built) = extension scans a form's field shape → backend POST /api/jq/form-fill/map (jq-form-fill.ts) maps it against the user's on-device notebook (keys only; values never leave the browser) → fills highlighted, empty-only, never submitted with an Undo bar; password/SSN/payment hard-excluded both sides. Path B = glasses OCR read off-screen forms (honest limit: for a laptop web form the glasses buy nothing). Path C — Scan-to-Form (the moat) = scan a paper form → reconstruct as a hosted fillable web form → JQ auto-fills from your notebook → review → submit; beats Lens (scan→static doc) + Jotform (build-by-hand) by combining scan+fillable+auto-filled+hosted. Turns JQ from reflective to useful. Gates: PII/consent (bright-line exclusions, no auto-submit) + a real notebook data model (learn-from-fills → retention flywheel). Enterprise edition = the encrypted closed-system data channel as the compliance story; insurance adjusters an early buyer (adjuster scans paper FNOL → hosted digital form) via the Crosstie warm channel — clear IP/conflict first.

  • DOWNSTREAM.md — v1 BUILT (not deployed) — the user's north-star "holy grail" app. Downstream — decide with the version of you who has to live with it. Models a deferred/maintenance thing not as a due date but as a curve (how cost + stress grow over time; internal model name = "stress curves"), and triages your list by where each thing is on its curve, leading with relief ("let these drift; do this one") — a permission-to-defer engine, never a nag. The maintenance half of the self (DreamPro = the aspiration half). Central intelligence = the cost-vs-stress mirror (high-dread/low-cost → just do it; low-dread/high-cost → the sneaky trap, warn). Curves are inferred (LLM) from a plain-language "thing I'm putting off", never hand-drawn; the resolve-time "how bad was it really?" tap is both personal calibration and the open-science data point ("the shape of human procrastination cost", riding the citizen-science infra). Built + merged: the curve model (5 archetypes, tested 8/8), inference, triage, the mirror, resolve/calibrate, snooze, and curve-timed nudges (in your own voice, in-app + web push). To continue, read DOWNSTREAM_HANDOFF.md — current state + exact deploy steps (migrations, VAPID env) + open threads. Next: glasses nudge-delivery, normative/open-science crowd curves, the ambient "Downstream Glasses" layer.

  • DOWNSTREAM_AUDIO_IDEAS.md — idea / sketch, nothing built (P3 tasks 1180ea1a / efdaeff0 / b5dfdad6): three audio-surface directions on Downstream's shipped nudge plumbing — (1) in-ear soundtracks on Downstream Glasses (rides the same session.audio.playAudio MP3 path; real work = ducking under JQ + licensing), (2) a built-in Pomodoro that turns triage's "do this one" into a bounded focus session and decays the item's curve on completion, and (3) an ultradian-rhythm engine (~90-min BRAC, Endel-style) as the timing layer under both — adaptive audio + phase-aware suggestions, phase estimated from time-since-wake → behavioral taps → opt-in watch HR/HRV. Calm-not-nagging; open-science energy calibration like the resolve-time taps.

  • INTERVENTION_ROI.md — v0 BUILT 2026-07-15 as "Levers" (task 7cff4348): the return-on-action engine, conceptual complement of Downstream (stress curves = cost of inaction; Levers = return on action). Track a level (energy, mood, hunger, a lab value) + log interventions (action X) with an optional predicted Δ; the ROI list scores actual vs. your prediction ("nailed it" / "off by N"). At /dashboard/levers; backend levers-core.ts (pure, tested 8/8) + /api/levers + migration 488. Honest v0: before/after correlation (not causal proof); the prediction-vs-reality loop is the overclaim-proof wedge. Ahead: X-vs-Z counterfactuals, between-people/normative dose–response, wearable/lab import.

  • DOWNSTREAM_SOUNDTRACKS_HANDOFF.md — start-here to build the in-ear soundtrack layer (task 1180ea1a). Audio source decided = Suno, and the ingestion is already built: reuse creator-audio-library.ts (importFromUrl scrapes a Suno share page → re-hosts the MP3 so it survives CDN rotation) + storeUpload. v0 build plan (thin downstream_soundtracks table with a mood col for the §3 adaptive tie-in, /api/downstream/soundtracks, a looping glasses player that ducks under JQ). The one on-device unknown: whether session.audio.playAudio mixes-or-interrupts + resolves-at-end (decides the duck + loop strategy).

  • DOWNSTREAM_HANDOFF.md — session handoff / start-here to continue Downstream. Build state (merged #1266 vs open #1267), the ordered deploy steps (apply migrations 483/484 + set VAPID env + merge #1267 + toggle the downstream_nudge cron on), the file map, open threads (glasses delivery, normative curves, the Downstream Glasses rename sweep + gesture check-ins + Sophia NLU), and the repo landmines (ESM jest flag, gh pr edit blocked, migration-gate flow, cron conventions).

  • LEGACY_CHANNEL_ELDERCARE.md — strategy / not built: the detailed eldercare GTM for Living Voice Track C, revising its strawman — the wedge is not a B2B facility license but the adult child at the moment of placing a parent in care (family pays; facility refers). Grounded in a cited market brief + a full Lovio-infra inventory. The strategic gift: buyer intent, clinical validity, and legal cleanliness all peak at the same early/pre-placement moment. Headline build: a subject-consents / facilitator-operates consent model (the current bright line forbids child-facilitates-parent), plus death-triggered delivery, custody-that-outlives-the-owner, family fan-out, and guided reminiscence prompts. Whitespace = cloned voice + after-death delivery + facility distribution (no competitor combines all three; the "talk to the dead" graveyard warns against server-dependent playback → own-your-masters). Counsel-gated before C0.

  • LEGACY_CHANNEL_CONSENT_MODEL.md — design / not built, COUNSEL-GATED: the keystone build under the eldercare Legacy Channel — the subject-consents / facilitator-operates consent model that lets an adult child (facilitator) capture + manage a voice clone of their parent (subject), which the shipped Lovio self-consent model forbids. Splits the conflated user_id into subject / operator / consenter; makes consent a ledger (voice_consents table), not a column; proposes schema + the v3 read-aloud consent statement + capacity/surrogate workflow + the ELVIS-Act/AB-1836 heir-durability answer (living, voice-specific, posthumous-explicit consent). Ends with the concrete questions for counsel (incl. BIPA voiceprint exposure, whether a surrogate can authorize cloning at all, heir-durability). Backward-compatible with the self-model. Nothing ships until an attorney signs off.

  • LIGHTHOUSE.md — vision / near-future (not built): a reconnection-narrative surface for alienated parents, composing HiveJournal journals + Odessa (reframe) + Lovio/FutureSend (delayed vault) + printed keepsakes, white-labeled through parental-alienation coach Ryan Thomas. The load-bearing calls: a lighthouse-vault child-facing model (the child opens on their terms, never a push) with a bright-line "never distribute before 18" rule (at 18 or when they reach out), and practitioner-gating as the safeguarding architecture against the abuser-as-user vector. Parent-facing healing product ships first; child-facing vault only after safeguarding + legal terms lock.

  • HABITFORGE_PAGE_REACTIVATION.md — plug-and-play kit for repurposing the dormant habitforge.com Facebook page (~2.7k cold 2009–2015 followers) toward Odessa: the strategic read (the audience psychographic, not the count, is the asset; the habit→story throughline is the bridge), Facebook rename mechanics, and ready-to-post copy — pinned bridge post, a 3-post reactivation sequence, About/bio blurbs, and cover-image text.

  • PROSE_QUALITY_BENCHMARK.md — decision doc (A4): our AI prose vs Sudowrite's Muse. The two opposite bets (Muse = fiction-tuned base model; us = general model + bible grounding + 13-critic iterate-and-refine loop), where we already compete + the real gaps (no voice-exemplar path, no sentence-rhythm lever, cost-tier draft model, no objective eval), a ready-to-run benchmark methodology (rubric + blind LLM-judge + model matrix + decision bar), and a ranked recommendation: don't out-Muse one paragraph — ship Style Examples + a rhythm critic, stand up an eval harness to pick the draft-model tier from data, and keep the consistency/pipeline moat.

  • WRITING_EXPERIENCE_A1.md — design doc for Workstream A: give the season/episode model a creator-facing manuscript editor, built off the existing HiveJournal writing surfaces (journal composer environment + prose_versions history + takes/critique refinement + the bible & read-layer tabs & JQ canon mode). Inventory findings (no rich-text lib; chapter prose is view-only today — the gap), the two real decisions (data home = season/episode model; editor tech = enhanced textarea for v1, TipTap for v2), a reuse map, and phasing (A1a editor shell + direct prose edit → A1b bible side panel → A2 inline AI actions → A3 chat-with-manuscript). Competitive angle: "consistency is free."

  • AUTO_DEMO_HANDOFF.md — operational handoff / start-here to continue the auto-demo work. Phases 0–3 are built + merged (PRs #1192–#1197); what remains is prod deploy/validation + refinements, not new capability. Covers the deploy checklist (migrations 472–475 + env vars — everything degrades silently until applied; 474 is the critical one — studio_demos.COLS already SELECTs its columns), what's live vs dormant, ranked next steps (full-registry auto-PICK, stale-demo regen, earned autonomous posting, true screen-recording infra), how to validate the built-blind video capture on prod, a file map, and the gotchas.

  • AUTO_DEMO_DISTRIBUTION_AND_CAPTURE.md — decision doc for the two remaining auto-demo next-steps: #5 true screen-recording video (finding: the full chromium binary is already installed — the limit is the headless-shell launch mode, not a nixpacks change; recommends validating 2b screenshots first, then a code-only full-chromium capture behind a flag) and #6 YouTube/TikTok/IG distribution (finding: demos are 16:9 landscape but the console's platforms are 9:16 vertical — YouTube-landscape fits now, the rest need a vertical re-render first). No code/infra changed; each ends with a concrete recommendation + the decision to make.

  • AUTO_DEMO_SYSTEM.md — design + live status: a system that auto-picks a feature (diffing the feature-index.ts registry), auto-generates a hands-free guided demo (LLM-authored steps[] grounded by a persona-browser look at the live UI + house-voice narration + a Playwright screen-recorded MP4), and auto-publishes it to a public /demos page that doubles as advertising — owned by a new "Demo Manager" AI persona role (is_demo_manager, modeled on is_platform_writer) that keeps the library current as features evolve. Finding: ~80% exists (Demo Studio studio_demos+GuidedDemo, studio-narrate house voice, persona-browser Chromium, season-video/render-kit ffmpeg mux, Bluesky auto-post). Three real gaps: LLM demo authoring, Playwright recordVideo capture, the public page. Key decision: a generic persona-browser verb set as the demo action vocabulary (unifies "persona browses" + "demo drives"). Governance = heartbeats + cron kill switches + approve-before-post + honesty bright line. 5-phase plan.

  • DEMO_CONTENT_SYSTEM.md — demo personas + roster + bounded enrichment (migration 559). Fixes auto-demos screenshotting the login wall (never ship a sign-in page as a feature frame; verify the capture's magic-link session). Reuses existing AI personas tagged by ai_personas.demo_role (@ishaan-r user, @jordan-k-3/@leona-g interaction, @arjun-k admin), designated via scripts/designate-demo-roster.ts, enriched by a targeted, spend-gated demo_roster_activity cron (only the roster, not persona_sim's every-persona sweep). Bring-up checklist + next phases (per-surface capture identity, multi-persona interaction demos) inside.

  • NOVEL_STUDIO_HANDOFF.md — operational handoff for the 2026-07-10 Graphene-lore → Novel-Studio push (14 PRs). The deploy checklist (apply migrations 464–467 to prod + env vars — everything degrades silently until then), what shipped by area, decisions made vs. open (naming reconciliation, external-creator RLS), and ranked next steps with risk notes. Start here to resume.

  • NOVEL_STUDIO_PLAN.md — vision/plan to evolve the admin "Lore Studio" into "The Studio," the flagship end-to-end novel-writing surface. Core finding from a full-codebase capability inventory: nearly every piece already exists (manuscript editor, story bible, JQ canon agent, inline AI, audiobook suite, screenplay engine, Production IR, distribution, commerce) — so this is a unification into one author cockpit (bible as spine, JQ as companion), not a greenfield build. Contains the capability→feature map, a five-mode cockpit interface design (Draft / Listen / Adapt / Produce / Publish), a phased plan, and the open decisions/gaps (llm.ts Anthropic tool-calling, external-creator RLS, naming vs /studio/write). Art-first per Odessa.

  • COMPARE_CLUSTER_AUDIT.md — audit of which products should have a competitor "vs" SEO cluster (/compare/<product>, honesty-first) + the registry service + quarterly cron that keeps them fresh. Live: Family Wall, journaling. Top build-candidate: EmberKiln/Graphene story studio. Skips the counsel-gated/niche surfaces. Registry = services/compare-registry.ts; the cron files a refresh/build product_tasks item per stale cluster / gap.

  • COMPETITIVE_LANDSCAPE_STORY_SOFTWARE.md — living competitive doc, re-analyzed weekly. Where our story/universe/character/production stack stands vs. Novelcrafter, Sudowrite, World Anvil, Campfire, Novarrium & the rest of the "story software" market. Strategic frame (we're a production pipeline, not a drafting tool — canon → audiobook + screenplay + video from one source of truth), a feature scorecard, per-competitor profiles, where we lead/lag, and the plan (Workstream A = best-in-class writing experience, B = canon intelligence incl. JQ Canon Keeper, C = production moat, D = positioning). Weekly-refresh protocol in §7; recurring reminder in .claude/scheduled-prompts/.

  • SCENE_STUDIO_ARCHITECTURE.md — design doc (not built) for the first step toward a movie-creation studio: generalize the Rehearsal Promo Studio's brief → shots → stills → assemble loop to turn a Graphene chapter into a dramatized scene (then trailer, then short). Reuses the existing story/script/audio layers; pipeline + proposed schema + Replicate image-to-video + consistency strategy + phasing + honest constraints. Ships under EmberKiln, art-first per Odessa.

  • REVERSE_SCREENPLAY_ENGINE.md — design doc (not built) for the missing "script" layer in story→script→movie: adapt a finished Graphene novella into an industry-standard screenplay that is both a sellable human artifact AND the clean scene boundaries Scene Studio consumes. Thesis: an adaptation engine, not a formatter — grounded in the existing story bible (dramatic_role / knowledge_layer / chapter_stakes / voice_brief). Fountain canonical (+ FDX/PDF export), target_pages compression dial, 5 adaptation passes, a screenplay critique panel + adaptation-fidelity rubric + golden tests, proposed schema (migrations 411+), and the Scene Studio contract. Reuses the chapter take/critique/version machinery. Art-first per Odessa. (Built — phases 1–4 shipped; see INDEX.)

  • SCREENPLAY_SCENE_STUDIO_INTEGRATION.md — design doc (not built) for letting a chapter hold multiple coexisting labeled breakdowns so a re-segmented screenplay (N scenes from 1 chapter) maps into Scene Studio additively instead of overwriting. Sizes the one-breakdown-per-chapter constraint (scene_projects.episode_id UNIQUE, ~60 touch points) and weighs Option B (full re-key to project-id, ~2–3 wks) vs the recommended Option C+ (promote breakdown_versions into a labeled, losslessly-switchable breakdown store + a Scene Studio picker; ~1 session, 1 trivial migration, no breaking change). Makes the "To Scene Studio" hand-off purely additive. Task efbc2b48. (Built — C+ shipped.)

  • JQ_CANON_KEEPER.md — design doc (not built) for making JQ (the AI companion) a conversational organizer over story/universe canon — manage universes, characters, settings, motifs, planted threads by talking to JQ instead of editing JSON. Thesis: JQ is already a function-calling agent that already writes story_universes/story_seasons, and the bible's applyDelta is already a versioned/audited safe-edit path — so this is "add tools + a canon-scoped chat mode," not new infra. Covers the tool surface (read + write wrappers over story-bible.ts / universe-canon.ts), the canon-mode conversation scope, the 3 decisions (model: gpt-4o-mini→gpt-4o/Sonnet for canon; per-resource ownership; propose-confirm vs auto-apply), the "organizer" canon-health payoff, and a 3-phase path (read-only → conversational edits → proactive organizer).

  • QUICKSITES_BLOCKS_RETURN_BRIEF.md — the quicksites session's reply + HJ's answers (the cross-repo handshake): quicksites shipped the About That block + real-estate listing card same-day; their requests (sandbox embed → LIVE 22e4692a…, Voice Welcome contract → proposed + task logged, per-site embeds + provisioning API → decision accepted + task logged, loader confirmations → answered) and their React-integration contribution (now in ABOUT_THAT.md).

  • QUICKSITES_BLOCKS_BRIEF.md — handoff brief for the quicksites.ai repo/session: block-type backlog for the sitebuilder + ecommerce service, led by the moat blocks only the HiveJournal stack enables (About That embed, owner-voice welcome, product pitch panels, audio FAQ) then conversion/trust/vertical tiers; includes the About That integration contract (loader snippet, domain gate) and the real-estate listing-card loop that makes quicksites and the About That $79 agent tier sell each other.

  • setup-guides/UNSPLASH.md — optional UNSPLASH_ACCESS_KEY for the Family Wall rotating backgrounds + Ken Burns screensaver.

  • setup-guides/ABOUT_THAT_PAID_LAUNCH.md — how to turn on the About That real-estate paywall (agent preset only, $79/$399; founder/candidate free). Dark behind NEXT_PUBLIC_ABOUT_THAT_PAID_MODE; create 2 Stripe prices → set env → flip flag. Includes the SQL to comp a user (Ryan's 90-day deal).

  • NEXT_SESSION_HANDOFF.md — the current entry point for a fresh session: leads with a fresh batch of new use cases (QS-integration blocks on already-shipped rails, new HJ initiatives, cross-cutting enablers, owner-gated money/consent items), then state of play + the open deploy gate (apply migrations 500–503) + recommended "start here".

  • ABOUT_THAT_HANDOFF.md — 2026-07-17 handoff snapshot: everything shipped this session (PRs #1299–#1313), live-vs-pending gates (paywall is dark; how to flip it), the QuickSites crosstalk mesh + contracts, the 8-idea funnel, and recommended next builds (Site Concierge, AisleAsk, Author Sites launch).

  • ABOUT_THAT.md — v1 BUILT 2026-07-16 (P0): "About That" by Emberkiln — an embeddable audio player for third-party sites (one script tag → iframe player) that speaks about the page it's on: spoken summary, explain-like-I'm-10, or the flagship Pitch Panel (the owner's cloned voice pitches the page's idea; an AI investor pushes back — original format). Lazy render on first listen, content-hash cached; domain allow-list + daily caps + IP throttle as the abuse/cost wall. The strategic bet: every embed is Emberkiln-branded distribution on someone else's site.

  • PODCAST_DISCUSSIONS.md — shipped (creator studio): a topic / pasted text / URL / journal entry / story → a two-person podcast script (AI host + you) → rendered to audio in your own cloned voice (auto-wired from your Lovio clone). The NotebookLM-style "discuss my content" form of the EmberKiln every-form thesis. Covers the sources, the pure golden-tested script parser, the render path (reuses the audiobook TTS/stitch/store plumbing), SSRF-guarded URL extraction, and the two voice-clone tiers — Quick (60s) and Studio (upload more audio) — at /dashboard/lovio/voice-setup. Creator console at /dashboard/podcast (creator-gated; render bounded by TTS quota).

  • SHORT_FILM_STUDIO.md — live roadmap turning the (now-built) Scene Studio into a short-film studio: 7 phases — universe canon library (chars+places) → canon image gen + editor UI → Scene Studio cross-pollination + Places → shot timeline editor → lip-sync → integrated sound → model currency. Honest gap framing (the distance to a finished film is product layers, not models).

  • EMBERKILN_PIPELINE_ARCHITECTURE.md — north-star + live status for the unified content-production pipeline (Work → Production IR → render kit → recipes). Diagnoses the duplication across audiobook / Scene Studio / reels / screenplay / print and lays out the incremental, behavior-preserving path. Steps 1–2 shipped: the render kit (render-kit/) — provider-client adapters, ffmpeg primitives, the composeStillVideo recipe (reels + cafe-shorts), and the loudnorm recipe (mastering + ACX), each golden-tested (#820–#827).

  • EMBERKILN_PRODUCTION_IR_TEST_GUIDE.md — prod smoke test for the merged IR adoptions (#829 print, #831 reel-source, #832 screenplay). The pure assemblers are golden-tested, but the DB loaders run prod queries with code-inferred columns (and MCP ≠ prod), so they need a real-data pass: three feature tests (print export, reel-from-entry, screenplay Fountain/FDX), the column risk-surface, where errors surface, and a fail→revert playbook.

  • EMBERKILN_PRODUCTION_IR_DESIGN.md — Step 3 design + live status (first slices shipped, #829/#831/#832): the Production IR, one segmented Work → Section → Segment contract (+ shared Cast) that every renderer reads from, plus the source→Work router. Grounded in the real shapes the five surfaces use today (the segment spine already converges; story_seasons is already the hub; the cast/voice model is already shared). Headline decision: the IR is a derived in-memory contract, not a new table — a behavior-preserving refactor, adopted one renderer at a time (print first, diffed). Strawman types + per-surface projection table + open questions for sign-off.

  • OPEN_ENERGY_ROADMAP.md — Original 10-phase Open Energy design (all shipped)

  • DREAMPRO_COMPLETE.md — DreamPro system overview (personal goals + step breakdown)

  • DREAMPRO_COACHING_SYSTEM.md — The DreamPro Coaching System: plan to repurpose DreamPro.io as a turnkey, gamified fitness-coaching platform a channel partner (John Rowley) rebrands, recruits coaches into, and earns a recurring override on. Two-tier ClickBank-style economics on the existing Stripe Connect payout rails; citizen science migrates to openenergy.*. Composes Workout Window + DreamPro templates + JQ Connect/Throughline + JQ companion + Rehearsal Room. Decisions locked + 5-phase build + honest gaps.

  • COACHING_BRAND_MAP.md — PROPOSED brand architecture for the coaching engine: one niche-agnostic engine + niche-native branded skins on top. Fitness skin → Workout Window (John Rowley; was "DreamPro"), spirituality/embodied skin → Lovio or Lantern (sister's network; front door /for-guides, built), dreampro.io freed up. Every name is a placeholder pending sign-off; captures the open decisions (Workout Window reserve-the-word refactor, Lovio-vs-fresh-name fork, GTM sequence via Kalyn Parker). The /for-coaches niche-neutral copy pass that proved the engine is skin-able is held to ship in the same bundle.

  • WORKOUT_WINDOW_APP.md — PROPOSED / meeting-prep: give John Rowley his own native iOS + Android app on the App Store / Play Store as a branded flavor of the existing apps/mobile codebase (the Workout Window screens are already built). One codebase, APP_FLAVOR switch drives identity/theme/nav/signup-tag; the real long pole is store logistics (developer accounts, a Workout Window domain, v1 scope, the Apple-IAP-30% trap), not code. Phase 0 = a TestFlight demo John holds in the meeting.

  • DREAMPRO_COACHING_CHANNEL_SCHEMA.md — Phase-2 channel-economics data model for the above, ready to implement: attribution graph (channel_partners / coaches / referral codes / memberships), the 3-way split policy, and the ledger extension that solves the 2-way→3-way mismatch by booking two creator_earnings rows per invoice on the existing Stripe Connect rails. Draft SQL + Stripe separate-transfers mechanics + RLS + build checklist.

  • DREAMPRO_COACHING_SEAT_SCHEMA.md — Phase-1 Coach Seat data model + brief-generator contract, ready to implement: coaching_seats (per client, swappable AI/human holder + supervisor_user_id) / _decisions (the AI-draft→approve→deliver lifecycle) / _goals / _invites, built on the shipped platform swappable-role pattern (migration 234). Includes the daily coach-brief cron contract (reads Throughline trends + Workout Window adherence), the 3-tier mode resolution, the wellness-lane guardrail, delivery-via-reuse, RLS, and build checklist.

  • DREAMPRO_COACHING_PERSONA_DOGFOOD.md — plan to enroll AI personas as is_seed coached clients so the coaching surfaces (coach review queue, cohort leaderboard, brief inputs, analytics) are populated + dogfoodable from day one, plus optional historical backfill. Two hard guardrails: is_seed everywhere (wipeable) and personas NEVER touch real money (the split path skips seed/persona memberships via isAiPersonaUserId()). Reuses Workout Window check_in_probability for adherence realism. Admin pitch surface for John lives at /for-john (super-admin-gated).

  • DREAMPRO_COACHING_BOOK.md — kickoff brief for John's front-end product/book: the strategy, the realization that EmberKiln (audiobook + cover) + the Graphene reader already provide the full production/delivery stack (ClickBank optional), what's already built that it leans on (/start + /go QR links, the override), the open format/lead-product decisions, and the first build steps. Written to seed a fresh working session.

  • DREAMPRO_COACHING_STRIPE.md — the money-in path: Stripe coaching checkout (POST /api/coaching/checkout) + the invoice.payment_succeeded webhook case that records the 3-way split per recurring invoice. Code shipped but inert until STRIPE_PRICE_COACHING + the webhook event are configured; includes the Stripe-test-mode test plan + the Connect-transfers follow-on.

  • DREAMPRO_COACHING_CLICKBANK_FUNNEL.md — ClickBank front-end + QR "start a plan" contract: a cheap front-end product whose QR codes / deep links (/start/<slug>?ref=<code> + a print-safe /go/<id> redirect layer) one-tap-clone a real DreamPro program and carry referral attribution into the recurring subscription/override. The two attribution layers (ClickBank HopLink vs. our ?ref=), dreams.public_slug + coaching_links schema, the lead-product recommendation (digital "30-Day Reset" challenge-in-a-box), refund/health-claims discipline, build checklist, and open decisions for John.

  • DREAMPRO_GLASSES_VOICE_PROGRAM.md — plan / not built: John Rowley's non-exclusive DreamPro-cohort program that delivers coaching encouragement in-ear through AR glasses in your own / your coach's / your teammate's voice ("your team and your best self pulling you toward the finish line"). The commercial application of the "Integrate" primitive, bridging three shipped layers (the glasses app, Living Voice sayInUserVoice, and the coach-brief encouragement the client already reads via GET /api/coaching/me). Names the three voices, the per-voice consent model (own-voice ships free; teammate = opt-in recorded clips; coach-clone-to-client deferred behind a new consent scope + counsel review), the reuse map, and 4 phases. Buildable-now Phase 0 = a coaching-aware own-voice nudge with zero glasses-app change. Founder decisions locked 2026-07-12.

  • DREAMPRO_JUNIOR_KIT_THEMES.md — Spec sheets for the proposed quarterly STEM kit subscription (Coil Geometry / Resonance / Pulsed DC / Synthesis); BOM + sponsor pitch hooks

  • DREAMPRO_JUNIOR_UNIT_ECONOMICS.md — Pilot quarter unit economics: per-starter contribution, sensitivity grid, break-even subscriber counts, three Year-1 P&L scenarios

  • DREAMPRO_JUNIOR_SPONSOR_PITCHES.md — Three ready-to-send sponsor pitches calibrated to Adafruit / SparkFun / Digi-Key, with send-order recommendation

  • DREAMPRO_JUNIOR_FULFILLMENT_QUOTES.md — Three ready-to-send fulfillment-partner quote requests calibrated to Cratejoy / ShipBob / a maker-space partner, with shared shipment specification

  • GRAPHENE_MONETIZATION.md — Brainstorm + recommended 4-phase rollout for monetizing Graphene & HiveJournal: 9 options weighed (listener sub, writer SaaS, Kindle/Audible, YouTube, adaptation, branded shows, course, B2B, translation), Affleck-pitch angle, deferral list

  • PHASE1_LISTENER_SUBSCRIPTION.md — Implementation plan for Graphene+ $5/mo: schema migrations, Stripe wiring extension, audio gating (story content free 7 days, then subscriber-only; meta content always free), Subscribe modal, letters priority, success metrics, PostHog events

  • CAFE_STORIES_TO_KINDLE.md — End-to-end pipeline turning weekly write.cafe contest winners into "Best Short Stories Vol. N" Kindle compilations. Writer journey + admin journey + what's automated vs. one-click vs. real-world ops still left for Vol. 1.

  • EMBERKILN_STORY_AS_MERCH.md — design doc (not built) for "a story as all forms" made physical: print-on-demand posters + apparel printed from a story/song's existing cover art (gpt-image-1), zero inventory via Gelato/Printful. The wedge is the author-for-self "inspiration poster" (a commitment object the writer pins up and writes beneath; sold at-cost), with an author-for-fans shareable support storefront as the second motion. The one real technical gate is a print-resolution path (covers are 1024², ~7× short of 300 DPI — upscale via the already-wired getReplicateClient(), cache @4x). Everything else reuses shipped infra: episode-tips Stripe one-time checkout, the creator_earnings payout ledger (source_kind='merch_revenue'), creator_revenue_splits (+merch_creator_pct), the providers.ts client pattern, and the heartbeat/cron registry. Standalone service for v1 (a poster isn't IR-segmented); fold into the IR only for designed multi-element posters later. One new table (merch_orders), 3 phases, gates (print rights / POD content moderation / thin margins), and 4 open decisions. Task 54663ae8.

  • EMBERKILN_ROLLOUT.md — Brand decision (EmberKiln, not DreamPro) + 4-phase GTM plan (dogfood → closed beta → paid public beta → scale) for the Audiobook Creator Suite. Includes pre-paid-launch punch list (cost tracking, ungate, billing, TOS).

  • EMBERKILN_NAME_CLEARANCE.md — Studio name: EmberKiln (chosen 2026-06-25, formal trademark clearance still open). The production studio in the architecture graphene.fm = distribution · EmberKiln = production studio · Odessa = flagship product. Informal landscape (no live media/software "EmberKiln" found; near-misses are a Scotch whisky + a band, different classes), USPTO/EUIPO search queries (classes 9/38/41/42), canonical domain emberkiln.studio, and a paste-to-attorney summary. Rewritten in the Allotrope → EmberKiln rename — the prior Allotrope clearance facts (incl. the real Allotrope Foundation mark) live in git history.

  • ODESSA_NAME_CLEARANCE.md — Flagship-product name: keep "Odessa," but as a named experience under EmberKiln, not a standalone brand. Informal landscape (2026-06-26) found three strikes — ODESZA (the homophone electronic act, directly in the audio lane), a live "Odessa AI" asset-finance software brand, and "Odessa" being a generic geographic term — so it's a loved name to use, not a brand to own. The creative-writing lane itself is open. Firm calls: drop the "AI," keep it under the EmberKiln umbrella, watch ODESZA.

  • EMBERKILN_PIPELINE_ARCHITECTURE.md — North-star for unifying the content-production surfaces (audiobook / Scene Studio / Reels / screenplay / print) into one flexible-yet-DRY pipeline: a shared render kit (tts/image/video/lipsync/assemble/meter), a canonical Production IR, a source→Work router, and thin per-surface recipes. Includes the incremental, no-big-bang path (extract the kit → converge Reels onto Scene Studio → introduce the IR). Direction, not built.

  • EMBERKILN_AL_MASCOT_KIT.md — SUPERSEDED. The "Al, a Trope" mascot was a pun on the retired Allotrope name (pronunciation gag) and does not carry to EmberKiln; the doc is now a stub pointing at git history. A new EmberKiln mascot/identity, if wanted, is creative work tracked with the visual-identity task (D4 in the rename handoff).

  • EMBERKILN_INDIE_AUTHOR_GTM.md — GTM thesis for reaching self-published authors with low/no sales: the market is millions of finished books with near-zero traction; the fit is "give your book a second life" (audiobook / scene clips / paperback = new discovery surfaces); the landmines (it's the scammer pitch, cold-scraping is illegal/spammy, dead-tail = no budget); and the model that works — inbound + community + a free-sample funnel, with Author Nation as the flagship channel.

  • EMBERKILN_CONFERENCES.md — Vetted, cited shortlist of conferences/expos where EmberKiln could buy a booth / startup package to demo. Fit/cost-ranked table + top picks by goal (author conversion vs press/launch vs film-tech buyers). Standout: Author Nation (Las Vegas, Nov 2026, $450 table, all authors). Flags the non-boothable traps (Runway AIFF, Cannes AI Summit). All dates/prices time-sensitive — verify before committing.

  • EMBERKILN_AUTHOR_NATION_BOOTH.md — Booth playbook for Author Nation (Nov 10–13, 2026). The built conversion path (emberkiln.studio/an short URL + QR → mobile magic-link signup tagged author-nation-2026 → creator access → 4-step drip), the 30-second demo script + signage copy, the physical kit checklist, the pre-conference build/config checklist (paid-mode posture, bonus-credits offer, drip cron, from-address), and the funnel metrics to instrument. Printable QR: assets/author-nation-qr.svg.

  • VISION_MANIFESTO_AUDIOBOOK.md — Production script + settings for the "Listen to the manifesto" EmberKiln audiobook embedded on /vision (season e4cac207…). The audio-pass prose (verbatim /vision copy, light narration edits), the create-season payload, single-narrator (Daniel) settings, cover-art image prompt, and the short Maxell promo-reel plan. Player: components/vision/VisionManifestoPlayer.tsx.

  • ODESSA_AUDIOBOOK_GTM.md — Distribution plan (organic → paid) for the "turn your journal into an inspiring fiction audiobook" creative. Consumer-journaler funnel, the canonical PostHog event sequence + north-star, Phase 0 measurement gates, and the disciplined "set budget after Phase 2 from a CAC ceiling" rule.

  • ODESSA_ORGANIC_KIT.md — Copy-paste-ready Phase 1 organic launch kit: UTM convention, per-channel captions (IG / TikTok / X / LinkedIn / Reddit), the demo-video shot list, owned-surface copy (email / import screen), the consent-gated "Amy" angle, and the free headline A/B that picks the eventual paid creative.

  • REHEARSAL_ROOM.md — Rehearsal Room: model a person + 2–3 options and see how each might land, before it's real ("Got a big conversation you're dreading?"). The AI-persona engine pointed sideways; honesty posture (a rehearsal, not a prediction). 3 verticals (general / work / writers); a public, anonymized (name-swapped), searchable+tagged gallery with a private opt-out; saved people ("remember this person"); the write.cafe plugin (test a character mid-draft) + a writers story-universe cross-sell that seeds the composer for HiveJournal/write.cafe/Graphene. North star: a decision-testing marketplace.

  • THROUGHLINE_PROVIDER_PLAN.md — Plan for Throughline (by HiveJournal), the therapist-facing service (codename JQ Connect) on top of JQ Bridge: providers recommend HiveJournal, clients share metadata-only trends by consent, providers get between-session vitals + engagement alerts. B2B2C funnel, the wellness-not-clinical compliance posture (+ HIPAA/BAA fork), reuse-vs-build on existing JQ Bridge, free-to-providers model, a Phase-0 design-partner sequence, and the Amy Torn outreach.

  • ETHOS.md — The manifesto / brand spine: fiction as an evolutionary technology, not an anesthetic. The five beliefs, and a surfaces-that-inherit table mapping the ethos to concrete pages, ad copy, and the Odessa generation prompt (which now threads ODESSA_ETHOS so the fiction itself carries the thesis).

  • ODESSA_NORTH_STAR.md — Odessa's product North Star: fiction as the cheapest defense-bypassing path from self-insight to self-change. Names the half-loop that exists today (real life → fiction) and the central bet — close the return path (fiction → real change → changed next story) without turning the art into coaching. Roadmap + the one honest success metric.

  • ODESSA_RCT_PROTOCOL.md — Study protocol for a pre-registered randomized controlled trial testing whether personalized AI fiction improves well-being beyond journaling alone (the marginal effect; control journals too). Extends Pennebaker's expressive-writing literature. 2-arm design with a journaling run-in, validated instruments (WHO-5) + objective journal-language markers, non-clinical well-being framing, pilot-first sample-size logic, ethics/IRB/pre-registration, and the reuse-vs-build map on the Citizen Science rails.

  • odessa-rct/ — Phase A study package (scientific + ethical spine, no code): the feasibility-pilot pre-registration, the instrument battery + scoring, the consent + intake forms, and the independent-IRB submission outline. Decisions locked: pilot first · well-being framing · docs before rails.

docs/reference/ — Stable reference docs

Feature specs, system designs, and API docs that change infrequently.

docs/operations/ — Deployment, dev setup, migrations

How to run, build, deploy, and operate HiveJournal.

Cron jobs

docs/setup-guides/ — One-time integration setup

Guides for services that were set up once and rarely need revisiting. Kept for reference.

  • ../.github/CONTRIBUTING.md — contributor front door (GitHub-surfaced): the whole flow — local setup, secrets policy, picking a task, branch/PR conventions, pre-PR checks.
  • LOCAL_DEV_SETUP.md — new contributors start here: run the app locally against your own free Supabase project, no production secrets. Pairs with apps/backend/.env.example + apps/frontend/.env.example.
  • SECRETS_HANDLING.md — how we treat credentials: never share secrets over chat, what's secret vs public (NEXT_PUBLIC_*), contributors use their own Supabase sandbox, and how to rotate a leaked key.
  • SLACK_INTEGRATION.md — Slack bot setup (SLACK_BOT_TOKEN) for DMs + channel messages: services/slack.ts, POST /api/slack/send, and the scripts/slack-dm.mjs CLI.
  • LULU_PRINT_API_SETUP.md — print-on-demand ordering (Phase 1): Lulu API credentials (LULU_CLIENT_KEY/LULU_CLIENT_SECRET/LULU_API_BASE), sandbox-first testing, the migration, and the spine-width verification step before going to production.
  • GELATO_MERCH.md — story-as-merch posters (Phase 0): Gelato API key + poster product UID + cost env vars (GELATO_API_KEY/GELATO_POSTER_13X19_UID/…), migration 426, and the print-resolution quality gate to verify before going live. Inert (orders park at awaiting_fulfillment) until configured.
  • CI_CD_SETUP.md — GitHub Actions for staging + prod deploys + automatic migration application + schema-drift detection
  • GLASSES_RAILWAY_DEPLOY.md — deploy the MentraOS glasses AppServer (apps/glasses) to Railway so JQ runs without a laptop + ngrok: create the service (config path apps/glasses/railway.json, root = repo root), set MENTRA_* + HIVEJOURNAL_* env, generate a public domain, paste it into the Mentra console (Microphone and Camera permissions), verify. Prototype single-user auth.
  • EMBERKILN_PAID_LAUNCH.md — go-live runbook for paid Studio: migrations → Stripe credit-pack prices → env vars (Railway vs Vercel) → flip NEXT_PUBLIC_STUDIO_PAID_MODE → smoke test → rollback
  • FAMILY_WALL_PLUS_LAUNCH.md — go-live runbook for Family Wall Plus (~$4.99/mo · $39/yr freemium): create 2 Stripe prices → set STRIPE_PRICE_FAMILY_WALL_PLUS/_ANNUAL → grandfather existing wall owners (SQL included) → flip FAMILY_WALL_PLUS_ENFORCED=true. Gate + checkout + cost-point gates already shipped dark (PR #1411); rollback = unset the flag.
  • SPOTIFY_SETUP.md — Spotify OAuth integration
  • RESEND_SMTP_SUPABASE_SETUP.md — Email delivery
  • PASSWORD_RESET_SETUP.md — Password reset emails
  • TURNSTILE_BOT_PROTECTION.md — Cloudflare Turnstile + Supabase CAPTCHA on signup/signin/reset (stops scripted signup abuse); activate with NEXT_PUBLIC_TURNSTILE_SITE_KEY + the Supabase secret
  • FIREBASE_IMPORT_GUIDE.md — One-time Firebase → Supabase migration
  • IMPERSONATION_SETUP.md — Admin impersonation
  • GOOGLE_ANALYTICS_SETUP.md — GA4 setup
  • GOOGLE_ADS_CONVERSION_IMPORT.md — import listen_started / listen_milestone_90s from GA4 as the Google Ads optimization goal (so YouTube ads chase listeners, not clicks)
  • GOOGLE_CALENDAR_SETUP.md — Google Calendar OAuth + Tasks sync
  • YOUTUBE_UPLOAD_SETUP.md — YouTube Data API OAuth + one-tap Shorts upload from /dashboard/admin/social-posting
  • META_PIXEL_SETUP.md — Meta Pixel + hostname gate so Graphene FM ads don't see HiveJournal traffic (+ when to wire CAPI)
  • UPTIME_MONITORING_SETUP.md — One-time external uptime monitor config (BetterStack / UptimeRobot) against the backend /health endpoint
  • ZENQUOTES_SETUP.md — Quote API
  • FACEBOOK_TESTING_INSTRUCTIONS.md — FB test accounts
  • WORKOUT_WINDOW_STORAGE_SETUP.md — Supabase Storage for WW images
  • SEASON_MEDIA_PIPELINE.md — Story Season → poster, podcast, YouTube pipeline (storage bucket + ElevenLabs + YouTube OAuth)
  • WORKOUT_WINDOW_TESTING.md — Testing guide for chains/battles
  • MULTI_BRAND_DOMAINS.md — write.cafe + graphene.fm + hivejournal.com domain aliasing (DNS, Vercel, host-aware middleware)
  • DREAMPRO_COACHING_GO_LIVE.md — consolidated go-live runbook for DreamPro Coaching: apply migrations (368–375) → provision the house coach + NEXT_PUBLIC_DREAMPRO_HOUSE_REF → dreampro.io DNS → Stripe price + webhook (money-in) → Connect onboarding + COACHING_PAYOUTS_ENABLED + cron toggle (money-out) → optional toggles. Links to the DNS + Stripe deep dives.
  • DREAMPRO_IO_DOMAIN.md — make dreampro.io serve the DreamPro Coaching front door (/coaching). Code shipped (middleware rewrite + brand detection); this is the DNS + Vercel + Supabase-redirect setup to activate it. CS stays at hivejournal.com/dreampro for now.
  • OPENENERGY_DOMAIN.md — make openenergy.* serve the Citizen Science platform (/dreampro surfaces), freeing dreampro.io for coaching. Code shipped (TLD-agnostic middleware rewrite); DNS + Vercel setup to activate. Full 301s + path carve-off are a later cleanup.
  • BLUESKY_AUTOPOST.md — write.cafe contest auto-posts to Bluesky on Monday open + Sunday close (handle + app password + autopost flag)
  • WRITER_FLEET_SETUP.md — Promote AI personas to platform writers, run the autonomous scaffold cron, approve + publish, mint real-writer invites (migrations 230-232 + WRITER_FLEET_ENABLED env var)
  • GOOGLE_OAUTH_SETUP.md — "Continue with Google" on /auth/signin + /auth/signup. Google Cloud Console OAuth client → Supabase provider config → brand-domain Redirect URLs allowlist → (optional) Manual linking toggle for the /dashboard/settings "Link Google" button
  • PLATFORM_ROLE_SEATS_SETUP.md — Activate the 5-seat platform-role hierarchy (Director / CM / Reader Lead / Marketing Advisor / Infra Monitor): migrations 234-245, per-seat env flags, persona assignment, scope-flag opt-in for autonomous mode, human handoff via invite/claim
  • PODCAST_ACCOUNT_SETUP.md — One-time Apple Podcasts Connect + Spotify for Podcasters account setup for the Graphene network. Canonical values for the show name / owner / email / category / language / cover art (with the 3000×3000 cover-art gotcha called out), Apple's common rejection reasons + fixes, how metadata flows from constants/graphene.ts into the RSS feed, when to change in code vs in the portal, and links to the per-show submission tracker for the repeat work after the one-time setup. Section 8 explains how the RSS feed stays current after submission (live-feed model, the 3 conditions that gate an episode into the feed, the 500-item cap, and how many episodes publish at once on first submission vs ongoing crawls).

docs/mobile/ — React Native / Expo app

The mobile app is pre-release. These are the current docs; archived pre-2026 docs are in docs/archive/react-native-pre-2026/.

docs/marketing/ — ICP, competitor, positioning strategy

Living strategy docs on who the products are for, who else is in the space, and how positioning should evolve. Dated documents — newest relevant doc supersedes older ones, but older ones stay in place for the historical reasoning trail. Pair with the Marketing Advisor dashboard (/dashboard/admin/marketing-advisor) which is the system-of-record for decisions + goals.

  • 2026-05-19-icp-and-competitor-analysis.md — first-pass ICPs per surface (Graphene listener / Graphene supervised-creator / write.cafe Pro / Lovio) + competitor landscape table. Companion to the 2026-06-02 marketing-plan-revisit scheduled prompt.
  • 2026-05-19-graphene-week-1-channel-execution.md — week-1 organic channel kit for Graphene (Reddit r/audiodrama post + 3 TikTok variants + Apple ASO sweep). Three free channels first; deploy paid after 4-6 week organic window.
  • 2026-05-19-graphene-apple-podcasts-aso-sweep.md — per-show ASO recommendations for the 8 priority Graphene shows (title cleanups + iTunes metadata fields).
  • 2026-05-20-graphene-paid-acquisition-kit.md — ready-to-deploy paid-ads kit (Reddit + Apple Search + Meta + TikTok + Google). Three budget scenarios ($250/$500/$1500), per-channel ad creative + targeting + KPIs, 2-week decision tree. Deploy after the organic window closes or earlier on pull-forward signals.
  • 2026-05-21-lovio-marketing-kit.md — full Lovio marketing strategy: ICP deep-dive (legacy-minded parents + gift-givers), competitor analysis (Storyworth/FutureMe/voice-memo apps), channel mix tuned to the older demo (Meta/Pinterest/Google + editorial > Reddit/TikTok), gift-cycle editorial calendar, grief-vertical handling rules, lovio.io brand-graduation plan (DNS + middleware + branded auth emails), waitlist nurture sequence, pre-launch checklist.
  • 2026-05-24-phase-0-launch-checklist.md — step-by-step runbook for the 5 user-action items unblocked by the Phase 0 infrastructure (PRs #102–#121): Apple/Spotify directory submission, Stripe Graphene+ price ID, Bluesky chapter-drop autopost, first TikTok vertical trailer post, r/audiodrama launch post. Click-by-click with verification steps + what to watch for in the first 24–48h per item. Recommended order: Apple/Spotify first (5–7 day crawl), then Stripe + Bluesky in parallel, then TikTok, then Reddit as the headline moment.
  • 2026-05-28-distribution-and-funnel-strategy.md — the "where distribution happens vs where value/monetization happens" doctrine: Spotify/Apple are a destination not a discovery engine (feed config is a ~5% optimization); graphene.fm is the owned platform + moat (letters, subscription, reading, creator funnel) so open platforms are the free taste that funnels back to the app; per-show feeds are right but secondary to one flagship; listeners before creators; short-form video is the real top-of-funnel. Also covers the spoken outro-CTA audio funnel (distribution-only, public-feed-only, state-aware, one-per-show in the network feed), serial-publishing timing (drip vs binge vs trailing-edge), and community posting voice (post as the maker, not a fan). Read before optimizing any directory/cross-platform decision.
  • 2026-06-11-paid-acquisition-action-items.md — post-mortem + checklist from the funnel-fix session. Verdict: the conversion funnel is fixed and verified (PRs #531–#535 shipped: cold-ad dead-end, 3-free-chapters, locked-card perks, /listen tap-to-play, robots /api/og/), but paid traffic still doesn't consume (consumed% ≈ 0 on FB/YouTube while direct/organic engages normally) — so the bottleneck is ad quality/intent, not the site. Action items are Ads-Manager-side: fix the Meta Pixel ID mismatch (site fires 1421…, ads use 976…), switch YouTube to landing-page-views, exclude Audience Network, point all ads at /seasons/<id>, re-scrape FB destination. Includes the PostHog dashboard/insight links + the consumed% north-star metric to watch.
  • promo-videos/ — Rehearsal Room promo video series (hand-off briefs for short funny ads). Shared 5-beat device + sound arc + brand rules in promo-videos/README.md; one self-contained brief per dreaded conversation (treatment + 15s cut + CapCut text track + Veo/Kling/Runway prompts + Midjourney stills + captions): the Raise Bear 🐻🍯, the Storm ⛈️☂️ (breakup), the Giant 🗯️🥪 (parent).

Founder-level research and paste-ready filing kits for the IP layer. Not legal advice — these are the homework you bring to a trademark attorney, not a replacement for one.

  • legal/README.md — Index + when-to-use-which-doc table + decision log
  • legal/TRADEMARK_FILING_KIT.md — USPTO landscape research (cancelled prior reg #3783939, adjacent players like GraphAudio + Studio Graphene), paste-ready application text for trademarkcenter.uspto.gov (EMBERKILN, Point Seven Studio LLC, Section 1(b) ITU, Classes 41 + 9, TEAS Standard), post-filing timeline through registration
  • legal/IP_STRATEGY.md — "What protects a software product" framing: copyright-vs-trademark confusion, why software patents barely work post-Alice (2014), the actual moats (trademark + content library + community + execution), conversation drafts for advisors/investors who worry about idea theft
  • legal/LEGACY_VOICE_CONSENT_COUNSEL_BRIEF.md — paste-ready attorney memo for the eldercare voice-cloning consent model: facilitated-capture mechanics + 7 questions (consent form, surrogate authority, posthumous/heir-durability under the ELVIS Act + CA AB 1836, BIPA voiceprint exposure, capacity, HIPAA scope, minor recipients). Gates the Legacy Channel build; companion to product/LEGACY_CHANNEL_CONSENT_MODEL.md
  • legal/PRIVACY_POLICY_DRAFT.md + legal/TERMS_OF_SERVICE_DRAFT.md — DRAFT Privacy Policy + Terms of Service across all brands, customized to real data practices (incl. the voice-biometric/BIPA section) with bracketed items + open business decisions for counsel. Not legal advice; counsel-review-gated before publishing as /privacy + /terms

docs/vendor-packs/ — Third-party implementation packs

Self-contained doc sets from vendor/implementation partners.

docs/archive/ — Historical docs

Preserved for git history. These are stale, superseded, or from shelved projects. Don't build on them without checking the current state first.

  • dreampro-v1/ — Original DreamPro design (v1 plan + implementation summary). Superseded by the unified Citizen Science Platform.
  • react-native-pre-2026/ — Pre-2026 React Native feature parity docs (4 overlapping docs consolidated into docs/mobile/)
  • habitforge/ — HabitForge reboot concept (on hold, not advertising)
  • ab-test/ — A/B test variant docs (experiment concluded)
  • conversion-tracking/ — GA + Facebook Pixel setup pack (integration complete)
  • ODESSA_PROTOTYPE_REFERENCE.md — Complete inventory of the Odessa / "The Hive" prototype (Next.js 15 + Clerk + Drizzle). Features: levels/atoms wellness tracking, zen-space deterioration, hex-grid social structure, insect visitors, voice interface, battle system. Prioritised porting guide.
  • landing-pack/ — Landing page implementation guide (implemented)
  • comparison-page/ — Competitor comparison design docs (page shipped at /compare)
  • migrations/ — Open Energy snapshot data

Other docs outside docs/

These live in their respective app directories and are documented here for completeness.

README — Docs | HiveJournal