Technical reference for agent_guide.v1: storage layout, schema sections, completeness algorithm, publish pipeline, and export enrichment. Schema file: schema/ai_presence.schema.json in the Birkly repo (canonical $id: agent_guide.v1.json).

Legacy schema version ai_presence.v1 is accepted on load and normalized to current behavior.

Schema version

"schema_version": "agent_guide.v1"

Also accepted: "ai_presence.v1" (legacy). New saves use agent_guide.v1.

Storage (runtime)

Not committed to git — lives under project settings/:

settings/ai_presence/
  draft.json          ← working copy (admin edits)
  published.json      ← last published snapshot
  meta.json           ← versions, timestamps, checksums
  versions/
    1.json … N.json   ← optional history (cap 50)

Internal path name ai_presence is historical; the product and export schema are Agent Guide.

meta.json fields

Field	Description
published_version	Integer, increments each publish
last_published_at	ISO 8601
draft_updated_at	Last draft save
draft_checksum / published_checksum	SHA-256 of normalized JSON

Top-level document structure

Key	Description
sources_of_truth	Registry of canonical sources (CMS, web, docs, media, marketplaces)
guide_meta	Export hints (product, summary_layer)
identity	Official name, descriptions, website, social, derived_from
positioning	Best known for, differentiators, fit
communication_guidance	Terms, tone, qualifications
connected_content	Legacy — migrated to sources_of_truth on save
products_services	Catalog items
claims	Factual statements + status
evidence	Proof artifacts
media_context	Media library contextual metadata
relationships	Partners, parent orgs, etc.
publication_settings	Enable, paths, JSON-LD, redactions
setup_completed_at / setup_skipped_at	Onboarding markers

Published export adds: published_version, generated_at, usage_hints, optional json_ld.

sources_of_truth item

{
  "id": "truth_about",
  "type": "cms_entry",
  "role": "narrative",
  "label": "About us",
  "url": "https://example.com/pages/about",
  "notes": "",
  "priority": 80,
  "last_verified_at": "2026-07-27T10:00:00+00:00",
  "link_status": "ok",
  "ref": {
    "collection": "pages",
    "entry_id": "abc123",
    "slug": "about",
    "label": "About us",
    "ref_type": "entry"
  }
}

Types: cms_entry, cms_collection, website, document, media_asset, marketplace, review_platform, other

Roles: narrative, proof, reference, archive

For document and media_asset, optional media_id links Media library.

On publish, CMS refs resolve to public URLs; guide_meta and enriched usage_hints mark the summary layer.

identity

{
  "official_name": "Acme Co",
  "short_description": "…",
  "full_description": "…",
  "what_we_do": "…",
  "industry": ["SaaS"],
  "categories": ["Productivity"],
  "locations": ["Berlin", "Remote-first"],
  "website": "https://example.com",
  "social_profiles": [{ "platform": "linkedin", "url": "https://…" }],
  "derived_from": {
    "short_description": {
      "collection": "pages",
      "entry_id": "about",
      "slug": "about",
      "label": "About us"
    }
  }
}

On publish, derived_from.*.url resolves to public CMS URL when possible.

products_services item

{
  "id": "prod_x",
  "name": "Widget Pro",
  "type": "product",
  "short_description": "…",
  "full_description": "…",
  "category": "Hardware",
  "pricing_model": "subscription",
  "best_for": ["Small teams"],
  "not_for": ["Enterprise SSO-only shops"],
  "claim_ids": ["claim_y"],
  "sources": [{ "$ref": "source_link" }],
  "connected_entry": { "collection": "…", "entry_id": "…" },
  "media_id": "…",
  "media_url": "…",
  "public": true
}

connected_entry legacy field normalized into sources[] on save. Export omits raw connected_entry; exports resolved sources.

Product source_link definition

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

Roles: canonical_detail, reference, marketplace, review, docs, proof, purchase, social, other

Types: cms_entry, public_page, marketplace_listing, review_platform, docs, certification, other

claims item

{
  "id": "claim_x",
  "statement": "ISO 27001 certified",
  "status": "supported",
  "evidence_ids": ["evidence_a", "evidence_b"],
  "related_content": [],
  "sources": [],
  "last_reviewed_at": "",
  "expires_at": "",
  "notes": ""
}

Public graph views add linked_evidence[] on export.

evidence item

{
  "id": "evidence_a",
  "type": "certification",
  "title": "ISO 27001 certificate",
  "url": "https://…",
  "rating": null,
  "review_count": null,
  "publisher": "",
  "verification_status": "user_verified",
  "claim_ids": ["claim_x"],
  "link_status": "ok",
  "last_verified_at": "2026-07-27T10:00:00+00:00",
  "notes": ""
}

Types: cms_content, external_url, upload, certification, publication, marketplace_listing, review_platform, other

usage_hints (export only)

Generated at publish — guides AI consumers:

{
  "summary_layer": true,
  "follow_sources_of_truth": true,
  "authoritative_fields": ["identity.official_name", "claims.supported", "evidence.user_verified"],
  "marketing_fields": ["positioning.best_known_for", "positioning.differentiators"],
  "citation": "Prefer citing sources_of_truth and linked detail URLs over paraphrasing summaries alone.",
  "claims_require_evidence": true,
  "follow_links_for": ["product specs", "pricing", "reviews", "certifications"]
}

Completeness scoring (max 100)

Key	Max	Logic
identity	20	name 10 + short 10
description	15	full or what_we_do
sources_of_truth	15	narrative source 15; any source 8
claims	20	supported+evidence 20; any claim 8
evidence	15	any 10 + URL 5
positioning	10	best_known_for non-empty
products	10	any 5 + grounded 5
terminology	5	preferred_terms
publishing	5	enabled flag

Publish pipeline

1. Load draft → validate → normalize sources (agent_guide_sources.php)
2. Require publication_settings.enabled
3. Write published.json, bump version, save meta
4. Snapshot to versions/{n}.json, prune >50
5. Build public export:

- Attach version, timestamp, guide_meta - Optional JSON-LD - Enrich: resolve sources_of_truth, product sources, usage_hints, linked_evidence

1. Write well-known file (default /.well-known/agent-guide.json) if public_site_mode=project

Admin API (authenticated)

Base: /api/ai_presence.php (internal name; serves Agent Guide)

Action	Method	Notes
get	read	Draft + published + completeness + staleness
save_draft	write	CSRF, merge partial
publish	write	Validate + snapshot
suggest / copilot	write	AI suggestions (sources-first grounding)
suggest_links	write	Link-specific suggestions
validate_links	write	Optional update_status
list_collection_entries	read	CMS picker
fetch_url_meta	write	SSRF-safe title fetch
cms_diff / cms_refresh	read/write	Sync helpers

Permissions

Capability	Permission
View	read OR manage_settings
Edit, publish	manage_settings

Related docs

• Public API
• Claims, evidence & cross-links