[cachafla]

Pull Request Description

What and why?

Adds the new Quickstart for documentation with individual tests notebook (notebooks/quickstart/quickstart_documentation_run_test.ipynb) to the developer docs, next to the other quickstart variants:

• site/developer/_sidebar.yaml: sidebar entry "Quickstart (individual tests)", after the OIDC quickstart
• site/developer/validmind-library.qmd: card in the Quickstart listing

The notebook documents a model by running and logging tests one at a time with run_test() / result.log() against an empty document, without applying a template.

How to test

After the notebook is copied in with make get-source (see below), render the site and check that the Developer sidebar and the ValidMind Library page's Quickstart listing both link to the notebook.

What needs special review?

The sidebar label "Quickstart (individual tests)" follows the existing "Quickstart (OIDC device flow)" entry.

Dependencies, breaking changes, and deployment notes

Draft until the next validmind-library release. This PR only adds the entries; site/notebooks/quickstart/quickstart_documentation_run_test.ipynb arrives with the usual make get-source for that release. Dependencies:

• validmind-library#576 adds the notebook.
• validmind-library#573 (merged, not yet released) fixes list_tests() on a plain validmind[xgboost] install, which the notebook calls. On v2.14.0 that cell crashes, so the entry shouldn't go live before the release that includes it.

Release notes

Added Quickstart for documentation with individual tests, which shows how to document a model by running and logging individual tests without applying a document template.

Checklist

• What and why
• Screenshots or videos (Frontend)
• How to test
• What needs special review
• Dependencies, breaking changes, and deployment notes
• Labels applied
• PR linked to Shortcut

🤖 Generated with Claude Code

[github-actions]

Validate docs site

✓ INFO: A live preview of the docs site is available — Open the preview

[juanmleng]

Merge with recommendations · no blocking issues · 2 small fixes · no questions for you

The sidebar entry, the Quickstart card and the vendored notebook all look right. The notebook is identical to the copy in validmind-library v2.15.0, and that release includes both library fixes it depends on, so it can go live now.

Small fixes: F1 PR description still describes the draft plan, F2 add the story id to the title.

Checked: notebook matches the released library copy, outputs are stripped, layout matches the other quickstarts, both entries mirror the OIDC quickstart.

Ready for your approval, @juanmleng.

_{calibrated-review v2 · review · run by @juanmleng · head a682db9}

Agent handoff · calibrated-review v2 · review · a682db9

calibrated-review: 2
mode: review
pr: validmind/documentation#1555
head: a682db959
merge_base: 5c3f5d1b4
run_by: juanmleng
verdict: merge-with-recs
downgraded: 0
items:
  - id: F1
    class: fix-now
    type: hygiene
    direction: safe
    title: PR description describes the earlier draft plan, not the branch
    scenario: >-
      The body says the PR stays a draft until the next validmind-library
      release, that the notebook arrives with `make get-source`, and that
      validmind-library#573 is not yet released. Commit a682db95 vendored the
      notebook, the PR is no longer a draft, and validmind-library v2.15.0
      (2026-10-26) contains both #573 and #576. A reader of the body gets the
      wrong picture of what merging does.
    evidence:
      - site/notebooks/quickstart/quickstart_documentation_run_test.ipynb is added by commit a682db95
      - validmind-library merge commits 28233e91 (#573) and c835b083 (#576) are ancestors of tag v2.15.0
      - PR isDraft is false
    fix: >-
      Dependencies: say the notebook is vendored from validmind-library v2.15.0,
      which includes both fixes, and drop the draft note. How to test: replace
      the get-source step with rendering the site. Tick "PR linked to Shortcut"
      once F2 is done.
    done_when: the body matches what the branch contains
  - id: F2
    class: fix-now
    type: hygiene
    direction: safe
    title: PR title has no story id, so the PR is not linked to its story
    scenario: >-
      Neither the title nor the branch carries an SC- id, so Shortcut does not
      attach this PR to SC-19133, which lists only validmind-library#576.
      Recent merged documentation PRs (#1552, #1542) use the
      "[SC-<id>] <title>" convention.
    evidence:
      - SC-19133 pull_requests lists only validmind-library#576
      - headRefName cachafla/quickstart-run-test-notebook
    fix: Rename the PR to "[SC-19133] List the individual-tests quickstart notebook".
    done_when: the PR appears on SC-19133
accepted_risks:
  - checked: vendored notebook matches its source
    why: byte-identical to validmind-library v2.15.0 and main, so the next make get-source overwrites it with the same bytes
  - checked: notebook hygiene and layout
    why: no cell outputs; same title, hidden contents and copyright cells as the OIDC quickstart
  - checked: every place the OIDC sibling is referenced
    why: sidebar and validmind-library.qmd listing are both mirrored; the remaining reference is on the OIDC-specific auth page
  - checked: notebooks.zip download
    why: new notebook not included yet, but the zip was last regenerated 2026-07-04 and the next get-source rebuilds it
verification:
  - run: diff of the vendored notebook against validmind-library v2.15.0 and main
    result: identical
  - run: git merge-base --is-ancestor for #573 and #576 merge commits against v2.15.0
    result: both included
  - run: CI checks at head
    result: execute pass, ci_check pass, validate pending
  - claim: sidebar and listing render and link to the notebook (PR body, How to test)
    result: NOT CHECKED
  - claim: on v2.14.0 the list_tests() cell crashes (PR body)
    result: NOT CHECKED

[juanmleng]

Approving. The preview renders both new entries and the notebook page, and all checks pass.

The two small fixes from my earlier review are still open, and neither blocks the merge: the description still describes the draft plan (waiting for a library release, notebook arriving with make get-source), and the title needs [SC-19133] so the PR links to its story. Worth doing before you merge if you get a minute.