Samsarix Story Studio is a local-first manuscript workspace from Samsarix LLC for writers who want explicit control over story canon and a bounded, multi-stage AI drafting process. Build a project, organize ordered scene beats, turn planned chapters into drafts without duplicating them, preview the exact canon selected for a chapter, recover prior revisions, tag and favorite chapters, and export or restore portable files.
The default experience is a deterministic, no-key demo. It does not call an AI provider and is labeled as demo output throughout the interface. Add one supported provider key to use the provider-backed workflow; missing preferred providers fall back to the provider you configured.
This repository is a coherent local product candidate. It is not a hosted collaboration service, a desktop installer, or a scientific consciousness system. Legacy UCF/database fields remain readable for storage and backup compatibility but are not part of the active product interface or represented as evidence.
Requirements:
- Node.js 20, 22, or 24
- pnpm 11.9.0
pnpm install --frozen-lockfile
pnpm devOpen http://127.0.0.1:3000. No account, database, .env file, or provider credential is required. Stories are stored by default at:
- Windows:
%USERPROFILE%\.samsarix-story-studio\studio.json - macOS/Linux:
~/.samsarix-story-studio/studio.json
Set SAMSARIX_DATA_FILE to choose another location. Existing default data at .helix-story-studio/studio.json is copied forward automatically on first use when the new archive does not exist. The legacy HELIX_DATA_FILE setting remains a compatibility alias. This release binds only to loopback and rejects non-local Host and browser Origin values.
- Create a project with a premise, genre, and optional style guidance.
- Add empty chapter plans with working titles and synopsis notes, track each as planned, drafting, revising, or complete, and reorder the manuscript with drag or accessible move buttons. Add and order scene cards with a beat, optional point of view, and location.
- Add characters, locations, factions, items, or lore to its canon. Entries can be always-on or activated by names and phrases.
- Write a planned chapter manually, or choose Draft this plan to complete that exact chapter in the studio while preserving its title, position, and continuity links. Before generation, review the selected canon entries and approximate context-token count; manually include any additional entry.
- Choose a preset or enable up to seven agent roles, then create a clearly labeled demo or provider-backed draft.
- Edit the chapter directly. Every changed save keeps the prior title and manuscript—even a blank planned draft—as a recoverable revision; the newest 50 snapshots per chapter are retained.
- Continue the manuscript, tag or favorite chapters, find them from the archive, export combined Markdown, or download a versioned project JSON backup.
- Restore a backup from the Projects page. The file is validated first and imported as a separate project, so existing work is never overwritten.
Standalone drafts remain supported when a project would be unnecessary.
Generation runs as a durable local job. The studio receives live server-authored stage events, reconnects to an active job after a page reload, and falls back to periodic status checks if the event stream disconnects. Writers can cancel an active job; cancellation aborts the current supported provider SDK request. Stage percentages describe workflow milestones, not token-level streaming or precise time remaining. Project context is capped at eight canon entries and 6,000 characters. Its token estimate uses the transparent approximation of four characters per token; provider billing remains authoritative.
Copy .env.example to .env and set at least one key:
| Provider | Key | Default model | Override |
|---|---|---|---|
| OpenAI | OPENAI_API_KEY |
gpt-4.1-mini |
OPENAI_MODEL |
| Anthropic | ANTHROPIC_API_KEY |
claude-sonnet-5 |
ANTHROPIC_MODEL |
| xAI | XAI_API_KEY |
grok-4.5 |
XAI_MODEL |
GEMINI_API_KEY |
gemini-3.6-flash |
GEMINI_MODEL |
|
| Perplexity | SONAR_API_KEY |
sonar-pro |
PERPLEXITY_MODEL |
Model catalogs change. The defaults reflect the provider documentation reviewed on 2026-07-28, and every model is configurable. Check the current OpenAI, Anthropic, xAI, Google, or Perplexity documentation before spending money.
An experimental preset can make at most eight provider calls and request at most 18,000 output tokens. Each request has one SDK retry and a 120-second timeout by default; LLM_TIMEOUT_MS may be set between 5,000 and 300,000 milliseconds. One generation per user may run at a time.
The upper-bound cost for a run is:
sum over calls ((input tokens / 1,000,000 × provider input price)
+ (output tokens / 1,000,000 × provider output price))
Input size depends on intermediate drafts, so Samsarix Story Studio does not print a dollar estimate that will become stale. Provider dashboards remain the billing source of truth. API keys stay server-side and must never use a VITE_ prefix.
OPENAI_BASE_URL supports an OpenAI-compatible endpoint for the OpenAI provider slot. Compatibility varies and has not been certified for arbitrary local-model servers.
The default profile is deliberately small:
Browser → Express/tRPC on 127.0.0.1 → local JSON archive
↘ optional provider API
- The release supports one local writer identity and requires loopback binding.
- Omitting
DATABASE_URLuses the atomic local-file adapter. - Setting
DATABASE_URLselects MySQL/Drizzle storage and requirespnpm db:migratebefore use.
Local JSON storage is designed for one process and one trusted desktop user. It is not appropriate for multiple replicas, shared-host multi-tenancy, or untrusted network exposure.
| Command | Purpose |
|---|---|
pnpm dev |
Run the local development server with reload |
pnpm build |
Build the browser app and bundled server |
pnpm start |
Run the production build on the configured host/port |
pnpm lint |
Check repository formatting |
pnpm check |
Run strict TypeScript checking on the active product graph |
pnpm test |
Run focused Vitest suites |
pnpm verify |
Run format check, type-check, tests, and production build |
pnpm package:source |
Package a clean committed source tree with SHA-256 metadata |
pnpm db:generate |
Generate a Drizzle migration after schema changes |
pnpm db:migrate |
Apply MySQL migrations |
The HTTP health endpoint is GET /healthz. The public tRPC status endpoint exposes mode and configured provider names/models, never credential values.
- The default build has no analytics and makes no font or provider request in demo mode.
- Local projects, canon, revisions, and stories can contain sensitive text; protect and back up the data file accordingly.
- Generation-job history contains lifecycle metadata and story/project identifiers, not prompts or draft text; the newest 100 terminal jobs per local writer are retained.
- In provider mode, prompts, intermediate material, and drafts are sent to the configured provider. Review that provider’s retention and training terms.
- Generated text can be incorrect, biased, derivative, or unwanted. Quality and content checks appear only when their configured provider-backed reviewer ran; they are advisory signals, not guarantees. Demo mode records no review result.
- Prompt validation, story ownership checks, loopback enforcement, body limits, timeouts, retry limits, and call ceilings reduce risk; they do not make hosted multi-user operation production-ready.
- Project imports accept only the versioned Samsarix backup shape, reject inconsistent references, and cap selected files at 7 MB. Imported ownership and database IDs are always replaced.
The release intentionally does not include token streaming, public sharing, PDF/EPUB export, billing, collaboration, or a desktop installer. Archive search is client-side and suited to a personal library. Backup restore always creates a new project; merging into or replacing an existing project is intentionally unsupported. Live provider calls require owner-supplied credentials and spend approval and were not exercised during credential-free verification.
Legacy component examples remain outside the active TypeScript and runtime graph so historical UI source is preserved without making it part of the release contract. Incomplete QoL helpers and private-platform runtime adapters were removed. Future cleanup is tracked in the productization record.
See CONTRIBUTING.md for the contributor workflow, DEPLOYMENT.md for operation boundaries, docs/PILOT.md for the writer-pilot protocol, docs/EXTERNAL_VERIFICATION.md for provider/MySQL checks, docs/LEGAL_REVIEW.md for counsel handoff, SECURITY.md for private vulnerability reporting, and docs/PRODUCTIZATION.md for the product audit.
No deployment, package publication, account creation, or paid provider request is performed by the repository setup.
Copyright © 2024–2026 Samsarix LLC. The code is source-available under the Business Source License 1.1, with limited production use under its Additional Use Grant. On 2030-07-28—or the fourth anniversary of a version’s first public distribution, if earlier—that version converts to Apache License 2.0. Commercial arrangements are available through contact@samsarix.com.
The license does not grant rights to Samsarix names or logos. See TRADEMARKS.md and NOTICE. This repository’s legal history includes automated and bot-authored commits; Samsarix LLC should have counsel confirm the copyright chain before relying on exclusivity, accepting outside contributions, or registering the work.
Support questions may be sent to support@samsarix.com. Please report vulnerabilities privately as described in SECURITY.md.