I Am Building WebDNA: A Zero-Config AI Context Standard for the Web

The Problem I Could Not Ignore

I spend a significant amount of my development time working with agentic tools. Claude Code, Cursor, Windsurf -- these tools are genuinely useful, but they share a fundamental flaw: they have no structured understanding of the website they are working on. Every new session, I find myself doing the same thing. Explaining the route structure. Pasting in component trees. Describing the brand language. Pointing out which API endpoints exist and what they expect.

This is not a workflow problem. It is an infrastructure problem. The web has no standard way to hand an AI agent a structured briefing about a website before it starts working. And that missing layer is costing developers real time, every single day.

The existing standards do not solve this. llms.txt, proposed as an AI-friendly content layer, operates closer to robots.txt -- it tells AI what it can read, but gives it no understanding of the site's structure, components, or design system. sitemap.xml handles page discovery for search crawlers, not semantic understanding. MCP (Model Context Protocol) is a powerful protocol that has seen strong adoption across Claude, OpenAI, and Google Gemini in 2025 and into 2026, but it requires a custom server per project -- a setup cost that is simply too high for most developers building standard websites and apps. OpenAPI specs cover API surfaces but say nothing about UI, brand, or layout.

There is a gap. A significant one. And I want to fill it.

What WebDNA Is

WebDNA is a build-time generated, framework-native manifest served at a standardised URL that gives any AI agent a complete, structured briefing about a website before it touches anything.

The analogy I keep coming back to: when a new designer joins your team, you hand them a brand guidelines document before they open Figma. You do not make them reverse-engineer the design system from the live site. Right now, every AI that works on your codebase has to do exactly that -- reverse-engineer everything from raw HTML and scattered source files. WebDNA is that brand guidelines document, auto-written by your framework on every single build.

The core principles I am designing around:

• Zero config by default. It works out of the box. No setup, no YAML, no configuration file required to get started.
• Always in sync. Because it is generated directly from your build process, it cannot go stale. The moment your code changes, your WebDNA changes.
• Framework-native. This is not a file you write manually. It is a file your framework produces.
• Consent-first. Private routes, auth-gated content, and dynamic data are never exposed without explicit developer consent and user-initiated authorization flows.
• Read-only, always. AI agents can read WebDNA. They cannot write to it. This is a core security principle, not a limitation.
• Open standard. No vendor lock-in. Any framework should be able to implement it.

What the Output Looks Looks Like

WebDNA is a JSON file served at /.well-known/webdna.json. Here is a representative example of what it looks like for a portfolio site:

{
  "meta": {
    "name": "My Portfolio",
    "description": "Personal portfolio and blog by Om Rajguru",
    "version": "1.0.0",
    "generatedAt": "2026-04-01T12:00:00Z",
    "tier": "custom"
  },
  "brand": {
    "colors": {
      "primary": "#0F172A",
      "accent": "#6366F1",
      "background": "#FFFFFF",
      "text": "#1E293B"
    },
    "typography": {
      "heading": "Cal Sans",
      "body": "Inter"
    },
    "tone": "Professional, minimal, direct"
  },
  "routes": {
    "/": {
      "type": "static",
      "description": "Homepage with hero section and featured work grid"
    },
    "/blog/[slug]": {
      "type": "dynamic",
      "dataSource": "/api/posts",
      "schema": {
        "title": "string",
        "body": "richtext",
        "author": "string",
        "publishedAt": "date",
        "tags": "string[]"
      }
    },
    "/dashboard": {
      "type": "private",
      "requiresAuth": true,
      "auth": "oauth2",
      "scopes": ["read:profile", "read:orders"],
      "exclude": true
    }
  },
  "components": {
    "Navbar": "Top navigation bar with logo and 4 page links",
    "HeroSection": "Full-width hero with headline, subtext, and CTA button",
    "BlogCard": "Card showing post title, date, tag, and excerpt",
    "Footer": "Links, social icons, and copyright notice"
  },
  "api": {
    "/api/posts": {
      "method": "GET",
      "description": "Returns all published blog posts",
      "example_request": "/api/posts?limit=10&tag=design",
      "example_response": {
        "title": "Building a Design System",
        "author": "Om Rajguru",
        "publishedAt": "2026-03-01",
        "slug": "building-a-design-system"
      }
    }
  }
}

In a single file, an AI agent gets the site name and description, the complete color palette and typography, every route and its type (static, dynamic, or private), the data schema for dynamic routes, every component with a plain-English description, and API endpoints with real usage examples.

This is everything I would tell a new developer on my first day pairing with them. Structured, machine-readable, and always current.

Two Tiers, One Principle

WebDNA has two operating modes.

WebDNA Auto is the default. No configuration required. It generates on every build, captures everything public, and gets served at /.well-known/webdna.json. For portfolios, blogs, landing pages, and marketing sites, this is the only thing you ever need.

WebDNA Custom is for developers who need granular control. You get page-level exclusions through a config file:

// webdna.config.js
module.exports = {
  webdna: {
    exclude: ["/pricing", "/internal"],
    privateRoutes: ["/dashboard", "/settings"]
  }
}

And element-level exclusions through a single HTML attribute:

<p data-webdna="exclude">
  This paragraph is completely invisible to any AI reading WebDNA.
</p>

The Custom output lives at /.well-known/webdna-custom.json. AI agents check for the Custom version first and fall back to Auto if it does not exist. The fallback logic is simple, predictable, and requires nothing from the developer.

Static File or Live API Route

One decision I spent considerable time thinking through is how WebDNA behaves on sites where content is dynamic. A blog that pulls posts from a CMS cannot produce a complete picture at build time. A SaaS app with per-tenant route structures cannot serve a single static file for all users.

The solution I landed on mirrors how Next.js handles sitemap.xml. WebDNA is static by default. When the framework detects dynamic data sources, it automatically becomes a live API route that reflects the current state of the site on every request. For Next.js ISR projects, it revalidates on the configured interval. For full SaaS apps with multi-tenant architectures, it becomes a tenant-scoped endpoint served per subdomain:

acme.yourapp.com/.well-known/webdna.json
google.yourapp.com/.well-known/webdna.json

Each tenant sees only their own routes and data. Cross-tenant leakage is impossible by design, because each endpoint is scoped to the authenticated session.

The developer never selects the mode manually. The framework detects it.

Private Routes and the Auth Model

One of the harder problems in this space is how AI agents should handle auth-gated content. The two approaches people use today are both bad: either share credentials with the AI tool (insecure) or block AI entirely from private routes (unusable).

WebDNA takes a different path. Private routes declare their OAuth 2.0 scopes directly in the manifest:

"/dashboard": {
  "type": "private",
  "requiresAuth": true,
  "auth": "oauth2",
  "scopes": ["read:profile", "read:orders"]
}

When an AI agent encounters a private route, it initiates a consent prompt. The user explicitly approves access. The agent receives a scoped, time-limited token. The token expires. No persistent access without re-consent. No credentials stored in or transmitted through the WebDNA file.

This is the same pattern as granting a third-party app access to your Google Calendar or GitHub repositories. It is well-understood, widely implemented, and secure. I am not inventing a new auth model. I am applying an established one to a problem where it is currently absent.

The Read-Only Guarantee

I want to address this directly because it will come up: WebDNA is read-only, and that is permanent.

Allowing AI agents to write back to WebDNA would introduce prompt injection risk (a malicious agent could embed instructions that manipulate other AI agents reading the file later), silent drift (descriptions diverge from actual code without the developer knowing), and a fundamental collapse of trust in the standard itself. The entire value of WebDNA rests on it being a reliable, developer-authored source of truth. Write access destroys that.

If AI feedback on WebDNA quality is ever desirable, it will go through a separate, opt-in suggestions endpoint that requires explicit developer approval before anything changes -- surfaced as a pull request, never auto-merged. The Dependabot model. AI opens a PR, developer merges it. Feedback yes, write access no.

The Validator

WebDNA ships with a linter from day one. Run it with:

npx webdna lint

It catches issues like routes marked private with no auth scope declared, components with no description, dynamic routes with no schema, and data-webdna attributes on non-existent elements. Think ESLint, but for your WebDNA configuration. It will integrate with VS Code for inline squiggles, CI/CD pipelines for build-time enforcement, and pre-commit hooks.

How WebDNA Compares to What Exists Today

I want to be honest about the landscape here. There are real solutions trying to solve adjacent problems. This is how I see the current state:

MCP is genuinely good at what it does, and its adoption has been rapid across 2025. But it is designed for structured, permissioned data access at an infrastructure level. WebDNA is designed for the much simpler, much more common case: a developer who wants their AI coding tools to understand their website without setting up a server. These are complementary tools, not competing ones.

The Roadmap

Development is starting now. Here is the plan:

Phase 1 is the Next.js Plugin MVP. I am building next-webdna as a standalone NPM package with a single activation flag (webdna: true in next.config.js), auto-generation from the route tree and Tailwind tokens at build time, automatic static/dynamic mode detection, and the published open spec for the JSON format.

Phase 2 adds WebDNA Custom: the config file, element-level exclusions, and the separate custom output endpoint.

Phase 3 introduces live API route mode for dynamic sites, OAuth scope declaration per private route, and CMS adapter plugins for Contentful, Sanity, and Notion.

Phase 4 handles multi-tenant support with subdomain and tenant-ID based scoping and full per-session data isolation.

Phase 5 ships the validator: the CLI tool, VS Code extension, and CI/CD integration guide.

Phase 6 is the push for broader adoption: an RFC to Next.js and Vercel for native integration, adapters for SvelteKit, Astro, and Nuxt, and direct outreach to the teams building Cursor, Windsurf, Claude Code, and GitHub Copilot to build native WebDNA reading into their context engines.

What Comes Next

The project is private during development. I am building in the open in the sense that I am documenting the thinking here, but the repository will go public when Phase 1 reaches a usable state. If you want to follow along, this blog is the place to do it.

I am also genuinely interested in feedback on the spec. If you work on an agentic tool and have thoughts on what context you wish you had when working on a website, I would like to hear from you. If you are building on Next.js and have a use case this does not cover, same thing. The spec is a draft. The best time to shape it is before the first line of plugin code ships.

The web deserves a proper AI context layer. I am going to build one.

WebDNA is an original concept. Development started April 2026.