docs: developer-first navigation restructure

[s-adamantine]

Summary

Restructures the entire documentation to be developer-first. The core change: put practical content before theory, and make every page reachable from the sidebar.

New sidebar structure

Welcome

Understand (5 pages)
  What are Hypercerts?
  Defining Work Scopes
  Why We're Building Hypercerts
  What is Certified?
  Why ATProto?

Build (6 pages)
  How Hypercerts Work
  Quickstart
  Account & Identity Setup
  Creating Your First Hypercert
  Working with Evaluations
  Common Use Cases

Architecture (4 + 2 pages)
  Infrastructure Overview
    ├── Indexers & Discovery
    └── Portability & Scaling
  Architecture Overview
  Data Flow & Lifecycle
  Funding & Tokenization

Tools (4 pages)
  Hypercerts CLI
  Scaffold Starter App
  Hyperboard
  Hyperindex

Reference (5 + 9 pages)
  Lexicons
    General Lexicons
      ├── Shared Definitions
      └── Location
    Hypercerts Lexicons
      ├── Activity Claim
      ├── Contribution
      ├── Evidence
      ├── Measurement
      ├── Evaluation
      ├── Collection
      └── Rights
  Building on Hypercerts
  Testing & Deployment
  Glossary
  FAQ
  Roadmap

What changed

Pages created

• How Hypercerts Work — merged from "Introduction to Impact Claims" + "The Impact and Work Space" into a practical data model page (record types, ERD, strong references, six dimensions)
• Defining Work Scopes — merged from "The Impact and Work Space" + "Deep Dive: The Work Scope" into a practical guide with SDK examples
• Testing & Deployment — merged from "Error Handling & Constraints" + "Testing & Security" (from PR docs: remove smart contract references, add security model, consolidate reference pages #2)

Pages deleted

• introduction-to-impact-claims.md (merged into How Hypercerts Work)
• the-impact-and-work-space.md (merged into How Hypercerts Work + Defining Work Scopes)
• deep-dive-the-work-scope.md (merged into Defining Work Scopes)
• error-handling.md (merged into Testing & Deployment)
• testing-and-security.md (merged into Testing & Deployment)
• infrastructure/blockchain-integration.md (was already a redirect stub)

Pages restored

• What is Certified? — brought back as standalone page with full PR Improve 'What is Certified?' page #1 content (why it exists, Bluesky callout, app.certified namespace)

Pages rewritten

• Landing page — card links replaced with markdown tables; sections: Start building, Understand, Tools, Reference & Architecture
• Account & Identity Setup — reframed as post-Quickstart configuration guide; added "Why Certified?" subsection and app.certified namespace
• Glossary — trimmed from 20 to 15 terms; removed ATProto internals (XRPC, Relay, Repository, SDS); added Hypergoat, Certified; reordered by usefulness
• FAQ — rewritten to be practical; added "How do I query hypercerts?"; answers link to specific docs

Navigation changes

• Understand before Build — conceptual context before code
• "What are Hypercerts?" moved to Understand (conceptual), "How Hypercerts Work" moved to Build (data model with SDK references)
• Architecture moved up from bottom to after Build (conceptual depth should be adjacent)
• "Building on Hypercerts" moved from Build to Reference (integration guide, not getting-started)
• Roadmap moved into Reference (was a standalone item that visually bled into Reference)
• 9 individual lexicon pages added to sidebar (existed on disk but were unreachable)
• Security model added to Architecture Overview (moved from deleted Testing & Security page)

No content changes

All Architecture, Tools, Lexicon, and tutorial pages are unchanged — only repositioned in the sidebar.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
hypercerts-atproto-documentation	Ready	Preview, Comment	Feb 16, 2026 7:40am