Imported from ljwzz/VoxWeaver (AGENTS.md). Install upstream with npx skills add ljwzz/VoxWeaver. Copyright stays with the author.

Repository Guidelines

Project Structure & Module Organization

VoxWeaver is a pnpm monorepo. apps/desktop/ contains the Electron Forge application: main/ for the main process, preload/ for the bridge, and renderer/src/ for Vue pages, styles, and local assets. Shared TypeScript modules live in packages/: contracts defines cross-layer data contracts, application holds use cases and ports, and project-workspace manages project files. services/app-core/ coordinates application services and the SQLite project catalog. Keep tests beside their subjects as *.test.ts.

Documentation starts at README.md, then routes through docs/README.md to docs/spec/ and docs/ideas/. Do not edit generated content under apps/desktop/.vite/ or apps/desktop/out/.

Figma Design Reference

Use the remote Figma design as the visual and interaction reference for production pages. Implement production behavior from the specified contracts, IPC, and real application state; production code must not depend on mock data or fixtures.

Before delivery, verify the production page's behavior, regression coverage, and visual result against the applicable design and production route.

Build, Test, and Development Commands

Use Node v24.13.0 (.nvmrc) and the pnpm version declared in package.json.

• corepack pnpm install installs the locked workspace dependencies.
• corepack pnpm run dev starts Electron Forge with the Vite renderer;
• corepack pnpm run check runs ESLint, Stylelint, TypeScript checks, and all tests.
• corepack pnpm run package builds the local macOS arm64 application; make creates the distributable archive.
• corepack pnpm --filter @voxweaver/desktop test runs only desktop tests during iteration.

Coding Style & Naming Conventions

Use two-space indentation, LF endings, a final newline, single quotes, semicolons, and 1TBS braces. ESLint and Stylelint are authoritative; run corepack pnpm run lint:fix before submitting broad formatting changes. Vue SFCs use script, template, then style; component names are PascalCase. Follow existing camelCase TypeScript module names and *.test.ts test names.

Keep product rules, defaults, thresholds, and timeouts in typed module configuration. Vite, Electron Forge, define, and import.meta.env are for build/runtime wiring, not business behavior.

Frontend model identifiers, defaults, and selectable model options must come from userData/config/model-providers.json; never hardcode or invent provider model names in renderer code. Resolve Provider credentials and connection details in the Core process, and pass only model selection metadata to the renderer through typed contracts and IPC. Do not expose API keys, base URLs, or the complete environment to the renderer.

Project Format and Migrations

Persisted project data must survive feature updates. Database versions use SQLite PRAGMA user_version; append ordered migrations in packages/project-workspace/src/projectDatabaseMigrations.ts. Keep the baseline and previously shipped migration SQL (including imported schema helpers) immutable. Project creation must replay the same migration chain as upgrades. When persisted structures or stored JSON contracts change, update migrations, validation, contracts, storage, tests, and documentation together.

Project inspection is read-only. Apply migrations only while holding the project's write lock, after backing up the database and manifest under state/backups/, and commit schema/data/version changes in one transaction. Preserve source assets, imported chapters, proofreading, script analysis, model responses, and manual edits. Initialize new feature data with explicit defaults; rerun only affected downstream work when a data change requires it. Unknown structures and newer versions must produce an actionable error without modifying the project. Test preservation of populated projects, repeat opens, rollback, and lock handling with synthetic fixtures; private local projects may be used only for smoke checks with status/count output.

Testing Guidelines

Desktop and renderer tests use Vitest; packages and services use Node's test runner. Add focused regression tests for behavior changes and keep fixtures local to the owning module. No numeric coverage gate is configured, so review changed branches explicitly. Run the targeted package test while developing and the root check before opening a pull request.

Local Novel Test Samples

Keep private novel samples in the repository's data/test-novels/ directory. Only .gitkeep belongs in version control; all other contents must remain ignored and untracked. Use neutral local filenames and never record original sample names or novel text in code, documentation, snapshots, logs, or test output.

Import discoverLocalTestNovels or readLocalTestNovels from @voxweaver/novel-import/test-support when a local test needs novel samples. The first returns a read-only map from lowercase extension to absolute file path; the second returns a read-only map from extension to raw bytes. Let the existing import pipeline determine text encoding. These helpers are for tests only.

Both helpers locate the default directory relative to their module, independently of the working directory, and accept a directory override for isolated tests. They use PROJECT_SOURCE_FILE_CONFIG.extensions, inspect only direct regular files, and exclude hidden entries, directories, and symbolic links. As this repository's selection convention, sort filenames by JavaScript string code-unit order and select the first filename for each supported extension, matching extensions case-insensitively. Do not hardcode individual sample paths.

A missing or empty directory, or an absent format, contributes no map entry. Other filesystem failures must report only a generic message and an error code, without sample paths, names, contents, or the original error as a cause. Automated tests must create temporary synthetic files; they must not depend on private local samples. Local smoke checks may report only success status and counts.

Commit & Pull Request Guidelines

Use lowercase Conventional Commit types such as feat, fix, docs, refactor, or test: fix: 修复程序坞激活逻辑. Keep headers at most 72 characters and omit a trailing period. Each commit and pull request should address one concern. Pull requests must summarize behavior and risk, list verification commands, link the relevant issue, and include screenshots or a short recording for renderer changes.