feat: adopt OKF v0.2 output

.changeset/adopt-okf-v0-2.md

@@ -0,0 +1,5 @@
+---
+"openwiki": minor
+---
+
+Adopt OKF v0.2 output: the bundle-root index now declares `okf_version: "0.2"`, agent prompts instruct the `generated: {by, at}` trust field (actor `openwiki/<version>`) in place of the superseded `timestamp`, and the front-matter validator checks the v0.2 provenance, trust, and lifecycle families (`generated`, `verified`, `sources`, `status`, `stale_after`) while still tolerating the legacy `timestamp` on v0.1 pages.

README.md

@@ -26,7 +26,7 @@ OpenWiki is a CLI that writes and maintains a wiki for your codebase or your per
 - **Built-in connectors** for Notion, Slack, Gmail, X, Web Search, Hacker News, and local git repositories.
 - **An interactive visualizer** that turns any wiki into a live, explorable node graph.
 - **Self-updating** through GitHub Actions, GitLab CI, or Bitbucket Pipelines.
-- **Open Knowledge Format** ([OKF v0.1](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md)) output with validated Mermaid diagrams.
+- **Open Knowledge Format** ([OKF v0.2](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md)) output with validated Mermaid diagrams.
 
 ## 🎉 What's new
 
@@ -149,12 +149,14 @@ Everything OpenWiki writes is plain Markdown you own and version alongside your
 
 ## Open Knowledge Format
 
-OpenWiki emits [Google Open Knowledge Format (OKF) v0.1](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md) bundles in both modes, so your wiki is portable to any OKF-aware tool.
+OpenWiki emits [Google Open Knowledge Format (OKF) v0.2](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md) bundles in both modes, so your wiki is portable to any OKF-aware tool.
 
 - Every concept document carries YAML front matter with a non-empty `type`; all other standard fields are optional.
+- Pages record their last meaningful change as `generated: {by, at}`; the legacy v0.1 `timestamp` field is still tolerated on existing pages.
+- The optional v0.2 provenance, trust, and lifecycle families (`sources`, `verified`, `status`, `stale_after`) are validated when present.
 - Standard Markdown links between concept documents express their relationships.
-- `index.md` and `log.md` are reserved documents rather than concepts. The root index declares `okf_version: "0.1"`.
-- Valid `timestamp` values and producer-defined extension fields are preserved across updates and migrations.
+- `index.md` and `log.md` are reserved documents rather than concepts. The root index declares `okf_version: "0.2"`.
+- Producer-defined extension fields are preserved across updates and migrations.
 
 ## Diagrams
 

src/agent/prompt.ts

@@ -1,3 +1,4 @@
+import { OPENWIKI_VERSION } from "../version.js";
 import type { OpenWikiIgnore } from "./openwiki-ignore.js";
 import { CODE_SYSTEM_PROMPTS, CODE_USER_PROMPTS } from "./prompts/code.js";
 import {
@@ -30,6 +31,7 @@ export function createSystemPrompt(
       : PERSONAL_SYSTEM_PROMPTS[command];
 
   const prompt = template
+    .replaceAll("{OKF_PRODUCER_ACTOR}", `openwiki/${OPENWIKI_VERSION}`)
     .replace(
       "{OUTPUT_LANGUAGE_INSTRUCTIONS}",
       formatLanguageInstructions(language),

src/agent/prompts/code.ts

@@ -60,8 +60,8 @@ Security and privacy rules:
 
 Front matter requirements (OKF):
 - Every non-reserved Markdown concept file you create or update under the target repository's openwiki/ directory, including the temporary /openwiki/_plan.md file, MUST begin with OKF-compliant YAML front matter.
-- The front matter MUST follow the Google Knowledge Catalog OKF v0.1 schema.
-- \`index.md\` and \`log.md\` are reserved OKF documents and must not be given concept front matter. Directory indexes are generated deterministically; only the bundle-root index may contain \`okf_version: "0.1"\` front matter.
+- The front matter MUST follow the Google Knowledge Catalog OKF v0.2 schema.
+- \`index.md\` and \`log.md\` are reserved OKF documents and must not be given concept front matter. Directory indexes are generated deterministically; only the bundle-root index may contain \`okf_version: "0.2"\` front matter.
 - Use this formatter at the very beginning of concept files, replacing placeholders with real values and omitting optional fields that do not apply:
 
 <okf_front_matter>
@@ -71,14 +71,14 @@ title: <Optional display name>
 description: <Optional one to two sentence summary (optimized for search & retrieval)>
 resource: <Optional canonical URI for the underlying asset>
 tags: [<tag>, <tag>, …]            # Optional
-timestamp: <Optional ISO 8601 datetime>
+generated: {by: <producer actor>, at: <ISO 8601 datetime>} # Optional
 # Producer-defined extension fields are allowed.
 ---
 </okf_front_matter>
 
 - Only \`type\` is required. Choose a short, descriptive, self-explanatory concept kind, such as \`BigQuery Table\`, \`BigQuery Dataset\`, \`API Endpoint\`, \`Metric\`, \`Playbook\`, or \`Reference\`. Type values are not centrally registered, so do not restrict them to a fixed list.
 - Recommended fields, in priority order, are: \`title\`, a human-readable display name; \`description\`, a one to two sentence summary optimized for search and retrieval; \`resource\`, the canonical URI of the underlying asset when one exists; and \`tags\`, a YAML list of short cross-cutting category strings.
-- \`timestamp\` is an optional ISO 8601 datetime for the last meaningful change.
+- \`generated\` optionally records the content's last meaningful change: \`by\` is required within it and names the producing actor (\`<producer>/<version>\` for agents, \`human:<id>\` for people, \`process:<id>\` for processes); \`at\` is an ISO 8601 datetime. When you create or meaningfully change a concept, write \`generated: {by: {OKF_PRODUCER_ACTOR}, at: <current ISO 8601 datetime>}\` and drop any superseded legacy \`timestamp\` field from that concept; otherwise leave existing \`generated\` and \`timestamp\` values untouched.
 - Produce valid YAML. Do not leave placeholder text or explanatory comments in written files.
 - Preserve all existing producer-defined front matter fields when updating a concept. Unknown extension fields are valid OKF and must survive round trips. Change metadata only when the underlying fact or meaningful content changes.
 - The description field is especially useful for retrieval tools. When present, make it clear, detailed, and optimized for search.
@@ -182,7 +182,7 @@ Do not draft wiki prose until every planned substantive page has an evidence bri
 - Only begin writing after this evidence gate is satisfied for the complete inventory. Do not start with quickstart prose while major components still have only manifest- or README-level understanding.
 
 Metadata and links (OKF):
-- Every non-reserved Markdown concept must begin with valid OKF v0.1 YAML front matter. index.md and log.md are reserved and must not receive concept front matter.
+- Every non-reserved Markdown concept must begin with valid OKF v0.2 YAML front matter. index.md and log.md are reserved and must not receive concept front matter.
 - Use this shape, omitting optional or empty fields:
 
 \`\`\`yaml
@@ -192,11 +192,12 @@ title: <display name>
 description: <one or two retrieval-optimized sentences>
 resource: <optional canonical URI>
 tags: [<specific-domain-tag>]
-timestamp: <optional ISO 8601 datetime>
+generated: {by: <producer actor>, at: <ISO 8601 datetime>} # optional
 ---
 \`\`\`
 
 - Only type is required by OKF, but add accurate title and description for retrieval.
+- Write \`generated: {by: {OKF_PRODUCER_ACTOR}, at: <current ISO 8601 datetime>}\` on pages you author; do not write the superseded legacy \`timestamp\` field.
 - Treat Markdown links between concept pages as semantic relationships. Put links in the prose that explains runtime, dependency, ownership, data-flow, lifecycle, or user-flow relationships; quickstart navigation alone is not a substitute.
 
 Diagrams:
@@ -303,8 +304,8 @@ OKF relationship modeling:
 
 Front matter requirements (OKF):
 - Every non-reserved Markdown concept file you create or update under the target repository's openwiki/ directory, including the temporary /openwiki/_plan.md file, MUST begin with OKF-compliant YAML front matter.
-- The front matter MUST follow the Google Knowledge Catalog OKF v0.1 schema.
-- \`index.md\` and \`log.md\` are reserved OKF documents and must not be given concept front matter. Directory indexes are generated deterministically; only the bundle-root index may contain \`okf_version: "0.1"\` front matter.
+- The front matter MUST follow the Google Knowledge Catalog OKF v0.2 schema.
+- \`index.md\` and \`log.md\` are reserved OKF documents and must not be given concept front matter. Directory indexes are generated deterministically; only the bundle-root index may contain \`okf_version: "0.2"\` front matter.
 - Use this formatter at the very beginning of concept files, replacing placeholders with real values and omitting optional fields that do not apply:
 
 <okf_front_matter>
@@ -314,14 +315,14 @@ title: <Optional display name>
 description: <Optional one to two sentence summary (optimized for search & retrieval)>
 resource: <Optional canonical URI for the underlying asset>
 tags: [<tag>, <tag>, …]            # Optional
-timestamp: <Optional ISO 8601 datetime>
+generated: {by: <producer actor>, at: <ISO 8601 datetime>} # Optional
 # Producer-defined extension fields are allowed.
 ---
 </okf_front_matter>
 
 - Only \`type\` is required. Choose a short, descriptive, self-explanatory concept kind, such as \`BigQuery Table\`, \`BigQuery Dataset\`, \`API Endpoint\`, \`Metric\`, \`Playbook\`, or \`Reference\`. Type values are not centrally registered, so do not restrict them to a fixed list.
 - Recommended fields, in priority order, are: \`title\`, a human-readable display name; \`description\`, a one to two sentence summary optimized for search and retrieval; \`resource\`, the canonical URI of the underlying asset when one exists; and \`tags\`, a YAML list of short cross-cutting category strings.
-- \`timestamp\` is an optional ISO 8601 datetime for the last meaningful change.
+- \`generated\` optionally records the content's last meaningful change: \`by\` is required within it and names the producing actor (\`<producer>/<version>\` for agents, \`human:<id>\` for people, \`process:<id>\` for processes); \`at\` is an ISO 8601 datetime. When you create or meaningfully change a concept, write \`generated: {by: {OKF_PRODUCER_ACTOR}, at: <current ISO 8601 datetime>}\` and drop any superseded legacy \`timestamp\` field from that concept; otherwise leave existing \`generated\` and \`timestamp\` values untouched.
 - Produce valid YAML. Do not leave placeholder text or explanatory comments in written files.
 - Preserve all existing producer-defined front matter fields when updating a concept. Unknown extension fields are valid OKF and must survive round trips. Change metadata only when the underlying fact or meaningful content changes.
 - The description field is especially useful for retrieval tools. When present, make it clear, detailed, and optimized for search.