socai-site-deployment
Skill257 starsChanged 50 days agoApache-2.0View on GitHub
Deploy, configure, troubleshoot, and verify the socai marketing/download website on Vercel. Use for socai.io deployments, Vercel project settings, domain/redirect checks, Git preview setup, /download and /github redirect validation, and deployment runbooks for the site/ Astro app.
- Installs packages
In this repository6 other files it gives its agents.
- AGENTS.mdAGENTS.md
- clean-targetsSkill
- socai-model-syncSkill
- socai-releaseSkill
- rsiSkill
- socai-cliSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
16 rules. About 0 are common, 10 are distinctive, and 6 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈10
Distinctive · estimate
This author's own choices. Worth a look.
6
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 8
Use this skill whenever the task involves the socai website deployment, Vercel configuration, socai.io, www.socai.io, /download, /github, …
- Very specific: line 38
Use the socai-d83824c8 scope for all Vercel project/domain commands.
- Distinctive: line 39
Do not deploy from the wrong Vercel team or a personal project.
- Very specific: line 40
Do not commit site/.vercel/, site/dist/, site/.astro/, or site/node_modules/.
- Distinctive: line 41
Do not enable analytics unless the user explicitly approves it.
- Distinctive: line 42
Do not edit app release assets while doing website deployment work.
- Distinctive: line 43
Keep issue work on a dedicated branch and open/update a PR for repo changes.
- Distinctive: line 44
If you temporarily change Vercel project settings for a manual deploy, restore them before finishing.
- Distinctive: line 48
Before deploying or opening a PR for deployment-related code/config:
- Distinctive: line 87
Verify production URLs with the commands below.
- Distinctive: line 128
After the deploy, confirm the root directory was restored:
- Very specific: line 134
Do not leave the project with Root Directory .
- Distinctive: line 138
Use HEAD checks first:
- Very specific: line 160
Use -L only when you want to follow the chain:
- Very specific: line 205
Ensure the latest production deployment includes the host redirect in site/vercel.json, then redeploy.
- Distinctive: line 217
When reporting a deployment task, include:
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
socai site deployment
Use this skill whenever the task involves the socai website deployment, Vercel configuration, socai.io, www.socai.io, /download, /github, or PR preview deployments.
This skill is the source-of-truth deployment runbook. ../../../docs/website-deployment.md intentionally stays brief and points back here to avoid duplicate instructions drifting.
Project context
- Website source:
site/ - Framework: Astro static site
- Vercel team/scope:
socai-d83824c8(socai) - Vercel project:
socai-site - Production domain:
https://socai.io - Documentation route:
https://socai.io/docs/(Starlight pages built with the Astro site) - Canonical host:
socai.io wwwbehavior:https://www.socai.io/*should 308/redirect tohttps://socai.io/*- Download route:
https://socai.io/downloadredirects to the latest universal macOS DMG on the socai OSS release mirror - GitHub route:
https://socai.io/githubredirects tohttps://github.com/socai-io/socai
Expected Vercel project settings:
| Setting | Value |
| Framework preset | Astro |
| Root directory | site |
| Install command | pnpm install |
| Build command | pnpm build |
| Output directory | dist |
| Node.js version | 24.x |
Safety rules
- Use the
socai-d83824c8scope for all Vercel project/domain commands. - Do not deploy from the wrong Vercel team or a personal project.
- Do not commit
site/.vercel/,site/dist/,site/.astro/, orsite/node_modules/. - Do not enable analytics unless the user explicitly approves it.
- Do not edit app release assets while doing website deployment work.
- Keep issue work on a dedicated branch and open/update a PR for repo changes.
- If you temporarily change Vercel project settings for a manual deploy, restore them before finishing.
Local validation
Before deploying or opening a PR for deployment-related code/config:
cd site
pnpm install
pnpm buildValidate JSON/XML config when touched:
python3 -m json.tool site/vercel.json >/dev/null
python3 -m json.tool site/public/site.webmanifest >/dev/null
python3 - <<'PY'
import xml.etree.ElementTree as ET
ET.parse('site/dist/sitemap-index.xml')
ET.parse('site/dist/sitemap-0.xml')
PYInspect Vercel state
vercel whoami
vercel teams ls
vercel projects ls --scope socai-d83824c8
vercel project inspect socai-site --scope socai-d83824c8 --yes
vercel domains inspect socai.io --scope socai-d83824c8
vercel domains inspect www.socai.io --scope socai-d83824c8Confirm project settings show root directory site, framework Astro, build command pnpm build, output dist, install pnpm install.
Preferred production deployment
Preferred path after Git integration is enabled:
- Merge website changes to
main. - Let Vercel build the
socai-siteproject from root directorysite. - Verify production URLs with the commands below.
PR previews also require Git integration to be connected in the Vercel dashboard.
Emergency/manual CLI production deployment
Because the Vercel project is configured with root directory site, a direct local deploy from site/ can fail with site/site root-directory errors. If Git integration is not available and a CLI deploy is required, use this temporary-root workaround and restore root directory afterward.
set -euo pipefail
cat > /tmp/vercel-root-null.json <<'EOF'
{
"rootDirectory": null
}
EOF
cat > /tmp/vercel-root-site.json <<'EOF'
{
"rootDirectory": "site"
}
EOF
restore_root() {
vercel api /v10/projects/socai-site \
--scope socai-d83824c8 \
-X PATCH \
--input /tmp/vercel-root-site.json \
--silent || true
}
trap restore_root EXIT
vercel api /v10/projects/socai-site \
--scope socai-d83824c8 \
-X PATCH \
--input /tmp/vercel-root-null.json \
--silent
cd site
vercel deploy --prod --scope socai-d83824c8 --project socai-site --yesAfter the deploy, confirm the root directory was restored:
vercel project inspect socai-site --scope socai-d83824c8 --yesDo not leave the project with Root Directory . or null; Git previews depend on site.
URL verification
Use HEAD checks first:
curl -I https://socai.io/
curl -I https://socai.io/docs/
curl -I https://socai.io/docs/quickstart/
curl -I https://www.socai.io/
curl -I https://socai.io/sitemap.xml
curl -I https://socai.io/sitemap-index.xml
curl -I https://socai.io/download
curl -I https://socai.io/githubExpected first-hop behavior:
https://socai.io/returns200.https://socai.io/docs/returns200, and a nested page such as/docs/quickstart/returns200.https://www.socai.io/returns308withlocation: https://socai.io/.https://socai.io/sitemap.xmlpermanently redirects to/sitemap-index.xml, which returns200.https://socai.io/downloadreturns a Vercel redirect (307) to the latest universal macOS DMG on the configured OSS release mirror.https://socai.io/githubreturns a Vercel redirect (307) tohttps://github.com/socai-io/socai.
Use -L only when you want to follow the chain:
curl -I -L --max-time 30 -o /dev/null -w 'code=%{http_code}\nfinal=%{url_effective}\n' https://socai.io/downloadGit preview setup
Try:
cd site
vercel link --yes --scope socai-d83824c8 --project socai-site
vercel git connect https://github.com/socai-io/socai --scope socai-d83824c8If Vercel returns:
Failed to link socai-io/socai. You need to add a Login Connection to your GitHub account first.then a Vercel/GitHub account owner must connect the GitHub login/integration in the Vercel dashboard, then connect socai-site to socai-io/socai with root directory site.
Troubleshooting
Website changes skipped after a multi-commit push
The ignored build step in site/vercel.json must compare HEAD against
VERCEL_GIT_PREVIOUS_SHA (the last successful deployment for this project and
branch), not HEAD^. The final commit in a push can change only Rust code while
earlier commits change the website. If the previous deployment SHA is missing
or unavailable in the shallow clone, build rather than skip. Exit 0 skips a
build; exit 1 proceeds.
Root Directory "site" does not exist
This usually happens when running local CLI deploy from site/ while the remote project also has root directory site. Use the emergency/manual CLI deployment workaround above, or prefer Git deployments.
Too many files uploaded
Deploying from the repo root can include Rust/Python build artifacts and exceed Vercel's file count. Do not deploy the repo root directly unless you have a tested ignore/archive strategy. Prefer Git deployments or the emergency/manual deploy from site/ with temporary root reset.
www.socai.io serves 200 instead of redirecting
Ensure the latest production deployment includes the host redirect in site/vercel.json, then redeploy. Verify with:
curl -I https://www.socai.io/GitHub latest release metadata is unavailable
The website should still show generic non-stale copy (latest release) and /download should still redirect to GitHub's latest release asset.
Reporting back
When reporting a deployment task, include:
- Branch/PR if repo files changed
- Vercel project settings confirmed
- Deployment URL and production domain
- Commands run
- Verification output summary for
/,/docs/,/docs/quickstart/,www,/download, and/github - Any remaining manual blockers, especially Git integration / PR previews
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

