Small-Business → AT Protocol Migration Toolkit — Research Brief
0
Migration_Toolkit_research.md
1# Migration_Toolkit_research.md
2## Small-Business → AT Protocol Migration Toolkit — Research Brief
3
4*Seed document for a new project chat · Derived from the AT Protocol Ecosystem Repository Analysis (2026-08-12)*
5
6## 1. The Opportunity
7
8[ptharbor](https://tangled.org/psingletary.com/ptharbor) is an existence proof: a real small business (Point Harbor Signs) was migrated off Weebly onto a fully AT Protocol–native stack, and its README explicitly frames itself as "a repeatable blueprint for migrating small businesses off Facebook/Instagram/WordPress/Wix to AT Protocol." But every step was manual: hand-ported HTML, hand-run key-generation and deploy scripts, hand-written did:web documents. **The toolkit's job is to turn that blueprint into an automated, repeatable pipeline.**
9
10## 2. The Proven Reference Architecture (from ptharbor)
11
12| Layer | ptharbor's choice | Notes |
13|---|---|---|
14| Website hosting | wisp.place (PDS-based static hosting) | Site files stored as PDS blobs, signed manifest, CDN cache invalidated via firehose |
15| Identity | did:web (`did-web/` dir, did.json served at the business domain) | Alternative: did:plc |
16| PDS | Protobase.at (managed PDS) | Business doesn't self-host |
17| Code hosting | Tangled (ATProto-native git) | |
18| Domain | Marque.at (registrar) | Optional layer |
19| Site itself | Plain static HTML, no framework | Ported from Weebly |
20
21## 3. What the Toolkit Must Automate (pipeline stages)
22
231. **Scrape/export** — pull the existing site from Weebly/Wix/WordPress/Squarespace/Facebook Pages. WordPress has XML export; Wix/Weebly/FB generally require crawling the rendered site.
242. **Static port** — normalize scraped output into clean static HTML/CSS; strip builder junk (tracking scripts, builder CSS bloat); rewrite internal links; generate `_redirects` for old URL structures (wisp.place supports `_redirects` and `.wispignore` — confirmed in the [wisp.place monorepo](https://tangled.org/nekomimi.pet/wisp.place-monorepo)).
253. **Identity setup** — generate did:web document (did.json) for the business domain, or register a did:plc; produce DNS instructions (`_atproto` TXT record for handle verification).
264. **PDS provisioning** — guided checklist for a managed PDS (Protobase.at or similar) or self-host option; account creation, handle = business domain.
275. **Deploy** — push the ported site to wisp.place via `wispctl` / `npm create wisp` (both confirmed as the official deploy paths in the wisp.place monorepo).
286. **Repo setup** — init a Tangled repo for the site source; optionally emit a `.tangled/workflows/deploy.yml` Spindle workflow so future pushes auto-deploy (Spindle supports push-triggered YAML pipelines with repo secrets — see [Tangled Spindle docs](https://docs.tangled.org/spindles); note: a deploy-to-wisp workflow template does not yet exist publicly and would be a novel contribution).
297. **Verification** — post-deploy checks: site up, did.json resolves, handle verifies, redirects work. (Pattern precedent: atprotozoa's `audit/` health-check scripts.)
30
31## 4. Recommended Tech Stack (evidence-based, from ecosystem rankings)
32
33- **Language:** TypeScript — the #1 language in the analyzed ecosystem (4/9 repos), and the language of wisp.place's own tooling.
34- **Runtime:** Bun — used by airglow; fast single-binary CLI story.
35- **Form factor:** CLI (`npx create-atproto-migration` style) + a template repo on Tangled. Matches wisp.place's own `npm create wisp` convention.
36- **ATProto access:** prefer light/vendorable libs over heavy SDKs for the CLI (ecosystem norm: hand-rolled `oauth.js`/`identity.js`; infra projects use real libs — wisp's Rust CLI uses [Jacquard](https://tangled.org/@nonbinary.computer/jacquard)). For TS: atcute or `@atproto/api` for `uploadBlob`/`putRecord` calls if not shelling out to `wispctl`.
37- **Scraping:** headless fetch + HTML rewriting (e.g. cheerio/linkedom); WordPress XML importer as a fast path.
38- **No backend needed** — the entire pipeline is local CLI + PDS writes, consistent with the ecosystem's static-first pattern.
39
40## 5. Known Constraints & Open Questions
41
42- **wisp.place limits:** file-size/blob limits per PDS, manifest size, supported MIME types — need to verify against the wisp.place monorepo source (`apps/main-app`, `cli/`); README-level docs confirmed only `.wispignore` and `_redirects`.
43- **did:web vs did:plc:** did:web ties identity to the domain (good for businesses, breaks if domain lapses); did:plc is portable. Toolkit should support both and explain the tradeoff.
44- **Scraping legality/ToS:** exporting one's own site is fine; automated crawling of Wix/Weebly may hit anti-bot measures — need per-platform export strategies.
45- **Dynamic features:** contact forms, e-commerce, booking widgets don't port to static hosting. Scope v1 to brochure sites; document escape hatches (formsubmit-style services, or a companion Worker).
46- **PDS provisioning API:** does Protobase.at expose programmatic account creation, or is this stage necessarily a human checklist? Unverified.
47- **Spindle runner availability:** Spindle CI requires a self-hosted runner; the auto-deploy stage (§3.6) should degrade gracefully to manual `wispctl deploy`.
48
49## 6. Competitive Landscape (from the analysis)
50
51- No tool in the analyzed set automates any of this; ptharbor is the only migration artifact and it is fully manual.
52- wisp.place provides deploy tooling (`wispctl`, `npm create wisp`) but nothing for *sourcing* content from legacy platforms.
53- Broader ecosystem: no known "Wix-to-ATProto" tool exists; adjacent prior art is WordPress→static exporters (Simply Static, wp2static) which solve only stage 2.
54
55## 7. Suggested First Milestones
56
571. **M0 — Manual playbook:** write the ptharbor process as a step-by-step doc; validates the pipeline before automating.
582. **M1 — `wisp-port` CLI:** scrape URL → clean static bundle → `_redirects` → `wispctl deploy`. (Stages 1, 2, 5.)
593. **M2 — Identity module:** did:web generator + DNS instruction output + verification checks. (Stages 3, 7.)
604. **M3 — Full `create-atproto-migration` wizard:** interactive CLI covering all 7 stages, Tangled repo + Spindle template emission.