Six honest agent-readiness fixes

Request simulator B3 bot-UA routing, B1 twin existence

Pick a client and a path. This runs the same decision middleware.ts makes: whether the request wants Markdown, and whether a Markdown twin actually exists at that path.

Markdown alternate link B1

No rel="alternate" existed anywhere. The link is now emitted, but only where mdTarget() genuinely maps a twin.

<link rel="canonical"
      href="…/docs/foundations/overview">

<link rel="canonical"
      href="…/docs/foundations/overview">
<link rel="alternate" type="text/markdown"
      href="…/docs/foundations/overview.md">

Markdown frontmatter B2

Served Markdown carried no identity: the title was only recoverable by parsing the first H1, and nothing said which URL the body belonged to. Every value below is the one the HTML twin already publishes.

# Overview

Start here.

…

---
title: "Overview"
description: "Start here."
canonical: "https://orchestkit.yonyon.ai/docs/foundations/overview"
---

# Overview

Start here.

…

A 404 body gets no frontmatter: canonical would have to name a URL that does not resolve.

trustManifest on catalog entries B4

A host-level manifest already existed. A consumer of the ARD catalog decides per resource, not per publisher, so identity has to travel with the entry it is deciding about.

host       ✓ trustManifest
entries[0]   (none)
entries[1]   (none)
entries[2]   (none)
entries[3]   (none)
entries[4]   (none)

host      ✓ trustManifest
entries[0] ✓
entries[1] ✓
entries[2] ✓
entries[3] ✓
entries[4] ✓

Two claims only, both verifiable without asking us: the did:web resolvable at /.well-known/did.json, and publishedFrom the public repository. Still absent by design: signature (no request-signing bot), attestations (no compliance program), trustSchema (no external governance).

llms.txt npm links B6

Measured 2026-08-23 with a ClaudeBot/1.0 User-Agent. Every reader of llms.txt is a non-browser client by definition, so the link it was handed could never be followed.

Both packages genuinely exist. Only the host changed, and the guard test still pins the exact shipping package name from packages/cli/package.json.

Agent Plugins manifest B5

The tempting move was to add $schema to the manifest Claude Code already reads. Measured against the canonical schema, that would have been a false claim. The two specs want the file in two different places, so ork now ships both and neither compromises.

The canonical schema is additionalProperties: false over ten permitted keys. Spec 4.1 and 5.1 place the Agent Plugins manifest at plugin.json in the plugin root; Claude Code reads .claude-plugin/plugin.json. Two paths, two correct files.

$schema  ✓ added
skills       (forbidden)
commands     (forbidden)
workflows    (forbidden)
=> names a schema it fails

plugin.json
  $schema, name, version,
  description, author,
  homepage, repository,
  license, keywords
=> 0 violations

Also measured and rejected: moving the three keys under extensions makes Claude Code warn "Unknown field 'extensions'. Claude Code ignores it at load time", trading a false claim for inert data.

Deliberately not done

• Markdown alternates on the 13 marketing pages. mdTarget() does not map them, so the link would point at a URL that answers with HTML. Worse than no link.
• Markdown for search-engine crawlers. Googlebot, bingbot and applebot index the HTML. Swapping it would drop the site out of results it currently earns. "AI bot" is not a synonym for "crawler".
• Markdown for generic HTTP clients. curl, python and node are the same string whether a human or an agent sent them. They still get Markdown the explicit way, by asking for it.