diff --git a/site/images/access-log.png b/site/src/assets/screenshots/access-log.png
similarity index 100%
rename from site/images/access-log.png
rename to site/src/assets/screenshots/access-log.png
diff --git a/site/images/amendments-diff.png b/site/src/assets/screenshots/amendments-diff.png
similarity index 100%
rename from site/images/amendments-diff.png
rename to site/src/assets/screenshots/amendments-diff.png
diff --git a/site/images/amendments-impact.png b/site/src/assets/screenshots/amendments-impact.png
similarity index 100%
rename from site/images/amendments-impact.png
rename to site/src/assets/screenshots/amendments-impact.png
diff --git a/site/images/anomalies.png b/site/src/assets/screenshots/anomalies.png
similarity index 100%
rename from site/images/anomalies.png
rename to site/src/assets/screenshots/anomalies.png
diff --git a/site/images/approval-queue.png b/site/src/assets/screenshots/approval-queue.png
similarity index 100%
rename from site/images/approval-queue.png
rename to site/src/assets/screenshots/approval-queue.png
diff --git a/site/images/audit-trail.png b/site/src/assets/screenshots/audit-trail.png
similarity index 100%
rename from site/images/audit-trail.png
rename to site/src/assets/screenshots/audit-trail.png
diff --git a/site/images/blinded-entry.png b/site/src/assets/screenshots/blinded-entry.png
similarity index 100%
rename from site/images/blinded-entry.png
rename to site/src/assets/screenshots/blinded-entry.png
diff --git a/site/images/blinded-field.png b/site/src/assets/screenshots/blinded-field.png
similarity index 100%
rename from site/images/blinded-field.png
rename to site/src/assets/screenshots/blinded-field.png
diff --git a/site/images/break-blind.png b/site/src/assets/screenshots/break-blind.png
similarity index 100%
rename from site/images/break-blind.png
rename to site/src/assets/screenshots/break-blind.png
diff --git a/site/images/coding.png b/site/src/assets/screenshots/coding.png
similarity index 100%
rename from site/images/coding.png
rename to site/src/assets/screenshots/coding.png
diff --git a/site/images/dynamic-fields.png b/site/src/assets/screenshots/dynamic-fields.png
similarity index 100%
rename from site/images/dynamic-fields.png
rename to site/src/assets/screenshots/dynamic-fields.png
diff --git a/site/images/form-entry.png b/site/src/assets/screenshots/form-entry.png
similarity index 100%
rename from site/images/form-entry.png
rename to site/src/assets/screenshots/form-entry.png
diff --git a/site/images/lab-import.png b/site/src/assets/screenshots/lab-import.png
similarity index 100%
rename from site/images/lab-import.png
rename to site/src/assets/screenshots/lab-import.png
diff --git a/site/images/login.png b/site/src/assets/screenshots/login.png
similarity index 100%
rename from site/images/login.png
rename to site/src/assets/screenshots/login.png
diff --git a/site/images/notifications-bell.png b/site/src/assets/screenshots/notifications-bell.png
similarity index 100%
rename from site/images/notifications-bell.png
rename to site/src/assets/screenshots/notifications-bell.png
diff --git a/site/images/protocol-review.png b/site/src/assets/screenshots/protocol-review.png
similarity index 100%
rename from site/images/protocol-review.png
rename to site/src/assets/screenshots/protocol-review.png
diff --git a/site/images/queries.png b/site/src/assets/screenshots/queries.png
similarity index 100%
rename from site/images/queries.png
rename to site/src/assets/screenshots/queries.png
diff --git a/site/images/repeating-entry.png b/site/src/assets/screenshots/repeating-entry.png
similarity index 100%
rename from site/images/repeating-entry.png
rename to site/src/assets/screenshots/repeating-entry.png
diff --git a/site/images/rtsm-panel.png b/site/src/assets/screenshots/rtsm-panel.png
similarity index 100%
rename from site/images/rtsm-panel.png
rename to site/src/assets/screenshots/rtsm-panel.png
diff --git a/site/images/rules-panel.png b/site/src/assets/screenshots/rules-panel.png
similarity index 100%
rename from site/images/rules-panel.png
rename to site/src/assets/screenshots/rules-panel.png
diff --git a/site/images/rules-syntax-error.png b/site/src/assets/screenshots/rules-syntax-error.png
similarity index 100%
rename from site/images/rules-syntax-error.png
rename to site/src/assets/screenshots/rules-syntax-error.png
diff --git a/site/images/sign-form.png b/site/src/assets/screenshots/sign-form.png
similarity index 100%
rename from site/images/sign-form.png
rename to site/src/assets/screenshots/sign-form.png
diff --git a/site/images/site-forms-editor.png b/site/src/assets/screenshots/site-forms-editor.png
similarity index 100%
rename from site/images/site-forms-editor.png
rename to site/src/assets/screenshots/site-forms-editor.png
diff --git a/site/images/snapshot-exports.png b/site/src/assets/screenshots/snapshot-exports.png
similarity index 100%
rename from site/images/snapshot-exports.png
rename to site/src/assets/screenshots/snapshot-exports.png
diff --git a/site/images/studies.png b/site/src/assets/screenshots/studies.png
similarity index 100%
rename from site/images/studies.png
rename to site/src/assets/screenshots/studies.png
diff --git a/site/images/study-builder-edit.png b/site/src/assets/screenshots/study-builder-edit.png
similarity index 100%
rename from site/images/study-builder-edit.png
rename to site/src/assets/screenshots/study-builder-edit.png
diff --git a/site/images/study-builder.png b/site/src/assets/screenshots/study-builder.png
similarity index 100%
rename from site/images/study-builder.png
rename to site/src/assets/screenshots/study-builder.png
diff --git a/site/images/study-overview.png b/site/src/assets/screenshots/study-overview.png
similarity index 100%
rename from site/images/study-overview.png
rename to site/src/assets/screenshots/study-overview.png
diff --git a/site/images/subject-lifecycle.png b/site/src/assets/screenshots/subject-lifecycle.png
similarity index 100%
rename from site/images/subject-lifecycle.png
rename to site/src/assets/screenshots/subject-lifecycle.png
diff --git a/site/images/subject-matrix.png b/site/src/assets/screenshots/subject-matrix.png
similarity index 100%
rename from site/images/subject-matrix.png
rename to site/src/assets/screenshots/subject-matrix.png
diff --git a/site/images/team.png b/site/src/assets/screenshots/team.png
similarity index 100%
rename from site/images/team.png
rename to site/src/assets/screenshots/team.png
diff --git a/site/images/users-admin.png b/site/src/assets/screenshots/users-admin.png
similarity index 100%
rename from site/images/users-admin.png
rename to site/src/assets/screenshots/users-admin.png
diff --git a/site/images/workbench-python.png b/site/src/assets/screenshots/workbench-python.png
similarity index 100%
rename from site/images/workbench-python.png
rename to site/src/assets/screenshots/workbench-python.png
diff --git a/site/images/workbench-r.png b/site/src/assets/screenshots/workbench-r.png
similarity index 100%
rename from site/images/workbench-r.png
rename to site/src/assets/screenshots/workbench-r.png
diff --git a/site/images/workbench-sql.png b/site/src/assets/screenshots/workbench-sql.png
similarity index 100%
rename from site/images/workbench-sql.png
rename to site/src/assets/screenshots/workbench-sql.png
diff --git a/site/src/components/Footer.astro b/site/src/components/Footer.astro
new file mode 100644
index 0000000..cab3ce1
--- /dev/null
+++ b/site/src/components/Footer.astro
@@ -0,0 +1,18 @@
+---
+import Default from "@astrojs/starlight/components/Footer.astro";
+---
+
+
+
+
+
diff --git a/site/src/content.config.ts b/site/src/content.config.ts
new file mode 100644
index 0000000..7fbcf2c
--- /dev/null
+++ b/site/src/content.config.ts
@@ -0,0 +1,7 @@
+import { defineCollection } from "astro:content";
+import { docsLoader } from "@astrojs/starlight/loaders";
+import { docsSchema } from "@astrojs/starlight/schema";
+
+export const collections = {
+ docs: defineCollection({ loader: docsLoader(), schema: docsSchema() }),
+};
diff --git a/site/compliance.qmd b/site/src/content/docs/compliance.md
similarity index 96%
rename from site/compliance.qmd
rename to site/src/content/docs/compliance.md
index 02f4ef4..1776bb9 100644
--- a/site/compliance.qmd
+++ b/site/src/content/docs/compliance.md
@@ -2,8 +2,8 @@
title: "Compliance"
---
-::: {.callout-important}
-## What a product can and can't claim
+
+:::danger[What a product can and can't claim]
No software is "Part 11 compliant" on its own: compliance belongs to the
sponsor's validated implementation, SOPs, and training. edc-core's job is to
@@ -76,7 +76,7 @@ running system.
## Data lifecycle procedures
-Requirements alone don't run a trial. The [data lifecycle](data-lifecycle.qmd)
+Requirements alone don't run a trial. The [data lifecycle](/edc-core/data-lifecycle/)
page walks ICH E6(R3) §4.2 element by element, from capture and audit trails
through corrections, transfer, finalisation, retention, and destruction. For
each, it separates what the system enforces by construction from what belongs
diff --git a/site/data-lifecycle.qmd b/site/src/content/docs/data-lifecycle.md
similarity index 85%
rename from site/data-lifecycle.qmd
rename to site/src/content/docs/data-lifecycle.md
index 5b5a327..128a18e 100644
--- a/site/data-lifecycle.qmd
+++ b/site/src/content/docs/data-lifecycle.md
@@ -2,14 +2,14 @@
title: "Data lifecycle"
---
+
ICH E6(R3) §4.2 is blunt: "Procedures should be in place to cover the full
data life cycle." This page is that map for edc-core: for each lifecycle
element (§4.2.1–4.2.8), what the system enforces by construction, and what
remains yours to write into SOPs and the data management plan. It is the
procedures companion to traceability row E6-01.
-::: {.callout-important}
-## Mechanisms are not procedures
+:::danger[Mechanisms are not procedures]
edc-core can make a control *impossible to skip* (an audit trail with no off
switch) or *cheap to follow* (a query dashboard). It cannot decide how much
@@ -25,20 +25,20 @@ units, and edit checks are defined in CDISC ODM, versioned as immutable
metadata versions, and every subject is pinned to a specific build, so
"what were we collecting, and how was it checked, on this date?" is a lookup,
not an archaeology project. Changes arrive as
-[amendments](guide/study-builds.qmd), with deliberate, audited migration of
+[amendments](/edc-core/guide/study-builds/), with deliberate, audited migration of
existing subjects.
§4.2.1(c) asks for automated validation checks whose implementation is
"controlled and documented". In edc-core, edit checks live *inside* the
versioned build: they fire on every accepted write, raise system
-[queries](guide/review.qmd) when violated, and auto-close when the data is
+[queries](/edc-core/guide/review/) when violated, and auto-close when the data is
corrected. Changing a check is a metadata amendment: versioned, audited,
and diffable, which is the control and the documentation.
Every captured value carries its metadata (§4.2.1(b)): who wrote it, when,
against which build, and by which path: manual entry, [lab
-import](guide/lab-import.qmd) (`item_value.imported`), or [RTSM
-integration](guide/rtsm-integration.qmd) (`item_value.integrated`).
+import](/edc-core/guide/lab-import/) (`item_value.imported`), or [RTSM
+integration](/edc-core/guide/rtsm-integration/) (`item_value.integrated`).
**Yours to decide:** the extent of transcription verification for data
transcribed from paper or EHR sources (§4.2.1(a)) is a risk-based call on
@@ -52,7 +52,7 @@ turned off:
- **User account history** (§4.2.2(a)(i)): account creation, activation
changes, role grants and revocations are audit events; every API request
- additionally lands in the [access log](guide/user-admin.qmd).
+ additionally lands in the [access log](/edc-core/guide/user-admin/).
- **Data changes** (§4.2.2(a)(ii)): initial entry and every subsequent
change or removal are separate versions with actor, timestamp, prior
value, and, for corrections, a required reason for change.
@@ -75,7 +75,7 @@ Timestamps are recorded server-side at write time and exported unambiguously
**Yours to decide:** which metadata require routine review and how long the
operational access log is kept (§4.2.2(e)); see [log
-retention](deployment.qmd#access-logging-and-log-retention) for the
+retention](/edc-core/deployment/#access-logging-and-log-retention) for the
distinction between prunable telemetry and the never-pruned audit trail.
## Review of data and metadata (§4.2.3)
@@ -85,10 +85,10 @@ built:
| Review | Where |
|---|---|
-| Data review | [Query dashboard](guide/review.qmd): open/answered/closed lifecycle, manual and system-raised, monitor reopen |
+| Data review | [Query dashboard](/edc-core/guide/review/): open/answered/closed lifecycle, manual and system-raised, monitor reopen |
| Audit trail review | `/studies/:id/audit`: filter by action, entity, actor, time; export CSV (`audit.review`-gated) |
-| Access review | [Access log](guide/user-admin.qmd) with CSV export |
-| Security events | [Anomaly review](deployment.qmd#security-anomaly-detection) with audited acknowledgement |
+| Access review | [Access log](/edc-core/guide/user-admin/) with CSV export |
+| Security events | [Anomaly review](/edc-core/deployment/#security-anomaly-detection) with audited acknowledgement |
**Yours to decide:** frequency, sampling, responsibility, and escalation,
risk-based, adapted to the trial, and adjusted on experience, per §4.2.3.
@@ -109,15 +109,15 @@ happened, not whether your source documents agree.
## Transfer, exchange and migration (§4.2.5)
-Inbound transfers ([lab CSV](guide/lab-import.qmd),
-[RTSM](guide/rtsm-integration.qmd)) go through the same audited write path
+Inbound transfers ([lab CSV](/edc-core/guide/lab-import/),
+[RTSM](/edc-core/guide/rtsm-integration/)) go through the same audited write path
as manual entry and **never overwrite**: identical replays are idempotent,
conflicting values are reported and not written. Every RTSM post, including
rejects, lands in an append-only event record, and every import run keeps
its row-level report; both are your reconciliation basis.
Outbound, exports are Dataset-JSON v1.1 and CSV pinned to immutable
-[snapshots](guide/analytics.qmd): the same snapshot version re-reads
+[snapshots](/edc-core/guide/analytics/): the same snapshot version re-reads
identically forever, so a transfer can be reconciled against its exact
source at any later date.
@@ -130,14 +130,14 @@ any migration.
The path to a defensible database lock, in system terms:
1. Resolve open queries (the dashboard shows the study-wide count).
-2. Complete [medical coding](guide/medical-coding.qmd) from the work queue.
+2. Complete [medical coding](/edc-core/guide/medical-coding/) from the work queue.
3. Walk forms through the workflow: `complete`, `verified` where your plan
requires it, investigator-`signed`, then `locked`, which restricts edit
access exactly as §3.16.1(r) expects before final analysis.
4. Publish a snapshot: an immutable, version-pinned dataset that interim or
final analysis references (traceability row E6-07).
-Analysis-side, [workbench](guide/analytics.qmd) SQL, R, and Python executions
+Analysis-side, [workbench](/edc-core/guide/analytics/) SQL, R, and Python executions
record their snapshot version, full code, logs, and outputs; data extraction
is documented by construction (§4.2.6(c)).
@@ -153,7 +153,7 @@ metadata for every build, Dataset-JSON and CSV data pinned to a snapshot,
the complete audit trail as CSV, the signature manifest, and per-subject PDF
casebooks, retrievable and human-readable long after the running system is
gone. In-system, records are protected by role-based access, the append-only
-audit trail, and the [deployment controls](deployment.qmd) (TLS, encrypted
+audit trail, and the [deployment controls](/edc-core/deployment/) (TLS, encrypted
volumes, paired database + lake backups sized to your retention period).
**Yours to decide:** the retention period itself (per study, per applicable
@@ -195,11 +195,11 @@ Two governance topics sit beside the lifecycle elements:
Assessing an unplanned unblinding's impact on trial results (§4.1.4) is
yours to decide and document.
- **Computerised systems** (§4.3): validation evidence ships per release as
- the [validation pack](compliance.qmd); security controls, backup, and
- monitoring are the [deployment page](deployment.qmd). Training (§4.3.2)
+ the [validation pack](/edc-core/compliance/); security controls, backup, and
+ monitoring are the [deployment page](/edc-core/deployment/). Training (§4.3.2)
and your documented procedures for system use (§4.3.1) are organizational;
this user guide is raw material for them, not a substitute.
Section references are to the ICH E6(R3) guideline (adopted January 2025),
Annex 1; the requirement-by-requirement map with test evidence is the
-[traceability matrix](compliance.qmd).
+[traceability matrix](/edc-core/compliance/).
diff --git a/site/deployment.qmd b/site/src/content/docs/deployment.md
similarity index 96%
rename from site/deployment.qmd
rename to site/src/content/docs/deployment.md
index 9d5df09..6bfb55a 100644
--- a/site/deployment.qmd
+++ b/site/src/content/docs/deployment.md
@@ -2,6 +2,7 @@
title: "Deployment"
---
+
Two compose files live in `infra/`. `compose.yaml` is the **local
development stack**: hard-coded database password, no TLS, every service
port published to the host. `compose.prod.yaml` is the **supported
@@ -28,18 +29,16 @@ the compose file. Two profiles cover the supported variations
at a managed PostgreSQL, and drop `engines` on small hosts that don't use
the analytics workbench.
-::: {.callout-warning}
-## One API instance, always
+:::caution[One API instance, always]
The notification and anomaly scheduler runs inside the API process and
assumes a single instance. Never scale the `api` service past one replica;
run a bigger VM instead. See [ADR-0011](https://github.com/tgerke/edc-core/blob/main/docs/adr/0011-single-vm-deployment-and-iac.md).
:::
-To provision the VM itself, see [Installation](installation.qmd).
+To provision the VM itself, see [Installation](/edc-core/installation/).
-::: {.callout-note}
-## Pseudonymized is not anonymous
+:::note[Pseudonymized is not anonymous]
edc-core keeps direct identifiers out of clinical tables by construction:
subjects exist as keys, and the site holds the link to the person. Under GDPR
@@ -86,7 +85,7 @@ they must never be reachable from outside the container network.
With a proxy in front, the API sees the proxy's address unless you tell it
which proxies to trust: set `EDC_TRUST_PROXY` on the API container (`1` for
a single proxy layer you control, a hop count or address/CIDR list for
-multi-hop setups) so the [access log](guide/user-admin.qmd), session
+multi-hop setups) so the [access log](/edc-core/guide/user-admin/), session
records, and IP-change audit events carry the real client address from
`X-Forwarded-For`. Leave it **unset when no proxy is in front**: trusting
the header without a proxy lets any client forge the address that lands in
@@ -211,7 +210,7 @@ Before first real use. Items marked *(wired)* are already handled by
- [ ] Review the authentication knobs against your SOPs
(`EDC_SESSION_IDLE_MINUTES`, `EDC_SESSION_ABSOLUTE_HOURS`,
`EDC_PASSWORD_MIN_LENGTH`, `EDC_MAX_FAILED_LOGINS`, `EDC_LOCKOUT_MINUTES`;
- see [Installation](installation.qmd) for SSO).
+ see [Installation](/edc-core/installation/) for SSO).
- [ ] A decision on user-agent-strict session binding. It is on by default
(a session presented by a different client is revoked). Set
`EDC_SESSION_UA_STRICT=0` only where UA churn is legitimate (managed
@@ -220,9 +219,9 @@ Before first real use. Items marked *(wired)* are already handled by
than revoked (anomaly detection still sees them); record the choice in
your SOPs.
- [ ] One API instance only: the notification scheduler assumes it (see
- [Installation](installation.qmd)).
+ [Installation](/edc-core/installation/)).
- [ ] Pin image tags to a released version; each release ships with its
- [validation pack](compliance.qmd).
+ [validation pack](/edc-core/compliance/).
- [ ] An `access_log` retention job, and a decision recorded for how long you
keep it.
- [ ] Anomaly thresholds reviewed (`EDC_ANOMALY_FAILED_LOGIN_THRESHOLD`,
diff --git a/site/glossary.qmd b/site/src/content/docs/glossary.md
similarity index 76%
rename from site/glossary.qmd
rename to site/src/content/docs/glossary.md
index d9ea089..751bb4e 100644
--- a/site/glossary.qmd
+++ b/site/src/content/docs/glossary.md
@@ -2,6 +2,7 @@
title: "Glossary"
---
+
Clinical data management has a vocabulary problem: half its terms come from
regulation, half from CDISC standards, and the rest from whatever the last
EDC vendor called things. This page defines the terms as edc-core uses them,
@@ -9,30 +10,30 @@ in plain language, with a link to the guide page that treats each one fully.
**Amendment.** A mid-study change to the study definition, made as a new
immutable build followed by an explicit, audited migration of in-flight
-forms. See [Mid-study amendments](guide/amendments.qmd).
+forms. See [Mid-study amendments](/edc-core/guide/amendments/).
**Audit trail.** The permanent record of every create, change, and state
transition in a study: who, when, what changed, and why. In edc-core the
audit tables are append-only at the database level, so history cannot be
-rewritten. See [Review workflows](guide/review.qmd#audit-trail-review).
+rewritten. See [Review workflows](/edc-core/guide/review/#audit-trail-review).
**Biomedical concept.** A CDISC-defined unit of clinical meaning ("systolic
blood pressure") that a protocol schedules and a build turns into concrete
-fields. Used by the [protocol import](guide/protocol-import.qmd) path.
+fields. Used by the [protocol import](/edc-core/guide/protocol-import/) path.
**Blinded item.** A field flagged so that only roles with the `data.unblind`
permission can see its value; everyone else sees a locked, masked field.
Typically the treatment arm in a blinded trial. See
-[Blinding](guide/blinding.qmd).
+[Blinding](/edc-core/guide/blinding/).
**Build** (also *study build*, *metadata version*). A versioned, immutable
snapshot of the study definition: events, forms, item groups, items,
codelists, and rules, shaped as CDISC ODM. Everything the system renders
-comes from a build. See [Study builds](guide/study-builds.qmd).
+comes from a build. See [Study builds](/edc-core/guide/study-builds/).
**Casebook.** A PDF rendering of one subject's complete captured data:
current values, correction markers, queries, and the signature manifest.
-See [Exports and the study archive](guide/exports-and-archive.qmd).
+See [Exports and the study archive](/edc-core/guide/exports-and-archive/).
**CDASH.** CDISC's standard for how data collection fields should be named
and structured on CRFs. The demo study's forms are CDASH-aligned.
@@ -48,48 +49,48 @@ across forms.
**ConditionDef.** The ODM construct holding a named true/false expression.
edc-core uses ConditionDefs for both edit checks and skip logic; which job
one does depends on where it is referenced. See
-[Rules and derivations](guide/rules-and-derivations.qmd).
+[Rules and derivations](/edc-core/guide/rules-and-derivations/).
**CRF / eCRF.** Case report form: the form on which a subject's study data
is collected, "e" for electronic. In edc-core, CRFs render directly from the
-build's metadata. See [Data capture](guide/data-capture.qmd).
+build's metadata. See [Data capture](/edc-core/guide/data-capture/).
**Cross-form check.** An edit check that reads the subject's other forms by
qualifying item OIDs with a form OID (`` `FO.DM`.`IT.VISDT` ``). It fires
on writes to any form it reads, and its query opens on its home form. See
-[Rules and derivations](guide/rules-and-derivations.qmd#cross-form-checks).
+[Rules and derivations](/edc-core/guide/rules-and-derivations/#cross-form-checks).
**Data-equivalence.** The machine-checked property that a site's custom form
layout collects exactly the same fields as the sponsor's build, with at
-least the same required flags. See [Site form layouts](guide/site-forms.qmd).
+least the same required flags. See [Site form layouts](/edc-core/guide/site-forms/).
**Dataset-JSON.** The CDISC exchange format (v1.1) for tabular study data,
accepted by FDA. One of the three snapshot export formats. See
-[Exports and the study archive](guide/exports-and-archive.qmd).
+[Exports and the study archive](/edc-core/guide/exports-and-archive/).
**Derived value.** A field the server computes from other answers (BMI from
height and weight) instead of accepting entry. Stored through the audited
write path and permanently marked as derived. See
-[Rules and derivations](guide/rules-and-derivations.qmd).
+[Rules and derivations](/edc-core/guide/rules-and-derivations/).
**Dictionary.** A licensed medical coding vocabulary loaded into edc-core:
MedDRA for adverse events, WHODrug for medications. See
-[Medical coding](guide/medical-coding.qmd).
+[Medical coding](/edc-core/guide/medical-coding/).
**Edit check.** A rule that inspects saved data and flags implausible or
inconsistent values (systolic below 70, end date before start date). A
failing check warns during entry and opens a system query on save. See
-[Rules and derivations](guide/rules-and-derivations.qmd).
+[Rules and derivations](/edc-core/guide/rules-and-derivations/).
**Electronic signature.** A signature applied inside the system, requiring
credential re-entry at the moment of signing and bound by hash to the exact
record versions signed. See
-[Review workflows](guide/review.qmd#electronic-signatures-21-cfr-part-11).
+[Review workflows](/edc-core/guide/review/#electronic-signatures-21-cfr-part-11).
**eTMF.** Electronic trial master file: the system holding a trial's
essential documents. edc-core can file build definitions and snapshot
manifests into an external eTMF automatically. See
-[Exports and the study archive](guide/exports-and-archive.qmd#automatic-etmf-filing).
+[Exports and the study archive](/edc-core/guide/exports-and-archive/#automatic-etmf-filing).
**Event** (also *visit*). A scheduled point in the study (screening, week 4)
that groups the forms collected there. Columns in the subject matrix.
@@ -100,7 +101,7 @@ records the build version it was captured under.
**ICH E6(R3).** The ICH harmonised guideline for Good Clinical Practice,
adopted January 2025: the international ethical, scientific, and quality
-standard for conducting clinical trials. [Compliance](compliance.qmd)
+standard for conducting clinical trials. [Compliance](/edc-core/compliance/)
describes how edc-core maps to it.
**Item / ItemDef.** A single collected field ("What was the systolic blood
@@ -118,26 +119,26 @@ they travel with the study definition.
**Lake.** The per-study analytics store (DuckLake: Parquet files cataloged
in Postgres) that snapshots publish into. The workbench queries the lake,
-never live capture tables. See [Analytics workbench](guide/analytics.qmd).
+never live capture tables. See [Analytics workbench](/edc-core/guide/analytics/).
**Listing.** A workbench query or script whose result rows are
data-cleaning findings: subjects with missing visits, out-of-window dates,
values that disagree across forms. Listing rows can be turned into manual
queries in bulk. See
-[From listings to queries](guide/analytics.qmd#from-listings-to-queries).
+[From listings to queries](/edc-core/guide/analytics/#from-listings-to-queries).
**MedDRA.** The Medical Dictionary for Regulatory Activities, the licensed
terminology used to code adverse events. See
-[Medical coding](guide/medical-coding.qmd).
+[Medical coding](/edc-core/guide/medical-coding/).
**MethodDef.** The ODM construct holding a computation. An item that
references a MethodDef is a derived value. See
-[Rules and derivations](guide/rules-and-derivations.qmd).
+[Rules and derivations](/edc-core/guide/rules-and-derivations/).
**ODM.** CDISC's Operational Data Model, the standard format for study
definitions and clinical data. edc-core's builds are ODM v2.0 documents
(XML or JSON), importable and exportable at any time. See
-[Study builds](guide/study-builds.qmd).
+[Study builds](/edc-core/guide/study-builds/).
**Parquet.** A compressed columnar file format common in analytics tooling.
One of the three snapshot export formats, and the storage format of the lake.
@@ -145,13 +146,13 @@ One of the three snapshot export formats, and the storage format of the lake.
**Part 11** (21 CFR Part 11). FDA's regulation on electronic records and
electronic signatures: the conditions under which they are trustworthy and
equivalent to paper records and handwritten signatures.
-[Compliance](compliance.qmd) describes how edc-core maps to it, and what no
+[Compliance](/edc-core/compliance/) describes how edc-core maps to it, and what no
software can claim on its own.
**Query.** A threaded conversation attached to a form or item questioning
the data. *System queries* open and close automatically with edit checks;
*manual queries* are opened by reviewers and answered by sites. See
-[Review workflows](guide/review.qmd#queries).
+[Review workflows](/edc-core/guide/review/#queries).
**Reason for change.** The explanation required whenever a saved value is
modified. Stored with the old and new value in the audit trail.
@@ -159,49 +160,49 @@ modified. Stored with the old and new value in the audit trail.
**Repeating item group.** An item group collected multiple times within one
form (several blood-pressure readings in one visit), each occurrence stored
and checked independently. See
-[Data capture](guide/data-capture.qmd#repeating-item-groups).
+[Data capture](/edc-core/guide/data-capture/#repeating-item-groups).
**RTSM / IRT.** Randomization and trial supply management (also called
interactive response technology): the external system that randomizes
subjects. edc-core receives its arm assignments; it never randomizes. See
-[RTSM integration](guide/rtsm-integration.qmd).
+[RTSM integration](/edc-core/guide/rtsm-integration/).
**SDV** (source data verification). A monitor's comparison of entered data
against source records, recorded in edc-core as the *verified* workflow
-state. See [Review workflows](guide/review.qmd#source-data-verification).
+state. See [Review workflows](/edc-core/guide/review/#source-data-verification).
**Site form layout.** A site's approved rearrangement of the sponsor's
forms: same fields, different grouping, order, and wording. See
-[Site form layouts](guide/site-forms.qmd).
+[Site form layouts](/edc-core/guide/site-forms/).
**Skip logic.** A rule that marks a field or section as *not collected*
while a condition is true, so the pregnancy-test question disappears when
sex is recorded male. Authored on the
-[rules page](guide/rules-and-derivations.qmd); the entry-side behavior is in
-[Data capture](guide/data-capture.qmd#conditional-and-computed-fields).
+[rules page](/edc-core/guide/rules-and-derivations/); the entry-side behavior is in
+[Data capture](/edc-core/guide/data-capture/#conditional-and-computed-fields).
**Snapshot.** An immutable, point-in-time publication of a study's data
into typed analytics tables. Analyses and locks reference a snapshot ID and
reproduce identically forever. See
-[Analytics workbench](guide/analytics.qmd#snapshots).
+[Analytics workbench](/edc-core/guide/analytics/#snapshots).
**Subject lifecycle status.** A subject's disposition: screening, enrolled,
screen failed, completed, or withdrawn, with reinstatement as the
correction path. Distinct from form workflow states. See
-[Data capture](guide/data-capture.qmd#subject-lifecycle).
+[Data capture](/edc-core/guide/data-capture/#subject-lifecycle).
**USDM.** CDISC's Unified Study Definitions Model, a machine-readable
protocol format. edc-core compiles a USDM v4 package into a candidate study
-build. See [Protocol import](guide/protocol-import.qmd).
+build. See [Protocol import](/edc-core/guide/protocol-import/).
**Verbatim term.** The term exactly as the site reported it ("stomach ake"),
kept unchanged while coding attaches the standardized dictionary term beside
-it. See [Medical coding](guide/medical-coding.qmd).
+it. See [Medical coding](/edc-core/guide/medical-coding/).
**WHODrug.** The licensed drug dictionary from the Uppsala Monitoring
Centre, used to code medications. See
-[Medical coding](guide/medical-coding.qmd).
+[Medical coding](/edc-core/guide/medical-coding/).
**Workflow state.** A form instance's position in the server-enforced state
machine: `not started → in progress → complete → verified → signed →
-locked`. See [Data capture](guide/data-capture.qmd#workflow-states).
+locked`. See [Data capture](/edc-core/guide/data-capture/#workflow-states).
diff --git a/site/guide/amendments.qmd b/site/src/content/docs/guide/amendments.md
similarity index 84%
rename from site/guide/amendments.qmd
rename to site/src/content/docs/guide/amendments.md
index e103a2c..18c66a9 100644
--- a/site/guide/amendments.qmd
+++ b/site/src/content/docs/guide/amendments.md
@@ -2,6 +2,7 @@
title: "Mid-study amendments"
---
+
Protocols change after first patient in. In edc-core an amendment is not an
edit to the live study: it is a **new immutable build**, followed by an
explicit, previewable **migration** of in-flight forms. Nothing moves
@@ -22,9 +23,9 @@ AMD-002) already have entered data. Then protocol amendment 1 lands:
- oxygen saturation (SpO2) is added, with a plausible-range edit check.
Step zero is producing build v2, by any of the
-[usual paths](study-builds.qmd): import the amended ODM file, edit v1 in
+[usual paths](/edc-core/guide/study-builds/): import the amended ODM file, edit v1 in
the visual builder and save, or re-import an amended
-[protocol package](protocol-import.qmd). The moment a study has two or
+[protocol package](/edc-core/guide/protocol-import/). The moment a study has two or
more builds, an **Amendments** panel appears on its study page.
## Step 1: read the diff
@@ -33,7 +34,7 @@ The panel compares any earlier build against the latest, grouped by what
changed: items added, removed, or changed (data type, codelist, length,
mandatory flag), edit checks, events, forms, and codelists.
-{.screenshot fig-alt="The Amendments panel diffing build v1 against v2: weight removed, oxygen saturation added, and a new edit check"}
+
Read it the way a reviewer would: does the diff say exactly what the
protocol amendment says, and nothing else? A surprise entry here (a
@@ -53,7 +54,7 @@ changes, which is why keeping identifiers stable across versions matters.
- values that will **not cast** to a changed data type;
- which **checks will re-run** after migration.
-{.screenshot fig-alt="The impact report: two forms will migrate, entered weight values become orphaned, and the new SpO2 check will re-run"}
+
This report is the amendment's data-management review in one screen. In
the demo: both subjects' forms are eligible, their weight values will be
@@ -97,17 +98,17 @@ An amendment touches more than forms:
still-equivalent layouts carry forward with an audited note, while a
layout the amendment broke goes **stale** and capture falls back to
standard forms until the site resubmits. See
- [Site form layouts](site-forms.qmd#amendments).
+ [Site form layouts](/edc-core/guide/site-forms/#amendments).
- **Protocol-derived builds** amend by importing the amended protocol as a
new protocol version and publishing the next build; the migration
tooling from there is identical. See
- [Protocol import](protocol-import.qmd#amendments).
+ [Protocol import](/edc-core/guide/protocol-import/#amendments).
- **Analytics snapshots** are unaffected by design: each snapshot is
pinned to the data and builds as they stood at publish time, so analyses
against pre-amendment snapshots reproduce forever.
- **Lab-import mappings** that reference a removed item start failing
loudly at validation, which is the intended signal to update the
- mapping. See [Lab data import](lab-import.qmd).
+ mapping. See [Lab data import](/edc-core/guide/lab-import/).
## What leadership should expect to see
@@ -122,9 +123,9 @@ doing the work.
## Where next
-- [Study builds](study-builds.qmd): the versioning model amendments build
+- [Study builds](/edc-core/guide/study-builds/): the versioning model amendments build
on.
-- [Rules and derivations](rules-and-derivations.qmd): what changing a
+- [Rules and derivations](/edc-core/guide/rules-and-derivations/): what changing a
check mid-study means.
-- [Data capture](data-capture.qmd#workflow-states): the workflow states
+- [Data capture](/edc-core/guide/data-capture/#workflow-states): the workflow states
that decide migration eligibility.
diff --git a/site/guide/analytics.qmd b/site/src/content/docs/guide/analytics.md
similarity index 94%
rename from site/guide/analytics.qmd
rename to site/src/content/docs/guide/analytics.md
index a3a4b65..0ba1428 100644
--- a/site/guide/analytics.qmd
+++ b/site/src/content/docs/guide/analytics.md
@@ -2,6 +2,7 @@
title: "Analytics workbench"
---
+
Most EDC systems make operational reporting a vendor-locked afterthought.
edc-core gives data managers **real SQL, R, and Python, inside the EDC**,
against versioned, analysis-ready study datasets.
@@ -24,7 +25,7 @@ snapshot ID and are reproducible indefinitely, even as capture continues.
Pick a snapshot, browse its tables and columns in the schema panel, and query
with DuckDB SQL:
-{.screenshot fig-alt="SQL workbench"}
+
Every run executes in a locked-down, read-only session that can only see the
selected study's snapshot (isolation is physical, at attach time, not a
@@ -52,11 +53,11 @@ browser; scripts can be **saved and versioned** per study, and the execution
history (code, logs, outputs, who and when) is retained and audited. This
directly serves ICH E6(R3)'s expectation of traceable data transformations.
-{.screenshot fig-alt="R workbench with execution history"}
+
-{.screenshot fig-alt="Python workbench with a pandas result grid"}
+
-::: {.callout-note}
+:::note
The workbench is for *operational* analytics: data cleaning status, accrual,
query aging, dataset review. It is deliberately not a validated statistical
compute environment: statistical deliverables should be produced in your
@@ -106,7 +107,6 @@ shows exactly why it will skip:
| `site_forbidden` | `query.manage` is checked per target's site, so a site-scoped reviewer gets skips for other sites' rows rather than a failed batch. |
| `form_locked` | Locked forms take no new queries. |
-: {tbl-colwidths="[30,70]"}
**Snapshot evidence, live targets.** The sandbox boundary does not move for
this feature: engines still read only snapshots. What changes is that the
@@ -119,7 +119,7 @@ silently queried. The endpoint also accepts `force`, which waives only the
though the value moved.
**What comes out is ordinary queries.** Created queries enter the normal
-[query lifecycle](review.qmd#queries): same threads, same dashboard, same
+[query lifecycle](/edc-core/guide/review/#queries): same threads, same dashboard, same
site workflow. What they add is provenance: each records the workbench
execution it came from, and its `query.opened` audit event carries the
batch, execution, snapshot, lake version, and the script and script version
@@ -137,7 +137,7 @@ the **study archive** bundles the whole study (every build's ODM, all
datasets, the audit trail, signatures, casebooks) into one self-contained
zip. When to use which format, what a casebook contains, and what the
archive is for are covered on
-[Exports, casebooks, and the study archive](exports-and-archive.qmd).
+[Exports, casebooks, and the study archive](/edc-core/guide/exports-and-archive/).
## Permissions
diff --git a/site/guide/blinding.qmd b/site/src/content/docs/guide/blinding.md
similarity index 82%
rename from site/guide/blinding.qmd
rename to site/src/content/docs/guide/blinding.md
index fabe772..2bfecf9 100644
--- a/site/guide/blinding.qmd
+++ b/site/src/content/docs/guide/blinding.md
@@ -2,6 +2,7 @@
title: "Blinding"
---
+
In a blinded trial, some values (most often the treatment arm) must be
invisible to some people while staying real, versioned, audited data. In
edc-core, blinding is a flag on the item definition, enforced everywhere
@@ -35,12 +36,12 @@ the administered dose. The site coordinator, holding `data.unblind` as an
entry role, sees a normal form; entering a dose next to a visible arm
feels like entering anything else:
-{.screenshot fig-alt="The dosing form as the site coordinator sees it: the assigned arm is visible alongside the dose fields"}
+
The monitor opens the same form and sees the item's presence and entry
status, but never its value:
-{.screenshot fig-alt="The same dosing form as the monitor sees it: the arm field is locked and shows a blinded placeholder instead of the value"}
+
That is the whole user-facing contract: the blinded reviewer can still
verify the form was filled, query it, and see *that* the arm changed in
@@ -67,13 +68,13 @@ In the builder, tick **Blinded** on the item; in an ODM file, set
other features:
- **Arm assignments from an RTSM should land on a blinded item.** The
- [RTSM integration](rtsm-integration.qmd) writes through a service
+ [RTSM integration](/edc-core/guide/rtsm-integration/) writes through a service
account whose unblind grant is write-only in practice, so the arm is
masked everywhere from the moment it arrives.
- **Blinded items are never codable**, and edit checks that reference
blinded items must not reveal the value in their message text; the
build importer warns about both. See
- [Rules and derivations](rules-and-derivations.qmd#pitfalls).
+ [Rules and derivations](/edc-core/guide/rules-and-derivations/#pitfalls).
## Breaking the blind
@@ -83,7 +84,7 @@ matrix: **Break the blind…** on the subject's status menu, taking a
category (planned, or unplanned: emergency, inadvertent, other) and a
required reason.
-{.screenshot fig-alt="The subject matrix with the break-the-blind confirmation open: a category selector and required reason before anything is recorded"}
+
The action writes an append-only `subject.unblinded` audit event and marks
the subject with an **unblinded** badge, and the event prints in the
@@ -100,7 +101,7 @@ subject's casebook. Two boundaries are deliberate:
## Governance
Access to blinded data is a grant, not a setting. The
-[team page](user-admin.qmd#study-teams) shows who holds `data.unblind`,
+[team page](/edc-core/guide/user-admin/#study-teams) shows who holds `data.unblind`,
at what scope, granted when and by whom; revoking it takes effect
immediately. System administrators deliberately have no bypass: without a
study role carrying the permission, an administrator sees `[BLINDED]`
@@ -111,8 +112,8 @@ unblinding's impact on trial results remains your organization's call.
## Where next
-- [RTSM integration](rtsm-integration.qmd): how the arm arrives without a
+- [RTSM integration](/edc-core/guide/rtsm-integration/): how the arm arrives without a
human ever typing it.
-- [Data capture](data-capture.qmd#blinded-items): the entry-side summary.
-- [User administration](user-admin.qmd): granting and revoking
+- [Data capture](/edc-core/guide/data-capture/#blinded-items): the entry-side summary.
+- [User administration](/edc-core/guide/user-admin/): granting and revoking
`data.unblind`.
diff --git a/site/guide/data-capture.qmd b/site/src/content/docs/guide/data-capture.md
similarity index 84%
rename from site/guide/data-capture.qmd
rename to site/src/content/docs/guide/data-capture.md
index f013315..ebd7fe4 100644
--- a/site/guide/data-capture.qmd
+++ b/site/src/content/docs/guide/data-capture.md
@@ -2,6 +2,7 @@
title: "Data capture"
---
+
## The subject matrix
Each study's home for site staff is the subject matrix: subjects as rows,
@@ -9,7 +10,7 @@ scheduled events and forms as columns, with each cell showing that form's
workflow state. Coordinators enroll subjects here and jump straight into
entry.
-{.screenshot fig-alt="Subject matrix"}
+
Site-scoped roles (coordinator, investigator) see only their site's subjects;
study-scoped roles (data manager, monitor) see all sites.
@@ -31,14 +32,14 @@ Transitions happen inline on the matrix: the menu next to the subject's
badge offers only the moves the current status allows, and terminal moves
prompt for their reason before anything is recorded.
-{.screenshot fig-alt="The subject matrix with a lifecycle transition in progress: DEMO-003's screen-fail action prompting for a required reason"}
+
To walk the whole cycle in the demo: as `demo-coord`, register a new
subject with status *screening*, **Enroll** them, then **Withdraw…** with a
reason, and finally **Reinstate…** (reason again). Each transition, with
its reason and the old and new status, is now in the audit trail, and the
matrix badge tracked every step. Each subject's row also offers their
-[PDF casebook](analytics.qmd#exports-and-the-study-archive) for download
+[PDF casebook](/edc-core/guide/analytics/#exports-and-the-study-archive) for download
(with `export.data`).
Two deliberate boundaries:
@@ -60,11 +61,11 @@ CRFs render directly from the study build's metadata: field types, required
flags, units, and codelists all come from the ODM item definitions. Failing
edit checks surface immediately as you type, before anything is saved. The
exception is a [cross-form
-check](rules-and-derivations.qmd#cross-form-checks), which compares against
+check](/edc-core/guide/rules-and-derivations/#cross-form-checks), which compares against
the subject's other forms: the browser never loads those, so its findings
arrive with the save response, marked **checked on save**.
-{.screenshot fig-alt="Metadata-driven CRF with edit checks and query panel"}
+
Saving writes each item value as a new immutable version row, in the same
database transaction as its audit event. **Changing a saved value requires a
@@ -72,13 +73,13 @@ reason for change**, and the previous value is never overwritten; the full
version history stays queryable and appears in the audit trail.
Values can also arrive in bulk from a central lab's batch file, through the
-same audited write path; see [Lab data import](lab-import.qmd). Verbatim
+same audited write path; see [Lab data import](/edc-core/guide/lab-import/). Verbatim
AE and medication terms entered here are standardized later by data
-management; see [Medical coding](medical-coding.qmd).
+management; see [Medical coding](/edc-core/guide/medical-coding/).
## Conditional and computed fields
-Builds that use [dynamic fields](study-builds.qmd#dynamic-fields) change the
+Builds that use [dynamic fields](/edc-core/guide/study-builds/#dynamic-fields) change the
form as answers land, evaluated instantly in the browser and re-checked by the
server on every write:
@@ -102,7 +103,7 @@ server on every write:
`item_value.derived`. Entering into a computed field is rejected — on every
path, including lab import and RTSM intake.
-{.screenshot fig-alt="Demographics form where selecting Male hides the pregnancy-test field, and a retained value shows a not-collected badge with a Clear button"}
+
## Repeating item groups
@@ -114,7 +115,7 @@ opens a system query pinned to that occurrence: fixing occurrence 2 never
touches occurrence 1. Analytics snapshots carry the occurrence as
`item_group_repeat_key` in the dataset grain.
-{.screenshot fig-alt="Repeating item group with two occurrences and a per-occurrence edit check"}
+
## Workflow states
@@ -140,7 +141,7 @@ the same mask follows the data into casebooks, audit review, and analytics
snapshots. Blinded values are still captured, versioned, and audited
normally: blinding scopes *visibility*, not collection. What each role
sees, the break-the-blind workflow, and the governance around
-`data.unblind` grants are on the [blinding page](blinding.qmd).
+`data.unblind` grants are on the [blinding page](/edc-core/guide/blinding/).
## System queries from edit checks
@@ -148,8 +149,8 @@ When a saved value fails an edit check, edc-core opens a **system query** on
that item automatically. The query thread lives on the form (visible in the
screenshot above) and in the study-wide queries dashboard. Correct the data
and the system query closes itself; the resolution is audited like everything
-else. A [cross-form check](rules-and-derivations.qmd#cross-form-checks)
+else. A [cross-form check](/edc-core/guide/rules-and-derivations/#cross-form-checks)
follows the same mechanics with one twist: its query opens on the check's
home form, so a save on a different form can open or close a query here.
Manual queries work the same way; see
-[Review workflows](review.qmd).
+[Review workflows](/edc-core/guide/review/).
diff --git a/site/guide/exports-and-archive.qmd b/site/src/content/docs/guide/exports-and-archive.md
similarity index 86%
rename from site/guide/exports-and-archive.qmd
rename to site/src/content/docs/guide/exports-and-archive.md
index 0f8e216..e69ab8e 100644
--- a/site/guide/exports-and-archive.qmd
+++ b/site/src/content/docs/guide/exports-and-archive.md
@@ -2,6 +2,7 @@
title: "Exports, casebooks, and the study archive"
---
+
Sooner or later the data has to leave: to biostatistics, to a submission,
to a sponsor handover, to a records room that will outlive every vendor
contract. edc-core's exit paths are deliberately boring: open formats,
@@ -15,7 +16,7 @@ demo).
## Snapshots are the export boundary
-Everything exports from a [snapshot](analytics.qmd#snapshots), never from
+Everything exports from a [snapshot](/edc-core/guide/analytics/#snapshots), never from
live capture tables. That is what makes an export defensible: a snapshot
is an immutable, point-in-time dataset, so the file you sent to
biostatistics in March re-reads identically in November, no matter how
@@ -24,10 +25,10 @@ fresh snapshot; the old one stays.
## Table exports
-On the [workbench](analytics.qmd), every snapshot table card offers its
+On the [workbench](/edc-core/guide/analytics/), every snapshot table card offers its
download links:
-{.screenshot fig-alt="Workbench table cards with per-table CSV, Parquet, and Dataset-JSON export links against a pinned snapshot"}
+
Three formats, three audiences:
@@ -41,7 +42,7 @@ Three formats, three audiences:
Tables are one per ODM item group (`ig_vs`, `ig_ae`, …) plus `subjects`,
`queries`, and `codings`, with repeating groups carried as
-`item_group_repeat_key`. [Blinded items](blinding.qmd) are absent from
+`item_group_repeat_key`. [Blinded items](/edc-core/guide/blinding/) are absent from
snapshots by construction, so every export is blinded without anyone
remembering to mask a column.
@@ -76,7 +77,7 @@ the point: retention obligations run long after any system is
decommissioned. Retrieval and retention duties under ICH E6(R3) §4.2.7,
and what remains procedural (the retention period itself, storage
location, periodic retrieval checks), are covered in the
-[data lifecycle](../data-lifecycle.qmd) page.
+[data lifecycle](/edc-core/data-lifecycle/) page.
For CRO and sponsor leadership evaluating exit risk: this archive *is*
the exit path. A study can be handed to a sponsor, a successor CRO, or a
@@ -111,8 +112,8 @@ Like all grants, both are per-study and audited.
## Where next
-- [Analytics workbench](analytics.qmd): querying snapshots before
+- [Analytics workbench](/edc-core/guide/analytics/): querying snapshots before
exporting them.
-- [Blinding](blinding.qmd): why exports can't leak blinded values.
-- [Data lifecycle](../data-lifecycle.qmd): retention, destruction, and
+- [Blinding](/edc-core/guide/blinding/): why exports can't leak blinded values.
+- [Data lifecycle](/edc-core/data-lifecycle/): retention, destruction, and
the procedural side.
diff --git a/site/guide/lab-import.qmd b/site/src/content/docs/guide/lab-import.md
similarity index 95%
rename from site/guide/lab-import.qmd
rename to site/src/content/docs/guide/lab-import.md
index ad09bb7..947766f 100644
--- a/site/guide/lab-import.qmd
+++ b/site/src/content/docs/guide/lab-import.md
@@ -2,6 +2,7 @@
title: "Lab data import"
---
+
Central labs deliver results as batch files. Instead of keying them in,
users with the `data.import` permission (data managers and admins by
default) upload the file, review a dry-run report, and execute. The
@@ -16,7 +17,7 @@ the mapping for that lab, chooses the file, and clicks **Validate**. The
dry-run report says exactly what would happen, per row, before anything is
written:
-{.screenshot fig-alt="The lab import panel after validating a CSV: per-row outcomes including rows that would import, a skipped completed form, and a value conflict, with nothing written yet"}
+
If the report looks right, typing the study name confirms the import, which
runs in the background with a final row-by-row report. The rest of this
@@ -132,5 +133,5 @@ is permanently distinguishable, and each run writes `lab_import.started`
- No unit conversion; the unit is stored verbatim.
- If a form is still pinned to an older build that lacks a mapped item,
its rows are skipped with a message; run the
- [amendment migration](study-builds.qmd#mid-study-amendments) first.
+ [amendment migration](/edc-core/guide/study-builds/#mid-study-amendments) first.
- Mappings cannot be deleted (runs reference them); rename retired ones.
diff --git a/site/guide/medical-coding.qmd b/site/src/content/docs/guide/medical-coding.md
similarity index 97%
rename from site/guide/medical-coding.qmd
rename to site/src/content/docs/guide/medical-coding.md
index b52a2b7..b29d2b9 100644
--- a/site/guide/medical-coding.qmd
+++ b/site/src/content/docs/guide/medical-coding.md
@@ -2,6 +2,7 @@
title: "Medical coding"
---
+
Sites report adverse events and medications in their own words:
"stomach ake", "asprin 81mg". Analysis needs standardized terms:
regulatory datasets pair each verbatim with its dictionary-derived
@@ -96,7 +97,7 @@ record, **not** in the form data:
corrects the verbatim, the coding shows as **stale** on the coding
page until a human confirms or recodes it.
-{.screenshot fig-alt="Medical coding work queue with auto-coded terms and one uncoded verbatim"}
+
**Auto-coding** handles the bulk: one click starts a background run
that assigns every uncoded verbatim exactly matching a dictionary term
diff --git a/site/guide/notifications.qmd b/site/src/content/docs/guide/notifications.md
similarity index 79%
rename from site/guide/notifications.qmd
rename to site/src/content/docs/guide/notifications.md
index c713389..7e24f19 100644
--- a/site/guide/notifications.qmd
+++ b/site/src/content/docs/guide/notifications.md
@@ -2,6 +2,7 @@
title: "Notifications"
---
+
Query aging is mostly waiting: the site doesn't know a query was opened,
the reviewer doesn't know it was answered, the signer doesn't know the
form is ready. edc-core closes those gaps with an in-app inbox (the bell
@@ -19,28 +20,27 @@ to the affected form or page, and can be marked read individually or all
at once. In the demo below, `demo-dm` has opened a manual query on
DEMO-001's vitals, and `demo-inv`, who can answer it, finds it waiting:
-{.screenshot fig-alt="The notification inbox open from the header bell, showing a new-query notification with a deep link to the affected form"}
+
## What notifies whom
| Event | Who is notified |
|---|---|
| Manual query opened | Site staff who can answer it (`query.answer`, at that site) |
-| Queries created from a [workbench listing](analytics.qmd#from-listings-to-queries) | The same site staff, but one summary per site per batch, not one entry per query |
+| Queries created from a [workbench listing](/edc-core/guide/analytics/#from-listings-to-queries) | The same site staff, but one summary per site per batch, not one entry per query |
| Query answered | Reviewers who manage queries (`query.manage`) |
| Form reaches complete or verified | Its potential signers (`data.sign`) |
| Form overdue (optional, see below) | Site data-entry staff |
| Site layout gone stale after an amendment | The site and the sponsor |
| Security anomaly detected | System administrators |
-: {tbl-colwidths="[45,55]"}
Two rules keep the volume honest. Notifications are never sent to the
person who caused the event. And **system queries from edit checks raise
no notifications at all**: they open and close with the data during entry,
and notifying anyone about self-resolving checks would train everyone to
ignore the bell. That holds for
-[cross-form checks](rules-and-derivations.qmd#cross-form-checks) too: a
+[cross-form checks](/edc-core/guide/rules-and-derivations/#cross-form-checks) too: a
save on one form can open a system query on another, and it waits on that
form and the queries dashboard rather than in anyone's inbox.
@@ -56,7 +56,7 @@ sign-ins, is the working loop between sites and reviewers.
## Email delivery
With SMTP configured
-([installation](../installation.qmd#notifications-and-email)), each
+([installation](/edc-core/installation/#notifications-and-email)), each
notification is also sent by email with the same deep link, so site staff
who aren't logged in still hear about queries the day they're opened.
Without SMTP, the in-app inbox works on its own.
@@ -79,13 +79,13 @@ Reminders deduplicate, so a form nags once, not every tick.
For clinical operations, the metric this machinery moves is **query aging**:
the time from query opened to answered to closed. Every hop in that cycle
that used to depend on someone remembering to check a dashboard is now a
-push. The [analytics workbench](analytics.qmd) has the other half: the
+push. The [analytics workbench](/edc-core/guide/analytics/) has the other half: the
`queries` table in every snapshot, where aging is one SQL query away.
## Where next
-- [Review workflows](review.qmd): the query lifecycle these notifications
+- [Review workflows](/edc-core/guide/review/): the query lifecycle these notifications
serve.
-- [Installation](../installation.qmd#notifications-and-email): SMTP setup.
-- [User administration](user-admin.qmd#security-anomalies): the
+- [Installation](/edc-core/installation/#notifications-and-email): SMTP setup.
+- [User administration](/edc-core/guide/user-admin/#security-anomalies): the
administrator-facing anomaly notifications.
diff --git a/site/guide/protocol-import.qmd b/site/src/content/docs/guide/protocol-import.md
similarity index 93%
rename from site/guide/protocol-import.qmd
rename to site/src/content/docs/guide/protocol-import.md
index 1908a9e..cbaf3a1 100644
--- a/site/guide/protocol-import.qmd
+++ b/site/src/content/docs/guide/protocol-import.md
@@ -2,9 +2,10 @@
title: "Protocol import (USDM)"
---
+
The protocol-first build path derives a study build from a CDISC **USDM v4**
protocol package instead of hand-built forms. If you are new to structured
-protocols, read [Why protocol-first?](why-protocol-first.qmd) first; this page
+protocols, read [Why protocol-first?](/edc-core/guide/why-protocol-first/) first; this page
is the how-to.
## What the importer accepts
@@ -42,7 +43,7 @@ biomedical concepts:
carry it. Click the badge to complete it: name the item, set the question
text, datatype, and optional codelist.
-{.screenshot fig-alt="The protocol review screen: the schedule of activities compiled from a USDM package, with per-concept resolution badges and the publish action"}
+
**Publish build** stays disabled until every draft is completed, so a
published build is always capture-ready. Publishing creates a normal study build (the
@@ -109,7 +110,7 @@ resolve`), which map one-to-one onto workbook rows.
Import the amended protocol as a new protocol version: it compiles to a new
candidate, review works the same way, and publishing creates the next build
-version. From there the standard [amendment tooling](study-builds.qmd)
+version. From there the standard [amendment tooling](/edc-core/guide/study-builds/)
applies: diff the builds, analyze the migration, and move in-flight
subjects.
diff --git a/site/guide/review.qmd b/site/src/content/docs/guide/review.md
similarity index 84%
rename from site/guide/review.qmd
rename to site/src/content/docs/guide/review.md
index 681f732..159b0c0 100644
--- a/site/guide/review.qmd
+++ b/site/src/content/docs/guide/review.md
@@ -2,6 +2,7 @@
title: "Review workflows"
---
+
## Queries
Queries are threaded conversations attached to a form or a specific item.
@@ -15,12 +16,12 @@ They come from two places:
Manual queries can also be opened in bulk from a workbench listing: a
cleaning query's result rows become queries, each carrying provenance back
to the exact execution and snapshot that flagged it. See
-[From listings to queries](analytics.qmd#from-listings-to-queries).
+[From listings to queries](/edc-core/guide/analytics/#from-listings-to-queries).
Each study has a queries dashboard showing every query with status, origin,
subject, and the latest message:
-{.screenshot fig-alt="Queries dashboard"}
+
The full lifecycle (`open → answered → closed`, with reopen) is audited, and
open queries are surfaced prominently on the affected form during entry.
@@ -32,7 +33,7 @@ opening a manual query notifies the site staff who can answer it, an answer
notifies the reviewers, and a form reaching complete or verified notifies
its potential signers, in-app and (with SMTP configured) by email. The full
event-to-recipient map, the overdue-reminder scan, and the deliberate
-silences are on the [notifications page](notifications.qmd).
+silences are on the [notifications page](/edc-core/guide/notifications/).
## Source data verification
@@ -47,7 +48,7 @@ the moment of signature**, even mid-session: the signing panel states what
the signature means and that later corrections will invalidate it, and asks
the signer to prove their identity again before anything is recorded.
-{.screenshot fig-alt="The electronic-signature panel on a completed form: a Part 11 statement, credential fields, and the signature meaning, shown before signing"}
+
How the re-authentication happens follows how the account signs in:
@@ -73,9 +74,9 @@ The audit page gives reviewers the study's complete trail, every create,
change, and state transition with actor, timestamp, before/after values, and
reason. Filter by action, entity, and user, or export the trail to CSV.
-{.screenshot fig-alt="Audit trail with filters and CSV export"}
+
Under the hood, audit rows and item-value versions are append-only tables;
PostgreSQL triggers reject `UPDATE` and `DELETE` outright, and the tests prove
it. The trail is also included, in full, in every
-[study archive](analytics.qmd#exports-and-the-study-archive).
+[study archive](/edc-core/guide/analytics/#exports-and-the-study-archive).
diff --git a/site/guide/rtsm-integration.qmd b/site/src/content/docs/guide/rtsm-integration.md
similarity index 91%
rename from site/guide/rtsm-integration.qmd
rename to site/src/content/docs/guide/rtsm-integration.md
index d199013..f1a2cfb 100644
--- a/site/guide/rtsm-integration.qmd
+++ b/site/src/content/docs/guide/rtsm-integration.md
@@ -2,6 +2,7 @@
title: "RTSM integration"
---
+
edc-core does not randomize subjects: randomization and trial supply
management (RTSM/IRT) is deliberately an external system. What edc-core
provides is the receiving end: the RTSM posts each subject's treatment-arm
@@ -23,9 +24,9 @@ dedicated randomization form with a text item for the arm. OIDs are
validated against the latest study build when you save, and every change
is audited with the full before/after. For a blinded trial, mark the arm
item `edc:Blinded="Yes"` in the build: masking then applies everywhere
-by construction (see the [blinding guide](blinding.qmd)).
+by construction (see the [blinding guide](/edc-core/guide/blinding/)).
-{.screenshot fig-alt="The RTSM integration panel: intake configuration pointing at the arm item, API-key management, and the transfer log with an applied assignment"}
+
**2. Mint an API key.** The RTSM authenticates with a study-scoped
bearer token (`edcrtsm_…`). The raw token is shown exactly once at mint
@@ -70,7 +71,7 @@ Unknown subjects are rejected rather than auto-enrolled (enrollment is a
site act), and the rejected event (below) is the discrepancy signal for
reconciliation. Withdrawn and screen-failed subjects are rejected too:
a subject who is out of the study must not silently accept an
-assignment, and [reinstatement](data-capture.qmd#subject-lifecycle) is
+assignment, and [reinstatement](/edc-core/guide/data-capture/#subject-lifecycle) is
the correction path if the disposition is wrong.
## The transfer record
diff --git a/site/guide/rules-and-derivations.qmd b/site/src/content/docs/guide/rules-and-derivations.md
similarity index 91%
rename from site/guide/rules-and-derivations.qmd
rename to site/src/content/docs/guide/rules-and-derivations.md
index 560c891..910ad95 100644
--- a/site/guide/rules-and-derivations.qmd
+++ b/site/src/content/docs/guide/rules-and-derivations.md
@@ -2,6 +2,7 @@
title: "Rules and derivations"
---
+
A study build can do three things with logic: flag implausible data (edit
checks), decide what gets collected (skip logic and dependent options), and
compute values instead of collecting them (derivations). All three are
@@ -9,7 +10,7 @@ authored the same way, in the **Conditions & methods** panel of the study
builder, as small [JSONata](https://jsonata.org) expressions stored inside
the ODM build. This page is the authoring guide; what these rules look like
during data entry is covered in
-[Data capture](data-capture.qmd#conditional-and-computed-fields).
+[Data capture](/edc-core/guide/data-capture/#conditional-and-computed-fields).
**Who does this:** anyone with the `study.manage` permission on the study
(`demo-admin` or `demo-dm` in the seeded demo). Follow along by opening the
@@ -24,7 +25,6 @@ demo study's latest build and clicking **Edit build**.
| Withdraw one option from a choice list | Condition, wired to the option | The same attribute on a `CodeListItem` (vendor extension) |
| Compute a value from other answers | Method, assigned to a field | A `MethodDef` referenced by the item's `MethodOID` |
-: {tbl-colwidths="[34,26,40]"}
The role follows from the wiring, and the builder shows it as a badge on
each rule: an unwired condition is labeled **edit check**, a wired one
@@ -33,7 +33,7 @@ Wiring a condition to a field changes what it does, not just where it
appears: skip logic gates collection and never raises queries, while an
edit check flags data and never hides anything.
-{.screenshot fig-alt="The Conditions & methods panel on the builder page, listing the demo study's edit checks, skip conditions, and BMI derivation with role badges"}
+
## JSONata in ten minutes
@@ -110,7 +110,7 @@ As `demo-admin`, open the demo study, open the latest build, and click
**Expression does not parse** with the parser's reason, immediately and
before anything is saved:
-{.screenshot fig-alt="Editing a condition expression in the builder, with the live syntax checker reporting that the expression does not parse"}
+
4. Leave it unwired: an unreferenced condition runs as an edit check.
5. Click **Save as new build**. The draft is validated whole and written as
@@ -119,7 +119,7 @@ As `demo-admin`, open the demo study, open the latest build, and click
Nothing you type is persisted until that save, so experimenting is free.
Existing forms keep the build they were captured under; moving them to the
-new build is an explicit [amendment migration](amendments.qmd).
+new build is an explicit [amendment migration](/edc-core/guide/amendments/).
## Walkthrough: skip logic and dependent options
@@ -138,7 +138,7 @@ Two things follow from the wiring:
becomes skipped; it is retained, badged **not collected**, and queried
until the site resolves it. The entry-side behavior, including the
retained-value workflow, is described in
- [Data capture](data-capture.qmd#conditional-and-computed-fields).
+ [Data capture](/edc-core/guide/data-capture/#conditional-and-computed-fields).
The same mechanism, referenced from a codelist option instead of a field,
withdraws that one option while the condition is true: the demo study
@@ -252,7 +252,7 @@ Round-tripping is a tested property; option-level skip references use the
## Pitfalls
- **Check messages are visible to everyone who sees the form.** Edit checks
- may reference [blinded items](blinding.qmd), but the description text is
+ may reference [blinded items](/edc-core/guide/blinding/), but the description text is
shown to blinded roles too; never word a message so it reveals the value.
The importer warns when a check references a blinded item.
- **A wired condition never raises queries.** If you want both behaviors
@@ -261,13 +261,13 @@ Round-tripping is a tested property; option-level skip references use the
an item affects every form that references that item.
- **Rules version with the build.** Tightening a check mid-study is an
amendment; when migrated forms re-run the new check, expect new system
- queries where it fires. The [amendments page](amendments.qmd) shows how
+ queries where it fires. The [amendments page](/edc-core/guide/amendments/) shows how
to preview that before executing.
## Where next
-- [Data capture](data-capture.qmd#conditional-and-computed-fields): what
+- [Data capture](/edc-core/guide/data-capture/#conditional-and-computed-fields): what
sites see when these rules run.
-- [Amendments](amendments.qmd): changing rules on a study that already has
+- [Amendments](/edc-core/guide/amendments/): changing rules on a study that already has
data.
-- [Study builds](study-builds.qmd): the build model these rules live in.
+- [Study builds](/edc-core/guide/study-builds/): the build model these rules live in.
diff --git a/site/guide/site-forms.qmd b/site/src/content/docs/guide/site-forms.md
similarity index 88%
rename from site/guide/site-forms.qmd
rename to site/src/content/docs/guide/site-forms.md
index 1270f5f..87a1a86 100644
--- a/site/guide/site-forms.qmd
+++ b/site/src/content/docs/guide/site-forms.md
@@ -2,6 +2,7 @@
title: "Site form layouts"
---
+
The sponsor's build defines *what* every site collects. Site form layouts let
each site decide *how*: regroup the fields of a visit into the forms that
match its clinic flow, reorder them, and relabel questions in the wording its
@@ -9,7 +10,7 @@ staff actually use. The data never changes: a layout only rearranges
references to the build's fields, and the system proves that on every edit.
This is the site half of the same idea as the
-[protocol-first path](why-protocol-first.qmd): the protocol (or the sponsor's
+[protocol-first path](/edc-core/guide/why-protocol-first/): the protocol (or the sponsor's
build) governs the data; presentation is adaptable per stakeholder.
A concrete example, using the demo study: Tampa General's screening visit
@@ -35,7 +36,7 @@ Open **site forms** from the study page (you need the site-scoped
drop, add, or weaken a field is flagged immediately; you cannot submit
until it's clean.
- {.screenshot fig-alt="The site form layout editor with a draft layout open and the live data-equivalence panel confirming the layout still collects the sponsor's fields"}
+ 
3. **Submit for approval.** The sponsor sees your layout with the equivalence
check already passed, so the review is about workflow, not data. You'll
@@ -43,7 +44,7 @@ Open **site forms** from the study page (you need the site-scoped
4. **Capture through it.** Once approved, the capture launcher on the same
page opens your layout's forms for your site's subjects. Data entry,
queries, signatures, and edit checks behave exactly as on standard forms.
- So do [dynamic fields](data-capture.qmd#conditional-and-computed-fields):
+ So do [dynamic fields](/edc-core/guide/data-capture/#conditional-and-computed-fields):
skip logic and computed values are protocol semantics, not layout, and
follow each item into every variant.
@@ -57,7 +58,7 @@ already passed structural data-equivalence validation (the badge is
machine-checked, not self-declared), so the decision is whether the workflow
is acceptable, with an optional note back to the site.
-{.screenshot fig-alt="The sponsor's layout approval queue with a submitted site layout awaiting an approve or request-changes decision"}
+
The part that matters for data management: captured values are identical in
shape regardless of layout. Value rows key on the build's canonical field and
diff --git a/site/guide/study-builds.qmd b/site/src/content/docs/guide/study-builds.md
similarity index 91%
rename from site/guide/study-builds.qmd
rename to site/src/content/docs/guide/study-builds.md
index a4efb24..611174b 100644
--- a/site/guide/study-builds.qmd
+++ b/site/src/content/docs/guide/study-builds.md
@@ -2,6 +2,7 @@
title: "Study builds"
---
+
A *study build* is a versioned, immutable snapshot of your study definition
(events, forms, item groups, items, codelists, and edit checks), shaped as
CDISC ODM v2.0. Everything else in edc-core renders from it: CRFs, the subject
@@ -23,13 +24,13 @@ layouts, embedded clinical data) are dropped **with an explicit warning for
each**. Review the import warnings before using a converted build.
{.screenshot}
+JSON.](../../../assets/screenshots/study-overview.png)
**Use the visual builder.** Every build can be opened in the study builder: a
tree of events and forms with a live, interactive preview of each CRF exactly
as data entry will render it.
-{.screenshot fig-alt="Study builder with event/form tree and live form preview"}
+
With the `study.manage` permission, **Edit build** switches the builder into a
point-and-click editor: rename forms and sections, add or delete events, forms,
@@ -38,7 +39,7 @@ assign codelists, toggle required/repeating flags, and wire skip conditions
and derivation methods to fields and sections. The **Conditions & methods**
panel below the form editor manages the rules themselves; JSONata expressions
are syntax-checked as you type, and
-[Rules and derivations](rules-and-derivations.qmd) is the full authoring
+[Rules and derivations](/edc-core/guide/rules-and-derivations/) is the full authoring
guide. Nothing is persisted
while you work. **Save as new build** validates the draft and writes it
through the same import path as a file, creating the next immutable version.
@@ -46,7 +47,7 @@ A study with no builds yet offers a **start from scratch** shortcut that
creates a minimal first build to edit. (Item definitions are shared: editing a
question changes every form that references that item.)
-{.screenshot fig-alt="Study builder in edit mode with an expanded item editor"}
+
**Script it.** Because file-driven and point-and-click builds hit the same
versioned-metadata API, builds are automatable: generate ODM from your
@@ -70,7 +71,7 @@ migration. Two rules are deliberate: signed and locked forms never migrate
(their signatures bind to the build they were signed under), and values
orphaned by removed items are never deleted. The full walkthrough, with the
impact report explained line by line, is on the
-[amendments page](amendments.qmd).
+[amendments page](/edc-core/guide/amendments/).
## Edit checks
@@ -84,7 +85,7 @@ includes three:
A failing check warns instantly during entry and, on save, raises a **system
query** attached to the item. When the data is corrected, the query closes
-automatically. See [Data capture](data-capture.qmd).
+automatically. See [Data capture](/edc-core/guide/data-capture/).
## Dynamic fields
@@ -120,4 +121,4 @@ be authored in the builder's rules panel and item editors, or imported inside
an ODM file; both land in the same build. What happens
at the point of entry — fields appearing and disappearing, retained values
that need clearing, read-only computed fields — is covered in
-[Data capture](data-capture.qmd).
+[Data capture](/edc-core/guide/data-capture/).
diff --git a/site/guide/user-admin.qmd b/site/src/content/docs/guide/user-admin.md
similarity index 90%
rename from site/guide/user-admin.qmd
rename to site/src/content/docs/guide/user-admin.md
index 9f23906..ead32de 100644
--- a/site/guide/user-admin.qmd
+++ b/site/src/content/docs/guide/user-admin.md
@@ -2,6 +2,7 @@
title: "User administration"
---
+
Accounts and access are administered in two places: a system-wide *Users*
page for account lifecycle, and a per-study *Team* page for role grants.
Both write every action to the audit trail.
@@ -14,7 +15,7 @@ requires signatures to stay attributable to one individual indefinitely,
so a departed user's account is switched off but their name remains on
everything they signed.
-{.screenshot fig-alt="Users administration page with account creation and lifecycle actions"}
+
Creating an account takes a username, email, full name, and one choice:
@@ -58,7 +59,7 @@ member of the study can see the team (who holds which role, at which
scope, granted when and by whom), since that is their own delegation
context.
-{.screenshot fig-alt="Study team page listing role grants with their scopes"} Changing the team requires the `roles.grant` permission (held
+ Changing the team requires the `roles.grant` permission (held
by the `admin` role by default; system administrators can also grant, so
a brand-new study's first grant is reachable).
@@ -96,7 +97,7 @@ or status code, and export the current view to CSV for an inspection
copy. Retention is your deployment's call; the table is ordinary
operational data, separate from the append-only audit trail.
-{.screenshot fig-alt="Access log with per-request rows and filters"}
+
Sessions are also **bound to the client they were issued to**. A session
token presented by a different browser than the one that signed in is
@@ -116,8 +117,8 @@ anomaly**. Findings notify system administrators and wait under
acknowledging one, with a note on what was done, writes the recorded
response to the audit trail.
-{.screenshot fig-alt="Security anomalies review page with open findings and acknowledge actions"}
+
Detection thresholds and the operational side (what to put in your
SOPs, how this relates to platform monitoring) are covered in the
-[deployment guide](../deployment.qmd#security-anomaly-detection).
+[deployment guide](/edc-core/deployment/#security-anomaly-detection).
diff --git a/site/guide/why-protocol-first.qmd b/site/src/content/docs/guide/why-protocol-first.md
similarity index 98%
rename from site/guide/why-protocol-first.qmd
rename to site/src/content/docs/guide/why-protocol-first.md
index 5a77919..5da26df 100644
--- a/site/guide/why-protocol-first.qmd
+++ b/site/src/content/docs/guide/why-protocol-first.md
@@ -2,6 +2,7 @@
title: "Why protocol-first?"
---
+
edc-core can build a study two broad ways: you can design the forms yourself
(ODM import, the visual builder, or a script), or you can hand it a structured
protocol and let it derive the data requirements for you. This page explains
@@ -97,7 +98,7 @@ the same versioned build store.
- **You have (or can produce) a USDM package**, from a study design tool, a
vendor export, or the Excel authoring route described in
- [Protocol import](protocol-import.qmd): use the protocol-first path and
+ [Protocol import](/edc-core/guide/protocol-import/): use the protocol-first path and
review the generated build.
- **You have an existing ODM library or CRF book**: import the ODM directly.
- **You are sketching a small study from scratch**: the visual builder is the
diff --git a/site/src/content/docs/index.mdx b/site/src/content/docs/index.mdx
new file mode 100644
index 0000000..073825c
--- /dev/null
+++ b/site/src/content/docs/index.mdx
@@ -0,0 +1,184 @@
+---
+title: edc-core
+description: A modern, open-source Electronic Data Capture system for clinical research
+template: splash
+tableOfContents: false
+hero:
+ title: Electronic Data Capture, built like modern software
+ tagline: >-
+ Commercial EDC platforms are expensive, closed, and dated. The open-source
+ alternatives run on legacy stacks. edc-core is a from-scratch EDC built on
+ modern web technology, an analytics-native data architecture, and CDISC
+ standards, designed so that regulatory expectations (21 CFR Part 11,
+ ICH E6(R3)) are structural properties of the system rather than
+ afterthoughts.
+ actions:
+ - text: Get started
+ link: /edc-core/installation/
+ icon: right-arrow
+ variant: primary
+ - text: Five-minute tour
+ link: /edc-core/tour/
+ variant: secondary
+ - text: GitHub
+ link: https://github.com/tgerke/edc-core
+ icon: github
+ variant: minimal
+---
+
+import { Image } from "astro:assets";
+import workbench from "../../assets/screenshots/workbench-sql.png";
+
+
+
+
+
+
+ The analytics workbench: self-service SQL over an immutable, version-pinned
+ study snapshot.
+
+
+
+
+
+
Why edc-core
+
+
+
+
No vendor lock-in
+
+ AGPL-3.0 licensed: nobody can take this code and sell it back to you as
+ a closed platform.
+
+
+
+
Programmable study builds
+
+ First-class CDISC ODM v2.0 import/export means study builds can be
+ file-driven, code-driven, and LLM-assisted. The visual builder writes
+ through exactly the same versioned-metadata API.
+
+
+
+
Self-service analytics, in the EDC
+
+ Data managers query published study snapshots with real SQL, R, and
+ Python, not a bespoke, vendor-locked reporting layer. Every execution is
+ read-only, sandboxed, version-pinned, and audited. And a listing's rows
+ can become
+ site queries in bulk, so the workbench doubles as the study's
+ data-cleaning surface.
+
+
+
+
Compliance by construction
+
+ Append-only audit trails enforced at the database level, Part 11
+ e-signatures bound to record versions, an audit-trail review UI, and a
+ validation pack shipped with every release.
+
+
+
+
Standards as the interface
+
+ ODM v2.0 (XML + JSON) for metadata, Dataset-JSON v1.1 for data exchange,
+ CDASH-aligned demo CRFs, and a self-contained study archive that
+ outlives the running system.
+
+
+
+
Boring to operate
+
+ The supported production shape is one compose file on a single VM:
+ pinned release images, automatic TLS, paired database-and-lake backups,
+ and cloud-init or Terraform recipes for the major clouds. See
+ Deployment.
+
+ Status: alpha. The full workflow (protocol-first or
+ forms-first build, capture, clean, code, sign, snapshot, analyze with SQL,
+ R, and Python, export) is released as
+ v0.5.0,
+ but edc-core has not yet been used in a production study. Follow progress
+ on GitHub.
+
+
+
diff --git a/site/installation.qmd b/site/src/content/docs/installation.md
similarity index 94%
rename from site/installation.qmd
rename to site/src/content/docs/installation.md
index e06c084..466775a 100644
--- a/site/installation.qmd
+++ b/site/src/content/docs/installation.md
@@ -2,6 +2,7 @@
title: "Installation"
---
+
edc-core ships as a small set of containers: a PostgreSQL system of record, a
Node/TypeScript API, a browser SPA, and sandboxed R and Python engines. One compose file
brings up the whole stack; rootless Podman is the recommended path, and Docker
@@ -21,7 +22,7 @@ The badge boots the full dev stack in a free GitHub Codespace; no local
tools needed, just a GitHub account. After ~3 minutes the web UI opens on
the forwarded port; sign in as `admin` / `edc-demo-admin`, or as any seeded
clinical-role user with the password `edc-demo-users` and take the
-[five-minute tour](tour.qmd). The codespace is yours alone and the study is
+[five-minute tour](/edc-core/tour/). The codespace is yours alone and the study is
fictional; delete it when you're done.
## Quick start
@@ -50,7 +51,7 @@ pnpm --filter @edc-core/api db:bootstrap-admin
This creates a root administrator account and prints its generated
credentials. Sign in with them at .
-{.screenshot fig-alt="The edc-core sign-in screen"}
+
### Seed the demo study (optional, recommended)
@@ -60,7 +61,7 @@ pnpm --filter @edc-core/api db:seed-demo
This creates a complete, CDASH-aligned demo study (`ST.CDASH.DEMO`) with two
sites, one user per clinical role, enrolled subjects, and an open data query:
-everything the [five-minute tour](tour.qmd) uses. The script prints the shared
+everything the [five-minute tour](/edc-core/tour/) uses. The script prints the shared
demo password (override it with the `EDC_DEMO_PASSWORD` environment variable)
and is idempotent: it exits without changes if the demo study already exists.
@@ -128,7 +129,7 @@ ghcr.io/tgerke/edc-core-py-engine
Each release also attaches a **validation pack**: the regulatory traceability
matrix joined to that exact release's automated test results. See
-[Compliance](compliance.qmd).
+[Compliance](/edc-core/compliance/).
## Production install
@@ -147,7 +148,7 @@ docker compose -f compose.prod.yaml exec api pnpm --filter @edc-core/api db:boot
at Caddy (certificates are provisioned and renewed automatically), publishes
nothing else, and sets the production hardening variables for you. The
remaining operational work (encrypted volumes, paired backups, retention
-policy) is the [deployment guide](deployment.qmd).
+policy) is the [deployment guide](/edc-core/deployment/).
### Provisioning the VM
@@ -178,8 +179,7 @@ contract. Each provisions the VM, firewall (SSH restricted to your admin
CIDR), static IP, and encrypted disk, and delegates the install to the same
cloud-init file. Each directory's README is a complete walkthrough.
-::: {.callout-tip}
-## Running edc-core alongside ctms-core
+:::tip[Running edc-core alongside ctms-core]
Everything on this page installs edc-core on its own. To co-deploy it with
[ctms-core](https://github.com/tgerke/ctms-core) (the eTMF/regulatory-document
@@ -190,13 +190,12 @@ install walkthrough covers the combined topology and the pre-wired EDC-to-eTMF
filing credential.
:::
-::: {.callout-warning}
-## The dev stack is not a deployment
+:::caution[The dev stack is not a deployment]
`infra/compose.yaml` (the quick start above) uses a hard-coded database
password and no TLS. It is for local development only; anywhere networked,
use `infra/compose.prod.yaml` and work through the
-[deployment guide](deployment.qmd).
+[deployment guide](/edc-core/deployment/).
:::
## Local development
diff --git a/site/start-here.qmd b/site/src/content/docs/start-here.md
similarity index 55%
rename from site/start-here.qmd
rename to site/src/content/docs/start-here.md
index 5d9b40c..80a34d1 100644
--- a/site/start-here.qmd
+++ b/site/src/content/docs/start-here.md
@@ -1,8 +1,8 @@
---
title: "Start here"
-toc: false
---
+
edc-core is used by people with very different jobs: coordinators keying
visits at a site, data managers building and cleaning studies, monitors
verifying data, and the people accountable for all of it. The guide pages
@@ -10,7 +10,7 @@ serve all of them, but nobody needs to read everything. Pick the track that
matches your role and read in order; each step says why it comes next.
Every track names a demo persona (`demo-coord`, `demo-dm`, `demo-inv`,
-`demo-cra`, `demo-admin`). If you [install the local stack](installation.qmd)
+`demo-cra`, `demo-admin`). If you [install the local stack](/edc-core/installation/)
and seed the demo study, you can sign in as that persona and do each step
yourself rather than just reading about it.
@@ -20,21 +20,21 @@ If terms like eCRF, edit check, and SDV are new, start with vocabulary and a
guided loop before any reference material. Follow along as `demo-coord` for
entry and `demo-dm` for review.
-1. [Glossary](glossary.qmd): skim it once so the rest of the guide reads
+1. [Glossary](/edc-core/glossary/): skim it once so the rest of the guide reads
without stopping to look things up.
-2. [Five-minute tour](tour.qmd): the whole lifecycle (enter → query → verify
+2. [Five-minute tour](/edc-core/tour/): the whole lifecycle (enter → query → verify
→ sign → snapshot → analyze) in one sitting, switching personas at each
step.
-3. [Data capture](guide/data-capture.qmd): the subject matrix, entering
+3. [Data capture](/edc-core/guide/data-capture/): the subject matrix, entering
values, corrections with reasons, and what the form does on its own
(skips, computed fields, repeating groups).
-4. [Review workflows](guide/review.qmd): where queries come from, who
+4. [Review workflows](/edc-core/guide/review/): where queries come from, who
answers them, and what verification and signature mean.
-5. [Medical coding](guide/medical-coding.qmd): why "asprin 81mg" needs a
+5. [Medical coding](/edc-core/guide/medical-coding/): why "asprin 81mg" needs a
dictionary term, and the queue where that happens.
-6. [Analytics workbench](guide/analytics.qmd): the SQL section is enough to
+6. [Analytics workbench](/edc-core/guide/analytics/): the SQL section is enough to
answer "how clean is my study today" yourself, and
- [From listings to queries](guide/analytics.qmd#from-listings-to-queries)
+ [From listings to queries](/edc-core/guide/analytics/#from-listings-to-queries)
turns the answer into site queries.
## Study builders (advanced data managers) {#study-builders}
@@ -43,25 +43,25 @@ You already run studies; this track is about building them in edc-core:
versioned ODM builds, rules, and what happens after go-live. Work as
`demo-dm` or `demo-admin`.
-1. [Study builds](guide/study-builds.qmd): the versioned, immutable build
+1. [Study builds](/edc-core/guide/study-builds/): the versioned, immutable build
model everything else renders from, and the three ways to author one.
-2. [Rules and derivations](guide/rules-and-derivations.qmd): edit checks
+2. [Rules and derivations](/edc-core/guide/rules-and-derivations/): edit checks
(single-form and cross-form), skip logic, and computed values, with a
JSONata primer.
-3. [Why protocol-first?](guide/why-protocol-first.qmd) and
- [Protocol import](guide/protocol-import.qmd): deriving a build from a
+3. [Why protocol-first?](/edc-core/guide/why-protocol-first/) and
+ [Protocol import](/edc-core/guide/protocol-import/): deriving a build from a
USDM protocol package instead of hand-built forms.
-4. [Mid-study amendments](guide/amendments.qmd): diff, impact analysis, and
+4. [Mid-study amendments](/edc-core/guide/amendments/): diff, impact analysis, and
audited migration once the protocol changes under live data.
-5. [Site form layouts](guide/site-forms.qmd): letting sites adapt form
+5. [Site form layouts](/edc-core/guide/site-forms/): letting sites adapt form
presentation while you keep one data shape across the study.
-6. [Lab data import](guide/lab-import.qmd) and
- [RTSM integration](guide/rtsm-integration.qmd): external data through
+6. [Lab data import](/edc-core/guide/lab-import/) and
+ [RTSM integration](/edc-core/guide/rtsm-integration/): external data through
the same audited write path as typed entry.
-7. [Blinding](guide/blinding.qmd): item-level masking, who sees what, and
+7. [Blinding](/edc-core/guide/blinding/): item-level masking, who sees what, and
the break-the-blind record.
-8. [Analytics workbench](guide/analytics.qmd) and
- [Exports and the study archive](guide/exports-and-archive.qmd):
+8. [Analytics workbench](/edc-core/guide/analytics/) and
+ [Exports and the study archive](/edc-core/guide/exports-and-archive/):
snapshots, R and Python against them, and every path data takes out.
## CRO and sponsor leadership {#leadership}
@@ -70,19 +70,19 @@ You are deciding whether to trust a study to this system. This track covers
the compliance posture, oversight evidence, and exit paths; none of it
requires touching a form.
-1. [Why edc-core](index.qmd#why-edc-core): the licensing and architecture
+1. [Why edc-core](/edc-core/#why-edc-core): the licensing and architecture
position in five paragraphs.
-2. [Compliance](compliance.qmd): how the system maps to 21 CFR Part 11 and
+2. [Compliance](/edc-core/compliance/): how the system maps to 21 CFR Part 11 and
ICH E6(R3), what the validation pack contains, and what remains your
organization's responsibility.
-3. [Data lifecycle](data-lifecycle.qmd): the ICH E6(R3) data lifecycle
+3. [Data lifecycle](/edc-core/data-lifecycle/): the ICH E6(R3) data lifecycle
elements, one by one, with how each is handled.
-4. [User administration](guide/user-admin.qmd): account lifecycle, per-study
+4. [User administration](/edc-core/guide/user-admin/): account lifecycle, per-study
role grants, the access log, and security anomaly review, which is the
access-control story an auditor will ask about.
-5. [Exports and the study archive](guide/exports-and-archive.qmd): the exit
+5. [Exports and the study archive](/edc-core/guide/exports-and-archive/): the exit
path, because your data outliving the system is part of the decision.
-6. [Deployment](deployment.qmd): what running this in production actually
+6. [Deployment](/edc-core/deployment/): what running this in production actually
involves, whether or not you operate it yourself.
## Clinical operations and site staff {#clinical-ops}
@@ -91,19 +91,19 @@ Your world is subjects, visits, and queries. This track stays on the
site-facing surfaces. Follow along as `demo-coord` (coordinator) and
`demo-inv` (investigator).
-1. [Five-minute tour](tour.qmd): the fastest way to see what sites, monitors,
+1. [Five-minute tour](/edc-core/tour/): the fastest way to see what sites, monitors,
and data management each do in the system.
-2. [Data capture](guide/data-capture.qmd): the subject matrix, subject
+2. [Data capture](/edc-core/guide/data-capture/): the subject matrix, subject
lifecycle (screening, enrolled, withdrawn, reinstated), entry, and
corrections.
-3. [Site form layouts](guide/site-forms.qmd): reorganizing a visit's forms
+3. [Site form layouts](/edc-core/guide/site-forms/): reorganizing a visit's forms
around your clinic's flow without changing what the study collects.
-4. [Review workflows](guide/review.qmd): answering queries, what the monitor
+4. [Review workflows](/edc-core/guide/review/): answering queries, what the monitor
is doing when a form shows *verified*, and what signing commits you to.
-5. [Notifications](guide/notifications.qmd): how query and signature work
+5. [Notifications](/edc-core/guide/notifications/): how query and signature work
finds you instead of waiting on a dashboard.
-6. [Blinding](guide/blinding.qmd): why some staff see the arm while others
+6. [Blinding](/edc-core/guide/blinding/): why some staff see the arm while others
see a masked field, and what breaking the blind records.
-If none of these fit, the [user guide sidebar](guide/study-builds.qmd) lists
-every page by topic, and the [glossary](glossary.qmd) covers the vocabulary.
+If none of these fit, the [user guide sidebar](/edc-core/guide/study-builds/) lists
+every page by topic, and the [glossary](/edc-core/glossary/) covers the vocabulary.
diff --git a/site/tour.qmd b/site/src/content/docs/tour.md
similarity index 80%
rename from site/tour.qmd
rename to site/src/content/docs/tour.md
index 46927f3..4852eb2 100644
--- a/site/tour.qmd
+++ b/site/src/content/docs/tour.md
@@ -2,6 +2,7 @@
title: "Five-minute tour"
---
+
This tour walks the entire clinical data lifecycle on the seeded demo study,
from data entry with edit checks through query resolution, source data
verification, Part 11 signature, snapshot publication, and self-service
@@ -9,7 +10,7 @@ analytics, switching between the clinical roles that would perform each step
in a real study.
Prerequisite: a running stack with the demo study seeded
-([Installation](installation.qmd)). The demo users are `demo-admin`,
+([Installation](/edc-core/installation/)). The demo users are `demo-admin`,
`demo-dm` (data manager), `demo-inv` (investigator), `demo-coord` (site
coordinator), and `demo-cra` (monitor); they share the password printed by
`db:seed-demo`.
@@ -20,16 +21,16 @@ Sign in as **`demo-coord`**. You land on the studies list. Users only see
studies they've been granted a role on, and site-scoped roles only see their
site's subjects.
-{.screenshot fig-alt="Studies list showing the demo study"}
+
Open the study, then **subjects**. The subject matrix shows every subject ×
event × form and its workflow state at a glance, with each subject's
lifecycle status (screening, enrolled, completed, withdrawn) badged next to
their key:
-{.screenshot fig-alt="Subject matrix with form status per event"}
+
-*Full guide: [Data capture](guide/data-capture.qmd).*
+*Full guide: [Data capture](/edc-core/guide/data-capture/).*
## 2. Correct data and watch the query close itself
@@ -37,7 +38,7 @@ DEMO-002's Vital Signs form is *in progress* with **1 open query**: the seeded
systolic blood pressure (62 mmHg) failed the plausible-range edit check, which
automatically raised a system query.
-{.screenshot fig-alt="Vital Signs entry form with an open system query and edit check warnings"}
+
Enter a plausible value (say `118`) and save, providing a reason for change:
every modification to saved clinical data requires one, and the prior value
@@ -49,7 +50,7 @@ client-side for instant feedback and server-side as the source of truth.
Checks can also read the subject's *other* forms (an AE onset date against
the visit date, say); those run server-side only and come back marked
**checked on save**. See
-[cross-form checks](guide/rules-and-derivations.qmd#cross-form-checks).
+[cross-form checks](/edc-core/guide/rules-and-derivations/#cross-form-checks).
The demo study's forms are dynamic, too. On the Demographics form, the
pregnancy-test question only appears while the subject's recorded sex allows
@@ -76,8 +77,8 @@ DEMO-002:
has closed itself: a write to one form re-evaluates the checks that
read it, wherever their queries live.
-*Full guide: [Data capture](guide/data-capture.qmd#conditional-and-computed-fields)
-for the entry side, [Rules and derivations](guide/rules-and-derivations.qmd)
+*Full guide: [Data capture](/edc-core/guide/data-capture/#conditional-and-computed-fields)
+for the entry side, [Rules and derivations](/edc-core/guide/rules-and-derivations/)
for authoring the checks and computations themselves.*
## 3. Verify as a monitor
@@ -90,10 +91,10 @@ current state allow them.
You can also review every query across the study from the **queries**
dashboard:
-{.screenshot fig-alt="Study-wide query dashboard"}
+
-*Full guide: [Review workflows](guide/review.qmd) and
-[Notifications](guide/notifications.qmd).*
+*Full guide: [Review workflows](/edc-core/guide/review/) and
+[Notifications](/edc-core/guide/notifications/).*
## 4. Sign as the investigator
@@ -103,7 +104,7 @@ signature records name, date/time, and meaning, and is cryptographically bound
(SHA-256) to the exact record versions signed. If the form is later reopened
for editing, the signature is invalidated, visibly and irreversibly.
-*Full guide: [Review workflows](guide/review.qmd#electronic-signatures-21-cfr-part-11).*
+*Full guide: [Review workflows](/edc-core/guide/review/#electronic-signatures-21-cfr-part-11).*
## 5. Review the audit trail
@@ -112,9 +113,9 @@ Any create, change, or state transition you just performed is in the study's
to CSV. Append-only storage is enforced by database triggers, so history
cannot be rewritten even by a buggy application path.
-{.screenshot fig-alt="Audit trail review UI with filters"}
+
-*Full guide: [Review workflows](guide/review.qmd#audit-trail-review).*
+*Full guide: [Review workflows](/edc-core/guide/review/#audit-trail-review).*
## 6. Publish a snapshot and analyze it
@@ -126,14 +127,14 @@ return identical results forever.
Run SQL against the pinned snapshot:
-{.screenshot fig-alt="SQL workbench with query results"}
+
Or switch to the **R** or **Python** tab: scripts execute server-side in
sandboxed containers with `lake_read()` / `lake_query()` helpers (data.frames
in R, pandas DataFrames in Python), and every execution is recorded with its
code, logs, and results:
-{.screenshot fig-alt="R workbench with console output and execution history"}
+
Then close the loop the way a data manager would. A listing that finds
problems can raise queries without re-keying anything. Run:
@@ -153,8 +154,8 @@ hears about the batch once, and each query records the execution and
snapshot that raised it. Run the preview again and every row now reports
an existing query: the loop does not double-file.
-*Full guide: [Analytics workbench](guide/analytics.qmd), and
-[From listings to queries](guide/analytics.qmd#from-listings-to-queries)
+*Full guide: [Analytics workbench](/edc-core/guide/analytics/), and
+[From listings to queries](/edc-core/guide/analytics/#from-listings-to-queries)
for this workflow.*
## 7. Export and archive
@@ -166,10 +167,10 @@ JSON), all datasets, the complete audit trail, the signature manifest, and a
PDF casebook for every subject.
*Full guide: [Exports, casebooks, and the study
-archive](guide/exports-and-archive.qmd).*
+archive](/edc-core/guide/exports-and-archive/).*
That's the whole loop: capture → clean → verify → sign → snapshot → analyze →
archive, with every step audited. And it is a loop, not a line: the analysis
step raises the next round of cleaning queries itself. For details on any
-piece, head to the [user guide](guide/study-builds.qmd) or pick a
-[reading track for your role](start-here.qmd).
+piece, head to the [user guide](/edc-core/guide/study-builds/) or pick a
+[reading track for your role](/edc-core/start-here/).
diff --git a/site/src/styles/custom.css b/site/src/styles/custom.css
new file mode 100644
index 0000000..8d0f26a
--- /dev/null
+++ b/site/src/styles/custom.css
@@ -0,0 +1,217 @@
+/* edc-core design system: zinc palette matching the app chrome, blue accent. */
+
+:root {
+ /* dark theme (Starlight default root) */
+ --sl-color-accent-low: #1e3a8a;
+ --sl-color-accent: #3b82f6;
+ --sl-color-accent-high: #bfdbfe;
+ --sl-color-white: #fafafa; /* zinc-50 */
+ --sl-color-gray-1: #e4e4e7; /* zinc-200 */
+ --sl-color-gray-2: #d4d4d8; /* zinc-300 */
+ --sl-color-gray-3: #a1a1aa; /* zinc-400 */
+ --sl-color-gray-4: #71717a; /* zinc-500 */
+ --sl-color-gray-5: #3f3f46; /* zinc-700 */
+ --sl-color-gray-6: #27272a; /* zinc-800 */
+ --sl-color-black: #18181b; /* zinc-900, the app chrome color */
+
+ --edc-screenshot-border: #3f3f46;
+ --edc-surface: #1f1f23;
+}
+
+:root[data-theme="light"] {
+ --sl-color-accent-low: #dbeafe;
+ --sl-color-accent: #2563eb;
+ --sl-color-accent-high: #1e40af;
+ --sl-color-white: #18181b; /* text: zinc-900 */
+ --sl-color-gray-1: #27272a; /* zinc-800 */
+ --sl-color-gray-2: #3f3f46; /* zinc-700 */
+ --sl-color-gray-3: #52525b; /* zinc-600 */
+ --sl-color-gray-4: #a1a1aa; /* zinc-400 */
+ --sl-color-gray-5: #e4e4e7; /* zinc-200 */
+ --sl-color-gray-6: #f4f4f5; /* zinc-100 */
+ --sl-color-gray-7: #fafafa; /* zinc-50 */
+ --sl-color-black: #ffffff;
+
+ --edc-screenshot-border: #e4e4e7;
+ --edc-surface: #fafafa;
+}
+
+/* Content typography: slightly tighter headings, comfortable measure */
+.sl-markdown-content h2 {
+ letter-spacing: -0.015em;
+}
+
+/* Every content image is an app screenshot: card treatment on a deliberate
+ surface so light-chrome screenshots sit well in dark mode too. */
+.sl-markdown-content img {
+ border: 1px solid var(--edc-screenshot-border);
+ border-radius: 0.75rem;
+ box-shadow: 0 1px 3px rgb(0 0 0 / 8%);
+ background: #ffffff;
+}
+
+/* Tables: quieter borders, zinc header row */
+.sl-markdown-content table {
+ font-size: var(--sl-text-sm);
+}
+.sl-markdown-content th {
+ background: var(--edc-surface);
+}
+
+/* ---------------------------------------------------------------------------
+ Landing page (index.mdx, template: splash)
+--------------------------------------------------------------------------- */
+
+.landing {
+ --landing-max: 72rem;
+}
+
+/* Starlight splash hero: centered, constrained measure, product-style CTAs */
+.hero {
+ padding-block: 3.5rem 1.5rem;
+ grid-template-columns: 1fr;
+}
+
+.hero .copy {
+ align-items: center;
+ text-align: center;
+ margin-inline: auto;
+}
+
+.hero h1 {
+ max-width: 46rem;
+ font-size: clamp(2.2rem, 5vw, 3.5rem);
+ line-height: 1.08;
+ letter-spacing: -0.03em;
+}
+
+.hero .tagline {
+ max-width: 46rem;
+ color: var(--sl-color-gray-3);
+ font-size: var(--sl-text-lg);
+}
+
+.hero .actions {
+ justify-content: center;
+}
+
+.sl-link-button.primary {
+ background: var(--sl-color-accent);
+ border-color: var(--sl-color-accent);
+ color: #ffffff;
+}
+
+.sl-link-button.secondary {
+ border: 1px solid var(--sl-color-gray-5);
+}
+
+.landing-shot {
+ max-width: var(--landing-max);
+ margin: 0 auto 4rem;
+}
+
+.landing-shot img {
+ width: 100%;
+ height: auto;
+ border: 1px solid var(--edc-screenshot-border);
+ border-radius: 0.9rem;
+ box-shadow: 0 20px 50px -20px rgb(0 0 0 / 35%);
+ background: #ffffff;
+}
+
+.landing-shot figcaption {
+ text-align: center;
+ color: var(--sl-color-gray-3);
+ font-size: var(--sl-text-sm);
+ margin-top: 0.9rem;
+}
+
+.landing section {
+ max-width: var(--landing-max);
+ margin: 0 auto 4rem;
+}
+
+.landing h2 {
+ font-size: var(--sl-text-2xl);
+ letter-spacing: -0.02em;
+ text-align: center;
+ margin-bottom: 2rem;
+}
+
+.landing-grid {
+ display: grid;
+ grid-template-columns: repeat(auto-fit, minmax(17rem, 1fr));
+ gap: 1rem;
+}
+
+/* Starlight's content sibling-spacing rule adds margin-top to every card
+ after the first, skewing the grid rows; the gap is the only spacing here. */
+.landing-grid > .landing-card {
+ margin-top: 0 !important;
+}
+
+/* 4-card sections: 4-up on wide screens, 2x2 in between, instead of 3+1 */
+@media (min-width: 72rem) {
+ .landing-grid--4 {
+ grid-template-columns: repeat(4, 1fr);
+ }
+}
+@media (min-width: 40rem) and (max-width: 71.99rem) {
+ .landing-grid--4 {
+ grid-template-columns: repeat(2, 1fr);
+ }
+}
+
+.landing-card {
+ border: 1px solid var(--sl-color-gray-5);
+ border-radius: 0.9rem;
+ padding: 1.4rem 1.5rem;
+ background: var(--edc-surface);
+}
+
+.landing-card h3 {
+ font-size: var(--sl-text-base);
+ font-weight: 600;
+ letter-spacing: -0.01em;
+ margin-bottom: 0.6rem;
+}
+
+.landing-card p {
+ font-size: var(--sl-text-sm);
+ color: var(--sl-color-gray-3);
+ line-height: 1.6;
+ margin: 0;
+}
+
+.landing-card p a {
+ color: var(--sl-color-accent-high);
+}
+
+a.landing-card {
+ display: block;
+ text-decoration: none;
+ color: inherit;
+ transition:
+ border-color 120ms ease,
+ transform 120ms ease;
+}
+
+a.landing-card:hover {
+ border-color: var(--sl-color-accent);
+ transform: translateY(-2px);
+}
+
+a.landing-card h3 {
+ color: var(--sl-color-accent-high);
+}
+
+.landing-status {
+ border: 1px solid var(--sl-color-gray-5);
+ border-left: 4px solid var(--sl-color-accent);
+ border-radius: 0.6rem;
+ padding: 1.1rem 1.4rem;
+ font-size: var(--sl-text-sm);
+ color: var(--sl-color-gray-2);
+ max-width: 52rem;
+ margin-inline: auto;
+}
diff --git a/site/theme.scss b/site/theme.scss
deleted file mode 100644
index 2d9f453..0000000
--- a/site/theme.scss
+++ /dev/null
@@ -1,33 +0,0 @@
-/*-- scss:defaults --*/
-
-$font-family-sans-serif: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto,
- "Helvetica Neue", Arial, sans-serif;
-$font-family-monospace: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
-
-$primary: #18181b; // zinc-900, matching the app chrome
-$body-color: #27272a; // zinc-800
-$link-color: #2563eb;
-$navbar-bg: #18181b;
-$code-bg: #f4f4f5; // zinc-100
-$code-color: #18181b;
-
-/*-- scss:rules --*/
-
-// screenshots: subtle card treatment
-img.screenshot,
-.screenshot img {
- border: 1px solid #e4e4e7; // zinc-200
- border-radius: 0.75rem;
- box-shadow: 0 1px 3px rgb(0 0 0 / 8%);
-}
-
-.hero-lead {
- font-size: 1.15rem;
- color: #52525b; // zinc-600
- max-width: 46rem;
-}
-
-figcaption {
- color: #71717a; // zinc-500
- font-size: 0.875rem;
-}
diff --git a/site/tsconfig.json b/site/tsconfig.json
new file mode 100644
index 0000000..8bf91d3
--- /dev/null
+++ b/site/tsconfig.json
@@ -0,0 +1,5 @@
+{
+ "extends": "astro/tsconfigs/strict",
+ "include": [".astro/types.d.ts", "**/*"],
+ "exclude": ["dist"]
+}