Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
feat(open-knowledge): OKF-conformant starter pack (`ok seed --pack okf`) (#1984)
serafin-garciae527b19eba7f
diff --git a/.changeset/okf-conformant-starter-pack.md b/.changeset/okf-conformant-starter-pack.mdnew file mode 100644index 000000000..24db4b49c--- /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.tsxindex eae18104d..12aca33fc 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-elementgritimport { 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.tsindex 1b9ce0466..b295cdc76 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.tsindex 87ac5b652..147fc99e9 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.mdnew file mode 100644index 000000000..a74d5f1c0--- /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.tsnew file mode 100644index 000000000..b3587af68--- /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.tsindex b0af991b4..3fd747693 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.tsindex 5f66d6d65..b317849ba 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];