Website audit

[BTCBoyd]

Edit and complete the website edit review aligned with the updated OP.

website-audit-proposed-edits.md

[LeoBchuk]

@BTCBoyd here is my review

Section 1 — Version numbers

Finding: Footer on demo.html and registry.html shows Observer Protocol v0.2. Hero eyebrow on demo.html shows Live Demo — Protocol v0.3.
Severity: Low — cosmetic but embarrassing
Proposed edit: Update all version references to v1.1 throughout. Update hero eyebrow to Live Demo — Protocol v1.1.
Leo's call: Approve
Note: Can we make the version number dynamic according to the current build?

---

Section 2 — Identity model: public_key_hash must go

Finding: registry.html shows "Public Key Hash" as the identity field in every agent profile modal (Maxi, Vicky, AgentPay MCP). The rebuild dropped public_key_hash entirely in Migration 005. The agent's identity is now their did:web DID string.
Severity: High — architecturally wrong, contradicts the live system
Proposed edit: Replace "Public Key Hash" label and sha256:... value with "DID" and did:web:observerprotocol.org:agents/{agent_id} in all agent profile modals. Update the agent card .agent-hash display to show the DID instead of a truncated hex hash.
Leo's call: Approve
Additional comments:

1. Timestamps in agent cards are too long, I suggest changing the format to a shorter one
2. Clicking any agent displays an "Agent not found error"

---

Section 3 — VAC described as custom JSON, not W3C VP

Finding: demo.html describes VACs in terms that imply the old custom JSON format (vac_id, agent_id, generic signature field). The live format is a W3C Verifiable Presentation containing W3C Verifiable Credentials with Ed25519Signature2020 proofs and multibase-encoded proofValue.
Severity: High — the format is fundamentally different
Proposed edit: Update VAC description in demo.html to: "Each verified transaction is issued as a W3C Verifiable Credential. Agents carry their credentials as a W3C Verifiable Presentation — portable across any platform, verifiable by anyone with HTTPS access, no query to OP required." Remove or update any JSON examples to show the W3C VC/VP format.
Leo's call: Approve

---

Section 4 — DID resolution endpoints entirely absent

Finding: The three new DID endpoints (GET /.well-known/did.json, GET /agents/{id}/did.json, GET /orgs/{id}/did.json) are not mentioned anywhere across all three pages. These are the primary v1.1 architectural feature.
Severity: High — the most significant v1.1 feature is invisible to visitors
Proposed edit:

• Add a "DID Identity" section to quickstart.html showing how to resolve an agent's DID Document with a curl example: curl https://observerprotocol.org/agents/{agent_id}/did.json
• Add DID Document links to agent cards in registry.html — a "View DID" button alongside "View VAC"
• Add a brief callout to demo.html hero section: "Every agent now has a W3C Decentralized Identifier — resolve their DID Document at /agents/{id}/did.json"
  Leo's call: Approve

---

Section 5 — Quickstart shows wrong registration endpoint and flow

Finding: quickstart.html Step 3 shows client.register({ solanaAddress, walletStandard: 'ows' }) — a client SDK method that doesn't match the live API. The live endpoint is POST /observer/register-agent. The response now returns agent_did and did_document — neither appears in the quickstart. Steps 4-5 use client.getChallenge() and client.verifyChallenge() which don't match live paths (POST /observer/challenge, POST /observer/verify-agent).
Severity: High — breaks developer onboarding immediately
Proposed edit: Rewrite Steps 3-4 of the quickstart to show the actual API calls:

# Step 3 — Register
curl -X POST https://api.observerprotocol.org/observer/register-agent \
  -H "Content-Type: application/json" \
  -d '{"public_key": "{your_ed25519_public_key_hex}", "agent_name": "my-agent"}'
# Returns: { "agent_id": "...", "agent_did": "did:web:observerprotocol.org:agents/..." }

# Step 4 — Get challenge
curl -X POST "https://api.observerprotocol.org/observer/challenge?agent_id={agent_id}"
# Returns: { "challenge": "...", "nonce": "..." }

# Step 5 — Verify (sign the nonce with your Ed25519 private key, hex-encode)
curl -X POST "https://api.observerprotocol.org/observer/verify-agent?agent_id={agent_id}&signed_challenge={hex_signature}"

Leo's call: Modify.
Note: I do not see the mentioned steps in the quickstart.html. Is it inside one of the guides? Which one?

---

Section 6 — "Reputation score" language in quickstart

Finding: quickstart.html Step 5 code comment reads // - Reputation score as part of the VAC response. The whitepaper explicitly states VACs replace reputation scores. The response returns a W3C VP, not a score.
Severity: Medium — explicitly deprecated concept still visible
Proposed edit: Replace the comment with: // - verifiableCredential[] (W3C VC array) and // - proof (Ed25519Signature2020). Remove reputation_score entirely.
Leo's call: Modify
Note: I do not see the mentioned steps in the quickstart.html. Is it inside one of the guides? Which one?

---

Section 7 — Wrong API endpoint paths throughout

Finding: All three pages reference endpoint paths from the old whitepaper that don't match the live API. Key mismatches:

Shown on website	Live API path
POST /agents/register	POST /observer/register-agent
POST /vacs/generate	POST /vac/{agent_id}/refresh
POST /vacs/verify	POST /vp/verify
GET /agents/{id}/verify	GET /observer/agents/{agent_id}
POST /organizations/register	POST /observer/register-org

Additionally, demo.html shows curl https://api.observerprotocol.org/observer/ask?q=maxi-0001 — this endpoint exists in main.py but not in the production api-server-v2.py.

Severity: High — misdirects developers trying to integrate
Proposed edit: Update all endpoint references to match the live API paths. Remove the /observer/ask curl example or replace with a working endpoint like GET /agents/{agent_id}/did.json.
Leo's call: Approve

---

Section 8 — Dead nav links

Finding: demo.html and registry.html nav bars link to architecture.html, spec.html, sdk.html, api.html — none of these pages exist in the website directory.
Severity: Medium — broken UX for anyone exploring
Proposed edit (Option A): Remove the dead links from the nav until the pages are built.
Proposed edit (Option B): Replace with working links: WHITEPAPER.md on GitHub for architecture/spec, api.observerprotocol.org/docs for API reference.
Leo's call: Defer
Note: I could not reproduce the problems reported here. I did notice the nav bar has a different alignment, it is centered, in spec.html, and present an inconsistent size along each page.

---

Section 9 — Badge tiers don't match protocol trust levels

Finding: registry.html shows Bronze/Silver/Gold/Platinum tiers based on transaction count (1+, 10+, 100+, 1000+). The protocol spec defines trust levels based on verification depth (Level 1 self-attested through Level 5 OP-verified), not transaction counts. The gamification layer has no correspondence to the formal TrustLevel enum.
Severity: Medium — creates confusion between UI construct and protocol spec
Proposed edit (Option A): Keep the Bronze/Silver/Gold/Platinum UX but add a note: "Badge tiers reflect transaction volume. For cryptographic verification depth, see the agent's VAC scope levels."
Proposed edit (Option B): Replace the badge tier system with the actual six-level scope framework from the protocol spec.
Leo's call: Approve. Option B

---

Section 10 — Stale hardcoded agent data

Finding: registry.html fallback modal data shows Maxi with 9 transactions, Vicky with 1, AgentPay MCP with 3 — frozen at early February 2026. Identity fields still show sha256:... format.
Severity: Medium — stale numbers, wrong identity format
Proposed edit: Update fallback data to show DID-format identity strings. Update transaction counts to reflect current reality. Ideally make the fallback pull from live API with a graceful error state rather than hardcoded stale data.
Leo's call: Approve

---

Section 11 — Missing W3C concepts to add

Finding: The following live production features have zero mentions across all three pages and should be introduced:

Feature	Where to add
W3C Verifiable Credentials	demo.html hero, quickstart.html intro
W3C Verifiable Presentations (VAC = VP)	demo.html, quickstart.html Step 5
did:web identity	quickstart.html Step 3, registry.html agent cards
DID Document resolution	quickstart.html new step, registry.html agent cards
Key rotation (PUT /agents/{id}/keys)	quickstart.html advanced section
issuer_trusted flag in VP verify response	quickstart.html Step 5
OP/AT architectural split	demo.html or new about section

Severity: High — core v1.1 architecture invisible to visitors
Proposed edit: Add a "What's new in v1.1" section to demo.html covering the above concepts concisely. Update quickstart.html to reference W3C standards throughout. Add DID Document links to agent cards in registry.html.
Leo's call: Approve

---

Section 12 — Whitepaper self-inconsistencies (for Leo's awareness)

These are issues Claude Code found in WHITEPAPER.md itself — not website issues, but relevant because website copy derives from the whitepaper. These may need a follow-up whitepaper patch (v1.3.2):

1. Section 2.2 still describes public_key_hash as the identity primitive — superseded by the v1.1 DID rebuild
2. Section 2.6 shows a pre-v1.1 VAC JSON schema that doesn't match the W3C VP/VC format in production
3. Section 3.2 lists endpoint paths that don't match the live API
4. Section 6 references "VAC architecture v0.3.1" — superseded by v1.1
5. Appendix A defines public_key_hash as "the agent's unique, portable identifier" — now superseded by the agent's DID

Leo's call: Approve