E2e tests and frist use docs

tests/test_practical_usecases_e2e.py

@@ -1,4 +1,5 @@
 import json
+import time
 from pathlib import Path
 
 import pytest
@@ -203,3 +204,202 @@ def test_structure_reuse_policy_and_literate_usecases(tmp_path: Path):
     implode = runner.invoke(main, ["implode", str(exploded), "--format", "markdown"])
     assert implode.exit_code == 0, implode.output
     assert "# Use Markdown Contracts" in implode.output
+
+
+@pytest.mark.parametrize(
+    ("label", "document", "contract", "context"),
+    [
+        ("small", "examples/documents/concept-note-valid.md", "examples/contracts/concept-note.contract.md", None),
+        (
+            "typical",
+            "examples/documents/business-letter-valid.md",
+            "examples/contracts/business-letter.contract.md",
+            "examples/runtime/business-letter.context.yaml",
+        ),
+        ("large", "examples/documents/prd-frs-valid.md", "examples/contracts/prd-frs.contract.md", None),
+    ],
+)
+def test_contract_and_runtime_usecases_small_typical_large(
+    label: str,
+    document: str,
+    contract: str,
+    context: str | None,
+):
+    runner = CliRunner()
+    command = ["contract", "check", document, "--contract", contract, "--format", "json"]
+    if context:
+        command.extend(["--context", context])
+
+    check = runner.invoke(main, command)
+
+    assert check.exit_code == 0, check.output
+    check_data = json.loads(check.output)
+    assert check_data["valid"] is True
+    assert check_data["document_path"].endswith(Path(document).name)
+
+    if context:
+        form_state = runner.invoke(
+            main,
+            [
+                "contract",
+                "form-state",
+                document,
+                "--contract",
+                contract,
+                "--context",
+                context,
+                "--format",
+                "json",
+            ],
+        )
+        assert form_state.exit_code == 0, form_state.output
+        form_data = json.loads(form_state.output)
+        assert form_data["valid"] is True
+        assert form_data["fields"], label
+
+
+@pytest.mark.parametrize(
+    ("label", "count"),
+    [
+        ("small", 1),
+        ("typical", 5),
+        ("large", 30),
+    ],
+)
+def test_transform_compose_and_include_usecases_small_typical_large(
+    tmp_path: Path,
+    label: str,
+    count: int,
+):
+    docs = tmp_path / "sources"
+    docs.mkdir()
+    for index in range(count):
+        (docs / f"source-{index:02d}.md").write_text(
+            f"""---
+review:
+  state: draft
+---
+
+# Source {index}
+
+## Decision
+
+The {label} transform pipeline keeps source {index} reusable.
+""",
+            encoding="utf-8",
+        )
+
+    runner = CliRunner()
+    transform = runner.invoke(
+        main,
+        [
+            "transform",
+            str(docs / "source-00.md"),
+            "--set",
+            "review.state=ready",
+            "--heading-delta",
+            "1",
+        ],
+    )
+    assert transform.exit_code == 0, transform.output
+    assert "state: ready" in transform.output
+    assert "## Source 0" in transform.output
+
+    compose = runner.invoke(
+        main,
+        [
+            "compose",
+            *[str(path) for path in sorted(docs.glob("*.md"))],
+            "--title",
+            f"{label.title()} Corpus",
+            "--heading-delta",
+            "1",
+            "--format",
+            "markdown",
+        ],
+    )
+    assert compose.exit_code == 0, compose.output
+    assert f"# {label.title()} Corpus" in compose.output
+    assert compose.output.count("### Decision") == count
+
+    include_file = tmp_path / "include.md"
+    include_file.write_text(
+        '<!-- mkt:include path="sources/source-00.md" selector="sections[heading=Decision]" heading_delta="1" -->',
+        encoding="utf-8",
+    )
+    include = runner.invoke(main, ["include", str(include_file), "--base-dir", str(tmp_path)])
+    assert include.exit_code == 0, include.output
+    assert "### Decision" in include.output
+    assert f"The {label} transform pipeline" in include.output
+
+
+@pytest.mark.parametrize(
+    "workflow_file",
+    [
+        "examples/workflows/source-snippets.workflow.md",
+        "examples/workflows/adr-release-notes.workflow.md",
+    ],
+)
+def test_workflow_and_refresh_planning_usecases(tmp_path: Path, workflow_file: str):
+    runner = CliRunner()
+
+    inspect = runner.invoke(main, ["workflow", "inspect", workflow_file, "--format", "json"])
+    assert inspect.exit_code == 0, inspect.output
+    assert json.loads(inspect.output)["valid"] is True
+
+    plan = runner.invoke(
+        main,
+        ["workflow", "plan", workflow_file, "--output-dir", str(tmp_path / "out"), "--format", "json"],
+    )
+    assert plan.exit_code == 0, plan.output
+    plan_data = json.loads(plan.output)
+    assert plan_data["valid"] is True
+    assert plan_data["dry_run"] is True
+
+    refresh = runner.invoke(
+        main,
+        ["backend", "refresh-plan", "examples/documents", "--root", ".", "--format", "json"],
+    )
+    assert refresh.exit_code == 1, refresh.output
+    refresh_data = json.loads(refresh.output)
+    assert refresh_data["dirty"] is True
+    assert refresh_data["counts"]["needs_parse"] >= 1
+
+
+def test_large_corpus_performance_smoke_stays_bounded(tmp_path: Path):
+    docs = tmp_path / "docs"
+    docs.mkdir()
+    for index in range(120):
+        (docs / f"note-{index:03d}.md").write_text(
+            f"""# Note {index}
+
+## Summary
+
+This synthetic performance smoke document mentions adoption latency and search.
+
+## Details
+
+The index should stay responsive for local corpora without requiring services.
+""",
+            encoding="utf-8",
+        )
+
+    runner = CliRunner()
+    started = time.perf_counter()
+    index = runner.invoke(main, ["cache", "index", str(docs), "--root", str(tmp_path), "--format", "json"])
+    index_seconds = time.perf_counter() - started
+
+    assert index.exit_code == 0, index.output
+    assert len(json.loads(index.output)["indexed"]) == 120
+    assert index_seconds < 30
+
+    started = time.perf_counter()
+    search = runner.invoke(
+        main,
+        ["search", "adoption", "--root", str(tmp_path), "--limit", "10", "--format", "json"],
+    )
+    search_seconds = time.perf_counter() - started
+
+    assert search.exit_code == 0, search.output
+    assert json.loads(search.output)["count"] >= 1
+    assert search_seconds < 5