feat: add copy raw and view raw for docs pages

Author: Kzoeps

components/CopyRawButton.js

@@ -0,0 +1,63 @@
+import { useState } from 'react';
+import { useRouter } from 'next/router';
+
+function getRawUrl(currentPath) {
+  if (currentPath === '/') return '/raw/index.md';
+  return `/raw${currentPath}.md`;
+}
+
+export function CopyRawButton() {
+  const [copied, setCopied] = useState(false);
+  const [copyError, setCopyError] = useState(false);
+  const router = useRouter();
+  const currentPath = router.asPath.split('#')[0].split('?')[0] || '/';
+  const rawUrl = getRawUrl(currentPath);
+
+  const handleCopy = async () => {
+    try {
+      const response = await fetch(rawUrl);
+      if (!response.ok) throw new Error('Failed to load raw markdown');
+
+      const raw = await response.text();
+
+      try {
+        await navigator.clipboard.writeText(raw);
+      } catch {
+        const textarea = document.createElement('textarea');
+        textarea.value = raw;
+        document.body.appendChild(textarea);
+        textarea.select();
+        document.execCommand('copy');
+        document.body.removeChild(textarea);
+      }
+
+      setCopyError(false);
+      setCopied(true);
+      setTimeout(() => setCopied(false), 2000);
+    } catch {
+      setCopyError(true);
+      setCopied(false);
+      setTimeout(() => setCopyError(false), 2000);
+    }
+  };
+
+  return (
+    <div className="page-tools" aria-label="Page tools">
+      <button
+        className="page-tools-button"
+        onClick={handleCopy}
+        type="button"
+      >
+        {copied ? 'Copied' : copyError ? 'Copy failed' : 'Copy raw'}
+      </button>
+      <a
+        className="page-tools-link"
+        href={rawUrl}
+        target="_blank"
+        rel="noopener noreferrer"
+      >
+        View raw
+      </a>
+    </div>
+  );
+}

components/Layout.js

@@ -9,6 +9,7 @@ import { LastUpdated } from './LastUpdated';
 import { Breadcrumbs } from './Breadcrumbs';
 import { ThemeToggle } from './ThemeToggle';
 import { SearchDialog } from './SearchDialog';
+import { CopyRawButton } from './CopyRawButton';
 
 const SITE_URL = 'https://docs.hypercerts.org';
 const SITE_NAME = 'Hypercerts Documentation';
@@ -192,6 +193,7 @@ export default function Layout({ children, frontmatter }) {
 
         <main className="layout-content" id="main-content">
           <Breadcrumbs />
+          {frontmatter && <CopyRawButton />}
           <LastUpdated />
           <article>{children}</article>
 

lib/generate-raw-pages.js

@@ -0,0 +1,45 @@
+const {
+  readdirSync,
+  statSync,
+  readFileSync,
+  writeFileSync,
+  rmSync,
+  mkdirSync,
+} = require('fs');
+const { dirname, join, relative } = require('path');
+
+const PAGES_DIR = join(__dirname, '..', 'pages');
+const OUTPUT_DIR = join(__dirname, '..', 'public', 'raw');
+
+function walkDir(dir) {
+  const results = [];
+  for (const entry of readdirSync(dir)) {
+    const full = join(dir, entry);
+    if (statSync(full).isDirectory()) {
+      results.push(...walkDir(full));
+    } else if (full.endsWith('.md')) {
+      results.push(full);
+    }
+  }
+  return results;
+}
+
+function getRawOutputPath(filePath) {
+  const rel = relative(PAGES_DIR, filePath).replace(/\.md$/, '');
+  const route = rel === 'index' ? '/index' : `/${rel.replace(/\/index$/, '')}`;
+  const outputRel = route === '/index' ? 'index.md' : `${route.slice(1)}.md`;
+  return join(OUTPUT_DIR, outputRel);
+}
+
+rmSync(OUTPUT_DIR, { recursive: true, force: true });
+mkdirSync(OUTPUT_DIR, { recursive: true });
+
+const files = walkDir(PAGES_DIR);
+
+for (const file of files) {
+  const outputPath = getRawOutputPath(file);
+  mkdirSync(dirname(outputPath), { recursive: true });
+  writeFileSync(outputPath, readFileSync(file, 'utf-8'));
+}
+
+console.log(`Generated raw markdown files for ${files.length} pages`);

package.json

@@ -4,8 +4,8 @@
   "private": true,
   "description": "Hypercerts Protocol Documentation",
   "scripts": {
-    "dev": "node lib/generate-search-index.js && node lib/generate-last-updated.js && node lib/generate-sitemap.js && next dev --webpack",
-    "build": "node lib/generate-search-index.js && node lib/generate-last-updated.js && node lib/generate-sitemap.js && next build --webpack",
+    "dev": "node lib/generate-search-index.js && node lib/generate-last-updated.js && node lib/generate-sitemap.js && node lib/generate-raw-pages.js && next dev --webpack",
+    "build": "node lib/generate-search-index.js && node lib/generate-last-updated.js && node lib/generate-sitemap.js && node lib/generate-raw-pages.js && next build --webpack",
     "start": "next start"
   },
   "dependencies": {

public/raw/architecture/account-and-identity.md

@@ -0,0 +1,102 @@
+---
+title: Account & Identity Setup
+description: Understand your identity, configure custom domains, and manage credentials.
+---
+
+# Account & Identity Setup
+
+If you followed the [Quickstart](/getting-started/quickstart), you already have an account. This page explains what that account gives you and how to configure it — custom domain handles for organizations, app passwords for scripts, shared repositories for teams, and account recovery.
+
+---
+
+## Create an account
+
+Sign up at [certified.app](https://certified.app/). You'll get:
+
+- **Low-friction sign-in** — Sign in with just your email and a code. No passwords or protocol knowledge required.
+- **A DID** — Your permanent, portable identifier (e.g., `did:plc:z72i7hdynmk6r22z27h6tvur`). It never changes, even if you switch servers or handles.
+- **A Repository** — Your own collection on the certified PDS, where your hypercerts, evaluations, and other records are stored. You own this data and you can migrate it between servers.
+- **An (embedded) wallet** — Add your existing EVM wallet or get a new one.
+- **Ecosystem access** — Your identity works across every Hypercerts application.
+
+### Why Certified?
+
+The Hypercerts Protocol is built on AT Protocol — the same decentralized data layer that powers Bluesky. But most Hypercerts users are not Bluesky users. They are researchers, land stewards, open-source maintainers, funders, and evaluators. Asking them to "sign in with Bluesky" to use a funding platform would be confusing — it ties a funding tool to a social media brand. This is no knock on Bluesky — it's a great platform, just not the right entry point for a funding tool.
+
+Certified is a neutral identity provider that isn't tied to any single application. You create an account and immediately have an identity that works across the entire ecosystem — no knowledge of Bluesky, ATProto, or decentralized protocols required.
+
+{% callout type="note" %}
+Hypercerts is fully interoperable with the AT Protocol ecosystem. If you already have a Bluesky account or any other ATProto identity, log in with your existing handle (e.g., `alice.bsky.social`) and use all Hypercerts applications — no additional account needed.
+{% /callout %}
+
+---
+
+## Your DID
+
+Your DID is your permanent identity. It looks like `did:plc:z72i7hdynmk6r22z27h6tvur` and is resolved via the [PLC directory](https://plc.directory), which maps it to your current PDS, public keys, and handle.
+
+Every record you create carries your DID as the author. If you change PDS providers, your DID stays the same — other applications continue to recognize you and your data migrates with you.
+
+---
+
+## Handles (your public username) and domain verification
+
+Handles are not needed to log in to the Hypercerts ecosystem, but every user has one. They serve as human-readable names for publicly addressing others and for interacting with other applications in the AT Protocol ecosystem that haven't implemented email-based login with Certified. Your handle is a human-readable name like `alice.certified.app`. Unlike your DID, your handle can change — it's a pointer to your DID, not your identity itself.
+
+**Organizations should use custom domain handles.** A handle like `numpy.org` proves organizational identity — anyone can verify that the DID behind `numpy.org` is controlled by whoever controls the domain.
+
+To set up a custom handle, add a DNS TXT record or host a file at `https://your-domain.com/.well-known/atproto-did`. See the [AT Protocol handle documentation](https://atproto.com/specs/handle) for details.
+
+{% callout type="note" %}
+If you sign up using your email on certified.app you will initially be given a random handle like `1lasdk.certified.app`. You can change your handle by going to your profile settings and clicking on "Change handle" on [certified.app](https://certified.app).
+{% /callout %}
+---
+
+## Organization accounts
+
+For teams with multiple contributors, create a dedicated organizational account on a PDS. The organization gets its own DID and repository. Team members can write to the organization's repository using app passwords or OAuth scoped to the organizational account. This is useful for open-source projects, research labs, and organizations where many people contribute to the same body of work.
+
+{% callout type="note" %}
+To set up an organizational account, create an account at [certified.app](https://certified.app) with the organization's email. Use a [custom domain handle](#handles-your-public-username-and-domain-verification) (e.g., `numpy.org`) to prove organizational identity.
+{% /callout %}
+
+---
+
+## Authentication
+
+### OAuth (for applications)
+
+Applications authenticate users via AT Protocol OAuth. The AT Protocol client libraries handle the full OAuth flow — authorization, token management, and session restoration. Users authorize your app through their PDS and never share credentials with your application. See the [Quickstart](/getting-started/quickstart) for the authentication setup.
+
+### OAuth (for ePDS)
+The ePDS (extended PDS) adds email/passwordless login on top of the standard PDS, without modifying the underlying AT Protocol PDS code. When a user authenticates, the ePDS Auth Service handles the OTP flow and then issues a standard AT Protocol authorization code back to your app.
+
+You can integrate ePDS with [`@atproto/oauth-client-node`](https://github.com/bluesky-social/atproto/tree/main/packages/oauth/oauth-client-node). If your app already has an email field, start OAuth normally and add `login_hint=<email>` to the authorization URL before redirecting the user. If your app just has a sign-in button, redirect the user normally and let ePDS collect the email itself. You can also optionally add `epds_handle_mode` to the authorization URL to control how new users get handles.
+
+{% callout type="note" %}
+See [ePDS (extended PDS)](/architecture/epds) for integration examples, handle mode configuration, and client metadata options. A ready-made skill that implements the full ePDS OAuth flow is available at `.agents/skills/epds-login/SKILL.md` in the [ePDS repository](https://github.com/hypercerts-org/ePDS).
+{% /callout %}
+
+
+### App passwords (for scripts and CLI)
+
+For scripts, CLI tools, and server-side automation, use app passwords instead of your main password. App passwords are scoped credentials that can be revoked independently.
+
+Create one in your account settings at [certified.app](https://certified.app). Give it a descriptive name (e.g., "CI/CD pipeline" or "Local development"). If a credential is compromised, revoke just that app password — your main account stays secure. The [Hypercerts CLI](/tools/hypercerts-cli) uses app passwords for authentication.
+
+{% callout type="warning" %}
+Never commit app passwords to version control. Use environment variables or a secrets manager.
+{% /callout %}
+
+---
+
+## The app.certified namespace
+
+Beyond identity, Certified contributes shared data schemas to the AT Protocol ecosystem. You'll see `app.certified.*` in some lexicon names — for example, [`app.certified.location`](/lexicons/certified-lexicons/location) defines how geographic locations are represented. These are general-purpose schemas available to any application on AT Protocol, not just Hypercerts.
+
+---
+
+## Next steps
+
+- [Quickstart](/getting-started/quickstart) — build a complete hypercert with contributions, attachments, and measurements
+- [Working with Evaluations](/getting-started/working-with-evaluations) — create evaluations of other people's work