@bevel-software/platform-core-backend 0.13.6 → 0.15.1

package/src/modules/skills/skill-access-requests.routes.ts

@@ -0,0 +1,199 @@
+import express from 'express';
+import '../auth/auth.middleware.js'; // Express Request.userId / userEmail augmentation
+import {
+  DEFAULT_BRANCH,
+  joinBranchFor,
+  type AuthUser,
+  type IWorkflowService,
+} from '@bevel-software/platform-shared';
+import type { IAccessControl } from '../access/access-control.interface.js';
+import { spliceGrant } from '../access-model/access-splice.js';
+import { WorkflowDomainError } from '../../shared/domain-errors.js';
+import { workspaceIdForBranch } from '../../shared/workspace-id.js';
+import type { WorkspaceService } from '../workspace/workspace.service.js';
+import type { JoinRequestsService } from '../plugins/join-requests.service.js';
+import type { ISkillService } from './skills.contract.js';
+
+/**
+ * Asking for WRITE on a shared skill — the same machinery as asking to join a
+ * plugin, pointed at a skill folder instead of a plugin folder.
+ *
+ *   POST /api/skills/:name/access-request               → { ok, number }
+ *   GET  /api/skills/:name/access-requests              → { requests }   (skill editors)
+ *   POST /api/skills/:name/access-requests/:n/reconcile → { closed }
+ *
+ * Why it exists: linking a skill into a plugin needs write on the skill's
+ * rules (the link grants the plugin's principal there), and a plugin manager
+ * often has no say over a skill some other scope owns. The request is a plain
+ * change request whose branch splices `write: <requester>` into the skill
+ * folder's `access.md`; the skill's editors see its proposals and accept
+ * through the ordinary grant path, and it retires itself once the default
+ * branch carries the grant (`JoinRequestsService`, keyed on the skill FOLDER
+ * path rather than a plugin name — the branch-name convention takes any
+ * exact string).
+ *
+ * Fail-closed like the skill catalog: a skill the caller cannot read answers
+ * as unknown, and the editors' listing answers `[]` to anyone else.
+ */
+export function createSkillAccessRequestRoutes(deps: {
+  skillService: ISkillService;
+  accessControl: IAccessControl;
+  workflow: IWorkflowService;
+  workspaceService: WorkspaceService;
+  joinRequests: JoinRequestsService;
+  kbDirName: string;
+  resolveUser: (req: express.Request) => Promise<AuthUser | null>;
+}): express.Router {
+  const { skillService, accessControl, workflow, workspaceService, joinRequests, kbDirName, resolveUser } = deps;
+  const router = express.Router();
+  const wsId = () => workspaceIdForBranch(DEFAULT_BRANCH);
+  const rulesOf = (folder: string) => `${folder}/access.md`;
+
+  /** The skill the caller may read, by name — or null after answering 404. */
+  async function readableSkill(
+    req: express.Request,
+    res: express.Response,
+  ): Promise<{ user: AuthUser; folder: string; name: string } | null> {
+    const user = await resolveUser(req);
+    if (!user) {
+      res.status(401).json({ error: 'Unauthenticated' });
+      return null;
+    }
+    const name = String(req.params.name);
+    const skill = (await skillService.listSkills(user.email)).find((s) => s.name === name);
+    if (!skill) {
+      res.status(404).json({ error: 'Unknown skill', kind: 'unknown-skill' });
+      return null;
+    }
+    return { user, folder: skill.path, name };
+  }
+
+  router.post('/skills/:name/access-request', async (req, res) => {
+    try {
+      const ctx = await readableSkill(req, res);
+      if (!ctx) return;
+      const { user, folder, name } = ctx;
+      if (await accessControl.canWrite(wsId(), user.email, rulesOf(folder))) {
+        res.status(409).json({ error: 'You can already edit this skill', kind: 'already-writable' });
+        return;
+      }
+      const branch = joinBranchFor(user.email, folder);
+      // FRESH: a repeated click must find the request the previous one opened,
+      // and the cached listing can trail it — a miss here would send the
+      // retry into a duplicate refusal.
+      const existing = (await workflow.listChangeRequestsAuthoredBy(user.email, { fresh: true })).find(
+        (cr) => cr.state === 'open' && cr.branch === branch,
+      );
+      if (existing) {
+        res.json({ ok: true, number: existing.number });
+        return;
+      }
+      // The branch may already exist (a request listed as closed, a retry
+      // after a failed open). Existence is PROBED, before and — if creation
+      // fails — after: the race shows up as "already exists" locally or as a
+      // rejected push when origin got there first, and a message is not a
+      // contract. A branch that is there is proceeded against; anything else
+      // is a real failure, and a proposal on a branch that was not made would
+      // be worse than the error. STRICT: the list proves absence, and a
+      // listing that could not fetch proves nothing — it throws instead of
+      // serving refs from before the branch was made (or deleted).
+      const branchExists = async () =>
+        (await workflow.listBranches(wsId(), { freshFetch: true, strictFetch: true })).some(
+          (b) => b.name === branch,
+        );
+      if (!(await branchExists())) {
+        try {
+          await workflow.createBranch(wsId(), branch, DEFAULT_BRANCH);
+        } catch (err) {
+          if (!(await branchExists())) throw err;
+        }
+      }
+      const ws = await workspaceService.getOrCreateForBranch(branch);
+      const accessPath = `${kbDirName}/${rulesOf(folder)}`;
+      // Only a PROVEN absence reads as "no rules yet": any other failure must
+      // not be turned into an empty file that a splice then overwrites.
+      const current = await workspaceService.readFile(ws.id, accessPath).catch((err: unknown) => {
+        const code = (err as { code?: unknown } | null)?.code;
+        if (code !== 'ENOENT' && code !== 'ENOTDIR') throw err;
+        return '';
+      });
+      const spliced = spliceGrant(
+        current,
+        'write',
+        { kind: 'user', email: user.email, displayName: user.name },
+        { target: 'folder' },
+      );
+      if (spliced.changed) {
+        await workspaceService.writeFile(ws.id, accessPath, spliced.text);
+        await workflow.commitChanges(ws.id, user, `Request write access to ${name}`);
+      }
+      const detail = await workflow.openChangeRequest(ws.id, user, {
+        sourceBranch: branch,
+        targetBranch: DEFAULT_BRANCH,
+        title: `Access request: ${name}`,
+        description:
+          `${user.name} asked to edit the skill ${name}. An editor of the skill accepts by ` +
+          `granting the access this branch proposes; the request closes itself once ` +
+          `every proposal has landed.`,
+      });
+      res.json({ ok: true, number: detail.number });
+    } catch (err) {
+      if (err instanceof WorkflowDomainError) {
+        res.status(err.status).json({ error: err.message, ...(err.payload ?? {}) });
+        return;
+      }
+      console.error('[skills] failed to open an access request:', err);
+      res.status(500).json({ error: 'Failed to request access' });
+    }
+  });
+
+  /** The caller as an EDITOR of the skill's rules, or null after answering. */
+  async function requireEditor(
+    req: express.Request,
+    res: express.Response,
+    onDenied: () => void,
+  ): Promise<{ user: AuthUser; folder: string } | null> {
+    const ctx = await readableSkill(req, res);
+    if (!ctx) return null;
+    if (!(await accessControl.canWrite(wsId(), ctx.user.email, rulesOf(ctx.folder)))) {
+      onDenied();
+      return null;
+    }
+    return ctx;
+  }
+
+  router.get('/skills/:name/access-requests', async (req, res) => {
+    try {
+      const ctx = await requireEditor(req, res, () => res.json({ requests: [] }));
+      if (!ctx) return;
+      const crs = await workflow.listChangeRequests();
+      res.json({ requests: await joinRequests.list(ctx.folder, ctx.folder, crs, ctx.user) });
+    } catch (err) {
+      console.error('[skills] failed to list access requests:', err);
+      res.status(500).json({ error: 'Failed to list access requests' });
+    }
+  });
+
+  router.post('/skills/:name/access-requests/:number/reconcile', async (req, res) => {
+    try {
+      const ctx = await requireEditor(req, res, () => res.status(404).json({ error: 'Not found' }));
+      if (!ctx) return;
+      const crNumber = Number(req.params.number);
+      if (!Number.isSafeInteger(crNumber) || crNumber <= 0) {
+        res.status(400).json({ error: 'Invalid change request number' });
+        return;
+      }
+      const cr = await workflow.getChangeRequest(crNumber);
+      if (!cr) {
+        res.status(404).json({ error: 'Not found' });
+        return;
+      }
+      res.json({ closed: await joinRequests.reconcile(ctx.folder, ctx.folder, cr, ctx.user) });
+    } catch (err) {
+      console.error('[skills] failed to reconcile an access request:', err);
+      res.status(500).json({ error: 'Failed to reconcile the request' });
+    }
+  });
+
+  return router;
+}

package/src/modules/skills/skills.contract.ts

@@ -7,13 +7,45 @@
  * bundled file's content (level 3).
  */
 
+/**
+ * One plugin a skill belongs to — by sitting INSIDE the plugin folder
+ * (`linked: false`) or by being LINKED from the plugin's manifest
+ * (`linked: true`). For a link, `granted` is the link's HEALTH: whether the
+ * plugin's members can read the skill through it. For a link this platform
+ * manages that is whether the skill's own access rules name the plugin's
+ * `plugin/<Name>/read` principal — the link service writes that grant with
+ * the link, so `false` means a hand edit took it away. A link read from an
+ * external plugin format needs no grant (the skill's own scope decides who
+ * reads it) and is always `true`; the flag never proves a principal exists.
+ */
+export interface PluginMembership {
+  /** The plugin folder name. */
+  name: string;
+  linked: boolean;
+  granted: boolean;
+}
+
 export interface SkillSummary {
   /** Canonical id = the skill's folder name (e.g. `rfi`). */
   name: string;
   description: string;
   version?: string;
+  /** The governance owner from `metadata.owner`, when the skill declares one. */
+  owner?: string;
+  /**
+   * The governance lifecycle from `metadata.lifecycle`, lowercased — `active`
+   * (or absent), `deprecated` (still served, flagged), `retired` (served to the
+   * catalog for its owners, never compiled into a distribution).
+   */
+  lifecycle?: string;
   /** Repo-root-relative skill folder, e.g. `Plugins/Everyone/rfi`. */
   path: string;
+  /**
+   * The plugins this skill belongs to, decorated onto the catalog by the
+   * browser route (the catalog itself is plugin-unaware). Absent on the agent
+   * surfaces, which load skills by name and never by plugin.
+   */
+  plugins?: PluginMembership[];
 }
 
 export interface Skill extends SkillSummary {

package/src/modules/skills/skills.routes.ts

@@ -1,6 +1,21 @@
 import express from 'express';
+import { DEFAULT_BRANCH } from '@bevel-software/platform-shared';
 import '../auth/auth.middleware.js'; // Express Request.userId / userEmail augmentation
-import type { IPendingSkillService, ISkillService } from './skills.contract.js';
+import { workspaceIdForBranch } from '../../shared/workspace-id.js';
+import type { IPendingSkillService, ISkillService, PluginMembership } from './skills.contract.js';
+
+/** The slice of the plugin link index this surface reads — see `PluginLinkIndex`. */
+export interface SkillMembershipSource {
+  membership(): Promise<{
+    bySkill: Map<string, PluginMembership[]>;
+    byPlugin: Map<string, { folder: string }>;
+  }>;
+}
+
+/** The one access verdict this surface needs: may the caller read a path on the default branch? */
+export interface SkillMembershipGate {
+  canReadBatch(workspaceId: string, userEmail: string, paths: string[]): Promise<Map<string, boolean>>;
+}
 
 /**
  * Browser-facing (JWT) skill routes for the `/`-command menu, mounted behind
@@ -8,14 +23,27 @@ import type { IPendingSkillService, ISkillService } from './skills.contract.js';
  * so discovery, default-branch pinning, and per-user `canRead` filtering live
  * ONCE — the frontend never re-implements skill discovery or bypasses access.
  *
- *   GET /api/skills            → { skills: SkillSummary[] }   (filtered to this user)
+ *   GET /api/skills            → { skills: SkillSummary[] }   (filtered to this user,
+ *                                                              each with its `plugins`)
  *   GET /api/skills/pending    → { skills: PendingSkill[] }   (proposed, not released)
  *   GET /api/skills/:name      → GetSkillResult               (body + files)
  *   GET /api/skills/:name?file=… → GetSkillResult             (a bundled file's content)
+ *
+ * `plugins` is decorated HERE, not in the catalog: the catalog is what agents
+ * load by name and it stays plugin-unaware; the browser is the surface that
+ * groups skills by plugin. Optional dependency, so a host without the link
+ * index gets undecorated summaries rather than a 500.
  */
 export function createSkillsRoutes(
   skillService: ISkillService,
   pendingSkills?: IPendingSkillService,
+  links?: SkillMembershipSource,
+  /**
+   * With `links`: the memberships a caller sees name only plugins they may
+   * DISCOVER (read the plugin's access.md — the plugin index's own listing
+   * verdict), so this surface never reveals a plugin `/api/plugins` omits.
+   */
+  gate?: SkillMembershipGate,
 ): express.Router {
   const router = express.Router();
 
@@ -25,7 +53,35 @@ export function createSkillsRoutes(
       res.status(401).json({ error: 'Unauthenticated' });
       return;
     }
-    res.json({ skills: await skillService.listSkills(email) });
+    const skills = await skillService.listSkills(email);
+    if (!links) {
+      res.json({ skills });
+      return;
+    }
+    let bySkill: Map<string, PluginMembership[]>;
+    // Fail closed: memberships without a gate to judge them by name nothing.
+    let discoverable: (plugin: string) => boolean = () => false;
+    try {
+      const membership = await links.membership();
+      bySkill = membership.bySkill;
+      if (gate) {
+        const folders = [...membership.byPlugin.entries()];
+        const verdicts = folders.length
+          ? await gate.canReadBatch(
+              workspaceIdForBranch(DEFAULT_BRANCH),
+              email,
+              folders.map(([, p]) => `${p.folder}/access.md`),
+            )
+          : new Map<string, boolean>();
+        const visible = new Set(folders.filter(([, p]) => verdicts.get(`${p.folder}/access.md`) === true).map(([name]) => name));
+        discoverable = (plugin) => visible.has(plugin);
+      }
+    } catch {
+      bySkill = new Map(); // membership is a decoration; the shelf must not fall with it
+    }
+    res.json({
+      skills: skills.map((s) => ({ ...s, plugins: (bySkill.get(s.path) ?? []).filter((m) => discoverable(m.name)) })),
+    });
   });
 
   /**

package/src/modules/skills/skills.service.ts

@@ -1,13 +1,14 @@
 import path from 'node:path';
 import fs from 'node:fs/promises';
 import { parseDocument } from 'yaml';
-import { DEFAULT_BRANCH, PLUGINS_DIR } from '@bevel-software/platform-shared';
+import { DEFAULT_BRANCH, PLUGINS_DIR, SKILLS_DIR } from '@bevel-software/platform-shared';
 import type { WorkspaceService } from '../workspace/workspace.service.js';
 import { workspaceIdForBranch } from '../../shared/workspace-id.js';
 import type { IAccessControl } from '../access/access-control.interface.js';
 import { extractFrontmatter, resolveDeclaredId, dedupeById } from '../../shared/frontmatter-id.js';
 import { walkFiles } from '../../shared/fs-walk.js';
 import { TtlCache } from '../../shared/ttl-cache.js';
+import { BevelIgnoreStack } from '../workspace/bevel-ignore.js';
 import type {
   ISkillService,
   GetSkillResult,
@@ -75,6 +76,9 @@ export class SkillService implements ISkillService {
     if (file !== undefined) {
       if (!isSafeRelFile(file)) return { ok: false, error: 'invalid_file' };
       const repoPath = `${found.summary.path}/${file}`;
+      // Only a file the catalog LISTS is served: the listing already applied
+      // the ignore rules, so a path that is not in it is one they hid.
+      if (!found.files.includes(repoPath)) return { ok: false, error: 'not_found' };
       try {
         const content = await this.workspaceService.readFile(wsId, `${this.kbDirName}/${repoPath}`);
         return { ok: true, kind: 'file', file: { name, file, path: repoPath, content } };
@@ -97,15 +101,20 @@ export class SkillService implements ISkillService {
   private async scan(): Promise<ParsedSkill[]> {
     const cached = this.cache.get();
     if (cached) return cached;
+    // Token first: a merge's `invalidate()` can land while `scanDisk` is still
+    // reading the pre-merge tree, and storing that read afterwards would undo
+    // the drop for a full TTL.
+    const token = this.cache.begin();
     const skills = await this.scanDisk();
-    this.cache.set(skills);
+    this.cache.set(skills, token);
     return skills;
   }
 
   private async scanDisk(): Promise<ParsedSkill[]> {
-    // Ensure the default-branch clone exists, then scan its Plugins/ dir. Any
-    // failure (no workspace, no Plugins/ dir) degrades to an empty catalog — the
-    // manual/tools must never break because skills can't be read.
+    // Ensure the default-branch clone exists, then scan its Skills/ and
+    // Plugins/ roots. Any failure (no workspace, no such dir) degrades to an
+    // empty catalog — the manual/tools must never break because skills can't
+    // be read.
     let wsId: string;
     try {
       wsId = (await this.workspaceService.getOrCreateForBranch(DEFAULT_BRANCH)).id;
@@ -115,20 +124,34 @@ export class SkillService implements ISkillService {
     const kbRoot = path.join(await this.workspaceService.getWorkspacePath(wsId), this.kbDirName);
 
     // Skills may be grouped in category subfolders (each carrying its own
-    // access.md), so a SKILL.md can live at any depth under the root. Walk the
-    // tree and treat every folder that directly contains a SKILL.md as a skill;
-    // don't descend past it — its inner files are bundled assets, not nested
-    // skills. The skill name is the leaf folder name; its path is the full
-    // repo-relative folder (e.g. `Plugins/Development/coding-guidelines`).
+    // access.md), so a SKILL.md can live at any depth under either root. Walk
+    // the tree and treat every folder that directly contains a SKILL.md as a
+    // skill; don't descend past it — its inner files are bundled assets, not
+    // nested skills. The skill name is the leaf folder name; its path is the
+    // full repo-relative folder (e.g. `Skills/Engineering/deploy`).
+    //
+    // `.bevelignore` files INSIDE a root are honoured on the way down, the
+    // same layered rules the file tree applies: a repository that carries a
+    // build output beside its source (a `dist/` holding compiled copies of
+    // every skill) would otherwise list each skill twice and refuse the
+    // duplicate — the wrong one, half the time. The REPO-ROOT file is
+    // deliberately not consulted: it is where the template hides `Plugins/`
+    // from the Knowledge tree, and a rule that hides a root from the browser
+    // must not empty the catalog that root exists to feed.
     const out: ParsedSkill[] = [];
-    const walk = async (dir: string, relFolder: string): Promise<void> => {
+    const walk = async (dir: string, relFolder: string, ignore: BevelIgnoreStack): Promise<void> => {
       let entries: import('node:fs').Dirent[];
       try {
         entries = await fs.readdir(dir, { withFileTypes: true });
       } catch {
         return;
       }
+      ignore = await ignore.extendedWith(dir);
       if (entries.some((e) => e.isFile() && e.name === 'SKILL.md')) {
+        // A skill folder is a LEAF whatever the ignore rules say of it: a rule
+        // naming its SKILL.md suppresses the skill, it does not turn the
+        // folder's assets into skills of their own.
+        if (ignore.isIgnored(path.join(dir, 'SKILL.md'), false)) return;
         let raw: string;
         try {
           raw = await fs.readFile(path.join(dir, 'SKILL.md'), 'utf-8');
@@ -144,26 +167,43 @@ export class SkillService implements ISkillService {
         const declared = resolveDeclaredId(fm.frontmatter, path.basename(dir));
         const name = isSafeSkillName(declared) ? declared : path.basename(dir);
         out.push({
-          summary: { name, description: fm.description, version: fm.version, path: relFolder },
+          summary: {
+            name,
+            description: fm.description,
+            version: fm.version,
+            owner: fm.owner,
+            lifecycle: fm.lifecycle,
+            path: relFolder,
+          },
           body: fm.body,
           allowedTools: fm.allowedTools,
-          files: await listBundledFiles(dir, relFolder),
+          files: await listBundledFiles(dir, relFolder, ignore),
         });
         return; // a skill folder is a leaf — its subfolders hold assets, not skills
       }
       for (const entry of entries) {
         if (!entry.isDirectory() || entry.name.startsWith('.')) continue;
-        await walk(path.join(dir, entry.name), `${relFolder}/${entry.name}`);
+        const abs = path.join(dir, entry.name);
+        if (ignore.isIgnored(abs, true)) continue;
+        await walk(abs, `${relFolder}/${entry.name}`, ignore);
       }
     };
-    await walk(path.join(kbRoot, PLUGINS_DIR), PLUGINS_DIR);
+    // Each root starts its own ignore stack (the walk extends it with the
+    // root's own file first). Order is cosmetic: the sort below is by name
+    // then path, so a same-named pair resolves the same way regardless.
+    await walk(path.join(kbRoot, SKILLS_DIR), SKILLS_DIR, BevelIgnoreStack.empty());
+    await walk(path.join(kbRoot, PLUGINS_DIR), PLUGINS_DIR, BevelIgnoreStack.empty());
     // A skill's id (frontmatter `id`/`name`, else folder name) is how getSkill()
-    // resolves it, so it must be unique. Sort by (name, path) for a deterministic
-    // winner, then REFUSE later duplicates via the shared dedup — the same rule
-    // tools use (no silent auto-suffix that would rebind an id under the caller).
+    // resolves it, so it must be unique. Sort by (name, root, path) for a
+    // deterministic winner — the shared root FIRST, since `Skills/` is a
+    // skill's canonical home and a same-named inline copy is the stale one —
+    // then REFUSE later duplicates via the shared dedup — the same rule tools
+    // use (no silent auto-suffix that would rebind an id under the caller).
+    const rootRank = (p: string) => (p === SKILLS_DIR || p.startsWith(`${SKILLS_DIR}/`) ? 0 : 1);
     out.sort(
       (a, b) =>
         a.summary.name.localeCompare(b.summary.name) ||
+        rootRank(a.summary.path) - rootRank(b.summary.path) ||
         a.summary.path.localeCompare(b.summary.path),
     );
     return dedupeById(out, (s) => s.summary.name, (s, id) =>
@@ -209,6 +249,10 @@ function scalarToString(value: unknown): string | undefined {
 export function parseSkillFrontmatter(raw: string): {
   description: string;
   version?: string;
+  /** `metadata.owner` (or a top-level `owner`) — the governance record's owner, verbatim. */
+  owner?: string;
+  /** `metadata.lifecycle` (or top-level) — e.g. `active`, `deprecated`, `retired`; lowercased. */
+  lifecycle?: string;
   allowedTools?: string[];
   body: string;
   /** The parsed frontmatter object (for shared id resolution: `id`/`name`). */
@@ -233,6 +277,11 @@ export function parseSkillFrontmatter(raw: string): {
   const description = typeof data.description === 'string' ? data.description.trim() : '';
   const metadata = (data.metadata ?? {}) as Record<string, unknown>;
   const version = scalarToString(data.version) ?? scalarToString(metadata.version);
+  // The governance record: `metadata.owner` / `metadata.lifecycle` first (the
+  // agentskills convention this catalog reads), a top-level spelling second.
+  const owner = (scalarToString(metadata.owner) ?? scalarToString(data.owner))?.trim() || undefined;
+  const lifecycle =
+    (scalarToString(metadata.lifecycle) ?? scalarToString(data.lifecycle))?.trim().toLowerCase() || undefined;
 
   // `allowed-tools` is a space-separated string (agentskills) or a YAML list.
   const at = data['allowed-tools'];
@@ -242,12 +291,25 @@ export function parseSkillFrontmatter(raw: string): {
       ? at.split(/\s+/).filter(Boolean)
       : undefined;
 
-  return { description, version, allowedTools, body, frontmatter: data };
+  return { description, version, owner, lifecycle, allowedTools, body, frontmatter: data };
 }
 
-/** Repo-root-relative paths of every bundled file under a skill folder (excludes SKILL.md). */
-async function listBundledFiles(dir: string, relFolder: string): Promise<string[]> {
+/**
+ * Repo-root-relative paths of every bundled file under a skill folder
+ * (excludes SKILL.md), under the same ignore rules the walk applied on the
+ * way down — a rule in the skill's own `.bevelignore` or any folder above
+ * hides an asset from the listing, and therefore (see `getSkill`) from
+ * being served.
+ */
+async function listBundledFiles(dir: string, relFolder: string, ignore: BevelIgnoreStack): Promise<string[]> {
+  const hidden = (rel: string): boolean => {
+    const parts = rel.split('/');
+    for (let i = 1; i < parts.length; i++) {
+      if (ignore.isIgnored(path.join(dir, ...parts.slice(0, i)), true)) return true;
+    }
+    return ignore.isIgnored(path.join(dir, ...parts), false);
+  };
   return (await walkFiles(dir, () => true))
-    .filter((rel) => rel !== 'SKILL.md')
+    .filter((rel) => rel !== 'SKILL.md' && !hidden(rel))
     .map((rel) => `${relFolder}/${rel}`);
 }

package/src/modules/tool-auth/external-api-key.interface.ts

@@ -22,6 +22,12 @@ declare global {
 export interface ExternalApiKeySummary {
   id: string;
   label: string;
+  /**
+   * What the key was minted AS — `key` for one a person created by hand,
+   * another kind for one a flow minted on their behalf (a Claude link).
+   * Stored with the row; the label is the person's to edit and proves nothing.
+   */
+  kind: string;
   createdAt: number;
   lastUsedAt: number | null;
   revokedAt: number | null;
@@ -37,6 +43,19 @@ export interface MintedExternalApiKey {
   summary: ExternalApiKeySummary;
 }
 
+/** The kind of a key a person creates by hand. */
+export const DEFAULT_KEY_KIND = 'key';
+
+/**
+ * How a key is minted. `kind` names one of the kinds the service was built
+ * with, each of which carries its own plaintext prefix (the tenant's for the
+ * default kind, `gho_` for a Claude link); an unknown kind is refused, since
+ * nothing would route its bearer back.
+ */
+export interface MintOptions {
+  kind?: string;
+}
+
 /**
  * Contract for connection-key (API token) lifecycle. Used by the MCP auth
  * middleware to resolve a Bearer token to a Bevel user, and by the settings
@@ -59,7 +78,7 @@ export interface IExternalApiKeyService {
    * plaintext is **only** returned here — there is no read path that can
    * surface it again.
    */
-  mint(userId: string, label: string): Promise<MintedExternalApiKey>;
+  mint(userId: string, label: string, options?: MintOptions): Promise<MintedExternalApiKey>;
 
   /**
    * Resolve a plaintext token to the owning user. Returns null when the

package/src/modules/tool-auth/external-api-key.service.ts

@@ -8,36 +8,53 @@ import {
   TokenNotFoundError,
   TokenStillActiveError,
 } from './external-api-key.errors.js';
-import type {
-  ExternalApiKeySummary,
-  IExternalApiKeyService,
-  MintedExternalApiKey,
+import {
+  DEFAULT_KEY_KIND,
+  type ExternalApiKeySummary,
+  type IExternalApiKeyService,
+  type MintOptions,
+  type MintedExternalApiKey,
 } from './external-api-key.interface.js';
 
-// Plaintext format: `<tenant>_<43 base64url chars>`. 32 random bytes encoded
+// Plaintext format: `<prefix><43 base64url chars>`. 32 random bytes encoded
 // base64url is 43 chars and gives 256 bits of entropy — overkill against
-// brute force, cheap to copy. The tenant prefix (default `bevel_`) lets the
-// auth middleware route key-vs-JWT requests without parsing both shapes.
+// brute force, cheap to copy. The prefix lets the auth middleware route
+// key-vs-JWT requests without parsing both shapes.
 const TOKEN_BYTES = 32;
 
 const MAX_LABEL_LEN = 200;
 
 export class ExternalApiKeyService implements IExternalApiKeyService {
+  private readonly prefixes: readonly string[];
+
   /**
    * @param keyPrefix Tenant-derived plaintext prefix (e.g. `bevel_`) — injected
    *   from {@link AppConfig.externalApiKeyPrefix} so a deploy can brand its keys.
+   *   Every key of the default kind is minted with it.
+   * @param kinds Other kinds a key may be minted as, each with the plaintext
+   *   prefix that kind is spelled with — a Claude link's `gho_`, the shape
+   *   claude.ai expects from a GitHub host. Same key, same table, same
+   *   revocation; the KIND is stored on the row and is what tells such keys
+   *   apart (a label is the person's to edit), the prefix is only what the
+   *   outside world sees and what routes the bearer back here.
    */
   constructor(
     private readonly db: Database,
     private readonly keyPrefix: string,
-  ) {}
+    private readonly kinds: Readonly<Record<string, string>> = {},
+  ) {
+    this.prefixes = [keyPrefix, ...Object.values(kinds)];
+  }
 
-  /** True if a bearer string carries this tenant's external-API-key prefix. */
+  /** True if a bearer string carries one of this service's key prefixes. */
   looksLikeExternalApiKey(token: string): boolean {
-    return typeof token === 'string' && token.startsWith(this.keyPrefix);
+    return typeof token === 'string' && this.prefixes.some((p) => token.startsWith(p));
   }
 
-  async mint(userId: string, label: string): Promise<MintedExternalApiKey> {
+  async mint(userId: string, label: string, options: MintOptions = {}): Promise<MintedExternalApiKey> {
+    const kind = options.kind ?? DEFAULT_KEY_KIND;
+    const prefix = kind === DEFAULT_KEY_KIND ? this.keyPrefix : this.kinds[kind];
+    if (!prefix) throw new Error(`Unknown key kind "${kind}"`);
     const trimmed = (label ?? '').trim();
     if (trimmed.length === 0) {
       throw new InvalidTokenLabelError('Label cannot be empty');
@@ -48,12 +65,12 @@ export class ExternalApiKeyService implements IExternalApiKeyService {
       );
     }
 
-    const plaintext = this.keyPrefix + randomBytes(TOKEN_BYTES).toString('base64url');
+    const plaintext = prefix + randomBytes(TOKEN_BYTES).toString('base64url');
     const tokenHash = hashToken(plaintext);
 
     const [row] = await this.db
       .insert(externalApiKeys)
-      .values({ userId, tokenHash, label: trimmed })
+      .values({ userId, tokenHash, label: trimmed, kind })
       .returning();
 
     return {
@@ -202,6 +219,7 @@ function toSummary(row: typeof externalApiKeys.$inferSelect): ExternalApiKeySumm
   return {
     id: row.id,
     label: row.label,
+    kind: row.kind,
     createdAt: row.createdAt.getTime(),
     lastUsedAt: row.lastUsedAt ? row.lastUsedAt.getTime() : null,
     revokedAt: row.revokedAt ? row.revokedAt.getTime() : null,