agent-first-web-avl-review

name	agent-first-web-avl-review
description	Review, position, and polish Agent View Layer (AVL) / agent-first web projects: .agent pages, agent.txt manifests, AI-native rendering, MCP/API positioning, and marketing/category narrative.
version	1.0.0
author	Hermes Agent
license	MIT
tags	["agent-first-web","avl","ai-agents","product-positioning","web-standards","mcp","marketing"]
triggers	["review AVL","agent-first website","AI-first website",".agent endpoint","agent.txt manifest","agents as first-class internet citizens","APIs are going away","MCP is the hands AVL is the eyes"]

Agent-First Web / AVL Review

Use this skill when reviewing or polishing projects that claim to make websites/applications agent-native, especially frontier-infra/avl, .agent endpoints, agent.txt, MCP-adjacent tools, AI-first websites, and agent commerce surfaces.

Core Thesis to Preserve

The user’s thesis:

• AI agents are first-class internet citizens.
• Agent traffic and business commerce may exceed human web usage.
• The internet is still primarily built for humans: HTML/CSS/JS, screens, DOM, mice, forms, pixels.
• Browser-use agents are impressive but fragile because they reverse-engineer human interfaces.
• New applications should become agent-first / AI-first, analogous to mobile-first design.
• APIs are necessary now, but many user-facing machine workflows may move toward agent-native web surfaces rather than bespoke API integrations.

Preferred framing nuance:

Do not bluntly claim “APIs will disappear” in public-facing copy unless the user specifically wants the provocative version. A more defensible framing is:

• APIs are not enough for the agent-first web.
• APIs expose functions; AVL exposes what matters on the current page.
• OpenAPI describes your backend; AVL describes the user’s current surface.
• APIs remain infrastructure, but they may stop being the primary user-facing machine interface for many workflows.

AVL Category Framing

AVL = Agent View Layer.

Best category phrase:

Agent-native rendering.

Avoid reducing AVL to “metadata for AI.” Metadata sounds optional, SEO-ish, and decorative. “Rendering target” sounds infrastructural.

Core analogy:

• HTML is for humans.
• AVL is for agents.
• Like i18n, but the target locale is agent.
• Like mobile-first, but for AI agents.

Strong one-liners:

• Make every web page agent-readable.
• The web was built for people. AVL makes it legible to agents.
• Stop making agents scrape meaning from pixels.
• Your app already knows what each page means. AVL ships that meaning directly.
• Every page your app serves to humans gets a parallel agent view.
• The page already knows what it means. We just don’t ship that knowledge.

Conceptual Distinctions

Use these distinctions when explaining AVL:

• Scraping: consumer-side recovery of meaning from pixels/DOM.
• AVL: producer-side rendering of meaning for agents.
• APIs/OpenAPI: backend function/catalog surfaces.
• AVL: page-level, situated, intent-rich user-surface rendering.
• MCP: tool/action protocol; “hands.”
• AVL: page/application perception and context; “eyes.”
• llms.txt: site-level guidance/discovery.
• AVL: route/page-level state, intent, actions, context, and navigation.

Important line:

MCP is the hands. AVL is the eyes.

Review Workflow

0. Distinguish AVL copy from AVL implementation.

   • A marketing/explainer page about AVL is not the same as an AVL-enabled site.
   • For sites claiming page-distributed AVL, verify actual surfaces exist before saying the work is correct:
     • curl -i https://site/agent.txt
     • curl -i https://site/.agent
     • curl -i -H "Accept: text/agent-view" https://site/
     • curl -i https://site/some-route.agent
   • Expected implementation evidence:
     • real agent.txt manifest, not SPA HTML fallback
     • .agent companion routes for meaningful human pages
     • Content-Type: text/agent-view; charset=utf-8; version=1 or equivalent
     • content negotiation for Accept: text/agent-view
     • per-page alternate discovery via HTTP Link header and/or HTML <link rel="alternate" type="text/agent-view" href="...">
     • page-specific AVL content using @meta, @intent, @state, @actions, @context, @nav
   • If .agent, agent.txt, or Accept: text/agent-view return the normal React/SPA HTML shell, the distributed AVL layer is not implemented even if the public copy describes it accurately.

1. Inspect the repo and docs.

   • Use GitHub API/browser rather than only reading the landing page.
   • Check README, package.json, specs, examples, implementation files, release metadata, license, stars/forks, commit activity, default branch.
   • For frontier-infra/avl, key paths have included:
     • README.md
     • package.json
     • specs/avl-agent-view-layer.md
     • specs/avl-thesis.md
     • specs/avl-auth-thesis.md
     • lib/avl/types.ts
     • lib/avl/serialize.ts
     • lib/avl/define.ts
     • src/index.ts
     • src/next.ts

2. Verify live agent endpoints if available.

   • Try:
     • curl -s https://site/.agent
     • curl -s -H "Accept: text/agent-view" https://site/
     • curl -s https://site/agent.txt
   • Check Content-Type, route, generated timestamp, TTL, auth/session declaration, sections, and action links.

3. Evaluate the AVL document shape.

   • Good AVL documents usually include:
     • @meta: version, route, generated timestamp, TTL, auth context
     • @intent: purpose, audience, capability
     • @state: structured backing data, ideally token-efficient
     • @actions: available actions with method/href/input schema
     • @context: narrative explanation / meaning
     • @nav: self/parents/peers/drilldown
   • Confirm that .agent is not merely a scraped summary of HTML but a producer-side rendering of the same application/page state.

4. Evaluate auth and security.

   • The key AVL auth principle:
     • The AI agent is not a new principal. It is a delegate of an existing human session.
   • Look for “same session, same RBAC, different rendering target.”
   • Use/ask for a surface equivalence test:
     • The agent can only see and do what the human principal can see and do.
   • Flag any new shadow permission system or unfiltered sensitive data as a serious risk.

5. Connect to stack positioning.

   • For the user’s ecosystem, the relationship can be framed as:
     • vLLM gives agents local intelligence.
     • AINode gives the stack a private compute base.
     • ArgentOS gives agents memory and governance.
     • MCP gives agents hands.
     • AVL gives agents eyes.
     • AMP Cortex / business apps provide commerce/workflow surfaces.

6. Provide marketing polish.

   • Prefer category-design language over implementation-only language.
   • Show “Human View vs Agent View” visually or structurally.
   • Lead with the problem of reverse-engineering pixels, then introduce producer-side agent rendering.
   • Include proof artifacts: live .agent endpoint, agent.txt, examples, package install, spec, adopter badge.

Suggested Landing Page Structure

1. Hero

   • Headline: “Make every web page agent-readable.”
   • Subhead: “AVL gives every human page a parallel view for AI agents — intent, state, actions, context, and navigation without scraping.”
   • CTAs: “Read the Spec”, “Add AVL to Next.js”, “See a Live .agent View”

2. The shift

   • Agents are becoming first-class internet users.
   • The web still renders primarily for humans.
   • Browser-use agents are a bridge, not the destination.

3. Human view vs agent view

   • Show /products/kettle next to /products/kettle.agent.
   • The side-by-side should sell the concept faster than paragraphs.

4. How it works

   • .agent suffix
   • text/agent-view; version=1
   • agent.txt
   • content negotiation
   • colocated agent.ts beside page.tsx

5. The six sections

   • @meta, @intent, @state, @actions, @context, @nav

6. Auth and trust

   • Same session, same RBAC, different rendering target.
   • Surface equivalence.
   • Delegate, not principal.

7. AVL vs alternatives

   • Scraping, llms.txt, OpenAPI/GraphQL, Schema.org, ARIA, MCP.
   • Emphasize complementarity, not replacement of everything.

8. Live proof

   • Link/curl a live adopter, e.g. AINode if still available:
     • https://ainode.dev/.agent
     • https://ainode.dev/agent.txt

9. Developer adoption

   • Install package.
   • Add .agent route.
   • Define agent views.
   • Add badge/manifest.

Output Template

When the user asks for a review, produce:

Short verdict:

• One sentence on whether the concept/repo/site is credible and how to frame it.

What I checked:

• Repo/docs/specs/live endpoints.

What the idea really is:

• Explain agent-native rendering in plain language.

Why it matters:

• Explain the pixel/DOM reverse-engineering waste.

What is strong:

• Category, spec, implementation, auth model, live proof, ecosystem fit.

What to be careful about:

• Overclaiming APIs disappearing, security/auth, sounding like metadata/SEO, lack of demos.

Marketing polish:

• Hero copy, subhead, CTAs, section structure, core phrases.

Next steps:

• Specific site/docs/demo improvements.

Implementation Hardening Workflow

When implementing AVL on an existing marketing/docs site rather than merely reviewing it:

1. Build route parity from the application route map, not from memory. Compare public human routes, prerender routes, sitemap entries, and generated .agent entries.
2. Add a dedicated route-parity verifier that fails if any meaningful public route lacks a page-specific .agent companion, if agent.txt omits generated companions, or if sitemap/prerender coverage drifts.
3. Verify canonical HTML and agent surfaces separately: canonical URLs must remain text/html; .agent URLs and Accept: text/agent-view should return the agent representation; agent.txt must not be an SPA fallback.
4. For prerendered React/SPAs, check head metadata after hydration/prerender. Base index.html metadata plus route-level SEO components can leave duplicate title/canonical/OpenGraph/Twitter tags; add singleton head dedupe in prerender and server injection paths, then test it mechanically.
5. Prefer making prerender a required build step once AVL/crawler verification depends on generated HTML. Silent prerender fallbacks can make a build look green while breaking agent discovery and crawler parity.
6. Smoke-test against the same server path production will use, not only a static/Vite preview. Vite preview may serve built assets correctly while failing to exercise Express/Node content negotiation, dotfile .agent routing, per-route HTML fallbacks, or Accept: text/agent-view handling. Use pnpm start/the production app server for final smoke when those behaviors live in the server.
7. Smoke-test with curl for /, representative human pages, representative .agent pages, /agent.txt, local AVL/badge assets, expected content types, required agent sections (@meta, @intent, @actions), and page-specific alternate discovery links.
8. If the site also has proof-rich marketing requirements, add a small targeted verifier that asserts important concepts on key pages so future edits do not regress back to thin generic copy.

Pitfalls

• Do not collapse AVL into “another API.” Its wedge is page-level producer-side rendering.
• Do not collapse AVL into “metadata.” Use “agent-native rendering” or “parallel rendering target.”
• Do not overstate that APIs literally vanish; explain that agent-native surfaces may replace many bespoke user-workflow integrations over time.
• Always inspect live .agent / agent.txt if claimed.
• Root /.agent is a dotfile path; Express/static hosts may ignore or deny it by default. Add an explicit route or enable dotfile serving for that endpoint, and verify it does not fall through to SPA HTML.
• Prerendered SPAs can accidentally stamp root /.agent discovery links into every route. Post-process or generate per-route HTML discovery links and page-specific badges, then verify no non-root page still has href="/.agent".
• Non-JS crawlers may read <noscript> or SPA fallback HTML instead of hydrated React. If a canonical human URL appears to return “agent-style” plain text, inspect the raw response and fallback/no-JS content before assuming content negotiation is wrong. Canonical URLs should stay text/html and styled/crawler-readable; .agent and Accept: text/agent-view should be the only agent representations.
• Express/static hosting can break crawler parity in two ways: dotfile .agent routes may be denied unless explicitly served with dotfiles allowed, and directory redirects such as /about -> /about/ can bypass route-specific fallback logic. Verify with real curl -i headers for canonical routes, .agent routes, agent.txt, and Accept: text/agent-view.
• Static preview servers can produce false negatives or false confidence for agent-first behavior. If .agent routes/content negotiation are implemented in the production Node/Express server, final verification must run against that server, not only vite preview.
• Self-host AVL badges and discovery assets for production pages. External raw.githubusercontent.com dependencies are brittle at runtime and are easy review flags; copy them under public assets and smoke-test the local URL.
• Discovery-link injection/removal regexes must be attribute-order tolerant. HTML can render <link rel="alternate" type="text/agent-view" ...> or with attributes reordered; verifiers and dedupers should detect semantics, not exact string order.
• Extract shared path/endpoint helpers for verifiers. Duplicated root/non-root .agent path logic drifts quickly across verify-agent-views, route parity, crawler HTML, prerender, and server checks.
• Add regression scripts for agent-first sites that assert canonical pages are substantive HTML, not empty SPA shells; required pages advertise page-specific alternate agent views; agent.txt is not SPA HTML; and forbidden stale terms/URLs are absent from prerendered output.
• Treat auth as central, not an implementation footnote.
• Keep the mobile-first analogy, but do not let it obscure the concrete product benefit.