docs(validation): state what --offline pins and what nothing pins

[LukasGold]

Closes the last open item of #125.

Item 5 was written as "default make validate to --offline, or state the asymmetry". Half of it was never a gap: make validate has passed --offline since 80ee29a, the commit that added the validator. So the remaining work was only ever the documentation, which this is.

The asymmetry

The vendored meta-schemas exist so that a released version cannot change meaning between runs, and docs/how-to/validation.md says so. A document's @context has no equivalent guarantee, and the options table gave --offline one line, "Never fetch; use local files and the cache only", which describes the mechanism without saying why anyone would want it.

offline defaults to false because that is what lets a cross-directory or genuinely remote @context resolve at all. It is the point rather than an oversight. But it also means two runs over the same document can disagree if a context it reaches for has moved in between, which sits oddly next to the reproducibility the vendored copies are there to provide.

The new section states both halves and explains why make validate passes the flag: the committed fixtures are supposed to give the same answer today and next year.

Documentation only. No behaviour changes, and nothing was renamed or defaulted differently.

Verification

• make docs-test: exit 0, no issues, which is the strict build that fails on any warning
• make check: clean
• CRLF preserved, so the file has no mixed line endings

[github-actions]

Release preview

No version bump from the current commits (stays at v0.19.0). Use conventional commit types (feat, fix, ...) to trigger a release.

Changelog preview (truncated)

_{Preview via python-semantic-release and conventional commits.}

[github-actions]

📊 Benchmark Results

Click to see benchmark comparison

📊 Benchmark Comparison (threshold: 1.3x)
============================================================

⚠️  Performance Regressions:
  ❌ test_class_hierarchy: 0.0497s → 0.0742s (+49.3%, ratio: 1.49x)

➖ Unchanged (within threshold):
  ➖ test_simple_dict_document_store: 0.0016s → 0.0016s (-0.0%)
  ➖ test_sqlite_document_store: 0.0017s → 0.0017s (-1.9%)
  ➖ test_local_sparql_store: 0.0388s → 0.0373s (-3.8%)
  ➖ test_oneof_subschema: 0.0566s → 0.0574s (+1.3%)
  ➖ test_enum_docstrings: 0.0472s → 0.0477s (+1.2%)
  ➖ test_subclass_inheritance: 0.0513s → 0.0513s (-0.1%)
  ➖ test_core[v1]: 0.0369s → 0.0370s (+0.5%)
  ➖ test_core[v2]: 0.0421s → 0.0426s (+1.2%)
  ➖ test_schema_generation[v1]: 0.0015s → 0.0015s (+1.5%)
  ➖ test_schema_generation[v2]: 0.0026s → 0.0026s (+0.6%)
  ➖ test_simple_json: 0.0006s → 0.0006s (+6.4%)
  ➖ test_complex_graph: 0.0014s → 0.0016s (+7.3%)

============================================================
Summary: 1 regressions, 0 improvements, 12 unchanged
============================================================

⚠️  Regressions detected but not failing build (informational only)

Threshold: 1.3x (30% slower triggers a regression warning)

Note: Benchmarks are informational only and won't fail the build.

_{💡 Tip: Download the benchmark-results artifact for detailed JSON data}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!