@shoalrun/cli 0.0.0-stage → 0.1.0-alpha.12

package/agent-docs/publish/mcp.sections/generate-a-vercel-endpoint.md

@@ -0,0 +1,50 @@
+---
+id: guide.mcp
+title: Connect an MCP client
+summary: Connect read-only MCP clients over stdio or HTTP to search and read
+  built documentation.
+type: how-to
+area: discovery
+subarea: discovery-mcp
+canonical: /publish/mcp
+---
+
+# Connect an MCP client
+
+> Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
+
+Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigation/docs-50f26fe22670.txt) (ID: docs). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Search, chat, and agent access > MCP > Connect an MCP client
+
+**Updated: 2026-10-27.**
+
+Parent page: [Full Markdown page](/publish/mcp.md)
+
+**Page reading path** — these links apply to the full page.
+
+**Next steps**
+
+- [Measure MCP tool usage](https://www.shoalrun.com/publish/mcp-analytics.md) — Optionally measure tool calls through a server adapter.
+
+Connect an MCP client to built documentation through four read-only tools. Use stdio for a client-launched local process, or enable an HTTP endpoint on Node or in a generated Vercel function. Both use the same search and Markdown reading core.
+
+The HTTP endpoint currently supports one explicitly selected public publication. The generated Vercel endpoint is deployed and verified on this site. Netlify and Cloudflare adapters are not implemented. Analytics is off by default; an optional [server adapter](https://www.shoalrun.com/publish/mcp-analytics.md) can measure tool calls.
+
+You need Node.js 22.12 or newer, the installed Shoalrun CLI, and a client that supports MCP stdio or Streamable HTTP. Follow [Getting started](https://www.shoalrun.com/start.md) to install the public npm package.
+
+## Generate a Vercel endpoint
+
+With the public MCP configuration above, generate deployment output from your project:
+
+```sh
+shoalrun vercel build docs.config.yaml .vercel/output
+```
+
+No extra MCP flag, Ask configuration, embeddings, or model key is required. The command packages the four tools and their selected public documentation in a Node function at the configured endpoint. Internal runtime files stay out of the public static output. Follow [Publish on Vercel](https://www.shoalrun.com/publish/vercel.md) to deploy the complete output directory.
+
+The function trusts `site.origin`, explicit allowed hosts, and Vercel’s reserved deployment host variables. It does not trust arbitrary forwarded hosts or other projects’ preview domains. Deployment protection may block an MCP client from reaching a preview; check that host setting if a client cannot connect.
+
+Returned Markdown links use the URLs generated at build time. Set the intended origin before building; request headers do not rewrite the documentation identity. Per-instance limits are not global deployment limits. Configure host-level traffic controls before opening a public endpoint.
+
+Local package tests cover SDK clients and the generated function. Read-only SDK calls have also been verified at this site’s production Vercel endpoint. Named desktop-client checks remain separate.

package/agent-docs/publish/mcp.sections/related-reading.md

@@ -0,0 +1,42 @@
+---
+id: guide.mcp
+title: Connect an MCP client
+summary: Connect read-only MCP clients over stdio or HTTP to search and read
+  built documentation.
+type: how-to
+area: discovery
+subarea: discovery-mcp
+canonical: /publish/mcp
+---
+
+# Connect an MCP client
+
+> Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
+
+Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigation/docs-50f26fe22670.txt) (ID: docs). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Search, chat, and agent access > MCP > Connect an MCP client
+
+**Updated: 2026-10-27.**
+
+Parent page: [Full Markdown page](/publish/mcp.md)
+
+Connect an MCP client to built documentation through four read-only tools. Use stdio for a client-launched local process, or enable an HTTP endpoint on Node or in a generated Vercel function. Both use the same search and Markdown reading core.
+
+The HTTP endpoint currently supports one explicitly selected public publication. The generated Vercel endpoint is deployed and verified on this site. Netlify and Cloudflare adapters are not implemented. Analytics is off by default; an optional [server adapter](https://www.shoalrun.com/publish/mcp-analytics.md) can measure tool calls.
+
+You need Node.js 22.12 or newer, the installed Shoalrun CLI, and a client that supports MCP stdio or Streamable HTTP. Follow [Getting started](https://www.shoalrun.com/start.md) to install the public npm package.
+
+## Related reading
+
+### Next steps
+
+- [Measure MCP tool usage](https://www.shoalrun.com/publish/mcp-analytics.md) — Optionally measure tool calls through a server adapter.
+
+### Reference while working
+
+- [CLI reference](https://www.shoalrun.com/cli.md) — Look up shared search and read flags and error behavior.
+
+### Related topics
+
+- [Agent-friendly documentation](https://www.shoalrun.com/publish/agent-friendliness.md) — Understand the published Markdown and discovery surfaces alongside MCP.

package/agent-docs/publish/mcp.sections/search-then-read.md

@@ -0,0 +1,53 @@
+---
+id: guide.mcp
+title: Connect an MCP client
+summary: Connect read-only MCP clients over stdio or HTTP to search and read
+  built documentation.
+type: how-to
+area: discovery
+subarea: discovery-mcp
+canonical: /publish/mcp
+---
+
+# Connect an MCP client
+
+> Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
+
+Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigation/docs-50f26fe22670.txt) (ID: docs). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Search, chat, and agent access > MCP > Connect an MCP client
+
+**Updated: 2026-10-27.**
+
+Parent page: [Full Markdown page](/publish/mcp.md)
+
+**Page reading path** — these links apply to the full page.
+
+**Next steps**
+
+- [Measure MCP tool usage](https://www.shoalrun.com/publish/mcp-analytics.md) — Optionally measure tool calls through a server adapter.
+
+Connect an MCP client to built documentation through four read-only tools. Use stdio for a client-launched local process, or enable an HTTP endpoint on Node or in a generated Vercel function. Both use the same search and Markdown reading core.
+
+The HTTP endpoint currently supports one explicitly selected public publication. The generated Vercel endpoint is deployed and verified on this site. Netlify and Cloudflare adapters are not implemented. Analytics is off by default; an optional [server adapter](https://www.shoalrun.com/publish/mcp-analytics.md) can measure tool calls.
+
+You need Node.js 22.12 or newer, the installed Shoalrun CLI, and a client that supports MCP stdio or Streamable HTTP. Follow [Getting started](https://www.shoalrun.com/start.md) to install the public npm package.
+
+## Search, then read
+
+Ask the client to discover the server's tools. It should find:
+
+| Tool          | Required input  | Optional inputs                                        | Result                                                              |
+| ------------- | --------------- | ------------------------------------------------------ | ------------------------------------------------------------------- |
+| `search_docs` | `query`         | `limit`, `maxTokens`, `channel`, `version`, `language` | Ranked document IDs, links, summaries, and excerpts.                |
+| `get_page`    | `id`            | `maxTokens`, `channel`, `version`, `language`          | The page's generated Markdown and publication metadata.             |
+| `get_outline` | `id`            | `maxTokens`, `channel`, `version`, `language`          | Top-level section IDs, fetch URLs, digests, and sizes.              |
+| `get_section` | `id`, `section` | `maxTokens`, `channel`, `version`, `language`          | One complete section with parent context and nested reader content. |
+
+For example, call `search_docs` with `{"query":"search provider","limit":5,"maxTokens":2048}`, choose a result, and call its `read.tool` with its `read.arguments` exactly. Choose a publication when the index or document ID spans multiple channels, versions, or languages. The server refuses to mix publications.
+
+Search uses the same lexical ranking as the CLI. Titles, summaries, and headings are searchable; article text is bounded. See [search index coverage](https://www.shoalrun.com/author/search.md). The page tool returns generated Markdown, including all reader-marked sections. Reader views remain visibility controls, not access controls.
+
+Search supplies the next call: `read.tool` is `get_section` for a unique matching section, or `get_page` otherwise. Its arguments include the ID, publication, section ID when needed, and a token budget based on the indexed size. Do not guess section IDs or call `get_outline` first. Check `budget.truncated` after a page read and increase the budget if needed.
+
+The result's `markdownUrl` fetches the recommended content directly; `pageMarkdownUrl` always fetches the full page. Use the full page when the section does not answer the question or needs more context. Search prefers the full page for short documents, broad queries, ambiguous headings, or queries spanning multiple sections. Search normally prefers complete lexical matches. With no complete match, results within one meaningful term of the best coverage (at least two matched terms) rank by non-filler field score first. A stronger result missing one meaningful term can outrank complete matches found only in body text; `matchMode: mixed` identifies that case. See [search ranking](https://www.shoalrun.com/author/search.md). A section recommendation also requires an explicit author declaration that its content and repeated introduction are self-contained. Undeclared sections use full-page reads, including indexes built before this declaration existed. The compiler checks heading identity, not prerequisite completeness. `get_outline` remains available for deliberate browsing. Retain publication coordinates and parent/section digests for citations. See [section resources](https://www.shoalrun.com/author/markdown-metadata.md).

package/agent-docs/publish/mcp.sections/serve-a-public-endpoint-on-node.md

@@ -0,0 +1,79 @@
+---
+id: guide.mcp
+title: Connect an MCP client
+summary: Connect read-only MCP clients over stdio or HTTP to search and read
+  built documentation.
+type: how-to
+area: discovery
+subarea: discovery-mcp
+canonical: /publish/mcp
+---
+
+# Connect an MCP client
+
+> Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
+
+Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigation/docs-50f26fe22670.txt) (ID: docs). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Search, chat, and agent access > MCP > Connect an MCP client
+
+**Updated: 2026-10-27.**
+
+Parent page: [Full Markdown page](/publish/mcp.md)
+
+**Page reading path** — these links apply to the full page.
+
+**Next steps**
+
+- [Measure MCP tool usage](https://www.shoalrun.com/publish/mcp-analytics.md) — Optionally measure tool calls through a server adapter.
+
+Connect an MCP client to built documentation through four read-only tools. Use stdio for a client-launched local process, or enable an HTTP endpoint on Node or in a generated Vercel function. Both use the same search and Markdown reading core.
+
+The HTTP endpoint currently supports one explicitly selected public publication. The generated Vercel endpoint is deployed and verified on this site. Netlify and Cloudflare adapters are not implemented. Analytics is off by default; an optional [server adapter](https://www.shoalrun.com/publish/mcp-analytics.md) can measure tool calls.
+
+You need Node.js 22.12 or newer, the installed Shoalrun CLI, and a client that supports MCP stdio or Streamable HTTP. Follow [Getting started](https://www.shoalrun.com/start.md) to install the public npm package.
+
+## Serve a public endpoint on Node
+
+Use this procedure when agents should connect to a URL instead of launching the CLI themselves. Analytics is not enabled by this setting.
+
+1. ### Enable a public publication
+
+   Add the endpoint and the exact channel, version, and language to your project config. The selected publication must contain public pages:
+
+   ```yaml title="docs.config.yaml"
+   mcp:
+     enabled: true
+     access: public
+     path: /mcp
+     publication: { channel: production, version: current, language: en }
+   ```
+
+   The endpoint supplies those publication coordinates when the client omits them. Requests for a different publication are rejected. Its lexical search index is generated even if browser search is disabled.
+
+2. ### Build and serve the site
+
+   With the CLI available as `shoalrun`, build the output and start the Node server:
+
+   ```sh
+   shoalrun build docs.config.yaml dist
+   shoalrun serve dist --port 8774
+   ```
+
+   The server reads the MCP settings from that build. It does not need the source config. With no site base path, the local endpoint is `http://127.0.0.1:8774/mcp`; a base path such as `/docs` makes it `/docs/mcp`.
+
+   Set `mcp: false` or remove the setting and rebuild to disable the endpoint. Restart a non-watching server after replacing its build; watched preview reloads settings with each successful build.
+
+3. ### Connect and check the tools
+
+   Add the endpoint URL in your client’s remote MCP settings. The client should discover the four tools listed below. Search for a known page, then follow the returned read instruction and verify its publication.
+
+   The SDK integration is tested with legacy and automatic protocol negotiation using MCP TypeScript client version `2.2.0`. Compatibility with a specific desktop client or public host still needs its own check.
+
+### Hosts, origins, and limits
+
+Local connections permit the configured loopback host. For a public Node deployment, `site.origin` supplies a trusted hostname and browser origin. Add explicit `mcp.allowedHosts` hostnames for other domains and `mcp.allowedOrigins` origins for browser-based clients. Forwarded host headers are not trusted. Native clients do not need an Origin header.
+
+The endpoint accepts JSON MCP requests through POST; it does not provide a persistent session or standalone event stream. GET and DELETE return 405. Browser preflight uses OPTIONS.
+
+Limits are 64 KiB per request, eight concurrent requests per handler, and a 15-second deadline. Excess concurrent requests return 429 with retry guidance. Tool token budgets still apply. These are process-local controls; configure deployment-level limits before exposing a public service. This is a public endpoint, not an authentication mechanism for private documentation.

package/agent-docs/publish/mcp.sections/verify-the-connection.md

@@ -0,0 +1,40 @@
+---
+id: guide.mcp
+title: Connect an MCP client
+summary: Connect read-only MCP clients over stdio or HTTP to search and read
+  built documentation.
+type: how-to
+area: discovery
+subarea: discovery-mcp
+canonical: /publish/mcp
+---
+
+# Connect an MCP client
+
+> Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
+
+Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigation/docs-50f26fe22670.txt) (ID: docs). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Search, chat, and agent access > MCP > Connect an MCP client
+
+**Updated: 2026-10-27.**
+
+Parent page: [Full Markdown page](/publish/mcp.md)
+
+**Page reading path** — these links apply to the full page.
+
+**Next steps**
+
+- [Measure MCP tool usage](https://www.shoalrun.com/publish/mcp-analytics.md) — Optionally measure tool calls through a server adapter.
+
+Connect an MCP client to built documentation through four read-only tools. Use stdio for a client-launched local process, or enable an HTTP endpoint on Node or in a generated Vercel function. Both use the same search and Markdown reading core.
+
+The HTTP endpoint currently supports one explicitly selected public publication. The generated Vercel endpoint is deployed and verified on this site. Netlify and Cloudflare adapters are not implemented. Analytics is off by default; an optional [server adapter](https://www.shoalrun.com/publish/mcp-analytics.md) can measure tool calls.
+
+You need Node.js 22.12 or newer, the installed Shoalrun CLI, and a client that supports MCP stdio or Streamable HTTP. Follow [Getting started](https://www.shoalrun.com/start.md) to install the public npm package.
+
+## Verify the connection
+
+Search for a known page, read the returned ID, and inspect its Markdown. Then request a nonexistent ID: it should return `unknown_page` without stopping the server. Confirm that a small budget sets `truncated` on a long page. These checks exercise the source selection and tool contract without an agent harness.
+
+The tools are read-only and do not expose authoring commands. Stdio makes them available to a local tool-capable client; clients that cannot launch a local process cannot use this transport. They can read published Markdown over HTTP when their tools support fetching URLs. Stdio has no analytics adapter. The optional HTTP adapter records tool outcomes without raw queries.

package/agent-docs/publish/mcp.sections/why-offer-mcp-for-public-docs.md

@@ -0,0 +1,42 @@
+---
+id: guide.mcp
+title: Connect an MCP client
+summary: Connect read-only MCP clients over stdio or HTTP to search and read
+  built documentation.
+type: how-to
+area: discovery
+subarea: discovery-mcp
+canonical: /publish/mcp
+---
+
+# Connect an MCP client
+
+> Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
+
+Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigation/docs-50f26fe22670.txt) (ID: docs). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Search, chat, and agent access > MCP > Connect an MCP client
+
+**Updated: 2026-10-27.**
+
+Parent page: [Full Markdown page](/publish/mcp.md)
+
+**Page reading path** — these links apply to the full page.
+
+**Next steps**
+
+- [Measure MCP tool usage](https://www.shoalrun.com/publish/mcp-analytics.md) — Optionally measure tool calls through a server adapter.
+
+Connect an MCP client to built documentation through four read-only tools. Use stdio for a client-launched local process, or enable an HTTP endpoint on Node or in a generated Vercel function. Both use the same search and Markdown reading core.
+
+The HTTP endpoint currently supports one explicitly selected public publication. The generated Vercel endpoint is deployed and verified on this site. Netlify and Cloudflare adapters are not implemented. Analytics is off by default; an optional [server adapter](https://www.shoalrun.com/publish/mcp-analytics.md) can measure tool calls.
+
+You need Node.js 22.12 or newer, the installed Shoalrun CLI, and a client that supports MCP stdio or Streamable HTTP. Follow [Getting started](https://www.shoalrun.com/start.md) to install the public npm package.
+
+## Why offer MCP for public docs?
+
+MCP gives tool-capable agents a predictable way to search your docs and request a page or section within a token budget. For example, an agent answering “How do I configure analytics?” can search and follow the returned read instruction. The result includes relevant Markdown, its publication, and a source link.
+
+The documentation can already be public. MCP adds a tool interface; it does not grant access that public Markdown lacks. Agents that can fetch and search your Markdown may not need it. Offer both when your readers use MCP clients, and check whether the tools help them find answers with fewer requests or less content.
+
+To use Shoalrun's own live documentation endpoint, follow [use this site's MCP](https://www.shoalrun.com/connect/mcp.md). The setup below is for hosting your own project's tools.

package/agent-docs/publish/openapi-extension-mappings.md

@@ -0,0 +1,84 @@
+---
+id: reference.openapi-extension-mappings
+title: OpenAPI extension mappings
+summary: Map selected operation-level x-* values into Shoalrun metadata without
+  depending on a particular authoring service.
+type: reference
+area: api
+subarea: api-contracts
+canonical: /publish/openapi-extension-mappings
+---
+
+# OpenAPI extension mappings
+
+> Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
+
+Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/navigation/reference-tab-50f26fe22670.txt) (ID: reference-tab). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > API support > OpenAPI extension mappings
+
+**Updated: 2026-10-25.**
+
+OpenAPI permits [specification extensions](https://spec.openapis.org/oas/v3.1.0#specification-extensions) whose names begin with `x-`. Their names and values belong to the tool or team that wrote the description. Shoalrun reads standard OpenAPI fields directly and applies an extension only when the project config explicitly maps it to a supported Shoalrun field.
+
+## Supported mapping
+
+Use these source locations and value shapes when mapping OpenAPI extensions to Shoalrun fields.
+
+| Shoalrun target    | Source location                                      | Accepted source shape                                           | Shoalrun values                                        |
+| ------------------ | ---------------------------------------------------- | --------------------------------------------------------------- | ------------------------------------------------------ |
+| `subjectLifecycle` | An operation under `paths` or OpenAPI 3.1 `webhooks` | A scalar `x-*` value, or a scalar member inside an `x-*` object | `beta`, `in-development`, `experimental`, `deprecated` |
+
+Use `apis.<apiId>.mappings.subjectLifecycle`. `from` starts with an operation-level `x-*` key. For an object, add a dot and the member name; further simple member names may follow. `values` maps exact source values to Shoalrun values. Unlisted, missing, null, array, or object values do not set a badge.
+
+For example, this fictional OpenAPI operation uses an object-shaped extension:
+
+```yaml title="openapi.yaml"
+paths:
+  /widgets:
+    get:
+      operationId: listWidgets
+      x-docs-availability:
+        status: testing
+        note: May change before general release
+      responses:
+        '200': { description: Widgets returned }
+```
+
+Map its `status` member without changing the OpenAPI file:
+
+```yaml title="config/api.yaml"
+catalog:
+  source: { kind: file, path: ../apis/catalog/openapi.yaml }
+  mappings:
+    subjectLifecycle:
+      from: x-docs-availability.status
+      values:
+        testing: beta
+        building: in-development
+        retired: deprecated
+  generateReferences: true
+```
+
+The `listWidgets` reference now shows **Beta** in its page header and navigation. Its Markdown twin and `documents.json` also report the mapped status. For a scalar extension such as `x-docs-availability: testing`, use `from: x-docs-availability` with the same `values` map. The source names are examples; the project chooses its own extension name and values.
+
+An authored reference page's `subjectLifecycle` takes precedence over the mapping. OpenAPI `deprecated: true` always makes the operation **Deprecated**; a conflicting authored status fails the build. A mapping is scoped to one API registration and applies to that API's selected operations across its publications.
+
+## Other extension shapes
+
+Extensions outside the supported mapping may need source changes or a different Shoalrun feature.
+
+| Source extension purpose              | Current Shoalrun behavior | Use in Shoalrun today                                                                                                                                                                   |
+| ------------------------------------- | ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Tag names and tag groups              | No automatic mapping      | Use OpenAPI `tags` for generated groups and [navigation config](https://www.shoalrun.com/author/navigation.md) for editorial grouping and MDX pages.                                    |
+| Custom code samples                   | No automatic mapping      | Add an authored MDX example or reusable snippet; standard OpenAPI request and response examples still appear automatically.                                                             |
+| Enum labels or descriptions           | No automatic mapping      | Standard `enum` values appear in schemas. Put explanatory prose in a schema or field `description`.                                                                                     |
+| Hide or internal flags                | No automatic mapping      | Select public operations with `generateReferences.include` or explicit `operations`; set page access in authored frontmatter. Do not rely on an unrecognized extension to hide content. |
+| Explorer settings and SDK naming      | No automatic mapping      | Shoalrun does not execute API requests. Keep SDK-specific settings in their owning tool.                                                                                                |
+| Webhook markers in older descriptions | No automatic mapping      | Describe inbound events with OpenAPI 3.1 `webhooks`.                                                                                                                                    |
+
+An unmapped `x-*` value does not change the rendered reference. A focused contract omits extension properties while retaining literal example payload keys, even when those keys begin with `x-`. A full OpenAPI download enabled by `source.publish: true` contains the source file as authored, including its extensions. Review that file before publishing it.
+
+## Choosing a new mapping target
+
+The target list above is intentionally small. An extension can describe presentation, visibility, SDK behavior, or actual wire semantics, and identical names do not guarantee identical shapes. When adding a target, define its source location, accepted value shapes, Shoalrun output, precedence over authored metadata and standard OpenAPI, and behavior for unknown values. Keep the source name configurable so projects can adapt descriptions from different tools without baking a vendor vocabulary into Shoalrun.