JVision — Complete File Guide

What Every File Is, Where It Goes, and How to Use It

---

Overview

You have 27 files. They fall into four groups:

Group	Purpose	Count
Specification files	Define exactly how the system works	13
Operational files	Tell the AI how to build it	6
Reference files	Guides you use at specific points in the build	6
Project files	Live inside the Dyad project itself	2

---

PART 1 — Before You Open Dyad

What to do with your files right now, before touching Dyad at all

---

Step 1 — Rename your 13 specification files

Your specification files currently have long names. Rename them exactly as shown below. The numbers control the order the AI reads them — do not skip this step.

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

Step 2 — Rename the activation prompt

Current filename	Rename to
JVision_AI_Activation_Prompt.md	ACTIVATE.md

Step 3 — Create a folder on your computer called jvision-files

Organise your files into subfolders like this:

jvision-files/
├── specs/                          ← Your 13 renamed specification files go here
│   ├── 01_master_spec.md
│   ├── 02_session_identity.md
│   ├── 03_error_standard.md
│   ├── 04_versioning.md
│   ├── 05_rate_limiting.md
│   ├── 06_spa_route_changes.md
│   ├── 07_rollback_strategy.md
│   ├── 08_jws_verification.md
│   ├── 09_jsonld_vocabulary.md
│   ├── 10_multi_agent.md
│   ├── 11_escalation.md
│   ├── 12_conformance.md
│   └── 13_implementation_guide.md
│
├── project/                        ← Files that go INTO the Dyad project
│   ├── ACTIVATE.md
│   ├── AI_RULES.md
│   └── jvision_README.md           ← This gets renamed to README.md inside the project
│
├── reference/                      ← Guides you open and read at specific points
│   ├── Key_Management_Guide.md
│   ├── Deployment_Guide.md
│   ├── Security_Considerations.md
│   ├── Agent_Client_SDK_Specification.md
│   ├── JVision_Conformance_Test_Implementation.md
│   └── CHANGELOG.md
│
└── about/                          ← Background reading — not used in the build
    ├── JVision_Project_Overview.md
    ├── JVision_Review_Report.md
    └── JVision_Dyad_File_Structure.md

---

PART 2 — What Every File Is and What It Does

The 13 Specification Files (go in specs/)

These are the core of everything. They tell the AI exactly how to build every part of the system. The AI must read all 13 before writing any code.

File	What it is	When the AI needs it
01_master_spec.md	The four-layer architecture — Perception, Agency, Veracity, Efficiency. The foundation everything else builds on.	Always — first file read every session
02_session_identity.md	How AI agents register, log in, refresh their token, and log out.	Before any session or auth code
03_error_standard.md	The exact shape every error response must take across all endpoints.	Before any error handling code
04_versioning.md	How the spec changes over time without breaking agents that depend on it.	Before any response header code
05_rate_limiting.md	How many requests each endpoint accepts per minute and what happens when limits are hit.	Before any request handling code
06_spa_route_changes.md	How the system stays in sync with a React app when the URL changes without a page reload.	Before building Layer 1
07_rollback_strategy.md	How to safely undo a destructive action that failed halfway through.	Before building Layer 2
08_jws_verification.md	What to do when a content signature fails — the trust failure protocol.	Before building Layer 3
09_jsonld_vocabulary.md	The exact JSON structure for serving content to AI agents efficiently.	Before building Layer 4
10_multi_agent.md	How multiple AI agents work together, avoid conflicts, and hand off tasks.	Before building multi-agent features
11_escalation.md	When an agent must stop and ask a human for help, and exactly how it does that.	Before any destructive action code
12_conformance.md	78 tests that prove the system is built correctly.	Before Session 9
13_implementation_guide.md	A master guide that tells the AI how to use all 12 files above together.	Always — last file read every session

---

The Operational Files (go in project/)

These are the files that go directly into your Dyad project. They control how Dyad's AI behaves.

AI_RULES.md

• What it is: A rulebook for Dyad's AI that it reads automatically at the start of every session
• Where it goes: The root of your Dyad project (same level as package.json)
• What it does: Tells the AI the project uses Next.js (not React Router), where every type of file belongs, which packages are available, and all the JVision rules it must always follow
• When you use it: You place it once and never touch it again unless you want to change the rules

ACTIVATE.md (renamed from JVision_AI_Activation_Prompt.md)

• What it is: The activation prompt that turns a general-purpose AI into a JVision specialist
• Where it goes: .jvision/ACTIVATE.md inside your Dyad project
• What it does: When you paste its contents as your first message in a Dyad session, the AI reads all the spec files and becomes a JVision specialist that follows the specification exactly
• When you use it: Paste it as the first message at the start of every Dyad session

jvision_README.md

• What it is: A README file that explains the .jvision/ folder to anyone (human or AI) who opens it
• Where it goes: .jvision/README.md inside your Dyad project (rename it when you put it there)
• What it does: Explains what the folder contains, how to use it, and what each spec file covers
• When you use it: Place it once when setting up the project

JVision_Dyad_Scaffold_Prompt.md

• What it is: A long prompt you paste into Dyad once to build the entire project skeleton
• Where it goes: Keep it in your jvision-files/project/ folder on your computer — do not put it inside Dyad
• What it does: Creates every folder, every placeholder file, and all configuration files in one pass. After running it, the project structure exists and every endpoint returns a proper 501 response immediately
• When you use it: Once only, at the very start — Phase 2 of the setup

JVision_Dyad_Instructions.md

• What it is: Your step-by-step build guide for the entire project
• Where it goes: Keep it on your computer — do not put it inside Dyad
• What it does: Walks you through all 10 build sessions from setup to a complete working system, including what to say to Dyad at each step
• When you use it: Keep it open alongside Dyad as your roadmap throughout the build

---

The Reference Files (go in reference/)

These are guides you read and act on at specific points during the build. You do not paste them into every Dyad session — only when you are working on the relevant part.

Key_Management_Guide.md

• What it is: Instructions for generating and managing the cryptographic keys that sign content
• When you use it: Open it at the start of Session 7 (Layer 3 — Veracity) before writing any signing code
• What it tells you: How to generate an RS256 key pair, add it to your .env.local, update the JWKS file, rotate keys, and what to do if a key is compromised

Deployment_Guide.md

• What it is: Step-by-step instructions for deploying to Vercel in production
• When you use it: After all build sessions are complete and conformance tests pass
• What it tells you: How to set up Vercel, configure Upstash Redis, set all production environment variables, verify the deployment, and roll back if something goes wrong

Security_Considerations.md

• What it is: The threat model and security requirements for the system
• When you use it: Before going to production, and whenever you add a new agent-facing endpoint
• What it tells you: What attacks to protect against, required security configuration, what to do if keys are compromised, how to penetration test the agent surface

JVision_Conformance_Test_Implementation.md

• What it is: The actual Vitest test code for all 78 conformance tests
• When you use it: During Session 9 — attach it to the Dyad AI context and ask it to implement the test suite
• What it tells you: How to set up Vitest, the full test code for every layer, and how to run the tests at different stages of the build

Agent_Client_SDK_Specification.md

• What it is: A specification for building a client library that AI agents use to talk to your server
• When you use it: During Session 10 — attach it to the Dyad AI context
• What it tells you: The exact interface a JVision client must expose, the eight mandatory behaviours every client must implement, and a reference TypeScript implementation

CHANGELOG.md

• What it is: A version history of the JVision specification
• When you use it: Any time you want to know what changed and when, or when updating to a new version of the spec
• What it tells you: Everything that was added in version 1.0.0, and what is planned for future versions

---

The About Files (go in about/)

These are background reading. You do not use them in the build process — they are for understanding the project.

JVision_Project_Overview.md

• A plain-language explanation of what JVision is, what it is for, and what its goal is
• Read this to explain the project to someone new, or to remind yourself of the big picture

JVision_Review_Report.md

• An honest assessment of the project — what is strong, what had problems, and what was missing
• Read this to understand the history of the project and what was fixed

JVision_Dyad_File_Structure.md

• A detailed diagram of the complete folder and file structure inside Dyad
• Read this if you want to understand why the project is organised the way it is

---

PART 3 — Setting Up Dyad Step by Step

Phase 1 — Create the Dyad project

1. Open Dyad
2. Click New Project
3. Select Next.js as the project type
4. Name it jvision-project
5. Wait for Dyad to finish generating the base files

Phase 2 — Place the project files

a) Replace AI_RULES.md

• In the Dyad file explorer, find AI_RULES.md in the project root
• Open it, select all, delete everything
• Open your AI_RULES.md from jvision-files/project/
• Copy all its contents and paste them in
• Save

b) Create the .jvision folder and its files

• Right-click the project root in Dyad → New Folder → name it .jvision
• Inside .jvision, create a subfolder called specs
• Inside .jvision, create a new file called ACTIVATE.md
  • Open your ACTIVATE.md from jvision-files/project/, copy all, paste in, save
• Inside .jvision, create a new file called README.md
  • Open your jvision_README.md from jvision-files/project/, copy all, paste in, save

c) Upload the 13 spec files into .jvision/specs/

• Select .jvision/specs/ in the Dyad file explorer
• Upload or create each of the 13 files from jvision-files/specs/
• Confirm all 13 files are present and named correctly (01_master_spec.md through 13_implementation_guide.md)

Phase 3 — Run the scaffold prompt

1. Open the Dyad chat window
2. Open JVision_Dyad_Scaffold_Prompt.md from your computer
3. Find the large block of text between the triple backticks (```)
4. Copy everything inside those backticks
5. Paste it into the Dyad chat window and press send
6. Wait for the AI to finish — it will create 40+ files and folders
7. When it finishes, confirm these folders exist in the file explorer:
   • src/app/api/agent/ with all subfolders
   • src/lib/jvision/ with all subfolders
   • tests/conformance/
   • docs/adr/
   • public/.well-known/

Phase 4 — Install packages and create .env.local

a) Install packages — send this to Dyad:

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

b) Create .env.local

• In Dyad, create a new file in the project root called .env.local
• Copy the contents of .env.example into it
• Fill in these values 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

• Leave JVISION_SIGNING_KEY_PRIVATE, JVISION_SIGNING_KEY_ID, REDIS_URL, and JVISION_ESCALATION_WEBHOOK_URL blank for now
• Save

c) Confirm .gitignore — open .gitignore and confirm .env.local is listed

d) 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.

Phase 5 — Verify the project runs

Send to Dyad:

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

Then open http://localhost:3000 in your browser. You should see the JVision home page with four layer cards.

Test one endpoint with curl:

curl -s http://localhost:3000/api/agent/manifest \
  -H "X-Agent-Identity: test" \
  -H "Authorization: Bearer test"

You should see a JSON error response with "code": "not_implemented". If you do, the setup is complete.

---

PART 4 — The 10 Build Sessions

Open JVision_Dyad_Instructions.md and follow it for the full detail. Here is the summary:

Session	What you build	Supplementary file to attach
1	Error envelope + version headers — foundation for everything	None
2	Session identity — registration, login, token refresh	02_session_identity.md
3	Rate limiting — apply to all endpoints	05_rate_limiting.md
4	Layer 4 (Efficiency) — compressed content endpoint	09_jsonld_vocabulary.md
5	Layer 1 (Perception) — manifest and SSE stream	06_spa_route_changes.md
6	Layer 2 (Agency) — action execution and rollback	07_rollback_strategy.md
7	Layer 3 (Veracity) — content signing and verification	08_jws_verification.md + Key_Management_Guide.md
8	Escalation — human handoff protocol	11_escalation.md
8b	Multi-agent — locking, teams, handoff	10_multi_agent.md
9	Conformance tests — verify everything works	JVision_Conformance_Test_Implementation.md
10	Agent Client SDK — client library for agent developers	Agent_Client_SDK_Specification.md

---

PART 5 — How to Start Every Dyad Session

Do this at the start of every session, every time.

Step 1 — Attach the spec files In the Dyad chat panel, use the attach/context button to attach all 13 files from .jvision/specs/

Step 2 — Also attach ACTIVATE.md Attach .jvision/ACTIVATE.md to the context

Step 3 — Paste the activation prompt Open .jvision/ACTIVATE.md, copy all its contents, paste as your first message, press send

Step 4 — Tell the AI what you are working on

"Today we are working on Session [number] — [what you are building]"

If you are continuing from a previous session:

"We are continuing from last session. We were implementing [what]. Here is where we left off: [brief description]"

---

PART 6 — Quick Reference

Something went wrong and the AI is not following the spec:

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

Not sure which spec file covers your question:

"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."

The AI seems to have forgotten the spec mid-session: It has run out of context. Start a new session and repeat the five steps above.

You want to 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."

Ready to go to production: Open Deployment_Guide.md and Security_Considerations.md and work through them before deploying.

---

Complete File Reference

This table lists all 28 files. The "Downloaded as" column is the filename you received. The "Rename to" column is what to rename it before using it. If "Rename to" is blank the file keeps its original name.

Specification Files — rename and place in .jvision/specs/ inside 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 directly inside Dyad as shown

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)	Your computer only — paste contents into Dyad chat once
JVision_Dyad_Instructions.md	(keep name)	Your computer only — your build roadmap

Reference Files — keep on your computer, open at the right time

Downloaded as	Rename to	When to use it
Key_Management_Guide.md	(keep name)	Start of Session 7 — before any signing code
Deployment_Guide.md	(keep name)	After all sessions complete — before going live
Security_Considerations.md	(keep name)	Before going live and before adding 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 you want to check the version history

About Files — background reading, keep on your computer

Downloaded as	Rename to	What it is
JVision_Project_Overview.md	(keep name)	Plain-language explanation of what JVision is and why it exists
JVision_Review_Report.md	(keep name)	Honest assessment of the project — what was strong, what was fixed
JVision_Dyad_File_Structure.md	(keep name)	Detailed diagram of the complete folder structure inside Dyad
JVision_Master_Instructions.md	(keep name)	This document — the complete guide to all 28 files