API Evangelist enhancements for the BioAegis Therapeutics Content API

# authorship: generated by API Evangelist tooling. Stamped 2026-08-18
# on the file's own generator header (roadmap#64). An unmarked file is
# NOT assumed to be ours -- absence of evidence was never stamped.
x-method: generated
overlay: 1.0.0
info:
  title: API Evangelist enhancements for the BioAegis Therapeutics Content API
  version: '1.0.0'
  x-generated: '2026-08-07'
  x-method: generated
  x-source: >-
    Generated by the API Evangelist enrichment pipeline from live anonymous probes of
    https://www.bioaegistherapeutics.com/wp-json/ on 2026-08-07, plus the artifacts in this repo.
  x-summary: >-
    This overlay records the enhancements API Evangelist applies on top of the derived OpenAPI in
    openapi/bioaegis-therapeutics-content-openapi.yml. BioAegis Therapeutics publishes no OpenAPI,
    so the base document is itself a derivation; this overlay is kept separate so the base stays a
    faithful projection of the route index while the operational knowledge — WAF behaviour, empty
    collections, response-size traps, the broken author arc — lives here and can be re-applied
    after any re-harvest.
extends: ./../openapi/bioaegis-therapeutics-content-openapi.yml
actions:
  - target: $.info
    update:
      x-provider-publishes-spec: false
      x-derivation: >-
        Derived from the WordPress REST route index at
        https://www.bioaegistherapeutics.com/wp-json/ (308 routes, 17 namespaces), restricted to
        the 23 operations verified to answer anonymously on 2026-08-07.
      x-edge: >-
        Fronted by a Sucuri CloudProxy WAF (Server: Sucuri/Cloudproxy). The WAF, not WordPress,
        answers /wp/v2/users with a 403 HTML interstitial, and marks every REST response
        X-Sucuri-Cache: BYPASS.
      x-artifacts:
        authentication: ../authentication/bioaegis-therapeutics-authentication.yml
        conventions: ../conventions/bioaegis-therapeutics-conventions.yml
        errors: ../errors/bioaegis-therapeutics-problem-types.yml
        lifecycle: ../lifecycle/bioaegis-therapeutics-lifecycle.yml
        conformance: ../conformance/bioaegis-therapeutics-conformance.yml
        data_model: ../data-model/bioaegis-therapeutics-data-model.yml
        json_ld: ../json-ld/bioaegis-therapeutics-json-ld.yml
        well_known: ../well-known/bioaegis-therapeutics-well-known.yml
        skills: ../skills/_index.yml

  - target: $
    update:
      x-rate-limits:
        published: false
        note: >-
          No RateLimit or Retry-After headers observed. The Sucuri WAF may throttle or challenge
          aggressive callers without advertising a budget. Crawl politely; there is no published
          allowance to plan against.
      x-caching:
        etag: false
        last_modified: false
        cache_control: none-observed
        note: >-
          Conditional requests are impossible. Use each object's `modified` field for change
          detection, or poll /sitemap_index.xml lastmod for a cheaper coarse signal.

  - target: $.paths['/wp/v2/posts'].get
    update:
      x-collection-size: 153
      x-category-breakdown:
        news: 94
        publication: 34
        event: 9
        clinical: 6
        leadership: 5
        board: 4
        feature: 2
        covid19: 1
        uncategorized: 1
      x-response-size-warning: >-
        `content.rendered` is populated on every post. An unfiltered per_page=100 request returns
        several megabytes. Always send `_fields`.
      x-recommended-projection: 'id,slug,title,link,date,modified,categories,featured_media'

  - target: $.paths['/wp/v2/pages'].get
    update:
      x-collection-size: 14
      x-response-size-warning: >-
        Page bodies are rendered Elementor markup. Page 5753 (Our Platform) returns ~100KB and page
        5277 (Our Science) ~45KB in `content.rendered` alone. Always send `_fields` unless you
        genuinely want the markup.
      x-hierarchy: flat
      x-hierarchy-note: '`parent` is 0 on all 14 pages — there is no page tree to walk.'

  - target: $.paths['/wp/v2/tags'].get
    update:
      x-empty-collection: true
      x-empty-reason: >-
        The `post_tag` taxonomy is registered but holds 0 terms. All classification on this site is
        carried by the hierarchical `category` taxonomy. Do not build a tag-based integration.

  - target: $.paths['/wp/v2/comments'].get
    update:
      x-empty-collection: true
      x-empty-reason: Comments are not used on this site (X-WP-Total 0).

  - target: $.paths['/wp/v2/blocks'].get
    update:
      x-empty-collection: true
      x-empty-reason: The site is authored in Elementor, not the block editor.

  - target: $.paths['/wp/v2/navigation'].get
    update:
      x-empty-collection: true
      x-empty-reason: >-
        Block-editor navigation is unused. The real site navigation lives in classic menus at
        /wp/v2/menus and /wp/v2/menu-locations, both of which return 401 anonymously.

  - target: $.paths['/wp/v2/search'].get
    update:
      x-observed-result-counts:
        gelsolin: 137
        ards: not-recorded
      x-note: >-
        The only full-text entry point on the surface. Returns lightweight records — resolve
        `id` + `subtype` against /wp/v2/posts/{id} or /wp/v2/pages/{id} for the body.

  - target: $.paths['/yoast/v1/get_head'].get
    update:
      x-plugin-dependency: Yoast SEO
      x-fragility: >-
        This operation exists only because the Yoast SEO plugin is installed. It is the single
        richest structured-data source on the surface — it carries the schema.org JSON-LD @graph —
        and it would disappear without notice if the plugin were removed. Treat as unstable.
      x-graph-nodes: [WebPage, ImageObject, BreadcrumbList, WebSite, Organization]

  - target: $.paths['/oembed/1.0/embed'].get
    update:
      x-sibling-gated: >-
        /oembed/1.0/proxy, which would fetch third-party URLs, returns 401 rest_forbidden. Only the
        provider endpoint for bioaegistherapeutics.com URLs is anonymous.

  - target: $.components.schemas.Post.properties.author
    update:
      x-unresolvable: true
      x-unresolvable-reason: >-
        /wp/v2/users returns 403 from the Sucuri WAF (HTML, not JSON), so this foreign key cannot be
        dereferenced and `_embed` on the author link relation returns an error stub. Observed value
        on every sampled record: 2. The author-sitemap.xml does publish three author slugs
        (admin, serrao6, sserrao), so the two surfaces disagree about whether authorship is public.

  - target: $.components.schemas.Page.properties.author
    update:
      x-unresolvable: true
      x-unresolvable-reason: Same WAF block as Post.author.

  - target: $.components.schemas.Post.properties.tags
    update:
      x-always-empty: true

  - target: $.components.schemas.Post.properties.meta
    update:
      x-effectively-empty: true
      x-note: >-
        The Elementor page-builder payload lives in unregistered post meta that WordPress does not
        project into REST, so `meta` yields nothing useful. The rendered result is in
        `content.rendered` instead.

  - target: $.components.schemas.RestError
    update:
      x-not-uniform: >-
        This envelope covers every error EXCEPT /wp/v2/users, which the Sucuri WAF answers in HTML.
        A generic client must branch on Content-Type before parsing an error body.
      x-status-semantics: >-
        WordPress returns 401 (not 403) for capability refusals to anonymous callers for whom no
        credential exists. Clients implementing retry-with-credentials will loop.