Server functions

All server functions use createServerFn from @tanstack/react-start with .inputValidator() for Zod validation (NOT .validator() -- this is a v1.133.5 API).

marketing-analytics.ts

performance-booth-fns.ts

Internal pipeline naming remains performance-booth; the user-facing Table Read stage is Audio Acting.

account-deletion-fns.ts

Deleting one's own account (legal gap G2). The core is account-deletion.ts (request, cancel, status, the admin closure, the daily sweep) and account-deletion-purge.ts (the purge, step by step); /api/v1/account/deletion reaches the same core for the Story API, CLI, MCP and the mobile app.

account-export-fns.ts

"Download my data" (legal gap G3). The core is account-export.ts (request, status with a fresh signed link, the daily sweep) and account-export-archive.ts (the zip, built on the workers); /api/v1/account/export reaches the same core for the Story API, CLI and MCP.

project-deletion-fns.ts

Deleted projects (legal gap G2). The core is project-deletion.ts (delete, list, restore, the daily sweep) and project-deletion-purge.ts (the purge after the 30-day window). Deleting takes the project's episodes with it: during the window they stay linked and private (Script.privateAt), a restore puts back exactly what that delete changed, and at the purge they are deleted with everything under the project (episodesAtPurge).

courses.ts

Admin Preview Override

All course functions read the sh_preview_tier cookie for ADMIN users to override tier/role for testing. Implemented via applyPreviewOverride().

dashboard.ts

customer-api-keys.ts

Customer-facing Story API keys are separate from provider/admin EncryptedAPIKey records.

customer-api-auth.ts

These are route helpers for /api/v1, not createServerFn exports.

story-api-route.ts

Story API-specific wrappers layered on top of handleCustomerApiRoute.

story-projects.ts

Business logic for story projects. Exposed via /api/v1/story-projects routes; not createServerFn.

episode-season.ts

Which season a new episode Script goes into. Not createServerFn; called by the plan's table-read scaffold (story-plan-table-read-adapter.ts, so Story API jobs, season runs and recurring producers) and startPlannedEpisode.

table-read-cast.ts

The table-read cast precondition — canon-cast (owner decision 2026-09-29). See docs/table-read.md, "Headless table reads: canon cast (owner decision 2026-09-29)".

story-project-documents.ts (readers)

Every script is born into a project (New Project, an upload, a plan), so there is no "create a project around this script" core left: reading a script never creates a project, and the only write that wraps one is findOrCreateStoryProjectForScript (row below). The rows here are the read side.

getScriptByRouteIds (scripts.ts) treats a soft-deleted project as no project, and still finds a script addressed by its own route id in the project slot after it has joined a project. The Writers Lab detail loader then redirects that stale URL to the project's URL, so the Back button and sidebar links built before the script joined keep working.

script-overrides.ts

The five episode overrides (scripts.overrides.get / scripts.overrides.update): avatar (table_read_avatar_style), theater (table_read_theater_style), soundscape (table_read_soundscape_style), pitchDeck (pitch_deck_visual_direction) and locations (storyboard_visual_direction) — ScriptSidecar rows on one script version, layered over the Series Bible's visual canon (the soundscape over the studio default). The list, the keys, the 8,000-character cap and the refusal sentences live once in @sleeperhit/shared's script-overrides.ts (SCRIPT_OVERRIDES, parseScriptOverridesPatch). One core for all four surfaces: the Writers Lab editors (Cast: avatar; Table Read theater settings: theater + soundscape; Videos tab Series assets panel: pitch deck + locations), GET/PATCH /api/v1/scripts/{scriptUploadId}/overrides, the get_script_overrides / update_script_overrides MCP tools, and sleeperhit script overrides get|update. Free; saving renders nothing.

Video editing scope (conversations.videoEditingScope.set): setVideoEditingScopeForUser verifies the existing conversation belongs to the named trailer/deck and changes only its selected segment/chapter. UI Discuss controls, Slug set_video_editing_scope, PATCH /api/v1/conversations/{conversationId}/video-editing-scope, MCP set_video_editing_scope, and sleeperhit conversations scope set <conversationId> --surface trailer|pitch-deck --job <id> (--scene <sceneIndex>|--whole) share it. sceneIndex: null selects the whole cut. The response includes previous/current focus and current order; structural edits change positions, so read that order before selecting again. The write merges current metadata in a serializable transaction. Free, naturally idempotent, no new conversation, render or change to edit/spending consent. Story API scope: story:write.

On shared product-project decks, the author's bound thread and each currently authorized member's own memberPitchDeckJobId thread use the same focus core. A viewer may change their own focus but cannot change the plan. Add, remove and reorder clear positional focus on those governing threads in the same plan transaction, including member threads before the author has opened one; revoked, orphan and display-only editsPitchDeckJobId threads retain their unrelated metadata.

The writer's own episodes (scripts.ts, project-episodes.ts, writing-lab-projects.ts, script-export.ts)

What the Writers Lab does with a script the writer made — list a project's episodes, upload a screenplay or a new version, read one script and change its fields and season, delete one version, export it, name a season — reached the Story API, MCP and the CLI only through a plan-made artifact, so an episode made in the app was invisible headlessly (parity audit 2026-10-09). Each is now one core that the Writers Lab's server fns and a Story API route both call; MCP and the CLI reach the route through the shared builders in @sleeperhit/shared's writer-episodes.ts, which also holds the limits and the one parser per input (parseScriptMetadataPatch, parseScriptUploadBody, parseScriptVersionUploadBody, parseScriptExportOptions, parseProjectSeasonName). A script id may be the script's own, the id in its Writers Lab URL, or any version's id (findOwnedScriptId, owner-only, calibration scripts excluded). All free.

| startPlannedEpisodeForUser (writing-lab-projects.ts) | "Start" on the project and Series Bible pages (startPlannedEpisode); POST /api/v1/story-projects/{projectId}/episodes (startPlannedEpisodeEnvelopeForUser, project-episodes.ts); MCP start_planned_episode; sleeperhit projects episodes start | The Bible episode's empty draft, or the script that already covers it. 409 project_precondition_failed until canStartEpisode. Its season is filed by fileNewEpisodeInSeason (episode-season.ts). | | writeScriptContentForUser (draft-scripts.ts) | Editor saves (saveDraftContent with mode: 'draft', saveVersionContent with mode: 'version'); PATCH /api/v1/scripts/{scriptUploadId}/content; MCP write_script_content; sleeperhit script write | Headless callers leave mode out and the version's status decides. expectedContent is a compare-and-swap (409 script_state_invalid); season-run versions are refused. Only the newest version is written: an older one is refused (409 script_state_invalid, naming the newest version's id) — copy it into a draft to change its words. | | finishDraftForUser (draft-scripts.ts) | Finalize (upgradeToVersion); POST /api/v1/scripts/{scriptUploadId}/finish; MCP finish_draft; sleeperhit script finish | Without coverage, judgeCoverageCarryover's recommendation; adopt / fresh lock the draft as the dialog does. | | listCoverageReportVersionsForUser (coverage.ts) | Coverage tab history (getCoverageReportVersions); GET /api/v1/artifacts/{id}/coverage/versions (listArtifactCoverageVersions); MCP list_coverage_versions; sleeperhit coverage versions | Every report across the lineage, newest first. | | getBlackListReportForUser (blacklist.ts) | Coverage tab; GET /api/v1/artifacts/{id}/coverage/blacklist (getArtifactBlackListAnalysis); MCP get_blacklist_analysis; sleeperhit coverage blacklist | A report's analysis, default the latest complete report. |

The coverage and script reads under /api/v1/artifacts/{artifactId}/ (getArtifactScriptContent, requestArtifactCoverage, getArtifactCoverage and the two above) resolve with allowWriterScript (story-jobs.ts): with no artifact of that id, the id may name a writer's own episode — a version, or a script by its id or Writers Lab URL id (its latest version). Music, SFX and performance stay artifact-only.

Drift fixed alongside: the project PATCH merges metadata and keeps metadata.seasons (mergeProjectMetadata, lib/project-metadata.ts — D7). D6, a plan's episode landing in the season it was written for, is fileNewEpisodeInSeason / readPlanIntendedSeason (episode-season.ts).

table-read-prepare.ts

Preparing a cast episode's table read (scripts.tableRead.prepare, owner decision 2026-10-04): the TABLE_READ charge — priced by the screenplay's pages, TABLE_READ_SHORT / TABLE_READ_LONG via resolveTableReadCreditQuote, the price a Story API job adopting the screenplay reserves — and the media it buys, queued through dispatchTableReadMediaStages (table-read-media-stages.ts, the call the Story API's own read makes). One core for all four surfaces: Cast's Continue to Table Read, the setup pane's POST /api/table-read/finalize, POST /api/v1/scripts/{scriptUploadId}/table-read/prepare, the prepare_table_read MCP tool and sleeperhit script table-read prepare.

series-bible-interview.ts

The Writing Lab's New Project action opens a resumable, DB-sidecar-driven Series Bible interview. The model chooses one adaptive question and 2–5 project-specific options at a time; code validates structured turns, persists the full interview state and transcript, merges the Series Bible patch, and decides completion mechanically.

The same Series Bible document is exposed to API, CLI, and MCP clients. Its serialized response includes readiness.development and readiness.visuals; headless clients can fill the document directly and use those fields as the shared completion contract. In the Writing Lab, that document is presented as read-only project canon; browser-side changes are proposed and approved through the persistent Slug conversation, while foundational coverage remains a separate analysis action.

app-captures.ts / app-captures-fns.ts

App captures: real screen recordings of a web app, for a product trailer's beat to play. One core for the Story API (/story-projects/{id}/captures), the CLI (sleeperhit capture), MCP (import_app_capture, list_app_captures, delete_app_capture), Slug's list_app_captures and the project page's Captures panel (app-captures-fns.ts: listProjectCapturesFn, createProjectCaptureFn, finalizeProjectCaptureFn, deleteProjectCaptureFn, workspace access required). Free.

claims-ledger.ts / claims-ledger-fns.ts

The claims ledger (app-to-trailer round 2 S7b). One core (readClaimsLedgerForUser, decideClaimForUser) for the Story API (GET /story-projects/{id}/claims-ledger, story:read; POST /story-projects/{id}/claims-ledger/{claimId} with { decision: confirm|reject|reopen, note? }, story:write; 404 claim_not_found, 409 project_not_product), the CLI (sleeperhit app claims|claim), MCP (get_claims_ledger, decide_claim), Slug's tools of the same names (product projects' chats only) and the claims list in the project page's "Learn from your site" panel (claims-ledger-fns.ts: getProjectClaimsLedgerFn, decideProjectClaimFn; workspace access required). Free.

product-bible.ts / product-bible-evidence.ts

The product Bible writer (round 2 S7b). generateSeriesBibleForProject (story-project-documents.ts) writes a kind: product project's Bible with the story_api_product_bible sidecar from the feature inventory and the claims ledger, then saves it through the ordinary save; every surface that generates a Bible reaches it. product-bible-evidence.ts is pure: stable evidence keys (src-… from a page's address, claim-… from a claim's wording), the evidence the model is given, and holdProductBibleToEvidence (availabilityBound: every feature bounded by the inventory feature its id names or starts with, else the founder's record, else at most planned/unknown; stripRejectedClaims: a sentence stating a rejected claim is struck from every field but "do not claim"). The writer asks once more when a draft states a rejected claim, and the save holds the draft again under the claims ledger's lock (lockAndReadClaimsLedger, inside the save's transaction via contentFromBase(base, db)), recording claimsLedgerVersion (at save), claimsLedgerVersionAtWrite, rejectedClaimsAskedAgain and rejectedClaimsStruck in generatedFrom. Product coverage gets the same evidence index (productCoverageEvidenceBlock in series-bible-coverage-worker.ts).

feature-inventory.ts / feature-inventory-fns.ts

"Learn from your site" (app-to-trailer round 2 S7a). One core (startFeatureInventoryLearning, readFeatureInventoryForUser) for the Story API (GET|POST /story-projects/{id}/feature-inventory, reads source:read, starting source:write; 409 project_not_product for a story project), the CLI (sleeperhit app learn|inventory), MCP (learn_from_site, get_feature_inventory), Slug's tools of the same names (mounted on product projects' chats only) and the project page's "Learn from your site" panel (feature-inventory-fns.ts: getProjectFeatureInventoryFn, which answers isProduct: false for a story project, and learnProjectFromSiteFn; workspace access required). The work runs on the feature-inventory-learn queue (feature-inventory-worker.ts; render-owned). Free, at most 10 runs a day per account, counted under an account-level advisory lock; a story project is refused with the shared F3 refusal (project_not_product, details.work: 'learn_from_site').

connectionId is tri-state on UI, Story API, CLI, MCP and Slug: omitted chooses the project's verified app automatically, null reads public pages only, and a nonblank trimmed id (at most FEATURE_INVENTORY_LIMITS.connectionId, 128 characters) chooses that owned connection. An in-flight run is returned unchanged with its actual id/site/connection, without starting a second run. The exact existing CHAT app subject (metadata.source: app-connections, projectId) mounts the product-gated inventory/readiness tools, attach_source and only the existing update_series_bible write for feature-map confirmation/refinement. Shared reads provide the current Bible and sources. Saves retain their project permissions and relock confirmation. Slug's inventory digest supplies stable canonical src-* evidence ids plus human titles, without page addresses or private screenshot keys. The UI read separately projects projectFeatures from the saved product Bible, so a missing learned inventory does not erase saved features. Product app/Bible guidance is read live from PRODUCT_APP_FEATURES_COACHING, including when base behavior rows are customized.

app-connections.ts / app-connections-fns.ts

Stored app logins for hosted capture (H3). One core for the Story API (/story-projects/{id}/app-connections, reads source:read, writes app:connect), the CLI (sleeperhit app), MCP (list_app_connections, connect_app (a link, never a secret), create_app_connection and update_app_connection (settings only; a secret is never an argument — the writer types it through connect_app's link), test_app_login, delete_app_connection), Slug's connect_app (a link only) and the project page's "Apps to record" panel (app-connections-fns.ts: listProjectAppConnectionsFn, getProjectAppConnectionFn, createProjectAppConnectionFn, updateProjectAppConnectionFn, saveProjectAppConnectionSecretFn, testProjectAppConnectionLoginFn, deleteProjectAppConnectionFn, workspace access required). Every write is audited (AppConnectionEvent). Free.

Sign-in steps (BL-2623, app-sign-in-recipe.ts + lib/sign-in-recipe/). A form sign-in follows a recipe: the sign-in page, the ONE form each step names, each field's role and label, the submit, reveal clicks, a cookie button. The test worker reads the newest kept version (AppConnectionSignInRecipe, last five kept, never on the connection row so the pass's updatedAt CAS holds); with none (or findSignIn), the scout surveys the SIGNED-OUT app on a runner (/v1/sign-in-surveys: a preview's headers are the only secret, opened headersOnly), and the app_sign_in_scout row's model (GPT-6.1 Sol, strict structured output, booked under PRODUCT, never counted) answers a flat draft that toSignInRecipe maps and checkSignInRecipe checks. signInRecipeNeeds checks it against the saved secret kinds before the login opens: a workspace field (needs_field, steps kept so every read asks for workspace), a field Sleeper cannot fill, single sign-on only (sso_only), a CAPTCHA or an emailed link stop with one sentence. A step the runner could not follow answers recipe_failed with the masked page; the app_sign_in_repair row mends the steps once, the login is opened again (audited) and the test dialled once more; a pass keeps the mended version (source: repair). Recordings and the signed-in walk call ensureSignInRecipe (scout first when none) and keep found steps once they signed in. Every read answers connection.signInRecipe (summary, steps' roles and labels, never a locator). Runners older than the steps (capabilities.signInRecipe missing) are sent nothing.

app-connection-retention.ts (runAppConnectionRetention, from the daily request-log-retention-tick): deletes audit rows past 90 days and connections past their own retentionDays.

The ChatGPT profile (/mcp/chatgpt) offers none of these yet: list_app_connections and connect_app (a link) join it in H5, with hosted capture's quote, record and status (decision 7). The two settings tools never join it: that profile is never granted app:connect.

app-connection-test-preview.ts

getAppConnectionTestPreviewForUser({ userId, projectId, connectionId, testId }) reads safe metadata for one exact current Test sign-in, without capturing a picture or starting another test. The Story API GET is /story-projects/{projectId}/app-connections/{connectionId}/test-login/{testId}/preview (source:read, project owner only, including owner OAuth). The CLI sleeperhit app preview <connectionId> <testId> --project <projectId>, MCP and Slug get_app_login_test_preview use the same shared metadata allowlist: step, state, sequence, freshness, picture availability and the canonical owner viewUrl. They never return an image, image URL, code or runner address; a replacement test is refused. CLI preview is metadata only and has no image-saving option.

The separate /preview/frame GET is for an owner session or personal API key; OAuth is refused. It returns a private no-store JPEG or 204 when no current safe frame exists. The open, visible Test sign-in dialog uses this channel and the existing exact-test secure code field. MCP and Slug do not expose the picture route. An arbitrary use of the owner's personal key cannot be identified as human or model use.

tour-drafts.ts / tour-drafts-fns.ts

Tour drafts (app-to-tour round 2 S8) — one drafting run per product feature, written from the feature's Bible entry, its evidence pages and the app connection's address, checked by the recorder's own rule and saved as an editable P-095 tour marked drafted. The app is never opened and no frame is recorded. One core (startTourDraftForUser, listTourDraftsForUser, getTourDraftForUser in tour-drafts.ts) for the Story API (GET|POST /story-projects/{id}/tours/drafts, GET …/tours/drafts/{runId}; the static drafts segment sits beside the static check), the CLI (sleeperhit tour draft|drafts|draft-status), MCP (draft_tour, list_tour_drafts, get_tour_draft), Slug's tools of the same names (the shared reads on every writer chat) and the project page's Tours panel (tour-drafts-fns.ts, workspace access required). The work runs on the tour-draft queue (tour-draft-worker.ts); free, at most 50 runs a day per account. An expected refusal (a story project, a feature the Bible does not list, a planned feature, no app connection or an ambiguous one, the daily cap, an unknown runId) is answered as data by these fns and as a value by Slug's tools — project_not_product, validation_failed, usage_limit_reached, tour_draft_not_found — never as a thrown request failure.

Bible reference reads

getSeriesBibleForProject returns a read-only references index beside canonical content, shared by the Writing Lab, Story API, CLI, MCP and Slug's get_series_bible. After project access is checked, it reads only that project's source labels and safe web addresses, inventory page names, claim statements and feature names. The index maps existing keys to human labels and links; available means the target resolves, not that a claim is confirmed or a feature is shipped. Deleted or missing evidence reads “Source unavailable”. No foreign row is looked up to resolve a cited key.

The Bible reader resolves exact known citation tokens in prose and keeps evidence names in closed disclosures. Unknown text, literal code and addresses are retained. Neither the read nor its presentation changes content, feature IDs, evidenceIds, the claims ledger or the saved Bible version. The index is not part of PATCH content. Product writers keep human names in prose and canonical keys in structured fields; the locked save still enforces availability and rejected claims.

series-bible-generation.ts and series-bible-generate-worker.ts

Writing a project's Series Bible from its sources runs in the background (#1509 L5): ChatGPT drops a tool call after about 60 s, and a Bible takes a minute or two (110–140 s measured). The contract every surface shares lives in @sleeperhit/shared series-bible-generation.ts (generateSeriesBibleRequest, getSeriesBibleRequest, SERIES_BIBLE_GENERATION_SENTENCE).

render-quote-preparation.ts and render-quote-prepare-worker.ts

A deck's or trailer's render price is prepared in the background (#1509 L5). The plan approval compiles and voices every chapter or beat before it can price (measured 70 s to 7 minutes; the shot-list compiler alone 18 s a call at the median, 54 s at worst). priceOrApprovePitchDeckPlanForUser / priceOrApproveTrailerPlanForUser — what the Story API, the deck and trailer pages and Slug call — price only from a stored compile (approve*PlanForUser with reuseOnly, which throws RenderCompileUnprepared before anything is written); otherwise they start a preparation and answer { quotedOnly: true, status: 'preparing', progress, checkAgainSeconds, note }, reserving nothing, confirmed or not. The same call asked again answers at once while it runs (before the gate and the screen run again), then with the price.

story-sources.ts

Business logic for story sources. Inline TEXT and MARKDOWN extract synchronously; URL and PDF enqueue a pg-boss extract job after synchronous SSRF + URL validation.

story-source-digest-worker.ts resolves story_api_source_digest through the shared provider circuit. When every configured route is capacity- or policy-blocked, it returns the digest to PENDING/provider_capacity_backoff and schedules a bounded delayed retry, preserving transient METADATA_ONLY preview text in the queue payload. Only retry exhaustion becomes FAILED/provider_capacity_blocked.

A digest gets at most one immediate re-ask, for one of two reasons: the reply does not fit the schema, or its summary/thesis adds "AI", "artificial intelligence", "LLM", "language model" or "machine learning" wording that the source (label, URL and text) never uses (addedMachineWording). The second re-ask is told which words, and its answer replaces the first only when it is clean. A failed re-ask keeps the first answer. The row says the same thing in words (Rule 9: the summary is shown in the project's Sources panel). Existing digests keep their text until the source is digested again.

story-plans.ts

Business logic for the StoryPlan abstraction.

story-plan-worker.ts

Async planning worker — registered as story-plan-generate.

Quote balance (lib/credits-quote-balance.ts, story-plan-quote.ts)

Every priced quote says what it leaves. Beside its price it carries balanceAfter (the balance available now minus the quote; negative means the writer is that many credits short) and sufficient (the balance covers the whole quote, so a confirmed call can reserve it). The shape is QuoteBalance in @sleeperhit/shared, so the web app, the CLI and the MCP server read one type. The balance is getCreditBalance(userId).balance, floored at zero: the number Billing shows and GET /api/v1/credits returns. The line-item reserve refuses on the same number, so sufficient: false is the refusal a confirmed call would hit. Quoting reserves nothing, so the balance can still move before the confirmed call.

A plan quote with no balanceAfter / sufficient means "not applicable" (the plan has a job, is not awaiting its spend, or the caller lacks credits:read), never "short". A job's own quote (StoryJob.creditQuoteJson) never carries the balance: it is already reserved.

publishing.ts

Business logic for project-owned Publishing. Publishing promotes finalized durable assets from existing artifact flows; it does not create MP3/MP4 media.

Synthetic-media disclosures (legal gap G8a). Every series has a syntheticDisclosure line (default "Voices and music in this show are synthetic.", @sleeperhit/shared DEFAULT_SYNTHETIC_DISCLOSURE). The writer can reword it on every surface (feed settings, Story API, CLI --synthetic-disclosure, MCP) but never empty it: normalizeSyntheticDisclosure refuses empty, blank or null with a 400. It is added where the words are shown, never stored into them, so nothing in a release payload can remove it: the end of the feed's description and of every episode's notes (withDisclosure), the feed's <podcast:txt purpose="synthetic-media">, the public show and episode pages, and the end of the YouTube description. YouTube uploads carry status.containsSyntheticMedia: true and TikTok direct posts post_info.is_aigc: true. The Slug composer always says "You're talking with an automated assistant."; the table-read toolbar says "The voices in this read are synthetic." until the read is live, and so do the public table-read share pages (theater, fullscreen and audio, playing or still rendering). HNR publishes through the same API, so its shows carry the default line with no change on its side (every-feed-and-episode-says-the-show-is-synthetic). A deck or trailer whose plan shows a long-dead historical figure records it (historicalFigures on PitchDeckJob / TrailerJob: set when the plan is approved, from what screenLikenessOf let through, and added to when a chapter or beat is rendered again), and the deck's shared page, the in-app deck video and the trailer review say "This is a synthetic depiction of a historical figure, not an archival record."

Create and update also hold the cadence rules (recurring series are audio-only; cadenceArmProblem on create, update and at fire time) and write the show's standing approval (standingApprovalKeyId; arming a cadence grants, revoking disarms). Over the Story API granting takes userConfirmed: true; the routes pass caller: seriesWriteCallerFromApi(ctx, body).

standing-approval.ts

The one place a per-call userConfirmed may be stood in for (owner decision 2026-09-29).

credit-topup-sheet.ts

The Billing page's top-up sheet, save-card sheet and spending card. Buying credits and saving a card are app-only by design (the API, MCP, the CLI and Slug hand out billing.topupUrl instead); the cap and auto top-up are the same setter every surface uses (updateCreditBillingSettings, PATCH /api/v1/credits/billing). The charging core is lib/stripe/topup-payments.ts; credits are granted only by the payment_intent.succeeded webhook. See docs/credit-billing.md and docs/stripe.md, "Studio credit top-ups". The expected refusals come back as values, never thrown.

credit-outage-notice.ts

noteCreditsExhausted — one credits_exhausted notification (bell + email) the first time credits run out in a billing cycle, deduped by its deterministic primary key (credits_exhausted:<userId>:<cycle>). Called, never awaited, through lib/credit-outage-report.ts from every refusal site — and only when the balance is below CREDIT_OUTAGE_FLOOR (one recurring audio episode), so a big one-off refusal from a funded account stays a plain 402.

payment-failed-notice.ts

notePaymentFailed — one payment_failed notification (bell + email) per failed Stripe invoice, deduped by its deterministic primary key (payment_failed:<invoiceId>), so Stripe's retries of the same invoice and webhook redeliveries send nothing more. Called (awaited) by the invoice.payment_failed webhook handler in lib/stripe/webhooks.ts; a write failure throws so Stripe redelivers. The bell opens /dashboard/billing. The words are in code (paymentFailedNoticeText).

coverage domains

Screenplay (coverage.ts), Series Bible (series-bible-coverage.ts), and brand (brand-coverage.ts) operations persist through the same CoverageReport lifecycle. Their public UI, API, CLI, and MCP entry points remain rubric-specific because their inputs, payload schemas, and workflow gates differ. gold-standard.ts exposes the shared curated exemplar corpus to the admin calibration surface; CoverageReportExemplar records the ordered exemplars used for each generated report.

Video coverage (video-coverage.ts, worker video-coverage-worker.ts on video-coverage-generate) watches a deck's or trailer's stitched master and gates the paid finish. One watch is too noisy to gate on near the bar, so the rules in lib/video-coverage-judging.ts apply: a first watch within 1.5 of the bar (its composed overall or a veto dimension) is followed by a second, two watches on opposite sides of the bar on any gating score by a third, and the bar reads the MEDIAN of each score. Each watch is its own queue execution (recorded on the generating row under reportJson.watching, compare-and-set on its count, then the next job is sent), so the expiry still nests one watch and a retry never pays for a recorded watch. Watches beyond each report's first share a $0.50 cap per master (a model with no price on file counts $0.25 a watch). An automatic report first fingerprints the master (video-coverage-fingerprint.ts: MD5 of every fifth decoded frame plus what each part was asked; SHA-256 of the decoded sound on that picture) and carries the picture's five scores from the newest earlier report on a frame-identical picture, judging only lip sync and audio sync again — nothing at all when the sound is identical too. report.judging records every watch, each score's distribution and median, what was carried from which report and why it stopped; every surface shows it.

Script coverage (coverage-worker.ts on coverage-generate) gets the same variance fix. One judgment is noisy near the bar (an HNRadio episode scored 8, then 7, on identical pages), so the rules in lib/script-coverage-judging.ts apply: a first judgment within nearGateBand (1) of the report's bar (gateThreshold: the coverage gate's target, a season's minimum, else 8) is judged again, up to maxJudgments (3), stopping once a majority sit on one side of the bar; the score is the MEDIAN (an even count reads the lower middle, so it is always a score one judgment gave, and the report shown is that judgment's). A clear pass or fail stays one judgment. The numbers are data: SiteSetting script_coverage_judging (nearGateBand, maxJudgments, extraSpendCapUsd $0.50 per script, unpricedJudgmentUsd $0.25). Each judgment is its own queue execution (recorded under reportJson.judgingInProgress, compare-and-set on its count), ledgered like the first; one beyond the first carries step: coverage_extra_judgment, which the monthly report count leaves out. Before its first judgment a report fingerprints what it would ask (server/script-coverage-judging.ts: the composed rubric, the script, the Series Bible and plan, any focus, the schema and the model). A report an orchestrator queued (subjectMetadata.trigger: auto: the story-job gate, its first-pass report, a season run) starts from the newest earlier report with that fingerprint, so the gate's report and the first-pass report on the same pages share one set of judgments; a writer's request (the app, the Story API, MCP, the CLI) is judged afresh, as video coverage re-watches a manual request. reportJson.judging records every judgment, the median, which judgment gave it and why, and why judging stopped; each judgment's whole report is kept under subjectMetadata.coverageJudgments. The Story API read (overallScore, gateThreshold, gatePassed, judging, summary), MCP get_coverage, the CLI, the Coverage tab and Slug's get_coverage all say "the median of N judgments"; the story-job gate's progress and coverageDrafts carry it too. Near the bar a script is never scored on one judgment (the owner's rule, 2026-10-04). A further judgment that fails for good is queued again as a fresh job (judgingInProgress.requeues, at most SCRIPT_COVERAGE_FAILED_JUDGMENT_REQUEUES (2), within the extra-judgment spend cap). A script, rubric or model that changed between judgments near the bar can't be judged further. When the median still cannot be completed, the report lands failed with subjectMetadata.judgingIncomplete (judgments, scores, maxJudgments, passMark): neither a pass nor a fail. Every surface says "Coverage couldn't finish judging — Score again": the read's judgingIncomplete and summary, MCP get_coverage, the CLI, the app's toast and Slug's failureReason. The story-job gate scores such a draft again, once (orchestration key …:rescore), before reading it as a null score. A null score sends the draft to a paid rewrite, and a good draft must not be rewritten because judging could not finish.

Plan coverage (storyboard-coverage-worker.ts) is never decided on one judgment near the bar (the owner's rule, 2026-10-04). A FURTHER judgment that fails for good is queued again as a fresh job (judgingInProgress.requeues, at most STORYBOARD_COVERAGE_FAILED_JUDGMENT_REQUEUES (2), within the revision's extra-judgment spend cap). If it still cannot run, the report lands failed with subjectMetadata.judgingIncomplete and judging.stoppedBecause: judging_incomplete: neither a pass nor a veto. Every surface says "Plan coverage couldn't finish judging — Score again" (judgingIncomplete on the read). A judgment's blind first-viewer read is kept on judgingInProgress.blindRead (bound to that judgment and to the blind rubric's hash), so a queue retry of the judgment never asks for it again. Its shape failures land on subjectMetadata.viewerTakeawayFailures beside the judge's structuredOutputFailure. Karamazov v2's report cmuvkcruq (2026-10-05) showed both: claude-sonnet-5 failed the blind read's shape on 14 of 22 calls, those failures spent judgment 2's attempts, and a Central-question veto was decided on one judgment.

publishing-ui.ts

CreateServerFn wrappers for the Writers Lab Publishing tab.

show-ui.ts

CreateServerFn wrappers for the Publishing tab's Show tab (components/writing-lab/show-panel.tsx): a read-out of a show that is set up by talking to Slug (BL-1083), plus its direct acts. Each calls the same core as the Story API, MCP, the CLI and Slug (server/show-api.ts); the signed-in owner pressing the button is the confirmation (no caller).

shows-running-fns.ts

story-season-runs-ui.ts

CreateServerFn wrappers for a season run in the app: the Overview's Seasons tab, where a season is produced and its run reviewed inline (components/writing-lab/seasons/project-seasons-tab.tsx, season-production-control.tsx, season-run-rail.tsx, season-run-next-step.tsx, season-episode-brief.tsx), and a product season's videos on the Publishing page (publishing-tab.tsx). Each calls the core the Story API's season-run routes call (story-season-runs.ts); the signed-in writer pressing the button is the userConfirmed: true an agent collects. Slug's create_season_run and map_season_episode (lib/ai/season-run-chat-tools.ts, the Series Bible chat, paid workspaces) call the same plain functions.

A run maps only its season's episodes: the Series Bible entries the season map files under that season (joinPlannedEpisodes: a written episode in its script's season, an unwritten one in the season its label names, else 1). A season the Bible maps nothing to is refused, naming the seasons it maps. The plan reads each must-know line as its own mustKnowBeforeWriting item (seasonEpisodeMustKnow).

story-sources-ui.ts

CreateServerFn wrappers for a project's Sources in the app: the Sources panel on the project page (components/writing-lab/project-sources-panel.tsx, mounted by routes/dashboard/projects.$projectId.tsx). Attaching a source was API, CLI and MCP only (dogfood gap, 2026-10-11). Each calls the core the Story API's source routes call (story-sources.ts: createStorySource, listStorySources, deleteStorySource), so a link is fetched by the one fetch path (fetchUrlSource, with its address checks) in the extract worker. Slug's attach_source (lib/ai/project-source-chat-tools.ts, the Series Bible and project-setup chats) calls attachProjectSourceForUser; the shared read list_sources (lib/ai/shared-read-tools.ts) calls listStorySources / getStorySource. The writer's view of a source (kind, state, failure reason in their words, summary) is lib/project-sources.ts.

publishing-worker.ts

Async publishing worker registered as publishing-release-publish.

/api/v1 routes

writer-profile.ts

contact.ts

newsletter.ts

comments.ts

settings.ts

Public Functions

Admin-Only Functions

All require role === ADMIN (enforced by requireAdmin()).

admin-integrations.ts

Registry for the products an organization can connect. Admin-only, enforced by a local requireAdmin() copy (same shape as settings.ts / ai-config.ts).

ai-config.ts: operator controls

Admin-only (requireAdmin()). Operator controls, not writer surfaces, so they have no Story API, MCP or CLI counterpart.

organizations.ts

Teams for the BUSINESS track. creatorContext === 'company' is the discriminator, not the workspace track — business and content creators both sit on STORYTELLER_TRACK, so hiddenForTracks: [STORYTELLER_TRACK] would hide these surfaces from the very users they are for.

Three exported assertions the rest of the feature is built on:

• requireCompanyCreator() — requireUser() + a UserProfile.creatorContext read. Throws the same 'Organization workspace not found.' for "no profile", "self creator" and "professional writer", so nothing about another track leaks. Every organization- and integration-scoped server fn opens with it.
• requireOrganizationMember(organizationId, userId, minimumRole?) — the ownership guard, shaped like requireOwnedInstall in all-hands.ts: re-reads the row and refuses with one sentence for both "does not exist" and "not yours".
• requireOrganizationAccess({organizationId, minimumRole?}) — the one-call rail: composes the two above and returns capabilities from lib/organization-access.ts so a handler never re-derives a rule from a role string.

One organization per person (assertNoExistingMembership, enforced on create and accept): getMyOrganization is singular and an integration's candidates need one unambiguous workspace.

Organization.ownerId and the founder's OWNER membership are protected by the FK (onDelete: Restrict) and by there being no transfer surface. The last OWNER can never be demoted or removed.

integrations.ts

Connected products for the business track: plain *ForUser cores taking an explicit userId (the Story API, MCP and CLI reach the same ones), with .inputValidator() server fns that resolve the session. Cores throw StoryApiError (organization_required, integration_not_found, integration_forbidden, integration_unavailable). Nothing returned carries a client secret, a token or a credentialId. See docs/integrations.md.

integration-project-feed.ts

integration-season-feed.ts

integration-sync.ts (worker)

runIntegrationSyncTick (queue integration-sync-tick, hourly at :07) queues one integration-sync job per CONNECTED connection with a fetcher, chosen origins and a due nextSyncAt. runIntegrationSync reads only for opted-in seasons (a season's own rule, or its project's feed) and for fed projects with no live season (their items are held for the next season), through the product's paced fetch, files NEW / WITHHELD candidates per season (evaluateCandidate, createMany skipDuplicates), saves the cursor per origin after every page, records an IntegrationSyncRun, and maps errors to healthCode (a rate limit never flips the connection to reconnect).

integration-curation.ts

Source curation — the human half of the leak guard. Business track only: every function opens with requireOrganizationAccess (which composes requireCompanyCreator + membership + role floor). Acting also requires canCurateSources (EDITOR and above); reading is open to VIEWER.

acceptSeasonSourceCandidate re-runs evaluateCandidate from lib/integrations/audience-policy.ts against the season's current audienceIntent + audiencePolicy. The state a sync worker stored at pull time is a display hint, never authorization. A withhold is a returned outcome (with its reason), not a thrown error, so a reviewer sees why and a bulk review is not aborted by one refusal.

Season ownership is asserted alongside org membership: the StorySeasonRun must be the caller's own, because the whole story/publishing tree is keyed on userId and carries no organizationId.

outline-map.ts (episode outlines)

An episode of a season map keeps its outline in ONE place: the project's outline_map document, keyed by the Series Bible's episode id. saveEpisodeOutline is the one writer, behind the episode's Outline tab (saveScriptOutline), Slug's save_episode_outline (Series Bible chat, general chat, and an episode's drafting chat), and PATCH /story-projects/{projectId}/outline-map (CLI outline save, MCP save_episode_outline). loadProjectOutlines is the one reader: the EFFECTIVE map, where an episode with nothing written takes its season-map note as its outline when that note lays the episode out act by act or scene by scene (seasonMapNoteIsOutline). Outline coverage (readiness, payload, staleness), the Outline tab, Slug's context and the season planner all read it. A written screenplay is not an outline. A script that covers no season-map episode keeps its outline on the script (creativeAnalysis.outline). Outline coverage staleness compares the scored episodes to the current ones by content, because a season-map note changes without the outline map's revision moving.

scripts.ts

pitch-deck.ts

video-platform-export.ts (a deck's or trailer's copy for YouTube or X)

Owner decision D7 (2026-10-12): an export takes a target. site is the master re-stitch it always was; youtube and x make a COPY of the finished master levelled to -14 LUFS integrated with its true peak at or under -1 dBTP, by a final two-pass ffmpeg loudnorm on the copy only (lib/platform-loudness.ts): the master is measured with the EBU R128 meter (ebur128), loudnorm is fed those readings with linear=true and its widest range target (50 LU, so a wide range alone never forces its dynamic mode), the picture is copied (-c:v copy) and the sound delivered as every master is (48 kHz stereo AAC 192k). The copy is measured as delivered and made again, aimed by what it measured, until it lands within 0.2 LU (at most three passes, each from the master); one outside ±0.5 LU or over -1 dBTP is refused, never delivered. A master whose peaks sit at the site's -1.5 dBTP cap cannot reach -14 with one gain, so loudnorm's dynamic mode limits it (it builds on production's ffmpeg 5.1 because the delivery format is named after it). The copy is made from the FINISHED master the job plays NOW: an out-of-date, failed or missing master is rebuilt first and the copy waits (waiting). Waiting copies are settled (kickWaitingPlatformExports) by both master stitches the moment a master is published (before the version, bell check and chapter mix) and by any read that finds one waiting: queued from a finished master; failed with the plain reason when the published master is a 480p preview of a cut that went back to review (a deck's complete with no preview stamp, a trailer's trailerExportReadiness); left waiting while the cut is finished again or a stitch is queued, running or retrying; failed for good when its rebuild failed with nothing coming. A finished deck assembling a preview refuses a new copy (409 video_platform_export_not_finished). A loudness measurement that fails is never silence: only ffmpeg's "matches no streams" or a silent reading passes the master through; any other failure throws and the job retries. State lives in the job's platformExports column (one entry per target, written atomically per target, owned by its requestId), worked by the video-platform-export queue (stately, one key per surface, job, target and accepted request; a null send succeeds only when that exact request is already backed), and read on the deck's chapters read and the trailer's beats read (platformExports), Slug's status tools, and the export dialog (getVideoExportState in server/video-export-state.ts, components/writing-lab/render/video-export-dialog.tsx). Story API POST /pitch-decks/{jobId}/video-export / POST /trailers/{jobId}/video-export { target? }; MCP export_pitch_deck_video / export_trailer_video (target); CLI pitch-deck|trailer export <jobId> [--target site|youtube|x]; Slug's two export tools take target. Free.

Publication settlement reports a target as queued only after dispatch succeeds or its exact request has backing work. Dispatch failure records and returns the failed copy, including when the master publishes before the waiting export request answers; a failure from a replaced request cannot classify its successor as failed.

artifact-titles.ts (renaming a plan, a deck, a trailer or a result)

Owner, 2026-10-11: no surface could rename these. One core per kind answers its Story API PATCH, MCP (rename_plan, rename_pitch_deck, rename_trailer, rename_artifact), the CLI (plans rename, pitch-deck rename, trailer rename, artifacts rename) and Slug (the project chat's rename_plan, the deck and trailer chats' rename_pitch_deck / rename_trailer, the table-read chat's rename_table_read). A deck's and a trailer's name is a display name on its own title column (their plan, coverage and master never read it; null gives the automatic name back); a plan's is StoryPlan.title; a table read's is the title of the script it performs (updateScriptForUser). Free; nothing renders or goes out of date.

A waiting plan's Rename on the project page is renamePlanFromApp (story-workflow-ui.ts, input {planId, title}), on the core renameStoryPlanForUser that PATCH /api/v1/story-plans/{planId} uses. renameArtifactForUser (PATCH /api/v1/artifacts/{artifactId}) renames a table read through its script's title and a finished deck or trailer through its job; renameTableReadScriptForUser is the table-read chat's door, by the script version it holds. A table read's name is also changed in the script's Edit dialog in the Writers Lab library (updateScriptMetadata).

score-to-picture.ts

One score composed to a deck's or trailer's cut and laid under the whole master in place of the table read's scene beds (lib/marketing/score-to-picture.ts; the queued composer is score-to-picture-worker.ts on the score-to-picture queue; the cue sheet is planned by the score_to_picture_cue_sheet sidecar). The writer's own music is never replaced. No dead air (score-no-dead-air): after composing and conforming, the worker scans the score against the cut's length (100 ms RMS windows under −50 dBFS for longer than 1.5 s; a quiet head longer than 1 s unless the cue sheet enters on a hit later, scoreDeliberateEntryMs; a tail whose digital silence, under −60 dBFS, starts more than 0.5 s before the cut, unless it is a real fade-out falling over the last 3 s); a silent composition is composed again with the silent sections told to sound from their start (on the per-section path, only those sections), what stays silent is filled from the music beside it (a silent tail from its last audible bars, extended to the cut), and the state's silentGap (with its writer-visible note, also the end of message) says what happened on every surface. EARLY MUSIC (owner, 2026-10-05): a score can be asked for on a draft plan (and while the first pass renders) with its direction; it is priced on the PLANNED cut (scoreCutFromPitchDeck(..., { planned: true }) lays every chapter at its planned share; a trailer's cut already does), waits for the master (waiting_for_master), and a SKETCH to the planned cut is composed right away by the same planner, composer and dead-air guard (the worker's mode: 'sketch', stored as scoreToPicture.sketch; never banked, laid or charged). While a score is asked for (scoreToPictureRequested: waiting, queued, composing or laid) the deck assembly neither reads nor lays the table read's beds, and the chapters read's musicPlan projects none: it leads with the direction and score.sketchUrl. Video coverage measures the laid score too: an audioSync finding over dead air in it gets the remedy rescore, never a retake. Story API: GET|POST /{pitch-decks|trailers}/{jobId}/score-to-picture, POST …/score-to-picture/revert; MCP get_/score_/revert_*_score_to_picture; CLI <pitch-deck|trailer> score-to-picture <jobId> show|start|revert; Slug mounts the same three tools.

bell-lane.ts

BELL ON THE BEAT (owner on Karamazov v2, 2026-10-06: the composed score held no regular 2 s strike, so a real bell is laid): one bell sound — a My Library sound effect, or one made from words with the sound-effect generator and banked — struck on every beat of a deck's bell beat grid (its title sequence's, #1116), frame-exact, as ONE lane on its audio timeline (audioTimeline.bell, lib/marketing/bell-lane.ts). Every beat or every 2nd; fromSeconds/toSeconds (default the whole deck); skipSceneIndexes (black interludes, chapters, the title sequence); the intros and the title accented; its level (default 0.12) on a sound levelled to one peak — when the lane's sound is set, a copy peaking at -1 dBFS is made once with ffmpeg's volume (server/bell-sound-level.ts, sound.normalized) and struck, so a level is the same loudness for every bell; ducked under the spoken lines with the score's duck. The sketch mixes the bell against the score at the level the master lays it (0.25), and both the sketch and the master check weigh each strike against the score (audibility, a note when the bell sits more than 12 dB under it). The strikes are derived wherever the lane plays: the master mix (resolveTimelinePlacements with the deck's pitchDeckMasterBellGrid, one <Audio> per strike), the sketch (lib/marketing/bell-lane-mix.ts, the score-to-picture worker's sketch and bell-mix modes: the score alone kept as sketch.scoreUrl, the sketch mixed again whenever the lane changes) and the check after assembly (server/bell-lane-check.ts, run where every deck master is published: each strike's onset measured in the master's audio, kept as assetManifest.bellCheck, bookkeeping). A score to picture composed with a lane leaves room for it (no bell descriptors, bells and downbeat percussion among the composer's negatives, the planner handed a Bell lane: line; the score_to_picture_cue_sheet row's THE BELL LANE section, rollout bell-lane). Free: a deck in review or finished re-stitches its master for its sound. Story API: GET|POST /pitch-decks/{jobId}/bell-lane, POST …/bell-lane/remove; MCP get_pitch_deck_bell_lane, strike_pitch_deck_bell_on_the_beat, remove_pitch_deck_bell_lane; CLI pitch-deck bell <jobId> show|strike|remove; Slug mounts the same three tools. The UI reads the bell (one read-only line on the deck page, components/audio/bell-lane-line.tsx, and the timeline's Bell lane) and changes it through Slug: its three tools, and a painted bell wizard's Apply (server/surfaces.ts). The bespoke Bell on the beat panel and its setBellLane / removeBellLane server fns are gone (owner, 2026-10-06).

video-versions.ts, video-versions-review.ts

A DECK'S AND A TRAILER'S VERSIONS (owner, 2026-10-09: "the raw individual clips are saved off and organized pre-stitching so we can always repurpose them"; owner D9, 2026-10-11: trailers too, so a trailer re-assembly never overwrites its master without keeping it). One core serves both surfaces through a surface adapter. Every published master — preview, early look or finished — is recorded as a numbered PitchDeckVersion or TrailerVersion (docs/database.md) by recordPitchDeckVersionSafely / recordTrailerVersionSafely, called where the master is published (pitch-deck-video-export.ts, trailer-video-export.ts; never fails the stitch). Its clips are copied server side (R2 CopyObject, never re-encoded) into pitch-decks/<jobId>/versions/<n>-<YYYYMMDD-HHMM>/chapters/<NN>-<slug>/ or trailers/<jobId>/versions/<n>-<YYYYMMDD-HHMM>/beats/<NN>-<slug>/ with a manifest.json by the video-version-archive queue (video-version-archive.ts, { surface, versionId, task: 'folder' }; a copy already there with the source's ETag is kept; at most 400 objects), queued only through the queue the stitching worker already runs. Its zip is packed on request (task zip: stored, streamed from R2 into a multipart upload, at most 16 GB) and read back as a signed link. Story API GET /pitch-decks/{jobId}/versions / GET /trailers/{jobId}/versions, GET …/versions/{number}, POST …/versions/{number}/zip, POST …/versions/{number}/restore (BL-4114: the takes it played chosen again and a master assembled from them); MCP list_pitch_deck_versions / list_trailer_versions, get_pitch_deck_version / get_trailer_version, request_pitch_deck_version_zip / request_trailer_version_zip, restore_pitch_deck_version / restore_trailer_version; CLI pitch-deck|trailer versions <jobId>, pitch-deck|trailer version-clips <jobId> <number> [--download <dir>] [--zip], pitch-deck|trailer restore-version <jobId> <number>; Slug mounts the same four tools in each chat (the reads work with a chapter or beat focused). The reviews' Versions list (components/writing-lab/render/video-versions-list.tsx) reads them through:

video-interludes.ts, video-closing-sequence.ts, master-interludes.ts

A DECK'S AND A TRAILER'S BLACK INTERLUDES AND CLOSING SEQUENCE (owner, 2026-10-02 and 2026-10-06 for decks; owner D9, 2026-10-11: trailers too). One core each serves both surfaces through a surface adapter (which table, which plan column, which key a unit goes by: a deck's afterChapterIndex, a trailer's afterBeatIndex, a beat's place, re-keyed when beats are inserted, moved or removed). The rules are one module each (lib/video-interludes.ts, lib/video-closing-sequence.ts): both masters lay the blacks and the closing as segments of their one segment list (pitchDeckMasterLayout, getTrailerRenderPlan), the score's cut, video coverage and plan coverage read them, and the voices check counts a line over black. updateVideoInterludesForUser({surface,…}) replaces the whole list (validated whole; a cast speaker needs a voice): a draft's plan is queued for coverage again, a rendered video's master is stitched again (free). updateVideoClosingSequenceForUser({surface,…}) sets the closing whole; directClosingTextMotionForUser / clearClosingTextMotionForUser direct one card through the motion-text director (every save a compare-and-swap on the plan). Each assembly voices a line over black and makes its sound through one loop (voiceInterludes, server/master-interludes.ts; our cost): the narrator's lines in the video's narrator (a deck's narrator rule; a trailer's resolveTrailerNarratorVoice), a cast line in that person's voice, a sound banked and never laid when someone talks in it. Story API POST /pitch-decks|trailers/{jobId}/interludes, POST …/closing-sequence, POST …/storyboard/direct-text-motion with a closingElement; MCP update_pitch_deck_interludes / update_trailer_interludes, update_pitch_deck_closing_sequence / update_trailer_closing_sequence; CLI pitch-deck|trailer update-interludes, pitch-deck|trailer closing-sequence, … direct-text-motion --closing-element; Slug mounts the same tools in each chat. The editors carry no transition control between two units and no Closing form (owner, 2026-10-18: the knobs are Slug's): the black between units and the closing are told to Slug, and the page only reads them. The server functions that remain:

project-brand-logo.ts

The deck and trailer Closing cards read, upload, replace and remove their project's logo through the same project update as the Story API's brandLogo, CLI projects update, and MCP set_project_brand_logo. Uploads accept PNG, JPEG or WebP up to 2 MB and 4096 pixels on a side. The server decodes the image and stores its own PNG or WebP copy without metadata or trailing content. Removal clears the project field; saved closings retain their copied logo until saved again. The site's "Remove logo" also saves this video's closing without the logo card when it was on.

project-access.ts / project-members.ts / project-members-fns.ts

THE ACCESS RULE FOR A PROJECT (server/project-access.ts). requireProjectAccess({ userId, projectId, need: 'read'|'edit'|'manage', match?, operation?, via? }) returns { projectId, routeId, name, kind, ownerUserId, actorUserId, role }: 404 project_not_found for anyone who is neither the owner nor a member (as before sharing), 403 project_read_only for a viewer asking to change it, 403 project_owner_only for a member asking to manage (delete, members). Admins get no content access from it. A member's edit is recorded as a member_write ProjectMemberEvent. Rows inside the project are read and stamped with ownerUserId; credits, caps, My Library, voices, conversations and the audit stay actorUserId. requireProjectOwner is the owner-only check for every surface not yet opened to members (assertProjectOwned in story-project-ownership.ts calls it); requireProjectJobAccess checks a trailer or deck through its project (a standalone job stays its owner's); accessibleProjectsWhere(userId) is the list filter.

PROJECT MEMBERS (packages/shared/src/project-members.ts). Core: listProjectMembersForUser (anyone who can open the project, or an admin), addProjectMemberForUser (by email — an address with no account is invited to set a password and joins in the same step, invited: true; owner or admin; product projects only, 409 project_members_product_only), updateProjectMemberForUser, removeProjectMemberForUser (a member may remove themselves), each with a ProjectMemberEvent in the same transaction and a live update to the member; listUserProjectsForAdmin (admin Users tab). A shared project's kind cannot change while it has members. Server fns (project-members-fns.ts): listProjectMembersFn, addProjectMemberFn, updateProjectMemberFn, removeProjectMemberFn (the project ⋯ menu's "Share project"; admin: true from the admin Users tab records admin_ui; an admin impersonating the owner is recorded as the actor), listUserProjectsForAdminFn (never while impersonating). Story API GET|POST /story-projects/{projectId}/members, PATCH|DELETE /story-projects/{projectId}/members/{userId}; MCP list_project_members, add_project_member, update_project_member, remove_project_member; CLI projects members list|add|update|remove; Slug list_project_members, manage_project_members (proposes, then acts on confirmed: true). Live updates of a shared project reach its members (server/live-events.ts).

ORGANIZATION MEMBERS (packages/shared/src/organization-members.ts). Core (server/organization-members.ts): listOrganizationMembersForUser (anyone in the caller's business organization), addOrganizationMemberForUser (by email as admin, editor or viewer — an address with no account is invited to set a password and joins in the same step, invited: true; the owner and admins, never above their own role; one organization per person: 409 organization_member_elsewhere), updateOrganizationMemberForUser, removeOrganizationMemberForUser (anyone may leave; the owner never changes or leaves: 403 organization_forbidden). Server fns (organization-members-fns.ts): the Integrations page's Team card. Story API GET|POST /organization/members, PATCH|DELETE /organization/members/{userId}; MCP list_organization_members, add_organization_member, update_organization_member, remove_organization_member; CLI integrations team list|add|update|remove; Slug list_organization_members, manage_organization_members (proposes, then acts on confirmed: true).

workspace-role.ts / workspace-role-fns.ts

UNLIMITED STUDIO CREDITS (server/unlimited-credits.ts, docs/credit-billing.md): setUnlimitedCredits (admins only, read from the database; only an admin or an allow-listed demo account, else 403 unlimited_credits_not_allowed; sets User.unlimitedCredits + internalAccount and writes an UnlimitedCreditsEvent; idempotent). Server fn (unlimited-credits-fns.ts): setUnlimitedCreditsFn (POST {userId, unlimited}; admin Users tab, never while impersonating). Story API PUT|DELETE /admin/users/{userId}/unlimited-credits; MCP set_unlimited_credits; CLI admin unlimited-credits on|off <userId>. Every limit reads the flag through isUnlimitedCreditAccount (lib/unlimited-credits.ts) or balanceCovers (lib/credits.ts).

THE WORKSPACE ROLE (Screenwriter writer, Content creator creator, Business business; packages/shared/src/workspace-role.ts). Read from the profile's track + creator context, never stored twice. Core: readWorkspaceRoleForUser, setWorkspaceRoleForUser (refused 403 role_switch_not_enabled unless User.workspaceRoleSwitchEnabled, admins included; writes the pair + a WorkspaceRoleEvent in one transaction; the same role is a no-op), setWorkspaceRoleSwitchForUser (admins only, read from the database; idempotent; audited), defaultProjectKindForUser (Business starts a project with no kind as product), assertFirstRunRoleWrite (onboarding's own track/context writes refuse once onboarding is done). Server fns (workspace-role-fns.ts): getMyWorkspaceRoleFn (GET), setMyWorkspaceRoleFn (POST {role}; the account menu's role picker, components/auth/workspace-role-picker.tsx, and the profile page; neither UI says who can turn switching on), setWorkspaceRoleSwitchFn (POST {userId, enabled}; admin Users tab, never while impersonating). Story API GET|PUT /account/workspace-role, PUT|DELETE /admin/users/{userId}/workspace-role-switch; MCP get_workspace_role, set_workspace_role, set_workspace_role_switch (and whoami.workspaceRole); CLI role, role set <writer|creator|business>, admin role-switch enable|disable <userId>; Slug set_workspace_role. Business adds the BUSINESS_PROMPT snippet on top of STORYTELLER_PROMPT (server/writer-guidance.ts). updateProfile no longer takes workspaceTrack.

THE CRAFT FOCUS (the kind of work Slug coaches toward; packages/shared/src/craft-focus.ts holds the one list, stored on UserProfile.storytellerSubset). Core: setCraftFocusForUser (server/craft-focus.ts): a key or plain words matched by normalizeStorytellerSubset, null/empty clears, a value naming no focus refused 400 validation_failed with details.options; the same focus twice writes nothing (changed: false). Server fn saveCraftFocus (POST {craftFocus}; Profile → Craft focus, components/profile/craft-focus-control.tsx). Story API PUT /account/craft-focus (read on GET /account/workspace-role as craftFocus); MCP set_craft_focus; CLI craft-focus, craft-focus set <focus>, craft-focus clear; Slug set_craft_focus.

demo-accounts.ts / demo-accounts-fns.ts

DEMO ACCOUNTS (admins only; docs/auth.md "Demo accounts"). Core: readDemoAccountIds, setDemoAccount (audited; an admin account is refused; removal revokes every minted session), listDemoAccounts, mintDemoSession (via the server-only Better Auth plugin; refused for non-admins, non-listed or admin targets, OAuth grants and TTLs outside 5 min–8 h), revokeDemoSession, checkDemoSession (the per-use check), demoImpersonationActor / demoSessionActor (who may act for a demo account), recordDemoAccountEvent. Server fns for the Users tab (demo-accounts-fns.ts, signed-in admin, never while impersonating): getDemoAccountsFn (GET), setDemoAccountFn (POST {userId, demo}), revokeDemoSessionFn (POST {sessionId}). No mint from the browser. Story API /admin/demo-accounts[/{userId}[/sessions]], /admin/demo-sessions/{sessionId}; MCP list_/add_/remove_demo_account, mint_/revoke_demo_session; CLI admin demo-accounts|demo-account|demo-session.

video-destinations.ts

VIDEO DESTINATIONS (destination videos PV1). listVideoDestinations() reads every switched-on VideoDestination row in order and checks each one's spec (and family) against @sleeperhit/shared/video-destination-spec: the usable ones as destinations, the failing ones as unavailable with the reason, never guessed. getVideoDestination(key) reads one: 404 video_destination_not_found without a switched-on row, 409 video_destination_unavailable when its spec fails. readVideoDestinationRow(row, now) is the pure check, and sets specMayBeStale when verifiedAt is more than 90 days old (or missing on a row with sourceUrls). The same catalog for every account; free. Story API GET /video-destinations and /video-destinations/{key} (source:read); MCP list_video_destinations / get_video_destination; CLI destination list|get <key>; Slug's list_video_destinations in the project's chats, painted as a Summary card (components/chat/video-destinations-card.tsx). No server fn: the UI is that painted read.

capture-depth.ts / capture-depth-setting.ts / capture-depth-review.ts

A CAPTURE BEAT'S DEPTH (app-to-trailer PR 1.6). captureDepthComposite(input, deps?) makes the composite a capture beat with a depth preset plays in the master's card slot: it reads the CaptureDepthPreset rows (clamped), plans the shot from the capture's events.json (lib/capture-depth/planner.ts), publishes the stage plate once, renders the CaptureShot composition through renderRemotionMediaToBuffer (label trailer-capture-depth; anything above flat farmPolicy: 'farm-only', and when no box takes it the pod renders subtle at 720p), stores it beside the trailer's media by a content key, and checks it against a flat twin (rendered text size, a sub-pixel exact text-crop SSIM via measureCaptureTextSsim, the camera's speed), stepping down one preset at a time while it got harder to read. Called by the assembly (server/trailer-capture-picture.ts), which hands it the edit's raw master and edit map when it has one: an edit with its cursor burned in then plays from the clean master under the one drawn cursor, planned from the edit's own events.json, decided per preset planned (captureCursorSource, lib/capture-depth/edit-map.ts; S3a). The raw master is private: the renderer gets a presigned GET (≤1 h, signTrailerRawCapture), never a public copy, and nothing stored names it. Free. getTrailerCaptureDepthForUser / setTrailerCaptureDepthForUser read and set TrailerJob.captureDepth (free, any state; a rendered trailer's master is assembled or stitched again); the server fn setTrailerCaptureDepth (server/trailer.ts, requireAIAccess) is the review's picker. A beat's own preset and stage caption are refineTrailerBeat's depthPreset / stageCaption. applyCaptureLegibilityVerdicts (the video coverage worker, after a report) sets a step-down ceiling on each capture beat the Gemini watch found harder to read and asks for the master again. Story API GET|POST /trailers/{jobId}/capture-depth; MCP get_/set_trailer_capture_depth; CLI trailer capture-depth <jobId> [--preset …]; Slug mounts the same two tools.

quiet-track-setting.ts

A DECK'S AND A TRAILER'S QUIET TRACK (Karamazov v5, 2026-10-08 for decks; owner D9, 2026-10-11: trailers too). One core reads and sets PitchDeckJob.quietTrack / TrailerJob.quietTrack (silence, room_tone, or null: none): getQuietTrackForUser({surface,…}) counts the renders it reaches, the quiet renders too long for one and the takes already rendered with each track, over the master's units (a deck's chapters, whose stretches that keep their own sound are left out; a trailer's beats, which keep none); setQuietTrackForUser({surface,…}) sets it (free, any state; it changes only the takes rendered after it). Each take is built with it by quietTrackForTake (server/scene-render/quiet-tracks.ts), from the deck's call audio and from the trailer's renderOneTake, and records what it was sent. No server fn: the UI reaches it through Slug. Story API GET|POST /pitch-decks|trailers/{jobId}/quiet-track; MCP get_/set_pitch_deck_quiet_track, get_/set_trailer_quiet_track; CLI pitch-deck|trailer quiet-track <jobId> [--track silence|room_tone | --off]; Slug mounts the same two tools in each chat. A duplicate carries it.

project-sounds.ts

THE SOUNDS A PROJECT USES (owner on Karamazov v3, 2026-10-06: "use the same bell as v2"): listProjectSoundsForUser finds every sound where it was used — each deck's bell lane, every music clip and sound effect on a deck's or trailer's audio timeline — named as used and by its video, numbered in the project by when it was made ("Deck 2 · Karamazov v2"), each with bellSound ({sound: {fromJobId}} or {assetId}) to strike it as a deck's bell. No server fn: the UI reaches it through Slug (list_project_sounds, and the bell rework wizard's answers). Story API GET /story-projects/{projectId}/sounds?kind=&query=; MCP list_project_sounds; CLI projects sounds <projectId> [--kind bell|music|sfx] [--query <text>]. Reads only.

surfaces.ts

PAINTED SURFACES (owner, 2026-10-06; docs/design/slug-painted-surfaces.md): Slug paints a short, curated wizard in the deck conversation (paint_surface: one question a step, 2–4 answers with one recommended, Listen on a sound, then one line and Apply) or a one-card summary, from a fixed catalog rendered by components/chat/painted-surface.tsx. The spec is a json-render Spec (lib/surfaces/spec.ts), stored as a ChatSurface row with the deck the chat resolved when it painted. An apply sends only the chosen answer ids; the arguments come from the stored spec and run through the op's own core (lib/surfaces/ops.ts: pitchDeck.bellLane.set → setBellLaneForUser, pitchDeck.scoreToPicture.start → priceOrScoreToPicture). A priced op answers a quote first and runs only on a confirm with that quote's token. What was applied reaches Slug on the writer's next turn (lib/surfaces/history.ts), with no model turn per apply. Headless callers call the op's own route, MCP tool or CLI command.

chat-reply-status.ts

writing-lab-projects.ts (project pages)

writing-lab-projects.ts serves the project pages from one index: getWritingLabProjectOverview (the project Overview page, /tools: project, gate, written episodes; its Next steps tab is the checklist and its Series Bible tab, ?tab=bible, the whole Bible read-only) and getWritingLabProjectForUser (Videos: every version with its job counts and characterCount; no version's cast or text).

conversation-messages.ts

A chat panel shows a conversation's tail (lib/ai/chat-message-window.ts: the latest 12 messages, plus anything streaming). getConversation({ slug, tail: true }) (the project chats, the full-page chat, and the screenplay editor chat outside a surgical pass), the trailer thread reads, the Cast chat (getOrCreateCastConversation) and the table-read chats (getOrCreateTableReadConversation, and the scene theater, global theater, DJ Studio and SFX Studio chats through openTableReadModeConversation in server/table-read-mode-conversation.ts) load only that tail and say how many saved messages come before it (olderMessageCount); "Show earlier messages" loads older ones a page at a time. While the panel holds only part of the history, each chat turn sends historyBeforeMessageId (its oldest saved message), and routes/api/chat/stream.ts reads everything saved before it, so the model still reads the whole conversation. One read, readConversationMessageWindow, serves all three, ordered by (createdAt, id). A conversation select takes the tail with ...CHAT_TAIL_SELECT and chatTailOf returns { messages, olderMessageCount }. getConversation never returns systemPromptSnapshot.

chat-tool-worker.ts: saving an approved preview

detect_sound_effects and audit_scene (the table-read setup chat and the Live Read manage pane) work in two steps. apply=false queues a preview: a ChatToolJob whose result.preview is true, which the chat card shows and Slug reads with get_tool_job_result. When the writer approves, Slug calls the same tool with apply=true and that preview's chatToolJobId, plus any subset the writer kept: onlyEntryIndices / excludeEntryIndices (sound effects, and a single-scene audit's emotion and timing changes), onlySceneIndices / excludeSceneIndices (the all-scenes soundscape audit), or keepCurrentSoundscape (a single-scene audit). The tool queues the apply job with previewChatToolJobId, so the chat card and its polling are unchanged. The worker saves exactly the previewed list: it does not call generateObject, resolve a provider or log usage, so there is no second provider cost. The table_read_manage_director prompt row teaches this apply.

A previewed sound-effect cue is skipped, with its reason in skipped, when its line text changed since the preview, the line is not an action line, or the line already has a sound effect. buildSoundEffectCues holds that one-cue-per-line rule for both a fresh run and a preview save. An audit proposal is skipped when its scene or line changed. Indices the writer named that were not in the preview come back in notInPreview. An audit save returns applied: true, plus scenesUpdated for the all-scenes audit.

Slug read cores

The Slug read-access work (docs/plans/slug-read-gaps.md) lets every chat surface read what the writer can see. Wherever a read lived only inside a createServerFn handler, which needs a request session, it was split into an owner-checked core that takes an explicit userId. The server fn calls that core, and so does the chat tool, so the page, Story API, MCP and Slug all go through the same ownership check. A read never dispatches, recovers or bills work. Where a load path used to generate a missing asset, it now takes readOnly, and every read passes it: the chat tools, the Videos panel server fn (getVideoWorkspaceAssets), the pitch-deck status poll (/api/pitch-deck/status) and getPitchDeckJobById, and both storyboard reads on every surface (the getPitchDeckStoryboardBoards / getTrailerStoryboardBoards server fns in the UI, and GET /api/v1/pitch-decks/{jobId}/storyboard / GET /api/v1/trailers/{jobId}/storyboard behind MCP and the CLI). Missing location plates are made by the paths that quote and reserve credits: the approval quote (requirePitchDeckVideoModelAssets) and the render workers.

The reads Slug has on every surface (background activity, Studio Credits, the Series Bible with its coverage and mood board) are chat tools, not server functions. See "Shared reads on every Slug surface" in docs/prompting-and-streaming.md.

Coverage add-on reports (blacklist.ts, production.ts)

The script page's status poll (/api/script/status) applies the same writer-facing relays to the errorMessage of coverage, tableRead, blackList and production (writerFacingFailureMessage on the last two, which read the whole failure in one plain sentence), so a failed job reaches the writer's toast and inline error in writer-facing words. characterAnalysis.errorMessage stays raw on purpose: script-job-status.tsx reads it to detect a missing provider (isMissingAiProviderMessage).

table-read.ts

table-read-chat.ts

table-read-manage-chat.ts

theater-canvas-chat.ts

cast-chat.ts

script-read-voices.ts, cast-jobs.ts: the Cast card's read voice and Redraw

The owner on the Karamazov Cast tab (2026-10-05): the card's voice and the episode's read must never silently disagree, and each picture gets its own Redraw.

cast-picture-redraw.ts: the project canon's Redraw

A person on the project cast canon whom no episode names (Karamazov v2's Grushenka) had no body shot or sheet Redraw: the episode Redraw casts only its screenplay's roster, and the project cast's force redraws the face too.

gold-standard.ts

opportunity.ts, strategy-card.ts

videos.ts, video-model-reference-assets.ts

The same readOnly flag was added to existing reads the chat tools reuse: getPitchDeckStoryboardBoardsForUser and inspectPitchDeckVideoModelPreflightSafe (pitch-deck.ts), inspectPitchDeckVideoModelAssets (pitch-deck-video-model-preflight.ts) and getTrailerStoryboardBoardsForUser (trailer.ts) report missing plates instead of generating them. getAudioTimelineStateForUser (marketing-audio-timeline.ts) shows a legacy timeline migrated without persisting it, since a chat read runs every turn and would race the render workers that write the same manifest.

A read-only inspectPitchDeckVideoModelAssets also passes the script's pending rooms to buildPitchDeckVideoModelAssetPreflight (pendingLocations). A chapter location that resolves only against a room the render will make then reads canonical_location status will_generate ("Made when the video renders…") instead of missing, and does not block plan approval. The approval quote is what makes that plate. The quote and render paths pass no pending set, so a plate they failed to make still reads missing and blocks. A chapter with no location still reads missing.

product-video-plans.ts / product-video-plans-fns.ts

PLAN A PRODUCT VIDEO FROM THE FEATURE MAP (P-101). One core (server/product-video-plans.ts) and one queued run (product-video-plan-worker.ts, budgets in product-video-plan-budget.ts): a queued planner writes capture beats for one feature of the project's feature map, or for a named release and its features, into an ordinary capture-only draft trailer — each beat names its capture, its kept stretch, a narration line, whether it keeps its own sound, and its depth. Free: nothing is charged, reserved or rendered. The run answers at once (202, or the live run an equal body already started with reused: true) and is polled until ready, when it names the draft (trailerJobId, the review link, the conversation bound to it), nextStep: approve_trailer_plan and its live plan check. A strict body: an unknown key is 400 validation_failed naming it; an unknown featureId is 400 with the feature map in details.features; a planned feature is 400 (details.availability); a story project is 409 project_not_product; no shipped feature with a recording of its own yet is 409 product_video_not_ready in the readiness step's own sentence (details.next its verb: the project's first readiness step not done, connect_app first), and a feature with no recording of its own is 409 product_video_not_ready naming it (details.recordedFeatures lists what can be planned) — both read through readProductVideoPlanningReadiness (server/product-readiness.ts, the Overview's readiness read); no eligible capture in the shape is 409 product_video_no_captures (details.byAspect); a run of another project is 404 product_video_plan_not_found; the 31st run in a UTC day is 403 usage_limit_reached. Approval is the ordinary approve_trailer_plan, gated inside approveTrailerPlanForUser (trailer-reference-api.ts) by assertProductVideoPlanCovered: a blocked plan check (409 trailer_state_invalid, details.refusal.code: product_video_plan_blocked) names each blocking finding with its fix and reserves nothing. Story API POST|GET /story-projects/{projectId}/product-video-plans, GET /story-projects/{projectId}/product-video-plans/{runId}, GET /trailers/{jobId}/product-plan-coverage (story:write for the plan; story:read for the reads); MCP plan_product_video, list_product_video_plans, get_product_video_plan, get_product_video_plan_coverage; CLI product-video plan|runs|run|coverage, then trailer approve-plan; the project Videos page's "Plan a video from your feature map" planner (registered only when the project makes capture videos) and the draft's "Plan check" card above Approve (components/writing-lab/trailer/product-plan-coverage-card.tsx); Slug mounts the same four tools in the project's chats. The planner row runs on its own product_video_planning sidecar (Feature TRAILER, its own binding, otherwise the chat's provider).

Exact-run one-time-code routing

app-connections-fns.ts keeps the owner's current connectionId + testId + askedAt checks. Recording answers keep the existing wire captureId + askedAt fields. Both relay through private CaptureRunBinding rows rather than process memory. Recording discovery lists only active bindings for the owned project. The runner GET embeds the expected wire run ID in the signed path (/v1/one-time-code/<encoded run ID>); another run's pause returns null, and the old unscoped GET is absent. POST retains the exact run and question timestamp. No API, CLI, MCP or Slug code entry capability is added. Web needs only its existing runner authentication configuration, never an opening key.

Running Test sign-in browser preview

app-connection-test-preview.ts requires the product's owner and exact current connection/test. getAppConnectionTestPreviewForUser reads signed metadata without taking a picture; CLI, MCP and Slug use its explicit metadata allowlist. A replaced test is app_connection_test_changed (409). Missing or unreachable browser state does not invent an image or sequence.

getAppConnectionTestPreviewFrameForUser is used only by the native owner-session proxy and direct owner-key Story API JPEG adapter; OAuth receives metadata only. It verifies the durable run lease and current configured target before and after the signed read. The private answer authenticates the image together with connection/test, phase, sequence and times. JPEG responses are private/no-store, at most 1 MiB, expire after ten seconds, and never appear in tool results. getProjectAppConnectionTestPreviewFn supplies the native dialog's metadata/current test and existing scoped one-time-code question. listProjectAppConnectionsFn.canPreviewTest comes from owner/product access, independently of sealing configuration or final-picture permissions.

The runner observes the actual login and session-check pages without creating a browser or controlling app state. Explicit image reads coalesce and capture at most every two seconds. Page changes, learned secret values, test completion and expiry invalidate cached bytes. Native masks cover inspectable editable controls, configured sensitive selectors and DOM echoes of already-available secret/session/header values; known uninspectable sensitive surfaces or uncertainty withhold the preview. No arbitrary image/OCR or unknown closed-shadow discovery is claimed. Existing authentication, final-picture handling, budgets and secure code-entry gates remain separate.