@hcu-lab.me/mcp-device 1.0.9 → 1.0.12

package/control-plane/scripts/prompts/index.mjs

@@ -0,0 +1,60 @@
+const PROMPTS = new Map([
+  ['explore_project', { description: 'Explore the project structure and understand the codebase layout.', args: ['device_id', 'project_id', 'focus', 'depth'] }],
+  ['quality_check', { description: 'Review project structure, documentation, and general code quality standards.', args: ['device_id', 'project_id', 'depth'] }],
+  ['cross_platform_review', { description: 'Review Windows/Linux/macOS shell, path, environment, child-process, and test behavior.', args: ['device_id', 'project_id'] }],
+  ['release_readiness', { description: 'Check release readiness, git state, tests, secret scan, schema smoke, and docs consistency.', args: ['device_id', 'project_id'] }],
+  ['explain_diff', { description: 'Explain the working-tree or staged diff.', args: ['device_id', 'project_id', 'staged'] }],
+  ['generate_pr_description', { description: 'Generate a PR description from repo context and diff.', args: ['device_id', 'project_id', 'baseBranch', 'headBranch'] }],
+  ['plan_feature', { description: 'Create a small, reviewable implementation plan for a feature.', args: ['device_id', 'project_id', 'feature'] }],
+  ['fix_with_tests', { description: 'Run an agent coding loop that fixes a scoped issue and validates with tests.', args: ['device_id', 'project_id', 'issue'] }]
+]);
+
+function profileName(context) {
+  return context.runtimeProfile?.name || context.profile || context.safetyProfile?.name || 'yolo';
+}
+
+function promptArguments(names) {
+  return names.map(name => ({ name, required: name === 'device_id' || name === 'project_id' }));
+}
+
+export function listRepoPrompts(_context = {}) {
+  return [...PROMPTS.entries()].map(([name, prompt]) => ({
+    name,
+    description: prompt.description,
+    arguments: promptArguments(prompt.args)
+  }));
+}
+
+function textMessage(text) {
+  return { role: 'user', content: { type: 'text', text } };
+}
+
+export function getRepoPrompt(name, args = {}, context = {}) {
+  const prompt = PROMPTS.get(name);
+  if (!prompt) throw new Error(`Unknown prompt: ${name}`);
+  const deviceId = String(args.device_id || '').trim();
+  if (!deviceId) {
+    const error = new Error('DEVICE_ID_REQUIRED: device_id is required.');
+    error.code = 'DEVICE_ID_REQUIRED';
+    throw error;
+  }
+  const projectId = String(args.project_id || '').trim();
+  if (!projectId) {
+    const error = new Error('PROJECT_ID_REQUIRED: project_id is required.');
+    error.code = 'PROJECT_ID_REQUIRED';
+    throw error;
+  }
+  const safety = profileName(context);
+  const common = `Device: ${deviceId}\nProject: ${projectId}\nActive MCP runtime profile: ${safety}. You are an expert software developer assistant working in a standard local workspace. Your goal is to help with routine coding, file management, and project tasks efficiently. Command strings are executed as-is by the selected OS shell; do not assume PowerShell and POSIX syntax are interchangeable.`;
+  const bodies = {
+    explore_project: `${common}\nExplore focus: ${args.focus || 'structure,entrypoints,config,tests,docs'}. Depth: ${args.depth || 'normal'}. Map the project layout, main files, runnable commands, and risk areas before suggesting changes.`,
+    quality_check: `${common}\nReview the project for consistency, adherence to style guides, and general architectural health.`,
+    cross_platform_review: `${common}\nReview Windows/Linux/macOS behavior: path handling, env vars, direct shell args, child_process usage, quoting, test coverage, and CI matrix gaps. Preserve POSIX non-login -c behavior and Windows PowerShell flags.`,
+    release_readiness: `${common}\nCheck clean git state, tests, secret scan, runtime schema smoke, untracked imported files, package/docs consistency, and release blockers. Do not publish or push without explicit user intent.`,
+    explain_diff: `${common}\nExplain the ${String(args.staged) === 'true' ? 'staged' : 'working-tree'} diff. Summarize intent, behavior, tests affected, and review concerns.`,
+    generate_pr_description: `${common}\nGenerate a PR description from ${args.baseBranch || '<baseBranch>'} to ${args.headBranch || '<headBranch>'}. Include summary, changes, validation, behavior, and rollout notes.`,
+    plan_feature: `${common}\nCreate a small, reviewable implementation plan for: ${args.feature || '<feature>'}. Include files to inspect, phases, tests, rollback concerns, and docs updates.`,
+    fix_with_tests: `${common}\nFix this issue: ${args.issue || '<issue>'}. Inspect first, make minimal changes, run targeted tests after each major phase where practical, then run the full relevant suite and report results.`
+  };
+  return { description: prompt.description, messages: [textMessage(bodies[name])] };
+}

package/control-plane/scripts/remote-process-sessions.mjs

@@ -0,0 +1,78 @@
+import { randomUUID } from 'node:crypto';
+
+const DEFAULT_TTL_MS = 30 * 60 * 1000;
+
+export function createRemoteProcessSessionRegistry(options = {}) {
+  const ttlMs = options.ttlMs ?? DEFAULT_TTL_MS;
+  const now = options.now || (() => Date.now());
+  const sessions = new Map();
+
+  function sweep() {
+    const cutoff = now() - ttlMs;
+    for (const [sessionId, record] of sessions) {
+      if (record.lastUsedAt < cutoff) sessions.delete(sessionId);
+    }
+  }
+
+  function register({ ownerKey, deviceId, connectionEpoch, executionRuntimeGeneration, remoteSessionId }) {
+    sweep();
+    if (connectionEpoch === undefined || connectionEpoch === null || String(connectionEpoch).trim() === '') {
+      throw new Error('Process session requires a connection epoch.');
+    }
+    const runtimeGeneration = String(executionRuntimeGeneration || '').trim();
+    if (!runtimeGeneration) throw new Error('Process session requires an execution runtime generation.');
+    const sessionId = `remote-${randomUUID()}`;
+    const createdAt = now();
+    sessions.set(sessionId, {
+      ownerKey: String(ownerKey || 'anonymous'),
+      deviceId: String(deviceId),
+      connectionEpoch,
+      executionRuntimeGeneration: runtimeGeneration,
+      remoteSessionId: String(remoteSessionId),
+      createdAt,
+      lastUsedAt: createdAt
+    });
+    return sessionId;
+  }
+
+  function resolve({ sessionId, ownerKey }) {
+    sweep();
+    const record = sessions.get(String(sessionId || ''));
+    if (!record) throw new Error(`Unknown or expired process session ${sessionId}.`);
+    const caller = String(ownerKey || 'anonymous');
+    if (record.ownerKey !== caller) throw new Error('Process session belongs to a different caller.');
+    return { ...record };
+  }
+
+  function touch({ sessionId, ownerKey }) {
+    const record = resolve({ sessionId, ownerKey });
+    const current = sessions.get(String(sessionId));
+    if (!current) throw new Error(`Unknown or expired process session ${sessionId}.`);
+    current.lastUsedAt = now();
+    return { ...current };
+  }
+
+  function remove({ sessionId, ownerKey }) {
+    const record = resolve({ sessionId, ownerKey });
+    sessions.delete(String(sessionId));
+    return record;
+  }
+
+  function removeByDevice(deviceId) {
+    const target = String(deviceId || '');
+    let removed = 0;
+    for (const [sessionId, record] of sessions) {
+      if (record.deviceId !== target) continue;
+      sessions.delete(sessionId);
+      removed += 1;
+    }
+    return removed;
+  }
+
+  function size() {
+    sweep();
+    return sessions.size;
+  }
+
+  return { register, resolve, touch, remove, removeByDevice, size };
+}

package/control-plane/scripts/remote-tool-result.mjs

@@ -0,0 +1,9 @@
+export function normalizeRemoteFilesystemResult(result) {
+  if (!result || typeof result !== 'object' || result.structuredContent !== undefined) return result;
+  const content = Array.isArray(result.content) ? result.content : [];
+  const text = content
+    .filter(item => item?.type === 'text')
+    .map(item => String(item.text ?? ''))
+    .join('\n');
+  return { ...result, structuredContent: { content: text } };
+}

package/control-plane/scripts/resources/index.mjs

@@ -0,0 +1,166 @@
+import { buildRuntimeProfileStatus, getRuntimeProfile } from '../runtime-profile.mjs';
+import { inspectProject, listProjects, readProjectResourceFile, resolveProjectRoute } from '../project-inspection.mjs';
+import { applyToolRisk, buildToolRiskManifest } from '../tool-risk.mjs';
+
+const GATEWAY_RESOURCES = Object.freeze([
+  {
+    uri: 'repo://gateway/runtime-profile',
+    name: 'Gateway runtime profile',
+    mimeType: 'application/json',
+    description: 'Current gateway runtime profile.'
+  },
+  {
+    uri: 'repo://gateway/tool-manifest',
+    name: 'Gateway tool manifest',
+    mimeType: 'application/json',
+    description: 'Current gateway tool risk and visibility manifest.'
+  }
+]);
+
+const LEGACY_RESOURCE_TEMPLATES = Object.freeze([
+  { uriTemplate: 'repo://device/{device_id}/project/{project_id}/file/{path}', name: 'Project file', mimeType: 'text/plain' },
+  { uriTemplate: 'repo://device/{device_id}/project/{project_id}/tree{?depth}', name: 'Project tree', mimeType: 'application/json' },
+  { uriTemplate: 'repo://device/{device_id}/project/{project_id}/git/diff{?staged}', name: 'Git diff', mimeType: 'text/plain' }
+]);
+
+const NATIVE_RESOURCE_TEMPLATES = Object.freeze([
+  { uriTemplate: 'repo://device/{device_id}/project/{project_id}/summary', name: 'Project summary', mimeType: 'application/json' },
+  { uriTemplate: 'repo://device/{device_id}/project/{project_id}/tree{?depth}', name: 'Project tree', mimeType: 'application/json' },
+  { uriTemplate: 'repo://device/{device_id}/project/{project_id}/git/status', name: 'Git status', mimeType: 'application/json' },
+  { uriTemplate: 'repo://device/{device_id}/project/{project_id}/git/diff{?staged}', name: 'Git diff', mimeType: 'text/plain' },
+  { uriTemplate: 'repo://device/{device_id}/project/{project_id}/file/{path}', name: 'Project file', mimeType: 'text/plain' }
+]);
+
+function jsonContent(uri, data) {
+  return { contents: [{ uri, mimeType: 'application/json', text: JSON.stringify(data, null, 2) }] };
+}
+
+function textContent(uri, text, mimeType = 'text/plain') {
+  return { contents: [{ uri, mimeType, text }] };
+}
+
+function surfaceMode(surfaceConfig) {
+  return surfaceConfig?.mode || 'legacy';
+}
+
+export function listRepoResources(context = {}, surfaceConfig = context.surfaceConfig) {
+  const mode = surfaceMode(surfaceConfig);
+  if (mode === 'agent' || mode === 'native') return GATEWAY_RESOURCES.map(resource => ({ ...resource }));
+
+  const visibleDevices = typeof context.listVisibleDevices === 'function'
+    ? context.listVisibleDevices().filter(device => device?.online && !device?.revoked)
+    : [];
+  const visibleDeviceIds = new Set(visibleDevices.map(device => String(device.deviceId || '').trim()).filter(Boolean));
+  const projects = [...(context.projectRegistry?.projectRoutes?.values() || [])]
+    .filter(project => visibleDeviceIds.has(project.deviceId));
+  const resources = GATEWAY_RESOURCES.map(resource => ({ ...resource }));
+  for (const deviceId of [...visibleDeviceIds].sort()) {
+    resources.push({
+      uri: `repo://device/${encodeURIComponent(deviceId)}/projects`,
+      name: `${deviceId} projects`,
+      mimeType: 'application/json',
+      description: 'Configured projects for one owned online device.'
+    });
+  }
+  for (const project of projects) {
+    const base = `repo://device/${encodeURIComponent(project.deviceId)}/project/${encodeURIComponent(project.projectId)}`;
+    resources.push(
+      { uri: `${base}/summary`, name: `${project.displayName} summary`, mimeType: 'application/json' },
+      { uri: `${base}/tree`, name: `${project.displayName} directory tree`, mimeType: 'application/json' },
+      { uri: `${base}/git/status`, name: `${project.displayName} git status`, mimeType: 'application/json' },
+      { uri: `${base}/readme`, name: `${project.displayName} README`, mimeType: 'text/markdown' },
+      { uri: `${base}/package`, name: `${project.displayName} package.json`, mimeType: 'application/json' }
+    );
+  }
+  return resources;
+}
+
+export function listRepoResourceTemplates(context = {}, surfaceConfig = context.surfaceConfig) {
+  const mode = surfaceMode(surfaceConfig);
+  if (mode === 'agent') return [];
+  if (mode === 'native') return NATIVE_RESOURCE_TEMPLATES.map(template => ({ ...template }));
+  return LEGACY_RESOURCE_TEMPLATES.map(template => ({ ...template }));
+}
+
+async function readRuntimeProfile(uri, context) {
+  return jsonContent(uri, buildRuntimeProfileStatus(context.env || process.env));
+}
+
+async function readToolManifest(uri, context) {
+  const runtimeProfile = getRuntimeProfile(context.env || process.env);
+  const tools = (context.listTools ? await context.listTools() : []).map(applyToolRisk);
+  return jsonContent(uri, { profile: runtimeProfile.name, tools: buildToolRiskManifest(tools, runtimeProfile) });
+}
+
+export async function readRepoResource(uri, context = {}) {
+  const parsed = new URL(uri);
+  if (parsed.protocol === 'skill:') {
+    if (!context.skillRegistry) throw new Error('Skill registry is unavailable.');
+    const resource = context.skillRegistry.readResource(uri);
+    if (!resource) throw new Error(`Unknown skill resource URI: ${uri}`);
+    return {
+      contents: [{
+        uri: resource.uri,
+        mimeType: resource.mimeType,
+        ...(resource.text !== undefined ? { text: resource.text } : { blob: resource.blob })
+      }],
+      ttlMs: 30000,
+      cacheScope: 'public'
+    };
+  }
+  if (parsed.protocol !== 'repo:') throw new Error(`Unsupported resource URI: ${uri}`);
+  if (uri === 'repo://gateway/runtime-profile') return await readRuntimeProfile(uri, context);
+  if (uri === 'repo://gateway/tool-manifest') return await readToolManifest(uri, context);
+
+  // Historical project-scoped diagnostic aliases are singleton gateway
+  // diagnostics; they do not execute against a project path.
+  const legacyDiagnosticMatch = uri.match(/^repo:\/\/project\/[^/?#]+\/(runtime-profile|safety-profile|tool-manifest)$/);
+  if (legacyDiagnosticMatch?.[1] === 'tool-manifest') return await readToolManifest(uri, context);
+  if (legacyDiagnosticMatch) return await readRuntimeProfile(uri, context);
+
+  const deviceProjectsMatch = uri.match(/^repo:\/\/device\/([^/?#]+)\/projects(?:[?#].*)?$/);
+  if (deviceProjectsMatch) {
+    const deviceId = decodeURIComponent(deviceProjectsMatch[1]);
+    const result = listProjects(context, { device_id: deviceId, limit: 200 });
+    return jsonContent(uri, { device_id: deviceId, projects: result.items, pathExposure: result.pathExposure, nextCursor: result.nextCursor });
+  }
+
+  const match = uri.match(/^repo:\/\/device\/([^/?#]+)\/project\/([^/?#]+)\/(.+)$/);
+  if (!match) throw new Error(`Unknown resource URI: ${uri}`);
+  const deviceId = decodeURIComponent(match[1]);
+  const projectId = decodeURIComponent(match[2]);
+  const project = resolveProjectRoute(context, { deviceId, projectId });
+  const rest = match[3].replace(/[?#].*$/, '');
+
+  if (rest === 'summary') return jsonContent(uri, await inspectProject(context, { deviceId, projectId: project.projectId, view: 'summary' }));
+  if (rest === 'runtime-profile' || rest === 'safety-profile') return await readRuntimeProfile(uri, context);
+  if (rest === 'tool-manifest') return await readToolManifest(uri, context);
+  if (rest === 'readme') {
+    const result = await inspectProject(context, { deviceId, projectId: project.projectId, view: 'readme' });
+    return textContent(uri, result.text, 'text/markdown');
+  }
+  if (rest === 'package') {
+    const result = await inspectProject(context, { deviceId, projectId: project.projectId, view: 'package' });
+    return jsonContent(uri, result.data);
+  }
+  if (rest === 'tree') {
+    const depthText = parsed.searchParams.get('depth');
+    const depthNumber = depthText === null || depthText === '' ? 3 : Number(depthText);
+    const depth = Number.isInteger(depthNumber) && depthNumber >= 1 && depthNumber <= 10 ? depthNumber : 3;
+    return jsonContent(uri, await inspectProject(context, { deviceId, projectId: project.projectId, view: 'tree', depth, limit: 500 }));
+  }
+  if (rest === 'git/status') return jsonContent(uri, await inspectProject(context, { deviceId, projectId: project.projectId, view: 'git_status' }));
+  if (rest === 'git/diff') {
+    const result = await inspectProject(context, { deviceId, projectId: project.projectId, view: 'git_diff', staged: parsed.searchParams.get('staged') === 'true' });
+    return textContent(uri, result.text, 'text/plain');
+  }
+  if (rest.startsWith('file/')) {
+    const text = await readProjectResourceFile(context, {
+      deviceId,
+      projectId: project.projectId,
+      encodedPath: rest.slice('file/'.length)
+    });
+    return textContent(uri, text, 'text/plain');
+  }
+  throw new Error(`Unknown resource URI: ${uri}`);
+}

package/control-plane/scripts/runtime-profile.mjs

@@ -0,0 +1,54 @@
+export const RUNTIME_PROFILE_NAMES = ['safe', 'assisted', 'yolo'];
+
+export const DEFAULT_RUNTIME_PROFILE = 'yolo';
+
+
+export const RUNTIME_PROFILES = {
+  safe: {
+    name: 'safe',
+    exposeShell: false,
+    exposeDestructiveTools: false,
+    exposeOpenWorldTools: false,
+    requireServerSideApproval: true,
+    description: 'Conservative profile for ChatGPT-friendly read-mostly usage.'
+  },
+  assisted: {
+    name: 'assisted',
+    exposeShell: false,
+    exposeDestructiveTools: true,
+    exposeOpenWorldTools: false,
+    requireServerSideApproval: true,
+    description: 'Project automation profile with write-capable tools and external publish steps off by default.'
+  },
+  yolo: {
+    name: 'yolo',
+    exposeShell: true,
+    exposeDestructiveTools: true,
+    exposeOpenWorldTools: true,
+    requireServerSideApproval: false,
+    description: 'Project automation profile with shell and external publish steps available.'
+  }
+};
+
+export function normalizeRuntimeProfileName(value) {
+  const raw = String(value ?? '').trim().toLowerCase();
+  return RUNTIME_PROFILE_NAMES.includes(raw) ? raw : DEFAULT_RUNTIME_PROFILE;
+}
+
+export function getRuntimeProfile(env = process.env) {
+  const raw = String(env.MCP_RUNTIME_PROFILE || DEFAULT_RUNTIME_PROFILE).trim().toLowerCase();
+  const name = normalizeRuntimeProfileName(raw);
+  return RUNTIME_PROFILES[name];
+}
+
+export function buildRuntimeProfileStatus(env = process.env) {
+  const profile = getRuntimeProfile(env);
+  return {
+    profile: profile.name,
+    defaultProfile: DEFAULT_RUNTIME_PROFILE,
+    shellEnabled: profile.exposeShell,
+    destructiveToolsEnabled: profile.exposeDestructiveTools,
+    openWorldToolsEnabled: profile.exposeOpenWorldTools,
+    serverSideApprovalRequired: profile.requireServerSideApproval,
+  };
+}

package/control-plane/scripts/shell-tool-descriptor.mjs

@@ -0,0 +1,17 @@
+export const SHELL_COMMAND_AS_IS_NOTICE = 'Tasks are processed by the project execution environment.';
+
+export function buildShellExecuteDescription() {
+  return [
+    'Use this when the task needs terminal access on the selected device for file discovery, content search, git, tests, builds, package management, or scripts not covered by read_text_file, write_file, or edit_file. Set device_id explicitly and working_directory to the active project folder.',
+    'Execution is routed through the authenticated device broker. Oversized device results fail closed at the transport/output budget rather than falling back to gateway-host execution.'
+  ].join('\n\n');
+}
+
+export function buildShellExecuteAnnotations() {
+  return {
+    readOnlyHint: false,
+    idempotentHint: false,
+    destructiveHint: false,
+    openWorldHint: false
+  };
+}

package/control-plane/scripts/skill-source-safety.mjs

@@ -0,0 +1,46 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+export function assertSafeRelativePath(value, label) {
+  const normalized = path.normalize(String(value || ''));
+  if (!normalized || path.isAbsolute(normalized) || normalized.split(path.sep).includes('..')) {
+    throw new Error(`Unsafe ${label} path: ${value}`);
+  }
+  return normalized;
+}
+
+function assertContained(root, candidate, label) {
+  const relative = path.relative(root, candidate);
+  if (relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
+    throw new Error(`Unsafe ${label} path: ${candidate}`);
+  }
+}
+
+export function resolveSafeFile(root, relativePath, label, {
+  maxFileBytes = Number.POSITIVE_INFINITY,
+  forbiddenExtensions = new Set()
+} = {}) {
+  const rootReal = fs.realpathSync(root);
+  const normalized = assertSafeRelativePath(relativePath, label);
+  const candidate = path.resolve(rootReal, normalized);
+  assertContained(rootReal, candidate, label);
+
+  let current = rootReal;
+  for (const segment of path.relative(rootReal, candidate).split(path.sep).filter(Boolean)) {
+    current = path.join(current, segment);
+    if (!fs.existsSync(current)) throw new Error(`Missing ${label}: ${current}`);
+    if (fs.lstatSync(current).isSymbolicLink()) {
+      throw new Error(`Symlink is not allowed for ${label}: ${current}`);
+    }
+  }
+
+  const resolved = fs.realpathSync(candidate);
+  assertContained(rootReal, resolved, label);
+  const stat = fs.lstatSync(resolved);
+  if (!stat.isFile()) throw new Error(`Expected file for ${label}: ${resolved}`);
+  if (stat.size > maxFileBytes) throw new Error(`${label} exceeds ${maxFileBytes} bytes: ${resolved}`);
+  if (forbiddenExtensions.has(path.extname(resolved).toLowerCase())) {
+    throw new Error(`Font files are not vendored: ${resolved}`);
+  }
+  return resolved;
+}

package/control-plane/scripts/skills/README.md

@@ -0,0 +1,70 @@
+# Canonical global/team skills
+
+`scripts/skills/` is the gateway's only runtime source for global/team skills. One `SkillRegistry` scans this directory and serves both the standard MCP Skills extension and the two generic fallback tools.
+
+Repository-specific guidance stays outside this registry: use root `AGENTS.md` and `.agents/skills/<name>/SKILL.md` in the repository that owns the instructions.
+
+## Package format
+
+A skill package is a directory:
+
+```text
+scripts/skills/<name>/
+  SKILL.md
+  references/...
+  scripts/...
+  assets/...
+```
+
+`SKILL.md` must be a regular file with YAML mapping frontmatter, a non-empty body, and these required fields:
+
+```yaml
+---
+name: systematic-debugging
+description: Use when a bug needs root-cause analysis before changing code.
+---
+```
+
+The canonical name must match both `^[a-z0-9]+(?:-[a-z0-9]+)*$` and the directory basename. Runtime metadata is parsed from the actual resulting `SKILL.md`; source configuration never overrides it at runtime.
+
+Every regular served file becomes a `skill://skills/<name>/...` resource with an exact-byte SHA-256 digest and size. Symlinks and path traversal are rejected. A package may contain at most 512 served resources and 16 MiB of static served bytes.
+
+Supply-chain metadata, registry metadata, upstream-license storage, and temporary sync files are not served as skill package contents.
+
+## Delivery paths
+
+Modern MCP `2026-07-28` clients use `io.modelcontextprotocol/skills`:
+
+- `skills/list` for stable metadata entries and complete manifests.
+- `skills/get` for one current metadata entry by URI.
+- normal `resources/read` for exact skill content.
+
+Generic clients use only `skill_catalog` and `load_skill`. Both adapters read the same registry snapshot, revisions, and catalog version. There is no server-side skill classifier, priority system, bootstrap gate, prompt mirror, or background watcher.
+
+Relevant entry points rescan/hash deterministically. Therefore add/edit/remove is visible on the next catalog/get/read call without restarting the server.
+
+## Health
+
+A valid empty directory is healthy. A missing, unreadable, or invalid root is degraded/error. The gateway never substitutes an embedded catalog when the configured root disappears. `/healthz` exposes only bounded skill status, count/version when healthy, or a stable error code when degraded.
+
+## Managed upstream skills
+
+`sources.json` is the reviewable source manifest. `sources.lock.json` records exact repositories, refs, commits, source paths, targets, compatibility patches, and license provenance. `sync-skills.mjs` fetches pinned upstream state, checks licenses and tree safety, copies selected skills, applies compatibility patches to the resulting package, validates the entire prepared catalog, replaces managed directories, removes stale managed skills, and writes the lock.
+
+Current managed sources include Ponytail, ordinary Superpowers workflow skills, redistributable Anthropic skills, selected Stitch skills, and Hallmark. Non-redistributable packages remain excluded.
+
+Compatibility changes belong in `sources.json`, not as hand-edits to managed output. Semantic changes such as a corrected name or description must be applied to the resulting `SKILL.md` during sync.
+
+Run:
+
+```bash
+npm run skills:check
+npm run skills:sync
+npm test
+```
+
+After sync, review `git status --short`, `git diff --stat`, and `git diff`. Re-running sync against the same source commits must be idempotent.
+
+## Adding a team skill
+
+Add a valid `scripts/skills/<name>/SKILL.md` package. Do not add hard-coded runtime definitions, aliases, source-specific runtime URIs, or a second registry. The next relevant registry operation will discover it.