Contributing

neondeck is still early. The roadmap is the source of truth for direction, and changes should keep the local-first Flue runtime, companion-display dashboard, and future TUI on one shared backend surface.

Local setup

fnm install 26.4.0
fnm use 26.4.0
npm install
npm run setup
npm run dev

Use NEONDECK_HOME or CLI --home when you want an isolated runtime for testing.

Project direction

Read AGENTS.md, .plans/ROADMAP.md, .plans/HERMES_RESEARCH.md, and SOUL.md before larger work. The roadmap defines implementation order and expected behavior.

Deviation log

Keep .plans/DEVIATIONS.md current when implementation intentionally differs from the roadmap, when work is deferred, or when a phase is partially complete. The deviations log is used for progress tracking and reviews.

Fast checks

npm run check

The fast loop runs Oxlint, TypeScript checks, Astro sync, and the unit Vitest suite. Keep it fast enough to run often.

Individual checks

npm run lint
npm run typecheck
npm run test
npm run test:git
npm run test:integration
npm run test:all
npm run format:check
npm run docs:build

Full verification

npm run verify

test:git runs the serial Git/performance/docs-drift group; test:integration runs the slower workflow and worktree group. Full verification runs both groups plus the unit suite, then adds formatting and production builds. Run it before broad or release-oriented changes, not after every unrelated edit.

Code style

Keep TypeScript clean, readable, composable, and typed at API and IO boundaries with Valibot. React should stay modern and componentized. Prefer existing project patterns over new abstractions unless the abstraction removes real complexity.

Reviews

Reviews should prioritize correctness, security, performance, maintainability, missing validation, and unreasonable deviations from the roadmap. Static review skills are available in-repo for roadmap implementation review.