fix: improvements

CONTRIBUTING.md

@@ -2,49 +2,60 @@
 
 ## 1. Coding Standards
 
-- Use TypeScript with `strict` mode enabled.
-- Follow the import order: core, library, project, then relative.
+- Use TypeScript with `strict` mode enabled; no `any` types.
+- Import order: core libs → third-party → project aliases (`@/`) → relative.
 - Naming: PascalCase for components, camelCase for functions/variables, UPPER_SNAKE_CASE for constants.
-- Add JSDoc comments for all public APIs.
-- Keep line length <= 120 characters, use Prettier for formatting.
-- Lint with `pnpm lint` and fix warnings.
+- Add JSDoc comments for all public APIs and exported types.
+- Line length ≤ 120 characters; use Prettier for formatting (`frontend/prettier.config.cjs`).
+- Run `npm run lint` and fix all warnings before opening a PR.
 
 ## 2. Branch Workflow
 
 - Create a feature branch: `git checkout -b feat/<short-description>`
-- Keep branches up to date with `main` via `git rebase` or `git merge --ff-only`.
+- Keep branches up to date with `main` via `git rebase`.
 - Submit a Pull Request with a clear title and description.
-- Ensure PR passes CI (tests, lint, type-check).
+- Ensure the PR passes CI (tests, lint, type-check).
 - Address review comments promptly.
 
 ## 3. Running Tests
 
-- Install dependencies: `pnpm install`.
-- Run tests in watch mode: `pnpm test --watch`.
-- Run tests with coverage: `pnpm test --coverage`.
-- Run lint: `pnpm lint`.
-- Run type-check: `pnpm typecheck`.
+```bash
+# Install dependencies
+cd frontend && npm install
+
+# Run tests in watch mode
+npm run test
+
+# Run tests once (CI)
+npm run test:run
+
+# Type-check
+npx tsc --noEmit
+```
 
 ## 4. Making Your First Contribution
 
 1. Pick a beginner-friendly issue labeled `good first issue`.
-2. Follow the steps in the Quickstart guide.
-3. Make a small change (e.g., fix typo, add JSDoc).
-4. Run the relevant tests.
-5. Commit and push, then open a PR.
+2. Read [ARCHITECTURE.md](ARCHITECTURE.md) to understand the relevant module.
+3. Make a small, focused change; avoid refactoring unrelated code.
+4. Run the relevant tests and confirm they pass.
+5. Commit and push, then open a PR with a clear description of what and why.
 
-## 5. Where to Extend (AI Agent Guidance)
+## 5. Where to Extend
 
-- **Canvas rendering**: Extend `src/app/canvas/CanvasPage.tsx` by adding new node types or customizing the context menu.
-- **Recollection management**: Modify `src/app/recollections/RecollectionsPage.tsx` to add new views or actions.
-- **State management**: Update `src/app/canvas/canvasStore.ts` for new graph features.
-- **Performance**: Optimize expensive renders in `src/app/recollections/RecollectionsPage.tsx` using memoization.
+| Goal | Where to look |
+| --- | --- |
+| Add a new node type | `src/lib/graph/nodeTypeBuilder.ts` + `registerBuiltinNodes.tsx` |
+| Add a new output/render type | `src/lib/graph/configTypes.ts` + `rendering.ts` |
+| Change canvas state shape | `src/app/canvas/canvasStore.ts` + reducer + tests |
+| Add a new Logos block | `src/app/recollections/logos/logosSchema.ts` |
+| Add a backend endpoint | `backend/src/routes/` → `services/` → `index.ts` |
 
 ## 6. Useful Links
 
-- [ARCHITECTURE.md](ARCHITECTURE.md) – High-level architecture overview.
-- [PERFORMANCE_IMPROVEMENTS.md](PERFORMANCE_IMPROVEMENTS.md) – Performance improvement plan.
-- [QUICKSTART_FOR_JUNIORS.md](QUICKSTART_FOR_JUNIORS.md) – Junior developer quickstart.
-- [CODE_REVIEW_CHECKLIST.md](CODE_REVIEW_CHECKLIST.md) – Checklist for reviewers.
+- [ARCHITECTURE.md](ARCHITECTURE.md) — architecture overview, key patterns, module map
+- [PERFORMANCE_IMPROVEMENTS.md](PERFORMANCE_IMPROVEMENTS.md) — bottleneck analysis and improvement plan
+- [docs/CODE_REVIEW_CHECKLIST.md](docs/CODE_REVIEW_CHECKLIST.md) — PR review checklist
+- [docs/NODE_TYPE_EXTENSIBILITY_PROPOSAL.md](docs/NODE_TYPE_EXTENSIBILITY_PROPOSAL.md) — node plugin system design
 
 *Thank you for contributing!*