# Coding Instructions — Root Guide (All Projects)

_Last updated: 2025-08-19_

This is the root document for any project. Read this first. It explains how we collaborate, set up testing and CI, apply standards, and bootstrap new projects. Then read the project-specific instructions for details unique to a repository.

## Communication & Collaboration

- Be clear and concise: propose a plan, then execute in small steps.
- Prefer test-first or test-along: write/update tests with each change.
- Before running tools or large edits, share a brief preamble of next actions.
- After changes, summarize outcomes, side effects, and next options.
- Capture decisions as ADRs; capture insights in the project’s “Living Memory”.
- Keep the repo tidy: remove obsolete files as we go; update docs and tests alongside code.

## Source Control & Workflow

- Small, atomic changes; avoid unrelated edits.
- Use meaningful commit messages and PR descriptions (if applicable).
- Run typecheck, lint, tests locally before opening PRs.
- Pre-commit hooks: Husky + lint-staged auto-fix formatting/lint on staged files.
- Link PRs/issues to roadmap items; record design decisions in ADRs.

## Testing Strategy

- Unit/Component: Vitest + React Testing Library + jsdom.
- E2E: Playwright (later), with MSW for network mocking.
- Coverage: v8 coverage; thresholds in CI for lines/branches/functions/statements.
- Conventions:
  - Co-locate tests: `*.test.ts`/`*.test.tsx` under `src/`.
  - Use `render` helpers (providers/router/theme) to keep tests focused.
  - Use `vi.mock()` for APIs and unstable dependencies.
  - Wrap state updates in `act`/`waitFor` to avoid flakiness.
  - Keep tests deterministic; avoid real sleeps; prefer fake timers for pure async.

## CI/CD

- Default: Gitea Actions (self-hosted runners supported).
- Minimal pipeline steps:
  1. Manual checkout (no marketplace actions)
  2. Install Node via official tarball
  3. `npm ci` (locked) — first run may use `npm install` to generate lockfile
  4. Lint (`npm run lint`) — keep zero warnings/errors; fix promptly
  5. Typecheck (`tsc -b --noEmit`) if TS is enabled
  6. Build
  7. Tests with coverage (thresholds: lines 70, branches 70, functions 50, statements 70)

## User Feedback & Status

- Always surface state changes: loading/success/error patterns.
- Non-blocking toasts and inline indicators preferred.

## Debugging & Support

- Add a debug menu and safe diagnostics. Be privacy-conscious.

## Performance & Reliability

- Avoid N+1; prefer batching. Handle errors explicitly with retries.

## Security & Privacy

- No secrets in code. Validate/sanitize inputs crossing boundaries.

## Documentation Standards

- `docs/project-instructions.md`, `docs/architecture.md`, `docs/testing.md`, `docs/roadmap.md`, ADRs under `docs/adr/`.
- Keep docs up to date in the same PR as changes.

## New Project Setup (applied here)

- Add minimal Node toolchain for lint/format/test.
- Add Gitea CI workflow.
- Add initial unit tests with coverage.

## Commands

- `npm run serve` — local static server at http://localhost:5173
- `npm run lint` / `npm run lint:fix`
- `npm run format` / `npm run format:check`
- `npm test` / `npm run test:watch`