From c4a9825c8e25b442fd1c09cb674648cb4b789080 Mon Sep 17 00:00:00 2001
From: Russell Dempsey <1173416+SgtPooki@users.noreply.github.com>
Date: Wed, 29 Jul 2026 13:33:01 -0400
Subject: [PATCH 01/26] feat(ipfs2filecoin): add IPFS to Filecoin campaign
 landing page

Adds filecoin.cloud/ipfs2filecoin, the front door for the IPFS-to-Filecoin
mini-campaign, ported from Jenni's wireframe in FilOzone/FOC-PM onto the
site's existing ui-filecoin components.

The page is both the campaign's front door and its measuring instrument. It
does three things: takes a pasted CID list, produces a deposit estimate from a
declared volume, and routes to the agent door or to contact.

Interactive parts run entirely client-side, with no wallet and no network
calls, so a check costs the visitor nothing and sends us nothing:

- CID list checker: validates, dedupes, and steers lists over the 500-item
  browser cap to the agent prompt.
- Deposit estimator: reproduces the PRD's worked example exactly ($128.08
  deposit, $5.25 refundable for 1 TiB over two years) from documented
  constants rather than hardcoded figures.
- Agent prompt with copy-to-clipboard, the primary conversion.

Plausible events cover the funnel the PRD asks for: CID List Checked,
Estimate Viewed, and Agent Prompt Copied, the last being the headline number.

Also serves a draft migration brief at /ipfs2filecoin/llms.txt and advertises
it via <link rel="alternate" type="text/markdown">, so an agent pointed at the
human URL discovers the brief without being told the convention. The brief
opens with a stage 0 ingress check, per the 2026-07-28 validation run that
found runs die there after the expensive commP pass.

The page is unlinked from site navigation, reachable by URL and sitemap only,
so campaign attribution stays clean.
---
 .../ipfs2filecoin/components/AgentPrompt.tsx  |  42 +++
 .../components/CidListChecker.tsx             | 191 +++++++++++++
 .../components/ComparisonTable.tsx            |  56 ++++
 .../components/CostEstimator.tsx              | 225 +++++++++++++++
 src/app/ipfs2filecoin/constants/migration.ts  |  40 +++
 src/app/ipfs2filecoin/constants/seo.ts        |   5 +
 src/app/ipfs2filecoin/data/faqs.tsx           | 109 +++++++
 src/app/ipfs2filecoin/data/limits.ts          |  31 ++
 .../ipfs2filecoin/data/pricing-comparison.ts  |  37 +++
 src/app/ipfs2filecoin/data/reasons.ts         |  22 ++
 src/app/ipfs2filecoin/data/steps.ts           |  26 ++
 src/app/ipfs2filecoin/llms.txt/route.ts       | 121 ++++++++
 src/app/ipfs2filecoin/page.tsx                | 267 ++++++++++++++++++
 src/app/ipfs2filecoin/utils/estimate-cost.ts  |  78 +++++
 .../utils/generate-structured-data.ts         |  23 ++
 src/app/ipfs2filecoin/utils/parse-cid-list.ts |  40 +++
 src/constants/paths.ts                        |   4 +
 17 files changed, 1317 insertions(+)
 create mode 100644 src/app/ipfs2filecoin/components/AgentPrompt.tsx
 create mode 100644 src/app/ipfs2filecoin/components/CidListChecker.tsx
 create mode 100644 src/app/ipfs2filecoin/components/ComparisonTable.tsx
 create mode 100644 src/app/ipfs2filecoin/components/CostEstimator.tsx
 create mode 100644 src/app/ipfs2filecoin/constants/migration.ts
 create mode 100644 src/app/ipfs2filecoin/constants/seo.ts
 create mode 100644 src/app/ipfs2filecoin/data/faqs.tsx
 create mode 100644 src/app/ipfs2filecoin/data/limits.ts
 create mode 100644 src/app/ipfs2filecoin/data/pricing-comparison.ts
 create mode 100644 src/app/ipfs2filecoin/data/reasons.ts
 create mode 100644 src/app/ipfs2filecoin/data/steps.ts
 create mode 100644 src/app/ipfs2filecoin/llms.txt/route.ts
 create mode 100644 src/app/ipfs2filecoin/page.tsx
 create mode 100644 src/app/ipfs2filecoin/utils/estimate-cost.ts
 create mode 100644 src/app/ipfs2filecoin/utils/generate-structured-data.ts
 create mode 100644 src/app/ipfs2filecoin/utils/parse-cid-list.ts

diff --git a/src/app/ipfs2filecoin/components/AgentPrompt.tsx b/src/app/ipfs2filecoin/components/AgentPrompt.tsx
new file mode 100644
index 00000000..1569d9f6
--- /dev/null
+++ b/src/app/ipfs2filecoin/components/AgentPrompt.tsx
@@ -0,0 +1,42 @@
+'use client'
+
+import { Button } from '@filecoin-foundation/ui-filecoin/Button'
+import { usePlausible } from 'next-plausible'
+
+import { useCopyToClipboard } from '@/hooks/use-copy-to-clipboard'
+
+import { AGENT_PROMPT, PLAUSIBLE_EVENTS } from '../constants/migration'
+
+type AgentPromptProps = {
+  /** Where on the page the prompt was copied from, so the two spots stay distinguishable. */
+  source: 'verdict' | 'agent-door'
+}
+
+export function AgentPrompt({ source }: AgentPromptProps) {
+  const { copy, isCopied } = useCopyToClipboard()
+  const plausible = usePlausible()
+
+  async function handleCopy() {
+    const copied = await copy(AGENT_PROMPT)
+
+    if (copied) {
+      plausible(PLAUSIBLE_EVENTS.promptCopied, { props: { source } })
+    }
+  }
+
+  return (
+    <div className="space-y-3">
+      <code className="block rounded-lg border border-(--color-border-muted) bg-(--color-card-background) p-3 font-mono text-(--color-paragraph-text) text-xs/relaxed">
+        {AGENT_PROMPT}
+      </code>
+
+      <Button type="button" variant="ghost" onClick={handleCopy}>
+        {isCopied ? 'Copied' : 'Copy prompt'}
+      </Button>
+
+      <span aria-live="polite" className="sr-only">
+        {isCopied ? 'Prompt copied to clipboard' : ''}
+      </span>
+    </div>
+  )
+}
diff --git a/src/app/ipfs2filecoin/components/CidListChecker.tsx b/src/app/ipfs2filecoin/components/CidListChecker.tsx
new file mode 100644
index 00000000..14e25136
--- /dev/null
+++ b/src/app/ipfs2filecoin/components/CidListChecker.tsx
@@ -0,0 +1,191 @@
+'use client'
+
+import { Button } from '@filecoin-foundation/ui-filecoin/Button'
+import { SmartTextLink } from '@filecoin-foundation/ui-filecoin/TextLink/SmartTextLink'
+import { Field, Label, Textarea } from '@headlessui/react'
+import { usePlausible } from 'next-plausible'
+import { useId, useState } from 'react'
+
+import { PATHS } from '@/constants/paths'
+
+import { AgentPrompt } from './AgentPrompt'
+import {
+  BROWSER_CHECK_ITEM_CAP,
+  MAX_ITEM_SIZE_LABEL,
+  PLAUSIBLE_EVENTS,
+} from '../constants/migration'
+import { type CidListSummary, parseCidList } from '../utils/parse-cid-list'
+
+const PLACEHOLDER = [
+  'bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi',
+  'bafkreieq5jui4j25lacwomsqgjeswwl3y5zcdrresptwgmfylxo2depppq',
+  'QmYwAPJzv5CZsnA625s3Xf2nemtYgPpHdWEz79ojWnPbdG',
+].join('\n')
+
+type Verdict =
+  | { kind: 'empty' }
+  | { kind: 'unreadable'; summary: CidListSummary }
+  | { kind: 'ok'; summary: CidListSummary }
+  | { kind: 'over-cap'; summary: CidListSummary }
+
+function getVerdict(summary: CidListSummary): Verdict {
+  if (summary.totalLines === 0) {
+    return { kind: 'empty' }
+  }
+  if (summary.uniqueCids.length === 0) {
+    return { kind: 'unreadable', summary }
+  }
+  if (summary.uniqueCids.length > BROWSER_CHECK_ITEM_CAP) {
+    return { kind: 'over-cap', summary }
+  }
+  return { kind: 'ok', summary }
+}
+
+function pluralize(count: number, singular: string, plural = `${singular}s`) {
+  return count === 1 ? singular : plural
+}
+
+function buildNotes({ invalidCount, duplicateCount }: CidListSummary) {
+  const notes: Array<string> = []
+
+  if (invalidCount > 0) {
+    notes.push(
+      `${invalidCount} ${pluralize(invalidCount, 'line')} could not be read as a CID and will be skipped`,
+    )
+  }
+  if (duplicateCount > 0) {
+    notes.push(
+      `${duplicateCount} ${pluralize(duplicateCount, 'duplicate')} removed`,
+    )
+  }
+
+  return notes.length > 0 ? `${notes.join('. ')}.` : null
+}
+
+export function CidListChecker() {
+  const inputId = useId()
+  const plausible = usePlausible()
+  const [value, setValue] = useState('')
+  const [verdict, setVerdict] = useState<Verdict | null>(null)
+
+  function handleCheck() {
+    const summary = parseCidList(value)
+    const next = getVerdict(summary)
+    setVerdict(next)
+
+    if (next.kind === 'empty') {
+      return
+    }
+
+    plausible(PLAUSIBLE_EVENTS.cidListChecked, {
+      props: {
+        outcome: next.kind,
+        cidCount: summary.uniqueCids.length,
+      },
+    })
+  }
+
+  return (
+    <div className="mx-auto w-full max-w-2xl text-left">
+      <Field>
+        <Label
+          htmlFor={inputId}
+          className="mb-2 inline-block text-(--color-paragraph-text) text-sm"
+        >
+          Paste the CIDs you want to move
+        </Label>
+        <Textarea
+          id={inputId}
+          value={value}
+          spellCheck={false}
+          rows={5}
+          placeholder={PLACEHOLDER}
+          onChange={(event) => setValue(event.target.value)}
+          className="focus:brand-outline block min-h-32 w-full resize-y rounded-lg border border-(--input-border-color) p-3 font-mono text-(--color-text-base) text-sm placeholder:text-(--input-placeholder-color)"
+        />
+      </Field>
+
+      <div className="mt-3">
+        <Button type="button" variant="primary" onClick={handleCheck}>
+          Check my list
+        </Button>
+      </div>
+
+      {verdict && (
+        <div
+          role="status"
+          aria-live="polite"
+          className="mt-4 rounded-lg border border-(--color-border-muted) bg-(--color-card-background) p-4 text-(--color-paragraph-text) text-sm"
+        >
+          <VerdictMessage verdict={verdict} />
+        </div>
+      )}
+
+      <p className="mt-3 text-(--color-paragraph-text) text-sm/relaxed">
+        Checking is free and needs no wallet, up to{' '}
+        {BROWSER_CHECK_ITEM_CAP.toLocaleString()} items and{' '}
+        {MAX_ITEM_SIZE_LABEL} per item. It runs entirely in your browser, so
+        your list is never sent anywhere. Past that,{' '}
+        <SmartTextLink href={`${PATHS.IPFS_TO_FILECOIN.path}#agent`}>
+          hand the migration to your agent
+        </SmartTextLink>
+        .
+      </p>
+    </div>
+  )
+}
+
+function VerdictMessage({ verdict }: { verdict: Verdict }) {
+  if (verdict.kind === 'empty') {
+    return (
+      <p>
+        <strong className="font-medium text-(--color-text-base)">
+          Nothing to check yet.
+        </strong>{' '}
+        Paste one CID per line.
+      </p>
+    )
+  }
+
+  const { summary } = verdict
+  const notes = buildNotes(summary)
+  const count = summary.uniqueCids.length
+
+  if (verdict.kind === 'unreadable') {
+    return (
+      <p>
+        <strong className="font-medium text-(--color-text-base)">
+          None of these look like CIDs.
+        </strong>{' '}
+        {summary.totalLines} {pluralize(summary.totalLines, 'line')} could not
+        be read as a CID. Check for extra text, URLs, or commas.
+      </p>
+    )
+  }
+
+  if (verdict.kind === 'over-cap') {
+    return (
+      <div className="space-y-3">
+        <p>
+          <strong className="font-medium text-(--color-text-base)">
+            {count.toLocaleString()} CIDs is more than a browser check handles.
+          </strong>{' '}
+          The limit here is {BROWSER_CHECK_ITEM_CAP.toLocaleString()} items.
+          Hand the list to your agent instead: no cap, and it resumes if it
+          stops. {notes}
+        </p>
+        <AgentPrompt source="verdict" />
+      </div>
+    )
+  }
+
+  return (
+    <p>
+      <strong className="font-medium text-(--color-text-base)">
+        {count.toLocaleString()} {pluralize(count, 'CID')} ready to check.
+      </strong>{' '}
+      Estimate what they cost to store below, then hand the list to your agent
+      to fetch, measure, and migrate them. {notes}
+    </p>
+  )
+}
diff --git a/src/app/ipfs2filecoin/components/ComparisonTable.tsx b/src/app/ipfs2filecoin/components/ComparisonTable.tsx
new file mode 100644
index 00000000..9b7a73b7
--- /dev/null
+++ b/src/app/ipfs2filecoin/components/ComparisonTable.tsx
@@ -0,0 +1,56 @@
+import { clsx } from 'clsx'
+
+import { pricingComparison } from '../data/pricing-comparison'
+
+export function ComparisonTable() {
+  return (
+    <div className="overflow-x-auto rounded-xl border border-(--color-border-muted)">
+      <table className="w-full min-w-140 text-left text-sm">
+        <thead>
+          <tr className="border-(--color-border-muted) border-b text-(--color-paragraph-text)">
+            <th scope="col" className="px-5 py-4 font-medium">
+              Where the data lives
+            </th>
+            <th scope="col" className="px-5 py-4 font-medium">
+              Storage, per TB per month
+            </th>
+            <th scope="col" className="px-5 py-4 font-medium">
+              Egress
+            </th>
+          </tr>
+        </thead>
+        <tbody className="text-(--color-paragraph-text)">
+          {pricingComparison.map(
+            ({ service, storagePerTbMonth, egress, highlighted }) => (
+              <tr
+                key={service}
+                className="border-(--color-border-muted) border-b last:border-b-0"
+              >
+                <th
+                  scope="row"
+                  className={clsx(
+                    'px-5 py-4 font-normal',
+                    highlighted && 'font-medium text-(--color-text-base)',
+                  )}
+                >
+                  {service}
+                </th>
+                <td
+                  className={clsx(
+                    'px-5 py-4 font-mono whitespace-nowrap',
+                    highlighted && 'text-(--color-text-base) text-lg',
+                  )}
+                >
+                  {storagePerTbMonth}
+                </td>
+                <td className="px-5 py-4 font-mono whitespace-nowrap">
+                  {egress}
+                </td>
+              </tr>
+            ),
+          )}
+        </tbody>
+      </table>
+    </div>
+  )
+}
diff --git a/src/app/ipfs2filecoin/components/CostEstimator.tsx b/src/app/ipfs2filecoin/components/CostEstimator.tsx
new file mode 100644
index 00000000..f8476e95
--- /dev/null
+++ b/src/app/ipfs2filecoin/components/CostEstimator.tsx
@@ -0,0 +1,225 @@
+'use client'
+
+import { Button } from '@filecoin-foundation/ui-filecoin/Button'
+import { Field, Input, Label, Select } from '@headlessui/react'
+import { usePlausible } from 'next-plausible'
+import { useId, useState } from 'react'
+
+import {
+  BUFFER_DAYS,
+  COPIES,
+  PLAUSIBLE_EVENTS,
+  USD_PER_TIB_MONTH_PER_COPY,
+} from '../constants/migration'
+import {
+  type CostEstimate,
+  estimateCost,
+  formatUsd,
+  toTebibytes,
+  type VolumeUnit,
+} from '../utils/estimate-cost'
+
+const DURATION_OPTIONS = [
+  { label: '6 months', days: 182 },
+  { label: '1 year', days: 365 },
+  { label: '2 years', days: 730 },
+  { label: '3 years', days: 1095 },
+]
+
+const fieldClassName =
+  'focus:brand-outline block w-full rounded-lg border border-(--input-border-color) p-3 text-(--color-text-base) placeholder:text-(--input-placeholder-color)'
+
+export function CostEstimator() {
+  const volumeId = useId()
+  const unitId = useId()
+  const durationId = useId()
+  const plausible = usePlausible()
+
+  const [volume, setVolume] = useState('1')
+  const [unit, setUnit] = useState<VolumeUnit>('TiB')
+  const [days, setDays] = useState(730)
+  const [estimate, setEstimate] = useState<CostEstimate | null>(null)
+  const [error, setError] = useState<string | null>(null)
+
+  function handleEstimate() {
+    const parsed = Number(volume)
+
+    if (!Number.isFinite(parsed) || parsed <= 0) {
+      setEstimate(null)
+      setError('Enter how much data you want to store, as a number above zero.')
+      return
+    }
+
+    const tebibytes = toTebibytes(parsed, unit)
+    const next = estimateCost(tebibytes, days)
+
+    setError(null)
+    setEstimate(next)
+
+    plausible(PLAUSIBLE_EVENTS.estimateViewed, {
+      props: {
+        volume: `${parsed} ${unit}`,
+        days,
+        deposit: Math.round(next.deposit),
+      },
+    })
+  }
+
+  return (
+    <div className="space-y-6">
+      <div className="grid gap-4 sm:grid-cols-3">
+        <Field>
+          <Label
+            htmlFor={volumeId}
+            className="mb-1 inline-block font-medium text-(--color-text-base) text-sm"
+          >
+            How much data
+          </Label>
+          <Input
+            id={volumeId}
+            type="number"
+            min="0"
+            step="any"
+            inputMode="decimal"
+            value={volume}
+            onChange={(event) => setVolume(event.target.value)}
+            className={fieldClassName}
+          />
+        </Field>
+
+        <Field>
+          <Label
+            htmlFor={unitId}
+            className="mb-1 inline-block font-medium text-(--color-text-base) text-sm"
+          >
+            Unit
+          </Label>
+          <Select
+            id={unitId}
+            value={unit}
+            onChange={(event) => setUnit(event.target.value as VolumeUnit)}
+            className={fieldClassName}
+          >
+            <option value="GiB">GiB</option>
+            <option value="TiB">TiB</option>
+          </Select>
+        </Field>
+
+        <Field>
+          <Label
+            htmlFor={durationId}
+            className="mb-1 inline-block font-medium text-(--color-text-base) text-sm"
+          >
+            Funded for
+          </Label>
+          <Select
+            id={durationId}
+            value={days}
+            onChange={(event) => setDays(Number(event.target.value))}
+            className={fieldClassName}
+          >
+            {DURATION_OPTIONS.map(({ label, days: value }) => (
+              <option key={value} value={value}>
+                {label}
+              </option>
+            ))}
+          </Select>
+        </Field>
+      </div>
+
+      <Button type="button" variant="primary" onClick={handleEstimate}>
+        Estimate my deposit
+      </Button>
+
+      {error && (
+        <p role="alert" className="text-(--color-brand-error) text-sm">
+          {error}
+        </p>
+      )}
+
+      {estimate && <EstimateBreakdown estimate={estimate} />}
+
+      <p className="text-(--color-paragraph-text) text-sm/relaxed">
+        Based on {formatUsd(USD_PER_TIB_MONTH_PER_COPY)} per TiB per month per
+        copy plus proving, across {COPIES} copies. Gas is separate, so you also
+        need a small amount of FIL. A deposit funds a rate rather than a term:
+        storing more data later spends the balance faster and moves your
+        funded-until date earlier. The exact deposit is shown before you approve
+        it.
+      </p>
+    </div>
+  )
+}
+
+function EstimateBreakdown({ estimate }: { estimate: CostEstimate }) {
+  const durationLabel =
+    DURATION_OPTIONS.find(({ days }) => days === estimate.days)?.label ??
+    `${estimate.days} days`
+
+  const rows = [
+    {
+      label: `Storage and proving for ${durationLabel}`,
+      amount: formatUsd(estimate.storage),
+      note: 'No, this is the cost',
+    },
+    {
+      label: `Buffer held while data is live (${BUFFER_DAYS} days of charges)`,
+      amount: formatUsd(estimate.buffer),
+      note: 'Yes, refundable',
+    },
+    {
+      label: 'Lifecycle reserve, per data set',
+      amount: formatUsd(estimate.lifecycleReserve),
+      note: 'Yes, unused portion',
+    },
+  ]
+
+  return (
+    <div
+      role="status"
+      aria-live="polite"
+      className="overflow-x-auto rounded-xl border border-(--color-border-muted)"
+    >
+      <table className="w-full text-left text-sm">
+        <thead>
+          <tr className="border-(--color-border-muted) border-b text-(--color-paragraph-text)">
+            <th scope="col" className="px-5 py-4 font-medium">
+              Line
+            </th>
+            <th scope="col" className="px-5 py-4 font-medium">
+              Amount
+            </th>
+            <th scope="col" className="px-5 py-4 font-medium">
+              Yours again afterwards
+            </th>
+          </tr>
+        </thead>
+        <tbody className="text-(--color-paragraph-text)">
+          {rows.map(({ label, amount, note }) => (
+            <tr key={label} className="border-(--color-border-muted) border-b">
+              <td className="px-5 py-4">{label}</td>
+              <td className="px-5 py-4 font-mono">{amount}</td>
+              <td className="px-5 py-4">{note}</td>
+            </tr>
+          ))}
+          <tr className="text-(--color-text-base)">
+            <td className="px-5 py-4 font-medium">Deposit</td>
+            <td className="px-5 py-4 font-medium font-mono text-lg">
+              {formatUsd(estimate.deposit)}
+            </td>
+            <td className="px-5 py-4">
+              {formatUsd(estimate.refundable)} comes back
+            </td>
+          </tr>
+        </tbody>
+      </table>
+      <p className="px-5 py-4 text-(--color-paragraph-text) text-xs/relaxed">
+        The buffer is set aside, not spent, and you get back whatever is unused.
+        Treat your funded-until date as the date to act by rather than the date
+        service stops: if the balance runs out, providers can end the service
+        and keep the buffer. Depositing for longer is not a discount, it just
+        means fewer trips back.
+      </p>
+    </div>
+  )
+}
diff --git a/src/app/ipfs2filecoin/constants/migration.ts b/src/app/ipfs2filecoin/constants/migration.ts
new file mode 100644
index 00000000..f226ed63
--- /dev/null
+++ b/src/app/ipfs2filecoin/constants/migration.ts
@@ -0,0 +1,40 @@
+import { BASE_URL } from '@/constants/site-metadata'
+
+/**
+ * Caps for the browser-based check. Larger inputs are steered to the CLI or to
+ * the contact form, because they need capacity agreed with providers up front.
+ */
+export const BROWSER_CHECK_ITEM_CAP = 500
+export const MAX_ITEM_SIZE_LABEL = '1 GiB'
+export const SELF_SERVE_VOLUME_CAP_LABEL = '500 GiB'
+
+/** Warm storage list price, per copy. Two copies are stored by default. */
+export const USD_PER_TIB_MONTH_PER_COPY = 2.5
+export const COPIES = 2
+
+/** Proving buffer charged alongside storage, per TiB per month per copy. */
+export const USD_PROVING_PER_TIB_MONTH_PER_COPY = 0.024
+
+/** Held per data set, and one data set is created per copy. Unused portion returns. */
+export const USD_LIFECYCLE_RESERVE_PER_DATA_SET = 0.1
+
+/** A billing month is a 30-day period, matching how storage is charged. */
+export const DAYS_PER_MONTH = 30
+
+/**
+ * Days of charges held in reserve while data is stored. Set aside rather than
+ * spent, and returned when the data set is closed.
+ */
+export const BUFFER_DAYS = 30
+
+export const LLMS_TXT_PATH = '/ipfs2filecoin/llms.txt'
+export const LLMS_TXT_URL = `${BASE_URL}${LLMS_TXT_PATH}`
+
+/** The one line a user hands to a coding agent. Copying it is signal, so it is tracked. */
+export const AGENT_PROMPT = `Migrate my IPFS data to Filecoin: read ${LLMS_TXT_URL} and follow it. My CIDs are in cids.txt.`
+
+export const PLAUSIBLE_EVENTS = {
+  cidListChecked: 'IPFS2Filecoin CID List Checked',
+  estimateViewed: 'IPFS2Filecoin Estimate Viewed',
+  promptCopied: 'IPFS2Filecoin Agent Prompt Copied',
+} as const
diff --git a/src/app/ipfs2filecoin/constants/seo.ts b/src/app/ipfs2filecoin/constants/seo.ts
new file mode 100644
index 00000000..78c4d3e9
--- /dev/null
+++ b/src/app/ipfs2filecoin/constants/seo.ts
@@ -0,0 +1,5 @@
+export const IPFS2FILECOIN_SEO = {
+  title: 'IPFS to Filecoin | Move Your Pinned Data Without Changing Your CIDs',
+  description:
+    'Move pinned IPFS data to Filecoin warm storage. Same CIDs, $2.50 per TiB per month per copy, and an onchain receipt you can verify yourself.',
+} as const
diff --git a/src/app/ipfs2filecoin/data/faqs.tsx b/src/app/ipfs2filecoin/data/faqs.tsx
new file mode 100644
index 00000000..6ff1406b
--- /dev/null
+++ b/src/app/ipfs2filecoin/data/faqs.tsx
@@ -0,0 +1,109 @@
+import { MarkdownLink } from '@filecoin-foundation/ui-filecoin/Markdown/MarkdownLink'
+
+import type { Question } from '@/components/Faq'
+
+import { PATHS } from '@/constants/paths'
+
+import { LLMS_TXT_PATH } from '../constants/migration'
+
+export const faqs: Array<Question> = [
+  {
+    question: 'Do my existing gateway links keep working?',
+    answer: (
+      <>
+        <p>
+          Yes. Data is stored as the CAR of the original DAG, so the CID is
+          unchanged and the content stays announced to the IPFS network.
+          Anything already published, whether an IPNS name, a token URI, or a
+          link in a document, resolves the same way after the migration as
+          before it.
+        </p>
+        <p>
+          That holds for any public gateway, a gateway you run yourself, or a
+          local node, because resolution goes through the network rather than
+          through us.
+        </p>
+      </>
+    ),
+  },
+  {
+    question: 'Do I have to delete the data from my current provider?',
+    answer: (
+      <p>
+        No, and we would suggest you do not until you have verified the
+        migration yourself. Run the retrieval check on the receipt, keep the
+        manifest, and cancel your old plan when you are satisfied.
+      </p>
+    ),
+  },
+  {
+    question: 'What do I need before I can migrate?',
+    answer: (
+      <>
+        <p>
+          USDFC to pay for storage and a small amount of FIL for gas, in a
+          wallet you control. Checking a list needs none of that, and you can
+          set the rest up in one pass: connect a wallet, deposit, approve
+          spending.
+        </p>
+        <p>
+          Those are ordinary transactions you confirm one at a time. After that
+          your account is ready and the migration itself can run without you
+          watching it.
+        </p>
+      </>
+    ),
+  },
+  {
+    question: 'What happens if the run stops halfway?',
+    answer: (
+      <p>
+        State is kept, so closing the tab does not lose the work and the run
+        picks up where it left off. Anything not yet stored stays in the
+        manifest so you can finish it here or carry it to the command line.
+      </p>
+    ),
+  },
+  {
+    question: 'What can the agent actually spend?',
+    answer: (
+      <>
+        <p>
+          Only what you have deposited. The migration runs from a key you
+          provide, and a key that can sign on your account can also draw against
+          its balance, so treat the deposit as the ceiling rather than as a
+          starting balance.
+        </p>
+        <p>
+          The safe pattern is a wallet you keep for this purpose, holding the
+          USDFC and FIL this migration needs and nothing else. Do not give a key
+          to your main wallet to anything that runs unattended, here or
+          anywhere.
+        </p>
+      </>
+    ),
+  },
+  {
+    question: 'How much of this can an agent actually do?',
+    answer: (
+      <>
+        <p>
+          All of the work, and none of the spending. The brief at{' '}
+          <MarkdownLink href={LLMS_TXT_PATH}>{LLMS_TXT_PATH}</MarkdownLink>{' '}
+          gives an agent the command sequence, the caps, and the prerequisites,
+          and the tool runs headless with JSON status output so it can read its
+          own progress and recover from failures.
+        </p>
+        <p>
+          What it hands back to you are the two steps that move money: funding
+          the run and signing it. If a migration is too large or your source is
+          not publicly reachable,{' '}
+          <MarkdownLink href={PATHS.CONTACT.path}>
+            talk to our team
+          </MarkdownLink>{' '}
+          instead.
+        </p>
+      </>
+    ),
+  },
+]
diff --git a/src/app/ipfs2filecoin/data/limits.ts b/src/app/ipfs2filecoin/data/limits.ts
new file mode 100644
index 00000000..5f4c863d
--- /dev/null
+++ b/src/app/ipfs2filecoin/data/limits.ts
@@ -0,0 +1,31 @@
+import {
+  MAX_ITEM_SIZE_LABEL,
+  SELF_SERVE_VOLUME_CAP_LABEL,
+} from '../constants/migration'
+
+export const limits = [
+  {
+    title: 'Your source has to be publicly readable',
+    description:
+      'Each CID is fetched through a public gateway that serves verifiable content. Private pinning accounts, authenticated endpoints, and custom storage are not reachable this way, so those go through the contact form.',
+  },
+  {
+    title: `${MAX_ITEM_SIZE_LABEL} per item`,
+    description: `Individual assets larger than ${MAX_ITEM_SIZE_LABEL} cannot be moved yet, because splitting them would change their CID and that is the one thing we will not do. Large sets of small items are fine.`,
+  },
+  {
+    title: `Past ${SELF_SERVE_VOLUME_CAP_LABEL}, talk to us first`,
+    description:
+      'A migration that size needs capacity and timing agreed with storage providers before it starts. We would rather scope it with you up front than have you discover the ceiling partway through a run.',
+  },
+  {
+    title: 'Filecoin uses its own identifier underneath',
+    description:
+      'Filecoin tracks storage under its own piece identifier, and your run produces a manifest mapping every IPFS CID to it. You never need that identifier to read your data, because retrieval is always by your original CID.',
+  },
+  {
+    title: 'Unreachable CIDs are reported, not hidden',
+    description:
+      'If a CID cannot be fetched from any gateway you provided, the run tells you which ones and how many, and the manifest records them. A count you can act on beats a silent partial success.',
+  },
+] as const
diff --git a/src/app/ipfs2filecoin/data/pricing-comparison.ts b/src/app/ipfs2filecoin/data/pricing-comparison.ts
new file mode 100644
index 00000000..94123826
--- /dev/null
+++ b/src/app/ipfs2filecoin/data/pricing-comparison.ts
@@ -0,0 +1,37 @@
+import { formatUsd, USD_PER_TB_MONTH } from '../utils/estimate-cost'
+
+export type PricingRow = {
+  service: string
+  storagePerTbMonth: string
+  egress: string
+  highlighted?: boolean
+}
+
+/**
+ * Third-party rates are published list overage rates, captured 27 July 2026.
+ * Overage is the rate that matters once you are past a plan's included
+ * allowance, which anyone migrating a real archive already is.
+ */
+export const pricingComparison: Array<PricingRow> = [
+  {
+    service: 'Filecoin Warm Storage',
+    storagePerTbMonth: formatUsd(USD_PER_TB_MONTH),
+    egress: 'IPFS gateway read path',
+    highlighted: true,
+  },
+  {
+    service: 'Filebase, Pro overage',
+    storagePerTbMonth: '$15.00',
+    egress: '$0.015 / GB',
+  },
+  {
+    service: 'Pinata, Fiesta overage',
+    storagePerTbMonth: '$35.00',
+    egress: '$0.080 / GB',
+  },
+  {
+    service: 'Pinata, Picnic overage',
+    storagePerTbMonth: '$70.00',
+    egress: '$0.100 / GB',
+  },
+]
diff --git a/src/app/ipfs2filecoin/data/reasons.ts b/src/app/ipfs2filecoin/data/reasons.ts
new file mode 100644
index 00000000..8eefd413
--- /dev/null
+++ b/src/app/ipfs2filecoin/data/reasons.ts
@@ -0,0 +1,22 @@
+export const reasons = [
+  {
+    title: 'Your CIDs do not change',
+    description:
+      'Nothing is re-chunked. Every CID stays byte-identical and keeps resolving from any public IPFS gateway, so existing links, IPNS names, and NFT metadata keep working exactly as they do today.',
+  },
+  {
+    title: 'A fraction of pinning-service pricing',
+    description:
+      '$2.50 per TiB per month per copy, two copies by default. You pay storage providers directly, streamed per epoch, with no plan tiers and no minimum commitment.',
+  },
+  {
+    title: 'Proof, not a dashboard',
+    description:
+      'Storage providers prove possession onchain on a schedule. You get a receipt with transaction links, and you can verify any piece yourself at any time without asking anyone.',
+  },
+  {
+    title: 'Your wallet owns it, not an account',
+    description:
+      'No signup and no vendor account to lose. The data set belongs to your wallet address and payment streams from your wallet straight to the providers. Reading your data never depends on your key, so the content stays reachable either way.',
+  },
+] as const
diff --git a/src/app/ipfs2filecoin/data/steps.ts b/src/app/ipfs2filecoin/data/steps.ts
new file mode 100644
index 00000000..eb5b81b9
--- /dev/null
+++ b/src/app/ipfs2filecoin/data/steps.ts
@@ -0,0 +1,26 @@
+export const steps = [
+  {
+    number: '01',
+    title: 'Hand over the list',
+    description:
+      'Give your agent a cids.txt, or paste a list here first to see what you are dealing with. Checking costs nothing.',
+  },
+  {
+    number: '02',
+    title: 'Read and measure',
+    description:
+      'Each CID is fetched from a public gateway and its Filecoin piece identifier computed. Nothing is uploaded anywhere and nothing is charged.',
+  },
+  {
+    number: '03',
+    title: 'Fund it, once',
+    description:
+      'Connect a wallet, deposit USDFC, approve spending. Use a wallet you keep for this and deposit what the migration needs, because that amount is also the most anything can spend.',
+  },
+  {
+    number: '04',
+    title: 'Migrate',
+    description:
+      'Storage providers pull the data and commit it onchain. You get a receipt, explorer links, and a manifest of everything that landed.',
+  },
+] as const
diff --git a/src/app/ipfs2filecoin/llms.txt/route.ts b/src/app/ipfs2filecoin/llms.txt/route.ts
new file mode 100644
index 00000000..5f57935c
--- /dev/null
+++ b/src/app/ipfs2filecoin/llms.txt/route.ts
@@ -0,0 +1,121 @@
+import { PATHS } from '@/constants/paths'
+import { BASE_URL, FOC_URLS } from '@/constants/site-metadata'
+
+import {
+  BROWSER_CHECK_ITEM_CAP,
+  COPIES,
+  MAX_ITEM_SIZE_LABEL,
+  SELF_SERVE_VOLUME_CAP_LABEL,
+  USD_PER_TIB_MONTH_PER_COPY,
+} from '../constants/migration'
+
+/**
+ * Placeholder migration brief. The full command sequence lives with the tool
+ * that runs it, in FilOzone/ipfs2foc, and replaces the body of this route once
+ * it is published. Serving it from here now means the prompt on the landing
+ * page resolves and we can see who is fetching it.
+ */
+const LLMS_TXT = `# IPFS to Filecoin — migration brief
+
+> DRAFT. This brief is published ahead of the full command sequence. It states
+> what the migration does, what it costs, and where it stops. Do not infer
+> commands that are not listed here; check the tool's README instead.
+
+## What this is
+
+A migration of pinned IPFS data into Filecoin warm storage. Content is stored as
+the CAR of the original DAG, so every CID stays byte-identical and keeps
+resolving from any public IPFS gateway. Storage providers prove possession
+onchain on a schedule.
+
+## Prerequisites
+
+- Node.js 26 or newer. This is a hard requirement.
+- A list of CIDs, one per line, in a text file (conventionally cids.txt).
+- Each CID must be retrievable from a public IPFS gateway. Private pinning
+  accounts and authenticated endpoints are not reachable this way.
+- A wallet holding USDFC for storage and a small amount of FIL for gas.
+  Use a wallet kept for this purpose. The deposited balance is the ceiling on
+  what any unattended run can spend.
+- A public HTTPS origin the storage provider can pull pieces from. See stage 0.
+
+## Stage 0 — check the ingress before anything else
+
+At submission a storage provider pulls pieces from a public HTTPS origin that
+you supply. Private and loopback addresses are rejected. Confirm you have one
+of these BEFORE computing piece commitments, because discovering it afterwards
+wastes the entire run:
+
+- the \`cloudflared\` binary installed, for \`--ingress cloudflared\`; or
+- a VPS or Tailscale fronting the port yourself, for \`--ingress funnel\`; or
+- a source relay URL, for \`--source-relay\`.
+
+If none is available, stop and report that to the user rather than choosing one
+on their behalf. Installing a tunnel binary and exposing a local port to the
+internet is the user's decision to make.
+
+## Caps
+
+- ${MAX_ITEM_SIZE_LABEL} per item. Larger assets cannot be moved yet, because
+  splitting them would change their CID.
+- ${SELF_SERVE_VOLUME_CAP_LABEL} total for a self-serve run. Past that, capacity
+  and timing must be agreed with storage providers first: ${BASE_URL}${PATHS.CONTACT.path}
+- ${BROWSER_CHECK_ITEM_CAP} items for the in-browser check on the landing page.
+  The command-line tool has no item cap and resumes if a run stops.
+
+## Cost
+
+Storage is ${USD_PER_TIB_MONTH_PER_COPY} USDFC per TiB per month per copy, at
+${COPIES} copies by default, streamed to providers per epoch. A small proving
+charge is billed alongside it. Funding is a deposit covering a chosen period,
+plus a refundable 30-day buffer and a per-data-set lifecycle reserve held while
+the data is stored. Gas is paid separately in FIL.
+
+A deposit funds a rate, not a term. Funded duration is the available balance
+divided by the burn rate across every data set on the account, so storing more
+data later moves the funded-until date earlier.
+
+## Stages
+
+1. analyze — read the CID list, fetch each CID from a public gateway, compute
+   its Filecoin piece identifier and size. Free, no wallet, nothing charged.
+2. plan — produce the deposit required for the chosen retention period, and the
+   list of CIDs that could not be retrieved.
+3. fund — deposit USDFC and approve spending. This step moves money and is
+   handed back to the human.
+4. migrate — providers pull the data and commit it onchain.
+5. verify — retrieve by original CID and check the onchain proof, then keep the
+   manifest mapping every IPFS CID to its Filecoin piece identifier.
+
+## Failure modes
+
+- Unreachable CIDs are reported with counts and recorded in the manifest. They
+  are never silently dropped.
+- A stopped run resumes from its recorded state. Nothing already stored is
+  re-paid for.
+- If the funded balance runs out, providers can end the service and keep the
+  buffer. Top up before the funded-until date.
+
+## Do not
+
+- Re-chunk, repackage, or otherwise alter content. Changing a CID defeats the
+  point of the migration.
+- Delete data from the existing pinning provider until the migration has been
+  verified.
+- Use a key to a wallet that holds anything beyond what this migration needs.
+
+## Links
+
+- Landing page: ${BASE_URL}${PATHS.IPFS_TO_FILECOIN.path}
+- Documentation: ${FOC_URLS.documentation.home}
+- Talk to our team: ${BASE_URL}${PATHS.CONTACT.path}
+`
+
+export function GET() {
+  return new Response(LLMS_TXT, {
+    headers: {
+      'Content-Type': 'text/markdown; charset=utf-8',
+      'Cache-Control': 'public, max-age=0, s-maxage=3600',
+    },
+  })
+}
diff --git a/src/app/ipfs2filecoin/page.tsx b/src/app/ipfs2filecoin/page.tsx
new file mode 100644
index 00000000..3a1ed035
--- /dev/null
+++ b/src/app/ipfs2filecoin/page.tsx
@@ -0,0 +1,267 @@
+import { Button } from '@filecoin-foundation/ui-filecoin/Button'
+import { Card } from '@filecoin-foundation/ui-filecoin/Card'
+import { CardGrid } from '@filecoin-foundation/ui-filecoin/CardGrid'
+import { Container } from '@filecoin-foundation/ui-filecoin/Container'
+import { Heading } from '@filecoin-foundation/ui-filecoin/Heading'
+import { PageHeader } from '@filecoin-foundation/ui-filecoin/PageHeader'
+import { PageSection } from '@filecoin-foundation/ui-filecoin/PageSection'
+import { SectionContent } from '@filecoin-foundation/ui-filecoin/SectionContent'
+import { ExternalTextLink } from '@filecoin-foundation/ui-filecoin/TextLink/ExternalTextLink'
+import { SmartTextLink } from '@filecoin-foundation/ui-filecoin/TextLink/SmartTextLink'
+import type { Metadata } from 'next'
+
+import { Faq } from '@/components/Faq'
+import { Navigation } from '@/components/Navigation/Navigation'
+import { StructuredDataScript } from '@/components/StructuredDataScript'
+
+import { PATHS } from '@/constants/paths'
+import { FOC_URLS } from '@/constants/site-metadata'
+import { createMetadata } from '@/utils/create-metadata'
+
+import { AgentPrompt } from './components/AgentPrompt'
+import { CidListChecker } from './components/CidListChecker'
+import { ComparisonTable } from './components/ComparisonTable'
+import { CostEstimator } from './components/CostEstimator'
+import {
+  LLMS_TXT_PATH,
+  SELF_SERVE_VOLUME_CAP_LABEL,
+} from './constants/migration'
+import { IPFS2FILECOIN_SEO } from './constants/seo'
+import { faqs } from './data/faqs'
+import { limits } from './data/limits'
+import { reasons } from './data/reasons'
+import { steps } from './data/steps'
+import { generateStructuredData } from './utils/generate-structured-data'
+
+const ghostOnDark =
+  '!border-zinc-50/40 !bg-transparent hover:!border-zinc-50 hover:!bg-zinc-50/5'
+
+export default function IpfsToFilecoin() {
+  return (
+    <>
+      <StructuredDataScript
+        structuredData={generateStructuredData(IPFS2FILECOIN_SEO)}
+      />
+
+      <Navigation backgroundVariant="dark" />
+
+      <PageSection backgroundVariant="dark">
+        <PageHeader
+          centered
+          variant="highContrast"
+          title="Move your pinned IPFS data to Filecoin"
+          description="Same CIDs, a fraction of what pinning services charge, and an onchain receipt you can verify yourself."
+        />
+        <Container>
+          <div className="mt-10">
+            <CidListChecker />
+          </div>
+        </Container>
+      </PageSection>
+
+      <PageSection backgroundVariant="gray">
+        <SectionContent
+          headingTag="h2"
+          title="Why move to Filecoin warm storage"
+          description="Your data keeps working the way it does today. What changes is the price, the proof, and who owns it."
+        >
+          <CardGrid as="ul" variant="lgTwoWide">
+            {reasons.map(({ title, description }) => (
+              <Card
+                key={title}
+                as="li"
+                title={title}
+                description={description}
+              />
+            ))}
+          </CardGrid>
+        </SectionContent>
+      </PageSection>
+
+      <PageSection backgroundVariant="light">
+        <SectionContent
+          headingTag="h2"
+          title="What it costs"
+          description="Pinning services bundle an allowance into a monthly plan, then charge per gigabyte past it. Once you are past the allowance, which anyone migrating a real archive already is, the overage rate is your real cost."
+        >
+          <div className="space-y-6">
+            <ComparisonTable />
+
+            <p className="text-(--color-paragraph-text) text-sm/relaxed">
+              Filecoin Warm Storage is $2.50 per TiB per month per copy at two
+              copies. Other rates are published list overage rates as of 27 July
+              2026, from{' '}
+              <ExternalTextLink href="https://filebase.com/pricing/">
+                Filebase
+              </ExternalTextLink>{' '}
+              and{' '}
+              <ExternalTextLink href="https://pinata.cloud/pricing">
+                Pinata
+              </ExternalTextLink>
+              . Filecoin includes two replicas; the other services do not
+              publish a replication factor, so the comparison is conservative.
+            </p>
+          </div>
+        </SectionContent>
+      </PageSection>
+
+      <PageSection backgroundVariant="light" paddingVariant="topNone">
+        <Container>
+          <div className="max-w-4xl space-y-6">
+            <Heading tag="h2" variant="card-heading">
+              Estimate your deposit
+            </Heading>
+            <p className="text-(--color-paragraph-text)">
+              Storage is charged continuously while your data sits there, so you
+              deposit for a period rather than paying a monthly bill. Enter
+              roughly how much you are holding and how long you want to be
+              covered. This runs in your browser and nothing is sent anywhere.
+            </p>
+            <CostEstimator />
+          </div>
+        </Container>
+      </PageSection>
+
+      <PageSection backgroundVariant="gray">
+        <SectionContent
+          headingTag="h2"
+          title="How it works"
+          description="Four steps, and the first two are free."
+        >
+          <CardGrid as="ul" variant="smTwoLgThreeWider">
+            {steps.map(({ number, title, description }) => (
+              <Card
+                key={title}
+                as="li"
+                title={`${number}. ${title}`}
+                description={description}
+              />
+            ))}
+          </CardGrid>
+        </SectionContent>
+      </PageSection>
+
+      <PageSection backgroundVariant="dark">
+        <SectionContent
+          headingTag="h2"
+          title="Nobody should migrate an archive by clicking"
+          description="Real migrations run unattended, so that is the path this is built around. Check a list for free, get your account funded in one pass, then hand the work to your agent or to us."
+        >
+          <div className="grid gap-8 lg:grid-cols-2">
+            <div id="agent" className="scroll-mt-24 space-y-4">
+              <Heading tag="h3" variant="card-heading">
+                Ask your agent to do it
+              </Heading>
+              <p className="text-(--color-paragraph-text)">
+                Give this line to Claude Code, Cursor, or any coding agent. It
+                reads the migration brief at{' '}
+                <SmartTextLink href={LLMS_TXT_PATH}>
+                  {LLMS_TXT_PATH}
+                </SmartTextLink>
+                , works through your list, and reports back what landed.
+              </p>
+              <p className="text-(--color-paragraph-text)">
+                It signs from a key you provide, and a key that can sign on your
+                account can draw against its balance, so your deposit is the
+                ceiling. Use a wallet you keep for this purpose, holding what
+                this migration needs and nothing else. Never give a main
+                wallet&apos;s key to something running unattended.
+              </p>
+              <AgentPrompt source="agent-door" />
+            </div>
+
+            <div className="space-y-4">
+              <Heading tag="h3" variant="card-heading">
+                Talk to us
+              </Heading>
+              <p className="text-(--color-paragraph-text)">
+                For datasets over {SELF_SERVE_VOLUME_CAP_LABEL}, or sources that
+                are not reachable from a public gateway. Tell us what you are
+                holding and we will scope it with you.
+              </p>
+              <Button
+                href={PATHS.CONTACT.path}
+                variant="ghost"
+                className={ghostOnDark}
+              >
+                Tell us about your data
+              </Button>
+            </div>
+          </div>
+        </SectionContent>
+      </PageSection>
+
+      <PageSection backgroundVariant="light">
+        <SectionContent
+          headingTag="h2"
+          title="What this does not do"
+          description="The things worth knowing up front, so nothing surprises you halfway through a run."
+        >
+          <dl className="divide-y divide-(--color-border-muted) border-(--color-border-muted) border-t">
+            {limits.map(({ title, description }) => (
+              <div
+                key={title}
+                className="grid gap-2 py-6 md:grid-cols-3 md:gap-8"
+              >
+                <dt className="font-medium text-(--color-text-base)">
+                  {title}
+                </dt>
+                <dd className="text-(--color-paragraph-text) md:col-span-2">
+                  {description}
+                </dd>
+              </div>
+            ))}
+          </dl>
+        </SectionContent>
+      </PageSection>
+
+      <PageSection backgroundVariant="gray">
+        <Faq questions={faqs} />
+      </PageSection>
+
+      <PageSection backgroundVariant="dark">
+        <PageHeader
+          centered
+          variant="highContrast"
+          title="Find out what your archive costs before you move it"
+          description="Checking is free and needs nothing but a list. You get a real number and the one line that hands the job to your agent."
+          cta={[
+            <Button
+              key="read-the-brief"
+              href={FOC_URLS.documentation.gettingStarted}
+              variant="primary"
+            >
+              Read the docs
+            </Button>,
+            <Button
+              key="talk-to-us"
+              href={PATHS.CONTACT.path}
+              variant="ghost"
+              className={ghostOnDark}
+            >
+              Talk to us instead
+            </Button>,
+          ]}
+        />
+      </PageSection>
+    </>
+  )
+}
+
+const baseMetadata = createMetadata({
+  title: IPFS2FILECOIN_SEO.title,
+  description: IPFS2FILECOIN_SEO.description,
+  path: PATHS.IPFS_TO_FILECOIN.path,
+})
+
+export const metadata: Metadata = {
+  ...baseMetadata,
+  alternates: {
+    ...baseMetadata.alternates,
+    /**
+     * So an agent pointed at the human URL discovers the migration brief
+     * without being told the llms.txt convention.
+     */
+    types: { 'text/markdown': LLMS_TXT_PATH },
+  },
+}
diff --git a/src/app/ipfs2filecoin/utils/estimate-cost.ts b/src/app/ipfs2filecoin/utils/estimate-cost.ts
new file mode 100644
index 00000000..99a79979
--- /dev/null
+++ b/src/app/ipfs2filecoin/utils/estimate-cost.ts
@@ -0,0 +1,78 @@
+import {
+  BUFFER_DAYS,
+  COPIES,
+  DAYS_PER_MONTH,
+  USD_LIFECYCLE_RESERVE_PER_DATA_SET,
+  USD_PER_TIB_MONTH_PER_COPY,
+  USD_PROVING_PER_TIB_MONTH_PER_COPY,
+} from '../constants/migration'
+
+const BYTES_PER_TIB = 1024 ** 4
+const BYTES_PER_TB = 1000 ** 4
+
+/** Storage alone. This is the rate the comparison table quotes. */
+export const USD_STORAGE_PER_TIB_MONTH = USD_PER_TIB_MONTH_PER_COPY * COPIES
+
+/**
+ * The comparison table quotes per-TB rates, because that is how pinning
+ * services publish theirs. Warm storage is priced per TiB.
+ */
+export const USD_PER_TB_MONTH =
+  USD_STORAGE_PER_TIB_MONTH * (BYTES_PER_TB / BYTES_PER_TIB)
+
+/**
+ * What actually gets charged per epoch: storage plus the proving buffer, on
+ * every copy. Used for the deposit, not for the headline comparison.
+ */
+export const USD_BURN_PER_TIB_MONTH =
+  (USD_PER_TIB_MONTH_PER_COPY + USD_PROVING_PER_TIB_MONTH_PER_COPY) * COPIES
+
+/** One data set is created per copy, each holding its own lifecycle reserve. */
+export const USD_LIFECYCLE_RESERVE = USD_LIFECYCLE_RESERVE_PER_DATA_SET * COPIES
+
+export type VolumeUnit = 'GiB' | 'TiB'
+
+export type CostEstimate = {
+  tebibytes: number
+  days: number
+  /** Charges consumed over the funded period. This is the actual cost. */
+  storage: number
+  /** Held while the data is stored, returned when the data set is closed. */
+  buffer: number
+  /** Held per data set for lifecycle operations; the unused portion returns. */
+  lifecycleReserve: number
+  /** What you deposit up front. */
+  deposit: number
+  /** The portion of the deposit you get back. */
+  refundable: number
+}
+
+export function toTebibytes(volume: number, unit: VolumeUnit) {
+  return unit === 'TiB' ? volume : volume / 1024
+}
+
+export function estimateCost(tebibytes: number, days: number): CostEstimate {
+  const perMonth = tebibytes * USD_BURN_PER_TIB_MONTH
+  const storage = perMonth * (days / DAYS_PER_MONTH)
+  const buffer = perMonth * (BUFFER_DAYS / DAYS_PER_MONTH)
+  const lifecycleReserve = USD_LIFECYCLE_RESERVE
+
+  return {
+    tebibytes,
+    days,
+    storage,
+    buffer,
+    lifecycleReserve,
+    deposit: storage + buffer + lifecycleReserve,
+    refundable: buffer + lifecycleReserve,
+  }
+}
+
+export function formatUsd(amount: number) {
+  return amount.toLocaleString('en-US', {
+    style: 'currency',
+    currency: 'USD',
+    minimumFractionDigits: 2,
+    maximumFractionDigits: 2,
+  })
+}
diff --git a/src/app/ipfs2filecoin/utils/generate-structured-data.ts b/src/app/ipfs2filecoin/utils/generate-structured-data.ts
new file mode 100644
index 00000000..f2ee7fa1
--- /dev/null
+++ b/src/app/ipfs2filecoin/utils/generate-structured-data.ts
@@ -0,0 +1,23 @@
+import type { WebPageGraph } from '@/components/StructuredDataScript'
+
+import { PATHS } from '@/constants/paths'
+import type { StructuredDataParams } from '@/types/structured-data-params'
+import { generatePageStructuredData } from '@/utils/generate-page-structured-data'
+
+export function generateStructuredData(
+  seo: StructuredDataParams,
+): WebPageGraph {
+  return generatePageStructuredData({
+    title: seo.title,
+    description: seo.description,
+    path: PATHS.IPFS_TO_FILECOIN.path,
+    pageType: 'WebPage',
+    service: {
+      name: 'IPFS to Filecoin migration',
+      description:
+        'Move pinned IPFS data to Filecoin warm storage without changing your CIDs, with onchain proof of possession.',
+      serviceType: 'Cloud Storage',
+      areaServed: 'Worldwide',
+    },
+  })
+}
diff --git a/src/app/ipfs2filecoin/utils/parse-cid-list.ts b/src/app/ipfs2filecoin/utils/parse-cid-list.ts
new file mode 100644
index 00000000..e7cb8613
--- /dev/null
+++ b/src/app/ipfs2filecoin/utils/parse-cid-list.ts
@@ -0,0 +1,40 @@
+/**
+ * CIDv0 (base58btc, `Qm…`) and CIDv1 (base32, `b…`). Deliberately narrow: this
+ * check runs in the browser with no network access, so it only tells you
+ * whether a line could be a CID, not whether the content is retrievable.
+ */
+const CID_PATTERN = /^(Qm[1-9A-HJ-NP-Za-km-z]{44}|b[a-z2-7]{58,})$/
+
+const GATEWAY_PREFIX_PATTERN = /^(?:ipfs:\/\/|https?:\/\/[^/]+\/ipfs\/)/
+
+export type CidListSummary = {
+  totalLines: number
+  uniqueCids: Array<string>
+  duplicateCount: number
+  invalidCount: number
+}
+
+function normalizeLine(line: string) {
+  return line
+    .trim()
+    .replace(/[,;]$/, '')
+    .replace(GATEWAY_PREFIX_PATTERN, '')
+    .split(/[?#/]/)[0]
+}
+
+export function parseCidList(input: string): CidListSummary {
+  const lines = input
+    .split('\n')
+    .map(normalizeLine)
+    .filter((line) => line && !line.startsWith('#'))
+
+  const valid = lines.filter((line) => CID_PATTERN.test(line))
+  const uniqueCids = [...new Set(valid)]
+
+  return {
+    totalLines: lines.length,
+    uniqueCids,
+    duplicateCount: valid.length - uniqueCids.length,
+    invalidCount: lines.length - valid.length,
+  }
+}
diff --git a/src/constants/paths.ts b/src/constants/paths.ts
index 4cc13e15..2758c240 100644
--- a/src/constants/paths.ts
+++ b/src/constants/paths.ts
@@ -18,6 +18,10 @@ export const PATHS = {
     path: '/',
     label: 'Homepage',
   },
+  IPFS_TO_FILECOIN: {
+    path: '/ipfs2filecoin',
+    label: 'IPFS to Filecoin',
+  },
   PRIVACY_POLICY: {
     path: '/privacy-policy',
     label: 'Privacy Policy',

From f8d4d449d8e602808c6bfe9118839edd70c581b5 Mon Sep 17 00:00:00 2001
From: Russell Dempsey <1173416+SgtPooki@users.noreply.github.com>
Date: Wed, 29 Jul 2026 15:44:21 -0400
Subject: [PATCH 02/26] feat(ipfs2filecoin): replace the draft brief with an
 executable runbook

A real agent run against the draft brief failed at the first hop: the brief
never named the tool, so the agent correctly refused to improvise a pipeline
and stopped. It also read the 500 GiB figure as a self-serve cap and routed a
56k-CID job to the contact form, which killed the conversion outright.

Both are fixed, and the format question behind them is settled.

llms.txt was the wrong format. Per llmstxt.org it is a documentation index --
H1, blockquote, then H2 lists of links -- so a procedure does not belong in
it. The procedure now lives at /ipfs2filecoin/migrate.md, named for what it
is, and llms.txt is used correctly in two places: a spec-conformant site
index at /llms.txt, and a campaign index at /ipfs2filecoin/llms.txt whose
first link is the runbook. Discovery never depended on the filename anyway --
the prompt carries the URL, and the page carries rel="alternate".

The runbook names ipfs2foc, pins the version its flags were verified against,
and carries the real command sequence read out of that repo. Notable content:

- One invocation form, stated once. A bare `ipfs2foc` after only an `npx`
  check was the most likely first failure.
- Prerequisites split into "needed now" and "needed before stage 4", so a
  missing key no longer blocks the free stages.
- Stage 0 settles ingress before the commitment pass, and records that the
  relay only serves the single-asset path.
- Stage 2 reports from analyze --json using fields that actually exist, with
  explicit cost and ETA formulas so nothing is invented.
- Stage 4 is executed by the user in their own terminal. The agent is told
  never to accept a private key -- a key pasted into a chat is a key in a
  transcript.
- Stage 5 spawns the pull source as a background process and extracts the
  tunnel URL from its log, rather than saying "terminal A".
- Duration is framed as expected, not as a limit: a long-running command is
  working, not hung, and there is no cap on CID count.

Page copy follows: SELF_SERVE_VOLUME_CAP_LABEL becomes
COORDINATION_VOLUME_LABEL and reads as coordination rather than a ceiling, so
an agent reading the page cannot reproduce the original false blocker.

Reviewed by Codex and Gemini via the peer-review skill; every finding above
came out of that pass. Cursor could not run -- it needs auth.
---
 .gitignore                                    |   3 +
 src/app/ipfs2filecoin/constants/migration.ts  |  28 +-
 src/app/ipfs2filecoin/data/faqs.tsx           |  10 +-
 src/app/ipfs2filecoin/data/limits.ts          |   6 +-
 .../ipfs2filecoin/data/migration-runbook.ts   | 332 ++++++++++++++++++
 src/app/ipfs2filecoin/llms.txt/route.ts       | 115 ++----
 src/app/ipfs2filecoin/migrate.md/route.ts     |  14 +
 src/app/ipfs2filecoin/page.tsx                |  20 +-
 src/app/llms.txt/route.ts                     |  47 +++
 9 files changed, 458 insertions(+), 117 deletions(-)
 create mode 100644 src/app/ipfs2filecoin/data/migration-runbook.ts
 create mode 100644 src/app/ipfs2filecoin/migrate.md/route.ts
 create mode 100644 src/app/llms.txt/route.ts

diff --git a/.gitignore b/.gitignore
index 5ef6a520..4fc5fa81 100644
--- a/.gitignore
+++ b/.gitignore
@@ -39,3 +39,6 @@ yarn-error.log*
 # typescript
 *.tsbuildinfo
 next-env.d.ts
+
+# Local test fixtures, not part of the site
+dapper-labs-nba-topshots-cids.txt
diff --git a/src/app/ipfs2filecoin/constants/migration.ts b/src/app/ipfs2filecoin/constants/migration.ts
index f226ed63..269fb858 100644
--- a/src/app/ipfs2filecoin/constants/migration.ts
+++ b/src/app/ipfs2filecoin/constants/migration.ts
@@ -1,12 +1,24 @@
 import { BASE_URL } from '@/constants/site-metadata'
 
 /**
- * Caps for the browser-based check. Larger inputs are steered to the CLI or to
- * the contact form, because they need capacity agreed with providers up front.
+ * Cap on the in-browser check only. The agent and CLI paths have no item cap,
+ * so this must never be presented as a limit on migration itself.
  */
 export const BROWSER_CHECK_ITEM_CAP = 500
+
+/** A hard limit: a larger item cannot be split without changing its CID. */
 export const MAX_ITEM_SIZE_LABEL = '1 GiB'
-export const SELF_SERVE_VOLUME_CAP_LABEL = '500 GiB'
+
+/**
+ * Above this, capacity and timing are worth agreeing with providers before a
+ * run starts. A prompt to coordinate, NOT a ceiling on what can be migrated.
+ */
+export const COORDINATION_VOLUME_LABEL = '500 GiB'
+
+/** The ipfs2foc release this runbook's commands and flags were verified against. */
+export const CLI_PACKAGE = 'ipfs2foc'
+export const CLI_VERSION = '0.6.0'
+export const CLI_REPO_URL = 'https://github.com/FilOzone/ipfs2foc'
 
 /** Warm storage list price, per copy. Two copies are stored by default. */
 export const USD_PER_TIB_MONTH_PER_COPY = 2.5
@@ -27,11 +39,19 @@ export const DAYS_PER_MONTH = 30
  */
 export const BUFFER_DAYS = 30
 
+/**
+ * The executable runbook. Named for what it is: llms.txt is specified as a
+ * documentation index, not a procedure, so the procedure lives at its own URL.
+ */
+export const RUNBOOK_PATH = '/ipfs2filecoin/migrate.md'
+export const RUNBOOK_URL = `${BASE_URL}${RUNBOOK_PATH}`
+
+/** Spec-conformant index for this campaign, pointing at the runbook. */
 export const LLMS_TXT_PATH = '/ipfs2filecoin/llms.txt'
 export const LLMS_TXT_URL = `${BASE_URL}${LLMS_TXT_PATH}`
 
 /** The one line a user hands to a coding agent. Copying it is signal, so it is tracked. */
-export const AGENT_PROMPT = `Migrate my IPFS data to Filecoin: read ${LLMS_TXT_URL} and follow it. My CIDs are in cids.txt.`
+export const AGENT_PROMPT = `Migrate my IPFS data to Filecoin: read ${RUNBOOK_URL} and follow it. My CIDs are in cids.txt.`
 
 export const PLAUSIBLE_EVENTS = {
   cidListChecked: 'IPFS2Filecoin CID List Checked',
diff --git a/src/app/ipfs2filecoin/data/faqs.tsx b/src/app/ipfs2filecoin/data/faqs.tsx
index 6ff1406b..06449fe1 100644
--- a/src/app/ipfs2filecoin/data/faqs.tsx
+++ b/src/app/ipfs2filecoin/data/faqs.tsx
@@ -4,7 +4,7 @@ import type { Question } from '@/components/Faq'
 
 import { PATHS } from '@/constants/paths'
 
-import { LLMS_TXT_PATH } from '../constants/migration'
+import { RUNBOOK_PATH } from '../constants/migration'
 
 export const faqs: Array<Question> = [
   {
@@ -89,10 +89,10 @@ export const faqs: Array<Question> = [
       <>
         <p>
           All of the work, and none of the spending. The brief at{' '}
-          <MarkdownLink href={LLMS_TXT_PATH}>{LLMS_TXT_PATH}</MarkdownLink>{' '}
-          gives an agent the command sequence, the caps, and the prerequisites,
-          and the tool runs headless with JSON status output so it can read its
-          own progress and recover from failures.
+          <MarkdownLink href={RUNBOOK_PATH}>{RUNBOOK_PATH}</MarkdownLink> gives
+          an agent the command sequence, the caps, and the prerequisites, and
+          the tool runs headless with JSON status output so it can read its own
+          progress and recover from failures.
         </p>
         <p>
           What it hands back to you are the two steps that move money: funding
diff --git a/src/app/ipfs2filecoin/data/limits.ts b/src/app/ipfs2filecoin/data/limits.ts
index 5f4c863d..d68d01df 100644
--- a/src/app/ipfs2filecoin/data/limits.ts
+++ b/src/app/ipfs2filecoin/data/limits.ts
@@ -1,6 +1,6 @@
 import {
+  COORDINATION_VOLUME_LABEL,
   MAX_ITEM_SIZE_LABEL,
-  SELF_SERVE_VOLUME_CAP_LABEL,
 } from '../constants/migration'
 
 export const limits = [
@@ -14,9 +14,9 @@ export const limits = [
     description: `Individual assets larger than ${MAX_ITEM_SIZE_LABEL} cannot be moved yet, because splitting them would change their CID and that is the one thing we will not do. Large sets of small items are fine.`,
   },
   {
-    title: `Past ${SELF_SERVE_VOLUME_CAP_LABEL}, talk to us first`,
+    title: `Past ${COORDINATION_VOLUME_LABEL}, talk to us first`,
     description:
-      'A migration that size needs capacity and timing agreed with storage providers before it starts. We would rather scope it with you up front than have you discover the ceiling partway through a run.',
+      'Not a ceiling: there is no cap on how many CIDs an agent or the command line can migrate. But a run that size is worth agreeing with storage providers up front, so capacity and timing are arranged before you start rather than discovered partway through.',
   },
   {
     title: 'Filecoin uses its own identifier underneath',
diff --git a/src/app/ipfs2filecoin/data/migration-runbook.ts b/src/app/ipfs2filecoin/data/migration-runbook.ts
new file mode 100644
index 00000000..db3d54cf
--- /dev/null
+++ b/src/app/ipfs2filecoin/data/migration-runbook.ts
@@ -0,0 +1,332 @@
+import { PATHS } from '@/constants/paths'
+import { BASE_URL } from '@/constants/site-metadata'
+
+import {
+  BUFFER_DAYS,
+  CLI_PACKAGE,
+  CLI_REPO_URL,
+  CLI_VERSION,
+  COORDINATION_VOLUME_LABEL,
+  COPIES,
+  DAYS_PER_MONTH,
+  MAX_ITEM_SIZE_LABEL,
+  RUNBOOK_PATH,
+  USD_LIFECYCLE_RESERVE_PER_DATA_SET,
+  USD_PER_TIB_MONTH_PER_COPY,
+  USD_PROVING_PER_TIB_MONTH_PER_COPY,
+} from '../constants/migration'
+
+const CONTACT_URL = `${BASE_URL}${PATHS.CONTACT.path}`
+const LANDING_URL = `${BASE_URL}${PATHS.IPFS_TO_FILECOIN.path}`
+
+/**
+ * The executable procedure served at {@link RUNBOOK_PATH}. This is the product
+ * for the agent audience, so it names the tool, pins the version its flags were
+ * verified against, and states its stop conditions explicitly. Every claim here
+ * should be checkable against the ipfs2foc README.
+ */
+export const MIGRATION_RUNBOOK = `---
+tool: ${CLI_PACKAGE}
+tool_version: "${CLI_VERSION}"
+tool_repo: ${CLI_REPO_URL}
+node: ">=26"
+default_network: mainnet
+input: a text file of IPFS CIDs, one per line
+item_size_limit: ${MAX_ITEM_SIZE_LABEL}
+item_count_limit: none
+stop_and_ask:
+  - stage 0, before exposing a local port to the internet
+  - stage 4, before any transaction that spends
+never:
+  - re-chunk or alter content
+  - delete data from the existing provider
+  - accept a private key into your context
+---
+
+# Migrate IPFS data to Filecoin — agent runbook
+
+> You are migrating already-pinned IPFS CIDs onto Filecoin warm storage using
+> the \`${CLI_PACKAGE}\` CLI. Each CID stays byte-identical and, on a data set
+> created with IPFS indexing, keeps resolving over IPFS afterwards. This
+> document is the whole procedure. Run these commands. Do not build a
+> commitment or packing pipeline of your own — the on-chain add rejects a
+> mismatched commitment, so an improvised pipeline fails late and expensively.
+
+Verified against \`${CLI_PACKAGE}@${CLI_VERSION}\`. Full command reference:
+${CLI_REPO_URL}
+
+## Rules
+
+1. **Never re-chunk, repackage, or alter content.** An unchanged CID is the
+   point of the migration.
+2. **Never delete data from the current provider.** Verification comes first;
+   deletion is the user's decision afterwards.
+3. **Never take a private key into your context.** Not in chat, not in a file
+   you read. Stage 4 is executed by the user in their own terminal.
+4. **Stop and ask at the two gates below.** Exposing a local port (stage 0) and
+   spending (stage 4) are the user's decisions.
+5. **The deposit is the ceiling.** A key that can sign on the account can draw
+   against its balance. Advise a wallet kept for this purpose, holding what this
+   migration needs and nothing else.
+6. **Report failures with counts and names.** Never silently drop a CID.
+
+## Setup
+
+Install once, then every command below runs as \`${CLI_PACKAGE} ...\`:
+
+\`\`\`bash
+npm install -g ${CLI_PACKAGE}@${CLI_VERSION}
+${CLI_PACKAGE} --version
+\`\`\`
+
+If you cannot install globally, prefix **every** command in this document with
+\`npx -y ${CLI_PACKAGE}@${CLI_VERSION}\` instead. Do not mix the two forms: a bare
+\`${CLI_PACKAGE}\` after only an \`npx\` check is the most common first failure.
+
+Set the network once and pass it to every on-chain command:
+
+\`\`\`bash
+NETWORK=mainnet        # or: NETWORK=calibration, to rehearse on the testnet
+\`\`\`
+
+Rehearsing the whole flow on calibration first is strongly recommended before
+spending real funds.
+
+### Needed now (stages 0-3)
+
+- Node 26 or newer. Hard requirement. Check with \`node --version\`.
+- A CID list, one per line. Blank lines and \`#\` comments are ignored.
+- A trustless gateway that serves deterministic CARs. Stage 1 verifies this.
+
+### Needed before stage 4, not before
+
+- A wallet holding USDFC for storage and FIL for gas. **The user holds this
+  key. You never see it.**
+- A provider id from \`https://pdp.vxb.ai/\${NETWORK}/providers\`.
+
+Do not block stages 0-3 on the wallet. Those stages are free and need no key.
+
+## Stage 0 — settle ingress before computing anything
+
+At submission the storage provider pulls each piece from a public HTTPS origin.
+Private, loopback, and CGNAT addresses are rejected. **Resolve this first.**
+Discovering it after the commitment pass wastes that entire pass, which on a
+large list is hours of work.
+
+| Option | Flag | Requires | Works with |
+| --- | --- | --- | --- |
+| Cloudflare quick tunnel | \`--ingress cloudflared\` | \`cloudflared\` on PATH, no account | any path |
+| Tailscale Funnel or a VPS | \`--ingress funnel\` | you front the port yourself | any path |
+| Shared relay | \`--source-relay <url>\` | a relay base URL | single-asset path only |
+
+\`\`\`bash
+command -v cloudflared
+\`\`\`
+
+The relay is **only** valid for the single-asset path. If stage 2 sends you to
+the multi-asset path, the provider must pull assembled CAR files from your own
+origin, and the relay cannot serve them.
+
+**Gate.** If no option is available, stop and tell the user. A tunnel exposes a
+local port to the internet; that is their decision to make, not yours. Do not
+install a tunnel binary on their behalf.
+
+## Stage 1 — confirm the gateway serves deterministic CARs
+
+\`\`\`bash
+${CLI_PACKAGE} probe <one-cid-from-the-list> --gateway https://trustless-gateway.link
+\`\`\`
+
+\`WARN\` means the bytes did not re-hash to the requested CID, or the response was
+not a CAR. That gateway cannot be a source. Try another before continuing; the
+repo's \`docs/sources.md\` lists per-provider notes. Do not proceed on a \`WARN\`:
+the provider re-fetches and recomputes, so a non-deterministic source fails
+every piece.
+
+## Stage 2 — measure, then tell the user what they are in for
+
+Free, read-only, no wallet.
+
+\`\`\`bash
+${CLI_PACKAGE} analyze --cids cids.txt --sample 100 --json
+\`\`\`
+
+Use \`--all\` instead of \`--sample 100\` only when the list is small enough that
+probing every CID is affordable; it is the only way to get an exact per-CID
+result at this stage.
+
+The JSON gives you \`input.totalCount\`, \`input.estimatedTotalSizeBytes\`,
+\`sourceGateway.successRate\`, \`sourceGateway.latencyP50Ms\`, per-probe \`bytes\`,
+and a \`persona\` block of recommended flags. It does **not** give you a cost or a
+completion time. Derive those as below; do not invent a formula.
+
+### What to report back before going further
+
+- CID count, and the sampled retrieval success rate. If you sampled, say so —
+  you know which CIDs failed **in the sample**, not across the whole list. The
+  exact per-CID result comes out of stage 3.
+- Projected total size, from \`estimatedTotalSizeBytes\`.
+- **Projected wall-clock time.** A rough lower bound for the commitment pass is
+  \`totalCount × latencyP50Ms ÷ concurrency\`. State it as approximate, and say
+  that the provider's pull rate — not this pass — dominates the total for a
+  large run.
+- Estimated storage cost, using the formula below.
+
+### Cost formula
+
+Storage is ${USD_PER_TIB_MONTH_PER_COPY} USDFC per TiB per month per copy plus
+${USD_PROVING_PER_TIB_MONTH_PER_COPY} proving, across ${COPIES} copies by default:
+
+\`\`\`
+burn_per_TiB_month = (${USD_PER_TIB_MONTH_PER_COPY} + ${USD_PROVING_PER_TIB_MONTH_PER_COPY}) × ${COPIES}
+storage   = size_TiB × burn_per_TiB_month × (days_funded ÷ ${DAYS_PER_MONTH})
+buffer    = size_TiB × burn_per_TiB_month          # ${BUFFER_DAYS} days, refundable
+reserve   = ${USD_LIFECYCLE_RESERVE_PER_DATA_SET} × ${COPIES}                     # per data set, unused portion returns
+deposit   = storage + buffer + reserve
+\`\`\`
+
+Gas is paid separately in FIL. A deposit funds a rate, not a term: storing more
+data later spends the balance faster and moves the funded-until date earlier.
+Treat these as estimates; the exact deposit is shown at funding time.
+
+### Long runs are normal, not a limit
+
+**There is no cap on how many CIDs this path can migrate.** A large list simply
+takes a long time — often many hours. Say so plainly and let the user decide.
+Do not treat duration as a blocker, and do not route a large list away on size
+alone.
+
+- A command that runs for hours is working, not hung. Do not kill it. State is
+  kept in SQLite and a stopped run resumes where it left off.
+- Run on a machine that stays awake. A sleeping laptop stalls the run.
+- Use the flags \`analyze\` recommends in its \`persona\` block rather than guessing.
+
+Above roughly ${COORDINATION_VOLUME_LABEL}, capacity and timing are worth
+agreeing with providers before starting. That is coordination, not a ceiling:
+mention ${CONTACT_URL} as an option and continue if the user wants to.
+
+### Choosing a packing path
+
+Providers enforce a **minimum piece size** (commonly 1 MiB) and a pull limit of
+roughly ${MAX_ITEM_SIZE_LABEL} raw per item. Read the actual values for your
+chosen provider from \`https://pdp.vxb.ai/\${NETWORK}/providers\` before deciding.
+
+Evaluate against the per-probe \`bytes\` in the \`analyze\` JSON:
+
+- **Few sampled items below the provider minimum** → single-asset path
+  (the default). Each CID becomes one passthrough item pulled straight from the
+  gateway. No staging disk needed.
+- **A meaningful share below the minimum** → multi-asset path, or those CIDs
+  fail at pull time. Needs disk for assembled CARs, and rules out the relay.
+- **Any item above the pull limit** → cannot be migrated; splitting it would
+  change its CID. Hold those out and report them to the user.
+
+## Stage 3 — plan
+
+\`\`\`bash
+# single-asset (default)
+${CLI_PACKAGE} plan --cids cids.txt --db migrate.db
+
+# multi-asset, when many items fall below the provider minimum
+${CLI_PACKAGE} plan --cids cids.txt --db migrate.db --no-auto-pack
+${CLI_PACKAGE} pack-cars --db migrate.db --car-store ./cars --pack-target-size 512MiB
+\`\`\`
+
+\`plan\` is insert-only and resumable: re-running it computes only CIDs not yet
+done and never disturbs committed state. This stage produces the **exact**
+per-CID result, including anything unretrievable or \`oversized\`. Report that to
+the user; it supersedes the stage 2 sample.
+
+Check progress at any time with \`${CLI_PACKAGE} status --json\`.
+
+## Stage 4 — funding (the user runs this, not you)
+
+**Gate. This stage spends money and requires a private key.**
+
+Stop. Give the user these commands to run **in their own terminal**, and ask
+them to paste back only the printed \`dataSetId\`. Do not offer to run these for
+them, and do not accept a key if one is offered — a key pasted into a chat is a
+key in a transcript.
+
+\`\`\`bash
+export PRIVATE_KEY=0x...                                  # user's terminal only
+npx filecoin-pin@latest payments setup --auto --network "$NETWORK"
+npx filecoin-pin@latest payments status --network "$NETWORK"
+${CLI_PACKAGE} create-data-set --provider-id <id> --network "$NETWORK"
+\`\`\`
+
+\`create-data-set\` reverts if the USDFC deposit or the operator approval is
+insufficient. Remind the user that the deposited amount is the ceiling on
+everything downstream.
+
+**Resume only when the user confirms funding succeeded and gives you the
+\`dataSetId\`.** Submission in stage 5 also signs, so it needs the same key
+available in the environment where it runs. If the user wants to keep the key
+off your machine entirely, stage 5 is theirs to run too, and you read back the
+report from stage 6.
+
+## Stage 5 — submit
+
+Two processes. The pull source must stay running for the whole submission.
+
+\`\`\`bash
+# Start in the background and read its log until it prints the public URL.
+${CLI_PACKAGE} redirect-serve --db migrate.db --port 4322 --ingress cloudflared
+# logs: "cloudflared ingress: ready at https://<words>.trycloudflare.com"
+\`\`\`
+
+Extract that HTTPS origin from the log output and pass it as \`--source-base\`.
+It is the **origin only** — scheme and host, no path. Then:
+
+\`\`\`bash
+${CLI_PACKAGE} pdp-submit --db migrate.db --data-set-id <id> \\
+  --source-base https://<public-host> --network "$NETWORK"
+\`\`\`
+
+With a relay instead of your own ingress (single-asset path only):
+
+\`\`\`bash
+${CLI_PACKAGE} pdp-submit --db migrate.db --data-set-id <id> \\
+  --source-relay <relay-base> --network "$NETWORK"
+\`\`\`
+
+\`pdp-submit\` is resumable and will not double-submit. It pauses when the network
+base fee is above \`--max-base-fee\`; that is congestion backoff, not a failure.
+Check with \`${CLI_PACKAGE} gas --network "$NETWORK"\`.
+
+## Stage 6 — verify
+
+\`\`\`bash
+${CLI_PACKAGE} report --db migrate.db --data-set-id <id> --network "$NETWORK" --json
+\`\`\`
+
+This reconciles local state against the pieces the data set actually holds on
+chain. Hand the user the report, the data set id, and the path to \`migrate.db\`.
+
+Tell them explicitly: **check retrieval of a few of their own CIDs, and keep the
+old pinning plan until they have.** Verification is theirs to accept, not yours
+to declare.
+
+## Failure modes
+
+| Symptom | Meaning | Action |
+| --- | --- | --- |
+| \`probe\` reports \`WARN\` | gateway does not serve deterministic CARs | pick another gateway |
+| \`plan\` reports \`oversized\` | padded size exceeds the aggregate budget | hold that CID out, report it |
+| \`below provider min piece size\` | items under the minimum on the passthrough path | switch to the multi-asset path |
+| provider rejects the pull | \`--source-base\` has a path, or is not a public IP | pass origin only, recheck ingress |
+| submission pauses on \`spike\` | base fee above the gate | wait it out; this is expected |
+| \`set PRIVATE_KEY\` error | key not in that shell's environment | the user exports it in their own terminal |
+| aggregate stuck \`failed\` | see the repo's recovery commands | \`reset-failed-aggregates\` |
+
+One unretrievable item fails everything batched with it, which is why stages 2
+and 3 validate retrievability before anything is submitted.
+
+## Links
+
+- Tool, full command reference, and troubleshooting: ${CLI_REPO_URL}
+- Rehearse on the testnet first: \`docs/tutorial-first-migration.md\` in that repo
+- Landing page: ${LANDING_URL}
+- Talk to the team about capacity: ${CONTACT_URL}
+- This runbook: ${BASE_URL}${RUNBOOK_PATH}
+`
diff --git a/src/app/ipfs2filecoin/llms.txt/route.ts b/src/app/ipfs2filecoin/llms.txt/route.ts
index 5f57935c..b1029a1e 100644
--- a/src/app/ipfs2filecoin/llms.txt/route.ts
+++ b/src/app/ipfs2filecoin/llms.txt/route.ts
@@ -2,113 +2,40 @@ import { PATHS } from '@/constants/paths'
 import { BASE_URL, FOC_URLS } from '@/constants/site-metadata'
 
 import {
-  BROWSER_CHECK_ITEM_CAP,
-  COPIES,
+  CLI_REPO_URL,
   MAX_ITEM_SIZE_LABEL,
-  SELF_SERVE_VOLUME_CAP_LABEL,
-  USD_PER_TIB_MONTH_PER_COPY,
+  RUNBOOK_PATH,
 } from '../constants/migration'
 
 /**
- * Placeholder migration brief. The full command sequence lives with the tool
- * that runs it, in FilOzone/ipfs2foc, and replaces the body of this route once
- * it is published. Serving it from here now means the prompt on the landing
- * page resolves and we can see who is fetching it.
+ * Spec-conformant llms.txt for this campaign: an H1, a blockquote summary, then
+ * H2 lists of links. Per llmstxt.org this format is a documentation index, not
+ * a procedure, so the procedure lives at migrate.md and this file points to it.
  */
-const LLMS_TXT = `# IPFS to Filecoin — migration brief
+const LLMS_TXT = `# IPFS to Filecoin
 
-> DRAFT. This brief is published ahead of the full command sequence. It states
-> what the migration does, what it costs, and where it stops. Do not infer
-> commands that are not listed here; check the tool's README instead.
+> Move already-pinned IPFS data onto Filecoin warm storage without changing your
+> CIDs. Each CID stays byte-identical and keeps resolving over IPFS. Storage
+> providers prove possession on chain on a schedule.
 
-## What this is
+If you are an agent asked to perform a migration, read the runbook first: it is
+the complete procedure, and the rest of these links are background.
 
-A migration of pinned IPFS data into Filecoin warm storage. Content is stored as
-the CAR of the original DAG, so every CID stays byte-identical and keeps
-resolving from any public IPFS gateway. Storage providers prove possession
-onchain on a schedule.
+## Do the migration
 
-## Prerequisites
+- [Migration runbook](${BASE_URL}${RUNBOOK_PATH}): the executable procedure — prerequisites, ordered command sequence, stop conditions, and failure modes. Start here.
+- [ipfs2foc](${CLI_REPO_URL}): the CLI the runbook drives, with the full command reference and troubleshooting.
 
-- Node.js 26 or newer. This is a hard requirement.
-- A list of CIDs, one per line, in a text file (conventionally cids.txt).
-- Each CID must be retrievable from a public IPFS gateway. Private pinning
-  accounts and authenticated endpoints are not reachable this way.
-- A wallet holding USDFC for storage and a small amount of FIL for gas.
-  Use a wallet kept for this purpose. The deposited balance is the ceiling on
-  what any unattended run can spend.
-- A public HTTPS origin the storage provider can pull pieces from. See stage 0.
+## Background
 
-## Stage 0 — check the ingress before anything else
+- [IPFS to Filecoin](${BASE_URL}${PATHS.IPFS_TO_FILECOIN.path}): what this is, what it costs, and what it does not do. Includes a free in-browser CID check.
+- [Warm storage service](${BASE_URL}${PATHS.WARM_STORAGE_SERVICE.path}): the storage product underneath, and its pricing.
+- [Service providers](${BASE_URL}${PATHS.SERVICE_PROVIDERS.path}): the providers that store and prove the data.
+- [Documentation](${FOC_URLS.documentation.home}): Filecoin Onchain Cloud docs.
 
-At submission a storage provider pulls pieces from a public HTTPS origin that
-you supply. Private and loopback addresses are rejected. Confirm you have one
-of these BEFORE computing piece commitments, because discovering it afterwards
-wastes the entire run:
+## Limits
 
-- the \`cloudflared\` binary installed, for \`--ingress cloudflared\`; or
-- a VPS or Tailscale fronting the port yourself, for \`--ingress funnel\`; or
-- a source relay URL, for \`--source-relay\`.
-
-If none is available, stop and report that to the user rather than choosing one
-on their behalf. Installing a tunnel binary and exposing a local port to the
-internet is the user's decision to make.
-
-## Caps
-
-- ${MAX_ITEM_SIZE_LABEL} per item. Larger assets cannot be moved yet, because
-  splitting them would change their CID.
-- ${SELF_SERVE_VOLUME_CAP_LABEL} total for a self-serve run. Past that, capacity
-  and timing must be agreed with storage providers first: ${BASE_URL}${PATHS.CONTACT.path}
-- ${BROWSER_CHECK_ITEM_CAP} items for the in-browser check on the landing page.
-  The command-line tool has no item cap and resumes if a run stops.
-
-## Cost
-
-Storage is ${USD_PER_TIB_MONTH_PER_COPY} USDFC per TiB per month per copy, at
-${COPIES} copies by default, streamed to providers per epoch. A small proving
-charge is billed alongside it. Funding is a deposit covering a chosen period,
-plus a refundable 30-day buffer and a per-data-set lifecycle reserve held while
-the data is stored. Gas is paid separately in FIL.
-
-A deposit funds a rate, not a term. Funded duration is the available balance
-divided by the burn rate across every data set on the account, so storing more
-data later moves the funded-until date earlier.
-
-## Stages
-
-1. analyze — read the CID list, fetch each CID from a public gateway, compute
-   its Filecoin piece identifier and size. Free, no wallet, nothing charged.
-2. plan — produce the deposit required for the chosen retention period, and the
-   list of CIDs that could not be retrieved.
-3. fund — deposit USDFC and approve spending. This step moves money and is
-   handed back to the human.
-4. migrate — providers pull the data and commit it onchain.
-5. verify — retrieve by original CID and check the onchain proof, then keep the
-   manifest mapping every IPFS CID to its Filecoin piece identifier.
-
-## Failure modes
-
-- Unreachable CIDs are reported with counts and recorded in the manifest. They
-  are never silently dropped.
-- A stopped run resumes from its recorded state. Nothing already stored is
-  re-paid for.
-- If the funded balance runs out, providers can end the service and keep the
-  buffer. Top up before the funded-until date.
-
-## Do not
-
-- Re-chunk, repackage, or otherwise alter content. Changing a CID defeats the
-  point of the migration.
-- Delete data from the existing pinning provider until the migration has been
-  verified.
-- Use a key to a wallet that holds anything beyond what this migration needs.
-
-## Links
-
-- Landing page: ${BASE_URL}${PATHS.IPFS_TO_FILECOIN.path}
-- Documentation: ${FOC_URLS.documentation.home}
-- Talk to our team: ${BASE_URL}${PATHS.CONTACT.path}
+- [Talk to our team](${BASE_URL}${PATHS.CONTACT.path}): for sources that are not reachable from a public gateway, or to agree capacity and timing before a large run. There is no cap on how many CIDs the agent or CLI path can migrate; individual items above ${MAX_ITEM_SIZE_LABEL} cannot be migrated, because splitting them would change their CID.
 `
 
 export function GET() {
diff --git a/src/app/ipfs2filecoin/migrate.md/route.ts b/src/app/ipfs2filecoin/migrate.md/route.ts
new file mode 100644
index 00000000..489a136a
--- /dev/null
+++ b/src/app/ipfs2filecoin/migrate.md/route.ts
@@ -0,0 +1,14 @@
+import { MIGRATION_RUNBOOK } from '../data/migration-runbook'
+
+/**
+ * The executable runbook an agent follows end to end. Served as markdown so an
+ * agent that fetches it gets the procedure verbatim rather than a rendered page.
+ */
+export function GET() {
+  return new Response(MIGRATION_RUNBOOK, {
+    headers: {
+      'Content-Type': 'text/markdown; charset=utf-8',
+      'Cache-Control': 'public, max-age=0, s-maxage=3600',
+    },
+  })
+}
diff --git a/src/app/ipfs2filecoin/page.tsx b/src/app/ipfs2filecoin/page.tsx
index 3a1ed035..439d7521 100644
--- a/src/app/ipfs2filecoin/page.tsx
+++ b/src/app/ipfs2filecoin/page.tsx
@@ -22,10 +22,7 @@ import { AgentPrompt } from './components/AgentPrompt'
 import { CidListChecker } from './components/CidListChecker'
 import { ComparisonTable } from './components/ComparisonTable'
 import { CostEstimator } from './components/CostEstimator'
-import {
-  LLMS_TXT_PATH,
-  SELF_SERVE_VOLUME_CAP_LABEL,
-} from './constants/migration'
+import { COORDINATION_VOLUME_LABEL, RUNBOOK_PATH } from './constants/migration'
 import { IPFS2FILECOIN_SEO } from './constants/seo'
 import { faqs } from './data/faqs'
 import { limits } from './data/limits'
@@ -154,9 +151,9 @@ export default function IpfsToFilecoin() {
               </Heading>
               <p className="text-(--color-paragraph-text)">
                 Give this line to Claude Code, Cursor, or any coding agent. It
-                reads the migration brief at{' '}
-                <SmartTextLink href={LLMS_TXT_PATH}>
-                  {LLMS_TXT_PATH}
+                reads the runbook at{' '}
+                <SmartTextLink href={RUNBOOK_PATH}>
+                  {RUNBOOK_PATH}
                 </SmartTextLink>
                 , works through your list, and reports back what landed.
               </p>
@@ -175,9 +172,10 @@ export default function IpfsToFilecoin() {
                 Talk to us
               </Heading>
               <p className="text-(--color-paragraph-text)">
-                For datasets over {SELF_SERVE_VOLUME_CAP_LABEL}, or sources that
-                are not reachable from a public gateway. Tell us what you are
-                holding and we will scope it with you.
+                For sources that are not reachable from a public gateway, or to
+                agree capacity and timing before a run over{' '}
+                {COORDINATION_VOLUME_LABEL}. That is coordination, not a
+                ceiling: the agent path has no cap on how many CIDs it migrates.
               </p>
               <Button
                 href={PATHS.CONTACT.path}
@@ -262,6 +260,6 @@ export const metadata: Metadata = {
      * So an agent pointed at the human URL discovers the migration brief
      * without being told the llms.txt convention.
      */
-    types: { 'text/markdown': LLMS_TXT_PATH },
+    types: { 'text/markdown': RUNBOOK_PATH },
   },
 }
diff --git a/src/app/llms.txt/route.ts b/src/app/llms.txt/route.ts
new file mode 100644
index 00000000..2f3e06a7
--- /dev/null
+++ b/src/app/llms.txt/route.ts
@@ -0,0 +1,47 @@
+import { RUNBOOK_PATH } from '@/app/ipfs2filecoin/constants/migration'
+import { PATHS } from '@/constants/paths'
+import { BASE_URL, FOC_URLS } from '@/constants/site-metadata'
+
+/**
+ * Site-root llms.txt, per llmstxt.org: an index of filecoin.cloud curated for
+ * language models. Subpaths may carry their own; /ipfs2filecoin/llms.txt does.
+ */
+const LLMS_TXT = `# Filecoin Onchain Cloud
+
+> Cloud services with onchain guarantees: ownership, verifiability, and
+> programmability. Storage is paid for on chain, proven on a schedule by storage
+> providers, and owned by a wallet rather than a vendor account.
+
+## Services
+
+- [Warm storage service](${BASE_URL}${PATHS.WARM_STORAGE_SERVICE.path}): verifiable storage backed by Proof of Data Possession, with pricing and live provider data.
+- [Service providers](${BASE_URL}${PATHS.SERVICE_PROVIDERS.path}): registry of providers, their capabilities, locations, and availability.
+- [Filecoin Pay](${FOC_URLS.filecoinPay}): payment rails that settle storage per epoch.
+
+## Migrate to Filecoin
+
+- [IPFS to Filecoin](${BASE_URL}${PATHS.IPFS_TO_FILECOIN.path}): move already-pinned IPFS data without changing your CIDs.
+- [Migration runbook](${BASE_URL}${RUNBOOK_PATH}): the executable procedure for an agent performing that migration.
+
+## Build
+
+- [Documentation](${FOC_URLS.documentation.home}): guides, core concepts, and API reference.
+- [Getting started](${FOC_URLS.documentation.gettingStarted}): first steps for developers.
+- [Showcase](${BASE_URL}${PATHS.SHOWCASE.path}): SDKs, reference apps, and agent tooling built on the platform.
+- [Agents](${BASE_URL}${PATHS.AGENTS.path}): requests for startups building agent-native storage.
+
+## Support
+
+- [Support](${BASE_URL}${PATHS.SUPPORT.path}): the right channel for each kind of problem.
+- [Talk to our team](${BASE_URL}${PATHS.CONTACT.path}): use-case and capacity conversations.
+- [Status](${FOC_URLS.status}): current service status and incidents.
+`
+
+export function GET() {
+  return new Response(LLMS_TXT, {
+    headers: {
+      'Content-Type': 'text/markdown; charset=utf-8',
+      'Cache-Control': 'public, max-age=0, s-maxage=3600',
+    },
+  })
+}

From cc32d8e7b53c192426e6d1a14b2c8f96f2b9c60e Mon Sep 17 00:00:00 2001
From: Russell Dempsey <1173416+SgtPooki@users.noreply.github.com>
Date: Thu, 30 Jul 2026 11:10:51 -0400
Subject: [PATCH 03/26] fix(ipfs2filecoin): correct two runbook claims the CLI
 does not support

Audited every command and flag in the runbook against the USAGE string in
ipfs2foc's packages/cli/src/index.ts, which is authoritative. Two were wrong.

`ipfs2foc --version` is not a subcommand. It falls through to the default
branch, writes "unknown command: --version" to stderr, and sets exit code 1.
As the very first step of the runbook that reads like a broken install, which
is exactly the first-hop failure this rewrite exists to remove. The install
check is now `--help`, with a note saying why.

The provider's minimum piece size is advisory, not enforced. `pdp-submit`
warns and proceeds by default and only refuses under `--strict-piece-size`
(see submit-pdp.ts: "The advertised floor is advisory in practice"). The
runbook claimed items below the minimum fail at pull time, which would have
pushed agents onto the multi-asset path unnecessarily -- it needs staging disk
and rules out the relay. Now stated as the trade it is: the minimum is a
packing efficiency question, the pull limit is the hard one.
---
 .../ipfs2filecoin/data/migration-runbook.ts   | 29 +++++++++++++------
 1 file changed, 20 insertions(+), 9 deletions(-)

diff --git a/src/app/ipfs2filecoin/data/migration-runbook.ts b/src/app/ipfs2filecoin/data/migration-runbook.ts
index db3d54cf..dd866f55 100644
--- a/src/app/ipfs2filecoin/data/migration-runbook.ts
+++ b/src/app/ipfs2filecoin/data/migration-runbook.ts
@@ -76,9 +76,12 @@ Install once, then every command below runs as \`${CLI_PACKAGE} ...\`:
 
 \`\`\`bash
 npm install -g ${CLI_PACKAGE}@${CLI_VERSION}
-${CLI_PACKAGE} --version
+${CLI_PACKAGE} --help
 \`\`\`
 
+\`--help\` is the install check. There is no \`--version\` subcommand; it exits
+non-zero as an unknown command, which reads like a broken install when it is not.
+
 If you cannot install globally, prefix **every** command in this document with
 \`npx -y ${CLI_PACKAGE}@${CLI_VERSION}\` instead. Do not mix the two forms: a bare
 \`${CLI_PACKAGE}\` after only an \`npx\` check is the most common first failure.
@@ -207,19 +210,27 @@ mention ${CONTACT_URL} as an option and continue if the user wants to.
 
 ### Choosing a packing path
 
-Providers enforce a **minimum piece size** (commonly 1 MiB) and a pull limit of
-roughly ${MAX_ITEM_SIZE_LABEL} raw per item. Read the actual values for your
-chosen provider from \`https://pdp.vxb.ai/\${NETWORK}/providers\` before deciding.
+Providers advertise a **minimum piece size** (commonly 1 MiB) and enforce a pull
+limit of roughly ${MAX_ITEM_SIZE_LABEL} raw per item. Read the actual values for
+your chosen provider from \`https://pdp.vxb.ai/\${NETWORK}/providers\`.
+
+The two limits behave differently, and this matters:
+
+- The **minimum** is advisory. \`pdp-submit\` warns and proceeds by default; pass
+  \`--strict-piece-size\` to refuse instead. So small items are a packing
+  efficiency question, not a blocker.
+- The **pull limit** is hard. An item above it cannot be migrated, because
+  splitting it would change its CID. Hold those out and report them.
 
 Evaluate against the per-probe \`bytes\` in the \`analyze\` JSON:
 
 - **Few sampled items below the provider minimum** → single-asset path
   (the default). Each CID becomes one passthrough item pulled straight from the
   gateway. No staging disk needed.
-- **A meaningful share below the minimum** → multi-asset path, or those CIDs
-  fail at pull time. Needs disk for assembled CARs, and rules out the relay.
-- **Any item above the pull limit** → cannot be migrated; splitting it would
-  change its CID. Hold those out and report them to the user.
+- **A large share below the minimum** → consider the multi-asset path, which
+  batches them into fewer, larger pieces. It needs disk for the assembled CARs
+  and rules out the relay, so it is a trade rather than an obligation. Say which
+  you chose and why.
 
 ## Stage 3 — plan
 
@@ -313,7 +324,7 @@ to declare.
 | --- | --- | --- |
 | \`probe\` reports \`WARN\` | gateway does not serve deterministic CARs | pick another gateway |
 | \`plan\` reports \`oversized\` | padded size exceeds the aggregate budget | hold that CID out, report it |
-| \`below provider min piece size\` | items under the minimum on the passthrough path | switch to the multi-asset path |
+| \`below provider min piece size\` warning | items under the advertised minimum | expected; it proceeds. Use the multi-asset path only to pack more efficiently |
 | provider rejects the pull | \`--source-base\` has a path, or is not a public IP | pass origin only, recheck ingress |
 | submission pauses on \`spike\` | base fee above the gate | wait it out; this is expected |
 | \`set PRIVATE_KEY\` error | key not in that shell's environment | the user exports it in their own terminal |

From 55dcabdb48f10f1b3526b3be75cf8c7c2f295fa9 Mon Sep 17 00:00:00 2001
From: Russell Dempsey <1173416+SgtPooki@users.noreply.github.com>
Date: Mon, 3 Aug 2026 09:02:57 -0400
Subject: [PATCH 04/26] chore(ipfs2filecoin): re-verify competitor rates

Checked all four rows against filebase.com/pricing and pinata.cloud/pricing.
Every rate still matches: Filebase Pro storage $0.015/GB and IPFS egress
$0.015/GB; Pinata Fiesta $0.035/GB and $0.080/GB; Pinata Picnic $0.070/GB
and $0.100/GB.

No figures changed. The verification date lives in the source comment rather
than on the page: it is a maintenance note for us, it ages badly in public,
and the two pricing links already let a reader check the current numbers.
---
 src/app/ipfs2filecoin/data/pricing-comparison.ts | 8 +++++---
 src/app/ipfs2filecoin/page.tsx                   | 3 +--
 2 files changed, 6 insertions(+), 5 deletions(-)

diff --git a/src/app/ipfs2filecoin/data/pricing-comparison.ts b/src/app/ipfs2filecoin/data/pricing-comparison.ts
index 94123826..a0c15520 100644
--- a/src/app/ipfs2filecoin/data/pricing-comparison.ts
+++ b/src/app/ipfs2filecoin/data/pricing-comparison.ts
@@ -8,9 +8,11 @@ export type PricingRow = {
 }
 
 /**
- * Third-party rates are published list overage rates, captured 27 July 2026.
- * Overage is the rate that matters once you are past a plan's included
- * allowance, which anyone migrating a real archive already is.
+ * Third-party rates are published list overage rates, re-verified 3 August 2026
+ * against filebase.com/pricing and pinata.cloud/pricing. Overage is the rate
+ * that matters once you are past a plan's included allowance, which anyone
+ * migrating a real archive already is. These move without notice; re-check
+ * before each campaign push.
  */
 export const pricingComparison: Array<PricingRow> = [
   {
diff --git a/src/app/ipfs2filecoin/page.tsx b/src/app/ipfs2filecoin/page.tsx
index 439d7521..2f009530 100644
--- a/src/app/ipfs2filecoin/page.tsx
+++ b/src/app/ipfs2filecoin/page.tsx
@@ -86,8 +86,7 @@ export default function IpfsToFilecoin() {
 
             <p className="text-(--color-paragraph-text) text-sm/relaxed">
               Filecoin Warm Storage is $2.50 per TiB per month per copy at two
-              copies. Other rates are published list overage rates as of 27 July
-              2026, from{' '}
+              copies. Other rates are the published list overage rates from{' '}
               <ExternalTextLink href="https://filebase.com/pricing/">
                 Filebase
               </ExternalTextLink>{' '}

From b67a9fb27053f81d52101eccdd64afad57519c67 Mon Sep 17 00:00:00 2001
From: Russell Dempsey <1173416+SgtPooki@users.noreply.github.com>
Date: Mon, 3 Aug 2026 09:05:30 -0400
Subject: [PATCH 05/26] fix(ipfs2filecoin): stop pinning the CLI to an
 unpublished version

The runbook told agents to run `npm install -g ipfs2foc@0.6.0`. npm has only
0.1.0 through 0.4.0, so that resolves to nothing and fails with ETARGET on
the first command of the procedure. 0.6.0 is the in-tree version; the repo
runs ahead of what has been released.

Installing latest is correct and safe here. I unpacked the published 0.4.0
and checked its bundle directly: all fourteen commands the runbook uses are
present (analyze, commp, create-data-set, export, gas, import-manifest,
pack-cars, pdp-submit, plan, probe, redirect-serve, report, serve, status),
as is every flag it passes, including --strict-piece-size, --ingress,
--source-relay, --no-auto-pack, --sample and --car-store. 0.4.0 also has no
--version subcommand, so the --help install check holds there too.

The frontmatter now carries tool_min_version rather than an exact pin, since
what an agent needs to know is the floor, not the version someone happened
to verify against.
---
 src/app/ipfs2filecoin/constants/migration.ts  | 11 +++++++++--
 .../ipfs2filecoin/data/migration-runbook.ts   | 19 ++++++++++---------
 2 files changed, 19 insertions(+), 11 deletions(-)

diff --git a/src/app/ipfs2filecoin/constants/migration.ts b/src/app/ipfs2filecoin/constants/migration.ts
index 269fb858..0e39b984 100644
--- a/src/app/ipfs2filecoin/constants/migration.ts
+++ b/src/app/ipfs2filecoin/constants/migration.ts
@@ -15,11 +15,18 @@ export const MAX_ITEM_SIZE_LABEL = '1 GiB'
  */
 export const COORDINATION_VOLUME_LABEL = '500 GiB'
 
-/** The ipfs2foc release this runbook's commands and flags were verified against. */
 export const CLI_PACKAGE = 'ipfs2foc'
-export const CLI_VERSION = '0.6.0'
 export const CLI_REPO_URL = 'https://github.com/FilOzone/ipfs2foc'
 
+/**
+ * Do not pin the install to an exact version here. The repo runs ahead of npm
+ * (0.6.0 in tree while 0.4.0 was the published latest), so a pin to the tree
+ * version resolves to nothing and the very first command an agent runs fails
+ * with ETARGET. Every command and flag this runbook uses is present from
+ * 0.4.0 onward, so installing latest is both correct and safe.
+ */
+export const CLI_VERIFIED_FROM = '0.4.0'
+
 /** Warm storage list price, per copy. Two copies are stored by default. */
 export const USD_PER_TIB_MONTH_PER_COPY = 2.5
 export const COPIES = 2
diff --git a/src/app/ipfs2filecoin/data/migration-runbook.ts b/src/app/ipfs2filecoin/data/migration-runbook.ts
index dd866f55..9a4278eb 100644
--- a/src/app/ipfs2filecoin/data/migration-runbook.ts
+++ b/src/app/ipfs2filecoin/data/migration-runbook.ts
@@ -5,7 +5,7 @@ import {
   BUFFER_DAYS,
   CLI_PACKAGE,
   CLI_REPO_URL,
-  CLI_VERSION,
+  CLI_VERIFIED_FROM,
   COORDINATION_VOLUME_LABEL,
   COPIES,
   DAYS_PER_MONTH,
@@ -21,13 +21,14 @@ const LANDING_URL = `${BASE_URL}${PATHS.IPFS_TO_FILECOIN.path}`
 
 /**
  * The executable procedure served at {@link RUNBOOK_PATH}. This is the product
- * for the agent audience, so it names the tool, pins the version its flags were
- * verified against, and states its stop conditions explicitly. Every claim here
- * should be checkable against the ipfs2foc README.
+ * for the agent audience, so it names the tool, states the version its commands
+ * are known to work from, and makes its stop conditions explicit. Every claim
+ * here should be checkable against the ipfs2foc CLI itself, not just its README:
+ * the two have disagreed before.
  */
 export const MIGRATION_RUNBOOK = `---
 tool: ${CLI_PACKAGE}
-tool_version: "${CLI_VERSION}"
+tool_min_version: "${CLI_VERIFIED_FROM}"
 tool_repo: ${CLI_REPO_URL}
 node: ">=26"
 default_network: mainnet
@@ -52,8 +53,8 @@ never:
 > commitment or packing pipeline of your own — the on-chain add rejects a
 > mismatched commitment, so an improvised pipeline fails late and expensively.
 
-Verified against \`${CLI_PACKAGE}@${CLI_VERSION}\`. Full command reference:
-${CLI_REPO_URL}
+Every command and flag below is present from \`${CLI_PACKAGE}@${CLI_VERIFIED_FROM}\`
+onward. Full command reference: ${CLI_REPO_URL}
 
 ## Rules
 
@@ -75,7 +76,7 @@ ${CLI_REPO_URL}
 Install once, then every command below runs as \`${CLI_PACKAGE} ...\`:
 
 \`\`\`bash
-npm install -g ${CLI_PACKAGE}@${CLI_VERSION}
+npm install -g ${CLI_PACKAGE}
 ${CLI_PACKAGE} --help
 \`\`\`
 
@@ -83,7 +84,7 @@ ${CLI_PACKAGE} --help
 non-zero as an unknown command, which reads like a broken install when it is not.
 
 If you cannot install globally, prefix **every** command in this document with
-\`npx -y ${CLI_PACKAGE}@${CLI_VERSION}\` instead. Do not mix the two forms: a bare
+\`npx -y ${CLI_PACKAGE}@latest\` instead. Do not mix the two forms: a bare
 \`${CLI_PACKAGE}\` after only an \`npx\` check is the most common first failure.
 
 Set the network once and pass it to every on-chain command:

From abbe4cab3446197cbebc4f849cde4d18c8e4c7f4 Mon Sep 17 00:00:00 2001
From: Russell Dempsey <1173416+SgtPooki@users.noreply.github.com>
Date: Mon, 3 Aug 2026 10:07:10 -0400
Subject: [PATCH 06/26] fix(ipfs2filecoin): add the flat data set fee once, not
 per TiB

---
 .../components/CostEstimator.tsx              | 13 ++++++-----
 src/app/ipfs2filecoin/constants/migration.ts  | 10 ++++++--
 .../ipfs2filecoin/data/migration-runbook.ts   | 15 +++++++-----
 src/app/ipfs2filecoin/utils/estimate-cost.ts  | 23 +++++++++++--------
 4 files changed, 38 insertions(+), 23 deletions(-)

diff --git a/src/app/ipfs2filecoin/components/CostEstimator.tsx b/src/app/ipfs2filecoin/components/CostEstimator.tsx
index f8476e95..c4b8a760 100644
--- a/src/app/ipfs2filecoin/components/CostEstimator.tsx
+++ b/src/app/ipfs2filecoin/components/CostEstimator.tsx
@@ -9,6 +9,7 @@ import {
   BUFFER_DAYS,
   COPIES,
   PLAUSIBLE_EVENTS,
+  USD_FLAT_PER_DATA_SET_MONTH,
   USD_PER_TIB_MONTH_PER_COPY,
 } from '../constants/migration'
 import {
@@ -141,11 +142,11 @@ export function CostEstimator() {
 
       <p className="text-(--color-paragraph-text) text-sm/relaxed">
         Based on {formatUsd(USD_PER_TIB_MONTH_PER_COPY)} per TiB per month per
-        copy plus proving, across {COPIES} copies. Gas is separate, so you also
-        need a small amount of FIL. A deposit funds a rate rather than a term:
-        storing more data later spends the balance faster and moves your
-        funded-until date earlier. The exact deposit is shown before you approve
-        it.
+        copy, plus a flat {formatUsd(USD_FLAT_PER_DATA_SET_MONTH)} per data set
+        per month, across {COPIES} copies. Gas is separate, so you also need a
+        small amount of FIL. A deposit funds a rate rather than a term: storing
+        more data later spends the balance faster and moves your funded-until
+        date earlier. The exact deposit is shown before you approve it.
       </p>
     </div>
   )
@@ -158,7 +159,7 @@ function EstimateBreakdown({ estimate }: { estimate: CostEstimate }) {
 
   const rows = [
     {
-      label: `Storage and proving for ${durationLabel}`,
+      label: `Storage for ${durationLabel}`,
       amount: formatUsd(estimate.storage),
       note: 'No, this is the cost',
     },
diff --git a/src/app/ipfs2filecoin/constants/migration.ts b/src/app/ipfs2filecoin/constants/migration.ts
index 0e39b984..5b67184b 100644
--- a/src/app/ipfs2filecoin/constants/migration.ts
+++ b/src/app/ipfs2filecoin/constants/migration.ts
@@ -31,8 +31,14 @@ export const CLI_VERIFIED_FROM = '0.4.0'
 export const USD_PER_TIB_MONTH_PER_COPY = 2.5
 export const COPIES = 2
 
-/** Proving buffer charged alongside storage, per TiB per month per copy. */
-export const USD_PROVING_PER_TIB_MONTH_PER_COPY = 0.024
+/**
+ * Flat fee per data set per month, charged alongside the size-based rate. It
+ * does NOT scale with stored size: a data set's monthly rate is
+ * `size_TiB * USD_PER_TIB_MONTH_PER_COPY + USD_FLAT_PER_DATA_SET_MONTH`.
+ * Verified against live mainnet rail 2286, which stores 1.511356 TiB and pays
+ * 3.8023902 USDFC/month, matching that formula to five decimal places.
+ */
+export const USD_FLAT_PER_DATA_SET_MONTH = 0.024
 
 /** Held per data set, and one data set is created per copy. Unused portion returns. */
 export const USD_LIFECYCLE_RESERVE_PER_DATA_SET = 0.1
diff --git a/src/app/ipfs2filecoin/data/migration-runbook.ts b/src/app/ipfs2filecoin/data/migration-runbook.ts
index 9a4278eb..656d7273 100644
--- a/src/app/ipfs2filecoin/data/migration-runbook.ts
+++ b/src/app/ipfs2filecoin/data/migration-runbook.ts
@@ -11,9 +11,9 @@ import {
   DAYS_PER_MONTH,
   MAX_ITEM_SIZE_LABEL,
   RUNBOOK_PATH,
+  USD_FLAT_PER_DATA_SET_MONTH,
   USD_LIFECYCLE_RESERVE_PER_DATA_SET,
   USD_PER_TIB_MONTH_PER_COPY,
-  USD_PROVING_PER_TIB_MONTH_PER_COPY,
 } from '../constants/migration'
 
 const CONTACT_URL = `${BASE_URL}${PATHS.CONTACT.path}`
@@ -178,13 +178,16 @@ completion time. Derive those as below; do not invent a formula.
 
 ### Cost formula
 
-Storage is ${USD_PER_TIB_MONTH_PER_COPY} USDFC per TiB per month per copy plus
-${USD_PROVING_PER_TIB_MONTH_PER_COPY} proving, across ${COPIES} copies by default:
+Storage is ${USD_PER_TIB_MONTH_PER_COPY} USDFC per TiB per month per copy, plus
+a flat ${USD_FLAT_PER_DATA_SET_MONTH} per data set per month, across ${COPIES}
+copies by default. The flat fee is added ONCE per data set, not multiplied by
+size. Folding it into a per-TiB rate is exact at 1 TiB and wrong at every other
+size, badly so below it:
 
 \`\`\`
-burn_per_TiB_month = (${USD_PER_TIB_MONTH_PER_COPY} + ${USD_PROVING_PER_TIB_MONTH_PER_COPY}) × ${COPIES}
-storage   = size_TiB × burn_per_TiB_month × (days_funded ÷ ${DAYS_PER_MONTH})
-buffer    = size_TiB × burn_per_TiB_month          # ${BUFFER_DAYS} days, refundable
+burn_per_month = (size_TiB × ${USD_PER_TIB_MONTH_PER_COPY} + ${USD_FLAT_PER_DATA_SET_MONTH}) × ${COPIES}
+storage   = burn_per_month × (days_funded ÷ ${DAYS_PER_MONTH})
+buffer    = burn_per_month                         # ${BUFFER_DAYS} days, refundable
 reserve   = ${USD_LIFECYCLE_RESERVE_PER_DATA_SET} × ${COPIES}                     # per data set, unused portion returns
 deposit   = storage + buffer + reserve
 \`\`\`
diff --git a/src/app/ipfs2filecoin/utils/estimate-cost.ts b/src/app/ipfs2filecoin/utils/estimate-cost.ts
index 99a79979..641d55a9 100644
--- a/src/app/ipfs2filecoin/utils/estimate-cost.ts
+++ b/src/app/ipfs2filecoin/utils/estimate-cost.ts
@@ -2,9 +2,9 @@ import {
   BUFFER_DAYS,
   COPIES,
   DAYS_PER_MONTH,
+  USD_FLAT_PER_DATA_SET_MONTH,
   USD_LIFECYCLE_RESERVE_PER_DATA_SET,
   USD_PER_TIB_MONTH_PER_COPY,
-  USD_PROVING_PER_TIB_MONTH_PER_COPY,
 } from '../constants/migration'
 
 const BYTES_PER_TIB = 1024 ** 4
@@ -20,16 +20,21 @@ export const USD_STORAGE_PER_TIB_MONTH = USD_PER_TIB_MONTH_PER_COPY * COPIES
 export const USD_PER_TB_MONTH =
   USD_STORAGE_PER_TIB_MONTH * (BYTES_PER_TB / BYTES_PER_TIB)
 
-/**
- * What actually gets charged per epoch: storage plus the proving buffer, on
- * every copy. Used for the deposit, not for the headline comparison.
- */
-export const USD_BURN_PER_TIB_MONTH =
-  (USD_PER_TIB_MONTH_PER_COPY + USD_PROVING_PER_TIB_MONTH_PER_COPY) * COPIES
-
 /** One data set is created per copy, each holding its own lifecycle reserve. */
 export const USD_LIFECYCLE_RESERVE = USD_LIFECYCLE_RESERVE_PER_DATA_SET * COPIES
 
+/**
+ * What actually gets charged, across every copy. The flat fee is per data set
+ * and is added once, not multiplied by size: folding it into a per-TiB rate
+ * happens to be exact at 1 TiB and wrong everywhere else, badly so below it.
+ */
+export function usdBurnPerMonth(tebibytes: number) {
+  return (
+    (tebibytes * USD_PER_TIB_MONTH_PER_COPY + USD_FLAT_PER_DATA_SET_MONTH) *
+    COPIES
+  )
+}
+
 export type VolumeUnit = 'GiB' | 'TiB'
 
 export type CostEstimate = {
@@ -52,7 +57,7 @@ export function toTebibytes(volume: number, unit: VolumeUnit) {
 }
 
 export function estimateCost(tebibytes: number, days: number): CostEstimate {
-  const perMonth = tebibytes * USD_BURN_PER_TIB_MONTH
+  const perMonth = usdBurnPerMonth(tebibytes)
   const storage = perMonth * (days / DAYS_PER_MONTH)
   const buffer = perMonth * (BUFFER_DAYS / DAYS_PER_MONTH)
   const lifecycleReserve = USD_LIFECYCLE_RESERVE

From bc84838e750844bfe7eb891972a8ba18a3c13260 Mon Sep 17 00:00:00 2001
From: Russell Dempsey <1173416+SgtPooki@users.noreply.github.com>
Date: Mon, 3 Aug 2026 14:16:44 -0400
Subject: [PATCH 07/26] feat(ipfs2filecoin): rewrite the runbook for the
 direct-upload flow

---
 src/app/ipfs2filecoin/constants/migration.ts  |  17 +-
 .../ipfs2filecoin/data/migration-runbook.ts   | 259 ++++++++----------
 src/app/ipfs2filecoin/data/steps.ts           |   2 +-
 3 files changed, 120 insertions(+), 158 deletions(-)

diff --git a/src/app/ipfs2filecoin/constants/migration.ts b/src/app/ipfs2filecoin/constants/migration.ts
index 5b67184b..c97c17f2 100644
--- a/src/app/ipfs2filecoin/constants/migration.ts
+++ b/src/app/ipfs2filecoin/constants/migration.ts
@@ -6,8 +6,12 @@ import { BASE_URL } from '@/constants/site-metadata'
  */
 export const BROWSER_CHECK_ITEM_CAP = 500
 
-/** A hard limit: a larger item cannot be split without changing its CID. */
-export const MAX_ITEM_SIZE_LABEL = '1 GiB'
+/**
+ * A hard limit: an item's CAR must fit one uploadable piece, capped at
+ * 1,065,353,216 bytes (1016 MiB) by the storage SDK. A larger item cannot be
+ * split without changing its CID.
+ */
+export const MAX_ITEM_SIZE_LABEL = '1016 MiB'
 
 /**
  * Above this, capacity and timing are worth agreeing with providers before a
@@ -22,10 +26,13 @@ export const CLI_REPO_URL = 'https://github.com/FilOzone/ipfs2foc'
  * Do not pin the install to an exact version here. The repo runs ahead of npm
  * (0.6.0 in tree while 0.4.0 was the published latest), so a pin to the tree
  * version resolves to nothing and the very first command an agent runs fails
- * with ETARGET. Every command and flag this runbook uses is present from
- * 0.4.0 onward, so installing latest is both correct and safe.
+ * with ETARGET. Installing latest is both correct and safe.
+ *
+ * The `upload` command this runbook is built on ships in the release cut from
+ * FilOzone/ipfs2foc#71. GATE: do not merge/deploy this page until npm serves
+ * a version >= this constant (`npm view ipfs2foc version`).
  */
-export const CLI_VERIFIED_FROM = '0.4.0'
+export const CLI_VERIFIED_FROM = '0.8.0'
 
 /** Warm storage list price, per copy. Two copies are stored by default. */
 export const USD_PER_TIB_MONTH_PER_COPY = 2.5
diff --git a/src/app/ipfs2filecoin/data/migration-runbook.ts b/src/app/ipfs2filecoin/data/migration-runbook.ts
index 656d7273..10c22f64 100644
--- a/src/app/ipfs2filecoin/data/migration-runbook.ts
+++ b/src/app/ipfs2filecoin/data/migration-runbook.ts
@@ -25,6 +25,11 @@ const LANDING_URL = `${BASE_URL}${PATHS.IPFS_TO_FILECOIN.path}`
  * are known to work from, and makes its stop conditions explicit. Every claim
  * here should be checkable against the ipfs2foc CLI itself, not just its README:
  * the two have disagreed before.
+ *
+ * Built on the direct-upload flow (`ipfs2foc upload`, FilOzone/ipfs2foc#71):
+ * the client downloads, packs multi-root CARs locally, streams each straight to
+ * the storage providers, and batches the on-chain adds. No public HTTPS origin,
+ * tunnel, or relay is involved anywhere in this procedure.
  */
 export const MIGRATION_RUNBOOK = `---
 tool: ${CLI_PACKAGE}
@@ -35,9 +40,8 @@ default_network: mainnet
 input: a text file of IPFS CIDs, one per line
 item_size_limit: ${MAX_ITEM_SIZE_LABEL}
 item_count_limit: none
-stop_and_ask:
-  - stage 0, before exposing a local port to the internet
-  - stage 4, before any transaction that spends
+disk: free space roughly the size of the data being migrated, for staged CARs
+stop_and_ask: stage 3, before any transaction that spends
 never:
   - re-chunk or alter content
   - delete data from the existing provider
@@ -47,11 +51,16 @@ never:
 # Migrate IPFS data to Filecoin — agent runbook
 
 > You are migrating already-pinned IPFS CIDs onto Filecoin warm storage using
-> the \`${CLI_PACKAGE}\` CLI. Each CID stays byte-identical and, on a data set
-> created with IPFS indexing, keeps resolving over IPFS afterwards. This
-> document is the whole procedure. Run these commands. Do not build a
-> commitment or packing pipeline of your own — the on-chain add rejects a
-> mismatched commitment, so an improvised pipeline fails late and expensively.
+> the \`${CLI_PACKAGE}\` CLI. Each CID stays byte-identical and, because data
+> sets are created with IPFS indexing, keeps resolving over IPFS afterwards.
+> This document is the whole procedure. Run these commands. Do not build a
+> commitment, packing, or upload pipeline of your own — the on-chain add
+> rejects a mismatched commitment, so an improvised pipeline fails late and
+> expensively.
+
+The migration runs entirely from this machine: download, pack, and upload
+straight to ${COPIES} storage providers. Nothing here requires a public HTTPS
+origin, a tunnel, or inbound connectivity of any kind.
 
 Every command and flag below is present from \`${CLI_PACKAGE}@${CLI_VERIFIED_FROM}\`
 onward. Full command reference: ${CLI_REPO_URL}
@@ -63,9 +72,10 @@ onward. Full command reference: ${CLI_REPO_URL}
 2. **Never delete data from the current provider.** Verification comes first;
    deletion is the user's decision afterwards.
 3. **Never take a private key into your context.** Not in chat, not in a file
-   you read. Stage 4 is executed by the user in their own terminal.
-4. **Stop and ask at the two gates below.** Exposing a local port (stage 0) and
-   spending (stage 4) are the user's decisions.
+   you read. The key lives in a shell environment; stage 3 is executed by the
+   user in their own terminal.
+4. **Stop and ask at the funding gate (stage 3).** Spending is the user's
+   decision.
 5. **The deposit is the ceiling.** A key that can sign on the account can draw
    against its balance. Advise a wallet kept for this purpose, holding what this
    migration needs and nothing else.
@@ -96,44 +106,20 @@ NETWORK=mainnet        # or: NETWORK=calibration, to rehearse on the testnet
 Rehearsing the whole flow on calibration first is strongly recommended before
 spending real funds.
 
-### Needed now (stages 0-3)
+### Needed now (stages 1-2)
 
 - Node 26 or newer. Hard requirement. Check with \`node --version\`.
 - A CID list, one per line. Blank lines and \`#\` comments are ignored.
 - A trustless gateway that serves deterministic CARs. Stage 1 verifies this.
+- Free disk roughly the size of the data being migrated. Stage 4 stages packed
+  CAR files under \`--car-store\` and deletes each one as soon as every copy is
+  committed onchain.
 
-### Needed before stage 4, not before
-
-- A wallet holding USDFC for storage and FIL for gas. **The user holds this
-  key. You never see it.**
-- A provider id from \`https://pdp.vxb.ai/\${NETWORK}/providers\`.
-
-Do not block stages 0-3 on the wallet. Those stages are free and need no key.
-
-## Stage 0 — settle ingress before computing anything
-
-At submission the storage provider pulls each piece from a public HTTPS origin.
-Private, loopback, and CGNAT addresses are rejected. **Resolve this first.**
-Discovering it after the commitment pass wastes that entire pass, which on a
-large list is hours of work.
-
-| Option | Flag | Requires | Works with |
-| --- | --- | --- | --- |
-| Cloudflare quick tunnel | \`--ingress cloudflared\` | \`cloudflared\` on PATH, no account | any path |
-| Tailscale Funnel or a VPS | \`--ingress funnel\` | you front the port yourself | any path |
-| Shared relay | \`--source-relay <url>\` | a relay base URL | single-asset path only |
-
-\`\`\`bash
-command -v cloudflared
-\`\`\`
-
-The relay is **only** valid for the single-asset path. If stage 2 sends you to
-the multi-asset path, the provider must pull assembled CAR files from your own
-origin, and the relay cannot serve them.
+### Needed before stage 3, not before
 
-**Gate.** If no option is available, stop and tell the user. A tunnel exposes a
-local port to the internet; that is their decision to make, not yours. Do not
-install a tunnel binary on their behalf.
+A wallet holding USDFC for storage and FIL for gas. **The user holds this key.
+You never see it.** Do not block stages 1-2 on the wallet — those stages are
+free and need no key.
 
 ## Stage 1 — confirm the gateway serves deterministic CARs
 
@@ -144,8 +130,8 @@ ${CLI_PACKAGE} probe <one-cid-from-the-list> --gateway https://trustless-gateway
 \`WARN\` means the bytes did not re-hash to the requested CID, or the response was
 not a CAR. That gateway cannot be a source. Try another before continuing; the
 repo's \`docs/sources.md\` lists per-provider notes. Do not proceed on a \`WARN\`:
-the provider re-fetches and recomputes, so a non-deterministic source fails
-every piece.
+stage 4 re-fetches and recomputes, so a non-deterministic source fails every
+piece it touches.
 
 ## Stage 2 — measure, then tell the user what they are in for
 
@@ -160,20 +146,24 @@ probing every CID is affordable; it is the only way to get an exact per-CID
 result at this stage.
 
 The JSON gives you \`input.totalCount\`, \`input.estimatedTotalSizeBytes\`,
-\`sourceGateway.successRate\`, \`sourceGateway.latencyP50Ms\`, per-probe \`bytes\`,
-and a \`persona\` block of recommended flags. It does **not** give you a cost or a
-completion time. Derive those as below; do not invent a formula.
+\`sourceGateway.successRate\`, \`sourceGateway.latencyP50Ms\`, and per-probe
+\`bytes\`. It does **not** give you a cost or a completion time. Derive those as
+below; do not invent a formula.
 
 ### What to report back before going further
 
 - CID count, and the sampled retrieval success rate. If you sampled, say so —
   you know which CIDs failed **in the sample**, not across the whole list. The
-  exact per-CID result comes out of stage 3.
+  exact per-CID result comes out of stage 4.
 - Projected total size, from \`estimatedTotalSizeBytes\`.
-- **Projected wall-clock time.** A rough lower bound for the commitment pass is
-  \`totalCount × latencyP50Ms ÷ concurrency\`. State it as approximate, and say
-  that the provider's pull rate — not this pass — dominates the total for a
-  large run.
+- **Projected wall-clock time.** The run downloads everything once and uploads
+  it once, so a rough lower bound is total size ÷ the slower of download and
+  upload bandwidth. State it as approximate. Upload bandwidth usually
+  dominates on residential connections.
+- The disk requirement: free space roughly the projected total size, freed
+  progressively as pieces commit.
+- Items above ${MAX_ITEM_SIZE_LABEL}. These cannot be migrated — splitting
+  them would change their CID — so hold them out and name them.
 - Estimated storage cost, using the formula below.
 
 ### Cost formula
@@ -206,136 +196,101 @@ alone.
 - A command that runs for hours is working, not hung. Do not kill it. State is
   kept in SQLite and a stopped run resumes where it left off.
 - Run on a machine that stays awake. A sleeping laptop stalls the run.
-- Use the flags \`analyze\` recommends in its \`persona\` block rather than guessing.
 
 Above roughly ${COORDINATION_VOLUME_LABEL}, capacity and timing are worth
 agreeing with providers before starting. That is coordination, not a ceiling:
 mention ${CONTACT_URL} as an option and continue if the user wants to.
 
-### Choosing a packing path
-
-Providers advertise a **minimum piece size** (commonly 1 MiB) and enforce a pull
-limit of roughly ${MAX_ITEM_SIZE_LABEL} raw per item. Read the actual values for
-your chosen provider from \`https://pdp.vxb.ai/\${NETWORK}/providers\`.
-
-The two limits behave differently, and this matters:
-
-- The **minimum** is advisory. \`pdp-submit\` warns and proceeds by default; pass
-  \`--strict-piece-size\` to refuse instead. So small items are a packing
-  efficiency question, not a blocker.
-- The **pull limit** is hard. An item above it cannot be migrated, because
-  splitting it would change its CID. Hold those out and report them.
-
-Evaluate against the per-probe \`bytes\` in the \`analyze\` JSON:
-
-- **Few sampled items below the provider minimum** → single-asset path
-  (the default). Each CID becomes one passthrough item pulled straight from the
-  gateway. No staging disk needed.
-- **A large share below the minimum** → consider the multi-asset path, which
-  batches them into fewer, larger pieces. It needs disk for the assembled CARs
-  and rules out the relay, so it is a trade rather than an obligation. Say which
-  you chose and why.
-
-## Stage 3 — plan
-
-\`\`\`bash
-# single-asset (default)
-${CLI_PACKAGE} plan --cids cids.txt --db migrate.db
-
-# multi-asset, when many items fall below the provider minimum
-${CLI_PACKAGE} plan --cids cids.txt --db migrate.db --no-auto-pack
-${CLI_PACKAGE} pack-cars --db migrate.db --car-store ./cars --pack-target-size 512MiB
-\`\`\`
-
-\`plan\` is insert-only and resumable: re-running it computes only CIDs not yet
-done and never disturbs committed state. This stage produces the **exact**
-per-CID result, including anything unretrievable or \`oversized\`. Report that to
-the user; it supersedes the stage 2 sample.
-
-Check progress at any time with \`${CLI_PACKAGE} status --json\`.
-
-## Stage 4 — funding (the user runs this, not you)
+## Stage 3 — funding (the user runs this, not you)
 
 **Gate. This stage spends money and requires a private key.**
 
 Stop. Give the user these commands to run **in their own terminal**, and ask
-them to paste back only the printed \`dataSetId\`. Do not offer to run these for
-them, and do not accept a key if one is offered — a key pasted into a chat is a
-key in a transcript.
+them to confirm when both succeed. Do not offer to run these for them, and do
+not accept a key if one is offered — a key pasted into a chat is a key in a
+transcript.
 
 \`\`\`bash
 export PRIVATE_KEY=0x...                                  # user's terminal only
 npx filecoin-pin@latest payments setup --auto --network "$NETWORK"
 npx filecoin-pin@latest payments status --network "$NETWORK"
-${CLI_PACKAGE} create-data-set --provider-id <id> --network "$NETWORK"
-\`\`\`
-
-\`create-data-set\` reverts if the USDFC deposit or the operator approval is
-insufficient. Remind the user that the deposited amount is the ceiling on
-everything downstream.
-
-**Resume only when the user confirms funding succeeded and gives you the
-\`dataSetId\`.** Submission in stage 5 also signs, so it needs the same key
-available in the environment where it runs. If the user wants to keep the key
-off your machine entirely, stage 5 is theirs to run too, and you read back the
-report from stage 6.
-
-## Stage 5 — submit
-
-Two processes. The pull source must stay running for the whole submission.
-
-\`\`\`bash
-# Start in the background and read its log until it prints the public URL.
-${CLI_PACKAGE} redirect-serve --db migrate.db --port 4322 --ingress cloudflared
-# logs: "cloudflared ingress: ready at https://<words>.trycloudflare.com"
 \`\`\`
 
-Extract that HTTPS origin from the log output and pass it as \`--source-base\`.
-It is the **origin only** — scheme and host, no path. Then:
+No data set needs to be provisioned by hand: stage 4 creates one per provider
+copy on its first onchain commit, with IPFS indexing enabled. Remind the user
+that the deposited amount is the ceiling on everything downstream.
 
-\`\`\`bash
-${CLI_PACKAGE} pdp-submit --db migrate.db --data-set-id <id> \\
-  --source-base https://<public-host> --network "$NETWORK"
-\`\`\`
+**Resume only when the user confirms funding succeeded.** Stage 4 signs with
+the same key, so it must run in a shell where \`PRIVATE_KEY\` is exported. If
+the user wants to keep the key off your machine entirely, stage 4 is theirs to
+run too, and you read back the summary it prints.
 
-With a relay instead of your own ingress (single-asset path only):
+## Stage 4 — upload
 
-\`\`\`bash
-${CLI_PACKAGE} pdp-submit --db migrate.db --data-set-id <id> \\
-  --source-relay <relay-base> --network "$NETWORK"
-\`\`\`
-
-\`pdp-submit\` is resumable and will not double-submit. It pauses when the network
-base fee is above \`--max-base-fee\`; that is congestion backoff, not a failure.
-Check with \`${CLI_PACKAGE} gas --network "$NETWORK"\`.
-
-## Stage 6 — verify
+One command owns the rest of the migration: it downloads each CID, packs
+multi-root CAR pieces (up to ~1000 MiB each), streams every piece straight to
+the primary provider, has the second provider copy from the first, and commits
+the adds onchain in batches of up to 40 pieces per transaction. Providers are
+chosen automatically; the batching timer commits early rather than risk a
+provider expiring an uncommitted piece.
 
 \`\`\`bash
-${CLI_PACKAGE} report --db migrate.db --data-set-id <id> --network "$NETWORK" --json
+${CLI_PACKAGE} upload --cids cids.txt --db migrate.db --car-store ./cars --network "$NETWORK"
 \`\`\`
 
-This reconciles local state against the pieces the data set actually holds on
-chain. Hand the user the report, the data set id, and the path to \`migrate.db\`.
-
-Tell them explicitly: **check retrieval of a few of their own CIDs, and keep the
-old pinning plan until they have.** Verification is theirs to accept, not yours
-to declare.
+- The run is resumable: re-running the same command continues where it
+  stopped, never re-uploads what is already committed, and never
+  double-commits.
+- Staged CARs under \`./cars\` are deleted during the run as each piece's
+  copies are all committed. Do not delete them by hand mid-run.
+- \`collected:\` lines mean a provider expired a piece before it was committed;
+  the run re-uploads it automatically and tightens its timing for that
+  provider. Informational, not a failure.
+- Check progress from another shell at any time with
+  \`${CLI_PACKAGE} status --db migrate.db --json\`.
+
+The final JSON summary lists, per provider, the data set id, the counts of
+committed and failed pieces, and how many staged CARs were cleaned up. Save it;
+stage 5 uses the data set ids.
+
+## Stage 5 — verify
+
+Verification is against the chain and real retrievals, not the tool's own
+bookkeeping.
+
+1. **Onchain.** Open each data set from the stage 4 summary at
+   \`https://pdp.vxb.ai/\${NETWORK}/dataset/<dataSetId>\` and confirm it is live
+   and holds the expected pieces. There is one data set per copy, so with the
+   default ${COPIES} copies there are ${COPIES} ids.
+2. **Retrieval.** Fetch a handful of the user's original CIDs — spread across
+   the list, not just the first few — and confirm the bytes come back. IPFS
+   indexing announces migrated CIDs to the public IPFS network (via IPNI), so
+   after indexing completes they resolve through ordinary IPFS gateways and
+   \`https://cid.contact/routing/v1/providers/<cid>\` lists the new providers.
+   Indexing lag of minutes to hours after commit is normal.
+3. **Accounting.** Compare committed piece counts in the summary against the
+   CID count, and name every CID that was held out or failed.
+
+Hand the user the summary, the data set ids, and the path to \`migrate.db\`.
+Tell them explicitly: **check retrieval of a few of their own CIDs, and keep
+the old pinning plan until they have.** Verification is theirs to accept, not
+yours to declare.
 
 ## Failure modes
 
 | Symptom | Meaning | Action |
 | --- | --- | --- |
 | \`probe\` reports \`WARN\` | gateway does not serve deterministic CARs | pick another gateway |
-| \`plan\` reports \`oversized\` | padded size exceeds the aggregate budget | hold that CID out, report it |
-| \`below provider min piece size\` warning | items under the advertised minimum | expected; it proceeds. Use the multi-asset path only to pack more efficiently |
-| provider rejects the pull | \`--source-base\` has a path, or is not a public IP | pass origin only, recheck ingress |
-| submission pauses on \`spike\` | base fee above the gate | wait it out; this is expected |
+| \`exceeds ... upload cap; not migrated\` | item larger than ${MAX_ITEM_SIZE_LABEL} | hold that CID out, report it |
+| \`collected:\` during upload | provider expired an uncommitted piece | none — it re-uploads and adapts automatically |
+| \`warn: secondary ... failed to pull\`, persistent | that provider cannot fetch from the primary | re-run; if it persists, pin different providers with \`--provider-id\` (ids at \`https://pdp.vxb.ai/\${NETWORK}/providers\`) |
+| \`batch left add_unconfirmed\` | an onchain add's outcome is unknown | re-run the same command; it reconciles against the provider before retrying |
 | \`set PRIVATE_KEY\` error | key not in that shell's environment | the user exports it in their own terminal |
-| aggregate stuck \`failed\` | see the repo's recovery commands | \`reset-failed-aggregates\` |
+| disk fills during the run | staged CARs plus data exceed free space | free space or use a larger disk for \`--car-store\`; committed pieces are already cleaned up |
 
-One unretrievable item fails everything batched with it, which is why stages 2
-and 3 validate retrievability before anything is submitted.
+One unretrievable item fails the piece it was packed into, which is why stages
+1-2 validate retrievability before anything is uploaded, and why the run names
+every affected CID rather than dropping it.
 
 ## Links
 
diff --git a/src/app/ipfs2filecoin/data/steps.ts b/src/app/ipfs2filecoin/data/steps.ts
index eb5b81b9..cb576c16 100644
--- a/src/app/ipfs2filecoin/data/steps.ts
+++ b/src/app/ipfs2filecoin/data/steps.ts
@@ -21,6 +21,6 @@ export const steps = [
     number: '04',
     title: 'Migrate',
     description:
-      'Storage providers pull the data and commit it onchain. You get a receipt, explorer links, and a manifest of everything that landed.',
+      'Your machine streams the data straight to two storage providers, and the adds are committed onchain in batches. You get explorer links and a summary of everything that landed.',
   },
 ] as const

From 4b579661e0f26060ddd90b2180889878483df283 Mon Sep 17 00:00:00 2001
From: G <gmoran651@gmail.com>
Date: Fri, 14 Aug 2026 20:20:02 +0100
Subject: [PATCH 08/26] fix(ipfs2filecoin): design review follow-ups for the
 landing page (#350)

* fix(faq): make accordion dividers and chevrons background-aware

Faq hardcoded divide-white/20, and Accordion hardcoded text-zinc-200 on the
chevron and text-zinc-300 on the body. All three assume a dark background, which
held while the homepage was the only consumer since it mounts the FAQ on a dark
section. On a light or gray section the dividers and chevrons are effectively
invisible.

They now use --color-border-base, --color-text-base and --color-paragraph-text,
which flip off the .light-section / .dark-section class that Section already
sets, so no isDark branching is needed. Faq keeps useBackground purely for
prose-invert.

Moving the colour onto the item rather than the parent also fixes the first
divider. divide-* targets every child after the first, so item one's border was
falling back to currentColor and rendering at full brightness on dark.

The homepage FAQ shifts slightly as a result: chevron zinc-200 to zinc-50, body
zinc-300 to zinc-400, both now matching the tokens used everywhere else. That
page is worth a look alongside this one.

Review: @filipagr
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

* fix(ipfs2filecoin): correct layout and type hierarchy from design review

Follow-ups from a walkthrough of the page with Filipa Ribeiro.

Alignment and spacing

- "Estimate your deposit" and the hero sat 60px inset from their siblings,
  because PageSection already wraps children in a Container and page.tsx nested
  a second one, doubling the horizontal padding. Removed both, plus the
  now-unused import.
- The Unit and Funded-for selects had the native arrow jammed against the border
  with a cavern between it and the value. A local SelectField goes
  appearance-none with a Phosphor caret inset to match the field's text, and the
  grid drops from three equal columns to 2fr/1fr/2fr so Unit is no longer a
  full-width field holding three characters.
- "What this does not do" is constrained to max-w-5xl; lines ran past 15 words
  at desktop.

Type

- Both tables move off text-sm to text-base, with service names at text-lg.
- Monospace figures dropped for the body font with tabular-nums. The reported
  problem was numbers appearing larger than the names beside them, which was a
  typeface illusion rather than a size difference, so matching the typeface
  removes it at the root while tabular-nums keeps the columns aligned. Flagging
  this one as the most debatable call in the batch.
- The highlighted Filecoin row carries weight instead of a marginally darker
  grey, which read as a mistake rather than emphasis.

Visual interest

- How it works renders 2x2 rather than 3-up with an orphaned fourth, and step
  numbers sit above each title in the accent colour. This needs a new StepList
  component because the shared Card types title as a plain string, so the number
  could only ever be inlined as "01. Hand over the list".
- Reason cards take icons, following how agents/ and warm-storage-service/
  already pass Phosphor icons to Card.
- The agent column takes two thirds and "Talk to us" becomes a one third
  call-out, giving the path with more to say more room.

The external-link arrow beside Filebase and Pinata is tightened with a local
override. It is sized for button text inside ExternalTextLink in ui-filecoin, so
the real fix belongs upstream; this is a commented stopgap.

Still open from the review and deliberately not attempted here: table whitespace
now that the type sizes are settled, the hero background treatment, and the
optional illustration beside the agent heading.

Review: @filipagr
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

* feat(ipfs2filecoin): turn a checked CID list into something actionable

parseCidList already validated, deduped and stripped gateway prefixes, but the
verdict box reported only a count. The successful path gave you nothing to act
on, so the top of the page had no purpose: you still assembled cids.txt by hand.
The prompt was in fact offered only on the over-cap branch, so the one outcome
that succeeded was the one outcome with no output.

A checked list now produces the agent prompt with your own CIDs inlined, via
buildAgentPrompt, plus a cids.txt download of the cleaned and deduped list.
AGENT_PROMPT stays as the fallback for the empty and over-cap cases, where
pointing at a file is the right shape rather than inlining hundreds of lines.

The instruction to "estimate what they cost to store below" is replaced. A check
reads the CIDs and not the bytes behind them, so it cannot price anything on its
own, and implying otherwise was the most confusing part of the flow. Resolving a
CID to its actual size needs backend capability and is a separate conversation.

Hero polish in the same component: "one per line" sits beside the label in the
accent colour rather than surfacing only after a failed check, the button is
centred, the empty textarea is shorter, and the free-check facts read as a
scannable list instead of fine print. Copy prompt demotes from a full-width
button to an icon in the code block's corner.

Verified against deliberately messy input: a bare CID, a gateway URL, a
duplicate and a junk line resolve to three unique CIDs, with the URL prefix
stripped and both the skipped line and the duplicate reported.

Review: @filipagr
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

* chore: ignore local agent and working files

CLAUDE.md is per-machine guidance for Claude Code, and todo.md is the working
list of design review actions for /ipfs2filecoin. Neither belongs in the repo.

Note that this keeps todo.md local, so it does not travel to reviewers via git.

Review: @filipagr
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

* feat(ipfs2filecoin): rework the CID checker into one input surface

Fold the label, textarea and action into a single bordered panel with a live "X of Y lines are CIDs" readout and a Cmd/Ctrl+Enter shortcut. Move the verdict into its own CidListVerdict component with an icon per outcome, and extract pluralize so the readout and verdict agree.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* fix(ipfs2filecoin): split provider from tier and make the price table responsive

Give each pricing row a detail sub-line so the provider is what you compare on and the plan tier stays secondary, and key rows by provider plus tier now that two Pinata tiers share a name. On mobile the three columns do not fit, so each provider becomes a stacked card; the full table returns at md.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* fix(ipfs2filecoin): pair the deposit estimator with the table, refine hero and type

Move the estimator into a companion card beside the comparison table (the table is the market rate, the card prices it for your data), with the two inputs side by side and a compact stacked result that fits the narrow column. Add a faint brand glow along the bottom of the hero, step the reason-card and agent-warning copy down a size, and render How it works four across on desktop.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* fix(ipfs2filecoin): derive the $2.50 rate from USD_PER_TIB_MONTH_PER_COPY

The rate footnote, one reason card, and the SEO description each restated
$2.50 as a literal, so they could silently drift from the comparison table
and estimator, which already derive from the constant.

---------

Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
Co-authored-by: filipagr <filipagoncalvesribeiro@gmail.com>
Co-authored-by: Russell Dempsey <1173416+SgtPooki@users.noreply.github.com>
---
 .gitignore                                    |   2 +
 .../ipfs2filecoin/components/AgentPrompt.tsx  |  38 ++-
 .../components/CidListChecker.tsx             | 295 +++++++++---------
 .../components/CidListVerdict.tsx             | 220 +++++++++++++
 .../components/ComparisonTable.tsx            |  99 +++++-
 .../components/CostEstimator.tsx              | 242 ++++++++------
 src/app/ipfs2filecoin/components/StepList.tsx |  36 +++
 src/app/ipfs2filecoin/constants/migration.ts  |  14 +
 src/app/ipfs2filecoin/constants/seo.ts        |   6 +-
 .../ipfs2filecoin/data/pricing-comparison.ts  |  27 +-
 src/app/ipfs2filecoin/data/reasons.ts         |  17 +-
 src/app/ipfs2filecoin/page.tsx                | 219 ++++++++-----
 src/app/ipfs2filecoin/utils/pluralize.ts      |   8 +
 src/components/Accordion.tsx                  |   6 +-
 src/components/Faq.tsx                        |   2 +-
 15 files changed, 883 insertions(+), 348 deletions(-)
 create mode 100644 src/app/ipfs2filecoin/components/CidListVerdict.tsx
 create mode 100644 src/app/ipfs2filecoin/components/StepList.tsx
 create mode 100644 src/app/ipfs2filecoin/utils/pluralize.ts

diff --git a/.gitignore b/.gitignore
index 4fc5fa81..fc1263e7 100644
--- a/.gitignore
+++ b/.gitignore
@@ -42,3 +42,5 @@ next-env.d.ts
 
 # Local test fixtures, not part of the site
 dapper-labs-nba-topshots-cids.txt
+CLAUDE.md
+todo.md
diff --git a/src/app/ipfs2filecoin/components/AgentPrompt.tsx b/src/app/ipfs2filecoin/components/AgentPrompt.tsx
index 1569d9f6..c83bd1a9 100644
--- a/src/app/ipfs2filecoin/components/AgentPrompt.tsx
+++ b/src/app/ipfs2filecoin/components/AgentPrompt.tsx
@@ -1,38 +1,54 @@
 'use client'
 
-import { Button } from '@filecoin-foundation/ui-filecoin/Button'
+import { Icon } from '@filecoin-foundation/ui-filecoin/Icon'
+import { CheckIcon, CopyIcon } from '@phosphor-icons/react/dist/ssr'
 import { usePlausible } from 'next-plausible'
 
 import { useCopyToClipboard } from '@/hooks/use-copy-to-clipboard'
 
-import { AGENT_PROMPT, PLAUSIBLE_EVENTS } from '../constants/migration'
+import { buildAgentPrompt, PLAUSIBLE_EVENTS } from '../constants/migration'
 
 type AgentPromptProps = {
   /** Where on the page the prompt was copied from, so the two spots stay distinguishable. */
   source: 'verdict' | 'agent-door'
+  /**
+   * The user's checked list. When present it is inlined into the prompt so the
+   * copied line carries the actual CIDs instead of pointing at a cids.txt the
+   * user would have to assemble themselves.
+   */
+  cids?: ReadonlyArray<string>
 }
 
-export function AgentPrompt({ source }: AgentPromptProps) {
+export function AgentPrompt({ source, cids }: AgentPromptProps) {
   const { copy, isCopied } = useCopyToClipboard()
   const plausible = usePlausible()
 
+  const prompt = buildAgentPrompt(cids)
+
   async function handleCopy() {
-    const copied = await copy(AGENT_PROMPT)
+    const copied = await copy(prompt)
 
     if (copied) {
-      plausible(PLAUSIBLE_EVENTS.promptCopied, { props: { source } })
+      plausible(PLAUSIBLE_EVENTS.promptCopied, {
+        props: { source, cidCount: cids?.length ?? 0 },
+      })
     }
   }
 
   return (
-    <div className="space-y-3">
-      <code className="block rounded-lg border border-(--color-border-muted) bg-(--color-card-background) p-3 font-mono text-(--color-paragraph-text) text-xs/relaxed">
-        {AGENT_PROMPT}
+    <div className="relative">
+      <code className="block max-h-48 overflow-y-auto whitespace-pre-wrap rounded-lg border border-(--color-border-muted) bg-(--color-card-background) p-3 pr-12 font-mono text-(--color-paragraph-text) text-xs/relaxed">
+        {prompt}
       </code>
 
-      <Button type="button" variant="ghost" onClick={handleCopy}>
-        {isCopied ? 'Copied' : 'Copy prompt'}
-      </Button>
+      <button
+        type="button"
+        onClick={handleCopy}
+        aria-label={isCopied ? 'Prompt copied' : 'Copy prompt'}
+        className="focus-visible:brand-outline absolute top-2 right-2 rounded-md border border-(--color-border-muted) bg-(--color-card-background) p-1.5 text-(--color-paragraph-text) hover:text-(--color-text-base)"
+      >
+        <Icon component={isCopied ? CheckIcon : CopyIcon} size={16} />
+      </button>
 
       <span aria-live="polite" className="sr-only">
         {isCopied ? 'Prompt copied to clipboard' : ''}
diff --git a/src/app/ipfs2filecoin/components/CidListChecker.tsx b/src/app/ipfs2filecoin/components/CidListChecker.tsx
index 14e25136..e800d1e7 100644
--- a/src/app/ipfs2filecoin/components/CidListChecker.tsx
+++ b/src/app/ipfs2filecoin/components/CidListChecker.tsx
@@ -1,75 +1,106 @@
 'use client'
 
 import { Button } from '@filecoin-foundation/ui-filecoin/Button'
-import { SmartTextLink } from '@filecoin-foundation/ui-filecoin/TextLink/SmartTextLink'
-import { Field, Label, Textarea } from '@headlessui/react'
+import { Description, Field, Label, Textarea } from '@headlessui/react'
 import { usePlausible } from 'next-plausible'
-import { useId, useState } from 'react'
+import { useEffect, useMemo, useRef, useState } from 'react'
 
-import { PATHS } from '@/constants/paths'
-
-import { AgentPrompt } from './AgentPrompt'
+import { CidListVerdict, getVerdict, type Verdict } from './CidListVerdict'
 import {
   BROWSER_CHECK_ITEM_CAP,
   MAX_ITEM_SIZE_LABEL,
   PLAUSIBLE_EVENTS,
 } from '../constants/migration'
-import { type CidListSummary, parseCidList } from '../utils/parse-cid-list'
-
-const PLACEHOLDER = [
-  'bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi',
-  'bafkreieq5jui4j25lacwomsqgjeswwl3y5zcdrresptwgmfylxo2depppq',
-  'QmYwAPJzv5CZsnA625s3Xf2nemtYgPpHdWEz79ojWnPbdG',
-].join('\n')
-
-type Verdict =
-  | { kind: 'empty' }
-  | { kind: 'unreadable'; summary: CidListSummary }
-  | { kind: 'ok'; summary: CidListSummary }
-  | { kind: 'over-cap'; summary: CidListSummary }
-
-function getVerdict(summary: CidListSummary): Verdict {
-  if (summary.totalLines === 0) {
-    return { kind: 'empty' }
-  }
-  if (summary.uniqueCids.length === 0) {
-    return { kind: 'unreadable', summary }
-  }
-  if (summary.uniqueCids.length > BROWSER_CHECK_ITEM_CAP) {
-    return { kind: 'over-cap', summary }
-  }
-  return { kind: 'ok', summary }
-}
+import { parseCidList } from '../utils/parse-cid-list'
+import { pluralize } from '../utils/pluralize'
+
+/**
+ * One line, not three. Three full CIDs fill the field edge to edge and read as
+ * a list already pasted; a single dim example reads as the prompt it is. The
+ * field keeps its height from `min-h`, so it still invites a list.
+ */
+const PLACEHOLDER =
+  'bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi'
+
+/** The free-check facts, broken out so they scan as features rather than fine print. */
+const CHECK_FACTS = [
+  'Free, no wallet required',
+  `Up to ${BROWSER_CHECK_ITEM_CAP.toLocaleString()} items`,
+  `${MAX_ITEM_SIZE_LABEL} per item`,
+  'Runs in your browser',
+  'Never sent anywhere',
+]
+
+/**
+ * The submit shortcut accepts Cmd or Ctrl, so the chip has to name whichever
+ * one this visitor actually has. Resolved after mount rather than rendered on
+ * the server, which has no way to know: `null` until then keeps the first
+ * client render identical to the server's and avoids a hydration mismatch.
+ */
+function useShortcutLabel() {
+  const [label, setLabel] = useState<string | null>(null)
+
+  useEffect(() => {
+    const isApple = /mac|iphone|ipad|ipod/i.test(
+      navigator.platform || navigator.userAgent,
+    )
+    setLabel(isApple ? '⌘ ↵' : 'Ctrl ↵')
+  }, [])
 
-function pluralize(count: number, singular: string, plural = `${singular}s`) {
-  return count === 1 ? singular : plural
+  return label
 }
 
-function buildNotes({ invalidCount, duplicateCount }: CidListSummary) {
-  const notes: Array<string> = []
-
-  if (invalidCount > 0) {
-    notes.push(
-      `${invalidCount} ${pluralize(invalidCount, 'line')} could not be read as a CID and will be skipped`,
-    )
+/**
+ * What the parser makes of the list as it is typed, so the button confirms a
+ * result the user can already see rather than being the first sign of one.
+ */
+function describeProgress(
+  totalLines: number,
+  recognizedCount: number,
+): string | null {
+  if (totalLines === 0) {
+    return null
   }
-  if (duplicateCount > 0) {
-    notes.push(
-      `${duplicateCount} ${pluralize(duplicateCount, 'duplicate')} removed`,
-    )
+  if (recognizedCount === 0) {
+    return 'No CIDs recognized yet'
+  }
+  if (recognizedCount === totalLines) {
+    return `${recognizedCount.toLocaleString()} ${pluralize(recognizedCount, 'CID')}`
   }
 
-  return notes.length > 0 ? `${notes.join('. ')}.` : null
+  return `${recognizedCount.toLocaleString()} of ${totalLines.toLocaleString()} lines are CIDs`
 }
 
 export function CidListChecker() {
-  const inputId = useId()
   const plausible = usePlausible()
   const [value, setValue] = useState('')
   const [verdict, setVerdict] = useState<Verdict | null>(null)
+  const verdictRef = useRef<HTMLDivElement>(null)
+
+  const shortcutLabel = useShortcutLabel()
+  const summary = useMemo(() => parseCidList(value), [value])
+  const hasInput = value.trim().length > 0
+  const progress = describeProgress(
+    summary.totalLines,
+    summary.uniqueCids.length,
+  )
+
+  /**
+   * The panel lands below the fold on a laptop, so a check would otherwise look
+   * like it did nothing. Aligning its bottom edge reveals the whole result while
+   * leaving the list itself in view, which `nearest` does not: for an element
+   * taller than the gap below it, the minimum scroll is barely any scroll.
+   */
+  useEffect(() => {
+    if (verdict) {
+      verdictRef.current?.scrollIntoView({
+        block: 'end',
+        behavior: 'smooth',
+      })
+    }
+  }, [verdict])
 
   function handleCheck() {
-    const summary = parseCidList(value)
     const next = getVerdict(summary)
     setVerdict(next)
 
@@ -88,104 +119,88 @@ export function CidListChecker() {
   return (
     <div className="mx-auto w-full max-w-2xl text-left">
       <Field>
-        <Label
-          htmlFor={inputId}
-          className="mb-2 inline-block text-(--color-paragraph-text) text-sm"
-        >
-          Paste the CIDs you want to move
-        </Label>
-        <Textarea
-          id={inputId}
-          value={value}
-          spellCheck={false}
-          rows={5}
-          placeholder={PLACEHOLDER}
-          onChange={(event) => setValue(event.target.value)}
-          className="focus:brand-outline block min-h-32 w-full resize-y rounded-lg border border-(--input-border-color) p-3 font-mono text-(--color-text-base) text-sm placeholder:text-(--input-placeholder-color)"
-        />
+        {/*
+          One enclosed surface rather than a label, a field and an action loose
+          on the page: the border is what says "this is the thing you use". The
+          header and footer bars carry the supporting text, so the input itself
+          stays uninterrupted.
+        */}
+        <div className="overflow-hidden rounded-xl border border-(--color-border-muted) bg-(--color-card-background) transition-colors has-[textarea:focus]:border-brand-600 has-[textarea:focus]:ring-1 has-[textarea:focus]:ring-brand-600">
+          <div className="flex flex-wrap items-baseline justify-between gap-x-4 gap-y-1 px-4 pt-3">
+            <Label className="font-medium text-(--color-text-base) text-sm">
+              Paste the CIDs you want to move
+            </Label>
+            {progress && (
+              <span
+                aria-live="polite"
+                className="text-(--color-paragraph-text) text-xs tabular-nums"
+              >
+                {progress}
+              </span>
+            )}
+          </div>
+
+          {/*
+            One entry per visual row: soft wrapping would render a long gateway
+            URL as two rows and contradict the line count in the header, so long
+            lines scroll sideways instead, the way a code editor holds them.
+          */}
+          <Textarea
+            value={value}
+            spellCheck={false}
+            wrap="off"
+            placeholder={PLACEHOLDER}
+            onChange={(event) => setValue(event.target.value)}
+            onKeyDown={(event) => {
+              if (event.key === 'Enter' && (event.metaKey || event.ctrlKey)) {
+                handleCheck()
+              }
+            }}
+            className="mt-2 block max-h-64 min-h-16 w-full resize-none overflow-auto whitespace-pre field-sizing-content border-0 bg-transparent px-4 pb-3 font-mono text-(--color-text-base) text-sm/relaxed placeholder:text-(--color-paragraph-text-subtle) focus:outline-none"
+          />
+
+          <div className="flex flex-col items-stretch gap-3 border-(--color-border-muted) border-t px-4 py-3 sm:flex-row sm:items-center sm:justify-between sm:gap-x-4">
+            <Description className="text-(--color-paragraph-text) text-xs">
+              One per line. Gateway URLs are fine, the prefix is stripped.
+            </Description>
+            <Button
+              type="button"
+              variant="primary"
+              size="compact"
+              onClick={handleCheck}
+              disabled={!hasInput}
+              className="w-full sm:w-auto"
+            >
+              Check my list
+              {/* Pointer-only: a shortcut is noise without a modifier key. */}
+              {shortcutLabel && (
+                <kbd className="ml-2 hidden rounded border border-(--color-border-base) px-1 py-px font-sans text-(--color-paragraph-text) text-xs/none sm:inline">
+                  {shortcutLabel}
+                </kbd>
+              )}
+            </Button>
+          </div>
+        </div>
       </Field>
 
-      <div className="mt-3">
-        <Button type="button" variant="primary" onClick={handleCheck}>
-          Check my list
-        </Button>
-      </div>
-
+      {/* Directly under the control that produced it: the reassurance below is
+          what you read before deciding, not between a question and its answer. */}
       {verdict && (
-        <div
-          role="status"
-          aria-live="polite"
-          className="mt-4 rounded-lg border border-(--color-border-muted) bg-(--color-card-background) p-4 text-(--color-paragraph-text) text-sm"
-        >
-          <VerdictMessage verdict={verdict} />
+        <div ref={verdictRef} className="mt-3 scroll-mb-6">
+          <CidListVerdict verdict={verdict} />
         </div>
       )}
 
-      <p className="mt-3 text-(--color-paragraph-text) text-sm/relaxed">
-        Checking is free and needs no wallet, up to{' '}
-        {BROWSER_CHECK_ITEM_CAP.toLocaleString()} items and{' '}
-        {MAX_ITEM_SIZE_LABEL} per item. It runs entirely in your browser, so
-        your list is never sent anywhere. Past that,{' '}
-        <SmartTextLink href={`${PATHS.IPFS_TO_FILECOIN.path}#agent`}>
-          hand the migration to your agent
-        </SmartTextLink>
-        .
-      </p>
+      <ul className="mt-3 flex flex-wrap items-center justify-center gap-x-2 gap-y-1 text-(--color-paragraph-text) text-xs">
+        {CHECK_FACTS.map((fact) => (
+          <li
+            key={fact}
+            className="flex items-center gap-2 before:text-(--color-border-base) before:content-['•'] first:before:hidden"
+          >
+            {fact}
+          </li>
+        ))}
+      </ul>
     </div>
   )
 }
-
-function VerdictMessage({ verdict }: { verdict: Verdict }) {
-  if (verdict.kind === 'empty') {
-    return (
-      <p>
-        <strong className="font-medium text-(--color-text-base)">
-          Nothing to check yet.
-        </strong>{' '}
-        Paste one CID per line.
-      </p>
-    )
-  }
-
-  const { summary } = verdict
-  const notes = buildNotes(summary)
-  const count = summary.uniqueCids.length
-
-  if (verdict.kind === 'unreadable') {
-    return (
-      <p>
-        <strong className="font-medium text-(--color-text-base)">
-          None of these look like CIDs.
-        </strong>{' '}
-        {summary.totalLines} {pluralize(summary.totalLines, 'line')} could not
-        be read as a CID. Check for extra text, URLs, or commas.
-      </p>
-    )
-  }
-
-  if (verdict.kind === 'over-cap') {
-    return (
-      <div className="space-y-3">
-        <p>
-          <strong className="font-medium text-(--color-text-base)">
-            {count.toLocaleString()} CIDs is more than a browser check handles.
-          </strong>{' '}
-          The limit here is {BROWSER_CHECK_ITEM_CAP.toLocaleString()} items.
-          Hand the list to your agent instead: no cap, and it resumes if it
-          stops. {notes}
-        </p>
-        <AgentPrompt source="verdict" />
-      </div>
-    )
-  }
-
-  return (
-    <p>
-      <strong className="font-medium text-(--color-text-base)">
-        {count.toLocaleString()} {pluralize(count, 'CID')} ready to check.
-      </strong>{' '}
-      Estimate what they cost to store below, then hand the list to your agent
-      to fetch, measure, and migrate them. {notes}
-    </p>
-  )
-}
diff --git a/src/app/ipfs2filecoin/components/CidListVerdict.tsx b/src/app/ipfs2filecoin/components/CidListVerdict.tsx
new file mode 100644
index 00000000..c760de4a
--- /dev/null
+++ b/src/app/ipfs2filecoin/components/CidListVerdict.tsx
@@ -0,0 +1,220 @@
+'use client'
+
+import { Icon } from '@filecoin-foundation/ui-filecoin/Icon'
+import { SmartTextLink } from '@filecoin-foundation/ui-filecoin/TextLink/SmartTextLink'
+import {
+  CheckCircleIcon,
+  InfoIcon,
+  WarningCircleIcon,
+} from '@phosphor-icons/react/dist/ssr'
+
+import { PATHS } from '@/constants/paths'
+
+import { AgentPrompt } from './AgentPrompt'
+import { BROWSER_CHECK_ITEM_CAP } from '../constants/migration'
+import type { CidListSummary } from '../utils/parse-cid-list'
+import { pluralize } from '../utils/pluralize'
+
+export type Verdict =
+  | { kind: 'empty' }
+  | { kind: 'unreadable'; summary: CidListSummary }
+  | { kind: 'ok'; summary: CidListSummary }
+  | { kind: 'over-cap'; summary: CidListSummary }
+
+export function getVerdict(summary: CidListSummary): Verdict {
+  if (summary.totalLines === 0) {
+    return { kind: 'empty' }
+  }
+  if (summary.uniqueCids.length === 0) {
+    return { kind: 'unreadable', summary }
+  }
+  if (summary.uniqueCids.length > BROWSER_CHECK_ITEM_CAP) {
+    return { kind: 'over-cap', summary }
+  }
+  return { kind: 'ok', summary }
+}
+
+/**
+ * Tone per outcome, in tokens rather than literals so the panel survives being
+ * mounted on a light section. Over-cap is informational, not a failure: the
+ * list is fine, it just routes to the agent instead of the browser.
+ */
+const TONE = {
+  empty: { icon: InfoIcon, className: 'text-(--color-paragraph-text)' },
+  unreadable: {
+    icon: WarningCircleIcon,
+    className: 'text-(--color-brand-error)',
+  },
+  'over-cap': { icon: InfoIcon, className: 'text-(--color-paragraph-text)' },
+  ok: { icon: CheckCircleIcon, className: 'text-(--color-icon-success)' },
+} as const
+
+/**
+ * What the parser changed about the list. Kept as separate lines rather than a
+ * run-on sentence, so two adjustments do not read as one.
+ */
+function buildAdjustments({ invalidCount, duplicateCount }: CidListSummary) {
+  const adjustments: Array<string> = []
+
+  if (invalidCount > 0) {
+    adjustments.push(
+      `${invalidCount} ${pluralize(invalidCount, 'line')} skipped, not readable as a CID`,
+    )
+  }
+  if (duplicateCount > 0) {
+    adjustments.push(
+      `${duplicateCount} ${pluralize(duplicateCount, 'duplicate')} removed`,
+    )
+  }
+
+  return adjustments
+}
+
+export function CidListVerdict({ verdict }: { verdict: Verdict }) {
+  const tone = TONE[verdict.kind]
+
+  return (
+    <div
+      role="status"
+      aria-live="polite"
+      className="flex items-start gap-2.5 rounded-xl border border-(--color-border-muted) bg-(--color-card-background) p-4"
+    >
+      <span className={`shrink-0 ${tone.className}`}>
+        <Icon component={tone.icon} size={16} />
+      </span>
+      <div className="-mt-0.5 min-w-0 flex-1 space-y-3 text-(--color-paragraph-text) text-sm/relaxed">
+        <VerdictBody verdict={verdict} />
+      </div>
+    </div>
+  )
+}
+
+function Headline({ children }: { children: React.ReactNode }) {
+  return (
+    <p className="font-medium text-(--color-text-base) text-sm tabular-nums">
+      {children}
+    </p>
+  )
+}
+
+function Adjustments({ summary }: { summary: CidListSummary }) {
+  const adjustments = buildAdjustments(summary)
+
+  if (adjustments.length === 0) {
+    return null
+  }
+
+  return (
+    <ul className="space-y-1 text-(--color-paragraph-text) text-xs">
+      {adjustments.map((adjustment) => (
+        <li key={adjustment} className="tabular-nums">
+          {adjustment}
+        </li>
+      ))}
+    </ul>
+  )
+}
+
+/**
+ * Offers the cleaned, deduped list as the cids.txt the runbook expects. Always
+ * used inside a sentence that says what the file is for: on its own, the
+ * filename tells you nothing about why you would want it.
+ */
+function DownloadCidsLink({
+  cids,
+  label,
+}: {
+  cids: ReadonlyArray<string>
+  label: string
+}) {
+  const href = `data:text/plain;charset=utf-8,${encodeURIComponent(`${cids.join('\n')}\n`)}`
+
+  return (
+    <a
+      href={href}
+      download="cids.txt"
+      className="text-link focus-visible:brand-outline"
+    >
+      {label}
+    </a>
+  )
+}
+
+function VerdictBody({ verdict }: { verdict: Verdict }) {
+  if (verdict.kind === 'empty') {
+    return (
+      <>
+        <Headline>Nothing to check yet</Headline>
+        <p>Paste one CID per line to get started.</p>
+      </>
+    )
+  }
+
+  const { summary } = verdict
+  const count = summary.uniqueCids.length
+
+  if (verdict.kind === 'unreadable') {
+    return (
+      <>
+        <Headline>None of these look like CIDs</Headline>
+        <p className="tabular-nums">
+          {summary.totalLines} {pluralize(summary.totalLines, 'line')} could not
+          be read as a CID. Check for extra text, commas, or a URL that is not a
+          gateway path.
+        </p>
+      </>
+    )
+  }
+
+  if (verdict.kind === 'over-cap') {
+    return (
+      <>
+        <Headline>
+          {count.toLocaleString()} CIDs is more than a browser check handles
+        </Headline>
+        <Adjustments summary={summary} />
+        <p>
+          The limit here is {BROWSER_CHECK_ITEM_CAP.toLocaleString()} items.
+          Hand the list to your agent instead: no cap, and it resumes if it
+          stops.
+        </p>
+        <AgentPrompt source="verdict" />
+        <p className="text-(--color-paragraph-text) text-xs">
+          That prompt reads your list from a file, so{' '}
+          <DownloadCidsLink
+            cids={summary.uniqueCids}
+            label="download cids.txt"
+          />{' '}
+          and keep it in the folder your agent runs from.
+        </p>
+      </>
+    )
+  }
+
+  return (
+    <>
+      <Headline>
+        {count.toLocaleString()} {pluralize(count, 'CID')} ready to migrate
+      </Headline>
+      <Adjustments summary={summary} />
+      <p>
+        Give this line to your agent and it will fetch each one, measure it, and
+        migrate it.
+      </p>
+      <AgentPrompt source="verdict" cids={summary.uniqueCids} />
+      <p className="text-(--color-paragraph-text) text-xs">
+        Running the migration yourself instead?{' '}
+        <DownloadCidsLink cids={summary.uniqueCids} label="Download cids.txt" />{' '}
+        for the same list, cleaned and deduped, in the file the runbook reads.
+      </p>
+      <p className="text-(--color-paragraph-text) text-xs">
+        A check reads the CIDs themselves, not the data behind them, so it
+        cannot tell how many bytes you are holding. Enter that in{' '}
+        <SmartTextLink href={`${PATHS.IPFS_TO_FILECOIN.path}#estimate`}>
+          the deposit estimator
+        </SmartTextLink>{' '}
+        to price it.
+      </p>
+    </>
+  )
+}
diff --git a/src/app/ipfs2filecoin/components/ComparisonTable.tsx b/src/app/ipfs2filecoin/components/ComparisonTable.tsx
index 9b7a73b7..57d82f5b 100644
--- a/src/app/ipfs2filecoin/components/ComparisonTable.tsx
+++ b/src/app/ipfs2filecoin/components/ComparisonTable.tsx
@@ -4,10 +4,70 @@ import { pricingComparison } from '../data/pricing-comparison'
 
 export function ComparisonTable() {
   return (
-    <div className="overflow-x-auto rounded-xl border border-(--color-border-muted)">
-      <table className="w-full min-w-140 text-left text-sm">
+    <>
+      <MobileComparisonCards />
+      <DesktopComparisonTable />
+    </>
+  )
+}
+
+/**
+ * The three columns do not fit a phone, and the egress value is a full sentence
+ * rather than a figure, so the table would clip it and scroll sideways. Each
+ * provider becomes a stacked card instead: the name and tier on top, then the
+ * two figures as labelled rows, so nothing is hidden. The table returns at md,
+ * where the columns have room.
+ */
+function MobileComparisonCards() {
+  return (
+    <ul className="space-y-3 md:hidden">
+      {pricingComparison.map(
+        ({ service, detail, storagePerTbMonth, egress, highlighted }) => (
+          <li
+            key={`${service} ${detail}`}
+            className={clsx(
+              'rounded-xl border border-(--color-border-muted) p-4',
+              highlighted && 'bg-(--color-card-background-hover)',
+            )}
+          >
+            <div
+              className={clsx(
+                highlighted && 'font-semibold text-(--color-text-base)',
+              )}
+            >
+              <p className="text-lg">{service}</p>
+              <p className="mt-0.5 font-normal text-(--color-paragraph-text) text-sm">
+                {detail}
+              </p>
+            </div>
+            <dl className="mt-3 space-y-2 border-(--color-border-muted) border-t pt-3 text-sm text-(--color-paragraph-text)">
+              <div className="flex items-baseline justify-between gap-4">
+                <dt>Storage, per TB per month</dt>
+                <dd className="shrink-0 tabular-nums">{storagePerTbMonth}</dd>
+              </div>
+              <div className="flex items-baseline justify-between gap-4">
+                <dt>Egress</dt>
+                <dd className="text-right">{egress}</dd>
+              </div>
+            </dl>
+          </li>
+        ),
+      )}
+    </ul>
+  )
+}
+
+function DesktopComparisonTable() {
+  return (
+    <div className="hidden overflow-x-auto rounded-xl border border-(--color-border-muted) md:block">
+      <table className="w-full min-w-140 text-left text-base">
         <thead>
-          <tr className="border-(--color-border-muted) border-b text-(--color-paragraph-text)">
+          {/*
+            `card-background-hover` is the only subtle-surface value the token
+            set has: zinc-50 on light sections, a lift rather than a wash on
+            dark ones. Named for hover, used here as a static header tint.
+          */}
+          <tr className="border-(--color-border-muted) border-b bg-(--color-card-background-hover) text-(--color-paragraph-text) text-sm">
             <th scope="col" className="px-5 py-4 font-medium">
               Where the data lives
             </th>
@@ -21,29 +81,40 @@ export function ComparisonTable() {
         </thead>
         <tbody className="text-(--color-paragraph-text)">
           {pricingComparison.map(
-            ({ service, storagePerTbMonth, egress, highlighted }) => (
+            ({ service, detail, storagePerTbMonth, egress, highlighted }) => (
+              // Weight and colour sit on the row so the highlighted line reads
+              // as one emphasised entry rather than two bold cells and a third
+              // that quietly drops back to the body colour.
               <tr
-                key={service}
-                className="border-(--color-border-muted) border-b last:border-b-0"
+                key={`${service} ${detail}`}
+                className={clsx(
+                  'border-(--color-border-muted) border-b last:border-b-0',
+                  highlighted && 'font-semibold text-(--color-text-base)',
+                )}
               >
+                {/*
+                  Service names carry the same typeface as the figures on purpose.
+                  They were previously monospace, which read as a size jump and
+                  made the names look smaller than the numbers beside them.
+                */}
                 <th
                   scope="row"
-                  className={clsx(
-                    'px-5 py-4 font-normal',
-                    highlighted && 'font-medium text-(--color-text-base)',
-                  )}
+                  className={clsx('px-5 py-4', !highlighted && 'font-normal')}
                 >
-                  {service}
+                  <span className="block text-lg">{service}</span>
+                  <span className="mt-0.5 block font-normal text-(--color-paragraph-text) text-sm">
+                    {detail}
+                  </span>
                 </th>
                 <td
                   className={clsx(
-                    'px-5 py-4 font-mono whitespace-nowrap',
-                    highlighted && 'text-(--color-text-base) text-lg',
+                    'whitespace-nowrap px-5 py-4 tabular-nums',
+                    highlighted && 'text-lg',
                   )}
                 >
                   {storagePerTbMonth}
                 </td>
-                <td className="px-5 py-4 font-mono whitespace-nowrap">
+                <td className="whitespace-nowrap px-5 py-4 tabular-nums">
                   {egress}
                 </td>
               </tr>
diff --git a/src/app/ipfs2filecoin/components/CostEstimator.tsx b/src/app/ipfs2filecoin/components/CostEstimator.tsx
index c4b8a760..a771fdb2 100644
--- a/src/app/ipfs2filecoin/components/CostEstimator.tsx
+++ b/src/app/ipfs2filecoin/components/CostEstimator.tsx
@@ -1,9 +1,12 @@
 'use client'
 
 import { Button } from '@filecoin-foundation/ui-filecoin/Button'
+import { Icon } from '@filecoin-foundation/ui-filecoin/Icon'
 import { Field, Input, Label, Select } from '@headlessui/react'
+import { CaretDownIcon } from '@phosphor-icons/react/dist/ssr'
+import { clsx } from 'clsx'
 import { usePlausible } from 'next-plausible'
-import { useId, useState } from 'react'
+import { type ChangeEvent, type ReactNode, useId, useState } from 'react'
 
 import {
   BUFFER_DAYS,
@@ -30,10 +33,11 @@ const DURATION_OPTIONS = [
 const fieldClassName =
   'focus:brand-outline block w-full rounded-lg border border-(--input-border-color) p-3 text-(--color-text-base) placeholder:text-(--input-placeholder-color)'
 
+const labelClassName =
+  'mb-1 inline-block font-medium text-(--color-text-base) text-sm'
+
 export function CostEstimator() {
   const volumeId = useId()
-  const unitId = useId()
-  const durationId = useId()
   const plausible = usePlausible()
 
   const [volume, setVolume] = useState('1')
@@ -68,67 +72,76 @@ export function CostEstimator() {
 
   return (
     <div className="space-y-6">
-      <div className="grid gap-4 sm:grid-cols-3">
-        <Field>
-          <Label
-            htmlFor={volumeId}
-            className="mb-1 inline-block font-medium text-(--color-text-base) text-sm"
-          >
-            How much data
-          </Label>
-          <Input
-            id={volumeId}
-            type="number"
-            min="0"
-            step="any"
-            inputMode="decimal"
-            value={volume}
-            onChange={(event) => setVolume(event.target.value)}
-            className={fieldClassName}
-          />
-        </Field>
-
-        <Field>
-          <Label
-            htmlFor={unitId}
-            className="mb-1 inline-block font-medium text-(--color-text-base) text-sm"
-          >
-            Unit
-          </Label>
-          <Select
-            id={unitId}
-            value={unit}
-            onChange={(event) => setUnit(event.target.value as VolumeUnit)}
-            className={fieldClassName}
-          >
-            <option value="GiB">GiB</option>
-            <option value="TiB">TiB</option>
-          </Select>
-        </Field>
-
-        <Field>
-          <Label
-            htmlFor={durationId}
-            className="mb-1 inline-block font-medium text-(--color-text-base) text-sm"
-          >
-            Funded for
-          </Label>
-          <Select
-            id={durationId}
+      {/*
+        Two controls for two questions, sharing one row inside the card. The
+        amount carries its unit inside one bordered box rather than beside a
+        separate field, so "How much data" reads as a single control; the "Unit"
+        label goes with it, since a select holding "TiB" needs no caption. A
+        two-column grid keeps the pair side by side and lets each fill its half
+        rather than being sized to the few characters it holds.
+      */}
+      <div className="space-y-2">
+        <div className="grid grid-cols-2 items-end gap-3">
+          <Field>
+            <Label htmlFor={volumeId} className={labelClassName}>
+              How much data
+            </Label>
+            <div className="focus-within:brand-outline flex w-full items-stretch rounded-lg border border-(--input-border-color)">
+              <Input
+                id={volumeId}
+                type="number"
+                min="0"
+                step="any"
+                inputMode="decimal"
+                value={volume}
+                onChange={(event) => setVolume(event.target.value)}
+                className="w-full min-w-0 border-0 bg-transparent p-3 text-(--color-text-base) focus:outline-none"
+              />
+              <div className="relative flex items-center border-(--input-border-color) border-l">
+                <Select
+                  aria-label="Unit"
+                  value={unit}
+                  onChange={(event) =>
+                    setUnit(event.target.value as VolumeUnit)
+                  }
+                  className="appearance-none bg-transparent py-3 pr-10 pl-3 text-(--color-text-base) focus:outline-none"
+                >
+                  <option value="GiB">GiB</option>
+                  <option value="TiB">TiB</option>
+                </Select>
+                <span className="pointer-events-none absolute right-0 flex items-center pr-3 text-(--color-paragraph-text)">
+                  <Icon component={CaretDownIcon} size={20} />
+                </span>
+              </div>
+            </div>
+          </Field>
+
+          <SelectField
+            className="w-full"
+            label="Funded for"
             value={days}
             onChange={(event) => setDays(Number(event.target.value))}
-            className={fieldClassName}
           >
             {DURATION_OPTIONS.map(({ label, days: value }) => (
               <option key={value} value={value}>
                 {label}
               </option>
             ))}
-          </Select>
-        </Field>
+          </SelectField>
+        </div>
+
+        <p className="text-(--color-paragraph-text-subtle) text-sm">
+          Total across everything you are storing, not per CID. 1 TiB is 1,024
+          GiB.
+        </p>
       </div>
 
-      <Button type="button" variant="primary" onClick={handleEstimate}>
+      <Button
+        type="button"
+        variant="primary"
+        onClick={handleEstimate}
+        className="w-full"
+      >
         Estimate my deposit
       </Button>
 
@@ -152,6 +165,51 @@ export function CostEstimator() {
   )
 }
 
+type SelectFieldProps = {
+  label: string
+  value: string | number
+  onChange: (event: ChangeEvent<HTMLSelectElement>) => void
+  children: ReactNode
+  /** Width of the field, set by the caller so it matches what it holds. */
+  className?: string
+}
+
+/**
+ * A native select styled to match the inputs beside it. The browser's own arrow
+ * is replaced so the caret keeps the same inset as the field's text instead of
+ * sitting hard against the border.
+ */
+function SelectField({
+  label,
+  value,
+  onChange,
+  children,
+  className,
+}: SelectFieldProps) {
+  const id = useId()
+
+  return (
+    <Field className={className}>
+      <Label htmlFor={id} className={labelClassName}>
+        {label}
+      </Label>
+      <div className="relative">
+        <Select
+          id={id}
+          value={value}
+          onChange={onChange}
+          className={clsx(fieldClassName, 'appearance-none pr-11')}
+        >
+          {children}
+        </Select>
+        <span className="pointer-events-none absolute inset-y-0 right-0 flex items-center pr-3 text-(--color-paragraph-text)">
+          <Icon component={CaretDownIcon} size={20} />
+        </span>
+      </div>
+    </Field>
+  )
+}
+
 function EstimateBreakdown({ estimate }: { estimate: CostEstimate }) {
   const durationLabel =
     DURATION_OPTIONS.find(({ days }) => days === estimate.days)?.label ??
@@ -161,65 +219,55 @@ function EstimateBreakdown({ estimate }: { estimate: CostEstimate }) {
     {
       label: `Storage for ${durationLabel}`,
       amount: formatUsd(estimate.storage),
-      note: 'No, this is the cost',
+      note: 'Not refundable, this is the cost',
     },
     {
       label: `Buffer held while data is live (${BUFFER_DAYS} days of charges)`,
       amount: formatUsd(estimate.buffer),
-      note: 'Yes, refundable',
+      note: 'Refundable',
     },
     {
       label: 'Lifecycle reserve, per data set',
       amount: formatUsd(estimate.lifecycleReserve),
-      note: 'Yes, unused portion',
+      note: 'Unused portion refundable',
     },
   ]
 
+  // Stacked rather than a table: the card column is too narrow for the
+  // three-column breakdown, so each line reads label over its refundable note
+  // on the left and the figure on the right, the way a receipt totals up.
   return (
     <div
       role="status"
       aria-live="polite"
-      className="overflow-x-auto rounded-xl border border-(--color-border-muted)"
+      className="space-y-4 rounded-xl border border-(--color-border-muted) bg-(--color-card-background) p-5"
     >
-      <table className="w-full text-left text-sm">
-        <thead>
-          <tr className="border-(--color-border-muted) border-b text-(--color-paragraph-text)">
-            <th scope="col" className="px-5 py-4 font-medium">
-              Line
-            </th>
-            <th scope="col" className="px-5 py-4 font-medium">
-              Amount
-            </th>
-            <th scope="col" className="px-5 py-4 font-medium">
-              Yours again afterwards
-            </th>
-          </tr>
-        </thead>
-        <tbody className="text-(--color-paragraph-text)">
-          {rows.map(({ label, amount, note }) => (
-            <tr key={label} className="border-(--color-border-muted) border-b">
-              <td className="px-5 py-4">{label}</td>
-              <td className="px-5 py-4 font-mono">{amount}</td>
-              <td className="px-5 py-4">{note}</td>
-            </tr>
-          ))}
-          <tr className="text-(--color-text-base)">
-            <td className="px-5 py-4 font-medium">Deposit</td>
-            <td className="px-5 py-4 font-medium font-mono text-lg">
-              {formatUsd(estimate.deposit)}
-            </td>
-            <td className="px-5 py-4">
-              {formatUsd(estimate.refundable)} comes back
-            </td>
-          </tr>
-        </tbody>
-      </table>
-      <p className="px-5 py-4 text-(--color-paragraph-text) text-xs/relaxed">
-        The buffer is set aside, not spent, and you get back whatever is unused.
-        Treat your funded-until date as the date to act by rather than the date
-        service stops: if the balance runs out, providers can end the service
-        and keep the buffer. Depositing for longer is not a discount, it just
-        means fewer trips back.
+      <dl className="space-y-3 text-(--color-paragraph-text)">
+        {rows.map(({ label, amount, note }) => (
+          <div
+            key={label}
+            className="flex items-baseline justify-between gap-4"
+          >
+            <dt>
+              <span className="block text-sm">{label}</span>
+              <span className="block text-(--color-paragraph-text-subtle) text-xs">
+                {note}
+              </span>
+            </dt>
+            <dd className="shrink-0 text-sm tabular-nums">{amount}</dd>
+          </div>
+        ))}
+        <div className="flex items-baseline justify-between gap-4 border-(--color-border-muted) border-t pt-3 text-(--color-text-base)">
+          <dt className="font-medium">Deposit</dt>
+          <dd className="shrink-0 font-medium text-lg tabular-nums">
+            {formatUsd(estimate.deposit)}
+          </dd>
+        </div>
+      </dl>
+      <p className="text-(--color-paragraph-text) text-xs/relaxed">
+        {formatUsd(estimate.refundable)} of this comes back. The buffer is set
+        aside, not spent. Treat your funded-until date as the date to act by: if
+        the balance runs out, providers can end the service and keep the buffer.
       </p>
     </div>
   )
diff --git a/src/app/ipfs2filecoin/components/StepList.tsx b/src/app/ipfs2filecoin/components/StepList.tsx
new file mode 100644
index 00000000..7a03c188
--- /dev/null
+++ b/src/app/ipfs2filecoin/components/StepList.tsx
@@ -0,0 +1,36 @@
+import { Heading } from '@filecoin-foundation/ui-filecoin/Heading'
+
+import type { steps } from '../data/steps'
+
+type StepListProps = {
+  steps: typeof steps
+}
+
+/**
+ * Not the shared `Card`: its `title` is a plain string, so the step number could
+ * only ever be inlined as "01. Hand over the list". Lifting the number above the
+ * title and giving it the accent colour is what makes the section read as a
+ * sequence rather than four unrelated cards.
+ */
+export function StepList({ steps }: StepListProps) {
+  return (
+    // Four across on desktop so the sequence reads left to right in one pass.
+    // Two-up in between, where four columns would be too narrow for the copy.
+    <ol className="grid gap-10 sm:grid-cols-2 sm:gap-x-10 lg:grid-cols-4 lg:gap-x-8">
+      {steps.map(({ number, title, description }) => (
+        <li key={title} className="space-y-3">
+          <span
+            aria-hidden="true"
+            className="block font-heading font-medium text-3xl text-brand-600 tabular-nums"
+          >
+            {number}
+          </span>
+          <Heading tag="h3" variant="card-heading">
+            {title}
+          </Heading>
+          <p className="text-(--color-paragraph-text)">{description}</p>
+        </li>
+      ))}
+    </ol>
+  )
+}
diff --git a/src/app/ipfs2filecoin/constants/migration.ts b/src/app/ipfs2filecoin/constants/migration.ts
index c97c17f2..c41cb5d0 100644
--- a/src/app/ipfs2filecoin/constants/migration.ts
+++ b/src/app/ipfs2filecoin/constants/migration.ts
@@ -73,6 +73,20 @@ export const LLMS_TXT_URL = `${BASE_URL}${LLMS_TXT_PATH}`
 /** The one line a user hands to a coding agent. Copying it is signal, so it is tracked. */
 export const AGENT_PROMPT = `Migrate my IPFS data to Filecoin: read ${RUNBOOK_URL} and follow it. My CIDs are in cids.txt.`
 
+/**
+ * The same instruction with the user's own list inlined, so a checked list is
+ * something you can act on rather than just a count. Falls back to the
+ * cids.txt form when there is no list yet, which is also the right shape for
+ * lists too long to paste into a prompt.
+ */
+export function buildAgentPrompt(cids?: ReadonlyArray<string>): string {
+  if (!cids || cids.length === 0) {
+    return AGENT_PROMPT
+  }
+
+  return `Migrate my IPFS data to Filecoin: read ${RUNBOOK_URL} and follow it. My CIDs are:\n${cids.join('\n')}`
+}
+
 export const PLAUSIBLE_EVENTS = {
   cidListChecked: 'IPFS2Filecoin CID List Checked',
   estimateViewed: 'IPFS2Filecoin Estimate Viewed',
diff --git a/src/app/ipfs2filecoin/constants/seo.ts b/src/app/ipfs2filecoin/constants/seo.ts
index 78c4d3e9..d0448a24 100644
--- a/src/app/ipfs2filecoin/constants/seo.ts
+++ b/src/app/ipfs2filecoin/constants/seo.ts
@@ -1,5 +1,7 @@
+import { USD_PER_TIB_MONTH_PER_COPY } from './migration'
+import { formatUsd } from '../utils/estimate-cost'
+
 export const IPFS2FILECOIN_SEO = {
   title: 'IPFS to Filecoin | Move Your Pinned Data Without Changing Your CIDs',
-  description:
-    'Move pinned IPFS data to Filecoin warm storage. Same CIDs, $2.50 per TiB per month per copy, and an onchain receipt you can verify yourself.',
+  description: `Move pinned IPFS data to Filecoin warm storage. Same CIDs, ${formatUsd(USD_PER_TIB_MONTH_PER_COPY)} per TiB per month per copy, and an onchain receipt you can verify yourself.`,
 } as const
diff --git a/src/app/ipfs2filecoin/data/pricing-comparison.ts b/src/app/ipfs2filecoin/data/pricing-comparison.ts
index a0c15520..829df31b 100644
--- a/src/app/ipfs2filecoin/data/pricing-comparison.ts
+++ b/src/app/ipfs2filecoin/data/pricing-comparison.ts
@@ -1,7 +1,16 @@
+import { COPIES } from '../constants/migration'
 import { formatUsd, USD_PER_TB_MONTH } from '../utils/estimate-cost'
 
 export type PricingRow = {
   service: string
+  /**
+   * The qualifier under the provider name: which plan the rate comes from, or
+   * what the Filecoin figure covers. Split out from the service so the provider
+   * is what you compare on and the tier name stays secondary: at one size they
+   * competed, and two Pinata tiers read as two unrelated vendors. Every row
+   * carries one so the rows are the same height.
+   */
+  detail: string
   storagePerTbMonth: string
   egress: string
   highlighted?: boolean
@@ -17,22 +26,32 @@ export type PricingRow = {
 export const pricingComparison: Array<PricingRow> = [
   {
     service: 'Filecoin Warm Storage',
+    detail: `${COPIES} copies included`,
     storagePerTbMonth: formatUsd(USD_PER_TB_MONTH),
-    egress: 'IPFS gateway read path',
+    /**
+     * Deliberately not a price and deliberately not "free". Reads happen by CID
+     * over public IPFS gateways, which this service does not meter. Fast
+     * delivery through Filecoin Beam is a separate, paid product, so any claim
+     * of zero egress cost here would be wrong.
+     */
+    egress: 'Read by CID from any IPFS gateway',
     highlighted: true,
   },
   {
-    service: 'Filebase, Pro overage',
+    service: 'Filebase',
+    detail: 'Pro plan overage',
     storagePerTbMonth: '$15.00',
     egress: '$0.015 / GB',
   },
   {
-    service: 'Pinata, Fiesta overage',
+    service: 'Pinata',
+    detail: 'Fiesta plan overage',
     storagePerTbMonth: '$35.00',
     egress: '$0.080 / GB',
   },
   {
-    service: 'Pinata, Picnic overage',
+    service: 'Pinata',
+    detail: 'Picnic plan overage',
     storagePerTbMonth: '$70.00',
     egress: '$0.100 / GB',
   },
diff --git a/src/app/ipfs2filecoin/data/reasons.ts b/src/app/ipfs2filecoin/data/reasons.ts
index 8eefd413..5f8cc8c9 100644
--- a/src/app/ipfs2filecoin/data/reasons.ts
+++ b/src/app/ipfs2filecoin/data/reasons.ts
@@ -1,22 +1,35 @@
+import {
+  CurrencyDollarIcon,
+  FingerprintIcon,
+  SealCheckIcon,
+  WalletIcon,
+} from '@phosphor-icons/react/dist/ssr'
+
+import { USD_PER_TIB_MONTH_PER_COPY } from '../constants/migration'
+import { formatUsd } from '../utils/estimate-cost'
+
 export const reasons = [
   {
     title: 'Your CIDs do not change',
     description:
       'Nothing is re-chunked. Every CID stays byte-identical and keeps resolving from any public IPFS gateway, so existing links, IPNS names, and NFT metadata keep working exactly as they do today.',
+    icon: FingerprintIcon,
   },
   {
     title: 'A fraction of pinning-service pricing',
-    description:
-      '$2.50 per TiB per month per copy, two copies by default. You pay storage providers directly, streamed per epoch, with no plan tiers and no minimum commitment.',
+    description: `${formatUsd(USD_PER_TIB_MONTH_PER_COPY)} per TiB per month per copy, two copies by default. You pay storage providers directly, streamed per epoch, with no plan tiers and no minimum commitment.`,
+    icon: CurrencyDollarIcon,
   },
   {
     title: 'Proof, not a dashboard',
     description:
       'Storage providers prove possession onchain on a schedule. You get a receipt with transaction links, and you can verify any piece yourself at any time without asking anyone.',
+    icon: SealCheckIcon,
   },
   {
     title: 'Your wallet owns it, not an account',
     description:
       'No signup and no vendor account to lose. The data set belongs to your wallet address and payment streams from your wallet straight to the providers. Reading your data never depends on your key, so the content stays reachable either way.',
+    icon: WalletIcon,
   },
 ] as const
diff --git a/src/app/ipfs2filecoin/page.tsx b/src/app/ipfs2filecoin/page.tsx
index 2f009530..db233b10 100644
--- a/src/app/ipfs2filecoin/page.tsx
+++ b/src/app/ipfs2filecoin/page.tsx
@@ -1,13 +1,14 @@
 import { Button } from '@filecoin-foundation/ui-filecoin/Button'
 import { Card } from '@filecoin-foundation/ui-filecoin/Card'
 import { CardGrid } from '@filecoin-foundation/ui-filecoin/CardGrid'
-import { Container } from '@filecoin-foundation/ui-filecoin/Container'
 import { Heading } from '@filecoin-foundation/ui-filecoin/Heading'
+import { Icon } from '@filecoin-foundation/ui-filecoin/Icon'
 import { PageHeader } from '@filecoin-foundation/ui-filecoin/PageHeader'
 import { PageSection } from '@filecoin-foundation/ui-filecoin/PageSection'
 import { SectionContent } from '@filecoin-foundation/ui-filecoin/SectionContent'
 import { ExternalTextLink } from '@filecoin-foundation/ui-filecoin/TextLink/ExternalTextLink'
 import { SmartTextLink } from '@filecoin-foundation/ui-filecoin/TextLink/SmartTextLink'
+import { WarningCircleIcon } from '@phosphor-icons/react/dist/ssr'
 import type { Metadata } from 'next'
 
 import { Faq } from '@/components/Faq'
@@ -22,17 +23,31 @@ import { AgentPrompt } from './components/AgentPrompt'
 import { CidListChecker } from './components/CidListChecker'
 import { ComparisonTable } from './components/ComparisonTable'
 import { CostEstimator } from './components/CostEstimator'
-import { COORDINATION_VOLUME_LABEL, RUNBOOK_PATH } from './constants/migration'
+import { StepList } from './components/StepList'
+import {
+  COORDINATION_VOLUME_LABEL,
+  RUNBOOK_PATH,
+  USD_PER_TIB_MONTH_PER_COPY,
+} from './constants/migration'
 import { IPFS2FILECOIN_SEO } from './constants/seo'
 import { faqs } from './data/faqs'
 import { limits } from './data/limits'
 import { reasons } from './data/reasons'
 import { steps } from './data/steps'
+import { formatUsd } from './utils/estimate-cost'
 import { generateStructuredData } from './utils/generate-structured-data'
 
 const ghostOnDark =
   '!border-zinc-50/40 !bg-transparent hover:!border-zinc-50 hover:!bg-zinc-50/5'
 
+/**
+ * `ExternalTextLink` sizes its arrow for button-style links: a fixed 16px glyph
+ * set `ml-1` off the label. Inside a 14px paragraph that reads as oversized and
+ * detached, so pull it in and scale it to the text. Fix belongs upstream in
+ * ui-filecoin; this keeps the footnote legible until then.
+ */
+const inlineExternalLink = '[&>span]:ml-0.5 [&_svg]:size-3.5'
+
 export default function IpfsToFilecoin() {
   return (
     <>
@@ -42,19 +57,33 @@ export default function IpfsToFilecoin() {
 
       <Navigation backgroundVariant="dark" />
 
-      <PageSection backgroundVariant="dark">
-        <PageHeader
-          centered
-          variant="highContrast"
-          title="Move your pinned IPFS data to Filecoin"
-          description="Same CIDs, a fraction of what pinning services charge, and an onchain receipt you can verify yourself."
-        />
-        <Container>
+      {/*
+        Full-bleed backdrop behind the hero, following the homepage pattern: an
+        `isolate relative` wrapper, an `absolute inset-0 -z-10` layer that spans
+        edge to edge rather than the padded container, and `transparentDark` on
+        the section so the layer shows through while text keeps its dark-section
+        tokens. The base stays zinc-950 as before; a faint brand glow along the
+        bottom lifts it just enough to read as lit rather than flat black, and
+        carries the eye toward the section that follows. The tint is the
+        --color-brand-500 token (the primary blue), mixed down to 12% so it reads
+        as light on the surface, not a coloured panel.
+      */}
+      <div className="isolate relative">
+        <div aria-hidden className="absolute inset-0 -z-10 bg-zinc-950">
+          <div className="absolute inset-x-0 bottom-0 h-144 bg-[radial-gradient(60%_100%_at_50%_100%,color-mix(in_oklab,var(--color-brand-500)_12%,transparent),transparent_70%)]" />
+        </div>
+        <PageSection backgroundVariant="transparentDark">
+          <PageHeader
+            centered
+            variant="highContrast"
+            title="Move your pinned IPFS data to Filecoin"
+            description="Same CIDs, a fraction of what pinning services charge, and an onchain receipt you can verify yourself."
+          />
           <div className="mt-10">
             <CidListChecker />
           </div>
-        </Container>
-      </PageSection>
+        </PageSection>
+      </div>
 
       <PageSection backgroundVariant="gray">
         <SectionContent
@@ -63,12 +92,18 @@ export default function IpfsToFilecoin() {
           description="Your data keeps working the way it does today. What changes is the price, the proof, and who owns it."
         >
           <CardGrid as="ul" variant="lgTwoWide">
-            {reasons.map(({ title, description }) => (
+            {reasons.map(({ title, description, icon }) => (
               <Card
                 key={title}
                 as="li"
                 title={title}
-                description={description}
+                // Card sets descriptions at text-xl/7; these reason blurbs run
+                // long and read heavier than the titles at that size. Stepped
+                // down per-instance so the shared Card stays untouched.
+                description={
+                  <span className="text-base/relaxed">{description}</span>
+                }
+                icon={icon}
               />
             ))}
           </CardGrid>
@@ -81,41 +116,57 @@ export default function IpfsToFilecoin() {
           title="What it costs"
           description="Pinning services bundle an allowance into a monthly plan, then charge per gigabyte past it. Once you are past the allowance, which anyone migrating a real archive already is, the overage rate is your real cost."
         >
-          <div className="space-y-6">
-            <ComparisonTable />
+          {/*
+            The comparison and the estimator answer one question between them:
+            the table is the market rate, the card prices it for your own data.
+            Paired side by side at lg so they read as two halves of "what it
+            costs"; stacked below that, where a 2fr/1fr split leaves the table
+            too narrow to hold its columns.
+          */}
+          <div className="grid gap-8 lg:grid-cols-3 lg:items-start">
+            <div className="space-y-6 lg:col-span-2">
+              <ComparisonTable />
 
-            <p className="text-(--color-paragraph-text) text-sm/relaxed">
-              Filecoin Warm Storage is $2.50 per TiB per month per copy at two
-              copies. Other rates are the published list overage rates from{' '}
-              <ExternalTextLink href="https://filebase.com/pricing/">
-                Filebase
-              </ExternalTextLink>{' '}
-              and{' '}
-              <ExternalTextLink href="https://pinata.cloud/pricing">
-                Pinata
-              </ExternalTextLink>
-              . Filecoin includes two replicas; the other services do not
-              publish a replication factor, so the comparison is conservative.
-            </p>
-          </div>
-        </SectionContent>
-      </PageSection>
+              <p className="text-(--color-paragraph-text) text-sm/relaxed">
+                Filecoin Warm Storage is {formatUsd(USD_PER_TIB_MONTH_PER_COPY)}{' '}
+                per TiB per month per copy at two copies. Other rates are the
+                published list overage rates from{' '}
+                <ExternalTextLink
+                  className={inlineExternalLink}
+                  href="https://filebase.com/pricing/"
+                >
+                  Filebase
+                </ExternalTextLink>{' '}
+                and{' '}
+                <ExternalTextLink
+                  className={inlineExternalLink}
+                  href="https://pinata.cloud/pricing"
+                >
+                  Pinata
+                </ExternalTextLink>
+                . Filecoin includes two replicas; the other services do not
+                publish a replication factor, so the comparison is conservative.
+              </p>
+            </div>
 
-      <PageSection backgroundVariant="light" paddingVariant="topNone">
-        <Container>
-          <div className="max-w-4xl space-y-6">
-            <Heading tag="h2" variant="card-heading">
-              Estimate your deposit
-            </Heading>
-            <p className="text-(--color-paragraph-text)">
-              Storage is charged continuously while your data sits there, so you
-              deposit for a period rather than paying a monthly bill. Enter
-              roughly how much you are holding and how long you want to be
-              covered. This runs in your browser and nothing is sent anywhere.
-            </p>
-            <CostEstimator />
+            <div
+              id="estimate"
+              className="scroll-mt-24 rounded-xl border border-(--color-border-muted) bg-(--color-card-background-hover) p-6"
+            >
+              <Heading tag="h3" variant="card-heading">
+                Estimate your deposit
+              </Heading>
+              <p className="mt-2 text-(--color-paragraph-text) text-sm/relaxed">
+                Storage is prepaid for a period rather than billed monthly.
+                Enter roughly how much you hold and for how long; it runs in
+                your browser.
+              </p>
+              <div className="mt-6">
+                <CostEstimator />
+              </div>
+            </div>
           </div>
-        </Container>
+        </SectionContent>
       </PageSection>
 
       <PageSection backgroundVariant="gray">
@@ -124,16 +175,7 @@ export default function IpfsToFilecoin() {
           title="How it works"
           description="Four steps, and the first two are free."
         >
-          <CardGrid as="ul" variant="smTwoLgThreeWider">
-            {steps.map(({ number, title, description }) => (
-              <Card
-                key={title}
-                as="li"
-                title={`${number}. ${title}`}
-                description={description}
-              />
-            ))}
-          </CardGrid>
+          <StepList steps={steps} />
         </SectionContent>
       </PageSection>
 
@@ -143,8 +185,15 @@ export default function IpfsToFilecoin() {
           title="Nobody should migrate an archive by clicking"
           description="Real migrations run unattended, so that is the path this is built around. Check a list for free, get your account funded in one pass, then hand the work to your agent or to us."
         >
-          <div className="grid gap-8 lg:grid-cols-2">
-            <div id="agent" className="scroll-mt-24 space-y-4">
+          {/*
+            No panels. Boxing both columns stacked three nested borders in the
+            left one: panel, then code block, then a warning box inside it. One
+            hairline between the columns does the same separating work, and the
+            code block stays the only bordered thing because it is a surface you
+            copy from rather than a container.
+          */}
+          <div className="grid gap-10 lg:grid-cols-3 lg:gap-14">
+            <div id="agent" className="scroll-mt-24 space-y-4 lg:col-span-2">
               <Heading tag="h3" variant="card-heading">
                 Ask your agent to do it
               </Heading>
@@ -156,17 +205,34 @@ export default function IpfsToFilecoin() {
                 </SmartTextLink>
                 , works through your list, and reports back what landed.
               </p>
-              <p className="text-(--color-paragraph-text)">
-                It signs from a key you provide, and a key that can sign on your
-                account can draw against its balance, so your deposit is the
-                ceiling. Use a wallet you keep for this purpose, holding what
-                this migration needs and nothing else. Never give a main
-                wallet&apos;s key to something running unattended.
-              </p>
+
+              {/* The action ahead of the caveat: this is what people came for. */}
               <AgentPrompt source="agent-door" />
+
+              {/*
+                Marked with an icon and a bolded rule rather than a box. This is
+                the one thing here that can cost someone real money, so it
+                cannot read as a third grey paragraph, but it does not need a
+                container to say so.
+              */}
+              <div className="flex gap-2.5">
+                <span className="mt-0.5 shrink-0 text-(--color-brand-error)">
+                  <Icon component={WarningCircleIcon} size={16} />
+                </span>
+                <p className="text-(--color-paragraph-text) text-sm/relaxed">
+                  It signs from a key you provide, and a key that can sign on
+                  your account can draw against its balance, so your deposit is
+                  the ceiling. Use a wallet you keep for this purpose, holding
+                  what this migration needs and nothing else.{' '}
+                  <strong className="font-medium text-(--color-text-base)">
+                    Never give a main wallet&apos;s key to something running
+                    unattended.
+                  </strong>
+                </p>
+              </div>
             </div>
 
-            <div className="space-y-4">
+            <div className="h-fit space-y-4 lg:border-(--color-border-muted) lg:border-l lg:pl-14">
               <Heading tag="h3" variant="card-heading">
                 Talk to us
               </Heading>
@@ -176,13 +242,18 @@ export default function IpfsToFilecoin() {
                 {COORDINATION_VOLUME_LABEL}. That is coordination, not a
                 ceiling: the agent path has no cap on how many CIDs it migrates.
               </p>
-              <Button
-                href={PATHS.CONTACT.path}
-                variant="ghost"
-                className={ghostOnDark}
-              >
-                Tell us about your data
-              </Button>
+              {/* Padding rather than a margin: the parent's `space-y` already
+                  owns each child's margin-top, so this adds to it instead of
+                  fighting it. */}
+              <div className="pt-4">
+                <Button
+                  href={PATHS.CONTACT.path}
+                  variant="ghost"
+                  className={ghostOnDark}
+                >
+                  Tell us about your data
+                </Button>
+              </div>
             </div>
           </div>
         </SectionContent>
@@ -194,7 +265,7 @@ export default function IpfsToFilecoin() {
           title="What this does not do"
           description="The things worth knowing up front, so nothing surprises you halfway through a run."
         >
-          <dl className="divide-y divide-(--color-border-muted) border-(--color-border-muted) border-t">
+          <dl className="max-w-5xl divide-y divide-(--color-border-muted) border-(--color-border-muted) border-t">
             {limits.map(({ title, description }) => (
               <div
                 key={title}
diff --git a/src/app/ipfs2filecoin/utils/pluralize.ts b/src/app/ipfs2filecoin/utils/pluralize.ts
new file mode 100644
index 00000000..f8085881
--- /dev/null
+++ b/src/app/ipfs2filecoin/utils/pluralize.ts
@@ -0,0 +1,8 @@
+/** Shared by the checker's live readout and its verdict, so the two agree. */
+export function pluralize(
+  count: number,
+  singular: string,
+  plural = `${singular}s`,
+) {
+  return count === 1 ? singular : plural
+}
diff --git a/src/components/Accordion.tsx b/src/components/Accordion.tsx
index 43cabcff..731fccf1 100644
--- a/src/components/Accordion.tsx
+++ b/src/components/Accordion.tsx
@@ -22,7 +22,7 @@ function AccordionItem({
     <AccordionPrimitive.Item
       data-slot="accordion-item"
       className={clsx(
-        'group/accordion border-b last:border-b-0 py-4',
+        'group/accordion border-(--color-border-base) border-b last:border-b-0 py-4',
         className,
       )}
       {...props}
@@ -46,7 +46,7 @@ function AccordionTrigger({
         {...props}
       >
         {children}
-        <span className="transition-transform duration-200 group-data-[state=open]/accordion:rotate-180 text-zinc-200">
+        <span className="transition-transform duration-200 group-data-[state=open]/accordion:rotate-180 text-(--color-text-base)">
           <Icon component={CaretDownIcon} color="inherit" />
         </span>
       </AccordionPrimitive.Trigger>
@@ -62,7 +62,7 @@ function AccordionContent({
   return (
     <AccordionPrimitive.Content
       data-slot="accordion-content"
-      className="data-[state=closed]:animate-slide-up data-[state=open]:animate-slide-down overflow-hidden text-zinc-300"
+      className="data-[state=closed]:animate-slide-up data-[state=open]:animate-slide-down overflow-hidden text-(--color-paragraph-text)"
       {...props}
     >
       <div className={clsx('pb-4', className)}>{children}</div>
diff --git a/src/components/Faq.tsx b/src/components/Faq.tsx
index 1e08609a..d91ca49a 100644
--- a/src/components/Faq.tsx
+++ b/src/components/Faq.tsx
@@ -21,7 +21,7 @@ export function Faq({ questions }: FaqProps) {
   return (
     <div className="max-w-4xl">
       <SectionContent headingTag="h2" title="Frequently asked questions">
-        <Accordion type="single" collapsible className="divide-white/20">
+        <Accordion type="single" collapsible>
           {questions.map(({ question, answer }) => {
             return (
               <Accordion.Item key={question} value={question} className="py-4">

From e15f45aa47fddf29f67a12688803a2bbedaa4b72 Mon Sep 17 00:00:00 2001
From: Russell Dempsey <1173416+SgtPooki@users.noreply.github.com>
Date: Fri, 14 Aug 2026 15:32:01 -0400
Subject: [PATCH 09/26] fix(ipfs2filecoin): drop llms.txt links to the hidden
 service-providers page

---
 src/app/ipfs2filecoin/llms.txt/route.ts | 1 -
 src/app/llms.txt/route.ts               | 1 -
 2 files changed, 2 deletions(-)

diff --git a/src/app/ipfs2filecoin/llms.txt/route.ts b/src/app/ipfs2filecoin/llms.txt/route.ts
index b1029a1e..111cd195 100644
--- a/src/app/ipfs2filecoin/llms.txt/route.ts
+++ b/src/app/ipfs2filecoin/llms.txt/route.ts
@@ -30,7 +30,6 @@ the complete procedure, and the rest of these links are background.
 
 - [IPFS to Filecoin](${BASE_URL}${PATHS.IPFS_TO_FILECOIN.path}): what this is, what it costs, and what it does not do. Includes a free in-browser CID check.
 - [Warm storage service](${BASE_URL}${PATHS.WARM_STORAGE_SERVICE.path}): the storage product underneath, and its pricing.
-- [Service providers](${BASE_URL}${PATHS.SERVICE_PROVIDERS.path}): the providers that store and prove the data.
 - [Documentation](${FOC_URLS.documentation.home}): Filecoin Onchain Cloud docs.
 
 ## Limits
diff --git a/src/app/llms.txt/route.ts b/src/app/llms.txt/route.ts
index 2f3e06a7..8863b94e 100644
--- a/src/app/llms.txt/route.ts
+++ b/src/app/llms.txt/route.ts
@@ -15,7 +15,6 @@ const LLMS_TXT = `# Filecoin Onchain Cloud
 ## Services
 
 - [Warm storage service](${BASE_URL}${PATHS.WARM_STORAGE_SERVICE.path}): verifiable storage backed by Proof of Data Possession, with pricing and live provider data.
-- [Service providers](${BASE_URL}${PATHS.SERVICE_PROVIDERS.path}): registry of providers, their capabilities, locations, and availability.
 - [Filecoin Pay](${FOC_URLS.filecoinPay}): payment rails that settle storage per epoch.
 
 ## Migrate to Filecoin

From 5a6ecc707b0072702901ff0c08eb6257d588b2d2 Mon Sep 17 00:00:00 2001
From: Russell Dempsey <1173416+SgtPooki@users.noreply.github.com>
Date: Fri, 14 Aug 2026 15:32:01 -0400
Subject: [PATCH 10/26] fix(ipfs2filecoin): accept subdomain-style gateway URLs
 in the CID checker

---
 src/app/ipfs2filecoin/utils/parse-cid-list.ts | 19 ++++++++++++++-----
 1 file changed, 14 insertions(+), 5 deletions(-)

diff --git a/src/app/ipfs2filecoin/utils/parse-cid-list.ts b/src/app/ipfs2filecoin/utils/parse-cid-list.ts
index e7cb8613..88bd8541 100644
--- a/src/app/ipfs2filecoin/utils/parse-cid-list.ts
+++ b/src/app/ipfs2filecoin/utils/parse-cid-list.ts
@@ -7,6 +7,14 @@ const CID_PATTERN = /^(Qm[1-9A-HJ-NP-Za-km-z]{44}|b[a-z2-7]{58,})$/
 
 const GATEWAY_PREFIX_PATTERN = /^(?:ipfs:\/\/|https?:\/\/[^/]+\/ipfs\/)/
 
+/**
+ * Subdomain gateways (`https://<cid>.ipfs.dweb.link/…`) carry the CID as the
+ * leftmost DNS label. Only case-insensitive encodings survive DNS, so this form
+ * is always a base32 CIDv1, never `Qm…` — the narrow character class is
+ * deliberate, and CID_PATTERN still has the final say on the captured label.
+ */
+const SUBDOMAIN_GATEWAY_PATTERN = /^https?:\/\/([a-z2-7]+)\.ipfs\.[^/\s]+/
+
 export type CidListSummary = {
   totalLines: number
   uniqueCids: Array<string>
@@ -15,11 +23,12 @@ export type CidListSummary = {
 }
 
 function normalizeLine(line: string) {
-  return line
-    .trim()
-    .replace(/[,;]$/, '')
-    .replace(GATEWAY_PREFIX_PATTERN, '')
-    .split(/[?#/]/)[0]
+  const trimmed = line.trim().replace(/[,;]$/, '')
+  const subdomain = SUBDOMAIN_GATEWAY_PATTERN.exec(trimmed)
+  if (subdomain) {
+    return subdomain[1]
+  }
+  return trimmed.replace(GATEWAY_PREFIX_PATTERN, '').split(/[?#/]/)[0]
 }
 
 export function parseCidList(input: string): CidListSummary {

From 93b896371cdcdfbe7fc9d72aaab683e0404de9dc Mon Sep 17 00:00:00 2001
From: Russell Dempsey <1173416+SgtPooki@users.noreply.github.com>
Date: Fri, 14 Aug 2026 15:32:01 -0400
Subject: [PATCH 11/26] fix(ipfs2filecoin): describe resumability as the CLI
 state database, not a browser tab

---
 src/app/ipfs2filecoin/data/faqs.tsx | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/src/app/ipfs2filecoin/data/faqs.tsx b/src/app/ipfs2filecoin/data/faqs.tsx
index 06449fe1..7046cf13 100644
--- a/src/app/ipfs2filecoin/data/faqs.tsx
+++ b/src/app/ipfs2filecoin/data/faqs.tsx
@@ -58,9 +58,10 @@ export const faqs: Array<Question> = [
     question: 'What happens if the run stops halfway?',
     answer: (
       <p>
-        State is kept, so closing the tab does not lose the work and the run
-        picks up where it left off. Anything not yet stored stays in the
-        manifest so you can finish it here or carry it to the command line.
+        The CLI keeps its state in a local database, so an interrupted run loses
+        nothing: re-run the same command and it picks up where it left off.
+        Anything not yet stored stays in the manifest, so you can finish it in a
+        later run.
       </p>
     ),
   },

From e6a9f596568b1cb434f280e52de7f8b0f3f0bd41 Mon Sep 17 00:00:00 2001
From: Russell Dempsey <1173416+SgtPooki@users.noreply.github.com>
Date: Fri, 14 Aug 2026 16:52:30 -0400
Subject: [PATCH 12/26] fix(ipfs2filecoin): runbook requires Node 24 per
 ipfs2foc 0.8.1

---
 src/app/ipfs2filecoin/constants/migration.ts    | 2 +-
 src/app/ipfs2filecoin/data/migration-runbook.ts | 4 ++--
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/src/app/ipfs2filecoin/constants/migration.ts b/src/app/ipfs2filecoin/constants/migration.ts
index c41cb5d0..0bb602cb 100644
--- a/src/app/ipfs2filecoin/constants/migration.ts
+++ b/src/app/ipfs2filecoin/constants/migration.ts
@@ -32,7 +32,7 @@ export const CLI_REPO_URL = 'https://github.com/FilOzone/ipfs2foc'
  * FilOzone/ipfs2foc#71. GATE: do not merge/deploy this page until npm serves
  * a version >= this constant (`npm view ipfs2foc version`).
  */
-export const CLI_VERIFIED_FROM = '0.8.0'
+export const CLI_VERIFIED_FROM = '0.8.1'
 
 /** Warm storage list price, per copy. Two copies are stored by default. */
 export const USD_PER_TIB_MONTH_PER_COPY = 2.5
diff --git a/src/app/ipfs2filecoin/data/migration-runbook.ts b/src/app/ipfs2filecoin/data/migration-runbook.ts
index 10c22f64..ccb9af5f 100644
--- a/src/app/ipfs2filecoin/data/migration-runbook.ts
+++ b/src/app/ipfs2filecoin/data/migration-runbook.ts
@@ -35,7 +35,7 @@ export const MIGRATION_RUNBOOK = `---
 tool: ${CLI_PACKAGE}
 tool_min_version: "${CLI_VERIFIED_FROM}"
 tool_repo: ${CLI_REPO_URL}
-node: ">=26"
+node: ">=24"
 default_network: mainnet
 input: a text file of IPFS CIDs, one per line
 item_size_limit: ${MAX_ITEM_SIZE_LABEL}
@@ -108,7 +108,7 @@ spending real funds.
 
 ### Needed now (stages 1-2)
 
-- Node 26 or newer. Hard requirement. Check with \`node --version\`.
+- Node 24 or newer. Hard requirement. Check with \`node --version\`.
 - A CID list, one per line. Blank lines and \`#\` comments are ignored.
 - A trustless gateway that serves deterministic CARs. Stage 1 verifies this.
 - Free disk roughly the size of the data being migrated. Stage 4 stages packed

From b8225b025505302a35813e0bc1499213116c11e5 Mon Sep 17 00:00:00 2001
From: Russell Dempsey <1173416+SgtPooki@users.noreply.github.com>
Date: Mon, 17 Aug 2026 12:56:11 -0400
Subject: [PATCH 13/26] feat(ipfs2filecoin): drop the 500-item browser check
 cap

---
 .../components/CidListChecker.tsx             |  8 +--
 .../components/CidListVerdict.tsx             | 62 ++++++++-----------
 src/app/ipfs2filecoin/constants/migration.ts  | 22 +++----
 3 files changed, 37 insertions(+), 55 deletions(-)

diff --git a/src/app/ipfs2filecoin/components/CidListChecker.tsx b/src/app/ipfs2filecoin/components/CidListChecker.tsx
index e800d1e7..9220feba 100644
--- a/src/app/ipfs2filecoin/components/CidListChecker.tsx
+++ b/src/app/ipfs2filecoin/components/CidListChecker.tsx
@@ -6,11 +6,7 @@ import { usePlausible } from 'next-plausible'
 import { useEffect, useMemo, useRef, useState } from 'react'
 
 import { CidListVerdict, getVerdict, type Verdict } from './CidListVerdict'
-import {
-  BROWSER_CHECK_ITEM_CAP,
-  MAX_ITEM_SIZE_LABEL,
-  PLAUSIBLE_EVENTS,
-} from '../constants/migration'
+import { MAX_ITEM_SIZE_LABEL, PLAUSIBLE_EVENTS } from '../constants/migration'
 import { parseCidList } from '../utils/parse-cid-list'
 import { pluralize } from '../utils/pluralize'
 
@@ -25,7 +21,7 @@ const PLACEHOLDER =
 /** The free-check facts, broken out so they scan as features rather than fine print. */
 const CHECK_FACTS = [
   'Free, no wallet required',
-  `Up to ${BROWSER_CHECK_ITEM_CAP.toLocaleString()} items`,
+  'No list-size limit',
   `${MAX_ITEM_SIZE_LABEL} per item`,
   'Runs in your browser',
   'Never sent anywhere',
diff --git a/src/app/ipfs2filecoin/components/CidListVerdict.tsx b/src/app/ipfs2filecoin/components/CidListVerdict.tsx
index c760de4a..09cfaa28 100644
--- a/src/app/ipfs2filecoin/components/CidListVerdict.tsx
+++ b/src/app/ipfs2filecoin/components/CidListVerdict.tsx
@@ -11,7 +11,7 @@ import {
 import { PATHS } from '@/constants/paths'
 
 import { AgentPrompt } from './AgentPrompt'
-import { BROWSER_CHECK_ITEM_CAP } from '../constants/migration'
+import { PROMPT_INLINE_CAP } from '../constants/migration'
 import type { CidListSummary } from '../utils/parse-cid-list'
 import { pluralize } from '../utils/pluralize'
 
@@ -19,7 +19,6 @@ export type Verdict =
   | { kind: 'empty' }
   | { kind: 'unreadable'; summary: CidListSummary }
   | { kind: 'ok'; summary: CidListSummary }
-  | { kind: 'over-cap'; summary: CidListSummary }
 
 export function getVerdict(summary: CidListSummary): Verdict {
   if (summary.totalLines === 0) {
@@ -28,16 +27,12 @@ export function getVerdict(summary: CidListSummary): Verdict {
   if (summary.uniqueCids.length === 0) {
     return { kind: 'unreadable', summary }
   }
-  if (summary.uniqueCids.length > BROWSER_CHECK_ITEM_CAP) {
-    return { kind: 'over-cap', summary }
-  }
   return { kind: 'ok', summary }
 }
 
 /**
  * Tone per outcome, in tokens rather than literals so the panel survives being
- * mounted on a light section. Over-cap is informational, not a failure: the
- * list is fine, it just routes to the agent instead of the browser.
+ * mounted on a light section.
  */
 const TONE = {
   empty: { icon: InfoIcon, className: 'text-(--color-paragraph-text)' },
@@ -45,7 +40,6 @@ const TONE = {
     icon: WarningCircleIcon,
     className: 'text-(--color-brand-error)',
   },
-  'over-cap': { icon: InfoIcon, className: 'text-(--color-paragraph-text)' },
   ok: { icon: CheckCircleIcon, className: 'text-(--color-icon-success)' },
 } as const
 
@@ -166,30 +160,10 @@ function VerdictBody({ verdict }: { verdict: Verdict }) {
     )
   }
 
-  if (verdict.kind === 'over-cap') {
-    return (
-      <>
-        <Headline>
-          {count.toLocaleString()} CIDs is more than a browser check handles
-        </Headline>
-        <Adjustments summary={summary} />
-        <p>
-          The limit here is {BROWSER_CHECK_ITEM_CAP.toLocaleString()} items.
-          Hand the list to your agent instead: no cap, and it resumes if it
-          stops.
-        </p>
-        <AgentPrompt source="verdict" />
-        <p className="text-(--color-paragraph-text) text-xs">
-          That prompt reads your list from a file, so{' '}
-          <DownloadCidsLink
-            cids={summary.uniqueCids}
-            label="download cids.txt"
-          />{' '}
-          and keep it in the folder your agent runs from.
-        </p>
-      </>
-    )
-  }
+  // Past this size the copied prompt points at cids.txt rather than inlining
+  // the list (see buildAgentPrompt), so the download stops being optional and
+  // the copy has to say so.
+  const promptReadsFromFile = count > PROMPT_INLINE_CAP
 
   return (
     <>
@@ -202,11 +176,25 @@ function VerdictBody({ verdict }: { verdict: Verdict }) {
         migrate it.
       </p>
       <AgentPrompt source="verdict" cids={summary.uniqueCids} />
-      <p className="text-(--color-paragraph-text) text-xs">
-        Running the migration yourself instead?{' '}
-        <DownloadCidsLink cids={summary.uniqueCids} label="Download cids.txt" />{' '}
-        for the same list, cleaned and deduped, in the file the runbook reads.
-      </p>
+      {promptReadsFromFile ? (
+        <p className="text-(--color-paragraph-text) text-xs">
+          That prompt reads your list from a file, so{' '}
+          <DownloadCidsLink
+            cids={summary.uniqueCids}
+            label="download cids.txt"
+          />{' '}
+          and keep it in the folder your agent runs from.
+        </p>
+      ) : (
+        <p className="text-(--color-paragraph-text) text-xs">
+          Running the migration yourself instead?{' '}
+          <DownloadCidsLink
+            cids={summary.uniqueCids}
+            label="Download cids.txt"
+          />{' '}
+          for the same list, cleaned and deduped, in the file the runbook reads.
+        </p>
+      )}
       <p className="text-(--color-paragraph-text) text-xs">
         A check reads the CIDs themselves, not the data behind them, so it
         cannot tell how many bytes you are holding. Enter that in{' '}
diff --git a/src/app/ipfs2filecoin/constants/migration.ts b/src/app/ipfs2filecoin/constants/migration.ts
index 0bb602cb..bdd1cc2c 100644
--- a/src/app/ipfs2filecoin/constants/migration.ts
+++ b/src/app/ipfs2filecoin/constants/migration.ts
@@ -1,10 +1,12 @@
 import { BASE_URL } from '@/constants/site-metadata'
 
 /**
- * Cap on the in-browser check only. The agent and CLI paths have no item cap,
- * so this must never be presented as a limit on migration itself.
+ * Above this, the copied agent prompt points at a downloaded cids.txt instead
+ * of inlining the list: a clipboard string is the wrong shape for thousands of
+ * lines. A bound on the prompt's form only. The check, the agent, and the CLI
+ * have no item cap.
  */
-export const BROWSER_CHECK_ITEM_CAP = 500
+export const PROMPT_INLINE_CAP = 500
 
 /**
  * A hard limit: an item's CAR must fit one uploadable piece, capped at
@@ -60,27 +62,23 @@ export const DAYS_PER_MONTH = 30
 export const BUFFER_DAYS = 30
 
 /**
- * The executable runbook. Named for what it is: llms.txt is specified as a
- * documentation index, not a procedure, so the procedure lives at its own URL.
+ * The executable runbook, at its own markdown URL. Named for what it is: a
+ * procedure an agent follows, not a documentation index.
  */
 export const RUNBOOK_PATH = '/ipfs2filecoin/migrate.md'
 export const RUNBOOK_URL = `${BASE_URL}${RUNBOOK_PATH}`
 
-/** Spec-conformant index for this campaign, pointing at the runbook. */
-export const LLMS_TXT_PATH = '/ipfs2filecoin/llms.txt'
-export const LLMS_TXT_URL = `${BASE_URL}${LLMS_TXT_PATH}`
-
 /** The one line a user hands to a coding agent. Copying it is signal, so it is tracked. */
 export const AGENT_PROMPT = `Migrate my IPFS data to Filecoin: read ${RUNBOOK_URL} and follow it. My CIDs are in cids.txt.`
 
 /**
  * The same instruction with the user's own list inlined, so a checked list is
  * something you can act on rather than just a count. Falls back to the
- * cids.txt form when there is no list yet, which is also the right shape for
- * lists too long to paste into a prompt.
+ * cids.txt form when there is no list yet, or when the list is too long to
+ * belong in a clipboard prompt.
  */
 export function buildAgentPrompt(cids?: ReadonlyArray<string>): string {
-  if (!cids || cids.length === 0) {
+  if (!cids || cids.length === 0 || cids.length > PROMPT_INLINE_CAP) {
     return AGENT_PROMPT
   }
 

From 030bb75d23f98e427ecfa64b0b15910d5bad1060 Mon Sep 17 00:00:00 2001
From: Russell Dempsey <1173416+SgtPooki@users.noreply.github.com>
Date: Mon, 17 Aug 2026 12:56:12 -0400
Subject: [PATCH 14/26] feat(ipfs2filecoin): remove llms.txt routes, the
 runbook at migrate.md is the agent surface

---
 src/app/ipfs2filecoin/llms.txt/route.ts | 47 -------------------------
 src/app/ipfs2filecoin/page.tsx          |  4 +--
 src/app/llms.txt/route.ts               | 46 ------------------------
 3 files changed, 2 insertions(+), 95 deletions(-)
 delete mode 100644 src/app/ipfs2filecoin/llms.txt/route.ts
 delete mode 100644 src/app/llms.txt/route.ts

diff --git a/src/app/ipfs2filecoin/llms.txt/route.ts b/src/app/ipfs2filecoin/llms.txt/route.ts
deleted file mode 100644
index 111cd195..00000000
--- a/src/app/ipfs2filecoin/llms.txt/route.ts
+++ /dev/null
@@ -1,47 +0,0 @@
-import { PATHS } from '@/constants/paths'
-import { BASE_URL, FOC_URLS } from '@/constants/site-metadata'
-
-import {
-  CLI_REPO_URL,
-  MAX_ITEM_SIZE_LABEL,
-  RUNBOOK_PATH,
-} from '../constants/migration'
-
-/**
- * Spec-conformant llms.txt for this campaign: an H1, a blockquote summary, then
- * H2 lists of links. Per llmstxt.org this format is a documentation index, not
- * a procedure, so the procedure lives at migrate.md and this file points to it.
- */
-const LLMS_TXT = `# IPFS to Filecoin
-
-> Move already-pinned IPFS data onto Filecoin warm storage without changing your
-> CIDs. Each CID stays byte-identical and keeps resolving over IPFS. Storage
-> providers prove possession on chain on a schedule.
-
-If you are an agent asked to perform a migration, read the runbook first: it is
-the complete procedure, and the rest of these links are background.
-
-## Do the migration
-
-- [Migration runbook](${BASE_URL}${RUNBOOK_PATH}): the executable procedure — prerequisites, ordered command sequence, stop conditions, and failure modes. Start here.
-- [ipfs2foc](${CLI_REPO_URL}): the CLI the runbook drives, with the full command reference and troubleshooting.
-
-## Background
-
-- [IPFS to Filecoin](${BASE_URL}${PATHS.IPFS_TO_FILECOIN.path}): what this is, what it costs, and what it does not do. Includes a free in-browser CID check.
-- [Warm storage service](${BASE_URL}${PATHS.WARM_STORAGE_SERVICE.path}): the storage product underneath, and its pricing.
-- [Documentation](${FOC_URLS.documentation.home}): Filecoin Onchain Cloud docs.
-
-## Limits
-
-- [Talk to our team](${BASE_URL}${PATHS.CONTACT.path}): for sources that are not reachable from a public gateway, or to agree capacity and timing before a large run. There is no cap on how many CIDs the agent or CLI path can migrate; individual items above ${MAX_ITEM_SIZE_LABEL} cannot be migrated, because splitting them would change their CID.
-`
-
-export function GET() {
-  return new Response(LLMS_TXT, {
-    headers: {
-      'Content-Type': 'text/markdown; charset=utf-8',
-      'Cache-Control': 'public, max-age=0, s-maxage=3600',
-    },
-  })
-}
diff --git a/src/app/ipfs2filecoin/page.tsx b/src/app/ipfs2filecoin/page.tsx
index db233b10..193fb412 100644
--- a/src/app/ipfs2filecoin/page.tsx
+++ b/src/app/ipfs2filecoin/page.tsx
@@ -327,8 +327,8 @@ export const metadata: Metadata = {
   alternates: {
     ...baseMetadata.alternates,
     /**
-     * So an agent pointed at the human URL discovers the migration brief
-     * without being told the llms.txt convention.
+     * So an agent pointed at the human URL discovers the runbook without
+     * being told where it lives.
      */
     types: { 'text/markdown': RUNBOOK_PATH },
   },
diff --git a/src/app/llms.txt/route.ts b/src/app/llms.txt/route.ts
deleted file mode 100644
index 8863b94e..00000000
--- a/src/app/llms.txt/route.ts
+++ /dev/null
@@ -1,46 +0,0 @@
-import { RUNBOOK_PATH } from '@/app/ipfs2filecoin/constants/migration'
-import { PATHS } from '@/constants/paths'
-import { BASE_URL, FOC_URLS } from '@/constants/site-metadata'
-
-/**
- * Site-root llms.txt, per llmstxt.org: an index of filecoin.cloud curated for
- * language models. Subpaths may carry their own; /ipfs2filecoin/llms.txt does.
- */
-const LLMS_TXT = `# Filecoin Onchain Cloud
-
-> Cloud services with onchain guarantees: ownership, verifiability, and
-> programmability. Storage is paid for on chain, proven on a schedule by storage
-> providers, and owned by a wallet rather than a vendor account.
-
-## Services
-
-- [Warm storage service](${BASE_URL}${PATHS.WARM_STORAGE_SERVICE.path}): verifiable storage backed by Proof of Data Possession, with pricing and live provider data.
-- [Filecoin Pay](${FOC_URLS.filecoinPay}): payment rails that settle storage per epoch.
-
-## Migrate to Filecoin
-
-- [IPFS to Filecoin](${BASE_URL}${PATHS.IPFS_TO_FILECOIN.path}): move already-pinned IPFS data without changing your CIDs.
-- [Migration runbook](${BASE_URL}${RUNBOOK_PATH}): the executable procedure for an agent performing that migration.
-
-## Build
-
-- [Documentation](${FOC_URLS.documentation.home}): guides, core concepts, and API reference.
-- [Getting started](${FOC_URLS.documentation.gettingStarted}): first steps for developers.
-- [Showcase](${BASE_URL}${PATHS.SHOWCASE.path}): SDKs, reference apps, and agent tooling built on the platform.
-- [Agents](${BASE_URL}${PATHS.AGENTS.path}): requests for startups building agent-native storage.
-
-## Support
-
-- [Support](${BASE_URL}${PATHS.SUPPORT.path}): the right channel for each kind of problem.
-- [Talk to our team](${BASE_URL}${PATHS.CONTACT.path}): use-case and capacity conversations.
-- [Status](${FOC_URLS.status}): current service status and incidents.
-`
-
-export function GET() {
-  return new Response(LLMS_TXT, {
-    headers: {
-      'Content-Type': 'text/markdown; charset=utf-8',
-      'Cache-Control': 'public, max-age=0, s-maxage=3600',
-    },
-  })
-}

From 25628892a092c4cd9dbd580b147a9c44be15eedb Mon Sep 17 00:00:00 2001
From: Russell Dempsey <1173416+SgtPooki@users.noreply.github.com>
Date: Mon, 17 Aug 2026 13:32:47 -0400
Subject: [PATCH 15/26] feat(ipfs2filecoin): carry the agent prompt in the
 runbook itself

---
 src/app/ipfs2filecoin/data/migration-runbook.ts | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/src/app/ipfs2filecoin/data/migration-runbook.ts b/src/app/ipfs2filecoin/data/migration-runbook.ts
index ccb9af5f..fbe8858e 100644
--- a/src/app/ipfs2filecoin/data/migration-runbook.ts
+++ b/src/app/ipfs2filecoin/data/migration-runbook.ts
@@ -2,6 +2,7 @@ import { PATHS } from '@/constants/paths'
 import { BASE_URL } from '@/constants/site-metadata'
 
 import {
+  AGENT_PROMPT,
   BUFFER_DAYS,
   CLI_PACKAGE,
   CLI_REPO_URL,
@@ -58,6 +59,11 @@ never:
 > rejects a mismatched commitment, so an improvised pipeline fails late and
 > expensively.
 
+If you are a human reading this: you do not have to run the procedure
+yourself. Hand your coding agent this one line and it does the rest.
+
+    ${AGENT_PROMPT}
+
 The migration runs entirely from this machine: download, pack, and upload
 straight to ${COPIES} storage providers. Nothing here requires a public HTTPS
 origin, a tunnel, or inbound connectivity of any kind.

From e9db548277186a022849476022f054daa237f0e2 Mon Sep 17 00:00:00 2001
From: Russell Dempsey <1173416+SgtPooki@users.noreply.github.com>
Date: Thu, 20 Aug 2026 14:32:46 -0400
Subject: [PATCH 16/26] perf(ipfs2filecoin): single-pass CID list parse

---
 src/app/ipfs2filecoin/utils/parse-cid-list.ts | 45 ++++++++++++++-----
 1 file changed, 33 insertions(+), 12 deletions(-)

diff --git a/src/app/ipfs2filecoin/utils/parse-cid-list.ts b/src/app/ipfs2filecoin/utils/parse-cid-list.ts
index 88bd8541..6c8d052c 100644
--- a/src/app/ipfs2filecoin/utils/parse-cid-list.ts
+++ b/src/app/ipfs2filecoin/utils/parse-cid-list.ts
@@ -31,19 +31,40 @@ function normalizeLine(line: string) {
   return trimmed.replace(GATEWAY_PREFIX_PATTERN, '').split(/[?#/]/)[0]
 }
 
+/**
+ * Single pass over the raw text. A pasted list can run to millions of lines,
+ * so the parse never materializes an intermediate array of them: each line is
+ * sliced out, normalized, and folded into the counts before the next one is
+ * looked at. Peak extra memory is the unique set, not a multiple of the input.
+ */
 export function parseCidList(input: string): CidListSummary {
-  const lines = input
-    .split('\n')
-    .map(normalizeLine)
-    .filter((line) => line && !line.startsWith('#'))
+  const uniqueCids: Array<string> = []
+  const seen = new Set<string>()
+  let totalLines = 0
+  let duplicateCount = 0
+  let invalidCount = 0
 
-  const valid = lines.filter((line) => CID_PATTERN.test(line))
-  const uniqueCids = [...new Set(valid)]
-
-  return {
-    totalLines: lines.length,
-    uniqueCids,
-    duplicateCount: valid.length - uniqueCids.length,
-    invalidCount: lines.length - valid.length,
+  let cursor = 0
+  while (cursor <= input.length) {
+    let newline = input.indexOf('\n', cursor)
+    if (newline === -1) {
+      newline = input.length
+    }
+    const line = normalizeLine(input.slice(cursor, newline))
+    cursor = newline + 1
+    if (!line || line.startsWith('#')) {
+      continue
+    }
+    totalLines += 1
+    if (!CID_PATTERN.test(line)) {
+      invalidCount += 1
+    } else if (seen.has(line)) {
+      duplicateCount += 1
+    } else {
+      seen.add(line)
+      uniqueCids.push(line)
+    }
   }
+
+  return { totalLines, uniqueCids, duplicateCount, invalidCount }
 }

From 81f6d5881bde466bd6f3cd3f1d35a936443558a4 Mon Sep 17 00:00:00 2001
From: Russell Dempsey <1173416+SgtPooki@users.noreply.github.com>
Date: Thu, 20 Aug 2026 14:44:05 -0400
Subject: [PATCH 17/26] docs(ipfs2filecoin): steer agents off pre-upgrade data
 sets

---
 src/app/ipfs2filecoin/data/migration-runbook.ts | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/src/app/ipfs2filecoin/data/migration-runbook.ts b/src/app/ipfs2filecoin/data/migration-runbook.ts
index fbe8858e..31ca230f 100644
--- a/src/app/ipfs2filecoin/data/migration-runbook.ts
+++ b/src/app/ipfs2filecoin/data/migration-runbook.ts
@@ -247,6 +247,12 @@ ${CLI_PACKAGE} upload --cids cids.txt --db migrate.db --car-store ./cars --netwo
 - The run is resumable: re-running the same command continues where it
   stopped, never re-uploads what is already committed, and never
   double-commits.
+- The run creates fresh data sets by default, and that is what you want:
+  data sets created before the network's 2026-08-24 contract upgrade miss its
+  gas optimizations, so every commit into one costs more. Only pass
+  \`--data-set-id\` to reuse a set this wallet created after that upgrade;
+  a set's creation date is on its explorer page at
+  \`https://pdp.vxb.ai/\${NETWORK}/dataset/<dataSetId>\`.
 - Staged CARs under \`./cars\` are deleted during the run as each piece's
   copies are all committed. Do not delete them by hand mid-run.
 - \`collected:\` lines mean a provider expired a piece before it was committed;

From e6af50ef4e6f93a851b96ccf9b04863654a932e8 Mon Sep 17 00:00:00 2001
From: Russell Dempsey <1173416+SgtPooki@users.noreply.github.com>
Date: Thu, 20 Aug 2026 17:42:14 -0400
Subject: [PATCH 18/26] docs(ipfs2filecoin): disclose CLI telemetry in runbook

---
 src/app/ipfs2filecoin/data/migration-runbook.ts | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/src/app/ipfs2filecoin/data/migration-runbook.ts b/src/app/ipfs2filecoin/data/migration-runbook.ts
index 31ca230f..5ed9682d 100644
--- a/src/app/ipfs2filecoin/data/migration-runbook.ts
+++ b/src/app/ipfs2filecoin/data/migration-runbook.ts
@@ -120,6 +120,9 @@ spending real funds.
 - Free disk roughly the size of the data being migrated. Stage 4 stages packed
   CAR files under \`--car-store\` and deletes each one as soon as every copy is
   committed onchain.
+- Telemetry: each CLI command reports one anonymous run event, the command
+  name and whether it succeeded — never CIDs, addresses, or paths. Disable
+  with \`DO_NOT_TRACK=1\`, and tell the user if you do.
 
 ### Needed before stage 3, not before
 

From 5a02931bd363e24f7b589b0898b1ab454a0214fe Mon Sep 17 00:00:00 2001
From: Russell Dempsey <1173416+SgtPooki@users.noreply.github.com>
Date: Fri, 21 Aug 2026 12:23:37 -0400
Subject: [PATCH 19/26] feat(ipfs2filecoin): state the list stays in the
 browser

---
 src/app/ipfs2filecoin/components/CidListChecker.tsx | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/src/app/ipfs2filecoin/components/CidListChecker.tsx b/src/app/ipfs2filecoin/components/CidListChecker.tsx
index 9220feba..2233f572 100644
--- a/src/app/ipfs2filecoin/components/CidListChecker.tsx
+++ b/src/app/ipfs2filecoin/components/CidListChecker.tsx
@@ -157,7 +157,8 @@ export function CidListChecker() {
 
           <div className="flex flex-col items-stretch gap-3 border-(--color-border-muted) border-t px-4 py-3 sm:flex-row sm:items-center sm:justify-between sm:gap-x-4">
             <Description className="text-(--color-paragraph-text) text-xs">
-              One per line. Gateway URLs are fine, the prefix is stripped.
+              One per line. Gateway URLs are fine, the prefix is stripped. Your
+              list never leaves the browser; only the count is measured.
             </Description>
             <Button
               type="button"

From 991613f7be02c7a4c18f1a89743806f1b442a4f8 Mon Sep 17 00:00:00 2001
From: Russell Dempsey <1173416+SgtPooki@users.noreply.github.com>
Date: Fri, 21 Aug 2026 12:23:56 -0400
Subject: [PATCH 20/26] fix(ipfs2filecoin): dedupe trust line with the fact
 chips

---
 src/app/ipfs2filecoin/components/CidListChecker.tsx | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/app/ipfs2filecoin/components/CidListChecker.tsx b/src/app/ipfs2filecoin/components/CidListChecker.tsx
index 2233f572..8434f6a3 100644
--- a/src/app/ipfs2filecoin/components/CidListChecker.tsx
+++ b/src/app/ipfs2filecoin/components/CidListChecker.tsx
@@ -157,8 +157,8 @@ export function CidListChecker() {
 
           <div className="flex flex-col items-stretch gap-3 border-(--color-border-muted) border-t px-4 py-3 sm:flex-row sm:items-center sm:justify-between sm:gap-x-4">
             <Description className="text-(--color-paragraph-text) text-xs">
-              One per line. Gateway URLs are fine, the prefix is stripped. Your
-              list never leaves the browser; only the count is measured.
+              One per line. Gateway URLs are fine, the prefix is stripped. Only
+              the count is measured, never the list.
             </Description>
             <Button
               type="button"

From 1475680ffe4c318f15f7a248e85c00316afcaf04 Mon Sep 17 00:00:00 2001
From: Russell Dempsey <1173416+SgtPooki@users.noreply.github.com>
Date: Mon, 24 Aug 2026 12:53:33 -0400
Subject: [PATCH 21/26] fix(ipfs2filecoin): keep the check button on one line

---
 src/app/ipfs2filecoin/components/CidListChecker.tsx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/app/ipfs2filecoin/components/CidListChecker.tsx b/src/app/ipfs2filecoin/components/CidListChecker.tsx
index 8434f6a3..32e519f6 100644
--- a/src/app/ipfs2filecoin/components/CidListChecker.tsx
+++ b/src/app/ipfs2filecoin/components/CidListChecker.tsx
@@ -166,7 +166,7 @@ export function CidListChecker() {
               size="compact"
               onClick={handleCheck}
               disabled={!hasInput}
-              className="w-full sm:w-auto"
+              className="w-full whitespace-nowrap sm:w-auto sm:shrink-0"
             >
               Check my list
               {/* Pointer-only: a shortcut is noise without a modifier key. */}

From b542fd1d5e446ecd950ad89a439ef9fdd209863f Mon Sep 17 00:00:00 2001
From: Russell Dempsey <1173416+SgtPooki@users.noreply.github.com>
Date: Mon, 24 Aug 2026 13:34:58 -0400
Subject: [PATCH 22/26] feat(ipfs2filecoin): apply product-sync feedback

---
 src/app/ipfs2filecoin/constants/migration.ts  |  9 ++++---
 src/app/ipfs2filecoin/data/limits.ts          |  2 +-
 .../ipfs2filecoin/data/migration-runbook.ts   | 10 +++----
 src/app/ipfs2filecoin/data/steps.ts           |  2 +-
 src/app/ipfs2filecoin/page.tsx                | 26 +++++++++----------
 5 files changed, 25 insertions(+), 24 deletions(-)

diff --git a/src/app/ipfs2filecoin/constants/migration.ts b/src/app/ipfs2filecoin/constants/migration.ts
index bdd1cc2c..74b92a5d 100644
--- a/src/app/ipfs2filecoin/constants/migration.ts
+++ b/src/app/ipfs2filecoin/constants/migration.ts
@@ -69,13 +69,14 @@ export const RUNBOOK_PATH = '/ipfs2filecoin/migrate.md'
 export const RUNBOOK_URL = `${BASE_URL}${RUNBOOK_PATH}`
 
 /** The one line a user hands to a coding agent. Copying it is signal, so it is tracked. */
-export const AGENT_PROMPT = `Migrate my IPFS data to Filecoin: read ${RUNBOOK_URL} and follow it. My CIDs are in cids.txt.`
+export const AGENT_PROMPT = `Migrate my IPFS data to Filecoin: read ${RUNBOOK_URL} and follow it.`
 
 /**
  * The same instruction with the user's own list inlined, so a checked list is
- * something you can act on rather than just a count. Falls back to the
- * cids.txt form when there is no list yet, or when the list is too long to
- * belong in a clipboard prompt.
+ * something you can act on rather than just a count. Falls back to the bare
+ * prompt when there is no list yet, or when the list is too long to belong
+ * in a clipboard prompt; the runbook covers getting a list from the pinning
+ * service.
  */
 export function buildAgentPrompt(cids?: ReadonlyArray<string>): string {
   if (!cids || cids.length === 0 || cids.length > PROMPT_INLINE_CAP) {
diff --git a/src/app/ipfs2filecoin/data/limits.ts b/src/app/ipfs2filecoin/data/limits.ts
index d68d01df..343ef156 100644
--- a/src/app/ipfs2filecoin/data/limits.ts
+++ b/src/app/ipfs2filecoin/data/limits.ts
@@ -7,7 +7,7 @@ export const limits = [
   {
     title: 'Your source has to be publicly readable',
     description:
-      'Each CID is fetched through a public gateway that serves verifiable content. Private pinning accounts, authenticated endpoints, and custom storage are not reachable this way, so those go through the contact form.',
+      'Each CID has to be retrievable from the public IPFS network; the migration fetches it through a public gateway that serves verifiable content. Private pinning accounts, authenticated endpoints, and custom storage are not reachable this way, so those go through the contact form.',
   },
   {
     title: `${MAX_ITEM_SIZE_LABEL} per item`,
diff --git a/src/app/ipfs2filecoin/data/migration-runbook.ts b/src/app/ipfs2filecoin/data/migration-runbook.ts
index 5ed9682d..e3eaa072 100644
--- a/src/app/ipfs2filecoin/data/migration-runbook.ts
+++ b/src/app/ipfs2filecoin/data/migration-runbook.ts
@@ -106,16 +106,16 @@ If you cannot install globally, prefix **every** command in this document with
 Set the network once and pass it to every on-chain command:
 
 \`\`\`bash
-NETWORK=mainnet        # or: NETWORK=calibration, to rehearse on the testnet
+NETWORK=mainnet
 \`\`\`
 
-Rehearsing the whole flow on calibration first is strongly recommended before
-spending real funds.
-
 ### Needed now (stages 1-2)
 
 - Node 24 or newer. Hard requirement. Check with \`node --version\`.
-- A CID list, one per line. Blank lines and \`#\` comments are ignored.
+- A CID list, one per line, saved as \`cids.txt\`. Blank lines and \`#\` comments
+  are ignored. If the user does not have a list, get it from their pinning
+  service first: dashboards export pinned CIDs, and services implementing the
+  IPFS Pinning Service API list them at its \`/pins\` endpoint.
 - A trustless gateway that serves deterministic CARs. Stage 1 verifies this.
 - Free disk roughly the size of the data being migrated. Stage 4 stages packed
   CAR files under \`--car-store\` and deletes each one as soon as every copy is
diff --git a/src/app/ipfs2filecoin/data/steps.ts b/src/app/ipfs2filecoin/data/steps.ts
index cb576c16..ebdd0c38 100644
--- a/src/app/ipfs2filecoin/data/steps.ts
+++ b/src/app/ipfs2filecoin/data/steps.ts
@@ -3,7 +3,7 @@ export const steps = [
     number: '01',
     title: 'Hand over the list',
     description:
-      'Give your agent a cids.txt, or paste a list here first to see what you are dealing with. Checking costs nothing.',
+      'Paste a list here to see what you are dealing with, or let your agent pull it straight from your pinning service, whose dashboard and API list every pinned CID. Checking costs nothing.',
   },
   {
     number: '02',
diff --git a/src/app/ipfs2filecoin/page.tsx b/src/app/ipfs2filecoin/page.tsx
index 193fb412..cd549a15 100644
--- a/src/app/ipfs2filecoin/page.tsx
+++ b/src/app/ipfs2filecoin/page.tsx
@@ -86,6 +86,16 @@ export default function IpfsToFilecoin() {
       </div>
 
       <PageSection backgroundVariant="gray">
+        <SectionContent
+          headingTag="h2"
+          title="How it works"
+          description="Four steps, and the first two are free."
+        >
+          <StepList steps={steps} />
+        </SectionContent>
+      </PageSection>
+
+      <PageSection backgroundVariant="light">
         <SectionContent
           headingTag="h2"
           title="Why move to Filecoin warm storage"
@@ -110,7 +120,7 @@ export default function IpfsToFilecoin() {
         </SectionContent>
       </PageSection>
 
-      <PageSection backgroundVariant="light">
+      <PageSection backgroundVariant="gray">
         <SectionContent
           headingTag="h2"
           title="What it costs"
@@ -169,16 +179,6 @@ export default function IpfsToFilecoin() {
         </SectionContent>
       </PageSection>
 
-      <PageSection backgroundVariant="gray">
-        <SectionContent
-          headingTag="h2"
-          title="How it works"
-          description="Four steps, and the first two are free."
-        >
-          <StepList steps={steps} />
-        </SectionContent>
-      </PageSection>
-
       <PageSection backgroundVariant="dark">
         <SectionContent
           headingTag="h2"
@@ -237,8 +237,8 @@ export default function IpfsToFilecoin() {
                 Talk to us
               </Heading>
               <p className="text-(--color-paragraph-text)">
-                For sources that are not reachable from a public gateway, or to
-                agree capacity and timing before a run over{' '}
+                For sources that are not reachable from the public IPFS network,
+                or to agree capacity and timing before a run over{' '}
                 {COORDINATION_VOLUME_LABEL}. That is coordination, not a
                 ceiling: the agent path has no cap on how many CIDs it migrates.
               </p>

From 0d558adcc3e613179b25579d33a14d751f475d14 Mon Sep 17 00:00:00 2001
From: Russell Dempsey <1173416+SgtPooki@users.noreply.github.com>
Date: Mon, 24 Aug 2026 13:55:51 -0400
Subject: [PATCH 23/26] feat(ipfs2filecoin): lead with the agent prompt

---
 .../ipfs2filecoin/components/AgentPrompt.tsx  |  2 +-
 src/app/ipfs2filecoin/page.tsx                | 25 +++++++++++++++++--
 2 files changed, 24 insertions(+), 3 deletions(-)

diff --git a/src/app/ipfs2filecoin/components/AgentPrompt.tsx b/src/app/ipfs2filecoin/components/AgentPrompt.tsx
index c83bd1a9..660e4296 100644
--- a/src/app/ipfs2filecoin/components/AgentPrompt.tsx
+++ b/src/app/ipfs2filecoin/components/AgentPrompt.tsx
@@ -10,7 +10,7 @@ import { buildAgentPrompt, PLAUSIBLE_EVENTS } from '../constants/migration'
 
 type AgentPromptProps = {
   /** Where on the page the prompt was copied from, so the two spots stay distinguishable. */
-  source: 'verdict' | 'agent-door'
+  source: 'hero' | 'verdict' | 'agent-door'
   /**
    * The user's checked list. When present it is inlined into the prompt so the
    * copied line carries the actual CIDs instead of pointing at a cids.txt the
diff --git a/src/app/ipfs2filecoin/page.tsx b/src/app/ipfs2filecoin/page.tsx
index cd549a15..44ad5395 100644
--- a/src/app/ipfs2filecoin/page.tsx
+++ b/src/app/ipfs2filecoin/page.tsx
@@ -79,8 +79,25 @@ export default function IpfsToFilecoin() {
             title="Move your pinned IPFS data to Filecoin"
             description="Same CIDs, a fraction of what pinning services charge, and an onchain receipt you can verify yourself."
           />
-          <div className="mt-10">
-            <CidListChecker />
+          {/*
+            The agent prompt is the page's terminal state, so it leads. The
+            checker moved beside the estimator: paste and estimate are one
+            interaction, and this link is the path down to it.
+          */}
+          <div className="mx-auto mt-10 max-w-2xl space-y-4">
+            <p className="text-center text-(--color-paragraph-text)">
+              Give this line to Claude Code, Cursor, or any coding agent. It
+              reads the runbook, works through your list, and reports back what
+              landed.
+            </p>
+            <AgentPrompt source="hero" />
+            <p className="text-center text-(--color-paragraph-text) text-sm/relaxed">
+              It signs from a key you provide and can spend up to your deposit,
+              so use a wallet kept for this migration and nothing else.{' '}
+              <SmartTextLink href="#check">
+                Or check your list first: free, in your browser.
+              </SmartTextLink>
+            </p>
           </div>
         </PageSection>
       </div>
@@ -133,6 +150,10 @@ export default function IpfsToFilecoin() {
             costs"; stacked below that, where a 2fr/1fr split leaves the table
             too narrow to hold its columns.
           */}
+          <div id="check" className="mx-auto mb-12 max-w-2xl scroll-mt-24">
+            <CidListChecker />
+          </div>
+
           <div className="grid gap-8 lg:grid-cols-3 lg:items-start">
             <div className="space-y-6 lg:col-span-2">
               <ComparisonTable />

From 31227d1fe73b225b3e579b0b1278a396f6ae88a0 Mon Sep 17 00:00:00 2001
From: Russell Dempsey <1173416+SgtPooki@users.noreply.github.com>
Date: Mon, 24 Aug 2026 14:51:48 -0400
Subject: [PATCH 24/26] fix(ipfs2filecoin): close with the promised actions

---
 src/app/ipfs2filecoin/data/steps.ts | 2 +-
 src/app/ipfs2filecoin/page.tsx      | 9 ++-------
 2 files changed, 3 insertions(+), 8 deletions(-)

diff --git a/src/app/ipfs2filecoin/data/steps.ts b/src/app/ipfs2filecoin/data/steps.ts
index ebdd0c38..c571d67e 100644
--- a/src/app/ipfs2filecoin/data/steps.ts
+++ b/src/app/ipfs2filecoin/data/steps.ts
@@ -15,7 +15,7 @@ export const steps = [
     number: '03',
     title: 'Fund it, once',
     description:
-      'Connect a wallet, deposit USDFC, approve spending. Use a wallet you keep for this and deposit what the migration needs, because that amount is also the most anything can spend.',
+      'Deposit USDFC and approve spending, from a wallet you keep for this migration. Deposit what the run needs, because that amount is also the most anything can spend.',
   },
   {
     number: '04',
diff --git a/src/app/ipfs2filecoin/page.tsx b/src/app/ipfs2filecoin/page.tsx
index 44ad5395..1e80a5c6 100644
--- a/src/app/ipfs2filecoin/page.tsx
+++ b/src/app/ipfs2filecoin/page.tsx
@@ -16,7 +16,6 @@ import { Navigation } from '@/components/Navigation/Navigation'
 import { StructuredDataScript } from '@/components/StructuredDataScript'
 
 import { PATHS } from '@/constants/paths'
-import { FOC_URLS } from '@/constants/site-metadata'
 import { createMetadata } from '@/utils/create-metadata'
 
 import { AgentPrompt } from './components/AgentPrompt'
@@ -315,12 +314,8 @@ export default function IpfsToFilecoin() {
           title="Find out what your archive costs before you move it"
           description="Checking is free and needs nothing but a list. You get a real number and the one line that hands the job to your agent."
           cta={[
-            <Button
-              key="read-the-brief"
-              href={FOC_URLS.documentation.gettingStarted}
-              variant="primary"
-            >
-              Read the docs
+            <Button key="check-my-list" href="#check" variant="primary">
+              Check my list free
             </Button>,
             <Button
               key="talk-to-us"

From 65760e4e9d63d281c0ab56b142c751a61db82db7 Mon Sep 17 00:00:00 2001
From: Russell Dempsey <1173416+SgtPooki@users.noreply.github.com>
Date: Mon, 24 Aug 2026 14:57:24 -0400
Subject: [PATCH 25/26] chore(ipfs2filecoin): point prompt at the preview

---
 src/app/ipfs2filecoin/constants/migration.ts | 11 +++++++++--
 1 file changed, 9 insertions(+), 2 deletions(-)

diff --git a/src/app/ipfs2filecoin/constants/migration.ts b/src/app/ipfs2filecoin/constants/migration.ts
index 74b92a5d..9d4ad0d6 100644
--- a/src/app/ipfs2filecoin/constants/migration.ts
+++ b/src/app/ipfs2filecoin/constants/migration.ts
@@ -1,4 +1,3 @@
-import { BASE_URL } from '@/constants/site-metadata'
 
 /**
  * Above this, the copied agent prompt points at a downloaded cids.txt instead
@@ -66,7 +65,15 @@ export const BUFFER_DAYS = 30
  * procedure an agent follows, not a documentation index.
  */
 export const RUNBOOK_PATH = '/ipfs2filecoin/migrate.md'
-export const RUNBOOK_URL = `${BASE_URL}${RUNBOOK_PATH}`
+/**
+ * TEMPORARY, REMOVE BEFORE MERGE (tracked in the PR checklist): the copied
+ * prompt points at the branch preview so testers can run the flow end to end.
+ * filecoin.cloud/ipfs2filecoin/migrate.md does not exist until this PR merges,
+ * so a prod URL here sends every tester's agent into a 404.
+ */
+const PREVIEW_BASE_URL =
+  'https://filecoin-cloud-git-feat-ipfs2filecoin-landing-page-filoz.vercel.app'
+export const RUNBOOK_URL = `${PREVIEW_BASE_URL}${RUNBOOK_PATH}`
 
 /** The one line a user hands to a coding agent. Copying it is signal, so it is tracked. */
 export const AGENT_PROMPT = `Migrate my IPFS data to Filecoin: read ${RUNBOOK_URL} and follow it.`

From d4c2d91ea8de17f564e8a0706564893ed721e047 Mon Sep 17 00:00:00 2001
From: Russell Dempsey <1173416+SgtPooki@users.noreply.github.com>
Date: Mon, 24 Aug 2026 19:26:11 -0400
Subject: [PATCH 26/26] fix(ipfs2filecoin): drop the last testnet mention

---
 src/app/ipfs2filecoin/data/migration-runbook.ts | 1 -
 1 file changed, 1 deletion(-)

diff --git a/src/app/ipfs2filecoin/data/migration-runbook.ts b/src/app/ipfs2filecoin/data/migration-runbook.ts
index e3eaa072..74105110 100644
--- a/src/app/ipfs2filecoin/data/migration-runbook.ts
+++ b/src/app/ipfs2filecoin/data/migration-runbook.ts
@@ -310,7 +310,6 @@ every affected CID rather than dropping it.
 ## Links
 
 - Tool, full command reference, and troubleshooting: ${CLI_REPO_URL}
-- Rehearse on the testnet first: \`docs/tutorial-first-migration.md\` in that repo
 - Landing page: ${LANDING_URL}
 - Talk to the team about capacity: ${CONTACT_URL}
 - This runbook: ${BASE_URL}${RUNBOOK_PATH}