docs(landing): align commands surface and link tutorial as canonical onboarding (#28)

- Add a tutorial admonition at the top of the manual quick-start and list it
  first in the reading order; surface the tutorial early in the README too.
- Rewrite the docs/index.md Commands section to reflect what is actually wired
  today: new Data acquisition + tracking group (get, add, mv, rm, queue, mark),
  move propose-alignment under semantic mapping, separate annotate/config from
  the standard build path, and split out a Stubs / not yet wired group
  (discover, benchmark, read, chat, search).
- Point readers from `biotope add` to the `.biotope.yaml` review +
  `annotate apply` loop for curated metadata that does not fit as CLI flags,
  and fix the annotate entry to describe each subcommand's actual scope
  (dataset/record-set, not field-level).
- README quick-start now mirrors the tutorial's spine (uvx init -> uv sync ->
  get -> add -> queue -> map -> build -> create_knowledge_graph.py -> view)
  and drops `annotate apply` from the minimum path.

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: slobentanzer

README.md

@@ -9,46 +9,54 @@ CLI for the BioCypher ecosystem: Croissant-described data → BioCypher knowledg
 
 **Status: pre-alpha, developer-facing.** APIs and CLI will change. Not yet suitable for end users.
 
+## Start here
+
+The fastest way in is the **[tutorial](https://biocypher.github.io/biotope/tutorial/)**
+— a 15-minute end-to-end walk-through that builds a real knowledge graph from
+public airport/flight data. It is the canonical, most up-to-date onboarding
+path; the snippet below is just a flavour preview.
+
 ## Install
 
 ```bash
-uv pip install biotope             # or
-uv pip install -e ".[dev]"         # editable, with test deps
+uv add biotope                     # in a uv-managed venv
+pipx install biotope               # global install
+uvx biotope init my-kg             # no install: ephemeral venv for the scaffolder
+uv pip install -e ".[dev]"         # editable, with test deps (for biotope itself)
 ```
 
 ## From `init` to a knowledge graph
 
 ```bash
-# 1. Scaffold a project.
-biotope init my-kg --purpose "What approved drugs target genes in T2D?"
-cd my-kg
+# 1. Scaffold a project (uvx works fine here — no local install needed).
+uvx biotope init my-kg --purpose "What approved drugs target genes in T2D?" --no-prompt
+cd my-kg && uv sync
 
-# 2. Declare intent — what entities and relations the graph must contain.
-#    Non-interactive (agent-friendly):
-biotope map --entity gene --entity disease --entity drug \
-            --relation gene_associated_with_disease
+# 2. Bring in data — biotope get downloads + tracks; biotope add stages a
+#    local file/folder and runs croissant-baker over it.
+uv run biotope get https://example.org/opentargets.parquet --output-dir data/ot --no-add
+uv run biotope add data/ot --license CC-BY-4.0 --creator "Open Targets"
 
-# 3. Bring in data and its Croissant metadata.
-biotope add data/opentargets --license CC-BY-4.0 --creator "Open Targets"
-biotope annotate apply data/opentargets        # after reviewing data/opentargets/.biotope.yaml
+# 3. Inspect the pipeline state at any time.
+uv run biotope queue        # raw / processed / mapped, with provenance footer
 
-# 4. Generate an unresolved mapping scaffold from your declared intent.
-#    The file has one slot per entity/relation plus an inspector appendix
-#    listing record sets, field kinds, identifier-like fields, and sample rows.
-biotope map scaffold .biotope/datasets/data/opentargets.jsonld
+# 4. Declare intent — what entities and relations the graph must contain.
+#    Non-interactive (agent-friendly); without flags, `biotope map` opens
+#    a wizard that captures intent and resolves slots in one flow.
+uv run biotope map --entity gene --entity disease --entity drug \
+                   --relation gene_associated_with_disease
 
 # 5. Resolve the slots. Two equivalent paths:
-#    a) Wizard (humans):            biotope map
-#    b) Edit `mappings/*.yaml` directly, then validate (agents):
-#       biotope map inspect <croissant> --json   # field catalogue
-#       biotope map preview --json               # status + projected schema + sample tuples
-
-# 6. Optional: align entities across multiple mappings.
-biotope propose-alignment mappings/*.mapping.yaml --out alignment.yaml
-
-# 7. Build a runnable BioCypher project. Strict: rejects unresolved slots.
-biotope build
-biotope view
+#    a) Wizard (humans):  uv run biotope map
+#    b) Edit mappings/*.mapping.yaml directly, then validate (agents):
+#       uv run biotope map scaffold .biotope/datasets/data/ot.jsonld
+#       uv run biotope map inspect  <croissant> --json   # field catalogue
+#       uv run biotope map preview  --json               # projected schema + tuples
+
+# 6. Build a runnable BioCypher project. Strict: rejects unresolved slots.
+uv run biotope build
+uv run python build/create_knowledge_graph.py
+uv run biotope view
 ```
 
 `biotope init` is a pure scaffolder. All non-autogeneratable metadata is supplied as CLI flags — by a user or an agent reading `AGENTS.md`. Semantic decisions (which record set, which fields, which transforms) are made by the human or copilot; biotope only enumerates options, validates, and previews.
@@ -70,14 +78,17 @@ The agent surface is `AGENTS.md` (template lives at `biotope/templates/AGENTS.md
 
 ```
 init                                project scaffolding
+get add mv rm                       acquisition + tracking (baker writes croissants)
+queue mark                          pipeline-state dashboard + manual transitions
 map (inspect|scaffold|preview)      semantic mapping (intent + wizard + agent path)
-add mv status commit log push pull  git-like metadata VCS
-check-data                          checksum verification
-discover                            registry-aware source ranking
 propose-alignment                   cross-mapping same_node equivalences
-build view benchmark                build + inspect a graph
-read chat                           NLP ingestion, conversation (promises)
-search annotate get config          legacy / auxiliary
+build view                          build + inspect a graph
+status commit log push pull         git-like metadata VCS
+check-data                          checksum verification
+annotate config                     field-level annotation + project config
+
+discover benchmark                  scaffolded but not yet wired into the standard flow
+read chat search                    promises / auxiliary
 ```
 
 `biotope describe` and the heuristic `biotope propose-mapping` were removed/deprecated. Intent capture is now `biotope map --entity ... --relation ...`; scaffolding is `biotope map scaffold`. `propose-mapping` remains as a deprecated alias for the scaffold subcommand.

docs/index.md

@@ -22,6 +22,13 @@ APIs, CLI flags, and config-file layouts will change. End-user docs come after t
 
 ## Quick start: without coding agent
 
+!!! tip "Prefer a worked end-to-end example?"
+
+    The [**Tutorial**](tutorial.md) walks through building a real knowledge graph
+    from public airport/flight data in ~15 minutes. It's the most up-to-date
+    onboarding path and the source of truth for the recommended workflow
+    (`init` → `get` → `add` → `queue` → `map` → `build`).
+
 ```bash
 uv pip install biotope
 
@@ -61,17 +68,24 @@ All semantic decisions (which record set, which fields, which transforms) are ma
 
 - `biotope init` — scaffold a project (`.biotope/`, `AGENTS.md`, `project.yaml`, `git init`).
 
+### Data acquisition + tracking
+
+- `biotope get <url>` — download a file (optionally into `--output-dir`) and, unless `--no-add`, track it.
+- `biotope add <path>` — stage data files or rooted directories; baker writes the Croissant entry under `.biotope/datasets/`. `--derived-from` records provenance for human/agent-extracted derivatives. For curated metadata that doesn't fit as CLI flags (descriptions, citations, per–record-set fields), `add` also drops a `.biotope.yaml` scaffold next to the dataset — review it, then run `biotope annotate apply <dir>` to merge it into the manifest.
+- `biotope mv` / `biotope rm` — move or untrack files and update metadata paths.
+- `biotope queue` — show every dataset grouped by pipeline state (`raw` / `processed` / `mapped`). The recommended dashboard during a build.
+- `biotope mark <dataset> <status>` — manually set a dataset's `biotope:status`.
+
 ### Semantic mapping
 
 - `biotope map` — bare command. If any intent flag (`--purpose`, `--entity`, `--relation`, `--source`, `--notes`, `--clear-*`, `--show`) is passed, it updates `project.yaml` non-interactively. Otherwise it launches the guided wizard.
 - `biotope map inspect <croissant>` — deterministic field catalogue + sample rows. `--json` for agents.
 - `biotope map scaffold <croissant>` — emit an unresolved mapping scaffold with an inspector comment appendix.
 - `biotope map preview [<mapping>]` — validate a (partial) mapping; show projected BioCypher schema + sample tuples. `--json` for agents.
+- `biotope propose-alignment` — propose cross-mapping `same_node` equivalences.
 
 ### Git-like metadata VCS
 
-- `biotope add` — stage data files; baker enriches the Croissant entry under `.biotope/datasets/`.
-- `biotope mv` — move tracked files; updates metadata paths.
 - `biotope status` — show staged/modified files and validation state.
 - `biotope commit` — commit metadata changes.
 - `biotope log` — show metadata commit history.
@@ -80,25 +94,30 @@ All semantic decisions (which record set, which fields, which transforms) are ma
 
 ### Knowledge-graph construction
 
-- `biotope discover` — rank registered adapters and local Croissant files against `required_entities`.
-- `biotope propose-alignment` — propose cross-mapping `same_node` equivalences.
 - `biotope build` — materialise a runnable BioCypher project from mappings + alignment. Emits `config/schema_config.yaml` (with `namespace` and autogenerated `input_label`) and per-mapping generated Python under `build/generated/<stem>/`.
-- `biotope view` — node/edge counts for the most recent build.
-- `biotope benchmark` — quality/coverage metrics (skeleton in v1).
+- `biotope view` — node/edge counts for the most recent build (or project competence questions if no build yet).
+
+### Annotation + project config
+
+- `biotope annotate` — `apply` (merge a curated `.biotope.yaml` scaffold into a dataset's Croissant manifest, with optional `--set dataset.<field>=…` / `--set record_set.<field>=…` overrides), `edit` (interactive annotation), `load` (sample records via the manifest), `validate` (mlcroissant validation).
+- `biotope config` — manage project-level validation rules, remote validation URLs, and project metadata.
+
+### Stubs / not yet wired
+
+- `biotope discover` — rank registered adapters and local Croissant files against `required_entities`. Exists as a CLI entry but the registry surface is not yet wired into the recommended workflow; the tutorial does not use it.
+- `biotope benchmark` — quality/coverage metrics. v1 stub: emits a skeleton JSON object so downstream tooling can structure-test against it. Real metric implementations land iteratively.
+- `biotope read` — NLP ingestion + health-check entry. Promise.
+- `biotope chat` — provider-agnostic conversational interface (biochatter backend). Promise.
+- `biotope search` — registry search across MCP / biotools. Auxiliary; not used in the standard build path.
 
 ### Deprecated
 
 - `biotope describe` — removed; folded into `biotope map` intent flags.
 - `biotope propose-mapping` — deprecated alias for `biotope map scaffold`. The old heuristic ("one RecordSet per node type, FK fields as edges") is gone; the alias now produces an unresolved scaffold for human/agent completion.
 
-### Promises (not feature-complete)
-
-- `biotope read` — NLP ingestion + health-check entry.
-- `biotope chat` — provider-agnostic conversational interface (biochatter backend ships first).
-- `biotope search` / `biotope get` / `biotope annotate` / `biotope config` — auxiliary surfaces.
-
 ## Reading order
 
+1. [Tutorial](tutorial.md) — 15-minute end-to-end walk-through; the ground-truth onboarding path.
 1. [Architecture](architecture.md) — modules, data flow, config files.
 1. [Project context](project-context.md) — project layout and `.biotope/` files.
 1. [Commands](api-docs/init.md) — per-command reference, generated from docstrings.