fantasia-archive

Runs and extends Fantasia Archive tests: Vitest unit tests vs Playwright component and E2E tests, including rebuild-before-Playwright rules and file naming. Use when writing tests, debugging CI, or when the user mentions Vitest, Playwright, component tests, or e2e.

Per-tab editState on opened workspace documents: preview (read-only) vs edit (inputs). Use when adding DocumentWorkspacePage fields, tab session state, or opened_documents snapshot columns.

Maintains the English in-app changelog at i18n/en-US/documents/changeLog.md in strict sync with package.json version, without any automatic version bumping. Changelog text must be user- or release-relevant only—never internal QA, Git meta (commits/pushes), or “updated changelog”. Prefer editing the log in the same commit as the work, before push. Use after substantive app, UX, or user-facing docs changes, or when the user asks for release notes.

Default post-edit verification for Fantasia Archive agents: ESLint on touched paths, full vue-tsc, stylelint on touched styles, and yarn vitest run only on specs connected to the edit batch. Full yarn testbatch:verify is reserved for final cleanup, git commit, and explicit user requests. Use after substantive code edits before reporting work done.

Sets up and runs Fantasia Archive locally using Yarn, Node.js 22.22 or newer, and Quasar Electron mode. Use when installing dependencies, choosing dev vs production build commands, or when the user mentions environment setup, CLI, or first run.

Works on Fantasia Archive Electron main process: app lifecycle, window management, platform tweaks, native integrations, and ipcMain registration (register*Ipc + electron-ipc-bridge channel names). Use when editing electron-main.ts, src-electron/mainScripts/, or main-side tests.

Extends or fixes renderer-facing Electron APIs exposed through the preload script and contextBridge. Use when adding IPC-like surface area, typing window.faContentBridgeAPIs, editing src-electron/contentBridgeAPIs, or extending shared IPC channel names in electron-ipc-bridge.ts.

End-of-batch ship workflow for Fantasia Archive: run full yarn testbatch:verify (not dev scoped gate), fix failures, sync README/AGENTS/rules/skills from Git changes, update in-app changelog, split conventional commits, and git push. Use when the user says final cleanup, doing final cleanup, run final cleanup, wrap up and ship, or similar end-of-session handoff language.

Collapses .faproject SQLite PRAGMA user_version ladders into a single bootstrap schema (currently version 1) during pre-release dev resets. Use when the user asks to flatten database schemas, reset migrations, or squash schema versions before wider release.

Reusable FaIconPickerInput element and src/scripts/faIcons catalogs: merged MDI / Font Awesome / Material icon grid, lazy load, search, and q-icon name storage. Use when adding icon fields, regenerating icon catalogs, or wiring the picker into dialogs and forms.

Builds Vue 3 + Quasar UI for Fantasia Archive: layouts, pages, router, Pinia, and boot files. Use when editing .vue files, Quasar components, routes, or stores under src/.

Produces production Electron builds for Fantasia Archive with electron- builder and Quasar. Use when changing build scripts, packaging, or publish flags, or when the user asks how to ship the desktop app.

Migrates Fantasia Archive features to two-level functions + managers layout: pure scripts/functions/, *_manager.ts wiring (underscore suffix, e.g. dialogFoo_manager.ts), thin Vue SFCs. Use when refactoring features, fixing fa-two-level ESLint violations, or adding new UI.

YAGNI and minimal diffs inside Fantasia mandatory structure: reuse ladder, no unrequested features or deps, shortest change that passes gates. Apply when scoping work, reviewing bloat, or choosing reuse vs greenfield.

Splits working tree changes into logical Git commits with conventional messages (feat, fix, test, chore, refactor, style, docs). Proposes commits one at a time and waits for explicit user approval before each git commit. Use when the user asks to commit, split commits, stage by topic, or use conventional / semantic commit messages.

Creates and updates local plan documents in .cursor/plans with required timestamp and package version metadata in both file body and filename. Before saving a new plan, deletes existing plan files whose last modified time is more than 30 days old.

Designs SQLite usage in Fantasia Archive’s Electron main process: file locations under userData, native better-sqlite3 module constraints, and migrations. Use when editing electron-main database code, schema, or persistence paths.

List and table drag-and-drop policy for Fantasia Archive: vue-draggable-plus for QList and flat lists; quasar-ui-q-draggable-table (v-draggable-table) for QTable row reorder; @he-tree/vue Draggable for trees. Use when adding reorder UX to settings lists, worlds, tables, or documenting DnD dependencies.

In-renderer floating Window* surfaces: Teleport to body, useFaFloatingWindowFrame, per-edge viewport margins, resize geometry and clamp, z-index band 5000–5999, Vitest teleport stub, custom fa-floatingWindowPop open/close transition. Use when adding or changing Window* components, frame behavior, or src/scripts/floatingWindows helpers.

Hierarchical tree UI with @he-tree/vue only — full project replacement for Quasar QTree (forbidden). Virtualization, drag-and-drop, Quasar slot styling. Use when adding or changing any nested tree in the renderer.

FaLocaleTranslationsInput element and per-locale string maps for Project Settings world names, document template titles, world appendix, layout group names, and placement nicknames. Use when wiring translation fields, snapshot JSON columns, or migrating display strings to translation maps.

Global keyboard shortcuts (faKeybinds): renderer matching, Pinia store, main-process persistence over IPC, and Keybind settings UI. Use when adding or changing app-wide shortcuts, capture validation, or bridge APIs for keybind storage.

Centralized renderer action manager: registry, sync FIFO queue, fire-and-forget async dispatch, unified error reporting (single console row + single toast), session-only action history, and the DialogActionMonitor surface. Use when adding or migrating user-meaningful UI actions, when a save/dialog needs consistent failure surfacing, or when working on the in-app action monitor.

Manages vue-i18n messages and locale structure for Fantasia Archive. Use when adding or changing user-facing strings, locale files under repo-root i18n/, or markdown-backed documents wired into i18n.

Implements or edits markdown-backed dialogs using Quasar QMarkdown and i18n- sourced document strings. Use when changing DialogMarkdownDocument, help docs, or changelog/license content shown in-app.

Use the neverthrow Result / ResultAsync pattern instead of try/catch for recoverable failures. Apply when touching error paths, IPC wrappers, parsers, or refactors around thrown errors.

Document template custom fields: field definitions, document values, merge-at-read, orphan retention, and template editor flows. Use when designing or implementing template fields, document forms, related SQLite schema, or projectContent IPC.

Aligns AI suggestions with Fantasia Archive as a worldbuilding database manager: projects, documents, and in-app concepts. Use when designing UX, data models, menus, or copy that should match the product purpose.

Compress natural language memory files (CLAUDE.md, todos, preferences) into caveman format to save input tokens. Preserves all technical substance, code, URLs, and structure. Compressed version overwrites the original file. Human-readable backup saved as FILE.original.md. Trigger: /caveman-compress FILEPATH or "compress memory file"

Ultra-compressed communication mode. Cuts token usage ~75% by speaking like caveman while keeping full technical accuracy. Supports intensity levels: lite, full (default), ultra, wenyan-lite, wenyan-full, wenyan-ultra. Use when user says "caveman mode", "talk like caveman", "use caveman", "less tokens", "be brief", or invokes /caveman. Also auto-triggers when token efficiency is requested.