tknuth/QR-master
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Impeccable

Browse Source
This commit is contained in:
Timo Knuth
2026-04-29 20:34:09 +02:00
parent 9b31e77daa
commit aab808c553
22 changed files with 1827 additions and 684 deletions
Download Patch File Download Diff File Expand all files Collapse all files

45
docs/automations/README.md Normal file
View File

@@ -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.

160
docs/automations/greenlens-pain-mining-machine.md Normal file
View File

@@ -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.

139
docs/automations/greenlens-viral-slideshow-machine.md Normal file
View File

@@ -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.

57
docs/automations/qrmaster-broken-link-cta-checker.md Normal file
View File

@@ -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.

163
docs/automations/qrmaster-pr-seo-review.md Normal file
View File

@@ -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.

211
docs/automations/qrmaster-seo-sprint-machine.md Normal file
View File

@@ -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.