@skyramp/mcp 0.4.4-rc.2 → 0.5.0-rc.2

package/build/entitlements/entitlementGate.d.ts

@@ -0,0 +1,8 @@
+import type { McpServer } from "@modelcontextprotocol/server";
+import { type RunCodes } from "./runCodes.js";
+/**
+ * Makes every tool registered on `server` after this call check the run's
+ * entitlement codes before it runs. Without a run token it does nothing, so
+ * every tool behaves as before. Must be called before any tool is registered.
+ */
+export declare function installEntitlementGate(server: McpServer, readCodes?: () => Promise<RunCodes>, token?: string | undefined): void;

package/build/entitlements/entitlementGate.js

@@ -0,0 +1,57 @@
+import { readRunCodes } from "./runCodes.js";
+import { NOT_GATED, TOOLS } from "../tool-phases.js";
+const FEATURE_NAMES = {
+    analyze: "change analysis",
+    recommend: "test recommendations",
+    generate: "test generation",
+    execute: "test execution",
+};
+function refusal(text) {
+    return { content: [{ type: "text", text }], isError: true };
+}
+/** Returns why `tool` may not run with these codes, or undefined if it may. */
+function refusalReason(tool, code, run) {
+    if ("refused" in run) {
+        return `Tool ${tool} is not available: Skyramp could not confirm what this run is allowed to do. ${run.refused}`;
+    }
+    if (run.codes.has(code))
+        return undefined;
+    return `Tool ${tool} is not available: your Skyramp plan does not include ${FEATURE_NAMES[code]}.`;
+}
+/**
+ * Makes every tool registered on `server` after this call check the run's
+ * entitlement codes before it runs. Without a run token it does nothing, so
+ * every tool behaves as before. Must be called before any tool is registered.
+ */
+export function installEntitlementGate(server, readCodes = readRunCodes, token = process.env.SKYRAMP_RUN_TOKEN) {
+    if (!token?.trim())
+        return;
+    let codes;
+    const runCodes = () => (codes ??= readCodes()
+        .catch((err) => ({
+        refused: err instanceof Error ? err.message : String(err),
+    }))
+        .then((run) => {
+        // A refusal can be temporary, so the next tool call reads again.
+        if ("refused" in run)
+            codes = undefined;
+        return run;
+    }));
+    // Typed loosely: the gate forwards every argument as it came, whatever
+    // overload the tool used.
+    const target = server;
+    const register = target.registerTool.bind(target);
+    target.registerTool = (name, config, cb) => {
+        const code = TOOLS[name]?.entitlement;
+        if (code === NOT_GATED)
+            return register(name, config, cb);
+        const handler = cb;
+        return register(name, config, async (...args) => {
+            if (code === undefined) {
+                return refusal(`Tool ${name} is not available in this run.`);
+            }
+            const reason = refusalReason(name, code, await runCodes());
+            return reason ? refusal(reason) : handler(...args);
+        });
+    };
+}

package/build/entitlements/runCodes.d.ts

@@ -0,0 +1,18 @@
+export type RunCodes = {
+    codes: ReadonlySet<string>;
+}
+/** Core refused the run token; `refused` is its reason. */
+ | {
+    refused: string;
+};
+type Entitlements = {
+    codes: string[];
+} | {
+    error: string;
+};
+/** The part of SkyrampClient this file uses. Core releases before getEntitlements lack it. */
+export interface Core {
+    getEntitlements?: (repository: string) => Promise<Entitlements>;
+}
+export declare function readRunCodes(core?: Core, env?: NodeJS.ProcessEnv): Promise<RunCodes>;
+export {};

package/build/entitlements/runCodes.js

@@ -0,0 +1,15 @@
+/**
+ * The only file that may ask Skyramp core for the run's entitlement codes.
+ * Everything else in MCP reads them through `readRunCodes`, so a change on the
+ * core side changes this file and nothing else.
+ */
+import { SkyrampClient } from "@skyramp/skyramp";
+export async function readRunCodes(core = new SkyrampClient(), env = process.env) {
+    if (!core.getEntitlements) {
+        return { refused: "This Skyramp version does not support it yet." };
+    }
+    const answer = await core.getEntitlements(env.GITHUB_REPOSITORY ?? "");
+    return "error" in answer
+        ? { refused: answer.error }
+        : { codes: new Set(answer.codes) };
+}

package/build/index.js

@@ -10,6 +10,7 @@ import { registerExecuteFleetTool } from "./tools/executeFleetTool.js";
 import { AUTH_PLACEHOLDER_TOKEN } from "./types/TestTypes.js";
 import { AUTH_CONFLICT_ERROR_MSG } from "./prompts/test-recommendation/recommendationSections.js";
 import { logger } from "./utils/logger.js";
+import { installEntitlementGate } from "./entitlements/entitlementGate.js";
 import { registerUITestTool } from "./tools/generate-tests/generateUIRestTool.js";
 import { registerUILoadTestTool } from "./tools/generate-tests/generateUILoadRestTool.js";
 import { registerSmokeTestTool } from "./tools/generate-tests/generateSmokeRestTool.js";
@@ -33,7 +34,6 @@ import { registerMockTool } from "./tools/generate-tests/generateMockRestTool.js
 import { registerBatchMockTool } from "./tools/generate-tests/batchMockGenerationTool.js";
 import { registerAnalyzeChangesTool, registerAnalyzeTestHealthTool, registerActionsTool, registerRegisterTestPlanTool, registerResolveScreenTool, } from "./tools/test-management/index.js";
 import { registerTestbotPrompt } from "./prompts/testbot/testbot-prompts.js";
-import { registerSutSetupResource } from "./resources/sutSetupResource.js";
 import { registerTestbotResource } from "./resources/testbotResource.js";
 import { registerLocalDevPrompt } from "./prompts/local-dev/local-dev-prompts.js";
 import { registerSubmitReportTool } from "./tools/submitReportTool.js";
@@ -74,7 +74,7 @@ else if (localDevEnabled) {
     oneClickInstructions = localDevInstructions;
 }
 // Global workspace-init nudge for bare MCP usage. Suppressed in testbot mode,
-// which runs its own INIT_WORKSPACE step (buildWorkspaceInitSection()) instead.
+// which initializes the workspace in its own steps instead.
 const workspaceInitInstructions = isTestbotEnabled() || oneClickEnabled || localDevEnabled
     ? ""
     : `
@@ -156,6 +156,8 @@ async function createServer({ era }) {
   8. The user can always override workspace defaults by explicitly specifying values in their request.
   `,
     });
+    // Before any tool registers, so every tool goes through the check.
+    installEntitlementGate(server);
     // Register prompts
     logger.info("Starting prompt registration process");
     const prompts = [
@@ -167,8 +169,6 @@ async function createServer({ era }) {
         prompts.push(registerTestbotPrompt);
         registerTestbotResource(server);
         logger.info("Testbot prompt enabled via SKYRAMP_FEATURE_TESTBOT");
-        registerSutSetupResource(server);
-        logger.info("Testbot SUT setup resource enabled via SKYRAMP_FEATURE_TESTBOT");
     }
     if (isLocalDevEnabled()) {
         prompts.push(registerLocalDevPrompt);

package/build/playwright/essentialTools.d.ts

@@ -0,0 +1 @@
+export declare const ESSENTIAL_TOOLS: ReadonlySet<string>;

package/build/playwright/essentialTools.js

@@ -0,0 +1,43 @@
+// Only expose essential browser tools to reduce LLM confusion.
+// The full set (23 tools) overwhelms the LLM and causes it to use
+// browser_evaluate/browser_run_code instead of the simpler tools.
+//
+// browser_blueprint is the only DOM Analyzer tool registered — it handles
+// both full captures and same-URL deltas via the URL-cache (isFullCapture).
+// browser_blueprint_diff, browser_sitemap_build, browser_sitemap_query fire
+// 0 times in production evals and have no active call path in the testbot prompt.
+//
+// browser_widget_contract_lookup / browser_widget_contract_cache are
+// intentionally excluded: the curated fingerprint library only covers
+// test fixtures (not production widgets), and the LLM can handle custom
+// widgets via snapshot-driven trial-and-error without the tool.
+// The widgetType field on blueprint elements still signals "custom" to
+// the agent — no guidance is lost.
+export const ESSENTIAL_TOOLS = new Set([
+    "browser_navigate",
+    "browser_snapshot",
+    "browser_click",
+    "browser_type",
+    "browser_press_key",
+    "browser_select_option",
+    "browser_hover",
+    "browser_drag",
+    "browser_file_upload",
+    "browser_evaluate",
+    "browser_tabs",
+    "browser_navigate_back",
+    "browser_wait_for",
+    "browser_take_screenshot",
+    "browser_assert",
+    "browser_assert_hidden",
+    "browser_assert_api_request",
+    "browser_assert_table_cell",
+    "browser_mouse_action",
+    "browser_visual_snapshot",
+    "browser_gojs_add_node",
+    "browser_gojs_link",
+    "skyramp_export_zip",
+    "skyramp_load_trace",
+    // DOM Analyzer: blueprint capture (capture-act-capture pattern)
+    "browser_blueprint",
+]);

package/build/playwright/registerPlaywrightTools.js

@@ -8,6 +8,7 @@ import { PlaywrightTraceService, } from "./PlaywrightTraceService.js";
 import { blueprintJsonSpan } from "./blueprintDigest.js";
 import { recordBlueprintCapture, recordBrowserNavigation, } from "./blueprintDigestStore.js";
 import { recordTraceExport } from "./traceExportStore.js";
+import { ESSENTIAL_TOOLS } from "./essentialTools.js";
 let _service = null;
 export function getPlaywrightTraceService() {
     return _service;
@@ -169,49 +170,6 @@ export async function registerPlaywrightTools(server, options) {
     }
     const tools = _service.getTools();
     logger.info(`Registering ${tools.length} Playwright browser tools`);
-    // Only expose essential browser tools to reduce LLM confusion.
-    // The full set (23 tools) overwhelms the LLM and causes it to use
-    // browser_evaluate/browser_run_code instead of the simpler tools.
-    //
-    // browser_blueprint is the only DOM Analyzer tool registered — it handles
-    // both full captures and same-URL deltas via the URL-cache (isFullCapture).
-    // browser_blueprint_diff, browser_sitemap_build, browser_sitemap_query fire
-    // 0 times in production evals and have no active call path in the testbot prompt.
-    //
-    // browser_widget_contract_lookup / browser_widget_contract_cache are
-    // intentionally excluded: the curated fingerprint library only covers
-    // test fixtures (not production widgets), and the LLM can handle custom
-    // widgets via snapshot-driven trial-and-error without the tool.
-    // The widgetType field on blueprint elements still signals "custom" to
-    // the agent — no guidance is lost.
-    const ESSENTIAL_TOOLS = new Set([
-        "browser_navigate",
-        "browser_snapshot",
-        "browser_click",
-        "browser_type",
-        "browser_press_key",
-        "browser_select_option",
-        "browser_hover",
-        "browser_drag",
-        "browser_file_upload",
-        "browser_evaluate",
-        "browser_tabs",
-        "browser_navigate_back",
-        "browser_wait_for",
-        "browser_take_screenshot",
-        "browser_assert",
-        "browser_assert_hidden",
-        "browser_assert_api_request",
-        "browser_assert_table_cell",
-        "browser_mouse_action",
-        "browser_visual_snapshot",
-        "browser_gojs_add_node",
-        "browser_gojs_link",
-        "skyramp_export_zip",
-        "skyramp_load_trace",
-        // DOM Analyzer: blueprint capture (capture-act-capture pattern)
-        "browser_blueprint",
-    ]);
     const filteredTools = tools.filter((t) => ESSENTIAL_TOOLS.has(t.name));
     logger.info(`Filtering to ${filteredTools.length} essential tools (from ${tools.length} total)`);
     for (const tool of filteredTools) {

package/build/prompts/initialize-workspace/initializeWorkspacePrompt.d.ts

@@ -1 +1,18 @@
 export declare const INIT_WORKSPACE_INSTRUCTIONS: string;
+/** A repository of the Target other than the workspace's own, scanned into the same workspace.yml. */
+export interface ScanRelatedRepository {
+    /** owner/repo, set verbatim as each of its services' `repository`. */
+    repository: string;
+    repositoryPath: string;
+}
+/**
+ * The scan instructions for one workspace. With related repositories, every
+ * repository is scanned into the one workspace.yml at `workspacePath`, each
+ * related repository's services carrying its `repository`. With a test
+ * repository, testDirectory is read from, and relative to, that checkout.
+ */
+export declare function buildInitWorkspaceInstructions(target: {
+    workspacePath: string;
+    relatedRepositories?: ScanRelatedRepository[];
+    testRepositoryPath?: string;
+}): string;

package/build/prompts/initialize-workspace/initializeWorkspacePrompt.js

@@ -1,178 +1,47 @@
 import { getPersonaPrefix } from "../personas.js";
-import { AUTH_TYPES_PROMPT_LIST } from "../../utils/workspaceAuth.js";
-export const INIT_WORKSPACE_INSTRUCTIONS = `${getPersonaPrefix()}Your task is to scan this repository, discover ALL services, and call the skyramp_init_workspace tool with the discovered services array and the scanToken.
-
-After scanning the workspace, before calling the skyramp_init_workspace tool, you MUST:
-1. Output a <thinking> block to justify the reasoning behind each field mapping for every discovered service. Follow the scanning sections first, then field definitions, then verification.
-2. Then output a Discovery Summary with the exact services array you will pass to the tool:
-\`\`\`json
-[
-  {
-    "serviceName": "<name>",
-    "language": "<language>",
-    "framework": "<framework>",
-    "testDirectory": "<path>",
-    "api": { "schemaPath": "<path-or-url>", "baseUrl": "<url>", "authType": "<type>", "authHeader": "<header>" },
-    "runtimeDetails": { "runtime": "<runtime>", "serverStartCommand": "<command>", "serverStopCommand": "<docker stop command>", "dockerNetwork": "<network>" }
-  }
-]
-\`\`\`
-
-### List all top-level directories
-<list_directories>
-Run a directory listing of the workspace root. Every top-level directory is a potential service. Common layouts:
-| Layout | Example dirs | Expect |
-|--------|-------------|--------|
-| Monorepo | apps/web, apps/api, packages/shared | 1 service per app |
-| Microservices | services/auth, services/orders | 1 service per service dir |
-| Single service | src/, lib/ | 1 service (the root) |
-
-If the repo is a monorepo, check for workspace manifests BEFORE scanning individual directories:
-1. JavaScript/TypeScript monorepos:
-   - If pnpm-workspace.yaml exists, read the packages array to find all package directories (for example, ["apps/*", "packages/*"]).
-   - If turbo.json exists, read the root package.json workspaces field to enumerate all packages.
-   - If lerna.json exists, read the packages array in lerna.json (for example, ["packages/*"]).
-   - If the root package.json has a "workspaces" field, use the glob patterns to identify all packages.
-   - If nx.json exists, scan the projects in nx.json or project.json files in subdirectories.
-2. Java monorepos:
-   - If a parent pom.xml has a <modules> section, each listed module is a separate service (Maven multi-module project).
-   - If settings.gradle or settings.gradle.kts has include statements, each included project is a separate service (Gradle multi-project).
-3. Python monorepos:
-   - If a pyproject.toml has a [tool.poetry.packages] or [tool.setuptools.packages] section with multiple paths, each is a potential service.
-   - If multiple directories each contain their own pyproject.toml or requirements.txt, treat each as an independent service.
-When any of these exist, use the workspace manifest to enumerate ALL packages and apps. Each package with its own server entry point, API routes, or UI framework is a separate service. Do NOT skip frontend packages. A Next.js app, React SPA, or Vue app in the monorepo is a service.
-</list_directories>
-
-### Inspect every candidate directory
-<inspect_directories>
-For each top-level directory, check for service indicator files.
-
-Language indicators (presence of any means an independent service):
-1. package.json indicates typescript or javascript
-2. requirements.txt, pyproject.toml, or Pipfile indicates python
-3. pom.xml or build.gradle indicates java
-
-Test framework (look inside the service directory):
-1. playwright.config.* indicates playwright
-2. pytest.ini, conftest.py, or pyproject.toml [tool.pytest] indicates pytest
-3. junit in pom.xml indicates junit
-
-API schemas (look inside the service directory and check known framework defaults):
-1. openapi.json/yaml or swagger.json/yaml provides the schema file path
-2. FastAPI projects serve the schema at http://localhost:{port}/openapi.json
-3. Express with swagger-ui serves at http://localhost:{port}/api-docs
-4. Spring Boot serves at http://localhost:{port}/v3/api-docs
-</inspect_directories>
-
-### Check root-level runtime config
-<runtime_config>
-Inspect the repo root (and subdirectories like .devcontainer/) for shared runtime configuration:
-1. CLAUDE.md or AGENTS.md: if either file exists at the repo root, check it for dev/test/CI setup instructions including how to start services, required environment variables, and runtime configuration.
-2. Docker Compose files: scan for ALL compose files including docker-compose.yml, docker-compose.yaml, docker-compose.*.yml (such as docker-compose.testbot.yml or docker-compose.dev.yml), compose.yml, and compose.*.yaml in the repo root and subdirectories. Distinguish between application compose files and infrastructure-only compose files. Infrastructure compose files contain only supporting services like databases, Redis, Minio, mail servers, or message queues and do NOT run the application itself. Application compose files contain the actual application services that build from the repo source code (look for "build:" directives pointing to the repo, or services that map to discovered application directories). Only use application compose files for determining runtime, serverStartCommand, and serverStopCommand. When a non-default compose file is found, the serverStartCommand and serverStopCommand must reference it explicitly (such as "docker compose -f docker-compose.testbot.yml up -d --build <service-name>" and "docker compose -f docker-compose.testbot.yml stop <service-name>"). Docker Compose ALWAYS prefixes the network name with the project name. If compose has "networks: { my-net: ... }", the actual network name is "<project-name>_my-net". If there is no explicit networks section, the default network is "<project-name>_default". The project name is the basename of the working directory where docker compose runs.
-3. Makefile: extract start and dev targets.
-4. Root package.json scripts: extract workspace-level commands.
-</runtime_config>
-
-### Build the complete services array
-<build_services>
-Create one service entry per deployable unit. You MUST include every backend/API service (Python, Java, Go, Node.js) and every frontend service (React, Vue, Angular, Next.js). Set runtime fields from docker-compose.yml if present.
-</build_services>
-
-### Basic fields
-<basic_fields>
-1. serviceName (required): A unique identifier for the service. Use the format <repoName>-<serviceDirName>-<frontend or backend> for consistency. For example: directus-api-backend, directus-app-frontend. If the directory name already ends with "backend" or "frontend", do not duplicate the suffix (use "demoshop-fullstack-backend" not "demoshop-fullstack-backend-backend"). For single-service repos where the service directory is the root, omit the directory portion such as onlineBoutique-frontend.
-2. language (required): One of python, typescript, javascript, or java. Detect from package.json (typescript or javascript), requirements.txt or pyproject.toml (python), or pom.xml or build.gradle (java).
-3. framework (required): One of playwright, pytest, robot, or junit. Detect from pytest.ini, playwright.config, jest.config, or junit in pom.xml. The framework MUST match the language: python uses pytest or robot, typescript or javascript uses playwright, and java uses junit.
-4. testDirectory (required): A stable path relative to the repo root where generated tests for this service will be placed. For each service, use the test directory configured by that service's test framework when one is discoverable:
-   - Playwright: Read playwright.config.ts (or .js/.mjs) and extract the testDir value.
-   - pytest: Read pytest.ini, pyproject.toml [tool.pytest.ini_options], or setup.cfg [tool:pytest] for testpaths.
-   - JUnit: Usually src/test/java. Check pom.xml or build.gradle for custom test source directories.
-   If no framework-configured test directory is available, use the Skyramp deterministic fallback:
-   - Single service: set testDirectory to tests/skyramp.
-   - Multiple services or monorepos: set testDirectory to tests/skyramp/<serviceDirName>, where <serviceDirName> is the service directory name with path separators and whitespace replaced by hyphens.
-   Framework config takes precedence. Use the Skyramp deterministic fallback only when no framework-configured test directory is available.
-   NEVER set testDirectory to \`.skyramp\`, to any path inside it, or to \`.\` or the repo root, whatever the framework config or existing test files say. \`.skyramp\` is the executor's own working area: it holds the run videos and executor artefacts. skyramp_init_workspace rejects all of these, and the generation tools refuse to write there.
-</basic_fields>
-
-### API fields
-<api_fields>
-1. api.schemaPath: Path or URL to an OpenAPI or Swagger schema. Search for openapi.json, openapi.yaml, swagger.json, or swagger.yaml files. Framework defaults are: FastAPI serves /openapi.json, Express serves /api-docs, and Spring serves /v3/api-docs. For locally-run services, use a localhost URL. For cloud or externally hosted services (such as Salesforce, Vercel, or Cloudflare), use the actual deployment URL found in config or documentation.
-2. api.baseUrl (required): The base URL where the service is reachable, such as "http://localhost:3000" or "https://api.example.com". Derive from docker-compose ports, app config, README, or environment variables. Use localhost for services run locally and the actual deployment URL for cloud or externally hosted services. NEVER fabricate a URL. Only use URLs found in config files, README, or environment variables.
-   Include the API path prefix (e.g. \`/api\`, \`/api/v1\`, \`/v1\`) when one applies — not just \`host:port\`. A bare host means every test request hits the root and 404s. Derive the prefix from the strongest available signal: OpenAPI \`servers[].url\` or \`basePath\`; the app's routing config (FastAPI \`root_path\`, Express \`app.use('/api/v1', ...)\`, Rails routes prefix, Django \`urlpatterns\` mount); or the longest common leading path across the existing test suite's endpoints. If none of those yield a prefix, leave it bare AND flag it in your summary so the user can review.
-3. api.authType (required): The authentication type. Valid values are: ${AUTH_TYPES_PROMPT_LIST}
-   Detect by checking in the following order (language-agnostic, apply whichever signals match):
-   a. Dependencies and packages (package.json, requirements.txt, go.mod, Gemfile, composer.json, pom.xml, build.gradle):
-      - jsonwebtoken, passport-jwt, @nestjs/jwt, jose, fastapi[security], PyJWT, python-jose, github.com/golang-jwt/jwt, jjwt, or spring-security-oauth2 indicates bearer. Spring exception: if spring-security is present but the security config uses HttpSecurity.formLogin() or sessionManagement() without a JwtDecoder bean, the actual auth is session cookies so use cookie. Check the SecurityConfig or WebSecurityConfigurerAdapter class before assigning bearer to any Spring service.
-      - passport-http or Spring basic auth indicates basic.
-      - passport-oauth2, openid-client, doorkeeper, keycloak-connect, spring-security-oauth2-resource-server, or github.com/coreos/go-oidc indicates oauth.
-      - rest_framework with TokenAuthentication or djangorestframework-simplejwt (Token scheme) indicates token.
-      - express-session, cookie-session, iron-session, next-auth, gorilla/sessions, or laravel/session indicates cookie.
-      - laravel/sanctum or laravel/passport on API routes indicates bearer; on frontend web routes indicates cookie.
-   b. Environment variables (.env, docker-compose, README):
-      - JWT_SECRET, ACCESS_TOKEN_SECRET, FIREBASE_SECRET, or SUPABASE_JWT_SECRET indicates bearer.
-      - API_KEY, X_API_KEY, ADMIN_KEY, or SERVICE_KEY (used as header value, not JWT signing) indicates apiKey.
-      - CLIENT_ID paired with CLIENT_SECRET, OAUTH_CLIENT_*, or OIDC_* indicates oauth.
-      - SESSION_SECRET, COOKIE_SECRET, or NEXTAUTH_SECRET indicates cookie.
-   c. Source code and middleware patterns (auth, middleware, or security config files):
-      - Node/Express: req.headers.authorization split "Bearer" indicates bearer. "Authorization: Token" indicates token. Custom header check indicates apiKey. Session or cookie middleware indicates cookie.
-      - FastAPI/Starlette: HTTPBearer, OAuth2PasswordBearer, or Depends(get_current_user) indicates bearer. SessionMiddleware indicates cookie.
-      - Django/DRF: TokenAuthentication indicates token. JWTAuthentication indicates bearer. SessionAuthentication indicates cookie.
-      - Spring: JwtDecoder or JwtAuthenticationFilter indicates bearer. HttpSecurity.formLogin() with sessions indicates cookie.
-      - Go: ParseWithClaims or GetHeader("Authorization") indicates bearer. gorilla/sessions indicates cookie.
-      - Rails: authenticate_or_request_with_http_token indicates bearer. before_action :authenticate_user! (Devise) indicates cookie.
-      - Laravel: auth:sanctum on API indicates bearer. middleware("auth") on web indicates cookie.
-      - Rust/Axum: Authorization<Bearer> extraction indicates bearer.
-   d. Query-parameter auth: Some APIs pass credentials as a URL query param rather than a header (such as ?key=<key>, ?api_key=<key>, or ?access_token=<token>). Signals include source code reading credentials from req.query.key, request.query_params["api_key"], or @RequestParam("token"), and API docs or README showing auth examples like /endpoint?key=<your-key>.
-   e. Fallback: For frontend or UI services, use none. For backend APIs with no header-based auth signals, use bearer.
-4. api.authHeader: The exact HTTP header name carrying the credential.
-   - For bearer, basic, oauth, or token: always "Authorization" (inferred automatically, so you may omit it).
-   - For cookie or session: always "Cookie" (also inferred automatically).
-   - For apiKey: this is required. Set to the actual custom header name such as "X-API-Key" or "X-Admin-Key".
-   - For none: set authHeader to "".
-5. api.authScheme: The Authorization header prefix (the word before the token). Standard types derive this automatically: bearer uses "Bearer", token uses "Token", and basic uses "Basic". Set explicitly only for custom or non-standard schemes (for example, Hawk uses "Hawk" and Digest uses "Digest"). Omit for cookie, session, or apiKey since they do not use the Authorization header.
-</api_fields>
-
-### Runtime fields
-<runtime_fields>
-1. runtimeDetails.runtime (required): One of local, docker, or k8s. Detect per service:
-   - If the service is listed in an application docker compose file (one that builds or runs the application, not infrastructure-only files containing only databases, caches, or queues) or has a Dockerfile as its intended run method, use "docker".
-   - If k8s manifests exist (charts/, k8s/, deploy/) AND the service is intended to run in K8s for local development, use "k8s".
-   - If the service has no Docker or k8s configuration and is run directly via a language runtime (npm, python, java, etc.), use "local".
-   A repo may have MIXED runtimes. A backend in docker-compose.yml uses "docker" while a frontend run with pnpm or npm locally uses "local". Include ALL services regardless of runtime.
-   If the frontend is bundled inside the API Docker container (no separate frontend service in the compose file), both frontend and backend services should use runtime "docker", share the same baseUrl (the container's exposed URL), and use the same serverStartCommand since they run in the same container.
-   IMPORTANT — proxy parameters are NOT runtime indicators: If proxyKubeconfig, proxyNamespace, or proxyUrl appear in the conversation context, they are for a Skyramp proxy worker that collects traffic samples for mock generation. They do NOT indicate the repo's runtime. Do not use proxy K8s params to set runtime, k8sNamespace, or k8sContext. Determine the runtime solely from the repo's own files (docker-compose.yml, Dockerfile, k8s manifests that are part of the repo's own local dev workflow). Note that many repos have K8s deployment manifests for staging/production but use Docker Compose for local development — check which setup the repo actually uses for local dev.
-2. runtimeDetails.serverStartCommand: The command to start or deploy the service. It MUST match the runtime:
-   - For "docker" runtime: Use a Docker command that rebuilds application services from the working tree before starting them, such as "docker compose up -d --build <service-name>" for the default docker-compose.yml, or "docker compose -f <compose-file> up -d --build <service-name>" when using a non-default compose file. This is always derivable from the application docker compose file and service name. If the compose service has no build context and only references an image, note that the command cannot rebuild local code.
-   - For "k8s" runtime: Use a deploy command such as "kubectl apply -f deploy/", "helm install myrelease .", or "skaffold run". This is always derivable from the manifests or charts present in the repo.
-   - For "local" runtime: Use an application command such as "uvicorn main:app", "npm run dev", or "java -jar app.jar". Derive from Makefile, package.json scripts, or README. If no start command is discoverable, omit this field entirely.
-   NEVER mix runtime types with incompatible commands (for example, using "uvicorn" with runtime "docker" will cause errors). For "local" runtime, NEVER fabricate a command. Only use commands found in Makefile, package.json scripts, or README.
-3. runtimeDetails.serverStopCommand: Optional command to stop the service after test execution. ONLY set when runtime is "docker" and serverStartCommand starts persistent Docker infrastructure. For docker compose starts, prefer matching stop/down commands from the same compose file. Omit this field for "local" and "k8s" runtimes, or when teardown is unsafe or not discoverable.
-4. runtimeDetails.dockerNetwork: Docker network name. ONLY set when runtime is "docker". NEVER set for "local" or "k8s".
-5. runtimeDetails.k8sNamespace: Kubernetes namespace. ONLY set when runtime is "k8s". NEVER set for "local" or "docker".
-6. runtimeDetails.k8sContext: Kubernetes context. ONLY set when runtime is "k8s". NEVER set for "local" or "docker".
-</runtime_fields>
-
-### Verification
-<verification>
-Before calling skyramp_init_workspace, confirm all of the following:
-1. Always scan the repo and find services. A repo should have at least one service.
-2. ALL services are included, both backend and frontend. The workspace config is a complete registry of the entire repo, not just the service relevant to your current task. A fullstack or monorepo MUST have multiple services. If you found only one, re-scan every top-level directory before proceeding.
-3. Services NOT in docker-compose.yml (such as a frontend run with pnpm or npm locally) MUST still be included with runtime "local".
-4. Every service has api.baseUrl set to a valid, discoverable URL. Use localhost for local services or the actual deployment URL for cloud or external services. Never fabricate a URL.
-5. Every service with authType apiKey has authHeader explicitly set to the actual custom header name (such as "X-API-Key" or "X-Admin-Key"). If you cannot find the header name in the source code, env vars, or README, do NOT use authType apiKey. Use authType none instead and add a YAML comment explaining auth is unresolved.
-6. framework matches language (python uses pytest or robot, typescript or javascript uses playwright, java uses junit).
-7. testDirectory follows the stable resolution rules above: framework config file when present (Playwright testDir in playwright.config.ts, pytest testpaths in pytest.ini or pyproject.toml, JUnit test source dir in pom.xml or build.gradle); otherwise the deterministic default (tests/skyramp for a single service, tests/skyramp/<serviceDirName> for multiple services). No service uses \`.skyramp\`, \`.\` or the repo root.
-8. If serverStartCommand is provided, it matches the runtime. If serverStopCommand is provided, runtime is "docker" and the command is a Docker command.
-9. For services in docker-compose.yml: runtime MUST be "docker" and the command MUST be a docker command such as "docker compose up -d --build <service-name>" when the service has a build context. Always include it since it is derivable from the service name.
-10. NEVER use application-level commands (uvicorn, npm, node, python, java, etc.) with runtime "docker".
-11. For "local" runtime: if no start command is discoverable from Makefile, package.json scripts, or README, omit serverStartCommand rather than guessing.
-12. dockerNetwork is set only when runtime is "docker".
-13. k8sNamespace and k8sContext are set only when runtime is "k8s".
-14. If force-recreating a workspace.yml due to a schema validation error, correct the schema error but keep any valid system-under-test setup (serviceName, baseUrl, auth config, runtime details) as it is.
-</verification>
-
-Once verified, call skyramp_init_workspace with:
-- workspacePath: the repository root path
-- services: the array built above
-- scanToken: the token returned by the first call to skyramp_init_scan
-- force: defaults to false. Set to true only if the user explicitly asks to overwrite an existing .skyramp/workspace.yml, or if the existing file must be regenerated due to a validation failure such as a schema mismatch, unknown fields, or a parse error.`;
+export const INIT_WORKSPACE_INSTRUCTIONS = `${getPersonaPrefix()}Scan this repository and register every component of the system under test in .skyramp/workspace.yml.
+
+### Find the components
+A component runs on its own: a backend API, a frontend app, or a worker with its own entry point. Shared libraries are not components. Read the workspace manifests, compose and container files, CI workflows, README, CLAUDE.md and AGENTS.md, then check every top-level directory. Register every component, frontends included; a monorepo usually has several.
+
+### Fields
+Take every value from a file you read or a rule below; never invent one. For each component:
+- serviceName: always \`<repoName>-<componentDir>\`, or \`<repoName>\` for a component at the root.
+- language: the language of its tests, or of its code when it has none, in lowercase.
+- framework: the framework of its API or UI tests; when it has none, the one its repository or language commonly uses. Never leave it out.
+- testDirectory: where generated tests go, relative to the repository root. Use the directory its test framework config names; otherwise \`tests/skyramp\` for a single component, or \`tests/skyramp/<componentDir>\` for several, with \`/\` in the directory replaced by \`-\`. Never \`.skyramp\`, a path inside it, or the root.
+- api.baseUrl: the URL its API paths are appended to: scheme, host and port where it runs locally (or its hosted URL), plus a base path only when its OpenAPI \`servers\` URL or \`basePath\` holds one the paths leave out. A frontend the backend serves shares the backend's. api.schemaPath: its OpenAPI file or URL, if any.
+- api.authType: from its auth code, dependencies or environment variables; \`none\` without a signal. For \`apiKey\`, set api.authHeader to the header name.
+- runtimeDetails.runtime: \`docker\` when it runs in containers, \`k8s\` when it runs on Kubernetes, else \`local\`, as the repository runs it. dockerNetwork: the network its containers join, if any.
+
+### Call the tool
+First write a Discovery Summary: the services array, and for each value the file or rule that set it. Then call skyramp_init_workspace with workspacePath (the repository root), services and scanToken. Set force only when the user asks to overwrite, or the existing file fails validation; then keep its valid values. When the tool refuses, fix every problem it lists and call it again with the full array and the same scanToken.`;
+/**
+ * The scan instructions for one workspace. With related repositories, every
+ * repository is scanned into the one workspace.yml at `workspacePath`, each
+ * related repository's services carrying its `repository`. With a test
+ * repository, testDirectory is read from, and relative to, that checkout.
+ */
+export function buildInitWorkspaceInstructions(target) {
+    const related = target.relatedRepositories ?? [];
+    const deliveryRoot = target.testRepositoryPath ?? target.workspacePath;
+    const blocks = [];
+    if (related.length > 0) {
+        blocks.push(`### Target repositories
+<target_repositories>
+Scan each repository below as above; pass the components of all ${related.length + 1} to one skyramp_init_workspace call with workspacePath "${target.workspacePath}":
+- ${target.workspacePath}: this workspace's own, with no repository.
+${related.map((r) => `- ${r.repositoryPath}: set repository to "${r.repository}" on each of its components.`).join("\n")}
+Write a related repository's paths from its own root, except testDirectory: every testDirectory is relative to ${deliveryRoot}, and a related repository's fallback is \`tests/skyramp/<repoName>\`, or \`tests/skyramp/<repoName>-<componentDir>\` with several components.
+</target_repositories>`);
+    }
+    if (target.testRepositoryPath) {
+        blocks.push(`### Test repository
+<test_repository>
+Generated tests go to the test repository at ${target.testRepositoryPath}. Read testDirectory from its framework config, relative to its root, with the same fallback. Register no component for it.
+</test_repository>`);
+    }
+    return blocks.length
+        ? `${INIT_WORKSPACE_INSTRUCTIONS}\n\n${blocks.join("\n\n")}`
+        : INIT_WORKSPACE_INSTRUCTIONS;
+}

package/build/prompts/test-maintenance/driftAnalysisShared.js

@@ -57,7 +57,7 @@ ${opts.domainNotes}
 
 **If your rationale concludes the test is unaffected, assign IGNORE, not VERIFY.** Assign VERIFY only for a doubt that the code you read does not settle. A rule that forbids IGNORE still applies.
 
-**A stated requirement wins over the code.** Before you write a new value or refresh a screenshot in an existing test, compare it with what the pull request title, the description and any requirements file they name state. If the new value breaks a stated requirement, do not write it: keep that assertion on the requirement's value and make only the other edits. If no other edit remains, mark the test VERIFY. The test stays red; do not relax it. If the requirements file is unchanged and the description presents the new behaviour as intended, the file is out of date: update the test.
+**A stated requirement wins over the code.** Before you write a new value or refresh a screenshot in an existing test, compare it with what the pull request title, the description and any requirements file they name state. If the new value breaks a stated requirement, do not write it: keep that assertion on the requirement's value and make only the other edits. If no other edit remains, mark the test VERIFY. The test stays red; do not relax it. Authority runs requirements > PR description > code change: an unchanged requirements file that the description contradicts still wins — keep the assertion on the file's value and report the requirement conflict.
 
 **Pre-commit verification — confirm before finalizing UPDATE/REGENERATE/DELETE:**
 1. You can quote a specific diff line${opts.blueprintSuffix} this test observes that triggered the action.

package/build/tool-phases.d.ts

@@ -1,11 +1,12 @@
 /**
- * Canonical mapping of Skyramp MCP tool names to testbot progress phases.
+ * One entry per Skyramp MCP tool: its testbot progress phase, if it has one,
+ * and the entitlement code it needs when the run has a SKYRAMP_RUN_TOKEN.
+ * Every registered tool must have an entry; tool-phase-coverage.test.ts fails
+ * when one is missing.
  *
- * The testbot progress UI reads this map at runtime to know which tool calls
- * correspond to which progress steps. When adding or renaming tools, update
- * this map so the progress UI stays accurate.
- *
- * Tools not in this map must be listed in TOOLS_WITHOUT_PHASE.
+ * The testbot progress UI reads TOOL_PHASE_MAP at runtime (through the
+ * `@skyramp/mcp/tool-phases` package export) to know which tool calls
+ * correspond to which progress steps.
  *
  * Phases: analyzing, generating, executing, maintaining, reporting
  *
@@ -29,10 +30,15 @@ export type PhaseMapping = string | {
     before: string;
     after: string;
 };
+export type EntitlementCode = "analyze" | "recommend" | "generate" | "execute";
+export declare const NOT_GATED = "not gated";
+export type ToolEntry = {
+    phase?: PhaseMapping;
+    entitlement: EntitlementCode | typeof NOT_GATED;
+};
+export declare const TOOLS: Readonly<Record<string, ToolEntry>>;
 export declare const TOOL_PHASE_MAP: Record<string, PhaseMapping>;
 /** Tools whose phase depends on context — listed here for consumer discovery. */
 export declare const CONTEXT_DEPENDENT_TOOLS: Set<string>;
 /** All tools that belong to the "generating" phase — used as the boundary. */
 export declare const GENERATING_TOOLS: Set<string>;
-/** Tools that intentionally have no progress phase (infrastructure/utility). */
-export declare const TOOLS_WITHOUT_PHASE: Set<string>;