docs(upload): add receipts guide flow and verification guidance

content/build/upload/index.mdx

@@ -152,6 +152,11 @@ Before uploading, learn best practices for structuring and tagging your data for
     description="Create folder structures and host websites"
     href="/build/upload/manifests"
   />
+  <Card
+    title="Receipts"
+    description="Capture timestamped upload attestations to preserve chronology and auditability"
+    href="/build/upload/receipts"
+  />
   <Card
     title="Encryption"
     description="Secure your data with client-side encryption"

content/build/upload/manifests.mdx

@@ -253,6 +253,14 @@ This makes HTML more readable and ensures links remain valid even if the hosting
 ## Next Steps
 
 <Cards>
+  <Card 
+    href="/build/upload/receipts" 
+    title="Receipts"
+    icon={<Upload />}
+  >
+    Capture timestamped upload attestations for chronology and audits.
+  </Card>
+
   <Card 
     href="/build/upload/encryption" 
     title="Data Encryption"

content/build/upload/meta.json

@@ -9,6 +9,7 @@
     "turbo-credits",
     "tagging",
     "manifests",
+    "receipts",
     "encryption"
   ]
 }

content/build/upload/receipts.mdx

@@ -0,0 +1,247 @@
+---
+title: "Receipts"
+description: "Understand Turbo upload receipts for chronology, auditability, and later verification workflows"
+---
+
+Turbo upload receipts provide a durable record of what was uploaded, who uploaded it, and what upload cost was assessed in Winston Credits (`winc`). They are useful for provenance, compliance, incident response, and operational debugging.
+
+## What Are Turbo Receipts?
+
+A Turbo receipt is a signed upload attestation returned by Turbo upload flows when a data item is successfully accepted and processed.
+
+In practice, receipts help you:
+
+- Link app-level records to immutable data item IDs
+- Track upload ownership and storage cost (`winc`)
+- Keep machine-readable proof metadata for investigations and audits
+
+<Callout type="info">
+  Receipts are proof of Turbo upload acceptance and signed receipt metadata for
+  a specific upload event. They are not a full substitute for your own
+  retrieval checks, gateway checks, or finality policies.
+</Callout>
+
+## Why Time and Ordering Matter
+
+Receipt timestamps are especially valuable because they let you prove when upload events occurred and how related uploads were ordered.
+
+- A receipt `timestamp` supports evidence of event time in incident and audit workflows.
+- Ordered receipts create chronology across related data items (for example, original item, revision, and derived artifacts).
+- Chronology improves chain-of-custody reconstruction and post-incident analysis.
+
+For production systems, preserving upload order can be as important as preserving data IDs.
+
+## When Receipts Are Created
+
+Turbo receipts are created in three common contexts:
+
+1. Standard SDK uploads: `turbo.upload()` and `turbo.uploadFile()` return upload result payloads that include receipt metadata such as `id`, `owner`, `winc`, `dataCaches`, and `fastFinalityIndexes`.
+2. Multipart uploads: for larger uploads that use chunking, Turbo finalizes the upload and returns a finalized receipt payload when multipart status reaches `FINALIZED`.
+3. x402 uploads: Turbo still returns an upload receipt, and x402 tooling can also provide a separate payment settlement receipt.
+
+Regardless of flow, store receipt timestamps and your own sequence metadata so ordered events can be reconstructed later.
+
+<Callout type="warning">
+  Turbo does not store and retrieve your receipts for you. If you need receipts
+  later, persist the exact payload returned by Turbo in your own storage. You
+  can also optionally store receipt records on Arweave for long-term archival.
+  See [Capturing Receipts in Turbo
+  SDK](#capturing-receipts-in-turbo-sdk) for an implementation example.
+</Callout>
+
+## Receipt Anatomy
+
+| Field | Meaning | Notes |
+| ----- | ------- | ----- |
+| `id` | Data item transaction ID | Primary key to join with your app records |
+| `owner` | Normalized address that signed/owns the data item | Useful for audit and policy checks |
+| `winc` | Upload cost measured in Winston Credits | Useful for billing and reporting. See [Paying for Uploads](/build/upload/turbo-credits) for unit and payment context |
+| `dataCaches` | Caches that accepted the data item | Operational visibility for upload path |
+| `fastFinalityIndexes` | Fast finality indexes that accepted the data item | Useful for observability |
+| `timestamp` | Receipt creation time in milliseconds | Core field for chronology, ordering, and evidence of event time |
+| `version` | Receipt schema/version identifier | Determines how verification inputs should be interpreted |
+| `deadlineHeight` | Deadline block height recorded in receipt payload | Useful as additional upload context |
+| `public` | Public key that signed the receipt | Needed to verify signature validity |
+| `signature` | Base64URL receipt signature | Required to verify receipt authenticity |
+
+Some fields vary by upload path and service response shape. Do not assume every SDK return object includes every signed receipt field in all flows.
+
+## Capturing Receipts in Turbo SDK
+
+Capture the upload response as your receipt record and persist it alongside your own object IDs. Below is a simple example, in practice you might chose to store this alongside your existing logs in S3, Sentry or similar:
+
+```typescript
+import fs from "fs";
+import { TurboFactory } from "@ardrive/turbo-sdk";
+
+const turbo = TurboFactory.authenticated({ privateKey });
+
+const receipt = await turbo.uploadFile({
+  fileStreamFactory: () => fs.createReadStream("./report.json"),
+  fileSizeFactory: () => fs.statSync("./report.json").size,
+  dataItemOpts: {
+    tags: [
+      { name: "Content-Type", value: "application/json" },
+      { name: "App-Name", value: "AnalyticsPipeline-v1.0" },
+    ],
+  },
+});
+
+await fetch("https://api.yourdomain.com/upload-receipts", {
+  method: "POST",
+  headers: { "Content-Type": "application/json" },
+  body: JSON.stringify({
+    appObjectId: "report-2026-02-16",
+    capturedAt: new Date().toISOString(),
+    receipt,
+  }),
+});
+
+console.log("Stored Turbo receipt:", {
+  id: receipt.id,
+  timestamp: receipt.timestamp,
+  owner: receipt.owner,
+  winc: receipt.winc,
+});
+```
+
+<Callout type="info">
+  Turbo CLI upload commands print JSON output that can be captured as a receipt
+  record in scripts and CI pipelines.
+</Callout>
+
+## Why Receipts Matter Across ar.io Use Cases
+
+| AR.IO Use Case | Receipt Value |
+| -------------- | ------------- |
+| [File Storage](https://ar.io/use-cases/file-storage/) | Map internal file objects to immutable upload IDs and timestamped upload events |
+| [Websites & Apps](https://ar.io/use-cases/websites-and-apps/) | Track deployment artifacts and ordering of publish history over time |
+| [Apps & Game Assets](https://ar.io/use-cases/apps-and-game-assets/) | Prove that specific asset versions were accepted and in which sequence they were released |
+| [Media Provenance](https://ar.io/use-cases/media-provenance/) | Establish chain-of-custody metadata for original and derivative media with event ordering |
+| [Verifiable AI Data](https://ar.io/use-cases/verifiable-ai-data/) | Attach signed upload evidence and chronology to datasets, prompts, and model outputs |
+| [Verifiable Computing](https://ar.io/use-cases/verifiable-computing/) | Bind compute inputs/outputs to durable upload receipts for reproducibility and timeline checks |
+| [Durable Financial Data](https://ar.io/use-cases/durable-financial-data/) | Maintain publish-time evidence for disclosures, reports, and compliance records |
+
+## Deep Dive: Media Provenance
+
+Receipts strengthen provenance workflows by giving each media upload a signed event record with a timestamp and ordering context.
+
+- Preserve the receipt for original media ingestion
+- Store receipts for edited or transformed derivatives
+- Link parent and derivative records in your metadata model
+- Use receipt IDs, timestamps, and signed fields as part of publishing audit trails
+
+This gives teams a clearer chain-of-custody model for authenticity claims, moderation workflows, and external verification requests.
+
+## Deep Dive: Verifiable AI Data
+
+AI pipelines benefit from receipts because reproducibility depends on stable, attributable inputs and outputs over time.
+
+- Store receipts for datasets, prompts, and generated artifacts
+- Link receipts to model versions, run IDs, and evaluation jobs
+- Preserve ordered receipt timelines to reconstruct dataset-to-output lineage
+- Use receipts as evidence in regulated or policy-bound AI workflows
+
+This makes lineage more transparent and reduces ambiguity when debugging model behavior or validating published results.
+
+## Verifying Receipts Later
+
+Delayed verification is valuable for audits, disputes, compliance reviews, and reproducibility checks that happen long after initial upload.
+
+### Verification Checklist
+
+1. Load the stored receipt payload.
+2. Validate required fields (`id`, `version`, `public`, `signature`, and contextual fields you depend on).
+3. Verify the signature against the public key using receipt-version-specific hashing/signing rules.
+4. Confirm data item status and availability via Turbo or gateway status endpoints.
+5. Compare verified receipt data with your internal upload metadata and flag mismatches.
+
+Example verification workflow:
+
+```typescript
+type StoredReceipt = {
+  id: string;
+  version?: string;
+  public?: string;
+  signature?: string;
+  timestamp?: number;
+  owner?: string;
+};
+
+async function verifyStoredReceipt(receipt: StoredReceipt) {
+  if (!receipt.id || !receipt.version || !receipt.public || !receipt.signature) {
+    throw new Error("Receipt is missing required verification fields.");
+  }
+
+  // Implement this in your backend with version-aware receipt rules.
+  const signatureValid = await verifyReceiptSignatureForVersion(receipt);
+  if (!signatureValid) {
+    throw new Error(`Invalid receipt signature for ${receipt.id}`);
+  }
+
+  const statusResponse = await fetch(
+    `https://upload.ardrive.io/v1/tx/${receipt.id}/status`,
+  );
+
+  if (!statusResponse.ok) {
+    throw new Error(`Unable to retrieve status for ${receipt.id}`);
+  }
+
+  const status = await statusResponse.json();
+
+  return {
+    id: receipt.id,
+    signatureValid,
+    status,
+  };
+}
+```
+
+<Callout type="warning">
+  Verification inputs are receipt-version dependent. Do not assume every
+  response field is signature-bound in every version, and do not assume a
+  high-level SDK helper exists unless it is explicitly documented for your
+  target version.
+</Callout>
+
+## Best Practices
+
+- Persist raw receipt payloads server-side and keep them immutable
+- Store receipts with your own object IDs, pipeline IDs, and environment metadata
+- Index by data item `id` for fast traceability across systems
+- Preserve upload chronology (for example sequence numbers, parent/child links, and timestamps)
+- Capture both upload receipts and payment receipts when using x402
+- Re-check status/finality in stricter workflows using service or gateway checks
+
+<Callout type="warning">
+  Treat a receipt as proof of Turbo upload acceptance and signing for that
+  event, not as a blanket guarantee for every downstream retrieval state.
+</Callout>
+
+## Next Steps
+
+<Cards>
+  <Card href="/build/upload/manifests" title="Manifests" icon={<FolderOpen />}>
+    Connect receipt evidence to structured path-based content organization.
+  </Card>
+
+  <Card href="/build/upload/encryption" title="Data Encryption" icon={<Shield />}>
+    Protect sensitive content before uploading to permanent storage.
+  </Card>
+
+  <Card
+    href="/build/upload/x402-uploading-to-turbo"
+    title="x402 Uploading To Turbo"
+    icon={<CreditCard />}
+  >
+    Add just-in-time payment flows to your upload pipeline.
+  </Card>
+
+  <Card
+    href="/build/upload/turbo-credits"
+    title="Paying for Uploads"
+    icon={<CreditCard />}
+  >
+    Understand Turbo Credits, top ups, and funding workflows.
+  </Card>
+</Cards>

content/build/upload/x402-uploading-to-turbo.mdx

@@ -70,6 +70,12 @@ await turbo.uploadRawX402Data({
 });
 ```
 
+<Callout type="info">
+  **Receipt context:** x402 integrations can surface both an upload receipt and a
+  payment settlement receipt. For how to capture and store Turbo upload
+  receipts, see [Receipts](/build/upload/receipts#verifying-receipts-later).
+</Callout>
+
 ### x402 Ecosystem Tooling
 
 Using the raw data API, developers can upload data to Turbo with minimal code using existing x402 ecosystem tooling.

content/glossary.mdx → content/glossary/index.mdx

@@ -7,6 +7,14 @@ description: "Key terms and definitions for the ar.io ecosystem"
 
 AO (Actor Oriented) is a hyper-parallel computing platform built on Arweave that enables decentralized applications to run with unlimited computational capacity. AO provides the compute layer for ar.io's smart contracts and token operations.
 
+## Winston
+
+Winston is the smallest unit of Arweave's native AR token. One AR equals 10^12 Winston.
+
+## Winston Credits (winc)
+
+Winston Credits (`winc`) are the unit used by Turbo to represent upload purchasing power. In Turbo contexts, receipt and balance fields often return values in `winc`.
+
 ## Public Key
 
 A cryptographic key that can be shared publicly and is used to verify digital signatures or encrypt data. In the ar.io context, public keys are used to identify wallet addresses and verify transactions.

content/glossary/meta.json

@@ -0,0 +1,7 @@
+{
+  "title": "Glossary",
+  "icon": "BookText",
+  "root": true,
+  "defaultOpen": false,
+  "pages": ["index"]
+}

content/meta.json

@@ -1,5 +1,5 @@
 {
   "title": "ar.io Docs",
   "root": true,
-  "pages": ["...", "learn", "build", "sdks", "apis", "guides", "!migrated"]
+  "pages": ["...", "learn", "build", "sdks", "apis", "glossary", "guides", "!migrated"]
 }

redirects.mjs

@@ -404,11 +404,6 @@ const redirects = [
   },
 
   // Community and other pages
-  {
-    source: '/glossary',
-    destination: '/glossary',
-    permanent: true,
-  },
   {
     source: '/community-resources',
     destination: '/',

src/components/page-actions.tsx

@@ -82,10 +82,9 @@ export function ViewOptions({
   githubUrl: string;
 }) {
   const items = useMemo(() => {
-    const fullMarkdownUrl =
-      typeof window !== 'undefined'
-        ? new URL(markdownUrl, window.location.origin)
-        : 'loading';
+    // markdownUrl is already passed as an absolute URL, so avoid client-only
+    // window access during render to keep server/client output deterministic.
+    const fullMarkdownUrl = markdownUrl;
     const q = `Read ${fullMarkdownUrl}, I want to ask questions about it.`;
 
     return [

src/lib/source.ts

@@ -100,6 +100,8 @@ export const source = loader({
     }
 
     // Handle lucide-react icons
-    if (icon in icons) return createElement(icons[icon as keyof typeof icons]);
+    if (icon in icons) {
+      return createElement(icons[icon as keyof typeof icons], { key: String(icon) });
+    }
   },
 });