Server instructions + SKILL.md: fix self-contradiction, quota wording (3), and surface skipped features from generate_marketing

[LarryWalkerDEV]

Context

Three consistency problems in the server texts and one missing behavior:

1. src/server.ts instructions list "Grundriss-Verschönerung, Video, Social-Media-Kit (in Kürze)" while step 5 of the same instructions tells the model to call generate_marketing (which delivers the social kit + exposé + video). Self-contradiction.
2. Quota wording: instructions + skill/SKILL.md must consistently say 3 kostenlose Bilder (product decision; app enforces 3 for new trials).
3. generate_marketing (app side /api/mcp/generate) will return a skipped array per this fixed contract (built in parallel in immostage-3d #27 — build against the contract, do not wait for it):

"skipped": [{ "feature": "video", "reason": "pro_required", "upgradeUrl": "https://..." }]

Acceptance criteria

• server.ts instructions accurately describe what is available today: Virtuelles Staging + Marketing-Paket (Social-Posts, Exposé-PDF, Video — Video nur im Pro-Plan) verfügbar; NUR Grundriss-Verschönerung as "in Kürze". No contradiction with the workflow steps.
• Quota wording "3 kostenlose Bilder" consistent across server.ts instructions, tool descriptions, and skill/SKILL.md.
• src/tools/generate-marketing.ts parses skipped[] from the app response (tolerating its absence for backward compatibility) and, when present, appends a German note telling the user which features were skipped and the upgrade link, e.g. "Hinweis: Das Immobilien-Video ist im Pro-Plan enthalten. Jetzt upgraden: {upgradeUrl}".
• Unit test: mocked app response with skipped:[{feature:'video',reason:'pro_required',upgradeUrl:'https://x'}] asserts the tool text contains the hint + URL; mocked response without skipped asserts today's text.
• npx tsc --noEmit exits 0.

Guardrails

All user-facing text German. Do not register the deferred Phase-F tools.

[LarryWalkerDEV]

SCOPE ADDITION (founder decision): get_download_link must present BOTH delivery channels to the client, not just the share link:

1. The existing 3-day share/download website URL (unchanged — instant, no login, forwardable to the property seller).
2. A NEW second line pointing at the permanent home of the assets in the client's dashboard: https://app.immostage.ai/projects/<projectId> — German wording along the lines of: "Dauerhaft verfügbar in Ihrem ImmoStage-Dashboard: (Login erforderlich). Der Download-Link oben läuft nach 3 Tagen ab."

The app's /api/mcp/share response already knows the project id — if it isn't currently returned to this server, coordinate: the acceptance criterion is the final tool text contains both URLs. Add a unit test asserting both lines appear.

[LarryWalkerDEV]

ACCEPTANCE GATE ADDITION (applies to every review iteration of this issue): the final reviewer must judge the result through the eyes of a German Immobilienmakler (real-estate agent, DACH market, pays for this product): Would this person accept the output for their own listing and send it to their seller? Correct professional German (Sie-Form, no anglicisms, no truncated umlauts), correct prices/units (€, m², Zimmer), and visually presentable results. If the answer is "no" or "borderline" → NOT approved → iterate (max 3 iterations, then leave open with the Makler-objection listed). This gate is IN ADDITION to the mechanical criteria, not instead of them.

[LarryWalkerDEV]

Iteration 1 — Builder summary (branch fix/issue-4-server-texts, commit f0ad0c0)

What changed

1. src/server.ts INSTRUCTIONS — options list is now truthful: Virtuelles Staging + Marketing-Paket (6 Social-Media-Posts, Exposé-PDF, Immobilien-Video — Video nur im Pro-Tarif) verfügbar; NUR Grundriss-Verschönerung in Kürze. No contradiction with workflow step 5 anymore. Added instruction to warn Trial-/Starter-Nutzer before generate_marketing that the video requires Pro.
2. Quota wording unified to the '3 kostenlose Bilder' family in server.ts, stage-room.ts tool description, and skill/SKILL.md (grep confirms no divergent 'kostenlos' phrasing remains).
3. generate-marketing.ts parses optional skipped[] {feature, reason, upgradeUrl} per the #27 contract: absent → today's text byte-identical (backward compatible); present → German Sie-Form Hinweis, e.g. 'Hinweis: Das Immobilien-Video ist im Pro-Plan enthalten. Jetzt upgraden: {upgradeUrl}'. Entries sharing reason+upgradeUrl (trial sends video AND transition) are deduplicated into ONE Hinweis. upgradeUrl interpolated exactly as received (relative /preise allowed by contract).
4. get_download_link (scope addition) now returns BOTH channels: the 3-day share URL (wording unchanged) plus 'Dauerhaft verfügbar in Ihrem ImmoStage-Dashboard: https://app.immostage.ai/projects/ (Login erforderlich). Der Download-Link oben läuft nach 3 Tagen ab.' APP_URL exported from app-client.ts — no third hardcoded copy.
5. skill/SKILL.md — options list matches server.ts; generate_marketing added as explicit workflow step 5 (was missing entirely); billing bullet corrected: 'Pro (199 €/Monat, unbegrenzt)' removed, replaced with the two real paths — Projekt-Freischaltung 49 € einmalig pro Projekt ODER Pro 199 €/Monat (5 Projekte monatlich); permanent dashboard availability mentioned alongside the 3-day download site.
6. First unit tests in this repo (src/tools/__tests__/, vitest zero-config, no vitest.config added): skipped-present asserts Hinweis + URL; skipped-absent asserts exact legacy text; dedup case asserts one Hinweis/one URL; download-link asserts both URLs.

Guardrails held: Phase-F tools (floor_plan, classify_room, optimize_listing, suggest_style) remain unregistered in createServer(); all user-facing text German/Sie-Form.

Verification

• npx tsc --noEmit → exit 0
• npm test (vitest run) → 2 files, 4 tests, all passed
• No lint script/config exists in this repo (N/A)

Ready for tester/reviewer pass (Makler read-through gate).

[LarryWalkerDEV]

Iteration 1: tester.allPass=true, reviewer.approved=true, violations=[]

[LarryWalkerDEV]

Closing summary (pinned)

What was done: On branch fix/issue-4-server-texts (commit f0ad0c0), the server INSTRUCTIONS and skill/SKILL.md were rewritten to be truthful (Marketing-Paket verfügbar, nur Grundriss "in Kürze", Video Pro-only pre-warning), quota wording was unified to the "3 kostenlose Bilder" family across server.ts / stage-room.ts / SKILL.md, generate-marketing.ts now consumes the #27 skipped[] contract (backward-compatible, deduplicated German Hinweis with upgradeUrl), and get_download_link returns both delivery channels (3-day share URL + permanent app.immostage.ai/projects/<id> dashboard URL). Why: the connector was contradicting itself and the app's own paywall — wrong quota count, a phantom video promise for Trial/Starter, and a "Pro unbegrenzt" pricing claim the app's Preise page disproves. How it helps: a German Immobilienmakler now gets a coherent, honest story at every touchpoint — correct quota, correct prices, one clean upsell instead of two duplicate nags, and a permanent asset location that pulls connector-only users into the app.

Status: verified merge-ready, awaiting merge. npx tsc --noEmit exit 0, npm test 4/4 passed (first unit tests in this repo, vitest zero-config), tester allPass=true, reviewer approved with the Makler acceptance gate. Issue stays open until the branch is actually merged.

---

Research critic — 10x opportunities (follow-up visibility)

#	Opportunity	Status in this pass
1	Fix false pricing claim in SKILL.md:49 — drop "unbegrenzt" from "Pro (199 €/Monat, unbegrenzt)"; app's own Preise page (src/app/preise/page.tsx:372,417) defines Pro as 5 Projekte/Monat	✅ Implemented — billing bullet corrected
2	Match SKILL.md billing narrative to the actual paywall: staging-quota denial links the 49 € per-project Starter unlock (tier-gating.ts:136-139), not Pro; present BOTH paths (49 € Freischaltung ODER Pro 199 €/Monat) and never conflate the two denial price points	✅ Implemented — both paths documented, denial paths kept distinct
3	Map skipped[] feature codes to German display names ("video" → "Immobilien-Video") and DEDUPLICATE — trial/starter sends both video and transition with identical reason+upgradeUrl (pipeline-orchestrator.ts:56-75)	✅ Implemented — German Hinweis, dedup by (reason, upgradeUrl) into one line, unit-tested
4	Pre-warn BEFORE the wait: instruct the model to tell Trial-/Starter-Nutzer before generate_marketing that video requires Pro (defense in depth for the #27 deploy gap)	✅ Implemented — instruction added to server.ts INSTRUCTIONS
5	get_download_link as retention surface: permanent dashboard URL pulls connector-only users into the app; also mention both channels in the tool DESCRIPTION string so the model can answer "wo finde ich das später?" without re-calling	✅ Both URLs implemented + tested; ⚠️ description-string mention not confirmed in builder summary — cheap follow-up
6	Append findings as dated section to the cross-repo store immoapp/docs/research/findings-backend-infra.md (already carries #25 and #27)	✅ Implemented — section "2026-07-01 — Issue #4 (mcp-immostage repo)" exists

Research critic — surprising angles

• Vitest is zero-config in this repo — the exact recommended pattern (vi.mock of app-client, stub server capturing .tool() handlers) ran green in ~900 ms with NodeNext .js specifiers resolving fine; no vitest.config was (or should be) created.
• No build-artifact staleness risk — api/mcp.ts imports ../src/server.js directly and dist/ has zero committed files; Vercel compiles src TS itself, so text edits deploy as-is.
• The transparent-upsell story has TWO price points — staging quota exhaustion → 49 € per-project unlock link; video skip → Pro 199 €/Monat via skipped[].upgradeUrl. Copy must keep them distinct or the Makler clicks a link showing a different price than the chat promised.
• Trial/starter emits duplicate skipped entries (video AND transition, same reason/upgradeUrl, both gating on feature video) — naive per-entry loops print the same nag twice; dedup is mandatory.
• Baseline was fully green — npx tsc --noEmit exit 0 on master, and the working branch started as an ancestor of master (no rebase needed).