docs: rebuild documentation from scratch with clean IA

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

docs/developer/contributing.md

@@ -1,24 +1,78 @@
+---
+title: Contributing
+sidebar_position: 4
+---
+
 # Contributing
 
-## Scope
-This project favors small, reviewable pull requests that keep runtime behavior clear and operationally safe.
+## PR Process
 
-## Essential-File Policy
-Commit only source-of-truth files required to build, run, test, or document the app.
+1. Create a feature branch from `main`.
+2. Make your changes following the code standards below.
+3. Run tests inside the container (see [Testing](testing.md)).
+4. Run `ruff check .` and `mypy app/` to catch lint and type errors.
+5. Open a pull request with a clear title and description.
 
-Do not commit generated or local-only artifacts, including:
-- `__pycache__/`, `*.pyc`, `.pytest_cache/`, `.mypy_cache/`, `.ruff_cache/`
-- frontend build/install outputs like `frontend/dist/`, `frontend/node_modules/`, `frontend/.vite/`
-- coverage outputs (`.coverage`, `htmlcov/`)
-- packaging/build leftovers (`*.egg-info/`, `build/`, `dist/`)
-- local probe/scratch material (`planning/`)
+## Commit Conventions
 
-CI enforces this with `scripts/check_no_generated_artifacts.sh`.
+This project uses [Conventional Commits](https://www.conventionalcommits.org/) with [python-semantic-release](https://python-semantic-release.readthedocs.io/) for automated versioning.
 
-## Merge Checklist
-- [ ] Changes are minimal, purposeful, and remove obsolete/dead code in touched areas.
-- [ ] Backend tests pass (`uv run pytest tests/unit` and integration scope as needed).
-- [ ] Frontend checks pass (`npm run typecheck`, `npm run test:run`, `npm run build`).
-- [ ] API/behavior docs are updated when env vars, endpoints, or payloads change.
-- [ ] `README.md`, `.env.example`, and deployment notes stay aligned.
-- [ ] `scripts/check_no_generated_artifacts.sh` passes locally.
+Commit message format:
+
+```
+<type>(<scope>): <description>
+
+[optional body]
+```
+
+Types: `feat`, `fix`, `docs`, `ci`, `refactor`, `test`, `chore`, `perf`.
+
+Examples:
+- `feat(scholars): add bulk import from CSV`
+- `fix(ingestion): handle empty citation blocks`
+- `docs: update configuration reference`
+
+## Code Standards
+
+### Function Length
+
+Maximum 50 lines per function. Break complex logic into small, testable, single-responsibility functions.
+
+### DRY
+
+Abstract repetitive logic immediately. No duplicate boilerplate for database queries, API responses, or error handling.
+
+### Negative Space Programming
+
+Use explicit assertions and constraints to define invalid states. Fail fast and early. Do not allow silent failures or cascading malformed data, especially in DOM parsing.
+
+### Cyclomatic Complexity
+
+Flatten logic. Use early returns and guard clauses instead of deep nesting. No magic numbers.
+
+### Domain Service Boundaries
+
+All business logic resides in `app/services/<domain>/`. Flat files in the `app/services/` root are strictly prohibited. Each domain owns its own application service, types, and helpers.
+
+### API Envelope
+
+All `/api/v1` responses use the strict envelope format:
+
+- Success: `{"data": ..., "meta": {"request_id": "..."}}`
+- Error: `{"error": {"code": "...", "message": "...", "details": ...}, "meta": {"request_id": "..."}}`
+
+### Data Isolation
+
+- Scholar tracking is user-scoped.
+- Publications are global, deduplicated records.
+- Read/favorite/visibility state lives on scholar-publication link rows.
+
+### Scrape Safety
+
+Rate limits and cooldowns are immutable constraints. They prevent IP bans and must not be optimized away or set to zero.
+
+## UI Standards
+
+- Integrate Tailwind with the preset theming system (`frontend/src/theme/presets/`).
+- Every UI element must have a clear purpose.
+- Clarity through both styling and language.