docs improvements (#294)

nikgraf · web-flow · commit b782faf0b5c6 · 2025-07-01T16:30:28.000+02:00
diff --git a/docs/blog/2025-06-11-hypergraph-alpha-released.md b/docs/blog/2025-06-11-hypergraph-alpha-released.md
@@ -1,50 +1,50 @@
 ---
 slug: hypergraph-alpha-released
-title: Announcing Hypergraph - A New Chapter in Web Development
-date: 2025-06-11
+title: Announcing Hypergraph (Developer Preview)
+date: 2025-07-03
 authors: [nik, pablo]
 tags: [release, alpha, hypergraph]
 ---
 
-After months of development and countless conversations with developers like you, **we're thrilled to unveil the Alpha version of Hypergraph**. This is more than just another data layer—it's a fundamental rethinking of how we build collaborative, secure, and offline-first Web3 applications.
+After months of development and countless conversations with developers like you, **we're thrilled to unveil the Developer Preview version of Hypergraph**. This is more than just another data layer—it's a fundamental rethinking of how we build collaborative, secure, and offline-first Web3 applications.
 
 <!-- truncate -->
 
 ## Why We Built Hypergraph
 
 The challenges of modern app development are clear: users expect real-time collaboration, bulletproof security, and apps that work flawlessly even when offline. Traditional architectures force uncomfortable trade-offs between these needs. We knew there had to be a better way.
 
-Enter Hypergraph, built on two core innovations: a local-first architecture that puts your data where it belongs—on the client—and our implementation of the GRC-20 standard for truly composable knowledge graphs.
+Enter Hypergraph, built on two core innovations: a architecture that puts your data where it belongs—on the client—and our implementation of the GRC-20 standard for truly composable knowledge graphs.
 
 <!-- TODO: ADD IMAGE OF HYPGRAPH UI -->
 
 ## What Makes Hypergraph Different
 
-At its heart, Hypergraph is local-first. Every piece of data is stored on the client, making reads and writes instant—no waiting for server responses. When you're online, our CRDT-based sync ensures your data flows seamlessly between devices and collaborators. When you're offline? Everything just works.
+<!-- At its heart, Hypergraph will local-first. Every piece of data is stored on the client, making reads and writes instant—no waiting for server responses. When you're online, our CRDT-based sync ensures your data flows seamlessly between devices and collaborators. When you're offline? Everything just works. -->
 
 Security isn't an afterthought—it's built into our foundation. With end-to-end encryption, your data is only readable by those you explicitly trust. No intermediaries, no compromises.
 
 The real magic happens with our GRC-20 Knowledge Graph. It's not just a data format; it's a new way of thinking about how information connects and flows through your applications. Every mutation, whether it's adding a note or updating a relationship, becomes part of a larger, interoperable knowledge network.
 
 <!-- TODO: ADD GIF OF DATA MODEL -->
 
-## Looking Ahead
+<!-- ## Looking Ahead
 
-We're launching this alpha today, June 10, 2025, and we're targeting a beta release in August. Our roadmap to a stable release in Q4 2025 is ambitious but achievable with your help. The beta will bring enhanced stability, an expanded API surface, and comprehensive documentation based on your feedback.
+We're launching this alpha today, July 3. Our roadmap to a stable release in Q4 2025 is ambitious but achievable with your help. The beta will bring enhanced stability, an expanded API surface, and comprehensive documentation based on your feedback. -->
 
-## Join the Alpha Today
+<!-- ## Join the Alpha Today
 
 Getting started is simple. Install our SDK:
 
 ```bash
 # TODO: ADD INSTALLER TO NPM npm install @hypergraph/sdk-alpha
 ```
 
-Head to our [Quickstart guide](/docs/quickstart) to build your first Hypergraph app, or dive deep into our [API Reference](/docs/api-reference) to explore the possibilities. We support Node.js and modern browsers, with React hooks that make integration a breeze.
+Head to our [Quickstart guide](/docs/quickstart) to build your first Hypergraph app, or dive deep into our [API Reference](/docs/api-reference) to explore the possibilities. We support Node.js and modern browsers, with React hooks that make integration a breeze. -->
 
 ## A Note on What to Expect
 
-Let's be transparent: this is an alpha release. You'll see rapid changes as we iterate based on your feedback. Some features are still experimental, and you might encounter sync delays with larger graphs or limited support on mobile browsers. But that's exactly why we need you—every bug report, feature request, and question helps shape Hypergraph's future.
+Let's be transparent: this is an developer preview release. You'll see rapid changes as we iterate based on your feedback. Some features are still experimental, and you might encounter sync delays with larger graphs or limited support on mobile browsers. But that's exactly why we need you—every bug report, feature request, and question helps shape Hypergraph's future.
 
 ## Let's Build Together
 
@@ -58,6 +58,6 @@ We read every message and your feedback directly shapes our roadmap.
 
 ## Ready to Shape the Future?
 
-This is just the beginning. Hypergraph represents our vision for the future of Web3 development, but it's your creativity and feedback that will help us realize its full potential. [Get started with the Quickstart](/docs/quickstart), and explore our [API Reference](/docs/api-reference), and join us in building the next generation of collaborative, decentralized applications.
+This is just the beginning. Hypergraph represents our vision for the future of Web3 development, but it's your creativity and feedback that will help us realize its full potential. [Get started with the Quickstart](/docs/quickstart), and join us in building the next generation of collaborative, decentralized applications.
 
 We can't wait to see what you'll create.
diff --git a/docs/docs/core-concepts.md b/docs/docs/core-concepts.md
@@ -7,12 +7,11 @@ tags: [concepts, architecture]
 
 # 🧠 Core Concepts
 
-Hypergraph re-imagines traditional client–server apps as **local-first**, **peer-syncing** knowledge graphs. Understanding the following building blocks will help you design applications that feel real-time, privacy-preserving, and interoperable by default.
+Hypergraph re-imagines traditional client–server apps as knowledge graphs. Understanding the following building blocks will help you design applications that feel real-time, privacy-preserving, and interoperable by default.
 
 ## Table of Contents
 
 - [Knowledge Graphs](#knowledge-graphs)
-- [Hypergraph SDK](#hypergraph-sdk-in-action)
 - [Spaces](#spaces)
 - [Identities](#identities)
 - [Inboxes](#inboxes)
@@ -53,62 +52,6 @@ Hypergraph takes knowledge graphs further by making them:
 
 > **The magic:** Under the hood, Hypergraph serializes everything using the **GRC-20** standard. As a developer, you just work with simple SDK calls—Hypergraph handles the complex cryptography and networking. If you're curious about the low-level details, check out the [GRC-20 section](#grc-20-advanced) below.
 
-## Hypergraph SDK in Action
-
-Let's build that photographer example step by step:
-
-```ts
-import { useHypergraph } from '@graphprotocol/hypergraph-react';
-
-function CreateProfile() {
-  const { createEntity, createRelation } = useHypergraph();
-
-  const handleCreateProfile = async () => {
-    // 1️⃣ Create Teresa as a person
-    const teresa = await createEntity({
-      name: 'Teresa',
-      type: 'Person',
-      properties: {
-        profession: 'photographer',
-        bio: 'Street photographer based in Tokyo'
-      }
-    });
-
-    // 2️⃣ Create her camera
-    const camera = await createEntity({
-      name: 'Fujifilm X100V',
-      type: 'Camera',
-      properties: {
-        brand: 'Fujifilm',
-        model: 'X100V'
-      }
-    });
-
-    // 3️⃣ Connect them with an "owns" relationship
-    await createRelation({
-      from: teresa.id,
-      to: camera.id,
-      type: 'owns',
-      properties: {
-        purchaseDate: '2023-06-15'
-      }
-    });
-  };
-
-  return <button onClick={handleCreateProfile}>Create Profile</button>;
-}
-```
-
-That's it! Behind the scenes, Hypergraph:
-- Generates unique IDs for each entity
-- Encrypts the data (if in a private Space)
-- Syncs changes to all connected devices
-- Makes everything queryable via GraphQL
-
-**Next:** Learn about [Spaces](#spaces)—how Hypergraph organizes people and data into collaborative groups.
-
-<!-- GRC-20 deep-dive moved to the bottom of the doc -->
-
 ## Spaces
 
 A **Space** is the fundamental unit of collaboration.
@@ -183,80 +126,6 @@ Imagine if every social app stored data differently—Instagram used JSON, TikTo
 
 GRC-20 solves this by creating a **universal format** for knowledge. Any app that speaks GRC-20 can read, write, and build upon data created by any other GRC-20 app.
 
-### The Five Building Blocks
-
-Let's decode the sentence *"Teresa, a photographer, owns a Fujifilm camera"* into its GRC-20 components:
-
-| **English** | **GRC-20 Term** | **What It Represents** |
-|-------------|-----------------|------------------------|
-| "Teresa" | **Entity** | A unique thing in the graph |
-| "photographer" | **Value** | A piece of data attached to an entity |
-| "profession" | **Property** | The type/schema of a value |
-| "Person" | **Type** | The category an entity belongs to |
-| "owns" | **Relation** | A connection between two entities |
-
-### Raw GRC-20 Code
-
-Here's how that sentence looks when written directly with the [`@graphprotocol/grc-20`](https://www.npmjs.com/package/@graphprotocol/grc-20) library:
-
-```ts title="Low-level GRC-20 example"
-import { Graph } from '@graphprotocol/grc-20';
-
-// 1️⃣ Define your schema IDs (normally auto-generated)
-const PERSON_TYPE = 'schema:type:person';
-const CAMERA_TYPE = 'schema:type:camera';
-const PROFESSION_PROP = 'schema:property:profession';
-const BRAND_PROP = 'schema:property:brand';
-const OWNS_RELATION = 'schema:relation:owns';
-
-// 2️⃣ Create entities with their properties
-const { id: teresaId, ops: teresaOps } = Graph.createEntity({
-  name: 'Teresa',
-  types: [PERSON_TYPE],
-  values: [
-    { property: PROFESSION_PROP, value: 'photographer' }
-  ]
-});
-
-const { id: cameraId, ops: cameraOps } = Graph.createEntity({
-  name: 'Fujifilm X100V',
-  types: [CAMERA_TYPE],
-  values: [
-    { property: BRAND_PROP, value: 'Fujifilm' }
-  ]
-});
-
-// 3️⃣ Create the relationship
-const { ops: relationOps } = Graph.createRelation({
-  fromEntity: teresaId,
-  toEntity: cameraId,
-  relationType: OWNS_RELATION
-});
-
-// 4️⃣ Bundle everything into a single "edit"
-const allOperations = [...teresaOps, ...cameraOps, ...relationOps];
-
-// 5️⃣ Publish to the network (IPFS, blockchain, etc.)
-await Graph.publishEdit({ ops: allOperations });
-```
-
-### When Would You Use GRC-20 Directly?
-
-Most developers should stick with the Hypergraph SDK! But you might drop down to GRC-20 if you're:
-
-- **Building infrastructure tools** (indexers, validators, etc.)
-- **Migrating data** from other formats into the knowledge graph
-- **Creating custom query engines** that need maximum performance
-- **Debugging issues** at the protocol level
-
-For typical app development, Hypergraph's React hooks and high-level APIs are much more convenient and handle all the GRC-20 complexity for you.
-
----
-
-**Want to learn more?** Read the full [GRC-20 specification](https://github.com/graphprotocol/graph-improvement-proposals/blob/main/grcs/0020-knowledge-graph.md) on GitHub.
-
----
-
 ### Edit on GitHub
 
 [✏️ Suggest changes](https://github.com/graphprotocol/hypergraph/edit/main/docs/docs/core-concepts.md) 
diff --git a/docs/docs/quickstart.md b/docs/docs/quickstart.md
@@ -35,7 +35,7 @@ It will walk you through creating a new, fully-functional React application powe
 
 ### 1. Install the Hypergraph CLI
 
-First, clone the Hypergraph repository, which contains TypeSync.
+First install the Hypergraph CLI.
 
 ```bash
 npm install -g @graphprotocol/hypergraph-cli@latest
diff --git a/docs/docs/schema.md b/docs/docs/schema.md
@@ -4,7 +4,7 @@ The Hypergraph schema allows you define the data model for your application. It
 
 ## Example
 
-Here is an example of a schema for a Todo app with the properties `name` and `completed`.
+Here is an example of a schema for an Event app with the properties `name` and `description`.
 
 ```ts
 import { Entity, Type } from '@graphprotocol/hypergraph';
diff --git a/docs/src/pages/index.js b/docs/src/pages/index.js
@@ -15,8 +15,9 @@ function HomepageHeader() {
         <Heading as="h1" className="hero__title">
           {siteConfig.title}
         </Heading>
+        <p style={{ marginTop: '-0.5rem', marginBottom: '2rem' }}>(Developer Preview)</p>
         <p className="hero__subtitle">{siteConfig.tagline}</p>
-        <div className={styles.buttons}>
+        <div className={styles.buttons} style={{ marginTop: '5rem' }}>
           <Link className="button button--secondary button--lg" to="/docs/quickstart">
             Hypergraph Quickstart - 5min ⏱️
           </Link>
