Welcome to JVision

Build the web for AI agents

JVision is a complete specification and build framework for creating websites that AI agents can natively read, act within, verify, and consume — without scraping, guessing, or simulating human behaviour.

Layer 1

Perception

Agents read page intent through a semantic manifest — not pixels

Layer 2

Agency

Agents execute typed actions via API — no clicking required

Layer 3

Veracity

Agents verify content authenticity with cryptographic signatures

Layer 4

Efficiency

Agents consume structured JSON-LD — no token-wasting noise

What you have

You downloaded 28 files that together form everything needed to build a JVision-compliant web application in Dyad. This guide walks you through exactly what each file is, where it goes, and what to do with it — step by step.

Before anything else

You need to rename 14 of your files before you start. Start with Part 1 — Organise Files.

Part 0

Your 28 files

Every file you downloaded, what it is, and where it ends up. Click a file to mark it as understood.

Specification Files — 13 files → rename → .jvision/specs/ in Dyad

Downloaded as	→	Rename to	What it covers
JVision_Agent_Interface_Module_Spec.md	→	01_master_spec.md	Four-layer architecture — the foundation
Agent_Session_and_Identity.md	→	02_session_identity.md	Agent registration, login, token lifecycle
Error_Response_Standard.md	→	03_error_standard.md	Unified error envelope for all endpoints
API_Versioning_and_Deprecation.md	→	04_versioning.md	How the spec evolves without breaking agents
Rate_Limiting_All_Layers.md	→	05_rate_limiting.md	Rate limits for all four layers
Semantic_DOM_Layer_SPA_Route_Changes.md	→	06_spa_route_changes.md	SPA route change handling (Layer 1)
Action_Manifest_Rollback_Strategy.md	→	07_rollback_strategy.md	Destructive action rollback (Layer 2)
Proof_of_Truth_JWS_Verification_Failure_Handling.md	→	08_jws_verification.md	JWS signature failure handling (Layer 3)
Compressed_Knowledge_Endpoint_Product_Catalogue_JSON-LD.md	→	09_jsonld_vocabulary.md	JSON-LD vocabulary (Layer 4)
Multi_Agent_and_Concurrency.md	→	10_multi_agent.md	Concurrent agents, conflict resolution
Human_Escalation_Protocol.md	→	11_escalation.md	When and how agents escalate to humans
Conformance_Testing_Guide.md	→	12_conformance.md	78-test conformance suite
JVision_AI_Implementation_Guide.md	→	13_implementation_guide.md	How an AI applies all of the above

Operational Files — place into Dyad project

Downloaded as	→	Rename to	Where it goes in Dyad
AI_RULES.md	—	keep name	Project root (same level as package.json)
JVision_AI_Activation_Prompt.md	→	ACTIVATE.md	.jvision/ACTIVATE.md
jvision_README.md	→	README.md	.jvision/README.md
JVision_Dyad_Scaffold_Prompt.md	—	keep name	Computer only — paste contents into Dyad once
JVision_Dyad_Instructions.md	—	keep name	Computer only — your build roadmap

Reference Files — keep on your computer

File	→		When to use it
Key_Management_Guide.md	—	keep name	Start of Session 7 — before signing code
Deployment_Guide.md	—	keep name	After all sessions — before going live
Security_Considerations.md	—	keep name	Before going live and new endpoints
JVision_Conformance_Test_Implementation.md	—	keep name	Session 9 — attach to Dyad AI context
Agent_Client_SDK_Specification.md	—	keep name	Session 10 — attach to Dyad AI context
CHANGELOG.md	—	keep name	Any time — check version history

About Files — background reading

File			What it is
JVision_Project_Overview.md	—	keep name	Plain-language explanation of JVision
JVision_Review_Report.md	—	keep name	Honest assessment — what was strong, what was fixed
JVision_Dyad_File_Structure.md	—	keep name	Detailed folder structure diagram
JVision_Master_Instructions.md	—	keep name	The markdown source of this guide

Part 1 — Before Dyad

Organise your files

Do these three steps on your computer before opening Dyad. Check each item as you complete it.

Step 1 — Rename your 14 files

The numbers on the spec files control the order the AI reads them. Do not skip this.

✓
Rename JVision_Agent_Interface_Module_Spec.md → 01_master_spec.md
✓
Rename Agent_Session_and_Identity.md → 02_session_identity.md
✓
Rename Error_Response_Standard.md → 03_error_standard.md
✓
Rename API_Versioning_and_Deprecation.md → 04_versioning.md
✓
Rename Rate_Limiting_All_Layers.md → 05_rate_limiting.md
✓
Rename Semantic_DOM_Layer_SPA_Route_Changes.md → 06_spa_route_changes.md
✓
Rename Action_Manifest_Rollback_Strategy.md → 07_rollback_strategy.md
✓
Rename Proof_of_Truth_JWS_Verification_Failure_Handling.md → 08_jws_verification.md
✓
Rename Compressed_Knowledge_Endpoint_Product_Catalogue_JSON-LD.md → 09_jsonld_vocabulary.md
✓
Rename Multi_Agent_and_Concurrency.md → 10_multi_agent.md
✓
Rename Human_Escalation_Protocol.md → 11_escalation.md
✓
Rename Conformance_Testing_Guide.md → 12_conformance.md
✓
Rename JVision_AI_Implementation_Guide.md → 13_implementation_guide.md
✓
Rename JVision_AI_Activation_Prompt.md → ACTIVATE.md

Step 2 — Create a folder called `jvision-files`

Create this folder structure on your computer and sort your files into it:

jvision-files/
├── specs/          ← 13 renamed spec files (01_ through 13_)
├── project/        ← AI_RULES.md, ACTIVATE.md, jvision_README.md,
│                      JVision_Dyad_Scaffold_Prompt.md,
│                      JVision_Dyad_Instructions.md
├── reference/      ← Key_Management_Guide.md, Deployment_Guide.md,
│                      Security_Considerations.md,
│                      JVision_Conformance_Test_Implementation.md,
│                      Agent_Client_SDK_Specification.md, CHANGELOG.md
└── about/          ← JVision_Project_Overview.md,
                       JVision_Review_Report.md,
                       JVision_Dyad_File_Structure.md,
                       JVision_Master_Instructions.md

✓
Created jvision-files/ folder with four subfolders
✓
Moved all 13 renamed spec files into specs/
✓
Moved project files into project/
✓
Moved reference files into reference/

Part 2 — Dyad Setup

Create your Dyad project

Open Dyad and set up the project with the JVision files in the right places.

Phase 1 — Create the project

✓
Open Dyad and click New Project
✓
Select Next.js as the project type
Do not choose React — JVision needs Next.js for server-side API routes
✓
Name it jvision-project and wait for Dyad to finish generating files

Phase 2 — Replace AI_RULES.md

✓
In Dyad's file explorer, find AI_RULES.md in the project root
✓
Delete all its contents and replace with your AI_RULES.md from jvision-files/project/
This tells Dyad's AI to use Next.js and follow JVision rules on every session
✓
Save the file

Phase 3 — Create the .jvision folder

✓
Right-click the project root → New Folder → name it .jvision
✓
Inside .jvision, create a subfolder called specs
✓
Create .jvision/ACTIVATE.md — paste in contents of your ACTIVATE.md
✓
Create .jvision/README.md — paste in contents of your jvision_README.md

Phase 4 — Upload the 13 spec files

✓
Upload or create all 13 files from jvision-files/specs/ into .jvision/specs/
Files must keep their numbered names: 01_master_spec.md through 13_implementation_guide.md
✓
Confirm all 13 files appear in .jvision/specs/

Part 3 — Scaffold & Configure

Build the project skeleton

Paste one prompt into Dyad to create the entire folder structure and all placeholder files. Then configure your environment.

Step 1 — Run the scaffold prompt

⚠ Do this once only

The scaffold prompt creates 40+ files. Running it twice will create duplicates.

✓
Open JVision_Dyad_Scaffold_Prompt.md from your computer
✓
Find the large block between the triple backticks (` ``` `)
✓
Copy everything inside those backticks and paste into the Dyad chat window
✓
Press send and wait for the AI to finish — this takes 1–2 minutes
✓
Confirm these folders exist: src/app/api/agent/, src/lib/jvision/, tests/conformance/, public/.well-known/

Step 2 — Install packages

Send this to Dyad:

Please run: npm install jose zod @upstash/ratelimit @upstash/redis

✓
Packages installed successfully

Step 3 — Create .env.local

✓
Create a new file in the project root called .env.local
✓
Copy the contents of .env.example into it
✓
Fill in the values below (leave signing keys and Redis URL blank for now)

JVISION_SESSION_TOKEN_EXPIRY=3600
JVISION_OPERATOR_API_KEY=dev-operator-key-change-before-production
JVISION_RATE_LIMIT_STORE=memory
JVISION_SPEC_VERSION=1.0.0
JVISION_ORG_ID=your-org-name
[email protected]
JVISION_DEFAULT_MAX_AGENT_AGE=3600

✓
Confirm .env.local is listed in .gitignore

Step 4 — Tell the AI your config

My .env.local is set up. I am using memory for rate limiting.
Signing keys are blank until Session 7. JVISION_SPEC_VERSION is 1.0.0.

Step 5 — Verify the project runs

Please run npm run dev and confirm the project starts without errors

✓
Dev server starts at http://localhost:3000
✓
Home page shows four JVision layer cards
✓
Agent manifest endpoint returns "code": "not_implemented" JSON

✓ Setup complete

Your project is scaffolded and running. Every agent endpoint returns a proper 501 response. Time to build.

Part 4 — Building

The 10 build sessions

Build the project one session at a time. Click a session card to mark it complete. Follow JVision_Dyad_Instructions.md for the full prompts.

Session 1

Error Envelope + Version Headers

Foundation for everything — build this first

No extra files needed

Session 2

Session Identity

Registration, login, token refresh

02_session_identity.md

Session 3

Rate Limiting

Apply to all endpoints

05_rate_limiting.md

Session 4

Layer 4 — Efficiency

Compressed knowledge endpoint

09_jsonld_vocabulary.md

Session 5

Layer 1 — Perception

Manifest and SSE stream

06_spa_route_changes.md

Session 6

Layer 2 — Agency

Action execution and rollback

07_rollback_strategy.md

Session 7

Layer 3 — Veracity

Content signing and verification

08_jws_verification.md + Key_Management_Guide.md

Session 8

Escalation Protocol

Human handoff

11_escalation.md

Session 8b

Multi-Agent

Locking, teams, handoff

10_multi_agent.md

Session 9

Conformance Tests

Verify everything works — 78 tests

JVision_Conformance_Test_Implementation.md

Session 10

Agent Client SDK

Build the client library that agent developers use to talk to your server

Agent_Client_SDK_Specification.md

Part 5 — Every Session

The session start routine

Do these four steps at the start of every Dyad session, every time. If you skip them the AI will not follow the JVision specification.

1

Attach all 13 spec files

Use the paperclip / "Add context" button in Dyad. Attach all 13 files from .jvision/specs/

2

Also attach ACTIVATE.md

Attach .jvision/ACTIVATE.md to the same context

3

Paste the activation prompt

Open ACTIVATE.md, copy all its contents, paste as your first message, press send. The AI will introduce itself as a JVision specialist.

4

Tell the AI what you are working on

New session: "Today we are working on Session [N] — [what you are building]"
Continuing: "We are continuing from last session. We were implementing [what]. Here is where we left off: [description]"

⚠ Context runs out

If the AI starts ignoring the specification mid-session, it has run out of context window. Start a new session and repeat the four steps above.

Part 6 — Reference

Quick reference

Copy-paste responses for the most common situations you will hit during development.

The AI is not following the specification

That does not match the JVision specification. Please re-read [relevant spec filename] and correct your approach.

Not sure which spec file covers a topic

Check 13_implementation_guide.md and tell me which spec file covers [topic].

A conformance test is failing

Conformance test [test ID e.g. AGY-004] is failing. Please check the relevant spec file and fix the implementation.

Check how complete the build is

Please run through the audit checklist in 13_implementation_guide.md and tell me what is complete, what is partial, and what has not been started.

Starting Session 7 — need signing keys

Please generate a small Node.js script I can run once locally to create an RS256 key pair and output the private key in PEM format for my .env.local and the public key for public/.well-known/agent-keys.jwks

Run the conformance test suite

Please run the conformance test suite and report which tests are passing, which are skipping (501 not yet implemented), and which are genuinely failing.

Part 7 — Going Live

Production checklist

Before deploying, work through these steps in order. Open the reference files listed for each step.

Pre-deployment

✓
All 78 conformance tests pass locally
Run: npm run test:conformance
✓
No TypeScript errors
Run: npm run build
✓
Production RS256 key pair generated
See Key_Management_Guide.md
✓
Redis instance provisioned (Upstash recommended)
See Deployment_Guide.md
✓
JVISION_RATE_LIMIT_STORE set to redis in production
✓
JVISION_OPERATOR_API_KEY is a strong random string
Generate: openssl rand -hex 32
✓
.env.local is NOT in version control
✓
public/.well-known/agent-keys.jwks contains the production public key

Security review

Open Security_Considerations.md

Work through the threat model, required security config, and penetration testing checklist before deploying.

Deploy to Vercel

✓
Import project to Vercel
✓
Add all environment variables in Vercel dashboard
See Deployment_Guide.md for the full list
✓
Deploy and verify /.well-known/jvision.json loads
✓
Run conformance suite against production URL
TEST_BASE_URL=https://your-project.vercel.app npm run test:conformance

🎉 You are live

Your JVision-compliant web application is now on the agentic web. Any AI agent following standard protocols can read, act within, verify, and efficiently consume your site.