# Mnemom Agent-Readability Commitment
#
# Single source of truth. Read by:
#   - client/pages/ForAgents.tsx (renders this file as the public spec)
#   - scripts/verify/_runner.ts (executes ciScript per commitment in CI)
#   - .github/workflows/verify-agent-readiness-watchdog.yml (nightly verification)
#
# Editing this file is editing a public, versioned commitment. Bump `version`
# semver-style: patch for clarifications, minor for new commitments, major
# for breaking changes to existing commitments. Update `lastReviewed` on every
# substantive edit and add a /changelog entry.
#
# Promoting `roadmap` → `commitments` requires a 7-consecutive-green-night
# soak period against the candidate surface. See AGENTS.md §
# "Agent-readability commitment" for the rationale (v1.4's trust subdomain
# commitment shipped red because the soak step was skipped).

version: "1.13.0"
lastReviewed: "2026-06-10"
nextReviewBy: "2026-09-08"
reviewCadenceDays: 90

# A short description that gets surfaced both in the page header and in
# JSON-LD as the document's `description`.
summary: >
  Mnemom's public, versioned, machine-verifiable commitment to agent-readability.
  Each commitment below is enforced in CI and re-verified nightly against
  production. Last verification status lives in agent-readiness-status.json.

commitments:
  - id: prerendered-content
    title: Every core marketing page returns prerendered HTML
    rationale: >
      Agents that render HTML — search crawlers, Anthropic Computer Use,
      Browserbase, and headless evaluators — see the full page content
      on every core marketing route without executing JavaScript. The
      prerender set is enumerated in STATIC_MARKETING_PATHS in
      react-router.config.ts and mirrored across the four EFIGS locales
      (fr / de / it / es). Two classes ship as shell-only by design and
      are named publicly here, not hidden: blog index pages, whose
      post lists hydrate via TanStack Query against api.mnemom.ai, and
      the legal triad (/privacy /terms /cookies), whose policy bodies
      render via Termly's third-party embed SDK. The prerendered <h1>
      and surrounding chrome are present on both — what this verifier
      asserts. Auth-gated SPA surfaces (/dashboard, /admin, /settings/*)
      are intentionally outside this commitment; they have no anonymous
      public view.
    verifyCli: |
      curl -s https://www.mnemom.ai/methodology/ | grep -c '<h1'
    expectation: Headings appear in raw HTML; ≥1 <h1> per non-excluded route
    ciScript: scripts/verify/prerender.ts

  - id: discovery-files
    title: agents.txt, llms.txt, and llms-full.txt are always available
    rationale: >
      Three discovery files at the site root: a hand-crafted second-person
      pitch (agents.txt), a curated index of every URL with descriptions
      (llms.txt), and the same with full descriptions (llms-full.txt).
      All three return 200 with text/plain content type. Always.
    verifyCli: |
      curl -sI https://www.mnemom.ai/agents.txt    | head -2
      curl -sI https://www.mnemom.ai/llms.txt      | head -2
      curl -sI https://www.mnemom.ai/llms-full.txt | head -2
    expectation: All three return HTTP/2 200 with text/plain content-type
    ciScript: scripts/verify/discovery-files.ts

  - id: structured-data
    title: Every prerendered marketing page contains valid, locale-aware JSON-LD
    rationale: >
      JSON-LD gives agents a typed graph of who published what, when, and
      how the page relates to other entities. v1.3 expands coverage from
      /for-agents to every prerendered marketing route in every locale&#58;
      a primary entity per page (Organization + WebSite + WebPage on the
      home page; Product on /pricing; WebApplication on /showcase and
      /arena; HowTo on /how-it-works; CollectionPage on /research,
      /directory, /teams/directory; Article / ScholarlyArticle / TechArticle
      across the rest), plus a BreadcrumbList companion on every page.
      Required keys per primary entity&#58; "@context", "@type", "name",
      "description", "url", "inLanguage", and one of "dateModified" /
      "datePublished". Locale-aware fields (name, description, url,
      inLanguage) come from the active route's :lang? param; technical
      identifiers (publisher name, schema.org @type) stay English.
    verifyCli: |
      for r in / /pricing/ /showcase/ /arena/ /fr/showcase/ /de/pricing/; do
        printf "%-25s " "$r"
        curl -s "https://www.mnemom.ai$r" | \
          grep -c '<script type="application/ld+json">'
      done
    expectation: ≥1 JSON-LD block per route; primary entity carries @context, @type, name, description, url, inLanguage, dateModified; locale-prefixed routes use matching inLanguage and url
    ciScript: scripts/verify/json-ld.ts

  - id: markdown-mirror
    title: Every prerendered marketing page has a markdown variant
    rationale: >
      Agents that prefer plaintext save ~80% on tokens versus rendering
      HTML. Every prerendered route is also served as markdown via
      content negotiation (Accept&#58; text/markdown) and at the explicit
      &lt;path&gt;.md URL. Same content; navigation chrome stripped.
    verifyCli: |
      curl -sI -H "Accept: text/markdown" https://www.mnemom.ai/methodology/
      curl -sI https://www.mnemom.ai/methodology/index.md
    expectation: Both return 200 with Content-Type containing "text/markdown"
    ciScript: scripts/verify/markdown-mirror.ts

  - id: no-cloaking
    title: Anonymous and bot user-agents receive equivalent content
    rationale: >
      Agents identifying as ClaudeBot, GPTBot, PerplexityBot, or
      anonymous get the same prerendered HTML a browser receives.
      Mnemom never serves different content to bots versus humans —
      no cloaking, no UA-gated paywalls, no hidden detail.
    verifyCli: |
      diff <(curl -sA "Mozilla/5.0" https://www.mnemom.ai/methodology/) \
           <(curl -sA "ClaudeBot/1.0" https://www.mnemom.ai/methodology/) | wc -l
    expectation: Structural diff under threshold (excluding known dynamic regions)
    ciScript: scripts/verify/no-cloaking.ts

  - id: open-protocols
    title: AAP and AIP remain Apache 2.0
    rationale: >
      The Agent Alignment Protocol (AAP) and Agent Integrity Protocol
      (AIP) are open source under Apache 2.0. The verification logic
      that backs every Mnemom claim is auditable by anyone, forever.
      We will never relicense to a more restrictive form.
    verifyCli: |
      curl -s https://raw.githubusercontent.com/mnemom/aap/main/LICENSE | grep -c "Apache License"
      curl -s https://raw.githubusercontent.com/mnemom/aip/main/LICENSE | grep -c "Apache License"
    expectation: Both LICENSE files contain "Apache License" string
    ciScript: scripts/verify/license-check.ts

  - id: docs-markdown-negotiation
    title: docs.mnemom.ai serves markdown via content negotiation and explicit .md URLs
    rationale: >
      The integration documentation surface (docs.mnemom.ai) honors
      Accept&#58; text/markdown and serves the same content at
      &lt;path&gt;.md, with discovery headers (Link rel="llms-txt",
      X-Llms-Txt) advertising the auto-generated llms.txt and
      llms-full.txt indexes. Cuts crawl tokens roughly 30x for agents
      that walk the docs. Same site, same content, machine-readable
      view-shape — no special API key, no robots.txt blocking.
    verifyCli: |
      curl -sI -H "Accept: text/markdown" https://docs.mnemom.ai/for-agents | grep -iE "content-type:|x-llms-txt:|^link:"
      curl -sI https://docs.mnemom.ai/for-agents.md | grep -i "content-type:"
      curl -sI https://docs.mnemom.ai/llms.txt
      curl -sI https://docs.mnemom.ai/llms-full.txt
    expectation: All four return 200; markdown responses include text/markdown content-type and the discovery headers
    ciScript: scripts/verify/docs-markdown-negotiation.ts

  - id: agents-md-discovery
    title: Every public Mnemom repo has an AGENTS.md at its root
    rationale: >
      Anthropic's AGENTS.md convention. Coding agents (Claude Code,
      Cursor, Cline, Aider) cloning a public Mnemom repo find a tailored
      entry point alongside README.md — install/test/build commands,
      project layout, conventions, what NOT to do. Different audience
      from agents.txt and from this page (both target agents *using* the
      product); AGENTS.md targets agents *working on* the codebase.
      Coverage is the six public canonical repos&#58; aap, aip,
      aip-otel-exporter, mnemom-types, reputation-check, docs.
      (mnemom-platform was deliberately taken private in June 2026; it
      still ships AGENTS.md, as do all private repos, but only public
      ones are externally verifiable.)
    verifyCli: |
      for r in aap aip aip-otel-exporter mnemom-types reputation-check docs; do
        curl -sI "https://raw.githubusercontent.com/mnemom/$r/main/AGENTS.md" | head -1
      done
    expectation: All six return HTTP 200 on raw.githubusercontent.com
    ciScript: scripts/verify/agents-md-discovery.ts

  - id: public-verification
    title: These commitments are re-verified nightly against production
    rationale: >
      A commitment without enforcement is marketing. Every commitment
      above is checked nightly by a GitHub Actions watchdog running
      this same manifest. Results are written to
      agent-readiness-status.json, committed to main, and surfaced as
      a status badge at the top of /for-agents. If verification fails,
      a GitHub issue auto-opens and the badge turns red.
    verifyCli: |
      curl -s https://www.mnemom.ai/agent-readiness-status.json | \
        jq -r '"Last verified: \(.lastVerified) — \(.summary)"'
    expectation: Manifest lastReviewed within reviewCadenceDays; status JSON lastVerified within 36 hours; summary reports pass count
    ciScript: scripts/verify/manifest-freshness.ts

  - id: pricing-coherence
    title: Pricing tiers agree with themselves across every surface
    rationale: >
      Agents reading mnemom.ai get one price per tier — never a $79
      claim on the homepage FAQ and a $99 Offer schema on /pricing in
      the same crawl. JSON-LD Offers, schema descriptions, markdown
      mirrors, and the rendered DOM all carry the same number. Built
      after a May 2026 audit found Team-tier prices disagreeing on the
      same domain, the exact failure class our Coherence Report would
      flag against a competitor.
    verifyCli: |
      curl -s https://www.mnemom.ai/pricing/ | grep -oE '"price":"[0-9]+"'
      curl -s https://www.mnemom.ai/ | grep -oE 'Team tier is \$[0-9]+/month'
    expectation: Every Team-tier price reference on every prerendered page returns the same dollar figure
    ciScript: scripts/verify/pricing-coherence.ts

  - id: sitemap-freshness
    title: sitemap.xml lastmod never lags the page's JSON-LD dateModified
    rationale: >
      Crawlers prioritize sitemap lastmod for re-crawl scheduling. If
      the sitemap says 2026-01-15 while the page's JSON-LD says
      2026-05-08, we're under-signaling freshness to exactly the
      LLM-crawler audience this commitment is courting. The fix:
      sitemap lastmod is derived per-deploy from each route's
      JSON-LD dateModified (server/routes/sitemap.ts reads
      route-dates.json, written at build time by
      scripts/build-route-dates.mjs), so by construction lastmod >=
      dateModified.
    verifyCli: |
      curl -s https://www.mnemom.ai/sitemap.xml | grep -A1 '<loc>https://www.mnemom.ai/pricing/</loc>' | grep '<lastmod>'
      curl -s https://www.mnemom.ai/pricing/ | grep -oE '"dateModified":"[^"]+"'
    expectation: For every <url> in sitemap.xml whose page emits a JSON-LD dateModified, sitemap lastmod >= dateModified
    ciScript: scripts/verify/sitemap-coherence.ts

  - id: preview-surface
    title: Every URL has a structured preview manifest
    rationale: >
      OG images are a human-facing preview surface. Markdown mirrors
      are an agent-facing full-content surface. The gap between them
      — a one-fetch typed summary an agent can ingest without rendering
      HTML or parsing markdown — is the agent-preview/v1 manifest. Every
      prerendered URL on mnemom.ai exposes a sibling <url>.preview.json
      with the same fields humans see in the OG image, but structured:
      title, summary, type, representations (html / markdown / image /
      json_ld), per-type context (author, reading time, agent grade,
      coherence-report status, etc.), and a publisher pointer back to
      the agent-readiness manifest. The schema is versioned, MIME-typed
      (application/vnd.agent-preview+json), and discoverable via
      <link rel="alternate"> in every page's head. Mnemom is the
      reference implementation; the spec is vendor-neutral so other
      sites can adopt it.
    verifyCli: |
      curl -sH 'Accept: application/vnd.agent-preview+json' https://www.mnemom.ai/methodology/index.preview.json | jq '.spec_url, .type, .title, .representations'
    expectation: Every prerendered route in STATIC_MARKETING_PATHS has a sibling <route>.preview.json that validates against the agent-preview/v1 schema and contains canonical_url, title, summary, representations, and a publisher block.
    ciScript: scripts/verify/preview-surface.ts

  - id: trust-subdomain-surface
    title: trust.mnemom.ai ships the same agent-readability surface as the apex
    rationale: >
      The Trust Center moved to its own subdomain
      (trust.mnemom.ai) to canonicalize the security/compliance pages
      independently of the marketing apex — a pattern that matches
      Cloudflare, Stripe, and OpenAI. Every standing /for-agents
      commitment that applies to the apex (markdown mirror, preview
      manifest, JSON-LD, agents.txt / llms.txt discovery) applies to
      the trust subdomain too, in all five EFIGS locales. No
      English-fallback hand-waving on a regulator-facing surface.
    verifyCli: |
      curl -sI https://trust.mnemom.ai/index.md
      curl -sI https://trust.mnemom.ai/index.preview.json
      curl -sI https://trust.mnemom.ai/slos.md
      curl -sI https://trust.mnemom.ai/slos.preview.json
      curl -sI https://trust.mnemom.ai/fr.md
      curl -sI https://trust.mnemom.ai/fr/slos.md
      curl -sI https://trust.mnemom.ai/agents.txt
      curl -sI https://trust.mnemom.ai/llms.txt
      curl -sL https://trust.mnemom.ai/fr/slos | grep -oE '<link rel="canonical"[^>]+>'
    expectation: All `.md` + `.preview.json` siblings return 200 with the right content-type (text/markdown / application/vnd.agent-preview+json); /agents.txt + /llms.txt return 200; each locale page's canonical points at trust.mnemom.ai/&lt;locale&gt;/...
    ciScript: scripts/verify/trust-subdomain-surface.ts

  - id: r-shield-enforcement
    title: Private coherence-report share-links are shielded from crawlers and indexers
    rationale: >
      Pre-claim, /r/&lt;slug&gt; URLs are private shareable links to a
      named client. Anyone with the URL can visit it in a browser
      (that's the point — the URL is the access-control mechanism per
      ADR-043), but the content is potentially sensitive to the
      client and MUST NOT be read by AI training crawlers, indexers,
      or shared into public search results. Coherence reports
      synthesize publicly-available information into commentary that
      may be unflattering to the subject org; they are produced as a
      courtesy to the client and are deliberately invisible to
      crawlers, indexers, and agents. Five layered defenses&#58;
      (L1) public/robots.txt disallows /r/ for every named crawler
      User-agent, including the 14 AI bots we explicitly opt INTO
      the marketing surface; (L2) netlify.toml sets X-Robots-Tag&#58;
      noindex, nofollow, noarchive, nosnippet, noimageindex on every
      /r/* response; (L3) a Netlify edge function
      (netlify/edge-functions/r-shield.ts) hard-403s the 21 named
      crawler + indexer User-agents AND any UA matching the generic
      bot|crawler|spider|agent pattern (defense-in-depth for honest
      agents not on our explicit allowlist) at the edge with no SPA
      shell; (L4) the same edge function serves a generic on-brand
      coherence-report OG card to humans + share-previewers, with NO
      slug-lookup, so fake-vs-real slugs produce byte-identical
      responses (ADR-043 side-channel preserved); (L5) the privacy
      invariant: /r/&lt;slug&gt; intentionally has no machine-readable
      mirror — .md, .preview.json, and .json variants return 404, not
      shielded content, so honest agents reading a coherence-report
      URL through any of those discovery mechanisms get an
      unambiguous "this surface is not for you" signal. The blocklist
      single source of truth is the inlined arrays in
      netlify/edge-functions/r-shield.ts (Netlify's bundler rejects
      underscore-prefixed sibling helper modules, so SSOT and consumer
      share one file); every entry carries a provenance comment naming
      the vendor + their documented crawler page. This is the
      private-surface complement to the marketing-surface stance below
      ("we do not block crawlers").
    verifyCli: |
      curl -sI -A 'GPTBot' https://www.mnemom.ai/r/test-shield | head -1
      curl -s -A 'Slackbot 1.0' https://www.mnemom.ai/r/test-shield | grep -oE 'og:image[^>]+type=coherence-report'
      curl -sI https://www.mnemom.ai/r/test-shield.md            | head -1
      curl -sI https://www.mnemom.ai/r/test-shield.preview.json  | head -1
      curl -sI https://www.mnemom.ai/r/test-shield.json          | head -1
    expectation: GPTBot / ClaudeBot / Googlebot (and 18 other named AI/indexer UAs) plus any generic *bot/*Crawler/*Spider/*Agent UA receive 403 at the edge. Slackbot / Twitterbot / browsers receive 200 with a generic coherence-report OG card and noindex meta. Two fake slugs produce byte-identical responses (no existence side-channel). .md / .preview.json / .json variants of any /r/&lt;slug&gt; URL return 404 (no machine-readable mirror).
    ciScript: scripts/verify/r-shield-enforcement.ts

  - id: ai-training-stance
    title: Mnemom permits AI model training on public marketing content
    rationale: >
      Mnemom's public marketing surfaces (mnemom.ai, docs.mnemom.ai,
      trust.mnemom.ai) are open for AI model training, retrieval-augmented
      generation, fine-tuning, and derived works. No permission required,
      no API key needed, no attribution fee. We ask (but do not require)
      that training datasets credit Mnemom when citing research papers
      or integration code. The stance is published in three places that
      this verifier asserts agree&#58; (1) public/robots.txt header
      ("training-data consumption by design"), (2) public/agents.txt
      metadata block (`training_data_policy: allowed`), (3) this
      commitment body. The PRIVATE surface stance — coherence reports
      at /r/&lt;slug&gt; — is the opposite (see commitment #13) and is
      independently enforced. This commitment is about the marketing
      surface only.
    verifyCli: |
      curl -s https://www.mnemom.ai/robots.txt | grep -i 'training-data consumption'
      curl -s https://www.mnemom.ai/agents.txt | grep -E '^training_data_policy:\s*allowed'
    expectation: 'robots.txt header carries the "training-data consumption" phrase; agents.txt metadata carries training_data_policy=allowed.'
    ciScript: scripts/verify/ai-training-stance.ts

  - id: og-twitter-coverage
    title: Every prerendered page emits a complete Open Graph + Twitter Card
    rationale: >
      Social-preview metadata is the human-facing companion to the
      machine-readable JSON-LD (#3) and markdown-mirror (#4) surfaces.
      Every prerendered marketing route emits at minimum&#58;
      og:title, og:description, og:image, og:url, og:type,
      twitter:card, twitter:title, twitter:description, twitter:image.
      The route-meta.ts emitter is the single source of truth; this
      verifier samples representative prerendered routes (apex,
      pricing, methodology, how-it-works, showcase, for-agents, plus
      two EFIGS variants) and asserts every required meta tag is
      present and has a non-empty content attribute. Catches drift if
      a route's `meta` export accidentally omits a field or if
      route-meta.ts loses a tag during refactor.
    verifyCli: |
      curl -sL https://www.mnemom.ai/pricing/ | grep -oE '<meta\s+property="og:[a-z]+"' | sort -u | wc -l
      curl -sL https://www.mnemom.ai/pricing/ | grep -oE '<meta\s+name="twitter:[a-z]+"' | sort -u | wc -l
    expectation: "At least 5 distinct og:* tags and at least 4 distinct twitter:* tags on every sampled prerendered route."
    ciScript: scripts/verify/og-twitter-coverage.ts

  - id: well-known-surfaces
    title: /.well-known/ discovery files are well-formed and standards-compliant
    rationale: >
      The `/.well-known/` namespace is where agents look for
      machine-readable discovery surfaces without prior knowledge.
      This verifier asserts several of them are well-formed&#58;
      (1) `/.well-known/security.txt` is RFC 9116-compliant — required
      fields (Contact, Expires, Canonical) present, Expires in the
      future, and Preferred-Languages enumerating every locale the
      site ships in (en, fr, de, it, es) so reports can land in any of
      those, anything less narrowing the disclosure channel below the
      customer surface; (2) `/.well-known/api-catalog` (RFC 9727) is a
      valid linkset pointing at the live OpenAPI 3.1 spec; (3)
      `/.well-known/oauth-protected-resource` (RFC 9728) names the
      www.mnemom.ai origin as a protected resource (same-origin) and
      lists its authorization servers; (4)
      `/.well-known/oauth-authorization-server` (RFC 8414) is valid JSON
      with a well-formed issuer and an `agent_auth` registration profile;
      and (5) `/.well-known/agent-card.json` is a
      valid A2A-style service card. The public MCP server card at
      `.well-known/mcp/server-card.json` is now present and points at the
      live `https://api.mnemom.ai/mcp` control-plane endpoint; it is
      validated by the dedicated `mcp-server` verifier (see roadmap —
      live and soaking toward a numbered commitment), not by this one,
      which keeps each verifier scoped to one surface cluster.
    verifyCli: |
      curl -s https://www.mnemom.ai/.well-known/security.txt | grep -E '^(Contact|Expires|Canonical|Preferred-Languages):'
      curl -s https://www.mnemom.ai/.well-known/api-catalog | jq '.linkset[0].anchor'
      curl -s https://www.mnemom.ai/.well-known/oauth-protected-resource | jq '.authorization_servers'
      curl -s https://www.mnemom.ai/.well-known/oauth-authorization-server | jq '.issuer'
      curl -s https://www.mnemom.ai/.well-known/agent-card.json | jq '.name'
    expectation: "security.txt declares Contact + Expires (in the future) + Canonical + Preferred-Languages covering en, fr, de, it, es; api-catalog, oauth-protected-resource, oauth-authorization-server, and agent-card.json each parse as valid JSON with their expected key fields present. The PRM names www.mnemom.ai as a same-origin resource with non-empty scopes_supported and bearer_methods_supported including header; the authorization-server doc carries issuer https://www.mnemom.ai plus a complete agent_auth registration method (anonymous, id-jag, or verified_email)."
    ciScript: scripts/verify/well-known-surfaces.ts

  - id: api-auth-discovery
    title: API, auth, and agent-skill discovery surfaces are published and resolvable
    rationale: >
      An agent that lands on www.mnemom.ai with no prior knowledge can
      now discover the API, how to authenticate against it, and what
      skills it can invoke — entirely from standard discovery files.
      `/.well-known/api-catalog` (RFC 9727) is a linkset whose
      service-desc points at the live OpenAPI 3.1 contract at
      api.mnemom.ai/openapi.json. Authentication is described honestly&#58;
      Mnemom delegates token issuance to Supabase GoTrue and mints no
      OAuth tokens of its own, so
      `/.well-known/oauth-protected-resource` (RFC 9728) names the
      www.mnemom.ai origin as the protected resource (same-origin, as
      RFC 9728 requires; the API surface has its own origin-matched PRM
      at api.mnemom.ai) and lists its authorization servers (Mnemom's
      first-party AS metadata at www.mnemom.ai plus the upstream Supabase
      GoTrue issuer).
      `/.well-known/oauth-authorization-server` (RFC 8414) declares
      issuer https://www.mnemom.ai, points its token / authorize / jwks
      endpoints at that upstream Supabase IdP, and carries an `agent_auth`
      profile describing Mnemom's agent-registration flow
      (POST /v1/agents → claim). `/auth.md` is the human- and
      agent-readable auth guide — it states plainly that the two real
      schemes are a Supabase-issued bearer JWT and a Mnemom
      `mnm_`-prefixed API key, documents the agent-registration flow, and
      clarifies that Mnemom mints no OAuth tokens of its own. Invokable
      skills are listed under `/.well-known/agent-skills/*`, each backed
      only by a real public endpoint, and `/.well-known/agent-card.json`
      is an A2A-style service card describing the same surface. HTTP
      `Link` headers on the relevant routes advertise these so an agent
      can find them from the response headers alone. Every URL named
      here resolves to something real today; nothing is aspirational.
    verifyCli: |
      curl -sI https://www.mnemom.ai/auth.md | head -2
      curl -s https://www.mnemom.ai/.well-known/api-catalog | head -c 80
      curl -s https://www.mnemom.ai/.well-known/agent-skills/index.json | jq '.skills | length'
    expectation: "auth.md is served FLAT at the root (no 3xx redirect) with Content-Type text/markdown, an H1 containing \"auth.md\", and a \"Bearer\" mention; api-catalog, oauth-protected-resource, oauth-authorization-server, and agent-card.json each return valid JSON; the agent-skills index (/.well-known/agent-skills/index.json) resolves and lists skills."
    ciScript: scripts/verify/api-auth-discovery.ts

# What we deliberately don't do — public negative space.
# Renders on /for-agents under "What we deliberately don't do".
exclusions:
  - We do not serve different HTML to bot user-agents on any marketing surface. There is no cloaking.
  - We do not gate documentation, API references, or integration code behind login.
  - We do not paywall the protocols. AAP and AIP are Apache 2.0, forever.
  - We do not block search crawlers, AI crawlers, or fair-use indexers from the public marketing site (mnemom.ai, docs.mnemom.ai). The marketing pitch is open by design — agents teaching their humans about Mnemom is part of the product. PRIVATE share-link surfaces (/r/<slug> coherence-report URLs pre-claim) ARE shielded — see commitment #13.
  - We do not require API keys or accounts to read agents.txt, llms.txt, or this page.
  - We do not put the main pitch behind JavaScript hydration. View-source proves it.

# Surface map — the canonical agent-facing surfaces, rendered as a
# linked-data signpost on /for-agents and emitted into JSON-LD as
# `subjectOf` / `mainEntity` references. Length is computed at render
# time so the page count stays in sync when entries are added or removed.
surfaces:
  - role: pitch
    label: agents.txt
    url: /agents.txt
    description: Second-person pitch to agents. English. Plaintext. Hand-crafted.
  - role: index
    label: llms.txt
    url: /llms.txt
    description: Curated map of every marketing URL, with one-line descriptions.
  - role: index-full
    label: llms-full.txt
    url: /llms-full.txt
    description: Same map with full descriptions for deeper crawls.
  - role: integration
    label: docs.mnemom.ai/for-agents
    url: https://docs.mnemom.ai/for-agents
    description: Integration documentation. Quickstarts, SDK, gateway, self-hosted. Every page also at <path>.md and via Accept&#58; text/markdown.
  - role: docs-index
    label: docs.mnemom.ai/llms.txt
    url: https://docs.mnemom.ai/llms.txt
    description: Auto-generated llms.txt index for the docs surface. Pair with llms-full.txt for full-description crawls.
  - role: docs-index-full
    label: docs.mnemom.ai/llms-full.txt
    url: https://docs.mnemom.ai/llms-full.txt
    description: Full-description index of every docs page, suitable for high-context retrieval.
  - role: identity
    label: /claim
    url: /claim
    description: Claim a verifiable identity in the Mnemom Trust Directory.
  - role: alignment-card
    label: /.well-known/alignment-card.json
    url: /.well-known/alignment-card.json
    description: >-
      Mnemom's own AAP (Agent Alignment Protocol) public card. JSON, served
      per the AAP spec for cross-agent discovery and value-coherence
      handshakes. Content-Type&#58; application/json.
  - role: api-catalog
    label: /.well-known/api-catalog
    url: /.well-known/api-catalog
    description: >-
      RFC 9727 linkset pointing at the live OpenAPI 3.1 spec
      (api.mnemom.ai/openapi.json), the docs, the protected-resource
      metadata, and status. Content-Type&#58; application/linkset+json.
  - role: oauth-protected-resource
    label: /.well-known/oauth-protected-resource
    url: /.well-known/oauth-protected-resource
    description: >-
      RFC 9728 protected-resource metadata for the www.mnemom.ai origin
      (same-origin resource; the Mnemom API surface has its own
      origin-matched PRM at api.mnemom.ai). Lists the authorization servers
      (Mnemom's first-party AS metadata at www.mnemom.ai plus the upstream
      Supabase GoTrue issuer) and points at auth.md. Content-Type&#58; application/json.
  - role: oauth-authorization-server
    label: /.well-known/oauth-authorization-server
    url: /.well-known/oauth-authorization-server
    description: >-
      Mnemom's first-party authorization-server metadata (RFC 8414,
      issuer https://www.mnemom.ai). Delegates token issuance to the
      upstream Supabase GoTrue IdP — Mnemom mints no OAuth tokens of its
      own — and carries an agent_auth profile describing the
      agent-registration flow. Content-Type&#58; application/json.
  - role: auth-guide
    label: /auth.md
    url: /auth.md
    description: >-
      Human- and agent-readable authentication guide. Documents the two
      real schemes (Supabase-issued bearer JWT and mnm_ API key), the agent
      registration flow, and states plainly that Mnemom delegates token
      issuance to Supabase and mints no OAuth tokens of its own.
      Content-Type&#58; text/markdown.
  - role: agent-skills
    label: /.well-known/agent-skills/index.json
    url: /.well-known/agent-skills/index.json
    description: >-
      Index of invokable agent skills, each backed by a real public Mnemom
      API endpoint, with per-skill SKILL.md manifests. Content-Type&#58;
      application/json.
  - role: agent-card
    label: /.well-known/agent-card.json
    url: /.well-known/agent-card.json
    description: >-
      A2A-style service card describing the Mnemom API, its security schemes,
      and its skills for cross-agent discovery. Content-Type&#58;
      application/json.
  - role: ioc-feed
    label: api.mnemom.ai/v1/trust/iocs
    url: https://api.mnemom.ai/v1/trust/iocs
    description: >-
      Public STIX 2.1 indicator-of-compromise bundle. Live; empty at GA by
      design (the system tells the truth). Filter by ?type=&lt;indicator-type&gt;
      and ?after=&lt;ISO-8601&gt;. Content-Type&#58; application/stix+json;version=2.1.
  - role: threat-state
    label: api.mnemom.ai/v1/network/threat-state
    url: https://api.mnemom.ai/v1/network/threat-state
    description: >-
      Per-axis network threat-level JSON (substrate / vertical / pattern /
      source) with totals and per-bucket state transitions. Live. Requires
      an authenticated session. Content-Type&#58; application/json.
  - role: advisories
    label: api.mnemom.ai/v1/trust/advisories
    url: https://api.mnemom.ai/v1/trust/advisories
    description: >-
      Post-incident advisory JSON list — title, summary, severity, slug,
      published_at. Live; one synthetic GA-seed advisory at launch by design.
      Per-advisory body at /v1/trust/advisories/&lt;slug&gt;. Content-Type&#58;
      application/json.
  - role: mcp-card
    label: /.well-known/mcp/server-card.json
    url: /.well-known/mcp/server-card.json
    description: >-
      MCP server card (MCP server.json shape) advertising the live
      control-plane MCP server. Point any MCP client at the remote it names.
      Content-Type&#58; application/json.
  - role: mcp
    label: api.mnemom.ai/mcp
    url: https://api.mnemom.ai/mcp
    description: >-
      Control-plane MCP server (streamable-HTTP). 62 tools mirroring the
      mnemom CLI — Trust Ratings, Alignment &amp; Protection Cards, governance
      signals, postures, teams, webhooks, API keys. tools/list is public;
      tool execution authenticates as the REST API (Bearer JWT or
      X-Mnemom-Api-Key).
  - role: mcp
    label: docs.mnemom.ai/mcp
    url: https://docs.mnemom.ai/mcp
    description: >-
      Read-only docs-search MCP server (streamable-HTTP). Tools&#58;
      search_mnemom_docs and query_docs_filesystem over the documentation and
      the OpenAPI spec. No auth.

# Intent routing — what an agent landing on /for-agents most often
# needs next, grouped by intent. Rendered as a "Where to look" block
# near the top of the page. Pure navigation: changes only when site
# surfaces change, so the maintenance debt is bounded.
intentRouting:
  - intent: integrate Mnemom
    destinations:
      - { label: Quickstart, url: "https://docs.mnemom.ai/quickstart" }
      - { label: SDK reference, url: "https://docs.mnemom.ai/sdk" }
      - { label: Self-hosted, url: "/docs/self-hosted" }
  - intent: connect over MCP
    destinations:
      - { label: Control plane (api.mnemom.ai/mcp), url: "https://api.mnemom.ai/mcp" }
      - { label: Docs search (docs.mnemom.ai/mcp), url: "https://docs.mnemom.ai/mcp" }
      - { label: Server card, url: "/.well-known/mcp/server-card.json" }
      - { label: Install configs, url: "https://docs.mnemom.ai/mcp-clients" }
  - intent: evaluate before integrating
    destinations:
      - { label: Showcase, url: "/showcase" }
      - { label: Arena, url: "/arena" }
      - { label: Sample report, url: "/report/sample" }
  - intent: price the platform
    destinations:
      - { label: Pricing, url: "/pricing" }
      - { label: Enterprise, url: "/enterprise" }
  - intent: research agent governance, safety, trust, or security
    destinations:
      - { label: Methodology, url: "/methodology" }
      - { label: Research, url: "/research" }
      - { label: Governance, url: "/governance" }
      - { label: Security, url: "/security" }
      - { label: What we prove, url: "/what-we-prove" }
  - intent: build on our open protocols
    destinations:
      - { label: AAP, url: "https://github.com/mnemom/aap" }
      - { label: AIP, url: "https://github.com/mnemom/aip" }
      - { label: agent-preview/v1 spec, url: "/spec/agent-preview/v1" }
  - intent: verify or claim an identity
    destinations:
      - { label: Trust Directory, url: "/directory" }
      - { label: Claim a card, url: "/claim" }
  - intent: look up one of our terms
    destinations:
      - { label: Glossary, url: "/glossary" }

# Roadmap items publicly named on /for-agents under "What's coming".
# These are commitments-in-flight, not yet enforced. Each should turn
# into a numbered commitment when shipped.
roadmap:
  - id: mcp-server-card
    title: Promote the live MCP servers to a numbered commitment
    note: >-
      Two public Model Context Protocol servers are LIVE today: the control
      plane at https://api.mnemom.ai/mcp (62 tools mirroring the mnemom CLI;
      tool execution authenticates exactly as the REST API) and docs search
      at https://docs.mnemom.ai/mcp (read-only). The control-plane server
      card is published at /.well-known/mcp/server-card.json. The dedicated
      verifier scripts/verify/mcp-server.ts is implemented and registered
      and checks both endpoints plus the card. This item remains on the
      roadmap — rather than in commitments — ONLY until that verifier
      clears the standard 7-consecutive-green-night soak (AGENTS.md), at
      which point it is promoted to a numbered commitment. The surfaces are
      real now (see auth.md and the MCP rows in the surface map); only the
      versioned green *commitment* is pending soak.