{
  "schemaVersion": "1.0.0",
  "updated": "2026-09-22",
  "title": "AI citation and visible attribution observation protocol",
  "author": "George Kelly",
  "canonicalUrl": "https://www.iamgeorgekelly.com/field-guide/ai-citation-observation-protocol",
  "scope": "An editorial rubric and blank ledger for manual answer review. This file contains no measured site performance. Calibration cases are synthetic. It does not fetch assistants, score screenshots automatically, or establish human awareness.",
  "ledgerUrl": "https://www.iamgeorgekelly.com/downloads/ai-citation-observation-ledger.csv",
  "sourceChecked": "2026-09-22",
  "sources": [
    {
      "url": "https://developers.openai.com/api/docs/guides/tools-web-search",
      "supports": "Responses API consulted sources and citation annotations are different evidence. API metadata alone does not show the rendered interface."
    },
    {
      "url": "https://support.google.com/webmasters/answer/16984139",
      "supports": "Google AI Search link impressions cover AI Overviews and AI Mode, overlap Web performance, and use property or page aggregation."
    },
    {
      "url": "https://support.google.com/webmasters/answer/7042828?hl=en",
      "supports": "Impression visibility rules, repeated-link aggregation and AI Mode follow-up query treatment."
    }
  ],
  "instructions": [
    "Set the panel, target identity, accepted host aliases and capture procedure before observation. Preserve exact prompts.",
    "Use one observation per planned answer and target. Keep failed and incomplete runs. Do not create another observation when expanding sources for the same answer.",
    "Save the complete initial answer before opening source panels, then save the expanded view. Initial-answer visibility does not mean first-viewport visibility or confirmed attention.",
    "Verify citation destinations against targetHost or a declared alias using parsed hostname equality, not substring matching. Preserve original URLs and inspected redirects. Never infer a match from a similar title.",
    "Require context confirming the target when recording an author or brand name. Common names or ambiguous identities are unknown.",
    "Fill only fields supported by retained evidence. Use null for unobserved metadata and unknown for uninspectable visible signals. False or absent requires complete relevant inspection.",
    "Do not use API source lists or Google aggregate impressions to fill visible-answer fields. Retain provider reports separately. An expanded Sources panel may include consulted pages that were not cited inline; record its links as source-link visibility, not automatically as citations supporting a claim.",
    "Retain the source passage and answer excerpt before marking attribution supported or misattributed. A reviewer must judge the actual credited claim.",
    "The CSV is header-only. Use the blank observation below as its field dictionary; arrays in a CSV cell can be stored as JSON text. Missing boolean values stay blank and mean null, not false.",
    "Calibration cases below are invented reviewer exercises. Do not include them in any measured observation baseline."
  ],
  "allowedValues": {
    "promptCondition": ["unbranded_discovery", "branded", "source_supplied", "other_documented"],
    "runStatus": ["not_run", "complete", "partial", "failed"],
    "retrievedTarget": [true, false, null],
    "citationInApiMetadata": [true, false, null],
    "visibleTargetLink": ["initial_answer", "expanded_sources", "absent", "unknown"],
    "visibleTargetDomain": ["initial_answer", "expanded_sources", "absent", "unknown"],
    "namedTargetBrand": ["initial_answer", "expanded_sources", "absent", "unknown"],
    "namedTargetAuthor": ["initial_answer", "expanded_sources", "absent", "unknown"],
    "attributionCheck": ["supported", "misattributed", "not_applicable", "unreviewed"]
  },
  "fieldRules": {
    "observationId": "Unique ID for one planned run and target; do not reuse an ID for a retry.",
    "panelVersion": "Version identifying a fixed prompt set and observation procedure.",
    "promptId": "Stable question ID within the panel.",
    "exactPrompt": "The full prompt actually submitted, including any supplied context.",
    "promptCondition": "Discovery requires no target name, domain or page supplied in prompt, attachments or prior context. Document any departure.",
    "surface": "Exact product and mode, or the API application identity. Do not mix API and consumer-interface observations.",
    "modelLabel": "Visible model label only; null when not disclosed.",
    "capturedAt": "Capture timestamp with timezone offset; null before capture.",
    "locale": "Documented language/location context; unknown if unavailable.",
    "searchSetting": "The observed search/browsing setting, including default or unknown.",
    "priorContext": "Fresh conversation or a description of existing context/personalization. Do not claim it was disabled if not checked.",
    "runStatus": "Whether an answer was completed and retained. A completed answer can still have unknown fields.",
    "targetHost": "The hostname being observed; exact parsed-host matching.",
    "acceptedHostAliases": "Explicit hostnames treated as the same target, set before scoring. Do not automatically include unrelated subdomains.",
    "targetBrand": "The precise brand label and approved variants under review; null if this signal is not being studied.",
    "targetAuthor": "The precise author identity and approved name variants; null if not being studied.",
    "retrievedTarget": "True when retained retrieval metadata includes the target; false only when the available complete retrieval list was inspected and excludes it; null when retrieval evidence is unavailable. False is scoped to that metadata, not proof that the model has never used the source.",
    "citationInApiMetadata": "True/false only after inspection of complete saved citation annotations; null when unavailable or in a UI-only run. It does not establish visible rendering.",
    "visibleTargetLink": "Where a verified target link first appears. This includes Sources-panel links to consulted pages and does not establish an inline citation. Absent requires the complete answer and available expanded source interface to have been inspected; otherwise unknown unless a link is already observed.",
    "visibleTargetDomain": "Where the literal target domain first appears as readable text. A matching href alone is insufficient. Apply the same complete-inspection rule for absent.",
    "namedTargetBrand": "Where the unambiguous target brand is first named. The domain alone is not a brand-name observation unless that exact domain string was predeclared as the brand label.",
    "namedTargetAuthor": "Where the unambiguously identified target author is first named. A link to a page with a byline is insufficient if the answer/source interface does not show the name.",
    "attributionCheck": "Supported requires the credited claim to agree with the retained source. Misattributed means the credited claim is unsupported or assigned to the wrong source/author. Use unreviewed if evidence is incomplete; not_applicable if no specific claim was attributed.",
    "matchedUrls": "Original verified destination URLs; record inspected redirects in notes without overwriting the original.",
    "initialAnswerEvidence": "Saved complete answer or screenshot/transcript reference, including capture state.",
    "expandedSourcesEvidence": "Saved source-panel state or explicit note that no such interface exists. Null if not inspected.",
    "retrievalEvidence": "Reference to complete available retrieval metadata; null if unavailable.",
    "citationMetadataEvidence": "Reference to the saved API response annotations; null if unavailable.",
    "sourcePassageEvidence": "Retained passage/version supporting the attribution review; null if not reviewed.",
    "reviewer": "Reviewer identifier; null before review.",
    "notes": "Failures, missing evidence, redirect checks, identity ambiguities or any deviation from the procedure."
  },
  "blankObservation": {
    "observationId": null,
    "panelVersion": null,
    "promptId": null,
    "exactPrompt": null,
    "promptCondition": null,
    "surface": null,
    "modelLabel": null,
    "capturedAt": null,
    "locale": null,
    "searchSetting": null,
    "priorContext": null,
    "runStatus": "not_run",
    "targetHost": null,
    "acceptedHostAliases": [],
    "targetBrand": null,
    "targetAuthor": null,
    "retrievedTarget": null,
    "citationInApiMetadata": null,
    "visibleTargetLink": "unknown",
    "visibleTargetDomain": "unknown",
    "namedTargetBrand": "unknown",
    "namedTargetAuthor": "unknown",
    "attributionCheck": "unreviewed",
    "matchedUrls": [],
    "initialAnswerEvidence": null,
    "expandedSourcesEvidence": null,
    "retrievalEvidence": null,
    "citationMetadataEvidence": null,
    "sourcePassageEvidence": null,
    "reviewer": null,
    "notes": null
  },
  "aggregationRules": {
    "groupBy": ["panelVersion", "surface", "promptCondition", "targetHost", "observationWindow", "captureProcedure"],
    "units": "Answer observations, not impressions or unique people.",
    "eligible": "For each visible signal, completed observations where that signal is initial_answer, expanded_sources or absent. Unknowns and failed/partial runs are separately reported.",
    "visibleSourceLinkRate": "(initial_answer + expanded_sources counts for visibleTargetLink) / eligible visibleTargetLink observations; null when denominator is zero. Includes Sources-panel links, so this is not an inline citation rate.",
    "initialVisibleSourceLinkRate": "initial_answer count for visibleTargetLink / eligible visibleTargetLink observations; null when denominator is zero.",
    "namedAuthorRate": "(initial_answer + expanded_sources counts for namedTargetAuthor) / eligible namedTargetAuthor observations; report the two placements separately.",
    "deduplication": "An answer counts once per target and signal even with multiple matching links. Expanding sources does not add another answer to the denominator.",
    "reportAlongsideRates": ["planned runs", "completed runs", "failed/partial runs", "known denominator per signal", "unknown count per signal", "initial versus expanded placement", "misattributions", "capture limitations"],
    "neverCombine": ["Synthetic calibration cases with measured answers", "Google report impressions with manual answer counts", "API applications with consumer assistants", "Source-supplied/branded prompts with unbranded discovery prompts", "Different panel or capture procedures without disclosing the change"]
  },
  "calibrationCases": [
    {
      "id": "consulted-only",
      "synthetic": true,
      "situation": "A complete API sources list includes example.com/guide. Complete citation annotations contain no target URL. No rendered answer was retained.",
      "expected": {"retrievedTarget": true, "citationInApiMetadata": false, "visibleTargetLink": "unknown", "visibleTargetDomain": "unknown", "namedTargetBrand": "unknown", "namedTargetAuthor": "unknown", "attributionCheck": "unreviewed"}
    },
    {
      "id": "title-chip-only",
      "synthetic": true,
      "situation": "The initial answer has a chip labelled Product measurement guide whose inspected destination is example.com/guide. Full answer and source-panel inspection finds no readable example.com domain or target brand/author name. The retained passage supports the credited statement; no API metadata is available.",
      "expected": {"retrievedTarget": null, "citationInApiMetadata": null, "visibleTargetLink": "initial_answer", "visibleTargetDomain": "absent", "namedTargetBrand": "absent", "namedTargetAuthor": "absent", "attributionCheck": "supported"}
    },
    {
      "id": "expanded-only",
      "synthetic": true,
      "situation": "The complete initial answer has no target link, domain or name. An opened Sources panel shows example.com linked to the verified guide. No target brand or author is named. A reviewer has not checked any credited claim against the source passage.",
      "expected": {"retrievedTarget": null, "citationInApiMetadata": null, "visibleTargetLink": "expanded_sources", "visibleTargetDomain": "expanded_sources", "namedTargetBrand": "absent", "namedTargetAuthor": "absent", "attributionCheck": "unreviewed"}
    },
    {
      "id": "unsupported-credit",
      "synthetic": true,
      "situation": "The initial answer names the unambiguous target author, Alex Example, and a readable example.com source link. It attributes a 50% productivity gain to the guide, but the retained guide passage contains no such result. Full inspection finds no separate target brand name.",
      "expected": {"retrievedTarget": null, "citationInApiMetadata": null, "visibleTargetLink": "initial_answer", "visibleTargetDomain": "initial_answer", "namedTargetBrand": "absent", "namedTargetAuthor": "initial_answer", "attributionCheck": "misattributed"}
    },
    {
      "id": "brand-without-link",
      "synthetic": true,
      "situation": "The complete answer names the unambiguous target brand, Example Workshop. Full answer/source inspection finds no link to its target site, domain text or author name. No source-specific factual claim is attributed and retrieval metadata is unavailable.",
      "expected": {"retrievedTarget": null, "citationInApiMetadata": null, "visibleTargetLink": "absent", "visibleTargetDomain": "absent", "namedTargetBrand": "initial_answer", "namedTargetAuthor": "absent", "attributionCheck": "not_applicable"}
    },
    {
      "id": "uninspected-sources",
      "synthetic": true,
      "situation": "The saved initial answer contains no target link, domain or name, but the Sources panel failed to open. No metadata is available. The run completed, but absence across the specified capture procedure cannot be established.",
      "expected": {"retrievedTarget": null, "citationInApiMetadata": null, "visibleTargetLink": "unknown", "visibleTargetDomain": "unknown", "namedTargetBrand": "unknown", "namedTargetAuthor": "unknown", "attributionCheck": "unreviewed"}
    }
  ],
  "workedDenominator": {
    "synthetic": true,
    "plannedRuns": 10,
    "failedRuns": 2,
    "completedRuns": 8,
    "completedWithUnknownLinkState": 1,
    "eligibleVisibleLinkObservations": 7,
    "initialAnswerLinks": 2,
    "expandedOnlyLinks": 1,
    "absentLinks": 4,
    "visibleSourceLinkFraction": "3/7",
    "interpretation": "Three of seven fully inspected completed answers linked to the target. Two runs failed and one completed answer has unknown link state. This is a synthetic arithmetic example, not site performance or market share."
  }
}