Signal/docs/agent-ready-ecosystem-handoff-2026-06-22.md

# Agent-Ready Ecosystem: Handoff to Pi for Spec Design

**Date:** 2026-06-22
**From:** Claude Code (analysis + live scan)
**To:** Pi (design the integration spec); Claude Code builds after
**Related:** `STTIL-Vault/Projects/2026-06-22-website-sttil-vs-signal-whitepaper.md` (copy audit, same project)

## Goal (Kisa's words, paraphrased)

Prepare sttilsolutions.com for where the agent web is going. Not necessarily ahead of the curve, but at minimum keeping pace as standards change in real time. The agent-readiness concept came from a coach call within the last month. Kisa has delegated the technical decisions, so this brief includes recommended defaults for each open question.

## Governing doctrine (non-negotiable)

Implement only what genuinely applies, and everything published must be REAL and resolvable. Never publish a card, endpoint, or metadata file for infrastructure that does not exist. Scanners penalize broken or faked artefacts, and faking it is dishonest. Honesty is also the better score strategy.

## Live scan result (Cloudflare "Is Your Site Agent-Ready?", 2026-06-22)

**Overall: 64 / 100, Level 4 "Agent-Integrated"** (Level 5 "Agent-Native" is the ceiling).

| Category | Score | Pass/Total | Notes |
|---|---|---|---|
| Content Accessibility | 100 | 1/1 | Markdown negotiation works on the homepage |
| Bot Access Control | 100 | 2/2 | AI bot rules + Content-Signal directives present for GPTBot, ClaudeBot, PerplexityBot, etc. |
| Discoverability | 75 | 3/4 | robots.txt, sitemap.xml, Link headers all valid. Miss: DNS-AID records exist but DNSSEC not validated |
| API, Auth, MCP & Skill | 43 | 3/7 | Pass: API Catalog, Agent Skills index, WebMCP (2 tools detected). Fail: OAuth/OIDC discovery, OAuth Protected Resource, MCP Server Card, A2A Agent Card |
| Commerce | n/a | not checked | Correct, no store |

## What is already solid (do NOT rebuild)

The agent-ready plumbing is well-built and honest, not slopped in:

- `robots.txt` with Content Signals, `sitemap.xml`, `llms.txt`, `llms-full.txt`, `index.md` all live with correct content-types.
- RFC 8288 `Link:` header on the homepage with 5 valid relations (describedby, alternate, agent-skills, api-catalog, author). This is the hardest part to get right and it passes.
- Markdown content negotiation on `/` (Accept: text/markdown returns markdown).
- `.well-known/api-catalog` (valid linkset) and `.well-known/agent-skills/index.json` (2 skills) resolve.
- `webmcp.js` is honest progressive enhancement: feature-detects `navigator.modelContext`, registers silently, never throws into the page, and its `request_walkthrough` tool opens the real demo form. The scanner confirmed 2 WebMCP tools detected.
- MCP Server Card and A2A Card return 404, which is the correct, honest state today (no real endpoint behind them yet).

## The core insight: the weak category is the unbuilt tiers

The "API, Auth, MCP & Skill" category scores 43 because all four failures describe a real protected API or agent endpoint that does not exist yet. They map exactly onto the product tier model:

| Tier | Product | Agent-ready artefact that becomes honest to publish |
|---|---|---|
| 1 | Worklist (CSV only) | Already covered by discovery + content + WebMCP request_walkthrough |
| 2 | Connected (API) | OAuth/OIDC discovery, OAuth Protected Resource, MCP Server Card pointing at the real Signal API |
| 3 | Intelligence (compliant support bot) | A2A Agent Card and/or an MCP server exposing the bot, once built and compliance-cleared |

So the path from Level 4 to Level 5 is to build the real tiers and publish the matching cards when each ships. No faking. The product roadmap and the agent-readiness roadmap are the same roadmap.

## The content-governance problem (cross-reference the copy whitepaper)

The plumbing is good, but the CONTENT flowing through the agent files is stale and is not fed from a single source of truth, so it has drifted from the human pages. Agents quote these files verbatim:

- `llms.txt`: "patients needing outreach" (violates the rule that Signal never conducts outreach).
- `llms-full.txt`: banned "over 25% denied first pass" stat, SWO mis-defined as "Statement of Medical Necessity" (should be Standard Written Order), and exposed pricing ($149-199/mo) that appears nowhere on the visible site.
- Agent Skills index: the 2 skills are detected but report "0 with valid v0.2.0 fields" — the entries need updating to the v0.2.0 schema.

**Recommended architecture (the real "integrate into the ecosystem" answer):** one canonical fact source (brand architecture, locked stats, scope language, tier definitions) that generates or feeds BOTH the human HTML and the agent-readable files, so they can never disagree again.

## Open design decisions (with recommended defaults, since Kisa delegated)

1. **Agents act vs read.** WebMCP is already live and lets an agent open the walkthrough form. Recommendation: keep it, ensure the submitted data routes compliantly (no PHI), and add a `join_pilot` action only after the pilot intake is defined.
2. **Single canonical fact source.** Recommendation: yes. Build it. It is the highest-leverage fix and prevents future drift.
3. **What is safe to broadcast to agents.** Recommendation: remove pricing and any unverified stat from the agent files until there is a deliberate decision to make pricing public. Keep the credential-led founder framing.
4. **Real MCP/A2A endpoint.** Recommendation: do NOT publish cards now. Design them as part of the Tier 2 API build so they point at a real endpoint. Honest-by-default.
5. **Version control + deploy path.** The site has no git repo and serves from the VPS via Caddy; the `Link:` header lives in Caddy config. Recommendation: put the site under Forgejo before systematic edits, so every change is tracked and reversible. Confirm Caddy ownership of the header.
6. **Scope.** This scan and plan cover sttilsolutions.com (marketing). signal.sttilsolutions.com and the Vercel app are separate surfaces, treat later.

## Quick wins available now (no new product needed)

- **Enable DNSSEC** on Cloudflare for sttilsolutions.com. DNS-AID records already exist; DNSSEC takes Discoverability from 3/4 to 4/4. Registrar/Cloudflare-side toggle.
- **Update the 2 Agent Skills to the v0.2.0 schema** so they validate.
- **Fix the agent-file content** (outreach wording, banned stat, SWO definition, pricing) in the same pass as the copy whitepaper.

## Roadmap items (rise with the real product)

- Tier 2 API ships, then publish OAuth/OIDC discovery + OAuth Protected Resource + MCP Server Card against it.
- Tier 3 compliant support bot ships, then expose it via an A2A Agent Card or MCP server.

## Compliance gate (hard requirement)

The Tier 3 support bot touches AI behavior and bot functionality. It MUST pass `sttil-compliance-check` before any build. Kisa has stated the bot must be verifiably compliant, and the existing PHI architecture (patient_id only, no names/DOB/SSN) is the foundation that makes that achievable.

## Build and verify protocol

- Build agent-ready changes against a preview/staging surface first, never straight to the live site.
- Verify by re-running the Cloudflare scan and the direct curl probes, confirm the level moved and nothing regressed, then deploy.