Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
Reference a starter pack for inspiration (ok seed --dry-run + skill + handoff pointer) (#1982)
tim-inkeep1e55fa496825
diff --git a/packages/app/src/components/handoff/useHandoffDispatch.test.ts b/packages/app/src/components/handoff/useHandoffDispatch.test.tsindex 9f6045f68..42edf4eb6 100644--- a/packages/app/src/components/handoff/useHandoffDispatch.test.ts+++ b/packages/app/src/components/handoff/useHandoffDispatch.test.ts@@ -1,6 +1,7 @@import { describe, expect, mock, test } from 'bun:test';import { setTimeout as wait } from 'node:timers/promises';import type { HandoffOutcome, HandoffPayload, HandoffTarget } from '@inkeep/open-knowledge-core';+import { withSkillPointer } from '@inkeep/open-knowledge-core';import type {HandoffDispatchDeps,HandoffDispatchInput,@@ -187,7 +188,9 @@ describe('runHandoffDispatch — success path', () => {'/tmp/demo-project/specs/2026-04-21-open-in-agent-desktop/SPEC.md',);expect(payload.prompt).toBe(- "Let's work on `specs/2026-04-21-open-in-agent-desktop/SPEC.md` using Open Knowledge. Open the OK editor in web view.",+ withSkillPointer(+ "Let's work on `specs/2026-04-21-open-in-agent-desktop/SPEC.md` using Open Knowledge. Open the OK editor in web view.",+ ),);});@@ -225,9 +228,11 @@ describe('runHandoffDispatch — success path', () => {expect(payload.target).toBe('codex');expect(payload.projectDir).toBe('/Users/sarah/proj');expect(payload.docPath).toBe('');- expect(payload.prompt).toBe(composeEmptySpacePrompt(true));+ expect(payload.prompt).toBe(withSkillPointer(composeEmptySpacePrompt(true)));expect(payload.prompt).toBe(- "Let's work on this project using Open Knowledge. Open the OK editor in web view.",+ withSkillPointer(+ "Let's work on this project using Open Knowledge. Open the OK editor in web view.",+ ),);});@@ -251,10 +256,12 @@ describe('runHandoffDispatch — success path', () => {expect(payload.projectDir).toBe('/Users/sarah/proj');expect(payload.docPath).toBe('');expect(payload.prompt).toBe(- composeFolderPrompt('specs/2026-05-16-sidebar-context-menus', true),+ withSkillPointer(composeFolderPrompt('specs/2026-05-16-sidebar-context-menus', true)),);expect(payload.prompt).toBe(- "Let's work on the `specs/2026-05-16-sidebar-context-menus` folder using Open Knowledge. Open the OK editor in web view.",+ withSkillPointer(+ "Let's work on the `specs/2026-05-16-sidebar-context-menus` folder using Open Knowledge. Open the OK editor in web view.",+ ),);});});@@ -267,7 +274,9 @@ describe('runHandoffDispatch — autoOpen=false honors the user preference', ()const [payload] = (deps.dispatchHandoff as ReturnType<typeof mock>).mock.calls[0] as [HandoffPayload,];- expect(payload.prompt).toBe("Let's work on `specs/foo/SPEC.md` using Open Knowledge.");+ expect(payload.prompt).toBe(+ withSkillPointer("Let's work on `specs/foo/SPEC.md` using Open Knowledge."),+ );expect(payload.prompt).not.toContain('Open the OK editor');});@@ -284,7 +293,9 @@ describe('runHandoffDispatch — autoOpen=false honors the user preference', ()const [payload] = (deps.dispatchHandoff as ReturnType<typeof mock>).mock.calls[0] as [HandoffPayload,];- expect(payload.prompt).toBe("Let's work on the `specs/notes` folder using Open Knowledge.");+ expect(payload.prompt).toBe(+ withSkillPointer("Let's work on the `specs/notes` folder using Open Knowledge."),+ );expect(payload.prompt).not.toContain('Open the OK editor');});@@ -300,7 +311,9 @@ describe('runHandoffDispatch — autoOpen=false honors the user preference', ()const [payload] = (deps.dispatchHandoff as ReturnType<typeof mock>).mock.calls[0] as [HandoffPayload,];- expect(payload.prompt).toBe("Let's work on this project using Open Knowledge.");+ expect(payload.prompt).toBe(+ withSkillPointer("Let's work on this project using Open Knowledge."),+ );expect(payload.prompt).not.toContain('Open the OK editor');});});@@ -783,9 +796,11 @@ describe('selectScopedPrompt — template selection across autoOpen modes', () ='claude-code',true,);- expect(out).toBe(composeFilePrompt('notes/today.md', true));+ expect(out).toBe(withSkillPointer(composeFilePrompt('notes/today.md', true)));expect(out).toBe(- "Let's work on `notes/today.md` using Open Knowledge. Open the OK editor in web view.",+ withSkillPointer(+ "Let's work on `notes/today.md` using Open Knowledge. Open the OK editor in web view.",+ ),);});@@ -800,7 +815,7 @@ describe('selectScopedPrompt — template selection across autoOpen modes', () ='claude-code',false,);- expect(out).toBe("Let's work on `notes/today.md` using Open Knowledge.");+ expect(out).toBe(withSkillPointer("Let's work on `notes/today.md` using Open Knowledge."));});test('folder scope (docContext null + folderRelativePath set) returns composeFolderPrompt with autoOpen=true trailer', async () => {@@ -816,9 +831,11 @@ describe('selectScopedPrompt — template selection across autoOpen modes', () ='claude-code',true,);- expect(out).toBe(composeFolderPrompt('notes', true));+ expect(out).toBe(withSkillPointer(composeFolderPrompt('notes', true)));expect(out).toBe(- "Let's work on the `notes` folder using Open Knowledge. Open the OK editor in web view.",+ withSkillPointer(+ "Let's work on the `notes` folder using Open Knowledge. Open the OK editor in web view.",+ ),);});@@ -834,7 +851,7 @@ describe('selectScopedPrompt — template selection across autoOpen modes', () ='claude-code',false,);- expect(out).toBe("Let's work on the `notes` folder using Open Knowledge.");+ expect(out).toBe(withSkillPointer("Let's work on the `notes` folder using Open Knowledge."));});test('empty-space scope (both null/absent) returns composeEmptySpacePrompt(autoOpen=true)', async () => {@@ -849,9 +866,11 @@ describe('selectScopedPrompt — template selection across autoOpen modes', () ='claude-code',true,);- expect(out).toBe(composeEmptySpacePrompt(true));+ expect(out).toBe(withSkillPointer(composeEmptySpacePrompt(true)));expect(out).toBe(- "Let's work on this project using Open Knowledge. Open the OK editor in web view.",+ withSkillPointer(+ "Let's work on this project using Open Knowledge. Open the OK editor in web view.",+ ),);});@@ -866,7 +885,7 @@ describe('selectScopedPrompt — template selection across autoOpen modes', () ='claude-code',false,);- expect(out).toBe("Let's work on this project using Open Knowledge.");+ expect(out).toBe(withSkillPointer("Let's work on this project using Open Knowledge."));});test('file scope threads the toolbar instruction into the directive prompt', async () => {@@ -882,7 +901,9 @@ describe('selectScopedPrompt — template selection across autoOpen modes', () ='claude-code',true,);- expect(out).toBe(composeFilePrompt('notes/today.md', true, 'Tighten the intro'));+ expect(out).toBe(+ withSkillPointer(composeFilePrompt('notes/today.md', true, 'Tighten the intro')),+ );expect(out).toContain('Instruction:\n\n> Tighten the intro');});@@ -988,7 +1009,9 @@ describe('selectScopedPrompt — template selection across autoOpen modes', () ='claude-code',true,);- expect(out).toBe(composeCreatePrompt('a worldbuilding wiki', true, 'new-project'));+ expect(out).toBe(+ withSkillPointer(composeCreatePrompt('a worldbuilding wiki', true, 'new-project')),+ );expect(out).toContain('> a worldbuilding wiki');expect(out).toContain('Open the OK editor in web view.');});@@ -1018,7 +1041,7 @@ describe('selectScopedPrompt — template selection across autoOpen modes', () ='claude-code',false,);- expect(out).toBe(composeCreatePrompt('a wiki', false, 'new-project'));+ expect(out).toBe(withSkillPointer(composeCreatePrompt('a wiki', false, 'new-project')));});test('create scope with empty createDescription routes to the create composer, NOT empty-space', async () => {@@ -1037,8 +1060,8 @@ describe('selectScopedPrompt — template selection across autoOpen modes', () ='claude-code',true,);- expect(out).toBe(composeCreatePrompt('', true, 'new-project'));- expect(out).not.toBe(composeEmptySpacePrompt(true));+ expect(out).toBe(withSkillPointer(composeCreatePrompt('', true, 'new-project')));+ expect(out).not.toBe(withSkillPointer(composeEmptySpacePrompt(true)));});test('precedence: docContext beats folderRelativePath when both are set (defensive ordering)', async () => {@@ -1054,7 +1077,7 @@ describe('selectScopedPrompt — template selection across autoOpen modes', () ='claude-code',true,);- expect(out).toBe(composeFilePrompt('a.md', true));+ expect(out).toBe(withSkillPointer(composeFilePrompt('a.md', true)));});test('selection scope (selection set) returns composeSelectionPrompt for the target', async () => {@@ -1078,6 +1101,43 @@ describe('selectScopedPrompt — template selection across autoOpen modes', () =expect(out).toBe(composeSelectionPrompt({ ...selection, target: 'cursor' }));});+ test('the standing skill pointer rides every directive scope but NOT selection', async () => {+ const { selectScopedPrompt } = await import('./useHandoffDispatch');+ const { OK_PROJECT_SKILL_POINTER } = await import('@inkeep/open-knowledge-core');+ const base = { projectDir: '/proj', docPath: '' } as const;++ const file = selectScopedPrompt(+ { ...base, docContext: { relativePath: 'a.md' }, docPath: '/proj/a.md' },+ 'claude-code',+ true,+ );+ const folder = selectScopedPrompt(+ { ...base, docContext: null, folderRelativePath: 'specs' },+ 'claude-code',+ true,+ );+ const empty = selectScopedPrompt({ ...base, docContext: null }, 'claude-code', true);+ const create = selectScopedPrompt(+ { ...base, docContext: null, createDescription: 'a wiki' },+ 'claude-code',+ true,+ );+ const selection = selectScopedPrompt(+ {+ ...base,+ docContext: null,+ selection: { relativePath: 'a.md', instruction: 'x', selectionMarkdown: 'y' },+ },+ 'claude-code',+ true,+ );++ for (const prompt of [file, folder, empty, create]) {+ expect(prompt.startsWith(OK_PROJECT_SKILL_POINTER)).toBe(true);+ }+ expect(selection).not.toContain(OK_PROJECT_SKILL_POINTER);+ });+test('precedence: selection beats docContext when both are set (defensive ordering)', async () => {const { selectScopedPrompt } = await import('./useHandoffDispatch');const { composeSelectionPrompt } = await import('@inkeep/open-knowledge-core');@@ -1309,7 +1369,7 @@ describe('composeTerminalLaunchPrompt — docked-terminal launcher always suppreprojectDir: '/proj',docPath: '/proj/notes/today.md',});- expect(out).toBe("Let's work on `notes/today.md` using Open Knowledge.");+ expect(out).toBe(withSkillPointer("Let's work on `notes/today.md` using Open Knowledge."));expect(out).not.toContain('Open the OK editor');});@@ -1321,7 +1381,9 @@ describe('composeTerminalLaunchPrompt — docked-terminal launcher always suppreprojectDir: '/proj',docPath: '',});- expect(out).toBe("Let's work on the `specs/foo` folder using Open Knowledge.");+ expect(out).toBe(+ withSkillPointer("Let's work on the `specs/foo` folder using Open Knowledge."),+ );expect(out).not.toContain('Open the OK editor');});@@ -1332,7 +1394,7 @@ describe('composeTerminalLaunchPrompt — docked-terminal launcher always suppreprojectDir: '/proj',docPath: '',});- expect(out).toBe("Let's work on this project using Open Knowledge.");+ expect(out).toBe(withSkillPointer("Let's work on this project using Open Knowledge."));expect(out).not.toContain('Open the OK editor');});diff --git a/packages/app/src/components/handoff/useHandoffDispatch.ts b/packages/app/src/components/handoff/useHandoffDispatch.tsindex 38bf136c1..d1a8271fd 100644--- a/packages/app/src/components/handoff/useHandoffDispatch.ts+++ b/packages/app/src/components/handoff/useHandoffDispatch.ts@@ -11,6 +11,7 @@ import {type HandoffScope,type HandoffTarget,type TargetData,+ withSkillPointer,} from '@inkeep/open-knowledge-core';import { toast as sonnerToast } from 'sonner';import { useConfigContext } from '@/lib/config-context';@@ -224,20 +225,19 @@ export function selectScopedPrompt(if (input.selection) {return composeSelectionPrompt({ ...input.selection, target });}- if (input.docContext !== null) {- return composeFilePrompt(input.docContext.relativePath, autoOpen, input.instruction);- }- if (input.folderRelativePath) {- return composeFolderPrompt(input.folderRelativePath, autoOpen, input.instruction);- }- if (input.createDescription !== undefined) {- return composeCreatePrompt(- input.createDescription,- autoOpen,- input.createScenario ?? 'new-project',- );- }- return composeEmptySpacePrompt(autoOpen, input.instruction);+ const directive =+ input.docContext !== null+ ? composeFilePrompt(input.docContext.relativePath, autoOpen, input.instruction)+ : input.folderRelativePath+ ? composeFolderPrompt(input.folderRelativePath, autoOpen, input.instruction)+ : input.createDescription !== undefined+ ? composeCreatePrompt(+ input.createDescription,+ autoOpen,+ input.createScenario ?? 'new-project',+ )+ : composeEmptySpacePrompt(autoOpen, input.instruction);+ return withSkillPointer(directive);}export function composeTerminalLaunchPrompt(input: HandoffDispatchInput): string {diff --git a/packages/cli/src/commands/seed.test.ts b/packages/cli/src/commands/seed.test.tsindex f981cd110..45a501999 100644--- a/packages/cli/src/commands/seed.test.ts+++ b/packages/cli/src/commands/seed.test.ts@@ -79,6 +79,20 @@ describe('runSeed — --dry-run', () => {}expect(existsSync(join(testDir, 'log.md'))).toBe(false);});++ test('surfaces the pack rationale (per-folder why) + anti-clone note for inspiration', async () => {+ scaffoldOkDir(testDir);+ const result = await runSeed({ cwd: testDir, pack: 'worldbuilding', dryRun: true });+ expect(result.status).toBe('dry-run');+ const pack = STARTER_PACKS.worldbuilding;+ for (const folder of pack.folders) {+ expect(result.message).toContain(folder.description);+ }+ expect(result.message.toLowerCase()).toContain('adapt'); // anti-clone framing+ for (const folder of pack.folders) {+ expect(existsSync(join(testDir, folder.path))).toBe(false);+ }+ });});describe('runSeed — no-op', () => {diff --git a/packages/cli/src/commands/seed.ts b/packages/cli/src/commands/seed.tsindex cccc468d3..13420d27c 100644--- a/packages/cli/src/commands/seed.ts+++ b/packages/cli/src/commands/seed.ts@@ -3,6 +3,7 @@ import { createInterface } from 'node:readline/promises';import {applySeed,DEFAULT_PACK_ID,+ formatPackRationale,type PackId,planSeed,type ScaffoldPlan,@@ -74,9 +75,10 @@ export async function runSeed(opts: SeedCommandOptions = {}): Promise<SeedComman}if (opts.dryRun) {+ const rationale = formatPackRationale(STARTER_PACKS[packId]);return {status: 'dry-run',- message: `${accent('Plan (dry-run — no changes made):')}\n\n${formatPlanBody(plan, cwd)}`,+ message: `${accent('Reference this pack for inspiration (dry-run — no changes made):')}\n\n${rationale}\n\n${accent('Plan:')}\n\n${formatPlanBody(plan, cwd)}`,plan,exitCode: 0,};diff --git a/packages/core/src/handoff/index.ts b/packages/core/src/handoff/index.tsindex c34c5f5b5..131e56b6e 100644--- a/packages/core/src/handoff/index.ts+++ b/packages/core/src/handoff/index.ts@@ -8,6 +8,8 @@ export {composeFilePrompt,composeFolderPrompt,composeSelectionPrompt,+ OK_PROJECT_SKILL_POINTER,+ withSkillPointer,} from './prompt-composer.ts';export { buildClaudeLaunchCommand, shellSingleQuote } from './terminal-launch.ts';export type {diff --git a/packages/core/src/handoff/prompt-composer.test.ts b/packages/core/src/handoff/prompt-composer.test.tsindex aa8542fc0..1251eed5a 100644--- a/packages/core/src/handoff/prompt-composer.test.ts+++ b/packages/core/src/handoff/prompt-composer.test.ts@@ -8,6 +8,7 @@ import {composeFilePrompt,composeFolderPrompt,composeSelectionPrompt,+ withSkillPointer,} from './prompt-composer.ts';import type { HandoffPayload, HandoffTarget } from './types.ts';@@ -198,9 +199,9 @@ test('composeEmptySpacePrompt blockquotes every line of a multi-line instructiontest('directive composers keep the dispatched URL within 4096 chars for an oversized instruction (every target)', () => {const hugeInstruction = 'please tighten this prose for clarity and concision '.repeat(200);const composed = [- composeFilePrompt('specs/deep/nested/SPEC.md', true, hugeInstruction),- composeFolderPrompt('specs/deep/nested', true, hugeInstruction),- composeEmptySpacePrompt(true, hugeInstruction),+ withSkillPointer(composeFilePrompt('specs/deep/nested/SPEC.md', true, hugeInstruction)),+ withSkillPointer(composeFolderPrompt('specs/deep/nested', true, hugeInstruction)),+ withSkillPointer(composeEmptySpacePrompt(true, hugeInstruction)),];for (const target of ALL_TARGETS) {for (const prompt of composed) {diff --git a/packages/core/src/handoff/prompt-composer.ts b/packages/core/src/handoff/prompt-composer.tsindex 74ccf6a10..cba40946a 100644--- a/packages/core/src/handoff/prompt-composer.ts+++ b/packages/core/src/handoff/prompt-composer.ts@@ -34,6 +34,13 @@ function sanitizePathForAtMention(path: string): string {return path.replace(AT_MENTION_PATH_INJECTION_SANITIZE_RE, '_');}+export const OK_PROJECT_SKILL_POINTER =+ "This is an Open Knowledge project: load the `open-knowledge` skill and use the Open Knowledge MCP tools for all markdown — don't probe for `.ok/` or use native file tools on `.md` / `.mdx`.";++export function withSkillPointer(directive: string): string {+ return `${OK_PROJECT_SKILL_POINTER} ${directive}`;+}+export function composeFilePrompt(relativePath: string,autoOpen: boolean,@@ -112,6 +119,10 @@ const URL_OVERHEAD_RESERVE = 1024;* to locus mode. */const INLINE_PROMPT_ENCODED_BUDGET = MAX_HANDOFF_URL_LENGTH - URL_OVERHEAD_RESERVE;+const POINTER_ENCODED_RESERVE = encodedPromptLength(`${OK_PROJECT_SKILL_POINTER} `, 'cursor');+const DIRECTIVE_INLINE_PROMPT_ENCODED_BUDGET =+ INLINE_PROMPT_ENCODED_BUDGET - POINTER_ENCODED_RESERVE;+const LOCUS_ANCHOR_MAX_CHARS = 160;const MIN_FENCE_LENGTH = 3;@@ -184,9 +195,9 @@ function fitInstruction(compose: (instruction: string) => string,instruction: string,target: HandoffTarget,+ budget: number = INLINE_PROMPT_ENCODED_BUDGET,): string {- const fits = (instr: string): boolean =>- encodedPromptLength(compose(instr), target) <= INLINE_PROMPT_ENCODED_BUDGET;+ const fits = (instr: string): boolean => encodedPromptLength(compose(instr), target) <= budget;if (fits(instruction)) return instruction;const codePoints = Array.from(instruction);let lo = 0;@@ -206,6 +217,7 @@ function fitInstructionForDirective(directive: string, instruction: string): str(instr) => directiveWithInstruction(directive, instr),instruction,'cursor',+ DIRECTIVE_INLINE_PROMPT_ENCODED_BUDGET,);}diff --git a/packages/core/src/index.ts b/packages/core/src/index.tsindex 9862e8c0d..111507ce9 100644--- a/packages/core/src/index.ts+++ b/packages/core/src/index.ts@@ -369,11 +369,13 @@ export {type IpcChannelReason,type IpcChannelWithUrn,lookupUrnInRegistry,+ OK_PROJECT_SKILL_POINTER,shellSingleQuote,type TargetData,URN_HTTP_ONLY,URN_IPC_REGISTRY,type UrnIpcLookup,+ withSkillPointer,} from './handoff/index.ts';export type {BundleManifest,diff --git a/packages/server/assets/skills/project/SKILL.md b/packages/server/assets/skills/project/SKILL.mdindex 3169d3c4a..305facc57 100644--- a/packages/server/assets/skills/project/SKILL.md+++ b/packages/server/assets/skills/project/SKILL.md@@ -483,7 +483,19 @@ Typical day-2 flow: user shares a URL → `ingest` (preserve) → user asks "now**Repeat invocations.** The `workflow` tool returns its full instructional body on every call, including 2nd / 3rd / Nth invocation in the same session. If you've already received a tool's body earlier this session, you can skim the repeat for changes (the body can evolve across server versions) but you don't need to re-internalize it — proceed to the next step with the new arguments.-**Project scaffolding — two paths.** **Empty repo:** run `ok seed` once from a terminal (scaffolds Karpathy three-layer + seeds `log.md` + registers folder defaults). **Existing content:** invoke `workflow({ kind: 'discover' })` (table above — extracts conventions from siblings, sets folder frontmatter + templates, curates `.okignore`, activates link graph; per-phase confirmation gates). Neither is required; the four workflow kinds work against any folder structure. Only mention each when explicitly relevant.+**Project scaffolding — two paths.** **Empty repo:** run `ok seed` once from a terminal (scaffolds the layout + seeds `log.md` + folder defaults). **Existing content:** invoke `workflow({ kind: 'discover' })` (table above). Neither is required; the four workflow kinds work against any folder structure. Only mention each when explicitly relevant.++**Starter packs — reference for inspiration.** The `ok` CLI (a Bash surface beside the MCP tools; other verbs `ok start` / `ok open` are documented above) ships proven layouts you can study to build a *similar* structure of your own — adapt the idea, don't clone the pack:++- `knowledge-base` — source-grounded research articles+- `software-lifecycle` — proposals, decisions, specs+- `plain-notes` — notes + daily journal+- `worldbuilding` — fiction story wiki+- `writing-pipeline` — drafts → published+- `entity-vault` — people / companies / meetings (personal CRM)+- `okf` — Open Knowledge Format–conformant base++To reference one **without installing it**: `ok seed --list-packs` (the menu) → `ok seed --pack <name> --dry-run` (its folders + the *why* of each folder + templates; writes nothing). Then either adapt the ideas into your own folders (`write({ folder })` + a template) or adopt the pack as-is by re-running without `--dry-run`. Reach for this when a user wants structure and an archetype fits — propose a tailored variant, not a verbatim copy.## Server lifecyclediff --git a/packages/server/src/index.ts b/packages/server/src/index.tsindex e226979f4..42a52f2e9 100644--- a/packages/server/src/index.ts+++ b/packages/server/src/index.ts@@ -338,6 +338,7 @@ export {coercePackId,DEFAULT_PACK_ID,type FileEntry,+ formatPackRationale,isKnownPackId,LOG_MD_TEMPLATE,listStarterPacks,diff --git a/packages/server/src/seed/index.ts b/packages/server/src/seed/index.tsindex 96c77a015..aa3375a6d 100644--- a/packages/server/src/seed/index.ts+++ b/packages/server/src/seed/index.ts@@ -1,5 +1,6 @@export { applySeed } from './apply.ts';export { planSeed } from './plan.ts';+export { formatPackRationale } from './rationale.ts';export {buildStarterFolderFrontmatterYaml,coercePackId,diff --git a/packages/server/src/seed/rationale.test.ts b/packages/server/src/seed/rationale.test.tsnew file mode 100644index 000000000..86d5dcb3f--- /dev/null+++ b/packages/server/src/seed/rationale.test.ts@@ -0,0 +1,50 @@+import { describe, expect, test } from 'bun:test';+import { formatPackRationale, PACK_INSPIRATION_NOTE } from './rationale.ts';+import { STARTER_PACK_IDS, STARTER_PACKS } from './starter.ts';++describe('formatPackRationale', () => {+ test('headers with the pack name + description', () => {+ const out = formatPackRationale(STARTER_PACKS.worldbuilding);+ expect(out).toContain(STARTER_PACKS.worldbuilding.name);+ expect(out).toContain(STARTER_PACKS.worldbuilding.description);+ });++ test('surfaces every folder’s "why" + template names, for every pack', () => {+ for (const id of STARTER_PACK_IDS) {+ const pack = STARTER_PACKS[id];+ const out = formatPackRationale(pack);+ for (const folder of pack.folders) {+ expect(out).toContain(`${folder.path}/`);+ expect(out).toContain(folder.description);+ expect(out).toContain(folder.starterTemplate);+ for (const extra of folder.extraTemplates ?? []) {+ expect(out).toContain(extra);+ }+ }+ }+ });++ test('carries the anti-clone inspiration note (adapt, not clone)', () => {+ expect(formatPackRationale(STARTER_PACKS['knowledge-base'])).toContain(PACK_INSPIRATION_NOTE);+ expect(PACK_INSPIRATION_NOTE.toLowerCase()).toContain('adapt');+ expect(PACK_INSPIRATION_NOTE).toContain('--dry-run');+ });++ test('lists root files when a pack ships them, omits the section otherwise', () => {+ const kbPack = STARTER_PACKS['knowledge-base'];+ const kbRootFiles = Object.keys(kbPack.rootFiles ?? {});+ expect(kbRootFiles.length).toBeGreaterThan(0); // guards the fixture choice below+ const kb = formatPackRationale(kbPack);+ expect(kb).toContain('Root files:');+ for (const fileName of kbRootFiles) {+ expect(kb).toContain(fileName);+ }+ const noRootFilesPack = STARTER_PACK_IDS.map((id) => STARTER_PACKS[id]).find(+ (p) => Object.keys(p.rootFiles ?? {}).length === 0,+ );+ expect(noRootFilesPack).toBeDefined();+ if (noRootFilesPack) {+ expect(formatPackRationale(noRootFilesPack)).not.toContain('Root files:');+ }+ });+});diff --git a/packages/server/src/seed/rationale.ts b/packages/server/src/seed/rationale.tsnew file mode 100644index 000000000..7742d2b49--- /dev/null+++ b/packages/server/src/seed/rationale.ts@@ -0,0 +1,34 @@+import type { StarterFolder, StarterPack } from './starter.ts';++export const PACK_INSPIRATION_NOTE = [+ 'These are patterns to adapt to your domain, not a layout to copy verbatim.',+ 'To build a variant: create your own folders (via `write` or your editor) and reuse only the ideas that fit.',+ 'To adopt this pack as-is: re-run without `--dry-run`.',+].join('\n');++function folderTemplateNames(folder: StarterFolder): string {+ return [folder.starterTemplate, ...(folder.extraTemplates ?? [])].join(', ');+}++export function formatPackRationale(pack: StarterPack): string {+ const lines: string[] = [+ `Pack: ${pack.name} — ${pack.description}`,+ '',+ PACK_INSPIRATION_NOTE,+ '',+ ];++ lines.push('Layout & rationale:');+ for (const folder of pack.folders) {+ lines.push(` ${folder.path}/ — ${folder.title}`);+ lines.push(` why: ${folder.description}`);+ lines.push(` templates: ${folderTemplateNames(folder)}`);+ }++ const rootFiles = pack.rootFiles ? Object.keys(pack.rootFiles) : [];+ if (rootFiles.length > 0) {+ lines.push('', `Root files: ${rootFiles.join(', ')}`);+ }++ return lines.join('\n');+}diff --git a/packages/server/src/seed/skill-pack-list-drift.test.ts b/packages/server/src/seed/skill-pack-list-drift.test.tsnew file mode 100644index 000000000..0605fa08b--- /dev/null+++ b/packages/server/src/seed/skill-pack-list-drift.test.ts@@ -0,0 +1,22 @@+import { describe, expect, test } from 'bun:test';+import { readFileSync } from 'node:fs';+import { join } from 'node:path';+import { STARTER_PACK_IDS } from './starter.ts';++const SKILL_PATH = join(import.meta.dir, '../../assets/skills/project/SKILL.md');+const PACK_BULLET_RE = /^- `([a-z][a-z0-9-]+)` —/gm;++describe('project SKILL.md starter-pack awareness list', () => {+ test('lists exactly the packs in STARTER_PACK_IDS (drift guard)', () => {+ const skill = readFileSync(SKILL_PATH, 'utf-8');+ const listed = [...skill.matchAll(PACK_BULLET_RE)].map((m) => m[1]);+ expect(listed.length).toBeGreaterThan(0);+ expect(new Set(listed)).toEqual(new Set(STARTER_PACK_IDS));+ });++ test('points the agent at the reference ladder (--list-packs → --dry-run)', () => {+ const skill = readFileSync(SKILL_PATH, 'utf-8');+ expect(skill).toContain('ok seed --list-packs');+ expect(skill).toContain('--dry-run');+ });+});