Skip to main content

Docs Provenance Model

Use this page when you need to verify where a public Helpifyr page came from, which repo owns it, and how reviewed publication should be read back.

When to use this page​

  • A public page looks stale or contradictory.
  • You need to compare source truth, reviewed artifact truth, and canonical public publication truth.
  • You need to explain the docs-system contract to another operator or contributor.

Prerequisites​

Architecture / Flow​

Step-by-step procedure​

1. Identify the owner layer​

Typical owner split:

  • source contracts and product truth:
    • helpifyr-fabric or another owner repo
  • reviewed public-docs materialization:
    • jhf-docs
  • live site publication:
    • jhf-docs
  • main-site shell, alias, or handoff consumption:
    • jhf-web

2. Read the docs-platform truth​

Start with:

GET /api/v1/docs/platform
GET /api/v1/docs/catalog
GET /api/v1/docs/readiness

These endpoints describe what the docs system believes is published and whether publication is healthy.

3. Read the reviewed artifact metadata​

In the jhf-docs reviewed artifact, high-value evidence includes:

  • docs-site/generated/validation_report.json
  • docs-site/static/generated/docs-platform.json
  • docs-site/generated/source_revisions.json

These files show provenance, coverage, and validation state for the materialized bundle.

4. Compare against the live site​

After the reviewed artifact is known-good, compare the exact public page and the metadata-backed expectation. If they differ, the issue is likely publication lag or stale artifact import rather than source truth.

Verification​

The provenance model is being applied correctly when:

  1. the owner layer is identified
  2. reviewed artifact metadata is checked before live claims are made
  3. live readback is compared to exact reviewed truth

Common failure modes​

Treating the live page as the only source of truth​

Problem:

  • publication staleness and source errors are indistinguishable.

Better path:

  • compare owner, reviewed, and live layers in order

Assuming a repo build automatically updated the live site​

Problem:

  • a green local build is overclaimed as public publication truth.

Better path:

  • require explicit live readback after reviewed artifact publication

Source Truth​

Next paths​