Single source of truth for Birkly CMS documentation

Claims, evidence, and cross-links are how Agent Guide stays honest: summaries tell agents the headline; links and the sources of truth registry tell them where to verify. This doc covers strategy, types, and worked examples — especially marketplace and review URLs.

Beginner

Example: an Amazon rating without pasting reviews

  1. Add a claim: “Consistently rated 4.5+ stars on Amazon US.”
  2. Attach evidence with the listing URL, the rating, and the review count. Do not paste review text.
  3. Mark the claim Supported after you open the listing yourself, then republish. Agents can repeat the claim and follow the URL.

Four layers of truth

LayerWhat it isAgent should…
Sources of truthDeclared registry (sources_of_truth[])Read these first for narrative and proof
SummaryShort description, positioning bulletsParaphrase carefully; follow registry
ClaimAsserted fact with statusRepeat only if supported
Evidence / source linkURL or CMS ref with proofFollow link to verify

Rule: Don’t paste marketplace review text into Agent Guide. Store the claim (“Highly rated on Amazon”) + link to the listing + optional rating/count metadata.

Sources of truth vs product cross-links

RegistryScopeWhen to use
sources_of_truth[]Site-wide canonical reading listAbout pages, primary website, key docs, proof archives
Product sources[]Per-offering detail linksProduct page, marketplace listing, docs, purchase URL

Both export resolved URLs. The registry sets global reading order; product sources set offering-specific depth.

Registry entry example

{
  "id": "truth_about",
  "type": "cms_entry",
  "role": "narrative",
  "label": "About us",
  "url": "https://example.com/pages/about",
  "ref": {
    "collection": "pages",
    "entry_id": "about",
    "slug": "about",
    "label": "About us",
    "ref_type": "entry"
  },
  "priority": 80,
  "link_status": "ok"
}

Claims

Writing good claims

Good claims are:

  • Specific — “ISO 27001 certified since 2023” not “very secure”
  • Checkable — You can point to evidence or a proof source
  • Bounded — Time, geography, audience where relevant

Bad claims:

  • Pure opinion without qualification
  • Superlatives you can’t prove (“best in the world”)
  • Forward-looking guarantees without disclaimer

Status workflow

pending_review → (evidence added, reviewed) → supported
                    ↓
              unsupported / expired / conflicting

Public export and view=summary only include supported claims.

Claim sources vs evidence

MechanismWhen to use
evidence[] + evidence_idsReusable proof documents shared across claims
claim.sources[]Direct URLs tied only to this claim

Example: Claim “Featured in TechCrunch 2025” → one evidence row with publication URL. Claim “4.8★ on Amazon” → evidence type marketplace_listing + URL; optional rating 4.8, review_count 1200.

Consider adding a proof role source in the registry when the same certification page supports multiple claims.

Evidence

Evidence types (reference)

TypeTypical URL
cms_contentResolved public CMS entry URL
external_urlAny allowed HTTPS page
marketplace_listingamazon.com/dp/…, App Store, Etsy
review_platformG2, Trustpilot, Capterra
certificationIssuer badge or certificate page
publicationNews article, paper
uploadInternal — prefer public URL when possible

Verification

  • user_verified — Editor confirmed link matches claim
  • unverified — Default for new evidence

Use Verify in admin after checking the page live.

Link health

Check all links (Overview) performs safe external HEAD requests:

link_statusMeaning
ok2xx/3xx response
redirectFinal URL differs — may update on check
broken4xx/5xx or network failure
unknownNot checked yet
blockedSSRF-safe filter rejected URL

Staleness: Evidence URLs not verified in 180 days trigger publish warnings.

SSRF safety

Admin URL fetch and link check block localhost, private IPs, non-HTTP schemes. Only public HTTPS/HTTP URLs.

Cross-links (product sources)

Source link shape

Each product source link has:

{
  "id": "src_abc",
  "role": "canonical_detail",
  "type": "cms_entry",
  "label": "Widget Pro — product page",
  "url": "https://example.com/products/widget-pro",
  "ref": {
    "collection": "products",
    "entry_id": "entry_123",
    "slug": "widget-pro",
    "label": "Widget Pro"
  },
  "link_status": "ok",
  "last_verified_at": "2026-07-27T10:00:00+00:00"
}

CMS entries without stored URL get resolved on publish from collection + slug + public site base.

Product source roles

RolePurpose
canonical_detailAuthoritative full detail
referenceGeneral background
marketplaceWhere to buy / listing
reviewReviews and ratings
docsSpecs, API docs, manuals
proofSupports a specific assertion
purchaseCheckout/pricing
socialSocial profile

Worked example — Amazon reviews

Goal: Agents can say you’re well-reviewed without hallucinating review text.

  1. Registry: Optional marketplace source with role proof for the listing.
  2. Claim: “Consistently rated 4.5+ stars on Amazon US”
  3. Evidence:

- type: marketplace_listing - url: https://www.amazon.com/dp/B0XXXXXX - rating: 4.7 - review_count: 842 - verification: user_verified after manual check

  1. Do not scrape or paste review bodies into Agent Guide
  2. Republish when rating changes materially — set calendar reminder

Worked example — B2B SaaS

  1. Sources: CMS About entry (narrative), pricing page (reference), security whitepaper (proof)
  2. Products: Plan names with canonical links to /pricing anchors
  3. Claims: “SOC 2 Type II certified” → evidence type certification → auditor page
  4. Claims: “Listed on G2 with 4.8 rating” → review_platform URL

Completeness interaction

  • Sources: need narrative source for full 15 pts
  • Products: need grounded source for full 10 pts
  • Evidence: need URL for full 15 pts
  • Claims: need supported + evidence_ids for full 20 pts

Use completeness as quality gate, not checkbox filling.

Advanced users

Public export & JSON-LD

Published exports include resolved sources_of_truth[] and product sources[]. Supported claims in graph views include linked_evidence. JSON-LD adds:

  • Product url, sameAs from sources
  • Claim isBasedOn from evidence URLs

See Public API.

Related docs