Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

Support LM Studio's Agent Skills, and offer the .agents hub (#3941)

tim-inkeep38211cf406b1
diff --git a/.changeset/lm-studio-agent-skills.md b/.changeset/lm-studio-agent-skills.md
new file mode 100644
index 000000000..4d034d407
--- /dev/null
+++ b/.changeset/lm-studio-agent-skills.md
@@ -0,0 +1,5 @@
+---
+"@inkeep/open-knowledge": patch
+---
+
+OpenKnowledge's user-global skills now install for LM Studio. LM Studio reads Agent Skills from `~/.lmstudio/skills`, listed as **Bionic Skills** in its agent mode, but OpenKnowledge treated it as an MCP-only host, so skills were never written there and the Skills panel never listed anything installed under it. Installing a tool that reads the shared `.agents/skills` folder now makes that folder available as a skill destination. Two tools read it: **LM Studio** reads it for project skills rather than a `.lmstudio/` folder, and **OpenClaw** reads it at user scope, so an OpenClaw user will see a `~/.agents/skills` row appear too. OpenKnowledge previously offered the folder only once a project already used it, so the only way to make the first placement was to type the path into Add custom path. The folder stays neutral: it appears because something on your machine reads it, is never preselected, and carries no per-tool marks. It is offered as a destination but not as a merge target until it exists, so accepting an offer never creates the folder behind your back or relocates skills into it. With neither tool installed, nothing changes.
diff --git a/docs/content/integrations/lm-studio.mdx b/docs/content/integrations/lm-studio.mdx
index b38b16a47..fe6f77ddc 100644
--- a/docs/content/integrations/lm-studio.mdx
+++ b/docs/content/integrations/lm-studio.mdx
@@ -24,6 +24,24 @@ After `ok init` writes the config, open LM Studio's **Program** tab and enable t
MCP tools only work when the chat model can call functions, and small local models vary a lot in how reliably they do. For the best results, load a model with strong tool-use / function-calling support and enough context to hold OK's tool descriptions. If the model answers in prose instead of calling `exec` / `search` / `write`, it either doesn't support tools or the server isn't enabled — check both before assuming OpenKnowledge is misconfigured.
+## Two surfaces: chat and agent mode
+
+LM Studio has a chat and an agent mode, and what OpenKnowledge gives you differs between them.
+
+The MCP server is app-wide, so `ok init` wires up both at once and the tools are there either way. **Agent Skills exist only in agent mode.** In chat you get the tools on their own. In agent mode you also get whatever skills are installed — which by default is the discovery skill, not the read/write contract; see [Agent contract](#agent-contract) below for what that means in practice.
+
+If you plan to have a model read and write a knowledge base rather than answer one-off questions, use agent mode.
+
+## Skills
+
+Agent mode reads your skills from `~/.lmstudio/skills`, where OpenKnowledge's user-global skills install like they do for any other tool. They show up under **Bionic Skills** in LM Studio's skills settings, available across all projects.
+
+For a project, LM Studio reads `.agents/skills` in the project's working directory rather than a `.lmstudio/` folder. That folder is shared ground rather than LM Studio's own, so OpenKnowledge offers it as a destination once it can see LM Studio installed, and never picks it for you: choose **`.agents`** when you install a project skill and LM Studio will find it. Nothing lands there until you choose it, and LM Studio does not create the folder itself.
+
+The folder also appears in **Settings → Skills → Folders**, where it can be linked once it exists. Until then it is a destination only — OpenKnowledge will not create it by merging another tool's folder into it.
+
+LM Studio can also read other tools' skill folders (`~/.claude/skills`, `~/.agents/skills`, `~/.cursor/skills` and more), listed under **Use skills found in other apps**. Those are off by default, and turning one on imports everything in that folder, not just OpenKnowledge's skills.
+
## Verify
Load a tool-capable model, open a knowledge base, and ask:
@@ -32,6 +50,15 @@ Load a tool-capable model, open a knowledge base, and ask:
If the model doesn't call the tool, confirm the `open-knowledge` server is toggled on in the **Program** tab and that the loaded model supports tool use.
+## Agent contract
+
+The **OpenKnowledge skill** — the authoritative agent contract for tool use, grounding, and linking — is project-scoped. What installs into `~/.lmstudio/skills` by default is the discovery skill; skill authoring is available alongside it. Between them they cover what OpenKnowledge is, how to open and install it, and how to write a skill, and deliberately do not carry the in-project read/write contract. LM Studio can receive that contract, but only through the `.agents` route above, so until you install a project skill there the contract for LM Studio is these two reminders:
+
+- **Markdown is MCP-owned.** Inside an OK project, read and write `.md` / `.mdx` through OK's tools (`exec`, `search`, `write`, `edit`, `links`), not native shell or file tools — native access loses attribution and skips the frontmatter, backlinks, and history OK returns. This matters most in agent mode, where the model can run shell commands in your project folder.
+- **Discover before concluding the MCP is missing.** Not seeing `exec` in the initial tool list isn't the escape hatch; reload the MCP servers first.
+
+For the complete tool surface, see the [MCP reference](/docs/reference/mcp).
+
## Troubleshooting
| Symptom | Cause | Fix |
@@ -39,7 +66,7 @@ If the model doesn't call the tool, confirm the `open-knowledge` server is toggl
| `ok init` showed LM Studio as `config root missing; skipped` | LM Studio's config dir doesn't exist yet, so it wasn't detected | Launch LM Studio once (it creates its config dir), then re-run `ok init` |
| `ok init` reported the config was `left unchanged` | OpenKnowledge declined to edit `mcp.json` for the reason shown in parentheses | Fix what the reason names (invalid JSON, a duplicated server block, an oversize config), then re-run `ok init` |
| Model answers in prose, never calls a tool | the loaded model doesn't support tool use, or the server is disabled | Load a tool-capable model and enable `open-knowledge` in the **Program** tab |
-| MCP call fails with `... exceeds the available context size ...` (400) | OpenKnowledge's MCP tools + skill are larger than a small local model's context window (e.g. 8K tokens), so the request can't fit | Load the model with the largest context window it supports (or pick a bigger model). If that still isn't enough, [open an issue](https://github.com/inkeep/open-knowledge/issues) or reach out — trimming the tool surface for small local models is on our radar. |
+| MCP call fails with `... exceeds the available context size ...` (400) | OpenKnowledge's MCP tool surface is larger than a small local model's context window (e.g. 8K tokens), so the request can't fit | Load the model with the largest context window it supports (or pick a bigger model). If that still isn't enough, [open an issue](https://github.com/inkeep/open-knowledge/issues) or reach out — trimming the tool surface for small local models is on our radar. |
| `write` / `edit` -> "Hocuspocus server is not running" | OK server not started | Run `ok start` (or leave the desktop app running) and retry |
New to OpenKnowledge itself? Start with the [quickstart](/docs/get-started/quickstart) for `ok init` and `ok start`.
diff --git a/docs/content/integrations/openclaw.mdx b/docs/content/integrations/openclaw.mdx
index eb03e4d0b..4e920c48a 100644
--- a/docs/content/integrations/openclaw.mdx
+++ b/docs/content/integrations/openclaw.mdx
@@ -119,6 +119,12 @@ One practical constraint: a vendor cannot POST to `127.0.0.1`. Keep hook endpoin
Write and edit responses include a route-only preview path like `/#/notes/mcp-round-trip` — a route id, **not** a full URL. Call `preview_url` for the openable browser address, and don't screenshot the preview to confirm an edit (the tool response is the confirmation). See [MCP reference → Preview links](/docs/reference/mcp#preview-links) for the full semantics.
+## Skill folder
+
+OpenClaw loads skills from `~/.agents/skills`, the shared folder several tools read rather than a `.openclaw/` directory of its own. OpenKnowledge now offers that folder as a skill destination whenever it can see OpenClaw installed, so it appears when you install a skill instead of having to type the path into **Add custom path**. It is also listed in **Settings → Skills → Folders**, though that row stays inert until the folder exists — folder linking merges one folder into another, which is not how it should first be created.
+
+It is offered as a destination only, not as a merge target, until the folder actually exists. Linking another tool's folder into a folder you do not have yet would create it and move your existing skills into it; OpenKnowledge does not do that on your behalf.
+
## Agent contract
The **OpenKnowledge skill** — the authoritative agent contract for tool use, grounding, and linking — is project-scoped, written for Claude, Cursor, Codex, and OpenCode; OpenClaw has no project skill directory to receive it. The bundles OpenKnowledge installs to `~/.agents/skills/` (which OpenClaw loads) cover discovery and skill authoring, not tool use — so for OpenClaw agents, the contract is these two reminders:
diff --git a/docs/content/reference/what-open-knowledge-writes.mdx b/docs/content/reference/what-open-knowledge-writes.mdx
index 85d764716..888a890e3 100644
--- a/docs/content/reference/what-open-knowledge-writes.mdx
+++ b/docs/content/reference/what-open-knowledge-writes.mdx
@@ -80,7 +80,7 @@ Delete the block and the app **won't re-add it** — the removal is recorded and
### User-global Agent Skills
-OpenKnowledge ships two user-global [Agent Skills](../features/skills.mdx) — `open-knowledge-discovery` (helps your coding agent recognize and route through OpenKnowledge projects) and `open-knowledge-write-skill` (a workflow for authoring new skills). They install into each detected editor's global skill folder (`~/.claude/skills/`, `~/.cursor/skills/`, `~/.codex/skills/`, `~/.opencode/skills/`) plus the shared `~/.agents/skills/` hub.
+OpenKnowledge ships two user-global [Agent Skills](../features/skills.mdx) — `open-knowledge-discovery` (helps your coding agent recognize and route through OpenKnowledge projects) and `open-knowledge-write-skill` (a workflow for authoring new skills). They install into each detected editor's global skill folder (`~/.claude/skills/`, `~/.cursor/skills/`, `~/.codex/skills/`, `~/.opencode/skills/`, `~/.lmstudio/skills/`) plus the shared `~/.agents/skills/` hub.
Only `open-knowledge-discovery` is set up at first launch — it is what lets an agent recognize an OpenKnowledge project at all, so it comes with the MCP wiring. `open-knowledge-write-skill` is an authoring convenience with no bearing on whether your tools work, so setup neither installs it nor records a decision about it; it is offered the first time you open **Settings → Skills Studio**, and remains installable there afterwards.
@@ -125,7 +125,7 @@ The app runs a collaboration server for the open project. It writes runtime stat
Diagnostic logs and telemetry are **on by default but local-only** — credential-bearing attributes are redacted (`[REDACTED]`) before anything is written, the files rotate at the size caps above, and nothing leaves the machine until you explicitly run `ok diagnose bundle`. Turn the local sink off with `telemetry.localSink.enabled: false`; see [Configuration](./configuration.mdx).
-On each launch and project open, the app also runs **repair sweeps**: it rewrites *existing* `open-knowledge` MCP entries (in the editor configs above) to the current canonical form, and **seeds** the built-in OpenKnowledge skill bundles (`open-knowledge-discovery` and `open-knowledge-write-skill`, in `~/.agents/skills/` and each detected editor's `~/.claude/skills/`, `~/.cursor/skills/`, `~/.codex/skills/`, `~/.opencode/skills/`) **only when they are missing and you previously installed them** — a bundle you never installed or declined is not seeded, and an existing copy is left untouched (updates to a built-in flow through the skills.sh "update available" path, never a force-refresh). It also removes any stale `open-knowledge-ui` entry left in `.claude/launch.json` by an older OK version. It **never adds** an MCP entry to an editor that doesn't already have one. Same `OK_RECLAIM_DISABLE=1` opt-out.
+On each launch and project open, the app also runs **repair sweeps**: it rewrites *existing* `open-knowledge` MCP entries (in the editor configs above) to the current canonical form, and **seeds** the built-in OpenKnowledge skill bundles (`open-knowledge-discovery` and `open-knowledge-write-skill`, in `~/.agents/skills/` and each detected editor's `~/.claude/skills/`, `~/.cursor/skills/`, `~/.codex/skills/`, `~/.opencode/skills/`, `~/.lmstudio/skills/`) **only when they are missing and you previously installed them** — a bundle you never installed or declined is not seeded, and an existing copy is left untouched (updates to a built-in flow through the skills.sh "update available" path, never a force-refresh). It also removes any stale `open-knowledge-ui` entry left in `.claude/launch.json` by an older OK version. It **never adds** an MCP entry to an editor that doesn't already have one. Same `OK_RECLAIM_DISABLE=1` opt-out.
### Home directory and credentials (`~/.ok/`)
@@ -199,6 +199,7 @@ With `--scope user` or `both` (the default), `ok init` also registers the `open-
| --- | --- | --- |
| `~/.agents/skills/open-knowledge-*/` | Shared hub read natively by Codex, OpenCode, and Cursor | Outside-project (home dir) |
| `~/.claude/skills/open-knowledge-*/` | Written only when `~/.claude/` already exists | Outside-project (home dir) |
+| `~/.lmstudio/skills/open-knowledge-*/` | Written only when `~/.lmstudio/` already exists (LM Studio reads these in agent mode) | Outside-project (home dir) |
| `~/.cursor/skills/open-knowledge-*/` | Written only when `~/.cursor/` already exists | Outside-project (home dir) |
| `~/.codex/skills/open-knowledge-*/` | Written only when `~/.codex/` already exists | Outside-project (home dir) |
| `~/.opencode/skills/open-knowledge-*/` | Written only when `~/.opencode/` already exists | Outside-project (home dir) |
@@ -245,7 +246,7 @@ On each boot, `ok start` also runs **repair sweeps**: it re-checks a few things
| What it re-checks | Where | Scope |
| --- | --- | --- |
| Existing `open-knowledge` MCP entries | The same editor configs `ok init` writes — **both** user-level (`~/.claude.json`, `~/.cursor/mcp.json`, …) and project-level | Outside-project (editor config) **and** in-project |
-| OpenKnowledge skill bundles (`open-knowledge-discovery`, `open-knowledge-write-skill`) | Project (`.claude/skills/…`) and user-global — `~/.agents/skills/` plus each detected editor's `~/.claude/skills/`, `~/.cursor/skills/`, `~/.codex/skills/`, `~/.opencode/skills/` | In-project **and** outside-project (home dir) |
+| OpenKnowledge skill bundles (`open-knowledge-discovery`, `open-knowledge-write-skill`) | Project (`.claude/skills/…`) and user-global — `~/.agents/skills/` plus each detected editor's `~/.claude/skills/`, `~/.cursor/skills/`, `~/.codex/skills/`, `~/.opencode/skills/`, `~/.lmstudio/skills/` | In-project **and** outside-project (home dir) |
| Stale `open-knowledge-ui` entry in `.claude/launch.json` | Project | Removed if present — OK no longer writes launch.json |
Disable all three with `OK_RECLAIM_DISABLE=1`.
diff --git a/knip.config.ts b/knip.config.ts
index b61debe5e..8ad68f996 100644
--- a/knip.config.ts
+++ b/knip.config.ts
@@ -124,7 +124,9 @@ export default {
'packages/server': {
entry: ['src/**/*.test.ts', 'src/parse-worker.ts'],
project: 'src/**',
- ignoreDependencies: ['@types/shell-quote'],
+ ignoreDependencies: [
+ '@types/shell-quote',
+ ],
},
'packages/cli': {
entry: ['src/**/*.test.ts', 'scripts/*.ts', 'tests/**/*.ts', 'src/parse-worker.ts'],
diff --git a/packages/app/src/components/AgentIconCluster.tsx b/packages/app/src/components/AgentIconCluster.tsx
index 525cc6752..39f2f4f3d 100644
--- a/packages/app/src/components/AgentIconCluster.tsx
+++ b/packages/app/src/components/AgentIconCluster.tsx
@@ -12,6 +12,7 @@ import { EDITOR_LABELS } from '@inkeep/open-knowledge-core';
import { Folder, Sparkles } from 'lucide-react';
import type { SVGProps } from 'react';
import { TargetIcon } from '@/components/handoff/OpenInAgentMenuItem';
+import { LmStudioIcon } from '@/components/icons/lmstudio';
import { OkBlob } from '@/components/OkBlob';
import { Tooltip, TooltipContent, TooltipTrigger } from '@/components/ui/tooltip';
import { cn } from '@/lib/utils';
@@ -58,6 +59,11 @@ export function AgentBrandIcon({
// brand — a neutral mark, not an invisible one (dropping it made a hub-hosted
// skill read as belonging to whichever editor copy happened to exist).
if (host === 'agents') return <Sparkles {...props} />;
+ // LM Studio is a skill host but NOT a handoff target — it registers no
+ // deeplink route OK can dispatch to — so its mark cannot live in
+ // `TARGET_ICON_KEY`, which is keyed by `HandoffTarget`. Handled here, where
+ // `host` is the wider skill-host vocabulary.
+ if (host === 'lm-studio') return <LmStudioIcon {...props} />;
// Custom-root host ids ARE paths (they contain '/'): the `.ok` home renders
// the OK blob, any other custom root the neutral folder — matching the
// install menu's row icons so the pill cluster can carry every location.
diff --git a/packages/app/src/components/handoff/OpenInAgentMenuItem.tsx b/packages/app/src/components/handoff/OpenInAgentMenuItem.tsx
index a9ec666a1..75701f3f2 100644
--- a/packages/app/src/components/handoff/OpenInAgentMenuItem.tsx
+++ b/packages/app/src/components/handoff/OpenInAgentMenuItem.tsx
@@ -58,9 +58,26 @@ import { cn } from '@/lib/utils';
/**
* Vendor icon per target. Claude Cowork and Claude share `ClaudeIcon`
- * since both dispatch to Claude Desktop. Unknown ids render nothing — the
- * row still reads correctly without an icon (graceful no-op if a 5th target
- * lands here before the map is updated).
+ * since both dispatch to Claude Desktop. `TARGET_ICON_KEY` is an exhaustive
+ * `Record<TargetData['id'], string>`, so adding a target forces a KEY there —
+ * but the `if`-chain below has no exhaustiveness assertion, so a new target with
+ * a key and no branch still falls through to `null`. That is precisely the
+ * `lm-studio` shape this comment used to claim was impossible.
+ *
+ * The nearest guard is the skill-host icon-coverage test, but it is narrower
+ * than this chain. It iterates `SkillUserTargetEditorSchema.options`, which
+ * excludes `openclaw` and `hermes` — so those TWO branches can each be deleted
+ * with the suite green. (`claude-cowork` is also never reached, since
+ * `targetIconIdForHost` maps to `claude-code`, but it shares an `if` with
+ * `claude-code`, so deleting it goes red anyway.) Adding a target here without a
+ * mark is caught only when that target is also a user-global skill host.
+ *
+ * Deliberately NOT a neutral-glyph fallback: skill hosts are a WIDER vocabulary
+ * than handoff targets and reach these marks through `AgentBrandIcon`, so a
+ * runtime fallback here would silently absorb a missing skill-host mark — the
+ * exact `lm-studio` failure this comment used to describe — and would make the
+ * icon-coverage test unable to fail. `Sparkles` is also already reserved as the
+ * `.agents` hub's own mark.
*
* DropdownMenuItem + DropdownMenuSubTrigger both auto-size `<svg>` children
* to `size-4`, so the icon doesn't need an explicit size prop.
diff --git a/packages/app/src/components/icons/lmstudio.tsx b/packages/app/src/components/icons/lmstudio.tsx
new file mode 100644
index 000000000..886599239
--- /dev/null
+++ b/packages/app/src/components/icons/lmstudio.tsx
@@ -0,0 +1,39 @@
+import type { SVGProps } from 'react';
+
+// LM Studio brand mark: six staggered rounded bars. Flattened to a single
+// `currentColor` silhouette so it tracks the row text color and brightens on
+// hover like the other monochrome marks (OpenCode, Pi, Hermes) — the shipped
+// icon is white bars over a purple gradient, and a gradient does not survive
+// being drawn at 14px inside a sidebar row.
+//
+// Geometry measured from `LM Studio.app/Contents/Resources/icon.icns` (0.4.21)
+// rather than eyeballed: bars are ~2.9 tall on a 4.22 vertical rhythm, five at
+// ~15.2 wide plus a short ~9.9 tail, normalized to a 24x24 viewBox to match
+// Lucide sizing.
+export function LmStudioIcon(props: SVGProps<SVGSVGElement>) {
+ const bars = [
+ { x: 1.9, y: 0, w: 15.15 },
+ { x: 8.0, y: 4.22, w: 15.15 },
+ { x: 4.35, y: 8.44, w: 15.3 },
+ { x: 0, y: 12.66, w: 15.15 },
+ { x: 4.35, y: 16.88, w: 15.3 },
+ { x: 14.1, y: 21.1, w: 9.9 },
+ ];
+ return (
+ <svg
+ role="img"
+ aria-label="LM Studio icon"
+ xmlns="http://www.w3.org/2000/svg"
+ width={24}
+ height={24}
+ fill="currentColor"
+ viewBox="0 0 24 24"
+ {...props}
+ >
+ <title>LM Studio icon</title>
+ {bars.map((b) => (
+ <rect key={b.y} x={b.x} y={b.y} width={b.w} height={2.9} rx={1.45} />
+ ))}
+ </svg>
+ );
+}
diff --git a/packages/app/src/components/settings/SkillTargetsPicker.dom.test.tsx b/packages/app/src/components/settings/SkillTargetsPicker.dom.test.tsx
index 1ca16f32a..496ca866e 100644
--- a/packages/app/src/components/settings/SkillTargetsPicker.dom.test.tsx
+++ b/packages/app/src/components/settings/SkillTargetsPicker.dom.test.tsx
@@ -329,3 +329,67 @@ describe('SkillTargetsPicker (folders)', () => {
expect(screen.queryByTestId('skill-folder-link-claude-to-.codex/skills')).toBeNull();
});
});
+
+describe('the .agents hub row', () => {
+ const withHub = (state: string) => ({
+ targets: ['claude'],
+ configured: false,
+ folders: [
+ { scope: 'project', host: 'claude', root: '.claude/skills', state: 'own' },
+ { scope: 'project', host: 'agents', root: '.agents/skills', state },
+ ],
+ });
+
+ test('an ABSENT hub offers no Link verb and says why', async () => {
+ // The consent guard, pinned. A link mkdirs the surviving root and renames the
+ // picked folder's bundles into it, so offering it on a hub that does not
+ // exist would create `.agents` and relocate the user's skills there. Nothing
+ // failed if this guard was lost — that is what this test is for.
+ global.fetch = vi.fn(async () => ({
+ ok: true,
+ status: 200,
+ json: async () => withHub('absent'),
+ })) as unknown as typeof fetch;
+
+ render(<SkillTargetsPicker scope="project" />);
+ await waitFor(() => expect(screen.getByTestId('skill-folder-row-agents')).toBeDefined());
+
+ expect(screen.queryByTestId('skill-folder-link-agents')).toBeNull();
+ expect(screen.getByTestId('skill-folder-hub-destination-only')).toBeDefined();
+ });
+
+ test('an ABSENT hub is not offered as a merge target on another row either', async () => {
+ // The row you act on is the merge TARGET, so excluding the hub from the pick
+ // list alone would have left the dangerous direction open.
+ global.fetch = vi.fn(async () => ({
+ ok: true,
+ status: 200,
+ json: async () => withHub('absent'),
+ })) as unknown as typeof fetch;
+
+ render(<SkillTargetsPicker scope="project" />);
+ await waitFor(() => expect(screen.getByTestId('skill-folder-row-claude')).toBeDefined());
+
+ // Assert the TRIGGER, not the menu item. Radix portals the item and unmounts
+ // it while the menu is closed, so querying it without clicking passes either
+ // way — the assertion could not fail. What `targets` actually gates is the
+ // trigger: with the absent hub excluded the claude row has no targets, so no
+ // DropdownMenu renders at all. Drop `!isAbsentHub(o)` and the trigger
+ // appears, which is the regression this must catch.
+ expect(screen.queryByTestId('skill-folder-link-claude')).toBeNull();
+ });
+
+ test('once the hub EXISTS it behaves like any other root', async () => {
+ global.fetch = vi.fn(async () => ({
+ ok: true,
+ status: 200,
+ json: async () => withHub('own'),
+ })) as unknown as typeof fetch;
+
+ render(<SkillTargetsPicker scope="project" />);
+ await waitFor(() => expect(screen.getByTestId('skill-folder-row-agents')).toBeDefined());
+
+ expect(screen.getByTestId('skill-folder-link-agents')).toBeDefined();
+ expect(screen.queryByTestId('skill-folder-hub-destination-only')).toBeNull();
+ });
+});
diff --git a/packages/app/src/components/settings/SkillTargetsPicker.tsx b/packages/app/src/components/settings/SkillTargetsPicker.tsx
index d9a526a36..cbccf3437 100644
--- a/packages/app/src/components/settings/SkillTargetsPicker.tsx
+++ b/packages/app/src/components/settings/SkillTargetsPicker.tsx
@@ -1,6 +1,10 @@
// biome-ignore-all lint/plugin/no-physical-direction-utility: pre-rule backlog — physical margin/padding/inset utilities predate the rule; drain by swapping ml/mr → ms/me, pl/pr → ps/pe, left/right → start/end, then deleting this line. See https://github.com/inkeep/open-knowledge/blob/main/biome-plugins/README.md#no-physical-direction-utilitygrit
-import type { SkillFolderLinkPreview, SkillScope } from '@inkeep/open-knowledge-core';
+import {
+ AGENTS_SKILLS_ROOT,
+ type SkillFolderLinkPreview,
+ type SkillScope,
+} from '@inkeep/open-knowledge-core';
import { Trans, useLingui } from '@lingui/react/macro';
import { useState } from 'react';
import { toast } from 'sonner';
@@ -162,17 +166,37 @@ export function SkillTargetsPicker({ scope }: { scope: SkillScope }) {
// still in the list" bug — picking it could only fail. Order is list
// order: no name-based promotion of any root.
//
- // `absent` stays offerable, and only because the server now filters
- // this list to roots whose agent home exists. So an absent row means
+ // `absent` stays offerable, and only because the server filters this
+ // list to roots whose agent home exists. So an absent row means
// "`.claude` is here, `.claude/skills` is not yet" — linking it
// creates a skills dir inside a dotdir the user already has, which is
// squarely inside the consent boundary. Before that filter the same
// disjunct offered `~/.copilot/skills` on a machine with no Copilot,
// and accepting it created `~/.copilot` — after which OK's own
// directory-based detection reported Copilot as installed.
+ //
+ // THE HUB IS THE ONE ROOT THAT BREAKS THAT PREMISE. `.agents/skills`
+ // is offered on a reader's presence (`HUB_READER_EDITORS`), so it can
+ // be `absent` on a base with no `.agents` at all — the agent-home
+ // guarantee above does not hold for it. A link does `mkdir` on either
+ // side and, in the merge-target direction, RENAMES the source's
+ // bundles into the target. Offering an absent hub as a target would
+ // therefore create a dotdir the user does not have AND relocate their
+ // existing skills into it, from a surface whose own copy promises it
+ // does not. So the hub is a destination, not a merge target, until it
+ // exists: `own` only. Once real, it behaves like any other root.
+ const isAbsentHub = (r: { root: string; state: string }): boolean =>
+ r.root === AGENTS_SKILLS_ROOT && r.state === 'absent';
const targets = folders.filter(
- (o) => o.root !== f.root && (o.state === 'own' || o.state === 'absent'),
+ (o) =>
+ o.root !== f.root && (o.state === 'own' || o.state === 'absent') && !isAbsentHub(o),
);
+ // The row you act on is the merge TARGET — it survives and RECEIVES
+ // the picked folder's bundles. So an absent hub is excluded from BOTH
+ // roles, not just from the pick list: acting on it would create
+ // `.agents` and rename the picked folder's skills into it, which is
+ // precisely the consent boundary the comment above describes.
+ const canLink = (f.state === 'own' || f.state === 'absent') && !isAbsentHub(f);
return (
<li key={f.host} className="text-sm" data-testid={`skill-folder-row-${f.host}`}>
<div className="flex items-center gap-2">
@@ -202,7 +226,19 @@ export function SkillTargetsPicker({ scope }: { scope: SkillScope }) {
<Trans>symlinked via parent</Trans>
</span>
) : null}
- {(f.state === 'own' || f.state === 'absent') && targets.length > 0 ? (
+ {isAbsentHub(f) ? (
+ // Without this the hub is the one row on the page with no
+ // verb and no reason given — it reads as broken rather than
+ // as deliberately destination-only. Says what to do instead.
+ <span
+ className="shrink-0 text-[10px] text-muted-foreground"
+ title={t`Linking merges another folder into this one. This folder does not exist yet, so install a skill here first.`}
+ data-testid="skill-folder-hub-destination-only"
+ >
+ <Trans>install a skill here first</Trans>
+ </span>
+ ) : null}
+ {canLink && targets.length > 0 ? (
<DropdownMenu>
<DropdownMenuTrigger asChild>
<Button
diff --git a/packages/app/src/lib/skill-host-icon-coverage.dom.test.tsx b/packages/app/src/lib/skill-host-icon-coverage.dom.test.tsx
new file mode 100644
index 000000000..9c64bf808
--- /dev/null
+++ b/packages/app/src/lib/skill-host-icon-coverage.dom.test.tsx
@@ -0,0 +1,45 @@
+/**
+ * Every skill-install target must render a visible mark.
+ *
+ * These brand icons double as the skill-host marks in the sidebar, the install
+ * menu, and the editor's icon cluster. An id with no glyph does not degrade to
+ * "row without a logo" — it degrades to an EMPTY `<span role="img">`, which
+ * reads as "not installed at all", and to a zero-size tooltip trigger that
+ * cannot be hovered.
+ *
+ * This is a lockstep guard, not a snapshot: adding an editor to
+ * `EDITOR_USER_SKILL_ROOT` widens the install vocabulary automatically, and
+ * nothing in the type system connects that map to the icon set (the cluster
+ * casts through `as TargetIconId`). `lm-studio` shipped exactly that way.
+ */
+import { SkillUserTargetEditorSchema } from '@inkeep/open-knowledge-core';
+import { render } from '@testing-library/react';
+import { describe, expect, test } from 'vitest';
+import { AgentBrandIcon } from '@/components/AgentIconCluster';
+
+describe('skill host icon coverage', () => {
+ test('every user-global install target renders its OWN mark', () => {
+ // Stronger than presence, weaker than identity — state which. A bare
+ // presence check goes green the moment any fallback glyph exists, so this
+ // requires a non-empty ACCESSIBLE NAME: a nameless or fallback mark fails.
+ // It does NOT pin which host the name belongs to, so a host wired to another
+ // host's correctly-labelled icon would still pass. Cross-host mis-wiring is
+ // caught by review, not here; what this pins is that no install target
+ // renders an unnamed or absent mark.
+ const wrong: string[] = [];
+ for (const host of SkillUserTargetEditorSchema.options) {
+ const { container, unmount } = render(<AgentBrandIcon host={host} />);
+ const svg = container.querySelector('svg');
+ const name =
+ svg?.getAttribute('aria-label') ?? svg?.querySelector('title')?.textContent ?? '';
+ if (svg === null || name.trim() === '') wrong.push(`${host}: no mark`);
+ unmount();
+ }
+ expect(wrong).toEqual([]);
+ });
+
+ test('the vendor-neutral hub renders a mark too', () => {
+ const { container } = render(<AgentBrandIcon host="agents" />);
+ expect(container.querySelector('svg')).not.toBeNull();
+ });
+});
diff --git a/packages/app/src/lib/skill-install-rows.test.ts b/packages/app/src/lib/skill-install-rows.test.ts
index e982675b7..c1b05b148 100644
--- a/packages/app/src/lib/skill-install-rows.test.ts
+++ b/packages/app/src/lib/skill-install-rows.test.ts
@@ -310,3 +310,62 @@ describe('global-scope vocabulary', () => {
expect(rows).not.toContain('antigravity');
});
});
+
+describe('the .agents hub gate', () => {
+ it('is offered when the server says a reader is installed, with nothing under .agents yet', () => {
+ // The case the whole feature exists for, and the one adoption-only could not
+ // reach: a fresh project, LM Studio installed, no skill under `.agents/`.
+ // Before `hubOffered` this returned no hub row, so the documented "choose
+ // .agents" was not an available action and there was no non-circular way to
+ // make the first placement.
+ const rows = derive({
+ ...base,
+ hosts: ['claude'],
+ path: '.claude/skills/x/SKILL.md',
+ hubOffered: true,
+ }).rows;
+ expect(rows).toContain('agents');
+ });
+
+ it('is NOT offered when the server says nothing reads it and the project has not adopted it', () => {
+ const rows = derive({
+ ...base,
+ hosts: ['claude'],
+ path: '.claude/skills/x/SKILL.md',
+ hubOffered: false,
+ }).rows;
+ expect(rows).not.toContain('agents');
+ });
+
+ it('stays offered on adoption alone, even when no reader is installed', () => {
+ // The pre-existing rule is preserved, not replaced: a project already using
+ // the hub keeps its row regardless of what is installed on this machine.
+ const rows = derive({
+ ...base,
+ hosts: ['agents'],
+ path: '.agents/skills/x/SKILL.md',
+ hubOffered: false,
+ }).rows;
+ expect(rows).toContain('agents');
+ });
+
+ it('a GLOBAL skill under .agents does not activate the hub on a PROJECT menu', () => {
+ // Scope leak: `allSkills` spans every scope, so without the scope filter one
+ // global skill under ~/.agents/skills lit the hub on a project menu the
+ // server had just answered `hubOffered: false` for.
+ const rows = derive(
+ { ...base, hosts: ['claude'], path: '.claude/skills/x/SKILL.md', hubOffered: false },
+ {
+ allSkills: [
+ {
+ scope: 'global',
+ name: 'g',
+ hosts: ['agents'],
+ path: '.agents/skills/g/SKILL.md',
+ } as unknown as SkillsListEntry,
+ ],
+ },
+ ).rows;
+ expect(rows).not.toContain('agents');
+ });
+});
diff --git a/packages/app/src/lib/skill-install-rows.ts b/packages/app/src/lib/skill-install-rows.ts
index b7c5cc794..6a372dc94 100644
--- a/packages/app/src/lib/skill-install-rows.ts
+++ b/packages/app/src/lib/skill-install-rows.ts
@@ -53,6 +53,7 @@ export type SkillInstallMenuSkill = Pick<SkillsListEntry, 'scope' | 'name'> &
| 'conflictHosts'
| 'driftPaths'
| 'installableEditors'
+ | 'hubOffered'
| 'origin'
| 'plugin'
>
@@ -115,14 +116,35 @@ export function deriveSkillInstallRows({
const pathFor = (host: string): string | null =>
skill ? `${skillHostRootDir(host, skill.scope)}/${skill.name}` : null;
- // The `.agents` hub is EXISTENCE-ACTIVATED: offered only when this project
- // already adopted it (any skill lives there or lists it as a host). OK never
- // pushes the hub on a repo — adopting it is one Custom path away, and the
- // first placement there lights this row up for every skill.
+ // The `.agents` hub is offered when the project has ALREADY adopted it (any
+ // skill lives there or lists it as a host) OR when the server says a host that
+ // reads it is installed (`hubOffered`, computed by the same predicate that
+ // filters the Folders surface). OK still never pushes the hub on a repo where
+ // nothing would read it.
+ //
+ // `hubOffered` is not a convenience: adoption-only was circular. The hub is
+ // not a link target until it exists (see `SkillTargetsPicker`), so with no
+ // skill under `.agents/` there was no non-circular way to make the first
+ // placement — the answer was offered only to people who already knew to type
+ // the path into Custom path. Reading the server's flag is also what keeps this
+ // surface and Settings from answering the same question differently.
+ const hubOffered =
+ skill?.hubOffered ??
+ (skill && allSkills !== null
+ ? allSkills.find((s) => s.scope === skill.scope)?.hubOffered
+ : undefined);
const hubActive =
skill !== undefined &&
- ((skill.hosts ?? []).includes('agents') ||
- allSkills?.some((s) => s.hosts.includes('agents') || s.path.startsWith(AGENTS_DIR_PREFIX)));
+ (hubOffered === true ||
+ (skill.hosts ?? []).includes('agents') ||
+ allSkills?.some(
+ (s) =>
+ // Scope-filtered: without this, ONE global skill under `~/.agents/skills`
+ // activates the hub on a PROJECT menu the server said `hubOffered: false`
+ // for — the two surfaces disagreeing again, by a different route.
+ s.scope === skill.scope &&
+ (s.hosts.includes('agents') || s.path.startsWith(AGENTS_DIR_PREFIX)),
+ ));
// Folder-level aliases. An aliased folder is a derived view of its target: NO
// row of its own (checking it could only write through the alias), its agent
diff --git a/packages/app/src/locales/ar/messages.json b/packages/app/src/locales/ar/messages.json
index aa5438006..d3ffde409 100644
--- a/packages/app/src/locales/ar/messages.json
+++ b/packages/app/src/locales/ar/messages.json
@@ -2322,6 +2322,9 @@
"QLgdT6": ["أي مستند باسم ", ["0"]],
"QM3SBZ": ["الخطة (", ["done"], "/", ["0"], ")"],
"QOINDn": ["فارغ"],
+ "QP9OU3": [
+ "الربط يدمج مجلداً آخر في هذا المجلد. هذا المجلد غير موجود بعد، لذا ثبّت مهارة هنا أولاً."
+ ],
"QPWyTw": ["تجميع المهارات حسب المصدر"],
"QQbwzK": ["لا يوجد وكلاء متاحون."],
"QQghPu": ["التثبيت في Claude Desktop"],
@@ -4387,6 +4390,7 @@
"mLAjyL": [
"امنح أدوات الذكاء الاصطناعي التي تستخدمها إذن قراءة مشاريعك وتحديثها. تحديد مربع يُعدّه فورًا؛ وإلغاء التحديد يزيله."
],
+ "mPoOmg": ["ثبّت مهارة هنا أولاً"],
"mPy9lS": [
"نظّم مواصفاتي الحالية في فهرس مترابط مجمَّع حسب المجال، وأشِر إلى أي منها انحرف عن الكود الحالي."
],
diff --git a/packages/app/src/locales/ar/messages.po b/packages/app/src/locales/ar/messages.po
index 96cf6dde7..14d79f4d5 100644
--- a/packages/app/src/locales/ar/messages.po
+++ b/packages/app/src/locales/ar/messages.po
@@ -7019,6 +7019,10 @@ msgstr "تثبيت {0}"
msgid "Install {brand} →"
msgstr "تثبيت {brand} ←"
+#: src/components/settings/SkillTargetsPicker.tsx
+msgid "install a skill here first"
+msgstr "ثبّت مهارة هنا أولاً"
+
#. placeholder {0}: res.error
#: src/hooks/use-explore-preview-install.ts
msgid "Install failed: {0}"
@@ -7508,6 +7512,10 @@ msgstr "لم تطابق استجابة رسم الروابط الشكل المت
msgid "Linked theme files aren’t supported"
msgstr "ملفات السمات المرتبطة غير مدعومة"
+#: src/components/settings/SkillTargetsPicker.tsx
+msgid "Linking merges another folder into this one. This folder does not exist yet, so install a skill here first."
+msgstr "الربط يدمج مجلداً آخر في هذا المجلد. هذا المجلد غير موجود بعد، لذا ثبّت مهارة هنا أولاً."
+
#: src/components/DocPanel.tsx
msgid "Links"
msgstr "الروابط"
diff --git a/packages/app/src/locales/bn/messages.json b/packages/app/src/locales/bn/messages.json
index 096b3b739..e0195b4fc 100644
--- a/packages/app/src/locales/bn/messages.json
+++ b/packages/app/src/locales/bn/messages.json
@@ -1999,6 +1999,9 @@
"QLgdT6": [["0"], " নামের যেকোনো নথি"],
"QM3SBZ": ["পরিকল্পনা (", ["done"], "/", ["0"], ")"],
"QOINDn": ["খালি"],
+ "QP9OU3": [
+ "লিংক করলে অন্য একটি ফোল্ডার এই ফোল্ডারে মার্জ হয়ে যায়। এই ফোল্ডারটি এখনও নেই, তাই প্রথমে এখানে একটি স্কিল ইনস্টল করুন।"
+ ],
"QPWyTw": ["উৎস অনুসারে স্কিল গোষ্ঠীবদ্ধ করুন"],
"QQbwzK": ["কোনো এজেন্ট নেই।"],
"QQghPu": ["Claude Desktop-এ ইনস্টল করুন"],
@@ -3762,6 +3765,7 @@
"mLAjyL": [
"আপনি যে AI টুলগুলো ব্যবহার করেন সেগুলোকে আপনার প্রকল্প পড়া ও হালনাগাদ করার অধিকার দিন। একটি বাক্সে টিক দিলেই সেটি সঙ্গে সঙ্গে সেট হয়ে যায়; টিক সরালে সরে যায়।"
],
+ "mPoOmg": ["প্রথমে এখানে একটি স্কিল ইনস্টল করুন"],
"mPy9lS": [
"আমার বিদ্যমান স্পেকগুলো এলাকা অনুযায়ী গোষ্ঠীবদ্ধ একটি যুক্ত সূচিতে সাজান, এবং যেগুলো বর্তমান কোডের সঙ্গে মিল হারিয়েছে সেগুলো চিহ্নিত করুন।"
],
diff --git a/packages/app/src/locales/bn/messages.po b/packages/app/src/locales/bn/messages.po
index b09ed19d4..bf451b40b 100644
--- a/packages/app/src/locales/bn/messages.po
+++ b/packages/app/src/locales/bn/messages.po
@@ -7015,6 +7015,10 @@ msgstr "{0} ইনস্টল করুন"
msgid "Install {brand} →"
msgstr "{brand} ইনস্টল করুন →"
+#: src/components/settings/SkillTargetsPicker.tsx
+msgid "install a skill here first"
+msgstr "প্রথমে এখানে একটি স্কিল ইনস্টল করুন"
+
#. placeholder {0}: res.error
#: src/hooks/use-explore-preview-install.ts
msgid "Install failed: {0}"
@@ -7504,6 +7508,10 @@ msgstr "লিংক-গ্রাফের সাড়া প্রত্যা
msgid "Linked theme files aren’t supported"
msgstr "লিঙ্ক করা থিম ফাইল সমর্থিত নয়"
+#: src/components/settings/SkillTargetsPicker.tsx
+msgid "Linking merges another folder into this one. This folder does not exist yet, so install a skill here first."
+msgstr "লিংক করলে অন্য একটি ফোল্ডার এই ফোল্ডারে মার্জ হয়ে যায়। এই ফোল্ডারটি এখনও নেই, তাই প্রথমে এখানে একটি স্কিল ইনস্টল করুন।"
+
#: src/components/DocPanel.tsx
msgid "Links"
msgstr "লিংক"
diff --git a/packages/app/src/locales/en/messages.json b/packages/app/src/locales/en/messages.json
index 6e5670ed4..ba105e09e 100644
--- a/packages/app/src/locales/en/messages.json
+++ b/packages/app/src/locales/en/messages.json
@@ -2051,6 +2051,9 @@
"QLgdT6": ["any doc named ", ["0"]],
"QM3SBZ": ["Plan (", ["done"], "/", ["0"], ")"],
"QOINDn": ["empty"],
+ "QP9OU3": [
+ "Linking merges another folder into this one. This folder does not exist yet, so install a skill here first."
+ ],
"QPWyTw": ["Group skills by source"],
"QQbwzK": ["No agents available."],
"QQghPu": ["Install in Claude Desktop"],
@@ -3870,6 +3873,7 @@
"mLAjyL": [
"Give the AI tools you use access to read and update your projects. Checking a box sets it up right away; unchecking removes it."
],
+ "mPoOmg": ["install a skill here first"],
"mPy9lS": [
"Organize my existing specs into a linked index grouped by area, and flag any that have drifted out of sync with the current code."
],
diff --git a/packages/app/src/locales/en/messages.po b/packages/app/src/locales/en/messages.po
index df755163b..6a473e8fd 100644
--- a/packages/app/src/locales/en/messages.po
+++ b/packages/app/src/locales/en/messages.po
@@ -7019,6 +7019,10 @@ msgstr "Install {0}"
msgid "Install {brand} →"
msgstr "Install {brand} →"
+#: src/components/settings/SkillTargetsPicker.tsx
+msgid "install a skill here first"
+msgstr "install a skill here first"
+
#. placeholder {0}: res.error
#: src/hooks/use-explore-preview-install.ts
msgid "Install failed: {0}"
@@ -7508,6 +7512,10 @@ msgstr "Link-graph response did not match expected shape."
msgid "Linked theme files aren’t supported"
msgstr "Linked theme files aren’t supported"
+#: src/components/settings/SkillTargetsPicker.tsx
+msgid "Linking merges another folder into this one. This folder does not exist yet, so install a skill here first."
+msgstr "Linking merges another folder into this one. This folder does not exist yet, so install a skill here first."
+
#: src/components/DocPanel.tsx
msgid "Links"
msgstr "Links"
diff --git a/packages/app/src/locales/es/messages.json b/packages/app/src/locales/es/messages.json
index 325f0d790..657570249 100644
--- a/packages/app/src/locales/es/messages.json
+++ b/packages/app/src/locales/es/messages.json
@@ -2370,6 +2370,9 @@
"QLgdT6": ["cualquier documento llamado ", ["0"]],
"QM3SBZ": ["Plan (", ["done"], "/", ["0"], ")"],
"QOINDn": ["vacío"],
+ "QP9OU3": [
+ "Enlazar fusiona otra carpeta en esta. Esta carpeta aún no existe, así que instala primero una habilidad aquí."
+ ],
"QPWyTw": ["Agrupar habilidades por origen"],
"QQbwzK": ["No hay agentes disponibles."],
"QQghPu": ["Instalar en Claude Desktop"],
@@ -4487,6 +4490,7 @@
"mLAjyL": [
"Da a las herramientas de IA que usas acceso para leer y actualizar tus proyectos. Al marcar una casilla se configura al momento; al desmarcarla se quita."
],
+ "mPoOmg": ["instala primero una habilidad aquí"],
"mPy9lS": [
"Organiza mis especificaciones existentes en un índice enlazado y agrupado por área, y señala las que se hayan desincronizado del código actual."
],
diff --git a/packages/app/src/locales/es/messages.po b/packages/app/src/locales/es/messages.po
index 14e348e8b..52c9f00ad 100644
--- a/packages/app/src/locales/es/messages.po
+++ b/packages/app/src/locales/es/messages.po
@@ -7019,6 +7019,10 @@ msgstr "Instalar {0}"
msgid "Install {brand} →"
msgstr "Instalar {brand} →"
+#: src/components/settings/SkillTargetsPicker.tsx
+msgid "install a skill here first"
+msgstr "instala primero una habilidad aquí"
+
#. placeholder {0}: res.error
#: src/hooks/use-explore-preview-install.ts
msgid "Install failed: {0}"
@@ -7508,6 +7512,10 @@ msgstr "La respuesta del grafo de enlaces no tenía la forma esperada."
msgid "Linked theme files aren’t supported"
msgstr "No se admiten archivos de tema vinculados"
+#: src/components/settings/SkillTargetsPicker.tsx
+msgid "Linking merges another folder into this one. This folder does not exist yet, so install a skill here first."
+msgstr "Enlazar fusiona otra carpeta en esta. Esta carpeta aún no existe, así que instala primero una habilidad aquí."
+
#: src/components/DocPanel.tsx
msgid "Links"
msgstr "Enlaces"
diff --git a/packages/app/src/locales/fr/messages.json b/packages/app/src/locales/fr/messages.json
index a32ccfc99..7a322b4d1 100644
--- a/packages/app/src/locales/fr/messages.json
+++ b/packages/app/src/locales/fr/messages.json
@@ -2393,6 +2393,9 @@
"QLgdT6": ["tout document nommé ", ["0"]],
"QM3SBZ": ["Plan (", ["done"], "/", ["0"], ")"],
"QOINDn": ["vide"],
+ "QP9OU3": [
+ "Lier fusionne un autre dossier dans celui-ci. Ce dossier n'existe pas encore, installez donc d'abord une compétence ici."
+ ],
"QPWyTw": ["Grouper les compétences par source"],
"QQbwzK": ["Aucun agent disponible."],
"QQghPu": ["Installer dans Claude Desktop"],
@@ -4521,6 +4524,7 @@
"mLAjyL": [
"Donnez aux outils IA que vous utilisez l'accès en lecture et en écriture à vos projets. Cocher une case configure l'outil immédiatement ; décocher le retire."
],
+ "mPoOmg": ["installez d'abord une compétence ici"],
"mPy9lS": [
"Organise mes spécifications existantes en un index lié, groupé par domaine, et signale celles qui ont divergé du code actuel."
],
diff --git a/packages/app/src/locales/fr/messages.po b/packages/app/src/locales/fr/messages.po
index 22afb73a7..20017435a 100644
--- a/packages/app/src/locales/fr/messages.po
+++ b/packages/app/src/locales/fr/messages.po
@@ -7019,6 +7019,10 @@ msgstr "Installer {0}"
msgid "Install {brand} →"
msgstr "Installer {brand} →"
+#: src/components/settings/SkillTargetsPicker.tsx
+msgid "install a skill here first"
+msgstr "installez d'abord une compétence ici"
+
#. placeholder {0}: res.error
#: src/hooks/use-explore-preview-install.ts
msgid "Install failed: {0}"
@@ -7508,6 +7512,10 @@ msgstr "La réponse du graphe de liens ne correspond pas à la forme attendue."
msgid "Linked theme files aren’t supported"
msgstr "Les fichiers de thème liés ne sont pas pris en charge"
+#: src/components/settings/SkillTargetsPicker.tsx
+msgid "Linking merges another folder into this one. This folder does not exist yet, so install a skill here first."
+msgstr "Lier fusionne un autre dossier dans celui-ci. Ce dossier n'existe pas encore, installez donc d'abord une compétence ici."
+
#: src/components/DocPanel.tsx
msgid "Links"
msgstr "Liens"
diff --git a/packages/app/src/locales/hi/messages.json b/packages/app/src/locales/hi/messages.json
index 4ba6e0546..8a9273be6 100644
--- a/packages/app/src/locales/hi/messages.json
+++ b/packages/app/src/locales/hi/messages.json
@@ -1992,6 +1992,9 @@
"QLgdT6": [["0"], " नाम का कोई भी दस्तावेज़"],
"QM3SBZ": ["योजना (", ["done"], "/", ["0"], ")"],
"QOINDn": ["खाली"],
+ "QP9OU3": [
+ "लिंक करने पर दूसरा फ़ोल्डर इस फ़ोल्डर में मर्ज हो जाता है। यह फ़ोल्डर अभी मौजूद नहीं है, इसलिए पहले यहाँ एक स्किल इंस्टॉल करें।"
+ ],
"QPWyTw": ["स्किल को स्रोत के अनुसार समूहित करें"],
"QQbwzK": ["कोई एजेंट उपलब्ध नहीं।"],
"QQghPu": ["Claude Desktop में इंस्टॉल करें"],
@@ -3748,6 +3751,7 @@
"mLAjyL": [
"आप जिन AI टूल का उपयोग करते हैं उन्हें अपने प्रोजेक्ट पढ़ने और अपडेट करने की पहुँच दें। बॉक्स चुनते ही यह तुरंत सेट हो जाता है; हटाने पर हट जाता है।"
],
+ "mPoOmg": ["पहले यहाँ एक स्किल इंस्टॉल करें"],
"mPy9lS": [
"मेरी मौजूदा स्पेक को क्षेत्र के अनुसार समूहित एक जुड़ी हुई अनुक्रमणिका में व्यवस्थित करें, और जो मौजूदा कोड से तालमेल खो चुकी हों उन्हें चिह्नित करें।"
],
diff --git a/packages/app/src/locales/hi/messages.po b/packages/app/src/locales/hi/messages.po
index f7c16cb64..7b2d08b41 100644
--- a/packages/app/src/locales/hi/messages.po
+++ b/packages/app/src/locales/hi/messages.po
@@ -7015,6 +7015,10 @@ msgstr "{0} इंस्टॉल करें"
msgid "Install {brand} →"
msgstr "{brand} इंस्टॉल करें →"
+#: src/components/settings/SkillTargetsPicker.tsx
+msgid "install a skill here first"
+msgstr "पहले यहाँ एक स्किल इंस्टॉल करें"
+
#. placeholder {0}: res.error
#: src/hooks/use-explore-preview-install.ts
msgid "Install failed: {0}"
@@ -7504,6 +7508,10 @@ msgstr "लिंक-ग्राफ़ की प्रतिक्रिया
msgid "Linked theme files aren’t supported"
msgstr "लिंक की गई थीम फ़ाइलें समर्थित नहीं हैं"
+#: src/components/settings/SkillTargetsPicker.tsx
+msgid "Linking merges another folder into this one. This folder does not exist yet, so install a skill here first."
+msgstr "लिंक करने पर दूसरा फ़ोल्डर इस फ़ोल्डर में मर्ज हो जाता है। यह फ़ोल्डर अभी मौजूद नहीं है, इसलिए पहले यहाँ एक स्किल इंस्टॉल करें।"
+
#: src/components/DocPanel.tsx
msgid "Links"
msgstr "लिंक"
diff --git a/packages/app/src/locales/id/messages.json b/packages/app/src/locales/id/messages.json
index d8236bce0..36e4b2de1 100644
--- a/packages/app/src/locales/id/messages.json
+++ b/packages/app/src/locales/id/messages.json
@@ -2062,6 +2062,9 @@
"QLgdT6": ["dokumen mana pun bernama ", ["0"]],
"QM3SBZ": ["Rencana (", ["done"], "/", ["0"], ")"],
"QOINDn": ["kosong"],
+ "QP9OU3": [
+ "Menautkan akan menggabungkan folder lain ke folder ini. Folder ini belum ada, jadi instal dulu sebuah skill di sini."
+ ],
"QPWyTw": ["Kelompokkan keterampilan menurut sumber"],
"QQbwzK": ["Tidak ada agen yang tersedia."],
"QQghPu": ["Pasang di Claude Desktop"],
@@ -3899,6 +3902,7 @@
"mLAjyL": [
"Beri alat AI yang Anda pakai akses untuk membaca dan memperbarui proyek Anda. Mencentang kotak langsung menyiapkannya; melepas centang menghapusnya."
],
+ "mPoOmg": ["instal dulu sebuah skill di sini"],
"mPy9lS": [
"Tata spesifikasi saya yang sudah ada menjadi indeks tertaut yang dikelompokkan per bidang, dan tandai mana saja yang sudah tidak selaras dengan kode saat ini."
],
diff --git a/packages/app/src/locales/id/messages.po b/packages/app/src/locales/id/messages.po
index 68c8e9917..53d2560a4 100644
--- a/packages/app/src/locales/id/messages.po
+++ b/packages/app/src/locales/id/messages.po
@@ -7015,6 +7015,10 @@ msgstr "Pasang {0}"
msgid "Install {brand} →"
msgstr "Pasang {brand} →"
+#: src/components/settings/SkillTargetsPicker.tsx
+msgid "install a skill here first"
+msgstr "instal dulu sebuah skill di sini"
+
#. placeholder {0}: res.error
#: src/hooks/use-explore-preview-install.ts
msgid "Install failed: {0}"
@@ -7504,6 +7508,10 @@ msgstr "Respons graf tautan tidak sesuai bentuk yang diharapkan."
msgid "Linked theme files aren’t supported"
msgstr "Berkas tema tertaut tidak didukung"
+#: src/components/settings/SkillTargetsPicker.tsx
+msgid "Linking merges another folder into this one. This folder does not exist yet, so install a skill here first."
+msgstr "Menautkan akan menggabungkan folder lain ke folder ini. Folder ini belum ada, jadi instal dulu sebuah skill di sini."
+
#: src/components/DocPanel.tsx
msgid "Links"
msgstr "Tautan"
diff --git a/packages/app/src/locales/ko/messages.json b/packages/app/src/locales/ko/messages.json
index 71bf77748..b19944fe3 100644
--- a/packages/app/src/locales/ko/messages.json
+++ b/packages/app/src/locales/ko/messages.json
@@ -1981,6 +1981,9 @@
"QLgdT6": ["이름이 ", ["0"], "인 문서"],
"QM3SBZ": ["계획 (", ["done"], "/", ["0"], ")"],
"QOINDn": ["비어 있음"],
+ "QP9OU3": [
+ "연결하면 다른 폴더가 이 폴더로 병합됩니다. 이 폴더는 아직 없으므로 여기에 먼저 스킬을 설치하세요."
+ ],
"QPWyTw": ["소스별로 스킬 그룹화"],
"QQbwzK": ["사용 가능한 에이전트 없음."],
"QQghPu": ["Claude Desktop에 설치"],
@@ -3741,6 +3744,7 @@
"mLAjyL": [
"사용하는 AI 도구에 프로젝트를 읽고 업데이트할 권한을 부여합니다. 확인란을 선택하면 즉시 설정하고, 선택을 해제하면 제거합니다."
],
+ "mPoOmg": ["여기에 먼저 스킬을 설치하세요"],
"mPy9lS": [
"기존 사양을 영역별로 그룹화한 연결된 색인으로 정리하고, 현재 코드와 동기화되지 않은 항목을 표시합니다."
],
diff --git a/packages/app/src/locales/ko/messages.po b/packages/app/src/locales/ko/messages.po
index 6adf45351..61393f5ab 100644
--- a/packages/app/src/locales/ko/messages.po
+++ b/packages/app/src/locales/ko/messages.po
@@ -7019,6 +7019,10 @@ msgstr "{0} 설치"
msgid "Install {brand} →"
msgstr "{brand} 설치 →"
+#: src/components/settings/SkillTargetsPicker.tsx
+msgid "install a skill here first"
+msgstr "여기에 먼저 스킬을 설치하세요"
+
#. placeholder {0}: res.error
#: src/hooks/use-explore-preview-install.ts
msgid "Install failed: {0}"
@@ -7508,6 +7512,10 @@ msgstr "링크 그래프 응답 형식이 예상과 일치하지 않습니다."
msgid "Linked theme files aren’t supported"
msgstr "연결된 테마 파일은 지원되지 않습니다"
+#: src/components/settings/SkillTargetsPicker.tsx
+msgid "Linking merges another folder into this one. This folder does not exist yet, so install a skill here first."
+msgstr "연결하면 다른 폴더가 이 폴더로 병합됩니다. 이 폴더는 아직 없으므로 여기에 먼저 스킬을 설치하세요."
+
#: src/components/DocPanel.tsx
msgid "Links"
msgstr "링크"
diff --git a/packages/app/src/locales/pseudo/messages.json b/packages/app/src/locales/pseudo/messages.json
index 91af3b995..ee2e4ce3d 100644
--- a/packages/app/src/locales/pseudo/messages.json
+++ b/packages/app/src/locales/pseudo/messages.json
@@ -2051,6 +2051,9 @@
"QLgdT6": ["àńŷ ďōć ńàḿēď ", ["0"]],
"QM3SBZ": ["Ƥĺàń (", ["done"], "/", ["0"], ")"],
"QOINDn": ["ēḿƥţŷ"],
+ "QP9OU3": [
+ "Ĺĩńķĩńĝ ḿēŕĝēś àńōţĥēŕ ƒōĺďēŕ ĩńţō ţĥĩś ōńē. Ţĥĩś ƒōĺďēŕ ďōēś ńōţ ēxĩśţ ŷēţ, śō ĩńśţàĺĺ à śķĩĺĺ ĥēŕē ƒĩŕśţ."
+ ],
"QPWyTw": ["Ĝŕōũƥ śķĩĺĺś ƀŷ śōũŕćē"],
"QQbwzK": ["Ńō àĝēńţś àvàĩĺàƀĺē."],
"QQghPu": ["Ĩńśţàĺĺ ĩń Ćĺàũďē Ďēśķţōƥ"],
@@ -3870,6 +3873,7 @@
"mLAjyL": [
"Ĝĩvē ţĥē ÀĨ ţōōĺś ŷōũ ũśē àććēśś ţō ŕēàď àńď ũƥďàţē ŷōũŕ ƥŕōĴēćţś. Ćĥēćķĩńĝ à ƀōx śēţś ĩţ ũƥ ŕĩĝĥţ àŵàŷ; ũńćĥēćķĩńĝ ŕēḿōvēś ĩţ."
],
+ "mPoOmg": ["ĩńśţàĺĺ à śķĩĺĺ ĥēŕē ƒĩŕśţ"],
"mPy9lS": [
"Ōŕĝàńĩźē ḿŷ ēxĩśţĩńĝ śƥēćś ĩńţō à ĺĩńķēď ĩńďēx ĝŕōũƥēď ƀŷ àŕēà, àńď ƒĺàĝ àńŷ ţĥàţ ĥàvē ďŕĩƒţēď ōũţ ōƒ śŷńć ŵĩţĥ ţĥē ćũŕŕēńţ ćōďē."
],
diff --git a/packages/app/src/locales/pseudo/messages.po b/packages/app/src/locales/pseudo/messages.po
index 9cf157106..d7c190e7f 100644
--- a/packages/app/src/locales/pseudo/messages.po
+++ b/packages/app/src/locales/pseudo/messages.po
@@ -7015,6 +7015,10 @@ msgstr ""
msgid "Install {brand} →"
msgstr ""
+#: src/components/settings/SkillTargetsPicker.tsx
+msgid "install a skill here first"
+msgstr ""
+
#. placeholder {0}: res.error
#: src/hooks/use-explore-preview-install.ts
msgid "Install failed: {0}"
@@ -7504,6 +7508,10 @@ msgstr ""
msgid "Linked theme files aren’t supported"
msgstr ""
+#: src/components/settings/SkillTargetsPicker.tsx
+msgid "Linking merges another folder into this one. This folder does not exist yet, so install a skill here first."
+msgstr ""
+
#: src/components/DocPanel.tsx
msgid "Links"
msgstr ""
diff --git a/packages/app/src/locales/pt-BR/messages.json b/packages/app/src/locales/pt-BR/messages.json
index fcf3c1bc3..0c8a57011 100644
--- a/packages/app/src/locales/pt-BR/messages.json
+++ b/packages/app/src/locales/pt-BR/messages.json
@@ -2332,6 +2332,9 @@
"QLgdT6": ["qualquer documento chamado ", ["0"]],
"QM3SBZ": ["Plano (", ["done"], "/", ["0"], ")"],
"QOINDn": ["vazio"],
+ "QP9OU3": [
+ "Vincular mescla outra pasta nesta. Esta pasta ainda não existe, então instale primeiro uma habilidade aqui."
+ ],
"QPWyTw": ["Agrupar habilidades por origem"],
"QQbwzK": ["Nenhum agente disponível."],
"QQghPu": ["Instalar no Claude Desktop"],
@@ -4389,6 +4392,7 @@
"mLAjyL": [
"Dê às ferramentas de IA que você usa acesso para ler e atualizar seus projetos. Marcar uma caixa configura na hora; desmarcar remove."
],
+ "mPoOmg": ["instale primeiro uma habilidade aqui"],
"mPy9lS": [
"Organize minhas especificações existentes em um índice interligado e agrupado por área, e sinalize as que se desencontraram do código atual."
],
diff --git a/packages/app/src/locales/pt-BR/messages.po b/packages/app/src/locales/pt-BR/messages.po
index 064f8862b..e291b03b3 100644
--- a/packages/app/src/locales/pt-BR/messages.po
+++ b/packages/app/src/locales/pt-BR/messages.po
@@ -7015,6 +7015,10 @@ msgstr "Instalar {0}"
msgid "Install {brand} →"
msgstr "Instalar {brand} →"
+#: src/components/settings/SkillTargetsPicker.tsx
+msgid "install a skill here first"
+msgstr "instale primeiro uma habilidade aqui"
+
#. placeholder {0}: res.error
#: src/hooks/use-explore-preview-install.ts
msgid "Install failed: {0}"
@@ -7504,6 +7508,10 @@ msgstr "A resposta do grafo de links não tinha o formato esperado."
msgid "Linked theme files aren’t supported"
msgstr "Arquivos de tema vinculados não são compatíveis"
+#: src/components/settings/SkillTargetsPicker.tsx
+msgid "Linking merges another folder into this one. This folder does not exist yet, so install a skill here first."
+msgstr "Vincular mescla outra pasta nesta. Esta pasta ainda não existe, então instale primeiro uma habilidade aqui."
+
#: src/components/DocPanel.tsx
msgid "Links"
msgstr "Links"
diff --git a/packages/app/src/locales/ur/messages.json b/packages/app/src/locales/ur/messages.json
index 5beee1e0f..991794d0a 100644
--- a/packages/app/src/locales/ur/messages.json
+++ b/packages/app/src/locales/ur/messages.json
@@ -2097,6 +2097,9 @@
"QLgdT6": [["0"], " نام کی کوئی بھی دستاویز"],
"QM3SBZ": ["منصوبہ (", ["done"], "/", ["0"], ")"],
"QOINDn": ["خالی"],
+ "QP9OU3": [
+ "لنک کرنے سے دوسرا فولڈر اس فولڈر میں ضم ہو جاتا ہے۔ یہ فولڈر ابھی موجود نہیں ہے، اس لیے پہلے یہاں ایک اسکل انسٹال کریں۔"
+ ],
"QPWyTw": ["مہارتوں کو ماخذ کے مطابق گروپ کریں"],
"QQbwzK": ["کوئی ایجنٹ دستیاب نہیں۔"],
"QQghPu": ["Claude Desktop میں نصب کریں"],
@@ -3966,6 +3969,7 @@
"mLAjyL": [
"اپنے استعمال کے AI ٹولز کو اپنے پروجیکٹس پڑھنے اور تازہ کرنے کی رسائی دیں۔ خانہ نشان زد کرنا اسے فوراً ترتیب دے دیتا ہے؛ نشان ہٹانا اسے ہٹا دیتا ہے۔"
],
+ "mPoOmg": ["پہلے یہاں ایک اسکل انسٹال کریں"],
"mPy9lS": [
"میری موجودہ اسپیکس کو شعبے کے لحاظ سے گروپ شدہ ایک مربوط اشاریے میں منظم کریں، اور ان میں سے کسی کو نشان زد کریں جو موجودہ کوڈ سے ہم آہنگ نہ رہی ہو۔"
],
diff --git a/packages/app/src/locales/ur/messages.po b/packages/app/src/locales/ur/messages.po
index 3a718ad24..f1856964b 100644
--- a/packages/app/src/locales/ur/messages.po
+++ b/packages/app/src/locales/ur/messages.po
@@ -7019,6 +7019,10 @@ msgstr "{0} نصب کریں"
msgid "Install {brand} →"
msgstr "{brand} نصب کریں ←"
+#: src/components/settings/SkillTargetsPicker.tsx
+msgid "install a skill here first"
+msgstr "پہلے یہاں ایک اسکل انسٹال کریں"
+
#. placeholder {0}: res.error
#: src/hooks/use-explore-preview-install.ts
msgid "Install failed: {0}"
@@ -7508,6 +7512,10 @@ msgstr "لنک گراف کا جواب متوقع ساخت سے میل نہیں
msgid "Linked theme files aren’t supported"
msgstr "منسلک تھیم فائلوں کی معاونت نہیں ہے"
+#: src/components/settings/SkillTargetsPicker.tsx
+msgid "Linking merges another folder into this one. This folder does not exist yet, so install a skill here first."
+msgstr "لنک کرنے سے دوسرا فولڈر اس فولڈر میں ضم ہو جاتا ہے۔ یہ فولڈر ابھی موجود نہیں ہے، اس لیے پہلے یہاں ایک اسکل انسٹال کریں۔"
+
#: src/components/DocPanel.tsx
msgid "Links"
msgstr "لنکس"
diff --git a/packages/app/src/locales/zh-Hans/messages.json b/packages/app/src/locales/zh-Hans/messages.json
index e88644156..dfc954055 100644
--- a/packages/app/src/locales/zh-Hans/messages.json
+++ b/packages/app/src/locales/zh-Hans/messages.json
@@ -1801,6 +1801,9 @@
"QLgdT6": ["任何名为 ", ["0"], " 的文档"],
"QM3SBZ": ["计划(", ["done"], "/", ["0"], ")"],
"QOINDn": ["空"],
+ "QP9OU3": [
+ "链接会将另一个文件夹合并到此文件夹中。此文件夹尚不存在,因此请先在此处安装一个技能。"
+ ],
"QPWyTw": ["按来源分组技能"],
"QQbwzK": ["没有可用的智能体。"],
"QQghPu": ["安装到 Claude Desktop"],
@@ -3415,6 +3418,7 @@
"mHf8mp": ["删除架构文件 ", ["file"]],
"mHo0kp": ["启用 Open Knowledge 工具的请求已超时。此线程将在没有这些工具的情况下运行。"],
"mLAjyL": ["让你使用的 AI 工具能够读取和更新你的项目。勾选即刻生效;取消勾选则移除。"],
+ "mPoOmg": ["请先在此处安装一个技能"],
"mPy9lS": ["把我现有的规格整理成一个按领域分组的链接索引,并标出与当前代码脱节的部分。"],
"mPzgTS": ["打开 ", ["docName"]],
"mToVM9": ["给 ", ["agentName"], " 发消息"],
diff --git a/packages/app/src/locales/zh-Hans/messages.po b/packages/app/src/locales/zh-Hans/messages.po
index 35d32d26e..b24af62a2 100644
--- a/packages/app/src/locales/zh-Hans/messages.po
+++ b/packages/app/src/locales/zh-Hans/messages.po
@@ -7019,6 +7019,10 @@ msgstr "安装 {0}"
msgid "Install {brand} →"
msgstr "安装 {brand} →"
+#: src/components/settings/SkillTargetsPicker.tsx
+msgid "install a skill here first"
+msgstr "请先在此处安装一个技能"
+
#. placeholder {0}: res.error
#: src/hooks/use-explore-preview-install.ts
msgid "Install failed: {0}"
@@ -7508,6 +7512,10 @@ msgstr "链接关系图响应的结构与预期不符。"
msgid "Linked theme files aren’t supported"
msgstr "不支持链接的主题文件"
+#: src/components/settings/SkillTargetsPicker.tsx
+msgid "Linking merges another folder into this one. This folder does not exist yet, so install a skill here first."
+msgstr "链接会将另一个文件夹合并到此文件夹中。此文件夹尚不存在,因此请先在此处安装一个技能。"
+
#: src/components/DocPanel.tsx
msgid "Links"
msgstr "链接"
diff --git a/packages/app/src/locales/zh-Hant/messages.json b/packages/app/src/locales/zh-Hant/messages.json
index 51b0dd00a..9f22f9383 100644
--- a/packages/app/src/locales/zh-Hant/messages.json
+++ b/packages/app/src/locales/zh-Hant/messages.json
@@ -1827,6 +1827,9 @@
"QLgdT6": ["任何名為 ", ["0"], " 的文件"],
"QM3SBZ": ["計畫(", ["done"], "/", ["0"], ")"],
"QOINDn": ["空的"],
+ "QP9OU3": [
+ "連結會將另一個資料夾合併到此資料夾中。此資料夾尚不存在,因此請先在此處安裝一個技能。"
+ ],
"QPWyTw": ["依來源分組技能"],
"QQbwzK": ["沒有可用的代理。"],
"QQghPu": ["安裝到 Claude Desktop"],
@@ -3441,6 +3444,7 @@
"mHf8mp": ["刪除結構描述檔案 ", ["file"]],
"mHo0kp": ["啟用 Open Knowledge 工具的請求已逾時。此執行緒將在沒有這些工具的情況下運作。"],
"mLAjyL": ["讓你用的 AI 工具能夠讀取和更新你的專案。勾選就會立刻設定好;取消勾選則會移除。"],
+ "mPoOmg": ["請先在此處安裝一個技能"],
"mPy9lS": ["把我現有的規格整理成一個依領域分組的連結索引,並標出和目前程式碼已經脫節的部分。"],
"mPzgTS": ["開啟 ", ["docName"]],
"mToVM9": ["傳訊息給 ", ["agentName"]],
diff --git a/packages/app/src/locales/zh-Hant/messages.po b/packages/app/src/locales/zh-Hant/messages.po
index a4fe2c76a..8ba6d46d2 100644
--- a/packages/app/src/locales/zh-Hant/messages.po
+++ b/packages/app/src/locales/zh-Hant/messages.po
@@ -7019,6 +7019,10 @@ msgstr "安裝 {0}"
msgid "Install {brand} →"
msgstr "安裝 {brand} →"
+#: src/components/settings/SkillTargetsPicker.tsx
+msgid "install a skill here first"
+msgstr "請先在此處安裝一個技能"
+
#. placeholder {0}: res.error
#: src/hooks/use-explore-preview-install.ts
msgid "Install failed: {0}"
@@ -7508,6 +7512,10 @@ msgstr "連結關係圖回應的結構與預期不符。"
msgid "Linked theme files aren’t supported"
msgstr "不支援連結的主題檔案"
+#: src/components/settings/SkillTargetsPicker.tsx
+msgid "Linking merges another folder into this one. This folder does not exist yet, so install a skill here first."
+msgstr "連結會將另一個資料夾合併到此資料夾中。此資料夾尚不存在,因此請先在此處安裝一個技能。"
+
#: src/components/DocPanel.tsx
msgid "Links"
msgstr "連結"
diff --git a/packages/app/tests/integration/skills-in-place-list.test.ts b/packages/app/tests/integration/skills-in-place-list.test.ts
index 9f9ef72f4..319dbea11 100644
--- a/packages/app/tests/integration/skills-in-place-list.test.ts
+++ b/packages/app/tests/integration/skills-in-place-list.test.ts
@@ -1331,6 +1331,52 @@ describe('folder-level verbs via PUT /api/skill-targets (slice 2)', () => {
body: JSON.stringify({ folderAction: action }),
});
+ test('refuses a link whose SOURCE root does not exist, and creates nothing', async () => {
+ // The composition, not the plumbing. Nothing tested that the route's
+ // `mayCreate` closure is wired to either call site: drop `mayCreate:` from
+ // the commit path and this goes green again while the consent boundary is
+ // gone. `.codex` is absent in this fixture, so linking it would mkdir a
+ // dotdir for a tool the user never installed — the circularity the whole
+ // rule exists to prevent.
+ const res = await putFolder({
+ scope: 'project',
+ root: '.codex/skills',
+ action: 'link',
+ target: '.agents/skills',
+ });
+ expect(res.status).toBe(400);
+ const body = (await res.json()) as { title?: string };
+ // Pin that it is the CONSENT refusal, not the known-roots 400 above it — an
+ // earlier draft of this test used `.copilot/skills`, which is Copilot's USER
+ // root, so it never reached this branch and passed for the wrong reason.
+ expect(body.title).toContain('may not create on this machine');
+ expect(existsSync(join(contentDir, '.codex'))).toBe(false);
+ // The source bundles are untouched — a refusal must not half-apply.
+ expect(existsSync(join(contentDir, '.agents/skills/shared/SKILL.md'))).toBe(true);
+ });
+
+ test('refuses the same link on the PREVIEW path, with the same status', async () => {
+ // Preview exists to tell a caller what commit will decide, so it must refuse
+ // too — and pin the SAME status, which is the second call site of the same
+ // closure. Dropping `mayCreate:` from the preview call alone leaves the
+ // commit test above green.
+ const res = await putFolder({
+ scope: 'project',
+ root: '.codex/skills',
+ action: 'link',
+ target: '.agents/skills',
+ preview: true,
+ });
+ expect(res.status).toBe(400);
+ const body = (await res.json()) as { title?: string };
+ // Preview is the path the Folders UI always takes, and it used to emit the
+ // sentence WITHOUT the roots — so the audience that most needs to know which
+ // folder was refused was the one not told. `parseApiError` reads `title`
+ // only, so `detail` never reached the toast.
+ expect(body.title).toContain('.codex/skills');
+ expect(existsSync(join(contentDir, '.codex'))).toBe(false);
+ });
+
test('link merges own-only skills into the target and swaps in a symlink; unlink materializes per-skill links', async () => {
const { lstatSync: lstat, realpathSync: realpath } = await import('node:fs');
const linkRes = await putFolder({
@@ -1624,3 +1670,92 @@ describe('repo-declared plugin identity on /api/skills (no harness registry)', (
expect(skills.find((s) => s.name === 'handmade')?.plugin).toBeUndefined();
});
});
+
+/**
+ * `hubOffered` and the `folders[]` activation filter, computed by a REAL server.
+ *
+ * Both were only ever exercised through unit tests that inject the answer:
+ * `skill-install-rows.test.ts` passes `hubOffered` as a stub boolean, and
+ * `in-place-skills.test.ts` calls `isActivatedSkillRoot` directly. Neither can
+ * see WHICH base the handler measures against — and that base already regressed
+ * once in this PR (`contentDir` where the install writes to `projectDir`).
+ *
+ * Same shape as the `outsideProject` block above: split `contentDir` from
+ * `projectDir` so a wrong base is observable rather than coincidentally right.
+ */
+describe('hub activation computed server-side', () => {
+ let server: TestServer | undefined;
+ const trash: string[] = [];
+
+ afterEach(async () => {
+ await server?.cleanup();
+ server = undefined;
+ for (const d of trash.splice(0)) rmSync(d, { recursive: true, force: true });
+ });
+
+ const fetchTargets = async (): Promise<{
+ folders?: Array<{ scope: string; root: string; state: string }>;
+ }> => {
+ const res = await fetch(`http://127.0.0.1:${(server as TestServer).port}/api/skill-targets`);
+ expect(res.status).toBe(200);
+ return (await res.json()) as {
+ folders?: Array<{ scope: string; root: string; state: string }>;
+ };
+ };
+
+ const fetchHubOffered = async (): Promise<boolean | undefined> => {
+ const res = await fetch(`http://127.0.0.1:${(server as TestServer).port}/api/skills`);
+ expect(res.status).toBe(200);
+ const body = (await res.json()) as { skills: Array<{ scope: string; hubOffered?: boolean }> };
+ return body.skills.find((s) => s.scope === 'project')?.hubOffered;
+ };
+
+ test('the hub is NOT a project folder row when nothing on the machine reads it', async () => {
+ // No `.agents` anywhere and no hub reader installed: the row must not appear.
+ const projectRoot = mkdtempSync(join(tmpdir(), 'ok-hub-none-'));
+ trash.push(projectRoot);
+ writeSkill(projectRoot, '.claude/skills/x', '# X');
+ const skillsHome = mkdtempSync(join(tmpdir(), 'ok-hub-home-'));
+ trash.push(skillsHome);
+
+ server = await createTestServer({ contentDir: projectRoot, skillsHome });
+
+ const rows = (await fetchTargets()).folders ?? [];
+ expect(rows.some((f) => f.scope === 'project' && f.root === '.agents/skills')).toBe(false);
+ });
+
+ test('an existing .agents makes it a project folder row', async () => {
+ // The base-independent half: adoption activates it wherever the reader
+ // question lands, so this pins the filter is wired at all.
+ const projectRoot = mkdtempSync(join(tmpdir(), 'ok-hub-adopted-'));
+ trash.push(projectRoot);
+ writeSkill(projectRoot, '.agents/skills/shared', '# Shared');
+ const skillsHome = mkdtempSync(join(tmpdir(), 'ok-hub-home2-'));
+ trash.push(skillsHome);
+
+ server = await createTestServer({ contentDir: projectRoot, skillsHome });
+
+ const rows = (await fetchTargets()).folders ?? [];
+ expect(rows.some((f) => f.scope === 'project' && f.root === '.agents/skills')).toBe(true);
+ });
+
+ test('hubOffered is computed against projectDir, not contentDir', async () => {
+ // The regression this PR already shipped once. `content.dir: docs`, and
+ // `.agents` sits at the PROJECT root — where the install actually writes,
+ // since `skillInstallBase('project')` is `projectDir`. Measuring against
+ // contentDir answers about `<projectRoot>/docs/.agents`, which is absent,
+ // and returns false for a hub the install would land in.
+ const projectRoot = mkdtempSync(join(tmpdir(), 'ok-hub-base-'));
+ trash.push(projectRoot);
+ const docsDir = join(projectRoot, 'docs');
+ mkdirSync(docsDir, { recursive: true });
+ writeSkill(docsDir, '.claude/skills/indocs', '# In docs');
+ mkdirSync(join(projectRoot, '.agents', 'skills'), { recursive: true });
+ const skillsHome = mkdtempSync(join(tmpdir(), 'ok-hub-home3-'));
+ trash.push(skillsHome);
+
+ server = await createTestServer({ contentDir: docsDir, projectDir: projectRoot, skillsHome });
+
+ expect(await fetchHubOffered()).toBe(true);
+ });
+});
diff --git a/packages/cli/src/commands/editors.test.ts b/packages/cli/src/commands/editors.test.ts
index ab066088e..10ca349ee 100644
--- a/packages/cli/src/commands/editors.test.ts
+++ b/packages/cli/src/commands/editors.test.ts
@@ -271,12 +271,16 @@ describe('resolvePiAgentDirPath', () => {
});
describe('resolveLmStudioConfigPath', () => {
- it('defaults macOS to the observed cache path when no config exists yet', () => {
- // The documented `~/.lmstudio/mcp.json` is a silent no-op on macOS (LM
- // Studio reads `~/.cache/lm-studio/mcp.json`; bug-tracker#1371), so a fresh
- // install resolves to the cache path we know it actually reads.
+ it('defaults macOS to the documented ~/.lmstudio path when no config exists yet', () => {
+ // Through v0.3.33 macOS really did read `~/.cache/lm-studio/mcp.json`
+ // (bug-tracker#1371) and this defaulted there. Verified on 0.4.21: the
+ // documented path is the real one. An upgraded machine can still hold an
+ // EMPTY `~/.cache/lm-studio/` dir, and defaulting there wrote a config
+ // LM Studio never reads — an install that kept a real file at the cache
+ // path is still resolved by the existing-file check below, which does not
+ // depend on this order.
expect(resolveLmStudioConfigPath({ home: '/Users/alice', platformName: 'darwin' })).toBe(
- '/Users/alice/.cache/lm-studio/mcp.json',
+ '/Users/alice/.lmstudio/mcp.json',
);
});
@@ -289,10 +293,61 @@ describe('resolveLmStudioConfigPath', () => {
);
});
+ it('darwin, both dirs present and no file anywhere: an EMPTY cache home loses', () => {
+ // The upgrade-leftover case. `~/.lmstudio` exists on every population, so it
+ // cannot discriminate; an empty `~/.cache/lm-studio` is the 0.3.x remnant the
+ // old macOS-first ordering resolved to, writing a config 0.4.21 never reads.
+ const home = mkdtempSync(join(tmpdir(), 'ok-lms-both-'));
+ mkdirSync(join(home, '.lmstudio'), { recursive: true });
+ mkdirSync(join(home, '.cache', 'lm-studio'), { recursive: true });
+ expect(resolveLmStudioConfigPath({ home, platformName: 'darwin' })).toBe(
+ join(home, '.lmstudio', 'mcp.json'),
+ );
+ rmSync(home, { recursive: true, force: true });
+ });
+
+ it('darwin, both dirs present, POPULATED cache home wins', () => {
+ // A real pre-0.3.34 install: the cache home holds state, so it is the one
+ // LM Studio actually reads and must not be abandoned for the documented path.
+ const home = mkdtempSync(join(tmpdir(), 'ok-lms-pop-'));
+ mkdirSync(join(home, '.lmstudio'), { recursive: true });
+ mkdirSync(join(home, '.cache', 'lm-studio'), { recursive: true });
+ writeFileSync(join(home, '.cache', 'lm-studio', 'settings.json'), '{}');
+ expect(resolveLmStudioConfigPath({ home, platformName: 'darwin' })).toBe(
+ join(home, '.cache', 'lm-studio', 'mcp.json'),
+ );
+ rmSync(home, { recursive: true, force: true });
+ });
+
+ it('a real file at the cache path with no ~/.lmstudio still resolves there', () => {
+ // The backward-compat guarantee the docblock promises. Step 1 is order-free,
+ // so this must hold regardless of how the candidate list is ordered.
+ const home = mkdtempSync(join(tmpdir(), 'ok-lms-cachefile-'));
+ mkdirSync(join(home, '.cache', 'lm-studio'), { recursive: true });
+ writeFileSync(join(home, '.cache', 'lm-studio', 'mcp.json'), '{"mcpServers":{}}');
+ expect(resolveLmStudioConfigPath({ home, platformName: 'darwin' })).toBe(
+ join(home, '.cache', 'lm-studio', 'mcp.json'),
+ );
+ rmSync(home, { recursive: true, force: true });
+ });
+
+ it('an EMPTY cache home does not win even when ~/.lmstudio is absent', () => {
+ // The one case the removed dir-existence step decided differently: with no
+ // `~/.lmstudio` at all, an empty `~/.cache/lm-studio` used to win purely by
+ // existing — the leftover the populated-check exists to reject.
+ const home = mkdtempSync(join(tmpdir(), 'ok-lms-emptycache-'));
+ mkdirSync(join(home, '.cache', 'lm-studio'), { recursive: true });
+ expect(resolveLmStudioConfigPath({ home, platformName: 'darwin' })).toBe(
+ join(home, '.lmstudio', 'mcp.json'),
+ );
+ rmSync(home, { recursive: true, force: true });
+ });
+
it('prefers an existing candidate dir over the platform default', () => {
const home = mkdtempSync(join(tmpdir(), 'lmstudio-home-'));
try {
- // Only the documented dir exists; macOS would otherwise default to cache.
+ // Only the documented dir exists. (Platform-dependent ordering is gone; the
+ // resolver is now the same on every platform.)
mkdirSync(join(home, '.lmstudio'), { recursive: true });
expect(resolveLmStudioConfigPath({ home, platformName: 'darwin' })).toBe(
join(home, '.lmstudio', 'mcp.json'),
diff --git a/packages/cli/src/commands/editors.ts b/packages/cli/src/commands/editors.ts
index 56fde2aec..dce8a8be2 100644
--- a/packages/cli/src/commands/editors.ts
+++ b/packages/cli/src/commands/editors.ts
@@ -5,7 +5,7 @@
* configuration. This module encodes those differences declaratively so that
* `init.ts` can loop over targets without per-editor branching.
*/
-import { existsSync } from 'node:fs';
+import { existsSync, readdirSync } from 'node:fs';
import { homedir } from 'node:os';
import { basename, dirname, join, posix, resolve, sep, win32 } from 'node:path';
import {
@@ -784,36 +784,84 @@ export function resolveAntigravityConfigPath(options: AppSupportOptions = {}): s
/**
* Candidate `mcp.json` locations for LM Studio, ordered so the first element is
* the platform default when none exist yet. LM Studio's own docs say
- * `~/.lmstudio/mcp.json`, but on macOS the file actually lives at
- * `~/.cache/lm-studio/mcp.json` — a documented-vs-real mismatch that is still
- * open upstream (lmstudio-ai/lmstudio-bug-tracker#1371, seen through v0.3.33).
- * So we probe both rather than trust either, and default macOS to the observed
- * cache path (writing the documented path there would be a silent no-op LM
- * Studio never reads).
+ * `~/.lmstudio/mcp.json`; on macOS through v0.3.33 the file actually lived at
+ * `~/.cache/lm-studio/mcp.json` (lmstudio-ai/lmstudio-bug-tracker#1371). Verified
+ * on 0.4.21: the documented path is now the real one — a fresh install creates
+ * `~/.lmstudio/mcp.json` and no `~/.cache/lm-studio` at all.
+ *
+ * We still probe both, because an install upgraded from 0.3.x may hold a real
+ * `mcp.json` at the cache path. Step 1 (an existing FILE) is order-free, so that
+ * install keeps resolving there whatever this list says.
+ *
+ * Step 2 (an existing DIR) is where the two populations are genuinely ambiguous,
+ * and `~/.lmstudio` cannot discriminate them — BOTH old and new installs have
+ * it (the app creates it as the models home). So step 2 does not guess by
+ * platform: a `~/.cache/lm-studio` that holds anything is evidence of a real
+ * pre-0.3.34 cache home and wins; an EMPTY one is the upgrade leftover that made
+ * the old macOS-first ordering write a config 0.4.21 never reads, and loses.
+ * Only when neither discriminates does the documented path win.
*/
-function lmStudioConfigCandidates(home: string, platformName: NodeJS.Platform): string[] {
+interface LmStudioCandidate {
+ /** Absolute `mcp.json` path. */
+ readonly file: string;
+ /** Its parent dir, resolved with the SAME platform path API — never the
+ * ambient `dirname`, which degenerates to `.` on a foreign-platform path and
+ * silently makes the emptiness probe read the process cwd. */
+ readonly dir: string;
+}
+
+function lmStudioConfigCandidates(
+ home: string,
+ platformName: NodeJS.Platform,
+): [LmStudioCandidate, LmStudioCandidate] {
const pathApi = pathApiForPlatform(platformName);
- const dotDir = pathApi.join(home, '.lmstudio', 'mcp.json');
- const cacheDir = pathApi.join(home, '.cache', 'lm-studio', 'mcp.json');
- return platformName === 'darwin' ? [cacheDir, dotDir] : [dotDir, cacheDir];
+ return [
+ { file: pathApi.join(home, '.lmstudio', 'mcp.json'), dir: pathApi.join(home, '.lmstudio') },
+ {
+ file: pathApi.join(home, '.cache', 'lm-studio', 'mcp.json'),
+ dir: pathApi.join(home, '.cache', 'lm-studio'),
+ },
+ ];
+}
+
+/** True when `dir` exists AND holds at least one entry. An empty dir is the
+ * upgrade leftover; a populated one is a real home. Unreadable → not evidence. */
+function isNonEmptyDir(dir: string): boolean {
+ try {
+ return readdirSync(dir).length > 0;
+ } catch {
+ return false;
+ }
}
/**
* Resolve LM Studio's user-global `mcp.json`. LM Studio is an MCP *host* that
* follows Cursor's `mcp.json` notation, so OK's entry shape is identical to
- * Cursor's — only the (unstable, see {@link lmStudioConfigCandidates}) location
- * differs. Prefers an existing `mcp.json`, then an existing candidate dir, then
- * the platform default, so we write where LM Studio will actually read.
+ * Cursor's — only the location differs (see {@link lmStudioConfigCandidates}).
+ * Two tiers, not three, and the same on every platform: an existing `mcp.json`
+ * wins wherever it sits; otherwise a POPULATED `~/.cache/lm-studio` marks a real
+ * pre-0.3.34 home and wins; otherwise the documented path. There is deliberately
+ * no "some candidate dir exists" tier — it only ever differed by handing the win
+ * to an EMPTY cache home, which is the upgrade leftover the populated check
+ * exists to reject.
*/
export function resolveLmStudioConfigPath(options: AppSupportOptions = {}): string {
const platformName = options.platformName ?? process.platform;
const home = options.home ?? homedir();
- const candidates = lmStudioConfigCandidates(home, platformName);
- const existingFile = candidates.find((candidate) => existsSync(candidate));
- if (existingFile) return existingFile;
- const existingDir = candidates.find((candidate) => existsSync(dirname(candidate)));
- if (existingDir) return existingDir;
- return candidates[0];
+ const [documented, cache] = lmStudioConfigCandidates(home, platformName);
+ const existingFile = [documented, cache].find((c) => existsSync(c.file));
+ if (existingFile) return existingFile.file;
+ // Step 2: only the CACHE home discriminates. `~/.lmstudio` exists on both
+ // populations (the app creates it as the models home), so an emptiness check
+ // there proves nothing — it is specifically a POPULATED `~/.cache/lm-studio`
+ // that marks a real pre-0.3.34 install. An empty one is the upgrade leftover.
+ if (isNonEmptyDir(cache.dir)) return cache.file;
+ // No step for "some dir exists": its ONLY behaviourally distinct outcome is
+ // `~/.lmstudio` absent + an EMPTY `~/.cache/lm-studio`, which would hand the
+ // win to the leftover the check above exists to reject. Every other input
+ // already resolves to the documented path. So the body reads as the rule does:
+ // existing file, then populated cache home, then documented.
+ return documented.file;
}
export interface EditorMcpTarget {
diff --git a/packages/cli/src/commands/repair-skills.placement.test.ts b/packages/cli/src/commands/repair-skills.placement.test.ts
index e92fb6770..6286d17d0 100644
--- a/packages/cli/src/commands/repair-skills.placement.test.ts
+++ b/packages/cli/src/commands/repair-skills.placement.test.ts
@@ -5,6 +5,7 @@
import { existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
+import { USER_SKILL_HOSTS } from '@inkeep/open-knowledge-core';
import { afterEach, describe, expect, test } from 'vitest';
import { repairSkills } from './repair-skills.ts';
@@ -19,8 +20,20 @@ const HOSTS: Array<[string, string]> = [
['.opencode', '.opencode/skills'],
['.pi', '.pi/agent/skills'],
['.gemini', '.gemini/skills'],
+ ['.lmstudio', '.lmstudio/skills'],
];
+// The list above is hand-written on purpose (these suites build fixture dirs
+// from it), but it documents itself as mirroring `USER_SKILL_HOSTS` — and a
+// hand-mirror drifts silently, which is exactly what happened when `.lmstudio`
+// was added to `EDITOR_USER_SKILL_ROOT` and neither suite noticed. This pins the
+// mirror so the NEXT editor fails here instead of going untested.
+test('HOSTS mirrors USER_SKILL_HOSTS', () => {
+ expect([...HOSTS].map(([, root]) => root).sort()).toEqual(
+ USER_SKILL_HOSTS.map((h) => h.skillsRoot).sort(),
+ );
+});
+
const cleanup: string[] = [];
afterEach(() => {
for (const p of cleanup.splice(0)) {
diff --git a/packages/core/src/bridge/bind-frontmatter-doc.ts b/packages/core/src/bridge/bind-frontmatter-doc.ts
index d7a845280..dfd95ef49 100644
--- a/packages/core/src/bridge/bind-frontmatter-doc.ts
+++ b/packages/core/src/bridge/bind-frontmatter-doc.ts
@@ -1,3 +1,4 @@
+
import type * as Y from 'yjs';
import type { Err, Ok, Result } from '../config/result.ts';
import { type FrontmatterValidationError, toFrontmatterIssue } from '../frontmatter/errors.ts';
diff --git a/packages/core/src/bridge/bridge-invariant.ts b/packages/core/src/bridge/bridge-invariant.ts
index 005627195..8bfdb40cd 100644
--- a/packages/core/src/bridge/bridge-invariant.ts
+++ b/packages/core/src/bridge/bridge-invariant.ts
@@ -1,3 +1,4 @@
+
import { fnv1aDigest } from './hash-util.ts';
export type BridgeInvariantSite = 'observer-b' | 'persistence' | 'test-harness';
diff --git a/packages/core/src/bridge/compose.ts b/packages/core/src/bridge/compose.ts
index f4cc8a286..2a597ec3d 100644
--- a/packages/core/src/bridge/compose.ts
+++ b/packages/core/src/bridge/compose.ts
@@ -1,3 +1,4 @@
+
import { prependFrontmatter, stripFrontmatter } from '../extensions/frontmatter.ts';
export type ComposeAdjustment = 'none' | 'body' | 'frontmatter' | 'unresolved';
diff --git a/packages/core/src/bridge/divergence-locate.ts b/packages/core/src/bridge/divergence-locate.ts
index 6b505314d..d979f4b39 100644
--- a/packages/core/src/bridge/divergence-locate.ts
+++ b/packages/core/src/bridge/divergence-locate.ts
@@ -1,3 +1,4 @@
+
import { findFirstDivergenceIndex } from './tolerance-telemetry.ts';
export const BRIDGE_LINE_KINDS = [
diff --git a/packages/core/src/bridge/doc-boundary-space.ts b/packages/core/src/bridge/doc-boundary-space.ts
index 8fb428b90..01ef76a9f 100644
--- a/packages/core/src/bridge/doc-boundary-space.ts
+++ b/packages/core/src/bridge/doc-boundary-space.ts
@@ -1,3 +1,4 @@
+
import { FRONTMATTER_RE, stripFrontmatter } from '../extensions/frontmatter.ts';
import { carriedEdgeEmpties, type DocEdgeEmpties } from '../markdown/doc-edge-blank-runs.ts';
diff --git a/packages/core/src/bridge/growth-detect.ts b/packages/core/src/bridge/growth-detect.ts
index 9d9c244b0..463e89595 100644
--- a/packages/core/src/bridge/growth-detect.ts
+++ b/packages/core/src/bridge/growth-detect.ts
@@ -1,3 +1,4 @@
+
const DEFAULT_MIN_SUBSTANTIVE_LINE_LENGTH = 16;
export const DUPLICATION_GATE_MIN_LINE_LENGTH = 8;
diff --git a/packages/core/src/bridge/intraline-predicate.ts b/packages/core/src/bridge/intraline-predicate.ts
index c43fdd7e7..0939885bb 100644
--- a/packages/core/src/bridge/intraline-predicate.ts
+++ b/packages/core/src/bridge/intraline-predicate.ts
@@ -1,3 +1,4 @@
+
export function rawLineCounts(doc: string): Map<string, number> {
const counts = new Map<string, number>();
for (const line of doc.split('\n')) {
diff --git a/packages/core/src/bridge/merge-three-way.ts b/packages/core/src/bridge/merge-three-way.ts
index 251560a35..c0dc65705 100644
--- a/packages/core/src/bridge/merge-three-way.ts
+++ b/packages/core/src/bridge/merge-three-way.ts
@@ -65,6 +65,7 @@ export function tryLineLevelCombine(
return { clean: true, merged };
}
+
export type BridgeMergeContentLossSide = 'user' | 'agent';
export type BridgeMergeContentLossWhich = 'substring' | 'order' | 'growth';
diff --git a/packages/core/src/bridge/normalize.ts b/packages/core/src/bridge/normalize.ts
index 01ac80099..dcc5b0690 100644
--- a/packages/core/src/bridge/normalize.ts
+++ b/packages/core/src/bridge/normalize.ts
@@ -1,3 +1,4 @@
+
import { stripFrontmatter } from '../extensions/frontmatter.ts';
import { bodyEdgeEmpties } from './doc-boundary-space.ts';
diff --git a/packages/core/src/bridge/pm-structural-equivalence.ts b/packages/core/src/bridge/pm-structural-equivalence.ts
index bb53e7c7c..4f7b79587 100644
--- a/packages/core/src/bridge/pm-structural-equivalence.ts
+++ b/packages/core/src/bridge/pm-structural-equivalence.ts
@@ -32,6 +32,7 @@ const BR_SENTINEL: PmStructuralNode = { type: '__br__' };
const BR_LITERAL_RE = /^<br\s*\/?>$/i;
+
interface DegradeEntry {
readonly label: string;
readonly severity: ToleranceClassSeverity;
@@ -128,6 +129,7 @@ export interface ComparePmStructuralOptions {
rawSourceSide?: 'expected';
}
+
/** Rebuild a node with `fn` applied to each child; identity when childless.
* Shared by the degrade canonicalizers so none re-implements the walk. */
function mapChildren(
@@ -253,6 +255,7 @@ function applyDegrades(tree: PmStructuralNode): {
return { normalized: current, fired };
}
+
export function comparePmStructural(
expected: PmStructuralNode,
actual: PmStructuralNode,
diff --git a/packages/core/src/bridge/subsequence.ts b/packages/core/src/bridge/subsequence.ts
index af20de1e2..dca644141 100644
--- a/packages/core/src/bridge/subsequence.ts
+++ b/packages/core/src/bridge/subsequence.ts
@@ -1,3 +1,4 @@
+
/** True when `needle` is a subsequence of `haystack` (two-pointer, O(n+m)):
* insertions in `haystack` are free; any dropped or substituted `needle` byte
* fails. */
diff --git a/packages/core/src/constants/editors.ts b/packages/core/src/constants/editors.ts
index af8b05f7e..4f77ae292 100644
--- a/packages/core/src/constants/editors.ts
+++ b/packages/core/src/constants/editors.ts
@@ -74,8 +74,13 @@ export const EDITOR_LABELS = {
* reads `.opencode/skills` natively AND `.agents/skills`) → duplicate /
* name-collision (the `<name>-<editor>` churn class), and
* (c) CLOBBER the symlink where `.codex`/`.cursor` symlink to `.agents`.
- * The per-editor fan-out already reaches every harness OK supports, so `.agents`
- * adds NO reach at project scope — only conflation. A genuinely new harness that
+ * The per-editor fan-out reaches every harness that HAS a project dir of its
+ * own, so for those `.agents` adds no reach at project scope — only conflation.
+ * That is not universal: a harness whose project skill surface IS the hub has
+ * no per-editor dir to fan out to, and for it `.agents` is the only reach there
+ * is (today `lm-studio`, whose entry below documents the case). Such a harness
+ * keeps a null root here — the hub is not its per-editor dir — and is declared
+ * in `HUB_READER_EDITORS` instead. A genuinely new harness that
* adopts the vendor-neutral `.agents/` convention is onboarded by adding it to
* this map (one line; flows to every dependent + lock-step test), NOT by
* broadcasting into a shared dir.
@@ -114,8 +119,21 @@ export const EDITOR_PROJECT_SKILL_ROOT = {
// Like OpenClaw, its integration is the user-global MCP config; OK ships no
// per-project skill for it.
antigravity: null,
- // LM Studio is an MCP host (its chat connects to MCP servers) with no Agent
- // Skills surface at all — OK's only integration is the user-global MCP config.
+ // LM Studio DOES read project skills, but from the vendor-neutral
+ // `<project>/.agents/skills` hub rather than a `.lmstudio/` dotdir (verified
+ // in 0.4.21: `NGProjectSkillsProvider` watches `resolve(workingDir, '.agents',
+ // 'skills')`, createIfMissing false). That hub is already a first-class OK
+ // install target (`AGENTS_SKILLS_ROOT` / the `agents` pseudo-host), so a
+ // project skill installed there ALREADY reaches LM Studio.
+ //
+ // Null here is therefore "no dedicated per-editor project dir", not "no
+ // project skills". Naming `.agents/skills` as lm-studio's project root would
+ // make one directory the write target for two different picker rows, which is
+ // exactly the Cursor/Codex conflation the header above rejects. The hub stays
+ // vendor-neutral and undecorated — no per-host rows or icons on it. It becomes
+ // an offered destination when a host that READS it is installed, via
+ // `HUB_READER_EDITORS` + `isActivatedSkillRoot`, so LM Studio's presence is
+ // what makes `.agents` available rather than LM Studio taking a row of its own.
'lm-studio': null,
// Hermes Agent (Nous Research) is a user-global terminal agent: its whole
// config lives at `~/.hermes/config.yaml` with no project-scoped skill dir OK
@@ -125,8 +143,8 @@ export const EDITOR_PROJECT_SKILL_ROOT = {
/**
* User-global skills root per editor (`~`-relative, POSIX), or `null` when OK
- * reads no user-global skill dir for it — either it keeps no skills (`lm-studio`
- * and `hermes` are config-only) or its skills live in a shared hub OK already
+ * reads no user-global skill dir for it — either it keeps no skills (`hermes` is
+ * config-only) or its skills live in a shared hub OK already
* scans (`claude-desktop` shares `~/.claude/skills`; `openclaw` reads the
* `~/.agents/skills` hub). Unlike the project map, the user dir does NOT follow
* the `<dotdir>/skills` convention for every editor — Pi nests its agent home
@@ -145,10 +163,51 @@ export const EDITOR_USER_SKILL_ROOT = {
openclaw: null,
pi: '.pi/agent/skills',
antigravity: '.gemini/skills',
- 'lm-studio': null,
+ // LM Studio loads Agent Skills from `~/.lmstudio/skills` (verified against
+ // 0.4.21: the app creates the dir on first launch, resolves it as
+ // `userGlobalSkillsFolder`, and lists what lands there). Its project skills
+ // come from the `.agents/skills` hub instead, which is why
+ // `EDITOR_PROJECT_SKILL_ROOT` stays null — see the note there.
+ 'lm-studio': '.lmstudio/skills',
hermes: null,
} as const satisfies Record<EditorId, string | null>;
+/**
+ * Editors that read the vendor-neutral `.agents/skills` hub instead of owning a
+ * skills root of their own, mapped to the dotdir whose presence proves the tool
+ * is actually installed, and the scope at which it reads the hub.
+ *
+ * These are the reason the hub can be a live destination on a project that has
+ * never used it: an agent-owned root activates when its own dotdir appears, but
+ * the hub has no owning tool, so nothing about the project could ever activate
+ * it. A host that READS it being present on this machine is the equivalent
+ * signal — without one, offering `.agents` is offering a folder nothing here
+ * would read.
+ *
+ * Scope is where the host reads the hub BY DEFAULT. LM Studio's project skills
+ * dir IS `<project>/.agents/skills` (verified 0.4.21). It can additionally be
+ * pointed at `~/.agents/skills` through its "use skills found in other apps"
+ * toggles, but those are off by default and per-user, so that is not a default
+ * OK may assume.
+ *
+ * MEMBERSHIP IS NARROWER THAN "reads the hub". A host belongs here only when it
+ * reads the hub AND has no root of its own at that scope — i.e. the hub is its
+ * ONLY destination. OpenCode (`.opencode/skills`) and Pi (`.pi/skills`) both
+ * read `.agents/skills` too and are deliberately absent: OK already writes their
+ * own roots, so activating the hub for them would not reach an agent it was
+ * missing, it would add a SECOND place the same agent reads. That is the
+ * double-load hazard `EDITOR_PROJECT_SKILL_ROOT`'s header warns about, which is
+ * also why this list is not derived from "who reads `.agents`".
+ */
+export const HUB_READER_EDITORS: ReadonlyArray<{
+ readonly editorId: EditorId;
+ readonly dotDir: string;
+ readonly scope: 'project' | 'global';
+}> = [
+ { editorId: 'lm-studio', dotDir: '.lmstudio', scope: 'project' },
+ { editorId: 'openclaw', dotDir: '.openclaw', scope: 'global' },
+];
+
/**
* Repo/home dirs that hold a skills root but are NOT owned by an agent.
* `.github` carries workflows, CODEOWNERS and issue templates in nearly every
diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts
index 14f14a982..affd2bb8a 100644
--- a/packages/core/src/index.ts
+++ b/packages/core/src/index.ts
@@ -364,6 +364,7 @@ export {
EDITOR_USER_SKILL_ROOT,
type EditorId,
HOSTS_WITH_USER_SKILL_DIR,
+ HUB_READER_EDITORS,
PROJECT_SKILL_EDITOR_IDS,
PROJECT_SKILL_PROJECTION_IGNORE_PATHS,
RESERVED_PROJECT_SKILL_NAME,
diff --git a/packages/core/src/markdown/callout-transformer.ts b/packages/core/src/markdown/callout-transformer.ts
index 83d47404a..a363dfd54 100644
--- a/packages/core/src/markdown/callout-transformer.ts
+++ b/packages/core/src/markdown/callout-transformer.ts
@@ -1,3 +1,4 @@
+
import type { Blockquote, Paragraph, Root } from 'mdast';
import type { MdxJsxAttribute, MdxJsxFlowElement } from 'mdast-util-mdx';
import { visit } from 'unist-util-visit';
diff --git a/packages/core/src/markdown/code-fence.ts b/packages/core/src/markdown/code-fence.ts
index 9807a7e82..4499dbc92 100644
--- a/packages/core/src/markdown/code-fence.ts
+++ b/packages/core/src/markdown/code-fence.ts
@@ -1,3 +1,4 @@
+
export function selectFenceChar(info: string): '`' | '~' {
return info.includes('`') ? '~' : '`';
}
diff --git a/packages/core/src/markdown/comment-promoter.ts b/packages/core/src/markdown/comment-promoter.ts
index 7415c474a..34704165b 100644
--- a/packages/core/src/markdown/comment-promoter.ts
+++ b/packages/core/src/markdown/comment-promoter.ts
@@ -1,3 +1,4 @@
+
import type { Nodes, Paragraph, PhrasingContent, Root, RootContent, Text } from 'mdast';
import { SKIP, visit } from 'unist-util-visit';
import type { VFile } from 'vfile';
diff --git a/packages/core/src/markdown/dedent-block-jsx-close.ts b/packages/core/src/markdown/dedent-block-jsx-close.ts
index ece5c02a1..b6299a948 100644
--- a/packages/core/src/markdown/dedent-block-jsx-close.ts
+++ b/packages/core/src/markdown/dedent-block-jsx-close.ts
@@ -1,3 +1,4 @@
+
import { findFencedRegions, isInsideFence } from './fence-regions.ts';
const INDENTED_BLOCK_JSX_CLOSE_RE = /^([ ]{1,3})(<\/[A-Z][A-Za-z0-9_]*\s*>)([ \t]*)$/gm;
diff --git a/packages/core/src/markdown/details-accordion-promoter.ts b/packages/core/src/markdown/details-accordion-promoter.ts
index 54774764a..acd398aa6 100644
--- a/packages/core/src/markdown/details-accordion-promoter.ts
+++ b/packages/core/src/markdown/details-accordion-promoter.ts
@@ -1,3 +1,4 @@
+
import type { Nodes, Paragraph, Parent, Root, Text } from 'mdast';
import type { MdxJsxAttribute, MdxJsxFlowElement } from 'mdast-util-mdx';
import { visit } from 'unist-util-visit';
diff --git a/packages/core/src/markdown/div-align-promoter.ts b/packages/core/src/markdown/div-align-promoter.ts
index 43ecdc709..ba9b56384 100644
--- a/packages/core/src/markdown/div-align-promoter.ts
+++ b/packages/core/src/markdown/div-align-promoter.ts
@@ -1,3 +1,4 @@
+
import type { Nodes, Paragraph, Parent, Root, Text } from 'mdast';
import type { MdxJsxFlowElement } from 'mdast-util-mdx';
import { visit } from 'unist-util-visit';
diff --git a/packages/core/src/markdown/fence-regions.ts b/packages/core/src/markdown/fence-regions.ts
index 6d3f3643e..4513da9bb 100644
--- a/packages/core/src/markdown/fence-regions.ts
+++ b/packages/core/src/markdown/fence-regions.ts
@@ -1,3 +1,4 @@
+
const FENCE_RE = /^(`{3,}|~{3,})/gm;
export function findFencedRegions(src: string): Array<[number, number]> {
diff --git a/packages/core/src/markdown/fixtures/index.ts b/packages/core/src/markdown/fixtures/index.ts
index 00f5771ee..6931623c7 100644
--- a/packages/core/src/markdown/fixtures/index.ts
+++ b/packages/core/src/markdown/fixtures/index.ts
@@ -1,3 +1,4 @@
+
import { readFileSync } from 'node:fs';
import { dirname, resolve } from 'node:path';
import { fileURLToPath } from 'node:url';
@@ -8,6 +9,7 @@ function fixturePath(...segments: string[]): string {
return resolve(FIXTURES_DIR, ...segments);
}
+
interface GfmExample {
section: string;
markdown: string;
@@ -17,6 +19,7 @@ export function loadGfmExamples(): GfmExample[] {
return JSON.parse(readFileSync(fixturePath('gfm', 'examples.json'), 'utf8')) as GfmExample[];
}
+
interface MdxCrashEntry {
id: string;
input: string;
@@ -68,6 +71,7 @@ export function loadLargeEmbedFixtures(): LargeEmbedFixture[] {
) as LargeEmbedFixture[];
}
+
export function loadPrd6955Before(): string {
return readFileSync(fixturePath('regression', 'prd-6955-before.md'), 'utf8');
}
@@ -76,6 +80,7 @@ export function loadPrd6955CorruptedTriplicated(): string {
return readFileSync(fixturePath('regression', 'prd-6955-corrupted-triplicated.md'), 'utf8');
}
+
export interface NgPinnedCase {
id: string;
name: string;
@@ -92,6 +97,7 @@ export function loadNgPinnedCases(): NgPinnedCase[] {
) as NgPinnedCase[];
}
+
export function loadLargeRealistic(): string {
return readFileSync(fixturePath('perf', 'large-realistic.md'), 'utf8');
}
diff --git a/packages/core/src/markdown/fixtures/perf/generate.ts b/packages/core/src/markdown/fixtures/perf/generate.ts
index 8b1eb8519..daa3ef82b 100644
--- a/packages/core/src/markdown/fixtures/perf/generate.ts
+++ b/packages/core/src/markdown/fixtures/perf/generate.ts
@@ -1,3 +1,4 @@
+
import { writeFileSync } from 'node:fs';
import { dirname, resolve } from 'node:path';
import { fileURLToPath } from 'node:url';
@@ -10,6 +11,7 @@ const BASELINE_ONLY_COUNTS = [500, 2500] as const;
const SEED = 0xf1de1117;
+
function mulberry32(seed: number): () => number {
let a = seed >>> 0;
return () => {
@@ -36,6 +38,7 @@ function pickWeighted<T>(rand: () => number, items: readonly [T, number][]): T {
return items[items.length - 1][0];
}
+
const WORDS = [
'lorem',
'ipsum',
@@ -153,6 +156,7 @@ function mdxBlock(rand: () => number): string {
return `<${name}>\n\n${sentence(rand)}\n\n</${name}>`;
}
+
type BlockKind = 'paragraph' | 'heading' | 'list' | 'code' | 'table' | 'mdx';
const MIX: readonly [BlockKind, number][] = [
@@ -191,6 +195,7 @@ function generateDocument(blockCount: number, seed: number): string {
return `${blocks.join('\n\n')}\n`;
}
+
function main(): void {
for (const count of [...BLOCK_COUNTS, ...BASELINE_ONLY_COUNTS]) {
const doc = generateDocument(count, SEED);
diff --git a/packages/core/src/markdown/guard-flanking-matrix.ts b/packages/core/src/markdown/guard-flanking-matrix.ts
index 420dc0fe5..32c055c5b 100644
--- a/packages/core/src/markdown/guard-flanking-matrix.ts
+++ b/packages/core/src/markdown/guard-flanking-matrix.ts
@@ -7,6 +7,7 @@ import {
import { BACKSLASH_GUARD_SUBSTITUTIONS, encodeBackslashEscapes } from './backslash-escape-guard.ts';
import { ENTITY_REF_GUARD_SUBSTITUTIONS, encodeEntityRefs } from './entity-ref-guard.ts';
+
export const ATTENTION_DELIMITERS = ['*', '_', '**', '~~', '=='] as const;
export type FlankClass = 'whitespace' | 'punctuation' | 'other';
diff --git a/packages/core/src/markdown/handler-shadow-audit.ts b/packages/core/src/markdown/handler-shadow-audit.ts
index 2653473da..283913255 100644
--- a/packages/core/src/markdown/handler-shadow-audit.ts
+++ b/packages/core/src/markdown/handler-shadow-audit.ts
@@ -1,3 +1,4 @@
+
export interface HandlerShadowWitness {
input: string;
expect: 'byte' | 'byte-and-reparse-type';
diff --git a/packages/core/src/markdown/highlight-promoter.ts b/packages/core/src/markdown/highlight-promoter.ts
index da0a81d23..5d1000cc4 100644
--- a/packages/core/src/markdown/highlight-promoter.ts
+++ b/packages/core/src/markdown/highlight-promoter.ts
@@ -1,3 +1,4 @@
+
import type { Nodes, Parent, PhrasingContent, Root, Text } from 'mdast';
import type { MdxJsxTextElement } from 'mdast-util-mdx';
import { SKIP, visit } from 'unist-util-visit';
diff --git a/packages/core/src/markdown/html-to-mdast.ts b/packages/core/src/markdown/html-to-mdast.ts
index 787315157..9681c0056 100644
--- a/packages/core/src/markdown/html-to-mdast.ts
+++ b/packages/core/src/markdown/html-to-mdast.ts
@@ -1,3 +1,4 @@
+
import type { Element as HastElement, Root as HastRoot } from 'hast';
import type { List, Nodes as MdastNodes, Root as MdastRoot } from 'mdast';
import rehypeParse from 'rehype-parse';
@@ -128,7 +129,8 @@ export function htmlToMdast(html: string, options?: HtmlToMdastOptions): MdastRo
throw new HtmlPayloadTooLargeError(html.length, maxBytes);
}
- const processor = unified().use(rehypeParse, { fragment: true });
+ const processor = unified()
+ .use(rehypeParse, { fragment: true });
for (const plugin of cleanupPlugins) {
processor.use(plugin);
diff --git a/packages/core/src/markdown/image-promoter.ts b/packages/core/src/markdown/image-promoter.ts
index 706fa9afb..994eb6917 100644
--- a/packages/core/src/markdown/image-promoter.ts
+++ b/packages/core/src/markdown/image-promoter.ts
@@ -1,3 +1,4 @@
+
import type { Image, Paragraph, Root } from 'mdast';
import type { MdxJsxAttribute, MdxJsxFlowElement } from 'mdast-util-mdx';
import { visit } from 'unist-util-visit';
diff --git a/packages/core/src/markdown/index.ts b/packages/core/src/markdown/index.ts
index 779e27500..ec1ac1b7e 100644
--- a/packages/core/src/markdown/index.ts
+++ b/packages/core/src/markdown/index.ts
@@ -1,3 +1,4 @@
+
import {
type FromProseMirrorOptions,
fromPmMark,
@@ -206,6 +207,7 @@ export class MarkdownManager {
}
}
+
const registry = createRegistry();
function destructureAttrs(
@@ -254,6 +256,7 @@ function destructureAttrs(
return result;
}
+
function hasDirtyDescendant(node: PmNode): boolean {
let found = false;
node.descendants((child) => {
@@ -276,6 +279,7 @@ function effectiveDirty(node: PmNode, freshnessChecker?: StructuralFreshnessChec
return freshnessChecker ? freshnessChecker.isDiverged(node.toJSON()) : false;
}
+
function isEmptyMdastParagraph(node: MdastNodes): boolean {
if (node.type !== 'paragraph') return false;
const children = node.children ?? [];
@@ -344,6 +348,7 @@ function extractTextFromMdastNodes(nodes: MdastNodes[]): string {
return out;
}
+
import {
AUDIO_EXTENSIONS,
FILE_ATTACHMENT_EXTENSIONS,
@@ -596,6 +601,7 @@ function buildMdastToPmHandlers(
}));
}
+
if (m.emphasis) {
handlers.emphasis = toPmMark(m.emphasis, (node: Emphasis) => ({
sourceDelimiter: node.data?.sourceDelimiter ?? '*',
@@ -676,6 +682,7 @@ function buildMdastToPmHandlers(
}));
}
+
if (m.link) {
const sourceLiteralMark = m.sourceLiteral;
handlers.link = (node: Link, _parent: MdastParent, state: MdastToPmState) => {
@@ -973,6 +980,7 @@ function buildMdastToPmHandlers(
};
}
+
const blockUnknownHandler = (node: {
type: string;
position?: { start: { offset: number }; end: { offset: number } };
@@ -1098,6 +1106,7 @@ function buildMdastToPmHandlers(
return handlers as RemarkProseMirrorOptions['handlers'];
}
+
function buildPmToMdastHandlers(
schema: Schema,
freshness: FreshnessCheckerHolder,
diff --git a/packages/core/src/markdown/lint/applies-to.ts b/packages/core/src/markdown/lint/applies-to.ts
index fa0be9e86..b79e9aef7 100644
--- a/packages/core/src/markdown/lint/applies-to.ts
+++ b/packages/core/src/markdown/lint/applies-to.ts
@@ -1,3 +1,4 @@
+
import picomatch from 'picomatch';
import { SUPPORTED_DOC_EXTENSIONS } from '../../constants/doc-extensions.ts';
diff --git a/packages/core/src/markdown/lint/config-files.ts b/packages/core/src/markdown/lint/config-files.ts
index 312c9c74b..94b34dee1 100644
--- a/packages/core/src/markdown/lint/config-files.ts
+++ b/packages/core/src/markdown/lint/config-files.ts
@@ -1,3 +1,4 @@
+
const MARKDOWNLINT_JSON_CONFIG_FILES: ReadonlySet<string> = new Set([
'.markdownlint.json',
'.markdownlint.jsonc',
diff --git a/packages/core/src/markdown/lint/config-schemas.ts b/packages/core/src/markdown/lint/config-schemas.ts
index cc667b93e..7c54c0a73 100644
--- a/packages/core/src/markdown/lint/config-schemas.ts
+++ b/packages/core/src/markdown/lint/config-schemas.ts
@@ -52,6 +52,7 @@ const fullPluginShape = Object.fromEntries(
LINT_PLUGINS.map((plugin) => [plugin.id, plugin.sliceSchema]),
) as z.ZodRawShape;
+
export const LinterConfigSchema = z.object({
enabled: z.boolean(),
plugins: z.object(fullPluginShape),
diff --git a/packages/core/src/markdown/lint/default-config.ts b/packages/core/src/markdown/lint/default-config.ts
index d48eea5e4..a51f2ffb0 100644
--- a/packages/core/src/markdown/lint/default-config.ts
+++ b/packages/core/src/markdown/lint/default-config.ts
@@ -6,6 +6,7 @@ export const DEFAULT_MARKDOWNLINT_CONFIG: Record<string, MarkdownlintRuleSetting
MD013: false,
};
+
export function resolveMarkdownlintConfig(
rules: Record<string, MarkdownlintRuleSetting> | undefined,
): Configuration {
diff --git a/packages/core/src/markdown/lint/frontmatter-schema-edit.ts b/packages/core/src/markdown/lint/frontmatter-schema-edit.ts
index ef478e268..9c9542661 100644
--- a/packages/core/src/markdown/lint/frontmatter-schema-edit.ts
+++ b/packages/core/src/markdown/lint/frontmatter-schema-edit.ts
@@ -1,3 +1,4 @@
+
import { CANONICAL_SCHEMA_DIALECT_URIS, DEFAULT_SCHEMA_DIALECT } from './frontmatter-validate.ts';
export interface FrontmatterFieldConstraint {
diff --git a/packages/core/src/markdown/lint/frontmatter-validate.ts b/packages/core/src/markdown/lint/frontmatter-validate.ts
index 5f953d667..b0e7833fd 100644
--- a/packages/core/src/markdown/lint/frontmatter-validate.ts
+++ b/packages/core/src/markdown/lint/frontmatter-validate.ts
@@ -1,3 +1,4 @@
+
import Ajv, { type ValidateFunction } from 'ajv';
import Ajv2019 from 'ajv/dist/2019.js';
import Ajv2020 from 'ajv/dist/2020.js';
diff --git a/packages/core/src/markdown/lint/index.ts b/packages/core/src/markdown/lint/index.ts
index 781226a5d..26fbc2b22 100644
--- a/packages/core/src/markdown/lint/index.ts
+++ b/packages/core/src/markdown/lint/index.ts
@@ -1,3 +1,4 @@
+
import type { LintPluginFailureReporter } from './plugin-failure.ts';
import { isLintPluginSelected, LINT_PLUGINS, type LinterConfig } from './plugins.ts';
import type { LintDiagnostic } from './types.ts';
@@ -79,7 +80,8 @@ function renderErrorMessage(error: unknown, depth = 0): string {
try {
const json = JSON.stringify(error);
if (json !== undefined) return json;
- } catch {}
+ } catch {
+ }
}
return String(error);
}
diff --git a/packages/core/src/markdown/lint/okf-frontmatter/materialize.ts b/packages/core/src/markdown/lint/okf-frontmatter/materialize.ts
index 7a5af097e..f438f1b16 100644
--- a/packages/core/src/markdown/lint/okf-frontmatter/materialize.ts
+++ b/packages/core/src/markdown/lint/okf-frontmatter/materialize.ts
@@ -1,3 +1,4 @@
+
import type { OkfRuleId } from '../okf-rule-meta.ts';
import { fileNameFor, OKF_SCHEMA_DIR, okfSchemaPathFor } from './paths.ts';
import { OKF_FRONTMATTER_REGISTRY } from './registry.ts';
diff --git a/packages/core/src/markdown/lint/okf-frontmatter/paths.ts b/packages/core/src/markdown/lint/okf-frontmatter/paths.ts
index 1ee913527..c290b6878 100644
--- a/packages/core/src/markdown/lint/okf-frontmatter/paths.ts
+++ b/packages/core/src/markdown/lint/okf-frontmatter/paths.ts
@@ -1,3 +1,4 @@
+
import type { OkfRuleId } from '../okf-rule-meta.ts';
export const OKF_SCHEMA_DIR = '.ok/okf';
diff --git a/packages/core/src/markdown/lint/okf-frontmatter/registry.ts b/packages/core/src/markdown/lint/okf-frontmatter/registry.ts
index f325fbbb4..53ecb619d 100644
--- a/packages/core/src/markdown/lint/okf-frontmatter/registry.ts
+++ b/packages/core/src/markdown/lint/okf-frontmatter/registry.ts
@@ -1,3 +1,4 @@
+
import { compileAppliesTo } from '../applies-to.ts';
import { validateFrontmatterSource } from '../frontmatter-validate.ts';
import {
diff --git a/packages/core/src/markdown/lint/okf-frontmatter/schemas.ts b/packages/core/src/markdown/lint/okf-frontmatter/schemas.ts
index f1c37671b..89845d3d5 100644
--- a/packages/core/src/markdown/lint/okf-frontmatter/schemas.ts
+++ b/packages/core/src/markdown/lint/okf-frontmatter/schemas.ts
@@ -1,3 +1,4 @@
+
// file-level form is deliberate: the sibling `biome-ignore` must sit on the line
// oxlint-disable unicorn/no-thenable
diff --git a/packages/core/src/markdown/lint/okf-project/rules.ts b/packages/core/src/markdown/lint/okf-project/rules.ts
index 6d691ae2b..8b476332e 100644
--- a/packages/core/src/markdown/lint/okf-project/rules.ts
+++ b/packages/core/src/markdown/lint/okf-project/rules.ts
@@ -1,3 +1,4 @@
+
import { SUPPORTED_DOC_EXTENSIONS } from '../../../constants/doc-extensions.ts';
import { isOkfRuleEnabled, type OkfRuleId, type OkfRuleToggles } from '../okf-rule-meta.ts';
diff --git a/packages/core/src/markdown/lint/okf-rule-meta.ts b/packages/core/src/markdown/lint/okf-rule-meta.ts
index 4de50d79f..44913a9dc 100644
--- a/packages/core/src/markdown/lint/okf-rule-meta.ts
+++ b/packages/core/src/markdown/lint/okf-rule-meta.ts
@@ -1,3 +1,4 @@
+
export const OKF_RULE_IDS = [
'no-wiki-links',
'log-shape',
diff --git a/packages/core/src/markdown/lint/okf-rules.ts b/packages/core/src/markdown/lint/okf-rules.ts
index 1d5538421..d0999b62e 100644
--- a/packages/core/src/markdown/lint/okf-rules.ts
+++ b/packages/core/src/markdown/lint/okf-rules.ts
@@ -1,3 +1,4 @@
+
import { isOkfRuleEnabled, type OkfRuleId, type OkfRuleToggles } from './okf-rule-meta.ts';
import type { OkfRule } from './okf-runner.ts';
import { indexShape } from './rules/index-shape.ts';
diff --git a/packages/core/src/markdown/lint/okf-runner.ts b/packages/core/src/markdown/lint/okf-runner.ts
index de130e3f4..fabb08d6e 100644
--- a/packages/core/src/markdown/lint/okf-runner.ts
+++ b/packages/core/src/markdown/lint/okf-runner.ts
@@ -1,3 +1,4 @@
+
import type { Root } from 'mdast';
import remarkFrontmatter from 'remark-frontmatter';
import remarkGfm from 'remark-gfm';
diff --git a/packages/core/src/markdown/lint/plugin-failure.ts b/packages/core/src/markdown/lint/plugin-failure.ts
index e7d694890..1cd0d2543 100644
--- a/packages/core/src/markdown/lint/plugin-failure.ts
+++ b/packages/core/src/markdown/lint/plugin-failure.ts
@@ -1,3 +1,4 @@
+
import type { LintPluginId } from './types.ts';
export interface LintPluginFailure {
diff --git a/packages/core/src/markdown/lint/plugins.ts b/packages/core/src/markdown/lint/plugins.ts
index e7455ccf7..1dae8316d 100644
--- a/packages/core/src/markdown/lint/plugins.ts
+++ b/packages/core/src/markdown/lint/plugins.ts
@@ -1,3 +1,4 @@
+
import { z } from 'zod';
import { DEFAULT_MARKDOWNLINT_CONFIG, resolveMarkdownlintConfig } from './default-config.ts';
import {
@@ -23,6 +24,7 @@ import {
type OkfSlice,
} from './types.ts';
+
const MarkdownlintRuleSettingSchema = z.union([
z.boolean(),
z.enum(MARKDOWNLINT_RULE_SEVERITIES),
diff --git a/packages/core/src/markdown/lint/rules/index-shape.ts b/packages/core/src/markdown/lint/rules/index-shape.ts
index 59fe9b87d..fcbb1b56c 100644
--- a/packages/core/src/markdown/lint/rules/index-shape.ts
+++ b/packages/core/src/markdown/lint/rules/index-shape.ts
@@ -1,3 +1,4 @@
+
import type { List, ListItem } from 'mdast';
import { EXIT, visit } from 'unist-util-visit';
import { defineScopedOkfRule } from '../okf-runner.ts';
diff --git a/packages/core/src/markdown/lint/rules/log-shape.ts b/packages/core/src/markdown/lint/rules/log-shape.ts
index e0159519f..431e4e9c8 100644
--- a/packages/core/src/markdown/lint/rules/log-shape.ts
+++ b/packages/core/src/markdown/lint/rules/log-shape.ts
@@ -1,3 +1,4 @@
+
import type { Heading } from 'mdast';
import { toString as headingText } from 'mdast-util-to-string';
import { visit } from 'unist-util-visit';
diff --git a/packages/core/src/markdown/lint/rules/no-wiki-links.ts b/packages/core/src/markdown/lint/rules/no-wiki-links.ts
index 2123e977f..f75a04d15 100644
--- a/packages/core/src/markdown/lint/rules/no-wiki-links.ts
+++ b/packages/core/src/markdown/lint/rules/no-wiki-links.ts
@@ -1,3 +1,4 @@
+
import type { Point } from 'unist';
import { visit } from 'unist-util-visit';
import { defineOkfRule } from '../okf-runner.ts';
diff --git a/packages/core/src/markdown/lint/rules/reserved-casing.ts b/packages/core/src/markdown/lint/rules/reserved-casing.ts
index 89ef3e4a9..c8b4d8f28 100644
--- a/packages/core/src/markdown/lint/rules/reserved-casing.ts
+++ b/packages/core/src/markdown/lint/rules/reserved-casing.ts
@@ -1,3 +1,4 @@
+
import { SUPPORTED_DOC_EXTENSIONS } from '../../../constants/doc-extensions.ts';
import { defineOkfRule } from '../okf-runner.ts';
diff --git a/packages/core/src/markdown/lint/types.ts b/packages/core/src/markdown/lint/types.ts
index 2cffecae6..594830b88 100644
--- a/packages/core/src/markdown/lint/types.ts
+++ b/packages/core/src/markdown/lint/types.ts
@@ -1,3 +1,4 @@
+
import type { BrokenLinkReason } from '../../schemas/api/agent-write.ts';
import type { OkfRuleId } from './okf-rule-meta.ts';
@@ -112,6 +113,7 @@ export interface OkfSlice {
generate?: { index?: boolean };
}
+
interface RuleOptionSpecBase {
key: string;
description: string;
diff --git a/packages/core/src/markdown/lint/validation-counts.ts b/packages/core/src/markdown/lint/validation-counts.ts
index 98238656e..437cc539a 100644
--- a/packages/core/src/markdown/lint/validation-counts.ts
+++ b/packages/core/src/markdown/lint/validation-counts.ts
@@ -1,3 +1,4 @@
+
export interface ValidationSourceCounts {
errorCount: number;
warningCount: number;
diff --git a/packages/core/src/markdown/math-promoter.ts b/packages/core/src/markdown/math-promoter.ts
index a5b511f25..bd79424c7 100644
--- a/packages/core/src/markdown/math-promoter.ts
+++ b/packages/core/src/markdown/math-promoter.ts
@@ -1,3 +1,4 @@
+
import type { Code, Root } from 'mdast';
import type { Math as MdastMath } from 'mdast-util-math';
import type { MdxJsxAttribute, MdxJsxFlowElement } from 'mdast-util-mdx';
diff --git a/packages/core/src/markdown/mdast-to-hast-handlers.ts b/packages/core/src/markdown/mdast-to-hast-handlers.ts
index ed89371d0..00fbc0035 100644
--- a/packages/core/src/markdown/mdast-to-hast-handlers.ts
+++ b/packages/core/src/markdown/mdast-to-hast-handlers.ts
@@ -1,3 +1,4 @@
+
import type { Comment, Element, ElementContent, Properties } from 'hast';
import type { FootnoteDefinition, FootnoteReference } from 'mdast';
import type { MdxJsxFlowElement, MdxJsxTextElement } from 'mdast-util-mdx';
diff --git a/packages/core/src/markdown/mdast-to-html.ts b/packages/core/src/markdown/mdast-to-html.ts
index 8ce2b2492..df788a80d 100644
--- a/packages/core/src/markdown/mdast-to-html.ts
+++ b/packages/core/src/markdown/mdast-to-html.ts
@@ -1,3 +1,4 @@
+
import type { Element, Root as HastRoot, Text as HastText } from 'hast';
import type { Root as MdastRoot, Text as MdastText } from 'mdast';
import type { Handler } from 'mdast-util-to-hast';
diff --git a/packages/core/src/markdown/merged-walker.ts b/packages/core/src/markdown/merged-walker.ts
index bfd7e3109..fa3cfcd86 100644
--- a/packages/core/src/markdown/merged-walker.ts
+++ b/packages/core/src/markdown/merged-walker.ts
@@ -1,3 +1,4 @@
+
import type { Nodes, Parent, Root } from 'mdast';
import { SKIP, visit } from 'unist-util-visit';
import type { VFile } from 'vfile';
diff --git a/packages/core/src/markdown/mermaid-promoter.ts b/packages/core/src/markdown/mermaid-promoter.ts
index 1a897fca8..17ed2b829 100644
--- a/packages/core/src/markdown/mermaid-promoter.ts
+++ b/packages/core/src/markdown/mermaid-promoter.ts
@@ -1,3 +1,4 @@
+
import type { Code, Root } from 'mdast';
import type { MdxJsxAttribute, MdxJsxFlowElement } from 'mdast-util-mdx';
import { visit } from 'unist-util-visit';
diff --git a/packages/core/src/markdown/parse-with-fallback.ts b/packages/core/src/markdown/parse-with-fallback.ts
index d988f4b8b..4aa0490c4 100644
--- a/packages/core/src/markdown/parse-with-fallback.ts
+++ b/packages/core/src/markdown/parse-with-fallback.ts
@@ -168,6 +168,7 @@ export function parseRecursive(
}
}
+
interface VFilePlace {
offset?: number;
start?: { offset?: number };
@@ -186,6 +187,7 @@ function extractErrorOffset(err: unknown): number | undefined {
return undefined;
}
+
interface Region {
start: number;
end: number;
@@ -209,6 +211,7 @@ function nearestBlankLineAfter(src: string, offset: number): number | null {
return null;
}
+
export interface TagEvent {
kind: 'open' | 'close' | 'self-close';
name: string;
@@ -355,6 +358,7 @@ function findFallbackRegion(src: string, errorOffset: number): Region {
return { start: blockStart, end: blockEnd };
}
+
interface SourceBlock {
src: string;
start: number;
@@ -452,6 +456,7 @@ function tryPerBlockFallback(
};
}
+
function wholeDocRawText(source: string): JSONContent {
return {
type: 'doc',
diff --git a/packages/core/src/markdown/parser-drop-closure.ts b/packages/core/src/markdown/parser-drop-closure.ts
index e6ab4fd57..43d420187 100644
--- a/packages/core/src/markdown/parser-drop-closure.ts
+++ b/packages/core/src/markdown/parser-drop-closure.ts
@@ -1,3 +1,4 @@
+
export type DroppedTokenAdjudication =
| {
kind: 'format-dof-axis';
diff --git a/packages/core/src/markdown/pipeline.ts b/packages/core/src/markdown/pipeline.ts
index 0e3224206..55736041c 100644
--- a/packages/core/src/markdown/pipeline.ts
+++ b/packages/core/src/markdown/pipeline.ts
@@ -1,3 +1,4 @@
+
import {
type FromProseMirrorOptions,
fromProseMirror,
diff --git a/packages/core/src/markdown/position-aware-join.ts b/packages/core/src/markdown/position-aware-join.ts
index 91cdf658f..ccf06e94d 100644
--- a/packages/core/src/markdown/position-aware-join.ts
+++ b/packages/core/src/markdown/position-aware-join.ts
@@ -1,3 +1,4 @@
+
import type { Join } from 'mdast-util-to-markdown';
import type { Position } from 'unist';
import { isBlankLineParagraph } from './zero-emission-blocks.ts';
diff --git a/packages/core/src/markdown/position-slice.ts b/packages/core/src/markdown/position-slice.ts
index 0f399d34c..e5b4c9eba 100644
--- a/packages/core/src/markdown/position-slice.ts
+++ b/packages/core/src/markdown/position-slice.ts
@@ -1,3 +1,4 @@
+
import type { Nodes, Root } from 'mdast';
import { visit } from 'unist-util-visit';
import type { VFile } from 'vfile';
@@ -476,7 +477,8 @@ export function applyPositionSliceToNode(
const first = source[startOff];
if (first !== '[' && first !== '<' && !node.title) {
node.data.sourceStyle = 'gfm-autolink';
- } else if (first === '[') {
+ }
+ else if (first === '[') {
const slice = source.slice(startOff, endOff);
const closeBracketIdx = slice.lastIndexOf('](');
if (closeBracketIdx !== -1) {
diff --git a/packages/core/src/markdown/rehype-plugins/skip-notion-whitespace.ts b/packages/core/src/markdown/rehype-plugins/skip-notion-whitespace.ts
index db10fa54b..ca225ce9b 100644
--- a/packages/core/src/markdown/rehype-plugins/skip-notion-whitespace.ts
+++ b/packages/core/src/markdown/rehype-plugins/skip-notion-whitespace.ts
@@ -1,3 +1,4 @@
+
import type { Comment, Element, Root, Text } from 'hast';
import type { Plugin } from 'unified';
diff --git a/packages/core/src/markdown/rehype-plugins/strip-cocoa-meta.ts b/packages/core/src/markdown/rehype-plugins/strip-cocoa-meta.ts
index 34068d103..3a2524a9a 100644
--- a/packages/core/src/markdown/rehype-plugins/strip-cocoa-meta.ts
+++ b/packages/core/src/markdown/rehype-plugins/strip-cocoa-meta.ts
@@ -1,3 +1,4 @@
+
import type { Element, ElementContent, Root } from 'hast';
import type { Plugin } from 'unified';
diff --git a/packages/core/src/markdown/rehype-plugins/strip-gdocs-wrapper.ts b/packages/core/src/markdown/rehype-plugins/strip-gdocs-wrapper.ts
index 93151d43b..2279a0189 100644
--- a/packages/core/src/markdown/rehype-plugins/strip-gdocs-wrapper.ts
+++ b/packages/core/src/markdown/rehype-plugins/strip-gdocs-wrapper.ts
@@ -1,3 +1,4 @@
+
import type { Element, Root } from 'hast';
import type { Plugin } from 'unified';
diff --git a/packages/core/src/markdown/rehype-plugins/strip-github-hovercard.ts b/packages/core/src/markdown/rehype-plugins/strip-github-hovercard.ts
index 188f02d83..a0f467c42 100644
--- a/packages/core/src/markdown/rehype-plugins/strip-github-hovercard.ts
+++ b/packages/core/src/markdown/rehype-plugins/strip-github-hovercard.ts
@@ -1,3 +1,4 @@
+
import type { Element, Root } from 'hast';
import type { Plugin } from 'unified';
diff --git a/packages/core/src/markdown/rehype-plugins/strip-gmail-classes.ts b/packages/core/src/markdown/rehype-plugins/strip-gmail-classes.ts
index 4ba2c3418..4e8542a21 100644
--- a/packages/core/src/markdown/rehype-plugins/strip-gmail-classes.ts
+++ b/packages/core/src/markdown/rehype-plugins/strip-gmail-classes.ts
@@ -1,3 +1,4 @@
+
import type { Element, Root } from 'hast';
import type { Plugin } from 'unified';
diff --git a/packages/core/src/markdown/rehype-plugins/strip-gsheets-wrapper.ts b/packages/core/src/markdown/rehype-plugins/strip-gsheets-wrapper.ts
index 1a74b1272..a3c96b24a 100644
--- a/packages/core/src/markdown/rehype-plugins/strip-gsheets-wrapper.ts
+++ b/packages/core/src/markdown/rehype-plugins/strip-gsheets-wrapper.ts
@@ -1,3 +1,4 @@
+
import type { Element, ElementContent, Root } from 'hast';
import type { Plugin } from 'unified';
diff --git a/packages/core/src/markdown/rehype-plugins/strip-mso-styles.ts b/packages/core/src/markdown/rehype-plugins/strip-mso-styles.ts
index de35e7b79..e95cf43d6 100644
--- a/packages/core/src/markdown/rehype-plugins/strip-mso-styles.ts
+++ b/packages/core/src/markdown/rehype-plugins/strip-mso-styles.ts
@@ -1,3 +1,4 @@
+
import type { Comment, Element, ElementContent, Root } from 'hast';
import type { Plugin } from 'unified';
diff --git a/packages/core/src/markdown/rehype-plugins/strip-slack-classes.ts b/packages/core/src/markdown/rehype-plugins/strip-slack-classes.ts
index b4be1b2ea..ffdb4d5b5 100644
--- a/packages/core/src/markdown/rehype-plugins/strip-slack-classes.ts
+++ b/packages/core/src/markdown/rehype-plugins/strip-slack-classes.ts
@@ -1,3 +1,4 @@
+
import type { Element, ElementContent, Root } from 'hast';
import type { Plugin } from 'unified';
diff --git a/packages/core/src/markdown/rehype-plugins/strip-vscode-spans.ts b/packages/core/src/markdown/rehype-plugins/strip-vscode-spans.ts
index 3c8d88b7c..e2a96d1a7 100644
--- a/packages/core/src/markdown/rehype-plugins/strip-vscode-spans.ts
+++ b/packages/core/src/markdown/rehype-plugins/strip-vscode-spans.ts
@@ -1,3 +1,4 @@
+
import type { Element, Root } from 'hast';
import type { Plugin } from 'unified';
diff --git a/packages/core/src/markdown/resolve-image-url.ts b/packages/core/src/markdown/resolve-image-url.ts
index cf2c9da8e..0389575ac 100644
--- a/packages/core/src/markdown/resolve-image-url.ts
+++ b/packages/core/src/markdown/resolve-image-url.ts
@@ -1,3 +1,4 @@
+
import { isRelativeUrl } from './safe-url.ts';
function isDevDiagnosticContext(): boolean {
diff --git a/packages/core/src/markdown/safe-url.ts b/packages/core/src/markdown/safe-url.ts
index 4d3250d3a..8be632ba4 100644
--- a/packages/core/src/markdown/safe-url.ts
+++ b/packages/core/src/markdown/safe-url.ts
@@ -1,3 +1,4 @@
+
export const SAFE_URL_SCHEMES = ['https', 'http', 'mailto', 'tel', 'ftp', 'sms'] as const;
const SCHEME_ALT = SAFE_URL_SCHEMES.map((s) => `${s}:`).join('|');
diff --git a/packages/core/src/markdown/serialize-fidelity.test-helper.ts b/packages/core/src/markdown/serialize-fidelity.test-helper.ts
index 0dd54070e..96304e7a5 100644
--- a/packages/core/src/markdown/serialize-fidelity.test-helper.ts
+++ b/packages/core/src/markdown/serialize-fidelity.test-helper.ts
@@ -1,3 +1,4 @@
+
import type { JSONContent } from '@tiptap/core';
import type { Nodes } from 'mdast';
import { expect } from 'vitest';
diff --git a/packages/core/src/markdown/serialize-helpers.ts b/packages/core/src/markdown/serialize-helpers.ts
index 7cac5b042..93798cf83 100644
--- a/packages/core/src/markdown/serialize-helpers.ts
+++ b/packages/core/src/markdown/serialize-helpers.ts
@@ -1,3 +1,4 @@
+
import type { Node as PmNode } from '@tiptap/pm/model';
import type {
MdxJsxAttribute,
diff --git a/packages/core/src/markdown/single-dollar-math-promoter.ts b/packages/core/src/markdown/single-dollar-math-promoter.ts
index b012a5aff..8c08b7a04 100644
--- a/packages/core/src/markdown/single-dollar-math-promoter.ts
+++ b/packages/core/src/markdown/single-dollar-math-promoter.ts
@@ -1,3 +1,4 @@
+
import type { PhrasingContent, Root, Text } from 'mdast';
import type { InlineMath } from 'mdast-util-math';
import { SKIP, visit } from 'unist-util-visit';
diff --git a/packages/core/src/markdown/to-markdown-handlers.ts b/packages/core/src/markdown/to-markdown-handlers.ts
index b50bea5ec..83d4af672 100644
--- a/packages/core/src/markdown/to-markdown-handlers.ts
+++ b/packages/core/src/markdown/to-markdown-handlers.ts
@@ -1,3 +1,4 @@
+
import type { Nodes, Parents } from 'mdast';
import type { MdxJsxAttribute, MdxJsxExpressionAttribute, MdxJsxFlowElement } from 'mdast-util-mdx';
import type { Handle, Info, State } from 'mdast-util-to-markdown';
diff --git a/packages/core/src/markdown/underline-promoter.ts b/packages/core/src/markdown/underline-promoter.ts
index 0f1b0f27d..6e6d73400 100644
--- a/packages/core/src/markdown/underline-promoter.ts
+++ b/packages/core/src/markdown/underline-promoter.ts
@@ -1,3 +1,4 @@
+
import type { Nodes, Parent, Root } from 'mdast';
import type { MdxJsxTextElement } from 'mdast-util-mdx';
import { visit } from 'unist-util-visit';
diff --git a/packages/core/src/markdown/unknown-mdast-guard.ts b/packages/core/src/markdown/unknown-mdast-guard.ts
index 1a082bda7..932d7d2a8 100644
--- a/packages/core/src/markdown/unknown-mdast-guard.ts
+++ b/packages/core/src/markdown/unknown-mdast-guard.ts
@@ -1,3 +1,4 @@
+
import type { Root as MdastRoot } from 'mdast';
import type { VFile } from 'vfile';
diff --git a/packages/core/src/markdown/whitespace-char-ref.ts b/packages/core/src/markdown/whitespace-char-ref.ts
index d578476a7..ac9f5239b 100644
--- a/packages/core/src/markdown/whitespace-char-ref.ts
+++ b/packages/core/src/markdown/whitespace-char-ref.ts
@@ -1,3 +1,4 @@
+
const INLINE_WHITESPACE_BY_CODE: ReadonlyMap<number, string> = new Map([
[0x20, ' '],
[0x09, '\t'],
diff --git a/packages/core/src/markdown/wiki-link-micromark.ts b/packages/core/src/markdown/wiki-link-micromark.ts
index 6dad26200..afd9936fe 100644
--- a/packages/core/src/markdown/wiki-link-micromark.ts
+++ b/packages/core/src/markdown/wiki-link-micromark.ts
@@ -17,6 +17,7 @@ declare module 'micromark-util-types' {
}
}
+
const CODE_BANG = 33; // !
const CODE_LBRACKET = 91; // [
const CODE_RBRACKET = 93; // ]
@@ -260,6 +261,7 @@ export function wikiLinkSyntax(): Extension {
};
}
+
function enterWikiLink(this: CompileContext, token: Token) {
this.enter(
{
@@ -385,6 +387,7 @@ export const wikiLinkToMarkdown: {
unsafe: [{ character: '[', inConstruct: ['phrasing'] }],
};
+
const MICROMARK_EXT = wikiLinkSyntax();
export function remarkWikiLink(this: Processor) {
diff --git a/packages/core/src/schemas/api/tags-search.ts b/packages/core/src/schemas/api/tags-search.ts
index eede18995..74a95eb54 100644
--- a/packages/core/src/schemas/api/tags-search.ts
+++ b/packages/core/src/schemas/api/tags-search.ts
@@ -550,6 +550,10 @@ export const SkillsListEntrySchema = z
* silently no-ops (e.g. Copilot with no `~/.copilot`), which flashed a
* checkmark then reverted. Absent → the menu offers all. */
installableEditors: z.array(z.string()).optional(),
+ hubOffered: z.boolean().optional().meta({
+ description:
+ 'Whether the vendor-neutral `.agents/skills` hub is a live destination at this scope on THIS machine — server-computed via the same predicate that filters the Folders surface, so the install menu and Settings cannot disagree. True when the project already uses the hub OR a host that reads it is installed (`HUB_READER_EDITORS`).',
+ }),
/** Per-skill install-mode preference: editor fan-out uses symlinks to the
* canonical instead of copies. Machine-local. */
linkMode: z.boolean().optional(),
diff --git a/packages/core/src/skill-targets/editor-single-source.test.ts b/packages/core/src/skill-targets/editor-single-source.test.ts
index 318781e03..03fec9c4f 100644
--- a/packages/core/src/skill-targets/editor-single-source.test.ts
+++ b/packages/core/src/skill-targets/editor-single-source.test.ts
@@ -21,6 +21,7 @@ import {
EDITOR_PROJECT_SKILL_ROOT,
EDITOR_USER_SKILL_ROOT,
HOSTS_WITH_USER_SKILL_DIR,
+ HUB_READER_EDITORS,
PROJECT_SKILL_EDITOR_IDS,
receivesProjectIntegrationWrite,
USER_MCP_GATED_EDITOR_IDS,
@@ -148,3 +149,27 @@ describe('receivesProjectIntegrationWrite', () => {
}
});
});
+
+describe('HUB_READER_EDITORS', () => {
+ // The docblock's rule is "reads the hub AND has no root of its own at that
+ // scope". Pinning two example exclusions (OpenCode, Pi) by name does not stop
+ // a future `{ editorId: 'codex', dotDir: '.codex', scope: 'project' }` — which
+ // violates the rule, compiles cleanly, and reintroduces the double-load hazard
+ // silently. This pins the invariant.
+ test('every member has a null skill root at its declared scope', () => {
+ for (const { editorId, scope } of HUB_READER_EDITORS) {
+ const map = scope === 'project' ? EDITOR_PROJECT_SKILL_ROOT : EDITOR_USER_SKILL_ROOT;
+ expect({ editorId, scope, root: map[editorId] }).toEqual({ editorId, scope, root: null });
+ }
+ });
+
+ test('a host with its own root at that scope is rejected by the rule', () => {
+ // The counter-case the rule exists for, stated as a property rather than a
+ // name: OpenCode and Pi read `.agents` too, but both have project roots, so
+ // neither may be a member.
+ for (const id of ['opencode', 'pi'] as const) {
+ expect(EDITOR_PROJECT_SKILL_ROOT[id]).not.toBeNull();
+ expect(HUB_READER_EDITORS.some((r) => r.editorId === id)).toBe(false);
+ }
+ });
+});
diff --git a/packages/core/src/skill-targets/schema.ts b/packages/core/src/skill-targets/schema.ts
index 6da28b8a9..29ec690ef 100644
--- a/packages/core/src/skill-targets/schema.ts
+++ b/packages/core/src/skill-targets/schema.ts
@@ -15,7 +15,8 @@
*
* Only editors with a project skill surface are valid targets
* (`claude` / `cursor` / `codex` / `copilot` / `opencode` / `pi`; Claude Desktop, OpenClaw,
- * and Antigravity read user-global skills only).
+ * Antigravity, LM Studio, and Hermes read user-global skills only — LM Studio's
+ * project skills come from the shared `.agents/skills` hub, not a dir of its own).
*/
import { z } from 'zod';
@@ -30,11 +31,12 @@ import {
* single source `PROJECT_SKILL_EDITOR_IDS` (derived from `EDITOR_PROJECT_SKILL_ROOT`)
* so the two can't drift. z.enum needs a literal tuple, which the derived array's
* `.filter` widens to `EditorId`, so the cast restates the narrow literal shape:
- * `Exclude<EditorId, 'claude-desktop' | 'openclaw' | 'antigravity' | 'hermes'>`
+ * `Exclude<EditorId, 'claude-desktop' | 'openclaw' | 'antigravity' | 'lm-studio' | 'hermes'>`
* is exactly the set of editors WITH a project skill surface (`claude` /
* `cursor` / `codex` / `copilot` / `opencode` / `pi`). claude-desktop, openclaw,
- * antigravity, and hermes have a null project skill root (user-global skills
- * only), so they are excluded. schema.test.ts asserts the cast stays
+ * antigravity, lm-studio, and hermes have a null project skill root, so they are
+ * excluded — for lm-studio that means "no per-editor project dir", not "no
+ * project skills": it reads the shared `.agents/skills` hub instead. schema.test.ts asserts the cast stays
* value-equal to the derived list as a backstop.
*/
type ProjectSkillEditorId = Exclude<
@@ -52,10 +54,11 @@ export type SkillTargetEditor = z.infer<typeof SkillTargetEditorSchema>;
/**
* Editor ids valid as USER-GLOBAL install targets — the project set plus the
* user-root-only editors (today: `antigravity`, whose skills live at
- * `~/.gemini/skills`). Same derived-tuple cast discipline as above;
- * schema.test.ts pins value-equality with `USER_SKILL_EDITOR_IDS`.
+ * `~/.gemini/skills`, and `lm-studio`, at `~/.lmstudio/skills`). Same
+ * derived-tuple cast discipline as above; schema.test.ts pins value-equality
+ * with `USER_SKILL_EDITOR_IDS`.
*/
-type UserSkillEditorId = Exclude<EditorId, 'claude-desktop' | 'openclaw' | 'lm-studio' | 'hermes'>;
+type UserSkillEditorId = Exclude<EditorId, 'claude-desktop' | 'openclaw' | 'hermes'>;
export const SkillUserTargetEditorSchema = z.enum(
USER_SKILL_EDITOR_IDS as unknown as readonly [UserSkillEditorId, ...UserSkillEditorId[]],
);
diff --git a/packages/desktop/src/main/integrations-settings.ts b/packages/desktop/src/main/integrations-settings.ts
index a1a3e85ae..67984d0e3 100644
--- a/packages/desktop/src/main/integrations-settings.ts
+++ b/packages/desktop/src/main/integrations-settings.ts
@@ -182,10 +182,12 @@ export interface EditorPresenceProbes {
* an editor the user has never installed, and keeps reporting it after the
* user removes the entry.
*
- * `lm-studio` is deliberately absent: it ships no CLI and registers no scheme OK
- * can ask about, so there is nothing honest to probe. It reports undetected
- * rather than falling back to the directory check — under-claiming is the safe
- * direction, and no surface prints a presence claim anyway.
+ * `lm-studio` is deliberately absent: it ships no CLI on PATH (0.4.21 drops an
+ * `lms` binary at `~/.lmstudio/bin/lms` and only best-effort links it), and its
+ * `lmstudio:` scheme routes nothing OK can ask about, so there is nothing honest
+ * to probe. It reports undetected rather than falling back to the directory
+ * check — under-claiming is the safe direction, and no surface prints a presence
+ * claim anyway.
*/
export function detectedEditorsFromProbes(probes: EditorPresenceProbes): Set<McpWiringEditorId> {
const scheme = (id: string): boolean => probes.schemeHandler[id] === true;
@@ -197,8 +199,8 @@ export function detectedEditorsFromProbes(probes: EditorPresenceProbes): Set<Mcp
//
// The gate is load-bearing, not a type formality: `cliOnPath` is keyed by
// `string`, and an id outside this registry is one OK has no honest CLI
- // signal for — `lm-studio` ships no CLI, so a caller handing us a `true` for
- // it must not turn into a presence claim.
+ // signal for — `lm-studio` ships no CLI OK resolves on PATH, so a caller
+ // handing us a `true` for it must not turn into a presence claim.
const cliIds = new Set<string>(TERMINAL_CLI_IDS);
for (const [id, onPath] of Object.entries(probes.cliOnPath)) {
if (onPath === true && cliIds.has(id)) detected.add(id as McpWiringEditorId);
diff --git a/packages/desktop/src/main/skill-reclaim.placement.test.ts b/packages/desktop/src/main/skill-reclaim.placement.test.ts
index 61ebbf19e..bfa2d3cf4 100644
--- a/packages/desktop/src/main/skill-reclaim.placement.test.ts
+++ b/packages/desktop/src/main/skill-reclaim.placement.test.ts
@@ -9,6 +9,7 @@
import { existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { dirname, join } from 'node:path';
+import { USER_SKILL_HOSTS } from '@inkeep/open-knowledge-core';
import { afterEach, describe, expect, test } from 'vitest';
import { reclaimUserSkillsOnLaunch } from './skill-reclaim.ts';
@@ -25,8 +26,20 @@ const HOSTS: Array<[string, string]> = [
['.opencode', '.opencode/skills'],
['.pi', '.pi/agent/skills'],
['.gemini', '.gemini/skills'],
+ ['.lmstudio', '.lmstudio/skills'],
];
+// The list above is hand-written on purpose (these suites build fixture dirs
+// from it), but it documents itself as mirroring `USER_SKILL_HOSTS` — and a
+// hand-mirror drifts silently, which is exactly what happened when `.lmstudio`
+// was added to `EDITOR_USER_SKILL_ROOT` and neither suite noticed. This pins the
+// mirror so the NEXT editor fails here instead of going untested.
+test('HOSTS mirrors USER_SKILL_HOSTS', () => {
+ expect([...HOSTS].map(([, root]) => root).sort()).toEqual(
+ USER_SKILL_HOSTS.map((h) => h.skillsRoot).sort(),
+ );
+});
+
const cleanup: string[] = [];
afterEach(() => {
for (const p of cleanup.splice(0)) {
diff --git a/packages/server/src/api-extension.ts b/packages/server/src/api-extension.ts
index bbf373bc8..e3f4ece88 100644
--- a/packages/server/src/api-extension.ts
+++ b/packages/server/src/api-extension.ts
@@ -572,6 +572,7 @@ import {
} from './http/workspace-tools-routes.ts';
import {
aliasedSourceRoots,
+ isActivatedSkillRoot,
removableSkillOccurrenceDirs,
resolveDefaultSkillHomeRel,
resolveGlobalNativeSkillDir,
@@ -13937,6 +13938,39 @@ export function createApiExtension(
const globalInstallableEditors: string[] = detectUserSkillHosts(skillsHome).map(
(h) => h.editorId,
);
+ // Probed against `projectDir`, not `contentDir`, for the same reason the
+ // sibling gate above states: that is what `skillInstallBase('project')`
+ // resolves to, so this must ask about the base the install it gates will
+ // actually write into. They differ when `content.dir` names a subdir.
+ //
+ // ONE predicate, TWO bases — each consumer probes the base it writes
+ // into. The install menu consumes this flag and installs to
+ // `skillInstallBase('project')` = `projectDir`; the Folders surface and
+ // the folder verbs write under `contentDir` and probe that. The two
+ // coincide unless `content.dir` names a subdirectory of the project.
+ //
+ // Where they diverge, only the `HUB_READER_EDITORS` branch is
+ // base-independent, so the split is narrow: `<contentDir>/.agents`
+ // present with no reader installed and no `<projectDir>/.agents` gives
+ // Folders an `absent` hub row while the menu gets `hubOffered: false`.
+ // ACCEPTED rather than papered over — probing one base for both would
+ // make one of the two gates answer about a directory its own writes
+ // never touch, which is the failure the sibling comment above documents.
+ //
+ // What is NOT accepted is the old split: the menu keying off a skill
+ // ALREADY living under `.agents/`, so a reader-activated hub showed in
+ // Settings and was absent from the menu the docs pointed at — with the
+ // hub not a link target until it exists, that left no non-circular way
+ // to make the first placement.
+ const projectHubOffered: boolean = projectDir
+ ? isActivatedSkillRoot(projectDir, 'project', AGENTS_SKILLS_ROOT, skillsHome)
+ : false;
+ const globalHubOffered: boolean = isActivatedSkillRoot(
+ skillsHome,
+ 'global',
+ AGENTS_SKILLS_ROOT,
+ skillsHome,
+ );
const projectInstalled = projectDir ? readInstalledSkills(projectDir).skills : {};
const globalInstalled = readInstalledSkills(skillsHome).skills;
// Import provenance (project skills only — the global store is unversioned
@@ -14140,6 +14174,7 @@ export function createApiExtension(
hosts: [...s.hosts],
size: s.size,
installableEditors: projectInstallableEditors,
+ hubOffered: projectHubOffered,
...(s.pack !== undefined ? { pack: s.pack } : {}),
...(s.linkedHosts.length > 0 ? { symlinkedHosts: [...s.linkedHosts] } : {}),
...(Object.keys(projectAliases).length > 0 ? { hostAliases: projectAliases } : {}),
@@ -14216,6 +14251,7 @@ export function createApiExtension(
...(hostQualifier !== undefined ? { hostQualifier } : {}),
size: s.size,
installableEditors: globalInstallableEditors,
+ hubOffered: globalHubOffered,
...(s.pack !== undefined ? { pack: s.pack } : {}),
...(s.linkedHosts.length > 0 ? { symlinkedHosts: [...s.linkedHosts] } : {}),
...(Object.keys(globalAliases).length > 0 ? { hostAliases: globalAliases } : {}),
diff --git a/packages/server/src/http/workspace-tools-routes.ts b/packages/server/src/http/workspace-tools-routes.ts
index c50c72e72..4c8168c67 100644
--- a/packages/server/src/http/workspace-tools-routes.ts
+++ b/packages/server/src/http/workspace-tools-routes.ts
@@ -23,8 +23,10 @@
* every `/api/*` request, so admission outcomes are identical either way.
*/
-import { resolve } from 'node:path';
+import { existsSync } from 'node:fs';
+import { join, resolve } from 'node:path';
import {
+ AGENTS_SKILLS_ROOT,
EmptyRequestSchema,
LinkPreviewRequestSchema,
LinkPreviewResponseSchema,
@@ -416,7 +418,7 @@ export function createWorkspaceToolsRoutes(deps: WorkspaceToolsRouteDeps): ApiRo
folders: [
...(projectDir
? scanSkillFolderStates(contentDir, knownSkillRootsFor(contentDir, 'project'))
- .filter((f) => isActivatedSkillRoot(contentDir, 'project', f.root))
+ .filter((f) => isActivatedSkillRoot(contentDir, 'project', f.root, skillsHome))
.map((f) => ({
...f,
scope: 'project' as const,
@@ -424,7 +426,7 @@ export function createWorkspaceToolsRoutes(deps: WorkspaceToolsRouteDeps): ApiRo
}))
: []),
...scanSkillFolderStates(skillsHome, knownSkillRootsFor(skillsHome, 'global'))
- .filter((f) => isActivatedSkillRoot(skillsHome, 'global', f.root))
+ .filter((f) => isActivatedSkillRoot(skillsHome, 'global', f.root, skillsHome))
.map((f) => ({
...f,
scope: 'global' as const,
@@ -525,6 +527,33 @@ export function createWorkspaceToolsRoutes(deps: WorkspaceToolsRouteDeps): ApiRo
);
return;
}
+ // CONSENT is enforced inside the link primitive via `mayCreate`, which
+ // is REQUIRED there — so both operands are covered (a link mkdirs the
+ // target root AND the folder's parent dotdir) and no caller can reach
+ // the primitive without answering. An earlier version guarded only the
+ // target, here in the route, which left the other operand reachable
+ // from MCP and any direct call; making the parameter optional would
+ // have left the same hole one omitted argument away.
+ // ONE emitter for this refusal, reached from BOTH the preview and the
+ // commit branch. They were hand-written twice and had already drifted:
+ // same status, different message — the preview one omitted the roots,
+ // and preview is the path the Folders UI always takes, so the audience
+ // that most needs to know WHICH folder was refused was the one not
+ // told. `parseApiError` reads `title` only, so `detail` does not
+ // rescue it. Parity is now structural rather than remembered.
+ const refuseNotPermitted = (roots: string[]): void => {
+ errorResponse(
+ res,
+ 400,
+ 'urn:ok:error:invalid-request',
+ `That link would create a folder OpenKnowledge may not create on this machine: ${roots.join(', ')}.`,
+ { handler: 'skill-targets-put', detail: roots.join(', ') },
+ );
+ };
+ const mayCreate = (rootRel: string): boolean =>
+ isActivatedSkillRoot(base, fa.scope, rootRel, skillsHome) &&
+ !(rootRel === AGENTS_SKILLS_ROOT && !existsSync(join(base, rootRel)));
+
// PREVIEW: classify the merge and return it, writing nothing — the
// Folders surface discloses what a link moves and deletes before it
// asks for it. No receipt, no change signal: nothing changed.
@@ -533,7 +562,12 @@ export function createWorkspaceToolsRoutes(deps: WorkspaceToolsRouteDeps): ApiRo
base,
folderRel: fa.root,
targetRootRel: target,
+ mayCreate,
});
+ if (p.kind === 'not-permitted') {
+ refuseNotPermitted(p.roots);
+ return;
+ }
const plan = p.kind === 'plan' ? p.plan : null;
successResponse(
res,
@@ -561,23 +595,32 @@ export function createWorkspaceToolsRoutes(deps: WorkspaceToolsRouteDeps): ApiRo
}
const result =
fa.action === 'link'
- ? linkEditorSkillFolder({ base, folderRel: fa.root, targetRootRel: target })
+ ? linkEditorSkillFolder({
+ base,
+ folderRel: fa.root,
+ targetRootRel: target,
+ mayCreate,
+ })
: unlinkEditorSkillFolder({
base,
folderRel: fa.root,
...(fa.exclude !== undefined ? { exclude: fa.exclude } : {}),
});
+ if (!result.ok && result.reason === 'not-permitted') {
+ refuseNotPermitted(result.roots);
+ return;
+ }
if (!result.ok) {
errorResponse(
res,
409,
'urn:ok:error:invalid-request',
result.reason === 'conflicts'
- ? `Cannot link — differing skills exist in both folders: ${(result.conflicts ?? []).join(', ')}. Resolve them first.`
+ ? `Cannot link — differing skills exist in both folders: ${result.conflicts.join(', ')}. Resolve them first.`
: result.reason === 'stray-entries'
- ? `Cannot link — the folder holds non-skill entries: ${(result.strays ?? []).join(', ')}.`
+ ? `Cannot link — the folder holds non-skill entries: ${result.strays.join(', ')}.`
: result.reason === 'partial-move'
- ? `The merge stopped partway (${(result.moved ?? []).length} skill(s) already moved — nothing lost). Run Link again to resume and complete it. (${result.error ?? ''})`
+ ? `The merge stopped partway (${result.moved.length} skill(s) already moved — nothing lost). Run Link again to resume and complete it. (${result.error ?? ''})`
: result.reason === 'not-linked'
? 'That folder is not a symlink — nothing to unlink.'
: 'That folder cannot be linked (it is already a link or the same directory).',
diff --git a/packages/server/src/in-place-skills.test.ts b/packages/server/src/in-place-skills.test.ts
index bae75659c..9a41cde99 100644
--- a/packages/server/src/in-place-skills.test.ts
+++ b/packages/server/src/in-place-skills.test.ts
@@ -14,6 +14,7 @@ import { parseSkillDir } from '@inkeep/open-knowledge-core/skills-catalog';
import { afterEach, beforeEach, describe, expect, test } from 'vitest';
import { createContentFilter } from './content-filter.ts';
import {
+ isActivatedSkillRoot,
removableSkillOccurrenceDirs,
resolveDefaultSkillHomeRel,
resolveGlobalNativeSkillDir,
@@ -565,3 +566,76 @@ describe('removableSkillOccurrenceDirs', () => {
expect(removableSkillOccurrenceDirs(base, 'project', 'nothing-here', 'h')).toEqual([]);
});
});
+
+describe('isActivatedSkillRoot', () => {
+ let base: string;
+ let home: string;
+ beforeEach(() => {
+ base = mkdtempSync(join(tmpdir(), 'ok-activated-root-'));
+ home = mkdtempSync(join(tmpdir(), 'ok-activated-home-'));
+ });
+ afterEach(() => {
+ rmSync(base, { recursive: true, force: true });
+ rmSync(home, { recursive: true, force: true });
+ });
+
+ test('an agent-owned root is gated on its dotdir', () => {
+ expect(isActivatedSkillRoot(base, 'project', '.claude/skills', home)).toBe(false);
+ mkdirSync(join(base, '.claude'), { recursive: true });
+ expect(isActivatedSkillRoot(base, 'project', '.claude/skills', home)).toBe(true);
+ });
+
+ test('the hub is NOT offered when nothing on the machine reads it', () => {
+ // The hub has no owning tool, so it must not be offered just because it
+ // could exist — that would put a folder nothing here would read in front of
+ // every user.
+ expect(existsSync(join(base, '.agents'))).toBe(false);
+ expect(isActivatedSkillRoot(base, 'project', '.agents/skills', home)).toBe(false);
+ expect(isActivatedSkillRoot(base, 'global', '.agents/skills', home)).toBe(false);
+ });
+
+ test('an installed hub reader activates the hub, at the scope it reads', () => {
+ // LM Studio reads `<project>/.agents/skills`, so installing it makes the
+ // hub a real project destination on a project that has never used it — the
+ // case that was previously reachable only by typing the path into "Add
+ // custom path". It does not speak for global scope, where LM Studio reads
+ // `~/.agents/skills` only behind an off-by-default toggle.
+ mkdirSync(join(home, '.lmstudio'), { recursive: true });
+ expect(isActivatedSkillRoot(base, 'project', '.agents/skills', home)).toBe(true);
+ expect(isActivatedSkillRoot(base, 'global', '.agents/skills', home)).toBe(false);
+ });
+
+ test('OpenClaw activates the hub at global scope, where it reads it', () => {
+ mkdirSync(join(home, '.openclaw'), { recursive: true });
+ expect(isActivatedSkillRoot(base, 'global', '.agents/skills', home)).toBe(true);
+ });
+
+ test('a hub reader that already has its own root does NOT activate the hub', () => {
+ // OpenCode and Pi read `.agents/skills` too, but OK already writes
+ // `.opencode/skills` and `.pi/skills`. Activating the hub for them would add
+ // a SECOND place the same agent reads rather than reach one it was missing —
+ // the double-load hazard `EDITOR_PROJECT_SKILL_ROOT`'s header warns about.
+ mkdirSync(join(home, '.opencode'), { recursive: true });
+ mkdirSync(join(home, '.pi'), { recursive: true });
+ expect(isActivatedSkillRoot(base, 'project', '.agents/skills', home)).toBe(false);
+ expect(isActivatedSkillRoot(base, 'global', '.agents/skills', home)).toBe(false);
+ });
+
+ test('an existing .agents dir activates it through the standard dotdir check', () => {
+ // Named for what it actually pins. `isActivatedSkillRoot` short-circuits on
+ // the dotdir check BEFORE the reader branch, so with `base/.agents` present
+ // the `true` comes entirely from that branch — this asserts nothing about
+ // HUB_READER_EDITORS, and would still pass if the reader branch were
+ // deleted. The two that DO go red if it is deleted are 'an installed hub
+ // reader activates the hub, at the scope it reads' and 'OpenClaw activates
+ // the hub at global scope, where it reads it' — named, not counted, because
+ // the negative assertions beside them stay green either way and a positional
+ // pointer breaks on the next insertion into this block.
+ mkdirSync(join(base, '.agents'), { recursive: true });
+ expect(isActivatedSkillRoot(base, 'project', '.agents/skills', home)).toBe(true);
+ });
+
+ test('a custom root always qualifies', () => {
+ expect(isActivatedSkillRoot(base, 'project', '.tim/skills', home)).toBe(true);
+ });
+});
diff --git a/packages/server/src/in-place-skills.ts b/packages/server/src/in-place-skills.ts
index 2550f728f..c3ef4122c 100644
--- a/packages/server/src/in-place-skills.ts
+++ b/packages/server/src/in-place-skills.ts
@@ -25,6 +25,7 @@ import {
EDITOR_USER_SKILL_ROOT,
type EditorId,
estimateSkillCost,
+ HUB_READER_EDITORS,
LEGACY_SKILL_STORE_ROOT,
parseFrontmatterRecord,
type SkillCostTiers,
@@ -230,11 +231,39 @@ export function standardSkillRoots(scope: SkillScope): ReadonlySet<string> {
* Deliberately NOT folded into `knownSkillRootsFor`: cleanup paths
* (`removableSkillOccurrenceDirs`, the reclaim sweeps) must keep seeing every
* root, or a stray bundle under a since-removed dotdir becomes unreachable.
+ * The `.agents/skills` hub takes its activation from a DIFFERENT signal, not
+ * from an exemption. An agent-owned root activates when its own dotdir appears,
+ * because that dotdir is evidence its tool was installed. The hub has no owning
+ * tool, so nothing about the base could ever produce that evidence — which left
+ * it reachable only by typing the path into "Add custom path", i.e. offered
+ * only to people who already knew the answer.
+ *
+ * Its equivalent signal is a host that READS it being installed on this machine
+ * (`HUB_READER_EDITORS`: LM Studio reads `<project>/.agents/skills`, OpenClaw
+ * `~/.agents/skills`). With one present, `.agents` is a folder something here
+ * would actually read, so offering it is the same promise every other row makes.
+ * With none, it is a folder nothing would read, and it stays hidden — the hub is
+ * NOT unconditionally offered.
+ *
* This gates what is OFFERED, never what is SEEN.
*/
-export function isActivatedSkillRoot(base: string, scope: SkillScope, root: string): boolean {
+export function isActivatedSkillRoot(
+ base: string,
+ scope: SkillScope,
+ root: string,
+ /** Where hub-reading tools are detected. Separate from `base` because a
+ * project-scope hub reader is still a USER-level install. Required, not
+ * defaulted: a `homedir()` fallback would let a caller silently bypass the
+ * `homeDirOverride` seam and probe the real user home from a rig or embedded
+ * host, and the failure mode is a wrong OFFER rather than an error. */
+ home: string,
+): boolean {
if (!standardSkillRoots(scope).has(root)) return true;
- return existsSync(join(base, skillRootActivationPath(root)));
+ if (existsSync(join(base, skillRootActivationPath(root)))) return true;
+ return (
+ root === AGENTS_SKILLS_ROOT &&
+ HUB_READER_EDITORS.some((r) => r.scope === scope && existsSync(join(home, r.dotDir)))
+ );
}
/**
diff --git a/packages/server/src/skill-folder-links.test.ts b/packages/server/src/skill-folder-links.test.ts
index f5b0416c3..666d6e715 100644
--- a/packages/server/src/skill-folder-links.test.ts
+++ b/packages/server/src/skill-folder-links.test.ts
@@ -19,6 +19,10 @@ import {
unlinkEditorSkillFolder,
} from './skill-folder-links.ts';
+/** Explicit opt-out for tests whose subject is not the consent gate. `mayCreate`
+ * is required precisely so this is greppable rather than an omitted argument. */
+const allow = (): boolean => true;
+
function writeSkill(root: string, rel: string, body: string): void {
const dir = join(root, rel);
mkdirSync(dir, { recursive: true });
@@ -48,6 +52,7 @@ describe('linkEditorSkillFolder (merge-then-swap)', () => {
base,
folderRel: '.codex/skills',
targetRootRel: '.agents/skills',
+ mayCreate: allow,
});
expect(preview.kind).toBe('plan');
if (preview.kind !== 'plan') return;
@@ -57,6 +62,7 @@ describe('linkEditorSkillFolder (merge-then-swap)', () => {
base,
folderRel: '.codex/skills',
targetRootRel: '.agents/skills',
+ mayCreate: allow,
});
expect(r.ok).toBe(true);
expect(lstatSync(join(base, '.codex/skills')).isSymbolicLink()).toBe(true);
@@ -72,6 +78,7 @@ describe('linkEditorSkillFolder (merge-then-swap)', () => {
base,
folderRel: '.codex/skills',
targetRootRel: '.agents/skills',
+ mayCreate: allow,
});
expect(r.ok).toBe(true);
if (!r.ok) return;
@@ -93,6 +100,7 @@ describe('linkEditorSkillFolder (merge-then-swap)', () => {
base,
folderRel: '.codex/skills',
targetRootRel: '.agents/skills',
+ mayCreate: allow,
});
expect(r.ok).toBe(false);
if (r.ok) return;
@@ -114,6 +122,7 @@ describe('linkEditorSkillFolder (merge-then-swap)', () => {
base,
folderRel: '.codex/skills',
targetRootRel: '.agents/skills',
+ mayCreate: allow,
});
expect(r.ok).toBe(true);
if (!r.ok) return;
@@ -131,6 +140,7 @@ describe('linkEditorSkillFolder (merge-then-swap)', () => {
base,
folderRel: '.codex/skills',
targetRootRel: '.agents/skills',
+ mayCreate: allow,
});
expect(r.ok).toBe(true);
@@ -152,6 +162,7 @@ describe('linkEditorSkillFolder (merge-then-swap)', () => {
base,
folderRel: '.codex/skills',
targetRootRel: '.agents/skills',
+ mayCreate: allow,
});
expect(r.ok).toBe(false);
if (!r.ok) expect(r.reason).toBe('stray-entries');
@@ -160,6 +171,7 @@ describe('linkEditorSkillFolder (merge-then-swap)', () => {
base,
folderRel: '.cursor/skills',
targetRootRel: '.agents/skills',
+ mayCreate: allow,
});
expect(r2.ok).toBe(true);
expect(lstatSync(join(base, '.cursor/skills')).isSymbolicLink()).toBe(true);
@@ -180,6 +192,7 @@ describe('linkEditorSkillFolder (merge-then-swap)', () => {
base,
folderRel: '.codex/skills',
targetRootRel: '.agents/skills',
+ mayCreate: allow,
});
expect(r.ok).toBe(true);
expect(lstatSync(join(base, '.codex/skills')).isSymbolicLink()).toBe(true);
@@ -192,6 +205,7 @@ describe('linkEditorSkillFolder (merge-then-swap)', () => {
base,
folderRel: '.codex/skills',
targetRootRel: '.agents/skills',
+ mayCreate: allow,
});
expect(r.ok).toBe(false);
if (!r.ok) expect(r.strays).toContain('notes');
@@ -206,6 +220,7 @@ describe('linkEditorSkillFolder (merge-then-swap)', () => {
base,
folderRel: '.codex/skills',
targetRootRel: '.agents/skills',
+ mayCreate: allow,
});
expect(r.ok).toBe(true);
expect(lstatSync(join(base, '.codex/skills')).isSymbolicLink()).toBe(true);
@@ -243,6 +258,7 @@ describe('previewEditorFolderLink (what a LINK would do)', () => {
base,
folderRel: '.codex/skills',
targetRootRel: '.agents/skills',
+ mayCreate: allow,
});
expect(tree(base)).toEqual(before);
expect(p.kind).toBe('plan');
@@ -255,6 +271,7 @@ describe('previewEditorFolderLink (what a LINK would do)', () => {
base,
folderRel: '.codex/skills',
targetRootRel: '.agents/skills',
+ mayCreate: allow,
});
expect(r.ok).toBe(true);
if (!r.ok) return;
@@ -275,12 +292,18 @@ describe('previewEditorFolderLink (what a LINK would do)', () => {
base,
folderRel: '.codex/skills',
targetRootRel: '.agents/skills',
+ mayCreate: allow,
});
expect(p.kind).toBe('plan');
if (p.kind !== 'plan') return;
expect(p.plan.removes).toEqual(['.system']);
- linkEditorSkillFolder({ base, folderRel: '.codex/skills', targetRootRel: '.agents/skills' });
+ linkEditorSkillFolder({
+ base,
+ folderRel: '.codex/skills',
+ targetRootRel: '.agents/skills',
+ mayCreate: allow,
+ });
expect(existsSync(join(base, '.agents/skills/.system'))).toBe(false);
});
@@ -293,6 +316,7 @@ describe('previewEditorFolderLink (what a LINK would do)', () => {
base,
folderRel: '.codex/skills',
targetRootRel: '.agents/skills',
+ mayCreate: allow,
});
expect(p.kind).toBe('plan');
if (p.kind !== 'plan') return;
@@ -305,6 +329,7 @@ describe('previewEditorFolderLink (what a LINK would do)', () => {
base,
folderRel: '.codex/skills',
targetRootRel: '.agents/skills',
+ mayCreate: allow,
});
expect(r.ok).toBe(true);
if (!r.ok) return;
@@ -322,12 +347,18 @@ describe('previewEditorFolderLink (what a LINK would do)', () => {
base,
folderRel: '.codex/skills',
targetRootRel: '.agents/skills',
+ mayCreate: allow,
});
expect(p.kind).toBe('plan');
if (p.kind !== 'plan') return;
expect(p.plan.removes).toEqual(['.git']);
- linkEditorSkillFolder({ base, folderRel: '.codex/skills', targetRootRel: '.agents/skills' });
+ linkEditorSkillFolder({
+ base,
+ folderRel: '.codex/skills',
+ targetRootRel: '.agents/skills',
+ mayCreate: allow,
+ });
// The disclosure has to match what actually happens: the history is gone.
expect(existsSync(join(base, '.agents/skills/.git'))).toBe(false);
});
@@ -344,13 +375,19 @@ describe('previewEditorFolderLink (what a LINK would do)', () => {
base,
folderRel: '.codex/skills',
targetRootRel: '.agents/skills',
+ mayCreate: allow,
});
expect(p.kind).toBe('plan');
if (p.kind !== 'plan') return;
expect(p.plan.liveDestLinks).toEqual(['shared']);
expect(p.plan.toMove).toEqual(['shared']);
- linkEditorSkillFolder({ base, folderRel: '.codex/skills', targetRootRel: '.agents/skills' });
+ linkEditorSkillFolder({
+ base,
+ folderRel: '.codex/skills',
+ targetRootRel: '.agents/skills',
+ mayCreate: allow,
+ });
// The delivery is gone: the target now holds codex's real copy, and
// `.ok/skills/shared` no longer reaches it.
expect(lstatSync(join(base, '.agents/skills/shared')).isSymbolicLink()).toBe(false);
@@ -371,6 +408,7 @@ describe('previewEditorFolderLink (what a LINK would do)', () => {
base,
folderRel: '.codex/skills',
targetRootRel: '.agents/skills',
+ mayCreate: allow,
});
expect(p.kind).toBe('plan');
if (p.kind !== 'plan') return;
@@ -389,6 +427,7 @@ describe('previewEditorFolderLink (what a LINK would do)', () => {
base,
folderRel: '.codex/skills',
targetRootRel: '.agents/skills',
+ mayCreate: allow,
});
expect(tree(base)).toEqual(before);
expect(p.kind).toBe('conflicts');
@@ -401,6 +440,7 @@ describe('previewEditorFolderLink (what a LINK would do)', () => {
base,
folderRel: '.cursor/skills',
targetRootRel: '.agents/skills',
+ mayCreate: allow,
});
expect(p.kind).toBe('absent');
expect(existsSync(join(base, '.cursor'))).toBe(false);
@@ -414,7 +454,7 @@ describe('unlinkEditorSkillFolder (materialize as per-skill links)', () => {
mkdirSync(join(base, '.codex'), { recursive: true });
symlinkSync(join(base, '.agents/skills'), join(base, '.codex/skills'), 'dir');
- const r = unlinkEditorSkillFolder({ base, folderRel: '.codex/skills' });
+ const r = unlinkEditorSkillFolder({ base, folderRel: '.codex/skills', mayCreate: allow });
expect(r.ok).toBe(true);
if (!r.ok) return;
expect(r.linked.sort()).toEqual(['one', 'two']);
@@ -436,6 +476,7 @@ describe('unlinkEditorSkillFolder (materialize as per-skill links)', () => {
base,
folderRel: '.codex/skills',
exclude: ['not-for-codex'],
+ mayCreate: allow,
});
expect(r.ok).toBe(true);
if (!r.ok) return;
@@ -447,8 +488,112 @@ describe('unlinkEditorSkillFolder (materialize as per-skill links)', () => {
test('a real folder refuses to unlink', () => {
writeSkill(base, '.codex/skills/foo', '# A');
- const r = unlinkEditorSkillFolder({ base, folderRel: '.codex/skills' });
+ const r = unlinkEditorSkillFolder({ base, folderRel: '.codex/skills', mayCreate: allow });
expect(r.ok).toBe(false);
if (!r.ok) expect(r.reason).toBe('not-linked');
});
});
+
+describe('mayCreate consent gate', () => {
+ let base: string;
+ beforeEach(() => {
+ base = mkdtempSync(join(tmpdir(), 'ok-maycreate-'));
+ });
+ afterEach(() => {
+ rmSync(base, { recursive: true, force: true });
+ });
+
+ const deny = () => false;
+
+ test('refuses when the TARGET root would be created', () => {
+ mkdirSync(join(base, '.claude', 'skills'), { recursive: true });
+ const r = linkEditorSkillFolder({
+ base,
+ folderRel: '.claude/skills',
+ targetRootRel: '.agents/skills',
+ mayCreate: deny,
+ });
+ expect(r.ok).toBe(false);
+ expect(r.ok === false && r.reason).toBe('not-permitted');
+ expect(existsSync(join(base, '.agents'))).toBe(false);
+ });
+
+ test('refuses when the FOLDER operand would be created — the half a target-only guard missed', () => {
+ // A link mkdirs `dirname(folderAbs)` too, so an absent `folderRel` creates a
+ // dotdir for a tool the user never installed. Guarding only the target left
+ // this reachable from MCP and any direct call.
+ mkdirSync(join(base, '.agents', 'skills'), { recursive: true });
+ const r = linkEditorSkillFolder({
+ base,
+ folderRel: '.copilot/skills',
+ targetRootRel: '.agents/skills',
+ mayCreate: deny,
+ });
+ expect(r.ok).toBe(false);
+ expect(r.ok === false && r.reason).toBe('not-permitted');
+ expect(existsSync(join(base, '.copilot'))).toBe(false);
+ });
+
+ test('names every root it refused, not just the first', () => {
+ const p = previewEditorFolderLink({
+ base,
+ folderRel: '.copilot/skills',
+ targetRootRel: '.agents/skills',
+ mayCreate: deny,
+ });
+ expect(p.kind).toBe('not-permitted');
+ expect(p.kind === 'not-permitted' && [...p.roots].sort()).toEqual([
+ '.agents/skills',
+ '.copilot/skills',
+ ]);
+ });
+
+ test('bypasses the predicate entirely when neither root needs creating', () => {
+ // Named for what the body does. `deny` proves the point: with both roots
+ // present the gate is never consulted, so a refusing predicate cannot block
+ // a link that creates nothing.
+ mkdirSync(join(base, '.claude', 'skills'), { recursive: true });
+ mkdirSync(join(base, '.agents', 'skills'), { recursive: true });
+ const r = linkEditorSkillFolder({
+ base,
+ folderRel: '.claude/skills',
+ targetRootRel: '.agents/skills',
+ mayCreate: deny,
+ });
+ expect(r.ok).toBe(true);
+ });
+
+ test('PERMITS and creates when the predicate allows — the common path', () => {
+ // The refusal direction was well covered and the permit direction was not,
+ // so nothing proved the gate ever lets a legitimate link through. This is
+ // the ordinary flow: `.claude` installed, `.claude/skills` not yet.
+ mkdirSync(join(base, '.claude', 'skills'), { recursive: true });
+ const r = linkEditorSkillFolder({
+ base,
+ folderRel: '.claude/skills',
+ targetRootRel: '.agents/skills',
+ mayCreate: () => true,
+ });
+ expect(r.ok).toBe(true);
+ expect(existsSync(join(base, '.agents', 'skills'))).toBe(true);
+ });
+
+ test('asks about the skills-root rel, not an absolute path or the dotdir', () => {
+ // Pins the argument contract. Every other test here ignores what the
+ // predicate receives, so passing `join(base, rel)` or the dotdir instead
+ // would leave them all green while breaking the route's real predicate,
+ // which resolves the dotdir itself via skillRootActivationPath.
+ mkdirSync(join(base, '.claude', 'skills'), { recursive: true });
+ const seen: string[] = [];
+ linkEditorSkillFolder({
+ base,
+ folderRel: '.claude/skills',
+ targetRootRel: '.agents/skills',
+ mayCreate: (rel) => {
+ seen.push(rel);
+ return true;
+ },
+ });
+ expect(seen).toEqual(['.agents/skills']);
+ });
+});
diff --git a/packages/server/src/skill-folder-links.ts b/packages/server/src/skill-folder-links.ts
index 01823a7ed..e6bb27dce 100644
--- a/packages/server/src/skill-folder-links.ts
+++ b/packages/server/src/skill-folder-links.ts
@@ -75,18 +75,24 @@ export function scanSkillFolderStates(
});
}
+/**
+ * Discriminated on `reason`, so each failure carries exactly the payload it has
+ * and TypeScript enforces it. The previous shape was one arm with every payload
+ * optional, which forced `result.roots ?? []` at the call site — a fallback that
+ * cannot fire (this is a same-process typed value, not a trust boundary) and
+ * that would silently ship an empty list if it ever did, printing the sentence
+ * with its subject removed.
+ */
export type FolderLinkResult =
| { ok: true; moved: string[]; dropped: string[]; linked: string[] }
- | {
- ok: false;
- reason: 'conflicts' | 'not-linkable' | 'not-linked' | 'stray-entries' | 'partial-move';
- conflicts?: string[];
- strays?: string[];
- /** partial-move: bundles moved before the failure — each move is a
- * complete rename, so RE-RUNNING the link resumes and completes. */
- moved?: string[];
- error?: string;
- };
+ | { ok: false; reason: 'not-permitted'; roots: string[] }
+ | { ok: false; reason: 'conflicts'; conflicts: string[] }
+ | { ok: false; reason: 'stray-entries'; strays: string[] }
+ | { ok: false; reason: 'not-linkable' }
+ | { ok: false; reason: 'not-linked' }
+ /** partial-move: bundles moved before the failure — each move is a complete
+ * rename, so RE-RUNNING the link resumes and completes. */
+ | { ok: false; reason: 'partial-move'; moved: string[]; error?: string };
/** OS / VCS noise that must not block a LINK. macOS Finder drops `.DS_Store`
* into any browsed directory, so treating every dotfile as a stray would
@@ -179,7 +185,9 @@ export type FolderLinkPreview =
| { kind: 'absent' }
| { kind: 'not-linkable' }
| { kind: 'stray-entries'; strays: string[] }
- | { kind: 'conflicts'; conflicts: string[] };
+ | { kind: 'conflicts'; conflicts: string[] }
+ /** A root the link would CREATE is not one the caller permits creating. */
+ | { kind: 'not-permitted'; roots: string[] };
/**
* Classify what `linkEditorSkillFolder` would do, WITHOUT writing anything.
@@ -190,10 +198,33 @@ export function previewEditorFolderLink(opts: {
base: string;
folderRel: string;
targetRootRel: string;
+ /** Consent gate for roots the link would CREATE. A link mkdirs BOTH the
+ * target root and the folder's parent dotdir, so both operands are creation
+ * sites — guarding only one leaves the other reachable.
+ *
+ * REQUIRED, and deliberately so. Optional-with-permissive-default only moves
+ * the remembering from "write the guard" to "pass the argument", and a
+ * missing optional property has no signal — no type error, no lint, nothing
+ * for a reviewer to see. Required means a caller that does not want the gate
+ * has to say so in a greppable way. The sibling `symlink-guard.ts` models the
+ * same fail-closed shape; this used to invert it.
+ *
+ * Called ONLY for roots already proven absent, and answered about the
+ * skills-root rel (`.copilot/skills`) — NOT the dotdir that actually gets
+ * created for the folder operand. An implementer must decide whether the
+ * root's creation is permitted, which for a host dir normally means asking
+ * about its dotdir (`isActivatedSkillRoot` → `skillRootActivationPath` does
+ * exactly that); answering the question literally would refuse the supported
+ * `.copilot` present / `.copilot/skills` absent flow. */
+ mayCreate: (rootRel: string) => boolean;
}): FolderLinkPreview {
- const { base, folderRel, targetRootRel } = opts;
+ const { base, folderRel, targetRootRel, mayCreate } = opts;
const folderAbs = join(base, folderRel);
const targetAbs = join(base, targetRootRel);
+ const wouldCreate = [targetRootRel, folderRel].filter(
+ (rel) => !existsSync(join(base, rel)) && !mayCreate(rel),
+ );
+ if (wouldCreate.length > 0) return { kind: 'not-permitted', roots: wouldCreate };
let st: ReturnType<typeof lstatSync>;
try {
st = lstatSync(folderAbs);
@@ -281,11 +312,15 @@ export function linkEditorSkillFolder(opts: {
base: string;
folderRel: string;
targetRootRel: string;
+ /** See `previewEditorFolderLink`. Required for the same reason. */
+ mayCreate: (rootRel: string) => boolean;
}): FolderLinkResult {
- const { base, folderRel, targetRootRel } = opts;
+ const { base, folderRel, targetRootRel, mayCreate } = opts;
const folderAbs = join(base, folderRel);
const targetAbs = join(base, targetRootRel);
- const preview = previewEditorFolderLink({ base, folderRel, targetRootRel });
+ const preview = previewEditorFolderLink({ base, folderRel, targetRootRel, mayCreate });
+ if (preview.kind === 'not-permitted')
+ return { ok: false, reason: 'not-permitted', roots: preview.roots };
if (preview.kind === 'absent') {
// Absent folder: nothing to merge — create the link directly.
tracedMkdirSync(dirname(folderAbs), { recursive: true });