From e527b19eba7fe3e416a420ff369a1cd7083600b2 Mon Sep 17 00:00:00 2001
From: serafin-garcia <serafin@inkeep.com>
Date: Thu, 18 Jun 2026 19:55:49 -0700
Subject: [PATCH] feat(open-knowledge): OKF-conformant starter pack (`ok seed
 --pack okf`) (#1984)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* docs(open-knowledge): OKF conformant starter pack spec (PRD-7119)

Spec for adding an OKF-conformant starter pack as a normal STARTER_PACKS
entry (ok seed --pack okf): type-bearing seed docs + frontmatter-free
reserved index.md/log.md, pre-populated not enforced. Includes evidence,
substrate map, and audit-corrected decisions.

* feat(open-knowledge): OKF-conformant starter pack (PRD-7119)

Add an `okf` entry to the `ok seed` STARTER_PACKS registry: a small mini-KB
that is conformant with Google's Open Knowledge Format (OKF) v0.1 by
construction. Every non-reserved seed doc carries a non-empty `type` (§9
rules 1-2); a lowercase, frontmatter-free `index.md` (§6 navigation) and
`log.md` (§7 change history) follow the reserved-file conventions (§9 rule 3).

Pure pre-populated content — the native frontmatter schema stays open-shaped,
nothing is enforced or linted, and `ok init` is untouched. The pack reuses the
pack-agnostic plan/apply/CLI/picker pipeline unchanged (only the registry
literal + `PackId` union widen), so it auto-appears in `ok seed --list-packs`.
Seeded links use standard markdown (a conformant OKF bundle's link graph is
plain markdown; `[[…]]` is an OK superset the export normalizes away).

Ships a guidance-only pack-local skill and an OKF §9 conformance test that runs
the real seed pipeline and asserts all three rules over the written bytes
(templates checked at their instantiated block-2 form), plus idempotent re-run.

* fix(open-knowledge): address okf pack review (PRD-7119)

Cloud-review feedback on PR #1984:

- Widen `OkPackId` in the two desktop-bridge mirror sites (core + app) to
  include `okf` — the "update all three sites" invariant the bridge-contract
  Eq<> drift test guards. Fixes real client/server type drift (server sent
  `okf`; core/app types didn't model it).
- PackCardGrid: add an `okf` icon (FileCheck) so it isn't visually identical
  to knowledge-base's Library; derive the loading-skeleton count from the icon
  map instead of a hardcoded 6; refresh the stale "Six-card" JSDoc.
- Add a non-empty `type` to the okf pack skill — it installs as project-local
  markdown that OK admits into the content corpus, so without it the seeded
  project had a non-reserved doc lacking `type` (the pack's own contract). New
  conformance test covers the editor-skill-installed path.
- Seed content uses standard markdown links everywhere (templates too); make
  the link-format comment accurate; drop `[[ ]]` from folder guidance.
- log.md seeds a prose instruction (documents the dated-entry format) instead
  of a placeholder entry, matching peer packs and avoiding a stale seeded date.
- Remove block-1 `tags:` from the templates (peers carry only title+description).
- starter.test.ts derives the reserved-file set from the exported
  `OKF_RESERVED_FILENAMES` single source of truth.

* fix(open-knowledge): sync okf skill log.md description + pin all §6 nav links

Re-review follow-ups on PR #1984:

- Update the okf pack skill's `log.md` description: the prose-only `log.md`
  change (no placeholder entry) left the SKILL.md still telling authors to
  "replace the placeholder date" on a file that no longer ships one.
- Strengthen the §6 navigation conformance test to pin all four seeded
  standard-markdown links (welcome + the three section folders), not just
  `welcome.md`.

---------

GitOrigin-RevId: 4dfa2e4aac7c01eecd4d39e3984c5545a69ec538
---
 .changeset/okf-conformant-starter-pack.md     |   5 +
 packages/app/src/components/PackCardGrid.tsx  |  14 +-
 packages/app/src/lib/desktop-bridge-types.ts  |   3 +-
 packages/core/src/desktop-bridge.ts           |   3 +-
 .../server/assets/skills/packs/okf/SKILL.md   |  52 +++++
 .../server/src/seed/okf-conformance.test.ts   | 204 ++++++++++++++++++
 packages/server/src/seed/starter.test.ts      |  11 +-
 packages/server/src/seed/starter.ts           | 144 ++++++++++++-
 8 files changed, 428 insertions(+), 8 deletions(-)
 create mode 100644 .changeset/okf-conformant-starter-pack.md
 create mode 100644 packages/server/assets/skills/packs/okf/SKILL.md
 create mode 100644 packages/server/src/seed/okf-conformance.test.ts

diff --git a/.changeset/okf-conformant-starter-pack.md b/.changeset/okf-conformant-starter-pack.md
new file mode 100644
index 00000000..24db4b49
--- /dev/null
+++ b/.changeset/okf-conformant-starter-pack.md
@@ -0,0 +1,5 @@
+---
+"@inkeep/open-knowledge": minor
+---
+
+Add an OKF-conformant starter pack: `ok seed --pack okf` (also shown by `ok seed --list-packs`) scaffolds a small knowledge base that is conformant with Google's Open Knowledge Format (OKF) v0.1 from the first commit — every non-reserved doc carries a non-empty `type`, plus a frontmatter-free lowercase `index.md` (§6 navigation) and `log.md` (§7 change history). Pure pre-populated content: the native frontmatter schema stays open-shaped and nothing is enforced or linted. Ships a guidance-only OKF conventions skill like every other pack.
diff --git a/packages/app/src/components/PackCardGrid.tsx b/packages/app/src/components/PackCardGrid.tsx
index eae18104..12aca33f 100644
--- a/packages/app/src/components/PackCardGrid.tsx
+++ b/packages/app/src/components/PackCardGrid.tsx
@@ -1,6 +1,15 @@
 // biome-ignore-all lint/plugin/no-raw-html-interactive-element: pre-rule backlog — file uses raw <button>/<input>/<textarea> awaiting shadcn migration; tracked at https://github.com/inkeep/open-knowledge/blob/main/biome-plugins/README.md#no-raw-html-interactive-elementgrit
 import { Trans, useLingui } from '@lingui/react/macro';
-import { Compass, GitBranch, Library, Loader2, Network, PenLine, StickyNote } from 'lucide-react';
+import {
+  Compass,
+  FileCheck,
+  GitBranch,
+  Library,
+  Loader2,
+  Network,
+  PenLine,
+  StickyNote,
+} from 'lucide-react';
 import { useEffect, useState } from 'react';
 import type { OkPackId, OkSeedPackInfo } from '@/lib/desktop-bridge-types';
 import { seedClient } from '@/lib/seed-client';
@@ -13,6 +22,7 @@ const PACK_ICONS: Record<OkPackId, React.ComponentType<{ className?: string }>>
   worldbuilding: Compass,
   'writing-pipeline': PenLine,
   'entity-vault': Network,
+  okf: FileCheck,
 };
 
 function iconForPack(id: string): React.ComponentType<{ className?: string }> {
@@ -74,7 +84,7 @@ export function PackCardGrid({ onPackSelect, className, packs: externalPacks }:
         aria-busy="true"
         aria-label={t`Loading starter packs`}
       >
-        {Array.from({ length: 6 }, (_, i) => i).map((i) => (
+        {Array.from({ length: Object.keys(PACK_ICONS).length }, (_, i) => i).map((i) => (
           <PackCardSkeleton key={`skeleton-${i}`} />
         ))}
       </div>
diff --git a/packages/app/src/lib/desktop-bridge-types.ts b/packages/app/src/lib/desktop-bridge-types.ts
index 1b9ce046..b295cdc7 100644
--- a/packages/app/src/lib/desktop-bridge-types.ts
+++ b/packages/app/src/lib/desktop-bridge-types.ts
@@ -53,7 +53,8 @@ export type OkPackId =
   | 'plain-notes'
   | 'worldbuilding'
   | 'writing-pipeline'
-  | 'entity-vault';
+  | 'entity-vault'
+  | 'okf';
 
 interface OkSeedPlanOptions {
   rootDir?: string;
diff --git a/packages/core/src/desktop-bridge.ts b/packages/core/src/desktop-bridge.ts
index 87ac5b65..147fc99e 100644
--- a/packages/core/src/desktop-bridge.ts
+++ b/packages/core/src/desktop-bridge.ts
@@ -270,7 +270,8 @@ type OkPackId =
   | 'plain-notes'
   | 'worldbuilding'
   | 'writing-pipeline'
-  | 'entity-vault';
+  | 'entity-vault'
+  | 'okf';
 
 interface OkSeedPlanOptions {
   rootDir?: string;
diff --git a/packages/server/assets/skills/packs/okf/SKILL.md b/packages/server/assets/skills/packs/okf/SKILL.md
new file mode 100644
index 00000000..a74d5f1c
--- /dev/null
+++ b/packages/server/assets/skills/packs/okf/SKILL.md
@@ -0,0 +1,52 @@
+---
+name: open-knowledge-pack-okf
+description: "How to work in an OKF starter project (the `okf` starter pack): a knowledge base that is conformant with Google's Open Knowledge Format (OKF) from commit one — `concepts/`, `references/`, `notes/`, a reserved `index.md` navigation hub, and a reserved `log.md` change history. Read when the project has these folders + reserved files. Carries the OKF conventions (non-empty `type` on every non-reserved doc; reserved files carry no frontmatter) as guidance, not enforcement. Complements the platform `open-knowledge` skill; does not replace it."
+compatibility: "Claude Code, Claude Desktop, Claude Cowork, Claude.ai web. Requires Open Knowledge MCP server. Installed project-local by `ok seed --pack okf`."
+# `type` keeps this skill doc OKF-conformant: it installs as project-local
+# markdown under `.claude`/`.cursor`/`.agents` skills dirs, which OK admits into
+# the content corpus — so without a non-empty `type` it would be a non-reserved
+# doc that violates the pack's own "every non-reserved doc has a `type`" contract.
+type: Document
+metadata:
+  pack: "okf"
+  author: "Inkeep"
+  repository: "https://github.com/inkeep/open-knowledge"
+---
+# OKF starter pack — how to work here
+
+This project was scaffolded to be conformant with **Google's Open Knowledge Format (OKF) v0.1** from the first commit — markdown + YAML frontmatter, a standard-markdown link graph, and two reserved files. Conformance here is pre-populated, **not enforced**: Open Knowledge's native frontmatter schema stays open-shaped, nothing is linted, and you are free to author however you like. This skill explains the conventions so the kit stays OKF-portable as it grows.
+
+> This skill is pack guidance. The platform `open-knowledge` skill (read/write/preview/grounding rules) still governs every markdown operation — this layers OKF conventions on top.
+
+## The one rule (keep the kit conformant)
+
+OKF requires exactly one thing of every **non-reserved** document: a **non-empty `type`** in its frontmatter. That is the whole conformance contract for your content.
+
+- The value is **yours to choose** — `concept`, `reference`, `note`, `person`, `event`, anything that fits. There is no blessed taxonomy.
+- `Document` is a fine **generic fallback** when nothing more specific fits (it is just a non-empty value, not a special keyword).
+- The folder templates already set a sensible `type` per section — create docs with `write({ document: { path, template: "<name>" } })` and you inherit it.
+
+## Folders
+
+- **`concepts/`** — durable ideas and definitions, one file per concept (`type: concept`).
+- **`references/`** — external sources and citations you rely on (`type: reference`).
+- **`notes/`** — working notes and observations (`type: note`).
+
+Link liberally with **standard markdown links** (`[text](./path.md)`) — the value is the graph that emerges from the links between typed docs, and standard links keep that graph portable to any OKF consumer. (Open Knowledge also accepts `[[wiki-link]]` shorthand as a native superset, and the OKF export normalizes it to standard links — but seeded content uses standard links so the bundle is conformant as-is.)
+
+## Reserved files (keep them frontmatter-free)
+
+OKF reserves two lowercase files at the project root. **Neither carries frontmatter** — adding any frontmatter to a reserved file breaks OKF conformance.
+
+- **`index.md`** (OKF §6) — the navigation hub: a link-list to the key docs and sections. Keep it current as you add important docs; it is how a reader (or a strict OKF consumer) finds their way in.
+- **`log.md`** (OKF §7) — the change history: newest-first dated entries shaped `## YYYY-MM-DD: <summary>`. Add an entry whenever you create, edit, or restructure content. The seed ships a prose instruction documenting this format — add your first dated entry on your first edit.
+
+The tool does not keep these live for you (that would be enforcement) — maintaining them is part of authoring here.
+
+## What stays OKF-portable
+
+- Every non-reserved doc has a non-empty `type`. ✅
+- `index.md` / `log.md` stay lowercase and frontmatter-free. ✅
+- Links use standard markdown / wiki-link syntax. ✅
+
+If you ever want to hand this knowledge base to a strict OKF consumer, those three habits are all it takes.
diff --git a/packages/server/src/seed/okf-conformance.test.ts b/packages/server/src/seed/okf-conformance.test.ts
new file mode 100644
index 00000000..b3587af6
--- /dev/null
+++ b/packages/server/src/seed/okf-conformance.test.ts
@@ -0,0 +1,204 @@
+import { describe, expect, test } from 'bun:test';
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join, relative } from 'node:path';
+import {
+  parseFrontmatterYaml,
+  stripFrontmatter,
+  unwrapFrontmatterFences,
+} from '@inkeep/open-knowledge-core';
+import { applySubstitution } from '../content/substitution.ts';
+import { applySeed } from './apply.ts';
+import { planSeed } from './plan.ts';
+import { OKF_RESERVED_FILENAMES, STARTER_PACKS } from './starter.ts';
+
+const OKF_PACK = STARTER_PACKS.okf;
+const OKF_INDEX_BODY = OKF_PACK.rootFiles?.['index.md'];
+const OKF_LOG_BODY = OKF_PACK.rootFiles?.['log.md'];
+if (!OKF_INDEX_BODY || !OKF_LOG_BODY) {
+  throw new Error('okf pack is missing its reserved index.md / log.md root files');
+}
+
+const RESERVED_FILES = new Set(OKF_RESERVED_FILENAMES);
+
+function collectMarkdown(root: string, dir = root): string[] {
+  const out: string[] = [];
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const abs = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      out.push(...collectMarkdown(root, abs));
+    } else if (entry.name.endsWith('.md')) {
+      out.push(relative(root, abs));
+    }
+  }
+  return out;
+}
+
+function consumerFrontmatterYaml(relPath: string, raw: string): string | null {
+  const isTemplate = relPath.includes('/.ok/templates/');
+  const docSource = isTemplate
+    ? applySubstitution(stripFrontmatter(raw).body, { date: '2026-01-01', user: 'Test User' })
+    : raw;
+  const { frontmatter } = stripFrontmatter(docSource);
+  if (frontmatter === '') return null;
+  return unwrapFrontmatterFences(frontmatter);
+}
+
+async function seedOkf(): Promise<{ projectDir: string; cleanup: () => Promise<void> }> {
+  const projectDir = await mkdtemp(join(tmpdir(), 'seed-okf-'));
+  mkdirSync(join(projectDir, '.ok'), { recursive: true });
+  writeFileSync(join(projectDir, '.ok', 'config.yml'), '', 'utf-8');
+  const plan = await planSeed({ projectDir, packId: 'okf' });
+  const result = await applySeed(plan, { projectDir, packId: 'okf' });
+  expect(result.errors).toEqual([]);
+  return {
+    projectDir,
+    cleanup: () => rm(projectDir, { recursive: true, force: true }),
+  };
+}
+
+describe('okf pack — OKF §9 conformance by construction', () => {
+  test('rule 1+2: every non-reserved seed .md parses to frontmatter with a non-empty type', async () => {
+    const { projectDir, cleanup } = await seedOkf();
+    try {
+      const docs = collectMarkdown(projectDir).filter((p) => !RESERVED_FILES.has(p));
+      expect(docs).toContain('welcome.md');
+      expect(docs.length).toBeGreaterThanOrEqual(4);
+
+      for (const relPath of docs) {
+        const raw = readFileSync(join(projectDir, relPath), 'utf-8');
+        const yaml = consumerFrontmatterYaml(relPath, raw);
+        expect(yaml, `${relPath}: rule 1 — no parseable frontmatter block`).not.toBeNull();
+
+        const parsed = parseFrontmatterYaml(yaml ?? '');
+        expect(
+          parsed.map,
+          `${relPath}: rule 1 — frontmatter failed to parse (${parsed.parseError ?? ''})`,
+        ).not.toBeNull();
+
+        const type = parsed.map?.type;
+        expect(
+          typeof type === 'string' && type.trim().length > 0,
+          `${relPath}: rule 2 — \`type\` must be a non-empty string, got ${JSON.stringify(type)}`,
+        ).toBe(true);
+      }
+    } finally {
+      await cleanup();
+    }
+  });
+
+  test('rule 3: reserved index.md/log.md are lowercase, present at root, and carry ZERO frontmatter', async () => {
+    const { projectDir, cleanup } = await seedOkf();
+    try {
+      for (const reserved of RESERVED_FILES) {
+        const abs = join(projectDir, reserved);
+        expect(existsSync(abs), `${reserved} must be seeded at the bundle root`).toBe(true);
+        const raw = readFileSync(abs, 'utf-8');
+        expect(raw.startsWith('---'), `${reserved} must NOT carry frontmatter`).toBe(false);
+        expect(stripFrontmatter(raw).frontmatter, `${reserved} has a frontmatter block`).toBe('');
+      }
+    } finally {
+      await cleanup();
+    }
+  });
+
+  test('rule 3: index.md matches OKF §6 navigation structure (H1 + standard-markdown link list)', async () => {
+    const { projectDir, cleanup } = await seedOkf();
+    try {
+      const index = readFileSync(join(projectDir, 'index.md'), 'utf-8');
+      expect(index.startsWith('# '), 'index.md should open with an H1 navigation heading').toBe(
+        true,
+      );
+      for (const link of [
+        '[welcome](./welcome.md)',
+        '[concepts/](./concepts/)',
+        '[references/](./references/)',
+        '[notes/](./notes/)',
+      ]) {
+        expect(index, `index.md should link ${link} in standard markdown`).toContain(link);
+      }
+      expect(index, 'seeded nav must not use [[wiki-link]] shorthand').not.toMatch(
+        /\[\[[^\]]+\]\]/,
+      );
+    } finally {
+      await cleanup();
+    }
+  });
+
+  test('rule 3: log.md matches OKF §7 change-history structure (H1 + documents the dated-entry format)', async () => {
+    const { projectDir, cleanup } = await seedOkf();
+    try {
+      const log = readFileSync(join(projectDir, 'log.md'), 'utf-8');
+      expect(log.startsWith('# '), 'log.md should open with an H1 heading').toBe(true);
+      expect(log).toMatch(/## YYYY-MM-DD: <summary>/);
+      expect(log.toLowerCase()).toContain('change history');
+    } finally {
+      await cleanup();
+    }
+  });
+
+  test('apply writes the reserved-file bodies to disk verbatim (no {{date}} substitution on root files)', async () => {
+    const { projectDir, cleanup } = await seedOkf();
+    try {
+      expect(readFileSync(join(projectDir, 'index.md'), 'utf-8')).toBe(OKF_INDEX_BODY);
+      expect(readFileSync(join(projectDir, 'log.md'), 'utf-8')).toBe(OKF_LOG_BODY);
+    } finally {
+      await cleanup();
+    }
+  });
+
+  test('idempotent + non-destructive: a second seed writes nothing new and never overwrites', async () => {
+    const { projectDir, cleanup } = await seedOkf();
+    try {
+      const welcomeAbs = join(projectDir, 'welcome.md');
+      writeFileSync(welcomeAbs, 'EDITED BY USER\n', 'utf-8');
+
+      const plan2 = await planSeed({ projectDir, packId: 'okf' });
+      expect(plan2.created, 're-run should plan zero new writes').toEqual([]);
+      const result2 = await applySeed(plan2, { projectDir, packId: 'okf' });
+      expect(result2.errors).toEqual([]);
+      expect(result2.applied).toBe(0);
+      expect(readFileSync(welcomeAbs, 'utf-8')).toBe('EDITED BY USER\n');
+    } finally {
+      await cleanup();
+    }
+  });
+
+  test('rule 2 holds with an editor present: the installed pack skill markdown carries a non-empty type', async () => {
+    const projectDir = await mkdtemp(join(tmpdir(), 'seed-okf-skill-'));
+    try {
+      mkdirSync(join(projectDir, '.ok'), { recursive: true });
+      writeFileSync(join(projectDir, '.ok', 'config.yml'), '', 'utf-8');
+      const platformSkillDir = join(projectDir, '.claude', 'skills', 'open-knowledge');
+      mkdirSync(platformSkillDir, { recursive: true });
+      writeFileSync(
+        join(platformSkillDir, 'SKILL.md'),
+        '---\nname: open-knowledge\n---\n',
+        'utf-8',
+      );
+
+      const plan = await planSeed({ projectDir, packId: 'okf' });
+      const result = await applySeed(plan, { projectDir, packId: 'okf' });
+      expect(result.errors).toEqual([]);
+      expect(result.packSkillsInstalled).toContain('Claude Code');
+
+      const packSkillDir = join(projectDir, '.claude', 'skills', 'open-knowledge-pack-okf');
+      const skillDocs = collectMarkdown(packSkillDir).map((p) => join(packSkillDir, p));
+      expect(skillDocs.length).toBeGreaterThanOrEqual(1);
+      for (const abs of skillDocs) {
+        const raw = readFileSync(abs, 'utf-8');
+        const { frontmatter } = stripFrontmatter(raw);
+        expect(frontmatter, `${abs}: installed skill doc must carry frontmatter`).not.toBe('');
+        const parsed = parseFrontmatterYaml(unwrapFrontmatterFences(frontmatter));
+        const type = parsed.map?.type;
+        expect(
+          typeof type === 'string' && type.trim().length > 0,
+          `${abs}: installed skill doc must carry a non-empty \`type\` (OKF rule 2), got ${JSON.stringify(type)}`,
+        ).toBe(true);
+      }
+    } finally {
+      await rm(projectDir, { recursive: true, force: true });
+    }
+  });
+});
diff --git a/packages/server/src/seed/starter.test.ts b/packages/server/src/seed/starter.test.ts
index b0af991b..3fd74769 100644
--- a/packages/server/src/seed/starter.test.ts
+++ b/packages/server/src/seed/starter.test.ts
@@ -2,6 +2,7 @@ import { describe, expect, test } from 'bun:test';
 import {
   buildStarterFolderFrontmatterYaml,
   listStarterPacks,
+  OKF_RESERVED_FILENAMES,
   STARTER_FOLDER_FRONTMATTER_FILENAME,
   STARTER_PACK_IDS,
   STARTER_PACKS,
@@ -136,11 +137,12 @@ describe('STARTER_FOLDER_FRONTMATTER_FILENAME', () => {
 });
 
 describe('STARTER_PACKS — all packs structural validation', () => {
-  test('STARTER_PACK_IDS contains exactly the 6 expected packs (pinned to detect silent additions/deletions)', () => {
-    expect(STARTER_PACK_IDS.length).toBe(6);
+  test('STARTER_PACK_IDS contains exactly the 7 expected packs (pinned to detect silent additions/deletions)', () => {
+    expect(STARTER_PACK_IDS.length).toBe(7);
     expect([...STARTER_PACK_IDS].sort()).toEqual([
       'entity-vault',
       'knowledge-base',
+      'okf',
       'plain-notes',
       'software-lifecycle',
       'worldbuilding',
@@ -254,9 +256,12 @@ describe('STARTER_PACKS — all packs structural validation', () => {
     }
   });
 
-  test('every rootFile body has frontmatter with a non-empty title', () => {
+  const OKF_RESERVED_ROOTFILES = new Set(OKF_RESERVED_FILENAMES);
+
+  test('every non-reserved rootFile body has frontmatter with a non-empty title', () => {
     for (const pack of Object.values(STARTER_PACKS)) {
       for (const [filename, body] of Object.entries(pack.rootFiles ?? {})) {
+        if (pack.id === 'okf' && OKF_RESERVED_ROOTFILES.has(filename)) continue;
         expect(
           body.startsWith('---\n'),
           `Pack "${pack.id}" rootFile "${filename}" missing frontmatter`,
diff --git a/packages/server/src/seed/starter.ts b/packages/server/src/seed/starter.ts
index 5f66d6d6..b317849b 100644
--- a/packages/server/src/seed/starter.ts
+++ b/packages/server/src/seed/starter.ts
@@ -4,7 +4,8 @@ export type PackId =
   | 'plain-notes'
   | 'worldbuilding'
   | 'writing-pipeline'
-  | 'entity-vault';
+  | 'entity-vault'
+  | 'okf';
 
 export const DEFAULT_PACK_ID: PackId = 'knowledge-base';
 
@@ -1047,6 +1048,132 @@ description: When the agent does scheduled work: daily briefings, end-of-day dos
 
 `;
 
+const OKF_FOLDERS: readonly StarterFolder[] = [
+  {
+    path: 'concepts',
+    title: 'Concepts',
+    description:
+      'Durable ideas and definitions, one file per concept. Each doc carries `type: concept` in its frontmatter. Link related concepts so the graph builds itself.',
+    tags: ['concept', 'okf'],
+    starterTemplate: 'concept',
+  },
+  {
+    path: 'references',
+    title: 'References',
+    description:
+      'External sources and citations you rely on, one file per source. Each doc carries `type: reference`. Link the docs that cite a reference so the evidence trail stays navigable.',
+    tags: ['reference', 'okf'],
+    starterTemplate: 'reference',
+  },
+  {
+    path: 'notes',
+    title: 'Notes',
+    description:
+      'Working notes and observations, one file per note. Each doc carries `type: note`. The lightest section — capture first, link as ideas connect.',
+    tags: ['note', 'okf'],
+    starterTemplate: 'note',
+  },
+] as const;
+
+const OKF_TEMPLATES: Readonly<Record<string, string>> = {
+  concept: `---
+title: Concept Name
+description: One-line definition of the concept.
+---
+---
+type: concept
+created: {{date}}
+author: {{user}}
+tags: [concept]
+---
+
+## Definition
+
+## Why it matters
+
+## Related
+
+- Link a related idea, e.g. [another concept](./another-concept.md).
+`,
+  reference: `---
+title: Reference Title
+description: One-line summary of the source.
+---
+---
+type: reference
+created: {{date}}
+author: {{user}}
+tags: [reference]
+---
+
+## Summary
+
+## Key points
+
+## Where this is used
+
+- Link the docs that cite this reference.
+`,
+  note: `---
+title: Note Title
+description: One-line summary of the note.
+---
+---
+type: note
+created: {{date}}
+author: {{user}}
+tags: [note]
+---
+
+## Note
+
+## Links
+`,
+};
+
+const OKF_WELCOME_MD = `---
+title: Welcome
+description: Start here — what this knowledge base is and how it is organized.
+type: Document
+tags: [welcome]
+---
+
+# Welcome
+
+This knowledge base was scaffolded with the **OKF starter pack**, so it is conformant with the Open Knowledge Format (OKF) from the first commit.
+
+## How it is organized
+
+- [index](./index.md) — the navigation hub (a reserved OKF file; carries no frontmatter).
+- [log](./log.md) — the change history (a reserved OKF file; carries no frontmatter).
+- [concepts/](./concepts/), [references/](./references/), [notes/](./notes/) — your content. Every document here carries a non-empty \`type\` in its frontmatter.
+
+## The one rule
+
+OKF requires exactly one thing of every non-reserved document: a non-empty \`type\`. The value is yours to choose — \`concept\`, \`reference\`, \`note\`, or anything that fits. \`Document\` is a fine generic fallback.
+
+See the project skill for the full set of conventions.
+`;
+
+const OKF_INDEX_MD = `# Index
+
+The navigation hub for this knowledge base. Start with [welcome](./welcome.md), then explore by section.
+
+## Sections
+
+- [welcome](./welcome.md) — what this knowledge base is and how it is organized
+- [concepts/](./concepts/) — durable ideas and definitions, one file per concept (\`type: concept\`)
+- [references/](./references/) — sources and citations you rely on (\`type: reference\`)
+- [notes/](./notes/) — working notes and observations (\`type: note\`)
+
+Every document outside this file and \`log.md\` carries a non-empty \`type\` in its frontmatter — that is all OKF requires.
+`;
+
+const OKF_LOG_MD = `# Log
+
+Change history for this knowledge base, newest entry first. Add a dated entry (\`## YYYY-MM-DD: <summary>\`) whenever you create, edit, or restructure content — one entry per working session, not per file.
+`;
+
 export const STARTER_PACKS: Readonly<Record<PackId, StarterPack>> = {
   'knowledge-base': {
     id: 'knowledge-base',
@@ -1104,10 +1231,25 @@ export const STARTER_PACKS: Readonly<Record<PackId, StarterPack>> = {
       'HEARTBEAT.md': ENTITY_VAULT_HEARTBEAT_MD,
     },
   },
+  okf: {
+    id: 'okf',
+    name: 'OKF starter',
+    description: 'An Open Knowledge Format–conformant knowledge base.',
+    defaultSubfolder: undefined,
+    folders: OKF_FOLDERS,
+    templates: OKF_TEMPLATES,
+    rootFiles: {
+      'welcome.md': OKF_WELCOME_MD,
+      'index.md': OKF_INDEX_MD,
+      'log.md': OKF_LOG_MD,
+    },
+  },
 };
 
 export const STARTER_PACK_IDS: readonly PackId[] = Object.keys(STARTER_PACKS) as PackId[];
 
+export const OKF_RESERVED_FILENAMES: readonly string[] = ['index.md', 'log.md'];
+
 export function resolvePack(packId?: PackId): StarterPack {
   if (!packId) return STARTER_PACKS[DEFAULT_PACK_ID];
   const pack = STARTER_PACKS[packId];