Interoperability: OKF, providers and the configurator

OKF conformance

Every KB is a conformant OKF v0.1 bundle and a git repository in its own right. Any external OKF tool can consume it without modification. Everything is git + files: history, diff, backup, sharing, zero lock-in. The skills (SKILL.md agentskills.io) and secrets (SOPS) are likewise open, portable standards.

Obsidian is the human viewer (graph view, Dataview), conceptually read-only.

Hard rules vs soft guidance

• Hard rules → server: path/layout validation, strict-map type palettes, optimistic writes and git serialization. Agents use MCP tools instead of editing KB files directly.
• Soft guidance → instructions provisioning (D56/D61, no longer an AGENTS.md in the KB — removed by D62): a generated block injected into each provider's global instructions file (.claude/CLAUDE.md, .config/opencode/AGENTS.md, .codex/AGENTS.md, Kiro steering), plus the optional curated instructions.md in the KB root (D61) and the auto-generated agent section — see sync.md §Instructions.

The MCP + skill + hook triad

Level	What it does	Token cost
MCP	Data and capabilities (bounded reads, structured frontmatter queries, search, validated writes)	Proportional to the content read
Skill	Competence/procedure (how to do ingest/query/lint), loaded on-demand	~100 tokens catalog; body on-demand
Hook	Deterministic client-side automation distributed by the KB	No model cost unless the hook invokes an agent

Multi-provider configurator

A dedicated tool (the cartographer client subcommands — agents/connect/status/sync, see docs/configurator.md) configures skills, MCP, hooks (and references to services/secrets) on each provider leveraging its capabilities to the fullest — no least-common-denominator. The client always talks to the server over HTTP (no stdio transport on the client side, D37).

Single source-of-truth → per-provider adapter: the source is the provisioning manifest generated by the server (compiled bundle + artifacts of the mounted KBs — skills, agents, hooks, instructions); a per-provider adapter (internal/configurator for the MCP config, internal/provisioning.Apply for materialization) translates each artifact into the native constructs, discarding what cannot be reliably mapped instead of guessing it. The full kind×provider matrix is in sync.md §Kind × provider matrix.

TUI: interactive dashboard (cartographer with no arguments): autodetects installed providers, per-provider status with per-kind counts, connect/resync/disconnect — see configurator.md §TUI mode.

Idempotent and non-destructive sync: deep-merge for JSON; marker-delimited blocks for TOML and instruction files; never overwrite the user's contracts or secrets; dry-run.

Automatic realignment when skills/agents/hooks change (bundle or KB): manifest+revision server-side, lockfile client-side, drift detection and layered triggers (SessionStart hook, MCP tool, push). See → sync.md.

Secrets and local commands: MCP descriptors may name environment variables in provider-native syntax, but Cartographer does not distribute or resolve their values. A trusted stdio descriptor configures a provider to run a locally preflighted executable; Cartographer never launches it during provisioning. Runtime secret injection remains an operator responsibility.

Provider behavior

Provider formats change independently of Cartographer, so this page does not duplicate a dated market-wide capability matrix. The maintained sources are:

• configurator — exact files Cartographer reads and writes;
• synchronization — the kind × provider materialization matrix, translation losses, trust and pruning;
• tests under internal/configurator and internal/provisioning — executable compatibility contract.

Current limitations are documented once in the relevant table/section rather than repeated here. In particular, Kiro's flat MCP tool namespace may require the server's per-KB tool prefix, and provider translations intentionally drop fields that cannot be represented safely.