@visulima/vis 1.0.0-alpha.1 → 1.0.0-alpha.11

package/schemas/vis-config.schema.json

@@ -0,0 +1,501 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://visulima.com/schemas/vis-config.schema.json",
+    "title": "vis.config.ts",
+    "description": "Workspace configuration for @visulima/vis. Used by defineConfig() in vis.config.ts. This schema is for non-TypeScript editors; TypeScript users get autocomplete from defineConfig() types.",
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+        "ai": {
+            "type": "object",
+            "description": "AI analysis configuration.",
+            "additionalProperties": false,
+            "properties": {
+                "cacheTtl": { "type": "number", "description": "Cache TTL in milliseconds." },
+                "priority": {
+                    "type": "object",
+                    "description": "Override default provider priority. Higher number = preferred.",
+                    "additionalProperties": { "type": "number" }
+                },
+                "provider": { "type": "string", "description": "Use a specific provider (e.g. \"claude\", \"gemini\")." }
+            }
+        },
+        "codeowners": {
+            "type": "object",
+            "description": "Controls vis sync codeowners output.",
+            "additionalProperties": false,
+            "properties": {
+                "orderBy": {
+                    "type": "string",
+                    "enum": ["file-source", "project-id"],
+                    "default": "file-source"
+                },
+                "provider": {
+                    "type": "string",
+                    "enum": ["github", "gitlab", "bitbucket", "other"],
+                    "default": "github"
+                },
+                "globalPaths": {
+                    "type": "object",
+                    "description": "Workspace-level paths and their owners (e.g. \"/.github/**\": [\"@org/platform\"]).",
+                    "additionalProperties": {
+                        "type": "array",
+                        "items": { "type": "string" }
+                    }
+                }
+            }
+        },
+        "constraints": {
+            "type": "object",
+            "description": "Project dependency constraints enforced before running tasks.",
+            "additionalProperties": false,
+            "properties": {
+                "enforceLayerRelationships": {
+                    "type": "boolean",
+                    "description": "Projects can only depend on the same or lower layer: configuration < library < scaffolding < tool < automation < application.",
+                    "default": false
+                },
+                "tagRelationships": {
+                    "type": "object",
+                    "description": "Tag-based rules. Key = source tag, value = allowed dependency tags.",
+                    "additionalProperties": {
+                        "type": "array",
+                        "items": { "type": "string" }
+                    }
+                },
+                "typeBoundaries": {
+                    "type": "object",
+                    "additionalProperties": false,
+                    "properties": {
+                        "enforceApplicationBoundary": {
+                            "type": "boolean",
+                            "description": "No project may depend on an application.",
+                            "default": true
+                        },
+                        "allowedDependencyTypes": {
+                            "type": "object",
+                            "description": "Maps project types to allowed dependency types.",
+                            "additionalProperties": {
+                                "type": "array",
+                                "items": { "type": "string" }
+                            }
+                        }
+                    }
+                },
+                "dependencyKindRules": {
+                    "type": "object",
+                    "additionalProperties": false,
+                    "properties": {
+                        "noDevDependencyOnProductionDep": { "type": "boolean", "default": false },
+                        "noProductionDependencyOnApplication": { "type": "boolean", "default": false }
+                    }
+                }
+            }
+        },
+        "install": {
+            "type": "object",
+            "description": "Installer backend selection. Lets `vis install` (and friends) use aube — a fast Rust-native PM that reads/writes pnpm/npm/yarn/bun lockfiles in place — or pin a specific conventional PM. Aube must be installed separately; vis does not bundle it.",
+            "additionalProperties": false,
+            "properties": {
+                "backend": {
+                    "type": "string",
+                    "enum": ["auto", "aube", "pnpm", "npm", "yarn", "bun"],
+                    "default": "auto",
+                    "description": "Which PM runs install/add/remove. `auto` uses aube when it is on PATH and falls back to the lockfile-detected PM. Explicit names error if the binary is missing. CLI flag `--installer` and env var `VIS_INSTALLER` override this."
+                }
+            }
+        },
+        "inferTargets": {
+            "default": false,
+            "oneOf": [
+                { "type": "boolean" },
+                {
+                    "type": "object",
+                    "description": "Per-detector opt-out map. Keys must be one of the 36 built-in detector names; set a key to `false` to disable that detector. Detectors omitted from the object stay enabled. Unknown keys log a warning at config-load time.",
+                    "additionalProperties": { "type": "boolean" },
+                    "propertyNames": {
+                        "enum": [
+                            "nuxt",
+                            "next",
+                            "remix",
+                            "astro",
+                            "gatsby",
+                            "docusaurus",
+                            "vite",
+                            "vitepress",
+                            "nest",
+                            "rolldown",
+                            "tsdown",
+                            "tsup",
+                            "packem",
+                            "rollup",
+                            "webpack",
+                            "vitest",
+                            "jest",
+                            "bun",
+                            "playwright",
+                            "cypress",
+                            "storybook",
+                            "typescript",
+                            "typedoc",
+                            "eslint",
+                            "prettier",
+                            "biome",
+                            "oxlint",
+                            "oxfmt",
+                            "stylelint",
+                            "knip",
+                            "deno",
+                            "prisma",
+                            "drizzle",
+                            "graphql-codegen",
+                            "api-extractor",
+                            "changeset"
+                        ]
+                    }
+                }
+            ],
+            "description": "Project Crystal-style inference. Synthesizes default targets (`build`, `test`, `dev`, `lint`, `format`, `typecheck`, `docs`, `db:*`, …) for each project by sniffing config files and `package.json` dependencies. Ships with 36 detectors covering app frameworks (nuxt, next, remix, astro, gatsby, docusaurus), bundlers (vite, rolldown, tsdown, tsup, packem, rollup, webpack), test runners (vitest, jest, bun, deno, playwright, cypress), lint/format tools (eslint, prettier, biome, oxlint, oxfmt, stylelint, knip), docs (typedoc, vitepress), DB tooling (prisma, drizzle), and release plumbing (graphql-codegen, api-extractor, changeset). Inferred targets are the lowest-priority layer — package.json scripts, project.json, and vis.task.ts always win on a per-target-name basis. Boolean `true` enables every detector; the object form opts individual detectors in or out by name. See `vis list --inferred` to inspect what each project resolves to."
+        },
+        "create": {
+            "type": "object",
+            "description": "Configuration for vis create scaffolding command.",
+            "additionalProperties": false,
+            "properties": {
+                "auth": { "type": "string", "description": "Authorization token for private templates." },
+                "defaultEditor": { "type": "string", "enum": ["vscode"] },
+                "defaultPm": { "type": "string", "enum": ["pnpm", "npm", "yarn", "bun"] },
+                "defaultProvider": { "type": "string", "enum": ["github", "gitlab", "bitbucket", "sourcehut"], "default": "github" },
+                "gitInit": { "type": "boolean", "default": false },
+                "install": { "type": "boolean", "default": true },
+                "preferOffline": { "type": "boolean", "default": false },
+                "registry": {
+                    "oneOf": [{ "type": "string" }, { "type": "boolean", "const": false }]
+                },
+                "templates": {
+                    "type": "object",
+                    "description": "Named template aliases mapping short names to giget source strings.",
+                    "additionalProperties": { "type": "string" }
+                }
+            }
+        },
+        "overrides": {
+            "type": "object",
+            "description": "Package override mappings applied during migration.",
+            "additionalProperties": { "type": "string" }
+        },
+        "preflight": {
+            "type": "object",
+            "description": "Preflight checks gating `vis run` / `vis ci`. Each check can be opted out individually; the CLI flag `--no-preflight` disables them all.",
+            "additionalProperties": false,
+            "properties": {
+                "lockfile": {
+                    "type": "boolean",
+                    "default": true,
+                    "description": "Detect lockfile drift by comparing the lockfile mtime against the package manager's install marker (e.g. `node_modules/.modules.yaml` for pnpm). When the lockfile is newer than the marker, the run fails with the right reinstall command for CI vs TTY."
+                }
+            }
+        },
+        "security": {
+            "type": "object",
+            "description": "Supply-chain security settings.",
+            "additionalProperties": false,
+            "properties": {
+                "allowBuilds": {
+                    "type": "object",
+                    "description": "Allow (true) or deny (false) build scripts per package.",
+                    "additionalProperties": { "type": "boolean" }
+                },
+                "blockExoticSubdeps": { "type": "boolean", "default": false },
+                "minimumReleaseAge": { "type": "number", "description": "Minutes since publish before allowing install.", "default": 0 },
+                "minimumReleaseAgeExclude": { "type": "array", "items": { "type": "string" } },
+                "socket": {
+                    "type": "object",
+                    "additionalProperties": false,
+                    "properties": {
+                        "acceptedRisks": {
+                            "type": "object",
+                            "additionalProperties": {
+                                "type": "object",
+                                "required": ["reason", "acceptedAt", "acceptedScore"],
+                                "properties": {
+                                    "reason": { "type": "string" },
+                                    "acceptedAt": { "type": "string", "format": "date-time" },
+                                    "acceptedScore": { "type": "number" }
+                                }
+                            }
+                        },
+                        "apiToken": { "type": "string" },
+                        "cacheTtlMs": { "type": "number", "default": 3600000 },
+                        "enabled": { "type": "boolean", "default": false },
+                        "minimumScore": { "type": "number", "default": 0.4 },
+                        "timeoutMs": { "type": "number", "default": 15000 }
+                    }
+                },
+                "strictDepBuilds": { "type": "boolean", "default": false },
+                "trustPolicy": { "type": "string", "enum": ["off", "no-downgrade"], "default": "off" },
+                "trustPolicyExclude": { "type": "array", "items": { "type": "string" } },
+                "trustPolicyIgnoreAfter": { "type": "number" },
+                "typosquatAllowlist": { "type": "array", "items": { "type": "string" } }
+            }
+        },
+        "sortPackageJson": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+                "sortScripts": { "type": "boolean", "default": false }
+            }
+        },
+        "toolchain": {
+            "type": "object",
+            "description": "Toolchain (Node / pnpm / python / ...) management. Delegates to proto / mise / fnm / volta / asdf / nvm / corepack.",
+            "additionalProperties": false,
+            "properties": {
+                "autoInstall": {
+                    "type": "boolean",
+                    "description": "Run the right manager install on engines.node mismatch before vis run / vis ci proceed. Default: true when a manager is detected on PATH."
+                },
+                "preferredManager": {
+                    "type": "string",
+                    "enum": ["proto", "mise", "fnm", "volta", "asdf", "nvm", "corepack", "none"],
+                    "description": "Explicit manager override, bypasses auto-detection. Note: self-activate is resolved automatically for pnpm/yarn + packageManager pins and is not a valid override."
+                },
+                "tools": {
+                    "type": "object",
+                    "description": "Override engines/packageManager-derived pins.",
+                    "additionalProperties": false,
+                    "properties": {
+                        "bun": { "type": "string" },
+                        "deno": { "type": "string" },
+                        "go": { "type": "string" },
+                        "node": { "type": "string" },
+                        "npm": { "type": "string" },
+                        "pnpm": { "type": "string" },
+                        "python": { "type": "string" },
+                        "ruby": { "type": "string" },
+                        "rust": { "type": "string" },
+                        "yarn": { "type": "string" }
+                    }
+                }
+            }
+        },
+        "staged": {
+            "description": "Staged file patterns and commands (replaces lint-staged). Accepts string, string[], {title, task}, or mixed arrays. Function-form tasks are supported at runtime but are not JSON-schema-representable.",
+            "type": "object",
+            "additionalProperties": {
+                "oneOf": [
+                    { "type": "string" },
+                    { "type": "array", "items": { "oneOf": [{ "type": "string" }, { "type": "object" }] } },
+                    {
+                        "type": "object",
+                        "required": ["title"],
+                        "properties": {
+                            "title": { "type": "string" }
+                        }
+                    }
+                ]
+            }
+        },
+        "targetDefaults": {
+            "type": "object",
+            "description": "Default target configurations applied to all projects with a matching target.",
+            "additionalProperties": { "$ref": "project.schema.json#/$defs/targetConfiguration" }
+        },
+        "fileGroups": {
+            "type": "object",
+            "description": "Named file-group patterns, reusable via @filegroup:<name> in target inputs. Strings may be bare globs or URI form (file://, glob://, env://, func://, dep://).",
+            "additionalProperties": {
+                "type": "array",
+                "items": { "$ref": "project.schema.json#/$defs/inputString" }
+            }
+        },
+        "namedInputs": {
+            "type": "object",
+            "description": "Named input patterns inherited by every project target.",
+            "additionalProperties": {
+                "type": "array",
+                "items": {
+                    "oneOf": [
+                        { "$ref": "project.schema.json#/$defs/inputString" },
+                        { "$ref": "project.schema.json#/$defs/fileSetInput" },
+                        { "$ref": "project.schema.json#/$defs/environmentInput" },
+                        { "$ref": "project.schema.json#/$defs/runtimeInput" },
+                        { "$ref": "project.schema.json#/$defs/externalDependencyInput" }
+                    ]
+                }
+            }
+        },
+        "taskDefaults": {
+            "type": "array",
+            "description": "Cascading task-default blocks scoped by project metadata.",
+            "items": {
+                "type": "object",
+                "required": ["targets"],
+                "additionalProperties": false,
+                "properties": {
+                    "scope": {
+                        "type": "object",
+                        "description": "Scope predicate — all fields must match for the block to apply.",
+                        "additionalProperties": false,
+                        "properties": {
+                            "tags": { "type": "array", "items": { "type": "string" } },
+                            "projectType": { "type": "string", "enum": ["library", "application"] },
+                            "layer": {
+                                "oneOf": [
+                                    { "type": "string", "enum": ["configuration", "library", "scaffolding", "tool", "automation", "application"] },
+                                    {
+                                        "type": "array",
+                                        "items": { "type": "string", "enum": ["configuration", "library", "scaffolding", "tool", "automation", "application"] }
+                                    }
+                                ]
+                            },
+                            "stack": {
+                                "oneOf": [
+                                    { "type": "string", "enum": ["backend", "frontend", "data", "infrastructure", "systems"] },
+                                    { "type": "array", "items": { "type": "string", "enum": ["backend", "frontend", "data", "infrastructure", "systems"] } }
+                                ]
+                            },
+                            "language": {
+                                "oneOf": [{ "type": "string" }, { "type": "array", "items": { "type": "string" } }]
+                            }
+                        }
+                    },
+                    "targets": {
+                        "type": "object",
+                        "additionalProperties": { "$ref": "project.schema.json#/$defs/targetConfiguration" }
+                    }
+                }
+            }
+        },
+        "taskRunnerOptions": {
+            "type": "object",
+            "description": "Task runner engine options.",
+            "additionalProperties": false,
+            "properties": {
+                "parallel": { "oneOf": [{ "type": "number" }, { "type": "boolean" }], "default": 3 },
+                "smartLockfileHashing": { "type": "boolean", "default": false },
+                "frameworkInference": { "type": "boolean", "default": false },
+                "autoFingerprint": { "type": "boolean", "default": false },
+                "cacheDiagnostics": { "type": "boolean", "default": false },
+                "cacheDirectory": { "type": "string" },
+                "dryRun": { "type": "boolean", "default": false },
+                "summarize": { "type": "boolean", "default": false },
+                "skipNxCache": { "type": "boolean" },
+                "globalInputs": { "type": "array", "items": { "type": "string" } },
+                "globalEnv": { "type": "array", "items": { "type": "string" } },
+                "maxCacheAge": { "type": "number" },
+                "maxCacheSize": { "type": "string" },
+                "remoteCache": {
+                    "type": "object",
+                    "required": ["url"],
+                    "additionalProperties": false,
+                    "properties": {
+                        "url": {
+                            "type": "string",
+                            "description": "Cache server URL. HTTP: 'https://cache.example.com'. REAPI: 'grpcs://host:port' (TLS) or 'grpc://host:port' (cleartext)."
+                        },
+                        "backend": {
+                            "type": "string",
+                            "enum": ["http", "reapi"],
+                            "default": "http",
+                            "description": "Wire-protocol selector. 'http' is Turborepo-compatible; 'reapi' speaks the Bazel Remote Execution API over gRPC (bazel-remote, BuildBuddy, BuildBarn, EngFlow)."
+                        },
+                        "mode": {
+                            "type": "string",
+                            "enum": ["read", "readwrite", "write"],
+                            "default": "readwrite",
+                            "description": "Cache mode. 'read' pulls only, 'write' pushes only, 'readwrite' does both."
+                        },
+                        "token": {
+                            "type": "string",
+                            "description": "HTTP backend bearer token sent as 'Authorization: Bearer …'. For REAPI, use 'bearerToken' instead."
+                        },
+                        "teamId": { "type": "string", "description": "Team / namespace for cache isolation." },
+                        "timeout": { "type": "number", "default": 30000, "description": "Per-call request timeout in milliseconds." },
+                        "compression": {
+                            "type": "string",
+                            "enum": ["gzip", "brotli"],
+                            "default": "gzip",
+                            "description": "HTTP-only: tarball compression on the wire."
+                        },
+                        "signing": {
+                            "type": "object",
+                            "additionalProperties": false,
+                            "required": ["secret"],
+                            "description": "HTTP-only HMAC-SHA256 signing for upload integrity.",
+                            "properties": {
+                                "secret": { "type": "string", "minLength": 16, "description": "Shared secret. Must be at least 16 characters." },
+                                "verifyOnDownload": { "type": "boolean", "default": false, "description": "Reject downloads whose signature doesn't match." }
+                            }
+                        },
+                        "localCasRoot": {
+                            "type": "string",
+                            "description": "Local CAS root used by per-blob backend methods. The HTTP bridge extracts retrieved tarballs into this root so follow-up fetchBlob calls hit local disk."
+                        },
+                        "bearerToken": {
+                            "type": "string",
+                            "description": "REAPI-only: bearer token sent in gRPC 'authorization: Bearer …' metadata."
+                        },
+                        "instanceName": {
+                            "type": "string",
+                            "description": "REAPI-only: 'instance_name' for multi-tenant servers (single gRPC endpoint hosting multiple logical caches)."
+                        },
+                        "allowInsecureBearer": {
+                            "type": "boolean",
+                            "default": false,
+                            "description": "REAPI-only: opt out of the safety check that refuses bearer tokens over cleartext gRPC. Only set when the connection terminates inside a trusted boundary (loopback, mTLS sidecar)."
+                        },
+                        "read": {
+                            "type": "boolean",
+                            "deprecated": true,
+                            "description": "Deprecated. Use 'mode' instead. Setting both still works but emits a one-time warning."
+                        },
+                        "write": {
+                            "type": "boolean",
+                            "deprecated": true,
+                            "description": "Deprecated. Use 'mode' instead. Setting both still works but emits a one-time warning."
+                        }
+                    }
+                }
+            }
+        },
+        "tui": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+                "autoExit": {
+                    "oneOf": [{ "type": "boolean" }, { "type": "number" }],
+                    "description": "Auto-exit TUI after completion. false=stay open, true=3s countdown, number=custom seconds.",
+                    "default": false
+                }
+            }
+        },
+        "update": {
+            "type": "object",
+            "description": "Defaults for vis check and vis update commands.",
+            "additionalProperties": false,
+            "properties": {
+                "depFields": { "type": "array", "items": { "type": "string" } },
+                "exclude": { "type": "array", "items": { "type": "string" } },
+                "format": { "type": "string", "enum": ["table", "json", "minimal"] },
+                "ignore": { "type": "array", "items": { "type": "string" } },
+                "include": { "type": "array", "items": { "type": "string" } },
+                "includeLocked": { "type": "boolean", "default": false },
+                "install": { "type": "boolean" },
+                "minimumReleaseAge": { "type": "number" },
+                "minimumReleaseAgeExclude": { "type": "array", "items": { "type": "string" } },
+                "packageMode": {
+                    "type": "object",
+                    "additionalProperties": { "type": "string", "enum": ["latest", "minor", "patch"] }
+                },
+                "prerelease": { "type": "boolean" },
+                "security": { "type": "boolean" },
+                "target": { "type": "string", "enum": ["latest", "minor", "patch"] }
+            }
+        },
+        "versionConstraint": {
+            "type": "string",
+            "description": "Minimum vis CLI version required. Accepts semver ranges (e.g. \">=1.0.0\", \"^1.2.0\")."
+        }
+    }
+}

package/skills/vis/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: vis
+description: Use when the workspace contains a vis.config.ts (or vis.config.js/json) at the repo root, or when the user mentions "vis", "task-runner", or "@visulima/vis". This skill orchestrates the vis MCP server's eight read-only tools to inspect projects, plan task graphs, and diagnose remote-cache rotations.
+---
+
+# Working with the `vis` task runner
+
+`vis` is the Visulima monorepo task runner — a Turborepo/Nx-class tool with a remote cache, REAPI gRPC backend, and project graph. When this skill is active you have the **`@visulima/vis-mcp` server** mounted, exposing eight read-only tools. Use them in preference to running `vis` shell commands yourself: the tools give you structured JSON and run faster.
+
+The MCP server deliberately does NOT execute targets or scaffold templates — Nx-style "agent prepares, human executes". When the user wants to run `<project>:<target>` or `vis generate <template>`, prepare the command (use `list_targets`/`describe_template` to confirm it exists and capture required arguments) and ask the user to run it themselves; afterwards use `get_run_logs` to read the result of any task run.
+
+## Tools available
+
+| Tool                | Purpose                                                                                                                           |
+| ------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
+| `list_projects`     | All projects in the workspace, optionally filtered by a vis query (`tag=frontend`, `type=application`, …)                         |
+| `describe_project`  | Full metadata for one project: language, layer, tags, root path, all targets                                                      |
+| `list_targets`      | Per-target rows across the workspace, optionally narrowed to a single project                                                     |
+| `list_templates`    | Scaffolding templates discovered in `.vis/templates/`, `.moon/templates/`, and `vis.config.ts` `generator.templates`              |
+| `describe_template` | Variable schema, default destination, and description for a single template — required before suggesting a `vis generate` command |
+| `get_run_logs`      | Most recent run summary from `.task-runner/`, or a specific `runId`, optionally filtered to one task                              |
+| `cache_why`         | Diff a task's cache hash against the previous run — pinpoints what changed (command, nodes, runtime, implicit deps)               |
+| `cache_hash`        | Recorded hash and per-input hash details for a task                                                                               |
+
+## Workflow patterns
+
+### Discovery — "what's in this repo?"
+
+Default opening move when the user asks about the workspace:
+
+1. `list_projects` (no filter). Shows everything with categories and target counts.
+2. If they ask about a specific package, `describe_project` for the full picture rather than re-running list with a filter.
+
+### Plan a build
+
+1. `list_targets` (optionally with `project: "@scope/name"`) to see what `build`/`test`/`lint`/etc. targets exist.
+2. Tell the user the exact command (`vis run @scope/name:build`) and let them run it.
+3. Use `get_run_logs` afterwards to inspect status, cache hits, and stderr tails.
+
+### Investigate a cache miss
+
+When a build that should have been cached re-ran:
+
+1. `get_run_logs` (no args → latest summary) — surfaces all task statuses for the last run.
+2. For any task with status `success` but `cacheStatus: "miss"`, call `cache_why` with that `taskId`. It diffs hashDetails against the previous run and tells you which input rotated (command string, file content, `implicitDependency`, runtime version, …).
+3. If `cache_why` shows the change but the user wants to see the raw hash inputs, `cache_hash` returns the full per-input breakdown.
+
+### Scaffold a new package or component
+
+When the user asks for "a new X" / "scaffold Y":
+
+1. `list_templates` — pick the template whose `name` or `description` matches the user's request.
+2. `describe_template` with that name — read the `variables[]` schema. Identify which variables are `required` and which have sensible `default` values.
+3. Construct the command: `vis generate <name> -- --var1=value1 --var2=value2`. For interactive prompts, drop the `--` overrides and let the user step through. For `--defaults`-friendly templates, add `--defaults` to skip prompts.
+4. Hand the command to the user to execute. Don't fabricate variable values — if the user hasn't told you what to pass for a required variable, ask.
+
+#### Worked example
+
+User: _"Scaffold a new React button component called PrimaryButton."_
+
+1. Call `list_templates` → response contains an entry `{ "name": "component", "source": "native", "description": "Scaffold a React component" }`. That's the closest match.
+2. Call `describe_template` with `{ "name": "component" }` → response shows `variables`:
+    ```json
+    [
+        { "name": "name", "type": "string", "required": true, "prompt": "Component name?" },
+        { "name": "withTest", "type": "boolean", "required": false, "default": true },
+        { "name": "style", "type": "enum", "required": false, "default": "primary", "values": ["primary", "secondary"] }
+    ]
+    ```
+3. The user supplied `name` (`PrimaryButton`) and implied `style=primary` (default already matches). `withTest` is unspecified — the default is fine, no need to override.
+4. Suggested command for the user to run:
+    ```sh
+    vis generate component -- --name=PrimaryButton --style=primary
+    ```
+    Do **not** invent values for required variables the user never mentioned — ask first.
+
+### Diagnose a failed run
+
+1. `get_run_logs` to see which task(s) failed.
+2. `get_run_logs` with `taskId` set to the failing task — returns just that entry, including the captured stderr tail.
+3. Decide: is it a code bug (read the project's source), a cache poisoning issue (`cache_why`), or environmental (look at the run summary's `runtime` block)?
+
+## Safety rules
+
+- **All tools are read-only.** The server does not execute targets. If the user wants something built/tested/linted, give them the command and let them run it.
+- **All tools run in the directory where `vis-mcp` was launched.** Override at server startup by setting `VIS_MCP_WORKSPACE_ROOT`. You can read that path from the server's stderr boot line: `[vis-mcp] ready (workspace: …)`.
+
+## When NOT to use this skill
+
+- The user wants to write a `vis.config.ts` — that's editing source, not running the CLI. Use Read/Edit/Write on the config file directly.
+- The user is asking about Turborepo, Nx, or Bazel specifically (not vis). The tools won't help with those.
+- The repo has no `vis.config.*` and no mention of vis. Don't volunteer the tools.
+
+## Tool-result conventions
+
+All tools return JSON-encoded text in the standard MCP `content[].text` slot. On error, `isError: true` is set and the text payload is `{"error": "<message>"}`. Parse the JSON before reasoning about it — the text field is structured data, not prose.