ash-webmcp

Files (4)

• SKILL.md
• adoption.md · references/
• build.md · references/
• regents.md · references/

SKILL.md (first lines)

# Ash agent readiness and WebMCP

Make the real product readable and usable by agents before adding protocol surfaces.
Reuse shared presentation and HTTP mechanics; keep product actions, authorization,
public-document selection and release authority with their owners.

## When to use

- Building WebMCP tools into an Ash/Phoenix site: follow [build](references/build.md).
- Ash/Phoenix Markdown negotiation, agent documentation, OpenAPI, discovery metadata,
  recoverable errors, or a WebMCP integration/adoption review.
- An agent-readiness report needs to be translated into verified product changes.
- Do not use a scanner score as authorization for new auth, signing, payments,
  publication, database mutation, or an unrelated deployment.

## Prerequisites and ownership

Read workspace/repository instructions, `ash-stack`, and the relevant frontend,
backend and security specialists. Inspect the actual branch, dirty files, router,
endpoint, controller formats, MIME configuration, error views, root layout and
installed package versions. Agree owned files first.

Use [product adoption](references/adoption.md) for concrete source entry points in
Autolaunch, Patchbay and Techtree. Use [Regents reference](references/regents.md) for
the verified implementation and its limits. The older
[Patchbay walkthrough](../ash-stack/references/agent-readiness.md) remains a worked
example; `regent-workflow` ("Every change proves itself") decides which checks a
change adds.

## Procedure

### 1. Establish the real surface

Record public read pages, authenticated/private pages, LiveView-only rooms, JSON
prefixes, actual API operations, and the browser tool registry. Trace advertised
capabilities to implementations and policies. Keep source availability, local
verification, deployed behavior and native-browser acceptance separate.

Completion: a bounded route/capability inventory with explicit exclusions, not an
assumption that every HTML page is public or supports Markdown.

The inventory includes every action a signed-in owner can take on a page, not only
the tools that exist. An action only a person can do is a bug (`regent-workflow`,
"An action only a person can do is a bug"): each one gets a row in
`docs/agent-parity.md` with its browser, WebMCP, hosted MCP, Claude connector and CLI
surface, and a missing surface is a gap with an owner, never an exclusion.

### 2. Negotiate truthful Markdown at the same URL

- Reuse the product's existing negotiation, or adopt `regent_agent_access` from
  `elixir-utils/agent_access`: `RegentAgentAccess.Plug` for Accept selection, Vary
  merging and public-document Markdown, and `RegentAgentAccess.Recovery` for Markdown
  and JSON error bodies. Regents is its first consumer. Pin one reviewed shared
  revision; do not paste plugs, error modules or route allowlists into a product.
  This package is distinct from the shared head component.
- Prefer HTML for ordinary browser/wildcard requests. Honor quality factors and
  specificity, including explicit `q=0`; do not use a substring check.
- Merge `Accept` into `Vary` without losing encoding, cookie or other dimensions.
  Multiple Vary fields are legal: inspect their combined values.
- Keep each product's public-document allowlist local. An early endpoint projection
  is only appropriate for explicitly public, database-free content. Dynamic/private
  reads must remain behind their real actors, policies, sessions and launch gates.
- HTML and Markdown should derive from the same authored content or read model.
  Preserve status and privacy behavior; never invent balances or missing data.
- Inspect installed MIME defaults first. MIME 2.0.7 already maps `text/markdown` to
  both `md` and `markdown`. Do not narrow that mapping or remove unrelated YAML types.

Completion: actual HTTP responses demonstrate HTML, Markdown, weighted Accept,
HEAD and refusal behavior without leaking an authenticated representation.

### 3. Make errors recoverable

Provide safe HTML and Markdown recovery links and machine-readable API errors.
Unknown API-prefix routes should stay JSON even with browser Accept headers.
Retain correct non-200 statuses and the existing published error contract; add
codes/hints only compatibly or through the owning contract change. Do not echo
credentials, session data, request bodies, private URLs or exception internals.

Completion: read back real unknown HTML/Markdown/JSON addresses and an unknown API
address. Development debugger pages are not proof of release error rendering.

### 4. Publish usable documentation and contracts

Publish one clear developer entry point with copyable public reads, real auth and
pagination rules, structured errors, actual limits, and supported/gated boundaries.
Use unique operation IDs and typed parameters/responses in OpenAPI. Validate it
structurally and trace every operation to the router. Never describe invented API
keys, scopes, OAuth servers, sandboxes, SDKs or MCP endpoints.

Keep existing frozen contracts intact. Where a CLI verifies contract headers, derive
its digest from the exact served bytes and its major version from the real contract;
update producer and consumer together. A repository CLI fix does not publish a new
npm version. Check the registry before recommending an install command.

Completion: documentation and machine contracts agree with the live product.

### 5. Reuse the shared head, not duplicate tags

Use `Regent.AgentMetadata.head` from `design-system/regent_ui` once in the root layout.
It owns canonical/description, optional real discovery links, OG/Twitter tags and
script-safe JSON-LD encoding. Pass actual product values and a structured-data map.
A page that holds a blog post, a forum thread or question, or a table of data adds its
own node with `Regent.StructuredData` as a `page_data` assign, which the root layout
joins to the site graph (`AshTemplateWeb.PublicDocuments.structured_data/1`); only
facts the page shows. New and changed public pages reach search engines through
`AshTemplate.IndexNow` (`ASH_TEMPLATE_INDEXNOW_KEY`, one key per site).
The product retains its title, viewport, CSRF/provider metadata, CSP and assets.

Set `markdown` only for supported pages; it defaults to false. Optional guide,
sitemap and service-description URLs must exist. Use a real raster image and its
measured dimensions. Pass the existing CSP nonce if needed; do not weaken CSP.
Choose any site-type declaration by product purpose, not by the highest score.

In HEEx script bodies, use EEx output for the encoded JSON; curly interpolation can
become literal script text. Parse the **rendered** JSON-LD, not merely its source or
presence. Escape `<` before raw insertion so data cannot terminate the script tag.

Completion: one canonical/tag set, parseable rendered JSON-LD, valid image, truthful
classification and no advertised representation on unsupported pages.

From regents-ai/ash-template, MIT.

More from regents-ai/ash-template