Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
feat(ok): rename pack skills to product names, nest the skills mirror, fix install reporting (#3152)
tim-inkeep8471ed39719c
diff --git a/.changeset/pack-skill-marketplace-rename.md b/.changeset/pack-skill-marketplace-rename.mdnew file mode 100644index 000000000..7c4825b89--- /dev/null+++ b/.changeset/pack-skill-marketplace-rename.md@@ -0,0 +1,60 @@+---+"@inkeep/open-knowledge": minor+---++The 15 starter-pack skills drop their generated `open-knowledge-pack-…` names and take marketplace short names, taken from SKILL.md frontmatter: the orientation skills become `note-taking` (was `…-plain-notes`), `writing-workflow` (was `…-writing-pipeline`), `personal-crm` (was `…-entity-vault`), `okf-knowledge-base` (was `…-okf`), and `worldbuilding`, `codebase-wiki`, `knowledge-base`, `software-lifecycle` (prefix dropped); the member skills become `frame-a-proposal`, `record-a-decision`, `write-a-spec`, `review-a-design`, `write-a-postmortem` (prefix dropped) plus `research-with-sources` (was `…-knowledge-base-research`) and `consolidate-notes` (was `…-knowledge-base-consolidate`). Every shipped skill now carries `metadata.author`/`metadata.repository`.++Skills you already have are left exactly as they are. Nothing is renamed on your+disk, your `.ok/skills-lock.json` is not rewritten, and no boot pass touches your+project. These are project-level skills that normally live in your git repo, and+silently renaming one you are already using would show up as an unexplained diff+for you and for everyone who pulls. An existing install keeps its current name,+keeps working, and still updates from source: "Update" resolves the old name to+the renamed bundle in the mirror. Re-seeding a pack recognizes the skill you+already have and will not author a second copy of it under the new name. Only+newly installed skills use the new names.++Note for maintainers: this is the reason there is no migration. If you later want+existing installs on the new names, it needs to be something a user opts into and+can see, not a rename that happens under them at boot.++Four Claude Code marketplace plugins are renamed to match their published skill names:+`entity-vault` becomes `personal-crm`, `okf` becomes `okf-knowledge-base`, `plain-notes`+becomes `note-taking`, and `writing-pipeline` becomes `writing-workflow`. The old+`/plugin install <name>@open-knowledge-skills` commands keep working for one more release:+the four old handles remain in the marketplace as aliases, marked outdated and installing+the same skills as the entry that replaced them. Switch to the new names — the aliases are+removed in a later release. The other seven plugins keep their names, but every plugin's+skill paths move as the published repo regroups into `skills/core/` and+`skills/starter-packs/`. `ok seed --pack <id>` flags are unchanged.++Switching a project's OpenKnowledge skill off in Settings now sticks. It previously+came back on the next open, because the project-open sweep recreates the skill for any+editor already wired for OpenKnowledge and nothing recorded that you had turned it off.+Your choice is now remembered per project, on your machine only, so it does not follow+the repo to teammates. A project where you never expressed a choice still gets the skill+seeded as before.++Installs of OpenKnowledge's own skills are now counted on skills.sh wherever they+actually happen. Previously only some routes reported, so most installs were invisible:+creating a project, the desktop seeding its built-in skills on first launch, opening a+wired project that had no project skill, switching the skill on in Settings, installing+for Claude Desktop, and importing our own repo by any route other than the Explore tab+all counted nothing. What is NOT counted: an app launch that installs nothing, reopening+a project, a failed write, a skill bundle you switched off, and — unchanged — any+third-party repository you typed yourself. Reporting still honours+`telemetry.skillInstallReports.enabled`, `DO_NOT_TRACK` and `DISABLE_TELEMETRY`.++A skill installed into a project is now counted once per project rather than once per+machine, because each project gets its own copy in its own editor directories. The+project path is used only as a local key to avoid double counting and is never sent.++Also: seeding now reports name collisions with your own skills instead of silently skipping, and rejected install reports are logged. skills.sh install counters for the old names reset under the new names.++Install reporting to skills.sh now retries after a rejection. Previously a report the+collector declined was recorded as sent and never retried, so any install rejected while+a newly renamed listing was still being indexed was lost for good. Only rejections the+collector application issued (400, 404, 410, 422) are retried: a 5xx, a 429, or an edge+403 may have been raised after the event was already counted, so those keep their claim,+as do reports the collector never received. A flaky network or a struggling collector can+never inflate a count.diff --git a/docs/content/features/skills.mdx b/docs/content/features/skills.mdxindex 6041ee306..f45736fff 100644--- a/docs/content/features/skills.mdx+++ b/docs/content/features/skills.mdx@@ -114,6 +114,21 @@ OpenKnowledge's own skills are published at [inkeep/open-knowledge-skills](https`open-knowledge` is the platform skill that teaches an agent to read, search, link, and write markdown through the MCP server. The starter packs ship there too, and `ok seed --pack <id>` installs a pack's skills directly.+The repo is grouped by role: `skills/core/` holds the three built-ins, and `skills/starter-packs/<pack>/` holds each pack's skills next to a README explaining the pack. Each pack is also its own plugin, so you can install just the one you want:++```bash+/plugin install knowledge-base@open-knowledge-skills+/plugin install personal-crm@open-knowledge-skills+```++<Callout type="info">+Pack skills were renamed: the generated `open-knowledge-pack-…` names became product names, so `open-knowledge-pack-plain-notes` is now `note-taking` and `open-knowledge-pack-knowledge-base-research` is now `research-with-sources`.++**Skills you already have are not renamed.** Nothing on your disk changes and your `.ok/skills-lock.json` is not rewritten — these are project-level skills that normally live in your git repo, so a silent rename would show up as an unexplained diff for you and everyone who pulls. An existing skill keeps its name, keeps working, and still updates from source. Re-seeding a pack recognizes it and will not install a second copy under the new name. Only newly installed skills use the new names.++Four plugin handles were renamed alongside their packs (`entity-vault` → `personal-crm`, `okf` → `okf-knowledge-base`, `plain-notes` → `note-taking`, `writing-pipeline` → `writing-workflow`). The old handles still resolve for one release and are marked outdated in the marketplace; switch to the new ones. `ok seed --pack <id>` flags are unchanged.+</Callout>+## Up next- **[Agentic search](../reference/agentic-search.mdx)**: how the agent reads your base.diff --git a/docs/content/reference/what-open-knowledge-writes.mdx b/docs/content/reference/what-open-knowledge-writes.mdxindex 7d53c3acb..d1778e8ee 100644--- a/docs/content/reference/what-open-knowledge-writes.mdx+++ b/docs/content/reference/what-open-knowledge-writes.mdx@@ -10,7 +10,7 @@ OpenKnowledge keeps your knowledge base as plain markdown in your own project diThis page lists every one of them: **when** each write happens, **what** it is, and **where** it is written.<Callout type="info" title="The short version">- **Nothing about your content leaves your machine by default.** Diagnostic logs and telemetry stay on your machine. The things that *can* send data off it — semantic search, a diagnostic or bug-report bundle, and GitHub sync — are opt-in or on-demand. Three automatic exceptions, none of which touch your documents: the desktop app checks for updates (sending its app version and channel), on its first launch it opens your browser once to check for a pending share link, and installing a **published skill** reports that install to skills.sh so the skill's public install count is accurate — the skill's name and source repository, once per skill per machine, and never for a private or local source. All of them are listed under [What leaves your machine](#what-leaves-your-machine), and the skill report can be turned off.+ **Nothing about your content leaves your machine by default.** Diagnostic logs and telemetry stay on your machine. The things that *can* send data off it — semantic search, a diagnostic or bug-report bundle, and GitHub sync — are opt-in or on-demand. Three automatic exceptions, none of which touch your documents: the desktop app checks for updates (sending its app version and channel), on its first launch it opens your browser once to check for a pending share link, and installing a **published skill** reports that install to skills.sh so the skill's public install count is accurate — the skill's name and source repository, once per skill (per project, for a skill installed into a project), and never for a private or local source. All of them are listed under [What leaves your machine](#what-leaves-your-machine), and the skill report can be turned off.</Callout>## How to read this page@@ -286,7 +286,7 @@ None of your content, by default. Everything above is written to your own disk.| GitHub sync / share | When you sync, clone, publish, or share | GitHub || Update check | Automatically — on launch and periodically while the desktop app runs | OpenKnowledge update service (`openknowledge.ai/updates`), which redirects to GitHub; sends the app version and channel || First-launch share check | Once, automatically, on the desktop app's first launch | `openknowledge.ai/continue` — redeems a share link if you installed from one |-| Skill-install report | Automatically, the first time a published skill is installed on this machine — OpenKnowledge's own built-in and starter-pack skills, and skills you install from a skills.sh listing. Once per skill per machine; never re-sent on a re-run, a reinstall, or an app launch. A skill you install by typing a repository yourself is **not** reported, and neither is a private, local, or internal-hostname source | `add-skill.vercel.sh` — the skill's name, its source repository, and which agent tools it was installed for. No file contents. This is what gives a published skill an accurate install count. Turn it off in **Settings → Preferences**, by setting `telemetry.skillInstallReports.enabled: false`, or with `DO_NOT_TRACK=1` / `DISABLE_TELEMETRY=1` |+| Skill-install report | Automatically, the first time a published skill is actually installed — OpenKnowledge's own built-in and starter-pack skills, and skills you install from a skills.sh listing. Counted once per skill for machine-wide installs (the built-in bundles), and once per skill **per project** for skills installed into a project, since each project gets its own copy in its own editor dirs. Never re-sent on a re-run, a reinstall, an app launch, or reopening a project — an app launch that installs nothing sends nothing. A skill you install by typing a **third-party** repository yourself is **not** reported, and neither is a private, local, or internal-hostname source. A skill bundle you switched off is never installed and so is never reported | `add-skill.vercel.sh` — the skill's name, its source repository, and which agent tools it was installed for. No file contents. This is what gives a published skill an accurate install count. Turn it off in **Settings → Preferences**, by setting `telemetry.skillInstallReports.enabled: false`, or with `DO_NOT_TRACK=1` / `DISABLE_TELEMETRY=1` || npm/`npx` fetch | During install (CLI) | The npm registry |Local diagnostic logs and telemetry are scrubbed of credential-bearing attributes and never sent anywhere on their own.diff --git a/docs/content/workflows/supporting-open-knowledge-format.mdx b/docs/content/workflows/supporting-open-knowledge-format.mdxindex 641b8bb4c..403928515 100644--- a/docs/content/workflows/supporting-open-knowledge-format.mdx+++ b/docs/content/workflows/supporting-open-knowledge-format.mdx@@ -51,7 +51,7 @@ In an initialized project (`ok init` first), pick **Open Knowledge Format** in t| `index.md` | Reserved OKF navigation hub | — (reserved) || `log.md` | Reserved OKF change history | — (reserved) |-Each of the three content folders (`concepts/`, `references/`, `notes/`) ships its **own template**, so new docs start with the right `type` and section skeleton already in place — you never hand-set the frontmatter. The conventions also ship as a project-local skill (`open-knowledge-pack-okf`) installed alongside the seed, so your agent learns the pack's discipline without a hand-written `CLAUDE.md`. Like every seeded file, that `SKILL.md` is committed to your repo and editable; see [Skills](../features/skills.mdx) and [what OpenKnowledge writes to disk](../reference/what-open-knowledge-writes.mdx).+Each of the three content folders (`concepts/`, `references/`, `notes/`) ships its **own template**, so new docs start with the right `type` and section skeleton already in place — you never hand-set the frontmatter. The conventions also ship as a project-local skill (`okf-knowledge-base`) installed alongside the seed, so your agent learns the pack's discipline without a hand-written `CLAUDE.md`. Like every seeded file, that `SKILL.md` is committed to your repo and editable; see [Skills](../features/skills.mdx) and [what OpenKnowledge writes to disk](../reference/what-open-knowledge-writes.mdx).## Conformance is pre-populated, not enforceddiff --git a/packages/app/src/components/SeedDialog.dom.test.tsx b/packages/app/src/components/SeedDialog.dom.test.tsxindex 3fb0013de..9fde3fe02 100644--- a/packages/app/src/components/SeedDialog.dom.test.tsx+++ b/packages/app/src/components/SeedDialog.dom.test.tsx@@ -50,6 +50,7 @@ vi.doMock('@/components/PackCardGrid', () => ({const toastSuccesses: string[] = [];const toastErrors: string[] = [];+const toastWarnings: string[] = [];const listPacksCalls: string[] = [];const planCalls: Array<{ packId?: OkPackId; rootDir?: string }> = [];const applyCalls: Array<{ plan: OkScaffoldPlan; packId?: OkPackId }> = [];@@ -114,7 +115,12 @@ vi.doMock('@/lib/seed-client', () => ({applyCalls.push({ plan, packId: options.packId });return {ok: true as const,- result: { applied: plan.created.length, errors: [], durationMs: 1 },+ result: {+ applied: plan.created.length,+ errors: [],+ durationMs: 1,+ packSkillConflicts: [],+ },};},}),@@ -124,6 +130,9 @@ vi.doMock('sonner', () => ({toast: {success: (message: string) => toastSuccesses.push(message),error: (message: string) => toastErrors.push(message),+ // Without this the conflict UX path throws inside the mock, making it+ // structurally untestable rather than merely uncovered.+ warning: (message: string) => toastWarnings.push(message),},}));@@ -150,6 +159,7 @@ describe('SeedDialog runtime behavior', () => {applyCalls.length = 0;toastSuccesses.length = 0;toastErrors.length = 0;+ toastWarnings.length = 0;planImpl = async (options) => ({ok: true,plan: options.packId === 'plain-notes' ? plainNotesPlan : knowledgeBasePlan,@@ -246,17 +256,37 @@ describe('SeedDialog runtime behavior', () => {ok: true,plan: {...plainNotesPlan,- packSkills: [{ name: 'open-knowledge-pack-plain-notes', pending: true }],+ packSkills: [{ name: 'note-taking', pending: true }],},});await renderSeedDialog({ initialPackId: 'plain-notes' });- // The skill card surfaces the pack name (prefix-stripped for legibility)- // with the full skill name preserved on hover, so users know what installs.- const skillName = await screen.findByText('plain-notes');- expect(skillName.getAttribute('title')).toBe('open-knowledge-pack-plain-notes');+ // The skill card names the skill, with the full name preserved on hover, so+ // users know what installs.+ const skillName = await screen.findByText('note-taking');+ expect(skillName.getAttribute('title')).toBe('note-taking');// The old free-standing "will be (re)installed" line is gone.expect(screen.queryByText(/will be \(re\)installed/)).toBeNull();});++ // A name collision leaves nothing to apply, so the dialog lands in+ // "already set up". Rendering the notice only in the plan phase meant the+ // user was told there was nothing to add while the pack's skill was silently+ // absent, with no Initialize button to reach the warning through.+ test('a conflicted pack skill is surfaced in the already-set-up phase', async () => {+ planImpl = async () => ({+ ok: true,+ plan: {+ ...plainNotesPlan,+ created: [],+ packSkills: [{ name: 'note-taking', pending: false, conflict: true }],+ },+ });++ await renderSeedDialog({ initialPackId: 'plain-notes' });++ expect(await screen.findByText(/already set up here/)).toBeTruthy();+ expect(await screen.findByText(/your own skill named "note-taking"/)).toBeTruthy();+ });});diff --git a/packages/app/src/components/SeedDialog.tsx b/packages/app/src/components/SeedDialog.tsxindex 2f5326be3..e83230776 100644--- a/packages/app/src/components/SeedDialog.tsx+++ b/packages/app/src/components/SeedDialog.tsx@@ -1,6 +1,7 @@import { plural } from '@lingui/core/macro';import { Trans, useLingui } from '@lingui/react/macro';import { ArrowLeft, Loader2 } from 'lucide-react';+import type { ReactElement } from 'react';import { useEffect, useRef, useState } from 'react';import { toast } from 'sonner';import { CreatedItemsList } from '@/components/CreatedItemsList';@@ -248,6 +249,20 @@ export function SeedDialog({ open, onOpenChange, onSeedApplied, initialPackId }:? t`${packName} skill installed.`: t`${packName} was already set up. Nothing to do.`;toast.success(message);+ // Name collisions are not errors — the seed succeeded and the user's own+ // skill was left untouched — but silence would read as "pack installed".+ // `hosts` means the skill DID install — a same-named skill of the user's+ // only displaced it in those editors. Saying "was not installed" there is+ // simply false, and the field that makes it true was being dropped.+ for (const conflict of result.result.packSkillConflicts ?? []) {+ const conflictName = conflict.name;+ const conflictHosts = conflict.hosts?.join(', ');+ toast.warning(+ conflictHosts === undefined || conflictHosts === ''+ ? t`Skill "${conflictName}" was not installed — you already have your own skill with that name. Rename yours if you want the pack's version.`+ : t`Skill "${conflictName}" was not installed for ${conflictHosts} — you already have your own skill with that name there. Rename yours if you want the pack's version.`,+ );+ }onSeedApplied?.();onOpenChange(false);} else {@@ -471,13 +486,20 @@ function SeedDialogBody({if (phase.kind === 'already-seeded') {return (- <div className="py-2 text-sm">- <p className="font-medium">- <Trans>This pack is already set up here.</Trans>- </p>- <p className="text-muted-foreground">- <Trans>The folders and templates are already here, so there's nothing to add.</Trans>- </p>+ <div className="space-y-3 py-2 text-sm">+ <div>+ <p className="font-medium">+ <Trans>This pack is already set up here.</Trans>+ </p>+ <p className="text-muted-foreground">+ <Trans>The folders and templates are already here, so there's nothing to add.</Trans>+ </p>+ </div>+ {/* A name collision leaves nothing to apply, so this phase is exactly+ where it lands. Without it the dialog says "nothing to add" while+ the pack's skill is silently absent, and the Initialize button that+ would surface the conflict is never rendered. */}+ <PackSkillConflicts plan={phase.plan} /></div>);}@@ -494,6 +516,25 @@ function SeedDialogBody({))}</div>) : null}+ <PackSkillConflicts plan={phase.plan} />+ </div>+ );+}++/** Name collisions from the plan: the pack skill the user's own skill displaces. */+function PackSkillConflicts({ plan }: { plan: OkScaffoldPlan }): ReactElement | null {+ const conflicts = plan.packSkills?.filter((s) => s.conflict) ?? [];+ if (conflicts.length === 0) return null;+ return (+ <div className="rounded-md bg-warning/10 p-3 text-xs text-warning-foreground">+ {conflicts.map((s) => (+ <p key={s.name}>+ <Trans>+ You already have your own skill named "{s.name}" — the pack's version will not be+ installed, and yours won't be touched. Rename yours to install the pack's version.+ </Trans>+ </p>+ ))}</div>);}diff --git a/packages/app/src/components/SkillPluginBundleDialog.tsx b/packages/app/src/components/SkillPluginBundleDialog.tsxindex f6d4220b9..e8147bfca 100644--- a/packages/app/src/components/SkillPluginBundleDialog.tsx+++ b/packages/app/src/components/SkillPluginBundleDialog.tsx@@ -137,6 +137,10 @@ export function SkillPluginBundleDialog({skills: [...selected],scope,install: false,+ // The bundle disclosure only exists on the Explore (skills.sh) flavor —+ // same marketplace-provenance condition the single-skill path uses — so+ // the whole selection is reported as one batched install event.+ marketplace: true,});if (!result.ok) {setBusy(false);diff --git a/packages/app/src/lib/skill-scope.dom.test.ts b/packages/app/src/lib/skill-scope.dom.test.tsnew file mode 100644index 000000000..6296601af--- /dev/null+++ b/packages/app/src/lib/skill-scope.dom.test.ts@@ -0,0 +1,24 @@+import { describe, expect, test } from 'vitest';+import { skillDisplayName } from './skill-scope';++describe('skillDisplayName', () => {+ // Load-bearing precisely BECAUSE existing installs are never renamed: the long+ // prefixed names live indefinitely, and without the strip they render in full+ // in the sidebar and tab labels — the overflow this helper exists to prevent.+ test('strips the pack prefix from a pre-rename install', () => {+ expect(skillDisplayName('open-knowledge-pack-software-lifecycle')).toBe('software-lifecycle');+ expect(skillDisplayName('open-knowledge-pack-knowledge-base-research')).toBe(+ 'knowledge-base-research',+ );+ });++ test('leaves post-rename and user-authored names alone', () => {+ for (const name of ['note-taking', 'research-with-sources', 'my-own-skill', 'open-knowledge']) {+ expect(skillDisplayName(name)).toBe(name);+ }+ });++ test('does not strip a name that merely contains the prefix', () => {+ expect(skillDisplayName('my-open-knowledge-pack-thing')).toBe('my-open-knowledge-pack-thing');+ });+});diff --git a/packages/app/src/lib/skill-scope.ts b/packages/app/src/lib/skill-scope.tsindex e9b717afe..822dab02d 100644--- a/packages/app/src/lib/skill-scope.ts+++ b/packages/app/src/lib/skill-scope.ts@@ -36,10 +36,14 @@ export function skillNameSetsByScope(/*** Browse-surface display name for a skill: drops the shared- * `open-knowledge-pack-` prefix so e.g. `open-knowledge-pack-software-lifecycle`- * (the longest shipped default) reads as `software-lifecycle` and fits a normal- * sidebar width. DISPLAY-ONLY — the full name stays the identity (rename field,- * doc path, tooltips); user-authored skills (no prefix) are unchanged.+ * `open-knowledge-pack-` prefix so a pre-rename install of e.g.+ * `open-knowledge-pack-software-lifecycle` reads as `software-lifecycle` and+ * fits a normal sidebar width. Load-bearing precisely BECAUSE existing installs+ * are never renamed: those long names live indefinitely, and stripping+ * makes them read the same as the short name a fresh install gets. DISPLAY-ONLY+ * — the full name stays the identity (rename field, doc path, tooltips);+ * user-authored skills and post-rename installs have no prefix and are+ * unchanged.*/export function skillDisplayName(name: string): string {return name.startsWith(PACK_SKILL_PREFIX) ? name.slice(PACK_SKILL_PREFIX.length) : name;diff --git a/packages/app/src/lib/skills-api.ts b/packages/app/src/lib/skills-api.tsindex 980f6fcf7..a76dceed3 100644--- a/packages/app/src/lib/skills-api.ts+++ b/packages/app/src/lib/skills-api.ts@@ -364,6 +364,10 @@ export async function importSkillsBulk(input: {scope: SkillScope;/** false = import only, no default-editor auto-projection. */install?: boolean;+ /** The source is a skills.sh listing the user chose (a marketplace plugin+ * bundle), so the import is reported to skills.sh as one batched install+ * event. Never set for a hand-entered source. */+ marketplace?: boolean;}): Promise<WriteResult<SkillsImportBulkSuccess>> {try {const res = await fetch('/api/skills/import-bulk', {diff --git a/packages/app/src/locales/en/messages.json b/packages/app/src/locales/en/messages.jsonindex 5cd9c3863..31cc61ad6 100644--- a/packages/app/src/locales/en/messages.json+++ b/packages/app/src/locales/en/messages.json@@ -815,6 +815,11 @@"CmeH9S": ["Add property to ", ["keyName"]],"CnOGgs": ["Sync mode"],"CoHvYd": ["Moved ", ["0"], " to position ", ["1"], " of ", ["2"]],+ "CtoghX": [+ "You already have your own skill named \"",+ ["0"],+ "\" — the pack's version will not be installed, and yours won't be touched. Rename yours to install the pack's version."+ ],"Cu6GXQ": ["The source folder itself does not move."],"CvsD6Y": ["via ", ["viaTags"]],"CwOXMT": ["Value for ", ["keyName"]],@@ -1080,6 +1085,11 @@"Gfr4fu": ["Server can't open documents"],"GhjUB_": ["Reconnected"],"GidGkh": ["Update from source"],+ "GifIjR": [+ "Skill \"",+ ["conflictName"],+ "\" was not installed — you already have your own skill with that name. Rename yours if you want the pack's version."+ ],"GkYV_4": ["Renamed ", ["0"], " → ", ["1"]],"Gp_twO": ["Local path"],"GrBgX_": [@@ -1427,6 +1437,13 @@"MqsbfN": ["Turn on external link previews?"],"MrwYIK": ["Toggle a source comment through CodeMirror."],"MuxcRB": [["0"], " lets ", ["1"], " act without asking"],+ "Mv2lM4": [+ "Skill \"",+ ["conflictName"],+ "\" was not installed for ",+ ["conflictHosts"],+ " — you already have your own skill with that name there. Rename yours if you want the pack's version."+ ],"My0wYT": ["When you hover an external link, its URL is sent to the destination site to fetch the page's preview metadata — one request per previewed link."],diff --git a/packages/app/src/locales/en/messages.po b/packages/app/src/locales/en/messages.poindex 107ba5400..4c1c8911c 100644--- a/packages/app/src/locales/en/messages.po+++ b/packages/app/src/locales/en/messages.po@@ -9946,6 +9946,14 @@ msgstr "skill \"{0}\""msgid "Skill \"{0}\" deleted"msgstr "Skill \"{0}\" deleted"+#: src/components/SeedDialog.tsx+msgid "Skill \"{conflictName}\" was not installed — you already have your own skill with that name. Rename yours if you want the pack's version."+msgstr "Skill \"{conflictName}\" was not installed — you already have your own skill with that name. Rename yours if you want the pack's version."++#: src/components/SeedDialog.tsx+msgid "Skill \"{conflictName}\" was not installed for {conflictHosts} — you already have your own skill with that name there. Rename yours if you want the pack's version."+msgstr "Skill \"{conflictName}\" was not installed for {conflictHosts} — you already have your own skill with that name there. Rename yours if you want the pack's version."+#: src/hooks/use-create-blank-skill.tsmsgid "Skill \"{name}\" created"msgstr "Skill \"{name}\" created"@@ -12097,6 +12105,11 @@ msgstr "YAML or JSON, in either base16 layout."msgid "yesterday"msgstr "yesterday"+#. placeholder {0}: s.name+#: src/components/SeedDialog.tsx+msgid "You already have your own skill named \"{0}\" — the pack's version will not be installed, and yours won't be touched. Rename yours to install the pack's version."+msgstr "You already have your own skill named \"{0}\" — the pack's version will not be installed, and yours won't be touched. Rename yours to install the pack's version."+#: src/components/ReportBugDialogBody.tsxmsgid "You can also create one from a terminal with <0>ok bug-report</0>."msgstr "You can also create one from a terminal with <0>ok bug-report</0>."diff --git a/packages/app/src/locales/pseudo/messages.json b/packages/app/src/locales/pseudo/messages.jsonindex a7a3bee31..e3a731c9f 100644--- a/packages/app/src/locales/pseudo/messages.json+++ b/packages/app/src/locales/pseudo/messages.json@@ -815,6 +815,11 @@"CmeH9S": ["Àďď ƥŕōƥēŕţŷ ţō ", ["keyName"]],"CnOGgs": ["Śŷńć ḿōďē"],"CoHvYd": ["Ḿōvēď ", ["0"], " ţō ƥōśĩţĩōń ", ["1"], " ōƒ ", ["2"]],+ "CtoghX": [+ "Ŷōũ àĺŕēàďŷ ĥàvē ŷōũŕ ōŵń śķĩĺĺ ńàḿēď \"",+ ["0"],+ "\" — ţĥē ƥàćķ'ś vēŕśĩōń ŵĩĺĺ ńōţ ƀē ĩńśţàĺĺēď, àńď ŷōũŕś ŵōń'ţ ƀē ţōũćĥēď. Ŕēńàḿē ŷōũŕś ţō ĩńśţàĺĺ ţĥē ƥàćķ'ś vēŕśĩōń."+ ],"Cu6GXQ": ["Ţĥē śōũŕćē ƒōĺďēŕ ĩţśēĺƒ ďōēś ńōţ ḿōvē."],"CvsD6Y": ["vĩà ", ["viaTags"]],"CwOXMT": ["Vàĺũē ƒōŕ ", ["keyName"]],@@ -1080,6 +1085,11 @@"Gfr4fu": ["Śēŕvēŕ ćàń'ţ ōƥēń ďōćũḿēńţś"],"GhjUB_": ["Ŕēćōńńēćţēď"],"GidGkh": ["Ũƥďàţē ƒŕōḿ śōũŕćē"],+ "GifIjR": [+ "Śķĩĺĺ \"",+ ["conflictName"],+ "\" ŵàś ńōţ ĩńśţàĺĺēď — ŷōũ àĺŕēàďŷ ĥàvē ŷōũŕ ōŵń śķĩĺĺ ŵĩţĥ ţĥàţ ńàḿē. Ŕēńàḿē ŷōũŕś ĩƒ ŷōũ ŵàńţ ţĥē ƥàćķ'ś vēŕśĩōń."+ ],"GkYV_4": ["Ŕēńàḿēď ", ["0"], " → ", ["1"]],"Gp_twO": ["Ĺōćàĺ ƥàţĥ"],"GrBgX_": [@@ -1427,6 +1437,13 @@"MqsbfN": ["Ţũŕń ōń ēxţēŕńàĺ ĺĩńķ ƥŕēvĩēŵś?"],"MrwYIK": ["Ţōĝĝĺē à śōũŕćē ćōḿḿēńţ ţĥŕōũĝĥ ĆōďēḾĩŕŕōŕ."],"MuxcRB": [["0"], " ĺēţś ", ["1"], " àćţ ŵĩţĥōũţ àśķĩńĝ"],+ "Mv2lM4": [+ "Śķĩĺĺ \"",+ ["conflictName"],+ "\" ŵàś ńōţ ĩńśţàĺĺēď ƒōŕ ",+ ["conflictHosts"],+ " — ŷōũ àĺŕēàďŷ ĥàvē ŷōũŕ ōŵń śķĩĺĺ ŵĩţĥ ţĥàţ ńàḿē ţĥēŕē. Ŕēńàḿē ŷōũŕś ĩƒ ŷōũ ŵàńţ ţĥē ƥàćķ'ś vēŕśĩōń."+ ],"My0wYT": ["Ŵĥēń ŷōũ ĥōvēŕ àń ēxţēŕńàĺ ĺĩńķ, ĩţś ŨŔĹ ĩś śēńţ ţō ţĥē ďēśţĩńàţĩōń śĩţē ţō ƒēţćĥ ţĥē ƥàĝē'ś ƥŕēvĩēŵ ḿēţàďàţà — ōńē ŕēǫũēśţ ƥēŕ ƥŕēvĩēŵēď ĺĩńķ."],diff --git a/packages/app/src/locales/pseudo/messages.po b/packages/app/src/locales/pseudo/messages.poindex 8c2a1f58b..453c6130d 100644--- a/packages/app/src/locales/pseudo/messages.po+++ b/packages/app/src/locales/pseudo/messages.po@@ -9942,6 +9942,14 @@ msgstr ""msgid "Skill \"{0}\" deleted"msgstr ""+#: src/components/SeedDialog.tsx+msgid "Skill \"{conflictName}\" was not installed — you already have your own skill with that name. Rename yours if you want the pack's version."+msgstr ""++#: src/components/SeedDialog.tsx+msgid "Skill \"{conflictName}\" was not installed for {conflictHosts} — you already have your own skill with that name there. Rename yours if you want the pack's version."+msgstr ""+#: src/hooks/use-create-blank-skill.tsmsgid "Skill \"{name}\" created"msgstr ""@@ -12093,6 +12101,11 @@ msgstr ""msgid "yesterday"msgstr ""+#. placeholder {0}: s.name+#: src/components/SeedDialog.tsx+msgid "You already have your own skill named \"{0}\" — the pack's version will not be installed, and yours won't be touched. Rename yours to install the pack's version."+msgstr ""+#: src/components/ReportBugDialogBody.tsxmsgid "You can also create one from a terminal with <0>ok bug-report</0>."msgstr ""diff --git a/packages/cli/src/commands/init.ts b/packages/cli/src/commands/init.tsindex ff378deda..856113d59 100644--- a/packages/cli/src/commands/init.ts+++ b/packages/cli/src/commands/init.ts@@ -17,6 +17,7 @@ import { existsSync, mkdirSync, readFileSync, realpathSync, statSync } from 'nodimport { homedir } from 'node:os';import { dirname, isAbsolute, join, relative, resolve } from 'node:path';import { inspect } from 'node:util';+import { OPENKNOWLEDGE_SKILLS_REPO } from '@inkeep/open-knowledge-core';import { atomicWriteFileSync, withFileLockSync } from '@inkeep/open-knowledge-core/server';import type {BundleId,@@ -34,6 +35,8 @@ import {installUserSkill,MCP_SERVER_NAME,ProjectGitInitError,+ reportSkillInstall,+ resolveSkillInstallReportSettings,USER_GLOBAL_BUNDLE_IDS,untrackTrackedProjectSkillProjection,writeBundleDecision,@@ -1789,6 +1792,36 @@ export async function runInit(options: InitCommandOptions = {}): Promise<InitComprojectSkillResults.push(writeProjectSkill(target, projectRoot, { home: options.home }));}+ // Count the project skill on skills.sh. Initializing a project installs the+ // `open-knowledge` skill into that project's editor dirs — a real install of a+ // skill we publish, and until now the only install path that reported nothing.+ // The user-global bundles report once per machine, so without this a user's+ // second, tenth and hundredth project were invisible.+ //+ // ONE event per project, not per editor: the same skill in three editor dirs+ // is one install. Scoped to the project so re-running `ok init` here counts+ // nothing while a genuinely new project counts once. Fire-and-forget for the+ // same reason as the user-global report — never make init wait on a third+ // party.+ // Only a SUCCESSFUL write is an install. `action` has five variants and three+ // of them are not one: the two skips, and `failed` — counting a failed write+ // would report an install of a skill that is not on disk.+ const installedForEditors = projectSkillResults+ .filter((r) => r.action === 'written' || r.action === 'overwritten')+ .map((r) => r.editorId);+ if (installedForEditors.length > 0) {+ const reportHome = options.home ?? homedir();+ void reportSkillInstall(+ {+ source: OPENKNOWLEDGE_SKILLS_REPO,+ skills: [BUNDLE_SKILL_NAME.project],+ agents: installedForEditors,+ scope: projectRoot,+ },+ { home: reportHome, enabled: resolveSkillInstallReportSettings(reportHome).enabled },+ );+ }+// Editors skipped for project-scope because they have no project-local artifact.// Copilot has no project MCP-config format, but it does receive a project skill.const projectScopeUnsupportedLabels =diff --git a/packages/cli/src/commands/seed.ts b/packages/cli/src/commands/seed.tsindex fca384636..e7bdb8e80 100644--- a/packages/cli/src/commands/seed.ts+++ b/packages/cli/src/commands/seed.ts@@ -104,9 +104,18 @@ export async function runSeed(opts: SeedCommandOptions = {}): Promise<SeedComman// and install it, so this is not a no-op. SeedDialog folds the same two signals.if (plan.created.length === 0 && !plan.packSkills?.some((s) => s.pending)) {const packName = STARTER_PACKS[packId].name;+ // A conflicted skill is present-but-not-ours: "already seeded" would+ // misread the user's own skill as the pack's, so say what's actually true.+ const conflictNote = (plan.packSkills ?? [])+ .filter((s) => s.conflict)+ .map(+ (s) =>+ `\n${warning('!')} Skill "${s.name}" is your own — the pack's version is not installed. Rename yours to install the pack's version.`,+ )+ .join('');return {status: 'no-op',- message: `${success(`Your ${packName} pack is already seeded.`)}\n${dim('Nothing to do.')}`,+ message: `${success(`Your ${packName} pack is already seeded.`)}${conflictNote}\n${dim('Nothing to do.')}`,plan,exitCode: 0,};@@ -168,9 +177,21 @@ export async function runSeed(opts: SeedCommandOptions = {}): Promise<SeedComman? `\n${dim(`Installed the ${packName} skills for: ${applyResult.packSkillsInstalled.join(', ')}`)}`: '';+ // Name collisions are not errors — the seed succeeded and the user's own+ // skill was left untouched — but silence would read as "pack installed".+ // `hosts` means the skill DID install — a same-named skill of the user's only+ // displaced it in those editors, so the flat "was not installed" is false.+ const conflictLines = (applyResult.packSkillConflicts ?? [])+ .map((c) =>+ c.hosts === undefined || c.hosts.length === 0+ ? `\n${warning('!')} Skill "${c.name}" was not installed — you already have your own skill with that name. Rename yours if you want the pack's version.`+ : `\n${warning('!')} Skill "${c.name}" was not installed for ${c.hosts.join(', ')} — you already have your own skill with that name there. Rename yours if you want the pack's version.`,+ )+ .join('');+return {status: 'applied',- message: `${success(`✓ Seeded ${packName}`)} ${dim(`(${applyResult.applied} entries, ${applyResult.durationMs}ms)`)}${skillLine}`,+ message: `${success(`✓ Seeded ${packName}`)} ${dim(`(${applyResult.applied} entries, ${applyResult.durationMs}ms)`)}${skillLine}${conflictLines}`,plan,exitCode: 0,};@@ -226,6 +247,21 @@ function formatPlanBody(plan: ScaffoldPlan, cwd: string): string {}}+ // Name collisions belong in the PREVIEW, not only in the applied output: this+ // body renders both `--dry-run` and the confirm prompt, and a user deciding+ // whether to seed needs to know a pack skill will be held back before the+ // write, not after it.+ const conflicts = (plan.packSkills ?? []).filter((s) => s.conflict);+ if (conflicts.length > 0) {+ if (lines.length > 0) lines.push('');+ lines.push(warning('Name collisions:'));+ for (const s of conflicts) {+ lines.push(+ ` ${warning('!')} Skill "${s.name}" is your own — the pack's version will not be installed. Rename yours to install the pack's version.`,+ );+ }+ }+return lines.join('\n');}diff --git a/packages/core/src/constants/skills.test.ts b/packages/core/src/constants/skills.test.tsindex da903d975..e1818022b 100644--- a/packages/core/src/constants/skills.test.ts+++ b/packages/core/src/constants/skills.test.ts@@ -1,5 +1,5 @@import { describe, expect, test } from 'vitest';-import { extractSkillRefs, rewriteSkillRefs } from './skills.ts';+import { extractSkillRefs, isOpenKnowledgeSkillsSource, rewriteSkillRefs } from './skills.ts';describe('rewriteSkillRefs', () => {test('rewrites both forms the extractor reads', () => {@@ -48,3 +48,54 @@ describe('rewriteSkillRefs', () => {expect(extractSkillRefs(out)).toEqual(['grilling']);});});++describe('isOpenKnowledgeSkillsSource', () => {+ // Decides two things: whether a present skill is ours (seed collision), and+ // whether an install counts toward our own skills.sh listing. The lock keeps+ // the raw source the user arrived through, so all of these are the same repo.+ test('matches the bare repo, a skills.sh listing URL, and a git URL', () => {+ for (const source of [+ 'inkeep/open-knowledge-skills',+ 'https://skills.sh/inkeep/open-knowledge-skills/note-taking',+ 'https://github.com/inkeep/open-knowledge-skills.git',+ '[email protected]:inkeep/open-knowledge-skills.git',+ ]) {+ expect(isOpenKnowledgeSkillsSource(source)).toBe(true);+ }+ });++ // The privacy rule this predicate carves out of: a repo the user did not+ // choose from the marketplace is never announced to a third party.+ // The predicate gates two things: whether a present skill is OURS (so seed may+ // refresh it) and whether an install is announced to skills.sh. A loose match+ // therefore both clobbers and leaks, so the boundaries are load-bearing.+ test('a lookalike owner is not us', () => {+ // Valid `owner/repo` shape, contains our repo as a substring, is not ours.+ // A substring test would announce this third party's repo to skills.sh.+ expect(isOpenKnowledgeSkillsSource('notinkeep/open-knowledge-skills')).toBe(false);+ expect(isOpenKnowledgeSkillsSource('inkeep/open-knowledge-skills-fork')).toBe(false);+ });++ test("our repo path on somebody else's host is not us", () => {+ for (const source of [+ 'https://evil.example/inkeep/open-knowledge-skills',+ 'evil.example.com/inkeep/open-knowledge-skills',+ 'https://evil.example/redirect?to=inkeep/open-knowledge-skills',+ '[email protected]:inkeep/open-knowledge-skills.git',+ ]) {+ expect(isOpenKnowledgeSkillsSource(source)).toBe(false);+ }+ });++ test('does not match somebody else', () => {+ for (const source of [+ 'someone-else/skills',+ 'inkeep/agents',+ 'https://skills.sh/anthropics/skills/code-review',+ 'adopt:claude',+ '',+ ]) {+ expect(isOpenKnowledgeSkillsSource(source)).toBe(false);+ }+ });+});diff --git a/packages/core/src/constants/skills.ts b/packages/core/src/constants/skills.tsindex d64747653..6331f5586 100644--- a/packages/core/src/constants/skills.ts+++ b/packages/core/src/constants/skills.ts@@ -1,15 +1,121 @@/**- * Shared prefix on OK's shipped starter-pack skills (`open-knowledge-pack-<packId>`,- * and `open-knowledge-pack-<packId>-<member>` for a decomposed pack's members).- *- * Structurally load-bearing: it exempts pack skills from the reserved-name install- * block (`skill-projection.ts`), drives `findPackSkillSource`, and is stripped for- * display in the browse surfaces. Lives in core so the server and app agree on one- * value. The Copybara skills-mirror manifest encodes it too — that copy is config,- * guarded by `check-skills-mirror-complete`.+ * LEGACY prefix the starter-pack skills carried before the marketplace rename+ * (`open-knowledge-pack-<packId>[-<member>]`). It no longer names anything the+ * codebase ships: shipped names come from SKILL.md frontmatter. It survives+ * solely to recognize OLD installs — `retrofitPackLockEntry`'s gate and the+ * keys of {@link RENAMED_PACK_SKILLS}. Never compare shipped skills against it,+ * and never set it to '' (a universal `startsWith('')` match).*/export const PACK_SKILL_PREFIX = 'open-knowledge-pack-';+/**+ * Did this lock/import source come from OK's OWN published skills repo? The+ * lock keeps the raw source the user arrived through, so the same bundle records+ * the bare `owner/repo` when seeded or hand-typed and a skills.sh URL naming that+ * repo when installed from a listing.+ *+ * Used for two different decisions, both of which need the loose match: whether a+ * present skill is ours (seed collision classification), and whether an install+ * counts toward our own skills.sh listing. The privacy rule that gates OTHER+ * sources — never announce a repo the user did not choose from the marketplace —+ * does not apply here, because the repo being named is ours.+ */+export function isOpenKnowledgeSkillsSource(source: string): boolean {+ const raw = source.trim();+ if (raw === OPENKNOWLEDGE_SKILLS_REPO) return true;++ // A bare `owner/repo` must match EXACTLY. A substring test reads+ // `notinkeep/open-knowledge-skills` as ours — a third party's repo, in a+ // valid owner/repo shape, which the reporter would then happily announce.+ if (!raw.includes('://') && !raw.includes('@')) return false;++ // Anything else has to name a host we actually publish through, with our repo+ // at the START of the path. Otherwise `evil.example/inkeep/open-knowledge-skills`+ // passes on the strength of a path segment anyone can create.+ if (raw.includes('://')) {+ try {+ const url = new URL(raw);+ return TRUSTED_SKILL_HOSTS.has(url.hostname.toLowerCase()) && pathIsOurRepo(url.pathname);+ } catch {+ return false;+ }+ }+ // scp-style git remote: `[email protected]:inkeep/open-knowledge-skills.git`.+ // Checked AFTER the URL branch — this pattern also matches `https://…`, where+ // it would read the scheme as the host.+ const scp = /^(?:[\w.-]+@)?([\w.-]+):(.+)$/.exec(raw);+ if (scp) return TRUSTED_SKILL_HOSTS.has(scp[1].toLowerCase()) && pathIsOurRepo(scp[2]);+ return false;+}++/** Hosts our skills repo is legitimately served from. */+const TRUSTED_SKILL_HOSTS: ReadonlySet<string> = new Set([+ 'skills.sh',+ 'www.skills.sh',+ 'github.com',+ 'www.github.com',+ 'raw.githubusercontent.com',+]);++/** Does this URL path name our repo at its root (`.git` suffix tolerated)? */+function pathIsOurRepo(pathname: string): boolean {+ const trimmed = pathname.replace(/^\/+/, '').replace(/\.git$/, '');+ return (+ trimmed === OPENKNOWLEDGE_SKILLS_REPO || trimmed.startsWith(`${OPENKNOWLEDGE_SKILLS_REPO}/`)+ );+}++/**+ * Decision key for a PROJECT's copy of the platform skill, stored in the+ * machine-local `bundles` map alongside the user-global bundle decisions.+ *+ * Exists because the desktop's project-open reclaim creates the project skill+ * for any wired host that lacks one. Without a recorded decision that heals the+ * cohort onboarded before the writer existed — but it also silently reinstates a+ * skill the user just switched OFF in Settings, on the very next open. Keyed by+ * project dir and machine-local on purpose: one teammate's choice must not ride+ * along in the repo.+ */+export function projectSkillDecisionKey(projectDir: string): string {+ return `project-skill:${projectDir}`;+}++/**+ * Old→new names from the 2026-07 pack-skill rename (marketplace short names).+ * Existing installs are NEVER renamed, so this map is only ever read+ * old-name-first — it never writes a new name onto anyone's disk. Live+ * consumers: the import and reimport selectors, which resolve an old-name+ * request against the renamed mirror bundle; the seed path, which counts an+ * old-name install as present so re-seeding authors no duplicate; and the+ * reserved-name gate, which keeps these exact old names installable. This is the ONLY+ * old→new map in the codebase — tests and mirror machinery must not carry a+ * copy of it.+ *+ *+ * ENTRIES ARE PERMANENT. Existing installs are never renamed, so an old name can+ * be on someone's disk indefinitely — and every consumer here reads old-name+ * first. Deleting an entry silently breaks that install's Update, its seed+ * presence check (a duplicate gets authored beside it), and its reserved-name+ * exemption (it stops being installable at all). Add entries; do not remove them.+ */+export const RENAMED_PACK_SKILLS: Readonly<Record<string, string>> = {+ 'open-knowledge-pack-plain-notes': 'note-taking',+ 'open-knowledge-pack-worldbuilding': 'worldbuilding',+ 'open-knowledge-pack-writing-pipeline': 'writing-workflow',+ 'open-knowledge-pack-codebase-wiki': 'codebase-wiki',+ 'open-knowledge-pack-knowledge-base': 'knowledge-base',+ 'open-knowledge-pack-software-lifecycle': 'software-lifecycle',+ 'open-knowledge-pack-entity-vault': 'personal-crm',+ 'open-knowledge-pack-okf': 'okf-knowledge-base',+ 'open-knowledge-pack-software-lifecycle-frame-a-proposal': 'frame-a-proposal',+ 'open-knowledge-pack-software-lifecycle-record-a-decision': 'record-a-decision',+ 'open-knowledge-pack-software-lifecycle-write-a-spec': 'write-a-spec',+ 'open-knowledge-pack-software-lifecycle-review-a-design': 'review-a-design',+ 'open-knowledge-pack-software-lifecycle-write-a-postmortem': 'write-a-postmortem',+ 'open-knowledge-pack-knowledge-base-research': 'research-with-sources',+ 'open-knowledge-pack-knowledge-base-consolidate': 'consolidate-notes',+};+/*** GitHub `owner/repo` of the public projection skills.sh indexes* (`copybara/manifests/public-open-knowledge-skills.json` mirrors the bundleddiff --git a/packages/core/src/desktop-bridge.ts b/packages/core/src/desktop-bridge.tsindex 929be4fdf..b6247bc92 100644--- a/packages/core/src/desktop-bridge.ts+++ b/packages/core/src/desktop-bridge.ts@@ -657,8 +657,9 @@ export interface OkScaffoldPlan {skipped: OkScaffoldSkipEntry[];warnings: string[];/** Project-local skills shipped by the pack. `pending` means apply would- * author or refresh the skill source. */- packSkills?: { name: string; pending: boolean }[];+ * author or refresh the skill source. `conflict` means a user-owned skill+ * holds the name; apply will neither install nor clobber it. */+ packSkills?: { name: string; pending: boolean; conflict?: boolean }[];}export interface OkScaffoldApplyError {path: string;@@ -670,6 +671,8 @@ export interface OkScaffoldApplyResult {durationMs: number;/** Editor display-names that received the pack's project skill (e.g. "Claude Code"). */packSkillsInstalled: string[];+ /** Pack skills skipped because a user-owned same-named skill holds the name. */+ packSkillConflicts: { name: string; hosts?: string[] }[];}export interface OkSeedError {diff --git a/packages/core/src/index.ts b/packages/core/src/index.tsindex e4ac295d0..fee3dc91a 100644--- a/packages/core/src/index.ts+++ b/packages/core/src/index.ts@@ -353,9 +353,12 @@ export { PRODUCT_NAME } from './constants/product.ts';export { DEFAULT_SERVER_HOST } from './constants/server.ts';export {extractSkillRefs,+ isOpenKnowledgeSkillsSource,isSkillRefCandidate,OPENKNOWLEDGE_SKILLS_REPO,PACK_SKILL_PREFIX,+ projectSkillDecisionKey,+ RENAMED_PACK_SKILLS,rewriteSkillRefs,SKILL_REF_RE,} from './constants/skills.ts';diff --git a/packages/core/src/schemas/api/tags-search.ts b/packages/core/src/schemas/api/tags-search.tsindex 1fb0e0f7e..63521c67c 100644--- a/packages/core/src/schemas/api/tags-search.ts+++ b/packages/core/src/schemas/api/tags-search.ts@@ -1571,6 +1571,10 @@ export const SkillsImportBulkRequestSchema = zinstall: z.boolean().optional().meta({description: 'Pass false to import WITHOUT the default-editor auto-projection. Default true.',}),+ marketplace: z.boolean().optional().meta({+ description:+ 'The source came from a skills.sh listing the user chose (a marketplace plugin bundle), so the import is reported to skills.sh as one batched install event and counts toward that listing. Off by default: a hand-typed repo must not be announced to skills.sh. Honors the `telemetry.skillInstallReports.enabled` setting and DO_NOT_TRACK.',+ }),...agentIdentityFields,summary: summaryField,})diff --git a/packages/core/src/skills-catalog/acquire/lockfile.test.ts b/packages/core/src/skills-catalog/acquire/lockfile.test.tsindex a008b43a3..c9aee2553 100644--- a/packages/core/src/skills-catalog/acquire/lockfile.test.ts+++ b/packages/core/src/skills-catalog/acquire/lockfile.test.ts@@ -19,4 +19,60 @@ describe('retrofitPackLockEntry', () => {null,);});++ // Post-rename a fresh pack install is short-named. Gating the retrofit on the+ // old prefix alone left those installs with no way back if their lock entry+ // went missing — Update answered "no recorded import source" and nothing in+ // the product could repair it.+ test('retrofits a post-rename pack skill name when the bundle proves it is ours', () => {+ const entry = retrofitPackLockEntry('note-taking', 'a'.repeat(64), '2026-08-04T00:00:00.000Z', {+ selfIdentifiesAsPack: true,+ });+ expect(entry?.source).toBe(OPENKNOWLEDGE_SKILLS_REPO);+ expect(entry?.skill).toBe('note-taking');+ });++ // The published short names are generic enough that a user may own one.+ // Without a witness we would stamp our provenance onto their skill, and the+ // next Update would offer to overwrite it with ours.+ test('refuses a post-rename name with no pack witness', () => {+ for (const name of ['note-taking', 'write-a-spec', 'knowledge-base']) {+ expect(retrofitPackLockEntry(name, 'a'.repeat(64), '2026-08-04T00:00:00.000Z')).toBeNull();+ expect(+ retrofitPackLockEntry(name, 'a'.repeat(64), '2026-08-04T00:00:00.000Z', {+ selfIdentifiesAsPack: false,+ }),+ ).toBeNull();+ }+ });++ // The witness alone must not grant retrofit: the name still has to be one we+ // actually publish. A user's own skill that happens to carry a `metadata.pack`+ // line — a doc about packs, a copied bundle — is not ours to claim.+ test('a name we do not publish is refused even with a witness', () => {+ for (const name of ['my-own-skill', 'code-review', 'open-knowledge']) {+ expect(+ retrofitPackLockEntry(name, 'a'.repeat(64), '2026-08-04T00:00:00.000Z', {+ selfIdentifiesAsPack: true,+ }),+ ).toBeNull();+ }+ });++ // The old prefixed names are namespaced — nobody else can hold them — so+ // presence alone stays sufficient there.+ test('an old prefixed name needs no witness', () => {+ const entry = retrofitPackLockEntry(+ `${PACK_SKILL_PREFIX}plain-notes`,+ 'a'.repeat(64),+ '2026-08-04T00:00:00.000Z',+ );+ expect(entry?.source).toBe(OPENKNOWLEDGE_SKILLS_REPO);+ });++ test('still returns null for a name that is not a pack skill', () => {+ expect(+ retrofitPackLockEntry('my-own-skill', 'a'.repeat(64), '2026-08-04T00:00:00.000Z'),+ ).toBeNull();+ });});diff --git a/packages/core/src/skills-catalog/acquire/lockfile.ts b/packages/core/src/skills-catalog/acquire/lockfile.tsindex 74f3e95e1..04a93b87a 100644--- a/packages/core/src/skills-catalog/acquire/lockfile.ts+++ b/packages/core/src/skills-catalog/acquire/lockfile.ts@@ -10,7 +10,11 @@import { z } from 'zod';import { OK_DIR } from '../../constants/ok-dir.ts';-import { OPENKNOWLEDGE_SKILLS_REPO, PACK_SKILL_PREFIX } from '../../constants/skills.ts';+import {+ OPENKNOWLEDGE_SKILLS_REPO,+ PACK_SKILL_PREFIX,+ RENAMED_PACK_SKILLS,+} from '../../constants/skills.ts';/** Filename of the committed import lockfile under `.ok/`. */export const SKILLS_LOCK_FILENAME = 'skills-lock.json';@@ -92,24 +96,56 @@ export function upsertLockEntry(lock: SkillsLock, name: string, entry: SkillLockreturn { ...lock, skills: { ...lock.skills, [name]: entry } };}+/** The published pack-skill names — the post-rename half of the retrofit gate. */+const RENAMED_PACK_SKILL_NAMES: ReadonlySet<string> = new Set(Object.values(RENAMED_PACK_SKILLS));+/**- * Retrofit provenance for a seeded starter pack that predates lockfile recording.- * A `open-knowledge-pack-*` skill installed before provenance existed has no lock- * entry, but every pack ships from OPENKNOWLEDGE_SKILLS_REPO — a deterministic- * upstream — so synthesize the entry from the installed `contentHash` and let it- * update through the normal reimport path. An unchanged upstream is then a correct- * no-op (installed hash === acquired hash). Returns null for any non-pack name.+ * Retrofit provenance for a seeded starter pack whose lock entry is missing.+ * A pack skill with no lock entry cannot update, but every pack ships from+ * OPENKNOWLEDGE_SKILLS_REPO — a deterministic upstream — so synthesize the entry+ * from the installed `contentHash` and let it update through the normal reimport+ * path. An unchanged upstream is then a correct no-op (installed hash ===+ * acquired hash).+ *+ * Accepts BOTH naming eras. Gating on the old prefix alone was right only while+ * every pack skill carried it; post-rename a fresh install is short-named, and a+ * short-named install that loses its lock entry — best-effort provenance write+ * failed, or a teammate cloned `.claude/skills/` without the gitignored lock —+ * had no way back and answered Update with a flat "no recorded import source".+ * Returns null for any name that is not a pack skill.*/export function retrofitPackLockEntry(name: string,installedContentHash: string,importedAt: string,+ opts?: {+ /**+ * Does the installed bundle carry this pack's `metadata.pack` marker? Only+ * consulted for the post-rename short names, which are generic enough that a+ * user may own one; the old prefixed names need no witness.+ */+ selfIdentifiesAsPack?: boolean;+ },): SkillLockEntry | null {- if (!name.startsWith(PACK_SKILL_PREFIX)) return null;+ if (name.startsWith(PACK_SKILL_PREFIX)) {+ // Namespaced: nobody else's skill can hold this name, so presence is proof.+ return packEntry(name, installedContentHash, importedAt);+ }+ // A published short name like `write-a-spec` or `knowledge-base` is generic —+ // a user can easily have authored their own. Presence alone is NOT proof, and+ // synthesizing our provenance onto their skill would offer to overwrite it+ // with ours on the next Update. Require the bundle to self-identify as this+ // pack's, the same witness `classifyPresentPackSkill` uses before treating a+ // present skill as ours.+ if (!RENAMED_PACK_SKILL_NAMES.has(name) || opts?.selfIdentifiesAsPack !== true) return null;+ return packEntry(name, installedContentHash, importedAt);+}++function packEntry(name: string, contentHash: string, importedAt: string): SkillLockEntry {return {source: OPENKNOWLEDGE_SKILLS_REPO,skill: name,- contentHash: installedContentHash,+ contentHash,importedAt,};}diff --git a/packages/desktop/src/main/index.ts b/packages/desktop/src/main/index.tsindex 2b1ec4a32..7c99fe1e4 100644--- a/packages/desktop/src/main/index.ts+++ b/packages/desktop/src/main/index.ts@@ -75,7 +75,9 @@ import {import {CLIENT_VERSION_HEADER,hasUninstallFeedbackContent,+ OPENKNOWLEDGE_SKILLS_REPO,PROTOCOL_VERSION,+ projectSkillDecisionKey,ServerInfoSuccessSchema,SPAWN_ERROR_LOG,TERMINAL_CLIS,@@ -105,8 +107,10 @@ import {readServerLock,readServerPackageVersion,recordSkillInstallEvent,+ reportSkillInstall,resolveBundledSkillDir,resolveLockDir,+ resolveSkillInstallReportSettings,runAuthStatusSubprocess,trustSystemCertificates,USER_GLOBAL_BUNDLE_IDS,@@ -2082,6 +2086,21 @@ async function openProject(// checkDesktop:false — the desktop resolves its own bundled assets.deps: {resolveBundledSkillDir: () => resolveBundledSkillDir('project', { checkDesktop: false }),+ readProjectSkillDecision: (dir) =>+ readBundleDecision(osHomedir(), projectSkillDecisionKey(dir)),+ // Opening a wired project without the project skill CREATES it — the+ // desktop's most common real install, and previously uncounted.+ reportInstalled: (skillNames, scope) => {+ const home = osHomedir();+ void reportSkillInstall(+ {+ source: OPENKNOWLEDGE_SKILLS_REPO,+ skills: skillNames,+ ...(scope === undefined ? {} : { scope }),+ },+ { home, enabled: resolveSkillInstallReportSettings(home).enabled },+ );+ },},}).catch((err) => {console.warn('[main] project-skill reclaim failed', {@@ -3652,6 +3671,21 @@ function buildReclaimUserSkillsOpts(): Parameters<typeof reclaimUserSkillsOnLaunwriteTargetVersion(home, target, version, surface),readBundleDecision: (home, name) => readBundleDecision(home, name),writeBundleDecision: (home, name, enabled) => writeBundleDecision(home, name, enabled),+ // Count a genuine seed on skills.sh. Fire-and-forget and honouring the+ // same telemetry setting + DO_NOT_TRACK gate as every other report, so a+ // launch never waits on a third party.+ reportInstalled: (skillNames, scope) => {+ const home = osHomedir();+ void reportSkillInstall(+ {+ source: OPENKNOWLEDGE_SKILLS_REPO,+ skills: skillNames,+ global: true,+ ...(scope === undefined ? {} : { scope }),+ },+ { home, enabled: resolveSkillInstallReportSettings(home).enabled },+ );+ },// `bundleId` originates from `USER_GLOBAL_BUNDLE_IDS`, so the cast to the// CLI's `BundleId` is sound.removeBundleFromDisk: (bundleId) =>@@ -5807,6 +5841,26 @@ function registerProjectIntegrationsSettingsIpc(): void {const skillPath = canonicalSkillTarget.projectSkillPath?.(projectDir);return skillPath !== undefined && existsSync(skillPath);},+ recordProjectSkillDecision: (projectDir, enabled) => {+ void writeBundleDecision(osHomedir(), projectSkillDecisionKey(projectDir), enabled).catch(+ (err: unknown) => {+ console.warn('[main] project-skill decision not recorded', {+ err: err instanceof Error ? err.message : String(err),+ });+ },+ );+ },+ reportProjectSkillInstalled: (projectDir) => {+ const home = osHomedir();+ void reportSkillInstall(+ {+ source: OPENKNOWLEDGE_SKILLS_REPO,+ skills: [BUNDLE_SKILL_NAME.project],+ scope: projectDir,+ },+ { home, enabled: resolveSkillInstallReportSettings(home).enabled },+ );+ },writeProjectSkill: (id, projectDir) => {const result = writeProjectSkill(EDITOR_TARGETS[id], projectDir);return { action: result.action, ...(result.error ? { error: result.error } : {}) };diff --git a/packages/desktop/src/main/project-integrations-settings.test.ts b/packages/desktop/src/main/project-integrations-settings.test.tsindex 55d7b87fe..faccee5a4 100644--- a/packages/desktop/src/main/project-integrations-settings.test.ts+++ b/packages/desktop/src/main/project-integrations-settings.test.ts@@ -46,8 +46,12 @@ function makeCli(overrides: CliOverrides = {}): ProjectIntegrationsCliSurface &removals: McpWiringEditorId[];skillWrites: McpWiringEditorId[];skillRemovals: McpWiringEditorId[];+ decisions: Array<{ dir: string; enabled: boolean }>;+ reports: string[];} {const writes: McpWiringEditorId[] = [];+ const decisions: Array<{ dir: string; enabled: boolean }> = [];+ const reports: string[] = [];const removals: McpWiringEditorId[] = [];const skillWrites: McpWiringEditorId[] = [];const skillRemovals: McpWiringEditorId[] = [];@@ -97,6 +101,14 @@ function makeCli(overrides: CliOverrides = {}): ProjectIntegrationsCliSurface &if (overrides.skillRemoveFails?.includes(id)) return { action: 'failed', error: 'nope' };return { action: 'removed' };},+ recordProjectSkillDecision: (dir, enabled) => {+ decisions.push({ dir, enabled });+ },+ reportProjectSkillInstalled: (dir) => {+ reports.push(dir);+ },+ decisions,+ reports,};}@@ -230,6 +242,38 @@ describe('registerProjectIntegrationsSettings — set', () => {expect(cli.skillWrites).toEqual([]); // never crosses into the install branch});+ // The writing half of the toggle-persistence fix. The reading half (reclaim+ // honouring the decision) is pinned in skill-reclaim.test.ts; without these,+ // dropping the record call silently restores the toggle-is-a-lie bug and only+ // the reclaim test's injected reader hides it.+ test('switching the skill ON records the decision and counts the install', async () => {+ const cli = makeCli();+ const { set } = register(cli);+ const r = await set({ component: { kind: 'skill' }, enabled: true });+ expect(r.ok).toBe(true);+ expect(cli.decisions).toEqual([{ dir: PROJECT, enabled: true }]);+ expect(cli.reports).toEqual([PROJECT]);+ });++ test('switching the skill OFF records the decision and counts nothing', async () => {+ const cli = makeCli();+ const { set } = register(cli);+ const r = await set({ component: { kind: 'skill' }, enabled: false });+ expect(r.ok).toBe(true);+ expect(cli.decisions).toEqual([{ dir: PROJECT, enabled: false }]);+ expect(cli.reports).toEqual([]);+ });++ test('a partial failure still records the choice but counts no install', async () => {+ // The decision is the user's INTENT, so it is recorded either way; the+ // install count must reflect what actually landed.+ const cli = makeCli({ skillWriteFails: ['codex'] as McpWiringEditorId[] });+ const { set } = register(cli);+ await set({ component: { kind: 'skill' }, enabled: true });+ expect(cli.decisions).toEqual([{ dir: PROJECT, enabled: true }]);+ expect(cli.reports).toEqual([]);+ });+test('skill uninstall reports the editors that failed', async () => {const cli = makeCli({ skillRemoveFails: ['codex'] as McpWiringEditorId[] });const { set } = register(cli);diff --git a/packages/desktop/src/main/project-integrations-settings.ts b/packages/desktop/src/main/project-integrations-settings.tsindex de5022337..4155d8566 100644--- a/packages/desktop/src/main/project-integrations-settings.ts+++ b/packages/desktop/src/main/project-integrations-settings.ts@@ -110,6 +110,18 @@ export interface ProjectIntegrationsCliSurface {id: McpWiringEditorId,projectDir: string,): { action: 'removed' | 'not-present' | 'skipped-unsupported' | 'failed'; error?: string };+ /**+ * Persist the user's choice for this project's skill so the project-open+ * reclaim honours it. Without this an OFF is undone on the next open, because+ * `createIfWired` recreates the skill for every wired host that lacks one.+ */+ recordProjectSkillDecision?(projectDir: string, enabled: boolean): void;+ /**+ * Count a genuine install on skills.sh — switching the skill ON for a project+ * installs it into that project's editor dirs. Scoped to the project, so a+ * toggle off-and-on again counts once.+ */+ reportProjectSkillInstalled?(projectDir: string): void;}interface ProjectIntegrationsLogger {@@ -312,6 +324,10 @@ export function registerProjectIntegrationsSettings();}}+ // Record the choice either way, so the project-open reclaim stops+ // resurrecting a skill the user switched off.+ cli.recordProjectSkillDecision?.(projectDir, enabled);+ if (enabled && failures.length === 0) cli.reportProjectSkillInstalled?.(projectDir);if (failures.length > 0) {return {ok: false,diff --git a/packages/desktop/src/main/skill-reclaim.test.ts b/packages/desktop/src/main/skill-reclaim.test.tsindex a8cb0ad1c..97f34f546 100644--- a/packages/desktop/src/main/skill-reclaim.test.ts+++ b/packages/desktop/src/main/skill-reclaim.test.ts@@ -122,6 +122,7 @@ function makeDeps(opts: {const events: CapturedEvent[] = [];const decisionWrites: Array<{ bundleName: string; enabled: boolean }> = [];const removals: string[] = [];+ const reports: Array<{ skills: string[]; scope?: string }> = [];const decisionFor = (bundleName: string): boolean | null => {const d = opts.bundleDecision;if (d === undefined) return true;@@ -158,10 +159,14 @@ function makeDeps(opts: {removeBundleFromDisk: (bundleId) => {removals.push(bundleId);},+ reportInstalled: (skillNames: readonly string[], scope?: string) => {+ reports.push({ skills: [...skillNames], scope });+ },stateWrites,events,decisionWrites,removals,+ reports,};}@@ -594,6 +599,39 @@ describe('reclaimUserSkillsOnLaunch — per-bundle opt-in gate', () => {expect(deps.removals).toEqual(['write-skill']);const installed = deps.events.filter((e) => e.outcome === 'installed').map((e) => e.bundle);expect(installed).toEqual(['discovery']);+ // A DECLINED bundle must never be counted on skills.sh. It is torn off disk+ // and never installed, so reporting it would claim an install the user+ // explicitly refused. Only the enabled bundle that actually landed is sent.+ expect(deps.reports).toEqual([{ skills: ['open-knowledge-discovery'], scope: undefined }]);+ });++ test('a launch that installs nothing new reports nothing', async () => {+ // Steady state: the reclaim is seed-if-absent, so every bundle already on+ // disk reads `skipped-present`. Reporting there would turn an install+ // counter into a launch counter.+ const home = makeHome();+ for (const name of ['open-knowledge-discovery', 'open-knowledge-write-skill']) {+ const dir = join(home, '.agents', 'skills', name);+ mkdirSync(dir, { recursive: true });+ writeFileSync(join(dir, 'SKILL.md'), 'preexisting');+ }+ const deps = {+ ...makeDeps({ bundle: setupBundle(), version: '1.0.0' }),+ userGlobalBundles: [+ { id: 'discovery', name: 'open-knowledge-discovery' },+ { id: 'write-skill', name: 'open-knowledge-write-skill' },+ ],+ };++ await reclaimUserSkillsOnLaunch({+ home,+ isPackaged: true,+ platform: 'darwin',+ executablePath: EXE,+ deps,+ });++ expect(deps.reports).toEqual([]);});});@@ -613,6 +651,89 @@ describe('reclaimProjectSkillsOnProjectOpen', () => {if (r.status === 'skipped') expect(r.reason).toBe('appimage-ephemeral');});+ test('an explicit OFF in Settings is honoured — no resurrection on the next open', async () => {+ // The toggle used to be a lie: switch the project skill off, reopen the+ // project, and `createIfWired` put it back for every wired host.+ const projectDir = mkdtempSync(join(tmpdir(), 'ok-proj-'));+ cleanupPaths.push(projectDir);+ mkdirSync(join(projectDir, '.claude'), { recursive: true });+ writeFileSync(+ join(projectDir, '.mcp.json'),+ JSON.stringify({ mcpServers: { 'open-knowledge': { args: ['# ok-mcp-v2'] } } }),+ );++ const r = await reclaimProjectSkillsOnProjectOpen({+ projectDir,+ executablePath: EXE,+ isPackaged: true,+ platform: 'darwin',+ createIfWired: true,+ deps: {+ resolveBundledSkillDir: () => setupBundle(),+ readProjectSkillDecision: async () => false,+ },+ });++ expect(r.status).toBe('skipped');+ if (r.status === 'skipped') expect(r.reason).toBe('declined-by-user');+ expect(existsSync(join(projectDir, '.claude', 'skills', 'open-knowledge', 'SKILL.md'))).toBe(+ false,+ );+ });++ test('creating the project skill counts one install, scoped to the project', async () => {+ const projectDir = mkdtempSync(join(tmpdir(), 'ok-proj-'));+ cleanupPaths.push(projectDir);+ mkdirSync(join(projectDir, '.claude'), { recursive: true });+ writeFileSync(+ join(projectDir, '.mcp.json'),+ JSON.stringify({ mcpServers: { 'open-knowledge': { args: ['# ok-mcp-v2'] } } }),+ );+ const reports: Array<{ skills: string[]; scope?: string }> = [];++ await reclaimProjectSkillsOnProjectOpen({+ projectDir,+ executablePath: EXE,+ isPackaged: true,+ platform: 'darwin',+ createIfWired: true,+ deps: {+ resolveBundledSkillDir: () => setupBundle(),+ reportInstalled: (skills, scope) => reports.push({ skills: [...skills], scope }),+ },+ });++ expect(reports).toEqual([{ skills: ['open-knowledge'], scope: projectDir }]);+ });++ test('reopening a project that already has the skill counts nothing', async () => {+ // The steady state. Counting here would make every project open an install.+ const projectDir = mkdtempSync(join(tmpdir(), 'ok-proj-'));+ cleanupPaths.push(projectDir);+ const dest = join(projectDir, '.claude', 'skills', 'open-knowledge');+ mkdirSync(dest, { recursive: true });+ writeFileSync(join(dest, 'SKILL.md'), 'already here');+ writeFileSync(+ join(projectDir, '.mcp.json'),+ JSON.stringify({ mcpServers: { 'open-knowledge': { args: ['# ok-mcp-v2'] } } }),+ );+ const reports: Array<{ skills: string[]; scope?: string }> = [];++ await reclaimProjectSkillsOnProjectOpen({+ projectDir,+ executablePath: EXE,+ isPackaged: true,+ platform: 'darwin',+ createIfWired: true,+ deps: {+ resolveBundledSkillDir: () => setupBundle(),+ reportInstalled: (skills, scope) => reports.push({ skills: [...skills], scope }),+ },+ });++ expect(reports).toEqual([]);+ });+test('no SKILL.md on disk → no-token, no creation', async () => {const projectDir = mkdtempSync(join(tmpdir(), 'ok-proj-'));cleanupPaths.push(projectDir);diff --git a/packages/desktop/src/main/skill-reclaim.ts b/packages/desktop/src/main/skill-reclaim.tsindex df38f13e1..cd4eec5fb 100644--- a/packages/desktop/src/main/skill-reclaim.ts+++ b/packages/desktop/src/main/skill-reclaim.ts@@ -270,6 +270,14 @@ interface ReclaimUserSkillsOpts {/** Remove a declined bundle's dirs from disk (CLI* `removeUserGlobalSkillBundle`). Keyed by bundle id. */removeBundleFromDisk(bundleId: string): void;+ /**+ * Count a genuine install on skills.sh (server `reportSkillInstall` ++ * `resolveSkillInstallReportSettings`, wired by the caller so this module+ * stays free of server imports). Called ONLY for bundles this pass actually+ * wrote: the reclaim is seed-if-absent, so `skipped-present` is not an+ * install and must not be reported. Optional — omitted in tests.+ */+ reportInstalled?(skillNames: readonly string[], scope?: string): void;writeTargetVersion(home: string,target: 'cli-hosts',@@ -544,11 +552,26 @@ export async function reclaimUserSkillsOnLaunch(// Seed each enabled user-global bundle (discovery + write-skill) into the// central store + per-host dirs (if-absent), each under its own name.const entries: UserSkillReclaimEntry[] = [];+ // Bundles this pass actually WROTE. The reclaim is seed-if-absent, so on+ // every launch after the first each bundle reads `skipped-present` — that is+ // not an install and reporting it would turn an install counter into a launch+ // counter. Collected per bundle because the entry rows do not carry a name.+ const installedBundleNames: string[] = [];for (const bundle of gatedBundles) {- entries.push(- ...installUserBundleToHostDirs(home, bundle.name, bundle.sourceDir, fs, logger, version),+ const bundleEntries = installUserBundleToHostDirs(+ home,+ bundle.name,+ bundle.sourceDir,+ fs,+ logger,+ version,);+ if (bundleEntries.some((e) => e.status === 'written')) installedBundleNames.push(bundle.name);+ entries.push(...bundleEntries);}+ // Machine-scoped, matching the CLI's user-global install: these bundles live+ // once per machine, so a second project must not re-count them.+ if (installedBundleNames.length > 0) deps.reportInstalled?.(installedBundleNames);const anyWriteSucceeded = entries.some((e) => e.status === 'written');const anyFailed = entries.some((e) => e.status === 'failed');@@ -637,6 +660,21 @@ interface ReclaimProjectSkillsOpts {createIfWired?: boolean;deps: {resolveBundledSkillDir(): string;+ /**+ * Count a genuine install on skills.sh. Called only for hosts this pass+ * CREATED the project skill for — opening a project that already has it is+ * not an install. Scoped to the project so a second project counts and+ * reopening the same one does not. Optional — omitted in tests.+ */+ reportInstalled?(skillNames: readonly string[], scope?: string): void;+ /**+ * The user's recorded choice for THIS project's skill: `false` when they+ * switched it off in Settings, `true` when they switched it on, `null` when+ * they never said. Only an explicit `false` suppresses creation — `null`+ * still heals the pre-writer cohort, which is what `createIfWired` is for.+ * Optional — omitted in tests (reads as "no recorded decision").+ */+ readProjectSkillDecision?(projectDir: string): Promise<boolean | null>;};fs?: SkillFsOps;logger?: SkillReclaimLogger;@@ -713,6 +751,17 @@ export async function reclaimProjectSkillsOnProjectOpen(return { status: 'skipped', reason: 'bundle-missing' };}+ // An explicit OFF in Settings outranks `createIfWired`. Without this the+ // toggle is a lie: the user switches the project skill off, and the very next+ // open recreates it for every wired host. `null` (never asked) still heals the+ // cohort onboarded before the project-skill writer existed.+ const skillDecision =+ (await deps.readProjectSkillDecision?.(projectDir).catch(() => null)) ?? null;+ if (skillDecision === false) {+ logger.event({ event: 'project-skill-reclaim-declined-by-user', projectDir });+ return { status: 'skipped', reason: 'declined-by-user' };+ }+const entries: ProjectSkillReclaimEntry[] = [];for (const host of HOSTS_WITH_USER_SKILL_DIR) {const dest = join(projectDir, host.hostDir, 'skills', PROJECT_SKILL_DIR_NAME);@@ -782,5 +831,14 @@ export async function reclaimProjectSkillsOnProjectOpen(}}+ // Opening a wired project that has no project skill CREATES it — a real+ // install of a skill we publish, and the case that made desktop counts look+ // flat. Only `created` counts: a project that already had the skill is+ // reopened constantly and reports nothing. Scoped to the project so a second+ // project counts and reopening the same one does not.+ if (entries.some((e) => e.status === 'created')) {+ deps.reportInstalled?.([PROJECT_SKILL_DIR_NAME], projectDir);+ }+return { status: 'done', entries };}diff --git a/packages/server/assets/skills/discovery/SKILL.md b/packages/server/assets/skills/discovery/SKILL.mdindex f9a5bd55c..ac2d6c33f 100644--- a/packages/server/assets/skills/discovery/SKILL.md+++ b/packages/server/assets/skills/discovery/SKILL.md@@ -4,7 +4,7 @@ description: "Read when the user asks what OpenKnowledge is, wants to install itcompatibility: "Any agent host — no MCP server required. Pure discovery + install guidance."metadata:author: "Inkeep"- repository: "https://github.com/inkeep/open-knowledge"+ repository: "https://github.com/inkeep/open-knowledge-skills"---# OpenKnowledge — what it is and how to install itdiff --git a/packages/server/assets/skills/packs/codebase-wiki/SKILL.md b/packages/server/assets/skills/packs/codebase-wiki/SKILL.mdindex e26ea8e3d..ff6b235a3 100644--- a/packages/server/assets/skills/packs/codebase-wiki/SKILL.md+++ b/packages/server/assets/skills/packs/codebase-wiki/SKILL.md@@ -1,11 +1,11 @@----name: open-knowledge-pack-codebase-wiki+name: codebase-wikidescription: "How to work in a Codebase Wiki project (the `codebase-wiki` starter pack): an agent-authored, source-grounded wiki of the surrounding codebase. Read when the project has a `wiki/` knowledge base with `architecture/`, `modules/`, `flows/`, `concepts/`, and `guides/` sections plus `wiki/OVERVIEW.md`, or when asked to generate or refresh a wiki of this codebase. Carries the per-folder rules and freshness + log discipline, summarizes the audience/depth knobs and source-reference convention, and bundles the full generate/refresh procedure in `references/`. Complements the platform `open-knowledge` skill; does not replace it."compatibility: "Claude Code, Claude Desktop, Claude Cowork, Claude.ai web. Requires OpenKnowledge MCP server. Installed project-local by `ok seed --pack codebase-wiki`."metadata:pack: "codebase-wiki"author: "Inkeep"- repository: "https://github.com/inkeep/open-knowledge"+ repository: "https://github.com/inkeep/open-knowledge-skills"---# Codebase Wiki pack — how to work herediff --git a/packages/server/assets/skills/packs/entity-vault/SKILL.md b/packages/server/assets/skills/packs/entity-vault/SKILL.mdindex c5608f269..ffd9ecb10 100644--- a/packages/server/assets/skills/packs/entity-vault/SKILL.md+++ b/packages/server/assets/skills/packs/entity-vault/SKILL.md@@ -1,11 +1,11 @@----name: open-knowledge-pack-entity-vault+name: personal-crmdescription: "How to work in a Personal CRM project (the `entity-vault` starter pack, GBrain-compatible): a typed-entity vault of people, companies, meetings, and concepts, each a dossier with a rewritable summary plus an append-only timeline. Read when the project has these folders, OR when asked to capture notes about a person or company, log a meeting, prep for an upcoming meeting, or answer who someone is and what was last said. Carries the dossier convention and entity-extraction behaviors so that guidance does not live inside template bodies or folder descriptions. Complements the platform `open-knowledge` skill; does not replace it."compatibility: "Claude Code, Claude Desktop, Claude Cowork, Claude.ai web. Requires OpenKnowledge MCP server. Installed project-local by `ok seed --pack entity-vault`."metadata:pack: "entity-vault"author: "Inkeep"- repository: "https://github.com/inkeep/open-knowledge"+ repository: "https://github.com/inkeep/open-knowledge-skills"---# Personal CRM (GBrain-compatible) — how to work herediff --git a/packages/server/assets/skills/packs/knowledge-base/SKILL.md b/packages/server/assets/skills/packs/knowledge-base/SKILL.mdindex 04e151365..c1cf86637 100644--- a/packages/server/assets/skills/packs/knowledge-base/SKILL.md+++ b/packages/server/assets/skills/packs/knowledge-base/SKILL.md@@ -1,11 +1,11 @@----name: open-knowledge-pack-knowledge-base+name: knowledge-basedescription: "How to work in a Knowledge Base project (the `knowledge-base` starter pack). Read when the project has the three-layer source-grounded layout — `external-sources/` → `research/` → `articles/` — or when asked how this project is organized. Carries the layer model, per-folder rules, status flows, and log discipline so this guidance does NOT live inside template bodies or log.md. The three procedures live elsewhere: ingest in the platform `open-knowledge` skill, research and consolidate as their own sibling skills in this pack. Complements the platform `open-knowledge` skill; does not replace it."compatibility: "Claude Code, Claude Desktop, Claude Cowork, Claude.ai web. Requires OpenKnowledge MCP server. Installed project-local by `ok seed --pack knowledge-base`."metadata:pack: "knowledge-base"author: "Inkeep"- repository: "https://github.com/inkeep/open-knowledge"+ repository: "https://github.com/inkeep/open-knowledge-skills"---# Knowledge Base pack — how to work here@@ -38,8 +38,8 @@ Each layer has a full, STOP-gated procedure, and each ships as its own skill so| Procedure | Where it lives | When || --- | --- | --- || ingest | Platform `open-knowledge` skill (`references/ingest-and-sources.md`) — its Grounding rule depends on it everywhere, so it ships with every project, not just this pack. | Preserve a shared URL / PDF / file verbatim, OR you fetched a URL to ground a KB claim (binary sources preserved, not scraped). |-| research | Sibling skill `open-knowledge-pack-knowledge-base-research` | Investigate / compare / synthesize multiple sources → `status: provisional` article + `sources:`. |-| consolidate | Sibling skill `open-knowledge-pack-knowledge-base-consolidate` | A decision was actually made → commit canonical source-of-truth with a `supersedes:` chain. |+| research | Sibling skill `research-with-sources` | Investigate / compare / synthesize multiple sources → `status: provisional` article + `sources:`. |+| consolidate | Sibling skill `consolidate-notes` | A decision was actually made → commit canonical source-of-truth with a `supersedes:` chain. |Typical day-2 flow: user shares a URL → **ingest** (preserve) → user asks "now research this" → **research** (provisional article, ingesting more sources as needed) → decision lands → **consolidate** (canonical article, supersedes the research).@@ -51,9 +51,9 @@ Typical day-2 flow: user shares a URL → **ingest** (preserve) → user asks "n**`external-sources/`** — Raw sources saved verbatim, not just cited: the actual fetched text of URLs, extracted text of PDFs, copies of referenced files. Each file's frontmatter carries the original URL, access date, and any author/publisher metadata. Produced by the ingest procedure (applies whether the user shared the URL or you fetched it yourself to ground a claim). Immutable after capture — update only to refresh a stale fetch. **No analysis here**; that belongs in `research/`.-**`research/`** — Provisional analysis synthesizing external sources. Produced by the `research` skill. Every factual claim cites a specific doc in `external-sources/` (or an inline URL if ingest was skipped); no unsourced assertions. Keep the `sources:` frontmatter list aligned with the docs actually linked in the body. Promote to `articles/` via the `consolidate` skill once the team decides the findings are stable.+**`research/`** — Provisional analysis synthesizing external sources. Produced by the `research-with-sources` skill. Every factual claim cites a specific doc in `external-sources/` (or an inline URL if ingest was skipped); no unsourced assertions. Keep the `sources:` frontmatter list aligned with the docs actually linked in the body. Promote to `articles/` via the `consolidate-notes` skill once the team decides the findings are stable.-**`articles/`** — Canonical knowledge, committed after a team decision. Produced by the `consolidate` skill. Carries a `supersedes:` chain tying back to the `research/` docs it replaces (which in turn cite `external-sources/`) so the full evidence chain is traceable without leaving the repo. Source-of-truth for the domain; update only when a new decision supersedes it.+**`articles/`** — Canonical knowledge, committed after a team decision. Produced by the `consolidate-notes` skill. Carries a `supersedes:` chain tying back to the `research/` docs it replaces (which in turn cite `external-sources/`) so the full evidence chain is traceable without leaving the repo. Source-of-truth for the domain; update only when a new decision supersedes it.## Status flowdiff --git a/packages/server/assets/skills/packs/knowledge-base/consolidate/SKILL.md b/packages/server/assets/skills/packs/knowledge-base/consolidate/SKILL.mdindex 7fe98dc51..9d909f2f0 100644--- a/packages/server/assets/skills/packs/knowledge-base/consolidate/SKILL.md+++ b/packages/server/assets/skills/packs/knowledge-base/consolidate/SKILL.md@@ -1,11 +1,11 @@----name: open-knowledge-pack-knowledge-base-consolidate-description: "Promote existing research into a canonical article under `articles/` in a Knowledge Base project (the `knowledge-base` starter pack). Read when a decision has actually been made and the team wants the source-of-truth written down, or when asked to consolidate, canonicalize, promote research, or supersede an older article. Carries the decision-confirmation gate, the `supersedes:` chain that keeps the evidence trail intact, and the canonical voice. Does not conduct new research — that is the sibling `research` skill."+name: consolidate-notes+description: "Promote existing research into a canonical article under `articles/` in a Knowledge Base project (the `knowledge-base` starter pack). Read when a decision has actually been made and the team wants the source-of-truth written down, or when asked to consolidate, canonicalize, promote research, or supersede an older article. Carries the decision-confirmation gate, the `supersedes:` chain that keeps the evidence trail intact, and the canonical voice. Does not conduct new research — that is the sibling `research-with-sources` skill."compatibility: "Claude Code, Claude Desktop, Claude Cowork, Claude.ai web. Requires OpenKnowledge MCP server. Installed project-local by `ok seed --pack knowledge-base`."metadata:pack: "knowledge-base"author: "Inkeep"- repository: "https://github.com/inkeep/open-knowledge"+ repository: "https://github.com/inkeep/open-knowledge-skills"---# Consolidate — promote research into a canonical article@@ -58,7 +58,7 @@ Locate research articles on this topic:- Follow its `sources:` frontmatter list — read every referenced source file- Also read any existing canonical article on the topic — if one already exists, you may be **updating** it rather than creating a new one-If there is no research to consolidate, stop. Consolidation is promotion, not creation. Do the `research` skill first.+If there is no research to consolidate, stop. Consolidation is promotion, not creation. Do the `research-with-sources` skill first.### 2. Re-confirm the decisiondiff --git a/packages/server/assets/skills/packs/knowledge-base/research/SKILL.md b/packages/server/assets/skills/packs/knowledge-base/research/SKILL.mdindex 74ea0c43b..3fc67eb43 100644--- a/packages/server/assets/skills/packs/knowledge-base/research/SKILL.md+++ b/packages/server/assets/skills/packs/knowledge-base/research/SKILL.md@@ -1,17 +1,17 @@----name: open-knowledge-pack-knowledge-base-research-description: "Investigate a topic against preserved sources and write a provisional research article under `research/` in a Knowledge Base project (the `knowledge-base` starter pack). Read when asked to research a topic, compare options, synthesize sources, gather evidence, or extend an existing research doc. Carries the full procedure: scan existing coverage, agree a research rubric, capture every source verbatim before analyzing, write the article incrementally so a crash never loses work, cite every claim, and link it back into the graph. Does not promote findings to canonical knowledge — that is the sibling `consolidate` skill, after a decision lands."+name: research-with-sources+description: "Investigate a topic against preserved sources and write a provisional research article under `research/` in a Knowledge Base project (the `knowledge-base` starter pack). Read when asked to research a topic, compare options, synthesize sources, gather evidence, or extend an existing research doc. Carries the full procedure: scan existing coverage, agree a research rubric, capture every source verbatim before analyzing, write the article incrementally so a crash never loses work, cite every claim, and link it back into the graph. Does not promote findings to canonical knowledge — that is the sibling `consolidate-notes` skill, after a decision lands."compatibility: "Claude Code, Claude Desktop, Claude Cowork, Claude.ai web. Requires OpenKnowledge MCP server. Installed project-local by `ok seed --pack knowledge-base`."metadata:pack: "knowledge-base"author: "Inkeep"- repository: "https://github.com/inkeep/open-knowledge"+ repository: "https://github.com/inkeep/open-knowledge-skills"---# Research — gather sources and write provisional findings> This skill is pack guidance. The platform `open-knowledge` skill (read/write/preview/linking/grounding rules) still governs every markdown operation — this layers the procedure on top.-Conduct **evidence-driven research** on a topic and produce a provisional research article under `research/`. Provisional, not canonical: research articles capture findings, trade-offs, and open questions at a point in time. They are promoted to canonical articles via the `consolidate` skill only when decisions solidify.+Conduct **evidence-driven research** on a topic and produce a provisional research article under `research/`. Provisional, not canonical: research articles capture findings, trade-offs, and open questions at a point in time. They are promoted to canonical articles via the `consolidate-notes` skill only when decisions solidify.The content directory is the resolved `content.dir` — read it with `config({ key: 'content.dir' })` if you don't already know it. Paths below are relative to it.@@ -296,7 +296,7 @@ sources:### Voice- **Provisional, not canonical.** Use "tentative", "initial findings", "based on current understanding."-- **Do NOT write as if it were canonical** — that's misleading. Canonicality is the `consolidate` skill's job, after decisions land.+- **Do NOT write as if it were canonical** — that's misleading. Canonicality is the `consolidate-notes` skill's job, after decisions land.- **Explicit about uncertainty.** Research is the layer where uncertainty is allowed to live.---@@ -366,7 +366,7 @@ In headless mode, write the recap into the research article's "Further reading"## Non-goals-- **Don't promote to a canonical article.** That's the `consolidate` skill's job after a decision actually lands. Premature canonicalization buries uncertainty and misleads future readers.+- **Don't promote to a canonical article.** That's the `consolidate-notes` skill's job after a decision actually lands. Premature canonicalization buries uncertainty and misleads future readers.- **Don't hide uncertainty.** Research is the layer where "we don't know yet" is acceptable prose. Say it explicitly.- **Don't skip ingest.** Always capture raw sources first, then analyze. An article without preserved sources is opinion.- **Don't skip the Step 1 scan.** Duplicate research wastes the user's time AND misses chances to extend prior work.diff --git a/packages/server/assets/skills/packs/okf/SKILL.md b/packages/server/assets/skills/packs/okf/SKILL.mdindex 0b121f546..f9da8245c 100644--- a/packages/server/assets/skills/packs/okf/SKILL.md+++ b/packages/server/assets/skills/packs/okf/SKILL.md@@ -1,5 +1,5 @@----name: open-knowledge-pack-okf+name: okf-knowledge-basedescription: "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 plus reserved files, OR when asked whether a document is OKF-conformant, or to add a document to an OKF knowledge base. 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 OpenKnowledge MCP server. Installed project-local by `ok seed --pack okf`."# `type` keeps this skill doc OKF-conformant: it installs as project-local@@ -10,7 +10,7 @@ type: Documentmetadata:pack: "okf"author: "Inkeep"- repository: "https://github.com/inkeep/open-knowledge"+ repository: "https://github.com/inkeep/open-knowledge-skills"---# OKF starter pack — how to work herediff --git a/packages/server/assets/skills/packs/plain-notes/SKILL.md b/packages/server/assets/skills/packs/plain-notes/SKILL.mdindex 9c1ff8103..121e1a878 100644--- a/packages/server/assets/skills/packs/plain-notes/SKILL.md+++ b/packages/server/assets/skills/packs/plain-notes/SKILL.md@@ -1,11 +1,11 @@----name: open-knowledge-pack-plain-notes+name: note-takingdescription: "How to work in a Plain Notes project (the `plain-notes` starter pack): a flat notes/ folder plus a daily/ journal. The 'I just want to write' layout. Read when the project has these folders, OR when asked to jot a note, capture a quick thought, or write today's journal entry. Carries the linking habit and daily-entry behavior so templates and folder descriptions stay minimal. Complements the platform `open-knowledge` skill; does not replace it."compatibility: "Claude Code, Claude Desktop, Claude Cowork, Claude.ai web. Requires OpenKnowledge MCP server. Installed project-local by `ok seed --pack plain-notes`."metadata:pack: "plain-notes"author: "Inkeep"- repository: "https://github.com/inkeep/open-knowledge"+ repository: "https://github.com/inkeep/open-knowledge-skills"---# Plain Notes pack — how to work herediff --git a/packages/server/assets/skills/packs/software-lifecycle/SKILL.md b/packages/server/assets/skills/packs/software-lifecycle/SKILL.mdindex 3b6742d1e..653ba4860 100644--- a/packages/server/assets/skills/packs/software-lifecycle/SKILL.md+++ b/packages/server/assets/skills/packs/software-lifecycle/SKILL.md@@ -1,11 +1,11 @@----name: open-knowledge-pack-software-lifecycle+name: software-lifecycledescription: "How to work in a Software Lifecycle project (the `software-lifecycle` starter pack): proposals → decisions → specs → postmortems, plus guides. Read when the project has these folders, or when asked how this project is organized. Carries the doc lifecycle, status flows, and per-folder agent behaviors so that guidance does not live inside template bodies or folder descriptions. The five workflows — frame a proposal, write a spec, record a decision, write a postmortem, review a design — each ship as their own sibling skill in this pack. Complements the platform `open-knowledge` skill; does not replace it."compatibility: "Claude Code, Claude Desktop, Claude Cowork, Claude.ai web. Requires OpenKnowledge MCP server. Installed project-local by `ok seed --pack software-lifecycle`."metadata:pack: "software-lifecycle"author: "Inkeep"- repository: "https://github.com/inkeep/open-knowledge"+ repository: "https://github.com/inkeep/open-knowledge-skills"---# Software Lifecycle pack — how to work here@@ -44,11 +44,11 @@ Authoring in this project is procedural, not conventional. Each workflow ships a| Workflow | Sibling skill | When || --- | --- | --- |-| Frame a proposal | `open-knowledge-pack-software-lifecycle-frame-a-proposal` | A change needs designing and arguing before anyone builds it. |-| Write a spec | `open-knowledge-pack-software-lifecycle-write-a-spec` | An accepted proposal needs scoping into an implementable spec. |-| Record a decision | `open-knowledge-pack-software-lifecycle-record-a-decision` | A decision was actually made and needs its context and consequences preserved. |-| Write a postmortem | `open-knowledge-pack-software-lifecycle-write-a-postmortem` | An incident happened and the team needs a blameless write-up. |-| Review a design | `open-knowledge-pack-software-lifecycle-review-a-design` | An existing proposal, spec, or decision needs pressure-testing for soundness. |+| Frame a proposal | `frame-a-proposal` | A change needs designing and arguing before anyone builds it. |+| Write a spec | `write-a-spec` | An accepted proposal needs scoping into an implementable spec. |+| Record a decision | `record-a-decision` | A decision was actually made and needs its context and consequences preserved. |+| Write a postmortem | `write-a-postmortem` | An incident happened and the team needs a blameless write-up. |+| Review a design | `review-a-design` | An existing proposal, spec, or decision needs pressure-testing for soundness. |## Templatesdiff --git a/packages/server/assets/skills/packs/software-lifecycle/frame-a-proposal/SKILL.md b/packages/server/assets/skills/packs/software-lifecycle/frame-a-proposal/SKILL.mdindex 899ce6cff..2490b36c8 100644--- a/packages/server/assets/skills/packs/software-lifecycle/frame-a-proposal/SKILL.md+++ b/packages/server/assets/skills/packs/software-lifecycle/frame-a-proposal/SKILL.md@@ -1,11 +1,11 @@----name: open-knowledge-pack-software-lifecycle-frame-a-proposal+name: frame-a-proposaldescription: "Frame a new design proposal (RFC-shape) under proposals/ — problem before solution, named beneficiary and observable change, real alternatives, honest drawbacks, and a live open-questions backlog. Read when asked to frame a proposal, write an RFC, propose a design, pitch a change, draft a PRD-style design doc, or open a design proposal for review. Do NOT read to record a decision after it is accepted (use record-a-decision), to write an implementation spec (use write-a-spec), to write a postmortem (use write-a-postmortem), or to review or critique an existing design (use review-a-design)."compatibility: "Claude Code, Claude Desktop, Claude Cowork, Claude.ai web. Requires OpenKnowledge MCP server. Installed project-local by `ok seed --pack software-lifecycle`."metadata:pack: "software-lifecycle"author: "Inkeep"- repository: "https://github.com/inkeep/open-knowledge"+ repository: "https://github.com/inkeep/open-knowledge-skills"---# Frame a proposal — turn a problem into a reviewable RFCdiff --git a/packages/server/assets/skills/packs/software-lifecycle/record-a-decision/SKILL.md b/packages/server/assets/skills/packs/software-lifecycle/record-a-decision/SKILL.mdindex 4d8eec15b..491fd492f 100644--- a/packages/server/assets/skills/packs/software-lifecycle/record-a-decision/SKILL.md+++ b/packages/server/assets/skills/packs/software-lifecycle/record-a-decision/SKILL.md@@ -1,11 +1,11 @@----name: open-knowledge-pack-software-lifecycle-record-a-decision+name: record-a-decisiondescription: "Records an architecture decision as a Nygard/MADR-shaped ADR under decisions/ — capturing the context that forced the choice, the options weighed, the decision itself, and its consequences in both directions, plus the supersedes chain that keeps a decision log honest. Read when asked to record an architecture decision, write an ADR, log the decision we made, document why we chose X over Y, capture this decision for the record, or supersede an old decision with a new one. Do NOT read to frame a proposal or explore an idea not yet decided (frame-a-proposal), to write a spec or implementation plan (write-a-spec), to write an incident postmortem (write-a-postmortem), or to judge whether a design is sound (review-a-design). This skill records a decision already made; it does not make one."compatibility: "Claude Code, Claude Desktop, Claude Cowork, Claude.ai web. Requires OpenKnowledge MCP server. Installed project-local by `ok seed --pack software-lifecycle`."metadata:pack: "software-lifecycle"author: "Inkeep"- repository: "https://github.com/inkeep/open-knowledge"+ repository: "https://github.com/inkeep/open-knowledge-skills"---# Record a decision — write an ADR under `decisions/`diff --git a/packages/server/assets/skills/packs/software-lifecycle/review-a-design/SKILL.md b/packages/server/assets/skills/packs/software-lifecycle/review-a-design/SKILL.mdindex 60cbce18b..ede2a2e10 100644--- a/packages/server/assets/skills/packs/software-lifecycle/review-a-design/SKILL.md+++ b/packages/server/assets/skills/packs/software-lifecycle/review-a-design/SKILL.md@@ -1,11 +1,11 @@----name: open-knowledge-pack-software-lifecycle-review-a-design+name: review-a-designdescription: "Reviews whether a design is SOUND — solving the right problem, derived from its stated goals and constraints — and emits ranked, evidence-backed findings, not edits. Read when asked to 'review this design', 'is this design sound', 'pressure-test this proposal', 'do a design review', 'does this solve the right problem', 'poke holes in this spec', 'should we build this', or to critique a proposal / spec / ADR / architecture or product decision. Do NOT read when the user wants to AUTHOR one of these — routing a new proposal is frame-a-proposal, a spec is write-a-spec, a decision record is record-a-decision, a postmortem is write-a-postmortem. Do NOT read for code review of a diff, or to fact-check individual claims (that is a correctness pass, a different job)."compatibility: "Claude Code, Claude Desktop, Claude Cowork, Claude.ai web. Requires OpenKnowledge MCP server. Installed project-local by `ok seed --pack software-lifecycle`."metadata:pack: "software-lifecycle"author: "Inkeep"- repository: "https://github.com/inkeep/open-knowledge"+ repository: "https://github.com/inkeep/open-knowledge-skills"---# Review a design — is it sound, not just completediff --git a/packages/server/assets/skills/packs/software-lifecycle/write-a-postmortem/SKILL.md b/packages/server/assets/skills/packs/software-lifecycle/write-a-postmortem/SKILL.mdindex 99047f927..985257e65 100644--- a/packages/server/assets/skills/packs/software-lifecycle/write-a-postmortem/SKILL.md+++ b/packages/server/assets/skills/packs/software-lifecycle/write-a-postmortem/SKILL.md@@ -1,11 +1,11 @@----name: open-knowledge-pack-software-lifecycle-write-a-postmortem+name: write-a-postmortemdescription: "Write a blameless incident postmortem under postmortems/ following the Google SRE shape — evidence-based timeline, trigger vs root cause vs symptom, contributing factors, what went well, and owned+dated+verifiable action items. Read when asked to write a postmortem, do an incident review, run a root cause analysis, write up the outage, retro on the outage, or when the user says we had an incident and wants it documented. Do NOT read to frame a proposal (use frame-a-proposal), write a spec (use write-a-spec), record a decision (use record-a-decision), or review a design (use review-a-design) — a postmortem documents an incident that already happened, it does not propose, specify, decide, or critique future work."compatibility: "Claude Code, Claude Desktop, Claude Cowork, Claude.ai web. Requires OpenKnowledge MCP server. Installed project-local by `ok seed --pack software-lifecycle`."metadata:pack: "software-lifecycle"author: "Inkeep"- repository: "https://github.com/inkeep/open-knowledge"+ repository: "https://github.com/inkeep/open-knowledge-skills"---# Write a postmortemdiff --git a/packages/server/assets/skills/packs/software-lifecycle/write-a-spec/SKILL.md b/packages/server/assets/skills/packs/software-lifecycle/write-a-spec/SKILL.mdindex dc82dec9a..5304b9ca7 100644--- a/packages/server/assets/skills/packs/software-lifecycle/write-a-spec/SKILL.md+++ b/packages/server/assets/skills/packs/software-lifecycle/write-a-spec/SKILL.md@@ -1,11 +1,11 @@----name: open-knowledge-pack-software-lifecycle-write-a-spec+name: write-a-specdescription: "Scope a feature end to end and write an implementation spec under specs/ from an accepted proposal — current-system mapping, goals/non-goals, a Decision Log for one-way-door choices, a live Open Questions backlog, and a real migration + test plan. Read when asked to write a spec, scope this feature, turn this proposal into a spec, plan the implementation, or break this into tasks. Do NOT fire on frame a proposal or write the PRD (sibling frame-a-proposal — a PRD frames a change before it is accepted; this skill starts once one is), record a decision or write the ADR (record-a-decision), write a postmortem (write-a-postmortem), or review this design (review-a-design) — those are separate skills. Complements the platform open-knowledge skill; does not replace it."compatibility: "Claude Code, Claude Desktop, Claude Cowork, Claude.ai web. Requires OpenKnowledge MCP server. Installed project-local by `ok seed --pack software-lifecycle`."metadata:pack: "software-lifecycle"author: "Inkeep"- repository: "https://github.com/inkeep/open-knowledge"+ repository: "https://github.com/inkeep/open-knowledge-skills"---# Write a spec — scope a feature and commit an implementation specdiff --git a/packages/server/assets/skills/packs/worldbuilding/SKILL.md b/packages/server/assets/skills/packs/worldbuilding/SKILL.mdindex e8e9b060d..926133c27 100644--- a/packages/server/assets/skills/packs/worldbuilding/SKILL.md+++ b/packages/server/assets/skills/packs/worldbuilding/SKILL.md@@ -1,11 +1,11 @@----name: open-knowledge-pack-worldbuilding+name: worldbuildingdescription: "How to work in a Worldbuilding project (the `worldbuilding` starter pack): a fiction encyclopedia of characters, settings, themes, factions, and lore. Read when the project has these folders, OR when asked to add a character, setting, faction, or piece of lore, or to check the world for internal consistency. Carries the auto-stub and consistency behaviors so that guidance does not live inside template bodies or folder descriptions. Complements the platform `open-knowledge` skill; does not replace it."compatibility: "Claude Code, Claude Desktop, Claude Cowork, Claude.ai web. Requires OpenKnowledge MCP server. Installed project-local by `ok seed --pack worldbuilding`."metadata:pack: "worldbuilding"author: "Inkeep"- repository: "https://github.com/inkeep/open-knowledge"+ repository: "https://github.com/inkeep/open-knowledge-skills"---# Worldbuilding pack — how to work herediff --git a/packages/server/assets/skills/packs/writing-pipeline/SKILL.md b/packages/server/assets/skills/packs/writing-pipeline/SKILL.mdindex 018a0dc52..17fc0fcf5 100644--- a/packages/server/assets/skills/packs/writing-pipeline/SKILL.md+++ b/packages/server/assets/skills/packs/writing-pipeline/SKILL.md@@ -1,11 +1,11 @@----name: open-knowledge-pack-writing-pipeline+name: writing-workflowdescription: "How to work in a Writing Pipeline project (the `writing-pipeline` starter pack): a three-stage drafting flow, ideas → drafts → published. Read when the project has these folders, OR when asked to capture an idea, start or revise a draft, review a piece before it ships, or publish it. Carries the stage flow and review behaviors so that guidance does not live inside template bodies or folder descriptions. Complements the platform `open-knowledge` skill; does not replace it."compatibility: "Claude Code, Claude Desktop, Claude Cowork, Claude.ai web. Requires OpenKnowledge MCP server. Installed project-local by `ok seed --pack writing-pipeline`."metadata:pack: "writing-pipeline"author: "Inkeep"- repository: "https://github.com/inkeep/open-knowledge"+ repository: "https://github.com/inkeep/open-knowledge-skills"---# Writing Pipeline pack — how to work herediff --git a/packages/server/assets/skills/project/SKILL.md b/packages/server/assets/skills/project/SKILL.mdindex ab3f82fe8..5a6df0cc6 100644--- a/packages/server/assets/skills/project/SKILL.md+++ b/packages/server/assets/skills/project/SKILL.md@@ -4,7 +4,7 @@ description: "Authoritative agent-runtime contract for working inside an OpenKnocompatibility: "Claude Code, Claude Desktop, Claude Cowork, Claude.ai web. Requires OpenKnowledge MCP server + code execution."metadata:author: "Inkeep"- repository: "https://github.com/inkeep/open-knowledge"+ repository: "https://github.com/inkeep/open-knowledge-skills"---# OpenKnowledge — agent guidance@@ -115,8 +115,8 @@ Three recurring practices, not tool calls — each a full procedure that ships a| Layer | When | Procedure || --- | --- | --- || **ingest** | Preserve a shared URL/PDF/file verbatim, or you fetched a URL to ground a claim (binary sources preserved, not scraped). | `references/ingest-and-sources.md` — ships here, §Grounding depends on it |-| **research** | Investigate / compare / synthesize sources → `status: provisional` article + `sources:`. | `open-knowledge-pack-knowledge-base-research` skill |-| **consolidate** | A decision was made → canonical source-of-truth with a `supersedes:` chain. | `open-knowledge-pack-knowledge-base-consolidate` skill |+| **research** | Investigate / compare / synthesize sources → `status: provisional` article + `sources:`. | `research-with-sources` skill |+| **consolidate** | A decision was made → canonical source-of-truth with a `supersedes:` chain. | `consolidate-notes` skill |Research and consolidate arrive with `ok seed --pack knowledge-base`. **Without that pack you do not have those procedures** — don't improvise one; do the work as an ordinary grounded `write`, or offer to seed it (`ok seed --pack knowledge-base --dry-run` shows what it would add).diff --git a/packages/server/assets/skills/project/references/starter-packs.md b/packages/server/assets/skills/project/references/starter-packs.mdindex 10922d655..993d6a93e 100644--- a/packages/server/assets/skills/project/references/starter-packs.md+++ b/packages/server/assets/skills/project/references/starter-packs.md@@ -12,8 +12,8 @@ Typical day-2 flow: user shares a URL → ingest (preserve) → user asks "now r- ingest → reference file `ingest-and-sources.md`, here in this bundle. Ships with every `ok init` because Core's Grounding rule depends on it, pack or no pack.- onboard a repo that already has content → reference file `onboard-existing-repo.md`, here in this bundle.-- research / consolidate → their own skills, `open-knowledge-pack-knowledge-base-research` and `open-knowledge-pack-knowledge-base-consolidate`, installed alongside their pack by `ok seed --pack knowledge-base`. **Not available otherwise** — if the pack isn't seeded, say so rather than improvising a lookalike pipeline.-- generate / refresh a codebase wiki → reference file `generate-and-refresh.md`, inside the `open-knowledge-pack-codebase-wiki` skill's bundle and readable once that skill loads. Installed by `ok seed --pack codebase-wiki`.+- research / consolidate → their own skills, `research-with-sources` and `consolidate-notes`, installed alongside their pack by `ok seed --pack knowledge-base`. **Not available otherwise** — if the pack isn't seeded, say so rather than improvising a lookalike pipeline.+- generate / refresh a codebase wiki → reference file `generate-and-refresh.md`, inside the `codebase-wiki` skill's bundle and readable once that skill loads. Installed by `ok seed --pack codebase-wiki`.Read the relevant procedure and execute its numbered steps with the OK verbs; don't skip its STOP gates.diff --git a/packages/server/assets/skills/write-skill/SKILL.md b/packages/server/assets/skills/write-skill/SKILL.mdindex ca470a1f5..62b0cae88 100644--- a/packages/server/assets/skills/write-skill/SKILL.md+++ b/packages/server/assets/skills/write-skill/SKILL.md@@ -4,7 +4,7 @@ description: "Use when the user wants to create, author, write, or design a newcompatibility: "OpenKnowledge project recommended (uses the `write` / `edit` / `install` MCP verbs). Authoring + validation are pure file ops; live preview + eval want a running server (`ok start`)."metadata:author: "Inkeep"- repository: "https://github.com/inkeep/open-knowledge"+ repository: "https://github.com/inkeep/open-knowledge-skills"---# Writing an OpenKnowledge skilldiff --git a/packages/server/scripts/build-skill-bundles.test.ts b/packages/server/scripts/build-skill-bundles.test.tsindex 806cecd0f..4cc86a7c0 100644--- a/packages/server/scripts/build-skill-bundles.test.ts+++ b/packages/server/scripts/build-skill-bundles.test.ts@@ -18,7 +18,9 @@ import {} from 'node:fs';import { tmpdir } from 'node:os';import { dirname, join } from 'node:path';+import { SKILL_NAME_REGEX } from '@inkeep/open-knowledge-core';import { afterEach, describe, expect, test } from 'vitest';+import { enumeratePackSkills } from '../src/skill-pack-sources.ts';import {BUNDLE_IDS,buildPackSkills,@@ -221,7 +223,7 @@ describe('buildPackSkills', () => {const packDir = join(paths.skillsDir, 'packs', 'demo-pack');mkdirSync(packDir, { recursive: true });writeFileSync(join(packDir, 'SKILL.md'), '# demo pack\n');- expect(buildPackSkills(paths)).toEqual(['open-knowledge-pack-demo-pack']);+ expect(buildPackSkills(paths)).toEqual(['demo-pack']);const out = join(paths.distDir, 'packs', 'demo-pack', 'SKILL.md');expect(existsSync(out)).toBe(true);expect(readFileSync(out, 'utf-8')).toBe('# demo pack\n');@@ -236,10 +238,7 @@ describe('buildPackSkills', () => {writeFileSync(join(packDir, 'do-a-thing', 'SKILL.md'), '# do a thing\n');writeFileSync(join(packDir, 'references', 'notes.md'), '# notes\n');- expect(buildPackSkills(paths)).toEqual([- 'open-knowledge-pack-demo-pack',- 'open-knowledge-pack-demo-pack-do-a-thing',- ]);+ expect(buildPackSkills(paths)).toEqual(['demo-pack', 'do-a-thing']);// dist keeps the nested layout verbatim — the installer and the public skills// mirror both enumerate it from there.const distPack = join(paths.distDir, 'packs', 'demo-pack');@@ -340,3 +339,72 @@ describe('repo assets — production guard', () => {expect(names.size).toBe(BUNDLE_IDS.length);});});++// The in-subtree half of the mirror contract: every skill OpenKnowledge ships+// reaches the public mirror as a directory named by its frontmatter `name`.+// Uniqueness must hold across ALL shipped skills (the nested mirror layout puts+// packs in separate folders, so the derive-time duplicate-destination throw no+// longer catches a cross-pack duplicate) and must be visible to subtree+// `pnpm check`, not only to the monorepo-root mirror test.+describe('repo assets — shipped skill names (mirror gate)', () => {+ const FRONTMATTER_NAME = /^name:[ \t]*(\S+)[ \t]*$/m;++ const collectShippedSkills = (): Array<{ name: string; dir: string }> => {+ const { skillsDir } = defaultPaths();+ const skills: Array<{ name: string; dir: string }> = [];+ for (const bundle of BUNDLE_IDS) {+ const dir = join(skillsDir, bundle);+ const md = readFileSync(join(dir, 'SKILL.md'), 'utf-8');+ skills.push({ name: FRONTMATTER_NAME.exec(md)?.[1] ?? '', dir });+ }+ const packsDir = join(skillsDir, 'packs');+ for (const entry of readdirSync(packsDir, { withFileTypes: true })) {+ if (!entry.isDirectory()) continue;+ for (const source of enumeratePackSkills(join(packsDir, entry.name))) {+ skills.push({ name: source.name, dir: source.sourceDir });+ }+ }+ return skills;+ };++ test('every shipped skill has a valid name, unique across packs and built-ins', () => {+ const skills = collectShippedSkills();+ // 3 built-ins + 8 pack orientation skills + 7 members. Deliberate tripwire:+ // adding or removing a shipped skill should be a conscious marketplace and+ // mirror decision, not a silent side effect.+ expect(skills.length).toBe(18);+ for (const { name, dir } of skills) {+ expect(name, `frontmatter name missing or invalid in ${dir}`).toMatch(SKILL_NAME_REGEX);+ expect(name.length, `name too long in ${dir}`).toBeLessThanOrEqual(64);+ }+ const seen = new Set<string>();+ const duplicates: string[] = [];+ for (const { name } of skills) {+ if (seen.has(name)) duplicates.push(name);+ seen.add(name);+ }+ expect(duplicates).toEqual([]);+ });++ test('every shipped skill declares its name in frontmatter (mirror derive throws without it)', () => {+ // enumeratePackSkills falls back to the dir basename, but the mirror's+ // discoverSkills throws on a missing/malformed `name:` — assert the+ // explicit declaration HERE so the failure lands in the subtree gate,+ // not later at mirror-generate.+ for (const { name, dir } of collectShippedSkills()) {+ const md = readFileSync(join(dir, 'SKILL.md'), 'utf-8');+ const declared = /^name:[ \t]*(\S+)[ \t]*$/m.exec(md)?.[1];+ expect(declared, `${dir} must declare frontmatter name:`).toBe(name);+ }+ });++ test('every shipped skill declares the public author + repository metadata', () => {+ for (const { dir } of collectShippedSkills()) {+ const md = readFileSync(join(dir, 'SKILL.md'), 'utf-8');+ expect(md, `${dir} missing author`).toContain('author: "Inkeep"');+ expect(md, `${dir} missing repository`).toContain(+ 'repository: "https://github.com/inkeep/open-knowledge-skills"',+ );+ }+ });+});diff --git a/packages/server/scripts/build-skill-bundles.ts b/packages/server/scripts/build-skill-bundles.tsindex 6310e6c52..84bad48c9 100644--- a/packages/server/scripts/build-skill-bundles.ts+++ b/packages/server/scripts/build-skill-bundles.ts@@ -156,7 +156,7 @@ export function buildPackSkills(paths: SkillBundlePaths = defaultPaths()): strinfor (const entry of readdirSync(packsSrc, { withFileTypes: true })) {if (!entry.isDirectory()) continue;const sourceDir = join(packsSrc, entry.name);- const skills = enumeratePackSkills(entry.name, sourceDir);+ const skills = enumeratePackSkills(sourceDir);if (skills.length === 0) continue;const outDir = join(paths.distDir, 'packs', entry.name);rmSync(outDir, { recursive: true, force: true });diff --git a/packages/server/src/api-extension.ts b/packages/server/src/api-extension.tsindex 9d5cbb156..88da07583 100644--- a/packages/server/src/api-extension.ts+++ b/packages/server/src/api-extension.ts@@ -119,6 +119,7 @@ import {isFrontmatterSchemaAsset,isHiddenDocName,isManagedArtifactDocName,+ isOpenKnowledgeSkillsSource,isSkillInstallTarget,isValidAttachmentFolderPath,LEGACY_SKILL_STORE_ROOT,@@ -179,6 +180,7 @@ import {parseTemplateFile,prependFrontmatter,projectSkillContentDocName,+ RENAMED_PACK_SKILLS,RenamePathRequestSchema,RenamePathSuccessSchema,type RescueEntryFlat,@@ -550,6 +552,19 @@ import {mintTempUploadPath,} from './upload-streaming.ts';+/** Does the bundle at `dir` carry a `metadata.pack` marker in its frontmatter? */+function bundleSelfIdentifiesAsPack(dir: string): boolean {+ try {+ const md = readFileSync(join(dir, 'SKILL.md'), 'utf-8');+ const frontmatter = /^---\r?\n([\s\S]*?)\r?\n---(\r?\n|$)/.exec(md)?.[1];+ return (+ frontmatter !== undefined && /^[ \t]+pack:[ \t]*"?[a-z0-9-]+"?[ \t]*$/m.test(frontmatter)+ );+ } catch {+ return false;+ }+}+export { extractPageTitle } from './page-identity.ts';import type { SkillHostId } from '@inkeep/open-knowledge-core/skills-catalog';@@ -19491,7 +19506,13 @@ export function createApiExtension(options: ApiExtensionOptions): Extension {// Metadata-only: this probe just matches a name. `parseSkillDir`// would read and hash every byte of every bundle in the clone,// before the size pre-flight below can refuse any of it.- dirs.find((d) => readSkillDirMeta(d.dir)?.name === selectedSkill);+ dirs.find((d) => readSkillDirMeta(d.dir)?.name === selectedSkill) ??+ // Rename alias: the skills.sh listings for the OLD pack-skill+ // names outlive the rename (there is no self-serve delist), so+ // someone can still arrive here asking for a name the mirror no+ // longer ships. Resolve it to the renamed bundle rather than+ // 404-ing a listing that looks perfectly healthy.+ dirs.find((d) => d.name === RENAMED_PACK_SKILLS[selectedSkill]);if (!found) {errorResponse(res, 404, 'urn:ok:error:not-found', 'Named skill not in source.', {handler: 'skill-import',@@ -19544,16 +19565,27 @@ export function createApiExtension(options: ApiExtensionOptions): Extension {actor,skipProjection: body.install === false,});- // Count it on skills.sh, but ONLY when the user came from a skills.sh- // listing (`marketplace`, set by the Explore tab). A hand-typed- // `owner/repo` is not announced to a third party — the user never went- // to the marketplace, and telling it which repos they install would be- // a disclosure they did not ask for.+ // Count it on skills.sh when EITHER the user came from a skills.sh+ // listing (`marketplace`, set by the Explore tab) OR the source is our+ // own published skills repo.+ //+ // The privacy rule that gates everything else — never announce a repo+ // the user did not choose from the marketplace, because telling a third+ // party which repos they install is a disclosure they did not ask for —+ // does not apply to our own repo: the name being reported is ours, and+ // `ok init` and `ok seed` already report it unconditionally. Without the+ // second arm, `ok skills import inkeep/open-knowledge-skills`, the MCP+ // import tool on a bare repo source, and every non-Explore route that+ // installs one of our own skills went uncounted while the seed path+ // counted the same skill.//// This is the mechanism that actually moves the counter. Fetching the// bundle through skills.sh's download API does NOT: verified against a// skill sitting at 8 installs, which stayed at 8 after a download.- if (body.marketplace === true && outcome.ok) {+ if (+ outcome.ok &&+ (body.marketplace === true || isOpenKnowledgeSkillsSource(resolvedSourceForReport))+ ) {void reportSkillInstall({ source: resolvedSourceForReport, skills: [outcome.body.name] },resolveSkillInstallReportSettings(),@@ -19613,6 +19645,9 @@ export function createApiExtension(options: ApiExtensionOptions): Extension {let dirs: ReturnType<typeof discoverSkillDirs> = [];let ref: string | undefined;let publisher: string | undefined;+ // The canonical repo behind a skills.sh page URL — what the install+ // report must name so the event lands on the right listing.+ let resolvedSourceForReport = rawSource;try {// Resolution is per-SKILL by contract: a website source refuses to// resolve without a name (there is no repo to point at, only the@@ -19623,6 +19658,7 @@ export function createApiExtension(options: ApiExtensionOptions): Extension {// against the single clone.const skillsSh = await resolveSkillsShImportSource(rawSource, body.skills[0]);const resolvedSource = skillsSh?.source ?? rawSource;+ resolvedSourceForReport = resolvedSource;const spec = skillsSh?.spec ?? parseSource(resolvedSource);if (!spec) {errorResponse(res, 400, 'urn:ok:error:invalid-request', 'Unrecognized import source.', {@@ -19694,7 +19730,10 @@ export function createApiExtension(options: ApiExtensionOptions): Extension {// SKILL.md frontmatter name (they routinely differ).const found =dirs.find((d) => d.name === requested) ??- dirs.find((d) => parseSkillDir(d.dir)?.name === requested);+ dirs.find((d) => parseSkillDir(d.dir)?.name === requested) ??+ // Same rename alias as the single import: a stale old-name listing+ // resolves to the renamed bundle instead of reading as not-found.+ dirs.find((d) => d.name === RENAMED_PACK_SKILLS[requested]);if (!found) {results.push({ requested, status: 'not-found', warnings: [] });continue;@@ -19756,6 +19795,28 @@ export function createApiExtension(options: ApiExtensionOptions): Extension {perSkill();}}+ // Count the plugin/bundle funnel on skills.sh — ONE batched event for+ // the whole selection. Same two-arm rule as the single import above: a+ // skills.sh listing the user chose (`marketplace`, set by the plugin+ // bundle dialog and the MCP import rider), OR our own published repo,+ // which needs no marketplace referral to be ours to count. A hand-typed+ // third-party repo is still never announced. Fire-and-forget; the+ // reporter dedupes per skill per machine.+ if (body.marketplace === true || isOpenKnowledgeSkillsSource(resolvedSourceForReport)) {+ // `requested` — the name the skills.sh listing carries — not `name`,+ // which is the LOCAL name after collision resolution (`foo-imported`+ // when the user already held `foo`). The collector indexes listings,+ // so a locally-suffixed name is an unknown skill it cannot count.+ const importedNames = results+ .filter((r) => r.status === 'imported')+ .map((r) => r.requested);+ if (importedNames.length > 0) {+ void reportSkillInstall(+ { source: resolvedSourceForReport, skills: importedNames },+ resolveSkillInstallReportSettings(),+ );+ }+ }successResponse(res,200,@@ -21794,6 +21855,9 @@ export function createApiExtension(options: ApiExtensionOptions): Extension {...SKILLS_LOCK_REL,);const lock = readSkillsLock(lockPath);+ // An old-name pack install resolves directly: it was never renamed, so+ // its lock key still matches its dir. The source-dir pick below carries+ // the old→new mapping so the fetch lands on the renamed mirror dir.let entry = lock.skills[body.name];if (!entry) {// Retrofit: a starter pack seeded before provenance was recorded has no@@ -21807,6 +21871,12 @@ export function createApiExtension(options: ApiExtensionOptions): Extension {body.name,parseSkillDir(resolve(skillsRoot, body.name))?.contentHash ?? '',new Date().toISOString(),+ // The post-rename names are generic (`write-a-spec`,+ // `knowledge-base`), so presence is not proof of ownership. Pass+ // the bundle's own `metadata.pack` marker as the witness, or a+ // user's same-named skill would be handed our provenance and+ // offered an overwrite with ours.+ { selfIdentifiesAsPack: bundleSelfIdentifiesAsPack(resolve(skillsRoot, body.name)) },) ?? synthBuiltinLockEntry(reimportBase, body.name);if (synthesized) entry = synthesized;}@@ -21849,9 +21919,20 @@ export function createApiExtension(options: ApiExtensionOptions): Extension {let acquired: ReturnType<typeof parseSkillDir> = null;let hasScripts = false;try {- const skillsSh = await resolveSkillsShImportSource(- entry.source,- entry.skill ?? body.name,+ // A listing-sourced install looks its skill up on skills.sh by name.+ // A pre-rename install asks for a name the repo no longer ships: that+ // still resolves today only because the superseded listing is still+ // up, and retiring those listings is an open ask — which would+ // otherwise turn "tidy up the old listings" into "break Update for+ // everyone who installed from one". Fall back to the renamed listing+ // so the two decisions stay independent.+ const recordedSkill = entry.skill ?? body.name;+ const renamedSkill = RENAMED_PACK_SKILLS[recordedSkill];+ const skillsSh = await resolveSkillsShImportSource(entry.source, recordedSkill).catch(+ async (err: unknown) => {+ if (renamedSkill === undefined) throw err;+ return resolveSkillsShImportSource(entry.source, renamedSkill);+ },);// A plugin-cache copy re-points at the NEWEST cached version — the// recorded dir is a version pin the plugin manager prunes, so honoring@@ -21882,6 +21963,9 @@ export function createApiExtension(options: ApiExtensionOptions): Extension {(resolvedSkill ? dirs.find((d) => d.name === resolvedSkill) : undefined) ??dirs.find((d) => d.name === body.name) ??dirs.find((d) => parseSkillDir(d.dir)?.name === body.name) ??+ // Rename alias: an old-name install updating against the renamed+ // mirror finds its bundle under the new name.+ dirs.find((d) => d.name === RENAMED_PACK_SKILLS[resolvedSkill ?? body.name]) ??(dirs.length === 1 ? dirs[0] : undefined);if (!pick) {errorResponse(diff --git a/packages/server/src/boot.ts b/packages/server/src/boot.tsindex 7a5f03b09..9239a622d 100644--- a/packages/server/src/boot.ts+++ b/packages/server/src/boot.ts@@ -1178,7 +1178,7 @@ async function bootServerInner(opts: BootServerOptions): Promise<BootedServer> {}} catch (err) {log.warn?.(- { event: 'store-skill-migration-failed', error: String(err) },+ { err, event: 'store-skill-migration-failed' },'Store-skill in-place migration failed (non-fatal).',);}@@ -1207,7 +1207,7 @@ async function bootServerInner(opts: BootServerOptions): Promise<BootedServer> {}} catch (err) {log.warn?.(- { event: 'global-store-skill-migration-failed', error: String(err) },+ { err, event: 'global-store-skill-migration-failed' },'Global store-skill in-place migration failed (non-fatal).',);}diff --git a/packages/server/src/build-skill-zip.ts b/packages/server/src/build-skill-zip.tsindex b094abf84..3e9bc4d7b 100644--- a/packages/server/src/build-skill-zip.ts+++ b/packages/server/src/build-skill-zip.ts@@ -135,9 +135,24 @@ export function resolveBundledSkillDir(const home = opts.home ?? homedir();const candidates: string[] = [];+ // A co-installed OK Desktop is probed FIRST and wins on mere existence. There+ // is no version comparison, and version could not arbitrate anyway: a working+ // tree carries unreleased changes at the SAME version as the app built from+ // the last release, so an app whose assets predate the branch still wins.+ //+ // In production that is intended. Under test it makes the result depend on+ // whatever is installed on the developer's machine — a stale OpenKnowledge.app+ // silently shadows the tree under test, producing failures CI cannot+ // reproduce. So the REAL machine roots are probed only outside tests; a test+ // that supplies its own `home` still gets the home-relative probe, scoped to+ // the directory it controls, which is how the desktop-wins behavior stays+ // covered.+ const underTest = process.env.NODE_ENV === 'test';if (checkDesktop && platform === 'darwin') {- candidates.push(join('/Applications', DESKTOP_SKILLS_REL, which));- candidates.push(join(home, 'Applications', DESKTOP_SKILLS_REL, which));+ if (!underTest) candidates.push(join('/Applications', DESKTOP_SKILLS_REL, which));+ if (!underTest || opts.home !== undefined) {+ candidates.push(join(home, 'Applications', DESKTOP_SKILLS_REL, which));+ }}candidates.push(fileURLToPath(new URL(`../dist/assets/skills/${which}`, import.meta.url)));candidates.push(fileURLToPath(new URL(`../assets/skills/${which}`, import.meta.url)));diff --git a/packages/server/src/index.ts b/packages/server/src/index.tsindex 274e3a7e6..adc5d60cc 100644--- a/packages/server/src/index.ts+++ b/packages/server/src/index.ts@@ -546,6 +546,7 @@ export {type SkillInstallEventOutcome,type SkillInstallEventSurface,} from './skill-install-events.ts';+export { resolveSkillInstallReportSettings } from './skill-install-report-config.ts';export {readAllTargets,readBundleDecision,@@ -561,6 +562,7 @@ export {writeBundleDecision,writeTargetVersion,} from './skill-state.ts';+export { reportSkillInstall, type SkillInstallReport } from './skills-sh-install-report.ts';export {CURSOR_BUNDLE_PATHS_BY_PLATFORM,type HandleSpawnCursorDeps,diff --git a/packages/server/src/mcp/tools/import.test.ts b/packages/server/src/mcp/tools/import.test.tsindex 75c955f83..6b554aafc 100644--- a/packages/server/src/mcp/tools/import.test.ts+++ b/packages/server/src/mcp/tools/import.test.ts@@ -129,7 +129,13 @@ describe('import MCP tool', () => {expect(calls).toEqual([{url: 'http://localhost:4321/api/skill/import',- body: { source: 'https://www.skills.sh/acme/skills/review-bot', install: false },+ // A pasted skills.sh page URL is marketplace provenance, so the import+ // rides the install-report rider; other source shapes never set it.+ body: {+ source: 'https://www.skills.sh/acme/skills/review-bot',+ install: false,+ marketplace: true,+ },},{url: 'http://localhost:4321/api/skill/install',diff --git a/packages/server/src/mcp/tools/import.ts b/packages/server/src/mcp/tools/import.tsindex 041ac94e9..20192fef8 100644--- a/packages/server/src/mcp/tools/import.ts+++ b/packages/server/src/mcp/tools/import.ts@@ -15,6 +15,7 @@ import {SkillLocationIdSchema,type SkillScope,} from '@inkeep/open-knowledge-core';+import { parseSkillsShSource } from '@inkeep/open-knowledge-core/skills-catalog';import { z } from 'zod';import type { AgentIdentity } from '../agent-identity.ts';import type { ConfigOrResolver, ServerInstance, ServerUrlOrResolver } from './shared.ts';@@ -136,6 +137,10 @@ export function register(server: ServerInstance, deps: ImportDeps): void {// location math lives in exactly one place, and so an import can never// leave a skill sitting somewhere the caller did not name.install: false,+ // A pasted skills.sh page URL is marketplace provenance — the user+ // chose the listing — so the install counts toward it. Any other+ // source shape (owner/repo, git URL, local path) is never announced.+ ...(parseSkillsShSource(args.source) !== null ? { marketplace: true } : {}),...(args.scope !== undefined ? { scope: args.scope } : {}),...(args.summary !== undefined ? { summary: args.summary } : {}),...agentIdentityFields(deps.identityRef?.current),diff --git a/packages/server/src/seed/apply.ts b/packages/server/src/seed/apply.tsindex 35a49f002..8cc2107f9 100644--- a/packages/server/src/seed/apply.ts+++ b/packages/server/src/seed/apply.ts@@ -148,7 +148,7 @@ export async function applySeed(plan: ScaffoldPlan, opts: SeedOptions = {}): Pro// to each set-up editor. Single site for every seed entry point (CLI /// desktop IPC / HTTP), since they all call applySeed. No-op when no editor// is set up or the pack ships no skill.- const packSkillsInstalled = await installPackSkill(projectDir, pack.id);+ const packSkillInstall = await installPackSkill(projectDir, pack.id);// `installPackSkill` logs and skips a skill whose source it could not author,// so a decomposed pack can land some skills and drop others while still@@ -168,6 +168,7 @@ export async function applySeed(plan: ScaffoldPlan, opts: SeedOptions = {}): Proapplied,errors,durationMs: Date.now() - started,- packSkillsInstalled,+ packSkillsInstalled: packSkillInstall.editors,+ packSkillConflicts: packSkillInstall.conflicts,};}diff --git a/packages/server/src/seed/install-pack-skill.test.ts b/packages/server/src/seed/install-pack-skill.test.tsindex 612dc7af5..403097895 100644--- a/packages/server/src/seed/install-pack-skill.test.ts+++ b/packages/server/src/seed/install-pack-skill.test.ts@@ -3,6 +3,7 @@ import {mkdirSync,mkdtempSync,readFileSync,+ rmSync,symlinkSync,writeFileSync,} from 'node:fs';@@ -11,7 +12,11 @@ import { join } from 'node:path';import { OPENKNOWLEDGE_SKILLS_REPO } from '@inkeep/open-knowledge-core';import { describe, expect, test } from 'vitest';import { readInstalledSkills } from '../installed-skills-marker.ts';-import { installPackSkill, resolvePackSkillSources } from './install-pack-skill.ts';+import {+ classifyPresentPackSkill,+ installPackSkill,+ resolvePackSkillSources,+} from './install-pack-skill.ts';/** Simulate `ok init` having installed the platform skill for an editor dir. */function setUpEditor(proj: string, editorDir: string): void {@@ -24,27 +29,38 @@ function tmpProject(): string {return mkdtempSync(join(tmpdir(), 'ok-seed-skill-'));}+/**+ * The pack's orientation-skill name AS RESOLVED ON THIS MACHINE. Names are+ * frontmatter-driven and `resolvePackSkillSources` probes a co-installed OK+ * Desktop bundle before the repo assets, so a hardcoded name would pin the test+ * to whichever bundle this machine happens to carry.+ */+function orientationName(packId: string): string {+ const [first] = resolvePackSkillSources(packId);+ expect(first).toBeDefined();+ return (first as { name: string }).name;+}+describe('installPackSkill', () => {test('authors the pack skill IN PLACE at the default home (store retirement)', async () => {const proj = tmpProject();setUpEditor(proj, '.claude');- const installed = await installPackSkill(proj, 'knowledge-base');- expect(installed).toEqual(['Claude Code']);+ const name = orientationName('knowledge-base');+ const result = await installPackSkill(proj, 'knowledge-base');+ expect(result.editors).toEqual(['Claude Code']);+ expect(result.conflicts).toEqual([]);// The source lands at the project's default skill home (here `.claude/// skills` — the first existing editor root), NOT the retired `.ok/skills`// store. The scan is the host-set truth; no install marker is written.- expect(- existsSync(join(proj, '.claude', 'skills', 'open-knowledge-pack-knowledge-base', 'SKILL.md')),- ).toBe(true);- expect(existsSync(join(proj, '.ok', 'skills', 'open-knowledge-pack-knowledge-base'))).toBe(- false,- );- expect(readInstalledSkills(proj).skills['open-knowledge-pack-knowledge-base']).toBeUndefined();+ expect(existsSync(join(proj, '.claude', 'skills', name, 'SKILL.md'))).toBe(true);+ expect(existsSync(join(proj, '.ok', 'skills', name))).toBe(false);+ expect(readInstalledSkills(proj).skills[name]).toBeUndefined();});test('records skills.sh provenance in .ok/skills-lock.json for reimport', async () => {const proj = tmpProject();setUpEditor(proj, '.claude');+ const name = orientationName('knowledge-base');await installPackSkill(proj, 'knowledge-base');// Provenance makes a seeded pack update through the SAME reimport path as any// imported skill: deterministic source (the open-knowledge-skills projection),@@ -52,10 +68,10 @@ describe('installPackSkill', () => {const lock = JSON.parse(readFileSync(join(proj, '.ok', 'skills-lock.json'), 'utf-8')) as {skills: Record<string, { source: string; skill: string; contentHash: string }>;};- const entry = lock.skills['open-knowledge-pack-knowledge-base'];+ const entry = lock.skills[name];expect(entry).toBeDefined();expect(entry.source).toBe(OPENKNOWLEDGE_SKILLS_REPO);- expect(entry.skill).toBe('open-knowledge-pack-knowledge-base');+ expect(entry.skill).toBe(name);expect(entry.contentHash).toMatch(/^[a-f0-9]{64}$/);});@@ -64,21 +80,16 @@ describe('installPackSkill', () => {setUpEditor(proj, '.claude');setUpEditor(proj, '.cursor');setUpEditor(proj, '.codex');- expect((await installPackSkill(proj, 'entity-vault')).sort()).toEqual([+ const name = orientationName('entity-vault');+ expect((await installPackSkill(proj, 'entity-vault')).editors.sort()).toEqual(['Claude Code','Codex','Cursor',]);// Source at the default home; real copies fanned to the other editors.- expect(- existsSync(join(proj, '.claude', 'skills', 'open-knowledge-pack-entity-vault', 'SKILL.md')),- ).toBe(true);- expect(- existsSync(join(proj, '.cursor', 'skills', 'open-knowledge-pack-entity-vault', 'SKILL.md')),- ).toBe(true);- expect(- existsSync(join(proj, '.codex', 'skills', 'open-knowledge-pack-entity-vault', 'SKILL.md')),- ).toBe(true);+ expect(existsSync(join(proj, '.claude', 'skills', name, 'SKILL.md'))).toBe(true);+ expect(existsSync(join(proj, '.cursor', 'skills', name, 'SKILL.md'))).toBe(true);+ expect(existsSync(join(proj, '.codex', 'skills', name, 'SKILL.md'))).toBe(true);});test('installs the codebase-wiki pack skill from the source assets', async () => {@@ -86,16 +97,15 @@ describe('installPackSkill', () => {// probe (source `assets/skills/packs/codebase-wiki/` when no built dist).const proj = tmpProject();setUpEditor(proj, '.claude');- expect(await installPackSkill(proj, 'codebase-wiki')).toEqual(['Claude Code']);- expect(- existsSync(join(proj, '.claude', 'skills', 'open-knowledge-pack-codebase-wiki', 'SKILL.md')),- ).toBe(true);+ const name = orientationName('codebase-wiki');+ expect((await installPackSkill(proj, 'codebase-wiki')).editors).toEqual(['Claude Code']);+ expect(existsSync(join(proj, '.claude', 'skills', name, 'SKILL.md'))).toBe(true);});test('a decomposed pack installs its root skill plus every member skill', async () => {// `software-lifecycle` ships an orientation SKILL.md at the pack root plus one// scenario skill per subdirectory. Each installs as its own top-level skill- // (name == leaf dir, per the Agent Skills standard).+ // (name == SKILL.md frontmatter, per the Agent Skills standard).//// Assert against `resolvePackSkillSources` rather than a hardcoded name list:// it probes a co-installed OK Desktop bundle first, so a machine with an older@@ -106,7 +116,7 @@ describe('installPackSkill', () => {setUpEditor(proj, '.claude');const sources = resolvePackSkillSources('software-lifecycle');expect(sources.length).toBeGreaterThan(0);- expect(await installPackSkill(proj, 'software-lifecycle')).toEqual(['Claude Code']);+ expect((await installPackSkill(proj, 'software-lifecycle')).editors).toEqual(['Claude Code']);for (const { name } of sources) {expect(existsSync(join(proj, '.claude', 'skills', name, 'SKILL.md'))).toBe(true);@@ -114,73 +124,236 @@ describe('installPackSkill', () => {}// The root skill's copy carries no member subdirectory — that would ship each// scenario skill twice, once nested inside a skill that is not its own.- const root = sources.find((s) => s.name === 'open-knowledge-pack-software-lifecycle');+ const root = sources[0];expect(root).toBeDefined();- for (const member of root?.excludeDirs ?? []) {+ for (const member of root?.excludePaths ?? []) {expect(existsSync(join(proj, '.claude', 'skills', root?.name ?? '', member))).toBe(false);}});test('no editor set up: the source is still authored at the fallback home', async () => {const proj = tmpProject();+ const name = orientationName('knowledge-base');// No set-up editor → nothing fanned/labelled, but the source still lands// (default fallback home) so the skill lists for that folder's agent.- expect(await installPackSkill(proj, 'knowledge-base')).toEqual([]);- expect(- existsSync(join(proj, '.claude', 'skills', 'open-knowledge-pack-knowledge-base', 'SKILL.md')),- ).toBe(true);- expect(readInstalledSkills(proj).skills['open-knowledge-pack-knowledge-base']).toBeUndefined();+ expect((await installPackSkill(proj, 'knowledge-base')).editors).toEqual([]);+ expect(existsSync(join(proj, '.claude', 'skills', name, 'SKILL.md'))).toBe(true);+ expect(readInstalledSkills(proj).skills[name]).toBeUndefined();});test('no-op for a pack that ships no skill', async () => {const proj = tmpProject();setUpEditor(proj, '.claude');- expect(await installPackSkill(proj, 'no-such-pack')).toEqual([]);- // Ships no skill → nothing authored.- expect(existsSync(join(proj, '.ok', 'skills', 'open-knowledge-pack-no-such-pack'))).toBe(false);+ const result = await installPackSkill(proj, 'no-such-pack');+ expect(result.editors).toEqual([]);+ expect(result.conflicts).toEqual([]);});test('re-seed preserves a user-edited pack skill (no rm+cp clobber)', async () => {const proj = tmpProject();setUpEditor(proj, '.claude');+ const name = orientationName('knowledge-base');// First install authors the shipped source.await installPackSkill(proj, 'knowledge-base');- const sourcePath = join(- proj,- '.claude',- 'skills',- 'open-knowledge-pack-knowledge-base',- 'SKILL.md',- );+ const sourcePath = join(proj, '.claude', 'skills', name, 'SKILL.md');expect(existsSync(sourcePath)).toBe(true);// The pack skill is now the user's fork — they edit it.- const edited =- '---\nname: open-knowledge-pack-knowledge-base\ndescription: my edit\n---\nmine\n';+ const edited = `---\nname: ${name}\ndescription: my edit\n---\nmine\n`;writeFileSync(sourcePath, edited, 'utf-8');// Re-running seed (CLI / desktop IPC / HTTP all funnel here) must NOT reset- // the source back to the shipped body. Projection + marker still refresh.- const installed = await installPackSkill(proj, 'knowledge-base');- expect(installed).toEqual(['Claude Code']);+ // the source back to the shipped body — the lock's provenance says the fork+ // is ours, so it is neither clobbered nor reported as a conflict.+ const result = await installPackSkill(proj, 'knowledge-base');+ expect(result.editors).toEqual(['Claude Code']);+ expect(result.conflicts.map((c) => c.name)).not.toContain(name);expect(readFileSync(sourcePath, 'utf-8')).toBe(edited);- expect(- existsSync(join(proj, '.claude', 'skills', 'open-knowledge-pack-knowledge-base', 'SKILL.md')),- ).toBe(true);+ });++ test('a user-owned same-named skill is a reported conflict, never clobbered', async () => {+ const proj = tmpProject();+ setUpEditor(proj, '.claude');+ const name = orientationName('knowledge-base');+ // The user's own skill occupies the pack skill's name: no lock entry and no+ // `metadata.pack` self-identification, so provenance says it is not ours.+ const dir = join(proj, '.claude', 'skills', name);+ mkdirSync(dir, { recursive: true });+ const mine = `---\nname: ${name}\ndescription: mine\n---\nmine\n`;+ writeFileSync(join(dir, 'SKILL.md'), mine, 'utf-8');++ const result = await installPackSkill(proj, 'knowledge-base');+ expect(result.conflicts.map((c) => c.name)).toContain(name);+ expect(readFileSync(join(dir, 'SKILL.md'), 'utf-8')).toBe(mine);});test('refuses to install through an editor dir that symlinks outside the project', async () => {const proj = tmpProject();const outside = tmpProject();+ const name = orientationName('knowledge-base');// `.claude` resolves outside the project; the platform skill is present// there, so we reach (and must be stopped by) the symlink-escape guard.symlinkSync(outside, join(proj, '.claude'));mkdirSync(join(outside, 'skills', 'open-knowledge'), { recursive: true });writeFileSync(join(outside, 'skills', 'open-knowledge', 'SKILL.md'), '# platform\n');- expect(await installPackSkill(proj, 'knowledge-base')).toEqual([]);- expect(existsSync(join(outside, 'skills', 'open-knowledge-pack-knowledge-base'))).toBe(false);+ expect((await installPackSkill(proj, 'knowledge-base')).editors).toEqual([]);+ expect(existsSync(join(outside, 'skills', name))).toBe(false);// The escaping root is ALSO the would-be default home — the whole install// is refused (never author through an out-of-project symlink).- expect(readInstalledSkills(proj).skills['open-knowledge-pack-knowledge-base']).toBeUndefined();+ expect(readInstalledSkills(proj).skills[name]).toBeUndefined();+ });+});++describe('installPackSkill — an install under the old name is left alone', () => {+ // We deliberately do NOT rename skills people are already using: these are+ // project-level, so the directory is normally committed and a silent rename+ // is an unexplained diff for them and everyone who pulls. The install must+ // therefore read as present, so seeding never authors a second copy of the+ // same skill under the new name.+ const OLD = 'open-knowledge-pack-plain-notes';++ test('no duplicate is authored beside it, and no conflict is reported', async () => {+ const proj = tmpProject();+ setUpEditor(proj, '.claude');+ const newName = orientationName('plain-notes');+ expect(newName).not.toBe(OLD);+ const oldDir = join(proj, '.claude/skills', OLD);+ mkdirSync(oldDir, { recursive: true });+ writeFileSync(+ join(oldDir, 'SKILL.md'),+ `---\nname: ${OLD}\ndescription: "Plain notes."\nmetadata:\n pack: "plain-notes"\n---\n\nMine now.\n`,+ );++ const result = await installPackSkill(proj, 'plain-notes');++ expect(existsSync(join(proj, '.claude/skills', newName, 'SKILL.md'))).toBe(false);+ expect(result.conflicts).toEqual([]);+ // Untouched, still theirs, still under the name they know.+ expect(readFileSync(join(oldDir, 'SKILL.md'), 'utf-8')).toContain('Mine now.');+ rmSync(proj, { recursive: true, force: true });+ });++ // Skipping the whole loop body for a legacy install would also skip fan-out,+ // silently regressing an editor set up AFTER the install: seeding would report+ // "already set up" and leave that editor without the skill.+ test('still fans out into an editor set up after it was installed', async () => {+ const proj = tmpProject();+ setUpEditor(proj, '.claude');+ setUpEditor(proj, '.cursor');+ const oldDir = join(proj, '.claude/skills', OLD);+ mkdirSync(oldDir, { recursive: true });+ writeFileSync(+ join(oldDir, 'SKILL.md'),+ `---\nname: ${OLD}\ndescription: "Plain notes."\nmetadata:\n pack: "plain-notes"\n---\n\nBody.\n`,+ );++ const result = await installPackSkill(proj, 'plain-notes');++ // Projected under the name it actually has, into the newly set-up editor.+ expect(existsSync(join(proj, '.cursor/skills', OLD, 'SKILL.md'))).toBe(true);+ expect(existsSync(join(proj, '.cursor/skills', orientationName('plain-notes')))).toBe(false);+ expect(result.editors).toContain('Cursor');+ rmSync(proj, { recursive: true, force: true });+ });+});++describe('classifyPresentPackSkill — ours-retrofit', () => {+ // A pack skill installed before provenance was recorded has no lock entry, so+ // the lock cannot vouch for it. Its own frontmatter `metadata.pack` is the+ // only remaining witness that OK authored it. Without this branch such an+ // install reads as a stranger's skill and the rename declines to touch it.+ test('no lock entry but matching metadata.pack reads as ours', () => {+ const dir = mkdtempSync(join(tmpdir(), 'ok-classify-'));+ writeFileSync(+ join(dir, 'SKILL.md'),+ '---\nname: note-taking\ndescription: "x"\nmetadata:\n pack: "plain-notes"\n---\n',+ );+ expect(+ classifyPresentPackSkill('plain-notes', 'note-taking', dir, { schema: 1, skills: {} }),+ ).toBe('ours-retrofit');+ rmSync(dir, { recursive: true, force: true });+ });++ test("another pack's id in the frontmatter is not ours", () => {+ const dir = mkdtempSync(join(tmpdir(), 'ok-classify-'));+ writeFileSync(+ join(dir, 'SKILL.md'),+ '---\nname: note-taking\nmetadata:\n pack: "worldbuilding"\n---\n',+ );+ expect(+ classifyPresentPackSkill('plain-notes', 'note-taking', dir, { schema: 1, skills: {} }),+ ).toBe('foreign');+ rmSync(dir, { recursive: true, force: true });+ });++ test('an unreadable or absent bundle is undecidable, never ours', () => {+ expect(+ classifyPresentPackSkill('plain-notes', 'note-taking', join(tmpdir(), 'ok-nope-missing'), {+ schema: 1,+ skills: {},+ }),+ ).toBe('foreign');+ });++ // The lock keeps the raw source the user came in through. The same bundle+ // records the bare repo when seeded and a skills.sh URL when installed from+ // the listing, so an exact match reports OK's own skill as the user's name+ // collision — on the very flow the published listings exist for.+ test('a skills.sh URL naming the OK skills repo still reads as ours', () => {+ const lock = {+ schema: 1 as const,+ skills: {+ 'note-taking': {+ source: 'https://skills.sh/inkeep/open-knowledge-skills/note-taking',+ skill: 'note-taking',+ contentHash: 'h',+ importedAt: '2026-01-01T00:00:00.000Z',+ },+ },+ };+ expect(classifyPresentPackSkill('plain-notes', 'note-taking', null, lock)).toBe('ours');+ });++ test("a genuinely foreign import source is still the user's", () => {+ const lock = {+ schema: 1 as const,+ skills: {+ 'note-taking': {+ source: 'someone-else/skills',+ skill: 'note-taking',+ contentHash: 'h',+ importedAt: '2026-01-01T00:00:00.000Z',+ },+ },+ };+ expect(classifyPresentPackSkill('plain-notes', 'note-taking', null, lock)).toBe('foreign');+ });++ // The retrofit verdict is what writes OK provenance onto a skill, and that+ // provenance is what a later "Update from source" reimports over. A skill+ // that merely DOCUMENTS a pack must never buy it.+ test('a pack id in the body, not the frontmatter, is not ours', () => {+ const dir = mkdtempSync(join(tmpdir(), 'ok-classify-'));+ writeFileSync(+ join(dir, 'SKILL.md'),+ [+ '---',+ 'name: note-taking',+ 'description: "My own notes skill."',+ '---',+ '',+ 'Starter packs declare their id in frontmatter, like:',+ '',+ '```yaml',+ 'metadata:',+ ' pack: "plain-notes"',+ '```',+ '',+ ].join('\n'),+ );+ expect(+ classifyPresentPackSkill('plain-notes', 'note-taking', dir, { schema: 1, skills: {} }),+ ).toBe('foreign');+ rmSync(dir, { recursive: true, force: true });});});diff --git a/packages/server/src/seed/install-pack-skill.ts b/packages/server/src/seed/install-pack-skill.tsindex 47862a17c..c0fe87fab 100644--- a/packages/server/src/seed/install-pack-skill.ts+++ b/packages/server/src/seed/install-pack-skill.ts@@ -1,5 +1,5 @@/**- * Install a starter pack's project-local skills (`open-knowledge-pack-<packId>`,+ * Install a starter pack's project-local skills (named by each SKILL.md's frontmatter,* plus `…-<packId>-<member>` for a pack decomposed into scenario skills).** Two parts, so a pack skill behaves like any other authored project skill@@ -23,14 +23,17 @@ import { dirname, join } from 'node:path';import {EDITOR_PROJECT_SKILL_ROOT,type EditorId,+ isOpenKnowledgeSkillsSource,OPENKNOWLEDGE_SKILLS_REPO,PROJECT_SKILL_EDITOR_IDS,+ RENAMED_PACK_SKILLS,} from '@inkeep/open-knowledge-core';import {emptySkillsLock,parseSkillDir,parseSkillsLock,SKILLS_LOCK_REL,+ type SkillsLock,upsertLockEntry,} from '@inkeep/open-knowledge-core/skills-catalog';import { tracedCpSync, tracedMkdirSync, tracedRmSync, tracedWriteFileSync } from '../fs-traced.ts';@@ -40,7 +43,9 @@ import { BUNDLE_SKILL_NAME } from '../skill-bundles.ts';import { resolveSkillInstallReportSettings } from '../skill-install-report-config.ts';import { listPackSkillSources, type PackSkillSource } from '../skill-pack-sources.ts';import { hostSkillsRootEscapes, projectInPlaceSkill } from '../skill-projection.ts';+import { readSkillsLockFile } from '../skills-lock-store.ts';import { reportSkillInstall } from '../skills-sh-install-report.ts';+import type { PackSkillConflict } from './types.ts';/*** Display labels for the editors that keep project-local skills (returned in the@@ -112,9 +117,69 @@ function recordPackSkillProvenance(projectDir: string, name: string, skillDir: s}}-export async function installPackSkill(projectDir: string, packId: string): Promise<string[]> {+/** New-name → old-name inverse of the rename map (legacy-install lookup). */+export const OLD_PACK_SKILL_NAME: Readonly<Record<string, string>> = Object.fromEntries(+ Object.entries(RENAMED_PACK_SKILLS).map(([oldName, newName]) => [newName, oldName]),+);++export interface PackSkillInstallResult {+ /** Editor labels the pack's skills were installed/refreshed for. */+ editors: string[];+ /** Skills skipped because a user-owned same-named skill holds the name. */+ conflicts: PackSkillConflict[];+}++/**+ * Classify a skill that is already present under the pack skill's name:+ * - `ours` — the lock records it as installed from the OK skills repo (a+ * user-edited fork of ours still counts: forks are the intended model);+ * - `ours-retrofit` — no lock entry, but the bundle self-identifies as this+ * pack's (`metadata.pack`), i.e. seeded before provenance recording;+ * - `foreign` — a user-owned skill that happens to share the name (a foreign+ * import source, or no entry and no pack marker). Never clobbered; surfaced+ * as a name conflict instead of reading as "already seeded".+ * Fails toward `foreign`: the false outcome is a spurious warning, never a+ * clobbered user skill.+ */+export function classifyPresentPackSkill(+ packId: string,+ name: string,+ presentDir: string | null,+ lock: SkillsLock,+): 'ours' | 'ours-retrofit' | 'foreign' {+ const entry = lock.skills[name];+ if (entry) return isOpenKnowledgeSkillsSource(entry.source) ? 'ours' : 'foreign';+ if (presentDir) {+ try {+ const md = readFileSync(join(presentDir, 'SKILL.md'), 'utf-8');+ if (packIdFromSkillMd(md) === packId) return 'ours-retrofit';+ } catch {+ // unreadable — undecidable, fall through to foreign+ }+ }+ return 'foreign';+}++/**+ * `metadata.pack` from a SKILL.md's FRONTMATTER. Scoped to the frontmatter+ * block and to an indented (nested) key on purpose: matching the whole file+ * let any skill that merely documents a pack — a YAML snippet, a fenced+ * example — pass as OK's own bundle, and the retrofit verdict is what writes+ * `inkeep/open-knowledge-skills` provenance onto it, which is what a later+ * "Update from source" reimports over.+ */+function packIdFromSkillMd(md: string): string | null {+ const frontmatter = /^---\r?\n([\s\S]*?)\r?\n---(\r?\n|$)/.exec(md)?.[1];+ if (frontmatter === undefined) return null;+ return /^[ \t]+pack:[ \t]*"?([a-z0-9-]+)"?[ \t]*$/m.exec(frontmatter)?.[1] ?? null;+}++export async function installPackSkill(+ projectDir: string,+ packId: string,+): Promise<PackSkillInstallResult> {const sources = resolvePackSkillSources(packId);- if (sources.length === 0) return [];+ if (sources.length === 0) return { editors: [], conflicts: [] };// The editors ALREADY set up for this project — the platform `open-knowledge`// skill is present. Computed once; every pack skill projects into the same set.@@ -127,9 +192,34 @@ export async function installPackSkill(projectDir: string, packId: string): Prom// Resolved once per seed, not per skill — a pack can ship a dozen.const reportSettings = resolveSkillInstallReportSettings();const installed = new Set<string>();+// The scan (not any marker) is truth under the in-place model — one scan// covers the absent-check for every pack skill.- const existingNames = new Set(scanInPlaceSkills(projectDir).map((sk) => sk.name));+ const scan = scanInPlaceSkills(projectDir);+ const existingNames = new Set(scan.map((sk) => sk.name));+ // An install under the skill's OLD name is still this pack's skill. We do not+ // rename it: these are project-level skills, so the directory is normally+ // committed, and silently renaming something someone is already using turns up+ // as an unexplained diff for them and for everyone who pulls. It keeps working+ // as-is, updates resolve through the rename alias in the reimport selector,+ // and it counts as present here so seeding never authors a second copy of the+ // same skill beside it.+ // Keyed by the shipped (new) name, valued with the OLD name this project+ // actually holds — everything below addresses such a skill by the old name,+ // because that is the name on disk, in the lock, and in the editor dirs.+ const legacyNamed = new Map(+ sources+ .map(({ name }) => [name, OLD_PACK_SKILL_NAME[name]] as const)+ .filter(+ ([, oldName]) =>+ oldName !== undefined &&+ (existingNames.has(oldName) ||+ existsSync(join(projectDir, '.ok', 'skills', oldName, 'SKILL.md'))),+ ) as Iterable<readonly [string, string]>,+ );+ const scanDirByName = new Map(scan.map((sk) => [sk.name, join(projectDir, sk.dir)]));+ const lock = readSkillsLockFile(join(projectDir, ...SKILLS_LOCK_REL));+ const conflicts: PackSkillConflict[] = [];const homeRel = resolveDefaultSkillHomeRel(projectDir, 'project');// The default home can be an editor dir that SYMLINKS OUT of the project// (the escape class the projection guard refuses) — authoring through it@@ -140,14 +230,22 @@ export async function installPackSkill(projectDir: string, packId: string): Prom{ packId, homeRel },'default skill home escapes the project (symlinked out) — pack skills not installed',);- return [];+ return { editors: [], conflicts: [] };}// The editor whose root HOLDS the source loads it directly — it counts as// installed even though fan-out (rightly) skips the canonical's own root.const homeHost = (Object.entries(EDITOR_PROJECT_SKILL_ROOT) as [EditorId, string | null][]).find(([, root]) => root === homeRel,)?.[0];- for (const { name, sourceDir, excludeDirs } of sources) {+ for (const { name: shippedName, sourceDir, excludePaths } of sources) {+ // The name this PROJECT uses for the skill. An install predating the rename+ // keeps its old name forever, and it is the old name that is on disk,+ // keyed in the lock, and projected into the editor dirs — so address it that+ // way for presence, provenance, classification, conflicts and fan-out alike.+ // Addressing it by the shipped name instead would miss its lock entry (and+ // so misread it as a stranger's skill) and would skip fanning it into an+ // editor set up after the install.+ const name = legacyNamed.get(shippedName) ?? shippedName;// (1) Author the SOURCE in place at the project's default skill home —// the same landing every create/import uses (store retirement; the old// `.ok/skills` authoring rode the boot migration forever). Authored ONLY@@ -160,6 +258,28 @@ export async function installPackSkill(projectDir: string, packId: string): PromexistsSync(join(skillDir, 'SKILL.md')) ||existsSync(join(legacyStoreDir, 'SKILL.md'));const sourceHome = existsSync(join(legacyStoreDir, 'SKILL.md')) ? legacyStoreDir : skillDir;+ if (alreadyPresent) {+ const presentDir =+ scanDirByName.get(name) ??+ (existsSync(join(skillDir, 'SKILL.md'))+ ? skillDir+ : existsSync(join(legacyStoreDir, 'SKILL.md'))+ ? legacyStoreDir+ : null);+ const classification = classifyPresentPackSkill(packId, name, presentDir, lock);+ if (classification === 'foreign') {+ // The user's own skill holds this name. Installing would clobber it and+ // fanning out would project THEIR skill as if it were the pack's —+ // do neither; report the collision instead of "already seeded".+ conflicts.push({ name });+ continue;+ }+ if (classification === 'ours-retrofit' && presentDir) {+ // Ours from a pre-provenance seed: write the lock entry now so the+ // Update path works (the prefix-gated retrofit is dead for new names).+ recordPackSkillProvenance(projectDir, name, presentDir);+ }+ }if (!alreadyPresent) {try {tracedRmSync(skillDir, { recursive: true, force: true });@@ -168,7 +288,7 @@ export async function installPackSkill(projectDir: string, packId: string): Prom// installs as its own top-level skill, so filter them out of the root copy.tracedCpSync(sourceDir, skillDir, {recursive: true,- filter: (src) => !excludeDirs.some((dir) => src === join(sourceDir, dir)),+ filter: (src) => !excludePaths.some((p) => src === join(sourceDir, p)),});} catch (err) {// A real disk failure (EACCES / ENOSPC / I/O) — NOT the benign@@ -187,8 +307,13 @@ export async function installPackSkill(projectDir: string, packId: string): Prom// is nothing to fetch from the marketplace and the event is the only way// the listing reflects them. Inside the `!alreadyPresent` branch AND// deduped per machine by the reporter, so re-running seed reports nothing.+ // Scoped to the project: a starter pack seeded into a SECOND project is a+ // second install of that skill — it lands in that project's own editor+ // dirs — and must count. Machine-wide keying silently dropped every seed+ // after the first, which is not what "installs" means for a pack.+ // Re-seeding the same project still contributes nothing.void reportSkillInstall(- { source: OPENKNOWLEDGE_SKILLS_REPO, skills: [name] },+ { source: OPENKNOWLEDGE_SKILLS_REPO, skills: [name], scope: projectDir },{ home: reportSettings.home, enabled: reportSettings.enabled },);}@@ -213,10 +338,18 @@ export async function installPackSkill(projectDir: string, packId: string): Promfor (const id of fanned.hosts) {installed.add(PROJECT_SKILL_EDITOR_LABELS[id as EditorId] ?? id);}+ if (fanned.conflicted.length > 0) {+ // A host slot holds a DIFFERENT same-name dir — fan-out (rightly) left+ // it alone; surface it instead of discarding the signal.+ conflicts.push({+ name,+ hosts: fanned.conflicted.map((id) => PROJECT_SKILL_EDITOR_LABELS[id as EditorId] ?? id),+ });+ }if (homeHost !== undefined && setUpHosts.includes(homeHost)) {installed.add(PROJECT_SKILL_EDITOR_LABELS[homeHost] ?? homeHost);}}- return [...installed];+ return { editors: [...installed], conflicts };}diff --git a/packages/server/src/seed/okf-conformance.test.ts b/packages/server/src/seed/okf-conformance.test.tsindex c5dd3f8a0..250062900 100644--- a/packages/server/src/seed/okf-conformance.test.ts+++ b/packages/server/src/seed/okf-conformance.test.ts@@ -254,7 +254,7 @@ describe('okf pack — OKF §9 conformance by construction', () => {expect(result.packSkillsInstalled).toContain('Claude Code');// Every `.md` the pack installed under its skill dir must carry a non-empty `type`.- const packSkillDir = join(projectDir, '.claude', 'skills', 'open-knowledge-pack-okf');+ const packSkillDir = join(projectDir, '.claude', 'skills', 'okf-knowledge-base');const skillDocs = collectMarkdown(packSkillDir).map((p) => join(packSkillDir, p));expect(skillDocs.length).toBeGreaterThanOrEqual(1);for (const abs of skillDocs) {diff --git a/packages/server/src/seed/plan.test.ts b/packages/server/src/seed/plan.test.tsindex 98feef242..a06a3a889 100644--- a/packages/server/src/seed/plan.test.ts+++ b/packages/server/src/seed/plan.test.ts@@ -171,4 +171,70 @@ describe('planSeed — codebase-wiki nested paths', () => {expect(createdPaths.has('wiki/OVERVIEW.md')).toBe(true);expect(createdPaths.has('wiki/log.md')).toBe(true);});++ // Existing installs are never renamed, so the planner has to recognize a+ // pack skill sitting under its OLD name. Two ways this goes wrong: reporting+ // it pending (dry-run promises an install apply then declines), or classifying+ // it by the shipped name — whose lock key does not exist — and calling the+ // user's own skill a name collision.+ test('a pack skill installed under its old name reads as present, not pending, not conflicted', async () => {+ const oldName = 'open-knowledge-pack-plain-notes';+ const skillDir = join(projectDir, '.claude', 'skills', oldName);+ mkdirSync(skillDir, { recursive: true });+ writeFileSync(+ join(skillDir, 'SKILL.md'),+ `---\nname: ${oldName}\ndescription: "Plain notes."\nmetadata:\n pack: "plain-notes"\n---\n\nBody.\n`,+ 'utf-8',+ );++ const plan = await planSeed({ projectDir, packId: 'plain-notes' });++ const orientation = plan.packSkills?.find((s) => s.name === 'note-taking');+ expect(orientation).toBeDefined();+ expect(orientation?.pending).toBe(false);+ expect(orientation?.conflict).toBeUndefined();+ });++ // The update path rewrites frontmatter as {name, description}, dropping+ // `metadata.pack`. After one Update the ONLY remaining proof that a legacy+ // install is ours is its lock entry — which is keyed by the OLD name. Probe+ // the lock with the shipped name and it always misses, so a skill we authored+ // starts reporting as the user's own name collision, for a skill that exists+ // nowhere on disk.+ test('an updated legacy install (no metadata.pack) is still ours, via its old lock key', async () => {+ const oldName = 'open-knowledge-pack-plain-notes';+ const skillDir = join(projectDir, '.claude', 'skills', oldName);+ mkdirSync(skillDir, { recursive: true });+ writeFileSync(+ join(skillDir, 'SKILL.md'),+ `---\nname: ${oldName}\ndescription: "Plain notes."\n---\n\nBody.\n`,+ 'utf-8',+ );+ mkdirSync(join(projectDir, '.ok'), { recursive: true });+ writeFileSync(+ join(projectDir, '.ok', 'skills-lock.json'),+ `${JSON.stringify(+ {+ schema: 1,+ skills: {+ [oldName]: {+ source: 'inkeep/open-knowledge-skills',+ skill: oldName,+ contentHash: 'h',+ importedAt: '2026-01-01T00:00:00.000Z',+ },+ },+ },+ null,+ 2,+ )}\n`,+ 'utf-8',+ );++ const plan = await planSeed({ projectDir, packId: 'plain-notes' });++ const orientation = plan.packSkills?.find((s) => s.name === 'note-taking');+ expect(orientation?.pending).toBe(false);+ expect(orientation?.conflict).toBeUndefined();+ });});diff --git a/packages/server/src/seed/plan.ts b/packages/server/src/seed/plan.tsindex 990840a1b..e2ab71a1e 100644--- a/packages/server/src/seed/plan.ts+++ b/packages/server/src/seed/plan.ts@@ -1,9 +1,15 @@import { existsSync } from 'node:fs';import { join, resolve } from 'node:path';import { OK_PROJECT_MARKER } from '@inkeep/open-knowledge-core';+import { SKILLS_LOCK_REL } from '@inkeep/open-knowledge-core/skills-catalog';import { isProjectRoot } from '../fs/find-project-root.ts';import { scanInPlaceSkills } from '../in-place-skills.ts';-import { resolvePackSkillSources } from './install-pack-skill.ts';+import { readSkillsLockFile } from '../skills-lock-store.ts';+import {+ classifyPresentPackSkill,+ OLD_PACK_SKILL_NAME,+ resolvePackSkillSources,+} from './install-pack-skill.ts';import { assertEntryPathInProject } from './path-safety.ts';import { DEFAULT_PACK_ID, resolvePack, STARTER_FOLDER_FRONTMATTER_FILENAME } from './starter.ts';import type { FileEntry, ScaffoldPlan, SeedOptions, SkipEntry } from './types.ts';@@ -211,13 +217,43 @@ export async function planSeed(opts: SeedOptions = {}): Promise<ScaffoldPlan> {// `installPackSkill` dedups against), with the legacy `.ok/skills` store// still honored for pre-inversion projects.const sources = resolvePackSkillSources(pack.id);- const inPlaceNames =- sources.length > 0 ? new Set(scanInPlaceSkills(projectDir).map((sk) => sk.name)) : null;- const packSkills = sources.map(({ name }) => ({- name,- pending:- !inPlaceNames?.has(name) && !existsSync(join(projectDir, '.ok', 'skills', name, 'SKILL.md')),- }));+ const scan = sources.length > 0 ? scanInPlaceSkills(projectDir) : [];+ const inPlaceDirByName = new Map(scan.map((sk) => [sk.name, join(projectDir, sk.dir)]));+ const lock = sources.length > 0 ? readSkillsLockFile(join(projectDir, ...SKILLS_LOCK_REL)) : null;+ const packSkills = sources.map(({ name }) => {+ const storeDir = join(projectDir, '.ok', 'skills', name);+ // An install under the skill's OLD name is the same skill, kept under the+ // name its owner already knows (never renamed for them). `installPackSkill`+ // skips it, so the preview has to read it as present or dry-run promises an+ // install that apply declines.+ const legacyName = OLD_PACK_SKILL_NAME[name];+ const legacyDir =+ legacyName === undefined+ ? null+ : (inPlaceDirByName.get(legacyName) ??+ (existsSync(join(projectDir, '.ok', 'skills', legacyName, 'SKILL.md'))+ ? join(projectDir, '.ok', 'skills', legacyName)+ : null));+ const presentDir =+ inPlaceDirByName.get(name) ??+ legacyDir ??+ (existsSync(join(storeDir, 'SKILL.md')) ? storeDir : null);+ // Classify under the name the install actually HAS. A legacy install's lock+ // entry is keyed by its old name, so probing the lock with the shipped name+ // always misses and the verdict falls through to the frontmatter witness —+ // which the update path drops, at which point a skill that is provably ours+ // starts reporting as a stranger's name collision.+ const presentName =+ inPlaceDirByName.has(name) || legacyDir === null ? name : (legacyName as string);+ // A present same-named skill that is NOT ours by provenance is a name+ // collision, not "already seeded" — apply will skip it without clobbering,+ // so the preview must say so rather than show the pack as set up.+ const conflict =+ presentDir !== null &&+ lock !== null &&+ classifyPresentPackSkill(pack.id, presentName, presentDir, lock) === 'foreign';+ return { name, pending: presentDir === null, ...(conflict ? { conflict: true } : {}) };+ });return { created, skipped, warnings, ...(packSkills.length > 0 ? { packSkills } : {}) };}diff --git a/packages/server/src/seed/types.ts b/packages/server/src/seed/types.tsindex bedb35f35..3f09ac15a 100644--- a/packages/server/src/seed/types.ts+++ b/packages/server/src/seed/types.ts@@ -9,6 +9,17 @@import type { PackId } from './starter.ts';+/**+ * A pack skill the seed could not install because a user-owned skill already+ * holds the name (lock provenance says it is not ours). `hosts` carries+ * per-editor slot conflicts from fan-out when the whole-name case does not+ * apply. Conflicts are not errors: the seed still succeeds and never clobbers.+ */+export interface PackSkillConflict {+ name: string;+ hosts?: string[];+}+/*** A filesystem entry that the scaffolder will create on apply.*/@@ -54,8 +65,12 @@ export interface ScaffoldPlan {* when the skill source is absent from `.ok/skills/` and apply would (re)author* it. Folders/templates being present does NOT imply the skill is — so callers* must treat a pending skill as outstanding work, not "already set up".+ * `conflict` is true when a present same-named skill is NOT ours by lock+ * provenance (the user's own skill happens to share the name): apply will+ * neither install nor clobber it, and callers must surface it instead of+ * reading the pack as already set up.*/- packSkills?: { name: string; pending: boolean }[];+ packSkills?: { name: string; pending: boolean; conflict?: boolean }[];}/**@@ -77,6 +92,8 @@ export interface ApplyResult {* pack ships no skill.*/packSkillsInstalled: string[];+ /** Pack skills skipped because a user-owned same-named skill holds the name. */+ packSkillConflicts: PackSkillConflict[];}export interface ApplyError {diff --git a/packages/server/src/skill-install.ts b/packages/server/src/skill-install.tsindex c9d61b1ea..e629483a4 100644--- a/packages/server/src/skill-install.ts+++ b/packages/server/src/skill-install.ts@@ -769,5 +769,21 @@ export async function buildAndOpenSkill(}await report('installed', installedVersion);+ // Count the Claude Desktop / Cowork funnel. Reported at `installed` only —+ // the point where the file-association handoff actually succeeded — not on+ // `built`, where the file is merely sitting in Downloads. The final step+ // happens inside Claude Desktop's own installer, so this is the strongest+ // signal we can observe; the per-machine ledger keeps a repeat click from+ // counting twice. Machine-scoped: this bundle is installed once per machine.+ void reportSkillInstall(+ {+ source: OPENKNOWLEDGE_SKILLS_REPO,+ skills: [BUNDLE_SKILL_NAME.project],+ agents: ['claude-desktop'],+ global: true,+ version: installedVersion,+ },+ { home, enabled: resolveSkillInstallReportSettings(home).enabled },+ );return { ...baseResult, status: 'installed' };}diff --git a/packages/server/src/skill-pack-sources.test.ts b/packages/server/src/skill-pack-sources.test.tsindex 18bb9edff..02df397bb 100644--- a/packages/server/src/skill-pack-sources.test.ts+++ b/packages/server/src/skill-pack-sources.test.ts@@ -10,40 +10,34 @@ import { enumeratePackSkills } from './skill-pack-sources.ts';const PACKS_DIR = join(dirname(fileURLToPath(import.meta.url)), '..', 'assets', 'skills', 'packs');describe('enumeratePackSkills', () => {- test('a flat pack ships exactly one skill, named for the pack', () => {- const skills = enumeratePackSkills('plain-notes', join(PACKS_DIR, 'plain-notes'));- expect(skills.map((s) => s.name)).toEqual(['open-knowledge-pack-plain-notes']);- expect(skills[0]?.excludeDirs).toEqual([]);+ test('a flat pack ships exactly one skill, named by its frontmatter', () => {+ const skills = enumeratePackSkills(join(PACKS_DIR, 'plain-notes'));+ expect(skills.map((s) => s.name)).toEqual(['note-taking']);+ expect(skills[0]?.excludePaths).toEqual(['README.md']);});test('a decomposed pack ships its root skill first, then one skill per member dir', () => {- const skills = enumeratePackSkills('software-lifecycle', join(PACKS_DIR, 'software-lifecycle'));+ const skills = enumeratePackSkills(join(PACKS_DIR, 'software-lifecycle'));expect(skills.map((s) => s.name)).toEqual([- 'open-knowledge-pack-software-lifecycle',- 'open-knowledge-pack-software-lifecycle-frame-a-proposal',- 'open-knowledge-pack-software-lifecycle-record-a-decision',- 'open-knowledge-pack-software-lifecycle-review-a-design',- 'open-knowledge-pack-software-lifecycle-write-a-postmortem',- 'open-knowledge-pack-software-lifecycle-write-a-spec',+ 'software-lifecycle',+ 'frame-a-proposal',+ 'record-a-decision',+ 'review-a-design',+ 'write-a-postmortem',+ 'write-a-spec',]);});test('the root skill excludes its member dirs; members exclude nothing', () => {- const [root, ...members] = enumeratePackSkills(- 'knowledge-base',- join(PACKS_DIR, 'knowledge-base'),- );- expect(root?.excludeDirs).toEqual(['consolidate', 'research']);- expect(members.map((m) => m.excludeDirs)).toEqual([[], []]);+ const [root, ...members] = enumeratePackSkills(join(PACKS_DIR, 'knowledge-base'));+ expect(root?.excludePaths).toEqual(['consolidate', 'research', 'README.md']);+ expect(members.map((m) => m.excludePaths)).toEqual([[], []]);// `references/` holds no SKILL.md, so it stays with the skill that owns it// rather than being mistaken for a member.- expect(members.map((m) => m.name)).toEqual([- 'open-knowledge-pack-knowledge-base-consolidate',- 'open-knowledge-pack-knowledge-base-research',- ]);+ expect(members.map((m) => m.name)).toEqual(['consolidate-notes', 'research-with-sources']);});test('a directory with no SKILL.md anywhere ships no skill', () => {- expect(enumeratePackSkills('nope', join(PACKS_DIR, 'does-not-exist'))).toEqual([]);+ expect(enumeratePackSkills(join(PACKS_DIR, 'does-not-exist'))).toEqual([]);});});diff --git a/packages/server/src/skill-pack-sources.ts b/packages/server/src/skill-pack-sources.tsindex 9c9544ad2..43a202daa 100644--- a/packages/server/src/skill-pack-sources.ts+++ b/packages/server/src/skill-pack-sources.ts@@ -4,21 +4,24 @@* A pack dir is one of two shapes, and both are supported everywhere a pack* skill is resolved (install, seed plan, dist composition, update detection):*- * packs/plain-notes/SKILL.md → one skill, `open-knowledge-pack-plain-notes`+ * packs/plain-notes/SKILL.md → one skill*- * packs/software-lifecycle/SKILL.md → `open-knowledge-pack-software-lifecycle`- * packs/software-lifecycle/write-a-spec/SKILL.md → `…-software-lifecycle-write-a-spec`+ * packs/software-lifecycle/SKILL.md → the pack's orientation skill+ * packs/software-lifecycle/write-a-spec/SKILL.md → one member skill** A member skill is any immediate subdirectory holding its own `SKILL.md`;* `references/` and friends carry no `SKILL.md` and stay with the owning skill.- * Skill name == leaf directory name in every install target, per the Agent Skills- * standard, so the root skill's copy must EXCLUDE the member dirs (`excludeDirs`)- * or a member would ship twice, nested inside its parent.+ * Skill names come from SKILL.md frontmatter — the single naming authority,+ * shared with the public-mirror projection (`deriveSkillMoves` reads the same+ * `name:` line), so the public directory name and the install target cannot+ * diverge. Skill name == leaf directory name in every install target, per the+ * Agent Skills standard, so the root skill's copy must EXCLUDE the member dirs+ * and the pack-level `README.md` (`excludePaths`) or they would ship inside+ * the installed root skill.*/-import { type Dirent, existsSync, readdirSync } from 'node:fs';-import { join } from 'node:path';-import { PACK_SKILL_PREFIX } from '@inkeep/open-knowledge-core';+import { type Dirent, existsSync, readdirSync, readFileSync } from 'node:fs';+import { basename, join } from 'node:path';import { type ResolveBundledSkillDirOptions, resolveBundledSkillDir } from './build-skill-zip.ts';export interface PackSkillSource {@@ -26,10 +29,11 @@ export interface PackSkillSource {readonly name: string;readonly sourceDir: string;/**- * Subdirectories of `sourceDir` that are member skills in their own right —- * omit them when copying this skill. Empty for member skills themselves.+ * Entries of `sourceDir` that must not ship with this skill's copy: member+ * skill dirs (skills in their own right) and the pack-level README. Empty+ * for member skills themselves.*/- readonly excludeDirs: readonly string[];+ readonly excludePaths: readonly string[];}/** Immediate subdirectories of `packDir` that hold their own `SKILL.md`. */@@ -46,22 +50,33 @@ function memberDirNames(packDir: string): string[] {.sort();}+/** Frontmatter `name:`, falling back to the leaf dir name (Agent Skills standard). */+function frontmatterName(skillDir: string): string {+ let md: string;+ try {+ md = readFileSync(join(skillDir, 'SKILL.md'), 'utf8');+ } catch {+ return basename(skillDir);+ }+ return /^name:[ \t]*(\S+)[ \t]*$/m.exec(md)?.[1] ?? basename(skillDir);+}+/** Pure enumeration over an already-resolved pack directory. */-export function enumeratePackSkills(packId: string, packDir: string): PackSkillSource[] {+export function enumeratePackSkills(packDir: string): PackSkillSource[] {const members = memberDirNames(packDir);const sources: PackSkillSource[] = [];if (existsSync(join(packDir, 'SKILL.md'))) {sources.push({- name: `${PACK_SKILL_PREFIX}${packId}`,+ name: frontmatterName(packDir),sourceDir: packDir,- excludeDirs: members,+ excludePaths: [...members, 'README.md'],});}for (const member of members) {sources.push({- name: `${PACK_SKILL_PREFIX}${packId}-${member}`,+ name: frontmatterName(join(packDir, member)),sourceDir: join(packDir, member),- excludeDirs: [],+ excludePaths: [],});}return sources;@@ -82,5 +97,5 @@ export function listPackSkillSources(} catch {return [];}- return enumeratePackSkills(packId, packDir);+ return enumeratePackSkills(packDir);}diff --git a/packages/server/src/skill-projection.test.ts b/packages/server/src/skill-projection.test.tsindex bfd6e4a21..2e52ac8f1 100644--- a/packages/server/src/skill-projection.test.ts+++ b/packages/server/src/skill-projection.test.ts@@ -76,12 +76,17 @@ describe('validateSkillForInstall', () => {).toBe(true);});- test('allows open-knowledge-pack-* (shipped pack skills) to reinstall', () => {- const name = 'open-knowledge-pack-knowledge-base';- const dir = makeSkill(name, '# x', `name: ${name}\ndescription: d`);- // Pack skills sit under the reserved prefix but are OK's own shipped content,- // so a user-triggered (re)install must not be blocked by the reserved guard.- expect(validateSkillForInstall(dir, name).ok).toBe(true);+ test('the exact LEGACY pack names stay installable; unknown pack-prefixed names stay rejected', () => {+ // Existing installs are never renamed, so every pre-rename install+ // keeps its reserved-prefix name indefinitely — add-to-host/repair for+ // those must keep working.+ const legacy = 'open-knowledge-pack-knowledge-base';+ const legacyDir = makeSkill(legacy, '# x', `name: ${legacy}\ndescription: d`);+ expect(validateSkillForInstall(legacyDir, legacy).ok).toBe(true);+ // Anything else under the prefix is still reserved.+ const unknown = 'open-knowledge-pack-something-else';+ const unknownDir = makeSkill(unknown, '# x', `name: ${unknown}\ndescription: d`);+ expect(validateSkillForInstall(unknownDir, unknown).ok).toBe(false);});test('rejects name != frontmatter.name and XML tags + missing frontmatter', () => {diff --git a/packages/server/src/skill-projection.ts b/packages/server/src/skill-projection.tsindex 692ea5ab7..0cb2e952f 100644--- a/packages/server/src/skill-projection.ts+++ b/packages/server/src/skill-projection.ts@@ -33,8 +33,8 @@ import {EDITOR_PROJECT_SKILL_ROOT,EDITOR_USER_SKILL_ROOT,type EditorId,- PACK_SKILL_PREFIX,PROJECT_SKILL_EDITOR_IDS,+ RENAMED_PACK_SKILLS,} from '@inkeep/open-knowledge-core';import type { SkillHostId } from '@inkeep/open-knowledge-core/skills-catalog';import { parse as parseYaml } from 'yaml';@@ -102,8 +102,11 @@ export interface SkillValidity {* Pre-install validity gate. A source that fails MUST NOT be projected —* a conflicted or malformed SKILL.md landing verbatim in an agent's live* context is the failure mode this guards. `allowReservedName` is set only for- * OK's own shipped `open-knowledge` bundle; `open-knowledge-pack-*` skills are- * exempt by name (they're shipped pack content, installable + reinstallable).+ * OK's own shipped `open-knowledge` bundle. Pack skills carry unreserved short+ * names since the marketplace rename; the exact LEGACY old names (keys of+ * `RENAMED_PACK_SKILLS`) stay installable because existing installs are never+ * renamed — EVERY pre-rename install keeps its old reserved-prefix name+ * indefinitely, not just forks, and must remain add-to-host/repairable.*/export function validateSkillForInstall(skillDir: string,@@ -117,7 +120,7 @@ export function validateSkillForInstall(existsSync(join(skillDir, 'scripts')) && statSync(join(skillDir, 'scripts')).isDirectory();const usesReservedName =- name.startsWith(RESERVED_SKILL_PREFIX) && !name.startsWith(PACK_SKILL_PREFIX);+ name.startsWith(RESERVED_SKILL_PREFIX) && RENAMED_PACK_SKILLS[name] === undefined;if (!opts?.allowReservedName && usesReservedName) {errors.push(`"${name}" uses the reserved \`${RESERVED_SKILL_PREFIX}*\` prefix (reserved for OK's shipped skills) — choose another name.`,diff --git a/packages/server/src/skill-state.test.ts b/packages/server/src/skill-state.test.tsindex 820016982..50681400c 100644--- a/packages/server/src/skill-state.test.ts+++ b/packages/server/src/skill-state.test.ts@@ -15,8 +15,10 @@ import { dirname, join } from 'node:path';import { fileURLToPath } from 'node:url';import { describe, expect, test } from 'vitest';import {+ clearInstallReported,readAllTargets,readBundleDecision,+ readInstallReported,readServerPackageVersion,readSkillInstallStateSnapshot,readTargetRecordedAt,@@ -24,6 +26,7 @@ import {resolveBundleEnabled,skillStateYamlPath,writeBundleDecision,+ writeInstallReported,writeTargetVersion,} from './skill-state.ts';@@ -301,3 +304,31 @@ describe('readAllTargets / readSkillInstallStateSnapshot', () => {expect(snapshot.targets['cli-hosts']).toBeNull();});});++describe('clearInstallReported', () => {+ // The ledger is claimed BEFORE the report is sent, so releasing a claim is the+ // only way a delivered rejection ever gets retried. These cover the defensive+ // branches the integration path never reaches.+ test('removes a claimed key so it reports again', async () => {+ const home = freshHome();+ await writeInstallReported(home, ['o/r#a', 'o/r#b']);+ await clearInstallReported(home, ['o/r#a']);+ expect([...(await readInstallReported(home))]).toEqual(['o/r#b']);+ });++ test('removing a key that was never claimed leaves the ledger untouched', async () => {+ const home = freshHome();+ await writeInstallReported(home, ['o/r#a']);+ await clearInstallReported(home, ['o/r#missing']);+ expect([...(await readInstallReported(home))]).toEqual(['o/r#a']);+ });++ test('an empty key list and an absent ledger are both no-ops, not throws', async () => {+ const home = freshHome();+ // Absent file: a clean machine must not fail an install over bookkeeping.+ await expect(clearInstallReported(home, ['o/r#a'])).resolves.toBeUndefined();+ await writeInstallReported(home, ['o/r#a']);+ await expect(clearInstallReported(home, [])).resolves.toBeUndefined();+ expect([...(await readInstallReported(home))]).toEqual(['o/r#a']);+ });+});diff --git a/packages/server/src/skill-state.ts b/packages/server/src/skill-state.tsindex de3c0a8d9..2c7bbbad2 100644--- a/packages/server/src/skill-state.ts+++ b/packages/server/src/skill-state.ts@@ -381,6 +381,35 @@ export async function writeInstallReported(});}+/**+ * Release previously-claimed report keys so a later run reports them again.+ *+ * The inverse of `writeInstallReported`, and deliberately NOT a general undo for+ * a failed send. Claim-first exists so an AMBIGUOUS outcome (a dropped request+ * that may or may not have reached the collector) under-counts rather than+ * double-counts. Only a DELIVERED rejection is unambiguous: the collector saw+ * the event and declined it, so nothing was counted and re-reporting cannot+ * double-count. That is the one case a caller may un-claim.+ *+ * Same lock as the append path, and it removes only the named keys, so a+ * concurrent install's claims survive.+ */+export async function clearInstallReported(+ home: string,+ keys: readonly string[],+ logger?: SkillStateLogger,+): Promise<void> {+ if (keys.length === 0) return;+ await withSkillStateWriteLock(home, async () => {+ const existing = await readSkillStateFile(home, logger);+ if (!existing?.installsReported?.length) return;+ const drop = new Set(keys);+ const kept = existing.installsReported.filter((k) => !drop.has(k));+ if (kept.length === existing.installsReported.length) return;+ await writeSkillStateFile(home, { ...existing, installsReported: kept });+ });+}+/*** Canonical skill version: the `version` field of* `@inkeep/open-knowledge-server`'s `package.json`. Exposed to the rendererdiff --git a/packages/server/src/skills-sh-install-report.test.ts b/packages/server/src/skills-sh-install-report.test.tsindex 50016894b..cf5208a07 100644--- a/packages/server/src/skills-sh-install-report.test.ts+++ b/packages/server/src/skills-sh-install-report.test.ts@@ -120,6 +120,147 @@ describe('reportSkillInstall', () => {),).resolves.toEqual(['x']);});++ // A rejected report (unknown-skill 4xx while a fresh listing indexes, a+ // collector 5xx) is DELIVERED but not counted. Unlike a dropped send, that+ // outcome is unambiguous, so the claim is released and a later run reports it+ // again — otherwise the installs a rename is measured by are discarded during+ // the exact window the collector is meeting every new name for the first time.+ test('a non-2xx collector response releases the claim so a later run retries', async () => {+ const home = freshHome();+ const rejecting = (async () => ({ ok: false, status: 404 })) as unknown as typeof fetch;+ // Nothing was counted, so nothing is reported back to the caller.+ await expect(+ reportSkillInstall(+ { source: 'o/r', skills: ['x'] },+ { home, ...ENABLED, fetchImpl: rejecting },+ ),+ ).resolves.toEqual([]);+ // The claim is gone, so the next run sends it again.+ const { calls, impl } = recordingFetch();+ await expect(+ reportSkillInstall({ source: 'o/r', skills: ['x'] }, { home, ...ENABLED, fetchImpl: impl }),+ ).resolves.toEqual(['x']);+ expect(calls).toHaveLength(1);+ });++ // The counterpart contract: an AMBIGUOUS failure keeps its claim. A dropped+ // request may have reached the collector and had only its response lost, so+ // retrying could inflate someone's public install count. Under-count once+ // rather than double-count.+ test('a dropped send keeps its claim and is never retried', async () => {+ const home = freshHome();+ const dropping = (async () => {+ throw new Error('network down');+ }) as unknown as typeof fetch;+ await reportSkillInstall(+ { source: 'o/r', skills: ['x'] },+ { home, ...ENABLED, fetchImpl: dropping },+ );+ const { calls, impl } = recordingFetch();+ await reportSkillInstall(+ { source: 'o/r', skills: ['x'] },+ { home, ...ENABLED, fetchImpl: impl },+ );+ expect(calls).toEqual([]);+ });++ // The collector is a serverless function behind an edge: a 5xx or 429 can be+ // synthesized AFTER the origin recorded the event, so it is ambiguous exactly+ // like a dropped send. Only an application-level rejection proves nothing was+ // counted and is therefore safe to retry.+ test('a 503 keeps its claim; a 404 releases it', async () => {+ const statusFetch = (status: number) =>+ (async () => ({ ok: false, status })) as unknown as typeof fetch;++ const ambiguous = freshHome();+ await reportSkillInstall(+ { source: 'o/r', skills: ['x'] },+ { home: ambiguous, ...ENABLED, fetchImpl: statusFetch(503) },+ );+ const after503 = recordingFetch();+ await reportSkillInstall(+ { source: 'o/r', skills: ['x'] },+ { home: ambiguous, ...ENABLED, fetchImpl: after503.impl },+ );+ expect(after503.calls).toEqual([]);++ const rejected = freshHome();+ await reportSkillInstall(+ { source: 'o/r', skills: ['x'] },+ { home: rejected, ...ENABLED, fetchImpl: statusFetch(404) },+ );+ const after404 = recordingFetch();+ await reportSkillInstall(+ { source: 'o/r', skills: ['x'] },+ { home: rejected, ...ENABLED, fetchImpl: after404.impl },+ );+ expect(after404.calls).toHaveLength(1);+ });+});++describe('reportSkillInstall — scope', () => {+ // THE privacy assertion. The changeset promises the project path "is used only+ // as a local key and is never sent". Nothing else stops a future edit to the+ // params builder from shipping a user's home-directory path to the collector.+ test('the project path never reaches the request', async () => {+ const { calls, impl } = recordingFetch();+ await reportSkillInstall(+ { source: 'o/r', skills: ['x'], scope: '/Users/someone/private-project' },+ { home: freshHome(), ...ENABLED, fetchImpl: impl },+ );+ expect(calls).toHaveLength(1);+ expect(calls[0]).not.toContain('private-project');+ expect(calls[0]).not.toContain('/Users/');+ expect(calls[0]).not.toContain('scope');+ });++ test('the same scope twice reports once', async () => {+ const home = freshHome();+ const first = recordingFetch();+ await reportSkillInstall(+ { source: 'o/r', skills: ['x'], scope: '/p/one' },+ { home, ...ENABLED, fetchImpl: first.impl },+ );+ expect(first.calls).toHaveLength(1);+ const second = recordingFetch();+ await reportSkillInstall(+ { source: 'o/r', skills: ['x'], scope: '/p/one' },+ { home, ...ENABLED, fetchImpl: second.impl },+ );+ expect(second.calls).toEqual([]);+ });++ test('a different scope reports again — a second project is a second install', async () => {+ const home = freshHome();+ await reportSkillInstall(+ { source: 'o/r', skills: ['x'], scope: '/p/one' },+ { home, ...ENABLED, fetchImpl: recordingFetch().impl },+ );+ const other = recordingFetch();+ await reportSkillInstall(+ { source: 'o/r', skills: ['x'], scope: '/p/two' },+ { home, ...ENABLED, fetchImpl: other.impl },+ );+ expect(other.calls).toHaveLength(1);+ });++ // Machine-wide and project-scoped keys must not collide: the built-in bundles+ // are reported unscoped, and a project install of the same name is a separate+ // event, not a duplicate of it.+ test('a scoped key is independent of the unscoped one', async () => {+ const home = freshHome();+ await reportSkillInstall(+ { source: 'o/r', skills: ['x'] },+ { home, ...ENABLED, fetchImpl: recordingFetch().impl },+ );+ const scoped = recordingFetch();+ await reportSkillInstall(+ { source: 'o/r', skills: ['x'], scope: '/p/one' },+ { home, ...ENABLED, fetchImpl: scoped.impl },+ );+ expect(scoped.calls).toHaveLength(1);+ });});describe('reportSkillInstall — stays silent', () => {diff --git a/packages/server/src/skills-sh-install-report.ts b/packages/server/src/skills-sh-install-report.tsindex 6d73f38df..3d44b457f 100644--- a/packages/server/src/skills-sh-install-report.ts+++ b/packages/server/src/skills-sh-install-report.ts@@ -25,14 +25,24 @@* timeout; a dead network is not an install error.*/+import { realpathSync } from 'node:fs';import { getLogger } from './logger.ts';-import { readInstallReported, writeInstallReported } from './skill-state.ts';+import { clearInstallReported, readInstallReported, writeInstallReported } from './skill-state.ts';/** The `skills` CLI's telemetry collector. Same endpoint, same query shape. */const TELEMETRY_URL = 'https://add-skill.vercel.sh/t';const REPORT_TIMEOUT_MS = 3000;+/**+ * Statuses that prove the COLLECTOR APPLICATION saw the event and declined it,+ * so nothing was counted and re-reporting later cannot double-count. Everything+ * else a non-2xx can be — 5xx and 429 from a serverless platform, 403 from an+ * edge WAF — may have been issued after the origin already recorded the event,+ * so those keep their claim.+ */+const RETRYABLE_REJECTION_STATUSES: ReadonlySet<number> = new Set([400, 404, 410, 422]);+/*** `owner/repo` — the only source shape we report. Deliberately NOT a general* URL matcher: a git URL can carry credentials, and a local path is nobody's@@ -94,6 +104,39 @@ export interface SkillInstallReport {global?: boolean;/** OK version, sent as the client version so the receiver can tell us apart. */version?: string;+ /**+ * Dedupe scope. Absent means machine-wide: the skill is installed once per+ * machine (the user-global bundles), so a re-init or a launch reclaim must+ * contribute nothing. Present means the install is PER-PROJECT — each project+ * gets its own copy of the skill in its own editor dirs — so the ledger keys+ * by project and a genuinely new project counts, while re-running init or+ * re-seeding the SAME project still contributes nothing.+ *+ * Local only: this never leaves the machine. It keys the ledger; the payload+ * sent to the collector is unchanged.+ */+ scope?: string;+}++/**+ * Ledger key: machine-wide by default, per-project when the report is scoped.+ *+ * The scope is canonicalized because callers disagree about it: `ok init`+ * reports the un-realpath'd cwd for a project that has no `.ok/` yet and the+ * realpath'd root afterwards, while the desktop always realpaths. Any project+ * reached through a symlinked ancestor (`/tmp` → `/private/tmp`, a `~/code`+ * symlink) would otherwise claim two different keys for one project and count+ * the same install twice. Local-only, so canonicalizing costs nothing.+ */+function ledgerKey(report: SkillInstallReport, skill: string): string {+ if (report.scope === undefined) return `${report.source}#${skill}`;+ let scope = report.scope;+ try {+ scope = realpathSync(scope);+ } catch {+ // Not on disk (yet, or ever) — the raw string is still a stable key.+ }+ return `${report.source}#${skill}@${scope}`;}export interface ReportSkillInstallDeps {@@ -142,7 +185,7 @@ export async function reportSkillInstall();return new Set<string>();});- const fresh = report.skills.filter((s) => !alreadyReported.has(`${report.source}#${s}`));+ const fresh = report.skills.filter((s) => !alreadyReported.has(ledgerKey(report, s)));if (fresh.length === 0) return [];const params = new URLSearchParams({@@ -169,7 +212,7 @@ export async function reportSkillInstall(try {await writeInstallReported(deps.home,- fresh.map((s) => `${report.source}#${s}`),+ fresh.map((s) => ledgerKey(report, s)),);} catch (err) {// No claim, no send. Reporting anyway would leave nothing on disk to@@ -182,12 +225,57 @@ export async function reportSkillInstall(}try {- await fetchImpl(`${TELEMETRY_URL}?${params.toString()}`, {+ const res = await fetchImpl(`${TELEMETRY_URL}?${params.toString()}`, {signal: AbortSignal.timeout(REPORT_TIMEOUT_MS),});+ // Only an APPLICATION rejection proves nothing was counted: the collector+ // parsed the event and declined it (an unknown-skill 4xx while a freshly+ // renamed listing is still being indexed). Releasing the claim there cannot+ // double-count, and a later run reports it again once the listing resolves+ // — which matters most right after a rename, when the collector meets every+ // new name for the first time and a permanent claim would silently discard+ // exactly the installs the rename is measured by.+ //+ // Every other non-2xx is AMBIGUOUS and keeps its claim. The collector is a+ // serverless function behind an edge: 502/504 are synthesized by the+ // platform and can fire AFTER the origin recorded the event, 429 can be+ // issued post-increment, and a WAF 403 never reaches the function at all.+ // Releasing on those re-reports something already counted, which inflates a+ // public number — the one direction this module must never err in.+ if (!res.ok && RETRYABLE_REJECTION_STATUSES.has(res.status)) {+ getLogger('skills').warn(+ { status: res.status, source: report.source, skills: fresh },+ 'skill install report rejected by the collector; releasing the claim to retry later',+ );+ await clearInstallReported(+ deps.home,+ fresh.map((s) => ledgerKey(report, s)),+ ).catch((err: unknown) => {+ // The claim stays, so this install is simply never retried — the old+ // behavior. Logged so a stuck counter is traceable to the ledger.+ // Carries the status that triggered the release attempt: the two warns+ // can interleave under load, so this one has to stand on its own.+ getLogger('skills').warn(+ { err, status: res.status, source: report.source, skills: fresh },+ 'could not release the install-report claim; this install will not be retried',+ );+ });+ return [];+ }+ if (!res.ok) {+ // Ambiguous rejection (5xx, 429, 403, 408): the event may already have+ // been counted upstream, so the claim stays and this install is simply+ // never retried — under-counting once beats inflating a public count.+ getLogger('skills').warn(+ { status: res.status, source: report.source, skills: fresh },+ 'skill install report rejected with an ambiguous status; keeping the claim so a counted install cannot be double-reported',+ );+ }} catch (err) {- // A dead network is not an install error, and by the contract above this- // one is simply not counted. Logged rather than swallowed: on a machine+ // A dead network is not an install error. Unlike the delivered-rejection+ // branch above, this outcome is AMBIGUOUS — the request may have reached the+ // collector and had its response lost — so the claim is deliberately kept:+ // under-counting once beats double-counting someone's public install count. Logged rather than swallowed: on a machine// that blocks the collector this fires on every install, and a silent// catch makes "why is our count flat" undiagnosable.getLogger('skills').warn(