# HowAICite research kit v1

Status: protocol published; no AI answer observations collected in this release.

The 30-question panel is an editorial research sample, not search-volume data.
It has 24 unbranded and 6 branded questions. The default scope is US / English,
four consumer surfaces, and three independent replicates (360 planned attempts).
Use a new versioned panel for a different country, language, API surface or prompt set.

Download metrics.mjs, prompt-panel.json and observations.json to one directory.
Run with Node.js 22 or later:

    node metrics.mjs prompt-panel.json observations.json

The script reads files and prints a summary. It does not call providers, send data,
write to your database, or infer recommendations automatically.
The empty file returns not-collected, with no fabricated zero visibility rate.

## Observation record

Each array entry needs:
- id: a unique observation identifier; retries must not duplicate a planned cell.
- wave: collection wave, such as 2026-09-16-baseline.
- promptId: an ID from the frozen panel.
- surface: exact panel surface; APIs must be named separately with API in the name.
- replicate: integer 1 through the panel replicate count.
- countryCode and language: must match the panel.
- observedAt: ISO timestamp including timezone.
- collectionMethod: consumer-ui or api.
- model: actual exposed model version, or unknown if the interface does not show it.
- locationProvenance: e.g. requested-only, collector-reported, or verified-session.
- status: complete, failed, or no-answer.
- answer: original answer for a completed attempt; empty otherwise.
- sourceUrls: array of observed http/https source URLs.
- mentioned, recommended, cited: boolean labels, or null if unreviewed/non-complete.
- reviewer: reviewer ID for completed fully reviewed records; omit for unreviewed.
- recommendationQuote: exact answer excerpt supporting a positive recommendation.

Citation label means a reviewed citation to the target domain (including its
subdomains), not a competitor citation. Inspect attribution and claim support.
Recommendation means a positive selection for a use case, not name occurrence.
Preserve full source/answer artifacts privately when redistribution rights are absent.
Public summaries must include missing attempts, dates, scope and limitations.
Model or location-provenance changes create separate cohorts.

## Study discipline

Freeze panel before collection; record failures; use fresh sessions; keep browser
personalization and provider settings in collection notes; log prompt changes as
new versions. Double-review a random 20% of annotations and resolve disagreements
before publication. Repeated answers are dependent samples, so the toolkit does
not produce a population confidence interval or a causal improvement claim.

The raw AI observations file is intentionally empty. The separately published
howaicite-readiness.json file contains actual HTML audit snapshots of our own site.
Do not mix website readiness findings into the AI answer dataset.

## Licenses

Prompt panel, protocol and our own-site audit findings: CC BY 4.0.
metrics.mjs: MIT (see LICENSE.txt). Third-party answers and source content retain
their own rights; no license for them is implied by this research kit.

Citation: HowAICite. Recommendation–Citation Gap Protocol, version 1.0.0,
September 9, 2026. https://howaicite.com/research/recommendation-citation-gap