docs: repo CLAUDE.md orientation + living project status

CLAUDE.md

@@ -0,0 +1,56 @@
+# CLAUDE.md — locusview
+
+Orientation for any Claude Code session (local, cloud, or a teammate's) and for new contributors.
+Keep it current. The live "where we are right now" lives in
+[docs/process/status.md](docs/process/status.md).
+
+## What this is
+locusview aggregates publicly available **QTL** (quantitative trait locus) data and lets users
+**search, browse, and download** it. It is built by Boxiang Liu's lab **and** is a graduate-level
+software-engineering teaching example — so docs, ADRs, and PR history are first-class deliverables.
+
+- Repo: <https://github.com/boxiangliulab/locusview> · Board: <https://github.com/orgs/boxiangliulab/projects/5>
+
+## Stack
+Python 3.11+ · **uv** (env/deps) · **FastAPI + Jinja2 + HTMX** (no JS build chain) · **pymysql** to the
+shared **locuscompare2 MySQL** database (ADR-0008) · Ruff + mypy (strict) + pytest. Storage is the
+shared DB, **not** a locusview-owned store (ADR-0008 supersedes the earlier Parquet/DuckDB plan).
+
+## Run it
+```bash
+uv sync                                  # env + deps
+uv run pytest                            # tests — must stay green (90% coverage gate)
+uv run ruff check . && uv run mypy       # lint + types (strict)
+uv run locusview serve                   # web app on http://127.0.0.1:8000
+```
+Data access needs `LOCUSCOMPARE2_DB_*` env vars (a read-only account). The public read-only **test**
+credentials + host are documented in
+[docs/how-to/connect-to-locuscompare2-database.md](docs/how-to/connect-to-locuscompare2-database.md);
+the password is never committed. For **cloud** Claude Code sessions, allowlist the DB host so the VM
+can reach it.
+
+## How we work — READ before changing code
+- **Trunk-based-lite + protected `main`.** Never push to `main`. Every change: feature branch → PR →
+  green CI → **code-owner review** → squash-merge + delete branch. See
+  [docs/explanation/pull-requests-and-branch-protection.md](docs/explanation/pull-requests-and-branch-protection.md).
+- **Agents write, humans merge.** Do not self-merge; a human code owner (`CODEOWNERS`) approves.
+- Never weaken a test to make CI pass; never commit secrets or large data (`data/` is gitignored;
+  `gitleaks` runs). Mark agent-authored commits with `Co-Authored-By`.
+- Full process: [docs/process/ways-of-working.md](docs/process/ways-of-working.md) ·
+  [docs/process/agent-workflow.md](docs/process/agent-workflow.md).
+
+## Code conventions
+- Read QTL data through the **`QtlRepository`** Protocol (`src/locusview/repository.py`):
+  `FakeQtlRepository` for hermetic tests, `LocuscompareRepository` for the real DB. **Program to the
+  interface; keep CI hermetic (no network in tests)** — the real DB is exercised only in ad-hoc checks.
+- DB keys are integer-encoded: `gene_id` = the ENSG number (`ENSG00000141510` → `141510`), `rs_id` =
+  rsID minus `rs`. Data lives in per-tissue `eqtl_snp_{dataset_id}` shards + the `eqtl_raw` catalog;
+  gene coords in `gencode_v26_hg38`. **The shards have no effect allele / MAF → do not present β
+  *direction*** (issue #18).
+- Docs use **Diátaxis** (tutorials/how-to/reference/explanation) + ADRs in `docs/adr/`. Design specs in
+  `docs/design/` and web templates are owned by the UI/UX designer (see `CODEOWNERS`).
+
+## Where knowledge lives (the repo is the source of truth)
+Decisions → `docs/adr/` · designs → `docs/design/` · process → `docs/process/` · current state &
+open threads → `docs/process/status.md` · the teaching layer → `docs/course/`. Prefer these over
+chat or machine-local memory — they travel with `git clone` to cloud sessions and teammates.

docs/process/status.md

@@ -0,0 +1,45 @@
+# Project status — locusview
+
+> A **living** "where we are right now" doc — update it whenever phase / PRs / blockers change.
+> For durable *decisions* see [`../adr/`](../adr/); for *how we work* see the other
+> [`process/`](.) docs; for the roadmap see [`../product/roadmap.md`](../product/roadmap.md).
+>
+> _Last updated: 2026-07 (see `git log` for precise dates)._
+
+## Phase
+**Phase 1 — thin vertical MVP** (search → gene page → browse/download to come). Phase 0 (foundation,
+process, docs, CI, guardrails) is complete.
+
+## Shipped (on `main`)
+- **Foundation:** repo, Diátaxis docs, ADRs 0001–0008, CI (lint / types / tests + genomics smoke +
+  docker build), branch protection, `CODEOWNERS`, the teaching layer (`docs/course/`, explainers).
+- **App skeleton:** FastAPI + Jinja2/HTMX, `/health`, config-in-env, `locusview serve`.
+- **Data layer:** the `QtlRepository` interface (`FakeQtlRepository` + real `LocuscompareRepository`
+  over the shared locuscompare2 DB) and the search query parser.
+- **Gene page:** search a gene → its eQTLs across tissues, on real GTEx v8 data via the shared DB.
+
+## In flight (open PRs)
+- **#22** — add code owners (Liu Fei, YANG Chen, Wenjing) + assign Liu Fei design/UI ownership.
+  _Awaiting review._
+- **#23** — **design spec** for the gene-page visualizations (LD-colored regional plot + tissue body
+  map). _Under review by @liufei-f (UI/UX)._ Spec: `docs/design/gene-page-visualizations.md`.
+
+## Next up
+- **Regional plot (Phase A)** once the design (#23) is signed off: a LocusZoom-style, LD-colored
+  Plotly plot (per gene × tissue), then LD click-to-recolor + population selector.
+- **Tissue body map (Phase B):** EBI anatomogram SVG (CC-BY) highlighting eQTL tissues.
+- Backlog: variant page (#6), download (#7), provenance banner (#8).
+
+## Open items / blockers
+- **#18** — the DB has no effect allele → β *direction* is not interpretable; decide how to handle
+  (join a variant reference / re-read source / show p-values only).
+- **LD covering index** on the `tkg_p3v5a_ld_*` tables (perf for the plot) — DDL on the *shared* DB,
+  owner **Junbin**, routed via [`schema-change-coordination.md`](schema-change-coordination.md).
+- **Board** (Project #5) is stale — needs a sync (closed issues → Done; add #18 + open PRs).
+
+## Team & roles
+- Lead: **@boxiangliu** (Boxiang Liu).
+- Engineers: **@gaojunbin** (Junbin Gao — owns the locuscompare2 DB), **@GhostAnderson** (Laurentius),
+  **@MickYang2333** (YANG Chen), **@wenjing-gakkilove** (Wenjing).
+- UI/UX: **@liufei-f** (Liu Fei — owns `docs/design/` + `src/locusview/templates/`).
+- Plus a PM and scientists. All new to software engineering; heavy, guardrailed use of coding agents.