Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
Name user-global skills correctly in ok init summary (PRD-8958) (#5794)
Andrew Mikofalvy01a32862cd24
diff --git a/.changeset/init-user-global-skill-summary.md b/.changeset/init-user-global-skill-summary.mdnew file mode 100644index 000000000..bd7f03238--- /dev/null+++ b/.changeset/init-user-global-skill-summary.md@@ -0,0 +1,5 @@+---+"@inkeep/open-knowledge": patch+---++`ok init` now names each user-global skill correctly in its summary and shows how to add starter content even with `--no-mcp`.diff --git a/docs/content/features/skills/reference.mdx b/docs/content/features/skills/reference.mdxindex ecb60fc08..1c87bfe1f 100644--- a/docs/content/features/skills/reference.mdx+++ b/docs/content/features/skills/reference.mdx@@ -49,7 +49,7 @@ ok init --no-skills| `ok skills import <source>` | Import from skills.sh, a repository, a git URL, or a local path. || `ok seed --pack <id>` | Install a starter pack's skills. || `ok init --skills discovery,write-skill` | Select built-ins during setup; the default is discovery. |-| `ok init --no-skills` | Skip skill installation for this setup run. |+| `ok init --no-skills` | Skip the user-global skills for this setup run; the project-local `open-knowledge` skill is still written. |See the [CLI reference](../../reference/cli.mdx) for all flags.diff --git a/docs/content/reference/cli.mdx b/docs/content/reference/cli.mdxindex 8b3345b8a..43ae1c46c 100644--- a/docs/content/reference/cli.mdx+++ b/docs/content/reference/cli.mdx@@ -52,6 +52,8 @@ One server on one port serves everything — the editor, the API, the MCP endpoi`ok start` also takes `-p/--port` and `--bind` to pick the address, `--idle-shutdown` (`off` or a duration like `30m`) to control when an unused server exits, `--only server` to run without the editor UI, and `--mode app` to hand off to the desktop app instead of running a server in the terminal (with the desktop app installed).+The browser needs no flag: `ok start` always runs the browser server unless you pass `--mode app`. Bare `ok`, with no subcommand, opens the desktop app when it is installed and otherwise runs the same browser server; it also runs the browser server when its output is not an interactive terminal, over SSH, or on Linux without `DISPLAY` or `WAYLAND_DISPLAY`, unless `OK_FORCE_DESKTOP=1` is set. Set `OK_FORCE_BROWSER=1` to make bare `ok` always run the browser server.+Idle shutdown is on by default at 30 minutes — a server with no connected clients exits so it doesn't linger. If you keep a session open for a long time without interacting, pass `--idle-shutdown off` (or a longer duration) to keep it running.For a complete list of every file OpenKnowledge creates or changes — during install, at runtime, and in the desktop app — see [What OpenKnowledge writes to your system](/docs/reference/what-open-knowledge-writes).diff --git a/docs/content/reference/configuration.mdx b/docs/content/reference/configuration.mdxindex 16d9ba5cf..8f182fc46 100644--- a/docs/content/reference/configuration.mdx+++ b/docs/content/reference/configuration.mdx@@ -119,6 +119,8 @@ Most users never set these — the schema settings above cover the common cases.| `HOST` | Server bind host. The `--bind` flag wins over this. || `PORT` | Server bind port. The `--port` flag wins over this. || `OK_MCP_AUTOSTART` | Set to `0` to stop MCP tool calls from auto-starting the project's OpenKnowledge server; tools error until you run `ok start` |+| `OK_FORCE_BROWSER` | Set to `1` so bare `ok` runs the browser server instead of opening the installed desktop app. `ok start` without `--mode app` runs the browser server either way, and `ok start --mode app` refuses to run while it is set. |+| `OK_FORCE_DESKTOP` | Set to `1` so bare `ok` and `ok start --mode app` open the installed desktop app even when output is not an interactive terminal, over SSH, or on Linux without a display. `OK_FORCE_BROWSER=1` takes precedence. || `OK_LOG_LEVEL` | Log verbosity (`info`, `debug`, `trace`). Falls back to `LOG_LEVEL` if unset. |**Advanced / operator:**diff --git a/docs/content/reference/what-open-knowledge-writes.mdx b/docs/content/reference/what-open-knowledge-writes.mdxindex cacf1817a..835dbe1a3 100644--- a/docs/content/reference/what-open-knowledge-writes.mdx+++ b/docs/content/reference/what-open-knowledge-writes.mdx@@ -273,9 +273,9 @@ On Windows, Claude Desktop and OpenCode configs live under `%APPDATA%\Claude\` a`ok init` also installs `open-knowledge-discovery` (the same skill first launch sets up — pass `--skills discovery,write-skill` to add the authoring skill too), honoring any prior consent choice, and, for a project it is setting up for the first time, adds the OpenKnowledge paths to `.git/info/exclude` so `.ok/` stays off your remote. Pass `--shared` to commit it instead. Re-running `ok init` on a project you already set up keeps that project's current choice. Switch modes later with `ok config-sharing share` / `unshare` (`unshare` refuses if an OK config file is already tracked); `ok config-sharing status` prints the current mode and the excluded paths.<Callout type="info" title="Controlling it">- - `--no-mcp` — scaffold `.ok/` only; register nothing with any editor.+ - `--no-mcp` — register nothing in any editor's MCP config. `ok init` still scaffolds `.ok/` and writes the project-local `open-knowledge` skill; GitHub Copilot's copy is written only when Copilot already has an OpenKnowledge MCP entry.- `--scope user | project | both` — where the MCP entry is written. In an interactive terminal, `ok init` prompts for this; scripted/CI runs default to `both`, so pass the flag to constrain them.- - `--no-skills` — install no user-global skills on this run; `--skills discovery,write-skill` — install only the named bundles. **Default installs `discovery` only**, matching what the desktop's first launch sets up; `write-skill` is opt-in here and in **Settings → Skills Studio**. Installing is recorded and honored by the desktop app too; skipping is not recorded, so it never affects another project.+ - `--no-skills` — install no user-global skills on this run; `--skills discovery,write-skill` — install only the named bundles. **Default installs `discovery` only**, matching what the desktop's first launch sets up; `write-skill` is opt-in here and in **Settings → Skills Studio**. Installing is recorded and honored by the desktop app too; skipping is not recorded, so it never affects another project. Neither flag affects the project-local `open-knowledge` skill, which is still written.- `--shared` (vs `--local-only`) — commit `.ok/` rather than keeping it out of git.</Callout>@@ -383,6 +383,8 @@ Bridge setup requires a project directory it can resolve and access, and refuses| The `postinstall` skill install (CLI) | `npm install --ignore-scripts` || The shell-config `PATH` block (macOS and Linux app) | Uncheck "Add the `ok` command to your terminal" in the first-launch dialog || All editor MCP registration in `ok init` | `ok init --no-mcp` |+| User-global skills in `ok init` | `ok init --no-skills` |+| The project-local `open-knowledge` skill | Not skippable at `ok init`, even with `--no-mcp` or `--no-skills`; `ok deinit` removes it || User-level (vs project) MCP writes | `ok init --scope project` || Committing `.ok/` to git | Off by default for a new project; `ok init --shared` commits it instead || The repair sweeps and the desktop app's shell / `PATH` changes | `OK_RECLAIM_DISABLE=1` (also delete the managed block from your shell config to remove the `PATH` entry) |diff --git a/docs/content/remote-control/methods/docker.mdx b/docs/content/remote-control/methods/docker.mdxindex 55b972225..c75095b1d 100644--- a/docs/content/remote-control/methods/docker.mdx+++ b/docs/content/remote-control/methods/docker.mdx@@ -54,7 +54,7 @@ ENTRYPOINT ["/usr/local/bin/entrypoint.sh"]The entrypoint is the container's boot script. It runs every time the container starts. `ok start` needs an initialized project, but no one is inside the container to run `ok init`. The script handles this automatically. The first boot initializes the project on the empty volume. Later boots find `.ok/` and start the server directly. Official database images use the same pattern for empty data directories.-The `--no-mcp --no-skills` flags only skip local agent configuration and skill files that the container does not need. The server still provides its `/mcp` endpoint.+The `--no-mcp --no-skills` flags skip the editor MCP registration and the user-global skills, which the container does not need. `ok init` still writes the project-local `open-knowledge` skill, and the server still provides its `/mcp` endpoint.```sh title="entrypoint.sh"#!/bin/shdiff --git a/packages/cli/src/commands/init.test.ts b/packages/cli/src/commands/init.test.tsindex 2e1b33bcd..b23bff588 100644--- a/packages/cli/src/commands/init.test.ts+++ b/packages/cli/src/commands/init.test.ts@@ -955,7 +955,8 @@ describe('runInit', () => {});expect(result.skillInstall).toBe('installed');const output = formatInitResult(result, testDir);- expect(output).toContain('User-global skill:');+ expect(output).toContain('User-global skills:');+ expect(output).toContain('open-knowledge-discovery');expect(output).toContain('installed for');expect(output).not.toContain('detected agent hosts');});@@ -985,7 +986,7 @@ describe('runInit', () => {});expect(result.skillInstall).toBe('skip-current');const output = formatInitResult(result, testDir);- expect(output).toContain('User-global skill:');+ expect(output).toContain('User-global skills:');expect(output).toContain('already installed at current version');});@@ -1109,6 +1110,70 @@ describe('runInit', () => {const output = formatInitResult(result, testDir);expect(output).toContain('install failed');});++ const userGlobalSection = (output: string): string => {+ const start = output.indexOf('User-global skills:');+ expect(start).toBeGreaterThanOrEqual(0);+ const rest = output.slice(start);+ const end = rest.indexOf('\n\n');+ return end === -1 ? rest : rest.slice(0, end);+ };++ it('--no-skills never names the project skill as the user-global skill it skipped', async () => {+ const result = await runInitForTest({+ skills: false,+ editors: ['cursor'],+ installUserSkill: async () => 'installed',+ });+ const output = formatInitResult(result, testDir);+ expect(output).toContain('.cursor/skills/open-knowledge/SKILL.md');+ const section = userGlobalSection(output);+ expect(section).toContain('--no-skills');+ expect(section).not.toMatch(/\bopen-knowledge\b(?!-)/);+ expect(section).toContain('project-local');+ });++ it('an unrecognized --skills id is reported as such, not as --no-skills', async () => {+ const result = await runInitForTest({+ skills: 'discovry',+ installUserSkill: async () => 'installed',+ });+ expect(result.skillInstall).toBe('declined');+ const section = userGlobalSection(formatInitResult(result, testDir));+ expect(section).not.toContain('--no-skills');+ expect(section).toContain('discovry');+ expect(section).toContain('discovery, write-skill');+ });++ it('reports each bundle by its own name and outcome when outcomes differ', async () => {+ const result = await runInitForTest({+ skills: 'discovery,write-skill',+ installUserSkill: async (opts) =>+ opts?.bundleId === 'discovery' ? 'skip-current' : 'installed',+ });+ const section = userGlobalSection(formatInitResult(result, testDir));+ const lines = section.split('\n');+ const discovery = lines.find((l) => l.includes('open-knowledge-discovery'));+ const writeSkill = lines.find((l) => l.includes('open-knowledge-write-skill'));+ expect(discovery).toContain('already installed at current version');+ expect(discovery).not.toContain('installed for');+ expect(writeSkill).toContain('installed for');+ expect(discovery?.indexOf('already installed')).toBe(writeSkill?.indexOf('installed for'));+ expect(section).not.toMatch(/\bopen-knowledge\b(?!-)/);+ });++ it('names only the failing bundle as failed', async () => {+ const result = await runInitForTest({+ skills: 'discovery,write-skill',+ installUserSkill: async (opts) =>+ opts?.bundleId === 'write-skill' ? 'failed' : 'installed',+ });+ const lines = userGlobalSection(formatInitResult(result, testDir)).split('\n');+ expect(lines.find((l) => l.includes('open-knowledge-discovery'))).not.toContain('failed');+ expect(lines.find((l) => l.includes('open-knowledge-write-skill'))).toContain(+ 'install failed',+ );+ });});describe('content preview in init output', () => {@@ -1568,6 +1633,34 @@ describe('runInit', () => {expect(matches).toHaveLength(1);});+ it('--no-mcp still shows how to add starter content, without the editor steps', async () => {+ const result = await runInitForTest({ mcp: false });+ const output = formatInitResult(result, testDir);+ expect(output).toContain('ok seed --list-packs');+ expect(output).toContain('scaffold an empty repo');+ expect(output).not.toContain('Open your editor');+ expect(output).not.toContain('Approve the MCP server');+ });++ it('does not suggest ok seed when content scaffolding failed', async () => {+ writeFileSync(join(testDir, '.ok'), 'not a directory\n', 'utf-8');+ const result = await runInitForTest({ editors: ['claude'] });+ expect(result.contentScaffoldFailed).toBe(true);+ const output = formatInitResult(result, testDir);+ expect(output).toContain('Content scaffolding failed');+ expect(output).not.toContain('ok seed');+ expect(output).not.toMatch(/\n\n$/);+ });++ it('keeps the editor next steps when content scaffolding failed', async () => {+ const result = await runInitForTest({ editors: ['claude'] });+ const output = formatInitResult({ ...result, contentScaffoldFailed: true }, testDir);+ expect(output).toContain('Open your editor');+ expect(output).toContain('Approve the MCP server');+ expect(output).toContain(' 3. Ask your agent');+ expect(output).not.toContain('ok seed');+ });+const allocOutsideTestDir = (suffix: string): string =>resolve(tmpdir(),diff --git a/packages/cli/src/commands/init.ts b/packages/cli/src/commands/init.tsindex 64e10e297..b3d640673 100644--- a/packages/cli/src/commands/init.ts+++ b/packages/cli/src/commands/init.ts@@ -649,6 +649,8 @@ interface InitCommandResult {legacyProjectConfigs: ProjectConfigResult[];projectSkills: ProjectSkillResult[];skillInstall?: InstallUserSkillResult | 'declined';+ skillBundles?: readonly { bundleId: BundleId; result: InstallUserSkillResult }[];+ skillsRequested?: string | boolean;skillHosts?: readonly string[];preview?: PreviewResult;didGitInit: boolean;@@ -1319,11 +1321,13 @@ export async function runInit(options: InitCommandOptions = {}): Promise<InitComlet anyFailed = false;let anySkipped = false;let anyNoHosts = false;+ const skillBundles: { bundleId: BundleId; result: InstallUserSkillResult }[] = [];for (const id of USER_GLOBAL_BUNDLE_IDS) {if (!enabledBundles.has(id)) continue;await writeBundleDecision(skillHome, BUNDLE_SKILL_NAME[id], true).catch(() => {});anyEnabled = true;const result = await installSkill({ home: options.home, bundleId: id, force: true });+ skillBundles.push({ bundleId: id, result });if (result === 'installed') anyInstalled = true;else if (result === 'failed') anyFailed = true;else if (result === 'no-hosts') anyNoHosts = true;@@ -1369,6 +1373,8 @@ export async function runInit(options: InitCommandOptions = {}): Promise<InitComprojectSkills: projectSkillResults,legacyProjectConfigs,skillInstall,+ skillBundles,+ skillsRequested: options.skills,skillHosts,didGitInit: gitResult.didInit,rootGitignoreCreated,@@ -1655,44 +1661,63 @@ export function formatInitResult(result: InitCommandResult, cwd: string): string);}- if (result.skillInstall) {+ if (result.skillInstall === 'declined') {lines.push('');- lines.push(accent('User-global skill:'));- switch (result.skillInstall) {- case 'installed': {- const hostLabels = (result.skillHosts ?? []).map(- (id) => EDITOR_LABELS[id as EditorId] ?? id,- );- const target = hostLabels.length > 0 ? hostLabels.join(', ') : 'the shared ~/.agents store';- lines.push(` open-knowledge ${success(`installed for ${target}`)}`);- lines.push(- ` ${dim('Counted on skills.sh (skill name + source repo, once per machine).')}`,- );- lines.push(` ${dim('Opt out: DO_NOT_TRACK=1, or Settings → User → Preferences.')}`);- break;+ lines.push(accent('User-global skills:'));+ if (typeof result.skillsRequested === 'string') {+ lines.push(+ ` ${dim(`none installed — --skills "${result.skillsRequested}" names no known skill bundle (known: ${USER_GLOBAL_BUNDLE_IDS.join(', ')})`)}`,+ );+ lines.push(` ${dim('No user-global skill was installed or removed.')}`);+ } else {+ lines.push(` ${dim('none installed — skipped for this run (--no-skills)')}`);+ lines.push(` ${dim('No user-global skill was installed or removed; any already on this')}`);+ lines.push(` ${dim('machine are untouched. Run init without the flag to install them:')}`);+ lines.push(` ${dim(' ok init')}`);+ lines.push(+ ` ${dim('--no-skills covers user-global skills only, not project-local skills.')}`,+ );+ }+ } else if (result.skillInstall) {+ lines.push('');+ lines.push(accent('User-global skills:'));+ const bundles = result.skillBundles ?? [];+ const nameWidth = Math.max(0, ...bundles.map((b) => BUNDLE_SKILL_NAME[b.bundleId].length));+ for (const bundle of bundles) {+ const name = BUNDLE_SKILL_NAME[bundle.bundleId].padEnd(nameWidth);+ switch (bundle.result) {+ case 'installed': {+ const hostLabels = (result.skillHosts ?? []).map(+ (id) => EDITOR_LABELS[id as EditorId] ?? id,+ );+ const target =+ hostLabels.length > 0 ? hostLabels.join(', ') : 'the shared ~/.agents store';+ lines.push(` ${name} ${success(`installed for ${target}`)}`);+ break;+ }+ case 'skip-current':+ lines.push(` ${name} ${success('already installed at current version')}`);+ break;+ case 'no-hosts':+ lines.push(+ ` ${name} ${dim('skipped — no supported agent host detected in your home directory')}`,+ );+ break;+ case 'failed':+ lines.push(` ${warning(`${name} install failed`)}`);+ break;+ default: {+ const _exhaustive: never = bundle.result;+ void _exhaustive;+ }}- case 'skip-current':- lines.push(` open-knowledge ${success('already installed at current version')}`);- break;- case 'declined':- lines.push(` open-knowledge ${dim('skipped for this run (--no-skills)')}`);- lines.push(- ` ${dim('Nothing was installed or removed. Any built-in skills already on this')}`,- );- lines.push(` ${dim('machine are untouched. Run init without the flag to install them:')}`);- lines.push(` ${dim(' ok init')}`);- break;- case 'no-hosts':- lines.push(- ` open-knowledge ${dim('skipped — no supported agent host detected in your home directory')}`,- );- break;- case 'failed':- lines.push(- ` ${warning('open-knowledge install failed — MCP still configured; retry with:')}`,- );- lines.push(` ${warning(' ok repair-skills')}`);- break;+ }+ if (bundles.some((b) => b.result === 'installed')) {+ lines.push(` ${dim('Counted on skills.sh (skill name + source repo, once per machine).')}`);+ lines.push(` ${dim('Opt out: DO_NOT_TRACK=1, or Settings → User → Preferences.')}`);+ }+ if (bundles.some((b) => b.result === 'failed')) {+ lines.push(` ${warning('Retry with: ok repair-skills')}`);}}@@ -1743,6 +1768,10 @@ export function formatInitResult(result: InitCommandResult, cwd: string): stringlines.push('');lines.push(...formatSharingOutcome(result.sharing, cwd));+ const seedLines = (indent: string): string[] => [+ `${indent}- ${info('ok seed --list-packs')} — browse the starter packs`,+ `${indent}- ${info('ok seed')} — scaffold an empty repo`,+ ];if (anyWritten) {const seen = new Set<EditorId>();const configuredLabels = result.editors@@ -1754,11 +1783,21 @@ export function formatInitResult(result: InitCommandResult, cwd: string): stringlines.push(`${success('✓')} ${accent('Next steps:')}`);lines.push(` 1. Open your editor (${info(configuredLabels.join(' / '))})`);lines.push(' 2. Approve the MCP server when prompted');- lines.push(' 3. (Optional) scaffold the starter knowledge-base structure:');- lines.push(` - ${info('ok seed --list-packs')} — browse the starter packs`);- lines.push(` - ${info('ok seed')} — scaffold an empty repo`);- lines.push(' 4. Ask your agent to capture a source, research a topic, or build a wiki —');+ let step = 3;+ if (!result.contentScaffoldFailed) {+ lines.push(` ${step++}. (Optional) scaffold the starter knowledge-base structure:`);+ lines.push(...seedLines(' '));+ }+ lines.push(+ ` ${step}. Ask your agent to capture a source, research a topic, or build a wiki —`,+ );lines.push(' the procedures ship as skills alongside the MCP tools.');+ } else if (!result.contentScaffoldFailed) {+ lines.push('');+ lines.push(+ `${accent('Next steps:')} (optional) scaffold the starter knowledge-base structure:`,+ );+ lines.push(...seedLines(' '));}return lines.join('\n');