docs: consolidate and expand project documentation

[ghostbloo]

This PR consolidates and expands the project documentation. It is docs-only — no code, config, or behavior changes.

What's here

• docs/ontology.md (new) — a single, maintained description of the annotation/ranking domain model (ontologies, tags, selections, ratings, ranking systems), reconciled against the current code. It replaces the two write-once snapshots ONTOLOGY_DESIGN.md and ONTOLOGY_REFACTOR_COMPLETE.md, which are removed.
• README.md — expanded into a full project overview: repo layout, dev/build commands, the complete environment-variable reference, and API examples. The standalone QUICKSTART.md is folded in and removed.
• REQUIREMENTS.md — annotated with implementation status throughout, so readers can tell shipped behavior from aspirational spec.
• CLAUDE.md (root, src/, frontend/) — contributor onboarding notes: layout, build/dev commands, the hybrid JSONL + SQLite storage design, dependency injection via AppContext, auth/roles, and the frontend data-flow conventions.

Notes

• Net +814 / −971 across 9 files; purely documentation.
• Commits are split by theme for easier review.

🤖 Generated with Claude Code

[greptile-apps]

Greptile Summary

This docs-only PR consolidates scattered, stale documentation into a coherent set of maintained references: a new docs/ontology.md replaces two write-once design snapshots, README.md is expanded into a full project reference, REQUIREMENTS.md is annotated with implementation status, and three new CLAUDE.md files give contributors a precise map of the codebase. Three outdated files (ONTOLOGY_DESIGN.md, ONTOLOGY_REFACTOR_COMPLETE.md, QUICKSTART.md) are removed.

• docs/ontology.md is the highlight — it accurately describes the tag-voting model, the selection/rating split, the full API surface, and the frontend component map in a single maintained document.
• REQUIREMENTS.md gains ✅/🚧/❌ flags throughout, clearly distinguishing shipped behavior from aspirational spec and calling out divergences.
• Root CLAUDE.md contradicts src/CLAUDE.md on ratings storage: the root says ratings live in "both worlds" (JSONL + SQLite), while src/CLAUDE.md states the JSONL path is dead and deprecated — a factual inconsistency that would mislead contributors adding new rating-adjacent code.

Confidence Score: 4/5

Safe to merge after fixing the ratings-storage contradiction in root CLAUDE.md — all other changes are accurate and well-written.

The root CLAUDE.md tells contributors that ratings are dual-stored in JSONL and SQLite, while src/CLAUDE.md (also new in this PR) explicitly says the JSONL path is dead and that all new rating code must go through AnnotationDatabase exclusively. A developer following only the root CLAUDE.md could incorrectly assume JSONL-side ratings are still canonical and waste time tracing a deprecated code path — or introduce new dual-write logic that's no longer needed. Everything else in the PR is internally consistent and accurate.

CLAUDE.md (root) — the ratings dual-storage claim on line 57 needs to be corrected to match src/CLAUDE.md.

Important Files Changed

Filename	Overview
CLAUDE.md	New root contributor guide — accurate overall, but contradicts src/CLAUDE.md on ratings storage (claims dual JSONL+SQLite; src/CLAUDE.md says JSONL is dead). The cross-reference to docs/ontology.md for an explanation is also broken.
src/CLAUDE.md	New backend contributor guide with detailed, accurate coverage of boot sequence, store conventions, SQLite vs JSONL decision logic, route patterns, and migration gotchas.
frontend/CLAUDE.md	New frontend contributor guide accurately describing the data-flow convention, the auth interceptor, router guard conventions, and the dark-only theme situation.
docs/ontology.md	New maintained domain-model reference replacing two stale snapshots. Accurately captures the tag-voting model, rating/selection split, API table, and component map.
README.md	Expanded from a stub into a full project overview with detailed env-var reference and updated API examples reflecting the current schema.
REQUIREMENTS.md	Annotated throughout with ✅/🚧/❌ implementation status flags with clear parenthetical notes on divergences.

Sequence Diagram

sequenceDiagram
    participant U as User (browser)
    participant AW as AnnotationWorkspace.vue
    participant API as services/api.ts
    participant BE as Backend (Express)
    participant DB as AnnotationDatabase (SQLite)

    U->>AW: Open submission /submissions/:id
    AW->>API: ontologiesAPI.getForSubmission(id)
    API->>BE: GET /api/ontologies/submission/:id
    BE->>DB: submission_ontologies lookup
    DB-->>AW: attached ontologies + tags

    U->>AW: Select text in message
    AW->>API: annotationsAPI.createSelection(...)
    API->>BE: POST /api/annotations/selections
    BE->>DB: INSERT selections
    DB-->>AW: selection record

    U->>AW: Open TagPicker, check tags
    AW->>API: ontologiesAPI.applyTags(selectionId, tagIds)
    API->>BE: POST /api/ontologies/tags/apply
    BE->>DB: INSERT selection_tags (tag vote)
    DB-->>AW: updated tag votes

    U->>AW: Add comment
    AW->>API: "annotationsAPI.createComment({selection_id})"
    API->>BE: POST /api/annotations/comments
    BE->>DB: INSERT comments (selection_id FK)
    DB-->>AW: comment record

    U->>AW: Open RatingForm (submission-level)
    AW->>API: "annotationsAPI.createRating({submission_id, criterion_id, score})"
    API->>BE: POST /api/annotations/ratings
    BE->>DB: INSERT ratings (submission_id FK, no selection)
    DB-->>AW: rating record

Loading

Prompt To Fix All With AI

Fix the following 1 code review issue. Work through them one at a time, proposing concise fixes.

---

### Issue 1 of 1
CLAUDE.md:57-58
**Ratings described as dual-stored, but src/CLAUDE.md says JSONL is dead**

This line tells contributors that ratings live in "both worlds" (JSONL per-submission and SQLite), but `src/CLAUDE.md` explicitly contradicts this: "Ratings live in SQLite, not here. The `ratings.jsonl` file and the rating methods in `SubmissionStore` are dead/deprecated; the comment in the file claiming ratings are dual-written is stale. New rating code goes through `AnnotationDatabase` only." A developer reading only the root `CLAUDE.md` would waste time looking for JSONL rating events, or worse, write new code that dual-writes expecting both to be canonical. The cross-reference "see `docs/ontology.md` for why" also doesn't resolve this — `docs/ontology.md` lists ratings under SQLite only and gives no explanation of dual storage.

```suggestion
Ratings are submission-level and live in SQLite only (`AnnotationDatabase`). The `ratings.jsonl` file and rating methods on `SubmissionStore` are deprecated dead code; new rating code goes through `AnnotationDatabase` exclusively — see `src/CLAUDE.md` for details.
```

_{Reviews (1): Last reviewed commit: "docs: add CLAUDE.md contributor and agen..." | Re-trigger Greptile}

[greptile-apps]

Ratings described as dual-stored, but src/CLAUDE.md says JSONL is dead

This line tells contributors that ratings live in "both worlds" (JSONL per-submission and SQLite), but src/CLAUDE.md explicitly contradicts this: "Ratings live in SQLite, not here. The ratings.jsonl file and the rating methods in SubmissionStore are dead/deprecated; the comment in the file claiming ratings are dual-written is stale. New rating code goes through AnnotationDatabase only." A developer reading only the root CLAUDE.md would waste time looking for JSONL rating events, or worse, write new code that dual-writes expecting both to be canonical. The cross-reference "see docs/ontology.md for why" also doesn't resolve this — docs/ontology.md lists ratings under SQLite only and gives no explanation of dual storage.

Suggested change

	**Types are duplicated, for now.** Zod schemas in `src/types/` define and validate the backend domain; `frontend/src/types/` hand-mirrors them as plain TS. When changing a shared shape, update both sides (consolidation tracked in issue #2).
	Ratings are submission-level and live in SQLite only (`AnnotationDatabase`). The `ratings.jsonl` file and rating methods on `SubmissionStore` are deprecated dead code; new rating code goes through `AnnotationDatabase` exclusively — see `src/CLAUDE.md` for details.

Prompt To Fix With AI

This is a comment left during a code review.
Path: CLAUDE.md
Line: 57-58

Comment:
**Ratings described as dual-stored, but src/CLAUDE.md says JSONL is dead**

This line tells contributors that ratings live in "both worlds" (JSONL per-submission and SQLite), but `src/CLAUDE.md` explicitly contradicts this: "Ratings live in SQLite, not here. The `ratings.jsonl` file and the rating methods in `SubmissionStore` are dead/deprecated; the comment in the file claiming ratings are dual-written is stale. New rating code goes through `AnnotationDatabase` only." A developer reading only the root `CLAUDE.md` would waste time looking for JSONL rating events, or worse, write new code that dual-writes expecting both to be canonical. The cross-reference "see `docs/ontology.md` for why" also doesn't resolve this — `docs/ontology.md` lists ratings under SQLite only and gives no explanation of dual storage.

```suggestion
Ratings are submission-level and live in SQLite only (`AnnotationDatabase`). The `ratings.jsonl` file and rating methods on `SubmissionStore` are deprecated dead code; new rating code goes through `AnnotationDatabase` exclusively — see `src/CLAUDE.md` for details.
```

How can I resolve this? If you propose a fix, please make it concise.

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!