Specification

WCI version 1.0 extends HTML with data-wci-* attributes and three optional site root files.

data-wci-* attributes

Attribute	Required	Type	Description
data-wci-id	recommended	string	Stable unique ID for dispatch and distillation
data-wci-role	recommended	enum	action · form · display · nav · status · landmark
data-wci-desc	recommended	string	LLM-oriented description of purpose and constraints
data-wci-action	for interactive nodes	enum	click · fill · select · check · upload · submit · navigate · focus · clear
data-wci-state	recommended	JSON object	Observable state snapshot (updated by Bridge)
data-wci-precondition	optional	string	Natural-language guard; Bridge checks disabled
data-wci-required	optional	boolean	"true" if required before form submit
data-wci-options	optional	JSON array	Choices for select/radio groups
data-wci-emit	optional	string	Custom event name fired after successful action
data-wci-scope	optional	string	Parent landmark data-wci-id
data-wci-hidden	optional	boolean	"true" — exclude from distilled output
data-wci-priority	optional	1–5	Sort key (1 = highest, e.g. primary CTA)

Roles

Role	Use for
landmark	Bounded task zone (form, checkout, modal)
action	Buttons, CTAs with side effects
form	Inputs, textarea, select
display	Read-only values (price, status text)
nav	Links that change route/page
status	Loading, error, success indicators

State JSON

Keep state small and serializable. Example for an email field:

{"value": "", "valid": null, "touched": false}

The Bridge merges patches into data-wci-state after each action.

Distilled view (WciView)

JSON output shape (from @webcontextinterface/distiller):

{
  "wci_version": "1.0",
  "page_title": "Register",
  "scope": "registration-form",
  "scope_desc": "New user registration",
  "distilled_at": "2026-05-22T12:00:00.000Z",
  "node_count": 5,
  "site_context": { "name": "...", "purpose": "..." },
  "nodes": [ { "id": "email-input", "role": "form", "desc": "...", "state": {} } ]
}

Site root files

wci.txt

Robots.txt-style directives. Key fields:

Key	Meaning
Site-Name / Site-Purpose	Identity for agents
Allow-Scope / Deny-Scope	Comma-separated scope IDs
Rate-Limit-Actions / Rate-Limit-Distil	Per-minute limits
Auth-Required	Scopes needing authentication
Require-Human-Confirmation	Scopes that must not auto-execute
Manifest / Context	URLs to wci.json and wci.md

wci.json

Structured manifest: site, capabilities, authentication, task_flows, scopes, denied_scopes, rate_limits. Types: SiteManifest, TaskFlow, ScopeDescriptor in @webcontextinterface/spec.

wci.md

Free-form Markdown injected into the LLM system prompt (policies, tone, domain glossary).

Discovery order

WciContextLoader resolves file URLs in this priority:

1. HTTP response headers: X-WCI-Directives, X-WCI-Manifest, X-WCI-Context
2. <meta name="wci:directives"> (and manifest/context) in the page
3. /.well-known/wci/* (RFC 8615)
4. /wci.txt, /wci.json, /wci.md

Events

Event	Target	Detail
wci:state-change	document	{ nodeId, action, stateAfter }
Custom (data-wci-emit)	target element	{ nodeId, action, value, stateAfter }

Versioning

• Attribute and JSON view version: 1.0 (wci_version field)
• Packages use semver; spec breaking changes bump major