mdbase-dev · callumalpass · Jul 26, 2026 · Jul 26, 2026
diff --git a/public/examples/sandbox-quickstart.mjs b/public/examples/sandbox-quickstart.mjs
@@ -0,0 +1,50 @@
+import { unwrapOperation } from "@mdbase/connect";
+import { createSandbox } from "@mdbase/connect-dev";
+
+const { client, transport } = createSandbox({
+  records: [
+    {
+      path: "tasks/first.md",
+      types: ["task"],
+      frontmatter: {
+        type: "task",
+        title: "Read the collection",
+        completed: false
+      }
+    }
+  ]
+});
+
+const first = unwrapOperation(await client.read({ path: "tasks/first.md" }));
+
+const created = unwrapOperation(
+  await client.create({
+    type: "task",
+    path: "tasks/second.md",
+    frontmatter: {
+      type: "task",
+      title: "Update one record",
+      completed: false
+    }
+  })
+);
+
+const updated = unwrapOperation(
+  await client.update({
+    path: created.path,
+    patch: { completed: true },
+    if_revision: created.revision
+  })
+);
+
+const tasks = unwrapOperation(
+  await client.query({
+    types: ["task"],
+    limit: 20
+  })
+);
+
+console.log(`Read: ${first.frontmatter.title}`);
+console.log(`Updated: ${updated.path} (completed: ${updated.frontmatter.completed})`);
+console.log(`Task records: ${tasks.results.length}`);
+console.log(`Markdown paths: ${transport.snapshot().map((record) => record.path).join(", ")}`);
diff --git a/src/components/DocsLayout.astro b/src/components/DocsLayout.astro
@@ -9,20 +9,36 @@ interface Props {
 }
 
 const { title, description, active, headings = [] } = Astro.props;
-const docs = [
-  { href: "/sdk/", label: "Overview", key: "overview" },
-  { href: "/sdk/quickstart/", label: "Quickstart", key: "quickstart" },
-  { href: "/sdk/portable-apps/", label: "Portable HTML apps", key: "portable-apps" },
-  { href: "/sdk/manifest/", label: "Application manifest", key: "manifest" },
-  { href: "/sdk/contracts/", label: "Contracts and adapters", key: "contracts" },
-  { href: "/sdk/authorization/", label: "Authorization", key: "authorization" },
-  { href: "/sdk/operations/", label: "Records and operations", key: "operations" },
-  { href: "/sdk/routing/", label: "Local and hosted routes", key: "routing" },
-  { href: "/sdk/testing/", label: "Testing", key: "testing" },
-  { href: "/sdk/notifications/", label: "Notifications and timers", key: "notifications" },
-  { href: "/sdk/offline-sync/", label: "Offline sync", key: "offline-sync" },
-  { href: "/sdk/security/", label: "Security model", key: "security" },
-  { href: "/sdk/api/", label: "API reference", key: "api" }
+const docGroups = [
+  {
+    label: "Start",
+    docs: [
+      { href: "/sdk/quickstart/", label: "Try the SDK locally", key: "quickstart" },
+      { href: "/sdk/connect-quickstart/", label: "Connect a browser app", key: "connect-quickstart" },
+      { href: "/sdk/", label: "SDK overview", key: "overview" }
+    ]
+  },
+  {
+    label: "Build",
+    docs: [
+      { href: "/sdk/portable-apps/", label: "Portable HTML apps", key: "portable-apps" },
+      { href: "/sdk/manifest/", label: "Application manifest", key: "manifest" },
+      { href: "/sdk/contracts/", label: "Contracts and adapters", key: "contracts" },
+      { href: "/sdk/authorization/", label: "Authorization", key: "authorization" },
+      { href: "/sdk/operations/", label: "Records and operations", key: "operations" },
+      { href: "/sdk/routing/", label: "Local and hosted routes", key: "routing" },
+      { href: "/sdk/testing/", label: "Testing", key: "testing" },
+      { href: "/sdk/notifications/", label: "Notifications and timers", key: "notifications" },
+      { href: "/sdk/offline-sync/", label: "Offline sync", key: "offline-sync" }
+    ]
+  },
+  {
+    label: "Reference",
+    docs: [
+      { href: "/sdk/security/", label: "Security model", key: "security" },
+      { href: "/sdk/api/", label: "API reference", key: "api" }
+    ]
+  }
 ];
 ---
 
@@ -33,10 +49,17 @@ const docs = [
         <summary>Connect SDK</summary>
         <nav aria-label="SDK documentation">
           {
-            docs.map((doc) => (
-              <a href={doc.href} aria-current={active === doc.key ? "page" : undefined}>
-                {doc.label}
-              </a>
+            docGroups.map((group) => (
+              <div class="docs-nav__group">
+                <strong>{group.label}</strong>
+                {
+                  group.docs.map((doc) => (
+                    <a href={doc.href} aria-current={active === doc.key ? "page" : undefined}>
+                      {doc.label}
+                    </a>
+                  ))
+                }
+              </div>
             ))
           }
         </nav>

diff --git a/src/components/SiteFooter.astro b/src/components/SiteFooter.astro
@@ -5,7 +5,11 @@
       <p>Markdown collections with types, queries, and explicit app permissions.</p>
     </div>
     <nav aria-label="Footer navigation">
+      <a href="/#orientation">Start here</a>
+      <a href="/connect/">Connect</a>
       <a href="/sdk/">SDK docs</a>
+      <a href="/runtime/">Runtime</a>
+      <a href="/implementations/">Implementations</a>
       <a href="/spec/">Specification</a>
       <a href="/security/">Security</a>
       <a href="/privacy/">Privacy</a>

diff --git a/src/components/SiteHeader.astro b/src/components/SiteHeader.astro
@@ -2,16 +2,16 @@
 import BrandMark from "./BrandMark.astro";
 
 interface Props {
-  current?: "connect" | "sdk" | "runtime" | "implementations" | "spec";
+  current?: "home" | "connect" | "sdk" | "runtime" | "implementations" | "spec";
   showSceneCount?: boolean;
 }
 
 const { current, showSceneCount = false } = Astro.props;
 const links = [
+  { href: "/", label: "Learn", key: "home" },
   { href: "/connect/", label: "Connect", key: "connect" },
-  { href: "/sdk/", label: "SDK", key: "sdk" },
-  { href: "/runtime/", label: "Runtime", key: "runtime" },
-  { href: "/implementations/", label: "Implementations", key: "implementations" },
+  { href: "/sdk/quickstart/", label: "Build", key: "sdk" },
+  { href: "/implementations/", label: "Implement", key: "implementations" },
   { href: "/spec/", label: "Spec", key: "spec" }
 ] as const;
 ---

diff --git a/src/layouts/BaseLayout.astro b/src/layouts/BaseLayout.astro
@@ -12,7 +12,7 @@ import ThemeControlScript from "../components/ThemeControlScript.astro";
 interface Props {
   title: string;
   description: string;
-  current?: "connect" | "sdk" | "runtime" | "implementations" | "spec";
+  current?: "home" | "connect" | "sdk" | "runtime" | "implementations" | "spec";
   noIndex?: boolean;
 }
 

diff --git a/src/layouts/HomeLayout.astro b/src/layouts/HomeLayout.astro
@@ -41,7 +41,7 @@ const canonical = new URL(Astro.url.pathname, Astro.site);
   </head>
   <body class="home-body">
     <a class="home-skip-link" href="#intro">Skip to introduction</a>
-    <SiteHeader showSceneCount />
+    <SiteHeader current="home" showSceneCount />
     <slot />
     <SiteFooter />
     <ThemeControlScript />

diff --git a/src/pages/connect/index.astro b/src/pages/connect/index.astro
@@ -34,19 +34,48 @@ const steps = [
       </div>
       <div class="page-hero__aside">
         <p>
-          mdbase Connect handles authorization, routing, and collection
-          hosting. A grant binds one application to one collection and an
-          approved set of operations. Local folder paths stay at the connector.
+          An application sends the user to Connect. The user chooses one
+          compatible collection and approves exact actions. The application
+          receives a collection-bound connection; local folder paths stay on
+          the user's computer.
         </p>
         <div class="button-row">
-          <a class="button button--primary" href="/sdk/quickstart/">SDK quickstart</a>
+          <a class="button button--primary" href="/sdk/connect-quickstart/">Connect an app</a>
+          <a class="button" href="/sdk/quickstart/">Try the SDK locally</a>
           <a class="button" href="/sdk/portable-apps/">Portable HTML apps</a>
           <a class="button" href="https://github.com/mdbase-dev/mdbase-connect">View source</a>
         </div>
       </div>
     </div>
   </section>
 
+  <section class="content-section">
+    <h2>Where Connect sits</h2>
+    <p>
+      Connect is optional. Applications can also use a conforming mdbase
+      implementation directly. Connect provides a common approval and routing
+      path when independent applications need access to a user's collections.
+    </p>
+    <ol class="plain-sequence" aria-label="Connect request path">
+      <li>
+        <strong>Application</strong>
+        <span>Declares compatible collections and requests exact operations.</span>
+      </li>
+      <li>
+        <strong>Connect</strong>
+        <span>Presents the request, records the decision, and selects the route.</span>
+      </li>
+      <li>
+        <strong>Collection authority</strong>
+        <span>Rechecks the grant and executes each approved operation.</span>
+      </li>
+      <li>
+        <strong>mdbase collection</strong>
+        <span>Remains the authoritative Markdown and collection history.</span>
+      </li>
+    </ol>
+  </section>
+
   <section class="content-section">
     <h2>Local and hosted collections</h2>
     <p>
@@ -164,4 +193,30 @@ const steps = [
       </a>
     </div>
   </section>
+
+  <section class="content-section">
+    <h2>Terms used on this site</h2>
+    <dl class="glossary-list">
+      <div>
+        <dt>Grant</dt>
+        <dd>One user's approval for one application, one collection, and a concrete set of operations.</dd>
+      </div>
+      <div>
+        <dt>Authority</dt>
+        <dd>The local connector or hosted provider that controls the main copy and makes the final authorization decision.</dd>
+      </div>
+      <div>
+        <dt>Control plane</dt>
+        <dd>The Connect service for identity, pairing, grants, short-lived tokens, and route coordination.</dd>
+      </div>
+      <div>
+        <dt>Contract</dt>
+        <dd>A portable declaration of domain behavior and its mapping to one collection type.</dd>
+      </div>
+      <div>
+        <dt>Operation envelope</dt>
+        <dd>A typed result containing a validity flag, result value, and structured diagnostics.</dd>
+      </div>
+    </dl>
+  </section>
 </BaseLayout>