# Lixity 3.0.0 — Claim chronology and reviewed causal interpretations

The research workspace adds a read-only **Timeline** inside Claims, explicit
**Cause and effect claims**, and an easier route from an evidence form to
keyword search. Research remains experimental and separate from manuscript
analysis. These features record and organize the author's choices; they do not
verify historical facts, causality or literary quality.

## Breaking API change

Claim lists consistently return `research-claims-local/2`, containing `claims`,
`project_id` and `snapshot` from one accepted snapshot. This applies to Python
`list_claims`, CLI `research claim` lists and HTTP `GET /api/research/claims`.
Consumers must update from the v1 envelope; there is no alternate legacy list
shape. Stored claim records and their revision history are unchanged. Source
search remains `research-search-local/1`; authored/unified search remains v2.

## Timeline and causal links

`research timeline` offers JSON, text and Markdown, optionally filtered by
dossier. It places only valid four-digit CE years, ISO dates and supported
same-precision ranges. Original labels remain visible; missing, unrecognized and
invalid periods appear separately. Creation dates never substitute for historical
periods, and reading changes no archive records or index.

`research relate FROM_CLAIM TO_CLAIM` saves an authored cause-to-effect assertion.
`results_in` is an alias for stored `causes` in that same direction. Exact claim
revisions remain pinned after later claim edits, with a review-needed notice.
The shared revision editor/API handles corrections and retractions without
overwriting history. Self-links fail; authored cycles are allowed; no reverse or
transitive relationships are inferred.

**Storage opt-in:** the first successful explicit causal-link write adds
`research-local/6` records and a `research-manifest-local/6` snapshot. Readers
before v3.0.0 reject that manifest. Back up the complete archive first and use
v3.0.0 or newer for all readers and writers afterward. Existing v1–v5 archives
remain readable without conversion; timeline and relation reads do not upgrade
them. Source bytes, old citations and authored revisions remain unchanged.
The existing export/restore bundle format preserves complete relation history.
Restore a complete backup if an older reader is needed; do not edit HEAD or
manifests to downgrade.

## Citation selection and reviewed context

Choose **Find source passage** in the evidence form to reuse Search → Sources →
**Use for claim**. Review the complete paragraph and choose a relation before
saving. `research cite --query "reading room"` resolves a single match without
typing its ID. Zero/multiple matches return source-search JSON and exit `1`;
ambiguous choices are safely numbered on stderr. Repeat the same query with
`--pick N --expected-snapshot DIGEST` to select a displayed match. A changed
snapshot or unavailable source requires another search. `--passage ID` remains
exact historical citation retrieval.

Citations keep their full paragraph/source-version/hash/offset identity.
Search and draft preparation create no claim, causal link or source capture.
Optional evidence project/snapshot/claim-revision guards reject changed reviewed
context and withdrawn evidence. Native causal writes and revisions require an
opaque selected-research-root token alongside reviewed archive/revision metadata;
restored copies sharing a project ID remain distinct selections.

## Existing application workflow

The uv-managed wheel installation and packaged `lixity service
start|stop|restart|status` workflow introduced in 2.4.0 remain. Stop managed
instances before replacing the installation, verify the installed version and
start/restart the intended instance. Manuscript PDF downloads, the read-only
dossier companion and source-text evidence drafts remain available.

Synthetic checks exercise conservative date parsing, unchanged v1–v5 reads,
exact endpoint pins, revision conflicts, retraction/history, atomic batches,
archive round trips, guarded evidence and delayed project/search responses.
Native UI coverage includes the seven interface languages and desktop/mobile
layouts. These checks do not establish historical truth or OCR recognition quality.

See the [research workflow](../research/USAGE.md#claim-chronology-and-causeeffect-links-since-v300),
[automation contracts](../AGENTS.md#51-research-api-lixityresearchapi) and
[installation/update reference](../INSTALLATION.md#updates-and-removal).