docmeta:ai-context:1.0.0-proposal.1

Proposal under review

Part of the metadata vocabularies proposal, open for community review. Draft schema: docs/proposals/0023/schemas/ai-context/1.0.0-proposal.1.json.

The question it answers: how did machines make this page, and how may they use it? Two production fields (generated-by, provenance) and two consumption fields (risks, sample-questions).

Fields

Field	Type	Notes
generated-by	string, non-empty	The model, agent, or tool that generated the page’s content
provenance	list of entries	Per-model attribution of machine-proposed metadata: which fields, at what confidence
risks	string or list; open list	Pre-flight flags for agents and reviewers. Recommended: cost-incurring · destructive · irreversible · privileged · open-world · read-only · idempotent. Any other non-empty string is legal
sample-questions	string or list	Questions this page should answer. Retrieval evals use them

A provenance entry has generated-by (required), fields (the frontmatter keys it proposed, non-empty and unique), and confidence (a number from 0 to 1 per field).

Example

---
title: Install the operator on Kubernetes
description: Deploy the operator with Helm and verify the rollout.
generated-by: claude-fable-5
provenance:
  - generated-by: claude-fable-5
    fields: [intent, sample-questions]
    confidence: { intent: 0.9, sample-questions: 0.84 }
risks: [privileged, cost-incurring]
sample-questions:
  - How do I install the operator on EKS?
  - Which Helm values enable the webhook?
---

Design decisions

• Machines propose; humans retire the provenance. A provenance entry is the review trail for machine-filled metadata. A human deletes the entry once its fields are reviewed, so a surviving entry means machine metadata nobody has checked. The same pattern appears in the kg block, and in both eval vocabularies. So the whole family has one answer to “which of this metadata did a machine write, and has anyone checked?”
• generated-by attributes the content; provenance attributes the metadata. They record different facts. Consumers also use generated-by for self-preference-bias checks: a judge should know when it is grading its own author.
• risks is an open list. Seven flags are recommended. cost-incurring, destructive, irreversible, and privileged cover operations. open-world, read-only, and idempotent mirror MCP’s tool annotations, the published prior art for agent-facing hints. Any other non-empty string is legal. The assurances are worth stating because an unannotated page has not been assessed, which is different from being safe. For the same reason, a consumer that branches on a flag should treat an unknown value as a caution. Unknown does not mean safe.
• sample-questions closes the retrieval loop. Ask them against the corpus and measure whether this page carries the answer. Per-page assertions belong to the evals vocabulary instead.

What reviewers should poke at

Two questions. Do generated-by and provenance belong here or in core? The eval bias check and the kg harvest both read generated-by, which argues for the one vocabulary that is always present. And is risks the right name for a field that carries assurances (read-only) alongside cautions?