For end users

I already have a site on Vercel + GitHub. How do I replace it (or add to it) with Pectus?

Common scenario: you already have a site (Astro, Next.js, whatever) deployed via Vercel from a GitHub repo, and you want Pectus to take over the same domain. Or you want to add a Pectus-managed section (like /insights/) to a site you’re keeping intact. Both are supported. The decisions all happen on the Content Insights settings page at step 11.

You don’t merge anything

The Vercel and GitHub tokens you create at install (steps 5 and 8) are account-level: one token works for your whole Vercel account, one auth covers all your GitHub repos. Pectus doesn’t pick a project or repo until you activate the Content Insights app from /apps in the CMS (step 11). So the install flow up to step 11 is identical whether you’re starting fresh or replacing an existing site.

The decision: which GitHub repo Pectus commits to

Two paths:

A. Reuse your existing repo

Pectus commits its content-insights structure (Astro app, layouts, content collection, generated pages) directly into the repo you’re already deploying. Your current site code gets replaced. Back up to a branch first so you can roll back:

git checkout -b archive-pre-pectus
git push origin archive-pre-pectus
git checkout main

Vercel keeps deploying from the same repo. Your domain mapping doesn’t change. Roll back: reset main to the archive branch, force-push, redeploy.

B. Use a new repo (recommended)

Create a fresh GitHub repo (e.g. yoursite-pectus). On the Content Insights settings page, give Pectus that repo’s owner/name. After install, in the Vercel project that serves your existing domain, change the git source from your old repo to the new one (Vercel project → Settings → Git → Connected Git Repository). Your old repo stays as a frozen archive at its current GitHub URL. Roll back: change the Vercel git source back to the old repo.

Pick B. The cutover is one Vercel setting toggle. Your old site stays inspectable. The Pectus repo and your old repo never intermix.

Site shape on the Content Insights settings page

If you want Pectus to replace the whole site: pick “Brand new site”. Mount slug stays /. Pectus owns the whole domain.

If you want Pectus to add a section to a site you’re keeping: pick “Existing site”. Mount slug becomes something like /insights/ or /blog/. Your existing site keeps serving everything else; Pectus pages live under the chosen sub-path. (More fiddly because routing has to be split between two systems; only pick this if keeping the existing site intact is the priority.)

You can change either of these later from Workspace → Content Insights → Site URL. The settings page is just where you set them the first time.

Bringing your existing posts across

After install, open the CMS, go to your workspace’s Articles page, and click Import. Paste your existing sitemap URL (e.g. https://yoursite.com/sitemap.xml) and an optional path filter (like /blog/ if you only want articles from that section). Pectus pulls the URLs into its content model. From there you pick which to publish back out through Pectus and which to leave behind.

Do this before letting Pectus publish anything new. Otherwise you risk the new content overwriting URLs that were live without Pectus knowing to generate redirects.