@bevel-software/platform-core-frontend 0.25.0 → 0.26.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@bevel-software/platform-core-frontend",
3
- "version": "0.25.0",
3
+ "version": "0.26.0",
4
4
  "description": "Open-source core UI of the Bevel platform (raw TS/TSX source): workspace explorer/viewer, branches & change requests, Library, secrets, tools, access control.",
5
5
  "type": "module",
6
6
  "main": "./src/index.ts",
@@ -45,7 +45,7 @@
45
45
  "tailwind-merge": "^3.5.0",
46
46
  "xlsx": "https://cdn.sheetjs.com/xlsx-0.20.3/xlsx-0.20.3.tgz",
47
47
  "yaml": "^2.9.0",
48
- "@bevel-software/platform-shared": "0.25.0"
48
+ "@bevel-software/platform-shared": "0.26.0"
49
49
  },
50
50
  "devDependencies": {
51
51
  "@testing-library/jest-dom": "^6.9.1",
@@ -327,6 +327,59 @@ describe('ToolPage: capabilities', () => {
327
327
  });
328
328
  });
329
329
 
330
+ /**
331
+ * The marker for a tool of this server that no agent is offered, because its
332
+ * input schema is not valid JSON Schema as the server sent it.
333
+ *
334
+ * An AI client handed such a tool drops it in silence, so without this section
335
+ * the only symptom is a capability that quietly does not work. The backend
336
+ * sends the findings only to someone who may write the tool, so the page has
337
+ * no permission rule of its own: it renders what it is given.
338
+ */
339
+ describe('ToolPage: tools hidden for an invalid schema', () => {
340
+ const HIDDEN = {
341
+ name: 'notion_srv_query_data_sources',
342
+ path: '/properties/value/anyOf/0/required/0',
343
+ reason: 'must be a string',
344
+ marker:
345
+ 'Hidden from agents: its schema is invalid at /properties/value/anyOf/0/required/0 (must be a string).',
346
+ };
347
+
348
+ it('names the tool and quotes the place in the schema and the reason', async () => {
349
+ toolsMock.getToolDetail.mockResolvedValue({ ...DETAIL, type: 'mcp', hiddenTools: [HIDDEN] });
350
+ renderPage();
351
+
352
+ expect(await screen.findByRole('heading', { name: 'Not offered to assistants' })).toBeInTheDocument();
353
+ const note = screen.getByRole('note');
354
+ expect(note).toHaveTextContent('notion_srv_query_data_sources');
355
+ expect(note).toHaveTextContent(
356
+ 'Hidden from agents: its schema is invalid at /properties/value/anyOf/0/required/0 (must be a string).',
357
+ );
358
+ // What a reader has to know: it is the SERVER's schema, the other tools
359
+ // are fine, and nobody here is rewriting anything.
360
+ expect(screen.getByText(/absent from every assistant/i)).toBeInTheDocument();
361
+ expect(screen.getByText(/rest of this server's tools are unaffected/i)).toBeInTheDocument();
362
+ });
363
+
364
+ // Both cases wait for the DETAIL to be on screen, not for the heading: the
365
+ // heading's name comes from the secrets listing (`page.tool.name`), loaded
366
+ // in parallel with the detail, so it can settle first and asserting absence
367
+ // against it could pass on a page whose detail had not loaded yet.
368
+ it('shows nothing when the server is healthy', async () => {
369
+ toolsMock.getToolDetail.mockResolvedValue({ ...DETAIL, type: 'mcp', hiddenTools: [] });
370
+ renderPage();
371
+ expect(await screen.findByText('Runs LinkedIn outreach campaigns.')).toBeInTheDocument();
372
+ expect(screen.queryByRole('heading', { name: 'Not offered to assistants' })).toBeNull();
373
+ });
374
+
375
+ it('shows nothing — and does not break — when the backend does not serve the field', async () => {
376
+ toolsMock.getToolDetail.mockResolvedValue({ ...DETAIL, type: 'mcp' });
377
+ renderPage();
378
+ expect(await screen.findByText('Runs LinkedIn outreach campaigns.')).toBeInTheDocument();
379
+ expect(screen.queryByRole('heading', { name: 'Not offered to assistants' })).toBeNull();
380
+ });
381
+ });
382
+
330
383
  describe('ToolPage: powers these skills', () => {
331
384
  it('links each matching skill at the reserved skill route', async () => {
332
385
  libraryMock.listSkills.mockResolvedValue([
@@ -12,7 +12,7 @@ import { libraryHomeForItemPath, pathForPlugin, LIBRARY_ROOT } from '../../route
12
12
  import { useLibrary } from '../../state/library-data';
13
13
  import { pluginHoldingPath, pluginLabel, pluginNameForPath } from '../../utils/plugin-summary';
14
14
  import { readOAuthFragment } from '../../utils/oauth-fragment';
15
- import type { ToolCapability } from '../../services/tools.api';
15
+ import type { HiddenTool, ToolCapability } from '../../services/tools.api';
16
16
  import type { LibrarySkillSummary } from '../../services/library.api';
17
17
  import { ToolConnectionSection } from './ToolConnectionSection';
18
18
  import { ToolLogo } from '../ToolLogo';
@@ -277,6 +277,15 @@ export function ToolPage({
277
277
  />
278
278
  )}
279
279
 
280
+ {/* Above the capabilities, because it is the one thing on this page that
281
+ asks the reader to act, and because a tool missing from the
282
+ assistant's list is read as a Hexis fault until this says otherwise.
283
+ The backend sends it only to a writer of this tool, so there is no
284
+ permission check here. */}
285
+ {page.detail && (page.detail.hiddenTools?.length ?? 0) > 0 && (
286
+ <HiddenToolsSection tools={page.detail.hiddenTools ?? []} />
287
+ )}
288
+
280
289
  {page.detail && page.detail.capabilities.length > 0 && (
281
290
  <CapabilitiesSection capabilities={page.detail.capabilities} />
282
291
  )}
@@ -335,6 +344,41 @@ function SectionHeading({ children }: { children: ReactNode }) {
335
344
  return <h2 className="mb-2.5 text-label font-semibold uppercase text-ink-faint">{children}</h2>;
336
345
  }
337
346
 
347
+ /**
348
+ * The tools of this server no agent is offered, because their input schema is
349
+ * not valid JSON Schema as the server sent it.
350
+ *
351
+ * This is the whole reason the check exists. An AI client handed such a tool
352
+ * drops it and says nothing — the tool is simply missing for the agent — so
353
+ * without this section the only symptom is a capability that quietly does not
354
+ * work, with nothing anywhere to look at. Each entry names the tool and quotes
355
+ * the place in the schema and the reason, which is what the server's vendor
356
+ * needs to hear; Hexis does not rewrite the schema to make it valid.
357
+ */
358
+ function HiddenToolsSection({ tools }: { tools: HiddenTool[] }) {
359
+ return (
360
+ <section className="mt-8">
361
+ <SectionHeading>Not offered to assistants</SectionHeading>
362
+ <Banner tone="urgent" role="note">
363
+ <ul className="space-y-1.5">
364
+ {tools.map((t) => (
365
+ <li key={t.name}>
366
+ <span className="font-semibold">{t.name}</span>
367
+ <span> — {t.marker}</span>
368
+ </li>
369
+ ))}
370
+ </ul>
371
+ </Banner>
372
+ <p className="mt-2 text-detail text-ink-muted">
373
+ {tools.length === 1 ? 'This tool is' : 'These tools are'} absent from every assistant's tool
374
+ list until the server sends a valid schema. The rest of this server's tools are unaffected,
375
+ and nothing here is rewritten to make the schema valid. The check runs when the server's
376
+ tools are loaded, so a corrected schema clears this on its own.
377
+ </p>
378
+ </section>
379
+ );
380
+ }
381
+
338
382
  function CapabilitiesSection({ capabilities }: { capabilities: ToolCapability[] }) {
339
383
  return (
340
384
  <section className="mt-8">
@@ -21,6 +21,26 @@ export interface ToolCapability {
21
21
  description: string | null;
22
22
  }
23
23
 
24
+ /**
25
+ * One tool of this server that Hexis keeps off every agent surface because its
26
+ * input schema is not valid JSON Schema as the server sent it.
27
+ *
28
+ * The backend sends these ONLY to a caller who may write the tool: the people
29
+ * who manage the server are the only ones who can get the schema fixed, and a
30
+ * reader has nothing to do with the knowledge. So the page may render whatever
31
+ * arrives, with no permission check of its own.
32
+ */
33
+ export interface HiddenTool {
34
+ /** The name the tool would have been offered to agents under. */
35
+ name: string;
36
+ /** JSON Pointer to the place in the schema that is not valid. */
37
+ path: string;
38
+ /** Why that place is not valid, in the validator's own words. */
39
+ reason: string;
40
+ /** The sentence to show, built on the server so every surface says the same thing. */
41
+ marker: string;
42
+ }
43
+
24
44
  export interface ToolManualDetail {
25
45
  slug: string;
26
46
  name: string;
@@ -35,6 +55,13 @@ export interface ToolManualDetail {
35
55
  * same "nothing to show" as a remote one.
36
56
  */
37
57
  capabilities: ToolCapability[];
58
+ /**
59
+ * Hidden-for-an-invalid-schema findings about THIS tool's server. Empty for
60
+ * a healthy server, and empty for a caller who may not write the tool.
61
+ * Optional on the wire so the page still renders against a backend that does
62
+ * not serve the field yet.
63
+ */
64
+ hiddenTools?: HiddenTool[];
38
65
  }
39
66
 
40
67
  async function unwrap(res: Response, fallback: string): Promise<never> {
@@ -1,4 +1,4 @@
1
- import { useCallback, useRef, useState, type ReactNode } from 'react';
1
+ import { useCallback, useEffect, useRef, useState, type ReactNode } from 'react';
2
2
  import { cn } from '../../../lib/utils';
3
3
  import { toastDuration } from '../utils/toast-duration';
4
4
  import { ToastContext, type ShowToast, type ToastTone } from './toast.context';
@@ -43,6 +43,14 @@ export function LibraryToastProvider({ children }: { children: ReactNode }) {
43
43
  visible: boolean;
44
44
  } | null>(null);
45
45
  const timer = useRef<ReturnType<typeof setTimeout> | null>(null);
46
+ // A toast still on screen when the provider goes away has a timer left to
47
+ // run, which would then set state on something that is no longer there.
48
+ useEffect(
49
+ () => () => {
50
+ if (timer.current) clearTimeout(timer.current);
51
+ },
52
+ [],
53
+ );
46
54
 
47
55
  const show = useCallback<ShowToast>((msg, tone = 'neutral') => {
48
56
  setToast({ message: msg, tone, visible: true });
@@ -1,5 +1,5 @@
1
1
  import { describe, it, expect, vi, beforeEach } from 'vitest';
2
- import { render, screen, waitFor, within } from '@testing-library/react';
2
+ import { cleanup, render, screen, waitFor, within } from '@testing-library/react';
3
3
  import userEvent from '@testing-library/user-event';
4
4
 
5
5
  const api = vi.hoisted(() => ({
@@ -27,7 +27,6 @@ const facade = vi.hoisted(() => ({
27
27
  }));
28
28
  vi.mock('../../settings/services/github-facade.api', () => facade);
29
29
 
30
- import { agentsFilePointerSentence } from '@bevel-software/platform-shared';
31
30
  import { SetupGate } from '../components/SetupGate';
32
31
  import { SetupScreen } from '../components/SetupScreen';
33
32
  import { KbInitFailed, SettingsProblems, type SettingStatus } from '../services/setup.api';
@@ -42,8 +41,6 @@ const SETTINGS: SettingStatus[] = [
42
41
  { key: 'knowledgeBaseDir', section: KB, source: 'unset', value: '', configured: false, secret: false, restartToApply: true },
43
42
  { key: 'skillsDir', section: KB, source: 'unset', value: '', configured: false, secret: false, restartToApply: true },
44
43
  { key: 'pluginsDir', section: KB, source: 'unset', value: '', configured: false, secret: false, restartToApply: true },
45
- { key: 'agentsFile', section: KB, source: 'unset', value: '', configured: false, secret: false, restartToApply: true },
46
- { key: 'agentsFileLink', section: KB, source: 'unset', value: '', configured: false, secret: false, restartToApply: true },
47
44
  { key: 'defaultBranch', envVar: 'DEFAULT_BRANCH', section: KB, source: 'unset', value: '', configured: false, secret: false, restartToApply: true },
48
45
  { key: 'protectedBranches', envVar: 'PROTECTED_BRANCHES', section: KB, source: 'unset', value: '', configured: false, secret: false, restartToApply: true },
49
46
  { key: 'oidcClientSecret', envVar: 'OIDC_CLIENT_SECRET', section: 'sign-in', source: 'unset', configured: false, secret: true, restartToApply: false },
@@ -1278,73 +1275,19 @@ describe('SetupScreen — sync panel when the whole knowledge base is env-set',
1278
1275
  });
1279
1276
 
1280
1277
  /**
1281
- * The agent guide's file name, and the one thing that rides with it: the
1282
- * sentence the platform would add to the customer's own `AGENTS.md`, and the
1283
- * consent to keep it there.
1278
+ * The agent guide is served by the platform, not written to the repository,
1279
+ * so there is no file name to choose: the field that let an admin rename the
1280
+ * written guide is gone from both screens.
1284
1281
  */
1285
- describe('SetupScreen — the agent guide file', () => {
1286
- async function renderScreen(variant: 'setup' | 'settings' = 'setup') {
1282
+ describe('SetupScreen — the agent guide', () => {
1283
+ it('offers no guide file name, on first run or on the Deployment settings page', async () => {
1287
1284
  api.fetchSetupStatus.mockResolvedValue({ complete: false, isAdmin: true, settings: SETTINGS });
1288
- if (variant === 'settings') {
1289
- render(<SetupScreen settings={SETTINGS} onSaved={vi.fn()} variant="settings" />);
1290
- return;
1291
- }
1292
1285
  render(<SetupGate>{APP}</SetupGate>);
1293
1286
  await screen.findByRole('heading', { name: /Set up this deployment/ });
1294
- }
1295
-
1296
- it('offers the field on first run, beside the three folder names', async () => {
1297
- await renderScreen();
1298
- expect(screen.getByLabelText('Agent guide file')).toHaveValue('');
1299
- // Not tucked under Advanced, for the same reason the folders are not: a
1300
- // repository that already has an AGENTS.md loses it unless this is
1301
- // answered before the first boot.
1302
1287
  expect(screen.getByLabelText('Knowledge folder')).toBeInTheDocument();
1303
- });
1304
-
1305
- it('offers it on the Deployment settings page too', async () => {
1306
- await renderScreen('settings');
1307
- expect(screen.getByLabelText('Agent guide file')).toBeInTheDocument();
1308
- });
1309
-
1310
- it('shows nothing about a pointer while the guide is still AGENTS.md', async () => {
1311
- await renderScreen('settings');
1312
- expect(screen.queryByTestId('agents-file-link')).toBeNull();
1313
- await userEvent.type(screen.getByLabelText('Agent guide file'), 'AGENTS.md');
1314
- expect(screen.queryByTestId('agents-file-link')).toBeNull();
1315
- });
1316
-
1317
- it('shows the exact sentence and a ticked box once the name differs', async () => {
1318
- await renderScreen('settings');
1319
- await userEvent.type(screen.getByLabelText('Agent guide file'), 'HEXIS.md');
1320
- const panel = within(screen.getByTestId('agents-file-link'));
1321
- // On by default — a renamed guide nothing points at is a guide no coding
1322
- // agent will find.
1323
- expect(panel.getByRole('checkbox')).toBeChecked();
1324
- // The sentence itself, from the same helper the server appends with.
1325
- expect(panel.getByText(agentsFilePointerSentence('HEXIS.md'))).toBeInTheDocument();
1326
- });
1327
-
1328
- it('saves the name and the consent the admin actually gave', async () => {
1329
- api.saveSettings.mockResolvedValue({ restartRequired: true, complete: false, settings: SETTINGS });
1330
- render(<SetupScreen settings={SETTINGS} onSaved={vi.fn()} variant="settings" />);
1331
- await userEvent.type(screen.getByLabelText('Agent guide file'), 'HEXIS.md');
1332
- await userEvent.click(within(screen.getByTestId('agents-file-link')).getByRole('checkbox'));
1333
- await userEvent.click(screen.getByRole('button', { name: /Save/ }));
1334
- await waitFor(() =>
1335
- expect(api.saveSettings).toHaveBeenCalledWith(
1336
- expect.objectContaining({ agentsFile: 'HEXIS.md', agentsFileLink: 'false' }),
1337
- ),
1338
- );
1339
- });
1340
-
1341
- it('shows the server\'s rule against a name it refused', async () => {
1342
- api.saveSettings.mockRejectedValue(
1343
- new SettingsProblems({ agentsFile: 'The name must end in .md.' }),
1344
- );
1288
+ expect(screen.queryByLabelText('Agent guide file')).toBeNull();
1289
+ cleanup();
1345
1290
  render(<SetupScreen settings={SETTINGS} onSaved={vi.fn()} variant="settings" />);
1346
- await userEvent.type(screen.getByLabelText('Agent guide file'), 'HEXIS.txt');
1347
- await userEvent.click(screen.getByRole('button', { name: /Save/ }));
1348
- expect(await screen.findByText('The name must end in .md.')).toBeInTheDocument();
1291
+ expect(screen.queryByLabelText('Agent guide file')).toBeNull();
1349
1292
  });
1350
1293
  });
@@ -1,9 +1,5 @@
1
1
  import { useEffect, useRef, useState, type FormEvent, type KeyboardEvent, type ReactNode } from 'react';
2
- import {
3
- DEFAULT_KB_LAYOUT,
4
- agentsFilePointerSentence,
5
- type KbLayout,
6
- } from '@bevel-software/platform-shared';
2
+ import { DEFAULT_KB_LAYOUT, type KbLayout } from '@bevel-software/platform-shared';
7
3
  import { Banner, Button, Surface, TextField } from '../../../shared/components';
8
4
  import { SlotBoundary } from '../../../shared/components/SlotBoundary';
9
5
  import { tokenUsernameForHost } from '../utils/git-host';
@@ -137,14 +133,6 @@ const FIELDS: Record<
137
133
  help: 'The top-level folder that holds plugins. The three folder names must differ.',
138
134
  placeholder: 'Plugins',
139
135
  },
140
- // Beside the folders, and not under Advanced, for the same reason they are
141
- // not: a repository that already has an `AGENTS.md` of its own loses it to
142
- // the platform's on the first boot unless this is answered first.
143
- agentsFile: {
144
- label: 'Agent guide file',
145
- help: 'The file the platform writes its own guide to, at the top of the repository. Change it if your repository already has an AGENTS.md you want to keep — that file then stays yours, and the platform never writes to it. Must end in .md.',
146
- placeholder: 'AGENTS.md',
147
- },
148
136
  defaultBranch: {
149
137
  label: 'Main branch',
150
138
  help: 'The version everyone sees. Filled in from your repository when you test the connection.',
@@ -255,22 +243,15 @@ const isRootFolderKey = (key: string): key is (typeof ROOT_FOLDER_KEYS)[number]
255
243
  (ROOT_FOLDER_KEYS as readonly string[]).includes(key);
256
244
 
257
245
  /**
258
- * The knowledge-base LAYOUT fields — the three folders and the agent guide's
259
- * file name — which render together, under the connection test whose listing
260
- * the folders are checked against, rather than with the connection fields
261
- * above it.
246
+ * The knowledge-base LAYOUT fields — the three folders — which render
247
+ * together, under the connection test whose listing they are checked
248
+ * against, rather than with the connection fields above it. (The guide's
249
+ * file name was one of them while the guide was written to disk; it is
250
+ * served by the platform now and has no field.)
262
251
  */
263
- const LAYOUT_KEYS: readonly (keyof KbLayout)[] = [...ROOT_FOLDER_KEYS, 'agentsFile'];
252
+ const LAYOUT_KEYS: readonly (keyof KbLayout)[] = [...ROOT_FOLDER_KEYS];
264
253
  const isLayoutKey = (key: string): boolean => (LAYOUT_KEYS as readonly string[]).includes(key);
265
254
 
266
- /**
267
- * The consent that rides along with a renamed guide: keep the platform's
268
- * one-sentence pointer in the customer's own `AGENTS.md`. Not a text field, so
269
- * it has no {@link FIELDS} entry and is drawn by hand under the name it
270
- * belongs to.
271
- */
272
- const AGENTS_LINK_KEY = 'agentsFileLink';
273
-
274
255
  /** How a near-miss folder differs from the configured name, as the warning words it. */
275
256
  const VARIANT_DIFFERENCE: Record<Extract<RootFolderState, { kind: 'variant' }>['difference'], string> = {
276
257
  case: 'differs only by case',
@@ -1298,42 +1279,6 @@ export function SetupScreen({
1298
1279
  );
1299
1280
  }
1300
1281
 
1301
- /**
1302
- * Under the guide's name, once it is no longer `AGENTS.md`: the exact
1303
- * sentence the platform would add to the customer's own `AGENTS.md`, and the
1304
- * consent to keep it there.
1305
- *
1306
- * Shown ONLY while the name differs, because that is the only time there is
1307
- * anything to point at — under the default name the guide IS `AGENTS.md`.
1308
- * The sentence is rendered by the same helper the server appends with, so
1309
- * what the admin reads here is what lands in their file, character for
1310
- * character.
1311
- */
1312
- function renderAgentsFileLink() {
1313
- const name = resolved('agentsFile') || DEFAULT_KB_LAYOUT.agentsFile;
1314
- if (name === DEFAULT_KB_LAYOUT.agentsFile) return null;
1315
- // Unset means on: the server reads an unanswered setting the same way.
1316
- const on = (draft[AGENTS_LINK_KEY] ?? settings.find((s) => s.key === AGENTS_LINK_KEY)?.value ?? 'true') !== 'false';
1317
- return (
1318
- <div className="mt-2 space-y-2" data-testid="agents-file-link">
1319
- <label className="flex cursor-pointer select-none items-start gap-2 text-detail text-ink">
1320
- <input
1321
- type="checkbox"
1322
- className="mt-0.5"
1323
- checked={on}
1324
- onChange={(e) => set(AGENTS_LINK_KEY, e.target.checked ? 'true' : 'false')}
1325
- />
1326
- <span>Keep a pointer to {name} in your own AGENTS.md</span>
1327
- </label>
1328
- <CopyValue value={agentsFilePointerSentence(name)} label="Copy the pointer sentence" />
1329
- <p className="text-meta text-ink-faint">
1330
- While this is ticked, every start looks for “{name}” in your AGENTS.md and adds the
1331
- sentence at the end when it is not there — in your own words counts too. Nothing is added
1332
- if you have no AGENTS.md, and no file is ever created for it. Untick it to stop.
1333
- </p>
1334
- </div>
1335
- );
1336
- }
1337
1282
 
1338
1283
  function renderField(setting: SettingStatus) {
1339
1284
  const copy = FIELDS[setting.key];
@@ -1374,7 +1319,6 @@ export function SetupScreen({
1374
1319
  )}
1375
1320
  <p className="mt-1 text-meta text-ink-faint">{copy.help}</p>
1376
1321
  {isRootFolderKey(setting.key) && renderRootFolderState(setting.key)}
1377
- {setting.key === 'agentsFile' && renderAgentsFileLink()}
1378
1322
  {setting.key === 'kbSyncSecret' && renderSyncPanel()}
1379
1323
  {/* Only AFTER setup: on first run there is nothing yet to lose, so
1380
1324
  the caution would be noise. Once a deployment is live, this field
@@ -1758,11 +1702,10 @@ export function SetupScreen({
1758
1702
  )}
1759
1703
  </SectionFields>
1760
1704
 
1761
- {/* The layout: the three root folders and the agent guide's
1762
- file name, in the main section, directly under the test
1763
- whose listing the folders are checked against — the
1764
- connection fields above it stay next to the button that
1765
- proves them. */}
1705
+ {/* The layout: the three root folders, in the main section,
1706
+ directly under the test whose listing they are checked
1707
+ against — the connection fields above it stay next to the
1708
+ button that proves them. */}
1766
1709
  {fields.filter((f) => isLayoutKey(f.key)).map((f) => renderField(f))}
1767
1710
 
1768
1711
  {/* Everything a normal setup never touches, out of the way but
@@ -215,11 +215,11 @@ describe('the interactive tab: Claude and ChatGPT first, each family on its own
215
215
  mount(PUBLIC_URL);
216
216
  const values = snippets();
217
217
  expect(values).toContain(
218
- `claude mcp add skills-tools-knowledge --env HEXIS_URL="${window.location.origin}" -- npx -y @bevel-software/hexis-mcp`,
218
+ `claude mcp add skills-tools-knowledge --env HEXIS_URL="${window.location.origin}" -- npx -y @bevel-software/hexis-mcp@latest`,
219
219
  );
220
220
  const json = values.find((v) => v.includes('mcpServers') && v.includes('"command"'));
221
221
  const parsed = JSON.parse(json!).mcpServers['skills-tools-knowledge'];
222
- expect(parsed.args).toEqual(['-y', '@bevel-software/hexis-mcp']);
222
+ expect(parsed.args).toEqual(['-y', '@bevel-software/hexis-mcp@latest']);
223
223
  expect(parsed.env.HEXIS_URL).toBe(window.location.origin);
224
224
  // Keyless = interactive: the browser-sign-in mode carries no key env.
225
225
  expect(parsed.env.HEXIS_CONNECTION_KEY).toBeUndefined();
@@ -332,12 +332,12 @@ describe('the key-bearing snippets quote the deployment too', () => {
332
332
 
333
333
  // 7. the Claude Code stdio one-liner
334
334
  expect(values).toContain(
335
- `claude mcp add skills-tools-knowledge --env HEXIS_URL="${window.location.origin}" --env HEXIS_CONNECTION_KEY="${KEY}" -- npx -y @bevel-software/hexis-mcp`,
335
+ `claude mcp add skills-tools-knowledge --env HEXIS_URL="${window.location.origin}" --env HEXIS_CONNECTION_KEY="${KEY}" -- npx -y @bevel-software/hexis-mcp@latest`,
336
336
  );
337
337
  // 8. the JSON config that spawns the package
338
338
  const json = values.find((v) => v.includes('mcpServers') && v.includes('"command"'));
339
339
  const parsed = JSON.parse(json!).mcpServers['skills-tools-knowledge'];
340
- expect(parsed.args).toEqual(['-y', '@bevel-software/hexis-mcp']);
340
+ expect(parsed.args).toEqual(['-y', '@bevel-software/hexis-mcp@latest']);
341
341
  expect(parsed.env.HEXIS_URL).toBe(window.location.origin);
342
342
  expect(parsed.env.HEXIS_CONNECTION_KEY).toBe(KEY);
343
343
  expect(json).not.toContain(PUBLIC_URL);
@@ -3149,9 +3149,10 @@ describe('FileExplorer: platform files stay put', () => {
3149
3149
  file(`${KB}/access.md`),
3150
3150
  file(`${KB}/roles.yaml`),
3151
3151
  file(`${KB}/.bevelignore`),
3152
+ // The organisation's own conventions file: the platform's guide is
3153
+ // served from code, so an AGENTS.md is content wherever it sits —
3154
+ // the server says the same.
3152
3155
  file(`${KB}/AGENTS.md`),
3153
- // Read from the repository root and nowhere else, so a nested one
3154
- // is ordinary content — the server says the same.
3155
3156
  file(`${KB}/Handbook/AGENTS.md`),
3156
3157
  file(`${KB}/Handbook/notes.md`),
3157
3158
  { name: 'Sales', relativePath: `${KB}/Sales`, type: 'directory', children: [] },
@@ -3160,7 +3161,7 @@ describe('FileExplorer: platform files stay put', () => {
3160
3161
  ],
3161
3162
  });
3162
3163
 
3163
- const PLATFORM = ['access.md', 'roles.yaml', '.bevelignore', 'AGENTS.md'];
3164
+ const PLATFORM = ['access.md', 'roles.yaml', '.bevelignore'];
3164
3165
 
3165
3166
  let alertSpy: ReturnType<typeof vi.spyOn>;
3166
3167
 
@@ -3364,12 +3365,13 @@ describe('FileExplorer: platform files stay put', () => {
3364
3365
  expect(rename).toHaveAttribute('title', sentence('access.md'));
3365
3366
  });
3366
3367
 
3367
- it('a nested AGENTS.md is content, not a platform file: it drags like any other row', () => {
3368
+ it('an AGENTS.md is content, not a platform file, at the root and nested: it drags like any other row', () => {
3368
3369
  renderExplorer({ fileTree: TREE });
3369
- // Both rows are named AGENTS.md; the nested one is the second.
3370
3370
  const rows = screen.getAllByText('AGENTS.md').map((n) => n.closest('button')!);
3371
- const nested = rows.find((r) => r.getAttribute('data-tree-path') === `${KB}/Handbook/AGENTS.md`);
3372
- expect(nested).toHaveAttribute('draggable', 'true');
3371
+ for (const at of [`${KB}/AGENTS.md`, `${KB}/Handbook/AGENTS.md`]) {
3372
+ const row = rows.find((r) => r.getAttribute('data-tree-path') === at);
3373
+ expect(row, at).toHaveAttribute('draggable', 'true');
3374
+ }
3373
3375
  });
3374
3376
  });
3375
3377
 
@@ -225,7 +225,7 @@ const KB = 'knowledge-base';
225
225
  * the sidebar cannot drift from the endpoint it would have called.
226
226
  */
227
227
  describe('platformFileMoveRefusal', () => {
228
- it('refuses the four platform files where the platform reads them', () => {
228
+ it('refuses the three platform files where the platform reads them', () => {
229
229
  expect(platformFileMoveRefusal(`${KB}/access.md`, KB))
230
230
  .toBe('access.md is a platform file and stays in its folder.');
231
231
  expect(platformFileMoveRefusal(`${KB}/Sales/access.md`, KB))
@@ -234,32 +234,29 @@ describe('platformFileMoveRefusal', () => {
234
234
  .toBe('.bevelignore is a platform file and stays in its folder.');
235
235
  expect(platformFileMoveRefusal(`${KB}/roles.yaml`, KB))
236
236
  .toBe('roles.yaml is a platform file and stays in its folder.');
237
- expect(platformFileMoveRefusal(`${KB}/AGENTS.md`, KB))
238
- .toBe('AGENTS.md is a platform file and stays in its folder.');
239
237
  });
240
238
 
241
- it('leaves content alone, including a nested roles.yaml or AGENTS.md the platform never reads', () => {
239
+ it('leaves content alone, including a nested roles.yaml the platform never reads, and any AGENTS.md', () => {
242
240
  expect(platformFileMoveRefusal(`${KB}/Sales/deal.md`, KB)).toBeNull();
243
241
  expect(platformFileMoveRefusal(`${KB}/Sales/roles.yaml`, KB)).toBeNull();
242
+ // The organisation's own conventions file, at the root or anywhere: the
243
+ // platform's guide is served from code, so nothing under this name is ours.
244
+ expect(platformFileMoveRefusal(`${KB}/AGENTS.md`, KB)).toBeNull();
244
245
  expect(platformFileMoveRefusal(`${KB}/Sales/AGENTS.md`, KB)).toBeNull();
245
246
  // Exact spelling, as the platform reads it.
246
247
  expect(platformFileMoveRefusal(`${KB}/Sales/Access.md`, KB)).toBeNull();
247
248
  });
248
249
 
249
250
  /**
250
- * The tree's copy of the rule reads the layout the browser was served, so a
251
- * deployment that renamed its guide gets the same two answers here as it
252
- * does from the server: ours is managed, theirs is a page.
251
+ * A deployment that gave the written guide a name of its own, back when it
252
+ * was written: that name is a read alias now, not a file, so a file under
253
+ * it is content like any other.
253
254
  */
254
- it('follows the configured guide name — and lets go of AGENTS.md when it differs', () => {
255
+ it('refuses nothing under a guide name a deployment saved', () => {
255
256
  configureKbLayout({ ...DEFAULT_KB_LAYOUT, agentsFile: 'HEXIS.md' });
256
- expect(platformFileMoveRefusal(`${KB}/HEXIS.md`, KB))
257
- .toBe('HEXIS.md is a platform file and stays in its folder.');
258
- // The customer's own conventions file moves, renames and deletes like any
259
- // page — which is the whole point of naming ours something else.
257
+ expect(platformFileMoveRefusal(`${KB}/HEXIS.md`, KB)).toBeNull();
260
258
  expect(platformFileMoveRefusal(`${KB}/AGENTS.md`, KB)).toBeNull();
261
259
  expect(platformFileDragRefusal(`${KB}/AGENTS.md`, KB, false)).toBeNull();
262
- // Root-only, like `roles.yaml`: a nested copy of ours is content too.
263
260
  expect(platformFileMoveRefusal(`${KB}/Sales/HEXIS.md`, KB)).toBeNull();
264
261
  });
265
262
 
@@ -289,7 +286,6 @@ describe('platformFileDragRefusal', () => {
289
286
  expect(platformFileDragRefusal(`${KB}/access.md`, KB, true)).toBe(sentence('access.md'));
290
287
  expect(platformFileDragRefusal(`${KB}/roles.yaml`, KB, true)).toBe(sentence('roles.yaml'));
291
288
  expect(platformFileDragRefusal(`${KB}/.bevelignore`, KB, true)).toBe(sentence('.bevelignore'));
292
- expect(platformFileDragRefusal(`${KB}/AGENTS.md`, KB, true)).toBe(sentence('AGENTS.md'));
293
289
  });
294
290
 
295
291
  it('leaves ordinary content alone for either of them', () => {
@@ -30,11 +30,13 @@ function repoRelative(wsRelativePath: string, kbDirName: string | null): string
30
30
  * server refuses with — or null when it may.
31
31
  *
32
32
  * Judged on the path's REPO-relative form, because that is what the platform
33
- * reads: `roles.yaml` and the agent guide (`AGENTS.md` unless this deployment
34
- * named it something else) count at the repository root only, so a nested file
35
- * of either name is ordinary content and stays draggable. Outside
36
- * the KB clone, and before `kbDirName` is known, nothing is refused here — the
37
- * server is the gate and says the same sentence.
33
+ * reads: `roles.yaml` counts at the repository root only, so a nested file of
34
+ * that name is ordinary content and stays draggable. (A file under the
35
+ * guide's name — `AGENTS.md`, or the name a deployment saved for the guide —
36
+ * is content wherever it sits: the platform's guide is served from code, not
37
+ * written to the tree.) Outside the KB clone, and before `kbDirName` is
38
+ * known, nothing is refused here — the server is the gate and says the same
39
+ * sentence.
38
40
  */
39
41
  export function platformFileMoveRefusal(
40
42
  wsRelativePath: string,
@@ -468,7 +468,7 @@ describe('snippets: one builder per client, keyed or not', () => {
468
468
  const parsed = JSON.parse(hexisMcpJsonSnippet(BASE, KEY));
469
469
  expect(parsed.mcpServers['skills-tools-knowledge']).toEqual({
470
470
  command: 'npx',
471
- args: ['-y', '@bevel-software/hexis-mcp'],
471
+ args: ['-y', '@bevel-software/hexis-mcp@latest'],
472
472
  env: {
473
473
  HEXIS_URL: BASE,
474
474
  HEXIS_CONNECTION_KEY: KEY,
@@ -492,7 +492,7 @@ describe('snippets: one builder per client, keyed or not', () => {
492
492
 
493
493
  it('builds the Claude Code command as a stdio add with both env values', () => {
494
494
  expect(hexisMcpClaudeCommand(BASE, KEY)).toBe(
495
- `claude mcp add skills-tools-knowledge --env HEXIS_URL="${BASE}" --env HEXIS_CONNECTION_KEY="${KEY}" -- npx -y @bevel-software/hexis-mcp`,
495
+ `claude mcp add skills-tools-knowledge --env HEXIS_URL="${BASE}" --env HEXIS_CONNECTION_KEY="${KEY}" -- npx -y @bevel-software/hexis-mcp@latest`,
496
496
  );
497
497
  });
498
498
 
@@ -393,7 +393,7 @@ export function langdockSnippet(mcpUrl: string, bearer: string): string {
393
393
  }
394
394
 
395
395
  /* ------------------------------------------------------------------ *
396
- * The LOCAL server (`npx @bevel-software/hexis-mcp`): the same workspace
396
+ * The LOCAL server (`npx @bevel-software/hexis-mcp@latest`): the same workspace
397
397
  * as a stdio server on the member's own machine, which is the only place
398
398
  * a plugin's local-only tools — stdio servers, localhost services — can
399
399
  * run. It serves everything the hosted endpoint serves plus those. It
@@ -421,8 +421,8 @@ export function workspaceBaseUrl(): string {
421
421
  * The JSON block that runs the workspace as a LOCAL MCP server. Read by the
422
422
  * same clients as `jsonConfigSnippet` — Claude Desktop, Cursor, Windsurf,
423
423
  * Cline, anything that loads servers from a JSON config — but the entry
424
- * spawns `npx @bevel-software/hexis-mcp` instead of pointing at the hosted
425
- * endpoint, so the command needs Node on the machine.
424
+ * spawns `npx @bevel-software/hexis-mcp@latest` instead of pointing at the
425
+ * hosted endpoint, so the command needs Node on the machine.
426
426
  *
427
427
  * Without a bearer there is NO key field at all: keyless is the interactive
428
428
  * mode, where the server opens the person's browser to sign in on first run
@@ -436,7 +436,10 @@ export function hexisMcpJsonSnippet(baseUrl: string, bearer?: string): string {
436
436
  mcpServers: {
437
437
  [MCP_SERVER_KEY]: {
438
438
  command: 'npx',
439
- args: ['-y', '@bevel-software/hexis-mcp'],
439
+ // `@latest`, spelled out: a bare name lets npx reuse whatever
440
+ // version its cache holds, and a machine that first ran the server
441
+ // before agents were named kept signing in as "hexis-mcp on <host>".
442
+ args: ['-y', '@bevel-software/hexis-mcp@latest'],
440
443
  env: {
441
444
  HEXIS_URL: baseUrl,
442
445
  ...(bearer ? { HEXIS_CONNECTION_KEY: bearer } : {}),
@@ -464,6 +467,6 @@ export function hexisMcpClaudeCommand(baseUrl: string, bearer?: string): string
464
467
  `claude mcp add ${MCP_SERVER_KEY}` +
465
468
  ` --env HEXIS_URL="${escapeForDoubleQuotes(baseUrl)}"` +
466
469
  (bearer ? ` --env HEXIS_CONNECTION_KEY="${escapeForDoubleQuotes(bearer)}"` : '') +
467
- ` -- npx -y @bevel-software/hexis-mcp`
470
+ ` -- npx -y @bevel-software/hexis-mcp@latest`
468
471
  );
469
472
  }