Migration guide
A v0.1 bundle remains readable. The migration replaces two legacy forms and adds optional fields that make provenance, review state, freshness, and sanctioned computations machine-readable.
Compatibility
A v0.2 consumer may fall back to both v0.1 forms. Migrate producers first, then keep fallback reads until every bundle has moved.
Replacement 01
timestamp becomes generated.atThe new mapping records both the producer and the time of the last meaningful content change.
Replacement 02
# Citations becomes sourcesSources move into frontmatter. Claims cite a stable source ID with an ordinary Markdown footnote.
Before
metrics/revenue.md
markdown
---
type: Metric
title: Revenue
timestamp: 2026-07-17T10:00:00Z
---
# Definition
Revenue follows the approved finance policy.
# Citations
- [Finance policy](https://example.com/finance-policy)After
metrics/revenue.md
markdown
---
type: Metric
title: Revenue
generated: { by: human:finance-owner, at: 2026-07-17T10:00:00Z }
sources:
- id: finance-policy
resource: https://example.com/finance-policy
title: Finance policy
---
# Definition
Revenue follows the approved finance policy.[^finance-policy]
[^finance-policy]: Finance policyMigration order
Do not fill optional trust fields merely to make the frontmatter look complete.
Set okf_version: "0.2" in the root index frontmatter. Leave nested indexes and every log without frontmatter.
Replace timestamp with generated.by and generated.at. Use human:<id>, process:<id>, or <producer>/<version>.
Create one sources entry per material the concept actually derives from. Every entry needs resource.
Give cited sources stable IDs and use those IDs as Markdown footnote labels.
Add verified only after a human or process checks the content against its sources or underlying resource.
Use draft, stable, or deprecated. Add stale_after only when the owner can name a real review deadline.
Optional additions
verified accepts one actor event or a list. Consumers derive unverified, machine-confirmed, or human-reviewed from those events.
status records draft, stable, or deprecated. stale_after records an absolute ISO 8601 datetime with an explicit UTC offset.
Use type: Attested Computation when an agent must run a sanctioned calculation. Declare its runtime and parameters, then point to deterministic executor and attester instructions.
Check the result
Senior Engineer, Product Builder, and Founder
Systems, product software, and practical execution for teams that need clear decisions, durable implementation, and agent-ready knowledge structures.