Skip to main content

OKF-Native Knowledge Bundles

Synth is OKF-native for project knowledge. The live knowledge/ tree is stored as Google Open Knowledge Format (OKF) v0.1-compatible Markdown, so Synth can download a validated OKF ZIP or import one through Ingest without changing how users work day to day.

How it happens: when Synth writes or ingests a page, it writes OKF frontmatter such as type and title, preserves unknown OKF keys, maintains knowledge/index.md as the OKF root marker, and keeps knowledge/log.md in OKF date-heading form. Export validates and packages the existing public knowledge files. Older projects use synth okf-migrate once to normalize legacy pages.

What You Can Do​

  • Validate OKF v0.1 directories and ZIP bundles.
  • Download a Synth project as a validated OKF ZIP.
  • Import a validated OKF ZIP into an existing Synth project.
  • Preview imports before Synth writes files.
  • Migrate older Synth projects to OKF-native layout.
  • Preserve unknown OKF frontmatter keys during import, migration, and export.
  • Resolve safe OKF absolute links such as /tables/customers.md, /index.md, and /log.md as bundle-relative knowledge links.

What Is Out Of Scope​

  • Remote OKF publishing.
  • OKF-specific MCP tools.

Download From The Web UI​

  1. Open Projects.
  2. Choose the project.
  3. Open the OKF drawer.
  4. Select Download OKF ZIP.

If an older project needs migration, Synth will tell an admin before download.

Import From The Web UI​

  1. Open Ingest.
  2. Choose OKF Bundle.
  3. Upload an OKF ZIP.
  4. Select Validate and review the preview.
  5. Select Apply Import only after the preview looks right.
  6. Open KB or Graph from the result to verify the imported pages.

The import flow validates before mutation. Existing files are not overwritten unless you explicitly choose overwrite.

CLI​

synthctl okf-validate ./docs-project/knowledge
synthctl okf-migrate --project docs --dry-run
synthctl okf-migrate --project docs --apply
synthctl okf-export --project docs --output ./exports
synthctl okf-import ./bundle.zip --project docs
synthctl okf-import ./bundle.zip --project docs --apply

Use okf-import without --apply first to preview the import plan. Use --overwrite only when replacing existing knowledge files is intentional.

REST API​

Project-scoped OKF routes live under /api/projects/okf:

  • GET /status
  • GET /status?validate=true
  • POST /validate
  • POST /export
  • GET /export/{job_id}/status
  • GET /export/{job_id}/download
  • POST /import/validate
  • POST /import/apply

Export and validation require project viewer access with read scope. Import requires project editor access with full_access, ingest:write, or knowledge:write.

Performance​

Synth does not run full-project OKF validation on normal Explore, search, graph, page reads, project navigation, or default project status. Normal writes normalize only the file being written. Full validation is explicit through validation, migration, export, or the OKF drawer's status check.

Safety​

OKF export excludes .synth, graph databases, search indexes, raw uploads, credentials, API keys, watcher state, local config, hidden paths, and runtime files.

OKF import rejects traversal, absolute ZIP members, hidden or system paths, symlinks, duplicate normalized ZIP paths, oversized bundles, and non-markdown targets. Uploads are capped while streaming to temporary storage.