Welcome to Fables — a personal Knowledge OS fused with an interactive fiction engine. This documentation hub guides you through using, building with, and deploying Fables.
Start here if you're new to Fables.
- Getting Started — Installation, first note, and the five-minute tour.
- Tailscale Setup — How to serve Fables over your tailnet and access it from iPhone.
- Troubleshooting — Common issues and solutions.
Learn to write interactive fiction in the Forge language.
- Forge Language Tutorial — Zero to your first story in ten steps. Start here.
- Forge Language Spec — Complete language reference: scenes, choices, variables, diverts, knowledge bindings, and all syntax.
- Forge Conformance Checklist — Comprehensive feature matrix and grammar (for implementers and spec readers).
Learn to build and explore your personal Knowledge OS.
- Fusion Cookbook — Ten recipes for blending notes with stories: entity cards, journal effects, world state, codex reveals, and more.
Deploy and maintain Fables on your infrastructure.
- Security & Privacy — Threat model, what data lives where, encryption, and best practices. Read this before deploying.
- Tailscale Integration — Complete setup: serve over your tailnet with HTTPS, install the PWA on iPhone.
- Disaster Recovery Runbook — Backup restoration and data recovery procedures.
- Rollback Runbook — How to revert to a previous version safely.
- Troubleshooting — Debug logs, sync health, common problems.
Understand Fables' architecture and contribute to the codebase.
- Architecture — System overview: monorepo structure, data model, server and web app, offline-first sync, fusion layer. Read this first.
- Plugin Architecture Concepts — The Fables plugin system design (Tier 2). What plugins are, how they work, the security model, and what they can do.
- Real-Time Collaboration Concepts — Fables collaboration design (Tier 2): CRDTs and Yjs, shared editing, WebSocket rooms, presence, comments, and how it fits the local-first model.
- v1.0 Announcement — What Fables is and why it exists.
Automate, query, and maintain a large vault.
- Multi-Vault — Named vaults across data dirs, per-vault settings and encryption, templates, cold storage.
- FQL v2 — Aggregations, computed-field expressions, query variables, EXPLAIN, and a linter.
- Webhooks & Integrations — Outbound webhooks, token-auth inbound capture, RSS output, iOS Shortcuts recipe.
- Scripting Console — A script library scoped to the plugin capability surface, with static dry-run analysis.
- Bulk Operations — Preview → apply → undo across many notes: find/replace, merge, split, retag.
- Workspace Profiles — Named UI states, focus modes, per-device defaults, export/import.
- Power Tools — Vault statistics, duplicate finder, broken-everything finder, linter, storage analyzer.
- Design System Core — The OKLCH colour engine, seed-to-system theming, type scale, and spring/motion policy (Epic 21).
Follow the daily progress of Fables development.
- Day 1: Foundation & Monorepo
- Day 2: Notes Core
- Day 3: Linking, Graph & Queries
- Day 4: Forge DSL — Language & Compiler Front-End
- Day 5: Compiler Back-End & VM
- Day 6: Story Authoring & Player
- Day 7: The Fusion — Knowledge ↔ Story
- Day 8: Search & Intelligence
- Day 9: PWA, Offline, Sync & Tailscale
- Day 10: Hardening, Tests, Perf & Ship
- Tier 1 Retrospective — Lessons learned building 1,000 features in 10 days.
- Epic 11: Plugin & Extension Architecture — Sandboxed worker-thread plugins with capability model, SDK, and distribution pipeline.
- Epics 12–19 — Collaboration, encryption, AI, importers, audio, spaced repetition, and story distribution (see the
devlog/directory). - Epic 20: Multi-Vault, Automation & Power Tools — The power-user tier and the close of the 2,000-feature plan.
- The Fables Book — A narrative tour of the whole system.
- v1.0 Announcement — What Fables is and why it exists.
- v2.0 Announcement — Tier 2 complete, written as a fable.
- README — Main project overview and quickstart (in the root of the repo).
- FEATURES.md — Canonical feature checklist: Tier 1 (complete) and Tier 2 epics (in progress).
- CLAUDE.md — Instructions for Claude Code sessions building Fables.
Fables is your knowledge base on your machine, fused with an interactive fiction engine you own.
- Your notes are the world. Write markdown notes and organize them into notebooks, tags, and links. Fables learns relationships, suggests connections, and never locks your data.
- Your stories run on a compiler you own. Author interactive fiction in the Forge language (inspired by Ink). Compile to bytecode, play on your phone PWA, and let stories mutate your entities and journal.
- Offline-first, synced over Tailscale. Work on your Mac or Linux machine. Serve the web app over your tailnet to your iPhone via
tailscale serve. Edit offline, sync when you're back. No cloud required.
Last updated: June 15, 2026. This documentation describes Fables v2.0 (Tier 1 + Tier 2 complete; the 2,000-feature plan shipped through Epic 20, with Epic 21 polish).