docs(deploy): document POST /deploy/new ?redeploy=true for in-place updates

[mastermanas805]

Summary

• Closes the agent-UX gap that makes POST /deploy/new repeatedly mint a fresh app_id + URL when an agent ships v2 of an existing app. The parallel api PR adds a redeploy=true multipart form field; this PR documents it on every agent-facing surface so an agent reading the docs discovers the flag before falling back to two POST /deploy/new calls and ending up with two parallel deployments + two distinct URLs (the customer complaint that triggered this swarm).
• Adds a cross-repo lock-step guard (scripts/fetch-content.mjs) that preserves the committed public/llms.txt when the upstream content repo's copy still lacks the new markers — so the docs PR is safe to land first.
• Adds a registry-iterating regression test (src/lib/llmsContract.test.ts, CLAUDE.md rule 18) so a future content sync that silently drops the redeploy guidance fails CI by file + field name.

Files changed (5)

File	What
public/llms.txt	Inline redeploy=true note on the POST /deploy/new bullet (sub-bullet under the existing endpoint description so it can't be skipped by agents grep-ing the file).
public/llms-full.txt	New ### POST /deploy/new section with both first-deploy and redeploy curl flows, full 202 response with redeployed field, 404 no_matching_deployment shape, and an explicit deprecation note steering agents AWAY from the POST /deploy/:id/redeploy endpoint (which is the dashboard internal).
src/pages/ForAgentsPage.tsx	5th reason card 05 · in-place app updates so an agent landing on /for-agents sees the redeploy story at a glance.
scripts/fetch-content.mjs	New requireMarkers field on SYNC_FILES. When the upstream .content/llms.txt is missing every listed marker (redeploy=true, "redeployed":), the script preserves the committed public/llms.txt instead of overwriting it. Prints a WARNING that goes away once the content-repo PR lands.
src/lib/llmsContract.test.ts	NEW. Registry-driven test iterating a CONTRACT_MARKERS list, one it() per (file, field) row, so a failure names the surface AND the field. Currently asserts both llms.txt and llms-full.txt document redeploy=true, "redeployed":, and no_matching_deployment.

Coverage block (rule 17)

Symptom:        agent calls POST /deploy/new twice with same name and
                ends up with two URLs, slot count + 1
Enumeration:    rg -nF '/deploy/new' public/ src/pages/
                rg -nF 'redeploy'    public/ src/pages/
Sites found:    4 agent-facing surfaces in instanode-web
                (llms.txt, llms-full.txt, ForAgentsPage.tsx, DocsPage.tsx)
Sites touched:  3 (llms.txt, llms-full.txt, ForAgentsPage.tsx)
                DocsPage.tsx is a pure markdown renderer — its content
                lives in InstaNode-dev/content/docs/deploy.md, which is
                handled by the cross-repo follow-up below.
Coverage test:  src/lib/llmsContract.test.ts — fails if either
                llms file silently drops the redeploy guidance.
Live verified:  awaiting api-PR deploy. Docs are additive and safe to
                land first; the flag returns 400 against today's live
                /deploy/new until the api PR ships, so the docs do not
                lie about a working endpoint until the matched-pair lands.

Cross-repo dependencies (NOT BLOCKING this PR — docs are additive)

Repo	PR / action	Status
InstaNode-dev/api	Add redeploy bool multipart field on POST /deploy/new, return redeployed: bool in the response, 404 no_matching_deployment when no team-scoped match.	parallel work — track separately
InstaNode-dev/mcp	Add redeploy: boolean to create_deploy tool input. Retire the broken standalone redeploy(id) tool that sends body: undefined against /deploy/:id/redeploy and always 400s.	parallel work — track separately
InstaNode-dev/content	Mirror the public/llms.txt edit in content/llms.txt. The canonical /llms.txt lives in the content repo (per CLAUDE.md memory project_repo_topology.md). scripts/fetch-content.mjs preserves the local copy until then. Open a follow-up issue + PR in the content repo. Also mirror the .content/docs/deploy.md update to surface the flag on the /docs page.
InstaNode-dev/web	web/docs/api-reference.md (separate marketing docs repo) currently documents /stacks/:slug/redeploy only. Follow-up PR to add a POST /deploy/new request-body table row for redeploy + a "Redeploying an app" subsection.

Discipline

• Branch: docs/deploy-new-redeploy-param (cut from origin/main, not coverage/raise-to-95).
• Default branch confirmed: main (instanode-web, not master).
• npm run gate green locally (tsc --noEmit && npm run build && vitest run): 78 test files, 1091 passed, 3 skipped, 45s.
• No --admin, no --no-verify, no force-push.

Test plan

• CI build-and-test job green
• CI playwright job green
• CI up-to-date-with-base job green
• src/lib/llmsContract.test.ts reports 3 passing test cases
• npm run prebuild prints the WARNING — upstream .content/llms.txt is missing required markers line (proves the cross-repo guard is wired). Will go silent after the content repo follow-up ships.

Co-Authored-By: Claude Opus 4.7 (1M context) noreply@anthropic.com

[github-actions]

size-limit report 📦

Path	Size
dist/assets/index-Di-yYCRi.js	0 B (-100% 🔽)
dist/assets/index-BsJUZYRr.css	6.13 KB (0%)
dist/assets/index-7FGKNfzq.js	163.65 KB (+100% 🔺)