feat(cli): export and validate OKF bundles

[phernandez]

Summary

Add an explicit CLI boundary for producing and validating Open Knowledge Format (OKF) v0.2 bundles.

This is the remaining producer/conformance work split from #1246. Basic Memory already consumes project-local Markdown links as graph relations and preserves its wikilink-native canonical note format. The live Wiki projector is a Basic Memory view, not the interchange artifact.

Proposed commands

• bm okf export — render a project into a static, self-contained OKF bundle.
• bm okf check — validate a bundle against the supported OKF structural contract.

The final command shape can differ if it fits the existing CLI better, but export and validation should remain an explicit boundary rather than a project-wide canonical syntax mode.

Export requirements

• Emit standard Markdown links for graph relationships.
• Preserve useful Basic Memory semantics through a documented bm extension namespace where OKF has no native equivalent, including typed relation/context and observation categories.
• Emit conformant reserved files:
  • index.md has no frontmatter except optional root okf_version;
  • index.md entries use standard Markdown links;
  • log.md has no frontmatter and uses ISO YYYY-MM-DD sections;
  • index.md and log.md are not concept documents.
• Leave canonical project files unchanged.
• Produce deterministic output for the same accepted project state.

Check requirements

Validate at least the normative OKF v0.2 structural rules:

1. every non-reserved Markdown file has parseable YAML frontmatter;
2. every concept has a non-empty type;
3. reserved index.md and log.md files follow their required structure.

Diagnostics must name the offending file and rule. Validation must not reject unknown types, unknown frontmatter keys, missing optional fields, broken cross-links, or missing indexes.

Compatibility verification

• Exercise an exported Basic Memory fixture against a pinned upstream OKF consumer/reference implementation.
• Assert the expected concept count so silently skipped parse failures cannot look like success.
• Validate and ingest a pinned upstream sample bundle, then prove project-local links are searchable/retrievable.
• Keep the pin explicit: passing a permissive viewer is compatibility evidence, not a substitute for bm okf check.

Out of scope

• A relation_link_style switch for canonical Basic Memory notes.
• Rewriting existing project files in place.
• Making the live Wiki projector itself strict OKF output.
• Runtime execution or attestation support beyond preserving supported frontmatter.

References

• [FEATURE] opt-in Open Knowledge Format (OKF) conformance for the note format #1246
• OKF v0.2 specification
• feat(core): index Markdown links to project files #1514
• feat(core): add PDF page citations to document observations #1490
• feat(core): add deterministic wiki projector #1381
• refactor(core): converge wiki logs on the accepted-change vocabulary #1396

[claude]

Claude finished @phernandez's task in 32s —— View job

---

Triage

Type: Enhancement — a feature request for new bm okf export / bm okf check CLI commands and their supporting export/validation logic. No defect is reported.

Component: CLI commands (new okf subcommand group), touching the markdown export/serialization and validation layers. Not cloud-specific, so no cloud label applied.

Priority: Medium. This is scoped producer/conformance follow-on work split from #1246 rather than a fix for broken or blocking functionality; it extends interop rather than addressing a regression.

Complexity: Complex. The request spans a new export pipeline (standard-Markdown-link rendering, a documented bm extension namespace, conformant index.md/log.md reserved-file emission, deterministic output), a structural validator with precise diagnostics, and compatibility verification against a pinned external OKF reference implementation and a pinned upstream sample bundle — each a substantial, separately testable piece of work.

Duplicates: None found. Searched issues for "OKF" — only #1246 (closed, the issue this work was split from) is related; the referenced PRs (#1514, #1490, #1381, #1396) are merged foundational work, not open duplicates.

Scope is already well-defined. The issue lays out clear export requirements, check requirements, and explicit out-of-scope items (no relation_link_style switch, no in-place rewriting, no strict-OKF Wiki projector, no runtime/attestation support), so no clarifying questions are needed before implementation planning.

Labels applied: enhancement.

[phernandez]

Milestone status (2026-09-14): ready for implementation; no PR exists yet.

This is the focused remainder split from #1246. Consumer-side Markdown-link interoperability is already merged; this issue owns only the static producer/validator boundary: deterministic bm okf export, strict bm okf check, conformant reserved files, and pinned upstream compatibility fixtures.

Next step: design the export value model and validator as separate testable layers, then expose them through the CLI. Do not change canonical Basic Memory syntax or make the live Wiki projector double as the export format.