SciDEX v2 Substrate — Tutorials

This directory is the onboarding path for anyone new to the v2 substrate. The substrate is a polymorphic, artifact-centric science platform: every persistable thing is an Artifact{type, id, version}, and ~17 typed verbs (scidex.get, list, search, create, update, …) operate across every type. The same Python @verb-decorated functions generate FastAPI HTTP routes and MCP tools — one source, three outputs.

Read the architecture spec first if you haven’t: SPEC-001 — Polymorphic Substrate.

Tutorial map

File	What you’ll learn
getting-started.md	Install the substrate, point it at a _test Postgres database, boot FastAPI, call your first scidex.list verb from curl and from Python.
writing-a-verb.md	Walk through adding a new verb: input / output Pydantic models, the @verb decorator, Context usage, read vs. write semantics, automatic HTTP + MCP exposure.
designing-a-schema.md	Add a brand-new artifact type. JSON Schema layout, id_strategy / lock_mode / mutability, polymorphic envelope fields, auto-registration on boot, and which verbs you get for free.
deploying-substrate.md	Production deployment notes: scidex_v2 database, scidex_v2_app role, the /etc/scidex-substrate/v2-db.env DSN convention, docs/deploy/nginx.conf, systemd unit naming, readiness probes.
agent-developer-guide.md	For AI agents working in this repo: worktree discipline, PR layer prefixes, the multi-worker .pth footgun, test patterns with the _test DSN guard, and the per-task spec policy under docs/planning/specs/.

What should I read first?

Pick by role.

You’re a human contributor / scientist

Start with getting-started.md so the substrate actually runs on your machine. Then read SPEC-001 §5 (artifact model) and SPEC-001 §7 (verbs) so you understand what an artifact and a verb are before you write code. If you want to extend the substrate with new science (a new artifact type like clinical_trial or assay_result), read designing-a-schema.md next. If you want to add a new operation across artifact types (e.g. scidex.papers.cite_count), read writing-a-verb.md.

You’re an AI agent working in this repo

agent-developer-guide.md is mandatory. It encodes the worktree discipline, the PR layer prefixes, and the per-task spec policy from AGENTS.md in a single place, plus the multi-worker install footgun that bites parallel workers. You should also skim writing-a-verb.md and the SPEC-007 test strategy because every verb you ship needs unit + service-layer tests.

You’re an operator / SRE

deploying-substrate.md is your primary doc. Pair it with docs/deploy/README.md (the docker-compose path) and docs/operations/v2-rc-checklist.md (the production readiness gate). Health and readiness probes are documented in deploying-substrate.md §health; use /readyz (not /health) for load-balancer health checks.

You want to skim everything

In order: index → getting-started → writing-a-verb → designing-a-schema → deploying-substrate → agent-developer-guide. Each file is self-contained and cross-references the others when a topic overlaps.

Where to find what’s NOT in tutorials

You want…	Look at…
The full list of registered verbs	GET / on a running substrate, or src/scidex_substrate/skill/verbs/
The full list of artifact types	src/scidex_substrate/schema_registry/default_schemas/
The full SPEC corpus	docs/design/spec-001…spec-191
The v2 production-readiness gate	docs/operations/v2-rc-checklist.md
The release retrospective (M1..M7+)	docs/operations/m_wave_summary.md
Operator runbooks (migrations, restore drills)	docs/operations/*.md
The v1 reference repo (read-only)	/home/ubuntu/scidex on the sandbox

Style of these docs

These tutorials are direct and concrete. They prefer code blocks over prose and they cite source files by absolute path inside the repo, so you can grep them. When something is a design decision rather than an implementation detail, the relevant SPEC section is linked inline. There are no marketing claims, no “you’ll be an expert in 5 minutes,” no emoji.

If a tutorial drifts from the code, the code is right and the tutorial needs a PR. The spec rule from AGENTS.md is the same: when implementation and documentation disagree, update the doc — never let the doc lie about what the code does.