Improve how ready https://wazoo.dev is for agents (Is Agentic 80/100) #24

Summary

Improve how ready https://wazoo.dev is for AI agents.

Current score: 80/100 (Is Agentic readiness model based on Ora audit evidence)
Source: https://is-agentic.com/scan/wazoo.dev
Baseline scan: 2026-08-24

Structure of this issue

All 15 findings from the audit are listed below, each tagged with ownership:

• [SITE] — actionable in this repo (wazoo.dev's static site; legacy GitHub Pages).
• [API] — owned by API repos (wazoo-api, worlds-api); referenced here for completeness, not implemented here.
• [CLI] — owned by wazoo-cli.
• [PAGES-LIMIT] — not feasible on the current legacy GitHub Pages hosting (needs custom headers or non-static hosting).
• [SEO] — partly non-code / long-term.

Failures (do first)

1. Content without JavaScript — [SITE] (Essential, currently Partial)

• Evidence: Only 805 chars of text content, no H1 tag — agents see limited content.
• Fix: Server-side render the homepage so AI crawlers see meaningful content without JavaScript; ensure an H1 and 500+ chars of text in raw HTML.
• Status in repo: index.html is already fully static, server-rendered HTML with an H1 and well over 500 chars (plus H2, structured JSON-LD). The scanner reading is likely stale or JS-executing. Action: re-verify live on deploy rather than rebuild.

2. Agent-friendly 404s — [SITE] (Essential, currently Partial)

• Evidence: Nonexistent paths return a real HTTP 404. Missing a short markdown body for agents to recover.
• Fix: Keep the real 404 (legacy Pages serves 404.html with a 404 status) and add a short markdown-style body pointing agents at /sitemap.xml, /llms.txt, /, and the docs index.
• Verify: curl -s -o /dev/null -w "%{http_code}" https://wazoo.dev/some-path-that-does-not-exist must print 404.

3. Markdown content negotiation (acceptmarkdown.com) — [PAGES-LIMIT] (Essential, Failed)

• Evidence: Not compliant: Accept: text/markdown returned text/html; Vary header missing Accept.
• Fix requested: Serve text/markdown via Accept negotiation and add Vary: Accept, Accept-Encoding.
• Not feasible here: legacy GitHub Pages serves static files with default headers only; it cannot set Vary: Accept or negotiate content types. Action: documented out-of-scope for this repo. To claim these points, content negotiation must move to a hostable layer (e.g., a Worker/CDN fronting the site, or the API layer in wazoo-api).

4. Developer resource discoverability — [SITE] (Recommended, Failed)

• Evidence: Agent searched for "wazoo" developer resources and found nothing relevant.
• Fix: Make dev resources discoverable by name at predictable URLs, list them in llms.txt, and include the product name in page titles/headings.
• Action (this repo): add /llms.txt + /llms-full.txt indexing /, /brand, /about, /contact, /sitemap.xml, https://docs.wazoo.dev, the OpenAPI spec URLs, and MCP (when live).

5. MCP server / manifest — [API] (Recommended, Failed)

• Evidence: No MCP server or manifest found.
• Fix: Build an MCP server exposing the platform API as tools (Streamable HTTP transport).
• Owned by: wazoo-api — already tracked as wazoo-api#40 ("feat(mcp): expose official MCP entrypoint at api.wazoo.dev/mcp"). Reference once live from llms.txt.

6. Agent instruction / when-to-use — [SITE] (Recommended, Failed)

• Evidence: No agent-instruction file with when-to-use guidance.
• Fix: Add a "when to use this" section to llms.txt naming best-fit use cases and how an agent should call the product. Be specific — not generic marketing copy.
• Action (this repo): llms.txt with a when-to-use section; add robots.txt referencing it and the sitemap.

7. REST typed error model — [API] (Recommended, Failed)

• Evidence: No typed error model in OpenAPI spec.
• Fix: Document 4xx/5xx responses with a typed error schema (or RFC 9457 application/problem+json).
• Owned by: wazoo-api / worlds-api OpenAPI specs. Out of scope for this static repo; referenced for completeness.

8. Sitemap exists — [SITE] (Recommended, Failed)

• Evidence: No sitemap found.
• Fix: Add a valid XML sitemap.xml (with lastmod, under 50MB) listing all indexable URLs.
• Action (this repo): commit /sitemap.xml; enable via robots.txt.

9. Rate limit response headers — [API] (Recommended, Failed)

• Evidence: No REST rate-limit headers on probed endpoints.
• Fix: Return RFC RateLimit headers plus Retry-After on 429.
• Owned by: worlds-api (related: worlds-api#39 "Rate limiting"). Out of scope for this static repo.

Warnings (fix after failures)

10. Brand name discoverability — [SEO] (Recommended, currently Partial)

• Evidence: wazoo.dev appears once for "Wazoo Technologies" (position feat: consolidate brand guidelines and add DESIGN.md #7 of 9).
• Fix: Consistent NAP, press mentions linking to the canonical domain, avoid redirect chains that mask the apex domain.
• Action: long-term / partly non-code (README/AGENTS already keep claims aligned with JSON-LD). Not a file change in this repo alone.

11. Metadata completeness — [SITE] (Recommended, currently Partial)

• Evidence: Missing canonical URL, og:image, og:type (1/4 signals present).
• Fix: Add <link rel="canonical">, og:image, og:type to the homepage (<html lang> already present).
• Action (this repo): add canonical, og:image (new 1200x630 raster asset), og:type to index.html.

12. Organization schema completeness — [SITE] (Recommended, currently Partial)

• Evidence: Organization schema found but missing contactPoint and address.
• Fix: Add Organization JSON-LD with both contactPoint (email/phone + contactType) and address (PostalAddress).
• Action (this repo): extend the existing Organization node in index.html JSON-LD. Input needed: public contact email + whether to publish a postal address.

13. Trust anchor pages — [SITE] (Recommended, currently Partial)

• Evidence: Only Privacy verified; missing About and Contact.
• Fix: Publish /about, /contact, and /privacy with >=500 chars each.
• Action (this repo): add /about and /contact static pages (privacy already exists at docs.wazoo.dev/privacy-policy). Keep /team (issue feat: add wazoo.dev/team page and docs footer integration #14) separate.

14. REST versioning / deprecation policy — [API] (Recommended, currently Partial)

• Evidence: URL versioning found but no deprecation/sunset policy.
• Fix: Publish a versioning policy and signal deprecation (Sunset/Deprecation headers or a documented timeline).
• Owned by: API repos (wazoo-api / worlds-api). Out of scope for this static repo.

15. CLI tool available — [CLI] (Recommended, currently Partial)

• Evidence: CLI mentioned in llms.txt.
• Fix: Publish an official CLI on npm / PyPI / Homebrew.
• Owned by: wazoo-cli. Out of scope for this static repo.

Priority order & ownership summary

Site-level (SITE) changes to land in this repo: #1, #2, #4, #6, #8, #11, #12, #13.

Open inputs before site implementation

• Public contact email for the Organization contactPoint (none currently published in the repo).
• Whether to publish a postal address (PostalAddress) — optional/legal decision.
• og:image asset source (generate a 1200x630 PNG from brand assets, or use a specified image URL).