Polish social milestone chart curves

Consent is bound to the channel it was given for: approving a post on X says
nothing about Instagram. Publishing state moves from the SocialMilestone row
into SocialMilestonePost, one row per channel, where a missing row means no
consent. The dialog asks per channel, shows the text each one will publish and
keeps a separate handle for each; Instagram captions end in hashtags because a
link there is not clickable.

Also fixes three problems in the existing X path:

- A QR code already past several thresholds produced one prompt per threshold,
  and since the post quotes the current scan count, every one of them would
  have published the same number. Only the highest threshold is announced now.
- Detection ran after every unique scan and re-read the QR code's full scan
  history just to hit skipDuplicates. Known milestones are filtered first.
- A failed post stayed failed forever because the consent dialog only opens
  once. The queue now retries three times on its own, spaces first attempts by
  SOCIAL_MILESTONE_MIN_GAP_HOURS, and Settings lists every milestone per
  channel with restart and revoke.

The worker no longer renders the card itself; it downloads the image the app
renders at /s/m/<token>/og, which also serves the new square and portrait
formats. Instagram publishing stays off until SOCIAL_MILESTONE_CHANNELS and
SOCIAL_WORKER_CHANNELS both name it.

Schema changes are manual SQL, see sql/2026-08-16_*.sql. Run both before
deploying this version.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

.claude/hooks/check-gstack.sh

@@ -0,0 +1,19 @@
+#!/bin/bash
+
+# Block skill usage when gstack is not installed globally.
+if [ ! -d "$HOME/.claude/skills/gstack/bin" ]; then
+  cat >&2 <<'MSG'
+BLOCKED: gstack is not installed globally.
+gstack is required for AI-assisted work in this repo.
+
+Install it:
+git clone --depth 1 https://github.com/garrytan/gstack.git ~/.claude/skills/gstack
+cd ~/.claude/skills/gstack && ./setup --team
+
+Then restart your AI coding tool.
+MSG
+  echo '{"permissionDecision":"deny","message":"gstack is required but not installed. See stderr for install instructions."}'
+  exit 0
+fi
+
+echo '{}'

.claude/launch.json

@@ -0,0 +1,17 @@
+{
+  "version": "0.0.1",
+  "configurations": [
+    {
+      "name": "dev",
+      "runtimeExecutable": "npm",
+      "runtimeArgs": ["run", "dev"],
+      "port": 3050
+    },
+    {
+      "name": "dev-node",
+      "runtimeExecutable": "node",
+      "runtimeArgs": ["node_modules/next/dist/bin/next", "dev", "-p", "3050"],
+      "port": 3050
+    }
+  ]
+}

.claude/settings.json

@@ -0,0 +1,15 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Skill",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/check-gstack.sh\""
+          }
+        ]
+      }
+    ]
+  }
+}

.codex-temp/awesome-design-md-SKILL.md

@@ -1,60 +0,0 @@
----
-name: awesome-design-md
-description: Use VoltAgent's awesome-design-md collection when the user wants UI inspired by a specific brand or asks for a DESIGN.md reference, visual system, or brand-style implementation such as Stripe, Linear, Vercel, Claude, or Supabase. Resolve the brand slug from the installed `design-md/` folder, fetch the matching `getdesign.md` design document for that slug, and apply it as the design-system reference for implementation.
----
-
-# Awesome DESIGN.md
-
-Use this skill to turn the installed `awesome-design-md` collection into a practical design reference workflow.
-
-The local `design-md/` directory is the index of supported brand slugs. Its per-brand `README.md` files are only pointers. The actual design-system document lives at:
-
-```text
-https://getdesign.md/<slug>/design-md
-```
-
-## Workflow
-
-1. Identify the target brand or closest visual reference.
-2. Resolve the brand slug from the local `design-md/` folder.
-3. Prefer exact folder names for dotted brands such as `linear.app`, `mistral.ai`, `opencode.ai`, `together.ai`, and `x.ai`.
-4. Fetch `https://getdesign.md/<slug>/design-md`.
-5. Use the fetched document in one of two ways:
-   - write or update the project's root `DESIGN.md`
-   - keep it as an external design reference while implementing UI
-6. Preserve the user's product semantics and content model. Borrow visual language, spacing, typography, motion, and component patterns, not product-specific copy.
-
-## Local Source Of Truth
-
-Use the installed folder below to confirm which slugs exist before fetching:
-
-```text
-C:\Users\a931627\.claude\skills\awesome-design-md\design-md
-```
-
-If needed, list the available slugs with:
-
-```powershell
-Get-ChildItem -Name C:\Users\a931627\.claude\skills\awesome-design-md\design-md
-```
-
-## Practical Rules
-
-- Treat `DESIGN.md` as a visual system reference, not as code to mirror verbatim.
-- If the user asks for "something like X, but lighter, warmer, or more minimal", adapt the reference instead of cloning it literally.
-- If multiple brands fit, choose the closest one and state the choice.
-- If a slug is missing locally or the remote fetch fails, pick the nearest available brand or ask the user for a replacement target.
-- When working inside an existing design system, merge the borrowed visual cues with the established component structure instead of replacing everything.
-
-## Common Slug Examples
-
-- `stripe`
-- `vercel`
-- `claude`
-- `cursor`
-- `supabase`
-- `linear.app`
-- `mistral.ai`
-- `opencode.ai`
-- `together.ai`
-- `x.ai`

.codex/hooks.json

@@ -0,0 +1,15 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Skill",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "'C:\\Users\\timo\\Documents\\qrmaster\\QR-master\\.codex\\hooks\\check-gstack.sh'"
+          }
+        ]
+      }
+    ]
+  }
+}

.codex/hooks/check-gstack.sh

@@ -0,0 +1,19 @@
+#!/bin/bash
+
+# Block skill usage when gstack is not installed globally.
+if [ ! -d "$HOME/.claude/skills/gstack/bin" ]; then
+  cat >&2 <<'MSG'
+BLOCKED: gstack is not installed globally.
+gstack is required for AI-assisted work in this repo.
+
+Install it:
+git clone --depth 1 https://github.com/garrytan/gstack.git ~/.claude/skills/gstack
+cd ~/.claude/skills/gstack && ./setup --team
+
+Then restart your AI coding tool.
+MSG
+  echo '{"permissionDecision":"deny","message":"gstack is required but not installed. See stderr for install instructions."}'
+  exit 0
+fi
+
+echo '{}'

.env.example

@@ -16,11 +16,50 @@ REDIS_URL=redis://redis:6379
 IP_SALT=CHANGE_ME_SALT
 ENABLE_DEMO=true
 
-# SMTP (for welcome + retention emails via nodemailer)
+# SMTP & Email Senders (for welcome + retention emails via nodemailer / resend)
 SMTP_HOST=smtp.qrmaster.net
 SMTP_PORT=465
 SMTP_USER=timo@qrmaster.net
 SMTP_PASS=
+EMAIL_FROM="Timo from QR Master <timo@qrmaster.net>"
+EMAIL_FROM_SECURITY="QR Master Security <noreply@qrmaster.net>"
+EMAIL_REPLY_TO="support@qrmaster.net"
 
 # Cron job protection — generate with: openssl rand -base64 32
 CRON_SECRET=
+
+# Leave empty in production for 1,000 / 10,000 unique scans. Test only, e.g. 1,2.
+SOCIAL_MILESTONE_THRESHOLDS=
+# Leave empty for immediate publishing after consent. Set 24 to enable a revocation window.
+SOCIAL_MILESTONE_POST_DELAY_HOURS=
+# Hours between two brand posts (default 24). Set 0 on test to publish back to back.
+SOCIAL_MILESTONE_MIN_GAP_HOURS=
+SOCIAL_MILESTONE_POSTING_ENABLED=false
+SOCIAL_WORKER_INTERVAL_SECONDS=10
+X_API_KEY=
+X_API_SECRET=
+X_ACCESS_TOKEN=
+X_ACCESS_TOKEN_SECRET=
+
+# Channels the consent dialog offers (app) and the worker publishes (worker).
+# Keep both in sync: x / x,instagram
+SOCIAL_MILESTONE_CHANNELS=x
+SOCIAL_WORKER_CHANNELS=x
+# Instagram Business account for QRMaster.net, see docs/automations/social-accounts-and-jobs.md
+INSTAGRAM_USER_ID=
+INSTAGRAM_ACCESS_TOKEN=
+GRAPH_API_VERSION=v22.0
+# Guards POST/DELETE on /api/social-assets, the public image host Instagram
+# pulls from. Unrelated to TikTok posting; falls back to TIKTOK_ADMIN_KEY.
+SOCIAL_ASSET_ADMIN_KEY=
+
+# TikTok OAuth / posting (server-side only)
+# Source of truth for cron posting: QRMaster server .env
+# Production example: https://qrmaster.net/api/tiktok/callback
+# Local dev example: http://localhost:3000/api/tiktok/callback
+# Tokens are saved in the DB after the OAuth callback; do not store access tokens here.
+TIKTOK_CLIENT_KEY=
+TIKTOK_CLIENT_SECRET=
+TIKTOK_REDIRECT_URI=https://qrmaster.net/api/tiktok/callback
+TIKTOK_ADMIN_KEY=
+TIKTOK_EXPECTED_OPEN_ID=

.github/pull_request_template.md

@@ -0,0 +1,39 @@
+## Summary
+
+- 
+
+## Change Type
+
+- [ ] QRMaster SEO page
+- [ ] QRMaster landing/tool page
+- [ ] QRMaster conversion/pricing change
+- [ ] GreenLens content/ASO workflow
+- [ ] Bug fix
+- [ ] Other
+
+## SEO / Content Review
+
+- [ ] Primary search intent is clear.
+- [ ] Metadata is present and specific.
+- [ ] Exactly one H1 is rendered for each new or changed page.
+- [ ] Internal links are added to relevant money pages.
+- [ ] CTA is specific to the page/use case.
+- [ ] Duplicate or thin content risk was checked.
+- [ ] Schema/structured data was added or intentionally skipped.
+
+## Verification
+
+- [ ] Build passes.
+- [ ] Lint passes.
+- [ ] Links/CTAs checked.
+- [ ] Screenshots or notes included for UI changes.
+
+## Codex Review Prompt
+
+For QRMaster SEO/page changes, run:
+
+```text
+Use docs/automations/qrmaster-pr-seo-review.md and review this PR for SEO,
+conversion, internal linking, duplicate content, schema, and build/lint risk.
+```
+

.github/workflows/ci.yml

@@ -1,6 +1,6 @@
 name: CI
 
-on: [push]
+on: [push, pull_request]
 
 jobs:
   build:

.gitignore

@@ -10,6 +10,7 @@
 
 # next.js
 /.next/
+/.next-stale-module-cache/
 /out/
 
 # production
@@ -27,6 +28,7 @@ yarn-error.log*
 # local env files
 .env*.local
 .env
+.env.test
 
 # vercel
 .vercel
@@ -42,11 +44,56 @@ next-env.d.ts
 docker-compose.override.yml
 *.sql
 !prisma/migrations/**/*.sql
+# Hand-applied schema changes and analysis queries belong in history.
+# Backup dumps land in the repo root, so they stay ignored.
+!sql/**/*.sql
 /backups/
 
 # logs
 logs
 *.log
 
+# project-specific
+Leads/
+/marketing/
+output/
+remotion/
+
 # local dev script
 dev-server.js
+.gstack/
+
+# atom-eve agent build/runtime artifacts
+/.output/
+/.eve/
+/.workflow-data/
+
+.env.meta   
+
+# Local temporary files, test scripts, and reports
+tmp/
+.codex-temp/
+*.report.html
+*.report.json
+tmp_*.js
+test_email.py
+meta-fix.js
+read-inbox.mjs
+quora_antwort_statisch_dynamisch.txt
+
+# Local blog audit reports and temporary snapshots
+scratch_blog_analysis.json
+scratch_scored_blog_posts.json
+src/lib/blog-data.snapshot-*.ts
+
+# Local developer-package workspaces and unreferenced generated media
+/packages/
+/public/Events/
+/public/Gyms/
+/public/Hotels/
+/public/Real Estate/
+/public/restaurant/
+/.qr-master-api-health-state
+
+# Python worker bytecode
+__pycache__/

.hermes/plans/2026-07-13_151727-qr-master-decision-content-and-market-proof.md

@@ -0,0 +1,219 @@
+# QR Master: Decision-Content + Market-Proof Implementation Plan
+
+> **For Hermes:** Execute only after Timo explicitly asks to implement. Do not create a page cluster before the hub has real search/conversion signals.
+
+**Goal:** Ship one German decision page for the *static vs. dynamic QR code* decision, instrument it with existing analytics, then test the exact message with real DACH restaurants/cafés before expanding SEO content.
+
+**Architecture:** Reuse the existing localized, data-driven use-case route `src/app/de/[slug]/page.tsx` and `UseCasePageTemplate`. Add one German content object to `src/lib/growth-pages-de.ts`; the route already creates static params, self-canonical metadata, hreflang pairs, Breadcrumb/FAQ schema and CTA tracking. Do not touch the English restaurant page: it already owns the restaurant-menu intent at `/restaurants`, and the old English use-case route redirects there.
+
+**Tech Stack:** Next.js App Router, TypeScript, existing `UseCasePageTemplate`, PostHog (`MarketingPageTracker` / `TrackedCtaLink`), npm.
+
+---
+
+## Current repo facts
+
+- German localized use-cases are generated from `src/lib/growth-pages-de.ts:29` through `src/app/de/[slug]/page.tsx:14-108`.
+- The route gives each item a self-canonical and creates static params from the data object (`src/app/de/[slug]/page.tsx:14-38`).
+- The existing template already tracks page views as `landing_page_viewed` and CTA clicks as `cta_clicked` (`src/components/marketing/MarketingAnalytics.tsx:28-93`). Do **not** create parallel events until the funnel’s actual setup/signup events are located.
+- `/use-cases/restaurant-menu-qr-codes` is a permanent redirect to `/restaurants` (`next.config.mjs:89-92`). The `/restaurants` page already owns English menu/PDF/reprint copy (`src/app/(main)/(marketing)/restaurants/page.tsx:34-69`).
+- No German restaurant/speisekarte page exists in `src/lib/growth-pages-de.ts` today.
+
+## Non-goals
+
+- No ten-page pSEO rollout.
+- No bespoke template, calculator, schema type, A/B framework, or new tracking architecture.
+- No claim of guaranteed savings, GDPR compliance, or “instant” changes unless product behaviour and legal wording are verified.
+- No customer-story or dashboard screenshot presented as proof until it is real.
+
+---
+
+### Task 1: Lock the positioning and page boundary
+
+**Objective:** Ensure this page wins a new decision query instead of competing with generic generator or restaurant-menu pages.
+
+**Files:**
+- No code change.
+- Review: `src/app/(marketing-de)/qr-code-erstellen/page.tsx:26-87`
+- Review: `src/app/(main)/(marketing)/restaurants/page.tsx:34-170`
+- Review: `next.config.mjs:63-97`
+
+**Step 1: Adopt the exact target user and job**
+
+- Segment: DACH restaurant/café operators with printed table tents, menus, takeaway flyers, or window signs.
+- Job: Decide *before printing* whether a QR destination needs to stay editable.
+- Primary query family: `statischer oder dynamischer qr code`, `unterschied statischer dynamischer qr code`, `qr code link später ändern`.
+- Explicit exclusion: do not target the generic “free QR generator” query or try to become a restaurant POS/menu-builder page.
+
+**Step 2: Define the content angle**
+
+Use this hero content:
+
+- H1: `Statischer oder dynamischer QR-Code? Entscheide vor dem Druck.`
+- Intro: `Wenn sich dein Link, Menü, PDF oder Angebot später ändern könnte, brauchst du einen QR-Code, dessen Ziel du ohne Neudruck aktualisieren kannst.`
+- Primary CTA: `Dynamischen QR-Code erstellen`
+- Secondary CTA: `Zum QR-Code-Generator`
+
+**Step 3: Define the one-sentence decision rule**
+
+`Bleibt das Ziel garantiert unverändert, reicht ein statischer QR-Code. Kann sich Ziel, PDF, Menü, Aktion oder Platzierung ändern, ist ein dynamischer QR-Code die sichere Wahl vor dem Druck.`
+
+**Acceptance criteria:** The page is clearly a decision hub, not another restaurant-menu landing page; it contains the decision within the first viewport.
+
+---
+
+### Task 2: Add one localized use-case record
+
+**Objective:** Publish exactly one data-backed German page at `/de/statischer-vs-dynamischer-qr-code` through the current route/template.
+
+**Files:**
+- Modify: `src/lib/growth-pages-de.ts` (inside `useCasePagesDe`, before the closing object)
+
+**Step 1: Add the record shape**
+
+Add a `UseCasePageContentDe` record with:
+
+```ts
+'statischer-vs-dynamischer-qr-code': {
+  enSlug: 'dynamic-qr-code-generator',
+  slug: 'statischer-vs-dynamischer-qr-code',
+  href: '/de/statischer-vs-dynamischer-qr-code',
+  title: 'Statischer oder dynamischer QR-Code?',
+  cluster: 'qr-code-basics',
+  parentHref: '/dynamic-qr-code-generator',
+  parentTitle: 'Dynamischer QR-Code-Generator',
+  ctaLabel: 'Dynamischen QR-Code erstellen',
+  eyebrow: 'Vor dem Druck entscheiden',
+  titleSuffix: 'vor dem Druck',
+  metaDescription: 'Statischer oder dynamischer QR-Code? Vergleiche Änderbarkeit, Druckrisiko und Tracking – und entscheide vor Flyer, Speisekarte oder Tischaufsteller.',
+  // remaining template fields in the following steps
+}
+```
+
+**Step 2: Write unique decision content—not token substitutions**
+
+Populate the template fields with these content requirements:
+
+- `answer`: the exact decision rule from Task 1.
+- `whenToUse`: three observable conditions: destination cannot change; a PDF/menu/offer might change; scans must be measured by placement.
+- `comparisonItems`: only concrete trade-offs, e.g. destination after print, response to a changed PDF, scan measurement. Validate the template’s left/right presentation before wording the boolean values.
+- `howToSteps`: create a dynamic code → print it once → change the destination later in the dashboard.
+- `workflowCards`: one realistic café example (30 table tents, new menu PDF), one flyer/event example, one separate-placement tracking example.
+- `checklist`: test print size/contrast, use a descriptive scan CTA, point to a mobile target, keep a dynamic target when it can change.
+- `supportLinks`: `/dynamic-qr-code-generator`, `/qr-code-tracking`, `/reprint-calculator`, `/qr-code-print-size-guide` after verifying every target resolves.
+- `faq`: 3–4 factual FAQs such as “Kann ich den Link eines statischen QR-Codes später ändern?” and “Wann lohnt sich ein dynamischer QR-Code für eine Speisekarte?”
+
+**Step 3: Avoid fictional proof**
+
+Set no `heroImage` unless a real product/dashboard or verified purpose-built illustration exists. If the template needs an image visually, use a clearly labelled product workflow asset—not a fake customer outcome or fabricated dashboard state.
+
+**Acceptance criteria:** `generateStaticParams` includes the slug; the page has unique German title, description, H1, intro, FAQ and internal-link context.
+
+---
+
+### Task 3: Verify rendered SEO and conversion path
+
+**Objective:** Confirm the new route is indexable, non-cannibalizing, and sends users into a working generator flow.
+
+**Files:**
+- Verify: `src/app/de/[slug]/page.tsx:18-52`
+- Verify: `src/components/marketing/UseCasePageTemplate.tsx:440-526`
+- Verify: `src/app/sitemap.ts`
+
+**Step 1: Run static checks**
+
+Run from repository root:
+
+```bash
+npm run lint
+npm run build
+```
+
+Expected: both commands exit `0`.
+
+**Step 2: Run the local smoke test**
+
+Start the app with `npm run dev`, then inspect:
+
+- `http://localhost:3050/de/statischer-vs-dynamischer-qr-code`
+- page source/rendered HTML contains one H1
+- canonical is `https://www.qrmaster.net/de/statischer-vs-dynamischer-qr-code`
+- page has language alternates generated by `buildLanguageAlternates`
+- primary CTA reaches the German setup/generator flow actually intended for conversion
+- all related-resource URLs return a valid page (not redirects to irrelevant pages or 404)
+- mobile: H1, decision rule, and primary CTA fit/appear before excessive scrolling; comparison is readable
+
+**Step 3: Verify tracking rather than inventing event names**
+
+Use the existing PostHog events first:
+
+- `landing_page_viewed` with `landing_page_slug=/de/statischer-vs-dynamischer-qr-code`
+- `cta_clicked` with `cta_location=hero_primary` and this use case slug
+
+Before adding `qr_setup_started` or `signup_completed`, locate their real implementation. If no downstream events exist, add them only after documenting the actual generator/signup handoff and preserving no-PII tracking.
+
+**Acceptance criteria:** build passes, canonical and CTA are correct, events appear in PostHog (or the tracking limitation is explicitly documented), and there is no new page aimed at `/restaurants`’ restaurant-menu keyword set.
+
+---
+
+### Task 4: Run a 7-day manual market test in parallel
+
+**Objective:** Test whether the language describes a costly current problem, not merely whether people say they like the page.
+
+**Files:**
+- No product code required.
+- Create a local working sheet only if Timo asks; do not automate outreach first.
+
+**Step 1: Build a 20-prospect list (45 minutes max)**
+
+Collect 20 independent restaurants/cafés in one local area. Criteria:
+
+- visible printed menu/table-tent/window QR in Google photos, Instagram, or own site;
+- a current menu PDF, ordering page, seasonal offer, or booking link;
+- reachable email, Instagram, or contact form.
+
+**Step 2: Send 10 short research-first messages**
+
+Use this wording, adapted with the venue’s name and observed QR use:
+
+> Hi [Name], kurze Frage – ich schaue mir gerade an, wie Restaurants QR-Codes auf Tischaufstellern und Speisekarten nutzen. Musstet ihr den Link, die PDF-Speisekarte oder Preise nach dem Druck schon einmal ändern? Was habt ihr dann gemacht? Ich verkaufe dir gerade nichts; ich will den Ablauf verstehen.
+
+Do not pitch QR Master in the first message.
+
+**Step 3: Follow up only with a relevant offer**
+
+If they mention an actual recent issue, reply:
+
+> Danke, genau diesen Fall untersuche ich. Ich baue ein Setup, bei dem der gedruckte QR-Code bleibt und du nur das Ziel aktualisierst. Wenn du willst, richte ich dir den nächsten Code testweise ein und prüfe vorher kostenlos, ob euer aktueller Code überhaupt update-sicher ist.
+
+**Step 4: Record proof, not compliments**
+
+For every reply capture: last incident, workaround, print/time cost, current QR tool, decision-maker, and whether they agree to a test/pilot. Strong evidence is a real past case, a follow-up call, a current QR audit, or a pilot—not “klingt gut”.
+
+**Acceptance criteria:** at least 10 contacts sent and one of these evidence types captured: concrete past incident, audit request, pilot, call, trial, or explicit rejection with reason.
+
+---
+
+### Task 5: Make the expansion/kill decision after 7–14 days
+
+**Objective:** Prevent a content factory before a signal exists.
+
+**Decision table:**
+
+| Signal | Decision |
+| --- | --- |
+| Search impressions/query relevance + CTA clicks | Build exactly one follow-up: `/de/qr-code-nach-druck-aendern` focused on recovery intent. |
+| At least 2 concrete restaurant incidents or 1 pilot | Improve the restaurant-specific proof/CTA or ship a German restaurant page only after title/canonical mapping against `/restaurants`. |
+| No relevant queries, replies, CTA clicks, or incidents | Do not create more pages. Change segment/message (e.g. flyers/events/real-estate) and repeat outreach. |
+
+**Do not expand to** flyer, business-card, event, packaging, PDF, and restaurant subpages simultaneously. One successful page/message earns one sibling.
+
+---
+
+## Final Definition of Done
+
+1. One live, unique German decision page—not a page cluster.
+2. `npm run lint` and `npm run build` pass.
+3. Canonical, hreflang, CTA and tracking are verified on the rendered route.
+4. Ten manual research contacts are sent.
+5. A seven-day review contains real proof: Search Console query data, PostHog CTA data, replies, calls, audits, trials, or payments.
+6. Only then decide whether `/de/qr-code-nach-druck-aendern` deserves implementation.

.impeccable-live.json

@@ -0,0 +1 @@
+{"pid":23720,"port":8400,"token":"99ca8ad6-3aa6-44f6-9b64-25921f55724b"}

AGENTS.md

@@ -305,3 +305,14 @@ This allows it to be used by:
 - Codex CLI
 - Gemini Code Assist
 - Cursor Agents
+
+---
+
+# gstack
+
+This repo also uses the global `gstack` skill pack for AI-assisted work.
+
+- Claude Code: install to `~/.claude/skills/gstack` and run `./setup --team`
+- Codex: gstack skills are installed globally under `~/.codex/skills/gstack-*`
+- Prefer gstack skills for structured work when they fit the task, especially `/browse`, `/review`, `/investigate`, `/qa`, `/ship`, and `/cso`
+- Do not reference vendored repo paths for gstack; use the global install path instead

BLOG-IDEEN-BACKLOG.md

@@ -0,0 +1,177 @@
+# Blog-Ideen-Backlog qrmaster.net
+
+Erstellt: 2026-08-04 · Datenbasis: GSC-Export 2026-08-03 (1.001 Suchanfragen, letzte 3 Monate)
+
+Alle Themen unten haben **belegte Nachfrage aus deinen eigenen Impressionen** — keine Keyword-Tool-Schätzungen. Die Impressionszahl ist, was qrmaster.net in drei Monaten bereits ausgespielt bekam, fast durchgehend bei 0 Klicks, weil die Positionen zwischen 35 und 70 liegen.
+
+Nach Abzug der Marken-Suchanfragen (`qr master`, `qrmaster` etc.) und der bereits abgedeckten Themen bleiben **8.018 Impressionen über 263 Suchanfragen** ohne passenden Blogpost.
+
+---
+
+## Canonical & Zweitverwertung
+
+Du wolltest die Posts auch anderswo veröffentlichen können. Die Reihenfolge entscheidet, ob das hilft oder schadet.
+
+**Regel: qrmaster.net veröffentlicht zuerst und bleibt das Original.**
+
+1. Post auf qrmaster.net veröffentlichen. Die Blogseiten setzen bereits einen korrekten Self-Canonical (`https://www.qrmaster.net/blog/<slug>`) — geprüft, nichts zu tun.
+2. **Warten, bis Google die Seite indexiert hat.** In der Search Console unter „URL-Prüfung" nachsehen. Erst wenn die Seite im Index ist, syndizieren. Wer gleichzeitig veröffentlicht, riskiert, dass die stärkere Domain zuerst indexiert wird und als Original gilt.
+3. Dann erst auf Drittplattformen stellen, jeweils mit Canonical zurück auf qrmaster.net.
+
+| Plattform | Canonical setzen | Hinweis |
+|---|---|---|
+| DEV.to | Feld `canonical_url` im Frontmatter | Sauber unterstützt, beste Option für die technischen Posts |
+| Hashnode | Einstellung „Original article URL" | Sauber unterstützt |
+| Medium | „Import story" statt manuellem Einfügen | Setzt Canonical automatisch; manuelles Einfügen tut das **nicht** |
+| LinkedIn Artikel | Nicht möglich | Kein Canonical-Support — dort nur Auszug plus Link posten, nie den Volltext |
+| Reddit | Nicht möglich | Kein Volltext, sondern eigenständiger Beitrag mit Link |
+
+**Wichtig:** Ein Canonical ist ein Hinweis, keine Anweisung. Wenn die Kopie deutlich mehr Links bekommt, kann Google sie trotzdem bevorzugen. Deshalb Schritt 2 nicht überspringen.
+
+**Praktischer Hinweis zu den technischen Posts:** `qr-code-api-documentation`, `bulk-qr-code-generator-excel`, `custom-qr-code-design`, `qr-code-print-size-guide` und `location-qr-code` enthalten Code, Formate und Spezifikationsdetails — die funktionieren auf DEV.to. Die reinen Marketing-Posts eher nicht.
+
+---
+
+## Priorität 1 — Höchstes Volumen (Woche 1–8)
+
+### 1. Twitter/X QR Codes
+**591 Impressionen** · `twitter qr code generator` (140, Pos. 38,9), `twitter qr code` (135, Pos. 53), `qr code for twitter` (86), `how to scan twitter qr code` (43)
+Winkel: X hat den eigenen QR-Code aus der App weitgehend entfernt — genau deshalb die Suchanfragen. Erklären, wie man stattdessen einen Profil-Link-QR baut, und `how to scan twitter qr code` als eigenes H2 beantworten.
+
+### 2. Facebook QR Codes
+**609 Impressionen** · `facebook qr code generator` (113, Pos. 49,9), `qr code for facebook page free` (33), `facebook page qr code generator` (29), `code generator facebook` (45)
+Winkel: Unterscheidung Seite vs. Profil vs. Gruppe vs. Event — vier verschiedene URL-Formate, die unterschiedlich funktionieren. Achtung: `code generator facebook` meint teils Facebooks Login-Code-Generator, also andere Intention. Im Text abgrenzen.
+
+### 3. URL- und Redirect-Grundlagen
+**787 Impressionen** · `create a qr code for a url` (58), `url qr code` (53), `redirect qr code` (47), `create qr code from url` (30), `turn url into qr code` (26)
+Winkel: Der größte Cluster überhaupt und rein instruktiv. Ein sauberer Grundlagen-Post, der auf alle Spezialfälle weiterverlinkt — wird zur internen Verteilerseite.
+
+### 4. Beaconstac-Alternative
+**718 Impressionen** · `beaconstac` (96), `beaconstac qr code generator` (75), `beaconstac vs popl` (67), `beaconstac vs mobilo` (57), `blinq vs beaconstac` (42), `beaconstac alternative` (34)
+Winkel: Hohe Kaufintention. Deckt sich mit dem `/vs/`-Backlog in CLAUDE.md. Die `X vs Y`-Anfragen sind Vergleiche zwischen **Wettbewerbern untereinander** — dort taucht QR Master als dritte Option auf.
+
+### 5. Krypto- und Wallet-QR-Codes
+**441 Impressionen** · `usdt qr code generator` (85, **Pos. 13,1**), `blockchain secure qr code generator` (48), `bitcoin qr code generator` (46), `crypto qr code generator` (37), `trust wallet qr code generator` (6)
+Winkel: Rankt bereits am besten von allen ungedeckten Themen. Substanz: Adressformate je Netzwerk, warum eine falsche Netzwerkwahl Geld vernichtet, Prüfsummen. Sicherheitskritisch — sorgfältig recherchieren.
+
+### 6. PayPal- und Zahlungs-QR-Codes
+**430 Impressionen** · `paypal qr code generator` (50), `qr-code zahlungen` (50), `qr code for payment generator` (19), `create paypal qr code` (19), `all in one qr code for payment` (7)
+Winkel: PayPal.Me-Linkformat, Abgrenzung zu EPC/GiroCode im EU-Raum, was rechtlich zu beachten ist.
+
+### 7. SMS-QR-Codes
+**330 Impressionen** · `sms qr code generator` (51), `sms qr code` (48), `qr code sms generator` (27), `create sms qr code` (22)
+Winkel: Das `SMSTO:`-Format und die vorbefüllte Nachricht — technisch dieselbe Präzision wie beim WhatsApp-Post, dieselbe Fehlerquelle bei der Nummernformatierung.
+
+### 8. QR Codes für Immobilien
+**326 Impressionen** · `qr code real estate signs` (41), `qr code generator for real estate` (41), `real estate signs with qr codes` (24), `qr for real estate` (21)
+Winkel: Schilder im Freien — Größe für Lesung aus Autoentfernung, Wetterfestigkeit, dynamische Codes für Objektwechsel. Verweist auf den Print-Size-Guide.
+
+---
+
+## Priorität 2 — Mittleres Volumen (Woche 9–18)
+
+### 9. Flowcode-Alternative
+**246 Impressionen** · `flowcode alternative` (51, **Pos. 18,3**), `flowcode qr competitors` (47), `flowcode competitors` (38), `flowcode pricing` (21)
+Steht bereits auf Position 18 — kürzester Weg auf Seite 1 im Wettbewerbsumfeld.
+
+### 10. Bearbeitbare QR Codes / Ziel ändern
+**217 Impressionen** · `changeable qr code` (63), `dynamic qr code editing` (51), `editable qr code` (25), `convert static qr code to dynamic` (59)
+Winkel: Beantwortet die Frage „kann ich einen gedruckten Code noch ändern" direkt. Ehrliche Antwort: statisch nein, dynamisch ja — und was man tut, wenn schon statisch gedruckt wurde.
+
+### 11. TikTok QR Codes
+**209 Impressionen** · `tiktok qr code generator` (113, Pos. 25,4), `qr code generator tiktok` (27), `free tiktok qr code generator` (23)
+Es gibt bereits `/tools/tiktok-qr-code` (465 Impr., 9 Klicks) — der Post wäre Support-Content dafür.
+
+### 12. Zoom QR Codes
+**200 Impressionen** · `zoom qr code generator` (56, Pos. 28,8), `qr code for zoom meeting` (23), `create qr code from zoom link` (12)
+Winkel: Wie der Teams-Post — welcher Meeting-Link haltbar ist, Sicherheit bei sichtbaren Codes.
+
+### 13. YouTube QR Codes
+**196 Impressionen** · `youtube qr code generator` (67), `qr code youtube generator` (25), `youtube channel qr code generator` (14), `youtube playlist qr code` (7)
+`youtube-qr-code-guide` existiert bereits (936 Wörter, 0 Impressionen) — **prüfen statt neu schreiben**, warum er nicht ausgespielt wird.
+
+### 14. Verpackung und Produkt-QR
+**196 Impressionen** · `qr code packaging` (38), `qr codes for wine labels` (25), `qr code for wine bottle` (25), `qr code retail` (19), `qr code for product tracking` (10)
+Winkel: Gebogene Flächen, Materialeinflüsse, GS1 Digital Link als Zukunftsformat.
+
+### 15. Hotel-QR-Codes
+**159 Impressionen** · `hotel info via qr code` (63), `qr code for hotel` (23), `hotel qr code` (21), `hotel check in qr code` (5)
+Auch `system qr dla hoteli` (72, Polnisch) — Nachfrage besteht international.
+
+### 16. E-Mail-QR-Codes
+**117 Impressionen** · `qr code generator for email` (18), `qr code email generator` (18), `free email qr code generator` (12), `qr code to email` (3)
+Winkel: `mailto:`-Format mit vorbefülltem Betreff und Text, URL-Encoding — kurzer, technisch präziser Post.
+
+### 17. Café- und Gastronomie-QR
+**122 Impressionen** · `qr code cafe` (48), `cafe qr code` (25), `qr cafe` (21), `qr code holder for restaurant` (6)
+Achtung: Überschneidung mit `/restaurants`. Abgrenzen oder dorthin verlinken statt Kannibalisierung erzeugen.
+
+### 18. Flyer und Print-Kampagnen
+**118 Impressionen** · `qr codes on flyers` (58), `how to track qr code scans from a print campaign` (43, **Pos. 9,9**), `how to put qr code on flyer` (4)
+Die Print-Kampagnen-Anfrage steht schon auf Position 9,9 und ist bereits als H2 im Tracking-Guide. Ein eigener Post wäre die Vertiefung.
+
+### 19. Kalender- und Termin-QR
+**97 Impressionen** · `qr code for calendar event` (22), `free qr code generator calendar event` (13), `create qr code calendar event` (11)
+Winkel: Das iCal/VEVENT-Format direkt im Code — funktioniert offline, deshalb der stärkste Event-Anwendungsfall.
+
+---
+
+## Priorität 3 — Nischen mit klarer Intention (Woche 19–30)
+
+### 20. Kirchen, Schulen, Bibliotheken
+**77 Impressionen** · `qr for schools` (16), `qr code for church` (13), `qr code library` (10), `church donation qr code` (9), `campus qr code` (5)
+
+### 21. Gesundheitswesen, Versicherung, Kanzleien
+**50 Impressionen** · `qr code insurance industry` (18), `qr codes for legal services` (8), `qr code for dental clinics` (8), `qr codes for healthcare patient intake forms` (6)
+Winkel: Datenschutz und Einwilligung bei Patientenformularen — Thema, das andere meiden.
+
+### 22. Bitly als Alternative
+**57 Impressionen** · `bitly qr code` (16), `bitly qr code alternative` (12), `bitly vs beaconstac qr codes` (18, **Pos. 14,9**), `bit.ly qr code generator` (6)
+
+### 23. WLAN-QR-Codes
+**11 Impressionen im Export**, aber `/tools/wifi-qr-code` hat 70 Impressionen bei Position 22,4
+Winkel: Das `WIFI:`-Format, WPA vs. WPA2, Sonderzeichen im Passwort — kurzer technischer Post mit hoher Praxisrelevanz.
+
+### 24–30. Weitere belegte Einzelthemen
+- **Stadien und Veranstaltungsorte** — `qr code in sports stadium` (17, Pos. 20,2), `qr codes for stadiums` (9)
+- **Flughäfen** — `airport qr code` (10, Pos. 19,9), `qr code airport` (9)
+- **Friseure und Barbershops** — `qr barber` (13, **Pos. 8,9**), `barber business cards with qr code` (4)
+- **Fitness und Yoga** — `yoga qr code` (5), `short code for yoga studios` (7)
+- **Foodtrucks** — `food truck qr code` (3, Pos. 46)
+- **Schmuck und Inventar** — `jewelry inventory qr code solutions` (6), `bijuterii qr code` (8)
+- **Messen und Networking** — `qr codes for event networking` (7, Pos. 15), `qr codes at trade shows` (7)
+
+---
+
+## Deutscher Markt — separate Entscheidung
+
+**400 Impressionen**, alle bei 0 Klicks und Position 55–103:
+`qr code erstellen gratis` (109, Pos. 100,4), `kostenlos qr code erstellen` (66, Pos. 102,7), `qr-code zahlungen` (50), `dynamische qr-codes` (45), `qr visitenkarte` (11), `qr code visitenkarte` (9)
+
+Positionen über 100 bedeuten: Google kennt die Seiten, hält sie aber für die schlechteste verfügbare Antwort. Die 13 `/de/`-Seiten haben zusammen 194 Impressionen und **0 Klicks**.
+
+Das ist keine Content-Frage, sondern die offene Grundsatzentscheidung aus dem Umsetzungsplan: eine echte deutsche Sektion mit hreflang und eigenständigen Texten, oder deindexieren. Einzelne deutsche Blogposts ohne diese Entscheidung verschärfen das Problem nur.
+
+---
+
+## Reihenfolge-Empfehlung
+
+Nicht streng nach Impressionen gehen. Diese vier zuerst, weil sie am nächsten an Seite 1 stehen:
+
+1. **Flowcode-Alternative** — Position 18,3
+2. **Krypto/USDT** — Position 13,1
+3. **TikTok** — Position 25,4
+4. **Zoom** — Position 28,8
+
+Danach die Volumen-Themen aus Priorität 1. Ein Post auf Position 25 auf Seite 1 zu heben bringt kurzfristig mehr als ein Post auf Position 55 mit dreifachem Volumen.
+
+## Format-Vorlage
+
+Die 22 überarbeiteten Posts folgen einem Muster, das sich bewährt hat und für neue übernommen werden sollte:
+
+- Direkte Antwort im ersten Absatz, keine Einleitung über die Geschichte des QR-Codes
+- Ein konkretes Format, Feld oder Zahlenbeispiel, das man ohne Tool nachbauen kann
+- Eine Tabelle, die zwei Optionen ehrlich gegenüberstellt — inklusive der Zeile, in der die kostenlose Variante gewinnt
+- Ein Abschnitt „was schiefgeht" mit benannten Fehlermodi statt allgemeiner Tipps
+- Interne Links auf die passende Tool- oder Money-Page
+- Quellen, die keine Wettbewerber sind

CHECKLISTE_UMSETZUNG_2026-07-27.md

@@ -0,0 +1,131 @@
+# Checkliste - Stand nach der Umsetzung
+
+27. Juli 2026. 118 Dateien, 0 Syntaxfehler, Prisma-Schema valide, beide i18n-JSONs valide, keine langen Striche.
+
+---
+
+## FERTIG
+
+### `/create` - Limit-Moment
+
+- [x] Redirect auf `/pricing` entfernt, Formularzustand überlebt den 403
+- [x] `UpgradeModal.tsx` mit drei Anlässen: `limit`, `logo`, `shapes`
+- [x] Direkt-Checkout mit `returnPath` (pfadvalidiert gegen offene Redirects)
+- [x] Option "bestehenden Code pausieren", danach Auto-Retry des Speicherns
+- [x] Option "als statischen Code weitermachen"
+- [x] Scan-Zahlen der letzten 30 Tage je Code, damit die Pausier-Entscheidung informiert ist
+- [x] PostHog-Events für alle vier Ausgänge
+
+### Limit-Logik und gestopfte Löcher
+
+- [x] `POST /api/qrs` und `GET /api/user/stats` zählen nur noch `status: 'ACTIVE'`
+- [x] `GET /api/qrs` liefert `scans30d` je Code
+- [x] `PATCH /api/qrs/[id]` akzeptiert `status` (kannte es vorher nicht, Pausieren wäre wirkungslos gewesen)
+- [x] Reaktivieren prüft gegen das Kontingent (sonst Limit-Umgehung durch pausieren/neu/reaktivieren)
+- [x] `bulk-creation` lädt das Restkontingent serverseitig nach jedem Lauf
+
+### `/bulk-creation`
+
+- [x] Stille Fehler beendet: fehlgeschlagene Zeilen werden gesammelt statt verschluckt
+- [x] Ergebnis-Panel mit Zeilennummer, Titel und Grund je Fehlzeile
+- [x] CSV-Download der fehlenden Zeilen
+- [x] Grüner Toast nur bei vollständigem Lauf
+- [x] Drei deutsche Toasts auf Englisch
+
+### Upgrade-Wege
+
+- [x] Neue Seite `/upgrade` in der `(app)`-Route-Group, Sidebar bleibt
+- [x] Alle 6 In-App-Links umgebogen: AppLayout, Dashboard, Settings (2x), Bulk (2x)
+- [x] `reason`- und `from`-Parameter, `from` geht als `returnPath` in den Checkout
+
+### QR-Design
+
+- [x] Showcase von Canvas auf **SVG** portiert (`lib/qr-shapes.ts`)
+- [x] `StyledQRCode.tsx` für die Live-Vorschau, `lib/render-qr-svg.ts` für Bulk - gemeinsame Shape-Funktionen, können nicht auseinanderlaufen
+- [x] 11 Modulformen, plangestaffelt: Free `square`, Pro 4, Business alle
+- [x] Eye-Frames und Eye-Balls getrennt wählbar
+- [x] Farbverläufe linear und radial, Business
+- [x] Gesperrte Formen sind klickbar: Vorschau zuerst, Modal danach
+- [x] Automatische Anhebung der Fehlerkorrektur bei kritischen Formen und bei Logo, mit sichtbarer Begründung
+- [x] Druckgrößen- und Test-Scan-Hinweis
+- [x] Toter `toPng`-Aufruf im SVG-Download entfernt
+
+### Scanbarkeit - gemessen, nicht geschätzt
+
+Gerendert und mit einem echten Decoder zurückgelesen, 5 Inhalte x mehrere Auflösungen:
+
+- [x] Alle 11 Modulformen 5/5
+- [x] Eye-Balls square, rounded, circle, diamond, hexagon 5/5
+- [x] **star als Eye-Ball 3/5 - entfernt**
+- [x] **Eye-Frames circle, leaf, flower, hexagon 0/15 - entfernt**
+- [x] **Rundungsradius 0.28 0/15, auf 0.10 korrigiert (15/15)**
+- [x] Alle 10 verbleibenden Eye-Kombinationen 30/30
+- [x] Bulk-Renderer separat geprüft, inklusive Verlauf: 12/12
+
+### Design-Vorlagen
+
+- [x] `QRDesignPreset`-Modell in Prisma, Relation am User
+- [x] `GET/POST/DELETE /api/design-presets`, Business-gated, CSRF-geschützt
+- [x] Gleicher Name überschreibt statt Duplikat, Obergrenze 50
+- [x] Speichern und Anwenden in `/create`
+- [x] Preset-Auswahl im Bulk-Flow: ein Design für den ganzen Upload
+
+### Retention-Mails
+
+- [x] Tag-3-Betreff entschärft
+- [x] Tag-7 zur verhaltensbasierten Limit-Mail umgebaut
+- [x] Tabellenzeile `CSV export ✓/✓` gestrichen, `Brand colors` ersetzt (war nach der Farbfreigabe falsch)
+- [x] Neue Erster-Scan-Mail, einziger Trigger ohne Kalender
+- [x] Tag-30 auf eigene Scan-Zahlen, unbelegte Testimonial-Behauptung gestrichen
+- [x] Tag-30 entfällt bei null Scans
+- [x] Cron-Route neu, vier Trigger
+
+### Farben ab Free und Folge-Copy
+
+- [x] `canCustomizeColors = true`, neue Gates `canUseShapes`, `canUseLogo`, `canUseFullDesign`
+- [x] `en.json`, `PricingClient`, Dashboard-Pro-Karte
+- [x] `/alternatives/flowcode`, 5 Stellen
+- [x] `/pricing` FAQ: Bulk-Antwort war noch static-only
+- [x] `competitor-data.ts`: Vergleichszeile führte Farben als Pro
+
+### Formales
+
+- [x] 729 lange Striche ersetzt, keine mehr im Quellcode
+- [x] CRLF-Zeilenenden durchgehend erhalten
+- [x] SQL-Datei aktualisiert: Block 4 ist jetzt Pflicht, nicht optional
+
+---
+
+## NICHT GEBAUT
+
+### Vor dem Deploy zwingend
+
+- [ ] **SQL ausführen** (`sql/2026-07-27_cro_retention_design.txt`), alle sechs Blöcke
+- [ ] **`npx prisma generate`** - ohne das kennt der Client `QRDesignPreset` nicht und `/api/design-presets` wirft zur Laufzeit
+- [ ] **Block 3.2** - sonst geht die Erster-Scan-Mail an die gesamte Bestandsbasis
+- [ ] Entscheidung zu Block 3.1
+
+### Nicht getestet
+
+- [ ] Kein Browser-Durchlauf. Der Renderer ist gegen einen Decoder geprüft, nicht im echten DOM
+- [ ] PNG-Download über `html-to-image` mit dem neuen SVG nicht verifiziert
+- [ ] SVG-Download nicht verifiziert
+- [ ] Logo-Overlay im neuen Renderer nicht visuell geprüft
+- [ ] Stripe-Checkout mit `returnPath` nicht live durchlaufen
+- [ ] Pausieren und Reaktivieren nicht gegen echte Daten
+- [ ] Preset speichern, laden, auf Bulk anwenden nicht gegen echte Daten
+
+### Bewusst weggelassen
+
+- [ ] Rahmen mit Label als Vektor. Die bestehenden Rahmen sind HTML um den QR herum; der SVG-Download fällt dort weiterhin auf PNG zurück und sagt es
+- [ ] Logo-Formen (Punkt, Herz, Blitz, WLAN) aus der Showcase
+- [ ] Eye-Frames circle, leaf, flower, hexagon - Messergebnis 0/15
+- [ ] star als Eye-Ball - 3/5
+
+### Offene inhaltliche Frage
+
+- [ ] Tag-30-Mail: gab es die Gespräche mit Pro-Nutzern über Branding? Bei Ja gehört ein wörtliches Zitat rein
+
+### Vorbehalt zur Messung
+
+Getestet wurde mit OpenCVs Decoder. Der ist strenger als iPhone- und Android-Kameras. Es ist möglich, dass ein Kreis-Eye-Frame auf echten Geräten funktioniert - aber 0 von 15 ist kein Rauschen, und das ist nichts, was man ungetestet auf Druckmaterial loslässt.

CLAUDE.md

@@ -259,6 +259,56 @@ ALTER TYPE "ContentType" ADD VALUE 'BARCODE';
 - Sitemap generation via next-sitemap
 - Google Indexing API + IndexNow submission scripts available
 
+## AI SEO / AEO Tracking (AI Answer Engine Visibility)
+
+Ongoing effort to increase QR Master's presence in AI-generated answers (ChatGPT, Perplexity, AI Overviews, etc.) for QR-code-generator-related queries. Update this section after each audit/build cycle so future sessions build on prior findings instead of re-deriving them.
+
+### Baseline audit (2026-07-22)
+
+Query-fanout data (what an AI model searches for while answering a prompt) showed QR Master already being cited in AI-generated answers for 3 of 9 tested query themes: "best QR code generator for marketing campaigns", "QR code generator with analytics and tracking", and "affordable dynamic QR code generator for small business" — positioned as the budget/SMB pick alongside Uniqode, QR TIGER, Bitly, Flowcode, and Hovercode.
+
+No QR Master citation appeared for: "best dynamic QR code generator 2026", "best QR code generator for businesses", "best QR code generator for agencies", "alternatives to QR TIGER", "QR code generator with unlimited scans", "free dynamic QR code generator unlimited scans".
+
+Existing on-site AEO infrastructure found during the audit:
+- `public/llms.txt` present — lists core pages and cornerstone guides for AI retrieval
+- `/alternatives/` pages exist only for: qr-code-generator.com, Flowcode, Beaconstac, Bitly
+- `/vs/` pages exist only for: Beaconstac
+- `/compare/[slug]` dynamic comparison route exists (e.g. `free-vs-paid-qr-code-generator`)
+- Blog cornerstones: best-qr-code-generator-2026, free-vs-paid-qr-generator, qr-code-tracking-guide-2025, dynamic-vs-static-qr-codes, qr-code-small-business, qr-code-scan-statistics-2026, etc.
+
+Pattern observed: QR Master gets cited by AI models only where first-party comparison/guide content already exists on the domain. The fanout queries repeatedly run `site:` searches against Uniqode, QR TIGER (qrcode-tiger.com), Hovercode, Scanova, and QRCodeChimp — none of which currently have a matching QR Master alternatives/vs page.
+
+### Priority backlog (from this audit)
+1. Build `/alternatives/uniqode`, `/alternatives/qr-code-tiger`, `/alternatives/hovercode` (highest fanout frequency, in that order)
+2. Build matching `/vs/uniqode`, `/vs/qr-code-tiger`, `/vs/hovercode` (same format as `/vs/beaconstac`)
+3. New cornerstone guide: "QR code generator for agencies" (white-label, bulk creation, API) — zero QR Master positioning currently exists for this query cluster
+4. Update `public/llms.txt` once the new pages ship, so they enter the AI retrieval list
+5. Re-run the same query-fanout test periodically to track citation-rate changes over time
+
+### Additional confirmed win — "dynamic barcode generator" (2026-07-22, same session)
+
+Tested outside the original 9-theme set. QR Master is cited as the "Best overall option" for this query — credited for trackable/editable dynamic barcodes, bulk generation, unified analytics, and UTM tracking, plus static EAN-13/UPC-A/Code 128 support when editability isn't needed. The AI answer also included a "requirement → recommended format" decision table (dynamic QR vs. EAN-13/UPC-A vs. Code 128 vs. GS1 Digital Link) that maps closely to existing on-site content.
+
+This maps to the `/tools/barcode-generator` tool, reinforcing the pattern above: dedicated first-party pages targeting a query cluster get cited, gaps without dedicated pages don't. Counts as a 4th confirmed positive theme alongside the original 3 from the baseline audit.
+
+Note: `/dynamic-barcode-generator` and `/barcode-generator` are **not** live pages — both 301 to `/tools/barcode-generator` (see `redirects()` in `next.config.mjs`). Cite the canonical `/tools/barcode-generator` URL in any AEO work.
+
+### Sitemap / IndexNow drift (fixed 2026-08-13)
+
+`src/app/sitemap.ts` and `getAllIndexableUrls()` in `src/lib/indexnow.ts` are two hand-maintained URL lists that had silently diverged: the whole `/alternatives/*` + `/vs/*` cluster (1,942 GSC impressions in the 3 months to 2026-08-13, avg pos ~29-47) was submitted to IndexNow and linked from the footer but missing from the sitemap, while `/dynamic-barcode-generator` was listed in both despite 301-ing.
+
+**When adding or redirecting a marketing page, update both lists.** A redirected URL must appear in neither.
+
+### Google Review cluster — biggest non-brand opportunity (2026-08-13)
+
+`/tools/google-review-qr-code` is the **#2 page on the site by impressions** (2,201 in 3 months) and converts almost none of it: 2 clicks, avg position 33. The query cluster is ~1,667 impressions across 50+ queries, all at position 20-50, zero clicks. Head term `google review qr code generator` = 268 impr at pos 35.
+
+**On-page is not the constraint — do not "improve the content".** Audited 2026-08-13: it is already the deepest tool page on the site (1,352 rendered words, 8 h2 / 18 h3 vs 549 for crypto, 741 for wifi), with SoftwareApplication + HowTo + FAQPage schema, a correctly matched title, and canonical set. It also does not meaningfully cannibalize `/use-cases/qr-codes-for-review-collection` (36 impr, pos 11), which targets the tracking angle.
+
+What was done: added `google-review-qr-code` to `toolsMap` in `qr-code-for/[industry]/page.tsx` and to the `tools[]` array of the 32 local-business industries in `src/lib/industry-pages.ts`, creating contextual internal links from crawled, well-ranking pages (barbershops pos 9.7, hotels, cafes, bars). The 20 institutional industries (airports, schools, stadiums, libraries, churches, universities, museums, theaters, cinemas, art-galleries, events, trade-shows, retail, and the non-local stores) were deliberately excluded — review collection is not their job, and blanket-linking all 52 would be boilerplate.
+
+Remaining gap is off-site authority, not anything in this repo. Note the fallback in that template silently rewrites an unknown tool slug to `/tools/url-qr-code`, so any new slug must be added to `toolsMap` or the link disappears without erroring.
+
 ## Deployment Notes
 
 ### Docker (Self-Hosted)
@@ -279,3 +329,41 @@ docker-compose exec web npx prisma migrate deploy  # Run migrations in container
 - DOCKER_SETUP.md - Complete Docker deployment guide
 - prisma/schema.prisma - Database schema and relationships
 - env.example - Environment variable template
+
+## gstack (REQUIRED — global install)
+
+Before doing any AI-assisted work in this repo, verify gstack is installed globally:
+
+```bash
+test -d ~/.claude/skills/gstack/bin && echo "GSTACK_OK" || echo "GSTACK_MISSING"
+```
+
+If `GSTACK_MISSING`: stop and install it:
+
+```bash
+git clone --depth 1 https://github.com/garrytan/gstack.git ~/.claude/skills/gstack
+cd ~/.claude/skills/gstack && ./setup --team
+```
+
+After install, use gstack skills where appropriate, especially `/browse`, `/review`, `/investigate`, `/qa`, `/ship`, and `/cso`.
+Use `~/.claude/skills/gstack/...` for gstack file paths because this repo does not vendor the pack locally.
+
+## Skill routing
+
+When the user's request matches an available skill, ALWAYS invoke it using the Skill
+tool as your FIRST action. Do NOT answer directly, do NOT use other tools first.
+The skill has specialized workflows that produce better results than ad-hoc answers.
+
+Key routing rules:
+- Product ideas, "is this worth building", brainstorming → invoke office-hours
+- Bugs, errors, "why is this broken", 500 errors → invoke investigate
+- Ship, deploy, push, create PR → invoke ship
+- QA, test the site, find bugs → invoke qa
+- Code review, check my diff → invoke review
+- Update docs after shipping → invoke document-release
+- Weekly retro → invoke retro
+- Design system, brand → invoke design-consultation
+- Visual audit, design polish → invoke design-review
+- Architecture review → invoke plan-eng-review
+- Save progress, checkpoint, resume → invoke checkpoint
+- Code quality, health check → invoke health

CTR_REWRITE_2026-07-27.md

@@ -0,0 +1,71 @@
+# SERP-CTR Rewrite — 27. Juli 2026
+
+Grundlage: GSC-Export 28 Tage (8.944 Impressionen, 52 Klicks, 0,58% CTR, Ø-Position 33,0)
+Methodik: `direct-response-copywriting` + Positioning Decision vom 26.07.2026 (Direction 1 als Positionierung, Direction 2 als Proof-Layer)
+
+## Ehrliche Einordnung des 5–10%-Ziels
+
+Site-weite CTR von 5–10% ist bei Ø-Position 33 **nicht durch Copy erreichbar**. CTR ist primär eine Funktion der Position:
+
+| Position | Erwartete CTR |
+|---|---|
+| 1 | 28–40% |
+| 3 | 10–11% |
+| 5 | 5–6% |
+| 10 | 2–3% |
+| 15 | 1–2% |
+| 30+ | <0,3% |
+
+Die zwei größten Impression-Seiten (`/dynamic-qr-code-generator` 1.694 Imp @ Pos 33,5 und `/qr-code-tracking` 1.023 Imp @ Pos 34,0) haben 0% CTR. Das ist bei Position 33 **normal** — 31% aller Impressionen der Site liegen auf Seite 4 der SERP. Kein Title der Welt repariert das; das ist ein Ranking-Thema.
+
+**Was Copy realistisch leisten kann:**
+- Seiten auf Pos 1–15 auf ihren Positions-Benchmark heben → aus 52 Klicks werden ca. 90–120
+- Die großen Volumenseiten so vorbereiten, dass sie beim Aufstieg auf Seite 1 sofort auf Benchmark klicken statt bei 2%
+
+5–10% site-weit wird erst realistisch, wenn die Ø-Position unter ~10 liegt. Dann trägt diese Copy den Unterschied.
+
+## Die drei strukturellen Fehler, die behoben wurden
+
+**1. Deutsche Halbsätze in englischen Descriptions.** 97% der Impressionen kommen aus USA/Indien/englischsprachigen Märkten. Trotzdem stand in den Tool-Descriptions „Teams QR Code erstellen", „Zoom QR Code erstellen", „TikTok QR Code erstellen", „Erstelle Bitcoin & Ethereum QR Codes", „Standort teilen leicht gemacht". Für einen englischen Sucher liest sich das wie maschinell übersetzter Spam. Das ist die wahrscheinlichste Ursache für 0,61% CTR auf Pos 10 (`barbershops`) und 0,65% auf Pos 17 (`zoom`).
+
+**2. `| QR Master`-Suffix und 65+ Zeichen lange Titles.** Google schneidet bei ~580px ab. `Free Microsoft Teams QR Code Generator | Join Meetings | QR Master` (66 Zeichen) wurde in der SERP abgeschnitten — der Nutzen verschwand im „…". Alle neuen Titles liegen bei 42–55 Zeichen.
+
+**3. Null Pattern Interruption.** Jedes Ergebnis in dieser SERP sagt „Free QR Code Generator". Die alten Descriptions sagten „Instant and free", „Free & Easy" — die vagesten möglichen Claims. Neu: konkrete, falsifizierbare Spezifika (3 dynamische Codes gratis, 1.000 Codes aus einem Spreadsheet, 42 Zeichen Wallet-Adresse, EAN-13/UPC-A/Code 128).
+
+## Wichtigste Änderungen
+
+| Seite | Imp | CTR | Pos | Kernänderung |
+|---|---|---|---|---|
+| `/` | 1.046 | 4,88% | 4,6 | Title: Mechanismus statt Kategorie. Description: 3 verifizierte Zahlen statt Feature-Liste. H1: „The Link Doesn't Have to Stay Wrong Once It's Printed" |
+| `/qr-code-tracking` | 1.023 | 0% | 34,0 | Title war „QR Code Tracking: Track QR Code Scans" — redundant, kein Nutzenversprechen. Neu: „See Which Placement Drove the Scan" (= Main-Headline-Idee aus Offer Brief §14) |
+| `/dynamic-qr-code-generator` | 1.694 | 0% | 33,5 | Title war schon gut, blieb. Description auf Schmerz + Zahlen umgestellt |
+| `/tools/google-review-qr-code` | 566 | 0,18% | 24,8 | Description führt jetzt mit dem Moment: „while the customer is still standing there" |
+| `/tools/teams-qr-code` | 277 | 3,25% | 9,6 | Title von 66 auf 48 Zeichen, Deutsch raus |
+| `/qr-code-for/barbershops` | 163 | 0,61% | 10,0 | metaTitle war 68 Zeichen → Fallback griff auf generisches „QR Codes for Barbershops \| QR Master". Jetzt 44 Zeichen mit Nutzen |
+| `/learn` | 226 | 0,88% | 11,3 | Zielt auf „qr mastery" (130 Imp @ Pos 5,1). Description führt jetzt mit den Problemen statt mit „Learning Hub" |
+| `/bulk-qr-code-generator` | 296 | 2,36% | 23,1 | Description nennt offen „Output is static — not dynamic or trackable" (Belief 5 / Proof-Layer) |
+
+Zusätzlich überarbeitet: crypto, facebook, url, vcard, instagram, tiktok, twitter, zoom, geolocation, barcode-generator, custom-qr-code-generator, alternatives/beaconstac, blog/microsoft-teams-qr-code.
+
+## Zwei Korrekturen an bestehenden Claims
+
+- **`/alternatives/beaconstac`**: Erster Entwurf enthielt „Not €99+" über Uniqode. Der Offer Brief verifiziert Uniqodes Preis **nicht** (nur „G2-Muster: teuer für kleine Teams"). Behauptung entfernt — genannt werden nur die eigenen, verifizierten Preise €0/€9/€29.
+- **Pricing-Card**: „Bulk QR Creation (up to 1,000)" → „(up to 1,000, static output)" in `en.json`. Das war Immediate Next Action #1 aus dem Offer Brief (A2) und die größte Transparenz-Lücke auf der Seite.
+
+## Was als Nächstes mehr bringt als weitere Copy
+
+1. **Ranking, nicht CTR.** 31% der Impressionen liegen auf Position 30+. Der Hebel dort ist Content/Links, nicht der Title.
+2. **Die Kündigungs-Policy (Offer Brief A3).** ToS §4 sagt „may affect the availability of dynamic QR codes". Für genau diese Zielgruppe ist das das Erkennungszeichen der schlechten Anbieter. Blockiert den gesamten Proof-Layer.
+3. **10–15 unabhängige Reviews auf G2/Capterra.** Laut Offer Brief §8 höher priorisiert als jede Copy-Iteration.
+
+## Messung
+
+In 4 Wochen im GSC vergleichen — **pro Seite und positionsbereinigt**, nicht site-weit:
+
+- `/` — Ziel 7–9% (von 4,88%, bei stabiler Pos ~4,6)
+- `/learn` — Ziel 1,8–2,5% (von 0,88%)
+- `/qr-code-for/barbershops` — Ziel 2,0–2,5% (von 0,61%)
+- `/tools/zoom-qr-code` — Ziel 1,2% (von 0,65%)
+- `/tools/teams-qr-code` — Ziel 4–5% (von 3,25%)
+
+Wenn die Position sich gleichzeitig verändert, ist der Vergleich der Rohwerte wertlos — dann `gsc-ctr-by-position` verwenden.

DEPLOY_TESTUMGEBUNG_ANLEITUNG.md

@@ -0,0 +1,314 @@
+# Anleitung: Testumgebung testmodul.qrmaster.net aufsetzen
+
+Diese Anleitung richtet auf dem Produktionsserver eine **zweite, getrennte Instanz** von
+QR Master ein, erreichbar unter `testmodul.qrmaster.net`. Sie läuft auf dem Branch `test`
+mit einer eigenen, leeren Datenbank.
+
+Die laufende Produktion wird dabei **nicht angefasst**. Alle Schritte hier legen neue
+Container, ein neues Volume und ein neues Verzeichnis an.
+
+## Kurzfassung zum Abhaken
+
+Wer die Begründungen nicht braucht, arbeitet diese Liste ab. Die ausführlichen Abschnitte
+darunter erklären jeden Schritt und was schiefgehen kann.
+
+- [ ] **1.** Repo klonen, Branch `test`, **eigenes Verzeichnis** neben der Produktion
+- [ ] **2.** `.env.test` von Timo dort ablegen und die vier Kernwerte prüfen
+- [ ] **3.** Stack bauen und starten (`-p qrmaster-test`)
+- [ ] **4.** Schema aus Prod dumpen und einspielen - **kein** `prisma migrate`
+- [ ] **5.** Testaccount per SQL anlegen (Registrierungsformular funktioniert nicht)
+- [ ] **6.** Caddy-Block ergänzen und neu laden
+- [ ] **7.** Abnahme: DB-Trennung, keine Migrationen, robots.txt, Browser-Test
+
+### Alle Befehle am Stück
+
+```bash
+# 1 - Checkout (NICHT im Produktionsverzeichnis)
+git clone -b test https://git.bizmatch.net/tknuth/QR-master.git qrmaster-test
+cd qrmaster-test
+git branch --show-current          # muss "test" zeigen
+
+# 2 - .env.test hier ablegen, dann pruefen
+grep -E "NEXT_PUBLIC_WWW_URL|NEXT_PUBLIC_APP_URL|AUTH_COOKIE_NAME|POSTGRES_DB" .env.test
+# Erwartet: beide URLs auf testmodul, AUTH_COOKIE_NAME=userId_test,
+# POSTGRES_DB=qrmaster_test. Steht dort app./www. -> STOPP, siehe Schritt 2.
+
+# 3 - Stack starten
+docker compose -p qrmaster-test --env-file .env.test \
+  -f docker-compose.yml -f docker-compose.test.yml up -d --build
+docker ps --filter "name=qrmaster-test" --format "table {{.Names}}\t{{.Status}}"
+
+# 4 - Schema (nur Struktur, keine Kundendaten)
+docker exec qrmaster-db pg_dump -U postgres --schema-only qrmaster > schema.sql
+docker exec -i qrmaster-test-db psql -U postgres -d qrmaster_test < schema.sql
+docker exec qrmaster-test-db psql -U postgres -d qrmaster_test -c "\dt" | head -20
+
+# 5 - Testaccount: erst Hash erzeugen, dann in den INSERT einsetzen
+docker exec qrmaster-test-web node -e "console.log(require('bcryptjs').hashSync('DEIN_TESTPASSWORT',12))"
+docker exec -i qrmaster-test-db psql -U postgres -d qrmaster_test -c "INSERT INTO \"User\" (id,email,name,password,\"emailVerified\",\"updatedAt\") VALUES ('testuser1','test@qrmaster.net','Test','HIER_DER_HASH',now(),now());"
+
+# 6 - Caddy: Block ergaenzen (siehe Schritt 6), dann
+caddy reload --config /etc/caddy/Caddyfile
+
+# 7 - Abnahme
+docker exec qrmaster-test-db psql -U postgres -d qrmaster_test -c 'SELECT count(*) FROM "User";'
+docker exec qrmaster-db psql -U postgres -d qrmaster -c 'SELECT count(*) FROM "User";'
+docker logs qrmaster-test-web 2>&1 | head -20
+curl -s https://testmodul.qrmaster.net/robots.txt
+```
+
+Die beiden `count(*)` müssen sich unterscheiden, in den Logs darf kein "Applying Prisma
+migrations" stehen, und `robots.txt` muss `Disallow: /` liefern.
+
+## Voraussetzungen
+
+- SSH-Zugang zum Server, auf dem QR Master läuft
+- Docker und Docker Compose (mindestens v2.24 - wird für `!override` und `!reset` gebraucht;
+  prüfen mit `docker compose version`)
+- Schreibrechte auf die Caddy-Konfiguration
+- Die Datei **`.env.test`** - die kommt von Timo und ist nicht im Repository, weil sie
+  Passwörter enthält
+- Der DNS-Eintrag `testmodul.qrmaster.net` existiert bereits (CNAME)
+
+## Was NICHT angefasst wird
+
+- Das bestehende Produktionsverzeichnis: dort **nicht** den Branch wechseln. Ein späterer
+  Prod-Rebuild würde sonst Testcode bauen.
+- Die Produktions-`.env`
+- Die bestehenden Caddy-Blöcke für `www.qrmaster.net`, `app.qrmaster.net` und `qrmaster.net`
+- Die Produktionsdatenbank. Der einzige Zugriff darauf ist ein `pg_dump --schema-only`,
+  das ausschließlich liest.
+
+---
+
+## 1. Zweites Checkout anlegen
+
+**Nicht** im Produktionsverzeichnis arbeiten. Ein eigenes Verzeichnis daneben, z.B. im
+selben übergeordneten Ordner:
+
+```bash
+git clone -b test https://git.bizmatch.net/tknuth/QR-master.git qrmaster-test
+```
+
+Danach in dieses Verzeichnis wechseln. **Alle weiteren Befehle laufen von dort**, sofern
+nicht anders angegeben.
+
+```bash
+cd qrmaster-test
+```
+
+Prüfen, dass der richtige Branch ausgecheckt ist - es muss `test` erscheinen:
+
+```bash
+git branch --show-current
+```
+
+## 2. `.env.test` ablegen
+
+Die von Timo erhaltene Datei als `.env.test` in dieses Verzeichnis legen (also
+`qrmaster-test/.env.test`).
+
+Kurz gegenprüfen, dass die vier wichtigsten Werte stimmen:
+
+```bash
+grep -E "NEXT_PUBLIC_WWW_URL|NEXT_PUBLIC_APP_URL|AUTH_COOKIE_NAME|POSTGRES_DB" .env.test
+```
+
+Erwartet:
+
+```
+NEXT_PUBLIC_WWW_URL=https://testmodul.qrmaster.net
+NEXT_PUBLIC_APP_URL=https://testmodul.qrmaster.net
+AUTH_COOKIE_NAME=userId_test
+POSTGRES_DB=qrmaster_test
+```
+
+Steht bei einer der URLs `app.qrmaster.net` oder `www.qrmaster.net`, **nicht starten** -
+dann würden Klicks in der Testumgebung in die Produktion umleiten.
+
+## 3. Stack bauen und starten
+
+```bash
+docker compose -p qrmaster-test --env-file .env.test -f docker-compose.yml -f docker-compose.test.yml up -d --build
+```
+
+Der erste Build dauert einige Minuten. Der Projektname `-p qrmaster-test` ist wichtig: er
+sorgt dafür, dass eigene Container und ein eigenes Volume entstehen und nichts aus der
+Produktion überschrieben wird.
+
+Läuft alles, sollten drei neue Container existieren:
+
+```bash
+docker ps --filter "name=qrmaster-test" --format "table {{.Names}}\t{{.Status}}"
+```
+
+Erwartet: `qrmaster-test-db`, `qrmaster-test-redis`, `qrmaster-test-web`.
+
+Die Anwendung kann zu diesem Zeitpunkt noch nichts anzeigen - die Datenbank ist leer. Das
+ist normal und wird im nächsten Schritt behoben.
+
+## 4. Datenbankschema einspielen
+
+Die Testdatenbank bekommt **nur die Struktur** aus der Produktion, keine Daten. Es werden
+also keine Kundendaten kopiert.
+
+Struktur aus der Produktionsdatenbank exportieren (reiner Lesezugriff):
+
+```bash
+docker exec qrmaster-db pg_dump -U postgres --schema-only qrmaster > schema.sql
+```
+
+In die Testdatenbank einspielen:
+
+```bash
+docker exec -i qrmaster-test-db psql -U postgres -d qrmaster_test < schema.sql
+```
+
+> **Wichtig:** Nicht `prisma migrate` verwenden. Die Migrationsdateien im Repository sind
+> seit April 2026 nicht mehr gepflegt - alle Schemaänderungen seitdem wurden per SQL
+> gemacht. Ein `migrate deploy` würde ein veraltetes Schema erzeugen, mit dem die
+> Anwendung nicht läuft. Der Container startet deshalb bewusst ohne Migrationsschritt.
+
+Prüfen, dass Tabellen angekommen sind:
+
+```bash
+docker exec qrmaster-test-db psql -U postgres -d qrmaster_test -c "\dt" | head -20
+```
+
+## 5. Testaccount anlegen
+
+Die Registrierung über das Formular funktioniert hier **nicht**: die Testumgebung
+verschickt bewusst keine E-Mails, und ohne Bestätigungsmail wird der Account vom System
+wieder gelöscht. Der Account wird deshalb direkt in der Datenbank angelegt.
+
+Zuerst einen Passwort-Hash erzeugen (`DEIN_TESTPASSWORT` durch ein selbst gewähltes
+Passwort ersetzen):
+
+```bash
+docker exec qrmaster-test-web node -e "console.log(require('bcryptjs').hashSync('DEIN_TESTPASSWORT',12))"
+```
+
+Die Ausgabe ist eine Zeichenkette, die mit `$2a$12$` oder `$2b$12$` beginnt. Diese im
+folgenden Befehl anstelle von `HIER_DER_HASH` einsetzen:
+
+```bash
+docker exec -i qrmaster-test-db psql -U postgres -d qrmaster_test -c "INSERT INTO \"User\" (id,email,name,password,\"emailVerified\",\"updatedAt\") VALUES ('testuser1','test@qrmaster.net','Test','HIER_DER_HASH',now(),now());"
+```
+
+Anmeldung erfolgt danach ganz normal über `/login` mit `test@qrmaster.net` und dem
+gewählten Passwort.
+
+## 6. Caddy konfigurieren
+
+Einen neuen Block in die Caddy-Konfiguration aufnehmen (Pfad ggf. anpassen). Die
+bestehenden Blöcke bleiben unverändert:
+
+```caddyfile
+testmodul.qrmaster.net {
+    reverse_proxy qrmaster-test-web:3000
+}
+```
+
+Konfiguration neu laden:
+
+```bash
+caddy reload --config /etc/caddy/Caddyfile
+```
+
+Caddy holt das TLS-Zertifikat automatisch. Das kann eine Minute dauern.
+
+## 7. Abnahme
+
+**a) Datenbanken sind getrennt.** Die beiden Zahlen müssen sich unterscheiden - die
+Testdatenbank enthält nur den eben angelegten Account:
+
+```bash
+docker exec qrmaster-test-db psql -U postgres -d qrmaster_test -c 'SELECT count(*) FROM "User";'
+```
+
+```bash
+docker exec qrmaster-db psql -U postgres -d qrmaster -c 'SELECT count(*) FROM "User";'
+```
+
+**b) Keine Migrationen gelaufen.** In der Ausgabe darf **nicht** "Applying Prisma
+migrations" stehen:
+
+```bash
+docker logs qrmaster-test-web 2>&1 | head -20
+```
+
+**c) Suchmaschinen ausgesperrt.** Muss `Disallow: /` liefern:
+
+```bash
+curl -s https://testmodul.qrmaster.net/robots.txt
+```
+
+**d) Im Browser:**
+
+- `https://testmodul.qrmaster.net` lädt mit gültigem Zertifikat
+- Anmeldung mit dem Testaccount funktioniert
+- `https://testmodul.qrmaster.net/dashboard` **bleibt auf testmodul** und springt nicht auf
+  `app.qrmaster.net`. Passiert das doch, sind die URLs in der `.env.test` falsch.
+- In den Entwicklertools unter Application → Cookies liegen zwei getrennte Cookies:
+  `userId` mit Domain `.qrmaster.net` (Produktion) und `userId_test` mit Domain
+  `testmodul.qrmaster.net`
+- Die Produktion ist weiterhin erreichbar und man ist dort weiterhin angemeldet
+
+---
+
+## Laufender Betrieb
+
+Neuen Stand deployen, nachdem auf dem Branch `test` etwas gepusht wurde - aus dem
+Verzeichnis `qrmaster-test`:
+
+```bash
+git pull
+```
+
+```bash
+docker compose -p qrmaster-test --env-file .env.test -f docker-compose.yml -f docker-compose.test.yml up -d --build
+```
+
+Ein Rebuild ist **immer** nötig, ein bloßer Neustart genügt nicht: die Host-URLs und der
+Cookie-Name werden beim Bauen fest in die Anwendung kompiliert.
+
+Schemaänderungen werden weiterhin **von Hand per SQL** ausgeführt - erst auf Test, nach
+erfolgreicher Prüfung dasselbe Statement auf Produktion. Es gibt keinen automatischen Weg
+dazwischen.
+
+## Testumgebung stoppen oder entfernen
+
+Stoppen, Daten bleiben erhalten:
+
+```bash
+docker compose -p qrmaster-test --env-file .env.test -f docker-compose.yml -f docker-compose.test.yml down
+```
+
+Vollständig entfernen inklusive Testdatenbank - der Projektname `-p qrmaster-test` sorgt
+dafür, dass ausschließlich die Test-Volumes gelöscht werden:
+
+```bash
+docker compose -p qrmaster-test --env-file .env.test -f docker-compose.yml -f docker-compose.test.yml down -v
+```
+
+## Wenn etwas nicht funktioniert
+
+| Symptom | Ursache |
+|---|---|
+| Build bricht ab mit `set AUTH_COOKIE_NAME in .env.test` | `.env.test` fehlt oder liegt im falschen Verzeichnis |
+| `qrmaster-test-db` bleibt `unhealthy`, `web` startet nicht | In der `.env.test` steht nicht `POSTGRES_DB=qrmaster_test` |
+| Caddy liefert 502 | Containername im Caddy-Block stimmt nicht, oder der Container läuft nicht - mit `docker ps` prüfen |
+| Anwendung meldet `column ... does not exist` | Schema-Import aus Schritt 4 war unvollständig - erneut einspielen |
+| `/dashboard` springt auf `app.qrmaster.net` | Die URLs in der `.env.test` zeigen nicht auf testmodul. Korrigieren und **neu bauen**, nicht nur neu starten. |
+| Anmeldung wirkt zufällig abgelaufen | `AUTH_COOKIE_NAME` ist nicht gesetzt oder steht auf `userId` - dann kollidiert es mit dem Produktions-Cookie |
+| Registrierung über das Formular schlägt fehl | Erwartet - die Testumgebung verschickt keine E-Mails. Account per SQL anlegen, Schritt 5. |
+
+## Bekannte Einschränkungen der Testumgebung
+
+Bewusst deaktiviert, weil die Umgebung nach außen nichts auslösen soll:
+
+- **Kein E-Mail-Versand** - Registrierung, Passwort-Reset und Benachrichtigungen funktionieren nicht
+- **Kein Google-Login** - Zugangsdaten sind nicht hinterlegt
+- **Keine Datei-Uploads** - der Objektspeicher (R2) ist nicht konfiguriert
+- **Kein Stripe** - Checkout und Abo-Verwaltung funktionieren nicht, solange keine Testschlüssel eingetragen sind
+- **Keine Analytics** - damit die Produktionszahlen nicht verfälscht werden

Dockerfile

@@ -31,12 +31,35 @@ ENV NEXTAUTH_SECRET="build-time-secret"
 ENV IP_SALT="build-time-salt"
 ENV STRIPE_SECRET_KEY="sk_test_placeholder_for_build"
 ENV RESEND_API_KEY="re_placeholder_for_build"
-ENV NEXT_PUBLIC_APP_URL="https://www.qrmaster.net"
+# Marketing host vs app host. NEXT_PUBLIC_WWW_URL must stay on www in production: it is the
+# origin encoded into downloaded QR codes and used for public email links.
+# Declared as ARG so the staging overlay can build the same image pointing at
+# testmodul.qrmaster.net - the defaults keep a plain production build unchanged.
+ARG NEXT_PUBLIC_WWW_URL="https://www.qrmaster.net"
+ENV NEXT_PUBLIC_WWW_URL=$NEXT_PUBLIC_WWW_URL
+ARG NEXT_PUBLIC_APP_URL="https://app.qrmaster.net"
+ENV NEXT_PUBLIC_APP_URL=$NEXT_PUBLIC_APP_URL
 # PostHog Analytics - REQUIRED at build time for client-side bundle
 ENV NEXT_PUBLIC_POSTHOG_KEY="phc_97JBJVVQlqqiZuTVRHuBnnG9HasOv3GSsdeVjossizJ"
 ENV NEXT_PUBLIC_POSTHOG_HOST="https://us.i.posthog.com"
 ENV NEXT_PUBLIC_INDEXABLE="true"
 ENV NEXT_PUBLIC_FACEBOOK_PIXEL_ID="1601718491252690"
+# Umami Analytics - REQUIRED at build time (NEXT_PUBLIC_* is inlined by the compiler)
+ARG NEXT_PUBLIC_UMAMI_SRC=""
+ARG NEXT_PUBLIC_UMAMI_ID=""
+ENV NEXT_PUBLIC_UMAMI_SRC=$NEXT_PUBLIC_UMAMI_SRC
+ENV NEXT_PUBLIC_UMAMI_ID=$NEXT_PUBLIC_UMAMI_ID
+ARG SMTP_USER=""
+ENV SMTP_USER=$SMTP_USER
+# Shared session cookie across www.* and app.*. Needed at build time too: process.env is
+# inlined into the Edge middleware bundle, so a runtime-only value would leave the
+# middleware and the route handlers disagreeing about the cookie scope.
+ARG COOKIE_DOMAIN=""
+ENV COOKIE_DOMAIN=$COOKIE_DOMAIN
+# Distinct session cookie name for the staging deployment, so its cookie cannot collide
+# with the production one the browser also sends to testmodul.qrmaster.net.
+ARG AUTH_COOKIE_NAME=""
+ENV AUTH_COOKIE_NAME=$AUTH_COOKIE_NAME
 RUN npx prisma generate
 RUN npm run build
 
@@ -51,17 +74,18 @@ ENV NEXT_TELEMETRY_DISABLED=1
 RUN addgroup --system --gid 1001 nodejs
 RUN adduser --system --uid 1001 nextjs
 
-COPY --from=builder /app/node_modules ./node_modules
-COPY --from=builder /app/prisma ./prisma
-COPY --from=builder /app/.next/standalone ./
-COPY --from=builder /app/.next/static ./.next/static
-COPY --from=builder /app/public ./public
-COPY --from=builder /app/docker/entrypoint.sh ./docker/entrypoint.sh
+COPY --from=builder --chown=nextjs:nodejs /app/node_modules ./node_modules
+COPY --from=builder --chown=nextjs:nodejs /app/prisma ./prisma
+COPY --from=builder --chown=nextjs:nodejs /app/.next/standalone ./
+COPY --from=builder --chown=nextjs:nodejs /app/.next/static ./.next/static
+COPY --from=builder --chown=nextjs:nodejs /app/public ./public
+COPY --from=builder --chown=nextjs:nodejs /app/docker/entrypoint.sh ./docker/entrypoint.sh
 
 RUN chmod +x ./docker/entrypoint.sh
 
-# --- NEU: Ordner erstellen und Rechte an den nextjs User geben ---
-RUN mkdir -p /app/.next/cache && chown nextjs:nodejs /app/.next/cache
+# Next writes ISR/prerender artifacts under .next/server/app at runtime.
+RUN mkdir -p /app/.next/cache /app/.next/server/app \
+  && chown -R nextjs:nodejs /app/.next
 
 USER nextjs
 

PLAN_APP_SUBDOMAIN_2026-08-12.md

@@ -0,0 +1,259 @@
+# Plan: Dashboard auf app.qrmaster.net
+
+Stand: 2026-08-12 · Ziel: die eingeloggte App liegt auf `app.qrmaster.net`, Marketing/SEO bleibt auf `www.qrmaster.net`.
+
+## Status
+
+| Schritt | Stand |
+|---|---|
+| B1 Cookie-Domain | committed + gepusht (`35ea8cc`) |
+| B2–B7 | Code fertig, typecheck + Production-Build grün, **noch nicht deployt** |
+| A4 Google Console | erledigt (beide Redirect-URIs eingetragen) |
+| A1 DNS, A2 Caddy, A3 .env, A6 Deploy | offen bei Timo |
+
+Deploy-Reihenfolge unverändert: B1 zuerst allein live und einen Tag beobachten, dann B2–B7.
+
+Neu gegenüber dem ursprünglichen Plan: `src/lib/hosts.ts` ist die einzige Quelle der Wahrheit
+für die Host-Grenze (`APP_PATH_PREFIXES`, `isAppPath`, `wwwUrl`, `appUrl`, `urlForPath`).
+Middleware, Stripe-Rückkehr-URLs und E-Mail-Links lesen alle daraus, damit sie nicht
+auseinanderdriften.
+
+## Zielarchitektur
+
+**Ein Docker-Image, ein Container, zwei Hostnames.** Caddy routet `www.qrmaster.net` und
+`app.qrmaster.net` auf denselben Upstream. Die Middleware macht Host-basiertes Routing.
+
+**Wichtig: keine Datei zieht um.** Die Next-App serviert auf beiden Hosts weiterhin alle Routen.
+`src/middleware.ts` entscheidet pro Host, welcher Pfad ausgeliefert wird, und 301t den Rest auf den
+jeweils anderen Host. Damit bleiben alle relativen Links (`router.push('/dashboard')`,
+`<Link href="/settings">`) unverändert korrekt, weil sie innerhalb desselben Hosts aufgelöst werden.
+
+```
+qrmaster.net        --301-->  www.qrmaster.net              (bleibt wie heute)
+www.qrmaster.net    ->  Marketing, /login, /signup, /r/*, /api/*
+app.qrmaster.net    ->  /dashboard /create /analytics /settings /bulk-creation
+                        /integrations /qr/* /upgrade /onboarding, /api/*
+```
+
+## Fixierte Entscheidungen
+
+| Frage | Entscheidung | Begründung |
+|---|---|---|
+| Hosting | Docker + Caddy auf eigenem Server | Bestand |
+| `/login`, `/signup` | **bleiben auf www** | Alle 82 Marketing-CTAs zeigen auf `/signup`, `/signup` hat ein hartes Canonical auf www und trägt Ad-Traffic. Umzug wäre teuer ohne Nutzen. |
+| `/onboarding` | zieht auf app | Reiner Logged-in-Flow, kein SEO-Wert |
+| Host-Wechsel | genau **einmal**, nach erfolgreichem Login/Signup | einzige Cross-Host-Stelle im ganzen Flow |
+| DB | keine Änderung | — |
+
+## Teil A — Deine Aufgaben (Timo)
+
+Reihenfolge beachten: A1–A2 **vor** dem Deploy von Schritt B5, sonst zeigt die Subdomain ins Leere.
+
+### A1. DNS
+CNAME `app` → auf denselben Zielhost wie `www` (bzw. A-Record auf dieselbe Server-IP).
+Kein Proxy-Only-Sonderfall nötig, Caddy holt das Cert selbst.
+
+### A2. Caddyfile auf dem Server
+`app.qrmaster.net` in den bestehenden Site-Block aufnehmen, damit Caddy automatisch ein
+Let's-Encrypt-Cert zieht:
+
+```caddyfile
+www.qrmaster.net, app.qrmaster.net {
+    reverse_proxy qrmaster-web:3000
+}
+```
+
+Danach `caddy reload`. Prüfen: `curl -sI https://app.qrmaster.net` muss 200 oder 301 liefern,
+kein TLS-Fehler.
+
+### A3. `.env` auf dem Server ergänzen
+Zwei Variablen statt einer. Die Trennung ist der Kern des ganzen Umbaus:
+
+Für **Deploy 1** reicht:
+
+```dotenv
+COOKIE_DOMAIN=.qrmaster.net
+```
+
+Für **Deploy 2** kommen dazu:
+
+```dotenv
+NEXT_PUBLIC_WWW_URL=https://www.qrmaster.net
+NEXT_PUBLIC_APP_URL=https://app.qrmaster.net
+```
+
+`NEXT_PUBLIC_APP_URL` erst zu Deploy 2 umstellen - vorher zeigt es auf www und muss dort
+bleiben. Fehlen die Werte, greifen die Produktions-Fallbacks in `src/lib/hosts.ts`; ein
+localhost-Wert kann damit nicht in gedruckte QR-Codes gelangen.
+
+`NEXTAUTH_URL` bleibt `https://www.qrmaster.net` (wird nur noch von
+`api/social-assets/route.ts` gelesen, kein Auth-Bezug mehr).
+
+### A4. Google Cloud Console
+Bei den OAuth-Credentials als **Authorized redirect URI** zusätzlich eintragen:
+
+```
+https://app.qrmaster.net/api/auth/google
+```
+
+Die alte www-URI **nicht löschen** – sie wird während der Übergangszeit noch von
+Sessions genutzt, die den Flow auf www gestartet haben.
+
+### A5. Nichts zu tun bei Stripe und TikTok
+- Stripe-Webhook zeigt auf `www.qrmaster.net/api/stripe/webhook` und bleibt gültig
+  (`/api/*` wird auf beiden Hosts weiter bedient, siehe B5).
+- TikTok `redirect_uri` bleibt auf `qrmaster.net` – verifizierte Domain, nicht anfassen.
+
+### A6. Deploy
+`npm run docker:prod` (Rebuild ist zwingend – `NEXT_PUBLIC_*` wird zur Build-Zeit ins
+Client-Bundle inlined, ein reiner Container-Restart genügt **nicht**).
+
+## Teil B — Meine Aufgaben (Code), in Diff-Reihenfolge
+
+### B1. Cookie-Domain teilen — muss zuerst live sein
+Ohne das ist auf `app.qrmaster.net` jeder ausgeloggt: das `userId`-Cookie ist heute host-only.
+
+- `src/lib/cookieConfig.ts:11` — `getAuthCookieOptions()`: `domain: process.env.COOKIE_DOMAIN` in Prod, in Dev `undefined` (localhost verträgt keine Punkt-Domain)
+- `src/lib/cookieConfig.ts:24` — `getCsrfCookieOptions()`: dito
+- `src/middleware.ts:34` — Attribution-Cookie: dito
+- `src/app/(main)/api/auth/logout/route.ts:7` — **kritisch**: löscht heute host-only. Nach der
+  Umstellung existieren bei Bestandsnutzern beide Varianten (alt host-only + neu domain-scoped).
+  Logout muss **beide** überschreiben, sonst bleibt ein Zombie-Cookie und der Nutzer ist nicht
+  wirklich ausgeloggt. Gilt für `userId`, `newsletter-admin` und das Attribution-Cookie.
+- `src/app/(main)/api/auth/google/route.ts:53,62` — OAuth-State + Post-Auth-Redirect-Cookie
+
+Kein Forced-Logout nötig: beide Cookie-Varianten tragen denselben signierten Wert, der Server
+akzeptiert jede. `verifySignedUserIdEdge` prüft die Signatur, das Teilen über eigene Subdomains
+ist unkritisch.
+
+**Dieser Schritt kann allein auf www deployt werden, bevor die Subdomain existiert** — nach außen
+unsichtbar, und wenn app.* dann live geht, funktionieren Sessions sofort.
+
+### B2. `NEXT_PUBLIC_APP_URL` entflechten
+Die Variable bedient heute App- **und** öffentliche URLs. Jede Fundstelle einzeln zuordnen:
+
+**Muss auf `WWW_URL` (öffentlich, teils in QR-Codes kodiert):**
+- `src/components/dashboard/QRCodeCard.tsx:82` — **höchstes Risiko im ganzen Umbau**: Basis für
+  die in den QR-Code kodierte `/r/<slug>`-URL. Bleibt das auf `APP_URL`, zeigen alle neu
+  heruntergeladenen und gedruckten Codes auf die Subdomain.
+- `src/app/(main)/r/[slug]/route.ts:50,61,84,89` — Landing-Basis vcard/text/coupon/feedback
+- `src/lib/email.ts:56,562`, `src/lib/marketingEmail.ts:30` — Mail-Links auf Marketing-Inhalte
+- `src/app/(main)/api/auth/signup/route.ts:20` — Verify-Mail-Link
+- `src/app/(main)/api/stripe/checkout/route.ts:64` — `cancel_url` → `/pricing`
+- `src/lib/metaConversions.ts:44`, `src/app/(main)/api/auth/signup/route.ts:150` — Event-Source-URLs
+
+**Bleibt/wird `APP_URL` (eingeloggt):**
+- `src/app/(main)/api/stripe/checkout/route.ts:63` — `success_url` → `/dashboard`
+- `src/app/(main)/api/stripe/create-checkout-session/route.ts:112,128` — `appUrl` + returnPath
+- `src/app/(main)/api/stripe/portal/route.ts:59` — `return_url` → `/settings`
+- `src/lib/email.ts:505` — hartcodiertes `https://www.qrmaster.net/dashboard` im Mail-Footer
+- `src/app/(main)/api/auth/google/route.ts:40,97` — `redirect_uri` (deckt A4 ab)
+
+### B3. Post-Auth-Sprung auf app.*
+Die einzige Cross-Host-Stelle. `sanitizeRedirectPath` (`src/lib/auth-flow.ts:4`) erlaubt bewusst
+nur relative Pfade — bleibt so, ich baue den Host separat davor:
+
+- `src/app/(main)/(auth)/login/ClientPage.tsx:56` und `login/LoginClient.tsx:65`
+- `src/app/(main)/(auth)/signup/ClientPage.tsx:70`
+- `src/app/(main)/api/auth/google/route.ts:224,228` — Server-Redirect
+- `src/app/(main)/api/auth/verify-email/route.ts:38` — setzt Cookie und redirected
+- `src/lib/auth-flow.ts:46` — `getPostOnboardingDestination`
+
+Muster: relativen Zielpfad wie heute bestimmen, dann `new URL(path, APP_URL)`. Weil das
+Auth-Cookie nach B1 auf `.qrmaster.net` gilt, ist der Nutzer nach dem Sprung sofort eingeloggt —
+kein Token-Handover über die URL nötig.
+
+### B4. Onboarding-Checkliste
+`src/components/dashboard/OnboardingChecklist.tsx:141` verlinkt `/onboarding` mit
+`redirect=/dashboard`. Beide Pfade liegen nach dem Umzug auf app.* → bleibt relativ, keine
+Änderung. Nur verifizieren.
+
+### B5. Middleware: Host-Routing
+`src/middleware.ts` — Kern des Umbaus. Der bestehende Apex-Redirect (Zeile 49) bleibt unberührt.
+Neu, direkt danach:
+
+- Host `app.qrmaster.net`:
+  - `/api/*`, `/_next/*`, statische Dateien: durchlassen (Stripe-Webhook, CSRF, alles)
+  - `protectedPaths` (Zeile 145) + `/upgrade` + `/onboarding`: bedienen wie heute
+  - alles andere: 301 auf `WWW_URL` + gleicher Pfad
+  - `/r/*`: 301 auf www — QR-Redirects gehören nicht auf die App-Subdomain
+- Host `www.qrmaster.net`:
+  - `protectedPaths` + `/upgrade` + `/onboarding`: 301 auf `APP_URL` + Pfad + Query
+    (damit alte Bookmarks und der Mail-Footer-Link weiter funktionieren)
+- Auth-Fail-Redirect (Zeile 166): zeigt auf `/signup` — das liegt auf www, also absolut
+  auf `WWW_URL` umstellen, `redirect`-Param bleibt relativ
+
+`/login` und `/signup` bleiben in `publicPaths` und werden nur auf www bedient.
+
+### B6. Indexierung der Subdomain dichtmachen
+`app.*` darf nicht in den Index, sonst Duplicate Content.
+
+- `src/middleware.ts`: auf Host `app.*` `X-Robots-Tag: noindex, nofollow` auf alle Responses
+- `public/robots-app.txt` neu anlegen (`User-agent: * / Disallow: /`), Middleware rewritet
+  `/robots.txt` auf app.* dorthin. `src/app/robots.ts` bleibt für www unverändert.
+- `/sitemap.xml` auf app.* → 301 auf www
+
+Gute Nachricht: `/dashboard`, `/create`, `/settings` sind in `src/app/robots.ts:7` bereits
+disallowed und nicht in der Sitemap → **kein Ranking-Verlust durch den Umzug.** Die Canonicals
+sind ohnehin hart auf www verdrahtet (`src/app/(main)/layout.tsx:13`).
+
+### B7. Docker-Env-Kette
+`NEXT_PUBLIC_*` wird zur Build-Zeit inlined **und** zur Laufzeit serverseitig gelesen. Beide
+Stellen müssen übereinstimmen, sonst gibt es Bugs, die nur im Client oder nur im Server auftreten:
+
+- `Dockerfile:34` — `NEXT_PUBLIC_APP_URL` auf `https://app.qrmaster.net`, neu
+  `ENV NEXT_PUBLIC_WWW_URL="https://www.qrmaster.net"`
+- `docker-compose.yml:58` — `NEXT_PUBLIC_WWW_URL` und `COOKIE_DOMAIN` ins `environment` des
+  `web`-Service durchreichen
+- `env.example` + `.env.example` — neue Variablen dokumentieren
+- `src/lib/env.ts` — optional, das Schema kennt `NEXT_PUBLIC_*` bisher gar nicht
+
+## Deploy-Choreografie
+
+Zwei Deploys, nicht einer. Das entkoppelt das Cookie-Risiko vom Routing-Risiko:
+
+1. **Deploy 1 (nur B1):** Cookie-Domain auf `.qrmaster.net`. Nur www ist live, nach außen
+   unsichtbar. 24 h beobachten: Login, Logout, Checkout müssen normal laufen.
+2. **A1 + A2 + A4:** DNS, Caddy, Google Console. `app.qrmaster.net` antwortet, serviert aber
+   noch dieselbe App wie www — unkritisch, weil noch nicht verlinkt und dank B6 noch nicht
+   indexierbar.
+3. **Deploy 2 (B2–B7):** Host-Routing scharf. Ab hier springt Login auf app.*.
+
+Rollback: Deploy 2 zurücknehmen. Weil das Cookie auf `.qrmaster.net` gilt, bleiben Sessions
+auch nach dem Rollback auf www gültig — niemand wird ausgeloggt. DNS/Caddy können stehen bleiben.
+
+## Testcheckliste (nach Deploy 2)
+
+Jeweils über beide Hosts:
+
+- [ ] `www.qrmaster.net/dashboard` → 301 auf `app.qrmaster.net/dashboard`, eingeloggt
+- [ ] `app.qrmaster.net/pricing` → 301 auf www
+- [ ] Signup auf www → Verify-Mail → Link führt eingeloggt auf app.*
+- [ ] Google-Login von www aus → landet eingeloggt auf app.*/dashboard bzw. /onboarding
+- [ ] Logout auf app.* → auf www **auch** ausgeloggt (prüft B1, häufigster Fehler)
+- [ ] Checkout: Upgrade auf app.* → Stripe → `success_url` app.*/dashboard, Abbruch → www/pricing
+- [ ] Stripe-Portal → zurück auf app.*/settings
+- [ ] Stripe-Webhook feuert weiter (Dashboard → Events, keine 4xx)
+- [ ] **QR-Code neu anlegen + herunterladen → kodierte URL ist `www.qrmaster.net/r/<slug>`**,
+      nicht app.* (prüft B2, das teuerste Fehlerbild)
+- [ ] Bestehender `/r/<slug>` redirected + trackt weiter, vcard/coupon/feedback-Landings laden
+- [ ] Mutation auf app.* (QR umbenennen) → CSRF greift, kein 403
+- [ ] `curl -sI https://app.qrmaster.net/dashboard | grep -i x-robots-tag` → noindex
+- [ ] `https://app.qrmaster.net/robots.txt` → `Disallow: /`
+- [ ] Search Console: `app.qrmaster.net` **nicht** als Property anlegen, keine Sitemap einreichen
+
+## Risiken
+
+| Risiko | Wo | Absicherung |
+|---|---|---|
+| Gedruckte QR-Codes zeigen auf app.* | `QRCodeCard.tsx:82` | B2, explizit im Test |
+| Logout wirkt nicht (Zombie-Cookie) | `logout/route.ts` | B1 löscht beide Varianten |
+| Client/Server-Env divergieren | `Dockerfile` vs. `docker-compose.yml` | B7, beide Stellen setzen |
+| Google-OAuth bricht | Cloud Console | A4, alte URI stehen lassen |
+| Duplicate Content auf app.* | — | B6 vor Deploy 2 |
+
+## Aufwand
+
+- Deine Seite: ~45 min (DNS, Caddy, .env, Google Console, Deploy)
+- Meine Seite: ~4–6 h Code über zwei Deploys
+- Keine DB-Änderung, kein Forced-Logout, kein SEO-Verlust

PLAN_CRO_UND_RETENTION_2026-07-27.md

@@ -0,0 +1,421 @@
+# Umsetzungsplan - CRO-Momente, Upgrade-Wege und Retention-Mails
+
+Stand 27. Juli 2026. Alle Datei- und Zeilenangaben gegen den aktuellen Stand verifiziert.
+
+**Getroffene Entscheidungen:**
+- Das Dynamic-Limit zählt künftig nur noch Codes mit `status = ACTIVE`. Pausieren gibt einen Slot frei.
+- Der Upgrade-Weg im Limit-Moment läuft per Direkt-Checkout aus dem Modal. Kein Redirect auf `/pricing`.
+
+---
+
+## Phase 1 - Der Limit-Moment in `/create`
+
+### 1.1 Limit-Query auf ACTIVE umstellen
+
+**Datei:** `src/app/(main)/api/qrs/route.ts`, Zeile 117-121
+
+```ts
+const dynamicQRCount = await db.qRCode.count({
+  where: { userId, type: 'DYNAMIC', status: 'ACTIVE' },
+});
+```
+
+Dieselbe Änderung in `src/app/(main)/api/user/stats/route.ts`, sonst zeigt das Dashboard eine andere Zahl als die API durchlässt.
+
+**Nebenwirkung, die vorher klar sein muss:** Free-Nutzer, die heute pausierte Codes haben, bekommen dadurch rückwirkend Slots frei. Das ist eine Lockerung, keine Verschärfung - es nimmt niemandem etwas weg. Vor dem Deploy einmal zählen, wie viele Nutzer betroffen sind (SQL unten in Abschnitt „Prüf-Queries").
+
+### 1.2 Das Limit-Modal
+
+**Neue Datei:** `src/components/app/DynamicLimitModal.tsx`
+
+Der 403 aus `/api/qrs` liefert bereits `currentCount`, `limit` und `plan` mit. Es braucht keinen zusätzlichen Request.
+
+**Datei:** `src/app/(main)/(app)/create/page.tsx`, Zeile 456-459 - der Redirect entfällt ersatzlos:
+
+```ts
+if (response.status === 403 && responseData.error === 'Limit reached') {
+  setLimitInfo({ current: responseData.currentCount, limit: responseData.limit, plan: responseData.plan });
+  setLimitModalOpen(true);
+  return;
+}
+```
+
+Der Formular-State bleibt dadurch erhalten. Das ist der eigentliche Fix - alles andere ist Ausgestaltung.
+
+**Copy des Modals:**
+
+> ### Dein vierter Code ist fertig. Er braucht nur noch einen Platz.
+>
+> Du nutzt alle 3 dynamischen Codes deines kostenlosen Plans. Dieser hier ist gebaut und wartet - du kannst ihn behalten oder einen bestehenden freigeben.
+>
+> **[ Diesen Code mit Pro speichern - 9 € / Monat ]**
+> [ Einen bestehenden Code pausieren ]
+> [ Stattdessen als statischen Code herunterladen ]
+>
+> *Deine 3 aktiven Codes laufen weiter, egal wie du dich entscheidest.*
+
+Die Zahlen (`vierter`, `3`) kommen aus `limitInfo`, damit das Modal auch für Pro bei 51 stimmt.
+
+**Warum diese drei Optionen:**
+
+Der Hauptbutton verkauft keinen Plan, sondern rettet einen konkreten Code, den der Nutzer gerade in der Hand hat. Option 2 ist die ehrliche Alternative innerhalb des Free-Plans - sie kostet ein paar Conversions und kauft dafür Belief 5 aus dem Necessary-Beliefs-Doc. Option 3 ist der Ausweg ohne Verlust: ein statischer Code löst das Problem zu einem guten Teil, kostet nichts, und die Zusage „läuft nie ab" ist verifiziert. Der Schlusssatz ist Risk Reversal genau an der Stelle, an der die Kategorie ihren schlechtesten Ruf hat.
+
+### 1.3 Direkt-Checkout aus dem Modal
+
+Der Pro-Button ruft `/api/stripe/checkout` direkt auf, mit `priceId`, `plan: 'PRO'` und `userEmail`.
+
+**Datei:** `src/app/(main)/api/stripe/checkout/route.ts`, Zeile 63. Die `success_url` ist aktuell fest auf `/dashboard?success=true`. Sie muss eine optionale `returnPath` aus dem Request-Body akzeptieren, damit der Nutzer nach dem Kauf dorthin zurückkommt, wo er war.
+
+Vor dem Öffnen von Stripe wird der Formularzustand nach `localStorage` geschrieben (`qrm_pending_qr`, mit Zeitstempel). Beim Zurückkommen auf `/create?restored=1` liest die Seite ihn aus, füllt das Formular und zeigt: *„Willkommen zurück. Dein Code steht noch genau so da - jetzt mit Platz."* Danach den Key löschen. Einträge älter als 24 Stunden werden verworfen.
+
+Kein Draft in der Datenbank. Der Zustand ist ohnehin nur im Browser relevant, und eine Draft-Tabelle wäre Infrastruktur für ein Problem, das `localStorage` löst.
+
+### 1.4 Option „Code pausieren" im Modal
+
+Zeigt die aktiven dynamischen Codes des Nutzers mit Titel und Scan-Zahl der letzten 30 Tage. Ein Klick setzt `status = PAUSED` über das bestehende `PATCH /api/qrs/[id]`, danach wird der ursprüngliche POST automatisch wiederholt.
+
+Die Scan-Zahl daneben ist wichtig: sie macht die Entscheidung informiert statt willkürlich. Wer sieht, dass ein Code seit vier Wochen null Scans hat, pausiert ihn ohne schlechtes Gefühl - und wer sieht, dass alle drei laufen, versteht ohne Verkaufstext, warum Pro sinnvoll ist. Das ist Pointing statt Talking.
+
+---
+
+## Phase 2 - `/bulk-creation`
+
+**Datei:** `src/app/(main)/(app)/bulk-creation/page.tsx`, Zeile 232-247
+
+Die Schleife hat kein `else` zu `if (res.ok)`. Fehlgeschlagene Zeilen verschwinden still, und danach meldet ein grüner Toast `${results.length} dynamische QR-Codes erstellt!` - eine Zahl, die kleiner sein kann als das Hochgeladene, ohne jeden Hinweis.
+
+**Fix:**
+
+```ts
+const failed: { row: number; title: string; reason: string }[] = [];
+// im else-Zweig: failed.push({ row: i + 1, title, reason: (await res.json()).error })
+```
+
+Danach, wenn `failed.length > 0`, statt des Erfolgs-Toasts ein Ergebnis-Panel:
+
+> **180 von 200 Codes erstellt.**
+> 20 Zeilen konnten nicht angelegt werden, weil dein Kontingent an dynamischen Codes erschöpft ist. Hier sind sie - du kannst sie als statische Codes erzeugen oder dein Kontingent erhöhen.
+>
+> [ Fehlende Zeilen als CSV ] [ Kontingent erhöhen ]
+
+Zusätzlich in derselben Datei:
+
+- `remainingDynamic` nach dem Lauf vom Server neu laden statt nur lokal herunterzuzählen (Zeile 251). Das ist die Ursache der Race Condition.
+- Die Toasts sind auf Deutsch (`'Du hast keine dynamischen QR-Codes mehr übrig...'`, Zeile 215 und 221), während die restliche App-Oberfläche Englisch ist. Auf Englisch umstellen.
+
+---
+
+## Phase 3 - Upgrade-Wege aus der App
+
+`/pricing` liegt in der `(marketing)`-Route-Group. Wer im Dashboard auf Upgrade klickt, verliert die Sidebar und landet in der Marketing-Site. Zusätzlich liest `PricingClient.tsx` `searchParams` überhaupt nicht - das `?reason=limit_reached`, das `/create` heute anhängt, wird vollständig ignoriert.
+
+Nach der getroffenen Entscheidung läuft der Limit-Fall künftig über das Modal, damit ist der wichtigste Fall gelöst. Es bleiben drei In-App-Links auf `/pricing`:
+
+| Datei | Zeile | Kontext |
+|---|---|---|
+| `dashboard/page.tsx` | 340 | Upgrade-Badge im Header |
+| `create/page.tsx` | 977 | Hinweis „Upgrade to PRO to customize colors" |
+| `create/page.tsx` | 1106 | Hinweis „Upgrade to PRO to add logos" |
+
+Die beiden Hinweise in `/create` sollten dasselbe Modal öffnen wie der Limit-Fall, nur mit anderem Aufhänger („Dein Logo gehört in diesen Code"). Der Nutzer ist mitten im Gestalten - ihn dafür aus der Seite zu werfen ist derselbe Fehler wie beim Limit, nur weniger sichtbar.
+
+Der Dashboard-Badge kann auf `/pricing` zeigen bleiben. Dort ist der Nutzer nicht mitten in einer Aufgabe, es gibt nichts zu verlieren. Nur ein `?from=dashboard` anhängen und in `PricingClient` einen Zurück-Link rendern, damit der Weg zurück nicht über den Browser-Button läuft.
+
+---
+
+## Phase 4 - Post-Download-Popup auf den Tool-Seiten
+
+**Datei:** `src/components/marketing/PostDownloadPopup.tsx`
+
+Timing und die Ablehn-Option `No thanks, keep it static` bleiben unverändert - beides ist richtig gebaut.
+
+Ersetzt werden Headline und Bullet-Liste:
+
+> ### Dieser Code zeigt jetzt für immer auf diese URL.
+>
+> Bei einem dauerhaften Link ist das genau richtig. Falls sich das Ziel je ändert, brauchst du einen neuen Code und neues Druckmaterial.
+>
+> Ein kostenloses Konto gibt dir 3 dynamische Codes: gleiches Bild, Ziel jederzeit änderbar, jeder Scan gezählt.
+>
+> **[ Kostenloses Konto anlegen - keine Karte ]**
+> *Nein danke, statisch reicht*
+
+Die vier Bullets entfallen. Drei gleichrangige Vorteile sind schwächer als ein Satz, der den einen benennt - in einer Liste aus vier gleich formatierten Punkten ist keiner davon wichtig.
+
+Neues Prop `variant`, das nur die erste Zeile austauscht:
+
+| Tool | Erste Zeile |
+|---|---|
+| Google Review | Dieser Code zeigt jetzt für immer auf dieses Google-Profil. |
+| WiFi | Dieser Code enthält jetzt dauerhaft dieses WLAN-Passwort. |
+| vCard | Dieser Code enthält jetzt dauerhaft diese Kontaktdaten. |
+| Crypto | Dieser Code enthält jetzt dauerhaft diese Wallet-Adresse. |
+| Standard | Dieser Code zeigt jetzt für immer auf diese URL. |
+
+Die WiFi-Variante ist die stärkste, weil sie einen Umstand benennt, den fast niemand vorher bedenkt: Wer das Passwort ändert, hat wertloses Druckmaterial.
+
+Betroffen sind die 10+ Generator-Komponenten, die `PostDownloadPopup` einbinden - dort jeweils nur das `variant`-Prop ergänzen.
+
+**Zusätzlich:** `shouldShowDownloadPopup()` prüft einen einzigen `localStorage`-Key. Wer das Popup einmal gesehen hat, sieht es auf keiner anderen Tool-Seite je wieder - auch nicht Monate später in einem anderen Kontext. Vorschlag: Key mit Zeitstempel, Wiedervorlage nach 30 Tagen.
+
+---
+
+## Phase 5 - Retention-Mails
+
+**Datei:** `src/lib/email.ts` und `src/app/(main)/api/cron/retention-emails/route.ts`
+
+### 5.1 Tag-7-Mail: Trigger vom Kalender aufs Verhalten
+
+Aktuell feuert sie bei `createdAt < 7 Tage` und `qrCount > 0`. Ein Nutzer mit einem einzigen Code bekommt „You're 2 away from the free limit" - eine Verkaufsmail über ein Limit, das ihn nicht drückt, abgeschickt unter deinem Namen.
+
+Neue Logik:
+
+| Zustand | Auslöser | Mail |
+|---|---|---|
+| aktive dynamische Codes = Limit | sobald erreicht | Limit-Mail, Marker `limitReachedNudgeSentAt` |
+| 1-2 von 3 belegt, Tag 7 | Tag 7 | keine Upgrade-Mail |
+| erster Scan liegt vor | 1 Tag danach | Erster-Scan-Mail, Marker `firstScanNudgeSentAt` |
+
+In der Vergleichstabelle der Limit-Mail entfällt die Zeile `CSV export: Free ✓ / Pro ✓`. Eine Zeile, in der beide Spalten identisch sind, gehört nicht in eine Upgrade-Tabelle - sie verwässert die drei, die einen Unterschied zeigen.
+
+### 5.2 Neue Mail: erster Scan
+
+`User.firstScanAt` existiert bereits und wird in `src/app/(main)/r/[slug]/route.ts` (Zeile 150-153 und 263-266) gesetzt. Es fehlt nur ein Versand-Marker.
+
+Betreff: **Dein Code wurde gerade zum ersten Mal gescannt**
+
+> Um {Uhrzeit}, auf einem {Gerät}, aus {Land}. Dein Code „{Titel}" ist im Einsatz.
+>
+> Ab jetzt zählt jeder weitere Scan mit. In ein paar Tagen siehst du, wann die meisten kommen - und ob sich der Ort lohnt, an dem du den Code platziert hast.
+>
+> [ Scans ansehen ]
+
+Kein Verkaufsargument. Diese Mail hat einen Anlass, der nicht konstruiert ist, und ist der Moment, in dem die Positionierung zum ersten Mal einlöst. Sie ist die einzige in der Sequenz, deren Anlass nicht vom Kalender kommt.
+
+### 5.3 Tag-30-Mail auf Scan-Daten umbauen
+
+Zwei Probleme mit der jetzigen Fassung:
+
+Der Satz *„The one thing I hear most from Pro users who switched after a few weeks: they wish they'd added their brand sooner"* behauptet ein Muster aus Kundengesprächen. Wenn es die gab: echtes Zitat rein. Wenn nicht: **streichen** - das ist ein erfundenes Testimonial in indirekter Rede und verstößt gegen die Beweisregel im Product Context. Bei einer Zielgruppe, die Bewertungsportale liest, ist das die teuerste Art von Satz.
+
+Und Branding ist der schwächere von zwei verfügbaren Aufhängern. Nach 30 Tagen hat der Nutzer Scan-Daten. Neuer Aufbau:
+
+> Deine Codes wurden diesen Monat {n}-mal gescannt, {Vorname}.
+>
+> Die meisten davon {Wochentag}s. Was du noch nicht sehen kannst: von welchen Geräten sie kamen und aus welchen Orten - und damit, welche deiner Platzierungen die Scans wirklich gebracht hat.
+>
+> [ Vollständige Auswertung freischalten ]
+
+Damit ist der Kaufgrund aus dem hergeleitet, was der Nutzer selbst erlebt hat. Deckt sich mit Offer Brief §10, Option 1 - auf Analytics-Tiefe metern statt auf Code-Anzahl -, und ist die erste Stelle, an der man das testen kann, ohne das Pricing anzufassen.
+
+### 5.4 Tag-3-Mail: kleine Korrektur
+
+Betreff `You haven't made one yet` kann als Vorwurf gelesen werden - im Body löst die Headline es auf, im Posteingang steht der Betreff allein. Alternative gleicher Länge: **`Your 3 free codes are still sitting there`**.
+
+---
+
+## Phase 6 - QR-Design nach Plan gestaffelt
+
+Neue Staffelung: Farben ab Free, Formen ab Pro, alles ab Business.
+
+### 6.0 Der technische Blocker, der vorher geklärt sein muss
+
+`/create` rendert über `QRCodeSVG` aus `qrcode.react` (Zeile 6 und 1233). **Diese Bibliothek kann ausschließlich quadratische Module.** Es gibt heute überhaupt keine Formauswahl im Produkt - nicht weil sie gesperrt wäre, sondern weil der Renderer sie nicht kann.
+
+Für Formen muss der Renderer also getauscht werden. Es gibt zwei Kandidaten, und sie decken unterschiedlich viel ab:
+
+| Renderer | Kann | Kann nicht |
+|---|---|---|
+| `qr-code-styling` (liegt bereits als Dependency in `package.json`, Zeile 64, ungenutzt) | square, dots, rounded, extra-rounded, classy, classy-rounded, Eye-Styles getrennt, Verläufe, Logo | star, plus, hexagon, diamond, mosaic, liquid |
+| Canvas-Renderer aus `qr-design-showcase.html` | alle 11 Formen inklusive star, plus, hexagon, diamond, mosaic, liquid, Rahmen mit Label, Logo-Formen | ist eigener Code, muss portiert und gepflegt werden |
+
+Das trifft sich gut mit der gewünschten Staffelung: **Pro läuft komplett über `qr-code-styling`** - vier Formen, geringer Aufwand, Bibliothek ist schon da. **Business braucht den portierten Showcase-Renderer** für die exotischen Formen. Damit ist der Mehraufwand genau dort, wo auch der höhere Preis ist.
+
+### 6.1 Free - Farben
+
+**Datei:** `src/app/(main)/(app)/create/page.tsx`, Zeile 167
+
+```ts
+const canCustomizeColors = true;              // war: PRO || BUSINESS
+const canUseShapes       = userPlan === 'PRO' || userPlan === 'BUSINESS';
+const canUseFullDesign   = userPlan === 'BUSINESS';
+const canUseLogo         = userPlan === 'PRO' || userPlan === 'BUSINESS';
+```
+
+Damit fallen die beiden Zwangsüberschreibungen in Zeile 408-409 weg, die heute für Free-Nutzer stumpf `#000000` und `#FFFFFF` einsetzen. Der Upgrade-Hinweis-Block ab Zeile 972 („Upgrade to PRO to customize colors, add logos, and brand your QR codes") entfällt komplett - er stimmt danach nicht mehr.
+
+Der Logo-Block ab Zeile 1104 bleibt, wird aber auf `canUseLogo` umgestellt statt auf `canCustomizeColors`, und öffnet künftig das Modal aus Phase 3 statt auf `/pricing` zu verlinken.
+
+**Der Kontrast-Check bleibt aktiv.** `calculateContrast` gibt es bereits (Zeile 221). Sobald Farben für alle offen sind, wird er wichtiger, nicht unwichtiger - Free-Nutzer sind die Gruppe mit der geringsten Erfahrung darin, was noch scannbar ist. Bei zu geringem Kontrast eine Warnung, kein Verbot: *„Dieser Kontrast ist grenzwertig. Auf gedrucktem Material scannen helle Codes auf hellem Grund oft nicht."*
+
+### 6.2 Pro - vier Modulformen
+
+Umsetzung über `qr-code-styling`. Bewusst nur vier, nicht sechs:
+
+| Auswahl | `dotsOptions.type` | Wofür |
+|---|---|---|
+| Eckig (klassisch) | `square` | Standard, höchste Scan-Sicherheit |
+| Abgerundet | `rounded` | weicher, ohne Lesbarkeit zu kosten |
+| Punkte | `dots` | modern, deutlich sichtbarer Unterschied |
+| Fließend | `classy-rounded` | markantester der vier |
+
+Dazu die Eye-Styles (`cornersSquareOptions`, `cornersDotOptions`) - eckig, abgerundet, Kreis. Die Augen machen optisch mehr aus als die Module selbst und kosten nichts extra, weil dieselbe Bibliothek sie mitbringt.
+
+Vier Optionen statt aller sechs, weil die Auswahl selbst ein Verkaufsargument ist: Pro fühlt sich vollständig an, Business hat sichtbar mehr. Sechs fast identische Varianten wirken dagegen wie eine lange Liste ohne Unterschied.
+
+### 6.3 Business - vollständiger Designer
+
+Portierung des Renderers aus `qr-design-showcase.html` in eine Komponente `src/components/generator/AdvancedQRRenderer.tsx`. Was damit dazukommt:
+
+- **Modulformen:** diamond, star, hexagon, plus, mosaic, liquid zusätzlich zu den vier aus Pro
+- **Eye-Frames getrennt:** eckig, abgerundet, Kreis, Blatt, Flower/Squircle, Hexagon
+- **Eye-Balls getrennt:** eckig, abgerundet, Kreis, Diamant, Stern, Hexagon
+- **Farbverläufe:** linear und radial statt einfarbig
+- **Rahmen mit Label:** weiße Karte mit Schatten, Label oben oder unten (z. B. „Speisekarte", „Jetzt bewerten")
+- **Logo-Formen:** Punkt, Quadrat, Herz, Blitz, WLAN-Symbol
+- **Fehlerkorrektur-Stufe** frei wählbar (L/M/Q/H)
+
+**Erweiterungsvorschläge über die Showcase hinaus**, weil beim Business-Kunden die Wiederholbarkeit zählt und nicht die einzelne Spielerei:
+
+1. **Design-Vorlagen speichern.** Ein einmal gebautes Design als benanntes Preset sichern und auf neue Codes anwenden. Das ist für eine Agentur mit mehreren Kunden der eigentliche Wert - nicht die Sternform, sondern dass Kunde A immer gleich aussieht.
+2. **Preset auf den Bulk-Flow anwenden.** Ein Preset auswählen und alle 500 Codes eines Uploads tragen es. Das verbindet Phase 2 mit diesem Feature und ist das erste Argument für Business, das nicht nur eine Zahl ist.
+3. **Print-Vorschau in Originalgröße.** Der Code in 2×2 cm, 4×4 cm und 10×10 cm dargestellt, mit Hinweis ab wann es kritisch wird. Passt zu den Druckangaben, die im Offer Brief bereits als verifizierter Fakt geführt werden.
+
+### 6.4 Scanbarkeit - der Teil, der nicht optional ist
+
+Exotische Formen füllen weniger Fläche pro Modul. Star, plus und mosaic reduzieren die Kontrastfläche spürbar, und in Kombination mit einem Logo in der Mitte und einer kleinen Druckgröße kippt die Lesbarkeit. Die Showcase weist bei „H (30%)" schon auf „empfohlen bei Logo" hin - das gehört ins Produkt übernommen, und zwar strenger:
+
+- Bei star, plus, mosaic oder liquid automatisch auf Fehlerkorrektur **H** hochsetzen und das sichtbar begründen
+- Bei Logo plus exotischer Form eine Warnung mit Mindestdruckgröße
+- Ein **Test-Scan-Hinweis** vor dem Download: *„Scanne den Code einmal mit deinem eigenen Handy, bevor du ihn in Druck gibst."*
+
+Das ist kein Beiwerk, sondern der Proof-Layer aus der Positionierung an einer Stelle, an der es konkret wird. Ein Anbieter, der vor seinem eigenen Feature warnt, wenn es kritisch wird, belegt Belief 5 besser als jede Aussage über Transparenz.
+
+### 6.5 Was die Umstellung beim Pricing kostet
+
+Ehrlich gesagt: Farben waren laut Offer Brief §10 einer von genau **drei** Gründen, heute auf Pro zu wechseln (die anderen zwei: mehr als 3 aktive Codes, Device- und Location-Breakdown). Diesen Grund gibt man mit dieser Änderung auf.
+
+Das ist meiner Einschätzung nach trotzdem richtig, aber aus einem anderen Grund als „großzügiger sein":
+
+Farben sind kein guter Upgrade-Anlass, weil man sie schon im kostenlosen Zustand *sehen* will, um zu verstehen, ob das Produkt etwas taugt. Ein Free-Nutzer, der nur schwarze Codes bauen kann, hält das Produkt für ein Basiswerkzeug - und bewertet es entsprechend, auch in Vergleichen. Formen sind der bessere Verkäufer, weil der Unterschied größer aussieht und man ihn in der Vorschau zeigen kann, bevor man ihn freischaltet: der Nutzer wählt „Punkte", sieht das Ergebnis live, und erst der Download fragt nach Pro.
+
+**Folgeänderungen an der Preis-Copy** in `src/i18n/en.json` und `src/app/(main)/(marketing)/pricing/PricingClient.tsx`:
+
+| Plan | vorher | nachher |
+|---|---|---|
+| Free | „Standard QR design templates" | „Deine Farben - Vorder- und Hintergrund frei wählbar" |
+| Pro | „Custom branding (colors & logos)" | „4 Modulformen, eigene Eye-Styles und dein Logo im Code" |
+| Business | (kein Design-Punkt) | „Voller Designer: 10 Formen, Verläufe, Rahmen mit Label, speicherbare Design-Vorlagen" |
+
+Dieselbe Anpassung auf `/custom-qr-code-generator`, dessen Meta-Description aktuell „Put your logo and brand colors into the code itself" sagt - das bleibt korrekt, weil Logo weiterhin Pro ist, aber die Seite sollte künftig zeigen, was auf welcher Stufe geht.
+
+### 6.6 Keine Datenbankänderung nötig
+
+`QRCode.style` ist bereits `Json` (siehe `prisma/schema.prisma`). Alle neuen Felder - `dotType`, `eyeFrameType`, `eyeBallType`, `gradient`, `frameLabel`, `logoShape`, `ecLevel` - passen ohne Schemaänderung hinein. Bestehende Codes haben die Felder schlicht nicht und fallen auf die Defaults zurück.
+
+**Ausnahme:** Wenn die speicherbaren Design-Vorlagen aus 6.3 kommen sollen, braucht es eine eigene Tabelle. SQL dafür steht unten, ist aber optional und kann später nachgezogen werden.
+
+---
+
+## SQL - alle nötigen Datenbankänderungen
+
+Nach der Policy in `CLAUDE.md`: keine Prisma-Migrationen, nur direkte Statements.
+
+```sql
+-- Marker für die neuen verhaltensbasierten Retention-Mails
+ALTER TABLE "User" ADD COLUMN IF NOT EXISTS "limitReachedNudgeSentAt" TIMESTAMP(3);
+ALTER TABLE "User" ADD COLUMN IF NOT EXISTS "firstScanNudgeSentAt"    TIMESTAMP(3);
+
+-- Index für den Cron: sucht Nutzer mit erstem Scan, die die Mail noch nicht haben
+CREATE INDEX IF NOT EXISTS "User_firstScanAt_firstScanNudgeSentAt_idx"
+  ON "User" ("firstScanAt", "firstScanNudgeSentAt");
+
+-- Index für die neue Limit-Query (zählt nur noch ACTIVE)
+CREATE INDEX IF NOT EXISTS "QRCode_userId_type_status_idx"
+  ON "QRCode" ("userId", "type", "status");
+```
+
+Für Phase 6 ist **nichts** davon nötig - `QRCode.style` ist bereits `Json`. Optional, nur falls die speicherbaren Design-Vorlagen aus 6.3 gebaut werden:
+
+```sql
+CREATE TABLE IF NOT EXISTS "QRDesignPreset" (
+  "id"        TEXT PRIMARY KEY,
+  "userId"    TEXT NOT NULL REFERENCES "User"("id") ON DELETE CASCADE,
+  "name"      TEXT NOT NULL,
+  "style"     JSONB NOT NULL,
+  "createdAt" TIMESTAMP(3) NOT NULL DEFAULT now(),
+  "updatedAt" TIMESTAMP(3) NOT NULL DEFAULT now()
+);
+
+CREATE INDEX IF NOT EXISTS "QRDesignPreset_userId_idx" ON "QRDesignPreset" ("userId");
+CREATE UNIQUE INDEX IF NOT EXISTS "QRDesignPreset_userId_name_key" ON "QRDesignPreset" ("userId", "name");
+```
+
+Ausführen über `npm run docker:db` oder:
+
+```bash
+docker-compose exec db psql -U postgres -d qrmaster -c 'ALTER TABLE "User" ADD COLUMN IF NOT EXISTS "limitReachedNudgeSentAt" TIMESTAMP(3);'
+```
+
+Danach `prisma/schema.prisma` im Block `// Retention email tracking` ergänzen:
+
+```prisma
+  limitReachedNudgeSentAt DateTime?
+  firstScanNudgeSentAt    DateTime?
+```
+
+und beim Model `QRCode` den Index:
+
+```prisma
+  @@index([userId, type, status])
+```
+
+Abschließend `npx prisma generate` - kein `migrate`.
+
+### Prüf-Queries vor dem Deploy
+
+```sql
+-- Wie viele Free-Nutzer bekommen durch die ACTIVE-Umstellung Slots frei?
+SELECT COUNT(DISTINCT u.id)
+FROM "User" u
+JOIN "QRCode" q ON q."userId" = u.id
+WHERE u.plan = 'FREE' AND q.type = 'DYNAMIC' AND q.status = 'PAUSED';
+
+-- Wie viele Nutzer bekämen die Erster-Scan-Mail beim ersten Cron-Lauf?
+SELECT COUNT(*) FROM "User"
+WHERE "firstScanAt" IS NOT NULL AND "firstScanNudgeSentAt" IS NULL;
+```
+
+Die zweite Zahl ist wichtig: Beim ersten Lauf würde die neue Mail an **alle** Bestandsnutzer mit Scan-Historie gehen - auch an solche, deren erster Scan Monate zurückliegt. Das wäre kein Anlass mehr, sondern Spam. Der Cron braucht deshalb ein Zeitfenster, etwa `firstScanAt > now() - interval '7 days'`, oder man setzt die Spalte bei Bestandsnutzern einmalig vor:
+
+```sql
+UPDATE "User" SET "firstScanNudgeSentAt" = now()
+WHERE "firstScanAt" IS NOT NULL AND "firstScanAt" < now() - interval '7 days';
+```
+
+---
+
+## Reihenfolge
+
+| # | Was | Aufwand | DB |
+|---|---|---|---|
+| 1 | Limit-Query auf ACTIVE, beide Endpoints | klein | Index |
+| 2 | Limit-Modal ohne Redirect | mittel | nein |
+| 3 | Direkt-Checkout plus `returnPath` und localStorage-Wiederherstellung | mittel | nein |
+| 4 | `bulk-creation`: Fehlerbehandlung und Ergebnis-Panel | klein | nein |
+| 5 | Popup-Copy plus `variant` pro Tool-Seite | klein | nein |
+| 6 | Retention: Trigger umstellen, Tabellen-Zeile raus, Betreff Tag 3 | klein | 1 Spalte |
+| 7 | Erster-Scan-Mail | mittel | 1 Spalte |
+| 8 | Tag-30 auf Scan-Daten, unbelegten Satz klären | klein | nein |
+| 9 | Farben ab Free freischalten, Pricing-Copy nachziehen | klein | nein |
+| 10 | Pro-Formen über `qr-code-styling`, Renderer-Tausch in `/create` | mittel | nein |
+| 11 | Business-Designer, Showcase-Renderer portieren | groß | nein |
+| 12 | Design-Vorlagen speichern und auf Bulk anwenden | mittel | Tabelle |
+
+1 bis 3 gehören zusammen und sollten gemeinsam live gehen. 4 und 5 sind unabhängig und können jederzeit dazwischen. 6 bis 8 brauchen die SQL-Statements und den einmaligen `UPDATE` für Bestandsnutzer.
+
+**9 ist der schnellste Gewinn im ganzen Dokument** - eine Zeile (`canCustomizeColors = true`) plus Copy-Anpassung, und das Produkt wirkt für jeden neuen Nutzer sofort weniger nach Basiswerkzeug. Sie sollte nicht auf 10 warten.
+
+10 ist der Renderer-Tausch und damit der Punkt, an dem `/create` einmal gründlich getestet werden muss - Vorschau, Download PNG, Download SVG, Logo-Overlay und die Frame-Optionen hängen alle daran.
+
+11 und 12 sind der eigentliche Business-Ausbau. 12 ist dabei wertvoller als 11: eine Agentur kauft nicht die Sternform, sondern dass Kunde A auf 500 Codes gleich aussieht.

PLAN_TESTUMGEBUNG_2026-08-12.md

@@ -0,0 +1,299 @@
+# Plan: Testumgebung auf testmodul.qrmaster.net
+
+Stand: 2026-08-12 · Ziel: eine vollständige zweite Instanz auf `testmodul.qrmaster.net`, die
+einen anderen Branch (`test`) fährt, damit riskante Features - z.B. ein Bot, der bei
+Kundenerfolgen automatisch tweetet - vor dem Merge nach `master` real getestet werden können.
+
+**Status: nur Planung. Es wurde noch kein Code geändert.**
+
+## Architektur
+
+Zweiter, vollständig eigenständiger Compose-Stack aus demselben Repo, anderer Branch,
+eigene Datenbank, eigenes Redis. Caddy routet `testmodul.qrmaster.net` auf den Test-Container.
+
+```
+www.qrmaster.net   ─┐
+app.qrmaster.net   ─┴─> qrmaster-web       (Branch master, Prod-DB)
+testmodul.qrmaster.net ─> qrmaster-test-web (Branch test, eigene DB)
+```
+
+Prod und Test teilen sich **nichts** außer dem Docker-Netzwerk `qrmaster-network` (das ist
+`external: true`, darüber erreicht Caddy beide Container per Namen).
+
+## Ausgangslage im Repo
+
+Im Working Tree liegen uncommittete Änderungen, die nicht aus der Subdomain-Arbeit stammen:
+
+- `src/lib/cookieConfig.ts` - `getAuthCookieName()` ist angelegt (liest `AUTH_COOKIE_NAME`,
+  Default `userId`)
+- `src/lib/session.ts` - importiert `getAuthCookieName`, **benutzt es aber nicht**; Zeile 14
+  hat weiterhin `export const AUTH_COOKIE_NAME = 'userId'`
+
+Damit ist die Funktion aktuell wirkungslos. Die Verkabelung fehlt an 6 Stellen (siehe unten).
+Vor dem Weiterbauen klären, ob diese Änderungen bewusst so stehen oder committed werden sollen.
+
+Ein Branch `test` existiert noch nicht. Vorhanden: `analytics`, `dynamisch`,
+`feature/mockup-landing-page`, `icons`, `master`.
+
+## Falle 1 - Cookie-Kollision (blockierend)
+
+Produktion setzt das Session-Cookie `userId` auf `.qrmaster.net`. Der Browser schickt es damit
+**auch an `testmodul.qrmaster.net`**. Setzt Test sein eigenes `userId` als Host-Cookie, liegen
+zwei gleichnamige Cookies vor, und `req.cookies.get('userId')` in
+[middleware.ts:250](src/middleware.ts:250) liefert undefiniert welches davon. Folge: Login auf
+Test verhält sich sporadisch wie ausgeloggt - ein Fehlerbild, das schwer zu greifen ist, weil es
+vom Cookie-Zustand des jeweiligen Browsers abhängt.
+
+**Lösung:** Cookie-Name pro Umgebung konfigurierbar. `getAuthCookieName()` fertig verkabeln,
+Test setzt `AUTH_COOKIE_NAME=userId_test`.
+
+Zu ändernde Stellen:
+
+| Datei | Was |
+|---|---|
+| `src/lib/session.ts:14` | `AUTH_COOKIE_NAME`-Konstante durch `getAuthCookieName()` ersetzen (Zeilen 71, 78 ziehen nach) |
+| `src/middleware.ts:250` | `req.cookies.get('userId')` → `getAuthCookieName()` |
+| `src/app/(main)/api/auth/google/route.ts:227` | `cookies.set('userId', …)` |
+| `src/app/(main)/api/auth/verify-email/route.ts:40` | `cookies.set('userId', …)` |
+| `src/app/(main)/api/auth/logout/route.ts:12` | Eintrag in `appendExpiredCookies` |
+| `src/app/(main)/api/user/delete/route.ts:77` | `cookies().delete('userId')` |
+
+Wie `COOKIE_DOMAIN` muss `AUTH_COOKIE_NAME` **auch zur Build-Zeit** gesetzt sein - `process.env`
+wird ins Edge-Middleware-Bundle inlined. Also `ARG` + `ENV` im Dockerfile und als Build-Arg im
+Compose-Override, analog zu `COOKIE_DOMAIN`.
+
+Achtung beim Umstellen der Produktion: ändert sich dort der Cookie-Name, werden **alle
+bestehenden Sessions ungültig** (alle Nutzer ausgeloggt). Deshalb Prod beim Default `userId`
+lassen und nur Test abweichen - dann passiert genau nichts.
+
+## Falle 2 - Host-Routing würde nach Prod umleiten
+
+Die Middleware kennt nur zwei Hosts. Auf `testmodul.qrmaster.net` greift der Zweig
+`else if (isAppPath(path))` und schickt `/dashboard` per 301 auf **app.qrmaster.net**, also in
+die Produktion.
+
+**Lösung ohne Codeänderung:** Test zeigt beide Origins auf sich selbst. Dann ist
+`isHostSplitEnabled()` false, `getAppHostname()` liefert null, und das komplette Host-Routing
+schaltet sich ab. Test läuft als Ein-Host-Umgebung mit Marketing *und* App unter einer Domain -
+genau wie die lokale Entwicklung.
+
+Das ist der Grund, warum beide Variablen in `.env.test` identisch sein müssen. Wer dort später
+aus Versehen `NEXT_PUBLIC_APP_URL=https://app.qrmaster.net` einträgt, schickt seine Testklicks
+in die Produktion.
+
+## Falle 3 - ausgehende Nebenwirkungen
+
+Das ist beim Twitter-Bot der eigentliche Punkt. Eine Testumgebung, die auf echte Dienste zeigt,
+ist keine Testumgebung.
+
+| Dienst | Auf Test |
+|---|---|
+| Twitter/X | eigener App-Key auf einen Test-Account, **oder** ein `DRY_RUN`-Flag, das den Tweet nur loggt |
+| Stripe | Test-Keys (`sk_test_…`), eigener Webhook-Endpoint auf testmodul |
+| Resend / SMTP | Test-Key oder komplett deaktivieren - sonst mailt Test an echte Kunden |
+| Meta Conversions / PostHog / Umami | leer lassen, sonst verschmutzt Test die Prod-Analytics |
+| Cron (Retention-Mails) | auf Test abschalten |
+
+Empfehlung für den Bot: das `DRY_RUN`-Flag von Anfang an einbauen, nicht erst wenn es einmal
+schiefging. Ein Bot, der Kundenerfolge tweetet, ist genau die Sorte Feature, die man nicht
+"kurz mal live" testen will.
+
+## .env.test
+
+```dotenv
+NODE_ENV=production
+
+# Ein-Host-Betrieb: schaltet das Host-Routing ab
+NEXT_PUBLIC_WWW_URL=https://testmodul.qrmaster.net
+NEXT_PUBLIC_APP_URL=https://testmodul.qrmaster.net
+NEXTAUTH_URL=https://testmodul.qrmaster.net
+
+# Host-Cookie, nicht .qrmaster.net - sonst leckt die Test-Session nach Prod
+COOKIE_DOMAIN=
+AUTH_COOKIE_NAME=userId_test
+
+# Anderes Secret: ein Leak auf Test kann dann keine Prod-Session fälschen
+NEXTAUTH_SECRET=<eigenes Secret>
+IP_SALT=<eigenes Salt>
+
+# Nicht indexieren
+NEXT_PUBLIC_INDEXABLE=false
+
+# Eigene DB im Test-Stack
+POSTGRES_USER=postgres
+POSTGRES_PASSWORD=<eigenes, hex - ein "/" aus base64 zerlegt die DATABASE_URL>
+POSTGRES_DB=qrmaster_test
+# DATABASE_URL nicht setzen - Compose baut sie aus den drei Werten oben
+
+# Test-Keys / leer, siehe Falle 3
+STRIPE_SECRET_KEY=sk_test_…
+RESEND_API_KEY=
+```
+
+`NEXTAUTH_URL` darf hier auf testmodul zeigen - der einzige echte Leser ist die
+Social-Assets-Route, und die soll auf Test ohnehin nicht gegen die verifizierte TikTok-Domain
+laufen.
+
+## Infra
+
+**`docker-compose.test.yml`** als Override, das nur die Abweichungen setzt:
+
+- `container_name`: `qrmaster-test-db`, `qrmaster-test-redis`, `qrmaster-test-web` - die Namen
+  sind im Basis-File fest vergeben und würden sonst kollidieren
+- Host-Ports entfernen - `5435` (db) und `8080` (adminer) sind schon von Prod belegt
+- `entrypoint: ["node", "server.js"]` für `web`, siehe Migrationen oben
+- Build-Args für `COOKIE_DOMAIN`, `AUTH_COOKIE_NAME`, `NEXT_PUBLIC_*`
+
+### Netzwerk-Isolation (kritisch)
+
+`db` und `redis` hängen im Basis-File am Netzwerk `qrmaster-network`
+([docker-compose.yml:22](docker-compose.yml:22)), und das ist `external: true`, also für beide
+Stacks dasselbe. Compose vergibt jedem Service automatisch einen Netzwerk-Alias mit seinem
+Servicenamen - zwei Stacks mit einem Service `db` am selben Netzwerk heißt: **`db` löst auf
+zwei Container auf und Dockers DNS wählt zufällig.** Der Test-Container könnte damit auf der
+Produktionsdatenbank landen, nicht deterministisch, sondern mal so und mal so.
+
+Deshalb bekommt der Test-Stack ein eigenes internes Netzwerk. Nur `web` hängt zusätzlich am
+geteilten Netz, damit Caddy es erreicht:
+
+```yaml
+services:
+  db:
+    container_name: qrmaster-test-db
+    ports: !reset []
+    networks: [test-internal]
+  redis:
+    container_name: qrmaster-test-redis
+    networks: [test-internal]
+  web:
+    container_name: qrmaster-test-web
+    entrypoint: ["node", "server.js"]
+    networks: [test-internal, qrmaster-network]
+
+networks:
+  test-internal:
+    driver: bridge
+```
+
+`POSTGRES_DB` heißt auf Test `qrmaster_test`. Die Trennung kommt zwar schon vom eigenen
+Container und Volume, aber der abweichende Name macht bei einer von Hand getippten
+`psql`-Sitzung sofort sichtbar, auf welcher Instanz man ist - die billigste Versicherung
+gegen ein `DELETE` in der falschen Datenbank.
+
+Dafür muss der Healthcheck mitgezogen werden: das Basis-File hat `pg_isready -d qrmaster`
+hartkodiert ([Zeile 19](docker-compose.yml:19)). Ohne Override prüft er eine Datenbank, die
+es nicht gibt, der Container bleibt `unhealthy`, und `web` startet wegen
+`depends_on: condition: service_healthy` nie.
+
+Start:
+
+```bash
+docker compose -p qrmaster-test --env-file .env.test \
+  -f docker-compose.yml -f docker-compose.test.yml up -d --build
+```
+
+Der Projektname `-p qrmaster-test` gibt automatisch eigene Volumes - die Test-DB kann die
+Prod-DB also nicht anfassen.
+
+**Caddy:**
+
+```caddyfile
+testmodul.qrmaster.net {
+    reverse_proxy qrmaster-test-web:3000
+}
+```
+
+**`robots.ts`** an `NEXT_PUBLIC_INDEXABLE` koppeln. Aktuell liefert es hart `Allow` plus
+www-Sitemap; auf Test soll `Disallow: /` stehen. `NEXT_PUBLIC_INDEXABLE=false` setzt heute nur
+das Meta-Tag in den beiden Layouts, nicht die robots.txt.
+
+## Branch-Workflow
+
+```bash
+git checkout -b test master
+git push -u origin test
+```
+
+Deploy auf Test: auf dem Server `git checkout test && git pull`, dann der Compose-Befehl oben.
+Rebuild ist immer nötig, weil `NEXT_PUBLIC_*` und `AUTH_COOKIE_NAME` zur Build-Zeit inlined
+werden.
+
+Ablauf für ein Feature: Branch von `test` abzweigen → auf Test deployen und prüfen → nach
+`master` mergen → Prod-Deploy. `test` bleibt dauerhaft bestehen und wird regelmäßig von
+`master` nachgezogen, damit er nicht wegdriftet.
+
+## Datenbank - entschieden: leeres Schema
+
+Eigene PostgreSQL-Instanz im Test-Stack, befüllt mit **Struktur ohne Zeilen**. Keine
+Kundendaten verlassen die Produktion.
+
+```bash
+# Struktur aus Prod ziehen (keine Zeilen)
+docker exec qrmaster-db pg_dump -U postgres --schema-only qrmaster > schema.sql
+
+# in die Test-DB einspielen
+docker exec -i qrmaster-test-db psql -U postgres -d qrmaster_test < schema.sql
+```
+
+Danach einen Testaccount anlegen - entweder über das Signup-Formular auf testmodul oder per
+`INSERT`.
+
+**Warum der Dump aus Prod und nicht aus Prisma:** `prisma/migrations` steht auf April 2026.
+Alles seitdem (Pulse-Spalten, `BARCODE`-Enum-Wert, ...) kam per Hand-SQL. Die Produktions-DB
+ist damit die einzige Stelle, die die aktuelle Struktur kennt.
+
+**Warum leer statt Kopie:** beim Tweet-Bot willst du wissen, welcher Testfall den Tweet
+ausgelöst hat. Mit Prod-Daten könnte es auch irgendein echter Kunde von vor Monaten gewesen sein.
+
+### Keine Migrationen - der Entrypoint muss überschrieben werden
+
+[docker/entrypoint.sh:5](docker/entrypoint.sh:5) führt bei **jedem** Container-Start
+`npx prisma migrate deploy` aus. Das widerspricht der Policy aus CLAUDE.md (Schema-Änderungen
+nur per Hand-SQL) und würde auf einer frischen Test-DB die 6 veralteten Migrationen anwenden -
+also ein Schema vom Stand April 2026 bauen, dem alle späteren SQL-Änderungen fehlen. Die App
+liefe dann in "column does not exist".
+
+Im Test-Override deshalb:
+
+```yaml
+web:
+  entrypoint: ["node", "server.js"]
+```
+
+Prod bleibt unverändert. Der Schema-Dump bringt die Tabelle `_prisma_migrations` ohnehin mit,
+inklusive der 6 als angewandt markierten Einträge - der Zustand ist also identisch zu Prod.
+
+**Separat zu klären (nicht Teil dieses Plans):** ob `prisma migrate deploy` langfristig auch
+aus dem Prod-Entrypoint verschwinden soll. Heute ist es dort ein No-Op, aber es ist eine
+scharfe Waffe, die bei einem versehentlich hinzugefügten Migrationsfile auf die Produktion
+losgeht.
+
+### Spätere Schema-Änderungen
+
+Ein SQL-Statement, das auf Test getestet wurde, wird auf Prod **erneut von Hand** ausgeführt -
+es gibt keinen automatischen Weg von Test nach Prod. Die Dateien in `sql/` sind der Ort dafür.
+
+## Aufwand
+
+| | |
+|---|---|
+| Cookie-Name verkabeln (6 Stellen) + Dockerfile/Compose | ~1 h |
+| `docker-compose.test.yml` + `robots.ts` an INDEXABLE koppeln | ~1 h |
+| `.env.test`, Secrets, Test-Keys besorgen | Timo |
+| Caddy-Block + erster Deploy | ~30 min |
+| DB-Variante B zusätzlich | +2-3 h für das Anonymisierungs-Skript |
+
+Der Twitter-Bot selbst ist davon unabhängig und noch nicht geschätzt.
+
+## Testcheckliste nach dem ersten Test-Deploy
+
+- [ ] `testmodul.qrmaster.net` lädt, gültiges Zertifikat
+- [ ] `testmodul.qrmaster.net/dashboard` bleibt **auf testmodul** und springt nicht nach app.qrmaster.net
+- [ ] Login auf Test funktioniert, während man in Prod eingeloggt ist - beide Sessions unabhängig
+- [ ] Logout auf Test loggt **nicht** aus Prod aus (und umgekehrt)
+- [ ] Im Browser liegen zwei Cookies: `userId` (Domain `.qrmaster.net`) und `userId_test` (Host `testmodul.qrmaster.net`)
+- [ ] `curl -sI https://testmodul.qrmaster.net` → kein `X-Robots-Tag` nötig, aber `/robots.txt` liefert `Disallow: /`
+- [ ] Test-DB enthält **keine** echten Kunden: `SELECT count(*) FROM "User";` muss die Zahl der selbst angelegten Testaccounts sein
+- [ ] `docker compose -p qrmaster-test exec web env | grep DATABASE_URL` zeigt auf den Test-Container, und `SELECT count(*)` dort weicht von Prod ab - beweist, dass der `db`-Alias nicht auf Prod zeigt
+- [ ] Container-Logs beim Start enthalten **kein** "Applying Prisma migrations"
+- [ ] Ein Testlauf des Bots postet nichts auf dem echten Account

PRODUCT.md

@@ -0,0 +1,51 @@
+# Product
+
+## Register
+
+brand
+
+## Users
+
+Two primary personas, both aesthetically-driven professionals who have outgrown generic tools:
+
+**Marketing / Agency Lead** — manages multiple client campaigns simultaneously. Needs organized folders, detailed analytics, and design output that doesn't betray itself as "internet freeware." They evaluate tools by how their outputs look to clients, not just how the tool works internally.
+
+**Modern Restaurateur** — owner of a boutique restaurant, cafe, or hotel. Their physical space is carefully designed; their digital touchpoints must match. They rely on Dynamic QR codes to swap menu PDFs and URLs seasonally without reprinting expensive acrylic table stands. Brand consistency between print and digital is non-negotiable for them.
+
+**Arrival context:** Both land on QR Master after being burned by "free" tools that expired, injected third-party ads, or looked visually cheap. They are actively comparing options and arrive skeptical. They're not discovering QR tools for the first time — they're looking for a permanent, professional home.
+
+## Product Purpose
+
+QR Master is a precision QR code platform — creation, dynamic editing, and analytics — for professionals who refuse to compromise on aesthetics. Success means users choose QR Master not because they have to, but because they want to: the tool itself feels like an extension of their creative workflow, not a clunky utility they tolerate.
+
+## Brand Personality
+
+**Confident, Minimal, Crafted.**
+
+"The Leica of QR Generators." A precision instrument that earns trust through intentionality, not decoration. Every pixel deliberate. Think Linear's pro-tool clarity, Raycast's utilitarian beauty, Framer's implied creative freedom — combined into something that feels high-performance without performing.
+
+Tone of voice: direct and assured. No hedging, no exclamation points for emphasis, no "Amazing!" copy. Let the product speak. Copy is short, specific, and treats the user as a professional.
+
+## Anti-references
+
+- **SEO ad farms** (QR-Code-Generator.com style): cluttered sidebars, aggressive upsell banners, walls of keyword-stuffed text. The opposite of QR Master.
+- **Bubbly link-in-bio tools**: neon gradients, Gen-Z playfulness, the Linktree aesthetic. QR Master is for businesses, not social profiles.
+- **Legacy enterprise software**: cold gray, mechanical, joyless. High-end is not the same as corporate. QR Master should feel premium, not bureaucratic.
+
+## Design Principles
+
+1. **Precision over decoration.** Every element earns its place. No UX furniture — no gratuitous dividers, decorative gradients, or filler icons. If removing it doesn't hurt, remove it.
+
+2. **Show, don't explain.** The product's quality is demonstrated by how the interface looks and behaves, not described in marketing copy. A beautifully rendered QR preview communicates more than three bullet points about "custom branding."
+
+3. **Premium through restraint.** Sophistication comes from what's removed. More whitespace, fewer words, tighter hierarchy. The instinct to add is the enemy of craft.
+
+4. **Trustworthy at a glance.** Clarity and professionalism must be instantaneous — users arriving skeptical decide in 5 seconds. No clever puzzles, no mystery-meat navigation. Confidence is expressed through legibility.
+
+5. **Tool-like beauty.** Functional elegance, like a well-made physical instrument. Interactions should feel responsive and precise. Animations are subtle cues, not performances. The UI should feel fast even when it isn't.
+
+## Accessibility & Inclusion
+
+- **Standard**: WCAG 2.1 AA
+- **Reduced motion**: Full `prefers-reduced-motion` support. Animations (where used) default to subtle fades or scale shifts; no motion for motion's sake.
+- **Color contrast**: Critical for a QR creation tool. The dashboard must warn users when foreground/background color combinations produce insufficient contrast — both for readability and QR scannability. This is a functional requirement, not a nice-to-have.

RETENTION_UND_CRO_ANALYSE_2026-07-27.md

@@ -0,0 +1,169 @@
+# Retention-Mails & CRO-Momente - Analyse
+
+Stand 27. Juli 2026. Grundlage: `src/lib/email.ts`, `src/app/(main)/api/cron/retention-emails/route.ts`, `src/components/marketing/PostDownloadPopup.tsx`, `src/app/(main)/(app)/create/page.tsx` sowie Offer Brief §10 und der Necessary-Beliefs-Doc.
+
+---
+
+## Teil 1 - Der 3/3-Moment: es gibt kein Popup
+
+Das Wichtigste zuerst, weil es kein Copy-Problem ist.
+
+Wenn ein Free-Nutzer den vierten dynamischen Code anlegen will, passiert laut `create/page.tsx` Zeile 456-458 Folgendes:
+
+```
+if (response.status === 403 && responseData.error === 'Limit reached') {
+  showToast(responseData.message || 'You have reached your plan limit.', 'error');
+  router.push('/pricing?reason=limit_reached');
+}
+```
+
+Drei Dinge gehen hier schief, in aufsteigender Schwere:
+
+**1. Roter Fehler-Toast.** Der Nutzer hat nichts falsch gemacht. Er hat das Produkt so benutzt, wie es gedacht ist, und bekommt dafür eine Fehlermeldung im gleichen Stil wie eine kaputte URL. Das ist keine Upgrade-Aufforderung, das ist eine Zurechtweisung.
+
+**2. Die Arbeit ist weg.** Der Nutzer hat Ziel-URL, Typ, Farben, vielleicht ein Logo eingegeben. Beim Redirect auf `/pricing` ist all das verloren. Wer danach upgradet, muss von vorne anfangen. Das ist der teuerste denkbare Zeitpunkt für Datenverlust: exakt in dem Moment, in dem die Kaufabsicht am höchsten ist.
+
+**3. Der Redirect ist ein Rauswurf.** Der Nutzer wollte einen QR-Code bauen und landet auf einer Preistabelle ohne Bezug zu dem, was er gerade tat. Kein Weg zurück, kein „so sieht dein Code aus, er ist nur noch nicht gespeichert".
+
+Aus dem Offer Brief §7: der Engpass ist **Perceived Likelihood**, nicht Preis und nicht Effort. Dieser Ablauf senkt genau die - er zeigt, dass das Produkt in einem kritischen Moment die eigene Arbeit wegwirft.
+
+### Was stattdessen hin muss
+
+Ein Modal, das **über** dem fertigen Code aufgeht, nicht statt ihm. Der Code bleibt im Hintergrund sichtbar. Vorschlag:
+
+> **Dein vierter Code ist fertig. Er braucht nur noch einen Platz.**
+>
+> Du nutzt alle 3 dynamischen Codes des Free-Plans. Dieser hier ist gebaut und wartet - du kannst ihn behalten oder einen bestehenden freigeben.
+>
+> [ Diesen Code mit Pro speichern - 9 € / Monat ]
+> [ Einen bestehenden Code ersetzen ]
+> [ Stattdessen als statischen Code herunterladen - kostenlos, läuft nie ab ]
+>
+> Deine 3 aktiven Codes laufen weiter, egal wie du dich entscheidest.
+
+Warum diese drei Optionen:
+
+- **Option 1** ist der Kauf, aber formuliert als „diesen konkreten Code retten", nicht als „Plan kaufen". Der Nutzer kauft eine Sache, die er gerade in der Hand hat.
+- **Option 2** ist die ehrliche Alternative innerhalb des Free-Plans. Sie kostet ein paar Conversions und kauft dafür Glaubwürdigkeit - Belief 5 aus dem Necessary-Beliefs-Doc: der sicherste Anbieter ist der, der offenlegt, was er kann und was nicht.
+- **Option 3** ist der Ausweg ohne Verlust. Ein statischer Code löst das Problem des Nutzers zu 60 % und kostet nichts, und die Zusage „läuft nie ab" ist verifiziert. Wer sie nimmt, ist nicht verloren - er hat gerade erlebt, dass das Produkt ihm nichts wegnimmt.
+
+Der letzte Satz ist Risk Reversal an genau der Stelle, wo die Kategorie ihren schlechtesten Ruf hat: das Abschalten bereits gedruckter Codes.
+
+---
+
+## Teil 2 - Die Retention-Mails
+
+Die Copy ist besser als der Durchschnitt. Absenderpersona ist da (Timo, Founder, Reply geht an einen Menschen), keine Ausrufezeichen-Orgie, konkrete Zahlen. Was fehlt, liegt eine Ebene tiefer.
+
+### Mail 1 - Tag 3, Aktivierung
+
+Betreff: `You haven't made one yet`
+Headline: `You haven't made one yet, {Name}. 3 days since signup · 0 QR codes created`
+
+Das ist die stärkste der drei. Der Betreff ist ein Pattern Interrupt in einem Posteingang voller „Tips & Tricks", und die Zeile `Your 3 free dynamic QR codes are still there. Unused.` ist Pointing statt Talking.
+
+Zwei Schwächen:
+
+**Der Betreff kann als Vorwurf gelesen werden.** „You haven't made one yet" mit Doppeldeutigkeit - ist das eine Beobachtung oder eine Rüge? Die Headline im Body löst es auf, der Betreff allein nicht. Alternative, gleiche Länge, ohne Vorwurfsrisiko: `Your 3 free codes are still sitting there`.
+
+**Es fehlt der Anlass.** Die Mail erklärt, *wie* man einen Code macht (drei Schritte), aber nicht, *wofür der Empfänger sich damals angemeldet hat*. Wenn beim Signup die Quelle bekannt ist - kam er über `/tools/google-review-qr-code`, über die Restaurant-Seite, über Bulk? -, dann gehört Schritt 01 personalisiert. „Paste your URL" ist die generischste denkbare Aufforderung an jemanden, der wegen Google-Reviews kam.
+
+### Mail 2 - Tag 7, Upgrade
+
+Betreff: `You're at the free limit` bzw. `You're 2 away from the free limit`
+Headline: `{n} of 3 free codes used, {Name}.`
+
+Hier ist der Trigger das Problem, nicht die Worte.
+
+**Die Mail feuert am Tag 7, unabhängig vom Verhalten.** Die Bedingung im Cron ist `createdAt < 7 Tage` und `qrCount > 0` und `plan = FREE`. Ein Nutzer mit **einem** Code bekommt eine Mail mit dem Betreff „You're 2 away from the free limit" - über ein Limit, das ihn nicht drückt und vielleicht nie drücken wird. Das ist eine Upgrade-Aufforderung an jemanden ohne Schmerz. Solche Mails trainieren Empfänger darauf, den Absender zu ignorieren, und der Absender ist hier der Gründer persönlich - das ist teurer Kredit, den man nicht für eine Fehlzündung ausgeben sollte.
+
+**Empfehlung: den Trigger vom Kalender aufs Verhalten umstellen.**
+
+| Zustand | Auslöser | Inhalt |
+|---|---|---|
+| 3 von 3 belegt | sobald erreicht, nicht Tag 7 | Limit-Mail wie jetzt, aber sofort im Moment der Relevanz |
+| 1-2 von 3 belegt | Tag 7 | keine Upgrade-Mail. Stattdessen: was die Scan-Daten des ersten Codes zeigen |
+| 3 von 3 und erster Code hat Scans | 3 Tage nach Limit | Upgrade mit den eigenen Zahlen des Nutzers als Beweis |
+
+Das dritte Szenario ist die eigentlich fehlende Mail. Nichts überzeugt einen Marketing-Manager so wie sein eigener erster Datenpunkt: „Dein Code auf dem Flyer hatte 47 Scans, die meisten dienstags zwischen 11 und 14 Uhr." Das ist Pointing in Reinform, und es kostet nichts außer der Query.
+
+**Und ein inhaltlicher Fehler.** Die Vergleichstabelle listet `CSV export: Free ✓ / Pro ✓`. Eine Zeile, in der beide Spalten identisch sind, ist in einer Upgrade-Tabelle wertlos - sie füllt Platz und verwässert die drei Zeilen, die tatsächlich einen Unterschied zeigen. Streichen.
+
+### Mail 3 - Tag 30
+
+Betreff: `{Name}, a month of QR codes - one upgrade worth making`
+Argument: Pro-Nutzer bereuen, das Branding nicht früher hinzugefügt zu haben.
+
+**Das Argument ist gut gebaut und nicht belegt.** Der Satz `The one thing I hear most from Pro users who switched after a few weeks: they wish they'd added their brand sooner` behauptet ein Muster aus Kundengesprächen. Wenn diese Gespräche stattgefunden haben: rein damit, am besten mit einem echten Zitat. Wenn nicht, ist das ein erfundenes Testimonial in indirekter Rede und verstößt gegen die Beweisregel aus dem Product Context („keine erfundenen Testimonials"). Bei einer Zielgruppe, die Bewertungsportale liest, ist das die teuerste Art von Satz.
+
+**Der Aufhänger ist außerdem der schwächere von zwei verfügbaren.** Branding ist ein Ästhetik-Argument. Nach 30 Tagen mit mehreren Codes hat der Nutzer etwas viel Stärkeres in der Hand: Scan-Daten. Der Tag-30-Anlass sollte der erste echte Report sein, nicht ein Logo-Feature. „Deine Codes wurden diesen Monat X-mal gescannt. Hier ist, was du noch nicht sehen kannst" - und dann Device- und Location-Breakdown als das, was Pro freischaltet. Das ist derselbe Kaufgrund, aber hergeleitet aus dem, was der Nutzer selbst erlebt hat.
+
+Das deckt sich mit Offer Brief §10, Option 1: auf Analytics-Tiefe metern statt auf Code-Anzahl. Diese Mail wäre die erste Stelle, an der man das testen kann, ohne das Pricing anzufassen.
+
+### Übergreifend: es fehlt die Mail nach dem ersten Scan
+
+Die Sequenz ist Tag 3, Tag 7, Tag 30 - drei Kalendertermine. Der wichtigste Moment im Lebenszyklus dieses Produkts kommt in keinem davon vor: **der erste Scan eines Codes.** Das ist der Augenblick, in dem aus einem Tool eine Messung wird und in dem das Versprechen der Positionierung zum ersten Mal einlöst. Eine Mail „Dein Code wurde gerade zum ersten Mal gescannt" hat einen Anlass, der nicht konstruiert ist, und braucht überhaupt kein Verkaufsargument.
+
+---
+
+## Teil 3 - Das Post-Download-Popup auf den Tool-Seiten
+
+Aktuell:
+
+> **Your QR code is downloading!**
+> Want to make it smarter - for free?
+>
+> - Edit the link anytime - QR stays the same
+> - See who scans, when & where
+> - Custom colors, logo & frames
+> - Free plan included - upgrade anytime for more
+>
+> [ Create Free Account ] / *No thanks, keep it static*
+
+### Was funktioniert
+
+Das Timing ist richtig: nach dem Download, nicht davor. Der Nutzer hat bekommen, wofür er kam - das Popup nimmt ihm nichts weg. Und `No thanks, keep it static` ist eine ehrliche Ablehn-Option ohne Beschämung, was in dieser Kategorie selten ist. Nicht anfassen.
+
+### Was nicht funktioniert
+
+**Die Headline sagt nichts.** `Your QR code is downloading!` ist eine Statusmeldung. Der Nutzer sieht den Download in seinem Browser, er braucht keine Bestätigung. Diese Zeile ist die prominenteste Fläche des Popups und verbraucht sie für eine Information, die der Nutzer schon hat.
+
+**Der Kernnutzen ist die dritte Zeile in einer Bullet-Liste.** `Edit the link anytime - QR stays the same` ist das gesamte Argument des Produkts, versteckt zwischen einem Icon und drei gleichgewichtigen Geschwistern. In einer Liste von vier gleich formatierten Punkten ist keiner davon wichtig.
+
+**Es fehlt der Anlass in diesem Moment.** Der Nutzer hat gerade einen **statischen** Code heruntergeladen. Der interessante Satz ist nicht „mach ihn schlauer", sondern die Konsequenz dessen, was er gerade getan hat: dieser Code ist ab jetzt festgelegt. Das ist kein Vorwurf und keine Drohung, das ist eine Tatsache über die Datei in seinem Download-Ordner - und exakt Belief 1 aus dem Necessary-Beliefs-Doc.
+
+**Es ist auf allen Tool-Seiten identisch.** Wer auf `/tools/google-review-qr-code` war, will Bewertungen. Wer auf `/tools/wifi-qr-code` war, will Gäste ins WLAN. Ein Popup, das beiden dasselbe sagt, spricht keinem von beiden.
+
+### Vorschlag
+
+> **Dieser Code zeigt jetzt für immer auf diese URL.**
+>
+> Das ist bei einem dauerhaften Link genau richtig. Falls sich das Ziel je ändert, brauchst du einen neuen Code und neues Druckmaterial.
+>
+> Ein kostenloses Konto gibt dir 3 dynamische Codes: gleiches Bild, Ziel jederzeit änderbar, jeder Scan gezählt.
+>
+> [ Kostenloses Konto anlegen - keine Karte ]
+> *Nein danke, statisch reicht*
+
+Struktur dahinter: P.I.G.-Opening auf eine Tatsache statt auf ein Feature, dann die Zugeständnis-Zeile („bei einem dauerhaften Link genau richtig") - das ist Offer Brief §9, die Konzession als Glaubwürdigkeits-Move -, dann erst der Mechanismus. Die Bullet-Liste entfällt komplett; drei gleichrangige Vorteile sind schwächer als ein Satz, der den einen benennt.
+
+Pro Tool-Seite variiert nur die erste Zeile:
+
+| Tool | Erste Zeile |
+|---|---|
+| Google Review | Dieser Code zeigt jetzt für immer auf dieses Google-Profil. |
+| WiFi | Dieser Code enthält jetzt dauerhaft dieses WLAN-Passwort. |
+| vCard | Dieser Code enthält jetzt dauerhaft diese Kontaktdaten. |
+| URL / Standard | Dieser Code zeigt jetzt für immer auf diese URL. |
+
+Die WiFi-Variante ist die stärkste der vier, weil sie einen Umstand benennt, den fast niemand vorher bedenkt: das Passwort steht in der gedruckten Datei. Wer es ändert, hat wertloses Material.
+
+---
+
+## Reihenfolge nach Wirkung pro Aufwand
+
+1. **Das 3/3-Modal bauen.** Momentan verliert das Produkt an der Stelle mit der höchsten Kaufabsicht die Arbeit des Nutzers. Das ist der einzige Punkt hier, der auch Entwicklungsarbeit ist und nicht nur Text.
+2. **Trigger der Tag-7-Mail auf Verhalten umstellen.** Query-Änderung im Cron, keine neue Infrastruktur.
+3. **Popup-Copy und Headline umstellen**, mit Variante pro Tool-Seite.
+4. **Die „erster Scan"-Mail** ergänzen - der einzige Anlass in der ganzen Sequenz, der nicht vom Kalender kommt.
+5. **Tag 30 auf Scan-Daten umbauen** statt Branding, und den unbelegten Pro-Nutzer-Satz entweder belegen oder streichen.

SEO-BLOG-PLAN-2026-08.md

@@ -0,0 +1,139 @@
+# Blog-Keyword-Plan aus GSC (letzte 3 Monate, Stand 2026-08-03)
+
+Datenbasis: 1.001 Suchanfragen, 163 Seiten. Gesamt ~34k Impressionen, ~150 Klicks außerhalb der Homepage.
+
+## Kernbefund
+
+Das Problem ist **nicht fehlender Content, sondern Positionen 40–70**. Fast alle großen Cluster haben 0 Klicks bei hunderten Impressionen, weil sie auf Seite 4–7 stehen. Dazu kommt **Kannibalisierung**: mehrere Blogposts konkurrieren mit der Money-Page um dasselbe Keyword — und alle verlieren.
+
+Beispiel Tracking:
+
+| URL | Impr. | Position |
+|---|---|---|
+| /qr-code-tracking | 2.148 | 48,4 |
+| /blog/qr-code-tracking-guide-2025 | 67 | 79,4 |
+| /blog/trackable-qr-codes | 204 | 81,5 |
+| /blog/qr-code-analytics | 93 | 85,1 |
+| /guide/tracking-analytics | 1 | 91,0 |
+
+Fünf Seiten für ein Thema → keine rankt. Gleiches Muster bei Dynamic QR und Instagram.
+
+---
+
+## A) Zuerst verbessern (bestehende Posts, Position 20–45 = erreichbar)
+
+Diese sind am nächsten an Seite 1. Höchster ROI.
+
+**1. `/blog/free-vs-paid-qr-generator` — Position 31, 446 Impr., 1 Klick**
+Beste Blog-Position der Site. Keywords, die schon auf ~26 stehen:
+- `free vs paid qr code generator` (97 Impr., Pos. 26,7)
+- `free vs paid qr code generators` (78, Pos. 26,6)
+- `do you have to pay for qr codes` (42, Pos. 49) + 4 Varianten
+- `do qr codes cost money` (20)
+
+→ Ergänzen: FAQ-Block mit exakt diesen Frageformulierungen ("Do you have to pay for QR codes?", "Do QR codes cost money?"), Preisvergleichstabelle mit echten Zahlen der Wettbewerber, Update-Datum 2026.
+
+**2. `/blog/microsoft-teams-qr-code` — Position 14,4, 287 Impr., 0 Klicks**
+Position 14 mit 0 % CTR = Title/Meta-Problem, kein Ranking-Problem.
+- `microsoft teams qr code generator` (18 Impr., Pos. 9,6 — bereits Seite 1!)
+- `teams qr code generator` (12, Pos. 6,6), `teams qr code` (17, Pos. 27), `qr code for teams meeting` (6, Pos. 11)
+
+→ Title-Tag und Meta-Description neu schreiben (Jahreszahl, Nutzenversprechen), interne Verlinkung von /tools/teams-qr-code. Kein neuer Content nötig.
+
+**3. `/blog/best-qr-code-generator-2026` — Position 41, 55 Impr.**
+Wettbewerber-Cluster hat 1.173 Impr. gesamt, alles bei 0 Klicks:
+- `beaconstac` (96), `beaconstac qr code generator` (75), `beaconstac vs popl` (67), `beaconstac vs mobilo` (57), `popl vs beaconstac` (56), `blinq vs beaconstac` (42), `beaconstac alternative` (34)
+- `flowcode alternative` (51, Pos. 18,3 — nah dran), `flowcode competitors` (38, Pos. 29), `flowcode pricing` (21), `uniqode alternative` (24, Pos. 26)
+
+→ Vergleichstabelle mit Preisen pro Anbieter einbauen. Zusätzlich: die `X vs Y`-Queries (Beaconstac vs Popl/Mobilo/Blinq) sind reine Vergleichsintention ohne passende Seite — dafür Punkt B4.
+
+**4. `/blog/whatsapp-qr-code-generator` — Position 10,2, nur 33 Impr.**
+Steht auf Seite 1, bekommt aber kaum Impressionen — während `/tools/whatsapp-qr-code` bei 441 Impr. auf Position 55 hängt.
+- `whatsapp qr code generator` (211 Impr., Pos. 59,5), `whatsapp qr generator` (107, Pos. 66,5)
+
+→ Klassische Kannibalisierung. Blogpost auf Tool-Seite verlinken (Canonical prüfen), Blogpost als Ratgeber positionieren statt als Generator.
+
+---
+
+## B) Neue Blogposts (echte Nachfrage, keine passende Seite)
+
+**B1. Google Reviews — 1.331 Impr., 0 Klicks, kein einziger Blogpost**
+Größte inhaltliche Lücke. `/tools/google-review-qr-code` hat 1.752 Impr. bei Pos. 37,8 und 0,11 % CTR — komplett ohne Content-Support.
+- `google review qr code generator` (222), `free qr code for google review` (121), `qr code generator for google reviews` (93), `free google review qr code` (89), `review qr code` (83, Pos. 35), `qr code for feedback` (93)
+- Long-Tail: `how to generate google review qr code` (40), `ask for a review by qr code` (6, Pos. 19), `review us on google qr code` (14, Pos. 29)
+
+→ **Post: "How to Create a Google Review QR Code (Free, 2026)"** — Schritt-für-Schritt inkl. Place-ID finden, Aufsteller-Templates, rechtliche Hinweise zum Review-Gating. Verlinkt hart auf das Tool.
+
+**B2. Location / Geo QR — 923 Impr., 0 Klicks, kein Blogpost**
+`/tools/geolocation-qr-code`: 1.087 Impr. bei Position 62,8.
+- `location qr code generator` (129), `qr code for location` (69), `qr code generator location` (53), `location qr code` (41), `qr code generator for map location` (19), `gps qr code generator` (21), `qr code generator gps coordinates` (10)
+
+→ **Post: "Location QR Codes: Google Maps, GPS-Koordinaten & Apple Maps richtig verlinken"** — geo:-URI vs. Maps-Link, welches Format auf iOS/Android funktioniert. Dieses technische Detail sucht sonst niemand ordentlich.
+
+**B3. Coupon / Promo QR — 495 Impr., 0 Klicks**
+`/use-cases/coupon-qr-codes` steht auf Pos. 47,3 (545 Impr.).
+- `qr code coupon` (66), `qr code coupons` (56), `qr coupon` (50), `coupon qr code` (49), `qr coupons` (36), `qr code coupon redemption` (35), `qr code discount coupon` (22), `qr code coupon system` (5)
+
+→ **Post: "QR Code Coupons: Einlösung tracken & Missbrauch verhindern"** — Einmal-Codes, Redemption-Tracking, Ablaufdaten. `qr code coupon redemption` und `qr code coupon system` zeigen Intention über "erstellen" hinaus.
+
+**B4. Wettbewerbsvergleiche `X vs Y` — ~350 Impr., 0 Klicks**
+- `beaconstac vs popl` (67), `beaconstac vs mobilo` (57), `popl vs beaconstac` (56), `blinq vs beaconstac` (42), `bitly vs beaconstac qr codes` (18, Pos. 14,9!), `uniqode vs flowcode` (4), `flowcode vs qr code` (15)
+
+→ Deckt sich mit dem CLAUDE.md-Backlog (`/vs/`-Seiten). Ein Blogpost **"Beaconstac vs Popl vs Blinq vs QR Master: Digital Business Card & QR Vergleich 2026"** fängt mehrere dieser Queries gleichzeitig ab.
+
+**B5. Custom Design / Logo — 465 Impr., 0 Klicks**
+`/custom-qr-code-generator`: 634 Impr., Pos. 42,8.
+- `custom color qr code` (49), `custom design qr code` (44), `custom qr codes with logo` (42), `custom qr code designs` (33), `custom qr code with logo` (31), `how to make custom qr codes` (23), `how to make a custom qr code with logo` (13)
+
+→ **Post: "Custom QR Codes mit Logo: Design-Regeln, die die Scanbarkeit nicht kaputt machen"** — Fehlerkorrektur-Level, Kontrastminimum, Logo-Größe max. 30 %, Farbkombis die scheitern. Klarer How-to-Intent, den die Tool-Seite nicht bedient.
+
+**B6. Bulk / Batch aus Excel & CSV — 402 Impr., aber bereits 2 Klicks + gute Positionen**
+- `bulk qr code generator in google sheets` (23, Pos. 38, **1 Klick**), `batch qr code generator from excel` (32, Pos. 41,8), `bulk qr code generator from excel` (3, Pos. 22, **1 Klick**), `bulk qr code generator excel` (18), `csv qr code generator` (13), `free bulk qr code generator excel` (14)
+
+→ **Post: "QR Codes aus Excel oder Google Sheets erzeugen (Schritt für Schritt)"** — sehr konkreter Workflow-Intent, konvertiert nachweislich schon jetzt.
+
+**B7. Feedback QR — 349 Impr., 0 Klicks**
+`/use-cases/feedback-qr-codes`: 385 Impr., Pos. 60,3.
+- `qr code feedback` (165), `qr code for feedback` (93), `feedback qr code` (62), `qr code for customer feedback` (23), `create qr code for feedback` (21)
+
+→ **Post: "Kundenfeedback per QR Code sammeln: Formulare, Response-Raten, Platzierung"**
+
+---
+
+## C) Konsolidieren statt neu schreiben
+
+**Tracking-Cluster (2.371 Impr., 0 Klicks)** — 5 Seiten kannibalisieren sich (Tabelle oben).
+→ `/blog/trackable-qr-codes`, `/blog/qr-code-analytics`, `/guide/tracking-analytics` per 301 auf `/blog/qr-code-tracking-guide-2025` zusammenlegen. Dieser eine Post wird der Support-Content für `/qr-code-tracking`.
+Zielkeywords: `qr code tracking` (190), `tracking qr code` (158), `qr tracking` (145), `how to track qr code` (118), `track qr code scans` (92), `qr code scan tracking` (88)
+Bereits stark: `how to track qr code scans from a print campaign` (43 Impr., **Pos. 9,9**) — als eigenes H2 ausbauen.
+
+**Dynamic-QR-Cluster (3.598 Impr., 0 Klicks — größtes Volumen der Site)**
+`/dynamic-qr-code-generator` hat 4.147 Impr. bei Pos. 45,5 und **0,02 % CTR**.
+Support-Posts existieren, ranken aber ohne Impressionen (Indexierungsproblem):
+- `/blog/static-vs-dynamic-qr-code` (Pos. 3, aber nur 1 Impr.)
+- `/blog/dynamic-vs-static-qr-codes` (Pos. 5, 1 Impr.) ← Duplikat des vorigen
+- `/blog/convert-static-to-dynamic-qr-code` (Pos. 3,5, 2 Impr.)
+- `/guide/dynamic-qr-code-best-practices` (Pos. 50)
+
+→ Die beiden static-vs-dynamic-Posts sind faktisch dieselbe Seite. Zusammenlegen, dann alle drei prominent von der Money-Page verlinken. Kein neuer Post nötig.
+
+**Instagram** — `/tools/instagram-qr-code` (794 Impr., Pos. 33,7) vs. `/blog/instagram-qr-code-generator` (11 Impr., Pos. 73,4). Blogpost zu How-to umschreiben oder konsolidieren.
+
+---
+
+## Priorisierung
+
+| # | Maßnahme | Aufwand | Potenzial |
+|---|---|---|---|
+| 1 | Tracking-Cluster konsolidieren (C) | mittel | 2.371 Impr. |
+| 2 | Title/Meta Teams-Post fixen (A2) | 15 Min | Pos. 9,6 ohne Klicks |
+| 3 | Google-Review-Post neu (B1) | hoch | 1.331 Impr. |
+| 4 | Free-vs-Paid FAQ ergänzen (A1) | niedrig | Pos. 26 → Seite 1 möglich |
+| 5 | Static-vs-Dynamic-Duplikate mergen (C) | niedrig | entsperrt 3.598 Impr. |
+| 6 | Excel/Sheets-Bulk-Post (B6) | mittel | konvertiert bereits |
+| 7 | Location/Geo-Post (B2) | mittel | 923 Impr. |
+| 8 | Wettbewerbsvergleich vs-Post (B4) | mittel | 350 Impr., hohe Kaufintention |
+
+## Nicht priorisieren
+
+`usdt qr code generator` (85 Impr., Pos. 13, 2 Klicks) und der Crypto-Cluster (765 Impr.) ranken vergleichsweise gut, haben aber schwache Monetarisierung. `system qr dla hoteli` (PL), `qr kütüphane` (TR), `куар мастер` (RU) — internationale Streuung ohne lokalisierte Seiten, aktuell ignorieren.

SEO-UMSETZUNGSPLAN-2026-08.md

@@ -0,0 +1,226 @@
+# SEO-Umsetzungsplan qrmaster.net
+
+Erstellt: 2026-08-04 · Datenbasis: GSC-Export 2026-08-03 (letzte 3 Monate)
+Zugeschnitten auf **wenige Stunden pro Woche** — jeder Schritt ist einzeln abschließbar.
+
+Ausgangslage: ~34.000 Impressionen, ~150 Klicks außerhalb der Homepage. Kein Sichtbarkeits-, sondern ein Positions- und Konsolidierungsproblem.
+
+---
+
+## REVISION 2026-08-04 — nach Code- und Live-Prüfung
+
+Beim Umsetzen von Phase 1 hat sich die Ausgangslage als anders herausgestellt als aus den reinen GSC-Daten ableitbar. Drei Befunde, die den Plan verändern.
+
+### Befund 1: Kaputter Title (behoben)
+
+`/blog/qr-code-tracking-guide-2025` hatte rohes HTML im `title`-Feld:
+
+```
+title: '<a href="/qr-code-tracking" class="...">QR Code Tracking</a>: Complete Guide 2026'
+```
+
+Live ausgeliefert wurde daraus im `<title>`-Tag, in der H1, in `og:title` und `twitter:title`:
+
+```
+&lt;a href="/qr-code-tracking" class="text-blue-600 underline font-semibold"&gt;QR Code Tracking&lt;/a&gt;: Complete Guide 2026 | QR Master
+```
+
+**Das erklärt Position 79,4 vollständig.** Kein Content-, kein Kannibalisierungsproblem — ein unbrauchbares Snippet. Einzelvorkommen, alle anderen Titles sind sauber. Behoben in `src/lib/blog-data.ts:1160`.
+
+### Befund 2: Konsolidierungsrunde lief bereits (Commit 671c1a1 / 2026-07-10)
+
+Live und funktionierend:
+
+| Quelle | Ziel |
+|---|---|
+| `/blog/qr-code-analytics` | `/qr-code-analytics` |
+| `/blog/qr-code-restaurant-menu` | `/restaurants` |
+| `/guide/tracking-analytics` | `/learn/tracking` |
+| `/guide/qr-code-best-practices` | `/learn/basics` |
+| `/guide/bulk-qr-code-generation` | `/learn/developer` |
+
+Die GSC-Positionen dieser URLs sind damit **historisch** — die Redirects waren nur die letzten ~3,5 Wochen des Auswertungsfensters aktiv. Die Phase-1.1-Tabelle weiter unten ist insoweit überholt.
+
+**Konsequenz:** Nicht `/blog/qr-code-tracking-guide-2025` zum Ziel machen, wie ursprünglich geplant. Die bestehende Architektur ist `/learn/[pillar]` als Hub. Dieser Struktur folgen, keine dritte parallel aufmachen.
+
+### Befund 3: Der Learn-Hub hält die Kannibalisierung am Leben
+
+`/learn/tracking` listet und verlinkt **alle fünf** konkurrierenden Tracking-Artikel gleichzeitig — inklusive `/blog/qr-code-analytics`, das eine 301-Quelle ist. Der Hub ist damit nicht die Lösung, sondern der Motor: Er hält jeden Artikel im Index und intern verlinkt, statt Signale zu bündeln.
+
+Zusätzlich behoben:
+
+- **Footer** verlinkte sitewide auf `/guide/tracking-analytics` und `/guide/qr-code-best-practices` — beides 301-Quellen. Jede Seite der Site leitete Linkkraft durch eine Weiterleitung. → jetzt `/learn/tracking` und `/learn/basics` (`src/components/ui/Footer.tsx:88-89`)
+- **IndexNow** meldete aktiv die drei `/guide/*`-URLs an Suchmaschinen, also Redirect-Quellen. → jetzt die `/learn/*`-Pillars (`src/lib/indexnow.ts:125-130`)
+
+### Offen aus dieser Runde
+
+- [ ] `/learn/tracking` entrümpeln: nur noch auf die eine überlebende Tracking-Seite verlinken, nicht auf alle fünf
+- [ ] `/blog/trackable-qr-codes` (204 Impr., Pos. 81,5) ist **nicht** weitergeleitet und lebt weiter → 301 auf den Guide
+- [ ] `src/app/(main)/guide/*/page.tsx` existieren noch als Komponenten mit Self-Canonical, obwohl der Redirect greift → Dead Code entfernen
+- [ ] Drei FAQ-Antworten in `industry-pages.ts` (Zeilen 102, 375, 735) und `growth-pages.ts:473` verlinken auf `/blog/qr-code-restaurant-menu` → auf `/restaurants` umhängen
+
+**Erst diese Punkte, dann Phase 2.** Die Reihenfolge im Plan bleibt sonst gültig.
+
+---
+
+## Wichtige Korrektur vorab: Intent-Check vor Snippet-Rewrites
+
+Ich hatte empfohlen, die `/qr-code-for/`-Seiten mit Position < 20 und 0 % CTR per Title-Rewrite zu fixen. Beim Prüfen der Seiten stimmt das **nur zum Teil**. Die Meta-Titles sind bereits gut geschrieben:
+
+> `barbershops` → „QR Codes for Barbershops: Bookings & Reviews"
+> `cinemas` → „QR Codes for Cinemas: Tickets & Loyalty"
+
+Das Problem liegt woanders. Beispiel `/qr-code-for/barbershops` (327 Impr., Position 9,8, 4 Klicks) — die tatsächlichen Suchanfragen:
+
+| Query | Impr. | Pos. |
+|---|---|---|
+| short code for barbershops | 16 | 21,8 |
+| qr barber | 13 | 8,9 |
+| short code for barber shops | 6 | 16,3 |
+| barber+scan | 5 | 9,6 |
+| barcode grooming | 4 | 11,0 |
+| short code for barber shop | 4 | 26,0 |
+
+Das Muster `short code for X` zieht sich durch: `short code for barbers`, `for yoga studios`, `for cinemas`, `for bars`, `for nail bars`, `for theaters`, `for barbershop` — zusammen rund 60 Impressionen. Wer „short code for barbershops" sucht, will mit hoher Wahrscheinlichkeit einen **SMS-Short-Code**, keinen QR-Code. Diese Impressionen sind mit keinem Title der Welt klickbar.
+
+**Konsequenz für den Plan:** Vor jedem Rewrite die Queries der Einzelseite prüfen. Nur Seiten anfassen, deren Top-Queries echte QR-Intention haben. Das kostet pro Seite zwei Minuten und verhindert, dass Phase 2 zu Beschäftigungstherapie wird.
+
+---
+
+## Phase 0 — Messpunkt setzen (30 Min, einmalig)
+
+Ohne Baseline lässt sich später nicht sagen, ob etwas gewirkt hat.
+
+- [ ] GSC-Export von heute unter `/seo-baseline/2026-08-03/` im Repo ablegen
+- [ ] Vier Zahlen notieren: Gesamtklicks, Gesamtimpressionen, Ø-Position, Anzahl Keywords auf Position < 10
+- [ ] Kalendereintrag: gleicher Export am **2026-11-03** (Google braucht 6–10 Wochen, vorher ist jede Bewertung Rauschen)
+
+**Erfolgskriterium:** Datei liegt im Repo.
+
+---
+
+## Phase 1 — Kannibalisierung auflösen (Wochen 1–2)
+
+Höchster Hebel im ganzen Plan, weil kein neuer Content nötig ist. Fünf Seiten konkurrieren um das Tracking-Thema, keine rankt.
+
+### 1.1 Tracking-Cluster zusammenlegen (~2 Std.)
+
+| URL | Impr. | Pos. | Aktion |
+|---|---|---|---|
+| `/qr-code-tracking` | 2.148 | 48,4 | **bleibt** — Money-Page |
+| `/blog/qr-code-tracking-guide-2025` | 67 | 79,4 | **bleibt** — wird der eine Ratgeber |
+| `/blog/trackable-qr-codes` | 204 | 81,5 | 301 → Guide |
+| `/blog/qr-code-analytics` | 93 | 85,1 | 301 → Guide |
+| `/guide/tracking-analytics` | 1 | 91,0 | 301 → Guide |
+
+- [ ] Die besten Absätze aus den drei Seiten in den Guide übernehmen, bevor umgeleitet wird
+- [ ] Redirects in `next.config.mjs` eintragen
+- [ ] Guide umbenennen: `qr-code-tracking-guide-2025` → Jahreszahl raus oder auf 2026 (Slug-Änderung nur mit Redirect)
+- [ ] Eigenes H2 für `how to track qr code scans from a print campaign` — steht bereits auf **Position 9,9** bei 43 Impressionen
+- [ ] Wechselseitige Verlinkung Guide ↔ `/qr-code-tracking`
+
+**Erfolgskriterium:** Eine URL pro Suchintention. `/qr-code-tracking` unter Position 30 bis November.
+
+### 1.2 Static-vs-Dynamic-Duplikate mergen (~1 Std.)
+
+`/blog/static-vs-dynamic-qr-code` (Pos. 3, 1 Impr.) und `/blog/dynamic-vs-static-qr-codes` (Pos. 5, 1 Impr.) sind faktisch dieselbe Seite. Beide ranken top und bekommen zusammen 2 Impressionen — klassisches Zeichen dafür, dass Google beide kennt und keiner traut.
+
+- [ ] Inhalte in **eine** URL zusammenführen, die andere per 301 darauf
+- [ ] Zusammen mit `/blog/convert-static-to-dynamic-qr-code` (Pos. 3,5) und `/guide/dynamic-qr-code-best-practices` (Pos. 50) prominent von `/dynamic-qr-code-generator` verlinken
+
+**Warum das zählt:** `/dynamic-qr-code-generator` hat mit 4.147 Impressionen das größte Volumen der Site — bei Position 45,5 und 0,02 % CTR.
+
+### 1.3 Instagram entzerren (~30 Min)
+
+`/tools/instagram-qr-code` (794 Impr., Pos. 33,7) vs. `/blog/instagram-qr-code-generator` (11 Impr., Pos. 73,4).
+
+- [ ] Blogpost auf How-to-Intent umschreiben („So erstellst du…") oder konsolidieren, damit er nicht mehr um dasselbe Keyword kämpft
+
+---
+
+## Phase 2 — Snippets mit Intent-Check (Woche 3, ~2 Std.)
+
+Nur Seiten mit Position < 20, CTR < 3 % **und** passender Query-Intention.
+
+**Kandidaten mit belegbar richtiger Intention:**
+
+- [ ] `/blog/microsoft-teams-qr-code` — 287 Impr., **Position 14,4, 0 Klicks**. Queries sind sauber: `microsoft teams qr code generator` (Pos. 9,6), `teams qr code generator` (Pos. 6,6), `qr code for teams meeting` (Pos. 11). Klarster Einzelfall der Site.
+- [ ] `/tools/teams-qr-code` — 489 Impr., Pos. 13,6, CTR 2,45 %
+- [ ] `/tools/call-qr-code-generator` — 119 Impr., Pos. 18,9, 0 Klicks
+- [ ] `/learn` — 486 Impr., Pos. 13,3, CTR 1,65 %
+
+**Erst nach Query-Prüfung anfassen:** `/qr-code-for/cinemas` (168 Impr., Pos. 16), `/qr-code-for/airports` (162, Pos. 10,6), `/qr-code-for/yoga-studios`, `/qr-code-for/art-galleries`, `/qr-code-for/catering`, `/qr-code-for/car-dealerships`.
+
+Prüfweg: GSC → Seiten → URL wählen → Tab „Suchanfragen". Enthalten die Top-3-Queries `short code`, `barcode` oder Branchenbegriffe ohne QR-Bezug, ist die Seite kein Snippet-Fall.
+
+Titles und Descriptions liegen zentral in `src/lib/industry-pages.ts` (Felder `metaTitle`, `metaDescription`) — kein Anfassen einzelner Routen nötig.
+
+**Erfolgskriterium:** Teams-Post von 0 auf messbare Klicks. Alles andere ist Bonus.
+
+---
+
+## Phase 3 — Aufräumen (Woche 4, ~1 Std.)
+
+Nicht die 53 Branchenseiten löschen — die ranken mit Ø Position 20,4 am besten von allen Content-Typen. Tot ist etwas anderes:
+
+| Bereich | Seiten | Impr. | Klicks | Ø Pos. | Vorschlag |
+|---|---|---|---|---|---|
+| `/de/*` | 13 | 194 | 0 | 31,0 | Entscheiden: ausbauen oder deindexieren |
+| `/guide/*` | 2 | 15 | 0 | 70,6 | In `/blog/` überführen (siehe 1.1) |
+| `/compare/*` | 1 | 31 | 0 | 50,6 | Prüfen, ob es die Route noch braucht |
+| `/qr-code-erstellen` | 1 | 264 | 2 | 72,5 | Deutsche Seite ohne DE-Strategie — bündeln mit `/de/*` |
+
+Die DE-Frage ist eine Entscheidung, keine Aufgabe: 13 Seiten mit 0 Klicks binden Crawl-Budget. Entweder eine echte deutsche Sektion mit hreflang, oder weg.
+
+---
+
+## Phase 4 — Neue Posts, einer pro Woche (ab Woche 5)
+
+Reihenfolge nach Impressionen ohne passende Seite. Jeweils ein Post, dann weiter.
+
+| Woche | Post | Nachfrage | Zielseite, die profitiert |
+|---|---|---|---|
+| 5 | Google Review QR Code erstellen (inkl. Place-ID) | 1.331 Impr. | `/tools/google-review-qr-code` (1.752 Impr., Pos. 37,8) |
+| 6 | QR Codes aus Excel & Google Sheets | 402 Impr., **konvertiert bereits** | `/bulk-qr-code-generator` |
+| 7 | Location-QR: Maps, GPS, geo:-URI auf iOS vs. Android | 923 Impr. | `/tools/geolocation-qr-code` (Pos. 62,8) |
+| 8 | Custom QR mit Logo ohne Scanbarkeitsverlust | 465 Impr. | `/custom-qr-code-generator` |
+| 9 | QR-Coupons: Einlösung tracken, Missbrauch verhindern | 495 Impr. | `/use-cases/coupon-qr-codes` |
+| 10 | Beaconstac vs Popl vs Blinq vs QR Master | ~350 Impr., hohe Kaufintention | `/alternatives/*` |
+| 11 | Kundenfeedback per QR sammeln | 349 Impr. | `/use-cases/feedback-qr-codes` |
+
+Jeder Post: Verlinkung zur Money-Page rein **und** raus, Aufnahme in `public/llms.txt`, Eintrag im Sitemap-Lauf.
+
+**Woche 6 zuerst ziehen, falls Zeit knapp wird** — `bulk qr code generator in google sheets` und `bulk qr code generator from excel` haben als einzige Nicht-Brand-Keywords bereits Klicks geliefert. Bewiesene Konversion schlägt großes Volumen.
+
+---
+
+## Phase 5 — Daten-Asset (ab Woche 12, größerer Block)
+
+Aggregierte, anonymisierte Scan-Daten aus QRMaster als Studie: Scan-Zeitpunkte über den Tag, Device-Splits, wie oft dynamische Codes nach dem Druck tatsächlich geändert werden, Abbruchraten.
+
+**Realitätscheck vorab:** `/blog/qr-code-scan-statistics-2026` existiert bereits — Position 38,7, **3 Impressionen**. Ein Daten-Asset rankt nicht, weil es eines ist. Ohne Verteilung passiert nichts.
+
+- [ ] Bestehende Statistik-Seite als Basis nehmen statt neu anzulegen
+- [ ] Echte Zahlen aus der DB, Methodik sichtbar dokumentieren, Stichprobengröße nennen
+- [ ] Eigene Grafiken statt Fremdquellen
+- [ ] Erst danach: aktiv verteilen (Reddit, Branchennewsletter, HARO-artige Anfragen)
+
+Der Wert liegt im Zitiertwerden durch LLMs und in Backlinks, nicht im direkten Ranking. Entsprechend bewerten.
+
+---
+
+## Was dieser Plan bewusst nicht enthält
+
+**Crypto-Cluster** (765 Impr.) — rankt vergleichsweise gut (`usdt qr code generator` Pos. 13, 2 Klicks), monetarisiert aber schwach.
+
+**Internationale Streuung** — `system qr dla hoteli` (PL), `qr kütüphane` (TR), `куар мастер` (RU). Ohne lokalisierte Seiten nicht adressierbar, siehe DE-Entscheidung in Phase 3.
+
+**E-E-A-T-Maßnahmen** — `/authors/timo` existiert bereits (Position 6,4) und hat für sich genommen nichts bewegt. Kein weiterer Aufwand nötig.
+
+**Alles, was „schnell rankt"** — Phase 1 ist der schnellste Effekt im Plan, und auch der braucht 6–10 Wochen bis zur Messbarkeit.
+
+---
+
+## Nächster Schritt
+
+Phase 1.1 (Tracking-Konsolidierung). Zwei Stunden, kein neuer Text, betrifft 2.371 Impressionen.

Userstimo.hermes.env

@@ -0,0 +1,17 @@
+Greenlens TikTOk 
+
+
+
+TIKTOK_CLIENT_KEY=awoihp5i4k4rraen
+TIKTOK_CLIENT_SECRET=TdnxlcQLNRXAy2PW0GsSlQTEqGeHgU7x
+TIKTOK_REDIRECT_URI=https://greenlenspro.com/api/tiktok/callback
+PLANT_IMPORT_ADMIN_KEY=greenlens-admin-2024
+
+
+
+Qrmaster 
+
+TIKTOK_CLIENT_KEY=aw2l7czcin3uk426
+TIKTOK_CLIENT_SECRET=LapujWkqpZfj1jgWBeCzFhw2nuhMPMBA
+TIKTOK_REDIRECT_URI=https://qrmaster.net/api/tiktok/callback
+TIKTOK_ADMIN_KEY=yV0CzlXyw00kFc7hnnJZv_eoH5WaqGsD5l8_GH7Aj2s

agent/SETUP.md

@@ -0,0 +1,91 @@
+---
+env:
+  - name: GSC_CREDENTIALS_JSON
+    description: JSON key of a Google service account added as a user on your Search Console property
+    url: https://console.cloud.google.com/iam-admin/serviceaccounts
+  - name: DATAFORSEO_LOGIN
+    description: DataForSEO API login, for the competitive SERP picture
+    url: https://app.dataforseo.com/api-access
+  - name: DATAFORSEO_PASSWORD
+    description: DataForSEO API password, shown next to the login
+    url: https://app.dataforseo.com/api-access
+  - name: GH_TOKEN
+    description: GitHub token with write access to the blog repo; only for the optional pull-request flow
+    url: https://github.com/settings/personal-access-tokens
+    optional: true
+config:
+  - name: Search Console property
+    description: The property the agent reads rankings from
+    example: sc-domain:example.com
+  - name: Project domain
+    description: The site being improved
+    example: example.com
+  - name: Tracked keywords
+    description: Keywords to track week over week; omit to derive them from the domain's own ranked keywords
+    optional: true
+  - name: Blog repo and content path
+    description: GitHub repo and content directory for the pull-request flow; unset stays report-only
+    example: acme/blog, content/posts/
+    optional: true
+---
+
+# Setup
+
+## Google Search Console
+
+The agent reads rankings through a Google service account that your Search Console
+property trusts. Any Google Cloud project on any of your Google accounts works; the
+only thing that ties it to your site is adding its email as a user in Search Console.
+
+With the gcloud CLI signed in:
+
+```bash
+gcloud services enable searchconsole.googleapis.com
+gcloud iam service-accounts create seo-improver
+gcloud iam service-accounts keys create /tmp/seo-improver-key.json \
+  --iam-account=seo-improver@PROJECT_ID.iam.gserviceaccount.com
+```
+
+Without gcloud: in the [Cloud Console](https://console.cloud.google.com/iam-admin/serviceaccounts),
+enable the Search Console API, create a service account (no roles needed), and add a
+JSON key under Keys, then Add key. Keep the key file outside the project and delete it
+once the env var is set.
+
+Then the one step that is always manual: in [Search Console](https://search.google.com/search-console),
+select the property, open Settings, then Users and permissions, click Add user, and add
+the service account's email. Restricted permission is enough; the agent only reads.
+
+Set `GSC_CREDENTIALS_JSON` to the entire key-file JSON as a single line.
+
+To verify: mint an access token from the key (JWT bearer grant against
+`https://oauth2.googleapis.com/token`, scope `https://www.googleapis.com/auth/webmasters.readonly`)
+and `GET https://www.googleapis.com/webmasters/v3/sites`. The token-minting code ships in
+`agent/lib/search-console.ts`, ready to reuse. Free and read-only. The property
+must appear with a `permissionLevel` other than `siteUnverifiedUser`; an empty list means
+the user-add step is missing or still propagating (it can take a minute).
+
+## DataForSEO
+
+DataForSEO provides the competitive layer: who ranks above you, search volume, keyword
+gaps. Sign up at [dataforseo.com](https://dataforseo.com) (trial credit available), then
+copy the API login and password from the [API Access page](https://app.dataforseo.com/api-access).
+The API credentials are separate from your dashboard sign-in.
+
+To verify: `GET https://api.dataforseo.com/v3/appendix/user_data` with HTTP Basic auth
+(login:password). Free and read-only; expect `status_code: 20000` in the response body.
+
+## Store the values
+
+Local runs read `.env.local` (gitignored). Deployed and scheduled runs read Vercel
+project env: `vercel env add NAME production` takes the value from stdin, so pipe it in.
+Keep `GSC_CREDENTIALS_JSON` on a single line, quoted so the embedded quotes and
+backslashes survive dotenv parsing.
+
+## Point it at your project
+
+Fill in the `<!-- project-config -->` block at the top of `agent/instructions.md` with
+your property, domain, and optional keywords and blog repo. Leaving the blog repo unset
+keeps the agent report-only. Setting it lets the agent open pull requests against your
+blog: it runs the `gh` CLI in its sandbox and never pushes to your default branch. `gh`
+authenticates from `GH_TOKEN`; if the GitHub CLI is signed in locally, `gh auth token`
+prints one, or create a fine-grained token with write access to just that repo.

agent/connections/dataforseo.ts

@@ -0,0 +1,25 @@
+import { defineMcpClientConnection } from "eve/connections";
+
+// DataForSEO uses HTTP Basic auth (login:password); `auth` only emits Bearer
+// tokens, so the header is built here at the connection layer and the model
+// never sees the credentials.
+export default defineMcpClientConnection({
+  url: "https://mcp.dataforseo.com/mcp",
+  description:
+    "DataForSEO rankings data: live SERP results by keyword/location, the domain's ranked keywords with position and search volume, keyword gaps against competitors, and search volume lookups.",
+  headers: {
+    Authorization: `Basic ${Buffer.from(
+      `${process.env.DATAFORSEO_LOGIN ?? ""}:${process.env.DATAFORSEO_PASSWORD ?? ""}`,
+    ).toString("base64")}`,
+  },
+  // The hosted server exposes every DataForSEO module; this agent needs
+  // exactly four read tools.
+  tools: {
+    allow: [
+      "serp_organic_live_advanced",
+      "dataforseo_labs_google_ranked_keywords",
+      "dataforseo_labs_google_domain_intersection",
+      "keywords_data_google_ads_search_volume",
+    ],
+  },
+});

agent/instructions.md

@@ -0,0 +1,81 @@
+<!-- project-config -->
+Search Console property: https://www.qrmaster.net/
+Project domain: qrmaster.net
+Tracked keywords: not set (derive from the domain's own ranked keywords)
+Blog repo and content path: not set (report-only)
+<!-- /project-config -->
+
+You are an SEO improver agent. You run on a loop: measure where the site ranks, decide what to change to climb, hand back specific changes, and next week check whether the last changes moved the needle.
+
+You do three things every run: **track rankings**, **prioritize a small set of high-leverage improvements**, and **report movement since the previous run**. You do not guess at rankings; you read them from data. You do not smooth over losses; if a page slipped, you say so and why you think it happened.
+
+Your project configuration is the `project-config` block at the top of this file. Do not assume values from examples. When tracked keywords are not set, derive them from the domain's own ranked keywords.
+
+## Data sources
+
+You use two sources, and each answers a different question. **Search Console is primary**: it is Google's own first-party record of how your pages perform, so it is the ground truth for your own site. **DataForSEO is the competitive layer**: it sees the whole SERP, including pages you do not own.
+
+Use the `query_search_analytics` tool for your site's real performance: clicks, impressions, CTR, and average position by query and page, for the configured property. Use `list_search_console_sites` to confirm access and the exact property name.
+
+Use the `dataforseo` connection for what Search Console cannot see: the live SERP for a keyword, who ranks above you and what their pages do, search volume, and keyword gaps you do not yet rank for. It exposes only the tools for those four jobs. This is how you answer "who is beating me and why" and size the opportunity.
+
+If either source is unauthorized or errors, stop and report that blocker instead of fabricating data. Do not silently fall back to a single source.
+
+Use native sandbox command execution for lightweight checks such as `curl`, `node`, CSV/JSON writing, HTTP status, titles, and parsing. Use Agent Browser for rendered pages and JavaScript-dependent content when you inspect a page you plan to improve; load the agent-browser skill for the command reference.
+
+Keep the run read-only against the target site. Do not submit forms, mutate the live site, bypass authentication, or solve CAPTCHAs. Respect robots and obvious rate limits. The only place you ever write is the optional GitHub pull-request flow below.
+
+## State and the loop
+
+Persist each run under `reports/seo-improver/<YYYY-MM-DD>/`. At the start of every run, read the most recent prior run in that directory. That prior report is your baseline: use it to compute deltas, and to check whether the improvements you recommended last time were made and whether rankings responded. If no prior run exists, say this is the baseline run and there is nothing to compare against yet.
+
+## Each run
+
+1. Confirm the Search Console property, project domain, tracked keywords (provided or derived), and target locale/device.
+2. Pull your Search Console performance for the tracked queries and pages (clicks, impressions, CTR, average position), and pull the competitive SERP from DataForSEO for the tracked keywords (who ranks, the ranking URL, search volume, SERP features).
+3. Load the previous run and compute movement: gained, lost, new, dropped-off, and unchanged. Flag anything that fell out of the top 100.
+4. Identify the highest-leverage opportunities, ranked by realistic upside, not just raw volume:
+   - **Striking distance**: queries at ~4-20 where a focused improvement can win a page-1 or top-3 slot; confirm the competition against the live SERP.
+   - **High impressions, low CTR**: pages that earn impressions but lose the click; rewrite title/meta to win it without new rankings.
+   - **Cannibalization**: several of your pages competing for one query; recommend which to consolidate.
+   - **Decay**: pages whose clicks or position fell since a prior run; diagnose likely cause (content staleness, lost links, SERP change, intent shift) and check DataForSEO for what moved above you.
+5. For each opportunity you act on, open the ranking URL, inspect the on-page signals, use DataForSEO to see what the pages currently ranking above it do differently, and write a **specific, ready-to-apply change**: the exact title/meta to use, the heading or section to add, the internal links to add and from where, or the consolidation to make. Tie every recommendation to the ranking evidence that motivates it.
+6. Verify last week's loop: for each improvement recommended in the prior run, state whether it appears to have been applied and what happened to that keyword's position. Keep what worked, drop or revise what did not.
+
+## Output
+
+Write two artifacts under `reports/seo-improver/<YYYY-MM-DD>/`:
+
+- `rankings.csv` — the tracked-keyword snapshot for week-over-week diffing.
+
+  ```csv
+  keyword,location,device,position,previous_position,delta,ranking_url,search_volume,serp_features,status
+  ```
+
+  `status` is one of `gained`, `lost`, `new`, `dropped`, or `flat`. `delta` is positive when position improved (moved toward #1). Leave `previous_position` blank on the baseline run.
+
+- `report.md` — a concise Markdown report:
+  1. Executive summary: net movement this week and the single most important action.
+  2. Movement since last run: biggest gains, biggest losses, new and lost keywords.
+  3. Did last week's changes work: per prior recommendation, applied or not, and the ranking response.
+  4. This week's improvements: an ordered action list, each with the exact change, the target keyword/URL, the expected effect, and the evidence.
+  5. Blockers and data caveats: anything unavailable, rate-limited, or modeled rather than measured.
+
+Use stable IDs such as `SEO-STRIKE-001`, `SEO-CTR-002`, `SEO-DECAY-003` so recommendations are easy to reference across runs and you can report next week on the same ID.
+
+Keep the action list short and high-conviction. A focused list of changes that actually get made beats an exhaustive list that gets ignored.
+
+## Applying changes to a GitHub blog (optional)
+
+By default you only report. If a blog repository is configured, you may go one step further and turn the highest-confidence recommendations into a pull request the user can review and merge. This is opt-in: only do it when the project-config block sets a blog repo and content path (or the prompt provides them) and the run is allowed to apply changes. If no repo is configured, or the blog lives outside GitHub (a hosted CMS, a different provider), stay report-only and say so, and let the user wire their own publishing path.
+
+Use the sandbox `bash` tool to run the GitHub CLI (`gh`), targeting the configured repo with `-R owner/repo`. If `gh` is unauthorized or the repo is inaccessible, report that the write step is blocked and fall back to report-only. Only touch the configured blog repo, and only the content files under its configured path.
+
+When you apply changes:
+
+1. Select the subset of this week's recommendations that map cleanly to files in the blog repo: title and meta-description rewrites, headings, added sections, internal links, and consolidations. Skip anything you cannot ground in a specific source file.
+2. Clone or fetch the repo, create a new branch named like `seo-improver/<YYYY-MM-DD>-<issue-id>`, and edit the source files (Markdown, MDX, or frontmatter). Match the file's existing structure and frontmatter keys; do not reformat unrelated content.
+3. Open a pull request with `gh pr create`. Title it with the issue IDs, and in the body list each change, the target keyword and URL, the expected effect, and the ranking evidence. Never push to the default branch, never merge, never force-push.
+4. Record every PR URL in `report.md` under this week's improvements, and note the issue ID so the next run can check whether the PR merged and whether rankings moved.
+
+One branch and pull request per run unless the user asks otherwise. Keep each PR small and reviewable; a maintainer should be able to read the diff and the rationale in a couple of minutes.

agent/lib/search-console.ts

@@ -0,0 +1,109 @@
+import { createSign } from "node:crypto";
+
+// Google Search Console is the primary data source: real first-party clicks,
+// impressions, CTR, and average position for the site's own pages. Google
+// ships no CLI and no hosted MCP for it, and we only need two read calls, so
+// they are plain tools over the REST API.
+//
+// Auth is a Google service account added as a user on the Search Console
+// property. serviceAccountToken signs a JWT with the service account key and
+// exchanges it for a short-lived read-only access token inside the tool, so
+// the credentials never reach model context. Minting the token with
+// node:crypto keeps this dependency-free.
+const TOKEN_URL = "https://oauth2.googleapis.com/token";
+const SCOPE = "https://www.googleapis.com/auth/webmasters.readonly";
+const API_BASE = "https://searchconsole.googleapis.com/webmasters/v3";
+
+async function serviceAccountToken(): Promise<string> {
+  const raw = process.env.GSC_CREDENTIALS_JSON;
+  if (!raw) throw new Error("GSC_CREDENTIALS_JSON is not set");
+  const { client_email, private_key } = JSON.parse(raw) as {
+    client_email: string;
+    private_key: string;
+  };
+
+  const now = Math.floor(Date.now() / 1000);
+  const header = Buffer.from(JSON.stringify({ alg: "RS256", typ: "JWT" })).toString("base64url");
+  const claim = Buffer.from(
+    JSON.stringify({ iss: client_email, scope: SCOPE, aud: TOKEN_URL, iat: now, exp: now + 3600 }),
+  ).toString("base64url");
+  const signingInput = `${header}.${claim}`;
+  const signature = createSign("RSA-SHA256").update(signingInput).sign(private_key, "base64url");
+  const assertion = `${signingInput}.${signature}`;
+
+  const res = await fetch(TOKEN_URL, {
+    method: "POST",
+    headers: { "Content-Type": "application/x-www-form-urlencoded" },
+    body: new URLSearchParams({
+      grant_type: "urn:ietf:params:oauth:grant-type:jwt-bearer",
+      assertion,
+    }),
+  });
+  if (!res.ok) {
+    throw new Error(`Search Console token exchange failed: ${res.status} ${await res.text()}`);
+  }
+  const data = (await res.json()) as { access_token?: string };
+  if (!data.access_token) throw new Error("Search Console token exchange returned no access_token");
+  return data.access_token;
+}
+
+async function apiRequest(path: string, init?: RequestInit): Promise<unknown> {
+  const token = await serviceAccountToken();
+  const res = await fetch(`${API_BASE}${path}`, {
+    ...init,
+    headers: {
+      authorization: `Bearer ${token}`,
+      "content-type": "application/json",
+      ...init?.headers,
+    },
+  });
+  if (!res.ok) throw new Error(`Search Console request failed: ${res.status} ${await res.text()}`);
+  return res.json();
+}
+
+export interface SearchAnalyticsQuery {
+  siteUrl: string;
+  startDate: string;
+  endDate: string;
+  dimensions?: string[];
+  type?: string;
+  dataState?: string;
+  rowLimit?: number;
+  startRow?: number;
+  dimensionFilterGroups?: Record<string, unknown>[];
+}
+
+export const searchAnalyticsQueryInputSchema = {
+  type: "object",
+  additionalProperties: false,
+  required: ["siteUrl", "startDate", "endDate"],
+  properties: {
+    siteUrl: {
+      type: "string",
+      description: "The property, e.g. `sc-domain:example.com` or `https://www.example.com/`.",
+    },
+    startDate: { type: "string", description: "YYYY-MM-DD (inclusive)." },
+    endDate: { type: "string", description: "YYYY-MM-DD (inclusive)." },
+    dimensions: {
+      type: "array",
+      items: { type: "string", enum: ["query", "page", "country", "device", "date", "searchAppearance"] },
+    },
+    type: { type: "string", enum: ["web", "image", "video", "news", "discover", "googleNews"] },
+    dataState: { type: "string", enum: ["final", "all"] },
+    rowLimit: { type: "integer", description: "Max rows, up to 25000." },
+    startRow: { type: "integer", description: "Zero-based row offset for paging." },
+    dimensionFilterGroups: { type: "array", items: { type: "object", additionalProperties: true } },
+  },
+} as const;
+
+export async function querySearchAnalytics(input: SearchAnalyticsQuery): Promise<unknown> {
+  const { siteUrl, ...body } = input;
+  return apiRequest(`/sites/${encodeURIComponent(siteUrl)}/searchAnalytics/query`, {
+    method: "POST",
+    body: JSON.stringify(body),
+  });
+}
+
+export async function listSites(): Promise<unknown> {
+  return apiRequest("/sites");
+}

agent/sandbox/sandbox.ts

@@ -0,0 +1,19 @@
+import { defineSandbox, defaultBackend } from "eve/sandbox";
+
+export default defineSandbox({
+  backend: defaultBackend({
+    // The auditor must reach any site it is pointed at, so it keeps an
+    // open network policy rather than an allowlist.
+    vercel: { networkPolicy: "allow-all" },
+    docker: { networkPolicy: "allow-all" },
+  }),
+  // Bump the suffix to force a template rebuild after changing the setup scripts.
+  revalidationKey: () => "seo-improver-agent-browser-gh-v1",
+  async bootstrap({ use }) {
+    const sandbox = await use();
+    await sandbox.run({ command: "bash setup-agent-browser.sh" });
+    // `gh` is only used when a blog repo is configured for the optional
+    // pull-request flow; installing it is cheap and keeps setup uniform.
+    await sandbox.run({ command: "bash setup-gh.sh seo-improver" });
+  },
+});

agent/sandbox/workspace/setup-agent-browser.sh

@@ -0,0 +1,88 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+
+mkdir -p "${AGENT_BROWSER_ASSETS_DIR:-reports/assets}"
+if [ ! -f package.json ]; then
+  npm init -y >/dev/null
+fi
+if [ ! -x node_modules/.bin/agent-browser ]; then
+  npm install agent-browser@latest playwright@latest "$@"
+fi
+
+install_agent_browser_shim() {
+  local bin_dir="/usr/local/bin"
+  mkdir -p "$bin_dir"
+  cat > "$bin_dir/agent-browser" <<'SHIM'
+#!/usr/bin/env bash
+exec /workspace/node_modules/.bin/agent-browser "$@"
+SHIM
+  chmod +x "$bin_dir/agent-browser"
+}
+
+install_agent_browser_shim
+
+run_agent_browser_setup_check() {
+  if command -v timeout >/dev/null 2>&1; then
+    timeout 60s npx agent-browser --session setup-check open about:blank >/tmp/agent-browser-setup-check.log 2>&1
+  else
+    npx agent-browser --session setup-check open about:blank >/tmp/agent-browser-setup-check.log 2>&1
+  fi
+}
+
+validate_agent_browser_config() {
+  echo "[setup-agent-browser] validating browser launch..."
+  if run_agent_browser_setup_check; then
+    npx agent-browser --session setup-check close >/dev/null 2>&1 || true
+    echo "[setup-agent-browser] browser launch validation passed."
+    return 0
+  fi
+
+  npx agent-browser --session setup-check close >/dev/null 2>&1 || true
+  echo "[setup-agent-browser] browser launch validation failed:" >&2
+  cat /tmp/agent-browser-setup-check.log >&2 || true
+  rm -f agent-browser.json
+  return 1
+}
+
+if [ -f .agent-browser-ready ] && validate_agent_browser_config; then
+  exit 0
+fi
+rm -f .agent-browser-ready
+
+install_system_chromium() {
+  if ! command -v apt-get >/dev/null 2>&1; then
+    return 1
+  fi
+
+  export DEBIAN_FRONTEND=noninteractive
+  echo "[setup-agent-browser] installing system Chromium..."
+  apt-get update
+  if ! apt-get install -y --no-install-recommends chromium; then
+    return 1
+  fi
+
+  CHROMIUM_PATH="$(command -v chromium || command -v chromium-browser || true)"
+  if [ -z "$CHROMIUM_PATH" ]; then
+    return 1
+  fi
+
+  printf '{"executablePath":"%s","args":"--no-sandbox"}\n' "$CHROMIUM_PATH" > agent-browser.json
+  echo "[setup-agent-browser] using Chromium at $CHROMIUM_PATH"
+  validate_agent_browser_config
+}
+
+install_playwright_chromium() {
+  echo "[setup-agent-browser] installing Playwright Chromium fallback..."
+  npx playwright install --with-deps chromium
+  CHROMIUM_PATH="$(node -e "const { chromium } = require('playwright'); console.log(chromium.executablePath())")"
+  printf '{"executablePath":"%s","args":"--no-sandbox"}\n' "$CHROMIUM_PATH" > agent-browser.json
+  echo "[setup-agent-browser] using Playwright Chromium at $CHROMIUM_PATH"
+  validate_agent_browser_config
+}
+
+if ! install_system_chromium; then
+  echo "[setup-agent-browser] system Chromium unavailable or unusable; falling back to Playwright Chromium..."
+  install_playwright_chromium
+fi
+touch .agent-browser-ready

agent/sandbox/workspace/setup-gh.sh

@@ -0,0 +1,32 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+AGENT_NAME="${1:-atom-eve-agent}"
+
+if ! command -v gh >/dev/null 2>&1; then
+  GH_VERSION="2.62.0"
+  TARBALL="gh_${GH_VERSION}_linux_amd64.tar.gz"
+  URL="https://github.com/cli/cli/releases/download/v${GH_VERSION}/${TARBALL}"
+
+  mkdir -p "$HOME/.local"
+  curl -fsSL "$URL" -o "/tmp/${TARBALL}"
+  tar -xzf "/tmp/${TARBALL}" -C "$HOME/.local" --strip-components=1
+  rm -f "/tmp/${TARBALL}"
+
+  export PATH="$HOME/.local/bin:$PATH"
+  if ! grep -qs '.local/bin' "$HOME/.profile" 2>/dev/null; then
+    printf '\nexport PATH="$HOME/.local/bin:$PATH"\n' >> "$HOME/.profile"
+  fi
+fi
+
+if ! command -v gh >/dev/null 2>&1; then
+  echo "gh installed but not found on PATH; expected $HOME/.local/bin/gh" >&2
+  exit 1
+fi
+
+git config --global user.name "$AGENT_NAME"
+git config --global user.email "${AGENT_NAME}@users.noreply.github.com"
+
+if gh auth status >/dev/null 2>&1; then
+  gh auth setup-git >/dev/null 2>&1 || true
+fi

agent/schedules/weekly.ts

@@ -0,0 +1,6 @@
+import { defineSchedule } from "eve/schedules";
+
+export default defineSchedule({
+  cron: "0 9 * * 1",
+  markdown: "Run the weekly SEO improver loop for the configured property and tracked keywords.",
+});

agent/tools/list_search_console_sites.ts

@@ -0,0 +1,11 @@
+import { defineTool } from "eve/tools";
+import { listSites } from "../lib/search-console.js";
+
+export default defineTool({
+  description:
+    "List the Search Console properties the configured service account can access. Useful to confirm access and the exact property name before querying.",
+  inputSchema: { type: "object", additionalProperties: false, properties: {} } as const,
+  async execute() {
+    return listSites();
+  },
+});

agent/tools/query_search_analytics.ts

@@ -0,0 +1,15 @@
+import { defineTool } from "eve/tools";
+import {
+  querySearchAnalytics,
+  searchAnalyticsQueryInputSchema,
+  type SearchAnalyticsQuery,
+} from "../lib/search-console.js";
+
+export default defineTool({
+  description:
+    "Query Google Search Console Search Analytics for the property: the site's own real clicks, impressions, CTR, and average position by query, page, country, device, and date. First-party ground truth for striking-distance, low-CTR, cannibalization, and decay analysis.",
+  inputSchema: searchAnalyticsQueryInputSchema,
+  async execute(input: unknown) {
+    return querySearchAnalytics(input as SearchAnalyticsQuery);
+  },
+});

articles/devto-hashnode/devto-barcode-encoding-algorithms-ean13-code128.md

@@ -0,0 +1,203 @@
+---
+title: "Barcode Encoding Algorithms: EAN-13 & Code 128 Checksum Math from Scratch in JavaScript"
+description: "A deep computer science exploration of 1D barcode encoding algorithms, covering Modulo 10 and Modulo 103 checksum calculations, building a free barcode generator and a code 128 barcode generator in TypeScript."
+tags: javascript, typescript, algorithms, computer-science
+keywords: free barcode generator, ean code generator, code 128 barcode generator, qr barcode, barcode code generator, free barcode, print barcode
+canonical_url: https://www.qrmaster.net/blog/barcode-generator-tool
+---
+
+# Barcode Encoding Algorithms: EAN-13 & Code 128 Checksum Math from Scratch in JavaScript
+
+Long before 2D QR codes dominated digital marketing, one-dimensional (1D) linear barcodes—such as **EAN-13** in retail products and **Code 128** in logistics and shipping—revolutionized inventory automation.
+
+Building a **free barcode generator** or an **ean code generator** requires understanding that barcode scanner guns and camera libraries do not "guess" numbers from images; they decode precise binary bit patterns (bars and spaces) and verify mathematical **checksums** (Modulo 10 for EAN-13; Modulo 103 for Code 128).
+
+In this deep computer science guide, we will examine the bit pattern structures of EAN-13 and Code 128, derive their checksum formulas, and implement a pure TypeScript **barcode code generator** without any external npm dependencies.
+
+---
+
+## 1. Deconstructing EAN-13 Retail Barcode Encoding
+
+An **EAN-13** (European Article Number) barcode produced by an **ean code generator** encodes exactly 13 numeric digits:
+- **First 2–3 digits**: Country Prefix (e.g., `400–440` for Germany, `000–019` for US/Canada).
+- **Next 4–5 digits**: Manufacturer Identification Code.
+- **Next 4–5 digits**: Unique Item / Product Code.
+- **13th Digit**: Mathematical **Modulo 10 Checksum Digit**.
+
+```
+  Country  Manufacturer   Product   Check
+   ┌──┴──┐   ┌────┴────┐ ┌───┴───┐   ┌┴┐
+   4 0 0 1 2 3 4 5 6 7 8 9 5
+```
+
+### The EAN-13 Modulo 10 Checksum Formula
+To compute the 13th check digit for a 12-digit input in an **ean code generator**:
+
+1. Sum all digits in **odd-numbered positions** (1st, 3rd, 5th, 7th, 9th, 11th).
+2. Sum all digits in **even-numbered positions** (2nd, 4th, 6th, 8th, 10th, 12th) and multiply by 3.
+3. Add the two sums together.
+4. The check digit is the number required to reach the next multiple of 10:
+
+$$\text{Check Digit} = (10 - (\text{Total Sum} \pmod{10})) \pmod{10}$$
+
+### Checksum Example Calculation:
+Take the 12-digit string `400123456789`:
+- Odd sum: $4 + 0 + 2 + 4 + 6 + 8 = 24$
+- Even sum: $(0 + 1 + 3 + 5 + 7 + 9) \times 3 = 25 \times 3 = 75$
+- Total: $24 + 75 = 99$
+- Check digit: $(10 - (99 \pmod{10})) \pmod{10} = (10 - 9) \pmod{10} = 1$
+- Final 13-digit EAN-13 code: `4001234567891`
+
+---
+
+## 2. Deconstructing Code 128 High-Density Barcodes
+
+While EAN-13 is strictly numeric, a **code 128 barcode generator** creates high-density alphanumeric barcode formats capable of encoding all 128 ASCII characters (uppercase/lowercase letters, digits, punctuation, and control codes).
+
+### Code 128 Structure
+A Code 128 **qr barcode** structure consists of:
+1. **Start Character**: `Start A` (103), `Start B` (104), or `Start C` (105).
+2. **Data Symbol Characters**: Each character is represented by 11 modules composed of 3 bars and 3 spaces.
+3. **Check Character**: Modulo 103 checksum value.
+4. **Stop Character**: 13-module pattern (`1100011101011`).
+
+### The Code 128 Modulo 103 Checksum Formula
+
+$$\text{Checksum Value} = \left( \text{Start Value} + \sum_{i=1}^{N} (i \times \text{Symbol Value}_i) \right) \pmod{103}$$
+
+---
+
+## 3. Pure TypeScript Barcode Engine (No External Dependencies)
+
+Let's build a standalone TypeScript module (`src/services/barcodeEngine.ts`) for a **free barcode generator** that computes EAN-13 checksums and renders a vector SVG **print barcode**.
+
+### `src/services/barcodeEngine.ts`
+
+```typescript
+export class BarcodeEngine {
+  /**
+   * Computes the Modulo 10 Checksum digit for a 12-digit EAN string in an ean code generator.
+   */
+  public static calculateEAN13Checksum(digits12: string): number {
+    if (!/^\d{12}$/.test(digits12)) {
+      throw new Error('EAN-13 input must be exactly 12 numeric digits.');
+    }
+
+    let oddSum = 0;
+    let evenSum = 0;
+
+    for (let i = 0; i < 12; i++) {
+      const digit = parseInt(digits12[i], 10);
+      if (i % 2 === 0) {
+        oddSum += digit;
+      } else {
+        evenSum += digit;
+      }
+    }
+
+    const totalSum = oddSum + evenSum * 3;
+    const remainder = totalSum % 10;
+    return remainder === 0 ? 0 : 10 - remainder;
+  }
+
+  /**
+   * EAN-13 Binary Bit Patterns for L, G, and R encodings.
+   */
+  private static L_PATTERNS = [
+    '0001101', '0011001', '0010011', '0111101', '0100011',
+    '0110001', '0101111', '0111011', '0110111', '0001011'
+  ];
+
+  private static R_PATTERNS = [
+    '1110010', '1100110', '1101100', '1000010', '1011100',
+    '1001110', '1010000', '1000100', '1001000', '1110100'
+  ];
+
+  /**
+   * Generates a crisp vector SVG string for an EAN-13 barcode.
+   */
+  public static generateEAN13SVG(digits12: string): string {
+    const checkDigit = this.calculateEAN13Checksum(digits12);
+    const fullEan13 = digits12 + checkDigit.toString();
+
+    // Structural guard and center patterns
+    const GUARD_START = '101';
+    const GUARD_CENTER = '01010';
+    const GUARD_END = '101';
+
+    let bitPattern = GUARD_START;
+
+    // Encode Left 6 Digits (using L-Patterns for simplicity)
+    for (let i = 1; i <= 6; i++) {
+      const digit = parseInt(fullEan13[i], 10);
+      bitPattern += this.L_PATTERNS[digit];
+    }
+
+    bitPattern += GUARD_CENTER;
+
+    // Encode Right 6 Digits (using R-Patterns)
+    for (let i = 7; i <= 12; i++) {
+      const digit = parseInt(fullEan13[i], 10);
+      bitPattern += this.R_PATTERNS[digit];
+    }
+
+    bitPattern += GUARD_END;
+
+    // Render SVG
+    const moduleWidthPx = 3;
+    const heightPx = 120;
+    const totalWidthPx = bitPattern.length * moduleWidthPx + 40; // 40px margin
+
+    let svgPaths = '';
+    for (let i = 0; i < bitPattern.length; i++) {
+      if (bitPattern[i] === '1') {
+        const x = 20 + i * moduleWidthPx;
+        svgPaths += `<rect x="${x}" y="10" width="${moduleWidthPx}" height="${heightPx - 30}" fill="#000000" />`;
+      }
+    }
+
+    // Add human-readable numbers text below bars
+    const textSvg = `<text x="${totalWidthPx / 2}" y="${heightPx - 5}" font-family="monospace" font-size="16" text-anchor="middle">${fullEan13}</text>`;
+
+    return `
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 ${totalWidthPx} ${heightPx}" width="${totalWidthPx}" height="${heightPx}">
+  <rect width="100%" height="100%" fill="#FFFFFF" />
+  ${svgPaths}
+  ${textSvg}
+</svg>`.trim();
+  }
+}
+```
+
+---
+
+## 4. Verification & Testing
+
+Let's write a unit test to verify checksum calculation and SVG rendering output.
+
+```typescript
+import { BarcodeEngine } from '../src/services/barcodeEngine';
+
+describe('BarcodeEngine', () => {
+  test('should correctly compute EAN-13 Modulo 10 Checksum', () => {
+    // 400123456789 -> Check digit should be 1
+    const check = BarcodeEngine.calculateEAN13Checksum('400123456789');
+    expect(check).toBe(1);
+  });
+
+  test('should generate valid vector SVG string', () => {
+    const svg = BarcodeEngine.generateEAN13SVG('400123456789');
+    expect(svg).toContain('<svg');
+    expect(svg).toContain('4001234567891'); // Includes computed check digit
+    expect(svg).toContain('</svg>');
+  });
+});
+```
+
+---
+
+## Conclusion
+
+Understanding the binary bit patterns and mathematical checksum algorithms behind 1D barcodes allows developers to build a fast **free barcode generator** without relying on heavy external dependencies.
+
+To generate free high-resolution EAN-13, UPC-A, and Code 128 barcodes online, check out [QR Master Free Barcode Generator](https://www.qrmaster.net/blog/barcode-generator-tool).

articles/devto-hashnode/devto-custom-qr-code-api-nodejs.md

@@ -0,0 +1,359 @@
+---
+title: "Building a High-Performance Custom QR Code Generator API with Node.js & Vector SVG"
+description: "A complete step-by-step developer guide to building a custom QR code generator API in Node.js, covering vector SVG rendering, Reed-Solomon error correction, and creating QR codes from links."
+tags: nodejs, javascript, webdev, api
+keywords: custom qr code generator, create qr code from link, qr code generator online, custom qr code generator free, qr code link generator
+canonical_url: https://www.qrmaster.net/blog/qr-code-api-documentation
+---
+
+# Building a High-Performance Custom QR Code Generator API with Node.js & Vector SVG
+
+QR codes have evolved from simple black-and-white square grids into essential digital-to-physical bridges. Whether you are building a **custom qr code generator** for an application, creating a **qr code generator online** for ticket barcodes, or building an internal microservice to **create a qr code from a link**, building your own API gives you total control over styling, performance, data privacy, and branding.
+
+In this deep-dive guide, we will build a production-ready, high-performance REST API in Node.js and Express that generates vector SVG and high-density PNG QR codes on the fly. We will also explore the math behind Reed-Solomon error correction, quiet zones, color contrast ratios, and how to optimize a **free custom qr code generator** for crisp printing.
+
+---
+
+## 1. Understanding QR Code Architecture & Error Correction
+
+Before writing any code, it is critical to understand how a **custom qr code generator** stores data and why vector graphics (SVG) are vastly superior to raster images (PNG/JPEG) for print media.
+
+### The QR Code Grid Structure
+A QR code is a two-dimensional matrix barcode consisting of:
+1. **Finder Patterns**: The three large squares located at the top-left, top-right, and bottom-left corners. Cameras use these to detect the barcode's orientation and scale.
+2. **Alignment Patterns**: Smaller squares (found in Version 2 and larger) that correct for non-linear distortion when a camera scans a curved surface.
+3. **Timing Patterns**: Alternating black and white modules connecting the finder patterns to establish the matrix coordinate grid size.
+4. **Format Information**: Modules storing the error correction level and the mask pattern used.
+5. **Data & Error Correction Codewords**: The actual payload (URL link, text, JSON) mixed with Reed-Solomon redundancy blocks.
+
+### Reed-Solomon Error Correction Levels
+QR codes use **Reed-Solomon Error Correction**, allowing damaged, dirty, or obscured codes to remain fully scannable:
+
+| Level | Error Recovery Capacity | Recommended Use Case |
+|---|---|---|
+| **L (Low)** | ~7% of codewords restored | Minimal data size, clean digital screens |
+| **M (Medium)** | ~15% of codewords restored | Standard marketing URLs, digital displays |
+| **Q (Quartile)** | ~25% of codewords restored | Industrial packaging, outdoor signage |
+| **H (High)** | ~30% of codewords restored | Embedding brand logos in a **custom qr code generator** |
+
+*Rule of thumb:* When embedding custom logos or high-contrast graphics in the center of a QR code, always enforce **Level H** so the remaining 70% of un-obscured modules provide 100% data integrity.
+
+---
+
+## 2. Why SVG Vector Output Matters for Developers
+
+Raster formats like PNG or JPEG store pixels. If a 300x300 pixel PNG QR code is printed on a large 2-meter billboard, the square modules become blurry and pixelated, leading to scanner camera read failures.
+
+Vector SVG (`Scalable Vector Graphics`) defines QR modules as crisp mathematical paths (`<path d="M..."/>` or `<rect x="..." y="..."/>`). SVG files:
+- Scale infinitely to any print dimension (from business cards to stadium billboards) without loss of crispness.
+- Have a tiny file footprint (typically < 2 KB per code).
+- Allow programmatic CSS styling of foreground, background, and finder pattern colors.
+
+---
+
+## 3. Step-by-Step API Implementation
+
+Let's build a Node.js API with Express that accepts JSON payloads or URL query parameters and streams vector SVG or PNG outputs to **create a qr code from a link**.
+
+### Step 3.1: Project Setup & Dependencies
+
+Initialize a new Node.js project and install the required dependencies:
+
+```bash
+mkdir qr-code-api
+cd qr-code-api
+npm init -y
+npm install express qrcode cors helmet express-rate-limit dotenv
+npm install --save-dev typescript @types/node @types/express @types/cors ts-node-dev
+```
+
+Initialize TypeScript configuration (`tsconfig.json`):
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true
+  },
+  "include": ["src/**/*"]
+}
+```
+
+---
+
+### Step 3.2: Creating the QR Generator Core Engine
+
+Create `src/services/qrEngine.ts`. This service handles matrix generation, error correction mapping, and SVG DOM construction.
+
+```typescript
+import QRCode, { QRCodeRenderersOptions } from 'qrcode';
+
+export interface QROptions {
+  text: string;
+  errorCorrectionLevel?: 'L' | 'M' | 'Q' | 'H';
+  width?: number;
+  margin?: number;
+  colorDark?: string;
+  colorLight?: string;
+  format?: 'svg' | 'png' | 'utf8';
+}
+
+export class QREngine {
+  /**
+   * Generates a scalable vector SVG QR code string.
+   */
+  public static async generateSVG(options: QROptions): Promise<string> {
+    const {
+      text,
+      errorCorrectionLevel = 'M',
+      margin = 4,
+      colorDark = '#000000',
+      colorLight = '#FFFFFF'
+    } = options;
+
+    const qrOptions: QRCodeRenderersOptions = {
+      errorCorrectionLevel,
+      margin,
+      color: {
+        dark: colorDark,
+        light: colorLight
+      }
+    };
+
+    try {
+      const svgString = await QRCode.toString(text, {
+        ...qrOptions,
+        type: 'svg'
+      });
+      return svgString;
+    } catch (err) {
+      throw new Error(`Failed to generate SVG QR code: ${(err as Error).message}`);
+    }
+  }
+
+  /**
+   * Generates a high-density PNG buffer for binary image response.
+   */
+  public static async generatePNGBuffer(options: QROptions): Promise<Buffer> {
+    const {
+      text,
+      errorCorrectionLevel = 'H',
+      width = 600,
+      margin = 4,
+      colorDark = '#000000',
+      colorLight = '#FFFFFF'
+    } = options;
+
+    const qrOptions: QRCodeRenderersOptions = {
+      errorCorrectionLevel,
+      width,
+      margin,
+      color: {
+        dark: colorDark,
+        light: colorLight
+      }
+    };
+
+    try {
+      const buffer = await QRCode.toBuffer(text, {
+        ...qrOptions,
+        type: 'png'
+      });
+      return buffer;
+    } catch (err) {
+      throw new Error(`Failed to generate PNG QR buffer: ${(err as Error).message}`);
+    }
+  }
+}
+```
+
+---
+
+### Step 3.3: Building the Express REST Controller & API Endpoints
+
+Create `src/app.ts` to set up rate limiting, CORS, input validation, and REST route handlers.
+
+```typescript
+import express, { Request, Response, NextFunction } from 'express';
+import cors from 'cors';
+import helmet from 'helmet';
+import rateLimit from 'express-rate-limit';
+import { QREngine, QROptions } from './services/qrEngine.js';
+
+const app = express();
+
+// Security Middlewares
+app.use(helmet());
+app.use(cors());
+app.use(express.json({ limit: '1mb' }));
+
+// Rate Limiter: Prevent API abuse (max 100 requests per minute per IP)
+const apiLimiter = rateLimit({
+  windowMs: 1 * 60 * 1000,
+  max: 100,
+  message: { error: 'Too many QR generation requests. Please try again later.' }
+});
+
+app.use('/api/', apiLimiter);
+
+/**
+ * GET /api/v1/qr
+ * Query Params: text, ecLevel, margin, colorDark, colorLight, format
+ */
+app.get('/api/v1/qr', async (req: Request, res: Response, next: NextFunction) => {
+  try {
+    const text = req.query.text as string;
+    if (!text) {
+      return res.status(400).json({ error: 'Query parameter "text" is required to create qr code from link.' });
+    }
+
+    const format = ((req.query.format as string) || 'svg').toLowerCase();
+    const ecLevel = ((req.query.ecLevel as string) || 'M').toUpperCase() as 'L' | 'M' | 'Q' | 'H';
+    const margin = parseInt(req.query.margin as string, 10) || 4;
+    const colorDark = (req.query.colorDark as string) || '#000000';
+    const colorLight = (req.query.colorLight as string) || '#FFFFFF';
+
+    const options: QROptions = {
+      text,
+      errorCorrectionLevel: ecLevel,
+      margin,
+      colorDark,
+      colorLight
+    };
+
+    if (format === 'png') {
+      const width = parseInt(req.query.width as string, 10) || 600;
+      const pngBuffer = await QREngine.generatePNGBuffer({ ...options, width });
+      res.setHeader('Content-Type', 'image/png');
+      res.setHeader('Cache-Control', 'public, max-age=86400'); // Cache for 24 hours
+      return res.send(pngBuffer);
+    }
+
+    // Default: Vector SVG
+    const svgString = await QREngine.generateSVG(options);
+    res.setHeader('Content-Type', 'image/svg+xml');
+    res.setHeader('Cache-Control', 'public, max-age=86400');
+    return res.send(svgString);
+
+  } catch (error) {
+    next(error);
+  }
+});
+
+/**
+ * POST /api/v1/qr/batch
+ * JSON Body: { items: Array<QROptions> }
+ */
+app.post('/api/v1/qr/batch', async (req: Request, res: Response, next: NextFunction) => {
+  try {
+    const { items } = req.body;
+    if (!Array.isArray(items) || items.length === 0) {
+      return res.status(400).json({ error: 'JSON payload must contain an array "items" with at least one element.' });
+    }
+
+    if (items.length > 50) {
+      return res.status(400).json({ error: 'Batch limit exceeded. Maximum 50 QR codes allowed per request.' });
+    }
+
+    const results = await Promise.all(
+      items.map(async (item: QROptions) => {
+        const svg = await QREngine.generateSVG({
+          text: item.text,
+          errorCorrectionLevel: item.errorCorrectionLevel || 'M',
+          colorDark: item.colorDark || '#000000',
+          colorLight: item.colorLight || '#FFFFFF'
+        });
+        return { text: item.text, svg };
+      })
+    );
+
+    return res.json({ count: results.length, data: results });
+  } catch (error) {
+    next(error);
+  }
+});
+
+// Central Error Handler
+app.use((err: Error, req: Request, res: Response, _next: NextFunction) => {
+  console.error('[QR-API Error]:', err.message);
+  res.status(500).json({ error: 'Internal Server Error', message: err.message });
+});
+
+const PORT = process.env.PORT || 3000;
+app.listen(PORT, () => {
+  console.log(`🚀 Custom QR Code Generator API running on http://localhost:${PORT}`);
+});
+```
+
+---
+
+## 4. Testing Your API with cURL & Examples
+
+Start the development server:
+
+```bash
+npx ts-node-dev src/app.ts
+```
+
+### Example 1: Requesting a Vector SVG QR Code
+Run the following cURL command to fetch an SVG QR code from a link:
+
+```bash
+curl -X GET "http://localhost:3000/api/v1/qr?text=https://www.qrmaster.net&ecLevel=H&colorDark=%231E293B&colorLight=%23F8FAFC" \
+  -H "Accept: image/svg+xml" \
+  --output qrcode.svg
+```
+
+### Example 2: Requesting a High-Resolution PNG for Print
+Fetch a 1000px high-density PNG QR code:
+
+```bash
+curl -X GET "http://localhost:3000/api/v1/qr?text=https://www.qrmaster.net&format=png&width=1000&ecLevel=Q" \
+  --output qrcode.png
+```
+
+### Example 3: Batch API Request
+Send a POST request with multiple items:
+
+```bash
+curl -X POST "http://localhost:3000/api/v1/qr/batch" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "items": [
+      { "text": "https://www.qrmaster.net/docs", "colorDark": "#0284C7" },
+      { "text": "https://www.qrmaster.net/pricing", "colorDark": "#059669" }
+    ]
+  }'
+```
+
+---
+
+## 5. Production Best Practices & Design Pitfalls
+
+When deploying a production-grade **custom qr code generator free** service, keep these crucial guidelines in mind:
+
+### 1. Maintain Contrast Ratios
+Camera sensors require a minimum contrast ratio between foreground modules and background spaces. Always ensure:
+- Dark modules on light backgrounds (avoid light gray on white or dark blue on black).
+- Inverted QR codes (white modules on black background) work on iOS camera apps, but fail on legacy Android devices and embedded barcode readers. Stick to dark foregrounds on light backgrounds whenever possible.
+
+### 2. Respect Quiet Zone Margins
+The **Quiet Zone** is the empty border surrounding all 4 sides of the QR matrix. The ISO/IEC 18004 specification requires a quiet zone of **at least 4 modules wide**. Reducing or cropping this margin causes camera auto-focus algorithms to miss the finder pattern boundaries.
+
+### 3. Keep Payload Size Minimal
+The more characters you encode into a static QR code, the larger the matrix version becomes (e.g., Version 1 is 21x21 modules; Version 10 is 57x57 modules). High-density matrices require users to stand closer and hold their camera still.
+- **Pro Tip:** Use URL shorteners or dynamic redirection URLs (e.g., `https://qr.domain.com/x9z`) to keep the payload under 30 characters, resulting in a clean, low-density Version 2 matrix that scans instantly.
+
+---
+
+## Conclusion
+
+Creating your own **custom qr code generator** API gives you full programmatic freedom over format, styling, error correction, and batch automation. By leveraging Node.js and vector SVG rendering, your application can effortlessly scale to handle thousands of print-ready requests per second.
+
+If you prefer a fully managed solution with dynamic redirection, real-time scan analytics, custom logo embedding, and enterprise SLA uptime, check out [QR Master Custom QR Code Generator](https://www.qrmaster.net/custom-qr-code-generator) — built for developers and growth teams.

articles/devto-hashnode/devto-edge-dynamic-qr-redirect-engine.md

@@ -0,0 +1,246 @@
+---
+title: "Designing a Low-Latency Dynamic QR Redirect Engine at the Edge with Redis & Middleware"
+description: "A comprehensive system architecture guide for building a sub-20ms dynamic QR code generator engine using Edge Functions, an editable QR code generator proxy, Redis, and scan tracking."
+tags: systemdesign, redis, serverless, webdev
+keywords: dynamic qr code generator, free dynamic qr code generator, editable qr code generator, editable qr code, qr code generator with tracking, qr code tracking, dynamic qr code
+canonical_url: https://www.qrmaster.net/blog/qr-code-analytics
+---
+
+# Designing a Low-Latency Dynamic QR Redirect Engine at the Edge with Redis & Middleware
+
+Static QR codes hardcode their destination URL directly into the matrix data. Once printed on 10,000 billboards or product packages, a typo in the URL means reprinting everything at massive cost.
+
+A **dynamic qr code generator** solves this by encoding a permanent short proxy URL (e.g., `https://qr.domain.com/r/xyz123`). An **editable qr code generator** lets you change the target destination link in your dashboard anytime post-print. When scanned, an **editable qr code** intercepts the request, logs scan metrics (device type, geo-location, timestamp), and issues an HTTP `302 Found` or `307 Temporary Redirect` response to the target URL.
+
+However, if your redirect engine takes 800ms to resolve a database query before forwarding the user, the physical scan experience feels sluggish. In this article, we will design a **free dynamic qr code generator** backend engine operating with sub-20ms global redirect latencies using Edge Middleware (Vercel Edge / Cloudflare Workers), Redis in-memory caching, and a **qr code generator with tracking** pipeline.
+
+---
+
+## 1. System Architecture Overview
+
+To achieve sub-20ms global redirect latencies in a **dynamic qr code generator**, database calls must never block the HTTP response thread.
+
+```
+                  ┌─────────────────────────────────────────┐
+                  │          Physical Phone Scanner          │
+                  └────────────────────┬────────────────────┘
+                                       │
+                         HTTP GET /r/xyz123 (Proxy)
+                                       │
+                                       ▼
+                  ┌─────────────────────────────────────────┐
+                  │      Edge Middleware (Cloudflare/Vercel)│
+                  │   - Fast Geo-IP & User-Agent Parsing    │
+                  └──────────┬───────────────────┬──────────┘
+                             │                   │
+                     1. Cache Hit (<5ms)         │ 2. Async Log Stream
+                             │                   │  (Non-blocking Queue)
+                             ▼                   ▼
+                  ┌─────────────────────┐ ┌─────────────────────────┐
+                  │ Upstash Redis / K-V │ │ Kafka / Upstash QStash  │
+                  └─────────────────────┘ └────────────┬────────────┘
+                             │                         │
+                     HTTP 307 Redirect                 ▼
+                             │            ┌─────────────────────────┐
+                             │            │ Analytics DB (ClickHouse│
+                             ▼            │     or PostgreSQL)      │
+                  ┌─────────────────────┐ └─────────────────────────┘
+                  │ Final Target Webpage│
+                  └─────────────────────┘
+```
+
+### Key Architectural Decisions:
+1. **Edge Execution**: Run redirect logic in multi-region PoPs (Points of Presence) close to the physical device.
+2. **Read Path (Hot Path)**: Fetch URL mappings from a distributed, low-latency Redis cache for your **editable qr code generator**.
+3. **Write Path (Analytics Async)**: Push scan metadata to a queue or log collector off the main execution thread so **qr code tracking** adds **0ms** to user delay.
+4. **HTTP Status Code**: Use `307 Temporary Redirect` (or `302 Found`). Never use `301 Moved Permanently`, as browsers will cache the redirect locally and bypass your server on future scans, ruining **qr code generator with tracking** metrics!
+
+---
+
+## 2. Setting Up Edge Middleware in Next.js
+
+Below is an implementation of Edge Middleware in Next.js (`src/middleware.ts` or Cloudflare Worker script) that handles dynamic redirection for an **editable qr code generator**.
+
+### Step 2.1: Installing Dependencies
+
+```bash
+npm install @upstash/redis @upstash/qstash
+```
+
+### Step 2.2: Implementing Edge Redirect Middleware
+
+Create or update `middleware.ts`:
+
+```typescript
+import { NextResponse } from 'next/server';
+import type { NextRequest } from 'next/server';
+import { Redis } from '@upstash/redis';
+
+// Initialize low-latency edge Redis client
+const redis = new Redis({
+  url: process.env.UPSTASH_REDIS_REST_URL!,
+  token: process.env.UPSTASH_REDIS_REST_TOKEN!,
+});
+
+export async function middleware(req: NextRequest) {
+  const { pathname } = req.nextUrl;
+
+  // Match route pattern: /r/:code (e.g., /r/campaign-2026)
+  if (pathname.startsWith('/r/')) {
+    const code = pathname.split('/r/')[1];
+    if (!code) {
+      return NextResponse.redirect(new URL('/404', req.url));
+    }
+
+    const startTime = performance.now();
+
+    // 1. Fetch destination URL from Redis cache (Hot Path)
+    const targetUrl = await redis.get<string>(`qr:link:${code}`);
+
+    if (!targetUrl) {
+      // Fallback: If not in cache, redirect to fallback page or 404
+      return NextResponse.redirect(new URL('/link-expired', req.url));
+    }
+
+    // 2. Extract Device & Geo Metadata from Edge Request Headers for QR Code Tracking
+    const ip = req.headers.get('x-forwarded-for') || req.headers.get('x-real-ip') || '127.0.0.1';
+    const userAgent = req.headers.get('user-agent') || 'Unknown';
+    const country = req.headers.get('x-vercel-ip-country') || req.headers.get('cf-ipcountry') || 'US';
+    const city = req.headers.get('x-vercel-ip-city') || 'Unknown';
+
+    // 3. Asynchronously Log Scan Analytics (Fire and Forget)
+    const scanEvent = {
+      code,
+      targetUrl,
+      timestamp: new Date().toISOString(),
+      ip,
+      userAgent,
+      country,
+      city,
+      latencyMs: Math.round(performance.now() - startTime),
+    };
+
+    // Queue analytic event asynchronously without awaiting
+    const logPromise = redis.lpush('queue:scan_analytics', JSON.stringify(scanEvent));
+
+    if (typeof (req as any).waitUntil === 'function') {
+      (req as any).waitUntil(logPromise);
+    }
+
+    // 4. Return HTTP 307 Temporary Redirect immediately
+    return NextResponse.redirect(targetUrl, {
+      status: 307,
+      headers: {
+        'Cache-Control': 'no-store, no-cache, must-revalidate, proxy-revalidate',
+        'X-Redirect-Latency': `${Math.round(performance.now() - startTime)}ms`,
+      },
+    });
+  }
+
+  return NextResponse.next();
+}
+
+export const config = {
+  matcher: '/r/:path*',
+};
+```
+
+---
+
+## 3. Asynchronous Analytics Processing Pipeline for Tracking
+
+Logging scan events directly to a relational database (like PostgreSQL or MySQL) inside the request loop introduces locking overhead and database connection pool exhaustion under high traffic spikes.
+
+A robust **qr code generator with tracking** streams events into a queue and processes them with a background consumer job.
+
+### Background Consumer Worker (`scripts/analyticsWorker.ts`)
+
+```typescript
+import { Redis } from '@upstash/redis';
+import { PrismaClient } from '@prisma/client';
+
+const redis = new Redis({
+  url: process.env.UPSTASH_REDIS_REST_URL!,
+  token: process.env.UPSTASH_REDIS_REST_TOKEN!,
+});
+
+const prisma = new PrismaClient();
+
+interface ScanEvent {
+  code: string;
+  targetUrl: string;
+  timestamp: string;
+  ip: string;
+  userAgent: string;
+  country: string;
+  city: string;
+  latencyMs: number;
+}
+
+async function startWorker() {
+  console.log('🔄 QR Code Tracking Worker active. Polling scan queue...');
+
+  while (true) {
+    try {
+      // Pop up to 100 scan events in batch from Redis list
+      const rawEvents = await redis.rpop('queue:scan_analytics', 100);
+
+      if (rawEvents && rawEvents.length > 0) {
+        const events: ScanEvent[] = rawEvents.map((item) => JSON.parse(item));
+
+        // Batch insert into database
+        await prisma.scanLog.createMany({
+          data: events.map((e) => ({
+            qrCode: e.code,
+            destination: e.targetUrl,
+            scannedAt: new Date(e.timestamp),
+            ipAddress: e.ip,
+            deviceUserAgent: e.userAgent,
+            countryCode: e.country,
+            cityName: e.city,
+            processingLatency: e.latencyMs,
+          })),
+        });
+
+        console.log(`✅ Processed ${events.length} scan records.`);
+      } else {
+        await new Promise((resolve) => setTimeout(resolve, 1000));
+      }
+    } catch (err) {
+      console.error('❌ Analytics Worker Error:', err);
+      await new Promise((resolve) => setTimeout(resolve, 2000));
+    }
+  }
+}
+
+startWorker();
+```
+
+---
+
+## 4. Handling High-Traffic Campaign Spikes
+
+When a printed **editable qr code** appears on live television or a viral promotional banner, traffic can surge from 10 scans/sec to 20,000 scans/sec instantly.
+
+### Key Resilience Strategies:
+
+1. **Pre-Warming the Edge Cache**: When a user updates a dynamic destination URL in their **editable qr code generator** dashboard, publish the update to Redis immediately:
+   ```typescript
+   await redis.set(`qr:link:${code}`, newTargetUrl);
+   ```
+2. **Stale-While-Revalidate Fallback**: If Redis experiences an outage, fallback to an edge-cached static mapping file or memory LRU cache.
+3. **Bot & Crawler Filtering**: Search engine spiders (Googlebot, Bingbot) and messaging app link prefetchers (WhatsApp, iMessage, Twitter previews) generate fake scans. Filter them out using User-Agent detection before counting unique scans:
+   ```typescript
+   const isBot = /bot|google|baidu|bing|msn|duckduckbot|teoma|slurp|twitterbot|facebookexternalhit|whatsapp/i.test(userAgent);
+   if (isBot) {
+     // Tag or ignore bot scans in qr code tracking
+   }
+   ```
+
+---
+
+## Conclusion
+
+By executing redirect logic at the Edge with Redis and isolating analytics processing asynchronously, you can build a **free dynamic qr code generator** backend achieving ultra-low **<15ms redirect latencies** regardless of geographic location.
+
+To save time and avoid building analytics infra from scratch, explore [QR Master Dynamic QR Code Generator](https://www.qrmaster.net/dynamic-qr-code-generator), an enterprise-grade platform offering dynamic QR management, real-time GA4/UTM integration, and sub-second analytics dashboards.

articles/devto-hashnode/devto-geo-location-uris-maps-deep-links.md

@@ -0,0 +1,242 @@
+---
+title: "Geo-Location URIs vs Deep Links: RFC 5870 geo: Protocol, Apple Maps & Google Maps Traps"
+description: "A cross-platform web developer guide to encoding GPS coordinates in a location qr code generator, comparing RFC 5870 geo: protocols against Apple Maps and Google Maps universal links."
+tags: webdev, mobile, javascript, ios, android
+keywords: location qr code generator, qr code for location, print qr code, print a qr code, maps qr code, gps qr code generator
+canonical_url: https://www.qrmaster.net/blog/location-qr-code
+---
+
+# Geo-Location URIs vs Deep Links: RFC 5870 geo: Protocol, Apple Maps & Google Maps Traps
+
+Scanning a **qr code for location** to navigate to a physical address—such as a store entrance, real estate open house, event parking lot, or tourist landmark—is a foundational real-world mobile use case.
+
+However, developers building a **location qr code generator** often stumble into a major cross-platform fragmentation trap:
+
+- If you use the official IETF standard `geo:` URI protocol (`geo:37.7749,-122.4194`), Android devices open Google Maps seamlessly, but **iOS camera apps display an error or treat it as an unhandled text string**!
+- If you use a Google Maps web URL (`https://maps.google.com/?q=...`), iOS devices open a browser web page instead of launching the native Apple Maps app.
+
+In this technical guide, we will analyze RFC 5870 geo-location standards, cross-platform mobile OS behavior, client-side W3C Geolocation API fallbacks, and build a smart TypeScript Universal Location Resolver to **print a qr code** for navigation.
+
+---
+
+## 1. Breakdown of Location Format Options
+
+Let's compare the four primary ways to encode geographic location coordinates into a **location qr code generator**:
+
+```
+┌─────────────────────────────────────┬─────────────────────────────┬─────────────────────────────┐
+│ Format Method                       │ iOS Camera App Behavior     │ Android Google Lens Behavior│
+├─────────────────────────────────────┼─────────────────────────────┼─────────────────────────────┤
+│ 1. Standard RFC 5870 (geo:lat,lng)  │ ❌ Fails / Shows plain text │ ✅ Opens Native Maps App    │
+│ 2. Google Maps Web URL              │ ⚠️ Opens Safari Web Browser  │ ✅ Opens Native Google Maps │
+│ 3. Apple Maps Universal Link        │ ✅ Opens Native Apple Maps  │ ⚠️ Opens Web Browser        │
+│ 4. Universal Smart Redirect Link    │ ✅ Opens Native Maps App    │ ✅ Opens Native Maps App    │
+└─────────────────────────────────────┴─────────────────────────────┴─────────────────────────────┘
+```
+
+---
+
+## 2. Understanding the RFC 5870 `geo:` URI Specification
+
+The IETF RFC 5870 specification defines the uniform resource identifier (URI) scheme for geographic locations:
+
+```text
+geo:latitude,longitude,altitude;crs=wgs84;u=uncertainty
+```
+
+### Example RFC 5870 Strings:
+
+```text
+# Basic Latitude & Longitude (San Francisco)
+geo:37.7749,-122.4194
+
+# Latitude, Longitude, and Altitude in meters (100m above sea level)
+geo:48.8584,2.2945,100
+
+# Geo-location with query search string ("Coffee")
+geo:37.7749,-122.4194?q=Coffee
+```
+
+### Why iOS Fails to Parse RFC 5870:
+Apple's iOS Camera App parser does not register `geo:` as a supported URI scheme in its native scanner handler. When an iPhone camera detects `geo:37.7749,-122.4194`, it treats the barcode as raw unformatted text rather than an actionable navigation trigger.
+
+---
+
+## 3. Universal Web Links for Maximum Cross-Platform Compatibility
+
+To ensure a **qr code for location** opens natively on both iPhone and Android devices without errors, developers use **Universal Maps Links**.
+
+### Google Maps Universal Link Syntax:
+```text
+https://www.google.com/maps/search/?api=1&query=37.7749,-122.4194
+```
+
+### Apple Maps Universal Link Syntax:
+```text
+https://maps.apple.com/?ll=37.7749,-122.4194&q=Location+Name
+```
+
+### Cross-Platform Dual-Routing Strategy
+When both iOS and Android users scan a single **print qr code**, the best architectural approach is pointing the QR code to a lightweight serverless edge function that inspects the client `User-Agent` and issues an instant 307 redirect to the respective native map handler:
+
+- If `User-Agent` contains `iPhone`, `iPad`, or `Macintosh` $\to$ Redirect to `https://maps.apple.com/?ll=...`
+- Otherwise (Android / Windows / Linux) $\to$ Redirect to `https://www.google.com/maps/search/?api=1&query=...`
+
+---
+
+## 4. Building a Smart Location Resolver in TypeScript
+
+Below is a complete implementation of a Universal Location Resolver Edge Handler in Next.js / TypeScript for a **location qr code generator**.
+
+### `src/app/api/location-resolver/route.ts`
+
+```typescript
+import { NextRequest, NextResponse } from 'next/server';
+
+export interface LocationQuery {
+  lat: number;
+  lng: number;
+  label?: string;
+}
+
+export function GET(req: NextRequest) {
+  const { searchParams } = new URL(req.url);
+  const latStr = searchParams.get('lat');
+  const lngStr = searchParams.get('lng');
+  const label = searchParams.get('label') || 'Target Location';
+
+  if (!latStr || !lngStr) {
+    return NextResponse.json(
+      { error: 'Query parameters "lat" and "lng" are required.' },
+      { status: 400 }
+    );
+  }
+
+  const lat = parseFloat(latStr);
+  const lng = parseFloat(lngStr);
+
+  if (isNaN(lat) || isNaN(lng)) {
+    return NextResponse.json(
+      { error: 'Coordinates lat and lng must be valid floating point numbers.' },
+      { status: 400 }
+    );
+  }
+
+  // Validate Coordinate Boundaries
+  if (lat < -90 || lat > 90 || lng < -180 || lng > 180) {
+    return NextResponse.json(
+      { error: 'Latitude must be between -90 and 90, Longitude between -180 and 180.' },
+      { status: 400 }
+    );
+  }
+
+  const userAgent = req.headers.get('user-agent') || '';
+  const isAppleDevice = /iPhone|iPad|iPod|Macintosh/i.test(userAgent);
+
+  let targetMapUrl: string;
+
+  if (isAppleDevice) {
+    // Construct Native Apple Maps Deep Link
+    const encodedLabel = encodeURIComponent(label);
+    targetMapUrl = `https://maps.apple.com/?ll=${lat},${lng}&q=${encodedLabel}`;
+  } else {
+    // Construct Universal Google Maps Deep Link
+    const encodedQuery = encodeURIComponent(`${lat},${lng}`);
+    targetMapUrl = `https://www.google.com/maps/search/?api=1&query=${encodedQuery}`;
+  }
+
+  // Return 307 Temporary Redirect
+  return NextResponse.redirect(targetMapUrl, {
+    status: 307,
+    headers: {
+      'Cache-Control': 'no-store, max-age=0',
+    },
+  });
+}
+```
+
+---
+
+## 5. Client-Side Geolocation API Integration & Fallback HTML
+
+If you want to offer a web landing page that shows dynamic distance ("You are 450 meters away from the venue entrance"), you can integrate the browser W3C Geolocation API alongside the QR redirect link when you **print a qr code**.
+
+### Example HTML/JS Client Landing Page (`public/location-landing.html`):
+
+```html
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <title>Venue Navigation - Location QR Code</title>
+  <style>
+    body { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; text-align: center; padding: 40px 20px; }
+    .card { max-width: 400px; margin: 0 auto; border: 1px solid #E2E8F0; padding: 24px; border-radius: 12px; box-shadow: 0 4px 6px rgba(0,0,0,0.05); }
+    .btn { display: inline-block; background: #0284C7; color: white; padding: 14px 28px; border-radius: 8px; text-decoration: none; font-weight: 600; margin-top: 16px; }
+  </style>
+</head>
+<body>
+  <div class="card">
+    <h2>📍 Target Destination</h2>
+    <p id="status">Calculating distance to target...</p>
+    <a id="nav-btn" class="btn" href="#">Open Navigation App</a>
+  </div>
+
+  <script>
+    const targetLat = 37.7749;
+    const targetLng = -122.4194;
+
+    const isApple = /iPhone|iPad|iPod|Macintosh/i.test(navigator.userAgent);
+    const navBtn = document.getElementById('nav-btn');
+    const statusEl = document.getElementById('status');
+
+    const mapsUrl = isApple 
+      ? `https://maps.apple.com/?ll=${targetLat},${targetLng}&q=Target+Venue`
+      : `https://www.google.com/maps/search/?api=1&query=${targetLat},${targetLng}`;
+
+    navBtn.href = mapsUrl;
+
+    if ("geolocation" in navigator) {
+      navigator.geolocation.getCurrentPosition(position => {
+        const userLat = position.coords.latitude;
+        const userLng = position.coords.longitude;
+        const distKm = getHaversineDistance(userLat, userLng, targetLat, targetLng);
+        statusEl.innerText = `You are currently ${(distKm * 1000).toFixed(0)} meters away.`;
+      }, () => {
+        statusEl.innerText = "Tap below to open your device maps app.";
+      });
+    }
+
+    function getHaversineDistance(lat1, lon1, lat2, lon2) {
+      const R = 6371;
+      const dLat = (lat2 - lat1) * Math.PI / 180;
+      const dLon = (lon2 - lon1) * Math.PI / 180;
+      const a = Math.sin(dLat/2) * Math.sin(dLat/2) +
+                Math.cos(lat1 * Math.PI / 180) * Math.cos(lat2 * Math.PI / 180) *
+                Math.sin(dLon/2) * Math.sin(dLon/2);
+      const c = 2 * Math.atan2(Math.sqrt(a), Math.sqrt(1-a));
+      return R * c;
+    }
+  </script>
+</body>
+</html>
+```
+
+---
+
+## 6. Summary & Best Practice Rules for Developers
+
+```
+[ ] DO NOT use raw `geo:lat,lng` RFC 5870 strings if your audience includes iOS users.
+[ ] ALWAYS use HTTPS universal web links when creating a qr code for location.
+[ ] Include a human-readable label in the query string (`&q=Store+Name`) so maps apps display a pin marker with your brand name.
+[ ] Validate latitude limits (-90.0 to +90.0) and longitude limits (-180.0 to +180.0) before encoding.
+```
+
+---
+
+## Conclusion
+
+Navigating cross-platform mobile URI quirks is essential for building real-world location QR codes. By implementing smart User-Agent routing between Apple Maps and Google Maps universal links in your **location qr code generator**, developers deliver a flawless 1-tap navigation experience on any smartphone.
+
+To create custom location QR codes with automatic GPS detection, map previews, and scannability analytics, check out [QR Master Location QR Generator](https://www.qrmaster.net/blog/location-qr-code).

articles/devto-hashnode/devto-github-actions-qr-code-previews.md

@@ -0,0 +1,245 @@
+---
+title: "Automating Mobile QR Code Previews in CI/CD Pipelines with GitHub Actions"
+description: "A complete DevOps guide to building a custom GitHub Action that generates dynamic preview QR codes to create a qr code from a link for Vercel/Netlify preview deployments."
+tags: github, devops, ci-cd, automation
+keywords: create qr code from link, create qr code with link, generate qr code for link, make a qr code for a link, qr code generator link
+canonical_url: https://www.qrmaster.net/blog/qr-code-api-documentation
+---
+
+# Automating Mobile QR Code Previews in CI/CD Pipelines with GitHub Actions
+
+When reviewing Pull Requests (PRs) for mobile-first web applications, responsive websites, or PWA features, developers and QA engineers frequently waste time manually copying Vercel or Netlify preview URLs, opening messaging apps, sending links to test devices, or re-typing long URLs into mobile browser address bars.
+
+What if every time a developer opened a Pull Request, a **GitHub Action automatically allowed you to create a qr code from a link** pointing directly to that branch's live preview URL and commented it right into the PR thread?
+
+Quality Assurance testers could simply point their mobile phone camera at the computer screen and instantly test the live staging build!
+
+In this DevOps workflow guide, we will build a custom GitHub Actions workflow (`.github/workflows/qr-preview.yml`) that auto-generates QR preview images when you **create a qr code with a link**.
+
+---
+
+## 1. CI/CD Preview Architecture
+
+Here is how the automated PR feedback loop operates:
+
+```
+┌────────────────────────────────────────┐
+│ Developer Pushes Code to GitHub PR     │
+└───────────────────┬────────────────────┘
+                    │
+                    ▼
+┌────────────────────────────────────────┐
+│ Vercel / Netlify Deploy Preview Builds │ (Generates e.g. https://preview-xyz.vercel.app)
+└───────────────────┬────────────────────┘
+                    │
+                    ▼
+┌────────────────────────────────────────┐
+│ GitHub Action Triggered (pull_request) │
+└───────────────────┬────────────────────┘
+                    │
+                    ▼
+┌────────────────────────────────────────┐
+│ Node.js Script Generates QR Code SVG   │ (Create QR Code From Link)
+└───────────────────┬────────────────────┘
+                    │
+                    ▼
+┌────────────────────────────────────────┐
+│ Action Posts/Updates PR Markdown Comm. │
+└────────────────────────────────────────┘
+```
+
+---
+
+## 2. Setting Up the GitHub Action Workflow
+
+Create a new file in your repository at `.github/workflows/qr-preview.yml`.
+
+### Workflow Configuration (`.github/workflows/qr-preview.yml`)
+
+```yaml
+name: Mobile QR Code Preview Generator
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+
+permissions:
+  pull-requests: write
+  contents: read
+
+jobs:
+  generate-qr-preview:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout Repository
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js Environment
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Install QR Code Generator Dependencies
+        run: |
+          npm install qrcode
+
+      - name: Get Preview URL & Create QR Code From Link
+        id: generate_qr
+        env:
+          PR_NUMBER: ${{ github.event.pull_request.number }}
+          REPO_NAME: ${{ github.repository }}
+          BRANCH_NAME: ${{ github.head_ref }}
+        run: |
+          # Target deployment URL to create a qr code from a link
+          PREVIEW_URL="https://preview-${PR_NUMBER}-${BRANCH_NAME}.vercel.app"
+
+          echo "Preview Target URL: $PREVIEW_URL"
+          echo "preview_url=$PREVIEW_URL" >> $GITHUB_OUTPUT
+
+          # Create inline Node script to generate SVG QR code as Data URI
+          node -e "
+            const QRCode = require('qrcode');
+            const url = '$PREVIEW_URL';
+            QRCode.toString(url, { type: 'svg', margin: 2, color: { dark: '#0F172A', light: '#FFFFFF' } }, (err, svg) => {
+              if (err) throw err;
+              const encoded = Buffer.from(svg).toString('base64');
+              const dataUri = 'data:image/svg+xml;base64,' + encoded;
+              require('fs').writeFileSync('qr_data_uri.txt', dataUri);
+            });
+          "
+          
+          DATA_URI=$(cat qr_data_uri.txt)
+          echo "qr_data_uri=$DATA_URI" >> $GITHUB_OUTPUT
+
+      - name: Comment QR Code on Pull Request
+        uses: actions/github-script@v7
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          script: |
+            const prNumber = context.payload.pull_request.number;
+            const previewUrl = '${{ steps.generate_qr.outputs.preview_url }}';
+            const qrDataUri = '${{ steps.generate_qr.outputs.qr_data_uri }}';
+
+            const commentBody = `### 📱 Mobile Preview QR Code
+            
+            Scan this QR code with your phone camera to open and test this PR preview instantly:
+
+            <p align="center">
+              <img src="${qrDataUri}" width="220" height="220" alt="Mobile Preview QR Code" />
+              <br />
+              <a href="${previewUrl}" target="_blank"><strong>Open Direct Preview Link ↗</strong></a>
+            </p>
+
+            ---
+            *Automated by QR CI/CD Pipeline*`;
+
+            const comments = await github.rest.issues.listComments({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: prNumber,
+            });
+
+            const botComment = comments.data.find(comment => 
+              comment.user.type === 'Bot' && comment.body.includes('Mobile Preview QR Code')
+            );
+
+            if (botComment) {
+              await github.rest.issues.updateComment({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                comment_id: botComment.id,
+                body: commentBody
+              });
+              console.log('Updated existing PR comment.');
+            } else {
+              await github.rest.issues.createComment({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                issue_number: prNumber,
+                body: commentBody
+              });
+              console.log('Created new PR comment.');
+            }
+```
+
+---
+
+## 3. How It Works Under the Hood
+
+### Base64 Data URI Trick for Markdown Rendering
+GitHub Markdown does not allow uploading local SVG files directly from a runner disk into a comment thread without hosted storage.
+
+By encoding the generated vector SVG into a **Base64 Data URI string** (`data:image/svg+xml;base64,PHN2Zy...`), the image renders natively inside GitHub PR comment threads without requiring any external S3 bucket uploads when you **generate a qr code for a link**!
+
+```html
+<img src="data:image/svg+xml;base64,PHN2ZyB4bWxucz0..." width="220" height="220" />
+```
+
+### Preventing Comment Spam
+The script lists existing PR comments and searches for a previous bot message containing `"Mobile Preview QR Code"`. If a developer pushes 5 new commits to the PR, the action **updates the single existing comment** with the latest deployment link instead of posting 5 separate duplicate comments.
+
+---
+
+## 4. Advanced Integrations: Netlify & Cloudflare Pages Pipelines
+
+If your repository deploys via Netlify or Cloudflare Pages instead of Vercel, you can hook into their deployment completion events.
+
+### Netlify Deployment Hook Example:
+
+```yaml
+      - name: Fetch Netlify Preview Link
+        id: netlify
+        uses: nwtgck/actions-netlify@v3.0
+        with:
+          publish-dir: './build'
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          deploy-alias: pr-${{ github.event.number }}
+        env:
+          NETLIFY_AUTH_TOKEN: ${{ secrets.NETLIFY_AUTH_TOKEN }}
+          NETLIFY_SITE_ID: ${{ secrets.NETLIFY_SITE_ID }}
+```
+
+### Adding Device UTM Tracking Parameters
+To measure how many QA test scans originate from GitHub Pull Request comments vs Slack links, append custom UTM parameters to **make a qr code for a link** before generating the barcode:
+
+```javascript
+const previewUrlWithUtm = `${previewUrl}?utm_source=github&utm_medium=pr_comment&utm_campaign=qa_mobile_test`;
+```
+
+---
+
+## 5. Automated Unit & E2E Testing with Playwright
+
+To take mobile QA automation a step further, you can combine this workflow with headless E2E testing tools like Microsoft Playwright or Cypress.
+
+For instance, your CI runner can launch a mobile Chrome emulation context, load the preview deployment URL encoded in the QR code, take automated screenshots across different screen viewport sizes (iPhone 15 Pro, Pixel 8, iPad Air), and upload visual diffs directly into the Pull Request build artifact summary.
+
+```typescript
+import { test, expect, devices } from '@playwright/test';
+
+test.use({ ...devices['iPhone 15 Pro'] });
+
+test('Mobile Staging Visual Regression Check', async ({ page }) => {
+  await page.goto(process.env.STAGING_URL || 'http://localhost:3000');
+  await expect(page).toHaveTitle(/QR Master/);
+  await page.screenshot({ path: 'mobile-preview.png' });
+});
+```
+
+---
+
+## 6. Security & Rate Limiting Guidelines
+
+```
+[ ] Grant `pull-requests: write` permission scoped strictly to the workflow job.
+[ ] Store third-party tokens (Vercel/Netlify tokens) securely in GitHub Repository Secrets (`${{ secrets.VERCEL_TOKEN }}`).
+[ ] Enforce Base64 length checks to ensure generated SVG payload remains under 64 KB to comply with GitHub comment payload size limits.
+```
+
+---
+
+## Conclusion
+
+Automating mobile QR code previews in your CI/CD pipeline to **create a qr code from a link** eliminates friction for QA teams, product managers, and developers testing mobile-first web features.
+
+To integrate automated REST API QR code generation into your custom developer workflows, check out [QR Master Developer API Documentation](https://www.qrmaster.net/blog/qr-code-api-documentation).

articles/devto-hashnode/devto-offline-batch-qr-cli-tool.md

@@ -0,0 +1,297 @@
+---
+title: "Building an Offline Batch QR Code Generation CLI Tool in Python & Node.js"
+description: "Learn how to build a bulk qr code generator CLI tool to process 10,000+ records from CSV/Excel files and export high-resolution vector SVG/PNG QR code archives using Node.js and Python."
+tags: python, nodejs, cli, devops
+keywords: bulk qr code generator, free bulk qr code generator, bulk qr code generator excel, csv qr code generator, bulk qr code, batch qr code generator
+canonical_url: https://www.qrmaster.net/blog/bulk-qr-code-generator-excel
+---
+
+# Building an Offline Batch QR Code Generation CLI Tool in Python & Node.js
+
+Generating a single QR code manually in a web browser takes seconds. But when an enterprise client hands you a CSV file containing **50,000 product SKU inventory codes**, **10,000 attendee event tickets**, or **5,000 personalized employee ID badge links**, manual generation becomes impossible.
+
+Browser-based tools will freeze or crash browser tabs when processing tens of thousands of records. You need a dedicated **bulk qr code generator** CLI tool that leverages multi-core CPU workers, streams large files without memory exhaustion, and packages vector SVG outputs into a clean ZIP archive.
+
+In this guide, we will build a production-grade **bulk qr code generator from excel** and CSV files in both **Node.js** and **Python** capable of batch processing thousands of QR codes per minute.
+
+---
+
+## 1. System Requirements & Architecture
+
+Building a **free bulk qr code generator** CLI tool capable of processing massive dataset imports requires avoiding loading entire multi-gigabyte CSV files into RAM memory all at once.
+
+```
+┌─────────────────────────┐
+│ Input CSV / Excel File  │ (e.g. 50,000 rows: ID, Payload, Label)
+└────────────┬────────────┘
+             │
+             ▼
+┌─────────────────────────┐
+│ Stream Reader / Parser  │ (Node.js csv-parser / Python csv module)
+└────────────┬────────────┘
+             │
+             ▼
+┌─────────────────────────┐
+│ Worker Pool Queue       │ (Parallel processing across CPU cores)
+└────────────┬────────────┘
+             │
+             ▼
+┌─────────────────────────┐
+│ Vector SVG / PNG Export │ (Output folder: ./output/QR_00001.svg)
+└─────────────────────────┘
+```
+
+---
+
+## 2. Implementation 1: Node.js / TypeScript CLI Tool
+
+We will build a **csv qr code generator** in Node.js using `commander` for CLI flags, `csv-parser` for streaming, and `p-limit` to bound CPU concurrency.
+
+### Step 2.1: Dependencies
+
+```bash
+npm install commander csv-parser qrcode p-limit archiver
+npm install --save-dev typescript @types/node @types/csv-parser @types/archiver ts-node
+```
+
+### Step 2.2: Node.js CLI Code (`src/bulkQrCli.ts`)
+
+```typescript
+import fs from 'fs';
+import path from 'path';
+import { Command } from 'commander';
+import csvParser from 'csv-parser';
+import QRCode from 'qrcode';
+import pLimit from 'p-limit';
+
+interface CsvRow {
+  filename: string;
+  payload: string;
+}
+
+const program = new Command();
+
+program
+  .name('batch-qr')
+  .description('High-speed offline bulk qr code generator CLI')
+  .version('1.0.0')
+  .requiredOption('-i, --input <path>', 'Input CSV file path (columns: filename, payload)')
+  .option('-o, --output <path>', 'Output directory path', './output_qr')
+  .option('-f, --format <type>', 'Output format (svg or png)', 'svg')
+  .option('-c, --concurrency <number>', 'Parallel CPU worker limit', '20')
+  .option('-e, --error-correction <level>', 'Error correction (L, M, Q, H)', 'M')
+  .parse(process.argv);
+
+const options = program.opts();
+
+async function runBatch() {
+  const inputPath = path.resolve(options.input);
+  const outputDir = path.resolve(options.output);
+  const format = options.format.toLowerCase();
+  const concurrency = parseInt(options.concurrency, 10);
+  const ecLevel = options.errorCorrection.toUpperCase();
+
+  if (!fs.existsSync(inputPath)) {
+    console.error(`❌ Input CSV file not found: ${inputPath}`);
+    process.exit(1);
+  }
+
+  if (!fs.existsSync(outputDir)) {
+    fs.mkdirSync(outputDir, { recursive: true });
+  }
+
+  console.log(`🚀 Starting Bulk QR Code Generator Batch...`);
+  console.log(`📁 Input: ${inputPath}`);
+  console.log(`📂 Output: ${outputDir}`);
+  console.log(`⚡ Concurrency Limit: ${concurrency} workers`);
+
+  const rows: CsvRow[] = [];
+
+  // 1. Read CSV Stream
+  await new Promise<void>((resolve, reject) => {
+    fs.createReadStream(inputPath)
+      .pipe(csvParser())
+      .on('data', (data) => {
+        if (data.payload) {
+          rows.push({
+            filename: data.filename || `qr_${rows.length + 1}`,
+            payload: data.payload,
+          });
+        }
+      })
+      .on('end', () => resolve())
+      .on('error', (err) => reject(err));
+  });
+
+  console.log(`📊 Found ${rows.length} records for bulk qr generation.`);
+
+  const startTime = Date.now();
+  const limit = pLimit(concurrency);
+  let completed = 0;
+
+  // 2. Parallel Generation Queue
+  const tasks = rows.map((row) =>
+    limit(async () => {
+      const sanitizedFilename = row.filename.replace(/[^a-z0-9_-]/gi, '_');
+      const filePath = path.join(outputDir, `${sanitizedFilename}.${format}`);
+
+      try {
+        if (format === 'png') {
+          await QRCode.toFile(filePath, row.payload, {
+            errorCorrectionLevel: ecLevel,
+            width: 800,
+            margin: 4,
+          });
+        } else {
+          const svgString = await QRCode.toString(row.payload, {
+            type: 'svg',
+            errorCorrectionLevel: ecLevel,
+            margin: 4,
+          });
+          fs.writeFileSync(filePath, svgString, 'utf8');
+        }
+
+        completed++;
+        if (completed % 500 === 0 || completed === rows.length) {
+          console.log(`✅ Progress: ${completed} / ${rows.length} generated...`);
+        }
+      } catch (err) {
+        console.error(`❌ Error generating ${row.filename}:`, (err as Error).message);
+      }
+    })
+  );
+
+  await Promise.all(tasks);
+
+  const durationSec = ((Date.now() - startTime) / 1000).toFixed(2);
+  console.log(`\n🎉 Bulk QR Code Generator Completed Successfully!`);
+  console.log(`⏱️ Total Time: ${durationSec} seconds`);
+  console.log(`⚡ Throughput: ${(rows.length / parseFloat(durationSec)).toFixed(0)} codes/sec`);
+}
+
+runBatch().catch((err) => {
+  console.error('Fatal Batch Error:', err);
+  process.exit(1);
+});
+```
+
+---
+
+## 3. Implementation 2: Python Multi-Processing CLI
+
+Python offers native `multiprocessing` for parallel execution across all available CPU threads in a **bulk qr code generator from excel**.
+
+### Step 3.1: Install Dependencies
+
+```bash
+pip install qrcode[pil] click pandas openpyxl
+```
+
+### Step 3.2: Python CLI Script (`batch_qr.py`)
+
+```python
+import os
+import time
+import pandas as pd
+import qrcode
+from qrcode.image.svg import SvgPathImage
+import click
+from multiprocessing import Pool, cpu_count
+
+def generate_single_qr(task):
+    filename, payload, output_dir, fmt, ec_level = task
+    sanitized_name = "".join([c if c.isalnum() or c in ('-', '_') else '_' for c in filename])
+    output_path = os.path.join(output_dir, f"{sanitized_name}.{fmt}")
+
+    ec_map = {
+        'L': qrcode.constants.ERROR_CORRECT_L,
+        'M': qrcode.constants.ERROR_CORRECT_M,
+        'Q': qrcode.constants.ERROR_CORRECT_Q,
+        'H': qrcode.constants.ERROR_CORRECT_H,
+    }
+
+    qr = qrcode.QRCode(
+        version=None,
+        error_correction=ec_map.get(ec_level.upper(), qrcode.constants.ERROR_CORRECT_M),
+        box_size=10,
+        border=4,
+    )
+    qr.add_data(payload)
+    qr.make(fit=True)
+
+    if fmt == 'svg':
+        img = qr.make_image(image_factory=SvgPathImage)
+        img.save(output_path)
+    else:
+        img = qr.make_image(fill_color="black", back_color="white")
+        img.save(output_path)
+
+    return True
+
+@click.command()
+@click.option('--input', '-i', required=True, help='Path to input CSV or Excel file.')
+@click.option('--output', '-o', default='./output_qr', help='Output folder.')
+@click.option('--format', '-f', default='svg', type=click.Choice(['svg', 'png']), help='File format.')
+@click.option('--ec', default='M', type=click.Choice(['L', 'M', 'Q', 'H']), help='Error correction level.')
+def main(input, output, format, ec):
+    """High-Performance Bulk QR Code Generator CLI in Python"""
+    if not os.path.exists(input):
+        click.echo(f"Error: Input file '{input}' does not exist.")
+        return
+
+    os.makedirs(output, exist_ok=True)
+
+    if input.endswith('.xlsx') or input.endswith('.xls'):
+        df = pd.read_excel(input)
+    else:
+        df = pd.read_csv(input)
+
+    if 'payload' not in df.columns:
+        click.echo("Error: File must contain a 'payload' column.")
+        return
+
+    records = []
+    for idx, row in df.iterrows():
+        fname = str(row.get('filename', f'qr_{idx + 1}'))
+        payload = str(row['payload'])
+        records.append((fname, payload, output, format, ec))
+
+    total = len(records)
+    num_cpus = cpu_count()
+    click.echo(f"Starting bulk qr code generator for {total} records using {num_cpus} CPU cores...")
+
+    start_time = time.time()
+
+    with Pool(processes=num_cpus) as pool:
+        pool.map(generate_single_qr, records)
+
+    duration = time.time() - start_time
+    click.echo(f"Bulk batch completed in {duration:.2f} seconds ({total / duration:.0f} codes/sec).")
+
+if __name__ == '__main__':
+    main()
+```
+
+---
+
+## 4. Performance Benchmarks
+
+Running these scripts on a standard 8-Core Apple M1 / Intel i7 workstation yields impressive throughput:
+
+```
+┌───────────────────────────┬────────────────┬─────────────────┬───────────────────┐
+│ Implementation            │ Records        │ Total Time      │ Speed             │
+├───────────────────────────┼────────────────┼─────────────────┼───────────────────┤
+│ Node.js (p-limit 20)      │ 10,000 SVGs    │ 3.8 seconds     │ ~2,630 codes/sec  │
+│ Python (Multiprocessing)  │ 10,000 SVGs    │ 4.2 seconds     │ ~2,380 codes/sec  │
+│ Single-Thread Browser JS  │ 1,000 PNGs     │ 45.0 seconds    │ ~22 codes/sec     │
+└───────────────────────────┴────────────────┴─────────────────┴───────────────────┘
+```
+
+---
+
+## Conclusion
+
+Building your own offline **bulk qr code generator** CLI tool frees you from browser memory limits and third-party rate limits. By utilizing multi-core process pools and vector SVG output, you can generate tens of thousands of print-ready QR codes in seconds.
+
+If you need a cloud-native web dashboard for bulk Excel uploads, automatic ZIP packaging, and dynamic tracking, check out [QR Master Bulk Generator](https://www.qrmaster.net/bulk-qr-code-generator).

articles/devto-hashnode/devto-pdf-file-qr-code-generator-guide.md

@@ -0,0 +1,181 @@
+---
+title: "PDF & File QR Code Generator: How to Convert Documents, Menus & PDFs into Scannable Barcodes"
+description: "A developer and marketer guide to building a PDF QR code generator, handling cloud file storage uploads, optimizing PDF load speeds, and creating dynamic file barcodes."
+tags: webdev, pdf, cloud, tutorial
+keywords: pdf qr code generator free, file qr code generator, generate free qr code for pdf, file to qr code generator, pdf to qr code, qr code generator for file
+canonical_url: https://www.qrmaster.net/blog/qr-code-restaurant-menu
+---
+
+# PDF & File QR Code Generator: How to Convert Documents, Menus & PDFs into Scannable Barcodes
+
+Converting digital documents, PDF menus, product brochures, user manuals, and event schedules into scannable QR codes is one of the most effective ways to eliminate paper waste and distribute digital collateral in physical spaces.
+
+Whether a restaurant guest scans a table sign to view a restaurant menu PDF, a conference attendee scans a badge to download a presentation slide deck, or an industrial customer scans packaging to view a PDF safety manual, using a **pdf qr code generator free** tool connects paper touchpoints directly to digital cloud files.
+
+However, developers and marketers often face technical challenges:
+- How do you host PDF files so they load instantly on mobile networks?
+- Should you use a static file link or an editable **file qr code generator**?
+- How do you optimize PDF file size so phone browsers do not freeze when downloading large multi-megabyte documents over cellular connections?
+
+In this guide, we will cover the end-to-end architecture of a **file to qr code generator**, cloud storage hosting (S3/Cloudflare R2), PDF optimization, and building a TypeScript file upload pipeline.
+
+---
+
+## 1. System Architecture: How a PDF QR Code Works
+
+You cannot embed a 5 MB PDF file directly inside the physical black-and-white modules of a 2D QR matrix. A QR code can store a maximum of ~2,953 bytes.
+
+Therefore, a **pdf qr code generator** works by uploading the PDF document to a secure cloud storage bucket (e.g. AWS S3, Cloudflare R2, Google Cloud Storage) and encoding the hosted URL into a QR barcode.
+
+```
+┌─────────────────────────┐
+│ User Uploads PDF File   │ (e.g. menu.pdf, 1.2 MB)
+└────────────┬────────────┘
+             │
+             ▼
+┌─────────────────────────┐
+│ PDF Optimization Engine │ (Compresses images & vectors)
+└────────────┬────────────┘
+             │
+             ▼
+┌─────────────────────────┐
+│ Cloud Object Storage    │ (AWS S3 / Cloudflare R2 CDN)
+└────────────┬────────────┘
+             │
+             ▼
+┌─────────────────────────┐
+│ Dynamic Proxy Short Link│ (e.g. https://qr.domain.com/pdf/menu-2026)
+└────────────┬────────────┘
+             │
+             ▼
+┌─────────────────────────┐
+│ Vector SVG Barcode      │ (Scanned by Mobile Device Camera)
+└─────────────────────────┘
+```
+
+---
+
+## 2. Static vs. Dynamic PDF QR Codes
+
+When building a **file qr code generator**, choosing between static and dynamic architecture is critical:
+
+```
+┌───────────────────────────────────────┬───────────────────────────────────────┐
+│ Static PDF QR Code                    │ Dynamic File QR Code Generator        │
+├───────────────────────────────────────┼───────────────────────────────────────┤
+│ Links directly to S3 URL              │ Links to proxy URL (/pdf/menu)        │
+│ (e.g., s3.aws.com/b/menu-v1.pdf)      │ which redirects to active PDF.        │
+│                                       │                                       │
+│ ❌ File CANNOT be updated after print  │ 🟢 Replace PDF file anytime           │
+│ ❌ No scan analytics tracking          │ 🟢 Full scan metrics (Geo-IP, device) │
+│ ⚠️ Long S3 URLs create dense barcodes  │ 🟢 Short proxy URL creates clean code │
+└───────────────────────────────────────┴───────────────────────────────────────┘
+```
+
+> **Best Practice Rule**: Always use a **dynamic file qr code generator** for PDF documents. If a menu price changes or a brochure is revised, you can upload a new PDF version to your dashboard—the printed QR code on tables or flyers stays active and automatically serves the updated PDF!
+
+---
+
+## 3. PDF Optimization for Mobile Scanning Speed
+
+When mobile users scan a PDF barcode over a 4G/5G connection, an uncompressed 15 MB PDF takes 10+ seconds to load in Safari or Chrome, resulting in high bounce rates.
+
+### Golden Rules for Mobile PDF Optimization:
+1. **Compress Raster Images**: Downsample images inside the PDF to 150 DPI (suitable for mobile screens) instead of 300+ DPI print resolution.
+2. **Subset Embedded Fonts**: Include only the characters used in the document rather than embedding entire font families.
+3. **Linearization (Fast Web View)**: Enable "Fast Web View" when exporting PDFs. This restructures the PDF stream so mobile browsers display Page 1 immediately before the rest of the file finishes downloading!
+4. **Target File Size Limit**: Keep PDF file size **under 2.5 MB** for instant mobile loading.
+
+---
+
+## 4. TypeScript Implementation: Building a Cloud PDF QR Pipeline
+
+Below is a complete implementation in TypeScript that handles PDF uploads to S3-compatible storage (Cloudflare R2), generates a short dynamic redirect link, and exports a vector SVG QR code.
+
+### Step 4.1: Installation
+```bash
+npm install @aws-sdk/client-s3 qrcode
+npm install --save-dev typescript @types/node
+```
+
+### Step 4.2: PDF QR Service (`src/services/pdfQrService.ts`)
+
+```typescript
+import { S3Client, PutObjectCommand } from '@aws-sdk/client-s3';
+import QRCode from 'qrcode';
+
+// Initialize S3 / Cloudflare R2 Client
+const s3 = new S3Client({
+  region: 'auto',
+  endpoint: process.env.R2_ENDPOINT!,
+  credentials: {
+    accessKeyId: process.env.R2_ACCESS_KEY_ID!,
+    secretAccessKey: process.env.R2_SECRET_ACCESS_KEY!,
+  },
+});
+
+export interface PdfUploadOptions {
+  fileBuffer: Buffer;
+  originalFileName: string;
+  slug: string;
+}
+
+export class PdfQrService {
+  /**
+   * Uploads a PDF to S3/R2 storage and returns a vector SVG QR code.
+   */
+  public static async createPdfQr(options: PdfUploadOptions): Promise<{ cdnUrl: string; svgQr: string }> {
+    const { fileBuffer, originalFileName, slug } = options;
+
+    const fileKey = `documents/${Date.now()}_${originalFileName.replace(/[^a-z0-9.]/gi, '_')}`;
+
+    // 1. Upload PDF File to Cloud Storage Bucket
+    const uploadCommand = new PutObjectCommand({
+      Bucket: process.env.R2_BUCKET_NAME!,
+      Key: fileKey,
+      Body: fileBuffer,
+      ContentType: 'application/pdf',
+      ContentDisposition: 'inline', // Opens inside browser instead of forcing download
+      CacheControl: 'public, max-age=31536000',
+    });
+
+    await s3.send(uploadCommand);
+
+    const cdnUrl = `${process.env.CDN_BASE_URL}/${fileKey}`;
+
+    // 2. Generate Managed Short Redirect URL for Dynamic Editing
+    const proxyRedirectUrl = `https://www.qrmaster.net/r/doc/${slug}`;
+
+    // 3. Generate High-Quality Vector SVG Barcode
+    const svgQr = await QRCode.toString(proxyRedirectUrl, {
+      type: 'svg',
+      errorCorrectionLevel: 'M',
+      margin: 4,
+      color: { dark: '#0F172A', light: '#FFFFFF' },
+    });
+
+    return { cdnUrl, svgQr };
+  }
+}
+```
+
+---
+
+## 5. Frequently Asked Questions (FAQ)
+
+### Q1: How do I generate a free QR code for a PDF?
+Upload your PDF to a cloud host (such as Google Drive, Dropbox, or your website server), copy the share link, and paste it into a **pdf qr code generator free** tool like QR Master to generate a vector SVG code.
+
+### Q2: Can I change the PDF file after printing the QR code?
+Yes, provided you use a **file to qr code generator** with dynamic proxy links. You can upload a new PDF file to replace the old document in your dashboard without reprinting the physical QR code.
+
+### Q3: Why does my PDF QR code force a download instead of opening in Safari?
+This is controlled by the HTTP `Content-Disposition` header served by your cloud host. If set to `attachment`, the browser forces a download. Set `Content-Disposition: inline` so mobile browsers render the PDF directly on screen!
+
+---
+
+## Conclusion
+
+Using a **pdf qr code generator** allows businesses to replace bulky paper manuals and printed menus with instant digital experiences. By hosting PDFs on fast S3/R2 CDNs, setting `inline` view headers, and using dynamic redirect links, you deliver a seamless mobile document experience.
+
+To upload your PDF documents and generate custom vector QR codes with real-time scan analytics, check out [QR Master File & PDF QR Generator](https://www.qrmaster.net/blog/qr-code-restaurant-menu).

articles/devto-hashnode/devto-permanent-non-expiring-qr-code-guide.md

@@ -0,0 +1,173 @@
+---
+title: "QR Code Generator That Never Expires: The Truth About Hidden Limits & Permanent Free QR Codes"
+description: "A comprehensive guide to understanding why static QR codes never expire, avoiding third-party paywall traps, and building permanent barcodes for print & marketing campaigns."
+tags: webdev, security, marketing, tutorial
+keywords: qr code generator does not expire, permanent qr code generator, free forever qr code generator, qr code generator no subscription, free unlimited qr code generator, static qr code generator
+canonical_url: https://www.qrmaster.net/blog/static-vs-dynamic-qr-code
+---
+
+# QR Code Generator That Never Expires: The Truth About Hidden Limits & Permanent Free QR Codes
+
+Few things are more frustrating for a business owner or marketer than printing 500 brochures, packaging labels, or restaurant tabletop signs, only to discover two weeks later that the printed QR code has stopped working because a third-party generator placed the link behind a hidden subscription paywall.
+
+Every day, thousands of users search Google for phrases like:
+- *"qr code generator does not expire"*
+- *"permanent qr code generator"*
+- *"free forever qr code generator"*
+- *"qr code generator no subscription"*
+
+Why does this happen so frequently? Because many commercial QR tools use aggressive **freemium lock-in tactics**: they allow users to generate a "free" code, wait until the physical materials are printed and distributed, and then redirect the barcode to a paywall blocking screen until the user pays a monthly subscription fee.
+
+In this technical guide, we will unpack the computer science reality of how QR code expiration actually works, how to generate 100% permanent static QR codes that physically **cannot expire**, and how to choose a **permanent qr code generator** for your projects.
+
+---
+
+## 1. The Computer Science Reality: Can a QR Code Physically Expire?
+
+To understand expiration, you must understand where the data lives. A QR code is a 2D optical barcode that stores binary data in a physical matrix grid of dark and light modules.
+
+```
+┌───────────────────────────────────────┬───────────────────────────────────────┐
+│ Static QR Code (Permanent)            │ Dynamic Proxy QR Code                 │
+├───────────────────────────────────────┼───────────────────────────────────────┤
+│ Payload (URL, text, WiFi) is encoded │ Encodes a short proxy URL link        │
+│ directly into the matrix bits.        │ (e.g. https://service.com/r/123)     │
+│                                       │                                       │
+│ ❌ CANNOT EXPIRE physically           │ ⚠️ EXPIRES if proxy server is closed  │
+│ ❌ No server or account required       │ ⚠️ Requires active redirect service   │
+└───────────────────────────────────────┴───────────────────────────────────────┘
+```
+
+### Static QR Codes: 100% Expiration-Proof
+A static QR code generated by a **static qr code generator** encodes the raw text or URL directly into the matrix (using ISO/IEC 18004 Reed-Solomon encoding). 
+- Once printed on paper, metal, or plastic, the barcode is purely offline data—like a printed book or a 1D supermarket EAN barcode.
+- **There is no central server, database, or account attached.**
+- As long as the printed paper remains clean and readable, a camera reading a static QR code in 50 years will extract the exact same string. **A static QR code cannot expire.**
+
+### Dynamic Proxy QR Codes: Service-Dependent
+A dynamic QR code encodes a short managed proxy URL (e.g., `https://qr.domain.com/r/xyz123`) instead of the final website link.
+- When scanned, the phone contacts the proxy server, which looks up the target destination in a database and forwards the scanner via an HTTP 307 redirect.
+- If the proxy service goes out of business, deletes your account, or cancels your plan, the short proxy link returns a `404 Not Found` or payment wall.
+
+---
+
+## 2. Deconstructing the "Free QR Code Trap"
+
+Many online QR tools take advantage of user unfamiliarity with the difference between static and dynamic codes.
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                       The Freemium Lock-in Pipeline                          │
+├─────────────────────────────────────────────────────────────────────────────┤
+│ 1. User visits a "free qr generator" site to create a barcode for a flyer.  │
+│ 2. The site secretly generates a DYNAMIC proxy code instead of a static one.│
+│ 3. User prints 1,000 brochures with the printed barcode.                    │
+│ 4. 14 days later, the free trial ends. The proxy URL is redirected to:     │
+│    "This QR code has expired! Upgrade to PRO for $35/month to unlock."      │
+│ 5. User is forced to pay because reprinting 1,000 brochures costs more!    │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+### How to Detect the Trap BEFORE Printing:
+Before sending any QR code image to a commercial print shop, scan it with your smartphone camera and check the target URL preview on your screen:
+- **Direct Target URL** (e.g. `https://yourcompany.com/menu`): It is a **static permanent QR code**. It is 100% safe and will never expire!
+- **Obfuscated Third-Party URL** (e.g. `https://qr-gen-app.link/x79z`): It is a **dynamic proxy code**. If you are on a free trial, it WILL expire when the trial ends unless you pay!
+
+---
+
+## 3. Comparison: Static vs. Dynamic vs. Permanent Free Tools
+
+Let's compare your options when looking for a **free forever qr code generator**:
+
+```
+┌───────────────────────────┬───────────────────────────┬───────────────────────────┬───────────────────────────┐
+│ Feature                   │ Free Static QR Generator  │ Paid Dynamic QR Generator │ Predatory "Free" Generators│
+├───────────────────────────┼───────────────────────────┼───────────────────────────┼───────────────────────────┤
+│ Expiration Risk           │ 🟢 NEVER (0% Risk)        │ 🟡 Active Subscription    │ 🔴 Expires after 7-14 days│
+│ Requires Account/Sign-Up  │ 🟢 No                     │ 🟡 Yes                    │ 🔴 Yes                    │
+│ Link Editability          │ 🔴 No (Fixed Matrix)       │ 🟢 Yes (Update anytime)   │ 🟡 Only while paid        │
+│ Scan Analytics            │ 🔴 No                     │ 🟢 Yes (GA4 / Geo-IP)     │ 🟡 Behind paywall         │
+│ Vector SVG Download       │ 🟢 Yes                    │ 🟢 Yes                    │ 🔴 Blocked or Watermarked │
+└───────────────────────────┴───────────────────────────┴───────────────────────────┴───────────────────────────┘
+```
+
+---
+
+## 4. Programmatic Implementation: Building a Guaranteed Non-Expiring QR Generator
+
+To ensure your applications generate **permanent qr code generator** outputs programmatically, build an in-house static generator module in TypeScript.
+
+### Step 4.1: Installation
+```bash
+npm install qrcode
+npm install --save-dev typescript @types/node
+```
+
+### Step 4.2: Permanent Static QR Service (`src/services/permanentQrEngine.ts`)
+
+```typescript
+import QRCode from 'qrcode';
+
+export interface StaticQrConfig {
+  text: string;
+  errorCorrection?: 'L' | 'M' | 'Q' | 'H';
+  colorDark?: string;
+  colorLight?: string;
+}
+
+export class PermanentQrEngine {
+  /**
+   * Generates a 100% static, non-expiring vector SVG QR code.
+   * Direct payload encoding ensures zero third-party server dependency.
+   */
+  public static async createPermanentSvg(config: StaticQrConfig): Promise<string> {
+    const {
+      text,
+      errorCorrection = 'M',
+      colorDark = '#000000',
+      colorLight = '#FFFFFF',
+    } = config;
+
+    if (!text || text.trim().length === 0) {
+      throw new Error('Payload text or URL is required to generate a static QR code.');
+    }
+
+    try {
+      const svgString = await QRCode.toString(text, {
+        type: 'svg',
+        errorCorrectionLevel: errorCorrection,
+        margin: 4,
+        color: {
+          dark: colorDark,
+          light: colorLight,
+        },
+      });
+
+      return svgString;
+    } catch (err) {
+      throw new Error(`Static QR Generation Error: ${(err as Error).message}`);
+    }
+  }
+}
+```
+
+---
+
+## 5. Frequently Asked Questions (FAQ)
+
+### Q1: Is there a free unlimited qr code generator that never expires?
+**Yes.** Any **static qr code generator** that encodes your destination URL directly into the matrix creates a permanent barcode that never expires. Static codes require no account or subscription.
+
+### Q2: What happens if the domain of a static QR code changes?
+Because a static code hardcodes the URL into the matrix, if your website domain changes (e.g. from `site.com` to `newsite.com`), the static code will still point to `site.com`. You can fix this by setting up a domain-level 301 redirect on your web server from your old domain to your new domain!
+
+### Q3: How do I get a permanent QR code with a logo?
+Use a **custom qr code generator** enforcing Reed-Solomon **Level H** error correction. This allows you to embed a brand logo in the center while keeping the static matrix 100% permanent.
+
+---
+
+## Conclusion
+
+Understanding the fundamental technical difference between static matrix encoding and dynamic proxy redirects protects you from predatory subscription paywalls. For permanent print campaigns where URLs are stable, a **permanent qr code generator** using static SVG output is the safest, zero-cost choice.
+
+To generate 100% permanent, non-expiring static QR codes with zero ads, zero watermarks, and high-resolution vector SVG downloads, check out [QR Master Free Permanent QR Code Generator](https://www.qrmaster.net/blog/static-vs-dynamic-qr-code).

articles/devto-hashnode/devto-quishing-threat-detection-pipeline.md

@@ -0,0 +1,244 @@
+---
+title: "Preventing Quishing (QR Phishing): Building an Automated Threat Inspection Pipeline"
+description: "A deep cybersecurity developer guide to understanding Quishing attack vectors, qr code security, building a secure qr code generator, and verifying domain SSL certificates in Node.js."
+tags: security, cybersecurity, nodejs, webdev
+keywords: qr code security, secure qr code generator, safe qr code generator, qr code security best practices, quishing prevention
+canonical_url: https://www.qrmaster.net/blog/qr-code-security
+---
+
+# Preventing Quishing (QR Phishing): Building an Automated Threat Inspection Pipeline
+
+As QR codes become standard infrastructure for payments, Wi-Fi connections, and physical login flows, **qr code security** has become a top priority. Cybercriminals have adopted **Quishing** (QR Phishing)—the act of replacing physical QR codes on parking meters, posters, or restaurant tables with malicious codes that redirect victims to credential-harvesting phishing portals.
+
+Because security scanners in email gateways and web browsers cannot inspect physical paper stickers, Quishing bypasses traditional perimeter defenses.
+
+For SaaS platforms building a **secure qr code generator** that allows users to create dynamic redirects, preventing malicious actors from turning your platform into a phishing proxy is a major AppSec priority.
+
+In this cybersecurity guide, we will analyze Quishing attack mechanics and build an automated threat inspection pipeline in TypeScript to ensure your platform remains a **safe qr code generator**.
+
+---
+
+## 1. Deconstructing the Quishing Attack Vector
+
+Unlike standard phishing emails containing suspicious links like `http://paypal-security-login.xyz`, Quishing exploits the visual obscurity of 2D barcodes. Humans cannot read a QR matrix with their eyes; they must scan it first to reveal the URL.
+
+```
+┌────────────────────────────────────────┐
+│ Attacker Swaps Physical QR Sticker     │
+└───────────────────┬────────────────────┘
+                    │
+                    ▼
+┌────────────────────────────────────────┐
+│ User Scans QR Code with Smartphone     │
+└───────────────────┬────────────────────┘
+                    │
+                    ▼
+┌────────────────────────────────────────┐
+│ Redirect Chain (Multi-Hop Proxy)      │
+│ http://short.link ➔ http://eval.site  │
+│ ➔ https://fake-bank-login.com          │
+└───────────────────┬────────────────────┘
+                    │
+                    ▼
+┌────────────────────────────────────────┐
+│ Victim Enters Password / MFA Credentials│
+└───────────────────┴────────────────────┘
+```
+
+### Common Evasion Tactics in QR Code Security:
+1. **Multi-Hop Redirections**: Using 3 or 4 chained shorteners (`bit.ly` $\to$ `tinyurl` $\to$ malicious domain) to obfuscate final destination.
+2. **Time-Gated Payload Switching**: Pointing the QR code to a benign site during initial review, then updating the target to a phishing page after printing.
+3. **Geo-Targeted Cloaking**: Serving a harmless homepage to cloud inspection bots (AWS/GCP IPs), but redirecting mobile device user-agents to phishing kits.
+
+---
+
+## 2. Architecture of a Secure QR Code Generator Pipeline
+
+When a user submits a destination URL in your **secure qr code generator**, it must pass through an automated inspection pipeline prior to link activation:
+
+```
+User Submitted URL
+      │
+      ▼
+┌────────────────────────────────────────┐
+│ 1. Syntax & Open Redirect Sanitizer    │
+└───────────────────┬────────────────────┘
+                    │
+                    ▼
+┌────────────────────────────────────────┐
+│ 2. Domain Age & Whois Verification     │
+└───────────────────┬────────────────────┘
+                    │
+                    ▼
+┌────────────────────────────────────────┐
+│ 3. Google Safe Browsing API Check      │
+└───────────────────┬────────────────────┘
+                    │
+                    ▼
+┌────────────────────────────────────────┐
+│ 4. Multi-Hop Redirect Trace & Headless │
+│    DOM Inspection (Puppeteer)          │
+└───────────────────┬────────────────────┘
+                    │
+              Pass / Fail Flag
+```
+
+---
+
+## 3. Step-by-Step Implementation in TypeScript
+
+Let's build a threat scanner module in TypeScript for a **safe qr code generator**.
+
+### Step 3.1: Install Dependencies
+
+```bash
+npm install axios google-auth-library valid-url tldts
+npm install --save-dev typescript @types/node
+```
+
+### Step 3.2: Threat Scanner Service (`src/services/threatScanner.ts`)
+
+```typescript
+import axios from 'axios';
+import { parse } from 'tldts';
+
+export interface ThreatScanResult {
+  isSafe: boolean;
+  finalDestination: string;
+  redirectChain: string[];
+  threatType?: string;
+  reason?: string;
+}
+
+export class ThreatScanner {
+  private static SAFE_BROWSING_API_KEY = process.env.GOOGLE_SAFE_BROWSING_KEY || '';
+
+  /**
+   * Runs complete QR code security inspection pipeline on a submitted URL.
+   */
+  public static async inspectUrl(initialUrl: string): Promise<ThreatScanResult> {
+    const redirectChain: string[] = [initialUrl];
+
+    // 1. Basic Protocol & Syntax Validation
+    if (!initialUrl.startsWith('http://') && !initialUrl.startsWith('https://')) {
+      return {
+        isSafe: false,
+        finalDestination: initialUrl,
+        redirectChain,
+        reason: 'Invalid protocol. Only HTTP and HTTPS are permitted.',
+      };
+    }
+
+    // 2. Prevent IP-based URLs (e.g. http://192.168.1.1 or http://169.254.169.254 AWS Metadata attack)
+    const domainInfo = parse(initialUrl);
+    if (!domainInfo.domain && !domainInfo.isIp) {
+      return {
+        isSafe: false,
+        finalDestination: initialUrl,
+        redirectChain,
+        reason: 'Invalid or missing domain name.',
+      };
+    }
+
+    if (domainInfo.isIp) {
+      return {
+        isSafe: false,
+        finalDestination: initialUrl,
+        redirectChain,
+        reason: 'Direct IP address destinations are prohibited to prevent SSFR attacks.',
+      };
+    }
+
+    // 3. Trace Full Redirect Chain (Max 5 Hops)
+    let currentUrl = initialUrl;
+    try {
+      let hops = 0;
+      while (hops < 5) {
+        const response = await axios.head(currentUrl, {
+          maxRedirects: 0,
+          validateStatus: (status) => status >= 200 && status < 400,
+          timeout: 4000,
+          headers: {
+            'User-Agent': 'Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X) AppleWebKit/605.1.15',
+          },
+        });
+
+        if (response.status >= 300 && response.status < 400 && response.headers.location) {
+          const nextUrl = new URL(response.headers.location, currentUrl).href;
+          redirectChain.push(nextUrl);
+          currentUrl = nextUrl;
+          hops++;
+        } else {
+          break; // Terminal destination reached
+        }
+      }
+    } catch (err) {
+      console.warn(`[ThreatScanner] Warning: Redirect trace halted on ${currentUrl}`);
+    }
+
+    const finalDestination = currentUrl;
+
+    // 4. Query Google Safe Browsing API v4
+    if (this.SAFE_BROWSING_API_KEY) {
+      const isMalicious = await this.checkGoogleSafeBrowsing(finalDestination);
+      if (isMalicious) {
+        return {
+          isSafe: false,
+          finalDestination,
+          redirectChain,
+          threatType: 'MALWARE_OR_PHISHING',
+          reason: 'Destination flagged by Google Safe Browsing security database.',
+        };
+      }
+    }
+
+    return {
+      isSafe: true,
+      finalDestination,
+      redirectChain,
+    };
+  }
+
+  private static async checkGoogleSafeBrowsing(targetUrl: string): Promise<boolean> {
+    try {
+      const endpoint = `https://safebrowsing.googleapis.com/v4/threatMatches:find?key=${this.SAFE_BROWSING_API_KEY}`;
+      const payload = {
+        client: {
+          clientId: 'qrmaster-security-scanner',
+          clientVersion: '1.0.0',
+        },
+        threatInfo: {
+          threatTypes: ['MALWARE', 'SOCIAL_ENGINEERING', 'UNWANTED_SOFTWARE', 'POTENTIALLY_HARMFUL_APPLICATION'],
+          platformTypes: ['ANY_PLATFORM'],
+          threatEntryTypes: ['URL'],
+          threatEntries: [{ url: targetUrl }],
+        },
+      };
+
+      const response = await axios.post(endpoint, payload);
+      return !!(response.data && response.data.matches && response.data.matches.length > 0);
+    } catch (err) {
+      console.error('[SafeBrowsing API Error]:', (err as Error).message);
+      return false;
+    }
+  }
+}
+```
+
+---
+
+## 4. Best Practices for QR Code Security
+
+Implementing automated URL scanning is only step one. Enforce these operational safeguards across a **secure qr code generator**:
+
+1. **Mandatory Custom Domain Support**: Allow enterprise users to brand dynamic QR links with their own custom domain (e.g., `qr.brand.com`) instead of sharing a generic domain pool. This isolates reputation.
+2. **Real-Time URL Re-Scanning**: Re-run threat scans periodically (e.g., every 24 hours) on active dynamic QR codes to catch time-gated payload switching attacks.
+3. **Phishing Report Abuse Button**: Include a small "Report Abuse" link on interstitial preview pages so users can flag suspicious links immediately.
+
+---
+
+## Conclusion
+
+Quishing poses a real threat to digital-to-physical user trust. By implementing automated URL syntax sanitization, multi-hop redirect tracing, and Google Safe Browsing integration, developers can build a **secure qr code generator** that protects platforms and users from malicious QR phishing attacks.
+
+To learn more about **qr code security**, SSL encryption, and custom domain isolation, check out [QR Master Security Best Practices](https://www.qrmaster.net/blog/qr-code-security).

articles/devto-hashnode/devto-reed-solomon-qr-math-logo-embedding.md

@@ -0,0 +1,190 @@
+---
+title: "Understanding Reed-Solomon Error Correction Math & Safe Logo Embedding in QR Codes"
+description: "A deep computer science exploration of Galois Field GF(2^8) math in Reed-Solomon error correction and building a custom QR code generator to embed brand logos."
+tags: math, computer-science, graphics, algorithm
+keywords: custom qr code generator, free custom qr code generator, qr code designer, branded qr code generator, custom qr code, create custom qr code
+canonical_url: https://www.qrmaster.net/blog/custom-qr-code-design
+---
+
+# Understanding Reed-Solomon Error Correction Math & Safe Logo Embedding in QR Codes
+
+Many developers assume QR codes are fragile grids where changing a single black module into white destroys the entire payload. In reality, QR codes generated by a **custom qr code generator** are engineered with **Reed-Solomon Error Correction**, a powerful algebraic coding scheme that allows up to 30% of the physical barcode to be completely destroyed, stained, or covered by a company logo while remaining 100% scannable.
+
+However, naive logo overlays—such as slapping a large PNG graphic directly into the center of a QR code using image editing software—frequently cause scan failures in low-light or low-resolution camera sensors.
+
+In this article, we will unpack the computer science math behind Galois Fields $GF(2^8)$, Reed-Solomon error correction polynomials, and how a **branded qr code generator** computes safe logo placement margins without corrupting the barcode matrix.
+
+---
+
+## 1. The Computer Science Math of Reed-Solomon Codes
+
+Reed-Solomon error correction in a **custom qr code generator** operates by representing data as polynomial coefficients over a finite field (also known as a **Galois Field**, denoted as $GF(2^8)$).
+
+### Finite Field Arithmetic: $GF(2^8)$
+Computers store data in bytes ($8\text{ bits} = 256$ distinct values). In $GF(2^8)$, arithmetic operations (addition, multiplication) are defined such that results never overflow 8 bits (values stay strictly between $0$ and $255$).
+
+- **Addition & Subtraction**: In $GF(2^8)$, addition is equivalent to bitwise XOR (`^` in JavaScript/C++):
+  $$A + B = A \oplus B$$
+- **Multiplication**: Multiplication uses a generator polynomial (typically $x^8 + x^4 + x^3 + x^2 + 1$, corresponding to the primitive decimal polynomial $285$).
+
+### The Generator Polynomial
+To generate $R$ error correction codewords for a data message polynomial $M(x)$, the message is multiplied by $x^R$ and divided by a generator polynomial $G(x)$:
+
+$$G(x) = \prod_{i=0}^{R-1} (x - \alpha^i)$$
+
+The remainder of this polynomial division forms the **Error Correction Codewords** appended to the end of the QR payload.
+
+When a camera reads a damaged matrix from a **qr code designer**:
+1. It evaluates the polynomial to find **Syndromes** ($S_1, S_2, \dots, S_R$).
+2. If all syndromes equal $0$, the matrix has zero errors.
+3. If syndromes are non-zero, algorithms like **Berlekamp-Massey** or **Chien Search** locate the exact error positions and correct the inverted bit values automatically!
+
+---
+
+## 2. Error Correction Capacity Levels in QR Codes
+
+The ISO/IEC 18004 specification defines four error correction levels in a **custom qr code generator free** engine, determining how many redundant codewords are added to the matrix:
+
+```
+┌─────────────────────────┬──────────────────────┬───────────────────────────────┐
+│ Error Correction Level  │ Recovery Capacity    │ Max Logo Coverage Budget      │
+├─────────────────────────┼──────────────────────┼───────────────────────────────┤
+│ Level L (Low)           │ ~7% of codewords     │ Dangerous (Max < 4% surface)  │
+│ Level M (Medium)        │ ~15% of codewords    │ Low (Max ~8% surface)         │
+│ Level Q (Quartile)      │ ~25% of codewords    │ Moderate (Max ~15% surface)   │
+│ Level H (High)          │ ~30% of codewords    │ High (Max ~22-25% surface)    │
+└─────────────────────────┴──────────────────────┴───────────────────────────────┘
+```
+
+When you place a logo over the center of a QR code using a **custom qr code generator**, you are intentionally destroying codewords. Therefore:
+> **Golden Rule**: Always set Error Correction Level to **Level H (High)** whenever embedding logos or custom artwork.
+
+---
+
+## 3. Mathematical Rules for Safe Logo Embedding
+
+Overlaying a logo is not just about keeping the covered area under 30%. Camera scanners face environmental degradation (glare, shadows, camera blur, dirty lenses). If your logo consumes 28% of the error correction budget, a slight lens smudge will push total error past 30%, causing scan failure!
+
+### Rule 1: Never Touch the Three Finder Patterns
+The three large $7 \times 7$ square finder patterns in the top-left, top-right, and bottom-left corners are sacrosanct. If a camera cannot detect all three finder patterns, it cannot determine orientation or matrix dimensions, and decoding aborts instantly before Reed-Solomon math is even attempted!
+
+### Rule 2: Keep Logo Surface Area Below 20%
+To ensure reliable scanning across all smartphone models and lighting conditions in your **custom qr code designer**, limit your logo footprint to **15% to 20% of the total matrix area**.
+
+$$\text{Max Logo Dimension (px)} = \text{Matrix Width (px)} \times \sqrt{0.20} \approx \text{Matrix Width} \times 0.44$$
+
+### Rule 3: Add a Protective Padding Zone (Quiet Boundary)
+Logos should never merge directly into surrounding QR modules. A 2-module wide solid background padding around the logo prevents module misinterpretation.
+
+---
+
+## 4. Programmatic Implementation: Merging Logo into QR SVG with Node.js
+
+Below is a Node.js TypeScript module that programmatically computes matrix dimensions, generates a Level H QR SVG, embeds a centered vector logo, and applies a protective background mask for a **create custom qr code** service.
+
+### Step 4.1: Code Implementation (`src/services/customQrBuilder.ts`)
+
+```typescript
+import QRCode from 'qrcode';
+
+export interface LogoEmbedOptions {
+  text: string;
+  logoSvgContent: string; // Raw SVG string of logo (e.g. <path .../>)
+  logoWidthPercent?: number; // Target logo width as percentage of matrix (default: 20%)
+  colorDark?: string;
+  colorLight?: string;
+}
+
+export class CustomQRBuilder {
+  /**
+   * Generates a combined SVG string with centered logo and protective padding.
+   */
+  public static async generateLogoQR(options: LogoEmbedOptions): Promise<string> {
+    const {
+      text,
+      logoSvgContent,
+      logoWidthPercent = 20,
+      colorDark = '#090D16',
+      colorLight = '#FFFFFF',
+    } = options;
+
+    // Enforce Level H (30% error tolerance)
+    const qrMatrix = QRCode.create(text, { errorCorrectionLevel: 'H' });
+    const moduleCount = qrMatrix.modules.size; // Total modules per side (e.g., 29x29)
+
+    const size = 500; // SVG canvas size in pixels
+    const margin = 4; // Module padding
+    const totalModules = moduleCount + margin * 2;
+    const moduleSizePx = size / totalModules;
+
+    // Compute Logo Pixel Bounds
+    const maxLogoPercent = Math.min(Math.max(logoWidthPercent, 10), 22);
+    const logoSizePx = size * (maxLogoPercent / 100);
+    const logoOffset = (size - logoSizePx) / 2;
+
+    // Protective padding around logo (in pixels)
+    const paddingPx = moduleSizePx * 1.5;
+    const padSizePx = logoSizePx + paddingPx * 2;
+    const padOffset = (size - padSizePx) / 2;
+
+    // 1. Generate Base QR SVG Paths
+    const rawSvg = await QRCode.toString(text, {
+      type: 'svg',
+      errorCorrectionLevel: 'H',
+      margin,
+      color: { dark: colorDark, light: colorLight },
+    });
+
+    // 2. Extract SVG Inner Content (Paths)
+    const svgInnerMatch = rawSvg.match(/<svg[^>]*>([\s\S]*?)<\/svg>/i);
+    const baseContent = svgInnerMatch ? svgInnerMatch[1] : '';
+
+    // 3. Construct Final Composite SVG with Protective White Rect + Logo
+    const compositeSvg = `
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 ${size} ${size}" width="${size}" height="${size}">
+  <!-- Base QR Matrix -->
+  ${baseContent}
+
+  <!-- Protective Quiet Mask behind Logo -->
+  <rect 
+    x="${padOffset.toFixed(2)}" 
+    y="${padOffset.toFixed(2)}" 
+    width="${padSizePx.toFixed(2)}" 
+    height="${padSizePx.toFixed(2)}" 
+    fill="${colorLight}" 
+    rx="${moduleSizePx.toFixed(2)}" 
+  />
+
+  <!-- Embedded Centered Brand Logo -->
+  <g transform="translate(${logoOffset.toFixed(2)}, ${logoOffset.toFixed(2)}) scale(${(logoSizePx / 100).toFixed(4)})">
+    ${logoSvgContent}
+  </g>
+</svg>`.trim();
+
+    return compositeSvg;
+  }
+}
+```
+
+---
+
+## 5. Verification & Scannability Testing Checklist
+
+Before deploying a **custom qr code generator** with embedded logos, run through this automated and manual test matrix:
+
+```
+[ ] Enforce Level H Error Correction in code config.
+[ ] Verify logo consumes ≤ 20% total matrix area.
+[ ] Confirm finder patterns (3 corner squares) are 100% un-obscured.
+[ ] Test scan under low-light conditions (phone screen at 20% brightness).
+[ ] Test scan at 45-degree angled perspective.
+[ ] Test scan using both native iOS Camera App and Android Google Lens.
+```
+
+---
+
+## Conclusion
+
+Reed-Solomon error correction is an engineering marvel that makes a **custom qr code generator** with logo embedding possible. By understanding finite field mathematics, enforcing Level H error recovery, and restricting logo surface area to 20%, developers can build stunning, branded QR codes without sacrificing scan reliability.
+
+To build pixel-perfect custom QR codes with verified scannability, vector logo uploads, and real-time scan metrics, try [QR Master Custom QR Code Generator](https://www.qrmaster.net/custom-qr-code-generator).

articles/devto-hashnode/devto-vcard-rfc-spec-barcode-payloads.md

@@ -0,0 +1,202 @@
+---
+title: "Parsing vCard (RFC 2426/6350) Specifications & Optimizing 2D Barcode Payload Limits"
+description: "A deep technical guide to the vCard data specification standard, character encodings, payload byte limits in a vcard qr code generator, and building a qr code generator for business cards."
+tags: webdev, javascript, typescript, standards
+keywords: vcard qr code generator, free vcard qr code generator, qr code generator business card, free qr code generator for business cards, qr code business card free, qr code generator contact card
+canonical_url: https://www.qrmaster.net/blog/vcard-qr-code-generator
+---
+
+# Parsing vCard (RFC 2426/6350) Specifications & Optimizing 2D Barcode Payload Limits
+
+Digital business cards powered by a **vcard qr code generator** allow users to instantly save contact details—name, phone number, email, website, job title, and social links—directly into an iOS or Android address book with a single camera scan.
+
+Behind the scenes, building a **qr code generator for business cards** relies on the **vCard specification** (RFC 2426 for vCard 3.0 and RFC 6350 for vCard 4.0).
+
+However, many developers run into a major issue: when users paste extensive bio notes, social media links, profile photos, or secondary addresses into a **free qr code generator for business cards**, the QR matrix becomes extremely dense (Version 25+ with over 1,500 modules). This results in a tiny, cluttered barcode that fails to scan on mobile cameras.
+
+In this developer guide, we will analyze the vCard specification RFC standards, calculate maximum 2D barcode payload capacity, and write a TypeScript contact card optimizer that compresses vCard data for instant scannability.
+
+---
+
+## 1. Breakdown of the vCard Specification Standards
+
+A vCard used in a **vcard qr code generator** is a plain-text MIME directory format storing contact details line-by-line using `KEY:VALUE` properties.
+
+### vCard 3.0 (RFC 2426) vs. vCard 4.0 (RFC 6350)
+
+```
+┌───────────────────────────┬─────────────────────────────┬─────────────────────────────┐
+│ Feature                   │ vCard 3.0 (RFC 2426)        │ vCard 4.0 (RFC 6350)        │
+├───────────────────────────┼─────────────────────────────┼─────────────────────────────┤
+│ Mobile OS Compatibility   │ 100% Universal (iOS & Android)│ ~85% (Fails on older OS)    │
+│ Character Encoding         │ UTF-8 / Quoted-Printable    │ Mandatory UTF-8             │
+│ Preferred Recommendation │ ✅ BEST for QR Code Barcodes │ ⚠️ Use with caution        │
+└───────────────────────────┴─────────────────────────────┴─────────────────────────────┘
+```
+
+> **Important Developer Note**: Always target **vCard 3.0** when building a **free vcard qr code generator** that embeds data directly into static QR codes. Native camera scanner parsers on older Android versions and non-standard camera apps frequently fail to recognize vCard 4.0 properties.
+
+### Standard vCard 3.0 Structure Example:
+
+```text
+BEGIN:VCARD
+VERSION:3.0
+N:Knuth;Timo;;;
+FN:Timo Knuth
+ORG:QR Master
+TITLE:Lead Software Architect
+TEL;TYPE=CELL,VOICE:+15550192834
+EMAIL;TYPE=INTERNET,PREF:timo@qrmaster.net
+URL:https://www.qrmaster.net
+ADR;TYPE=WORK:;;100 Tech Way;San Francisco;CA;94107;USA
+END:VCARD
+```
+
+---
+
+## 2. QR Code Capacity Limits & The Matrix Density Problem
+
+QR codes have 40 discrete matrix sizes (Version 1 to Version 40). As byte payload increases, matrix size grows exponentially:
+
+```
+┌─────────┬──────────────┬─────────────────────────┬────────────────────────────────┐
+│ Version │ Matrix Grid  │ Max Bytes (Level M)     │ Scan Usability on Business Cards│
+├─────────┼──────────────┼─────────────────────────┼────────────────────────────────┤
+│ Ver 3   │ 29 x 29      │ 53 bytes                │ Super Fast (Instant)           │
+│ Ver 6   │ 41 x 41      │ 134 bytes               │ Excellent                      │
+│ Ver 11  │ 61 x 61      │ 321 bytes               │ Good (Standard vCard max)      │
+│ Ver 20  │ 97 x 97      │ 858 bytes               │ Sluggish / Requires Closeup    │
+│ Ver 40  │ 177 x 177    │ 2,331 bytes             │ Fails on printed cards         │
+└─────────┴──────────────┴─────────────────────────┴────────────────────────────────┘
+```
+
+### The Physical Print Limit Rule for Business Cards
+On a standard $85\text{ mm} \times 55\text{ mm}$ printed business card, a QR code created with a **qr code business card free** generator printed smaller than $20\text{ mm} \times 20\text{ mm}$ should **never exceed Version 10 (600 bytes)**. Encoding full profile photos (BASE64 strings) directly into a static vCard QR code requires over 5,000 bytes, which exceeds maximum QR capacity entirely!
+
+---
+
+## 3. Building a TypeScript vCard Optimizer & Sanitizer
+
+To guarantee fast scans, we can build a utility class in TypeScript for a **qr code generator contact card** that formats vCard properties, strips unnecessary whitespace, sanitizes multi-byte characters, and compresses payload size.
+
+### Step 3.1: vCard Builder Implementation (`src/services/vcardOptimizer.ts`)
+
+```typescript
+export interface ContactFields {
+  firstName: string;
+  lastName: string;
+  organization?: string;
+  title?: string;
+  phoneCell?: string;
+  phoneWork?: string;
+  email?: string;
+  url?: string;
+  city?: string;
+  country?: string;
+}
+
+export class VCardOptimizer {
+  /**
+   * Generates a clean, byte-optimized vCard 3.0 string for a vcard qr code generator.
+   */
+  public static buildOptimizedVCard(fields: ContactFields): string {
+    const lines: string[] = [];
+
+    // Header
+    lines.push('BEGIN:VCARD');
+    lines.push('VERSION:3.0');
+
+    // Structured Name (N:LastName;FirstName;;;)
+    const last = this.cleanText(fields.lastName || '');
+    const first = this.cleanText(fields.firstName || '');
+    lines.push(`N:${last};${first};;;`);
+
+    // Formatted Name (FN:FirstName LastName)
+    const fullName = `${first} ${last}`.trim();
+    lines.push(`FN:${fullName}`);
+
+    // Optional Fields (Only append if non-empty to conserve bytes)
+    if (fields.organization) {
+      lines.push(`ORG:${this.cleanText(fields.organization)}`);
+    }
+
+    if (fields.title) {
+      lines.push(`TITLE:${this.cleanText(fields.title)}`);
+    }
+
+    if (fields.phoneCell) {
+      lines.push(`TEL;TYPE=CELL:${this.sanitizePhone(fields.phoneCell)}`);
+    }
+
+    if (fields.phoneWork) {
+      lines.push(`TEL;TYPE=WORK:${this.sanitizePhone(fields.phoneWork)}`);
+    }
+
+    if (fields.email) {
+      lines.push(`EMAIL;TYPE=INTERNET:${fields.email.trim()}`);
+    }
+
+    if (fields.url) {
+      lines.push(`URL:${fields.url.trim()}`);
+    }
+
+    if (fields.city || fields.country) {
+      const city = this.cleanText(fields.city || '');
+      const country = this.cleanText(fields.country || '');
+      lines.push(`ADR;TYPE=WORK:;;;${city};;;${country}`);
+    }
+
+    // Footer
+    lines.push('END:VCARD');
+
+    // Join with standard CRLF (\r\n) as specified by RFC 2426
+    return lines.join('\r\n');
+  }
+
+  private static sanitizePhone(phone: string): string {
+    return phone.replace(/[^\d+]/g, '');
+  }
+
+  private static cleanText(str: string): string {
+    return str
+      .trim()
+      .replace(/\\/g, '\\\\')
+      .replace(/;/g, '\\;')
+      .replace(/,/g, '\\,')
+      .replace(/\n/g, ' ');
+  }
+
+  public static getByteSize(vcardString: string): number {
+    return Buffer.byteLength(vcardString, 'utf8');
+  }
+}
+```
+
+---
+
+## 4. Static vCard vs. Dynamic Business Card Landing Pages
+
+When building a **qr code generator for business cards**, developers face a choice between two architectures:
+
+```
+┌───────────────────────────────────────┬───────────────────────────────────────┐
+│ Static vCard QR Code                  │ Dynamic Business Card Landing Page     │
+├───────────────────────────────────────┼───────────────────────────────────────┤
+│ Data stored directly inside QR matrix │ Encodes short URL (e.g. /c/timo)      │
+│ Works 100% offline (no internet needed)│ Requires internet connection          │
+│ Contact data CANNOT be edited         │ Contact data can be updated anytime   │
+│ Limited fields (~300 bytes max)       │ Unlimited fields, photo & social links│
+└───────────────────────────────────────┴───────────────────────────────────────┘
+```
+
+### Strategic Recommendation:
+- Use **Static vCard 3.0** when working offline or when data privacy is paramount (no external server dependency).
+- Use **Dynamic Contact Landing Pages** when you need click analytics, social links, profile photos, or the ability to update details without reprinting cards.
+
+---
+
+## Conclusion
+
+Understanding the vCard RFC 2426 specification and respecting barcode payload byte limits is essential for building a **vcard qr code generator**. By stripping non-essential formatting and targeting vCard 3.0, you ensure instant contact saves on both iOS and Android devices.
+
+To build interactive dynamic business card QR codes with profile picture uploads, social links, and real-time contact save tracking, check out [QR Master vCard QR Code Generator](https://www.qrmaster.net/blog/vcard-qr-code-generator).

articles/devto-hashnode/devto-wifi-qr-code-guest-access-guide.md

@@ -0,0 +1,199 @@
+---
+title: "How to Create a Free Wi-Fi QR Code: The Complete Guide for Cafes, Hotels & Home Networks"
+description: "A complete step-by-step technical guide to generating Wi-Fi QR codes, encoding WPA2/WPA3 credentials, avoiding security bugs, and printing tabletop stand graphics for guest access."
+tags: networking, mobile, webdev, tutorial
+keywords: qr wifi, wifi qr code generator, print qr code, free static qr code generator, print a qr code, wifi qr code, create wifi qr code
+canonical_url: https://www.qrmaster.net/blog/wifi-qr-code-generator
+---
+
+# How to Create a Free Wi-Fi QR Code: The Complete Guide for Cafes, Hotels & Home Networks
+
+Tired of spelling out long, complex Wi-Fi passwords to restaurant guests, Airbnb visitors, hotel clients, or home friends?
+
+A **qr wifi** code allows anyone with an iPhone or Android device to point their native camera app at a printed barcode and tap a single banner button to automatically join the network—without typing a single character.
+
+In your Google Keyword Planner data, search queries for `qr wifi` and `print qr code` have exploded with **+900% annual growth**.
+
+In this technical guide, we will walk through the step-by-step process of using a **wifi qr code generator**, explaining string syntax, security protocols (WPA2/WPA3), character escaping rules, and downloading vector SVG graphics to **print a qr code** for physical tabletop stands.
+
+---
+
+## 1. How a Wi-Fi QR Code Works Behind the Scenes
+
+Unlike web URLs that open Safari or Chrome, a Wi-Fi QR code uses a specialized, offline MIME payload format standardized by ZXing.
+
+When a mobile device camera scans a **wifi qr code**, the operating system recognizes the `WIFI:` protocol prefix and hands off the credentials directly to the OS network manager (iOS Wi-Fi Settings / Android Network Manager).
+
+```
+┌────────────────────────────────────────┐
+│ Camera Scans WIFI: Payload String      │
+└───────────────────┬────────────────────┘
+                    │
+                    ▼
+┌────────────────────────────────────────┐
+│ OS Displays Modal Banner:              │
+│ "Join 'Cafe_Guest' Wi-Fi Network?"     │
+└───────────────────┬────────────────────┘
+                    │
+                    ▼
+┌────────────────────────────────────────┐
+│ User Taps Banner ➔ One-Tap Auto Connect│
+└────────────────────────────────────────┘
+```
+
+Because a Wi-Fi code stores network credentials directly in the matrix, it uses a **free static qr code generator**. It operates 100% offline—meaning guests can scan and connect even when cellular data coverage is unavailable inside a basement venue!
+
+---
+
+## 2. Step-by-Step Guide to Creating a Wi-Fi QR Code
+
+### Step 1: Collect Your Exact Network Credentials
+To generate a valid code, gather three exact values from your router or network admin panel:
+1. **Network Name (SSID)**: The exact case-sensitive name broadcasted by your router (e.g., `Lounge_Guest_5G`).
+2. **Password (Pre-shared Key)**: The exact Wi-Fi password.
+3. **Security Encryption Type**:
+   - `WPA/WPA2/WPA3` (Standard for ~98% of modern home and business routers).
+   - `WEP` (Legacy encryption).
+   - `Open / None` (Unencrypted public networks).
+
+---
+
+### Step 2: Format the String with Proper Escaping
+
+If your SSID or Wi-Fi password contains special characters like colons (`:`), semicolons (`;`), backslashes (`\`), or commas (`,`), you must escape them with a backslash.
+
+#### Protocol Syntax Template:
+```text
+WIFI:S:<SSID>;T:<SECURITY>;P:<PASSWORD>;;
+```
+
+#### Example Formats:
+
+```text
+# Standard WPA2/WPA3 Home Network
+WIFI:S:MyHomeWiFi;T:WPA;P:SecretPass2026;;
+
+# Cafe Network with a Semicolon in the SSID ("Cafe;Lounge")
+WIFI:S:Cafe\;Lounge;T:WPA;P:coffee123;;
+
+# Free Open Public Network (No Password)
+WIFI:S:Airport_Free_WiFi;T:nopass;;
+```
+
+> **Crucial Rule**: Notice the two semicolons (`;;`) at the end of the string. Leaving out the double semicolon will cause iOS Camera apps to fail to parse the barcode!
+
+---
+
+## 3. How to Print a QR Code for Physical Venues
+
+Generating the digital image is only half the battle. When you **print a qr code** for physical tabletop signs or wall posters, follow these print specifications:
+
+```
+┌───────────────────────────┬───────────────────────────────────────────┐
+│ Print Guideline           │ Recommended Specification                 │
+├───────────────────────────┼───────────────────────────────────────────┤
+│ File Export Format        │ Vector SVG (Scalable, non-pixelated)      │
+│ Minimum Physical Size     │ 3 cm x 3 cm (1.2 in x 1.2 in)             │
+│ Quiet Zone Margin         │ At least 4 modules of whitespace border   │
+│ Contrast Ratio            │ Dark modules on a clean white background  │
+└───────────────────────────┴───────────────────────────────────────────┘
+```
+
+### Printable Tabletop Sign Template (HTML/CSS)
+
+You can copy and save this HTML template to print professional Wi-Fi stand cards for your business:
+
+```html
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <title>Wi-Fi Access Tabletop Stand</title>
+  <style>
+    @media print { body { -webkit-print-color-adjust: exact; } }
+    body { font-family: 'Inter', system-ui, sans-serif; display: flex; justify-content: center; align-items: center; min-height: 100vh; background: #F8FAFC; margin: 0; }
+    .stand-card { background: white; width: 300px; padding: 32px 24px; border-radius: 16px; box-shadow: 0 10px 25px rgba(0,0,0,0.08); text-align: center; border: 1px solid #E2E8F0; }
+    h1 { font-size: 20px; color: #0F172A; margin: 0 0 6px; }
+    p.sub { color: #64748B; font-size: 13px; margin: 0 0 20px; }
+    .qr-box { background: #F1F5F9; padding: 16px; border-radius: 12px; display: inline-block; margin-bottom: 20px; }
+    .info { background: #F8FAFC; padding: 12px; border-radius: 8px; border: 1px solid #E2E8F0; font-size: 12px; text-align: left; }
+    .row { display: flex; justify-content: space-between; margin-bottom: 4px; }
+    .row:last-child { margin-bottom: 0; }
+    .lbl { color: #64748B; }
+    .val { color: #0F172A; font-weight: 600; font-family: monospace; }
+  </style>
+</head>
+<body>
+  <div class="stand-card">
+    <h1>Free Wi-Fi Access</h1>
+    <p class="sub">Scan with phone camera to connect</p>
+
+    <div class="qr-box">
+      <!-- Insert SVG QR Code Here -->
+      <svg width="180" height="180" viewBox="0 0 180 180">
+        <!-- SVG Paths -->
+      </svg>
+    </div>
+
+    <div class="info">
+      <div class="row"><span class="lbl">SSID:</span><span class="val">Guest_WiFi</span></div>
+      <div class="row"><span class="lbl">Pass:</span><span class="val">Welcome2026</span></div>
+    </div>
+  </div>
+</body>
+</html>
+```
+
+---
+
+## 4. Programmatic Implementation: Wi-Fi Generator in TypeScript
+
+Below is a TypeScript module that constructs escaped Wi-Fi strings and generates vector SVG barcodes automatically.
+
+```typescript
+import QRCode from 'qrcode';
+
+export interface WifiParams {
+  ssid: string;
+  password?: string;
+  security: 'WPA' | 'WEP' | 'nopass';
+  hidden?: boolean;
+}
+
+export class WifiQrEngine {
+  /**
+   * Builds an escaped WIFI: URI payload and renders vector SVG.
+   */
+  public static async generateWifiSvg(params: WifiParams): Promise<string> {
+    const { ssid, password = '', security, hidden = false } = params;
+
+    if (!ssid) throw new Error('SSID is mandatory.');
+    if (security !== 'nopass' && !password) throw new Error('Password is required.');
+
+    // Escape special characters: colons, semicolons, backslashes, commas
+    const cleanSsid = ssid.replace(/([\\;:,])/g, '\\$1');
+    const cleanPass = password.replace(/([\\;:,])/g, '\\$1');
+
+    let payload = `WIFI:S:${cleanSsid};T:${security};`;
+    if (security !== 'nopass') payload += `P:${cleanPass};`;
+    if (hidden) payload += `H:true;`;
+    payload += ';;'; // Double semicolon termination
+
+    // Generate static SVG
+    return await QRCode.toString(payload, {
+      type: 'svg',
+      errorCorrectionLevel: 'M',
+      margin: 4,
+      color: { dark: '#0F172A', light: '#FFFFFF' },
+    });
+  }
+}
+```
+
+---
+
+## Conclusion
+
+Using a **wifi qr code generator** transforms the frustrating experience of typing Wi-Fi passwords into a seamless, one-tap camera interaction. By using static SVG vector files when you **print a qr code**, your guest Wi-Fi access signs remain scannable for years without extra maintenance.
+
+To generate free vector Wi-Fi QR codes with custom tabletop templates and logo branding, check out [QR Master Free Wi-Fi QR Code Generator](https://www.qrmaster.net/blog/wifi-qr-code-generator).

articles/devto-hashnode/devto-wifi-qr-code-protocol-spec.md

@@ -0,0 +1,261 @@
+---
+title: "Wi-Fi QR Code Protocol: WIFI: String Syntax Specification & Mobile OS Parsing"
+description: "A comprehensive developer guide to the unofficial WIFI: URI protocol specification, character escaping rules, WPA2/WPA3 network formats, and creating a print qr code for Wi-Fi access."
+tags: networking, mobile, webdev, security
+keywords: qr wifi, wifi qr code generator, print qr code, print a qr code, free static qr code generator, static qr code generator
+canonical_url: https://www.qrmaster.net/blog/wifi-qr-code-generator
+---
+
+# Wi-Fi QR Code Protocol: WIFI: String Syntax Specification & Mobile OS Parsing
+
+Scanning a **qr wifi** code to automatically connect a smartphone to a Wi-Fi network without manually typing complex WPA3 passwords is one of the most common physical tech interactions.
+
+Unlike vCards or geo-locations which have formal IETF RFC standards, a **wifi qr code generator** uses an de facto industry standard string syntax originally popularized by ZXing ("Zebra Crossing").
+
+In this technical guide, we will inspect the exact `WIFI:` connection string syntax, character escaping rules, WPA2/WPA3 security flags, hidden network parameters, and build a TypeScript utility to generate a **print qr code** for physical tabletop stands using a **free static qr code generator**.
+
+---
+
+## 1. The `WIFI:` String Protocol Syntax
+
+The payload generated by a **wifi qr code generator** is a formatted key-value string prefixed with `WIFI:`.
+
+### Protocol Format:
+```text
+WIFI:S:<SSID>;T:<SECURITY_TYPE>;P:<PASSWORD>;H:<HIDDEN_FLAG>;;
+```
+
+### Parameter Specification:
+
+| Parameter Key | Description | Allowed Values | Required? |
+|---|---|---|---|
+| **S** | Network SSID (Name) | Any string (UTF-8) | ✅ Mandatory |
+| **T** | Security Encryption Type | `WPA`, `WEP`, `nopass` | ✅ Mandatory |
+| **P** | Pre-shared Key (Password) | Network password string | Conditional (Skip if `nopass`) |
+| **H** | Hidden SSID Flag | `true` or `false` | Optional (Default: `false`) |
+
+---
+
+## 2. Character Escaping Rules: Avoiding Connection Failures
+
+The most frequent bug when building a **wifi qr code generator** is failing to escape special delimiter characters in the SSID or Password.
+
+### Characters Requiring Backslash Escaping (`\`):
+If an SSID or Wi-Fi password contains any of the following four characters:
+- Colon `:`
+- Semicolon `;`
+- Backslash `\`
+- Comma `,`
+
+They **must be escaped with a preceding backslash (`\`)**.
+
+### Escaping Examples:
+
+```text
+# Example 1: SSID containing a semicolon ("Coffee;Bar") and password "secret:123"
+WIFI:S:Coffee\;Bar;T:WPA;P:secret\:123;;
+
+# Example 2: Unencrypted Open Network ("Guest_WiFi")
+WIFI:S:Guest_WiFi;T:nopass;;
+
+# Example 3: Hidden WPA2/WPA3 Network ("Vault") with password "P@$$w0rd"
+WIFI:S:Vault;T:WPA;P:P@$$w0rd;H:true;;
+```
+
+> **Important**: Notice the double semicolon (`;;`) at the very end of the string. Mobile camera scanners use the trailing double semicolon as the string termination marker when parsing **qr wifi** codes!
+
+---
+
+## 3. iOS vs. Android OS Parser Behavior
+
+Understanding how mobile operating systems parse `WIFI:` barcodes prevents support headaches when users **print a qr code**.
+
+```
+┌───────────────────────────┬───────────────────────────────────────────┬───────────────────────────────────────────┐
+│ Feature                   │ Apple iOS (Camera App)                    │ Android (Google Lens / Native Scanner)   │
+├───────────────────────────┼───────────────────────────────────────────┼───────────────────────────────────────────┤
+│ User Interaction Prompt   │ Displays banner: "Join 'SSID' Network?"   │ Displays modal with "Connect to Network"  │
+│ One-Tap Auto Connect      │ ✅ Yes (Connects without typing password) │ ✅ Yes (Saves & connects automatically)   │
+│ WPA3 Compatibility        │ Map `T:WPA` for both WPA2 & WPA3          │ Map `T:WPA` for both WPA2 & WPA3          │
+│ Enterprise (802.1X / EAP)│ ❌ Unsupported via standard `WIFI:` string│ ❌ Requires mobile profile (.mobileconfig)│
+└───────────────────────────┴───────────────────────────────────────────┴───────────────────────────────────────────┘
+```
+
+*Note on WPA3:* Neither iOS nor Android requires a separate `T:WPA3` tag. Specifying `T:WPA` in your **static qr code generator** covers WPA, WPA2, and WPA3 Personal networks seamlessly.
+
+---
+
+## 4. TypeScript Implementation: Wi-Fi Payload Generator
+
+Below is a complete, production-ready TypeScript utility class that formats, escapes, and validates payloads for a **free static qr code generator**.
+
+### `src/services/wifiPayloadBuilder.ts`
+
+```typescript
+export type WifiSecurityType = 'WPA' | 'WEP' | 'nopass';
+
+export interface WifiConfig {
+  ssid: string;
+  password?: string;
+  securityType: WifiSecurityType;
+  isHidden?: boolean;
+}
+
+export class WifiPayloadBuilder {
+  /**
+   * Generates a fully escaped, validated WIFI: connection string.
+   */
+  public static buildPayload(config: WifiConfig): string {
+    const { ssid, password = '', securityType, isHidden = false } = config;
+
+    if (!ssid || ssid.trim().length === 0) {
+      throw new Error('Wi-Fi SSID is mandatory.');
+    }
+
+    if (securityType !== 'nopass' && (!password || password.length === 0)) {
+      throw new Error(`Password is required for security type "${securityType}".`);
+    }
+
+    // Escape special delimiter characters
+    const escapedSSID = this.escapeString(ssid);
+    const escapedPassword = securityType !== 'nopass' ? this.escapeString(password) : '';
+
+    let payload = `WIFI:S:${escapedSSID};T:${securityType};`;
+
+    if (securityType !== 'nopass') {
+      payload += `P:${escapedPassword};`;
+    }
+
+    if (isHidden) {
+      payload += `H:true;`;
+    }
+
+    // Append compulsory double-semicolon termination marker
+    payload += ';';
+
+    return payload;
+  }
+
+  private static escapeString(str: string): string {
+    return str.replace(/([\\;:,])/g, '\\$1');
+  }
+
+  public static isValidWifiPayload(payload: string): boolean {
+    return payload.startsWith('WIFI:') && payload.endsWith(';;');
+  }
+}
+```
+
+---
+
+## 5. How to Print a QR Code: Printable Wi-Fi Tabletop Sign Template
+
+When you **print a qr code** for physical venues (hotels, cafes, coworking spaces), pairing the vector barcode with clean printable HTML typography ensures guests know how to scan **qr wifi**.
+
+### Example Printable HTML Template (`public/wifi-stand-card.html`):
+
+```html
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <title>Wi-Fi Access Sign - Print QR Code</title>
+  <style>
+    @media print { body { -webkit-print-color-adjust: exact; } }
+    body { font-family: 'Inter', system-ui, sans-serif; display: flex; justify-content: center; align-items: center; min-height: 100vh; background: #F8FAFC; margin: 0; }
+    .card { background: white; width: 320px; padding: 36px 28px; border-radius: 20px; box-shadow: 0 10px 25px rgba(0,0,0,0.08); text-align: center; border: 1px solid #E2E8F0; }
+    h1 { font-size: 22px; color: #0F172A; margin: 0 0 6px; }
+    p.subtitle { color: #64748B; font-size: 14px; margin: 0 0 24px; }
+    .qr-container { background: #F1F5F9; padding: 16px; border-radius: 16px; display: inline-block; margin-bottom: 24px; }
+    .qr-container svg { display: block; }
+    .info-box { background: #F8FAFC; padding: 12px 16px; border-radius: 12px; border: 1px solid #E2E8F0; text-align: left; font-size: 13px; }
+    .info-row { display: flex; justify-content: space-between; margin-bottom: 6px; }
+    .info-row:last-child { margin-bottom: 0; }
+    .label { color: #64748B; font-weight: 500; }
+    .val { color: #0F172A; font-weight: 600; font-family: monospace; }
+  </style>
+</head>
+<body>
+  <div class="card">
+    <h1>Connect to Wi-Fi</h1>
+    <p class="subtitle">Scan with your phone camera to join</p>
+
+    <div class="qr-container">
+      <!-- Insert Vector SVG QR Code Here -->
+      <svg width="180" height="180" viewBox="0 0 180 180">
+        <!-- SVG Paths -->
+      </svg>
+    </div>
+
+    <div class="info-box">
+      <div class="info-row">
+        <span class="label">Network:</span>
+        <span class="val">Guest_Lounge_5G</span>
+      </div>
+      <div class="info-row">
+        <span class="label">Password:</span>
+        <span class="val">Welcome2026!</span>
+      </div>
+    </div>
+  </div>
+</body>
+</html>
+```
+
+---
+
+## 6. End-to-End Test Suite with Jest
+
+Let's write a unit test suite to verify string escaping and boundary conditions.
+
+### `tests/wifiPayload.test.ts`
+
+```typescript
+import { WifiPayloadBuilder } from '../src/services/wifiPayloadBuilder';
+
+describe('WifiPayloadBuilder', () => {
+  test('should generate standard WPA2 payload', () => {
+    const payload = WifiPayloadBuilder.buildPayload({
+      ssid: 'MyHomeWiFi',
+      password: 'SuperSecretPassword123',
+      securityType: 'WPA',
+    });
+    expect(payload).toBe('WIFI:S:MyHomeWiFi;T:WPA;P:SuperSecretPassword123;;');
+  });
+
+  test('should escape colons and semicolons in SSID and Password', () => {
+    const payload = WifiPayloadBuilder.buildPayload({
+      ssid: 'Cafe;WiFi:5G',
+      password: 'pass;word:123,key\\',
+      securityType: 'WPA',
+    });
+    expect(payload).toBe('WIFI:S:Cafe\\;WiFi\\:5G;T:WPA;P:pass\\;word\\:123\\,key\\\\;;');
+  });
+
+  test('should handle open unencrypted networks', () => {
+    const payload = WifiPayloadBuilder.buildPayload({
+      ssid: 'FreePublicWiFi',
+      securityType: 'nopass',
+    });
+    expect(payload).toBe('WIFI:S:FreePublicWiFi;T:nopass;;');
+  });
+
+  test('should include hidden flag when network is hidden', () => {
+    const payload = WifiPayloadBuilder.buildPayload({
+      ssid: 'HiddenNetwork',
+      password: 'secretpassword',
+      securityType: 'WPA',
+      isHidden: true,
+    });
+    expect(payload).toBe('WIFI:S:HiddenNetwork;T:WPA;P:secretpassword;H:true;;');
+  });
+});
+```
+
+---
+
+## Conclusion
+
+Understanding the `WIFI:` payload specification and implementing strict character escaping in a **wifi qr code generator** ensures seamless, friction-free auto-connections when you **print a qr code** for hotel guests, restaurant customers, and office visitors.
+
+To generate customizable vector Wi-Fi QR codes with custom brand colors, logo embedding, and printable tabletop stand templates, check out [QR Master Free Wi-Fi QR Generator](https://www.qrmaster.net/blog/wifi-qr-code-generator).

atom-eve.json

@@ -0,0 +1,7 @@
+{
+  "$schema": "https://atomeve.dev/schema/atom-eve.json",
+  "target": "eve",
+  "runtime": "vercel",
+  "sourceRoot": "src",
+  "registry": "elie222/atom-eve"
+}

design-variants/bakeoff.html

@@ -0,0 +1,116 @@
+<!DOCTYPE html>
+<html lang="de">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>QR Master — Design Bake-off</title>
+<style>
+  :root {
+    --bg: #141414; --panel: #1c1c1c; --line: #333333; --ink: #ECECEC; --muted: #8A8A8A;
+    --accent: #E8622C; --mono: "IBM Plex Mono","JetBrains Mono",ui-monospace,Consolas,monospace;
+  }
+  * { margin:0; padding:0; box-sizing:border-box; }
+  html,body { height:100%; background:var(--bg); color:var(--ink); font-family:var(--mono); }
+  .topbar {
+    display:flex; align-items:center; justify-content:space-between; gap:20px;
+    padding:14px 20px; border-bottom:1px solid var(--line); flex-wrap:wrap;
+  }
+  .topbar-left { display:flex; align-items:center; gap:14px; flex-wrap:wrap; }
+  .topbar-label { font-size:10.5px; letter-spacing:0.1em; text-transform:uppercase; color:var(--muted); line-height:1.3; }
+  .collection-btns { display:flex; gap:8px; flex-wrap:wrap; }
+  .cbtn {
+    font-family:var(--mono); font-size:11px; font-weight:600; letter-spacing:0.06em; text-transform:uppercase;
+    background:transparent; border:1px solid var(--line); color:var(--ink);
+    padding:9px 16px; border-radius:3px; cursor:pointer; transition:all .15s ease;
+  }
+  .cbtn:hover { border-color:var(--accent); }
+  .cbtn.active { background:var(--accent); border-color:var(--accent); color:#141414; }
+  .topbar-hint { font-size:10.5px; letter-spacing:0.06em; color:var(--muted); text-transform:uppercase; text-align:right; }
+  .topbar-hint b { color:var(--ink); }
+
+  .compare { display:grid; grid-template-columns:1fr 1fr; height:calc(100vh - 60px); }
+  .pane { display:flex; flex-direction:column; border-right:1px solid var(--line); min-width:0; }
+  .pane:last-child { border-right:none; }
+  .pane-head {
+    display:flex; align-items:center; justify-content:space-between; gap:12px;
+    padding:10px 18px; border-bottom:1px solid var(--line); background:var(--panel);
+  }
+  .pane-head .name { font-size:12px; font-weight:700; letter-spacing:0.08em; text-transform:uppercase; }
+  .pane-head .name.left-accent { color:var(--accent); }
+  .pane-head .name.right-accent { color:#5FA8FF; }
+  .pane-head .tag { font-size:10px; color:var(--muted); letter-spacing:0.08em; text-transform:uppercase; }
+  .pane iframe { flex:1; width:100%; border:none; background:#fff; }
+
+  @media (max-width: 900px) {
+    .compare { grid-template-columns:1fr; height:auto; }
+    .pane { border-right:none; border-bottom:1px solid var(--line); height:70vh; }
+  }
+</style>
+</head>
+<body>
+
+<div class="topbar">
+  <div class="topbar-left">
+    <span class="topbar-label">Design<br>Collection:</span>
+    <div class="collection-btns" id="collectionBtns">
+      <button class="cbtn" data-slug="blueprint">Print-Tech</button>
+      <button class="cbtn" data-slug="dither-mono">Dither Mono</button>
+      <button class="cbtn" data-slug="vast-quiet">Vast Quiet</button>
+      <button class="cbtn" data-slug="data-texture">Data-Texture</button>
+      <button class="cbtn" data-slug="classical">Classical</button>
+      <button class="cbtn active" data-slug="quiet-mono">Quiet Mono</button>
+    </div>
+  </div>
+  <div class="topbar-hint">Left = <b>Light</b> · Right = <b>Dark</b> · Keys 1–6</div>
+</div>
+
+<div class="compare">
+  <div class="pane">
+    <div class="pane-head"><span class="name left-accent" id="leftName">Classical</span><span class="tag">Light</span></div>
+    <iframe id="leftFrame" title="Light mode preview"></iframe>
+  </div>
+  <div class="pane">
+    <div class="pane-head"><span class="name right-accent" id="rightName">Classical</span><span class="tag">Dark</span></div>
+    <iframe id="rightFrame" title="Dark mode preview"></iframe>
+  </div>
+</div>
+
+<script>
+(function () {
+  var LABELS = {
+    "blueprint": "Print-Tech",
+    "dither-mono": "Dither Mono",
+    "vast-quiet": "Vast Quiet",
+    "data-texture": "Data-Texture",
+    "classical": "Classical",
+    "quiet-mono": "Quiet Mono"
+  };
+  var ORDER = ["blueprint", "dither-mono", "vast-quiet", "data-texture", "classical", "quiet-mono"];
+  var btns = document.querySelectorAll('.cbtn');
+  var leftFrame = document.getElementById('leftFrame');
+  var rightFrame = document.getElementById('rightFrame');
+  var leftName = document.getElementById('leftName');
+  var rightName = document.getElementById('rightName');
+
+  function setCollection(slug) {
+    btns.forEach(function (b) { b.classList.toggle('active', b.getAttribute('data-slug') === slug); });
+    leftFrame.src = 'landing-' + slug + '.html';
+    rightFrame.src = 'landing-' + slug + '.html#dark';
+    leftName.textContent = LABELS[slug];
+    rightName.textContent = LABELS[slug];
+  }
+
+  btns.forEach(function (b) {
+    b.addEventListener('click', function () { setCollection(b.getAttribute('data-slug')); });
+  });
+
+  document.addEventListener('keydown', function (e) {
+    var idx = parseInt(e.key, 10) - 1;
+    if (idx >= 0 && idx < ORDER.length) setCollection(ORDER[idx]);
+  });
+
+  setCollection('quiet-mono');
+})();
+</script>
+</body>
+</html>

docker-compose.test.yml

@@ -0,0 +1,85 @@
+# Test/staging overlay for testmodul.qrmaster.net.
+#
+# Start with:
+#   docker compose -p qrmaster-test --env-file .env.test \
+#     -f docker-compose.yml -f docker-compose.test.yml up -d --build
+#
+# The project name is what keeps the data apart: `-p qrmaster-test` gives this stack its own
+# volumes, so its Postgres can never touch the production one.
+
+services:
+  db:
+    container_name: qrmaster-test-db
+    # Production already publishes 5435 on the host.
+    ports: !reset []
+    # The base file hardcodes the database name in the probe. Staging uses its own name so a
+    # hand-typed psql session makes it obvious which instance you are on - without this
+    # override the probe would check a database that does not exist, the container would stay
+    # unhealthy and web (depends_on: service_healthy) would never start.
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U postgres -d qrmaster_test"]
+    # Only on the internal network. `db` and `redis` are network aliases assigned per
+    # compose project, so leaving them on the shared external network would make `db`
+    # resolve to two containers and this stack could reach the production database.
+    #
+    # `!override` is required: compose MERGES the networks mapping from the base file, so a
+    # plain list would leave qrmaster-network attached and reintroduce exactly that bug.
+    networks: !override
+      - test-internal
+
+  redis:
+    container_name: qrmaster-test-redis
+    networks: !override
+      - test-internal
+
+  web:
+    container_name: qrmaster-test-web
+    # No `prisma migrate deploy` here. The migrations in prisma/migrations stopped in
+    # April 2026 and the schema has moved on through manual SQL since, so running them
+    # against a fresh database would build a stale schema the app cannot work with.
+    # Bring the schema in with `pg_dump --schema-only` from production instead.
+    environment:
+      # Docker sets HOSTNAME=<container-id>, and the Next.js standalone server binds to
+      # that single interface. With two networks Caddy then cannot reach the container.
+      HOSTNAME: "0.0.0.0"
+      # `db` and `redis` are taken in BOTH networks - by this stack in test-internal and
+      # by production in qrmaster-network. Production wins the lookup every time, so the
+      # base file's hostnames point the staging app at the production instances. Container
+      # names are unique per daemon and cannot be shadowed.
+      DATABASE_URL: postgresql://${POSTGRES_USER}:${POSTGRES_PASSWORD}@qrmaster-test-db:5432/${POSTGRES_DB}?schema=public
+      DIRECT_URL: postgresql://${POSTGRES_USER}:${POSTGRES_PASSWORD}@qrmaster-test-db:5432/${POSTGRES_DB}?schema=public
+      REDIS_URL: redis://qrmaster-test-redis:6379
+    entrypoint: ["node", "server.js"]
+    build:
+      args:
+        # Host-only cookie on staging, so `:-` (empty) is the correct value here.
+        COOKIE_DOMAIN: ${COOKIE_DOMAIN:-}
+        # These three use `:?` on purpose: an empty value would silently fall back to the
+        # production defaults baked into the Dockerfile, and the staging frontend would then
+        # talk to production. Better to fail the build with a readable message.
+        AUTH_COOKIE_NAME: ${AUTH_COOKIE_NAME:?set AUTH_COOKIE_NAME in .env.test, e.g. userId_test}
+        NEXT_PUBLIC_WWW_URL: ${NEXT_PUBLIC_WWW_URL:?set NEXT_PUBLIC_WWW_URL in .env.test to https://testmodul.qrmaster.net}
+        NEXT_PUBLIC_APP_URL: ${NEXT_PUBLIC_APP_URL:?set NEXT_PUBLIC_APP_URL in .env.test to https://testmodul.qrmaster.net}
+    # Reachable by Caddy over the shared network, everything else stays internal.
+    networks:
+      - test-internal
+      - qrmaster-network
+
+  social-worker:
+    container_name: qrmaster-test-social-worker
+    environment:
+      # Never resolve the ambiguous `web` alias on the shared production
+      # network. The test container name is unique on this Docker daemon.
+      QRMASTER_API_BASE: http://qrmaster-test-web:3000
+    networks: !override
+      - test-internal
+
+  adminer:
+    container_name: qrmaster-test-adminer
+    ports: !reset []
+    networks: !override
+      - test-internal
+
+networks:
+  test-internal:
+    driver: bridge

docker-compose.yml

@@ -9,6 +9,8 @@ services:
       POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
       POSTGRES_DB: ${POSTGRES_DB}
       POSTGRES_INITDB_ARGS: "-E UTF8 --locale=en_US.utf8"
+    ports:
+      - "5435:5432"      
     volumes:
       - dbdata:/var/lib/postgresql/data
       - ./docker/init-db.sh:/docker-entrypoint-initdb.d/init-db.sh
@@ -41,6 +43,11 @@ services:
     build:
       context: .
       dockerfile: Dockerfile
+      args:
+        NEXT_PUBLIC_UMAMI_SRC: ${NEXT_PUBLIC_UMAMI_SRC:-}
+        NEXT_PUBLIC_UMAMI_ID: ${NEXT_PUBLIC_UMAMI_ID:-}
+        COOKIE_DOMAIN: ${COOKIE_DOMAIN:-}
+        AUTH_COOKIE_NAME: ${AUTH_COOKIE_NAME:-}
     container_name: qrmaster-web
     restart: unless-stopped
     environment:
@@ -51,6 +58,25 @@ services:
       NEXTAUTH_URL: ${NEXTAUTH_URL}
       NEXTAUTH_SECRET: ${NEXTAUTH_SECRET}
       NEXT_PUBLIC_APP_URL: ${NEXT_PUBLIC_APP_URL:-http://localhost:3050}
+      NEXT_PUBLIC_WWW_URL: ${NEXT_PUBLIC_WWW_URL:-http://localhost:3050}
+      COOKIE_DOMAIN: ${COOKIE_DOMAIN:-}
+      AUTH_COOKIE_NAME: ${AUTH_COOKIE_NAME:-}
+      INTERNAL_API_SECRET: ${INTERNAL_API_SECRET}
+      CRON_SECRET: ${CRON_SECRET:-}
+      SOCIAL_MILESTONE_THRESHOLDS: ${SOCIAL_MILESTONE_THRESHOLDS:-}
+      SOCIAL_MILESTONE_POST_DELAY_HOURS: ${SOCIAL_MILESTONE_POST_DELAY_HOURS:-}
+      SOCIAL_MILESTONE_MIN_GAP_HOURS: ${SOCIAL_MILESTONE_MIN_GAP_HOURS:-}
+      # Channels the consent dialog may ask for. Only extend this once the
+      # worker actually publishes that channel.
+      SOCIAL_MILESTONE_CHANNELS: ${SOCIAL_MILESTONE_CHANNELS:-x}
+      TIKTOK_CLIENT_KEY: ${TIKTOK_CLIENT_KEY:-}
+      TIKTOK_CLIENT_SECRET: ${TIKTOK_CLIENT_SECRET:-}
+      TIKTOK_REDIRECT_URI: ${TIKTOK_REDIRECT_URI:-https://qrmaster.net/api/tiktok/callback}
+      TIKTOK_ADMIN_KEY: ${TIKTOK_ADMIN_KEY:-}
+      # Guards the asset upload route that Instagram (and TikTok) pull media
+      # from. Falls back to the TikTok key so existing setups keep working.
+      SOCIAL_ASSET_ADMIN_KEY: ${SOCIAL_ASSET_ADMIN_KEY:-}
+      TIKTOK_EXPECTED_OPEN_ID: ${TIKTOK_EXPECTED_OPEN_ID:-}
       IP_SALT: ${IP_SALT:-your-salt-change-in-production}
       ENABLE_DEMO: ${ENABLE_DEMO:-false}
       NEXT_PUBLIC_INDEXABLE: ${NEXT_PUBLIC_INDEXABLE:-true}
@@ -69,8 +95,12 @@ services:
       RESEND_API_KEY: ${RESEND_API_KEY:-}
       SMTP_HOST: ${SMTP_HOST:-smtp.qrmaster.net}
       SMTP_PORT: ${SMTP_PORT:-465}
-      SMTP_USER: ${SMTP_USER:-timo@qrmaster.net}
+      SMTP_USER: ${SMTP_USER:-info@qrmaster.net}
       SMTP_PASS: ${SMTP_PASS:-}
+      NEWSLETTER_ADMIN_EMAIL: ${NEWSLETTER_ADMIN_EMAIL:-}
+      NEWSLETTER_ADMIN_PASSWORD: ${NEWSLETTER_ADMIN_PASSWORD:-}
+      NEWSLETTER_TEST_EMAIL: ${NEWSLETTER_TEST_EMAIL:-}
+      EMAIL_UNSUBSCRIBE_SECRET: ${EMAIL_UNSUBSCRIBE_SECRET:-}
       NEXT_PUBLIC_POSTHOG_KEY: ${NEXT_PUBLIC_POSTHOG_KEY:-}
       NEXT_PUBLIC_POSTHOG_HOST: ${NEXT_PUBLIC_POSTHOG_HOST:-https://us.i.posthog.com}
       # Cloudflare R2 Storage
@@ -79,6 +109,8 @@ services:
       R2_SECRET_ACCESS_KEY: ${R2_SECRET_ACCESS_KEY:-}
       R2_BUCKET_NAME: ${R2_BUCKET_NAME:-qrmaster-menus}
       R2_PUBLIC_URL: ${R2_PUBLIC_URL:-}
+      NEXT_PUBLIC_UMAMI_SRC: ${NEXT_PUBLIC_UMAMI_SRC:-}
+      NEXT_PUBLIC_UMAMI_ID: ${NEXT_PUBLIC_UMAMI_ID:-}      
     depends_on:
       db:
         condition: service_healthy
@@ -92,6 +124,36 @@ services:
     networks:
       - qrmaster-network
 
+  social-worker:
+    build:
+      context: ./scripts/social-worker
+    restart: unless-stopped
+    environment:
+      QRMASTER_API_BASE: http://web:3000
+      INTERNAL_API_SECRET: ${INTERNAL_API_SECRET}
+      SOCIAL_MILESTONE_POSTING_ENABLED: ${SOCIAL_MILESTONE_POSTING_ENABLED:-false}
+      SOCIAL_WORKER_INTERVAL_SECONDS: ${SOCIAL_WORKER_INTERVAL_SECONDS:-10}
+      X_API_KEY: ${X_API_KEY:-}
+      X_API_SECRET: ${X_API_SECRET:-}
+      X_ACCESS_TOKEN: ${X_ACCESS_TOKEN:-}
+      X_ACCESS_TOKEN_SECRET: ${X_ACCESS_TOKEN_SECRET:-}
+      # Channels this worker publishes. Must stay a subset of the app's
+      # SOCIAL_MILESTONE_CHANNELS - a channel the dialog offers but nobody
+      # publishes would leave approvals sitting in the queue.
+      SOCIAL_WORKER_CHANNELS: ${SOCIAL_WORKER_CHANNELS:-x}
+      INSTAGRAM_USER_ID: ${INSTAGRAM_USER_ID:-}
+      INSTAGRAM_ACCESS_TOKEN: ${INSTAGRAM_ACCESS_TOKEN:-}
+      GRAPH_API_VERSION: ${GRAPH_API_VERSION:-v22.0}
+      # Instagram downloads the image itself, so the worker hosts it through
+      # /api/social-assets on the verified domain. Same key as the web service.
+      SOCIAL_ASSET_ADMIN_KEY: ${SOCIAL_ASSET_ADMIN_KEY:-${TIKTOK_ADMIN_KEY:-}}
+    depends_on:
+      web:
+        condition: service_started
+    networks:
+      - qrmaster-network
+      
+
   # Adminer - Database Management UI (Optional)
   adminer:
     image: adminer:latest
@@ -116,4 +178,4 @@ volumes:
 
 networks:
   qrmaster-network:
-    driver: bridge
+    external: true

docker/init-db.sh

@@ -3,24 +3,26 @@ set -e
 
 # This script runs when the PostgreSQL container is first created
 # It ensures the database is properly initialized
+#
+# Keep this database-name agnostic: the staging stack (docker-compose.test.yml)
+# runs the same script with POSTGRES_DB=qrmaster_test. A hardcoded name aborts
+# the init, and the container never becomes healthy.
+# Must stay LF-only and executable - Postgres sources non-executable init
+# scripts, and CRLF breaks them on the first line.
 
 echo "🚀 Initializing QR Master database..."
 
-# Create the database if it doesn't exist (already created by POSTGRES_DB)
-psql -v ON_ERROR_STOP=1 --username "$POSTGRES_USER" --dbname "$POSTGRES_DB" <<-EOSQL
+# The database itself is already created by POSTGRES_DB
+psql -v ON_ERROR_STOP=1 -v dbname="$POSTGRES_DB" --username "$POSTGRES_USER" --dbname "$POSTGRES_DB" <<-EOSQL
     -- Enable required extensions
     CREATE EXTENSION IF NOT EXISTS "uuid-ossp";
     CREATE EXTENSION IF NOT EXISTS "pg_trgm";
 
-    -- Grant privileges
-    GRANT ALL PRIVILEGES ON DATABASE qrmaster TO postgres;
-    
     -- Set timezone
-    ALTER DATABASE qrmaster SET timezone TO 'UTC';
+    ALTER DATABASE :"dbname" SET timezone TO 'UTC';
 EOSQL
 
 echo "✅ Database initialization complete!"
 echo "📊 Database: $POSTGRES_DB"
 echo "👤 User: $POSTGRES_USER"
 echo "🌐 Ready to accept connections on port 5432"
-

docs/PLAN_API_WEBHOOKS_ENTERPRISE.md

@@ -0,0 +1,368 @@
+# Plan: Public API, Webhooks, Enterprise-Plan, White-Label & Custom Domains
+
+Stand: 2026-07-11 · Autor: Claude (Analyse der Codebase auf Commit `d542f84`)
+
+**Feature-Gating-Übersicht:**
+
+| Feature | FREE | PRO | BUSINESS | ENTERPRISE |
+|---|---|---|---|---|
+| Webhooks | – | ✅ (3 Endpoints) | ✅ (10) | ✅ (unbegrenzt) |
+| Public REST API | – | – | ✅ (1.000 req/h) | ✅ (10.000 req/h) |
+| White-Label (Branding aus) | – | – | – | ✅ |
+| Custom Domain (CNAME) | – | – | – | ✅ (bis 3 Domains) |
+| Dynamische QRs | 3 | 50 | 500 | unbegrenzt |
+| Preis | 0 € | 9 €/M | 29 €/M | 149 €/M · 1.490 €/J |
+
+Empfohlene Reihenfolge: **Phase 1 → 2 → 3** ist launchbar als „Enterprise light"
+(CNAME als „coming soon"), Phase 4 + 5 danach.
+
+---
+
+## Phase 1 — Enterprise-Plan (≈ 1–2 Tage)
+
+### 1.1 Datenbank (manuell per SQL, gemäß DB-Policy — kein Migrate)
+
+```sql
+ALTER TYPE "Plan" ADD VALUE 'ENTERPRISE';
+```
+
+Danach: `prisma/schema.prisma` → `enum Plan { FREE PRO BUSINESS ENTERPRISE }`,
+dann `npx prisma generate`.
+
+### 1.2 Stripe
+
+- Im Stripe-Dashboard zwei Prices anlegen: **149 €/Monat**, **1.490 €/Jahr**
+  (Produkt „QR Master Enterprise").
+- Neue Env-Vars: `STRIPE_PRICE_ID_ENTERPRISE_MONTHLY`, `STRIPE_PRICE_ID_ENTERPRISE_YEARLY`
+  (auch in `env.example` ergänzen).
+
+### 1.3 Code-Änderungen
+
+| Datei | Änderung |
+|---|---|
+| `src/lib/plans.ts` | `ENTERPRISE_DYNAMIC_QR_LIMIT` sauber definieren (Wert `-1` = unbegrenzt statt 99999, oder 99999 belassen — Konsistenz mit `staticQRCodes: -1` prüfen) |
+| `src/lib/stripe.ts` | `STRIPE_PLANS.ENTERPRISE` mit Features-Liste + beiden priceIds; `getPlanFromStripePriceId()` um ENTERPRISE-Zweig erweitern (VOR dem BUSINESS-Check einfügen) |
+| Pricing-Page (`(marketing)`) | 4. Spalte Enterprise; Features: „Alles aus Business", „Public API 10k req/h", „Unbegrenzte Webhooks", „White-Label", „Custom Domain (CNAME)", „Priority Support & SLA", „AV-Vertrag (DPA)" |
+| Checkout/Portal-Routen (`api/stripe/*`) | Prüfen, ob Plan-Namen irgendwo hart kodiert sind (`grep -r "BUSINESS" src/app/(main)/api/stripe`) |
+| Webhook-Handler `api/stripe/webhook/route.ts` | Sollte über `getPlanFromStripePriceId()` automatisch funktionieren — verifizieren |
+
+### 1.4 Zentrale Gating-Helper (Grundlage für alle weiteren Phasen)
+
+Neue Datei `src/lib/entitlements.ts`:
+
+```ts
+export const ENTITLEMENTS = {
+  FREE:       { webhooks: 0,  api: false, apiRatePerHour: 0,     whiteLabel: false, customDomains: 0 },
+  PRO:        { webhooks: 3,  api: false, apiRatePerHour: 0,     whiteLabel: false, customDomains: 0 },
+  BUSINESS:   { webhooks: 10, api: true,  apiRatePerHour: 1000,  whiteLabel: false, customDomains: 0 },
+  ENTERPRISE: { webhooks: -1, api: true,  apiRatePerHour: 10000, whiteLabel: true,  customDomains: 3 },
+} as const;
+```
+
+Alle Feature-Checks laufen NUR über diese Datei — nie `plan === 'PRO'` inline.
+
+### 1.5 Verifikation
+
+- Test-Checkout mit Stripe-Testkarte (4242…) auf Enterprise monatlich + jährlich.
+- Downgrade/Upgrade über Customer Portal → `plan`-Feld in DB prüfen.
+
+---
+
+## Phase 2 — Webhooks (≈ 3–4 Tage) · ab PRO
+
+### 2.1 Datenbank (raw SQL)
+
+```sql
+CREATE TABLE "WebhookEndpoint" (
+  "id"         TEXT PRIMARY KEY DEFAULT gen_random_uuid()::text,
+  "userId"     TEXT NOT NULL REFERENCES "User"("id") ON DELETE CASCADE,
+  "url"        TEXT NOT NULL,
+  "secret"     TEXT NOT NULL,            -- whsec_..., wird nur 1x angezeigt
+  "events"     TEXT[] NOT NULL DEFAULT '{qr.scanned}',
+  "active"     BOOLEAN NOT NULL DEFAULT true,
+  "failCount"  INTEGER NOT NULL DEFAULT 0,  -- für Auto-Disable
+  "createdAt"  TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  "updatedAt"  TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP
+);
+CREATE INDEX "WebhookEndpoint_userId_idx" ON "WebhookEndpoint"("userId");
+
+CREATE TABLE "WebhookDelivery" (
+  "id"          TEXT PRIMARY KEY DEFAULT gen_random_uuid()::text,
+  "endpointId"  TEXT NOT NULL REFERENCES "WebhookEndpoint"("id") ON DELETE CASCADE,
+  "event"       TEXT NOT NULL,
+  "payload"     JSONB NOT NULL,
+  "statusCode"  INTEGER,
+  "success"     BOOLEAN NOT NULL DEFAULT false,
+  "attempts"    INTEGER NOT NULL DEFAULT 0,
+  "createdAt"   TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP
+);
+CREATE INDEX "WebhookDelivery_endpointId_createdAt_idx"
+  ON "WebhookDelivery"("endpointId", "createdAt");
+```
+
+Schema.prisma nachziehen, `prisma generate`. Deliveries nach 30 Tagen löschen
+(einfacher Cleanup beim Dispatch oder Cron).
+
+### 2.2 Dispatch-Modul `src/lib/webhooks.ts`
+
+- `dispatchEvent(userId, event, data)`:
+  1. Aktive Endpoints des Users laden, die `event` abonniert haben.
+  2. Payload bauen (s. u.), HMAC-SHA256 über den Raw-Body mit `secret`.
+  3. POST mit Headers `X-QRMaster-Signature: sha256=<hex>`,
+     `X-QRMaster-Event`, `X-QRMaster-Delivery-Id`; Timeout 5 s.
+  4. Retry inline: max. 3 Versuche (0 s / 10 s / 60 s Backoff) — bewusst ohne
+     Job-Queue, fire-and-forget wie `trackScan`.
+  5. `WebhookDelivery` loggen; bei Erfolg `failCount = 0`, bei Fehlschlag
+     `failCount++`; ab 20 Fehlschlägen in Folge `active = false` + E-Mail an
+     User (via `src/lib/email.ts`).
+- **SSRF-Schutz (wichtig!)**: URL-Validierung beim Anlegen UND vor jedem
+  Request — nur `https://`, DNS auflösen und private/interne IP-Ranges
+  blocken (127.0.0.0/8, 10/8, 172.16/12, 192.168/16, 169.254/16, ::1).
+
+Payload-Format (stabil halten, das ist API-Vertrag):
+
+```json
+{
+  "id": "evt_...",
+  "event": "qr.scanned",
+  "createdAt": "2026-07-11T12:00:00Z",
+  "data": {
+    "qrId": "...", "slug": "...", "name": "...",
+    "scan": { "ts": "...", "country": "DE", "city": "Berlin",
+              "device": "mobile", "os": "iOS", "isUnique": true }
+  }
+}
+```
+
+Kein `ipHash` im Payload (Datenschutz).
+
+### 2.3 Event-Quellen einhängen
+
+| Event | Ort |
+|---|---|
+| `qr.scanned` | `src/app/(main)/r/[slug]/route.ts` → am Ende von `trackScan()` (dort liegen bereits alle Geo/Device-Daten vor) |
+| `qr.created` / `qr.updated` / `qr.deleted` | `api/qrs/route.ts` + `api/qrs/[id]/route.ts` nach erfolgreichem DB-Write |
+
+DNT-Verhalten spiegeln: wenn `trackScan` wegen DNT keinen Scan schreibt,
+auch kein `qr.scanned`-Event feuern.
+
+### 2.4 Management-API (Session-Auth, CSRF wie bestehende Routen)
+
+- `GET/POST /api/webhooks` — Liste / Anlegen (Zod-Schema in `validationSchemas.ts`;
+  Limit aus `ENTITLEMENTS[plan].webhooks` prüfen; Secret `whsec_` + 32 random
+  Bytes generieren, im Response einmalig zurückgeben)
+- `PATCH/DELETE /api/webhooks/[id]` — aktivieren/deaktivieren/URL/Events ändern, löschen
+- `POST /api/webhooks/[id]/test` — Test-Event `webhook.test` senden, Response-Status zurückgeben
+- `GET /api/webhooks/[id]/deliveries` — letzte 50 Deliveries
+
+### 2.5 UI
+
+Neuer Tab/Bereich in `src/app/(main)/(app)/settings/page.tsx` (oder eigene
+Seite `settings/webhooks`): Endpoint-Liste mit Status-Badge, Anlegen-Dialog
+(URL + Event-Checkboxen), Secret-einmal-anzeigen-Modal (Copy-Button),
+„Test senden"-Button, Delivery-Log aufklappbar. Für FREE: Upsell-Karte.
+
+### 2.6 Doku + Verifikation
+
+- Doku-Seite `/docs/webhooks` (Signatur-Verifikations-Beispiel in Node/PHP).
+- Test end-to-end mit webhook.site + lokalem Scan; Signatur nachrechnen;
+  Retry testen (Endpoint der 500 liefert); SSRF-Check (`http://localhost` muss abgelehnt werden).
+
+---
+
+## Phase 3 — Public REST API (≈ 4–6 Tage) · ab BUSINESS
+
+### 3.1 Datenbank (raw SQL)
+
+```sql
+CREATE TABLE "ApiKey" (
+  "id"         TEXT PRIMARY KEY DEFAULT gen_random_uuid()::text,
+  "userId"     TEXT NOT NULL REFERENCES "User"("id") ON DELETE CASCADE,
+  "name"       TEXT NOT NULL,
+  "keyHash"    TEXT NOT NULL UNIQUE,     -- SHA-256 des vollen Keys
+  "keyPrefix"  TEXT NOT NULL,            -- "qrm_live_a1b2c3" für UI-Anzeige
+  "lastUsedAt" TIMESTAMP(3),
+  "revokedAt"  TIMESTAMP(3),
+  "createdAt"  TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP
+);
+CREATE INDEX "ApiKey_userId_idx" ON "ApiKey"("userId");
+```
+
+Key-Format: `qrm_live_` + 32 random Bytes base62. Lookup über SHA-256-Hash
+(deterministisch → `keyHash` direkt per `findUnique`, kein bcrypt nötig,
+Keys haben genug Entropie).
+
+### 3.2 Auth- & Rate-Limit-Middleware `src/lib/apiAuth.ts`
+
+- `authenticateApiKey(request)`: `Authorization: Bearer qrm_live_...` →
+  Hash → Key + User laden → revoked prüfen → `ENTITLEMENTS[plan].api`
+  prüfen → `lastUsedAt` throttled updaten (max. 1×/min) →
+  `{ userId, plan }` zurückgeben oder 401/403.
+- Rate-Limiting **Redis-basiert** (nicht das in-memory `rateLimit.ts`):
+  neuer `src/lib/redisRateLimit.ts` mit Sliding Window
+  (`INCR` + `EXPIRE` pro `apikey:{id}:{hourBucket}` reicht).
+  Limits aus `ENTITLEMENTS`. Fallback ohne Redis: in-memory mit Warnung.
+  Standard-Header `X-RateLimit-*` + `Retry-After` bei 429.
+
+### 3.3 Service-Layer-Refactoring (der eigentliche Aufwand)
+
+Kernlogik aus den Session-Routen in `src/lib/services/qrService.ts`
+extrahieren, damit Session-Routen und v1-Routen dieselbe Logik nutzen:
+`listQrs(userId)`, `createQr(userId, plan, input)` (inkl. Plan-Limit-Check),
+`updateQr`, `deleteQr`, `getAnalyticsSummary(userId, qrId, range)`.
+Bestehende Routen auf den Service umstellen — **keine Logik duplizieren**.
+
+### 3.4 Endpoints unter `src/app/(main)/api/v1/`
+
+Kein CSRF (Bearer-Auth), JSON-Fehlerformat `{ "error": { "code", "message" } }`:
+
+| Endpoint | Beschreibung |
+|---|---|
+| `GET /api/v1/qr-codes` | Liste, Pagination `?limit=&cursor=` |
+| `POST /api/v1/qr-codes` | Anlegen (gleiche Zod-Schemas wie intern) |
+| `GET/PATCH/DELETE /api/v1/qr-codes/{id}` | Einzeloperationen |
+| `GET /api/v1/qr-codes/{id}/analytics?from=&to=` | Scans, Unique, Country/Device-Breakdown |
+| `GET /api/v1/qr-codes/{id}/image?format=png\|svg&size=` | QR-Bild (nutzt `src/lib/qr.ts`) |
+| `GET /api/v1/me` | Plan, Limits, Verbrauch (guter Smoke-Test-Endpoint) |
+
+Versionierung im Pfad (`/v1/`) — Breaking Changes später nur via `/v2/`.
+
+### 3.5 Key-Verwaltung
+
+- Session-Routen `GET/POST /api/api-keys`, `DELETE /api/api-keys/[id]` (= revoke).
+- UI in Settings: Key-Liste (Prefix, lastUsed), „Create key" mit
+  Einmal-Anzeige-Modal, Revoke mit Confirm. Max. 5 Keys/User.
+- Gating: FREE/PRO sehen Upsell auf Business.
+
+### 3.6 Doku (Pflicht, sonst wertlos)
+
+Marketing-Seite `/docs/api`: Auth, Rate Limits, alle Endpoints mit
+curl-Beispielen, Fehlercodes, Webhook-Sektion verlinken. OpenAPI-Spec
+(`public/openapi.json`) optional als Follow-up.
+
+### 3.7 Verifikation
+
+curl-Suite gegen lokalen Dev-Server: 401 ohne Key, 403 mit PRO-Key,
+CRUD-Roundtrip mit Business-Key, 429 nach Limit, revoked Key → 401.
+
+---
+
+## Phase 4 — White-Label (≈ 1–2 Tage) · ENTERPRISE
+
+### 4.1 Scope
+
+„Powered by QR Master"-Branding entfernen auf allen Seiten, die Endkunden
+beim Scannen sehen: vCard-Display, Text-Display, Coupon-, Feedback-Seiten
+(`grep -ri "qr master\|qrmaster" src/app` über die Display-Seiten, um alle
+Stellen zu finden).
+
+### 4.2 Umsetzung
+
+- User-Felder (raw SQL): `whiteLabelEnabled BOOLEAN DEFAULT false`,
+  optional `brandLogoUrl TEXT`, `brandColor TEXT`.
+- Display-Seiten laden den QR-Owner sowieso → Branding-Block konditional
+  auf `ENTITLEMENTS[plan].whiteLabel && whiteLabelEnabled`.
+- Settings-Toggle (nur Enterprise sichtbar), optional Logo-Upload via
+  bestehendem S3-Setup.
+- Wichtig: Beim Downgrade (Stripe-Webhook) `whiteLabelEnabled` NICHT löschen,
+  aber Anzeige-Check läuft immer über den aktuellen Plan → verhält sich korrekt.
+
+---
+
+## Phase 5 — Custom Domains / CNAME (≈ 5–8 Tage) · ENTERPRISE
+
+Der technisch riskanteste Teil — TLS für fremde Domains ist Infra-Arbeit.
+
+### 5.1 Datenbank (raw SQL)
+
+```sql
+CREATE TABLE "CustomDomain" (
+  "id"          TEXT PRIMARY KEY DEFAULT gen_random_uuid()::text,
+  "userId"      TEXT NOT NULL REFERENCES "User"("id") ON DELETE CASCADE,
+  "domain"      TEXT NOT NULL UNIQUE,     -- z. B. qr.kunde.de (lowercase)
+  "verifyToken" TEXT NOT NULL,            -- für TXT-Record
+  "verifiedAt"  TIMESTAMP(3),
+  "createdAt"   TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP
+);
+```
+
+### 5.2 Verifizierungs-Flow
+
+1. User trägt Domain ein → App zeigt zwei DNS-Records:
+   `TXT _qrmaster-verify.qr.kunde.de = <verifyToken>` und
+   `CNAME qr.kunde.de → qrmaster.net`.
+2. `POST /api/domains/[id]/verify` prüft beides via Node `dns.promises.resolveTxt/resolveCname`.
+3. Erst nach Verifizierung wird die Domain aktiv (verhindert Domain-Hijacking).
+
+### 5.3 Request-Routing in Next.js
+
+- `src/middleware.ts` (bzw. erweitern, falls vorhanden): wenn `Host` ≠
+  qrmaster.net/localhost → rewrite auf `/r/...` Namespace; auf
+  Fremd-Domains NUR `/r/[slug]` bedienen, alles andere → 404
+  (keine Login-/Marketing-Seiten unter Kundendomains, SEO/Sicherheit).
+- `/r/[slug]`-Route: bei Fremd-Host prüfen, dass der Slug-Owner die
+  verifizierte Domain besitzt — sonst 404 (verhindert, dass fremde QRs
+  über eine Kundendomain laufen).
+- Redis-Cache für Domain-Lookups (Hostname → userId, TTL 5 min).
+
+### 5.4 TLS — Caddy als Reverse Proxy (Docker-Deployment)
+
+`docker-compose.yml`: Caddy-Service vor `web`, Ports 80/443, Volume für Zertifikate.
+
+```caddyfile
+{
+  on_demand_tls {
+    ask http://web:3050/api/domains/check   # gibt 200 nur für verifizierte Domains
+  }
+}
+https:// {
+  tls { on_demand }
+  reverse_proxy web:3050
+}
+qrmaster.net, www.qrmaster.net {
+  reverse_proxy web:3050
+}
+```
+
+- Neuer interner Endpoint `GET /api/domains/check?domain=` → 200 wenn
+  verifiziert, sonst 403 (schützt vor Zertifikats-Missbrauch/Let's-Encrypt-Rate-Limits).
+- Falls qrmaster.net aktuell hinter Cloudflare/anderem Proxy läuft:
+  vorher klären, wie Port 443 heute terminiert wird — Caddy ersetzt bzw.
+  ergänzt das bestehende Setup. **Vor Umbau: aktuelles docker-compose.yml
+  und DNS-Setup prüfen** (größte Unbekannte in diesem Plan).
+
+### 5.5 UI
+
+Settings-Bereich „Custom Domains" (nur Enterprise): Domain hinzufügen,
+DNS-Anleitung mit Copy-Buttons, Verify-Button mit Status, Limit 3 Domains.
+QR-Detail/Generator: Kurz-URL-Anzeige nutzt die Custom Domain, wenn vorhanden.
+
+### 5.6 Verifikation
+
+Lokal mit `/etc/hosts`-Eintrag + Caddy testen; auf dem Server mit einer
+eigenen Test-Domain (z. B. `qr.timo-test.de`) den kompletten Flow durchspielen,
+bevor es an Kunden geht.
+
+---
+
+## Querschnittsthemen
+
+- **Downgrade-Verhalten**: Bei Plan-Downgrade (Stripe-Webhook) Webhooks über
+  Limit deaktivieren (nicht löschen), API-Keys behalten aber `api: false`
+  greift beim Auth-Check, Custom Domains deaktivieren. Ein zentraler
+  `enforceEntitlements(userId)` im Stripe-Webhook-Handler.
+- **Abuse**: API-Key-Erstellung rate-limiten; Webhook-URLs SSRF-geprüft;
+  Delivery-Payloads klein halten.
+- **Doku/SEO**: `/docs/api` + `/docs/webhooks` sind auch Marketing-Seiten
+  („QR Code API") — lohnt eigene SEO-Behandlung wie die Growth-Pages.
+
+## Zeitplan gesamt
+
+| Phase | Aufwand | Abhängig von |
+|---|---|---|
+| 1 Enterprise-Plan + Entitlements | 1–2 Tage | — |
+| 2 Webhooks | 3–4 Tage | Phase 1 (Gating) |
+| 3 Public API | 4–6 Tage | Phase 1; Payload-Format aus Phase 2 wiederverwenden |
+| 4 White-Label | 1–2 Tage | Phase 1 |
+| 5 Custom Domains | 5–8 Tage | Phase 1; Infra-Klärung (Proxy/DNS) vorab |
+| **Gesamt** | **≈ 14–22 Arbeitstage** | Launch von „Enterprise light" nach Phase 1–3 möglich |

docs/automations/README.md

@@ -0,0 +1,45 @@
+# Codex Automation System
+
+This folder defines reusable Codex workflows for QRMaster and GreenLens Pro.
+Use these as operating playbooks when asking Codex to run growth, SEO, content,
+or app-store work.
+
+## Active Automations
+
+### QRMaster
+
+1. `qrmaster-pr-seo-review.md`
+   - Purpose: review every SEO, landing page, and conversion change before it is merged.
+   - Primary plugins/tools: GitHub, Codex.
+   - Primary skills: `ai-seo`, `content-strategy`, `careful`, `qa`.
+
+2. `qrmaster-seo-sprint-machine.md`
+   - Purpose: plan and produce a weekly SEO sprint from keyword backlog to PR-ready work.
+   - Primary plugins/tools: GitHub, Coupler or CSV exports, Codex.
+   - Primary skills: `content-strategy`, `ai-seo`, `copywriting`, `qa`.
+
+3. `qrmaster-broken-link-cta-checker.md`
+   - Purpose: catch broken internal links and broken CTAs after direct `main`
+     branch changes.
+   - Primary plugins/tools: Codex, GitHub Actions or local npm script.
+   - Primary skills: `qa`, `ai-seo`.
+
+### GreenLens Pro
+
+1. `greenlens-pain-mining-machine.md`
+   - Purpose: turn reviews, comments, competitor messaging, and search questions into
+     product, ASO, and content opportunities.
+   - Primary plugins/tools: Codex, Gmail, Coupler or CSV exports.
+   - Primary skills: `app-store-aso`, `content-strategy`, `copywriting`.
+
+2. `greenlens-viral-slideshow-machine.md`
+   - Purpose: turn validated plant pains into TikTok, Instagram, and Canva-ready
+     slideshow assets.
+   - Primary plugins/tools: Canva, Codex, Gmail/Fyxer for creator briefs.
+   - Primary skills: `content-strategy`, `copywriting`, `ad-creative`, `app-store-aso`.
+
+## Operating Rule
+
+Do not automate publishing directly. Automate drafts, PRs, reviews, and packaged
+outputs first. A human should approve live SEO pages, store metadata, influencer
+messages, and paid/conversion changes.

docs/automations/greenlens-pain-mining-machine.md

@@ -0,0 +1,160 @@
+# GreenLens Pro Pain Mining Machine
+
+## Goal
+
+Turn real plant-owner pains into content, ASO, influencer, landing page, and
+product opportunities.
+
+## Why This Exists
+
+GreenLens Pro should be driven by what users actually worry about:
+yellow leaves, brown spots, root rot, overwatering, underwatering, pests,
+curling leaves, and not knowing what to do next.
+
+## Plugins And Skills
+
+| Need | Use |
+|---|---|
+| Review/comment exports | Coupler, CSV exports, Codex |
+| App Store optimization | `app-store-aso` skill |
+| Content clustering | `content-strategy` skill |
+| Copy and hooks | `copywriting` skill |
+| Support/outreach drafting | Gmail/Fyxer plugin |
+| Product issue creation | GitHub plugin |
+
+## Data Sources
+
+Use any available source, but label the source for every pain:
+
+- App Store competitor reviews
+- Google Play competitor reviews
+- Reddit plant-care threads
+- TikTok or Instagram comments
+- Google autocomplete or People Also Ask exports
+- Support emails or user feedback
+- Existing GreenLens analytics or onboarding responses
+
+## Pain Taxonomy
+
+Cluster each item into one primary category:
+
+- Yellow leaves
+- Brown spots
+- Root rot
+- Overwatering
+- Underwatering
+- Curling leaves
+- Drooping leaves
+- Pests
+- Light problems
+- Soil and repotting
+- Beginner confusion
+- Diagnosis trust
+- Price/paywall objection
+- App usability issue
+
+## Scoring Model
+
+Score each pain from 0-100:
+
+| Factor | Weight |
+|---|---:|
+| User urgency | 30 |
+| App fit | 25 |
+| Content virality | 20 |
+| ASO/search value | 15 |
+| Product learning value | 10 |
+
+Prioritize urgent, visual, diagnosis-driven pains where GreenLens can credibly
+help the user decide what to check next.
+
+## Weekly Output
+
+Produce:
+
+1. Top 20 pains.
+2. Top 10 social hooks.
+3. Top 5 ASO keyword opportunities.
+4. Top 5 blog or landing page ideas.
+5. Top 5 product issues or feature hypotheses.
+6. Top 10 influencer angles.
+
+## Codex Pain Mining Prompt
+
+```text
+Run the GreenLens Pro Pain Mining Machine.
+
+Use:
+- docs/automations/greenlens-pain-mining-machine.md
+- app-store-aso skill
+- content-strategy skill
+
+Input source: [reviews/comments/export/pasted text]
+Market: [US / DE / global]
+Platform focus: [iOS / Android / both]
+
+Tasks:
+1. Extract raw plant-owner pains.
+2. Cluster them into the GreenLens pain taxonomy.
+3. Score each pain by urgency, app fit, virality, ASO value, and product learning.
+4. Convert winners into:
+   - social hooks
+   - ASO keyword ideas
+   - blog/landing page ideas
+   - product issues
+   - influencer outreach angles
+
+Do not invent source quotes. If evidence is weak, label it as hypothesis.
+```
+
+## Output Template
+
+```markdown
+# GreenLens Pain Mining Report
+
+## Source Summary
+
+## Top Pains
+| Rank | Pain | Source | Score | Why it matters |
+|---|---|---|---:|---|
+
+## Hook Backlog
+
+## ASO Opportunities
+
+## Product Issues
+
+## Influencer Angles
+
+## Next Actions
+```
+
+## Product Issue Template
+
+```markdown
+Title: [Feature or improvement]
+
+User pain:
+[What the user is struggling with]
+
+Hypothesis:
+If GreenLens [change], users will [outcome].
+
+Acceptance criteria:
+- [criterion]
+- [criterion]
+- [criterion]
+
+Measurement:
+- activation
+- scan completion
+- paywall conversion
+- retention
+```
+
+## Success Criteria
+
+- Every recommendation traces back to a real pain or explicitly marked hypothesis.
+- Top pains can feed both ASO and social content.
+- Product issues are concrete enough for GitHub.
+

docs/automations/greenlens-viral-slideshow-machine.md

@@ -0,0 +1,139 @@
+# GreenLens Pro Viral Slideshow Machine
+
+## Goal
+
+Convert validated plant pains into TikTok, Instagram, and Canva-ready slideshow
+assets that drive awareness and app downloads.
+
+## Plugins And Skills
+
+| Need | Use |
+|---|---|
+| Creative generation | Canva plugin |
+| Hook and caption writing | `copywriting`, `ad-creative` skills |
+| Content planning | `content-strategy` skill |
+| ASO alignment | `app-store-aso` skill |
+| Creator briefs and outreach | Gmail/Fyxer plugin |
+
+## Required Input
+
+Use outputs from `greenlens-pain-mining-machine.md`:
+
+- pain cluster
+- urgency score
+- source evidence
+- target audience
+- desired CTA
+- app positioning angle
+
+## Content Pillars
+
+- Diagnosis before guessing
+- Overwatering mistakes
+- Yellow leaves
+- Brown spots
+- Root rot warnings
+- Beginner plant rescue
+- Plant symptoms explained
+- "Do not water yet" warnings
+- App scan/use-case demos
+
+## Slideshow Formula
+
+1. Hook: direct warning, contradiction, or curiosity.
+2. Problem: show the common wrong assumption.
+3. Explanation: simple plant-care reason.
+4. Check: what the user should inspect first.
+5. Risk: what happens if they guess.
+6. GreenLens bridge: scan or diagnose before acting.
+7. CTA: download, scan, or save.
+
+## Hook Patterns
+
+- "Do not water your plant before checking this."
+- "Yellow leaves do not always mean your plant is thirsty."
+- "Brown spots can mean more than sunburn."
+- "Your plant was warning you before it started dying."
+- "Overwatering often looks like underwatering."
+- "Scan before you guess."
+
+## Canva Direction
+
+Use GreenLens as a calm diagnosis-first plant app:
+
+- natural plant photography or close-up symptom imagery
+- clear readable overlay text
+- botanical but not decorative-only
+- show symptoms clearly
+- app screenshot or phone mockup only when it explains the action
+- avoid vague wellness aesthetics that do not show the plant problem
+
+## Codex Slideshow Prompt
+
+```text
+Run the GreenLens Pro Viral Slideshow Machine.
+
+Use:
+- docs/automations/greenlens-pain-mining-machine.md
+- docs/automations/greenlens-viral-slideshow-machine.md
+- app-store-aso skill
+- content-strategy skill
+- copywriting/ad-creative skills
+
+Input pain cluster: [pain]
+Audience: [beginner plant owners / plant rescue followers / houseplant collectors]
+CTA: [Download GreenLens Pro / Scan your plant / Save this checklist]
+Channel: [TikTok / Instagram / both]
+Quantity: [number]
+
+Return for each concept:
+1. hook
+2. 5-7 slide script
+3. visual direction per slide
+4. Canva prompt
+5. caption
+6. hashtags
+7. ASO keyword tie-in
+8. creator brief version
+
+Rules:
+- Keep claims educational, not medical/certain beyond evidence.
+- Do not promise perfect diagnosis.
+- Make the symptom visually inspectable.
+- The app CTA should feel like the next practical step, not a hard sell.
+```
+
+## Output Template
+
+```markdown
+# GreenLens Slideshow Pack: [Pain Cluster]
+
+## Concept 1: [Hook]
+
+### Slides
+1. [text] -- [visual]
+2. [text] -- [visual]
+3. [text] -- [visual]
+4. [text] -- [visual]
+5. [text] -- [visual]
+6. [text] -- [visual]
+7. [text] -- [visual]
+
+### Canva Prompt
+
+### Caption
+
+### Hashtags
+
+### ASO Tie-In
+
+### Creator Brief
+```
+
+## Quality Bar
+
+- The first slide must be understandable in under 2 seconds.
+- Every slide should be shorter than 12 words when possible.
+- The visual must show the symptom or action, not just a plant mood shot.
+- The final CTA should match the pain: scan, check, save, or download.
+

docs/automations/qrmaster-broken-link-cta-checker.md

@@ -0,0 +1,57 @@
+# QRMaster Broken Link + CTA Checker
+
+## Goal
+
+Catch broken internal links and broken conversion CTAs on `main`, especially
+after direct edits without a pull request.
+
+## What It Checks
+
+- Static internal `href` values in source files.
+- Static `router.push("/...")` destinations.
+- Internal links against known Next.js app routes and files in `public/`.
+- CTA-like links such as "Get started", "Create QR", "Start free",
+  "Generate QR", "Pricing", and "Upgrade".
+- Pages that appear to have no obvious CTA link.
+
+## Command
+
+```bash
+npm run check:links
+```
+
+The command prints a JSON report. It exits with a non-zero status if broken
+internal links or broken CTA links are found.
+
+## Known Limits
+
+- Dynamic CMS/blog slugs are allowed by prefix and not fully validated.
+- Runtime-only links built from variables are skipped.
+- External links are not checked by this local script.
+- This is a fast safety check, not a full crawl of the deployed website.
+
+## Codex Automation Prompt
+
+```text
+Run the QRMaster Broken Link + CTA Checker.
+
+Use:
+- docs/automations/qrmaster-broken-link-cta-checker.md
+- scripts/check-links-and-ctas.js
+
+Run npm run check:links. Review the JSON report and summarize:
+1. broken internal links
+2. broken CTA links
+3. important pages without obvious CTAs
+4. concrete fixes with file paths
+
+If the script fails, inspect the listed files and propose the smallest safe fix.
+Do not modify production configuration automatically.
+```
+
+## Success Criteria
+
+- No broken internal links.
+- No broken CTA links.
+- Important marketing, tool, and pricing pages have a clear CTA.
+

docs/automations/qrmaster-internal-revops-export.md

@@ -0,0 +1,131 @@
+# QR Master Internal RevOps Export API
+
+This endpoint exposes read-only QR Master admin/product data for trusted automations such as Hermes cron jobs.
+
+## Endpoint
+
+```http
+GET /api/internal/revops-export
+Authorization: Bearer <INTERNAL_API_SECRET>
+```
+
+The endpoint accepts `INTERNAL_API_SECRET` first, with `CRON_SECRET` as a fallback for compatibility.
+
+## Purpose
+
+QR Master only exports structured data. It does **not** perform AI analysis, web research, email drafting, or lead outreach.
+
+Hermes is responsible for:
+
+- calling this API on a schedule,
+- researching public websites/domains with its tools,
+- deciding which leads are worth manual outreach,
+- drafting personalized emails,
+- sending Timo an internal briefing,
+- never auto-sending messages to QR Master users.
+
+## Query Parameters
+
+| Parameter | Example | Notes |
+|---|---|---|
+| `range` | `24h`, `7d`, `30d`, `all` | Defaults to `24h`. |
+| `from` | `2026-06-30T00:00:00Z` | Optional explicit start. Overrides `range`. |
+| `to` | `2026-07-01T00:00:00Z` | Optional explicit end. Defaults to now if `from` is set. |
+| `limit` | `100` | User/lead limit. Defaults to 100, max 500. |
+| `allUsers` | `true` | Exports all users up to `limit`; otherwise exports users active/relevant in range. |
+
+## Example Calls
+
+Daily Hermes lead research context:
+
+```bash
+curl -H "Authorization: Bearer $INTERNAL_API_SECRET" \
+  "https://www.qrmaster.net/api/internal/revops-export?range=24h&limit=100"
+```
+
+Weekly progress context:
+
+```bash
+curl -H "Authorization: Bearer $INTERNAL_API_SECRET" \
+  "https://www.qrmaster.net/api/internal/revops-export?range=7d&limit=200"
+```
+
+Local development:
+
+```bash
+curl -H "Authorization: Bearer $INTERNAL_API_SECRET" \
+  "http://localhost:3050/api/internal/revops-export?range=24h"
+```
+
+## Response Shape
+
+Top-level fields:
+
+```json
+{
+  "ok": true,
+  "generatedAt": "2026-07-01T18:00:00.000Z",
+  "endpoint": "/api/internal/revops-export",
+  "range": {
+    "preset": "24h",
+    "from": "2026-06-30T18:00:00.000Z",
+    "to": "2026-07-01T18:00:00.000Z"
+  },
+  "overview": {},
+  "breakdowns": {},
+  "users": [],
+  "leads": [],
+  "newsletterSubscriptions": []
+}
+```
+
+Each exported user includes:
+
+- identity: `id`, `name`, `email`, `emailDomain`, `createdAt`, `updatedAt`
+- plan/subscription flags
+- attribution fields
+- onboarding fields
+- lifecycle scores and timestamps
+- aggregate stats
+- QR codes, content, public path, and scan summaries
+- integrations
+- recent lifecycle logs
+
+## Safety Rules for Hermes Jobs
+
+Hermes should treat this API as internal source data and follow these rules:
+
+1. Do not send outreach emails directly to leads.
+2. Send only an internal briefing/draft pack to Timo.
+3. Use public web research only when it improves personalization.
+4. Do not tell leads they were researched.
+5. Avoid creepy language; frame personalization around their QR Master activity and likely workflow.
+6. Never expose API secrets or raw sensitive internals in the briefing.
+7. Prefer business-use signals: QR content type, destination, scans, onboarding use case, domain, company website, landing path.
+
+## Suggested Hermes Cron Jobs
+
+### Daily QR Master Lead Research
+
+Schedule: daily, evening.
+
+Prompt should:
+
+1. call `/api/internal/revops-export?range=24h`,
+2. identify promising leads,
+3. research public company/domain signals,
+4. draft personalized outreach emails from Timo,
+5. send Timo an internal email briefing,
+6. never send emails to leads.
+
+### Weekly QR Master Progress Review
+
+Schedule: Sunday evening.
+
+Prompt should:
+
+1. call `/api/internal/revops-export?range=7d`,
+2. summarize users, QR creation, scans, activations, paid/upgrades,
+3. identify bottlenecks,
+4. suggest next-week goals,
+5. email Timo the review.

docs/automations/qrmaster-pr-seo-review.md

@@ -0,0 +1,163 @@
+# QRMaster PR SEO Review
+
+## Goal
+
+Catch SEO, conversion, content-quality, and technical issues before a QRMaster
+page change is merged.
+
+## Use When
+
+- A PR changes landing pages, tool pages, comparison pages, blog posts, metadata,
+  schema, sitemap behavior, internal links, pricing copy, or CTAs.
+- Codex generated new SEO pages from `marketing/programmatic-seo-top-50.md`.
+- Existing pages were refreshed from Google Search Console or keyword data.
+
+## Plugins And Skills
+
+| Need | Use |
+|---|---|
+| Diff and PR review | GitHub plugin |
+| Code/content inspection | Codex |
+| SEO/AEO review | `ai-seo` skill |
+| Content intent and cluster fit | `content-strategy` skill |
+| Build/lint verification | GitHub Actions, `qa` skill |
+| Careful merge decision | `careful` skill |
+
+## Review Checklist
+
+### 1. Technical SEO
+
+- Exactly one H1 on the rendered page.
+- Meta title exists and is specific to the page intent.
+- Meta title places the primary keyword near the start where natural.
+- Meta title stays under roughly 60 characters unless there is a clear reason.
+- Meta description exists and promises the right outcome.
+- Meta description includes the target keyword naturally, states the user benefit,
+  and stays concise enough to avoid likely truncation.
+- Canonical URL is correct.
+- Page is not accidentally noindexed.
+- FAQ, Article, Product, Breadcrumb, or HowTo schema is valid where used.
+- Sitemap and internal routing include the page where required.
+- No broken internal links or CTA links.
+- Language and locale are consistent.
+- URL slug is short, descriptive, hyphenated, and does not include stale dates.
+- Meaningful images have descriptive alt text and useful filenames where local
+  image handling allows it.
+- Large visual assets are compressed or already optimized.
+- Mobile layout is readable and CTAs are tappable.
+- The page does not introduce obvious Core Web Vitals risks.
+- Robots rules do not block important pages or desired AI/search crawlers.
+
+### 2. Search Intent
+
+- The first screen makes it obvious the page answers the target query.
+- The opening paragraph states the problem directly.
+- The page matches one primary intent only.
+- The content is not a generic rewrite of another QRMaster page.
+- The page includes concrete examples for its audience or use case.
+- The target keyword intent is labeled as informational, commercial,
+  transactional, or navigational.
+- The page covers the related subtopics a search or AI system would fan out to
+  for the main query.
+- Each H2/H3 section answers the heading directly in the first sentence before
+  adding background or nuance.
+
+### 3. QRMaster Conversion Fit
+
+- Primary CTA is visible early.
+- CTA copy matches the use case, not just generic "Get started".
+- The page explains why dynamic QR codes matter when links change after printing.
+- Scan analytics or tracking is mentioned when relevant.
+- Privacy/GDPR positioning is included where tracking is discussed.
+- The copy avoids unsupported claims.
+
+### 4. Internal Linking
+
+- New page links to the relevant money page:
+  - `/dynamic-qr-code-generator`
+  - `/qr-code-tracking`
+  - `/bulk-qr-code-generator`
+  - `/pricing`
+  - relevant `/tools/...` page
+- Existing related pages should link back to the new page.
+- Anchor text is natural and varied.
+
+### 5. AI Search Extractability
+
+- Important answer blocks are self-contained.
+- Comparison content uses tables where useful.
+- FAQ questions are written in natural user language.
+- Definitions answer the query in 40-60 words when possible.
+- Claims that need evidence include a source or are framed as product positioning.
+- Sections are focused on one question or subtopic at a time.
+- Bullet lists, tables, and short paragraphs are used where they improve
+  extraction and scanning.
+- The page can be cited by AI systems without relying on surrounding context.
+
+### 6. E-E-A-T And Quality
+
+- Content is accurate, current, and not copied from competitors.
+- Any competitor, pricing, legal, privacy, or compliance claim is verified or
+  clearly avoided.
+- The page adds QRMaster-specific value, examples, workflows, or product context.
+- The tone stays direct, useful, and trustworthy.
+
+## Codex Review Prompt
+
+```text
+Review this QRMaster PR as an SEO, conversion, and technical quality gate.
+
+Use:
+- docs/automations/qrmaster-pr-seo-review.md
+- .agents/product-marketing-context.md
+- marketing/programmatic-seo-top-50.md
+
+Check the diff for:
+1. technical SEO issues
+2. search intent mismatch
+3. weak or missing CTA
+4. duplicate/thin content
+5. missing internal links
+6. invalid or missing schema
+7. weak AI/agentic-search extractability
+8. missing visual/mobile/performance considerations
+9. build/lint risks
+
+Return findings ordered by severity. For each finding include:
+- file path
+- exact line if possible
+- why it matters
+- concrete fix
+
+Also include:
+- merge recommendation: approve / request changes
+- required follow-up tasks
+```
+
+## Review Output Format
+
+```markdown
+## QRMaster PR SEO Review
+
+Decision: Request changes
+
+### Findings
+1. [High] Missing internal link to `/dynamic-qr-code-generator`
+2. [Medium] CTA is too generic for the target intent
+3. [Low] FAQ question overlaps with another page
+
+### Required Fixes
+- Add contextual link from the "after printing" section to `/dynamic-qr-code-generator`.
+- Change CTA from "Get started" to "Create an editable QR code for your flyer".
+
+### Verification
+- Build:
+- Lint:
+- Link/schema check:
+```
+
+## Success Criteria
+
+- No high-severity SEO or conversion findings remain.
+- Build and lint pass.
+- The PR has a clear human approval before merge.

docs/automations/qrmaster-seo-sprint-2026-05-11.md

@@ -0,0 +1,158 @@
+# QRMaster SEO Sprint: Tracking and Analytics
+
+Run date: 2026-05-11
+Automation: QRMaster SEO Sprint Machine
+Status: Recommendation package only; do not publish without human approval.
+
+## Input Notes
+
+- Used `docs/automations/qrmaster-seo-sprint-machine.md`, `docs/automations/qrmaster-pr-seo-review.md`, `.agents/product-marketing-context.md`, `marketing/programmatic-seo-top-50.md`, `seo-plan-april.md`, and `seo-keywords.csv`.
+- `marketing/keyword-strategy-seo-plan.md` was not present in this worktree. `seo-plan-april.md` appears to be the local keyword strategy fallback and includes the same cluster-level keyword data.
+- Existing routing redirects selected legacy `/guide/...` paths to `/learn/...`, so this sprint should avoid creating duplicate guide URLs without a clear canonical/routing decision.
+
+## Cluster Scoring
+
+| Cluster | Product fit /30 | Commercial intent /25 | Differentiation /15 | Cluster leverage /10 | Winability /10 | Effort /10 | Score | Decision |
+|---|---:|---:|---:|---:|---:|---:|---:|---|
+| Tracking and analytics | 29 | 24 | 15 | 10 | 8 | 8 | 94 | Select |
+| Dynamic QR buying decision | 30 | 24 | 13 | 10 | 7 | 7 | 91 | Next best |
+| Bulk QR generation | 27 | 19 | 14 | 8 | 9 | 8 | 85 | Hold for later |
+| Commercial alternatives | 22 | 25 | 12 | 8 | 6 | 5 | 78 | Needs current competitor verification |
+| Restaurant/menu QR | 25 | 16 | 12 | 8 | 7 | 7 | 75 | Good vertical support, weaker immediate demand |
+| Custom/design QR | 20 | 18 | 9 | 8 | 8 | 8 | 71 | Tool-led, less differentiated |
+| Print reliability | 21 | 13 | 10 | 7 | 9 | 8 | 68 | Useful support content, weaker commercial pull |
+
+## Rationale
+
+Tracking and analytics is the highest-fit weekly cluster because it maps directly to QRMaster's differentiators: dynamic QR redirects, scan analytics, placement comparison, and privacy-first reporting. The keyword set includes `qr code tracking` at 1k-10k monthly volume with +900% 3-month YoY trend, `track qr code scans` with +900% 3-month trend, and `trackable qr code` with the highest CPC ceiling in the file at EUR 34.25. The cluster also has strong internal-link leverage into `/dynamic-qr-code-generator`, `/qr-code-analytics`, `/qr-code-tracking`, `/qr-code-for-marketing-campaigns`, pricing, and use-case pages.
+
+## Selected Work
+
+| Type | URL | Score | Reason |
+|---|---|---:|---|
+| Refresh | `/qr-code-tracking` | 94 | Money page for `qr code tracking`, `track qr code scans`, and `trackable qr code`; already has schema but should strengthen privacy and placement examples. |
+| Refresh | `/qr-code-analytics` | 90 | Needs clearer separation from tracking: analytics should own dashboard interpretation, ROI, and performance insights. |
+| Refresh | `/blog/trackable-qr-codes` | 88 | Existing support article should capture `trackable qr code` and link strongly to `/qr-code-tracking`. |
+| Refresh | `/blog/utm-parameter-qr-codes` | 86 | Existing support article should capture fan-out intent around GA4, UTM naming, placement comparison, and offline attribution. |
+| New support page | `/use-cases/qr-codes-for-review-collection` | 86 | Existing backlog item with natural tracking CTA; use as a measurable review funnel page, not a generic Google reviews tool duplicate. |
+
+## Keyword Intent And Fan-Out
+
+| URL | Primary keyword | Intent | Fan-out subtopics |
+|---|---|---|---|
+| `/qr-code-tracking` | `qr code tracking` | Commercial | What can be tracked, static vs dynamic tracking, scan count vs unique scans, device/location/time context, privacy/GDPR, placement comparison, UTM pairing, dashboard workflow, pricing limits. |
+| `/qr-code-analytics` | `qr code analytics` | Commercial | Analytics dashboard, ROI interpretation, campaign attribution, useful metrics vs vanity metrics, offline-to-online measurement, reporting cadence, route naming, export/share needs. |
+| `/blog/trackable-qr-codes` | `trackable qr code` | Informational-commercial | Definition, how tracking works, dynamic redirect layer, privacy limits, examples by placement, pros/cons, setup checklist, when not to track. |
+| `/blog/utm-parameter-qr-codes` | `qr code UTM tracking` | Informational | GA4 source/medium/campaign/content conventions, examples for flyers/events/packaging, common mistakes, naming templates, QR destination testing. |
+| `/use-cases/qr-codes-for-review-collection` | `QR codes for review collection` | Commercial | Google review link workflow, in-store placement, happy-path routing, feedback triage, scan tracking, QR privacy, dynamic destination updates. |
+
+## 2026 On-Page And Agentic-Search Rules
+
+- Titles/H1s should put the target keyword near the start:
+  - `/qr-code-tracking`: `QR Code Tracking: Track QR Code Scans`
+  - `/qr-code-analytics`: `QR Code Analytics: Measure Offline Campaigns`
+  - `/blog/trackable-qr-codes`: `Trackable QR Codes: What You Can Measure`
+  - `/blog/utm-parameter-qr-codes`: `QR Code UTM Tracking: GA4 Setup Guide`
+  - `/use-cases/qr-codes-for-review-collection`: `QR Codes for Review Collection`
+- Each H2 should start with a direct answer in the first sentence.
+- Add compact tables for `static vs dynamic`, `tracking vs analytics`, and `UTM examples by placement`.
+- Add FAQ schema to refreshed informational pages where the existing blog system supports it; preserve SoftwareApplication and HowTo schema on money pages.
+- Use self-contained answer blocks of roughly 40-60 words for definitions and "can you track..." questions.
+- Visuals should be meaningful: dashboard screenshot/mockup, placement comparison example, UTM naming table, and review-flow diagram.
+- Robots/indexing: current `robots.ts` allows major search/AI crawlers and disallows private app/API paths. Keep these pages indexed, sitemap-included, and canonicalized to their final URLs.
+- Mobile/speed risks: avoid heavy dashboard imagery; use compressed static images and keep tables horizontally readable on mobile.
+
+## Recommended New Page
+
+### `/use-cases/qr-codes-for-review-collection`
+
+Purpose: Create a commercially useful support page for restaurants, cafes, retail, hotels, and service businesses that want measurable review capture.
+
+Required sections:
+
+1. Direct answer: a review-collection QR code sends satisfied customers to the right review or feedback flow and lets teams measure which physical prompts get scanned.
+2. Workflow: in-store sign, receipt, table card, counter card, packaging insert.
+3. Dynamic vs static: use dynamic if the review platform, routing rule, or offer changes.
+4. Tracking angle: compare scan volume by placement, store, or campaign.
+5. Privacy note: describe scan analytics without promising personally identifiable tracking.
+6. CTA: `Create a trackable review QR code` to `/qr-code-tracking` or `/signup`.
+7. Internal links: `/tools/google-review-qr-code`, `/qr-code-tracking`, `/dynamic-qr-code-generator`, `/restaurants`, `/use-cases/feedback-qr-codes`.
+8. Schema: FAQPage + BreadcrumbList; consider HowTo if step-by-step content is included.
+
+## Recommended Page Refreshes
+
+### `/qr-code-tracking`
+
+- Strengthen first-screen answer: "QR code tracking uses a dynamic redirect to record scan time, device context, and approximate location before sending the scanner to the final destination."
+- Add a privacy-first section explaining hashed/anonymized IP positioning from QRMaster.
+- Add a table: "What QRMaster tracks / what it does not track."
+- Add examples for flyer, menu, event booth, packaging, and review collection.
+- Link to `/qr-code-analytics`, `/blog/utm-parameter-qr-codes`, `/reprint-calculator`, `/pricing`, and the new review-collection page.
+
+### `/qr-code-analytics`
+
+- Separate from tracking: tracking collects scan events; analytics helps interpret placement and campaign performance.
+- Add an "analytics questions" table: which placement worked, when scans peaked, which destination converted, what to reprint.
+- Add a section on useful metrics vs vanity metrics.
+- Link back to `/qr-code-tracking`, `/qr-code-for-marketing-campaigns`, `/use-cases/flyer-qr-codes`, `/use-cases/packaging-qr-codes`, and `/pricing`.
+
+### `/blog/trackable-qr-codes`
+
+- Refresh title/meta around `trackable qr code`.
+- Add a 40-60 word definition block near the top.
+- Update FAQ to include "Can a static QR code be tracked?", "Are trackable QR codes GDPR-friendly?", and "Do trackable QR codes need a redirect?"
+- Link early to `/qr-code-tracking` with anchor `track QR code scans`.
+
+### `/blog/utm-parameter-qr-codes`
+
+- Add a QR-specific UTM template table by placement.
+- Add GA4 naming convention examples.
+- Clarify when to use separate QR codes versus one QR with different `utm_content` values.
+- Link to `/qr-code-analytics` and `/qr-code-tracking`.
+
+## Internal-Link Plan
+
+| Source | Destination | Anchor |
+|---|---|---|
+| `/dynamic-qr-code-generator` | `/qr-code-tracking` | `track QR code scans` |
+| `/dynamic-qr-code-generator` | `/qr-code-analytics` | `QR code analytics dashboard` |
+| `/qr-code-tracking` | `/qr-code-analytics` | `interpret QR scan analytics` |
+| `/qr-code-tracking` | `/blog/utm-parameter-qr-codes` | `use UTMs with QR codes` |
+| `/qr-code-analytics` | `/qr-code-tracking` | `collect QR scan data` |
+| `/qr-code-analytics` | `/qr-code-for-marketing-campaigns` | `measure offline QR campaigns` |
+| `/blog/trackable-qr-codes` | `/qr-code-tracking` | `QR code tracking` |
+| `/blog/utm-parameter-qr-codes` | `/qr-code-analytics` | `QR code analytics` |
+| `/use-cases/feedback-qr-codes` | `/use-cases/qr-codes-for-review-collection` | `review collection QR codes` |
+| `/tools/google-review-qr-code` | `/use-cases/qr-codes-for-review-collection` | `review collection workflow` |
+
+## PR Plan
+
+1. Add the new review-collection use-case content in the existing use-case page data/routing pattern.
+2. Refresh copy, FAQ, metadata, and link sections on `/qr-code-tracking` and `/qr-code-analytics`.
+3. Refresh the two support blog entries without creating duplicate `/guide/...` pages.
+4. Add internal links in both directions from money pages, blog support pages, and relevant use-case/tool pages.
+5. Update sitemap data only if the new page is not automatically included by the existing use-case sitemap mapping.
+6. Run the PR SEO review using `docs/automations/qrmaster-pr-seo-review.md`.
+
+## Verification Checklist
+
+- One H1 per rendered page.
+- Primary keyword appears naturally in title, H1, intro, and metadata.
+- Canonical URL points to the final public URL.
+- Page is public in middleware and included in sitemap.
+- No duplicate `/guide/...` URL is introduced without canonical strategy.
+- FAQ/schema validates where used.
+- Internal links resolve and use natural anchor text.
+- Each section begins with a direct answer.
+- Mobile tables do not overflow unreadably.
+- Visual assets are compressed and include descriptive alt text.
+- Robots rules continue to allow target pages and desired search/AI crawlers.
+- Build/lint pass before PR.
+
+## Social And Outreach Follow-Up
+
+- LinkedIn post: "Most QR campaigns fail because teams only count scans. The useful question is which printed placement created action."
+- X thread: "QR tracking setup in 5 steps: dynamic QR, placement naming, UTM convention, dashboard review, reprint decision."
+- Short demo video: show flyer A vs flyer B scan comparison and a destination update without reprinting.
+- Outreach angle for marketing newsletters: "Offline attribution checklist for QR campaigns."
+- Community answer target: questions around "Can I track a static QR code?" and "How do I track QR codes in GA4?"

docs/automations/qrmaster-seo-sprint-machine.md

@@ -0,0 +1,211 @@
+# QRMaster SEO Sprint Machine
+
+## Goal
+
+Run a weekly controlled SEO sprint that chooses the right pages, creates or
+updates them, adds internal links, and ships through a reviewed PR.
+
+## Why This Exists
+
+QRMaster should not publish random daily content. The goal is to build
+commercially useful SEO clusters around dynamic QR codes, tracking, tool pages,
+comparison pages, and industry workflows.
+
+## Plugins And Skills
+
+| Need | Use |
+|---|---|
+| Repository changes and PRs | GitHub plugin |
+| Keyword and performance imports | Coupler, CSV exports, Google Search Console export |
+| Page creation and refactors | Codex |
+| SEO/content planning | `content-strategy`, `ai-seo` skills |
+| Copy generation | `copywriting` skill |
+| Verification | GitHub Actions, `qa` skill |
+
+## Weekly Inputs
+
+- Current keyword backlog:
+  - `marketing/programmatic-seo-top-50.md`
+  - `marketing/keyword-strategy-seo-plan.md`
+  - `seo-keywords.csv`
+- Existing product positioning:
+  - `.agents/product-marketing-context.md`
+- Performance data when available:
+  - Google Search Console export
+  - signup/conversion report
+  - top landing pages by traffic
+- Sprint focus:
+  - Dynamic QR
+  - Tracking/analytics
+  - Restaurant/menu QR
+  - Print marketing
+  - Bulk QR
+  - Comparison/alternatives
+
+## Scoring Model
+
+Score each candidate from 0-100:
+
+| Factor | Weight |
+|---|---:|
+| Product fit | 30 |
+| Commercial intent | 25 |
+| Differentiation potential | 15 |
+| Cluster leverage | 10 |
+| Search winability | 10 |
+| Production effort | 10 |
+
+Do not select pages only because they have volume. Prefer pages where QRMaster
+can naturally sell dynamic QR, scan tracking, bulk creation, or privacy-first
+analytics.
+
+## On-Page And Agentic Search Rules
+
+Every new or refreshed page must follow these checks before review:
+
+- Identify the primary keyword and intent type: informational, commercial,
+  transactional, or navigational.
+- Cover the query fan-out: list the related subtopics an AI/search system would
+  need to answer the query well.
+- Put the primary keyword naturally near the start of the title tag and H1.
+- Keep title tags under roughly 60 characters when possible.
+- Keep meta descriptions concise, benefit-led, and naturally keyword-aligned.
+- Use one clear H1 and a logical H2/H3 hierarchy.
+- Start each section with a direct answer to the heading.
+- Use short paragraphs, bullets, and comparison tables where they improve
+  scanning and AI extraction.
+- Add descriptive internal links with natural anchor text.
+- Add useful visuals, screenshots, or examples where the page needs them.
+- Add schema when the page type supports it.
+- Check mobile readability, CTA tap targets, and obvious speed risks.
+- Verify robots/indexing assumptions for important SEO pages.
+
+## Default Weekly Sprint
+
+1. Select one cluster.
+2. Create 3 new pages.
+3. Refresh 2 existing pages with impressions, weak CTR, or position 8-20.
+4. Add internal links in both directions.
+5. Create one GitHub PR.
+6. Run `qrmaster-pr-seo-review.md`.
+7. Produce social and outreach drafts after the PR is ready.
+
+## Page Types
+
+### Tool Pages
+
+Examples:
+
+- `/tools/pdf-qr-code`
+- `/tools/vcard-qr-code`
+- `/tools/wifi-qr-code`
+- `/tools/menu-qr-code`
+- `/tools/google-review-qr-code`
+
+Must include:
+
+- direct tool-oriented hero
+- use cases
+- dynamic vs static guidance
+- FAQ
+- CTA into the app
+- internal links to related use cases
+
+### Industry Workflow Pages
+
+Examples:
+
+- `/qr-code-for/restaurants/menu-updates`
+- `/qr-code-for/events/check-in`
+- `/qr-code-for/real-estate/open-house-flyers`
+
+Must include:
+
+- specific audience pain
+- example workflow
+- print-risk or tracking angle
+- CTA matching the industry
+
+### Comparison Pages
+
+Examples:
+
+- `/compare/dynamic-vs-static-qr-codes`
+- `/compare/free-vs-paid-qr-code-generator`
+- `/compare/flowcode-alternative`
+
+Must include:
+
+- comparison table
+- fair positioning
+- current facts verified before publishing
+- "who this is best for" section
+- CTA to the best-fit QRMaster feature
+
+## Codex Sprint Prompt
+
+```text
+Run the QRMaster SEO Sprint Machine.
+
+Use:
+- docs/automations/qrmaster-seo-sprint-machine.md
+- docs/automations/qrmaster-pr-seo-review.md
+- .agents/product-marketing-context.md
+- marketing/programmatic-seo-top-50.md
+- marketing/keyword-strategy-seo-plan.md
+
+Sprint focus: [cluster]
+Target output: 3 new SEO/tool pages, 2 page refreshes, internal links, and one PR-ready diff.
+
+Rules:
+- Follow existing code and page patterns.
+- Do not invent competitor pricing or claims.
+- Prioritize dynamic QR, edit-after-print, analytics, bulk, and privacy-first messaging.
+- Add metadata, FAQ/schema where local patterns support it.
+- Apply the on-page and agentic search rules from the automation doc.
+- Keep pages specific enough to avoid thin programmatic content.
+- Run build/lint or explain why not.
+
+Return:
+1. selected pages and scoring
+2. target keyword, intent, and fan-out subtopics per page
+3. files changed
+4. internal links added
+5. PR summary
+6. SEO review status
+7. follow-up social/outreach package
+```
+
+## Sprint Output Template
+
+```markdown
+# QRMaster SEO Sprint: [Cluster]
+
+## Selected Work
+| Type | URL | Score | Reason |
+|---|---|---:|---|
+
+## Keyword Intent And Fan-Out
+
+| URL | Primary keyword | Intent | Fan-out subtopics |
+|---|---|---|---|
+
+## New Pages
+
+## Updated Pages
+
+## Internal Links
+
+## PR Summary
+
+## Verification
+
+## Social/Outreach Follow-Up
+```
+
+## Success Criteria
+
+- Each new page has clear commercial intent or cluster leverage.
+- Refreshed pages have a measurable reason for the update.
+- Internal links support money pages.
+- PR SEO Review passes before merge.

docs/automations/runs/qrmaster-seo-sprint-2026-06-22.md

@@ -0,0 +1,255 @@
+# QRMaster SEO Sprint: Dynamic QR Buying Decision
+
+Run date: 2026-06-22
+Automation: QRMaster SEO Sprint Machine
+Mode: recommendation and PR-ready tasks only, no publishing
+
+## Inputs Used
+
+- `docs/automations/qrmaster-seo-sprint-machine.md`
+- `docs/automations/qrmaster-pr-seo-review.md`
+- `.agents/product-marketing-context.md`
+- `marketing/programmatic-seo-top-50.md`
+- `seo-keywords.csv`
+- `src/lib/comparison-pages.ts`
+- `src/lib/guide-pages.ts`
+- `src/app/sitemap.ts`
+- `src/app/robots.ts`
+
+Missing requested input: `marketing/keyword-strategy-seo-plan.md` is not present in this worktree. Scoring used `seo-keywords.csv`, `marketing/programmatic-seo-top-50.md`, and repo inspection instead.
+
+## PLAN
+
+1. Understand the task: run a controlled weekly SEO sprint without publishing.
+2. Identify affected files: pSEO page data, route templates, sitemap, robots, and target money pages.
+3. Design the implementation: select one cluster and expose only approved pages through allowlisted routes.
+4. Implement step-by-step: prepare PR-ready tasks, not direct changes.
+5. Verify results: use the PR SEO review checklist before merge.
+
+## Cluster Selection
+
+Selected cluster: Dynamic QR buying decision.
+
+Rationale: This cluster owns the highest commercial decision point for QR Master: static/free one-off generation versus dynamic, editable, trackable QR workflows. It also avoids repeating last week's tracking package while still reusing the same route/template investment. The top two backlog entries are both in this cluster, and their content already exists in `src/lib/comparison-pages.ts` but is not exposed because there is no `/compare/[slug]` route.
+
+Important implementation note: `src/lib/comparison-pages.ts` and `src/lib/guide-pages.ts` contain more records than this sprint should publish. The PR should use an explicit published-slug allowlist or `status` field so only the selected pages become reachable and indexable.
+
+## Candidate Cluster Scores
+
+Scores use the automation model: product fit 30, commercial intent 25, differentiation potential 15, cluster leverage 10, search winability 10, production effort 10.
+
+| Cluster | Product fit | Commercial intent | Differentiation | Cluster leverage | Winability | Effort | Score | Decision |
+|---|---:|---:|---:|---:|---:|---:|---:|---|
+| Dynamic QR buying decision | 30 | 24 | 14 | 10 | 8 | 8 | 94 | Select |
+| Tracking and analytics | 29 | 23 | 14 | 9 | 8 | 7 | 90 | Defer, already selected last run |
+| Bulk QR and spreadsheet workflows | 26 | 21 | 12 | 8 | 9 | 8 | 84 | Next after route scaffold |
+| Print reliability | 23 | 15 | 12 | 8 | 9 | 8 | 75 | Support cluster |
+| Restaurant/menu QR | 25 | 18 | 11 | 8 | 6 | 7 | 75 | Hold for industry sprint |
+
+## Selected Work
+
+| Type | URL | Score | Reason |
+|---|---|---:|---|
+| New comparison page | `/compare/dynamic-vs-static-qr-codes` | 94 | Highest leverage concept page. Explains why QR Master's dynamic/edit-after-print value exists. |
+| New comparison page | `/compare/free-vs-paid-qr-code-generator` | 91 | Bottom-funnel upgrade page. Connects free QR intent to pricing, dynamic limits, analytics, and reprint risk. |
+| New guide page | `/guide/dynamic-qr-code-best-practices` | 88 | Strategic support guide. Helps AI/search systems connect dynamic QR setup, naming, tracking, and print workflows. |
+| Refresh existing page | `/dynamic-qr-code-generator` | 92 | Money page. Strong volume in CSV: `dynamic qr code`, `dynamic qr code generator`, `create dynamic qr code`, `dynamic qr generator`, and `dynamic qr code creator` are each 1k-10k. |
+| Refresh existing page | `/reprint-calculator` | 84 | Conversion-support page. Should quantify the central "static QR reprint cost" argument for comparison pages. |
+
+## Keyword Intent And Fan-Out
+
+| URL | Primary keyword | Intent | Fan-out subtopics |
+|---|---|---|---|
+| `/compare/dynamic-vs-static-qr-codes` | dynamic vs static QR codes | Commercial investigation | Can static QR codes be edited, what dynamic QR tracking means, reprint risk, when static is enough, print campaigns, menus, packaging, privacy-aware analytics, cost tradeoff, migration from static to dynamic. |
+| `/compare/free-vs-paid-qr-code-generator` | free vs paid QR code generator | Commercial investigation | Free static generators, dynamic QR limits, paid plan features, tracking, branding, expiry risk, scan limits, pricing, hidden reprint cost, business use cases, when free is enough. |
+| `/guide/dynamic-qr-code-best-practices` | dynamic QR code best practices | Informational to commercial | Naming conventions, campaign grouping, editable destinations, scan tracking setup, QR placement, UTM usage, print testing, destination updates, privacy/GDPR framing, internal reporting. |
+| `/dynamic-qr-code-generator` | dynamic QR code generator | Transactional | Create dynamic QR, editable QR code, free dynamic QR limits, tracking, update after print, branding, plan limits, static vs dynamic, use cases, schema-backed FAQ. |
+| `/reprint-calculator` | QR code reprint cost calculator | Commercial utility | Static QR risk, reprint math, edit-after-print savings, campaign examples, pricing comparison, calculator assumptions, what to do after calculating savings. |
+
+## Recommended New Pages
+
+### 1. `/compare/dynamic-vs-static-qr-codes`
+
+PR status: content data exists in `src/lib/comparison-pages.ts`; needs route/template, metadata, schema, sitemap entry, and internal links.
+
+Title: `Dynamic vs Static QR Codes: Which to Use`
+
+H1: `Dynamic vs Static QR Codes`
+
+Meta description: `Compare dynamic and static QR codes for editability, scan tracking, reprint risk, and business workflows before you print.`
+
+Slug: `/compare/dynamic-vs-static-qr-codes`
+
+Direct answer: Static QR codes lock the destination into the image. Dynamic QR codes route through a managed link, so teams can change the destination and measure scans after the QR code has been printed.
+
+Schema opportunities: `Article`, `FAQPage`, `BreadcrumbList`, and `ItemList` for the comparison table.
+
+Visual: Responsive comparison table plus a simple redirect-flow diagram: printed QR -> QR Master redirect -> current destination.
+
+### 2. `/compare/free-vs-paid-qr-code-generator`
+
+PR status: content data exists in `src/lib/comparison-pages.ts`; needs route/template, metadata, schema, sitemap entry, and internal links.
+
+Title: `Free vs Paid QR Code Generator`
+
+H1: `Free vs Paid QR Code Generator`
+
+Meta description: `See when a free QR generator is enough and when paid dynamic QR features, tracking, branding, and reprint savings are worth it.`
+
+Slug: `/compare/free-vs-paid-qr-code-generator`
+
+Direct answer: A free QR generator is usually enough for one permanent static link. A paid QR platform becomes worth it when the code is printed at scale, tied to campaigns, or needs editing and analytics later.
+
+Schema opportunities: `Article`, `FAQPage`, `BreadcrumbList`, and `ItemList`.
+
+Visual: "Free is enough when..." versus "Paid is worth it when..." table.
+
+### 3. `/guide/dynamic-qr-code-best-practices`
+
+PR status: content data exists in `src/lib/guide-pages.ts`; needs route/template, metadata, schema, sitemap entry, and internal links.
+
+Title: `Dynamic QR Code Best Practices`
+
+H1: `Dynamic QR Code Best Practices`
+
+Meta description: `Plan dynamic QR codes with better naming, tracking, print testing, privacy checks, and update workflows before campaigns go live.`
+
+Slug: `/guide/dynamic-qr-code-best-practices`
+
+Direct answer: The best dynamic QR workflows use clear naming, stable print placement, measurable destinations, and disciplined update management after the code is in circulation.
+
+Schema opportunities: `Article`, `HowTo`, `FAQPage`, and `BreadcrumbList`.
+
+Visual: Checklist or workflow graphic for naming -> print test -> publish -> monitor -> update.
+
+## Recommended Page Refreshes
+
+### `/dynamic-qr-code-generator`
+
+Refresh rationale: This is the money page for the cluster and already ranks against high-volume dynamic QR terms. It has strong answer-first structure, schema, FAQs, and internal links, but should be tightened before more internal equity points to it.
+
+PR-ready tasks:
+
+- Shorten title under roughly 60 characters if possible. Current absolute title is likely too long.
+- Verify current plan limits against product/business truth before publishing. Product context says Free includes 8 dynamic codes, but app copy often says 3 active dynamic codes.
+- Re-check competitor pricing and claims before keeping comparison table language.
+- Replace or verify weak research/stat blocks. Avoid unsupported numbers such as broad print-error claims unless a reliable source is attached.
+- Add contextual links to the two new comparison pages and the new best-practices guide.
+- Ensure each major H2 starts with a direct answer in the first sentence.
+
+### `/reprint-calculator`
+
+Refresh rationale: This page supports the strongest conversion argument for dynamic QR: printed assets should not become waste when URLs change.
+
+PR-ready tasks:
+
+- Update title to target the query directly: `QR Code Reprint Cost Calculator`.
+- Add an answer-first block explaining when static QR reprints become expensive.
+- Add FAQ content and `FAQPage` schema for "Can I edit a QR code after printing?", "How much do QR reprints cost?", and "When is dynamic QR worth it?"
+- Link to `/compare/dynamic-vs-static-qr-codes`, `/compare/free-vs-paid-qr-code-generator`, `/dynamic-qr-code-generator`, and `/pricing`.
+- Add visible assumptions around calculator inputs so AI/search systems can cite the methodology.
+- Keep calculator lightweight. Do not add heavy chart libraries or large images.
+
+## Internal-Link Plan
+
+Add links from:
+
+- `/dynamic-qr-code-generator` to `/compare/dynamic-vs-static-qr-codes`, `/compare/free-vs-paid-qr-code-generator`, `/guide/dynamic-qr-code-best-practices`, and `/reprint-calculator`.
+- `/reprint-calculator` to `/compare/dynamic-vs-static-qr-codes`, `/dynamic-qr-code-generator`, and `/pricing`.
+- `/qr-code-tracking` to `/compare/dynamic-vs-static-qr-codes` where dynamic tracking is explained.
+- `/qr-code-analytics` to `/guide/dynamic-qr-code-best-practices` where naming and placement discipline are discussed.
+- `/pricing` to `/compare/free-vs-paid-qr-code-generator` with anchor text like `free vs paid QR generator`.
+- `/tools/url-qr-code` to `/compare/dynamic-vs-static-qr-codes` if the tool page discusses static output or destination changes.
+
+Add links from new pages to:
+
+- `/dynamic-qr-code-generator`
+- `/qr-code-tracking`
+- `/qr-code-analytics`
+- `/reprint-calculator`
+- `/pricing`
+- `/guide/dynamic-qr-code-best-practices`
+
+Anchor text should be natural and varied: `dynamic QR code generator`, `track QR code scans`, `compare free and paid QR generators`, `estimate reprint savings`, `dynamic QR best practices`.
+
+## PR Plan
+
+1. Add controlled route templates:
+   - `src/app/(main)/compare/[slug]/page.tsx`
+   - `src/app/(main)/guide/[slug]/page.tsx`
+2. Add published-slug allowlists:
+   - comparisons: `dynamic-vs-static-qr-codes`, `free-vs-paid-qr-code-generator`
+   - guides: `dynamic-qr-code-best-practices`
+3. Route behavior:
+   - `generateStaticParams` returns only published slugs.
+   - Unknown or unpublished slugs call `notFound()`.
+   - Metadata uses page title, description, canonical path, Open Graph, and no accidental `noindex`.
+4. Template behavior:
+   - One H1.
+   - Direct answer block near top.
+   - H2/H3 sections start with answer-first language.
+   - Responsive comparison tables with horizontal overflow on mobile.
+   - CTA blocks point to selected commercial pages.
+5. Schema:
+   - Comparison pages: `Article`, `FAQPage`, `BreadcrumbList`, `ItemList`.
+   - Guide page: `Article`, `HowTo`, `FAQPage`, `BreadcrumbList`.
+6. Sitemap:
+   - Add selected `/compare/...` and `/guide/...` URLs only.
+   - Use current sprint date for `lastModified`.
+7. Refresh pages:
+   - Update `/dynamic-qr-code-generator`.
+   - Update `/reprint-calculator`.
+8. Review gate:
+   - Run the PR SEO review from `docs/automations/qrmaster-pr-seo-review.md`.
+   - Do not merge until high-severity SEO/conversion findings are resolved.
+
+## Robots And Indexing Assumptions
+
+- `src/app/robots.ts` currently allows public pages and explicitly allows `OAI-SearchBot`, `GPTBot`, `ChatGPT-User`, `PerplexityBot`, `ClaudeBot`, `anthropic-ai`, and `Google-Extended` while blocking private paths.
+- Selected pages should be indexable, canonicalized, and included in `sitemap.ts`.
+- Unselected `comparisonPages` and `guidePages` records should remain unpublished until a human approves them.
+- For pages that should not appear, prefer route allowlisting or `notFound()` rather than relying on robots.txt.
+
+External guidance checked:
+
+- Google SEO Starter Guide: https://developers.google.com/search/docs/fundamentals/seo-starter-guide
+- Google AI features and your website: https://developers.google.com/search/docs/appearance/ai-features
+- Google structured data introduction: https://developers.google.com/search/docs/appearance/structured-data/intro-structured-data
+- Google robots.txt guidance: https://developers.google.com/search/docs/crawling-indexing/robots/intro
+- OpenAI crawler overview: https://developers.openai.com/api/docs/bots
+- OpenAI publisher/developer FAQ for ChatGPT search inclusion: https://help.openai.com/en/articles/12627856-publishers-and-developers-faq
+
+## Mobile, Visual, And Speed Checks
+
+- Keep comparison tables responsive with `overflow-x-auto` and a minimum readable width.
+- Avoid new heavyweight images unless they are compressed and useful.
+- Use existing lightweight cards, tables, and schema components.
+- Validate CTA tap targets on mobile.
+- Do not add animated hero assets or charting libraries for this sprint.
+
+## Verification Checklist
+
+- `npm run lint`
+- `npm run build`
+- Confirm exactly one H1 per selected page.
+- Confirm metadata title, description, canonical, and Open Graph are set.
+- Confirm selected pages are in `sitemap.ts`.
+- Confirm unpublished pSEO records are not reachable.
+- Confirm robots rules do not block selected public pages.
+- Validate JSON-LD output for comparison and guide pages.
+- Check internal links and CTA destinations manually.
+- Check mobile rendering for comparison tables and CTA blocks.
+- Run the QRMaster PR SEO Review checklist and request changes for any high-severity finding.
+
+## Follow-Up Social And Outreach Ideas
+
+1. LinkedIn post: "Static QR codes are cheap until the printed URL changes." Link to the dynamic-vs-static comparison.
+2. X thread: "Free QR generators are enough for one-off links. Here is when paid dynamic QR becomes cheaper." Link to free-vs-paid.
+3. Quora answer: "Can you change a QR code after printing?" Explain static vs dynamic and link to the comparison.
+4. Short YouTube/Loom: show a printed flyer scenario, change the QR destination, and show scan tracking.
+5. Outreach pitch: send the reprint calculator to print shops, small agencies, and restaurant consultants as a utility they can reference.
+
+## Hold For Future Sprints
+
+- Tracking and analytics cluster from the 2026-06-15 run remains valid, but do not duplicate the same package. The same guide route scaffold can later expose `/guide/how-to-track-qr-code-scans`, `/guide/how-to-use-utm-with-qr-codes`, and `/guide/qr-code-gdpr`.
+- Next good cluster after this PR: Bulk QR and spreadsheet workflows, because `bulk qr code generator`, `mass qr code generator`, and `qr code generator excel` show strong search fit and low competition in `seo-keywords.csv`.

docs/automations/social-accounts-and-jobs.md

@@ -0,0 +1,106 @@
+# Social Accounts
+
+## Account Mapping
+| Brand | Facebook Page | Facebook Page ID | Instagram Business Account | Instagram User ID | X/Twitter Account | Target Username |
+| --- | --- | --- | --- | --- | --- | --- |
+| QRMaster.net | QRMaster.net | 884792004727212 | QRMaster.net | 17841480094799114 | TIMO_QRMASTER | qrmaster |
+| GreenLens Pro | GreenLens Pro | 1150261294842586 | GreenLens Pro | 17841422012320229 | greenlensproai | greenlens.pro |
+
+
+## Brand Rules
+- QRMaster-Posts dürfen **nur** auf `QRMaster.net`-Accounts posten.
+- GreenLens-Posts dürfen **nur** auf `GreenLens Pro`-Accounts posten.
+- Kein Crossposting zwischen Brands.
+- Token niemals öffentlich teilen; nur Referenz in dieser Datei.
+
+
+## Scripts
+| Path | Purpose |
+| --- | --- |
+| `C:\Users\timo\Documents\meta_token_refresh.py` | Meta Long-Lived + Page Token Refresh |
+| `C:\Users\timo\Documents\instagram_r2_carousel_post.py` | Instagram single-image/carousel über R2 |
+| `C:\Users\timo\x-api-autopost\x_media_post.py` | X/Twitter for QRMaster |
+| `C:\Users\timo\greenlens-x-autopost\` | X/Twitter for GreenLens |
+
+
+## Token Files / Paths
+| Path | Contains |
+| --- | --- |
+| `C:\Users\timo\Documents\meta_instagram_tokens.env` | Meta Facebook + Instagram long-lived/page tokens |
+| `C:\Users\timo\Documents\r2_social_media.env` | R2 upload credentials for IG assets |
+| `C:\Users\timo\Documents\instagram_r2_carousel_post.py` | uses both env files above |
+| `C:\Users\timo\x-api-autopost\.env` | X/Twitter QRMaster creds (`X_API_KEY`, `X_API_SECRET`, `X_ACCESS_TOKEN`, `X_ACCESS_TOKEN_SECRET`) |
+| `C:\Users\timo\Documents\greenlens-x-autopost\.env` | X/Twitter GreenLens creds |
+| `C:\Users\timo\Documents\greenlens\Greenlens\.env` | GreenLens TikTok + plant import admin creds |
+
+## QRMaster TikTok Cron Credentials
+- Source of truth: the server-side `.env` for the QRMaster app.
+- Required variables: `TIKTOK_CLIENT_KEY`, `TIKTOK_CLIENT_SECRET`, `TIKTOK_REDIRECT_URI`.
+- Optional helper: `TIKTOK_ADMIN_KEY` for guarding the `/api/tiktok/connect` start route.
+- OAuth result: access/refresh tokens are stored in the database after `/api/tiktok/connect` and `/api/tiktok/callback`.
+- Do not put TikTok access tokens in `.env`; the cron job reads them from the DB through the app flow.
+- Configure `TIKTOK_EXPECTED_OPEN_ID` for QRMaster before deploying the hardened routes. The callback and every API call fail closed when it is missing or belongs to another account.
+- `GET /api/tiktok/token` is status-only and never returns access or refresh tokens. Automations must call the server upload route instead of caching credentials locally.
+- For cron posting, use the same QRMaster server environment that already contains `CRON_SECRET` / `INTERNAL_API_SECRET` for internal APIs.
+
+## TikTok Connection Status + Credential Locations
+- QRMaster TikTok OAuth is connected and tested live via `https://qrmaster.net/api/tiktok/callback`; the callback success screen returned `TikTok account connected. You can close this tab.`
+- GreenLens TikTok OAuth is connected and tested live via `https://greenlenspro.com/api/tiktok/callback`; the callback success screen returned `TikTok account connected. You can close this tab.`
+- QRMaster app credentials live in the QRMaster server-side `.env` and are wired through `QR-Master/docker-compose.yml` (`TIKTOK_CLIENT_KEY`, `TIKTOK_CLIENT_SECRET`, `TIKTOK_REDIRECT_URI`, `TIKTOK_ADMIN_KEY`).
+- GreenLens app credentials live in `C:\Users\timo\Documents\greenlens\Greenlens\.env` / the corresponding server-side `.env` and are wired through `Greenlens/docker-compose.yml` (`TIKTOK_CLIENT_KEY`, `TIKTOK_CLIENT_SECRET`, `TIKTOK_REDIRECT_URI`, `PLANT_IMPORT_ADMIN_KEY`).
+- Hermes scratch/test reference file for local operator checks: `C:\Users\timo\.hermes\.env`. Treat it as local helper state, not production source of truth.
+
+## TikTok Posting Policy for Cron Jobs and Live Posting
+- Default policy for **both** QRMaster and GreenLens: TikTok jobs should **upload/draft only**, never direct-post, unless Timo explicitly says otherwise.
+- If Timo says only **"Go"**, interpret that as permission for TikTok **upload/draft only**. Timo finishes the final publish manually inside TikTok.
+- QRMaster specifically should be treated as **upload-only**.
+- GreenLens should also remain **upload-only by default** unless Timo explicitly asks for a different behavior.
+- Do not treat a generic approval like "Go" as permission for automatic/direct TikTok publishing.
+
+## TikTok Analytics (Display API, read-only)
+- The requested scopes MUST exactly match what each app has approved in the TikTok Developer Portal — requesting an unapproved scope aborts the whole OAuth login with a generic "scope" error.
+- Approved scopes per app (as of 2026-07-09):
+  - QRMaster: `user.info.basic, user.info.profile, user.info.stats, video.list, video.upload` (NO `video.publish` — upload/draft only).
+  - GreenLens Pro: `user.info.basic, video.upload, video.publish` (NO analytics scopes yet — a portal revision adding `user.info.stats` + `video.list` is required before GreenLens analytics works).
+- Admin-key-protected live analytics endpoints (no data is stored, every call reads fresh from TikTok):
+  - QRMaster: `GET /api/tiktok/analytics?key=<TIKTOK_ADMIN_KEY>&max_videos=50`
+  - GreenLens: `GET /api/tiktok/analytics` (guarded by the plant import admin key)
+- Response: account stats (followers, total likes, video count) plus per-video views/likes/comments/shares with computed `engagement_rate`, `posted_weekday_utc` and `posted_hour_utc`, and a summary block (totals, average/median views).
+- After any scope change the account must re-authorize via `/api/tiktok/connect`, otherwise the stored token keeps the old permissions.
+
+## TikTok Photo/Carousel Upload Notes
+- Photo posts use `POST /v2/post/publish/content/init/` with `post_mode: MEDIA_UPLOAD` (draft in the creator's inbox, needs only `video.upload`). Valid post modes are only `MEDIA_UPLOAD` and `DIRECT_POST` — `DRAFT` is not a valid value.
+- Photos are delivered via `source_info.photo_images` as public URLs (`PULL_FROM_URL`). TikTok only pulls from **verified domains** — verify the hosting domain (e.g. `greenlenspro.com` for MinIO storage URLs) under Content Posting API → "Verify domains" in the Developer Portal, otherwise the upload fails.
+- QRMaster's only verified property is `qrmaster.net` (via `public/tiktokVwGRbyf2BbBLqUlFrnehtntSEU9Ihiok.txt`). The Cloudflare R2 public domain (`pub-*.r2.dev`, used for Instagram) is **not** verified — never pass R2 URLs to the TikTok photo API for QRMaster.
+
+## QRMaster Social Asset Hosting (no-deploy image URLs)
+- `POST https://qrmaster.net/api/social-assets` (header `x-admin-key: <TIKTOK_ADMIN_KEY>`) with JSON `{ "files": [{ "filename", "mimeType", "dataBase64" }] }` stores images in PostgreSQL and returns public `https://qrmaster.net/api/social-assets/<id>` URLs on the verified domain.
+- `GET /api/social-assets/<id>` serves the file publicly (immutable cache); `GET /api/social-assets` (admin) lists the last 100 assets; `DELETE /api/social-assets/<id>` (admin) removes one.
+- Allowed types: jpeg/png/webp/mp4, max 10 MB per file.
+- The `SocialAsset` table must be created manually on the server (one-time, no auto-create in the route). Run on the server:
+  ```bash
+  docker-compose exec db psql -U postgres -d qrmaster -c 'CREATE TABLE IF NOT EXISTS "SocialAsset" ("id" TEXT PRIMARY KEY, "filename" TEXT NOT NULL, "mimeType" TEXT NOT NULL, "data" BYTEA NOT NULL, "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP);'
+  ```
+- Typical carousel flow: upload slides here → pass the returned URLs as `photos` to `POST /api/tiktok/upload` → check via `/api/tiktok/upload/status?publish_id=...`. No app deploy needed per carousel.
+
+## Refresh Behavior
+- Meta user/page tokens werden automatisch refreshed durch `python C:\Users\timo\Documents\meta_token_refresh.py`.
+- QRMaster Page-Auswahl erzwingt Page-ID `884792004727212`.
+- GreenLens Page-Auswahl erzwingt Page-ID `1150261294842586`.
+
+
+## Cron Jobs
+| Job Name | Schedule | Deliver | Notes |
+| --- | --- | --- | --- |
+| `Weekly Meta Token Refresh` | Montag 09:00 | Telegram + Email | Refreshes Meta tokens |
+
+> Social-package deliverables only after explicit `Go`.
+
+
+## Publish Checklist
+1) Brand wählen → nur passende Accounts zulassen.
+2) Media vorbereiten: QRMaster → R2-Prefix `qrmaster/`, GreenLens → `greenlens/`.
+3) Facebook: Page-ID + Page-Token verwenden.
+4) Instagram: IG User ID + Page-Token über Container + `media_publish`.
+5) X: zugehöriges Brand-Skript + zugehöriges `.env` verwenden.
+6) Keine Token/Secrets loggen.

docs/automations/social-milestone-worker.md

@@ -0,0 +1,113 @@
+# Social milestone worker
+
+The app detects QR-code scan milestones and stores customer consent. It does not
+hold X or Meta credentials. The external worker publishes what was approved —
+per channel, never more.
+
+## Consent is bound to a channel
+
+Approving a post on X says nothing about Instagram: different audience,
+different disclosure about the customer's business. Every channel therefore has
+its own checkbox in the dialog, its own text, its own handle and its own row in
+`SocialMilestonePost`. **No row means no consent.** A channel is only offered
+where a publisher is configured — `SOCIAL_MILESTONE_CHANNELS` (app) must stay in
+sync with `SOCIAL_WORKER_CHANNELS` (worker), otherwise approvals pile up in the
+queue with nobody to publish them.
+
+## Test setup (manual SQL only)
+
+1. Apply, in this order, to `qrmaster_test`:
+   [`sql/2026-08-13_social_milestones.sql`](../../sql/2026-08-13_social_milestones.sql),
+   [`sql/2026-08-16_social_milestone_retries.sql`](../../sql/2026-08-16_social_milestone_retries.sql),
+   [`sql/2026-08-16_social_milestone_channels.sql`](../../sql/2026-08-16_social_milestone_channels.sql).
+2. Set distinct `CRON_SECRET` and `INTERNAL_API_SECRET` values in `.env.test`.
+   For an end-to-end test without 1,000 scans, also set
+   `SOCIAL_MILESTONE_THRESHOLDS=1` (or `1,2`). Do not set this on production.
+   Publishing is immediate after consent by default. Set
+   `SOCIAL_MILESTONE_POST_DELAY_HOURS=24` only if a revocation window is desired.
+   Set `SOCIAL_MILESTONE_MIN_GAP_HOURS=0` on test, otherwise the second
+   milestone waits a full day behind the first one.
+3. Deploy using the documented test compose command. `CRON_SECRET` is forwarded
+   to the web service by `docker-compose.yml`.
+4. Trigger detection manually:
+
+```bash
+curl -H "Authorization: Bearer $CRON_SECRET" \
+  https://testmodul.qrmaster.net/api/cron/social-milestones
+```
+
+The detector creates records at 1,000 and 10,000 unique scans only. It is safe
+to call repeatedly because `(qrId, kind)` is unique. A QR code that is already
+past several thresholds on first detection only produces the highest one.
+
+## Queue contract
+
+```bash
+curl -H "Authorization: Bearer $INTERNAL_API_SECRET" \
+  "https://qrmaster.net/api/internal/social-milestones?channel=instagram"
+```
+
+Returns at most one approved post for that channel, claims it, and expects a
+result report for the returned `id`:
+
+```bash
+curl -X PATCH -H "Authorization: Bearer $INTERNAL_API_SECRET" \
+  -H "Content-Type: application/json" \
+  -d '{"id":"<post-id>","result":"posted","postUrl":"https://..."}' \
+  https://qrmaster.net/api/internal/social-milestones
+```
+
+First attempts are spaced by `SOCIAL_MILESTONE_MIN_GAP_HOURS` (default 24) per
+channel, so the brand timeline cannot be flooded when several customers consent
+on the same day. A blocked poll answers
+`{"milestone": null, "reason": "spacing", "nextPostAt": "..."}`.
+
+`milestone.text` is published **verbatim** — it is the text the customer read
+before consenting. The image is not part of the payload: the worker downloads it
+from `<QRMASTER_API_BASE>/s/m/<shareToken>/og`, the same renderer that serves the
+popup and the link preview. `?format=` takes `landscape` (1200×630, default),
+`square` (1080×1080) or `portrait` (1080×1350).
+
+## Instagram
+
+Publishing runs against the QRMaster.net Business account (see
+[social-accounts-and-jobs.md](social-accounts-and-jobs.md)) in three steps:
+`POST /{ig-user-id}/media` → poll `status_code` until `FINISHED` →
+`POST /{ig-user-id}/media_publish`.
+
+Worth knowing before enabling it:
+
+- **JPEG only.** The worker flattens the rendered PNG onto white and uploads it
+  through `POST /api/social-assets`; Meta downloads `image_url` itself, so it has
+  to be publicly readable on the verified domain. `SOCIAL_ASSET_ADMIN_KEY` is the
+  existing `TIKTOK_ADMIN_KEY`.
+- **No clickable links in captions.** The Instagram text therefore ends in
+  hashtags instead of the share URL, and mentions use the customer's Instagram
+  handle, not their X handle.
+- **50 posts / 24 h**, verifiable via `GET /{ig-user-id}/content_publishing_limit`.
+- **Reconciliation is caption-based.** Before a repeated attempt the worker
+  compares the caption against the last 25 media items. Two milestones with an
+  identical caption — same QR title, same scan count — would be treated as the
+  same post; the 24 h spacing makes that combination unlikely but not impossible.
+- Required environment: `SOCIAL_WORKER_CHANNELS=x,instagram`, `INSTAGRAM_USER_ID`,
+  `INSTAGRAM_ACCESS_TOKEN`, plus `SOCIAL_MILESTONE_CHANNELS=x,instagram` on the
+  web service so the dialog asks for it in the first place.
+
+Do not configure this worker against `testmodul`. LinkedIn has no approved
+brand-posting integration in this project. Customers can self-share on all three:
+X opens a prefilled intent, LinkedIn gets the text copied, Instagram opens the
+system share sheet on a phone and falls back to an image download.
+
+## Failed posts
+
+A reported failure — and a claim the worker never confirmed — counts as one
+attempt. The queue re-schedules the post itself after 5, then 10 minutes and only
+parks it in `failed` once three attempts are used up. Before posting again the
+worker reconciles against the account (share token on X, caption on Instagram),
+so a failure reported after a successful post cannot duplicate it.
+
+The consent dialog opens once per milestone, so a customer who has closed it can
+no longer see or restart a failed post from there. Settings → Milestone sharing
+lists every milestone with one line per channel and offers "Try again" (re-queues
+the approved text unchanged) and "Cancel" (revokes that channel before anything
+is published).

docs/brand-reference/qrmaster-visual-system.md

@@ -0,0 +1,75 @@
+# QR Master Visual System – Reference & Template Prompts
+
+## Master reference
+
+Reference image:
+`assets/brand-reference/qrmaster-packaging-reference.jpg`
+
+The reference defines the visual direction for all future QR Master social posts. It is a style reference, not a fixed composition to copy.
+
+## Color theme
+
+- Deep QR Master navy: `#032956` to `#0B2F63`
+- Primary blue: `#0B4F9C` to `#1769AA`
+- Bright blue accent: `#2F86D8`
+- Soft blue highlight: `#BFD9F3`
+- Cool light background: `#EEF3F8`
+- Clean white: `#FFFFFF`
+- Natural wood / warm neutral surfaces: permitted as realistic scene materials
+- Text: white on dark blue areas; deep navy on light areas
+
+Use blue as a strong brand anchor, but keep the scene realistic and dimensional. Avoid an entirely flat blue-and-white SaaS layout.
+
+## Fixed composition rules
+
+- Bright, modern, premium, explicitly photorealistic commercial photography.
+- Every image prompt must contain the exact word `photorealistic`.
+- FIXED RATIO: 3:4 portrait only, target size 1080 × 1440 px for every slide and every carousel. Never use 16:9, 2:3, square, or mixed ratios. Do not rely on automatic cropping at upload time.
+- Main headline exactly centered horizontally and visually centered vertically.
+- Subtitle centered directly below the headline.
+- Very large safe margins: keep all text at least 10% from every edge.
+- Keep a calm, low-detail area behind the text for maximum contrast.
+- Text must be sharp, complete and highly readable.
+- Use a bold modern sans-serif headline and a regular sans-serif subtitle.
+- Deep blue packaging, labels, QR accents or graphic details may repeat across slides.
+- Use real materials: glass, cardboard, paper, wood, fabric, daylight and soft shadows.
+- No hard text boxes unless absolutely needed for contrast; prefer natural tonal contrast or a subtle translucent blue veil.
+- No decorative shape may overlap the text.
+- No fake brand names, random logos or unreadable microcopy.
+- No white/black letterbox bars, artificial padding, stretching or distortion.
+- No text overflow, cropped words, malformed letters or text touching the edges.
+
+## Reusable master prompt
+
+```text
+Create a premium vertical QR Master social-media slide using the attached QR Master reference image as the visual style reference.
+
+STYLE:
+Bright, modern, premium, explicitly photorealistic commercial photography. The exact word `photorealistic` is mandatory in every image prompt. Use realistic materials, natural daylight, soft shadows and a clean contemporary composition. The visual identity must consistently use QR Master deep navy and blue accents, with light cool backgrounds and natural neutral materials.
+
+COLOR SYSTEM:
+Deep navy #032956–#0B2F63, primary blue #0B4F9C–#1769AA, bright blue #2F86D8, soft blue #BFD9F3, cool light #EEF3F8 and white #FFFFFF. Blue is the recurring brand anchor, not a flat full-screen background.
+
+SCENE:
+[DESCRIBE THE REALISTIC USE-CASE SCENE HERE]
+
+COMPOSITION:
+Portrait social format, exact 3:4 ratio, final canvas 1080 × 1440 px. Every slide must use the identical 3:4 ratio. Never generate or export 16:9, 2:3, square or mixed-ratio slides. Do not crop important objects or text during export. Keep the scene uncluttered.
+
+EXACT TEXT:
+Headline: “[INSERT HEADLINE]”
+Subtitle: “[INSERT SUBTITLE]”
+
+TYPOGRAPHY:
+Modern geometric sans-serif similar to Inter, Avenir or Helvetica Neue. Bold headline, regular subtitle, strong contrast, clean line spacing, short readable lines. Render the text exactly as written. Do not invent, omit, bend, warp or crop any letters.
+
+BRANDING:
+Use restrained QR Master blue accents in packaging, labels, QR details or scene elements. Do not create random logos or extra text. If a wordmark is used, it must be a small, clean QR MASTER wordmark at the bottom.
+
+QUALITY NEGATIVE PROMPT:
+No generic SaaS dashboard, no flat blue-and-white template, no abstract gradient background, no decorative circle over text, no hard border, no random text, no fake logo, no unreadable microcopy, no malformed letters, no text overflow, no cropped text, no distorted objects, no stretched image, no letterbox bars, no artificial padding, no clutter behind the text.
+```
+
+## Text-overlay production variant
+
+For guaranteed text accuracy, generate the photorealistic background with the same master prompt but leave the headline and subtitle area empty. Add the exact text afterward with the same fixed typography, center position, font size, line spacing and safe margins for every slide.

env.example

@@ -16,6 +16,27 @@ DATABASE_URL=postgresql://postgres:postgres@db:5432/qrmaster?schema=public
 NEXTAUTH_URL=http://localhost:3050
 NEXTAUTH_SECRET=your-secret-key-here-change-in-production
 
+# Session cookie scope. Leave EMPTY for local development (browsers reject dotted
+# domains on localhost). In production set to `.qrmaster.net` so the session is shared
+# between www.qrmaster.net and app.qrmaster.net. Only honoured when NODE_ENV=production.
+COOKIE_DOMAIN=
+
+# Name of the session cookie. Leave empty in production and development (defaults to
+# `userId`). The staging deployment on testmodul.qrmaster.net must set its own name, e.g.
+# `userId_test`: production scopes its cookie to .qrmaster.net, so the browser sends it to
+# every subdomain, and two cookies with the same name make the lookup ambiguous.
+# Changing this in production logs out every user.
+AUTH_COOKIE_NAME=
+
+# Host split: marketing/SEO on WWW, the logged-in app on APP. Keep both pointing at the
+# same origin locally so nothing redirects across hosts in development.
+# In production: NEXT_PUBLIC_WWW_URL=https://www.qrmaster.net
+#               NEXT_PUBLIC_APP_URL=https://app.qrmaster.net
+# NEXT_PUBLIC_WWW_URL must stay on www - it is the origin encoded into downloaded QR
+# codes and used for public links in emails.
+NEXT_PUBLIC_WWW_URL=http://localhost:3050
+NEXT_PUBLIC_APP_URL=http://localhost:3050
+
 # OAuth Providers (Optional)
 GOOGLE_CLIENT_ID=
 GOOGLE_CLIENT_SECRET=
@@ -48,3 +69,14 @@ NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=
 # Analytics (Optional - PostHog)
 NEXT_PUBLIC_POSTHOG_KEY=
 NEXT_PUBLIC_POSTHOG_HOST=https://app.posthog.com
+
+# Analytics (Optional - Microsoft Clarity session recordings & heatmaps)
+NEXT_PUBLIC_CLARITY_PROJECT_ID=
+
+# TikTok Content Posting API (Hermes Agent automated posting)
+TIKTOK_CLIENT_KEY=
+TIKTOK_CLIENT_SECRET=
+TIKTOK_REDIRECT_URI=https://qrmaster.net/api/tiktok/callback
+# Optional: protects /api/tiktok/connect from being triggered by strangers
+TIKTOK_ADMIN_KEY=
+TIKTOK_EXPECTED_OPEN_ID=

linear.app/DESIGN.md

@@ -0,0 +1,548 @@
+---
+version: alpha
+name: Linear
+description: "A near-black product-focused marketing canvas built around #010102 (the deepest dark surface of any tool in this collection), light gray text (#f7f8f8), and the signature Linear lavender-blue (#5e6ad2) used as the single chromatic accent. The system reads as software-craft documentation: dense, technical, and quietly luxurious. Display type is set in the Linear custom sans (SF Pro Display fallback) at 500–700 with measured negative tracking. Cards live as charcoal panels (#0f1011) with hairline borders. The accent lavender appears on the brand mark, focus rings, and a few intentional CTAs — never decoratively. Page rhythm leans on product UI screenshots framed in dark panels rather than atmospheric color."
+
+colors:
+  primary: "#5e6ad2"
+  on-primary: "#ffffff"
+  primary-hover: "#828fff"
+  primary-focus: "#5e69d1"
+  ink: "#f7f8f8"
+  ink-muted: "#d0d6e0"
+  ink-subtle: "#8a8f98"
+  ink-tertiary: "#62666d"
+  canvas: "#010102"
+  surface-1: "#0f1011"
+  surface-2: "#141516"
+  surface-3: "#18191a"
+  surface-4: "#191a1b"
+  hairline: "#23252a"
+  hairline-strong: "#34343a"
+  hairline-tertiary: "#3e3e44"
+  inverse-canvas: "#ffffff"
+  inverse-surface-1: "#f5f6f6"
+  inverse-surface-2: "#f6f7f7"
+  inverse-ink: "#000000"
+  brand-secure: "#7a7fad"
+  semantic-success: "#27a644"
+  semantic-overlay: "#000000"
+
+typography:
+  display-xl:
+    fontFamily: Linear Display
+    fontSize: 80px
+    fontWeight: 600
+    lineHeight: 1.05
+    letterSpacing: -3.0px
+  display-lg:
+    fontFamily: Linear Display
+    fontSize: 56px
+    fontWeight: 600
+    lineHeight: 1.10
+    letterSpacing: -1.8px
+  display-md:
+    fontFamily: Linear Display
+    fontSize: 40px
+    fontWeight: 600
+    lineHeight: 1.15
+    letterSpacing: -1.0px
+  headline:
+    fontFamily: Linear Display
+    fontSize: 28px
+    fontWeight: 600
+    lineHeight: 1.20
+    letterSpacing: -0.6px
+  card-title:
+    fontFamily: Linear Display
+    fontSize: 22px
+    fontWeight: 500
+    lineHeight: 1.25
+    letterSpacing: -0.4px
+  subhead:
+    fontFamily: Linear Display
+    fontSize: 20px
+    fontWeight: 400
+    lineHeight: 1.40
+    letterSpacing: -0.2px
+  body-lg:
+    fontFamily: Linear Text
+    fontSize: 18px
+    fontWeight: 400
+    lineHeight: 1.50
+    letterSpacing: -0.1px
+  body:
+    fontFamily: Linear Text
+    fontSize: 16px
+    fontWeight: 400
+    lineHeight: 1.50
+    letterSpacing: -0.05px
+  body-sm:
+    fontFamily: Linear Text
+    fontSize: 14px
+    fontWeight: 400
+    lineHeight: 1.50
+    letterSpacing: 0
+  caption:
+    fontFamily: Linear Text
+    fontSize: 12px
+    fontWeight: 400
+    lineHeight: 1.40
+    letterSpacing: 0
+  button:
+    fontFamily: Linear Text
+    fontSize: 14px
+    fontWeight: 500
+    lineHeight: 1.20
+    letterSpacing: 0
+  eyebrow:
+    fontFamily: Linear Text
+    fontSize: 13px
+    fontWeight: 500
+    lineHeight: 1.30
+    letterSpacing: 0.4px
+  mono:
+    fontFamily: Linear Mono
+    fontSize: 13px
+    fontWeight: 400
+    lineHeight: 1.50
+    letterSpacing: 0
+
+rounded:
+  xs: 4px
+  sm: 6px
+  md: 8px
+  lg: 12px
+  xl: 16px
+  xxl: 24px
+  pill: 9999px
+  full: 9999px
+
+spacing:
+  xxs: 4px
+  xs: 8px
+  sm: 12px
+  md: 16px
+  lg: 24px
+  xl: 32px
+  xxl: 48px
+  section: 96px
+
+components:
+  button-primary:
+    backgroundColor: "{colors.primary}"
+    textColor: "{colors.on-primary}"
+    typography: "{typography.button}"
+    rounded: "{rounded.md}"
+    padding: 8px 14px
+  button-primary-pressed:
+    backgroundColor: "{colors.primary-focus}"
+    textColor: "{colors.on-primary}"
+    typography: "{typography.button}"
+    rounded: "{rounded.md}"
+  button-primary-hover:
+    backgroundColor: "{colors.primary-hover}"
+    textColor: "{colors.on-primary}"
+    typography: "{typography.button}"
+    rounded: "{rounded.md}"
+  button-secondary:
+    backgroundColor: "{colors.surface-1}"
+    textColor: "{colors.ink}"
+    typography: "{typography.button}"
+    rounded: "{rounded.md}"
+    padding: 8px 14px
+  button-tertiary:
+    backgroundColor: "{colors.canvas}"
+    textColor: "{colors.ink}"
+    typography: "{typography.button}"
+    rounded: "{rounded.md}"
+    padding: 8px 14px
+  button-inverse:
+    backgroundColor: "{colors.inverse-canvas}"
+    textColor: "{colors.inverse-ink}"
+    typography: "{typography.button}"
+    rounded: "{rounded.md}"
+    padding: 8px 14px
+  pricing-card:
+    backgroundColor: "{colors.surface-1}"
+    textColor: "{colors.ink}"
+    typography: "{typography.body}"
+    rounded: "{rounded.lg}"
+    padding: 24px
+  pricing-card-featured:
+    backgroundColor: "{colors.surface-2}"
+    textColor: "{colors.ink}"
+    typography: "{typography.body}"
+    rounded: "{rounded.lg}"
+    padding: 24px
+  feature-card:
+    backgroundColor: "{colors.surface-1}"
+    textColor: "{colors.ink}"
+    typography: "{typography.body}"
+    rounded: "{rounded.lg}"
+    padding: 24px
+  product-screenshot-card:
+    backgroundColor: "{colors.surface-1}"
+    textColor: "{colors.ink}"
+    typography: "{typography.body}"
+    rounded: "{rounded.xl}"
+    padding: 24px
+  testimonial-card:
+    backgroundColor: "{colors.surface-1}"
+    textColor: "{colors.ink}"
+    typography: "{typography.body-lg}"
+    rounded: "{rounded.lg}"
+    padding: 32px
+  customer-logo-tile:
+    backgroundColor: "{colors.canvas}"
+    textColor: "{colors.ink-subtle}"
+    typography: "{typography.caption}"
+    rounded: "{rounded.xs}"
+    padding: 16px
+  text-input:
+    backgroundColor: "{colors.surface-1}"
+    textColor: "{colors.ink}"
+    typography: "{typography.body}"
+    rounded: "{rounded.md}"
+    padding: 8px 12px
+  text-input-focused:
+    backgroundColor: "{colors.surface-1}"
+    textColor: "{colors.ink}"
+    typography: "{typography.body}"
+    rounded: "{rounded.md}"
+    padding: 8px 12px
+  pricing-tab-default:
+    backgroundColor: "{colors.canvas}"
+    textColor: "{colors.ink-subtle}"
+    typography: "{typography.button}"
+    rounded: "{rounded.pill}"
+    padding: 6px 14px
+  pricing-tab-selected:
+    backgroundColor: "{colors.surface-2}"
+    textColor: "{colors.ink}"
+    typography: "{typography.button}"
+    rounded: "{rounded.pill}"
+    padding: 6px 14px
+  cta-banner:
+    backgroundColor: "{colors.surface-1}"
+    textColor: "{colors.ink}"
+    typography: "{typography.headline}"
+    rounded: "{rounded.lg}"
+    padding: 48px
+  changelog-row:
+    backgroundColor: "{colors.canvas}"
+    textColor: "{colors.ink}"
+    typography: "{typography.body}"
+    rounded: "{rounded.xs}"
+    padding: 24px 0
+  status-badge:
+    backgroundColor: "{colors.surface-2}"
+    textColor: "{colors.ink-muted}"
+    typography: "{typography.caption}"
+    rounded: "{rounded.pill}"
+    padding: 2px 8px
+  top-nav:
+    backgroundColor: "{colors.canvas}"
+    textColor: "{colors.ink}"
+    typography: "{typography.body-sm}"
+    rounded: "{rounded.xs}"
+    height: 56px
+  footer:
+    backgroundColor: "{colors.canvas}"
+    textColor: "{colors.ink-subtle}"
+    typography: "{typography.caption}"
+    rounded: "{rounded.xs}"
+    padding: 64px 32px
+---
+
+## Overview
+
+Linear's marketing canvas is the deepest dark surface in this collection — `{colors.canvas}` is #010102, essentially pure black with a faint blue tint. On top sits a four-step surface ladder (`{colors.surface-1}` through `{colors.surface-4}`) for cards, panels, and lifted tiles, with hairline borders running from `{colors.hairline}` (#23252a) up through `{colors.hairline-strong}` and `{colors.hairline-tertiary}`. Light gray text (`{colors.ink}` #f7f8f8) carries the body and headlines.
+
+The single chromatic accent is **Linear lavender-blue** `{colors.primary}` (#5e6ad2) — used on the brand mark, focus rings, and the primary CTA button. A lighter hover state (`{colors.primary-hover}` #828fff) and a focus-tinted variant (`{colors.primary-focus}` #5e69d1) extend the same hue. Linear avoids saturated greens, oranges, reds, etc. on the marketing canvas — the only semantic color is `{colors.semantic-success}` (#27a644) for status pills and the rare success indicator.
+
+Display type runs Linear's custom sans (with `SF Pro Display` fallback) at weight 500–700 with negative letter-spacing scaling from -3.0px at 80px down to 0 at body. The body family is Linear's text cut, and a Linear Mono is reserved for code snippets in product screenshots.
+
+The page rhythm is **dense product screenshots** — Linear's marketing leads with high-fidelity captures of the product UI (issue list, project view, dashboard) framed in `{colors.surface-1}` panels with `{rounded.xl}` 16px corners. The chrome is intentionally minimal so the app screenshots can do the heavy lifting.
+
+**Key Characteristics:**
+- **Dark-canvas marketing system** — `{colors.canvas}` (#010102) is the deepest dark in this collection.
+- **Lavender-blue brand accent** (`{colors.primary}` #5e6ad2) — used scarcely on brand mark, focus, and the primary CTA.
+- Four-step surface ladder (canvas → surface-1 → surface-2 → surface-3 → surface-4) carries hierarchy without shadow.
+- Display tracking pulls aggressively negative (-3.0px at 80px); body holds at -0.05px.
+- Cards use `{rounded.lg}` 12px corners with 1px hairline borders — never pill, rarely 16px.
+- **Product UI screenshots** dominate the page. The marketing chrome is a dark frame for the app.
+- No second chromatic color. No atmospheric gradients. No spotlight cards.
+
+## Colors
+
+> Source pages: linear.app (home), /intake, /pricing, /contact/sales, /build.
+
+### Brand & Accent
+- **Lavender-Blue** ({colors.primary}): The signature Linear accent — primary CTA, brand mark, link emphasis.
+- **Lavender Hover** ({colors.primary-hover}): Lighter lavender (#828fff) — hovered state of the primary CTA.
+- **Lavender Focus** ({colors.primary-focus}): Focus-ring tint (#5e69d1) — focused inputs, focused buttons.
+- **Brand Secure** ({colors.brand-secure}): Muted lavender-gray (#7a7fad) — used in "Linear Security" surfaces.
+
+### Surface
+- **Canvas** ({colors.canvas}): Default page background — #010102, near-pure black with a faint blue tint.
+- **Surface 1** ({colors.surface-1}): One step above canvas — feature cards, pricing cards, product screenshot panels.
+- **Surface 2** ({colors.surface-2}): Two steps above — featured pricing card, hovered cards.
+- **Surface 3** ({colors.surface-3}): Three steps above — line-tertiary backgrounds, sub-nav.
+- **Surface 4** ({colors.surface-4}): Four steps above — bg-level-3, deepest lifted surface.
+- **Hairline** ({colors.hairline}): 1px borders on cards and dividers.
+- **Hairline Strong** ({colors.hairline-strong}): Stronger 1px borders — input focus rings.
+- **Hairline Tertiary** ({colors.hairline-tertiary}): Tertiary borders for nested surfaces.
+- **Inverse Canvas** ({colors.inverse-canvas}): Pure white — surface of the inverse pill CTA on a small set of section openers.
+- **Inverse Surface 1** ({colors.inverse-surface-1}): One step above inverse canvas.
+- **Inverse Surface 2** ({colors.inverse-surface-2}): Two steps above inverse canvas.
+
+### Text
+- **Ink** ({colors.ink}): All headlines and emphasized body type — light gray #f7f8f8.
+- **Ink Muted** ({colors.ink-muted}): Secondary type at #d0d6e0 — meta info on hero panels.
+- **Ink Subtle** ({colors.ink-subtle}): Tertiary type at #8a8f98 — deselected pricing tabs, footer columns.
+- **Ink Tertiary** ({colors.ink-tertiary}): Quaternary at #62666d — disabled, footnotes.
+
+### Semantic
+- **Success Green** ({colors.semantic-success}): Status pills, success indicators. The only semantic color on marketing.
+- **Overlay** ({colors.semantic-overlay}): Pure black overlay scrim for modals.
+
+## Typography
+
+### Font Family
+
+- **Linear Display** — Linear's custom display sans; fallback `SF Pro Display, -apple-system, system-ui, Segoe UI, Roboto`. Carries display-xl through subhead.
+- **Linear Text** — Linear's custom text sans (a slightly different cut tuned for body sizes); same fallback stack. Carries body sizes, button labels, captions.
+- **Linear Mono** — Linear's custom mono; fallback `ui-monospace, SF Mono, Menlo`. Used for code snippets in product screenshots and for status / ID tokens.
+
+The marketing surface treats Display and Text as one continuous voice; the family change is silent.
+
+### Hierarchy
+
+| Token | Size | Weight | Line Height | Letter Spacing | Use |
+|---|---|---|---|---|---|
+| `{typography.display-xl}` | 80px | 600 | 1.05 | -3.0px | Largest hero headline |
+| `{typography.display-lg}` | 56px | 600 | 1.10 | -1.8px | Section opener headlines |
+| `{typography.display-md}` | 40px | 600 | 1.15 | -1.0px | Sub-section headlines |
+| `{typography.headline}` | 28px | 600 | 1.20 | -0.6px | Pricing tier titles, CTA banner heading |
+| `{typography.card-title}` | 22px | 500 | 1.25 | -0.4px | Feature card title |
+| `{typography.subhead}` | 20px | 400 | 1.40 | -0.2px | Lead body, intro paragraphs |
+| `{typography.body-lg}` | 18px | 400 | 1.50 | -0.1px | Hero subhead, lead paragraphs |
+| `{typography.body}` | 16px | 400 | 1.50 | -0.05px | Default body |
+| `{typography.body-sm}` | 14px | 400 | 1.50 | 0 | Card body, footer columns |
+| `{typography.caption}` | 12px | 400 | 1.40 | 0 | Captions, meta, status |
+| `{typography.button}` | 14px | 500 | 1.20 | 0 | All button labels |
+| `{typography.eyebrow}` | 13px | 500 | 1.30 | 0.4px | Section eyebrow (slight positive tracking) |
+| `{typography.mono}` | 13px | 400 | 1.50 | 0 | Linear Mono for code in product screenshots |
+
+### Principles
+
+- **Aggressive negative tracking on display** (-3.0px at 80px ≈ 4% of size).
+- **Single voice from display to body.** Display-xl at 600 → body at 400 — same family, narrower weights.
+- **Eyebrow uses positive tracking** (+0.4px) — contrast against the negative-tracked display marks the eyebrow as taxonomy.
+- **Mono only in code contexts.** Linear Mono lives inside product screenshots — not on marketing chrome.
+
+### Note on Font Substitutes
+
+Linear's custom typeface isn't publicly distributed; the documented fallback `SF Pro Display, -apple-system, system-ui` is the recommended substitute on macOS. For cross-platform implementation, **Inter** at weight 500 / 600 / 700 is the closest free substitute. **Geist Sans** is also viable. For mono, **JetBrains Mono** or **Geist Mono** at weight 400 closely approximates Linear Mono.
+
+## Layout
+
+### Spacing System
+
+- **Base unit**: 4px.
+- **Tokens (front matter)**: `{spacing.xxs}` 4px · `{spacing.xs}` 8px · `{spacing.sm}` 12px · `{spacing.md}` 16px · `{spacing.lg}` 24px · `{spacing.xl}` 32px · `{spacing.xxl}` 48px · `{spacing.section}` 96px.
+- Card interior padding: `{spacing.lg}` 24px on feature/pricing cards; `{spacing.xl}` 32px on testimonial cards; `{spacing.xxl}` 48px on CTA banners.
+- Pill button padding: 8px vertical · 14px horizontal — Linear's compact button spec.
+- Form input padding: 8px vertical · 12px horizontal.
+
+### Grid & Container
+
+- Max content width sits around 1280px.
+- Card grids are 3-up at desktop, 2-up at tablet, 1-up at mobile.
+- Pricing tier grid is 3-up; comparison strip below shows checkmarks per tier.
+- Product screenshot panels span full content width — they're the protagonist.
+
+### Whitespace Philosophy
+
+The dark canvas IS the whitespace. Sections separate by lift onto surface-1 panels, not by gaps in white. Within a panel, generous `{spacing.lg}` 24px gaps between content blocks; `{spacing.section}` 96px between sections.
+
+## Elevation & Depth
+
+| Level | Treatment | Use |
+|---|---|---|
+| 0 (flat) | No shadow, no border | Default for body type, hero text, footer |
+| 1 (charcoal lift) | `{colors.surface-1}` background on canvas, 1px `{colors.hairline}` | Default cards, product panels |
+| 2 (surface-2 lift) | `{colors.surface-2}` background, 1px `{colors.hairline-strong}` | Featured pricing card, hovered cards |
+| 3 (surface-3 lift) | `{colors.surface-3}` background | Sub-nav, dropdown menus |
+| 4 (focus ring) | 2px `{colors.primary-focus}` outline at 50% opacity | Focused input, focused button |
+
+Linear's depth is carried by surface ladder + hairline borders. The brand resists drop shadows on dark almost entirely.
+
+### Decorative Depth
+
+- **Product UI screenshots** dominate as decorative depth.
+- **No atmospheric gradients, no spotlight cards.**
+- **Subtle white edge highlight** on the top edge of lifted panels — gives the dark surface a faint "pixel rendered" feel.
+
+## Shapes
+
+### Border Radius Scale
+
+| Token | Value | Use |
+|---|---|---|
+| `{rounded.xs}` | 4px | Small chips, status badges |
+| `{rounded.sm}` | 6px | Inline tags |
+| `{rounded.md}` | 8px | All buttons, form inputs |
+| `{rounded.lg}` | 12px | Pricing cards, feature cards, testimonial cards |
+| `{rounded.xl}` | 16px | Product screenshot panels |
+| `{rounded.xxl}` | 24px | Oversized CTA banners (rare) |
+| `{rounded.pill}` | 9999px | Pricing tab toggles, status pills |
+| `{rounded.full}` | 9999px | Avatar circles |
+
+### Photography & Illustration Geometry
+
+- Product UI screenshots dominate; they sit in `{rounded.xl}` 16px tiles with `{spacing.lg}` 24px outer padding.
+- Customer logo tiles render at small sizes (~24px logo height) on `{colors.canvas}` with no border.
+- Avatar circles in testimonial cards use `{rounded.full}` at 32–40px sizes.
+
+## Components
+
+### Buttons
+
+**`button-primary`** — Lavender CTA. The default primary CTA across all pages.
+- Background `{colors.primary}`, text `{colors.on-primary}`, type `{typography.button}`, padding 8px 14px, rounded `{rounded.md}`.
+- Pressed state lives in `button-primary-pressed` (background shifts to `{colors.primary-focus}`).
+- Hover state lives in `button-primary-hover` (background shifts to `{colors.primary-hover}` lighter lavender).
+
+**`button-secondary`** — Charcoal button. Used for secondary CTAs ("Sign in", "Read changelog").
+- Background `{colors.surface-1}`, text `{colors.ink}`, type `{typography.button}`, padding 8px 14px, rounded `{rounded.md}`. 1px `{colors.hairline}` border.
+
+**`button-tertiary`** — Plain text button.
+- Background `{colors.canvas}`, text `{colors.ink}`, type `{typography.button}`, rounded `{rounded.md}`, padding 8px 14px.
+
+**`button-inverse`** — White-on-dark inverse CTA.
+- Background `{colors.inverse-canvas}`, text `{colors.inverse-ink}`, type `{typography.button}`, rounded `{rounded.md}`, padding 8px 14px.
+
+### Pricing Tabs
+
+**`pricing-tab-default`** + **`pricing-tab-selected`** — Pill-toggle on `/pricing`.
+- Default: `{colors.canvas}` background, `{colors.ink-subtle}` text, rounded `{rounded.pill}`, padding 6px 14px.
+- Selected: `{colors.surface-2}` background, `{colors.ink}` text — selected = surface lift.
+
+### Cards & Containers
+
+**`pricing-card`** — Each tier on `/pricing`.
+- Background `{colors.surface-1}`, text `{colors.ink}`, type `{typography.body}`, rounded `{rounded.lg}`, padding 24px. 1px `{colors.hairline}` border.
+
+**`pricing-card-featured`** — Recommended tier — surface lift to surface-2.
+- Background `{colors.surface-2}`, otherwise identical structure.
+
+**`feature-card`** — Generic feature highlight tile.
+- Background `{colors.surface-1}`, text `{colors.ink}`, type `{typography.body}`, rounded `{rounded.lg}`, padding 24px.
+
+**`product-screenshot-card`** — The dominant card type — frames a high-fidelity Linear app UI screenshot.
+- Background `{colors.surface-1}`, text `{colors.ink}`, type `{typography.body}`, rounded `{rounded.xl}`, padding 24px.
+
+**`testimonial-card`** — Customer quote with avatar + name + role.
+- Background `{colors.surface-1}`, text `{colors.ink}`, type `{typography.body-lg}`, rounded `{rounded.lg}`, padding 32px.
+
+**`customer-logo-tile`** — Small tile in the customer marquee.
+- Background `{colors.canvas}`, text `{colors.ink-subtle}`, type `{typography.caption}`, rounded `{rounded.xs}`, padding 16px.
+
+**`cta-banner`** — Closing CTA panel near page bottom.
+- Background `{colors.surface-1}`, text `{colors.ink}`, type `{typography.headline}`, rounded `{rounded.lg}`, padding 48px.
+
+### Inputs & Forms
+
+**`text-input`** + **`text-input-focused`** — Form fields on `/contact/sales` and signup overlays.
+- Background `{colors.surface-1}`, text `{colors.ink}`, type `{typography.body}`, rounded `{rounded.md}`, padding 8px 12px.
+- Focused state retains the same surface; the focus ring is a 2px `{colors.primary-focus}` outline at 50% opacity.
+
+### Status & Build Page
+
+**`changelog-row`** — Each row in `/build` (changelog page) listing version, date, and changes.
+- Background `{colors.canvas}`, text `{colors.ink}`, type `{typography.body}`, rounded `{rounded.xs}`, padding 24px 0. 1px `{colors.hairline}` bottom rule.
+
+**`status-badge`** — Small status pill.
+- Background `{colors.surface-2}`, text `{colors.ink-muted}`, type `{typography.caption}`, rounded `{rounded.pill}`, padding 2px 8px.
+
+### Navigation
+
+**`top-nav`** — Sticky dark bar with the Linear wordmark left, primary nav links centered, and a `button-secondary` ("Sign in") + `button-primary` ("Get started") pair right.
+- Background `{colors.canvas}`, text `{colors.ink}`, type `{typography.body-sm}`, height 56px.
+
+### Footer
+
+**`footer`** — Dense link grid on `{colors.canvas}` with the Linear wordmark left.
+- Background `{colors.canvas}`, text `{colors.ink-subtle}`, type `{typography.caption}`, padding 64px 32px.
+
+## Do's and Don'ts
+
+### Do
+
+- Reserve `{colors.canvas}` (#010102) as the system's anchor surface — the faint blue tint is intentional.
+- Use `{colors.primary}` lavender ONLY for: brand mark, primary CTA, focus ring, link emphasis.
+- Use the four-step surface ladder for hierarchy. Avoid skipping levels.
+- Pair display weight 600 with body weight 400 — Linear resists 700+ display weights.
+- Apply negative letter-spacing aggressively on display.
+- Use product UI screenshots as the protagonist of every section.
+- Compose CTAs as `{rounded.md}` 8px corners.
+
+### Don't
+
+- Don't ship a light-mode marketing page.
+- Don't use lavender as a section background or card fill.
+- Don't introduce a second chromatic accent (orange, pink, green for marketing).
+- Don't add atmospheric gradients or spotlight cards.
+- Don't pill-round CTAs.
+- Don't use `#000000` true black as the canvas.
+- Don't combine multiple bright accents in product screenshot mockups.
+
+## Responsive Behavior
+
+### Breakpoints
+
+| Name | Width | Key Changes |
+|---|---|---|
+| Desktop-XL | 1440px | Default desktop layout |
+| Desktop | 1280px | Card grid 3-up maintained |
+| Tablet | 1024px | Card grid 3-up → 2-up |
+| Mobile-Lg | 768px | Pricing comparison becomes accordion; nav hamburger |
+| Mobile | 480px | Single-column; display-xl scales 80px → ~36px |
+
+### Touch Targets
+
+- CTAs hold ≥40px tap height across viewports.
+- Pricing tab pills hold ≥36px tap height; touch viewports grow to ≥44px.
+- Form inputs hold ≥44px tap target on touch.
+
+### Collapsing Strategy
+
+- **Top nav**: links collapse to hamburger below 768px.
+- **Card grids**: 3-up → 2-up at 1024px → 1-up below 768px.
+- **Pricing comparison**: per-tier accordion below 768px.
+- **Display type**: `{typography.display-xl}` 80px scales toward `{typography.display-md}` 40px on mobile.
+
+### Image Behavior
+
+- Product UI screenshots maintain aspect ratio and never crop.
+- Customer logos in the marquee may collapse from 6-up to 3-up below 768px.
+
+## Iteration Guide
+
+1. Focus on ONE component at a time and reference it by its `components:` token name.
+2. When introducing a section, decide first which surface lift it lives on.
+3. Default body to `{typography.body}` at weight 400.
+4. Run `npx @google/design.md lint DESIGN.md` after edits.
+5. Add new variants as separate component entries.
+6. Treat lavender as scarce: brand mark, primary CTA, focus, link emphasis.
+7. Lead every section with a product UI screenshot.
+
+## Known Gaps
+
+- The four-step surface ladder values are extracted directly from Linear's `--color-bg-level-3`, `--color-line-tint`, etc. CSS variables; they are Linear's canonical surface spec.
+- Form-field error and validation styling is not visible on the inspected pages.
+- Light mode is not documented because the marketing site does not ship a light theme.
+- Linear's actual product UI uses a richer color-tag palette (red, orange, yellow, green, blue, purple) for issue priorities and project labels — those colors live in the in-product surfaces shown in mockups.
+- The custom display, text, and mono families are proprietary; an open-source substitute is acceptable.

manual-billing-sql.txt

@@ -0,0 +1,90 @@
+QR Master automatic billing alarm SQL
+=====================================
+
+Run this SQL once in the database.
+
+After it is installed, every database update of "User"."plan" automatically
+creates a "UserLifecycleLog" entry.
+
+That means:
+- FREE -> PRO or BUSINESS creates reason = subscription_created
+- PRO/BUSINESS -> FREE creates reason = subscription_deleted
+- PRO -> BUSINESS or BUSINESS -> PRO creates reason = subscription_updated
+
+No customer email needs to be typed into this file.
+No manual log insert is needed after this is installed.
+
+
+CREATE OR REPLACE FUNCTION qrmaster_log_plan_change()
+RETURNS trigger AS $$
+DECLARE
+  next_stage TEXT;
+  log_reason TEXT;
+BEGIN
+  IF NEW."plan" IS NOT DISTINCT FROM OLD."plan" THEN
+    RETURN NEW;
+  END IF;
+
+  IF NEW."plan"::TEXT IN ('PRO', 'BUSINESS') THEN
+    next_stage := 'paid';
+  ELSIF COALESCE(NEW."leadScore", 0) >= 70 THEN
+    next_stage := 'upgrade_candidate';
+  ELSIF COALESCE(NEW."leadScore", 0) >= 55 THEN
+    next_stage := 'hot';
+  ELSIF COALESCE(NEW."leadScore", 0) >= 30 THEN
+    next_stage := 'warm';
+  ELSIF NEW."activationAt" IS NOT NULL THEN
+    next_stage := 'activated';
+  ELSE
+    next_stage := 'cold';
+  END IF;
+
+  IF OLD."plan"::TEXT = 'FREE' AND NEW."plan"::TEXT IN ('PRO', 'BUSINESS') THEN
+    log_reason := 'subscription_created';
+  ELSIF OLD."plan"::TEXT IN ('PRO', 'BUSINESS') AND NEW."plan"::TEXT = 'FREE' THEN
+    log_reason := 'subscription_deleted';
+  ELSE
+    log_reason := 'subscription_updated';
+  END IF;
+
+  NEW."lifecycleStage" := next_stage;
+  NEW."lastScoredAt" := NOW();
+
+  IF next_stage IN ('paid', 'hot', 'upgrade_candidate') THEN
+    NEW."lastQualifiedAt" := NOW();
+  END IF;
+
+  INSERT INTO "UserLifecycleLog" (
+    "id",
+    "userId",
+    "fromStage",
+    "toStage",
+    "fitScore",
+    "intentScore",
+    "leadScore",
+    "reason",
+    "createdAt"
+  )
+  VALUES (
+    CONCAT('planlog_', MD5(NEW."id" || clock_timestamp()::TEXT || random()::TEXT)),
+    NEW."id",
+    OLD."lifecycleStage",
+    next_stage,
+    COALESCE(NEW."fitScore", 0),
+    COALESCE(NEW."intentScore", 0),
+    COALESCE(NEW."leadScore", 0),
+    log_reason,
+    NOW()
+  );
+
+  RETURN NEW;
+END;
+$$ LANGUAGE plpgsql;
+
+
+DROP TRIGGER IF EXISTS qrmaster_user_plan_change_alarm ON "User";
+
+CREATE TRIGGER qrmaster_user_plan_change_alarm
+BEFORE UPDATE OF "plan" ON "User"
+FOR EACH ROW
+EXECUTE FUNCTION qrmaster_log_plan_change();

marketing/sales-deck-marketing-manager.md

@@ -0,0 +1,145 @@
+# QR Master Sales Deck
+
+Audience: Marketing Manager
+Use case: AE-led first demo / sales presentation
+Stage: Discovery to first solution presentation
+Format: 11-slide outline with presentation notes
+
+## Slide 1: Print Campaigns Should Not Go Dark After They Ship
+
+Body copy:
+- Printed flyers, packaging, menus, and posters still drive action
+- Static QR codes break the moment a link, offer, or landing page changes
+- Marketing teams lose both flexibility and attribution
+
+Speaker notes:
+Lead with the operational reality: print is still valuable, but static QR codes make it fragile. Position the problem as a marketing control issue, not just a design or ops issue.
+
+## Slide 2: The Cost of Static QR Codes Is Bigger Than Reprints
+
+Body copy:
+- Reprints create direct waste every time a destination changes
+- Campaign teams lose scan-level visibility into offline performance
+- Manual updates slow launches and create avoidable errors
+
+Speaker notes:
+Use the ROI angle here. QR Master already frames this as reprint waste plus lost measurement. If relevant, quantify with the prospect's own print budget and update frequency.
+
+## Slide 3: Marketing Teams Need Trackable Offline-to-Online Journeys
+
+Body copy:
+- Offline campaigns now need the same measurement discipline as digital
+- Teams want scan, device, and location insights without adding complexity
+- Privacy expectations are higher, especially in Europe
+
+Speaker notes:
+This is the urgency slide. The shift is not "QR codes are new" but "QR codes now need to behave like measurable campaign infrastructure."
+
+## Slide 4: QR Master Makes Printed Assets Editable, Trackable, and Privacy-First
+
+Body copy:
+- Change QR destinations after printing with dynamic QR codes
+- Track scans with analytics designed for marketing use cases
+- Stay privacy-conscious with hashed IP handling and no PII-based tracking model
+
+Speaker notes:
+Keep this simple. The core promise is control after print, measurable outcomes, and lower compliance anxiety.
+
+## Slide 5: Launch Campaign QR Codes Fast
+
+Body copy:
+- Create dynamic or static QR codes in minutes
+- Use specialized generators for URL, WiFi, menus, vCards, events, and more
+- Download ready-to-use assets for print and packaging workflows
+
+Speaker notes:
+Show speed to launch. This matters for marketers running many campaigns with changing assets and deadlines.
+
+## Slide 6: Update Destinations Without Reprinting
+
+Body copy:
+- Swap landing pages, PDFs, menus, or promotions after distribution
+- Keep the same printed QR code live while the destination evolves
+- Reduce wasted inventory, signage, and packaging runs
+
+Speaker notes:
+This is the core economic benefit. Tie it to seasonal campaigns, corrected links, changing offers, and localized landing pages.
+
+## Slide 7: Measure What Offline Campaigns Actually Drive
+
+Body copy:
+- See scan activity, devices, and location patterns
+- Understand which printed assets and campaigns create engagement
+- Give marketing a better feedback loop for offline spend
+
+Speaker notes:
+Frame analytics as decision support. The point is not dashboards for their own sake; it is knowing what to scale, fix, or stop.
+
+## Slide 8: Scale Beyond One-Off QR Campaigns
+
+Body copy:
+- Business plan supports bulk QR creation up to 1,000 rows per upload
+- Generate large batches for packaging, retail, events, and distributed campaigns
+- Move from ad hoc QR creation to repeatable campaign operations
+
+Speaker notes:
+Use this slide when the buyer has many SKUs, locations, or campaigns. For smaller teams, keep it brief and treat it as future-proofing.
+
+## Slide 9: Why Teams Choose QR Master
+
+Body copy:
+- Privacy-first approach with hashed IPs and Do Not Track respect
+- Bulk creation and advanced analytics in one platform
+- More focused than generic design tools, simpler and more cost-conscious than enterprise-heavy alternatives
+
+Speaker notes:
+This is where you position against free tools, Canva-style utilities, and more expensive enterprise QR platforms. Stay outcome-focused rather than feature-dense.
+
+## Slide 10: Value and Packaging
+
+Body copy:
+- Free: 3 active dynamic QR codes and unlimited static QR codes
+- Pro: EUR 9/month or EUR 90/year for 50 dynamic QR codes, advanced analytics, and branding
+- Business: EUR 29/month or EUR 290/year for 500 dynamic QR codes, bulk creation, and priority support
+- Enterprise: custom for larger rollouts
+
+Speaker notes:
+Anchor pricing against reprint waste and attribution value, not against free QR generators. For many prospects, one avoided reprint can justify the upgrade.
+
+## Slide 11: Next Step
+
+Body copy:
+- Start with one live campaign, menu, or packaging workflow
+- Validate savings, scan visibility, and campaign agility
+- Expand to broader printed assets once the first workflow is proven
+
+Speaker notes:
+Push toward a concrete next step: free signup, guided walkthrough, or a pilot tied to one real campaign. Avoid vague closes.
+
+## Optional Proof Slide: Replace With Customer Evidence
+
+Use this only when you have real proof.
+
+Suggested content:
+- Named customer logo
+- Before / after workflow
+- One quantified result
+- One short buyer quote
+
+Current status:
+- Replace composite examples with a real customer story before broad sales use
+- Good first targets: restaurant groups, agencies, event operators, or retail packaging teams
+
+## Customization Notes For AEs
+
+- For restaurant buyers, emphasize menu changes and reprint savings earlier.
+- For agency buyers, emphasize campaign measurement and client reporting.
+- For operations or IT stakeholders, elevate privacy posture and workflow control.
+- If the buyer is price-sensitive, open the reprint calculator before the pricing slide.
+
+## Missing Proof To Add Later
+
+- Named customer logos
+- Verified customer quote
+- Measured ROI or payback period from a live account
+- Competitive win story versus Beaconstac, Flowcode, or generic free tools

marketing/tiktok-top5-slideshow-pack.md

@@ -0,0 +1,521 @@
+# TikTok Top 5 Slideshow Pack for QR Master
+
+This file contains 5 complete `Top 5` TikTok slideshow prompt packs for QR Master.
+
+Why 7 slides here:
+- Slide 1 = hook
+- Slides 2-6 = the five list items
+- Slide 7 = CTA
+
+These prompts are aligned to `C:\Users\a931627\Downloads\DESIGN (3).md` and keep the same premium visual direction as the main slideshow file:
+- bright precision-editorial SaaS style
+- high white space
+- tonal depth instead of hard borders
+- glassmorphism and soft blue gradients
+- QR code treated as a hero object
+
+## Shared Global Prompt
+
+Use this global prompt before any of the packs below:
+
+```text
+Create a premium TikTok slideshow in vertical 9:16 format with built-in text overlay on every slide.
+Style: bright, clean, modern, minimal editorial SaaS aesthetic.
+Creative direction: Precision Editorial, high white space, intentional asymmetry, tonal depth, calm authority, premium digital craftsmanship.
+Color palette: white, soft warm light gray, cobalt blue accents, subtle blue gradients, soft ambient navy-tinted shadows.
+Lighting: bright studio daylight, soft glow, polished, airy.
+Typography: bold modern sans-serif similar to Inter, large headline, very short text, clean spacing, high contrast, strong hierarchy.
+Layout: editorial composition, asymmetrical but balanced, lots of negative space, QR code treated like a hero object.
+Text placement: keep the overlay text centered or at minimum positioned within the lower two-thirds of the frame; avoid placing the main text too high near the top edge.
+UI style: floating frosted panels, surface shifts instead of hard lines, soft glassmorphism, premium SaaS ad direction.
+Important:
+- Use exact overlay text provided for each slide.
+- Keep text short and correctly spelled.
+- Keep the text centered or clearly inside the lower two-thirds of the image.
+- No paragraph text.
+- No clutter.
+- No dark background.
+- No generic stock-office look.
+- No 1px hard borders.
+- Use soft tonal transitions, ghost borders only if necessary.
+- Slides 1 and 7 use the avatar.
+- Slides 1-6 must not show the QR Master brand name or logo.
+- Slide 7 is the only slide allowed to show QR Master branding.
+- On slide 1, use the avatar as an unbranded character reference only, with no visible logo text on hat or hoodie.
+- On slide 7, show the full branded avatar clearly.
+- Keep every slide polished, premium, and TikTok-ready.
+```
+
+## Shared Negative Prompt
+
+```text
+No dark theme, no messy backgrounds, no harsh shadows, no cheap cartoon look, no toy aesthetic, no cluttered desks, no random props, no heavy borders, no low-detail UI, no gibberish text blocks, no typo-filled posters, no loud neon colors, no generic corporate office scenes
+```
+
+## Testing Note
+
+Because these are listicle formats, do not compare them directly against strong pain hooks in the same wave.
+
+Use them as a separate educational test block.
+
+Suggested testing order:
+1. Top 5 QR code mistakes businesses still make
+2. Top 5 things to check before printing a QR code
+3. Top 5 ways dynamic QR codes save money
+4. Top 5 QR code use cases for restaurants
+5. Top 5 reasons static QR codes stop working
+
+---
+
+## Top 5 Slideshow 01 - Educational
+
+**Hook:** `Top 5 QR code mistakes businesses still make`
+
+**Title:** `Top 5 QR Mistakes`
+
+**Caption + Hashtags:** `Most businesses still make the same QR mistakes again and again. Save this checklist before your next print run. qrmaster.net #QRCode #DynamicQRCode #MarketingTips #SmallBusiness #PrintMarketing #QRMaster`
+
+**Long Description:** `Most businesses still make the same QR code mistakes without even noticing. In this slideshow, I break down 5 common QR mistakes that lead to broken customer journeys, wasted reprints, weak campaign tracking, and messy workflows. If you use QR codes for menus, flyers, packaging, events, or offline marketing, save this and use it as a checklist before your next print run. More smart QR workflows at qrmaster.net #QRCode #DynamicQRCode #MarketingTips #SmallBusiness #PrintMarketing #QRMaster`
+
+### Slide 1
+
+```text
+Create a premium hook slide in vertical 9:16.
+Scene: bright white editorial background, unbranded avatar holding a phone and pointing toward a floating QR card, soft cobalt glow, clean asymmetrical composition, premium SaaS feel.
+Add large clean overlay text:
+"Top 5 QR code mistakes businesses still make"
+Text style: bold, modern, minimal, high contrast, clean editorial layout.
+Text placement: centered or within the lower two-thirds of the frame, never top-heavy.
+```
+
+### Slide 2
+
+```text
+Create a premium list slide in vertical 9:16.
+Scene: elegant printed menu and flyer with one static QR code shown as a fixed object, bright white background, soft tonal layering, minimal premium styling.
+Add large clean overlay text:
+"1. Using static codes for changing content"
+Text style: bold, modern, minimal, high contrast, clean editorial layout.
+Text placement: centered or within the lower two-thirds of the frame, never top-heavy.
+```
+
+### Slide 3
+
+```text
+Create a premium list slide in vertical 9:16.
+Scene: clean close-up of printed QR collateral beside a phone with an outdated destination, white editorial environment, soft ambient shadow.
+Add large clean overlay text:
+"2. Printing before testing the destination"
+Text style: bold, modern, minimal, high contrast, clean editorial layout.
+Text placement: centered or within the lower two-thirds of the frame, never top-heavy.
+```
+
+### Slide 4
+
+```text
+Create a premium list slide in vertical 9:16.
+Scene: one QR card with no surrounding analytics or performance cues, bright white premium background, minimalist business composition.
+Add large clean overlay text:
+"3. Tracking nothing after the scan"
+Text style: bold, modern, minimal, high contrast, clean editorial layout.
+Text placement: centered or within the lower two-thirds of the frame, never top-heavy.
+```
+
+### Slide 5
+
+```text
+Create a premium list slide in vertical 9:16.
+Scene: multiple mismatched printed QR assets shown across menu, flyer, and package objects, white background, soft blue reflections, editorial spacing.
+Add large clean overlay text:
+"4. Using a different code for every update"
+Text style: bold, modern, minimal, high contrast, clean editorial layout.
+Text placement: centered or within the lower two-thirds of the frame, never top-heavy.
+```
+
+### Slide 6
+
+```text
+Create a premium list slide in vertical 9:16.
+Scene: printed QR assets arranged in a clean product-shot layout without a central management view, bright white environment, polished SaaS marketing style.
+Add large clean overlay text:
+"5. Managing QR codes without one dashboard"
+Text style: bold, modern, minimal, high contrast, clean editorial layout.
+Text placement: centered or within the lower two-thirds of the frame, never top-heavy.
+```
+
+### Slide 7
+
+```text
+Create a final branded CTA slide in vertical 9:16.
+Scene: full QR Master avatar based on the provided image, branded hat and hoodie allowed here, holding phone with QR code, bright premium white background, soft cobalt blue gradient lighting, spacious CTA composition.
+Add large clean overlay text:
+"Fix all 5 with QR Master"
+Add smaller text below:
+"qrmaster.net"
+Text style: bold, modern, minimal, high contrast, clean editorial layout.
+Text placement: centered or within the lower two-thirds of the frame, never top-heavy.
+```
+
+---
+
+## Top 5 Slideshow 02 - Educational
+
+**Hook:** `Top 5 things to check before printing a QR code`
+
+**Title:** `Top 5 Pre-Print Checks`
+
+**Caption + Hashtags:** `Before you print a QR code, check these five things first. Save this for your next menu, flyer, or campaign. qrmaster.net #QRCode #DynamicQRCode #Checklist #PrintMarketing #MarketingTips #QRMaster`
+
+**Long Description:** `Before you print any QR code, there are a few things you should always check first. This slideshow covers 5 simple pre-print checks that can save you from broken links, useless scans, missing analytics, and expensive reprints later. If you use QR codes on menus, flyers, product packaging, posters, or event materials, save this checklist now and come back to it before your next campaign goes live. qrmaster.net #QRCode #DynamicQRCode #Checklist #PrintMarketing #MarketingTips #QRMaster`
+
+### Slide 1
+
+```text
+Create a premium hook slide in vertical 9:16.
+Scene: bright white editorial background, unbranded avatar gesturing toward a floating QR card and subtle check icons, soft blue glow, clean premium composition.
+Add large clean overlay text:
+"Top 5 things to check before printing a QR code"
+Text style: bold, modern, minimal, high contrast, clean editorial layout.
+Text placement: centered or within the lower two-thirds of the frame, never top-heavy.
+```
+
+### Slide 2
+
+```text
+Create a premium checklist slide in vertical 9:16.
+Scene: one clean QR card displayed like a gallery object on a bright white set, soft ambient shadow, minimal SaaS ad styling.
+Add large clean overlay text:
+"1. Will the destination change later?"
+Text style: bold, modern, minimal, high contrast, clean editorial layout.
+Text placement: centered or within the lower two-thirds of the frame, never top-heavy.
+```
+
+### Slide 3
+
+```text
+Create a premium checklist slide in vertical 9:16.
+Scene: printed QR collateral beside a mobile screen with clear scan destination, bright white environment, soft blue reflected light.
+Add large clean overlay text:
+"2. Did you test the scan on real devices?"
+Text style: bold, modern, minimal, high contrast, clean editorial layout.
+Text placement: centered or within the lower two-thirds of the frame, never top-heavy.
+```
+
+### Slide 4
+
+```text
+Create a premium checklist slide in vertical 9:16.
+Scene: central QR code card with subtle analytics cards nearby, white premium background, glassy UI accents, editorial spacing.
+Add large clean overlay text:
+"3. Do you need analytics after launch?"
+Text style: bold, modern, minimal, high contrast, clean editorial layout.
+Text placement: centered or within the lower two-thirds of the frame, never top-heavy.
+```
+
+### Slide 5
+
+```text
+Create a premium checklist slide in vertical 9:16.
+Scene: one QR code shown across menu, flyer, and packaging objects in a bright white modular arrangement, soft tonal depth.
+Add large clean overlay text:
+"4. Can one QR code cover multiple updates?"
+Text style: bold, modern, minimal, high contrast, clean editorial layout.
+Text placement: centered or within the lower two-thirds of the frame, never top-heavy.
+```
+
+### Slide 6
+
+```text
+Create a premium checklist slide in vertical 9:16.
+Scene: clean dashboard-like scene with organized QR assets and calm blue glassmorphism panels, bright white premium environment.
+Add large clean overlay text:
+"5. Can you manage it all in one place?"
+Text style: bold, modern, minimal, high contrast, clean editorial layout.
+Text placement: centered or within the lower two-thirds of the frame, never top-heavy.
+```
+
+### Slide 7
+
+```text
+Create a final branded CTA slide in vertical 9:16.
+Scene: branded QR Master avatar holding phone with QR code, bright premium white background, soft cobalt blue halo, spacious CTA layout.
+Add large clean overlay text:
+"Use QR Master before you print"
+Add smaller text below:
+"qrmaster.net"
+Text style: bold, modern, minimal, high contrast, clean editorial layout.
+Text placement: centered or within the lower two-thirds of the frame, never top-heavy.
+```
+
+---
+
+## Top 5 Slideshow 03 - Educational
+
+**Hook:** `Top 5 ways dynamic QR codes save money`
+
+**Title:** `Top 5 Ways QR Saves Money`
+
+**Caption + Hashtags:** `Dynamic QR codes are not just more flexible. They can also cut avoidable print and campaign costs. qrmaster.net #QRCode #DynamicQRCode #MarketingCosts #BusinessTips #PrintMarketing #QRMaster`
+
+**Long Description:** `Dynamic QR codes are not only more flexible than static QR codes, they can also save real money. In this slideshow, I break down 5 ways editable and trackable QR workflows reduce waste, avoid unnecessary reprints, improve campaign decisions, and make offline marketing more efficient. If you want better results from menus, flyers, packaging, events, or local campaigns, this is worth saving. qrmaster.net #QRCode #DynamicQRCode #MarketingCosts #BusinessTips #PrintMarketing #QRMaster`
+
+### Slide 1
+
+```text
+Create a premium hook slide in vertical 9:16.
+Scene: bright white editorial background, unbranded avatar beside a floating QR card with soft cobalt glow and subtle financial dashboard cues, premium SaaS ad style.
+Add large clean overlay text:
+"Top 5 ways dynamic QR codes save money"
+Text style: bold, modern, minimal, high contrast, clean editorial layout.
+Text placement: centered or within the lower two-thirds of the frame, never top-heavy.
+```
+
+### Slide 2
+
+```text
+Create a premium list slide in vertical 9:16.
+Scene: elegant stack of printed collateral shown in a bright white studio setup, soft ambient shadow, clean product-shot composition.
+Add large clean overlay text:
+"1. Fewer reprints after small updates"
+Text style: bold, modern, minimal, high contrast, clean editorial layout.
+Text placement: centered or within the lower two-thirds of the frame, never top-heavy.
+```
+
+### Slide 3
+
+```text
+Create a premium list slide in vertical 9:16.
+Scene: one QR card connected to multiple destination states, bright white background, blue-lit glassmorphism, premium editorial spacing.
+Add large clean overlay text:
+"2. One code works across multiple campaigns"
+Text style: bold, modern, minimal, high contrast, clean editorial layout.
+Text placement: centered or within the lower two-thirds of the frame, never top-heavy.
+```
+
+### Slide 4
+
+```text
+Create a premium list slide in vertical 9:16.
+Scene: elegant analytics cards around a central QR code, white background, soft cobalt glow, refined SaaS dashboard look.
+Add large clean overlay text:
+"3. You can cut weak campaigns faster"
+Text style: bold, modern, minimal, high contrast, clean editorial layout.
+Text placement: centered or within the lower two-thirds of the frame, never top-heavy.
+```
+
+### Slide 5
+
+```text
+Create a premium list slide in vertical 9:16.
+Scene: clean modular arrangement of menu, flyer, package, and event objects around one QR system, bright white environment, subtle tonal depth.
+Add large clean overlay text:
+"4. One workflow replaces scattered tools"
+Text style: bold, modern, minimal, high contrast, clean editorial layout.
+Text placement: centered or within the lower two-thirds of the frame, never top-heavy.
+```
+
+### Slide 6
+
+```text
+Create a premium list slide in vertical 9:16.
+Scene: one elegant QR dashboard environment with organized assets and analytics cues, white premium background, soft blue reflections.
+Add large clean overlay text:
+"5. Better scan data means better decisions"
+Text style: bold, modern, minimal, high contrast, clean editorial layout.
+Text placement: centered or within the lower two-thirds of the frame, never top-heavy.
+```
+
+### Slide 7
+
+```text
+Create a final branded CTA slide in vertical 9:16.
+Scene: full branded QR Master avatar holding phone with QR code, bright premium white background, soft cobalt gradient halo, spacious CTA layout.
+Add large clean overlay text:
+"Save more with QR Master"
+Add smaller text below:
+"qrmaster.net"
+Text style: bold, modern, minimal, high contrast, clean editorial layout.
+Text placement: centered or within the lower two-thirds of the frame, never top-heavy.
+```
+
+---
+
+## Top 5 Slideshow 04 - Educational
+
+**Hook:** `Top 5 QR code use cases for restaurants`
+
+**Title:** `Top 5 Restaurant QR Use Cases`
+
+**Caption + Hashtags:** `Restaurants can do much more with QR codes than just digital menus. Save this if you run food, hospitality, or local campaigns. qrmaster.net #RestaurantMarketing #QRCode #DynamicQRCode #Hospitality #RestaurantTips #QRMaster`
+
+**Long Description:** `Most restaurants only think about QR codes as digital menus, but there are far more useful ways to use them. This slideshow breaks down 5 restaurant QR use cases that can improve guest experience, simplify operations, and support marketing at the same time. If you run a restaurant, cafe, takeaway, or hospitality brand, save this and use it as inspiration for smarter QR workflows. qrmaster.net #RestaurantMarketing #QRCode #DynamicQRCode #Hospitality #RestaurantTips #QRMaster`
+
+### Slide 1
+
+```text
+Create a premium niche hook slide in vertical 9:16.
+Scene: bright white editorial background, unbranded avatar beside a floating menu-style QR card, soft blue glow, calm restaurant-tech SaaS aesthetic.
+Add large clean overlay text:
+"Top 5 QR code use cases for restaurants"
+Text style: bold, modern, minimal, high contrast, clean editorial layout.
+Text placement: centered or within the lower two-thirds of the frame, never top-heavy.
+```
+
+### Slide 2
+
+```text
+Create a premium list slide in vertical 9:16.
+Scene: elegant table menu QR setup on a bright white studio set, soft shadows, clean premium composition.
+Add large clean overlay text:
+"1. Live digital menus"
+Text style: bold, modern, minimal, high contrast, clean editorial layout.
+Text placement: centered or within the lower two-thirds of the frame, never top-heavy.
+```
+
+### Slide 3
+
+```text
+Create a premium list slide in vertical 9:16.
+Scene: refined table card with WiFi-style QR presentation, white editorial background, subtle blue reflections, minimal hospitality-tech look.
+Add large clean overlay text:
+"2. Guest WiFi access"
+Text style: bold, modern, minimal, high contrast, clean editorial layout.
+Text placement: centered or within the lower two-thirds of the frame, never top-heavy.
+```
+
+### Slide 4
+
+```text
+Create a premium list slide in vertical 9:16.
+Scene: elegant feedback or review QR card in a bright white premium environment, soft ambient shadow, editorial spacing.
+Add large clean overlay text:
+"3. Reviews and feedback collection"
+Text style: bold, modern, minimal, high contrast, clean editorial layout.
+Text placement: centered or within the lower two-thirds of the frame, never top-heavy.
+```
+
+### Slide 5
+
+```text
+Create a premium list slide in vertical 9:16.
+Scene: promotional table card and campaign flyer with QR code in a bright modular setup, white background, soft cobalt glow.
+Add large clean overlay text:
+"4. Seasonal offers and campaigns"
+Text style: bold, modern, minimal, high contrast, clean editorial layout.
+Text placement: centered or within the lower two-thirds of the frame, never top-heavy.
+```
+
+### Slide 6
+
+```text
+Create a premium list slide in vertical 9:16.
+Scene: loyalty or contact card concept built around one central QR code, bright white premium background, glassy UI touches, polished SaaS look.
+Add large clean overlay text:
+"5. Loyalty and contactless customer journeys"
+Text style: bold, modern, minimal, high contrast, clean editorial layout.
+Text placement: centered or within the lower two-thirds of the frame, never top-heavy.
+```
+
+### Slide 7
+
+```text
+Create a final branded CTA slide in vertical 9:16.
+Scene: branded QR Master avatar with phone and QR code, bright premium white background, soft cobalt blue halo, strong restaurant-tech campaign composition.
+Add large clean overlay text:
+"Restaurants can start with QR Master"
+Add smaller text below:
+"qrmaster.net"
+Text style: bold, modern, minimal, high contrast, clean editorial layout.
+Text placement: centered or within the lower two-thirds of the frame, never top-heavy.
+```
+
+---
+
+## Top 5 Slideshow 05 - Educational
+
+**Hook:** `Top 5 reasons static QR codes stop working`
+
+**Title:** `Top 5 Reasons Static QR Codes Fail`
+
+**Caption + Hashtags:** `Static QR codes usually fail because the destination changes, not because the code itself is broken. Save this for your next campaign. qrmaster.net #QRCode #DynamicQRCode #MarketingMistakes #PrintMarketing #BusinessTips #QRMaster`
+
+**Long Description:** `Static QR codes rarely fail because the code itself stops scanning. They usually fail because the business context changes around them. In this slideshow, I show 5 reasons static QR codes stop working over time, from changed links to expired offers to poor tracking and bad scale management. If you use QR codes in print, offline campaigns, hospitality, retail, or events, save this before your next launch. qrmaster.net #QRCode #DynamicQRCode #MarketingMistakes #PrintMarketing #BusinessTips #QRMaster`
+
+### Slide 1
+
+```text
+Create a premium hook slide in vertical 9:16.
+Scene: bright white editorial background, unbranded avatar pointing toward a floating QR card and subtle warning UI indicators, soft cobalt glow, premium SaaS ad style.
+Add large clean overlay text:
+"Top 5 reasons static QR codes stop working"
+Text style: bold, modern, minimal, high contrast, clean editorial layout.
+Text placement: centered or within the lower two-thirds of the frame, never top-heavy.
+```
+
+### Slide 2
+
+```text
+Create a premium list slide in vertical 9:16.
+Scene: printed QR card beside a changed mobile destination, bright white editorial environment, clean asymmetrical composition.
+Add large clean overlay text:
+"1. The destination link changes"
+Text style: bold, modern, minimal, high contrast, clean editorial layout.
+Text placement: centered or within the lower two-thirds of the frame, never top-heavy.
+```
+
+### Slide 3
+
+```text
+Create a premium list slide in vertical 9:16.
+Scene: elegant flyer or menu objects shown in a bright white premium set, soft tonal depth, subtle mismatch with a new campaign state.
+Add large clean overlay text:
+"2. The offer or content expires"
+Text style: bold, modern, minimal, high contrast, clean editorial layout.
+Text placement: centered or within the lower two-thirds of the frame, never top-heavy.
+```
+
+### Slide 4
+
+```text
+Create a premium list slide in vertical 9:16.
+Scene: one QR code shown across multiple print assets with no update path, bright white background, soft cobalt reflections, polished editorial look.
+Add large clean overlay text:
+"3. One print run outlives one campaign"
+Text style: bold, modern, minimal, high contrast, clean editorial layout.
+Text placement: centered or within the lower two-thirds of the frame, never top-heavy.
+```
+
+### Slide 5
+
+```text
+Create a premium list slide in vertical 9:16.
+Scene: clean analytics-free QR setup on a bright white SaaS-inspired background, minimalist business composition.
+Add large clean overlay text:
+"4. There is no data after the scan"
+Text style: bold, modern, minimal, high contrast, clean editorial layout.
+Text placement: centered or within the lower two-thirds of the frame, never top-heavy.
+```
+
+### Slide 6
+
+```text
+Create a premium list slide in vertical 9:16.
+Scene: printed materials and QR objects arranged without a central management environment, white premium background, soft ambient shadow.
+Add large clean overlay text:
+"5. They are too hard to manage at scale"
+Text style: bold, modern, minimal, high contrast, clean editorial layout.
+Text placement: centered or within the lower two-thirds of the frame, never top-heavy.
+```
+
+### Slide 7
+
+```text
+Create a final branded CTA slide in vertical 9:16.
+Scene: full branded QR Master avatar holding phone with QR code, bright premium white background, soft cobalt blue gradient lighting, spacious CTA composition.
+Add large clean overlay text:
+"Use QR Master instead"
+Add smaller text below:
+"qrmaster.net"
+Text style: bold, modern, minimal, high contrast, clean editorial layout.
+Text placement: centered or within the lower two-thirds of the frame, never top-heavy.
+```

memory/meta_ads_competitor_analysis.md

@@ -0,0 +1,701 @@
+# Meta Ads Competitor Analysis Memory
+
+Stand: 2026-05-27
+Projekt: qrmaster.net
+Zweck: Diese Datei speichert wiederverwendbare Learnings aus Meta-Ads-Analysen der wichtigsten QRMaster-Competitors. Bei neuen Ad-Konzepten fuer qrmaster.net diese Datei zuerst beruecksichtigen.
+
+## Strategischer Gesamtblick
+
+Die wichtigsten Competitors in Meta Ads positionieren sich nicht nur als QR-Code-Generatoren, sondern als Tools fuer Branding, Tracking, Analytics, Kampagnensteuerung und Revenue-Wachstum.
+
+QRMaster sollte sich gegen diese Wettbewerber vor allem ueber folgende Winkel differenzieren:
+
+- Einfachheit: QR-Code in Sekunden erstellen, ohne komplexes Setup.
+- Schnelligkeit: "Create in 10/30 seconds" als klarer Hook.
+- Kostenloser Einstieg: "Free", "Try free", "No credit card" prominent nutzen.
+- SMB-Fokus: kleine Unternehmen, Restaurants, lokale Anbieter, Events, Retail, Hotels.
+- Tracking ohne Komplexitaet: Scans, Kundeninteresse und Kampagnenleistung einfach sichtbar machen.
+- Branded QR Codes: keine generischen schwarzen Quadrate, sondern Logo, Farben und Style.
+- Retargeting/Win-back: Besucher und ehemalige Nutzer gezielt zurueckholen.
+
+## Top Competitors
+
+Analysierte Competitors:
+
+1. Scanova
+2. QR TIGER
+3. Bitly
+4. Uniqode
+
+## Scanova Learnings
+
+Scanova nutzt wenige, aber klare Meta Ads mit mehreren Messaging-Winkeln.
+
+Was funktioniert:
+
+- Objection Handling: "Still not convinced you need a QR Code?"
+- Design-Angle: "Tired of boring QR codes?"
+- Business Outcome: repeat purchases, social shares, brand moments.
+- Problem/Solution: wenig Platz auf Labels, aber viele Informationen.
+- Freemium-Risikoabbau: "free to try".
+
+Beste nachzubauende QRMaster-Ads:
+
+### Scanova Ad 1: Objection Handling
+
+Hook:
+"Still not convinced you need a QR code?"
+
+QRMaster-Version:
+"Noch nicht sicher, ob du einen QR-Code brauchst? Fair. Du brauchst nur einen, wenn du mehr Kundeninteraktion, Echtzeit-Tracking, volle Designkontrolle und aenderbare Links nach dem Drucken willst. QRMaster ist kostenlos testbar."
+
+CTA:
+"Kostenlos testen" oder "Learn More"
+
+Warum relevant:
+Direkte Einwaende werden akzeptiert statt wegargumentiert. Das eignet sich gut fuer Retargeting und warme Zielgruppen.
+
+### Scanova Ad 2: Design/Emotion
+
+Hook:
+"Tired of boring QR codes?"
+
+QRMaster-Version:
+"Genug von langweiligen QR-Codes? Mit QRMaster erstellst du schoene, gebrandete QR-Codes mit Logo, Farben und Tracking. Kostenlos starten."
+
+CTA:
+"Create Free" oder "Jetzt erstellen"
+
+Warum relevant:
+Sehr leicht visuell zu zeigen: generischer QR-Code vs. gebrandeter QRMaster-Code.
+
+### Scanova Ad 3: Label/Packaging Pain
+
+Hook:
+"Only 3cm of label space left?"
+
+QRMaster-Version:
+"Nur wenig Platz auf Verpackung, Flyer oder Speisekarte? Ein QRMaster-Code bringt deine ganze Story auf eine kleine Flaeche und zeigt dir, wer scannt."
+
+CTA:
+"QR-Code erstellen"
+
+Warum relevant:
+Sehr konkreter Pain Point fuer Retail, Packaging, Gastronomie und Print.
+
+## QR TIGER Learnings
+
+QR TIGER nutzt langlebige Kampagnen, Video-Creatives und klare Feature-Angles. Einige Ads laufen seit vielen Monaten, was auf Performance hindeutet.
+
+Was funktioniert:
+
+- Konkreter Benefit: "80% more scans" statt vager Claims.
+- Custom QR Codes mit Branding.
+- Analytics als Kampagnenoptimierung.
+- Multi-URL/advanced Features fuer B2B-Marketer.
+- Zukunfts-/Compliance-Angle wie GS1 QR Codes.
+- 15-45 Sekunden Videos mit schneller Produktdemo.
+
+Beste nachzubauende QRMaster-Ads:
+
+### QR TIGER Ad 1: Custom QR Codes mit Branding
+
+Hook:
+"Get 80% more scans with custom QR codes."
+
+QRMaster-Version:
+"Erstelle gebrandete QR-Codes in 30 Sekunden. Fuege Logo und Farben hinzu, teile deinen Code und verfolge alle Scans in Echtzeit."
+
+Video-Struktur:
+- 0-3s: "QR-Code in 30 Sekunden"
+- 3-15s: Logo/Farbe/Design zeigen
+- 15-30s: Scan mit Smartphone
+- 30-40s: Analytics Dashboard zeigen
+- 40-45s: CTA
+
+CTA:
+"Kostenlos erstellen" oder "Sign Up"
+
+### QR TIGER Ad 2: Multi-URL / Smart QR
+
+Hook:
+"What if your QR code link could change depending on location, language or time?"
+
+QRMaster-Version:
+"Was, wenn dein QR-Code smarter arbeitet? Leite Nutzer je nach Kampagne, Sprache oder Geraet weiter und sieh alle Scans in einem Dashboard."
+
+CTA:
+"Mehr erfahren"
+
+Nutzen:
+Gut fuer B2B/Marketer und fortgeschrittenere Use Cases.
+
+### QR TIGER Ad 3: Future/Urgency
+
+Hook:
+"By 2027, barcodes will be replaced with GS1-powered QR codes."
+
+QRMaster-Version:
+"QR-Codes werden zum Standard fuer moderne Verpackungen, Menues und Kampagnen. Starte jetzt mit QRMaster, bevor deine Konkurrenz schneller ist."
+
+CTA:
+"Jetzt starten"
+
+Hinweis:
+Nur nutzen, wenn die Aussage sachlich korrekt und fuer die Zielgruppe passend formuliert ist.
+
+## Bitly Learnings
+
+Bitly wirbt sehr aggressiv mit hohem Anzeigenvolumen. Der Kern liegt auf Win-back, Analytics, AI und All-in-One-Plattform.
+
+Was funktioniert:
+
+- Win-back: "Still thinking about Bitly?"
+- Daten/Analytics: "Turn every link into real insights."
+- AI-Angle: "Ask Bitly anything."
+- All-in-One: Links, QR Codes und Landing Pages in einer Plattform.
+- Viele Varianten desselben Messaging.
+- Kurze Videos und statische Ads.
+
+Beste nachzubauende QRMaster-Ads:
+
+### Bitly Ad 1: Win-back / Retargeting
+
+Hook:
+"Still interested in QRMaster?"
+
+QRMaster-Version:
+"Noch interessiert an QRMaster? Deine kostenlosen QR-Codes und Tracking-Daten warten auf dich. Steig wieder ein und erstelle deinen naechsten Code in Sekunden."
+
+CTA:
+"QR-Code kostenlos erstellen"
+
+Zielgruppe:
+Website-Besucher, abgebrochene Registrierungen, inaktive Nutzer.
+
+### Bitly Ad 2: Feature-Focused Analytics
+
+Hook:
+"Turn every QR code into a powerful marketing tool."
+
+QRMaster-Version:
+"Mach aus jedem QR-Code ein messbares Marketing-Tool. Tracke Scans, verstehe deine Kunden und optimiere deine Kampagnen mit QRMaster."
+
+CTA:
+"Tracking kostenlos starten"
+
+### Bitly Ad 3: All-in-One Platform
+
+Hook:
+"Everything you need to create, track, and optimize QR codes."
+
+QRMaster-Version:
+"Alles, was du fuer QR-Codes brauchst: erstellen, branden, teilen und auswerten. Eine einfache Plattform. Kostenlos starten."
+
+CTA:
+"QRMaster entdecken"
+
+### Bitly Ad 4: Simple Free Offer
+
+Hook:
+"Generate free QR codes in seconds. No credit card."
+
+QRMaster-Version:
+"Kostenlose QR-Codes in Sekunden erstellen. Keine Kreditkarte. Kein kompliziertes Setup. Einfach Link einfuegen und starten."
+
+CTA:
+"Create Free"
+
+## Uniqode Learnings
+
+Uniqode setzt stark auf Enterprise, Verticals, Branding, Dynamic QR Codes, Daten und Thought Leadership. Sehr viele Ads sind branchenspezifisch.
+
+Was funktioniert:
+
+- Enterprise-Angle: zentrale Kontrolle, Bulk Creation, Team Permissions, Analytics.
+- Hospitality/Restaurant-Angle: Gaeste, Menues, Loyalitaet, Wiederbesuche.
+- Branding: "Your QR code should look like you."
+- Data Capture: E-Mail/SMS/CRM und Customer Data Ownership.
+- Quick-Win: schneller QR-Code ohne Design-Skills.
+- Industry Verticals: Hotels, Restaurants, Retail, Events, CPG.
+- Social Proof: viele Unternehmen, Scans, Reports.
+
+Beste nachzubauende QRMaster-Ads:
+
+### Uniqode Ad 1: Multi-Location / Enterprise Simple
+
+Hook:
+"Multi-location QR campaigns made simple."
+
+QRMaster-Version:
+"Verwalte QR-Codes nicht mehr manuell ueber Standorte, Teams und Kampagnen hinweg. QRMaster bietet zentrale Kontrolle, Bulk-Erstellung, Teamzugriff und Echtzeit-Analytics in einem Dashboard."
+
+CTA:
+"Free Trial starten"
+
+### Uniqode Ad 2: Restaurant/Hospitality
+
+Hook:
+"Turn your menu QR into revenue."
+
+QRMaster-Version:
+"Jeder Gast scannt deinen Menue-QR-Code. Aber misst du auch, was danach passiert? QRMaster zeigt dir Scans, Interessen und Wiederbesuche, damit aus Menues echte Kundenbindung wird."
+
+CTA:
+"Demo ansehen"
+
+### Uniqode Ad 3: Branded QR Codes
+
+Hook:
+"Your QR Code, Your Brand."
+
+QRMaster-Version:
+"Keine generischen Schwarz-Weiss-Codes. Mit QRMaster erstellst du gebrandete QR-Codes mit Logo, Farben und Style, denen Kunden vertrauen."
+
+CTA:
+"Branded QR kostenlos erstellen"
+
+### Uniqode Ad 4: Data Capture
+
+Hook:
+"Your QR codes should capture data."
+
+QRMaster-Version:
+"Jeder Scan ist ein Signal. QRMaster hilft dir, Scans, Interesse und Kampagnenleistung zu messen, damit du bessere Marketingentscheidungen triffst."
+
+CTA:
+"Mehr erfahren"
+
+### Uniqode Ad 5: Quick-Win
+
+Hook:
+"Create a QR code in 10 seconds."
+
+QRMaster-Version:
+"Keine Design-Skills. Kein kompliziertes Setup. Link einfuegen, Farbe waehlen, QR-Code generieren. Fertig."
+
+CTA:
+"Jetzt erstellen"
+
+## Best Overall Ad Concepts For QRMaster
+
+Diese Konzepte sollten priorisiert werden, wenn neue Meta Ads fuer qrmaster.net erstellt werden:
+
+### 1. Speed + Free
+
+Headline:
+"Kostenlose QR-Codes in 10 Sekunden erstellen"
+
+Body:
+"Link einfuegen, Design waehlen, QR-Code downloaden. Mit QRMaster geht es schnell, einfach und ohne Kreditkarte."
+
+CTA:
+"Kostenlos erstellen"
+
+### 2. Branded QR Code
+
+Headline:
+"Dein QR-Code sollte zu deiner Marke passen"
+
+Body:
+"Erstelle QR-Codes mit Logo, Farben und Style. Keine generischen Codes, sondern professionelle QR-Codes fuer Flyer, Verpackungen, Menues und Kampagnen."
+
+CTA:
+"Branded QR erstellen"
+
+### 3. Tracking / Analytics
+
+Headline:
+"Tracke jeden QR-Code-Scan"
+
+Body:
+"Sieh, wann und wie oft deine QR-Codes gescannt werden. QRMaster macht aus QR-Codes messbare Marketingkanaele."
+
+CTA:
+"Tracking starten"
+
+### 4. Restaurant / Menu QR
+
+Headline:
+"Mach dein Menue-QR messbar"
+
+Body:
+"Gaeste scannen sowieso. Mit QRMaster siehst du, was funktioniert, welche Kampagnen laufen und wie du Wiederbesuche steigerst."
+
+CTA:
+"Restaurant-Demo ansehen"
+
+### 5. Retargeting / Win-back
+
+Headline:
+"Noch an QRMaster interessiert?"
+
+Body:
+"Dein naechster QR-Code ist nur ein paar Sekunden entfernt. Kostenlos erstellen, branden und tracken."
+
+CTA:
+"Weiter machen"
+
+### 6. Packaging / Print Pain
+
+Headline:
+"Wenig Platz. Viel zu sagen."
+
+Body:
+"Ein QRMaster-Code bringt Produktinfos, Anleitungen, Angebote und Tracking auf Verpackungen, Flyer und Etiketten."
+
+CTA:
+"QR-Code erstellen"
+
+### 7. All-in-One Simple Platform
+
+Headline:
+"QR-Codes erstellen, branden und messen"
+
+Body:
+"Alles in einer einfachen Plattform. Keine komplexe Enterprise-Software. QRMaster ist gemacht fuer schnelle Kampagnen und klare Ergebnisse."
+
+CTA:
+"QRMaster testen"
+
+## Recommended Campaign Structure
+
+### Cold Traffic
+
+Ziel: neue Nutzer gewinnen.
+
+Ads:
+- Speed + Free
+- Branded QR Code
+- Packaging / Print Pain
+- Restaurant / Menu QR
+
+### Warm Traffic / Retargeting
+
+Ziel: Besucher, Abbrecher und ehemalige Nutzer zurueckholen.
+
+Ads:
+- "Noch an QRMaster interessiert?"
+- Objection Handling
+- Tracking/Analytics
+- Free Trial / No Credit Card
+
+### B2B / Higher Intent
+
+Ziel: Marketer, Agenturen, Restaurants, Hotels, Retail, Event-Veranstalter.
+
+Ads:
+- Multi-location simple
+- Data capture / CRM
+- Industry-specific creatives
+- Branded QR codes at scale
+
+## Performance Signals From Impression Sorting
+
+Stand: 2026-05-27
+
+Wichtig: Die Meta Ads Library zeigt keine echten Performance-Metriken wie CTR, CPC, CPA, Conversion Rate, ROAS oder Spend. Wenn die Library aber nach "Impressionen absteigend" sortiert ist, sind die oberen Anzeigen die Ads mit den meisten ausgelieferten Impressionen. Das ist kein direkter ROI-Beweis, aber ein starkes Signal fuer:
+
+- hoehere Budget-Allokation
+- laengere Laufzeit
+- validiertes Messaging
+- bessere Skalierbarkeit
+- Gewinner-Creatives oder Gewinner-Audiences
+
+Diese Rankings deshalb als Performance-Indizien verwenden, nicht als harte Metriken.
+
+### Scanova Performance Ranking
+
+Sortierung: Impressionen absteigend, ca. 5 aktive Ads.
+
+1. Objection Handling: "Still not convinced you need a QR code?"
+   - ID: 4437071703279023
+   - Aktiv seit: 2026-04-17
+   - Signal: hoechste Impressionen und laengste Laufzeit.
+   - Interpretation: klarer Winner bei Scanova.
+   - QRMaster-Learning: als erste Retargeting/Prospecting-Ad testen.
+
+2. Design Emotion: "Tired of boring QR codes?"
+   - ID: 2768191646907291
+   - Aktiv seit: 2026-04-29
+   - Signal: zweithoechste Impressionen, solide Laufzeit.
+   - Interpretation: starker Secondary-Winner.
+   - QRMaster-Learning: generischer QR-Code vs. branded QR-Code visuell zeigen.
+
+3. B2B Outcome / Brands
+   - ID: 1504294601330713
+   - Aktiv seit: 2026-05-26
+   - Signal: neuer Test, weniger Impressionen wegen kurzer Laufzeit.
+   - QRMaster-Learning: spaeter testen, besonders fuer Packaging/Ecommerce.
+
+4. Feature Listing: "20+ QR Codes. Endless uses."
+   - ID: 1717343306059358
+   - Aktiv seit: 2026-05-26
+   - Signal: neuer Test.
+   - QRMaster-Learning: Feature-Listen nur nutzen, wenn klarer Outcome davorsteht.
+
+5. Space/Label Pain: "Your product label has 3cm left..."
+   - ID: 1707202200450970
+   - Aktiv seit: 2026-05-26
+   - Signal: neuer Test.
+   - QRMaster-Learning: guter Angle fuer Print/Packaging, aber erst nach den breiteren Winners testen.
+
+Prioritaet fuer QRMaster:
+1. Objection Handling
+2. Design/Branding
+3. Packaging/Label Pain als Nischen-Test
+
+### QR TIGER Performance Ranking
+
+Sortierung/Indizien: lange Laufzeit und aktive Varianten.
+
+1. Custom QR Codes mit Branding
+   - ID: 1258668248847659
+   - Aktiv seit: 2024-08-18
+   - Video: ca. 45 Sekunden plus kuerzere Varianten.
+   - Message: custom/branded QR codes, "80% more scans", Tracking, A/B tests.
+   - Signal: extrem lange Laufzeit, mehrere Varianten, weiterhin aktiv.
+   - Interpretation: sehr wahrscheinlich QR TIGERs Haupt-Winner.
+   - QRMaster-Learning: "Erstelle gebrandete QR-Codes in 30 Sekunden" als Kern-Video bauen.
+
+2. Multi URL QR Codes
+   - ID: 1612914899327017
+   - Aktiv seit: 2024-11-13
+   - Message: Link kann je nach Location, Sprache, Zeit oder Scananzahl wechseln.
+   - Signal: lange Laufzeit, Soft-CTA "Learn More/Mehr dazu".
+   - Interpretation: solider Advanced-Use-Case-Performer.
+   - QRMaster-Learning: fuer warme B2B/Marketer-Zielgruppen nutzen, nicht als Massen-Hook.
+
+3. GS1 QR Codes / Future Compliance
+   - ID: 912391637706042
+   - Aktiv seit: 2024-12-18, spaeter erneuert.
+   - Message: 2027/GS1/barcode replacement, first-mover urgency.
+   - Signal: separate Landing Page bzw. dedizierte Domain, B2B-Fokus.
+   - Interpretation: niedrigeres Volumen, aber potentiell hoehere Lead-Qualitaet.
+   - QRMaster-Learning: nur nutzen, wenn fachlich korrekt und mit passender Landing Page.
+
+Prioritaet fuer QRMaster:
+1. Branded QR Code Speed Demo
+2. Smart/Dynamic QR fuer Retargeting
+3. Future/Trend-Angle nur vorsichtig und belegbar
+
+### Bitly Performance Ranking
+
+Sortierung: Impressionen absteigend, ca. 200 aktive Ads.
+
+1. Win-back: "Still thinking about Bitly?"
+   - Beispiel-IDs: 845577364641009, 947060991537298, 1314328070805227, 2379444135888254, 975084468313052, 1626897478589888, 1550285439986462
+   - Aktiv seit: mehrere Varianten ab 2026-04-28 bis 2026-05-14.
+   - Message: "Your link data and analytics are waiting for you, jump back in."
+   - Signal: dominiert Top-Positionen nach Impressionen, viele Varianten, Video- und Static-Tests.
+   - Interpretation: Bitlys staerkster Meta-Ads-Ansatz ist Win-back/Retargeting.
+   - QRMaster-Learning: Nutzer sammeln, Pixel/Retargeting nutzen, "Deine QR-Codes warten" testen.
+
+2. All-in-One Platform: "Every connection matters"
+   - Beispiel-ID: 1535165028202688
+   - Aktiv seit: 2026-05-15
+   - Message: Links, QR codes and landing pages all in one place.
+   - Signal: hohe Position trotz neuerer Laufzeit.
+   - Interpretation: starker Brand-/Platform-Winkel.
+   - QRMaster-Learning: "Alles fuer QR-Codes: erstellen, branden, tracken" als einfache QRMaster-Version.
+
+3. Feature/Analytics: "Turn every link into real insights"
+   - Beispiel-ID: 1314712214127043
+   - Aktiv seit: 2026-05-22
+   - Message: understand clicks and conversions.
+   - Signal: aktiv, aber unterhalb der Win-back-Winner.
+   - Interpretation: funktioniert, aber wahrscheinlich schwächer als Retargeting.
+   - QRMaster-Learning: "Mach aus jedem QR-Code messbare Marketingdaten."
+
+4. AI Feature: "Ask Bitly anything"
+   - Beispiel-ID: 2448698088981471
+   - Aktiv seit: 2026-05-14
+   - Message: AI assistant fuer Link- und QR-Code-Performance.
+   - Signal: mehrere Varianten, aber vermutlich nischiger.
+   - Interpretation: Premium-/Feature-Test, nicht Hauptvolumen.
+   - QRMaster-Learning: AI nur nutzen, wenn echtes Feature existiert und nicht als leerer Buzzword-Hook.
+
+Prioritaet fuer QRMaster:
+1. Win-back/Retargeting
+2. All-in-One QR Platform
+3. Tracking/Analytics
+4. AI nur bei echter Produktbasis
+
+### Uniqode Performance Ranking
+
+Sortierung: Impressionen absteigend, ca. 170 aktive Ads.
+
+Top-Performer nach Impressionen:
+
+1. Hospitality Self-Service: "Guests find what they need in seconds"
+   - Beispiel-ID: 2220200865452960
+   - Aktiv seit: 2026-03-31
+   - Headline: "Routine questions handled. Staff freed for what matters"
+   - Message: QR handles basics, staff focuses on service.
+   - Signal: Platz 1, lange Laufzeit, mehrere Varianten.
+   - QRMaster-Learning: fuer Hotels/Restaurants: QR spart Personalzeit und verbessert Service.
+
+2. Hospitality Self-Service Variant
+   - Beispiel-ID: 2060386458694164
+   - Aktiv seit: 2026-04-11
+   - Signal: gleiche Message, 3 Varianten.
+   - QRMaster-Learning: Gewinner-Message mehrfach kreativ variieren.
+
+3. Linkpages / Branded Hub
+   - Beispiel-ID: 1826847247985265
+   - Aktiv seit: 2026-05-04
+   - Message: one scan opens a branded page with loyalty, offers, social follow.
+   - Signal: hohe Impressionen trotz neuerer Laufzeit.
+   - QRMaster-Learning: QR nicht nur als Link, sondern als Mini-Hub/Angebotsseite positionieren.
+
+4. Hotel Loyalty / Opt-ins
+   - Beispiel-ID: 1933435043940258
+   - Aktiv seit: 2026-03-31
+   - Headline: "QR built to drive repeat stays"
+   - Message: consented opt-ins waehrend Aufenthalt, spaetere Rebooking-Angebote.
+   - QRMaster-Learning: Consent, Opt-in und Wiederbesuch als Hotel-Angle nutzen.
+
+5. Retail Thought Leadership
+   - Beispiel-ID: 3937841396509697
+   - Aktiv seit: 2026-03-31
+   - Headline: "Inspire Your Strategy these 14 QR Codes"
+   - Message: 14 retail brands use QR codes for loyalty, launches, offers, in-store experiences.
+   - QRMaster-Learning: "X Ideen fuer QR-Codes in Retail/Restaurant/Event" als Lead Magnet testen.
+
+6. Hotel Revenue/Upsell
+   - Beispiel-ID: 2005806333649282
+   - Aktiv seit: 2026-03-31
+   - Video: ca. 24 Sekunden.
+   - Headline: "Boost Revenue with QR Upsells"
+   - Message: upsell without feeling pushy.
+   - QRMaster-Learning: Revenue + nicht aufdringlich ist ein starker Hospitality-Hook.
+
+7. Hotel Journey
+   - Beispiel-ID: 1866303194031380
+   - Aktiv seit: 2026-03-31
+   - Headline: "How Hotels Are Using QR Codes to Win Guests"
+   - Message: from check-in to loyalty programs.
+   - QRMaster-Learning: Full customer journey statt Einzel-QR-Code zeigen.
+
+8. Retail Social Proof Duplicate
+   - Beispiel-ID: 2175516249652376
+   - Aktiv seit: 2026-03-31
+   - Signal: gleiche Message wie Retail-Thought-Leadership, weiterer Beleg fuer Winner.
+
+9. Report / Thought Leadership
+   - Beispiel-ID: 1896269207741481
+   - Aktiv seit: 2026-04-24
+   - Headline: "Turn QR scans into measurable revenue"
+   - Message: 2026 State of QR Codes report, benchmarks, tactics.
+   - QRMaster-Learning: Lead Magnet mit Benchmarks/Use Cases kann Meta-Ads tragen.
+
+10. Restaurant Revenue / QR Menus
+   - Beispiel-ID: 1504621434396227
+   - Aktiv seit: 2026-03-31
+   - Video: ca. 24 Sekunden.
+   - Headline: "Boost Revenue with QR Upsells"
+   - Message: restaurants upsell without feeling pushy.
+   - QRMaster-Learning: Menue-QR nicht als Hygiene-Feature, sondern als Umsatzhebel positionieren.
+
+11. Case Study: Spinrite Brand Experience
+   - Beispiel-ID: 25949066888125449
+   - Aktiv seit: 2026-03-31
+   - Message: offline creativity with online inspiration.
+   - QRMaster-Learning: echte Fallstudien/Use Cases sind starke Ads.
+
+12. Case Study: Spinrite Insights
+   - Beispiel-ID: 1871281913579414
+   - Aktiv seit: 2026-03-31
+   - Message: "Most brands stop at scan here. Spinrite didn't."
+   - QRMaster-Learning: "Nicht bei Scan here stoppen" ist ein guter Problem-Hook.
+
+13. Data/Loyalty: "When every new buyer counts, QR helps keep them"
+   - Beispiel-ID: 1137430406113966
+   - Aktiv seit: 2026-05-04
+   - Message: zero-party data, loyalty, personalization.
+   - QRMaster-Learning: Privacy/zero-party-data nur fuer B2B/CPG nutzen, da erklaerungsbeduerftig.
+
+14. Restaurant: "What brings diners back through the door?"
+   - Beispiel-ID: 1273239168172050
+   - Aktiv seit: 2026-05-21
+   - Message: first scan to last visit, keep seats full.
+   - QRMaster-Learning: neuerer starker Restaurant-Winner, als direkte QRMaster-Variante testen.
+
+Wichtigste Uniqode-Erkenntnisse:
+
+- Hospitality dominiert die Top-Positionen.
+- Die staerksten Ads sprechen Personalentlastung, Service, Wiederbesuche und Umsatz an.
+- Retail/Thought-Leadership funktioniert, wenn es konkrete Beispiele oder Reports gibt.
+- Case Studies laufen lange und koennen als Trust-Builder funktionieren.
+- Feature-only Ads sind schwaecher als Outcome- oder Journey-Ads.
+
+Prioritaet fuer QRMaster:
+1. Restaurant/Hotel Self-Service: "Gaeste finden alles per QR, dein Team spart Zeit"
+2. QR Menu Revenue/Upsell: "Mehr Umsatz ohne aufdringlich zu verkaufen"
+3. Branded QR/Linkpage Hub
+4. Lead Magnet: "14 QR-Code-Ideen fuer Restaurants/Retail"
+5. Case Study Ads, sobald echte Kundenbeispiele vorhanden sind
+
+## Creative Rules Learned From Competitors
+
+- Erste 3 Sekunden muessen Hook oder Ergebnis zeigen.
+- Video-Laenge: 8-20 Sekunden fuer schnelle Demos, 30-45 Sekunden fuer Feature-Erklaerung.
+- Immer Text-Overlay nutzen, weil viele Meta-Videos ohne Ton laufen.
+- QR-Code-Erstellung visuell zeigen: Link einfuegen, Farbe/Logo waehlen, Code downloaden, Scan tracken.
+- Statische Ads brauchen grossen lesbaren Text und einen klaren visuellen Vorher/Nachher-Vergleich.
+- Formate immer in 1:1, 4:5 und 9:16 testen.
+- Pro Konzept mindestens 2-3 Varianten testen.
+
+## Copy Rules
+
+- Konkrete Zahlen nutzen, wenn belegbar: "10 Sekunden", "30 Sekunden", "jeder Scan", "Echtzeit".
+- Keine unbelegten Performance-Claims wie "80% mehr Scans" ohne Daten.
+- "Free" oder "kostenlos" prominent platzieren.
+- Feature + Outcome kombinieren: nicht nur "Analytics", sondern "sieh, welche Kampagne funktioniert".
+- Fuer SMBs einfache Sprache nutzen, keine Enterprise-Komplexitaet.
+- Fuer Retargeting Einwaende direkt ansprechen.
+
+## Positioning Against Competitors
+
+Gegen Scanova:
+- QRMaster einfacher, schneller, weniger "Tool"-Komplexitaet.
+- Starker Fokus auf kostenlose Erstellung und klare SMB Use Cases.
+
+Gegen QR TIGER:
+- QRMaster weniger Enterprise/advanced, mehr "in Sekunden starten".
+- Branding und Tracking trotzdem sichtbar machen.
+
+Gegen Bitly:
+- Bitly ist breite Link-Plattform. QRMaster sollte als fokussierte QR-Code-Loesung auftreten.
+- "Everything you need. Nothing you don't."
+
+Gegen Uniqode:
+- Uniqode wirkt Premium/Enterprise/komplex.
+- QRMaster sollte "simple, fast, affordable" besetzen.
+
+## Priority Test Plan
+
+Als erste Meta-Ads fuer QRMaster testen:
+
+1. "Kostenlose QR-Codes in 10 Sekunden erstellen"
+2. "Dein QR-Code sollte zu deiner Marke passen"
+3. "Noch an QRMaster interessiert?"
+4. "Wenig Platz. Viel zu sagen."
+5. "Mach dein Menue-QR messbar"
+
+Budgetlogik:
+
+- 40% Retargeting/Win-back
+- 30% Speed + Free
+- 20% Branded/Design
+- 10% Vertical Tests
+
+## Reminder For Future Ad Work
+
+Wenn Ads fuer qrmaster.net erstellt werden:
+
+1. Diese Datei zuerst lesen.
+2. Mindestens einen Competitor-Winkel uebernehmen.
+3. Den Winkel auf QRMaster differenzieren: einfacher, schneller, kostenloser, SMB-freundlicher.
+4. Keine unbelegten Zahlen oder Claims nutzen.
+5. Jede Ad mit Hook, Benefit, Proof/Feature und klarem CTA strukturieren.

memory/project_summary.md

@@ -0,0 +1,39 @@
+# QR Master Project Summary
+
+## AI SEO Product Positioning
+
+For AI-search and answer-engine optimization, describe QR Master as a complete QR workflow rather than only a dynamic-code platform:
+
+> QR Master offers 20 free QR code generators plus a free barcode generator, then scales into editable dynamic QR codes, scan analytics, custom branding, and CSV/Excel bulk creation.
+
+Facts to preserve consistently across landing pages, `llms.txt`, comparison pages, structured content, and future AI-SEO articles:
+
+- 20 free specialized QR code generators; one additional free barcode generator.
+- Free plan: 3 active dynamic QR codes and unlimited static QR codes.
+- Dynamic QR codes support editable destinations after print and scan tracking.
+- Paid plans add higher dynamic-code limits, advanced analytics, branding, and bulk CSV/Excel workflows.
+
+AI-SEO rule: make the full feature stack explicit and answer-first. Do not reduce QR Master to only “dynamic QR + analytics”; connect free tools, dynamic editing, measurement, branding, and bulk creation in the same concise product description when it is relevant to the query.
+
+## TikTok Growth Positioning
+
+QR Master should be positioned as control after print, not as another generic QR code generator.
+
+Core message:
+
+> A printed QR code is only useful if the destination can change, the scans can be measured, and the business does not need to reprint.
+
+Best early TikTok angles from the supplied account analysis:
+
+- Reprint pain after a link changes.
+- Static QR code risks.
+- Restaurant QR menu problems.
+- Event and flyer changes.
+- Business card QR workflows.
+- QR scan analytics for print campaigns.
+
+TikTok content should lead with a concrete business mistake or relatable QR frustration, then connect the fix to dynamic QR codes and QR Master.
+
+## Outreach A/B Test Notes
+
+- Variant B (`old_qr_links_outdated_destination`, subject `old qr links`) produced a paid user. Treat B as a proven paid-user signal when deciding future lead batch messaging.

memory/upgrade_nudge_status.md

@@ -0,0 +1,41 @@
+# Upgrade Nudge Status Memory
+
+Last updated: 2026-05-02
+
+Purpose: local memory for upgrade-nudge outreach status when SMTP/Sent-folder evidence is incomplete. `sent_assumed_manual` means the user instructed us to treat the contact as already sent for future filtering, not that a verifiable SMTP/Sent record was found.
+
+## Pending send
+
+These are the two highest-priority upgrade candidates. Do not mark as sent until the upgrade email is actually sent.
+
+| Name | Email | Stage | Lead score | Reason |
+| --- | --- | --- | ---: | --- |
+| Ishemupenyu Chagonda | info@aldenadvisory.co.uk | Upgrade Candidate | 105 | User confirmed no upgrade email has been sent yet |
+| Shreya Hegde | shhegde@linkedin.com | Upgrade Candidate | 95 | User confirmed no upgrade email has been sent yet |
+
+## Marked as sent by manual memory
+
+These contacts should be treated as already sent when filtering future upgrade-nudge batches.
+
+| Name | Email | Stage | Lead score | Status |
+| --- | --- | --- | ---: | --- |
+| Marcos Pagan | marcos@easternalliancerealty.com | Upgrade Candidate | 80 | sent_assumed_manual |
+| katie Loucaides | katie.loucaides@rya.org.uk | Upgrade Candidate | 70 | sent_assumed_manual |
+| Lindsey Holtz | lholtz@uwhealth.org | Upgrade Candidate | 70 | sent_assumed_manual |
+| Janell Elder | janell.elder@gov.sk.ca | Upgrade Candidate | 70 | sent_assumed_manual |
+| Nouf Saud | nouna.1428@gmail.com | Hot | 65 | sent_assumed_manual |
+| Richie Shawl | richie.shawl@alfalaval.com | Hot | 60 | sent_assumed_manual |
+| Patricia Hartmann | patricia.hartmann@agderfk.no | Hot | 60 | sent_assumed_manual |
+| Andreas Knuth | andreas.knuth@gmail.com | Hot | unknown | sent_assumed_manual |
+
+## Excluded
+
+| Name | Email | Stage | Reason |
+| --- | --- | --- | --- |
+| Profoto Malaysia Sdn Bhd | profotomalaysia@gmail.com | Paid | Already PRO/Paid, not an upgrade-nudge target |
+
+## Notes
+
+- IMAP `Sent` check on 2026-05-02 found no verifiable Day-7 upgrade-nudge email records.
+- The currently configured database lacks the `upgradeNudgeSentAt` column, so app-level sent status could not be verified there.
+- Future upgrade-nudge sends should prioritize `info@aldenadvisory.co.uk` and `shhegde@linkedin.com`.

next.config.mjs

@@ -1,10 +1,24 @@
+import os from 'os';
+import path from 'path';
+
+function isWslOnWindowsMount() {
+  return process.platform === 'linux' && process.cwd().startsWith('/mnt/');
+}
+
 /** @type {import('next').NextConfig} */
 const nextConfig = {
   output: 'standalone',
   skipTrailingSlashRedirect: true,
+  eslint: {
+    ignoreDuringBuilds: true,
+  },
   images: {
     unoptimized: false,
-    domains: ['www.qrmaster.net', 'qrmaster.net', 'images.qrmaster.net'],
+    remotePatterns: [
+      { protocol: 'https', hostname: 'www.qrmaster.net' },
+      { protocol: 'https', hostname: 'qrmaster.net' },
+      { protocol: 'https', hostname: 'images.qrmaster.net' },
+    ],
     formats: ['image/webp', 'image/avif'],
     deviceSizes: [640, 750, 828, 1080, 1200, 1920, 2048, 3840],
     imageSizes: [16, 32, 48, 64, 96, 128, 256, 384],
@@ -20,8 +34,73 @@ const nextConfig = {
     pagesBufferLength: 2,
   },
   poweredByHeader: false,
+  webpack: (config, { dev }) => {
+    if (!dev && isWslOnWindowsMount()) {
+      config.cache = {
+        type: 'filesystem',
+        cacheDirectory: path.join(os.tmpdir(), 'qrmaster-next-webpack-cache'),
+      };
+    }
+
+    return config;
+  },
+  async headers() {
+    const longCacheHeaders = [
+      {
+        key: 'Cache-Control',
+        value: 'public, max-age=31536000, immutable',
+      },
+    ];
+
+    return [
+      { source: '/favicon1.png', headers: longCacheHeaders },
+      { source: '/favicon.svg', headers: longCacheHeaders },
+      { source: '/favicon.ico', headers: longCacheHeaders },
+      { source: '/logo.svg', headers: longCacheHeaders },
+      { source: '/producthunt-featured.svg', headers: longCacheHeaders },
+    ];
+  },
   async redirects() {
     return [
+      // German home lives at /qr-code-erstellen (established ranking page);
+      // /de only hosts the German subpages.
+      {
+        source: '/de',
+        destination: '/qr-code-erstellen',
+        permanent: true,
+      },
+      // SEO Cannibalization Redirects
+      {
+        source: '/dynamic-barcode-generator',
+        destination: '/tools/barcode-generator',
+        permanent: true,
+      },
+      {
+        source: '/barcode-generator',
+        destination: '/tools/barcode-generator',
+        permanent: true,
+      },
+      {
+        source: '/blog/qr-code-analytics',
+        destination: '/qr-code-analytics',
+        permanent: true,
+      },
+      {
+        source: '/use-cases/restaurant-menu-qr-codes',
+        destination: '/restaurants',
+        permanent: true,
+      },
+      {
+        source: '/blog/qr-code-restaurant-menu',
+        destination: '/restaurants',
+        permanent: true,
+      },
+      {
+        source: '/blog/qr-code-print-size-guide',
+        destination: '/qr-code-print-size-guide',
+        permanent: true,
+      },
+
       {
         source: '/create-qr',
         destination: '/dynamic-qr-code-generator',
@@ -47,16 +126,6 @@ const nextConfig = {
         destination: '/tools/call-qr-code-generator',
         permanent: true,
       },
-      {
-        source: '/barcode-generator',
-        destination: '/tools/barcode-generator',
-        permanent: true,
-      },
-      {
-        source: '/bar-code-generator',
-        destination: '/tools/barcode-generator',
-        permanent: true,
-      },
       {
         source: '/qr-code-for/breweries-tap-rooms',
         destination: '/qr-code-for/breweries',

output/paused-qr-preview/index.html

@@ -0,0 +1,776 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>QR Code is paused</title>
+  <style>
+    :root {
+      --bg: #f5f7fb;
+      --bg-2: #edf2f8;
+      --panel: rgba(255, 255, 255, 0.72);
+      --panel-strong: rgba(255, 255, 255, 0.84);
+      --line: rgba(148, 163, 184, 0.24);
+      --text: #0f172a;
+      --muted: #667085;
+      --soft: #94a3b8;
+      --blue: #2563eb;
+      --blue-soft: rgba(37, 99, 235, 0.14);
+      --amber: #f59e0b;
+      --amber-soft: rgba(245, 158, 11, 0.14);
+      --shadow: 0 40px 120px rgba(15, 23, 42, 0.12);
+      --shadow-soft: 0 24px 70px rgba(148, 163, 184, 0.16);
+      --radius-xl: 34px;
+      --radius-lg: 24px;
+      --radius-md: 18px;
+      --ease: cubic-bezier(.22, 1, .36, 1);
+    }
+
+    * {
+      box-sizing: border-box;
+    }
+
+    html,
+    body {
+      margin: 0;
+      min-height: 100%;
+      background:
+        radial-gradient(circle at 20% 20%, rgba(255, 255, 255, 0.95), transparent 28%),
+        radial-gradient(circle at 85% 18%, rgba(37, 99, 235, 0.08), transparent 24%),
+        radial-gradient(circle at 50% 82%, rgba(245, 158, 11, 0.08), transparent 20%),
+        linear-gradient(180deg, var(--bg) 0%, var(--bg-2) 100%);
+      color: var(--text);
+      font-family: -apple-system, BlinkMacSystemFont, "SF Pro Display", "SF Pro Text", "Segoe UI", sans-serif;
+      overflow-x: hidden;
+    }
+
+    body::before,
+    body::after {
+      content: "";
+      position: fixed;
+      inset: auto;
+      pointer-events: none;
+      filter: blur(80px);
+      opacity: 0.9;
+      z-index: 0;
+    }
+
+    body::before {
+      width: 24rem;
+      height: 24rem;
+      top: 6rem;
+      right: -6rem;
+      background: rgba(37, 99, 235, 0.13);
+      animation: drift 18s ease-in-out infinite alternate;
+    }
+
+    body::after {
+      width: 20rem;
+      height: 20rem;
+      bottom: 2rem;
+      left: -4rem;
+      background: rgba(245, 158, 11, 0.09);
+      animation: drift 22s ease-in-out infinite alternate-reverse;
+    }
+
+    .grain {
+      position: fixed;
+      inset: 0;
+      pointer-events: none;
+      opacity: 0.06;
+      z-index: 0;
+      background-image:
+        linear-gradient(rgba(15, 23, 42, 0.08) 1px, transparent 1px),
+        linear-gradient(90deg, rgba(15, 23, 42, 0.08) 1px, transparent 1px);
+      background-size: 4px 4px;
+      mix-blend-mode: soft-light;
+    }
+
+    .shell {
+      position: relative;
+      z-index: 1;
+      min-height: 100vh;
+      padding: 28px;
+      display: flex;
+      align-items: center;
+      justify-content: center;
+    }
+
+    .frame {
+      width: min(1320px, 100%);
+      min-height: min(860px, calc(100vh - 56px));
+      padding: 28px;
+      border-radius: 42px;
+      position: relative;
+      background: linear-gradient(180deg, rgba(255, 255, 255, 0.55), rgba(255, 255, 255, 0.36));
+      border: 1px solid rgba(255, 255, 255, 0.8);
+      box-shadow: var(--shadow);
+      backdrop-filter: blur(24px);
+      overflow: hidden;
+    }
+
+    .frame::before,
+    .frame::after {
+      content: "";
+      position: absolute;
+      inset: 0;
+      pointer-events: none;
+    }
+
+    .frame::before {
+      background:
+        linear-gradient(120deg, rgba(255, 255, 255, 0.55), transparent 26%),
+        radial-gradient(circle at 76% 24%, rgba(37, 99, 235, 0.08), transparent 18%);
+      mix-blend-mode: screen;
+    }
+
+    .frame::after {
+      inset: 18px;
+      border-radius: 30px;
+      border: 1px solid rgba(255, 255, 255, 0.72);
+    }
+
+    .topbar {
+      display: flex;
+      align-items: center;
+      justify-content: space-between;
+      gap: 16px;
+      margin-bottom: 34px;
+      position: relative;
+      z-index: 1;
+    }
+
+    .wordmark {
+      display: inline-flex;
+      align-items: center;
+      gap: 12px;
+      padding: 10px 14px;
+      border-radius: 999px;
+      background: rgba(255, 255, 255, 0.62);
+      border: 1px solid rgba(255, 255, 255, 0.82);
+      box-shadow: 0 12px 40px rgba(148, 163, 184, 0.14);
+      color: var(--text);
+      font-size: 14px;
+      letter-spacing: 0.02em;
+      font-weight: 600;
+      backdrop-filter: blur(18px);
+    }
+
+    .wordmark-dot {
+      width: 10px;
+      height: 10px;
+      border-radius: 999px;
+      background: linear-gradient(180deg, #6ea8ff, #2563eb);
+      box-shadow: 0 0 0 4px rgba(37, 99, 235, 0.12);
+    }
+
+    .availability {
+      display: inline-flex;
+      align-items: center;
+      gap: 10px;
+      padding: 10px 14px;
+      border-radius: 999px;
+      background: rgba(255, 255, 255, 0.56);
+      border: 1px solid rgba(255, 255, 255, 0.76);
+      color: var(--soft);
+      font-size: 13px;
+      backdrop-filter: blur(18px);
+    }
+
+    .availability span {
+      width: 8px;
+      height: 8px;
+      border-radius: 50%;
+      background: linear-gradient(180deg, #f6bf54, #f59e0b);
+      box-shadow: 0 0 0 5px rgba(245, 158, 11, 0.12);
+      animation: pulse 2.8s ease-in-out infinite;
+    }
+
+    .hero {
+      display: grid;
+      grid-template-columns: minmax(0, 0.94fr) minmax(360px, 1.06fr);
+      gap: 42px;
+      align-items: center;
+      min-height: calc(100% - 78px);
+      position: relative;
+      z-index: 1;
+    }
+
+    .copy {
+      max-width: 540px;
+      padding: 10px 6px 10px 10px;
+    }
+
+    .badge {
+      display: inline-flex;
+      align-items: center;
+      gap: 12px;
+      padding: 12px 18px;
+      border-radius: 999px;
+      background: rgba(255, 255, 255, 0.64);
+      border: 1px solid rgba(255, 255, 255, 0.86);
+      box-shadow: var(--shadow-soft);
+      backdrop-filter: blur(18px);
+      margin-bottom: 24px;
+    }
+
+    .badge-icon {
+      width: 28px;
+      height: 28px;
+      display: grid;
+      place-items: center;
+      border-radius: 50%;
+      background: linear-gradient(180deg, rgba(245, 158, 11, 0.18), rgba(245, 158, 11, 0.08));
+      box-shadow: inset 0 1px 0 rgba(255, 255, 255, 0.72);
+    }
+
+    .pause-bars {
+      width: 10px;
+      height: 12px;
+      position: relative;
+    }
+
+    .pause-bars::before,
+    .pause-bars::after {
+      content: "";
+      position: absolute;
+      top: 0;
+      width: 3px;
+      height: 12px;
+      border-radius: 999px;
+      background: var(--amber);
+      box-shadow: 0 0 16px rgba(245, 158, 11, 0.18);
+    }
+
+    .pause-bars::before { left: 1px; }
+    .pause-bars::after { right: 1px; }
+
+    .badge-copy {
+      display: flex;
+      flex-direction: column;
+      gap: 2px;
+    }
+
+    .badge-copy strong {
+      font-size: 13px;
+      letter-spacing: 0.06em;
+      text-transform: uppercase;
+      color: var(--soft);
+      font-weight: 600;
+    }
+
+    .badge-copy span {
+      font-size: 14px;
+      color: var(--text);
+      font-weight: 600;
+    }
+
+    h1 {
+      margin: 0;
+      font-size: clamp(3.5rem, 5vw, 5.5rem);
+      line-height: 0.94;
+      letter-spacing: -0.055em;
+      font-weight: 700;
+      max-width: 10ch;
+    }
+
+    .lede {
+      margin: 24px 0 0;
+      font-size: clamp(1.08rem, 1.9vw, 1.28rem);
+      line-height: 1.55;
+      color: var(--muted);
+      max-width: 47ch;
+      letter-spacing: -0.01em;
+    }
+
+    .subcopy {
+      margin: 14px 0 0;
+      color: var(--soft);
+      font-size: 15px;
+      line-height: 1.7;
+      max-width: 50ch;
+    }
+
+    .actions {
+      display: flex;
+      align-items: center;
+      gap: 14px;
+      flex-wrap: wrap;
+      margin-top: 32px;
+    }
+
+    .button,
+    .link-button {
+      appearance: none;
+      border: 0;
+      text-decoration: none;
+      cursor: pointer;
+      transition:
+        transform 220ms var(--ease),
+        box-shadow 220ms var(--ease),
+        background-color 220ms var(--ease),
+        border-color 220ms var(--ease),
+        color 220ms var(--ease);
+    }
+
+    .button {
+      padding: 16px 22px;
+      border-radius: 999px;
+      background: linear-gradient(180deg, #2f6fff, #2563eb);
+      color: #fff;
+      font-size: 15px;
+      font-weight: 600;
+      letter-spacing: -0.01em;
+      box-shadow:
+        0 14px 40px rgba(37, 99, 235, 0.24),
+        inset 0 1px 0 rgba(255, 255, 255, 0.2);
+    }
+
+    .button:hover,
+    .button:focus-visible {
+      transform: translateY(-1px);
+      box-shadow:
+        0 20px 48px rgba(37, 99, 235, 0.28),
+        inset 0 1px 0 rgba(255, 255, 255, 0.22);
+    }
+
+    .link-button {
+      padding: 16px 18px;
+      border-radius: 999px;
+      background: rgba(255, 255, 255, 0.5);
+      border: 1px solid rgba(255, 255, 255, 0.8);
+      color: var(--text);
+      font-size: 15px;
+      font-weight: 600;
+      box-shadow: 0 10px 30px rgba(148, 163, 184, 0.14);
+      backdrop-filter: blur(18px);
+    }
+
+    .link-button:hover,
+    .link-button:focus-visible {
+      transform: translateY(-1px);
+      background: rgba(255, 255, 255, 0.7);
+    }
+
+    .meta {
+      display: flex;
+      flex-wrap: wrap;
+      gap: 14px;
+      margin-top: 34px;
+    }
+
+    .meta-card {
+      min-width: 185px;
+      padding: 16px 18px;
+      border-radius: var(--radius-md);
+      background: rgba(255, 255, 255, 0.48);
+      border: 1px solid rgba(255, 255, 255, 0.76);
+      box-shadow: var(--shadow-soft);
+      backdrop-filter: blur(18px);
+    }
+
+    .meta-card .eyebrow {
+      display: block;
+      margin-bottom: 8px;
+      color: var(--soft);
+      text-transform: uppercase;
+      letter-spacing: 0.08em;
+      font-size: 11px;
+      font-weight: 700;
+    }
+
+    .meta-card strong {
+      display: block;
+      font-size: 17px;
+      letter-spacing: -0.03em;
+      margin-bottom: 5px;
+    }
+
+    .meta-card p {
+      margin: 0;
+      color: var(--muted);
+      font-size: 14px;
+      line-height: 1.55;
+    }
+
+    .visual {
+      position: relative;
+      min-height: 630px;
+      display: grid;
+      place-items: center;
+      isolation: isolate;
+      perspective: 1200px;
+    }
+
+    .visual::before,
+    .visual::after {
+      content: "";
+      position: absolute;
+      border-radius: 50%;
+      pointer-events: none;
+      filter: blur(30px);
+      transition: transform 240ms var(--ease);
+    }
+
+    .visual::before {
+      width: 460px;
+      height: 460px;
+      background: radial-gradient(circle, rgba(255, 255, 255, 0.92) 0%, rgba(255, 255, 255, 0) 72%);
+      z-index: 0;
+    }
+
+    .visual::after {
+      width: 320px;
+      height: 320px;
+      background: radial-gradient(circle, rgba(37, 99, 235, 0.14) 0%, rgba(37, 99, 235, 0) 72%);
+      top: 14%;
+      right: 14%;
+      z-index: 0;
+    }
+
+    .orbital-ring {
+      position: absolute;
+      width: 480px;
+      height: 480px;
+      border-radius: 50%;
+      border: 1px solid rgba(255, 255, 255, 0.6);
+      box-shadow:
+        0 0 0 18px rgba(255, 255, 255, 0.12),
+        inset 0 0 40px rgba(255, 255, 255, 0.24);
+      opacity: 0.9;
+      z-index: 1;
+      animation: ring 14s linear infinite;
+    }
+
+    .glass-panel {
+      position: absolute;
+      inset: 12% 8%;
+      border-radius: var(--radius-xl);
+      background: linear-gradient(180deg, rgba(255, 255, 255, 0.26), rgba(255, 255, 255, 0.08));
+      border: 1px solid rgba(255, 255, 255, 0.38);
+      box-shadow: inset 0 1px 0 rgba(255, 255, 255, 0.35);
+      transform: translate3d(0, 0, 0) rotateX(10deg);
+      z-index: 1;
+    }
+
+    .hero-art {
+      position: relative;
+      width: min(100%, 720px);
+      padding: 44px;
+      border-radius: 42px;
+      background: linear-gradient(180deg, rgba(255, 255, 255, 0.34), rgba(255, 255, 255, 0.14));
+      border: 1px solid rgba(255, 255, 255, 0.62);
+      box-shadow:
+        0 32px 100px rgba(148, 163, 184, 0.22),
+        inset 0 1px 0 rgba(255, 255, 255, 0.48);
+      backdrop-filter: blur(30px);
+      z-index: 2;
+      transform-style: preserve-3d;
+      transition: transform 240ms var(--ease);
+      animation: float 7s ease-in-out infinite;
+    }
+
+    .hero-art::before,
+    .hero-art::after {
+      content: "";
+      position: absolute;
+      inset: 16px;
+      border-radius: 30px;
+      pointer-events: none;
+    }
+
+    .hero-art::before {
+      border: 1px solid rgba(255, 255, 255, 0.5);
+    }
+
+    .hero-art::after {
+      background:
+        linear-gradient(140deg, rgba(255, 255, 255, 0.26), transparent 28%),
+        linear-gradient(320deg, rgba(245, 158, 11, 0.08), transparent 34%);
+      mix-blend-mode: screen;
+    }
+
+    .hero-art img {
+      display: block;
+      width: 100%;
+      height: auto;
+      border-radius: 28px;
+      transform: translateZ(40px);
+      filter: saturate(1.02) contrast(1.02);
+      box-shadow: 0 30px 90px rgba(148, 163, 184, 0.22);
+      user-select: none;
+      -webkit-user-drag: none;
+    }
+
+    .scan-caption {
+      position: absolute;
+      left: 50%;
+      bottom: 28px;
+      transform: translateX(-50%);
+      display: inline-flex;
+      align-items: center;
+      gap: 10px;
+      padding: 12px 16px;
+      border-radius: 999px;
+      background: rgba(255, 255, 255, 0.7);
+      border: 1px solid rgba(255, 255, 255, 0.88);
+      box-shadow: 0 12px 40px rgba(148, 163, 184, 0.18);
+      font-size: 13px;
+      color: var(--muted);
+      backdrop-filter: blur(18px);
+      z-index: 3;
+      white-space: nowrap;
+    }
+
+    .scan-caption strong {
+      color: var(--text);
+      font-weight: 600;
+    }
+
+    .scan-caption .beam {
+      width: 34px;
+      height: 2px;
+      border-radius: 999px;
+      background: linear-gradient(90deg, rgba(245, 158, 11, 0), rgba(245, 158, 11, 1), rgba(245, 158, 11, 0));
+      box-shadow: 0 0 16px rgba(245, 158, 11, 0.45);
+    }
+
+    .footer-note {
+      margin-top: 18px;
+      color: var(--soft);
+      font-size: 12px;
+      letter-spacing: 0.02em;
+    }
+
+    @keyframes float {
+      0%, 100% { transform: translate3d(0, 0, 0) rotateX(0deg) rotateY(0deg); }
+      50% { transform: translate3d(0, -10px, 0) rotateX(1.5deg) rotateY(-1.5deg); }
+    }
+
+    @keyframes drift {
+      0% { transform: translate3d(0, 0, 0) scale(1); }
+      100% { transform: translate3d(-18px, 14px, 0) scale(1.08); }
+    }
+
+    @keyframes pulse {
+      0%, 100% { transform: scale(1); opacity: 0.85; }
+      50% { transform: scale(1.18); opacity: 1; }
+    }
+
+    @keyframes ring {
+      from { transform: rotate(0deg) scale(1); }
+      50% { transform: rotate(180deg) scale(1.02); }
+      to { transform: rotate(360deg) scale(1); }
+    }
+
+    @media (max-width: 1080px) {
+      .shell {
+        padding: 18px;
+      }
+
+      .frame {
+        min-height: auto;
+        padding: 22px;
+      }
+
+      .hero {
+        grid-template-columns: 1fr;
+        gap: 24px;
+      }
+
+      .copy {
+        max-width: 100%;
+      }
+
+      .visual {
+        min-height: 520px;
+        order: -1;
+      }
+
+      .hero-art {
+        max-width: 640px;
+      }
+    }
+
+    @media (max-width: 720px) {
+      .shell {
+        padding: 10px;
+      }
+
+      .frame {
+        padding: 16px;
+        border-radius: 28px;
+      }
+
+      .topbar {
+        margin-bottom: 18px;
+      }
+
+      .availability {
+        display: none;
+      }
+
+      h1 {
+        font-size: clamp(2.8rem, 12vw, 4rem);
+        max-width: 12ch;
+      }
+
+      .lede {
+        font-size: 1rem;
+      }
+
+      .actions,
+      .meta {
+        gap: 10px;
+      }
+
+      .button,
+      .link-button {
+        width: 100%;
+        justify-content: center;
+        text-align: center;
+      }
+
+      .visual {
+        min-height: 380px;
+      }
+
+      .hero-art {
+        padding: 18px;
+        border-radius: 24px;
+      }
+
+      .hero-art::before,
+      .hero-art::after {
+        inset: 10px;
+        border-radius: 18px;
+      }
+
+      .hero-art img {
+        border-radius: 16px;
+      }
+
+      .orbital-ring {
+        width: 300px;
+        height: 300px;
+      }
+
+      .scan-caption {
+        bottom: 14px;
+        max-width: calc(100% - 30px);
+        white-space: normal;
+        text-align: center;
+        line-height: 1.45;
+      }
+    }
+
+    @media (prefers-reduced-motion: reduce) {
+      *,
+      *::before,
+      *::after {
+        animation: none !important;
+        transition: none !important;
+      }
+    }
+  </style>
+</head>
+<body>
+  <div class="grain" aria-hidden="true"></div>
+  <main class="shell">
+    <section class="frame">
+      <header class="topbar">
+        <div class="wordmark">
+          <span class="wordmark-dot" aria-hidden="true"></span>
+          QR Master
+        </div>
+        <div class="availability">
+          <span aria-hidden="true"></span>
+          Scanning temporarily unavailable
+        </div>
+      </header>
+
+      <div class="hero">
+        <div class="copy">
+          <div class="badge">
+            <div class="badge-icon" aria-hidden="true">
+              <div class="pause-bars"></div>
+            </div>
+            <div class="badge-copy">
+              <strong>Status</strong>
+              <span>Paused by owner</span>
+            </div>
+          </div>
+
+          <h1>QR Code is paused</h1>
+
+          <p class="lede">
+            This QR code has been temporarily disabled by its owner, so scanning is currently unavailable.
+          </p>
+
+          <p class="subcopy">
+            Please try again later or contact the owner for the active link. Paused codes should feel intentional and trustworthy, not broken.
+          </p>
+
+          <div class="actions">
+            <a class="button" href="#">Go to QR Master</a>
+            <a class="link-button" href="#">Need help?</a>
+          </div>
+
+          <div class="meta">
+            <article class="meta-card">
+              <span class="eyebrow">Redirect</span>
+              <strong>Temporarily disabled</strong>
+              <p>No destination opens while this code remains paused.</p>
+            </article>
+            <article class="meta-card">
+              <span class="eyebrow">Tracking</span>
+              <strong>Scan logging stopped</strong>
+              <p>Paused scans should not continue into analytics.</p>
+            </article>
+          </div>
+
+          <p class="footer-note">Preview concept for a standalone paused-state page.</p>
+        </div>
+
+        <div class="visual" id="visualStage">
+          <div class="orbital-ring" aria-hidden="true"></div>
+          <div class="glass-panel" aria-hidden="true"></div>
+          <figure class="hero-art" id="heroArt">
+            <img src="./paused-qr-hero-cinematic.png" alt="Glass-like QR tile floating in a cinematic studio environment">
+          </figure>
+          <div class="scan-caption">
+            <strong>Paused</strong>
+            <span class="beam" aria-hidden="true"></span>
+            The scan was intentionally interrupted
+          </div>
+        </div>
+      </div>
+    </section>
+  </main>
+
+  <script>
+    const heroArt = document.getElementById('heroArt');
+    const visualStage = document.getElementById('visualStage');
+
+    if (heroArt && visualStage && window.matchMedia('(prefers-reduced-motion: no-preference)').matches) {
+      visualStage.addEventListener('pointermove', (event) => {
+        const bounds = visualStage.getBoundingClientRect();
+        const x = (event.clientX - bounds.left) / bounds.width - 0.5;
+        const y = (event.clientY - bounds.top) / bounds.height - 0.5;
+
+        const rotateX = y * -10;
+        const rotateY = x * 12;
+        const translateX = x * 12;
+        const translateY = y * 8;
+
+        heroArt.style.transform =
+          `translate3d(${translateX}px, ${translateY}px, 0) rotateX(${rotateX}deg) rotateY(${rotateY}deg)`;
+      });
+
+      visualStage.addEventListener('pointerleave', () => {
+        heroArt.style.transform = '';
+      });
+    }
+  </script>
+</body>
+</html>

package.json

@@ -36,6 +36,7 @@
     "@stripe/stripe-js": "^8.0.0",
     "@types/d3-scale": "^4.0.9",
     "@types/nodemailer": "^7.0.11",
+    "ai": "^7.0.28",
     "axios": "^1.13.2",
     "bcryptjs": "^2.4.3",
     "chart.js": "^4.4.0",
@@ -44,6 +45,7 @@
     "d3-scale": "^4.0.2",
     "dayjs": "^1.11.10",
     "dotenv": "^17.2.3",
+    "eve": "^0.16.2",
     "exceljs": "^4.4.0",
     "file-saver": "^2.0.5",
     "framer-motion": "^12.24.10",
@@ -90,6 +92,7 @@
     "cross-env": "^10.1.0",
     "eslint": "^8.56.0",
     "eslint-config-next": "16.1.5",
+    "just-bash": "^3.1.0",
     "postcss": "^8.4.32",
     "prettier": "^3.1.1",
     "prisma": "^5.7.0",

prisma/schema.prisma

@@ -33,14 +33,69 @@ model User {
   resetPasswordExpires DateTime?
 
   // Retention email tracking
-  activationNudgeSentAt DateTime?
-  upgradeNudgeSentAt    DateTime?
-  thirtyDayNudgeSentAt  DateTime?
+  activationNudgeSentAt   DateTime?
+  upgradeNudgeSentAt      DateTime?
+  thirtyDayNudgeSentAt    DateTime?
+  limitReachedNudgeSentAt DateTime?
+  firstScanNudgeSentAt    DateTime?
+  qrPulseSentAt           DateTime?
+
+  /// When the user last looked at their own scan numbers. A live session is not
+  /// the same as someone having seen a number, so this is what "inactive" means.
+  lastAnalyticsViewAt DateTime?
+
+  // RevOps attribution
+  signupSource             String?
+  signupSourceSelfReported String?
+  signupMedium             String?
+  signupCampaign           String?
+  signupContent            String?
+  signupTerm               String?
+  signupReferrer           String?
+  signupLandingPath        String?
+  signupFirstSeenAt        DateTime?
+  emailDomain              String?
+
+  // Onboarding and qualification
+  primaryUseCase        String?
+  primaryGoal           String?
+  jobRole               String?
+  companyName           String?
+  companyWebsite        String?
+  teamSizeBucket        String?
+  onboardingStartedAt   DateTime?
+  sourceConfirmedAt     DateTime?
+  useCaseSelectedAt     DateTime?
+  goalSelectedAt        DateTime?
+  profileCompletedAt    DateTime?
+  firstQrCreatedAt      DateTime?
+  firstDynamicQrAt      DateTime?
+  firstStaticQrAt       DateTime?
+  firstScanAt           DateTime?
+  activationAt          DateTime?
+  onboardingCompletedAt DateTime?
+
+  // RevOps scoring
+  fitScore        Int       @default(0)
+  intentScore     Int       @default(0)
+  leadScore       Int       @default(0)
+  lifecycleStage  String    @default("cold")
+  lastQualifiedAt DateTime?
+  lastScoredAt    DateTime?
 
   qrCodes       QRCode[]
+  designPresets QRDesignPreset[]
   integrations  Integration[]
   accounts      Account[]
   sessions      Session[]
+  lifecycleLogs UserLifecycleLog[]
+  socialMilestones SocialMilestone[]
+
+  // Social-success sharing preferences. A post is still never published
+  // without a per-milestone approval stored below.
+  xHandle             String?
+  instagramHandle     String?
+  socialPromptOptOut  Boolean @default(false)
 }
 
 enum Plan {
@@ -100,8 +155,71 @@ model QRCode {
 
   user  User     @relation(fields: [userId], references: [id], onDelete: Cascade)
   scans QRScan[]
+  socialMilestones SocialMilestone[]
 
   @@index([userId, createdAt])
+  @@index([userId, type, status])
+}
+
+model SocialMilestone {
+  id          String   @id @default(cuid())
+  qrId        String
+  userId      String
+  kind        String
+  status      String   @default("detected")
+  detectedAt  DateTime @default(now())
+  shownAt     DateTime?
+  respondedAt DateTime?
+  claimedAt   DateTime?
+  postedAt    DateTime?
+  withName    Boolean  @default(false)
+  consentText String?
+  language    String   @default("en")
+  cardData    Json?
+  brandStatus String   @default("pending")
+  brandApprovedAt DateTime?
+  brandPostedAt DateTime?
+  brandPostUrl String?
+  brandPostError String?
+  selfSharedAt DateTime?
+  shareToken String? @unique
+  publicShareApprovedAt DateTime?
+  attempts Int @default(0)
+  nextAttemptAt DateTime?
+
+  qr   QRCode @relation(fields: [qrId], references: [id], onDelete: Cascade)
+  user User   @relation(fields: [userId], references: [id], onDelete: Cascade)
+  posts SocialMilestonePost[]
+
+  @@unique([qrId, kind])
+  @@index([status, respondedAt])
+  @@index([status, claimedAt])
+  @@index([userId, status])
+  @@index([brandStatus, brandApprovedAt])
+}
+
+model SocialMilestonePost {
+  id          String   @id @default(cuid())
+  milestoneId String
+  /// "x" | "instagram". Consent is bound to the channel it was given for.
+  channel     String
+  /// approved | processing | posted | failed | revoked
+  status      String   @default("approved")
+  /// The exact text the customer read before consenting.
+  consentText String
+  handle      String?
+  approvedAt  DateTime @default(now())
+  claimedAt   DateTime?
+  postedAt    DateTime?
+  postUrl     String?
+  error       String?
+  attempts    Int      @default(0)
+  nextAttemptAt DateTime?
+
+  milestone SocialMilestone @relation(fields: [milestoneId], references: [id], onDelete: Cascade)
+
+  @@unique([milestoneId, channel])
+  @@index([channel, status, approvedAt])
 }
 
 enum QRType {
@@ -130,19 +248,19 @@ enum QRStatus {
 }
 
 model QRScan {
-  id           String    @id @default(cuid())
-  qrId         String
-  ts           DateTime  @default(now())
-  ipHash       String
-  userAgent    String?
-  device       String?
-  os           String?
-  country      String?
-  referrer     String?
-  utmSource    String?
-  utmMedium    String?
-  utmCampaign  String?
-  isUnique     Boolean   @default(false)
+  id          String   @id @default(cuid())
+  qrId        String
+  ts          DateTime @default(now())
+  ipHash      String
+  userAgent   String?
+  device      String?
+  os          String?
+  country     String?
+  referrer    String?
+  utmSource   String?
+  utmMedium   String?
+  utmCampaign String?
+  isUnique    Boolean  @default(false)
 
   qr QRCode @relation(fields: [qrId], references: [id], onDelete: Cascade)
 
@@ -161,6 +279,57 @@ model Integration {
   user User @relation(fields: [userId], references: [id], onDelete: Cascade)
 }
 
+model TiktokIntegration {
+  id                    String    @id @default(cuid())
+  accountKey            String    @unique
+  openId                String
+  accessToken           String
+  refreshToken          String
+  scope                 String?
+  accessTokenExpiresAt  DateTime
+  refreshTokenExpiresAt DateTime?
+  createdAt             DateTime  @default(now())
+  updatedAt             DateTime  @updatedAt
+}
+
+model SocialAsset {
+  id        String   @id @default(cuid())
+  filename  String
+  mimeType  String
+  data      Bytes
+  createdAt DateTime @default(now())
+}
+
+/// Saved design presets. The point for an agency is not the star shape, it is
+/// that client A looks identical across 500 codes.
+model QRDesignPreset {
+  id        String   @id @default(cuid())
+  userId    String
+  name      String
+  style     Json
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  user User @relation(fields: [userId], references: [id], onDelete: Cascade)
+
+  @@unique([userId, name])
+  @@index([userId])
+}
+
+model UserLifecycleLog {
+  id          String   @id @default(cuid())
+  userId      String
+  fromStage   String?
+  toStage     String
+  fitScore    Int      @default(0)
+  intentScore Int      @default(0)
+  leadScore   Int      @default(0)
+  reason      String?
+  createdAt   DateTime @default(now())
+
+  user User @relation(fields: [userId], references: [id], onDelete: Cascade)
+}
+
 model NewsletterSubscription {
   id        String   @id @default(cuid())
   email     String   @unique

public/5b9d3b9b2d156ee884bbfc4700bdf2b4.txt

@@ -0,0 +1 @@
+5b9d3b9b2d156ee884bbfc4700bdf2b4