A low-effort, beginner-friendly system for novels and speculative worldbuilding.
Built for authors on Linux Mint (XFCE), Debian & modern Linux. Everything in sovereign Markdown & OpenXML. Zero terminal required for daily writing.
-success.svg){kind=icon}
Note
Ars Arcanum is a sovereign, 100% offline, privacy-first authoring platform and worldbuilding operating system.
- Comprehensive Test Suite: Automated test suite with 757 passing unit & integration tests, strict Ruff linter compliance, clean Mypy static typing across 145 files, and the canonical 7-stage integration verification harness (
scripts/verify.sh). - Absolute Creative Sovereignty & Zero Telemetry: Operates strictly on your local machine with zero network calls, zero tracking, and pure Python standard library craft engines without external pip dependencies.
- Advisory-First Creative Freedom (ADR-115): Craft diagnostics provide non-blocking alerts with three resolution pathways (Hard Realism, Speculative Trope, and Author Sovereignty), preserving 100% authorial creative intent.
- Defense in Depth & Data Safety: Strict path traversal validation (
^[A-Za-z0-9_-]+$), atomic file operations (atomic_write), cross-platform file locking (ArcanumLock), hardened archive extraction member inspection, and SHA-256 backup verification. - Zero Vendor Lock-In: Plain Markdown (
.md), standard OpenXML (.docx), YAML manifests, and local multi-tier Git version control.
Start here: Consult the comprehensive Author's Field Manual for a visual step-by-step guide to worldbuilding, multi-volume drafting, automated concordance generation, and publishing. Run Quick Start to install everything. Run
bash scripts/verify.shanytime for a comprehensive health check.
Ars Arcanum provides everything an author needs to brainstorm lore, outline storylines, draft prose, revise manuscripts, compile ebooks, and typeset publication-grade print PDFs—without proprietary software locks or continuous maintenance.
~/Universes/<UniverseName>/
├── universe.yaml → Overarching Universe manifest & continuity Git repository
├── Universe-Index.md → Narrative cosmos hub & cross-world index
└── <WorldName>/ → Pure World Lore Vault (Direct Obsidian Vault with Git repository)
├── world.yaml → World Lore manifest
├── Characters/ → Character profiles with Dataview metadata & relationship maps
├── Locations/ → Sensory regional palettes, cities, and landmarks
├── Factions/ → Guilds, empires, ideologies, and military rosters
├── Economies/ → Currency systems, commodity baskets, and PPP definitions
├── Magic-Technology/ → Hard/soft magic rules, limitations, and costs
├── Bestiary/ → Creatures, apex predators, flora, and monster ecologies
├── Artifacts/ → Legendary relics, magical weapons, and focal items
├── Cosmology/ → Pantheons, deities, astral planes, and prophecies
├── History/ → Historical eras, timelines, and catalytic events
├── Languages/ → Conlangs, phonetic rules, sound laws, and world glossaries
├── Templates/ → fileClasses schemas, writing logs, scene cards, and central index
└── .obsidian/ → Out-of-the-box plugin configs & fileClasses schemas
~/Manuscripts/<ManuscriptName>/
├── manuscript.yaml → Project manifest linking Universe, World Lore Vault & active draft
├── nwProject.nwx → novelWriter project manifest (fileVersion 1.5)
├── Book-01/ → Discrete Git repository for Book-01
│ ├── Draft-01/ → Active discrete draft directory
│ │ ├── Draft-01_Manuscript.docx → Consolidated draft in standard MS Word / Google Docs format
│ │ ├── 01_Act_I/
│ │ │ ├── 01_Chapter.md → Sovereign Plain Markdown source with scene metadata
│ │ │ └── 01_Chapter.docx → Individual chapter in standard Word format (auto-synchronized)
│ │ ├── 02_Act_II/
│ │ ├── 03_Act_III/
│ │ └── 04_Back_Matter/ → Automatically generated Dramatis Personae & Glossary
├── Outlines/ → Three-act structural beats & Subplot-Thread-Matrix.md
├── Exports/ → Exported print PDFs (Typst), EPUBs, and submission DOCXs (Pandoc)
└── Backups/ → Standalone timestamped .tar.gz archives with SHA-256 digests
If you have booted into Linux Mint XFCE or Debian:
-
Clone or download this repository into your home folder:
cd ~/Downloads git clone https://github.com/aryansinghnagar/Scriptorium.git Ars-Arcanum cd Ars-Arcanum
-
Run the automated setup installer:
bash scripts/setup_arcanum.sh
This single command tests your OS environment, installs Git, PyGObject, Zenity, LibreOffice, FocusWriter, Calibre, Obsidian, novelWriter, Typst, Pandoc, literary typography fonts, and installs desktop launchers.
-
Double-click "Ars Arcanum Control Center" on your Desktop (or run
arcanum control-center). On first launch, the welcoming wizard offers a 1-click starter cosmos ("Eldoria-Cosmos / Eldoria-World / Chronicles-of-Eldoria") with pre-configured lore and starter chapters!
| Creative Phase | Tool | Format | Role & Setup |
|---|---|---|---|
| Desktop Control Center | Ars Arcanum App | Native GTK 3 / Zenity / Libadwaita | 6-studio author dashboard with Universe/World/Manuscript navigation, Visual Scene Metadata Inspector, word counts, Word Processor toolbar, 1-click Typst/Pandoc publishing, Git snapshots, and 18 craft/speculative engines. |
| World Bible & Wiki | Obsidian | Markdown (.md) |
Open <WorldName> directly as Vault. Comes pre-configured with Longform, Dataview, Metadata Menu, Calendarium, Storyteller Suite, Storyline, Novel Word Count, and Obsidian Git (10-min auto-commits). (See Plugin Guide) |
| Outlining & Drafting | novelWriter / Longform | Markdown (.md) + nwProject.nwx |
Open ~/Manuscripts/<Manuscript> to draft with novelWriter's structured project tree, status badges (Draft, Revision, Finished), and scene annotations (@pov:, @location:, @char:, @thread:, @time:, @status:). |
| Word Processor Drafting | Microsoft Word / Google Docs / LibreOffice | Standard OpenXML (.docx) |
Dual-synchronized .docx drafting for authors and editors. Pure Python zero-dependency OpenXML engine with bidirectional tag-preserving sync. |
| Deep Sprint Canvas | FocusWriter | Plaintext (.txt / .md) |
Minimalist full-screen distraction-free distraction sprint sessions (F11) with procedural ambient audio generator. |
| Revisions & Collaboration | LibreOffice Writer | .odt / .docx |
Track changes with professional editors and redlining. |
| Ebook Compilation | Calibre | .epub / .mobi |
Graphical EPUB inspection, metadata tagging, and e-reader sync. |
| Typesetting & Print PDF | Typst + Pandoc | .typ / Vector PDF |
Compiles sub-second, publication-grade print PDFs with trade margins, alternating running headers, ornamental breaks, and front matter (half-title, title, copyright, dedication). |
Ars Arcanum includes zero-dependency Python standard library craft engines tailored for science fiction, epic fantasy, space opera, grimdark, alternate history, and novel craftsmanship:
| # | Domain & Engine | Key CLI Commands | Primary Capabilities |
|---|---|---|---|
| 1 | Universal Craft Documentation & Lore Discovery |
arcanum doc <engine>, arcanum doc calc <subcmd>
|
In-CLI and interactive guide across all 50+ craft engines, detailing scientific foundations, worldbuilding relevance, storytelling applications, and prose writing principles. |
| 2 | Resonance Mesh & Thematic Synergy Engine |
arcanum resonance [world] [ms], arcanum resonance bridge <e1> <e2>
|
51-engine knowledge graph calculating cross-domain synergy, narrative tension sparks, coherence audits, and multi-hop thematic conceptual bridges. |
| 3 | Astrophysics & Relativistic Spaceflight |
arcanum calc transit, arcanum calc time-dilation, arcanum calc orbit, arcanum calc system-dossier
|
Non-standard planetary configurations (eyeball worlds, gas giant exomoons, brown dwarfs, circumbinaries), stellar mass-luminosity scaling, parameter sweet-spot engine, scientific plausibility advisor, |
| 4 | Hard Magic & Arcane Constraints |
arcanum magic check, arcanum magic report
|
Sanderson-style advisory rule contradiction and axiom consistency detector (MAG-101), reagent/catalyst audit, arcane fatigue tracking, standalone HTML audit report. |
| 5 | Dynastic Genealogies & Lineages |
arcanum genealogy <House>, arcanum lineage <House>
|
Family tree DAG builder supporting fuzzy unrecorded generations and disputed claims, Obsidian Mermaid compilation, interactive HTML/SVG trees, chronological paradox checks. |
| 6 | Conlang Phonotactics & Sound Laws |
arcanum conlang generate <Lang>, arcanum conlang mutate <Lang>, arcanum conlang family
|
Syllable structure word generator ((C)V(C)), phoneme frequency weighting, cluster blacklist, sound-change mutation rules with overlapping environment support, language family tree registry, and conlanging primer. |
| 7 | Narrative Pacing & Tension Arcs |
arcanum pace [ms], arcanum tension [ms], arcanum words --pov
|
Dialogue vs action vs exposition ratios, sentence length variance, POV screen-time balance & starvation alerts, subplot momentum, Unicode-aware tokenizers, interactive HTML tension curve. |
| 8 | Journeys & Planetary Calendars |
arcanum calc journey, arcanum calendar [world]
|
14 terrain friction coefficients, 8 movement modes, party ration/water burn rates, multi-calendar/multi-era registry with custom date templates and continuous epoch chronology. |
| 9 | Faction Matrix & Campaign Logistics |
arcanum faction [world], arcanum calc battle, arcanum calc logistics
|
Alliance/rivalry chord diagrams, diplomatic paradox linter, writer's battle scenario planner with terrain modifiers and Lanchester formulas, military draft horse and wagon supply radius. |
| 10 | Economy, PPP & Tech Anachronisms |
arcanum economy [world], arcanum audit tech [world] [ms]
|
Multi-currency commodity basket Purchasing Power Parity (PPP), scene price outlier audits, interstellar trade viability, historical technological era anachronism linter. |
| 11 | Causal DAGs & Multiverse Timelines |
arcanum causality [world] [ms], arcanum causality branch [name]
|
Multi-paradigm time-travel validator (Fixed/Novikov, Dynamic Butterfly, Multiverse Branching, Time Loops, Chrono-bubbles), Grandfather & Bootstrap paradox linters. |
| 12 | Climate, Biomes & Trophic Webs |
arcanum calc climate, arcanum ecology [world]
|
Stellar insolation ( |
| 13 | Earth-Eponyms & Sensory Palette |
arcanum audit idioms [ms], arcanum audit senses [ms]
|
Earth-eponym scanner (Achilles heel, Pandora's box, boycott, diesel) with custom whitelist, 6D sensory balance analyzer (Visual, Auditory, Olfactory, Gustatory, Tactile, Kinesthetic). |
| 14 | Prophecy Resolution Matrix | arcanum prophecy [world] [ms] |
Prophecy clause lifecycle tracker (Cosmology/Prophecies/*.md) auditing resolution, fulfillment, and contradictions across manuscript chapters. |
| 15 | Prose Stylistics & Smart Typography |
arcanum audit dialogue [ms], arcanum typography [ms]
|
Dialogue mechanics linter (DIA-101 said-bookisms, DIA-102 floating dialogue, DIA-103 adverb overload), word repetition scanner (ECH-101), smart curly quotes, em-dashes, and ellipsis normalization with frontmatter protection. |
| 16 | Character Voice Profiler | arcanum audit voice [ms] |
Lexical fingerprint analyzer isolating character dialogue by @char: tags: sentence complexity, syllable count, Flesch-Kincaid grade, and voice divergence checks with Unicode character support. |
| 17 | Visual Story Canvas & Corkboard | arcanum canvas [ms] |
Interactive drag-and-drop narrative corkboard mapping scenes onto 11+ story paradigms (Save the Cat, Hero's Journey, 3-Act, 8-Sequence, Kishōtenketsu) with live pacing harmony scoring. |
| 18 | Dual-Track Timeline Synchronizer | arcanum timeline [ms] [world] |
Dual-track timeline engine aligning reader narrative progression with in-world astronomical epoch timestamps to detect chronological paradoxes. |
| 19 | Multi-POV Narrative Threads & Subway Map | arcanum branch [ms] |
Multi-POV character storyline split and convergence tracker with interactive Subway Map exporter and branching choice engine. |
| 20 | Multi-Volume Series Omnibus Compiler | arcanum omnibus [ms] |
Multi-volume compiler assembling multi-book series manuscripts into unified omnibus editions with merged Dramatis Personae. |
| 21 | Universal Corpus & Local Semantic RAG |
arcanum corpus [export|restore], arcanum rag <query>
|
Zero-dependency hybrid TF-IDF + SQLite FTS5 semantic lore retrieval and structured JSONL/SQLite corpus exporter with bidirectional vault restore. |
| 22 | Ambient Craft Wisdom & Tip Engine |
arcanum tip [engine], arcanum tip --depth masterclass
|
Non-obvious narrative mechanics and craft wisdom delivered ambiently across CLI footers, Studio Hub top bars, and Zen Studio drawers. |
Ars Arcanum provides intuitive GUI cockpits, an offline web studio hub, and a unified CLI dispatcher (arcanum or ars-arcanum):
Ars Arcanum Control Center(arcanum control-center): Native Python/GTK 3 & Libadwaita desktop application with 6 studios:- 🪐 Cosmos & Worlds: Universe and World Lore Vault management, creation wizards, interactive cartography, and codex exports.
- ✍️ Manuscripts & Drafting: Manuscript hierarchy tree, live word counts, Word Processing Toolbar ("Open in Word Processor", "Sync DOCX ↔ Markdown"), Draft Revisions & Redline Comparator (fork drafts, visual diff, LibreOffice bridge), and Visual Scene Metadata Inspector.
- 🔮 Speculative Fiction & Craft: Astrophysics, hard magic, dynastic trees, conlangs, pacing, factions, economy, causal DAGs, climate, 6D senses, and prophecy trackers.
- 📚 Publishing & Typesetting: 1-Click Typst PDF, Pandoc EPUB, submission DOCX export, Pre-Flight publication compliance linter, Front/Back matter builder, and Query package generator.
- 🔒 Vault Safety & Backups: 1-Click Git version snapshot button with log viewer, standalone
.tar.gz+ SHA-256 backup creator, Dual-Target Secure External/USB Backup destination manager, restore drill wizard. - 🩺 Diagnostics & Doctor: Toolchain status badges, World Bible lore consistency checks (
world-doctor), and 7-stage verification trigger.
Sovereign Studio Hub(arcanum hub [--port 8080]): Single-file offline responsive web dashboard featuring live project telemetry, chapter progression, lore distribution charts, interactive craft guide, and ambient craft hints.Zen Drafting Studio(arcanum studio [ms]/arcanum zen [ms]): Standalone offline distraction-free drafting studio with slide-out lore drawer and ambient soundscapes.Visual Story Canvas(arcanum canvas [ms]): Drag-and-drop narrative corkboard with live pacing harmony score recalculation.Word Processor Drafting & Sync(arcanum word [ms]/arcanum docx <build|sync|import|open> [ms]):arcanum word [ms]: Opens active manuscript draft in Microsoft Word, Google Docs, or LibreOffice Writer.arcanum docx sync [ms]: Bidirectionally syncs prose changes between.docxand Markdown while strictly preserving YAML frontmatter and scene metadata tags.arcanum config docx-preset <preset>: Switches global formatting preset (standard-submission,modern-manuscript,classic-trade,custom).
New Project Scaffolder(arcanum new <manuscript|draft|world|universe|volume> <name>): Scaffolds novels, drafts, world lore vaults, narrative universes, or subsequent manuscript volumes.Manuscript Drafts & Redline Comparison(arcanum draft <ms>/arcanum compare <ms> <target_draft> <prior_draft>):arcanum draft <ms> [name]: Atomically forks existing prose into discrete draft folders (Draft-01,Draft-02,Draft-03), updates active draft pointer, and tags Git milestone.arcanum compare <ms> [d2] [d1] --browser: Generates accessible, high-contrast standalone HTML Redline reports with soft pastel deletion/addition styling, word delta metrics, chapter navigation sidebar, and search filtering.
Save Snapshot(arcanum save [target] [-m "note"]/arcanum snapshot): Records an instant timestamped Git version snapshot.Dual-Target Secure Backups(arcanum backup [target|--all]/arcanum backup-dest set <path>):arcanum backup-dest set /media/usb/backups: Configures a persistent secure secondary destination (USB, encrypted vault, external mount).arcanum backup <target>: Creates standalone verified.tar.gzarchive with SHA-256 sidecar, simultaneously replicating to local05-Backups/and secondary destination with path traversal rejection.
Publish & Export(arcanum publish [manuscript] [--format book|submission|all]/arcanum export): Compiles print PDF (Typst), distribution EPUB (Pandoc), and standard submission DOCX in one command.Words & Analytics(arcanum words [manuscript]/arcanum report): Shows live word counts, chapter metrics, and status breakdowns.Back-Matter Concordance(arcanum concordance <world> --manuscript <ms>): Compiles publication-ready Dramatis Personae and Glossary back-matter.Health & Diagnostics(arcanum check/arcanum doctor/arcanum continuity): Runs system diagnostics, toolchain verification, character consistency audits, and all craft/speculative fiction checks.
- Firefox Site Blocker:
- Install LeechBlock NG from the Firefox Add-ons Store.
- Open LeechBlock Options -> Import -> Select
configs/leechblock_arcanum_rules.json. - Blocks YouTube, Reddit, Twitter/X, TikTok, and social media during writing hours (09:00–13:00 and 14:00–17:00).
- Procedural Ambient Focus:
- Run
arcanum ambient rain --htmlorarcanum ambient hearthfor procedural synthesized sound masking during deep drafting sprints.
- Run
- OS Notification Muting:
- Click the Notification Bell icon in the Linux Mint panel and toggle Do Not Disturb.
- See XFCE DND Guide for custom keyboard shortcut setup.
- Multi-Tier Git Version History:
- Every Universe, World, and individual Book manuscript has dedicated Git version control.
- Obsidian Git automatically commits changes every 10 minutes and on manual saves.
- Click Save Snapshot (
arcanum snapshot) anytime to create milestone commits.
- Dual-Target Standalone Archive Backups:
- Configure external backup target with
arcanum backup-dest set /media/usb/backupsor via Control Center. - Run
arcanum backup <project>to create timestamped.tar.gzarchives with SHA-256 verification checksums stored simultaneously in local05-Backups/and replicated to external media. - Test full system recovery with
arcanum restore.
- Configure external backup target with
- Full-Disk Encryption & Automated External Backups:
- During Linux Mint installation, tick "Encrypt the new Linux Mint installation" (LUKS).
- Use Déjà Dup for automated offsite/USB backups (see Déjà Dup Backup Guide).
- Author's Field Manual — Visual plain-English handbook for novel writing, worldbuilding, and publishing.
- Technical Architecture & ADRs — System blueprint, technical deep-dives, exit codes, and Architectural Decision Records (ADR-001 through ADR-035).
- Software Catalog & Download Links — Exact packages, Flatpak IDs, ISOs, and commands.
- Optional Extras Guide — Azgaar maps, Krita, Inkscape, Gramps, PolyGlot, Sigil, Kiwix, and native standard library tools.
- Typography & Fonts Guide — Free literary typefaces (Linux Libertine, EB Garamond, Alegreya), DOCX styling presets, and Typst formatting rules.
- Obsidian Plugin Suite Guide — Pre-configured Obsidian writing and worldbuilding suite with Metadata Menu schemas.
- Distraction Control Guide — XFCE notification muting and FocusWriter tips.
- Automated Backup Guide — 3-2-1 backup strategy with Déjà Dup and native dual-target replication.
- Typst Book Template — Reusable novel layout engine.
- Obsidian World Bible Index Dashboard — Dataview queries and lore hub.
- Roadmap & Milestones — Project charter, hardware baselines, milestones (M0–M28), and operational status.
| Doc | What it is |
|---|---|
| docs/AUTHOR_MANUAL.md | Comprehensive Author's Field Manual for daily writing, lore building, DOCX dual-sync, 18 craft engines, cartography, and publication |
| docs/ARCHITECTURE.md | Technical architecture, invariants, exit codes, and full ADR catalog (ADR-001 through ADR-035) |
| docs/ROADMAP.md | Project charter, milestones (M0–M28), hardware baseline, and real-time status queues |
| CHANGELOG.md | Notable changes: audit remediation series, separated architecture, multi-drafts, DOCX sync, 18 craft engines, preflight, corpus export, and cartography |
| CONTRIBUTING.md | How to contribute: ground rules, exit-code contract, quality gate, commit style, submission flow |
| SECURITY.md | Security scope, installer privilege surface disclosure, and private vulnerability reporting |
| PRIVACY.md | Privacy policy, offline data minimization, and zero telemetry guarantee |
| REFERENCES.md | Asset provenance, Creative Commons / FOSS attribution index, and licensing references |
| docs/SUPPORT_MATRIX.md | Supported Linux distributions, desktop environments, architectures, and display servers |
| docs/COMPATIBILITY.md | Toolchain version baselines, SHA-256 binary digests, and Flatpak application IDs |
| scripts/verify.sh | 7-stage automated health check: syntax, schema validation, Universe/World lifecycle, Git snapshots, and backup/restore drills |