# Codex Cryptica - User Guide & Features This file contains an amalgamation of the user-facing help documentation and core features of Codex Cryptica. ## Core Features ### AI Oracle Chat with the AI about your world. Ask questions, brainstorm ideas, or get help writing descriptions directly from your notes. Use the system proxy for free access, or add your own API key for direct connection. ### Oracle Connection Modes The Oracle works in two modes: System Proxy (free, uses shared access) or Custom API Key (direct connection to Google Gemini). The status badge in the Oracle sidebar shows which mode is active. ### Visual Graph Navigate your lore through a dynamic, interactive web. Nodes grow visually larger as visible links accumulate around them, making major lore hubs easy to identify at a glance. ### World Front Page Use the briefing field to edit the world blurb directly. If it is empty, the Generate Briefing button appears inside the field; if it already has text, the generate action moves to the bottom next to Save Briefing. Tagged `frontpage` entities stay pinned at the top of recent entities and show their chronicle/body preview there. ### Load and Save Folders Use the linked folder as an external copy of your world. Save writes your internal archive to the folder for backups or editing in tools like Obsidian. Load pulls folder changes back into the app when you want to bring them in. ### Search Indexing Search builds quietly in the background when a large vault opens. Early results may be incomplete while indexing is still running. If indexing fails, use Retry indexing to rebuild the local search index for the current vault. ### Save to Folder The 'SAVE TO FOLDER' button writes your internal work to the linked folder. It only enables when you have unsaved changes, keeping the folder copy current. ### Load from Folder Use 'LOAD FROM FOLDER' in the Vault Selector to refresh your internal archive with changes from the linked folder. A safety gate warns you if unsaved internal work would be overwritten. ### Total Privacy Your notes stay on your device. We use local storage for maximum security with no cloud accounts required. ### Linking Notes Connect people and locations. Click one item then another to link them together, or right-click two selected items to connect them. ### AI Generated Art Save art made by the Artificial Intelligence (AI). You can drag any image created by the AI onto an entry to save it as their portrait. ### AI Suggestions The AI finds new links in your notes and suggests connections you might have missed. ### Multi-Selection Actions Use the toolbar to quickly Apply Labels to multiple items or Merge duplicates into a single entry. ### Hide Secrets Keep secrets hidden. Hide items from your map so players don't see them during a session. Press `P` to toggle the preview. ### Switching Stories Change your world. Click the folder name at the top to switch to a different story. ### Pick Dates Select dates seamlessly using smooth, center-snapping scroll wheels. Features side-by-side vertical tracks, intercalary anchors, inline repair warnings on calendar change, and quick keyboard year/day overrides. ### Smart Importing Safe file loading. If a file import stops, just pick the file again to finish where you left off. ### Themes Instantly transform the look and feel of your workspace. Choose from a variety of distinct visual themes—from Ancient Parchment to Sci-Fi Terminal—to perfectly match the genre of your story. ### Instant Visualization For Advanced Tier users: Instantly generate visuals for your lore. Look for the DRAW button on Oracle responses, entity panels, Zen mode, and graph nodes. The AI uses Art Direction from normal notes or entities, then Category Defaults and the active Default Art Style. ### Demo Mode Explore the tool with pre-loaded sample data. Any changes you make are transient. Click 'Save as World' in Settings or the Oracle to keep your work. ### AI Disabled Prefer a non-AI experience? Enable AI Disabled in Settings to disable all AI-powered features. The Oracle remains available for utility commands like /roll, /create, /connect and /merge. ### SEO Prerendering Our marketing and legal pages are pre-baked as static HTML for instant loading and perfect search engine indexing, while your data remains private and client-side. ### Map Mode Plot your world data onto custom geographic or tactical canvases with persistent pins and Fog of War. ### VTT Mode Turn the map into a lightweight tactical board. Add tokens, move them with grid snapping, manage initiative, measure distances, and save encounters without changing the underlying map. ### VTT Entity List Open Vault Entities in the VTT sidebar to search your world notes, then drag characters, creatures, or items straight onto the map to create tokens. A ghost marker follows your cursor so placement stays precise. ### Spatial Canvas Design custom layouts like conspiracy boards or quest flowcharts. Drag entities onto the infinite board, draw visual links with custom themed labels, and navigate via name-based URL slugs. Includes a theme-aware MiniMap for seamless navigation. ### The Archive Visit our blog for deep dives into data sovereignty and tactical world-building guides. Check out our Comprehensive Help Guide for a full system manual. ### Die Roller Perform polyhedral dice rolls via the /roll command in Oracle chat or using the dedicated Die Roller modal. Click dice icons in quick succession to roll multiple dice at once, and use the reroll button to instantly repeat any previous roll. ### Entity Explorer Quickly browse and filter all your world entities via the persistent sidebar. Search by title, labels, or alternative names (aliases). Switch between List and Label views to group entities by their labels. Click label pills to filter the explorer, or use Ctrl/Cmd+Click to combine multiple labels for a focused drill-down. ### Navigation Hub Access your core tools (Oracle, Explorer) via the Activity Bar on the leftmost edge. Tools remain persistent as you switch between Graph, Map, and Canvas views. ### Proactive Discovery While you chat, the Oracle can identify new characters, locations, and items. In Settings, choose whether discoveries are off, shown as chips for review, or saved automatically as drafts. ### Oracle Automation Entity Discovery controls record creation. Connection Discovery controls graph links. Keep connections on Suggest if you want proposed edges reviewed before they appear on the graph. ### Adjustable Sidebars Dynamically resize the left and right sidebars to suit your workspace needs. Hover over the inner edge of a sidebar and drag left or right. Your custom widths are automatically saved across sessions. ### Reviewing Drafts Entities created via Auto-Archive appear as 'Drafts'. Find them in the Review tab of the Entity Explorer or as semi-transparent 'Ghost' nodes on the graph canvas. Click Verify to make them permanent. ### AI Description Regeneration Instantly generate or refine entity descriptions. The AI produces both a player-facing 'Chronicle' and a GM-facing 'Lore' entry based on your existing notes, tags, and connections. Review and save changes directly within the entity detail view. ### P2P Connection Manager Seamlessly establish peer-to-peer connections between campaign hosts and trusted guests. Features an active heartbeat monitor to maintain connection stability, measure round-trip latency, and support automatic reconnection backoffs during brief signal drops. ### QuickNote Fast Scratchpad Capture fleeting ideas instantly. Press Ctrl+I or Cmd+I from anywhere to toggle the glassmorphic fast scratchpad. Jot down thoughts, auto-save drafts, and use the 'Elevate' button to let the AI structure your raw notes into complete Character, Location, or Item draft entities. ### Nested Entities Organize your world hierarchically. Drag and drop entities in the explorer to nest them under parents (e.g. putting a tavern inside a city). Expand/collapse nodes using the chevron. When you delete a parent, its children are promoted to the root level. Cycle detection prevents recursive loop errors. ## Help Documentation ### GETTING STARTED Codex Cryptica is designed to give you **absolute sovereignty** over your lore. Everything you write is saved as a Markdown file in your local vault. ### Core Concepts - **Entities**: The building blocks of your world (NPCs, Locations, Items). - **Chronicles**: The main text content of an entity. - **Lore**: Hidden attributes and meta-data used by the Oracle for context. --- ### KNOWLEDGE GRAPH The graph is your primary way to navigate. ### Shortcuts - `C`: Toggle manual Connect Mode (click source then target). - `L`: Toggle Node Labels. - `Scroll`: Zoom in/out. - `Drag`: Pan the view. - `Click Node`: Focus entity and open detail panel. ### Toolbar Controls The bottom-left toolbar provides quick access to layout and visibility: - **Minimap**: Toggle the overview map. - **Timeline**: Toggle chronological layout. - **Zoom**: Adjust view scale. - **Stable Layout (Pin)**: Prevent nodes from moving automatically. - **Link (Chain icon)**: Quickly connect two selected nodes. - **Redraw (Refresh)**: Recalculate node positions. --- ### MAP MODE **Map Mode** transitions Codex Cryptica from a document-heavy manager to a visual, spatial experience. You can plot your campaign data onto custom geographic or tactical canvases. ### Getting Started 1. Click the **MAP** tab in the top navigation bar. 2. If no map exists, click **Upload World Image** to select a JPG or PNG from your device. 3. Once uploaded, use your **Mouse Wheel** to zoom and **Click-Drag** to pan. ### Placing Lore Pins Connect your geography directly to your notes: - **Double-Click** anywhere on the map to create a new pin. - **Drag an entity** from the **Entity Explorer** sidebar and drop it anywhere on the map to instantly create a pin linked to that entity. - Use the **Link Lore** search box on a pin to connect it to an existing NPC, Location, or Item. - **Click a Pin** to instantly open its associated chronicle in the side panel. ### Fog of War (GM Only) Manage mystery and player progression: 1. Toggle **GM MODE** in the bottom control bar. 2. Ensure **FOG** is toggled ON. 3. Hold the **Alt Key** and **Click-Drag** to "paint away" the fog and reveal areas of the map. 4. Reveals are persistent and will be saved to your vault. ### Hierarchical Maps Dive deeper into your world: - You can attach specific sub-maps to entities (e.g., a "Tavern" note can have its own floor plan). - In the **Entity Detail Panel**, go to the **MAP** tab to upload a sub-map. - Once attached, pins linked to that entity will show an **ENTER** button, allowing you to dive into the sub-map. - Use the breadcrumbs or "Go Back" logic to return to the parent map. --- ### SPATIAL CANVAS The **Spatial Canvas** is a free-form workspace that emphasizes **Spatial Intentionality**. Unlike the automated Knowledge Graph, every node position and connection here is manually placed and preserved. ### Core Features - **Infinite Workspace**: Pan and zoom across an unlimited board to organize your narrative. - **Persistent Layouts**: Your card coordinates and custom links are saved directly to `.canvas` files in your vault. - **Themed Components**: The **MiniMap** and all UI elements adapt to your active theme (Fantasy, Sci-Fi, etc.), ensuring a cohesive aesthetic. - **Readable URLs**: Each canvas uses a name-based **slug** in its URL (e.g., `/canvas/battle-at-the-docks`), making it easy to bookmark and identify specific workspaces. ### Adding Entities The fastest way to populate a canvas is to drag entities directly from the **Entity Explorer** sidebar onto the board. Open the Explorer, find the entity you want, and drag it onto the canvas — it will be placed wherever you drop it. You can also right-click nodes in the **Knowledge Graph** and use **Add to Canvas** to send one or more entities to any of your boards without leaving the graph. ### Managing Canvases Click the **workspace name** in the top-left HUD to open the **Canvas Manager**. From there you can create new canvases, rename or delete existing ones, and switch between boards. ### Managing Connections - **Custom Labels**: Double-click any connection (edge) to open a themed modal and enter a name for the relationship. - **Hidden Labels**: To hide a label, simply clear the text in the modal. Empty labels are not rendered, keeping your canvas clean. - **Visual Links**: Create lines between any two entities to map out conspiracy boards, family trees, or quest flowcharts. ### Tips for Organization 1. **Use Multiple Canvases**: Create separate boards for different regions, plot lines, or character groups to avoid clutter. 2. **Drag from Explorer**: Open the Entity Explorer sidebar and drag lore directly onto the board for the fastest workflow. 3. **Zen Integration**: Double-click any entity card to open it in **Zen Mode** (the full detail panel) for quick editing. --- ### ADDING ENTITIES TO CANVAS You can quickly bring your lore onto a **Spatial Canvas** in several ways — by dragging from the sidebar, right-clicking in the graph, or choosing from search results. ### Drag from Entity Explorer The fastest way to add a single entity is to drag it directly from the **Entity Explorer** sidebar onto the canvas. 1. **Open the Explorer**: Click the Explorer icon in the left activity bar. 2. **Find your entity**: Use the search bar or browse the list. 3. **Drag onto the canvas**: Click and drag the entity card onto the board. It will be placed wherever you drop it. ### Right-Click to Add The most direct way to add entities to a canvas is via the **Context Menu** on the Knowledge Graph. 1. **Select Entities**: Click on a single node, or hold `Shift` and click to select multiple nodes. 2. **Right-Click**: Open the context menu on any of the selected entities. 3. **Add to Canvas**: Hover over "Add to Canvas" to see a list of your most recently accessed boards. 4. **Select a Canvas**: Click a canvas name to instantly add all selected entities to that board. ### Creating New Canvases If you have a group of entities that need a new home, you can create a canvas directly from your selection. - In the "Add to Canvas" submenu, select **+ New Canvas**. - Enter a name for your new board. - The new canvas will be created and all selected entities will be automatically added to it. ### Smart Duplicate Detection Don't worry about adding the same entity twice. The system automatically detects if an entity is already present on your chosen canvas: - **New Entities**: Added to the center of the canvas. - **Duplicates**: Automatically skipped to keep your layout clean. - **Feedback**: A toast notification will summarize how many items were added and how many were skipped. ### Finding Other Canvases If the canvas you need isn't in the "Recents" list, select **Choose Canvas...** to open a searchable modal containing every board in your vault. --- ### THE LORE ORACLE The Oracle is powered by **Google Gemini**. It doesn't just 'chat'; it retrieves relevant lore from your graph to provide context-aware answers. ### Features - **Context Fusion**: Combines visible chronicles and hidden lore. - **Image Generation**: Type `/draw [description]` to visualize your world. - **Instant Visualization**: Advanced Tier users will see a "DRAW VISUAL" button on Oracle responses and empty Entity profiles to quickly generate images based on lore. --- ### ACQUIRING A GEMINI API KEY Codex Cryptica uses Google Gemini to power the Lore Oracle. Follow these steps to get a free key: 1. **Visit Google AI Studio**: Go to [aistudio.google.com](https://aistudio.google.com/app/apikey). 2. **Sign In**: Use your standard Google Account. 3. **Create API Key**: Click on 'Get API key' in the sidebar, then click 'Create API key in new project'. 4. **Copy & Paste**: Copy the generated key and paste it into the **Intelligence** tab in Settings. ### Why do I need this? Using your own key ensures higher availability, faster response times, and access to the 'Advanced' tier for complex world-building tasks. --- ### CHAT COMMANDS The Lore Oracle supports several interactive commands to help you manage your world. To discover available commands, simply type a forward slash (`/`) in the chat input. ### Available Commands - `/draw [subject]`: Triggers the AI to generate a visual representation of the subject. Category words such as `character`, `location`, or `item` can guide composition when no matching entity category is available. - `/create [description]`: Ask the Oracle to draft a new entity record based on your description. - `/connect`: The primary tool for building relationships. - `/merge`: Combine two entities into one, synthesizing their lore and re-mapping all connections. ## Efficient Linking with /connect The `/connect` command is designed for high-speed world building. You can use the **Tab** key to navigate through a structured sequence without leaving your keyboard. ### The Tab Sequence 1. Type `/con` and press **Enter** or **Tab** to start the command. 2. **From**: Start typing the first entity name. Select a suggestion with **Tab**. 3. **Relationship**: Type the connection label (e.g., `is the mentor of`) or pick a suggested one, then press **Tab**. 4. **To**: Type the second entity name and select it with **Tab** or **Enter**. ### Direct Commands (Instant) For power users, you can create connections instantly by wrapping entity names in quotes. This bypasses the AI parser for zero-latency execution: `/connect "Eldrin" is the mentor of "Kaelen"` ## Merging Entities with /merge The `/merge` command allows you to consolidate duplicate entries or combine related notes into a single cohesive record. ### Direct Merge You can trigger an immediate merge by specifying the source and target: `/merge "Old Notes" into "Kingdom of Aethel"` The "Source" (Old Notes) will be deleted, and its content will be appended to the "Target" (Kingdom of Aethel). All inbound and outbound connections will be automatically updated to point to the Target. ### Guided Merge Wizard Type `/merge oracle` to open the interactive **Merge Wizard**. This tool provides: - **Entity Selection**: Guided lookup for source and target. - **Merge Strategy**: Choose between simple **Concatenation** or **AI Synthesis** (where the Oracle rewrites the combined content into a single cohesive narrative). - **Preview**: View the resulting content before finalizing the merge. ## Guided Oracle Assistance If you are unsure how two entities should be related or how they should be combined, add `oracle` to your command: - `/connect oracle`: Analyzes lore to propose thematic relationship types. - `/merge oracle`: Opens the step-by-step consolidation wizard with content preview. ## Art Direction Image generation uses Art Direction from your world before falling back to shipped Category Defaults, Default Art Style from the active theme, and the global Codex Cryptica default. To customize it, add normal notes or entity sections titled `Art Direction`, `Default Art Style`, or `Visual Direction`; no separate settings form is required. --- ### IMPORTING NOTES Codex Cryptica can transform your unstructured notes into a structured Knowledge Graph using the Lore Oracle. ## How it Works 1. **Upload**: Drag and drop your `.txt`, `.docx`, or `.json` files. 2. **Analysis**: The Oracle breaks your documents into chunks and analyzes them to find characters, locations, and items. 3. **Review**: You review the discovered entities and their relationships before adding them to your vault. ## Dedicated Importer For uninterrupted world-building, clicking **IMPORT** in the top menu or the Entity Palette opens a dedicated, distraction-free popout window. - **Seamless Sync**: Any entities you import or review in this popup are instantly saved and synchronized back to your main graph in real-time. No manual refresh required! ## Resilient Imports Large documents can take time to process. The system automatically tracks your progress: - **Automatic Resume**: If you close the app or lose connection, re-selecting the same file will resume exactly where you left off. - **Content-Aware**: We use unique file fingerprints (hashes) to remember progress even if you rename your files. - **Visual Tracking**: The segmented progress bar shows you exactly which parts of your file have been analyzed, skipped, or are currently active. ## Manual Restart If you want to re-analyze a file from scratch, click the **Restart** button in the import dialog to clear its saved progress. --- ### RELATIONSHIP LABELS Not every connection is the same. You can add labels to the lines in your graph to show _how_ people or places are related. ### How to Add Labels You can add labels using two methods: #### 1. The Link Button (Recommended) 1. **Select Two Nodes**: Click one node, then `Shift + Click` or `Cmd/Ctrl + Click` another. 2. **Click Link**: Click the **Chain icon** in the bottom-left toolbar. 3. **Type the Label**: Enter the relationship name in the box that appears. #### 2. Manual Connect Mode 1. **Toggle Mode**: Press `C` on your keyboard. 2. **Click Nodes**: Click the first node, then the second. 3. **Type the Label**: Enter the relationship name. ### Tips for Labels - **Common Labels**: Use "Enemy," "Child of," or "Home Town" for consistency. - **Hide Labels**: If your graph gets too cluttered, press `L` to hide the text on the lines. ### AI Context The Lore Oracle understands these labels. If you label someone as a "Rival," the AI will remember that conflict when you ask for plot ideas! --- ### MERGING NODES Sometimes duplicate entities appear, especially after importing content. The **Merge Nodes** feature allows you to combine them into a single, definitive record. ### How to Merge 1. **Select Nodes**: Hold `Shift` or `Ctrl` and click multiple nodes in the Graph View. 2. **Right-Click**: Open the context menu on one of the selected nodes. 3. **Select 'Merge Nodes'**: This opens the merge dialog. ### Merge Strategies - **Concatenate**: Simply appends the content of all source nodes into the target node. - **AI Merge**: Uses the Oracle (Gemini) to intelligently rewrite and summarize the combined lore into a cohesive entry. **Warning**: The source nodes will be permanently deleted after merging. The target node will be updated. --- ### CUSTOM CHRONOLOGY Codex Cryptica allows you to define the very structure of time for your campaign world. Gone are the days of manual math or being forced into a standard Earth calendar. ## The Date Picker When editing an entity's temporal data (Date, Start Date, or End Date), you will use the dynamic **Scroll-Wheel Date Picker**. ### Center-Aligned Scroll Wheels The date picker uses a smooth, vertical, center-aligned scroll wheel interface designed for both desktop mouse-wheel and mobile touch interactions: 1. **Center Snapping**: Wheels automatically snap center-aligned options into place. A highlight lens guides your visual focus. 2. **Synchronized Preview**: Below the wheels, a live, full-text preview renders the exact formatted date so you are always clear on your selection, even when dealing with truncated long names. 3. **Direct Jump Override**: Need to select a year far in the past or future? Simply click the keyboard icon in any column to directly type a numeric override. ### Precision Levels & Intercalary Anchors The picker allows you to choose your granularity using the toggle at the top: - **Year**: For broad historical events. - **Month/Unit**: For seasonal occurrences. - **Day**: For specific, high-precision moments. - **Anchor**: For special intercalary days (e.g., Midyear festivals) that sit outside standard months. ### Conflict Auto-Repair If you change your campaign calendar structure after saving dates, opening the picker automatically triggers an **inline repair warning**. You can view the discrepancy and click **Confirm Repair** to cleanly align the date to the new calendar constraints without silent, accidental data loss. ## Campaign Calendars In the **Vault Settings**, you can fully customize your world's calendar: 1. **Standard Gregorian**: Keep this enabled to use the standard 12-month calendar. 2. **Custom Months**: Disable Gregorian mode to define your own months. You can rename them (e.g., "Hammer", "Alturiak") and set custom lengths. 3. **Epoch Suffixes**: Add suffixes like "AF" (After Fall) or "BCE" to your years for immersion. 4. **Present Year**: Set a "Present" marker to anchor your narrative timeline. ## Linear Time Mapping Regardless of how many months or days you define, the Knowledge Graph automatically calculates a linear value for each date. This ensures that even the most complex custom calendars are visualized correctly on the **World Timeline**. --- ### QUICKNOTES & FAST SCRATCHPAD The **QuickNote Scratchpad** is designed to let you write down sudden brainstorms or game session observations immediately, without needing to navigate away from your active view or create formal wiki entries first. ### Key Features - **Global Hotkey Toggle**: Press `Ctrl+I` (or `Cmd+I` on macOS) from anywhere in the app to slide open the glassmorphic QuickNote overlay. - **Debounced Auto-Save**: Just start typing. Every keystroke is saved locally to your device's IndexedDB with under 150ms activation latency. - **Floating Action Bubble (FAB)**: A glowing, interactive bubble sits in the bottom-right corner of your screen when active notes are present, pulsing to remind you of pending drafts. - **glowing Counter Badges**: High-visibility orange badges on the leftmost Activity Bar `[⚡]` and compact draft pills in the Campaign Header count your active QuickNotes. ### Visual Brainstorming Integration Your active, un-elevated QuickNotes aren't just hidden away in the scratchpad—they are seamlessly integrated into your visual tools: - **Interactive Graph Nodes**: QuickNotes appear directly on your Cytoscape Knowledge Graph as **golden-amber dotted clickable nodes**. - **Interactive Click & Double-Tap**: Clicking or double-tapping a QuickNote node on the graph canvas instantly opens the scratchpad focused on that note, avoiding any default mode interruptions. - **Unified Global Search**: Your QuickNotes are searched alongside your wiki entities. Typing a keyword into the global search bar will instantly return matching notes, which open directly in the scratchpad editor when clicked. ### AI Entity Elevation When you're ready to turn a fleeting draft into a formal wiki article, let the Lore Oracle do the heavy lifting: 1. Click **Elevate** (or the magic wand icon) in the QuickNote editor. 2. The AI reads your raw draft, retrieves semantic context from your vault, and structures the note into a rich draft entity (determining `Name`, `Type`, `Chronicle`, and `Lore`). 3. The newly generated draft is loaded into your sidebar review panel, complete with a `discoverySource` back-link referencing your original QuickNote. 4. When you click **Verify/Approve** on the Svelte sidebar draft banner, the original QuickNote is automatically archived, keeping your scratchpad perfectly clean. --- ### FOG OF WAR The **Fog of War** system lets you track what your players have discovered. You can hide nodes on the graph so they don't see spoilers during a session. ### Visibility States - **Revealed**: Everyone can see this node and its links. - **Hidden**: Only you (the GM) can see this entry in the list, but it's gone from the graph. - **Rumor (Link Only)**: A "ghost" node that appears when an entry is mentioned but not yet fully discovered. ### How to Reveal 1. **Right-Click**: Tap a node and look for the Visibility menu. 2. **Toggle Reveal**: Click to show or hide it from the graph. 3. **GM View**: Click the **Eye Icon** in the bottom controls (or press `P`) to see everything at once, regardless of Fog of War. --- ### CONNECTIONS PROPOSER The **Connections Proposer** works in the background to find hidden links between your entities. It uses the Lore Oracle to analyze your writing and suggest relationships you might have missed. ### How it Works 1. **Background Scan**: When you view an entity, the system silently checks for potential links to other records. 2. **Review**: Suggestions appear at the bottom of the detail panel. 3. **Apply**: Click the checkmark to create a real connection. 4. **Dismiss**: Click 'X' to ignore. Dismissed suggestions are saved in history just in case. --- ### MULTIPLE VAULTS Codex Cryptica lets you manage multiple "Vaults" (folders). Each vault is completely separate, so your sci-fi notes won't mix with your fantasy ones. ### How to Switch 1. **Vault Name**: Look at the top-left of the screen. 2. **Click Name**: This opens the Vault Switcher. 3. **Add or Switch**: You can jump to a vault you've used before or "Add Archive" to link a new folder. > [!NOTE] > Your AI API Key works for all vaults, but things like NPC categories and tags are unique to each campaign. --- ### THEMES Codex Cryptica allows you to shift the visual dimension of your workspace using **Themes**. These themes redefine the entire interface aesthetic to match your world's genre, using curated color palettes, custom typography, and atmospheric textures to ensure total immersion for lore keepers. ## Changing Themes You can switch between available templates at any time: 1. Open **Settings** (click the gear icon or press `S`). 2. Navigate to the **Theme** tab. 3. Select a theme from the **Themes** list. The changes will be applied instantly across the entire application, including the knowledge graph and all detail panels. ## Available Themes - **Ancient Parchment**: Our flagship fantasy theme, designed to feel like an enchanted magic tome with parchment textures and inked typography. - **Sci-Fi Terminal**: A high-contrast, neon-green terminal aesthetic for futuristic settings. - **Blood & Noir**: A dark, moody theme with crimson accents, ideal for horror or investigative campaigns. - **Neon Night**: A vibrant, cyberpunk-inspired palette with high-energy colors. - **Wasteland**: A rugged, textured theme for post-apocalyptic or industrial worlds. - **Clean Modern**: A minimalist, distraction-free aesthetic for general-purpose world-building. ## Persistence Your selected theme is saved to your local browser storage and will be automatically applied every time you return to the workspace. --- ### OFFLINE SUPPORT & SYNCHRONIZATION Codex Cryptica is designed as a **local-first** application. This means your data always lives on your device first, ensuring you can continue building your world even without an internet connection. ## Local Storage (OPFS) By default, all your campaign data is stored in the **Origin Private File System (OPFS)**. This is a high-performance, sandboxed area within your browser. - **Privacy:** Your data is not uploaded to our servers. - **Speed:** Reading and writing thousands of chronicles is near-instant. - **Persistence:** Your work is saved automatically as you type. ## Synchronization with Local Folders You can mirror your internal archives with any folder on your computer. This enables several powerful workflows: 1. **External Backups:** Keep a real-time copy of your world in a folder you control. 2. **External Editing:** Use your favorite Markdown editor (like Obsidian or VS Code) to edit your chronicles while Codex is closed. 3. **Cloud Mirroring:** By selecting a folder managed by a cloud provider (like Google Drive, Dropbox, or iCloud), you can achieve multi-device synchronization using your OS's built-in support. ### How to set up Cloud Sync (via OS) To sync your world across multiple devices using Google Drive or other providers: 1. Install the official client for your provider (e.g., [Google Drive for Desktop](https://www.google.com/drive/download/)). 2. In Codex Cryptica, go to **Settings > Vault**. 3. Under **Synchronization**, click **Sync to Folder**. 4. Select a folder within your local Google Drive/Cloud directory. 5. Codex will now mirror your files to that folder, and your OS will handle the background upload to the cloud. ## Managing Multiple Devices When you open Codex on a new device: 1. Create a new vault or open the **Vault Selector**. 2. Click **Open Folder**. 3. Select the cloud-synced folder you set up on your first device. 4. Codex will import your world and keep it in sync with the cloud mirror. --- ### GOOGLE DRIVE CLOUD SYNC Codex Cryptica can back up your vault to your personal Google Drive and restore it from any device. Your files go straight from your browser to your Drive — our servers never see them. ## Connect Your Vault 1. Open **Settings → Cloud Sync**. 2. Click **Connect Google Drive** and sign in when Google prompts you. 3. Codex creates a `CodexCryptica/` folder on your Drive (if it doesn't exist) and a subfolder named after your vault inside it. The folder ID is saved locally so future syncs know where to go. Once connected you'll see two buttons: - **Save to Drive** — pushes your local vault up to the cloud. - **Load from Drive** — pulls the cloud version back down. Only files that are newer than your local copy are downloaded, so a full re-pull stays fast. > [!NOTE] > Sync is always manual. Codex never uploads in the background without you clicking a button, so you stay in control of what leaves your device. ## Import a Vault from Drive If you have vaults already stored in your `CodexCryptica/` Drive folder (from another device), you can load them without setting them up from scratch: 1. In **Settings → Cloud Sync**, click **Browse Drive**. 2. Codex lists every vault subfolder it finds under `CodexCryptica/`. 3. Click **Load** next to any vault. Codex creates a local vault (or finds the existing one), then pulls only the files that are newer than what you have locally. ## Join a Shared Vault (Co-GM Flow) If your GM has shared their Drive vault folder with you, you can connect to it directly: 1. Ask your GM to share the Drive folder and copy the share link (it looks like `https://drive.google.com/drive/folders/…`). 2. In **Settings → Cloud Sync**, paste the link into the **Join a Shared Vault** field and click **Join**. 3. Google will ask you to grant read access to the shared folder. Once approved, Codex imports the vault locally and you can pull updates any time with **Load from Drive**. > [!NOTE] > The first join asks for broader Drive access so Codex can read folders you don't own. Normal push/pull to your own vaults uses the narrower `drive.file` scope and only accesses files Codex itself created. ## Disconnect Click **Disconnect** in the connected state to remove the Drive link from this vault. Your local vault and the files on Drive are both preserved — only the sync mapping is removed. --- ### VAULT STRUCTURE Codex Cryptica uses standard Markdown files. You can even open your vault folder in other apps like Obsidian or VS Code. ### File Format Each file has a simple "header" (called YAML frontmatter) followed by your writing: ```markdown --- id: unique-id type: npc tags: [noble, ally] status: alive --- # Character Name Your story starts here... ``` ### Tips for Advanced Users - **Metadata**: You can add your own fields to the header (like `age: 45`). The AI Oracle will see these and use them for extra context. - **Syncing**: Because these are just files, you can use any cloud service (Dropbox, OneDrive, etc.) to keep them synced across devices. --- ### WORLD FRONT PAGE The front page is the first thing you see when a vault opens. It gives you a world briefing, a quick way to jump to the graph or tools, and a space for recent activity cards. ### What You Can Do - Edit the world briefing directly from the page. - Upload a cover image, paste an image URL, or ask the Oracle to generate one. - Tag any markdown entity with `frontpage` to pin it to the top of recent entities and use its chronicle/body text in the card preview. - Use the navigation buttons to move into the Graph view, open the map, or open the canvas. ### Tips - Keep the briefing short and useful. You can always expand it later. - If you add more than one `frontpage` tag, the most recently edited entity wins. - Recent cards update automatically from the vault’s latest edits, and any `frontpage` entity stays pinned at the top. --- ### TERMINAL LANDING PAGE The Terminal Landing Page serves as the initial entry point for Codex Cryptica, designed to introduce users to the core operational protocols while maintaining a high-performance, SEO-friendly surface for search engines. ## Operational Protocols The landing page highlights several key "Protocols" that define the application: - **Local-First Architecture**: Your data is stored in the Origin Private File System (OPFS) and remains strictly on your local machine. - **Privacy-Centric Intelligence**: All AI processing via the Oracle respects your privacy and data sovereignty. - **Zero-Cloud Dependency**: The core application functions entirely without external cloud requirements, ensuring 100% offline availability. ## Navigating the Terminal - **Enter Workspace**: Click this button to transition from the public landing page into your private workspace. - **Hide Welcome Screen**: You can choose to skip the landing page on future visits by checking this box on the terminal or toggling it in **Settings > Theme**. - **Features Index**: Visit `/features` at any time for a deep dive into the technical specifications and capabilities of the system. ## Performance & SEO The landing page is optimized for near-instant load times (LCP < 1.2s) and provides crawlable metadata for search engines, ensuring that Codex Cryptica remains discoverable while your private notes stay hidden. --- ### THE ARCHIVE (BLOG) Explore the official **Codex Cryptica Blog**, also known as **The Archive**. Here you will find deep dives into: - **Local-First Architecture**: Why your lore belongs to you, not the cloud. - **Tactical World-Building**: Tips for mastering the spatial brain. - **Data Sovereignty**: How to use modern tools without sacrificing privacy. You can access the blog at any time by visiting [/blog](/blog). Read our latest dispatch: **The GM’s Guide to Data Sovereignty**. ---