Zum Hauptinhalt springen

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 live publication truth.
  • You need to explain the docs-system contract to another operator or contributor.

Prerequisites​

Architecture / Flow​

flowchart LR
    A["Owner repo source files"] --> B["Fabric docs-platform truth"]
    B --> C["jhf-docs reviewed materialization"]
    C --> D["Generated metadata and validation report"]
    D --> E["jhf-web live publication"]
    E --> F["User-visible docs readback"]

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-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​