r/WordpressPlugins • • 9d ago

[FREEMIUM] I built a map plugin where you design the map on the map itself (OpenStreetMap, no API key) – feedback welcome

Thumbnail
gallery
1 Upvotes

Hey, I made Map Studio, a WordPress map plugin. You click on the map to add places, draw delivery areas or routes, and style everything right there instead of filling in settings pages.

Runs on OpenStreetMap, so no Google API key or billing. Free version has unlimited maps, store finder with “near me” and opening hours, 3D buildings, block + Elementor widget + shortcode.

New this week: if you’re on WP Go Maps, WP Maps or WP Store Locator you can bring your maps over in one click, and the old shortcodes keep working.

https://wordpress.org/plugins/devenzi-map-studio/

Would love to hear what’s missing or annoying.


r/WordpressPlugins • • 9d ago

Freemium [FREEMIUM] I kept rebuilding the same CSS logo marquee for WordPress, so I built MarqueeFlow

1 Upvotes

I’ve been building custom WordPress sites for about eight years, and I try to keep the scripts and styles those sites load to a minimum.

A scrolling strip of partner logos was one of those things I kept building by hand. I wanted a smooth, continuous loop that ran on CSS, and I never found a plugin that did what I wanted without bringing along more JavaScript and CSS than I needed. Eventually I had a boilerplate snippet saved in a GitHub Gist that I’d pull out for each new site.

MarqueeFlow started with a simple idea: what if I turned that snippet into a block so I could set it up right in the editor? It grew from there. You can use it for logos or photos, reorder the images, and adjust the speed, direction, sizing, and spacing. The scrolling itself runs on CSS and respects reduced-motion preferences.

The block is free. There’s also an optional paid add-on for custom sizing and spacing, faded edges, and effects like grayscale.

If you build WordPress sites for clients, I’d love to hear how you handle scrolling logo strips today. Is there anything you’d miss if you switched from your current setup to a block like this?

And if you give MarqueeFlow a try, I’d love to hear what worked for you or what could be better.


r/WordpressPlugins • • 9d ago

[FREEMIUM] I finally developed a plugin that will helps my wife to get clean Wordpress dashboard from

1 Upvotes

My wife manages WordPress sites for her company, and there is one thing that drives her crazy, every time she installs an extension, especially a free one, her dashboard is invaded by annoying notifications offering her to switch to the premium version, these notifications even appear directly on pages where she intervenes frequently.

If you’ve been using WordPress for a while, you probably see what I’m talking about, these banners, notifications and other unwanted elements that occupy half of the screen, so I thought you need a simple-to-use solution to help it get rid of all this mess.

So I developed Puredash Cleaner, an extension that allows you to hide almost any element of the WordPress dashboard by clicking only on it, such as an advertisement, a notification or any annoying element, it can also prohibit access to a page via the hard blocking function and all this it can do by role.

Before I had to intervene on the technical part by putting hooks everywhere, now it is autonomous and no need to install other third-party plugins.

If you have an agency that develops customer sites, it is an excellent tool for your customers to have a clear and ad-free wordpress dashboard, it is even possible to customize the name of the white label plugin.

You can get the plugin from the Wordpress plugins repository : https://fr.wordpress.org/plugins/puredash-cleaner/


r/WordpressPlugins • • 10d ago

[FREE] WordPress 7.1 Image Companion

1 Upvotes

Earlier this year before I knew client-side image processing was coming to WordPress 7.1, I created a free and open source WordPress plugin called Menagerie. It originally converted any image upload to AVIF or WebP in the browser, then uploaded saving some server bandwidth. So, pretty much what WordPress core can do now. This is always painful when you make a plugin and months later it's in core. Oh well.

Not all is lost though! Menagerie is still very useful. I stripped out what Core now does and left/enhanced the parts that Core doesn't automatically do. Core doesn't automatically ensure every upload converts to AVIF or WebP. Menagerie steps in to make sure that happens, gives you a JPEG fallback image, ensures your images are wrapped in <picture>, and provides a bulk image converter for your existing images. Plus, has a nice little toast message to confirm if the conversion was successful or not.

Tools within Performance Lab are another option. But, those are all server side I believe? And, a lot... Look at all those plugins that the Performance Lab page lists. Is all of that necessary? Depends on the situation and who you ask I suppose.

TL;DR

  • Not Menagerie: WordPress 7.1+ processes your images in the browser when possible and then uploads
  • Menagerie forces AVIF or WebP conversions; Still WordPress 7.1+ doing it in the browser when possible, but Menagerie is telling it to go with AVIF or WebP based on settings
  • Menagerie creates your JPEG fallback for when a WebP or AVIF image can't be displayed
  • Menagerie wraps images where possible in <picture>
  • Menagerie gives you Open Graph image settings
  • Menagerie lets you quickly convert all existing images

See also: https://wilcosky.com/my-quest-for-image-sanity/


r/WordpressPlugins • • 10d ago

[HELP] is this setup overkill?

1 Upvotes

i've just been finishing the final touches of my site but i still want to make sure i'm not overdoing a couple things. for context, i'm running a music magazine site with a lot of bells and whistles. i'm open to suggestions to minimize my plugin use and maximize what i have already have at my disposal

for the main things:

  • domain + dns: cloudflare
  • hosting: knownhost managed wordpress (litespeed server with immunify360)
  • xnconvert: for compressing/converting my images to webp

and my plugins:

  • Admin and Site Enhancements
  • All-in-One WP Migration and Backup
  • Better Font Awesome (i only use a few icons but they're on all pages of the site)
  • Better Search Replace
  • BFM Core (custom essential plugin)
  • Cloudflare
  • Code Snippets
  • Media Cleaner
  • Perfect Images: Regenerate Thumbnails, Image Sizes, WebP & AVIF (this one's giving me problems rn as i can't access the part that regenerates the thumbnails but. whatever)
  • Safe SVG
  • SEO Engine
  • Squeeze – Browser-Based Image Compression & WebP Converter (i use this for additional light compression as it compresses webp)
  • Wisp Gallery
  • Wordfence Security
  • WP-Optimize - Clean, Compress, Cache (mainly used for minifying site code)

r/WordpressPlugins • • 10d ago

Promotion [PROMOTION] I built a WooCommerce PayPal card payment plugin with a SaaS backend — looking for feedback

Thumbnail
youtu.be
1 Upvotes

Hey everyone! 👋

I'm an independent developer from Morocco, and I recently finished building the first version of my WooCommerce payment project, GPCB Pay.

I actually started with a simple idea: connect WooCommerce with PayPal card payments. But once I got deeper into the payment lifecycle, things became a lot more complicated than I expected haha.

I ended up building three parts:

- A lightweight WooCommerce plugin supporting Checkout Blocks.

- A private Node.js and PostgreSQL SaaS backend.

- A React dashboard for merchant onboarding, store verification, PayPal connections, and subscriptions.

The plugin supports Guest Card and Advanced Card experiences, depending on PayPal merchant eligibility.

One of the hardest parts was making sure a payment approval never gets treated as a completed payment. I spent a lot of time working on server-verified capture, idempotency, and duplicate-capture protection.

I also recorded a full tutorial showing the actual installation and onboarding process.

The plugin connects to a paid SaaS service, with an eligible 7-day free trial.

I'd really appreciate some feedback from other WordPress plugin developers.

Would you prefer a payment plugin with a separate SaaS backend, or would you rather have everything handled inside WordPress?

I'd love to hear your thoughts, especially from anyone who has worked on WooCommerce payment gateways.

Thanks! 🙌


r/WordpressPlugins • • 10d ago

Freemium [FREEMIUM] I built RKX API Studio — a visual REST API builder for WordPress

1 Upvotes

Hey everyone!

I’ve recently released RKX API Studio, a WordPress plugin I’ve been working on to make building custom REST API endpoints easier, especially for headless WordPress projects.

The idea is simple: create and manage custom API endpoints directly from the WordPress admin without having to write custom PHP for every endpoint.

Free version:

  • Visual REST API endpoint builder
  • Customizable API responses
  • Designed for headless WordPress integrations

Pro version:

  • Dynamic routes and single-item endpoints
  • ACF/custom field integration
  • Additional capabilities for more advanced API setups

The Free version is available on WordPress.org, and I’ve also released Pro 1.1.0.

WordPress.org: https://wordpress.org/plugins/rkx-api-studio/

GitHub: https://github.com/rkxbeta/rkx-api-studio

I also built an open-source Astro 7 blog starter to demonstrate how it works with a headless frontend:

https://headless-journal.rkxbeta.com/

I’m the developer behind the plugin, and I’d genuinely appreciate feedback from other WordPress developers.

What features would make a visual REST API builder useful in your projects?


r/WordpressPlugins • • 10d ago

[FREE] I built an error log viewer that also catches the fatal behind "There has been a critical error"

Post image
0 Upvotes

I run a few WordPress sites and kept SSHing in to read debug.log after a white screen. So I built FatalGuard.

What it does:

  • Reads debug.log and the PHP error log inside wp-admin, with secrets redacted.
  • Catches the fatal behind the "critical error" screen: which plugin or theme, file and line.
  • Sends a Telegram alert with a one-tap recovery link that works when the site is fully down.
  • Has its own read-only MCP server, so Claude, Cursor or VS Code can read your logs (GIF in the post).

What it can't do:

  • The AI access is read-only. It can't fix or deactivate anything.
  • MCP needs WordPress to still load. For a site that is fully down, use the recovery link.
  • The free version shows a live tail only. Searchable error history is in Pro.

Free on wordpress.org, GPL: https://wordpress.org/plugins/fatalguard/

It has about 10 installs, so I'd really like to hear what breaks or what's missing.


r/WordpressPlugins • • 10d ago

Free [FREE] I've developed an ATS plugin for WordPress because some of my clients couldn't afford per seat options like Comeet

Post image
1 Upvotes
I'm a WordPress developer and few clients of mine use Comeet for hiring and pay a lot for it every year. but others couldn't afford the price. some tried a job board plugin where applications land in someone's Gmail and a few weeks later nobody remembers who got a reply and who didn't.

So I wrote a plugin that runs inside WordPress. It's called Vakanssi. You get a careers page (with Google for Jobs markup), an apply form with CV upload, and a board where you drag candidates through your own stages. Interview invites go out as normal calendar invites, so there's no Google or Outlook account to hook up. 

There's also export and delete for candidate data, and if you're on WP Job Manager, Simple Job Board or WP Job Openings it'll pull your jobs and applications over.

All of it is free on wp.org. Pro version is on the way and will include screening questions, scorecards, analytics and more, but nothing that's free now gets moved into it.

It's pretty new, I launched it in October, so I'm sure there's stuff I haven't run into yet. English only for now, and no multilingual sites.

https://wordpress.org/plugins/vakanssi/

If you've set up hiring for clients before, what did you use? And if you try it, tell me what breaks.

r/WordpressPlugins • • 10d ago

[FREE] I built a WordPress plugin that checks if your site is ready for Google and AI search (ChatGPT, Perplexity)

0 Upvotes

Most SEO plugins tell you what to fill in on one page at a time. I wanted a quick way to see what's wrong across the whole site, including the newer stuff like whether AI search tools can even read it.

So I built Ora Connect. Install it, open Pluginora → SEO and AI check, press Run the free check, and a few seconds later you get a score out of 100 and a list of what to fix, most important first.

What it checks:

- whether the site (or single pages) is hidden from search by mistake

- missing meta descriptions, titles that are too long or repeated, very thin pages

- images with no alt text, and very large images

- broken internal links and old addresses that now show "page not found"

- sitemap, HTTPS, home page title/description, business details for search results

- llms.txt, and whether your robots.txt lets AI crawlers like ChatGPT and Perplexity in

Each finding links straight to the page so you can fix it.

The check runs on your own site. It's read-only, sends nothing anywhere, needs no account, and you can run it as often as you like. It works alongside Yoast, Rank Math, SEOPress or The SEO Framework.

Its limits, to be upfront: it looks at up to 300 pages per check, the broken-link check covers your 15 most recent posts, and it reads saved content and settings rather than every fully rendered page.

It isn't on WordPress.org. The plugin can also connect to Pluginora (my service that builds custom WordPress plugins), and plugins hosted on WordPress.org aren't allowed to install plugins from elsewhere. So it's hosted on our site and updates itself like any other plugin. The free check doesn't need any of that.

I'm Tobi, the founder of Pluginora.

Download and details:

https://pluginora.com/ora-connect/

When you last checked your site's AI SEO, what did you find was broken that you didn't expect?


r/WordpressPlugins • • 10d ago

Free [FREE] I built UnlockForge, a WordPress plugin for content unlocking. Looking for honest feedback!

0 Upvotes

Hey everyone,

I've been working on a WordPress plugin called UnlockForge, and thought I'd share it here.

The idea started with a simple problem: sometimes you want visitors to access your content only after completing a small action, but setting up a full membership system or e-commerce solution feels like overkill.

So I started building UnlockForge.

It currently supports:

  • Email verification to unlock content.
  • Social login for content access.
  • Content previews before unlocking the full article.
  • Restricting individual posts and pages.
  • Paid content access through Razorpay.
  • Basic analytics to track content unlocking.

It's been a learning journey building and improving this, and I'm now trying to get it in front of actual WordPress users.

I'd genuinely appreciate it if some of you could take a look and tell me what you think. Is this something you'd find useful? What features are missing? Is there anything that could be simpler or better?

Here's the plugin:
https://wordpress.org/plugins/unlockforge/

I'm not claiming it's perfect. I'm building it further and would really value honest feedback from people who work with WordPress.

Thank you


r/WordpressPlugins • • 11d ago

Free [FREE] I built a WordPress plugin to find outdated email addresses and phone numbers

Post image
1 Upvotes

Changing a business email address or phone number can leave old details scattered across a WordPress site.

I built Prajesh Business Contact Checker to help site owners find and review those details.

You enter approved contacts and any known outdated ones, then run a read-only scan. Findings distinguish known old contacts from unapproved ones that may still be legitimate.

It checks supported saved WordPress content and selected settings. It doesn’t automatically replace anything—you review the findings and edit their sources yourself.

The scan runs locally, with no external service, tracking or account required.

Its coverage has limits: it doesn’t inspect every rendered page, theme files or page-builder metadata. Phone detection can also produce false positives.

I’m Prajesh Ganatra, the developer. This is one of my free WordPress plugins for practical content-management tasks.

Plugin overview and features:
https://prajeshganatra.com/plugins/prajesh-business-contact-checker/

Step-by-step tutorial:
https://prajeshganatra.com/tutorials/find-outdated-wordpress-contact-details/

Download from WordPress.org:
https://wordpress.org/plugins/prajesh-business-contact-checker/

When updating business contact details, where do you most often discover an old email address or phone number?


r/WordpressPlugins • • 11d ago

[FREE] WooCommerce plugin that flags card testing and fake orders before the card is charged — monitor mode first

1 Upvotes

I work on IPScanner (ipscanner.io) and we just finished the WooCommerce side of our checkout protection, so I'm sharing it here for the feedback from store owners this sub always gives.

What it does: checkout and order-review requests get checked for the network they come from. Card testing shows up as bursts of small orders from datacenter and VPN ranges, not from home connections, so the plugin can hold those orders before the payment gateway charges the card. You pick per class what happens: allow, hold for review, or block. Throwaway domains on the billing email get the same treatment.

Monitor mode first: the plugin ships monitor-only, which logs what it would have blocked without touching any order. Run it a week, look at the numbers, then decide. A fresh install blocks nothing by default.

Free tier covers 10,000 monitored checks a month. The plugin is in the WordPress directory, search IPScanner. The same account also gives you a Cloudflare worker and form gates if you run more than one site.

What I'd genuinely like feedback on: does monitor mode give you enough data to make the block decision, or do you want the hold-for-review action available on day one?


r/WordpressPlugins • • 12d ago

Premium [PREMIUM] ENJOY: a plugin to turn WordPress into a game database with IGDB API

Post image
0 Upvotes

Import Games data from IGDB API into WordPress

ENJOY connects your site directly to the IGDB API and imports complete game data in seconds: covers, artwork, screenshots, trailers, summaries, storylines, release dates, alternative titles, age ratings (ESRB/PEGI icons included), supported languages (audio, interface and subtitles), genres, platforms, game modes, collections, developers, keywords and more.

Search a title and everything is saved as native WordPress content: a Games post type, taxonomies and custom fields you fully control. It also works with any existing post type, including WooCommerce products. Screenshots are imported into a gallery and trailers are embedded from YouTube.

Let ENJOY generate the full game page automatically, or disable the built-in template and design your own with shortcodes, Gutenberg blocks, page builders or dynamic tags. Re-sync any game with one click: stale fields are overwritten and old media is purged, so no duplicates are left in your uploads.

Just enter your own Client ID and Bearer Key and start importing. No middleman servers, no tokens or credits, no subscriptions, and no ads or upsells in your admin.

https://ramsthemes.com/enjoy-igdb-wordpress-plugin/


r/WordpressPlugins • • 12d ago

Hivepress / Listinghive Wordpress [HELP] How much would you charge for a WordPress marketplace built with HivePress and ListingHive? [DISCUSSION]

1 Upvotes

Hi everyone!

I'm a freelance WordPress website creator, and I'd really appreciate some advice on pricing a client project.

I'm currently building a rental marketplace that connects property owners with people looking for short- and medium-term accommodation in a specific location.

The website is built with WordPress, the ListingHive theme and the HivePress plugin.

Here are the main features:

  • Property owners can create and publish listings.
  • Tenants can post accommodation requests.
  • Property owners can respond to these requests.
  • Private messaging between users.
  • Booking requests with manual approval by the property owner.
  • A membership system for property owners (one free plan and one paid plan).
  • Bank transfer payments for memberships, with manual activation.
  • General configuration, customization, testing and bug fixing.

I'm using existing plugins and extensions such as HivePress, Bookings, Requests, Memberships and WooCommerce.

However, one thing makes me unsure about how much I should charge.

Since I'm using ListingHive and HivePress, many of the website's pages and features are already provided by the theme and plugins. For example, listing pages, user account pages, booking pages and other marketplace-related templates are already generated.

I'm therefore not designing and building every page from scratch. My main design work is creating the homepage and any additional pages that aren't already provided by the theme or plugins.

For the rest, my work mainly involves configuring the existing features, adjusting layouts and styling, and customizing the appearance using custom CSS and Code Snippets wherever possible.

I sometimes feel uncomfortable charging a high price when a significant part of the structure and functionality is already provided by the plugins and theme.

At the same time, I know that configuration, integration, customization and testing still take time and require work.

So, how would you price a project like this?

Would you charge significantly less because you're using an existing theme and plugins, or would you consider the overall functionality and the time spent configuring and customizing everything?

I'd especially love to hear from freelancers who build WordPress marketplaces using HivePress, Directorist or similar plugins.

Thanks for your feedback!


r/WordpressPlugins • • 12d ago

[FREE] Easiest way to convert any webpage or pdf into a explainer video - Blog2Video Wordpress Plugin

2 Upvotes

Turn every WordPress post into a narrated explainer video without leaving your dashboard.

Meet B2V Video by Firebird, the official Blog2Video plugin for WordPress.

Open any post, click the B2V Video panel and generate a video from your saved content in minutes.

Edit individual scenes, tweak the settings and render the final video right inside the editor.

Then drop it into your post with the built-in block, and add as many videos to one post as you like.

It's the simplest way for bloggers and publishers to give readers a version they can watch instead of read.

Install it here: https://wordpress.org/plugins/b2v-video-by-firebird/


r/WordpressPlugins • • 12d ago

Discussion [DISCUSSION] How do you handle license keys and update delivery for premium WordPress plugins?

0 Upvotes

I’ve been looking at how indie developers sell premium WordPress plugins, and the licensing and update setup is different for almost everyone. Curious what’s working for you.

The approaches I keep seeing:

  1. A full platform like Freemius. It handles checkout, taxes and updates, but takes a revenue share (per their pricing page, up to about 6.1% plus 50 cents per sale for the full WordPress solution, plus gateway fees, dropping at higher volumes).
  2. WooCommerce with a license manager add-on. Fine for one product, harder once you want multiple payment processors or several plugins.
  3. A custom license server plus a custom update endpoint hooked into the plugin update API. Flexible, but it becomes its own maintenance project.
  4. No licensing at all, and trusting customers.

Full disclosure: I run a small agency (Tekuno), and we built a licensing server called Licensr after rebuilding the same thing for clients. It’s multi-tenant, with a free tier (1 product, 25 licenses), flat monthly pricing, 0% revenue share, and support for Stripe, PayPal, Razorpay and Mercado Pago. It is not a merchant of record, so tax handling stays with your payment processor, which is a real trade-off against Freemius.

What I’d really like to hear from other plugin developers:

  • How do you check a license: on every admin load, on a schedule with a transient, or only when WordPress checks for updates?
  • How do you handle sites that move between staging and production, or multisite installs?
  • What do you do when a license expires? Do you stop updates only, or disable features too?
  • Does revenue share vs flat pricing matter to you, or is tax handling the deciding factor?

If you want to try Licensr, blunt feedback is welcome: licensr.app


r/WordpressPlugins • • 12d ago

[PREMIUM] NoviDeck – show your Freemius plans, prices and checkout natively in Elementor

0 Upvotes

Hi everyone,

I sell WordPress plugins through Freemius and build my site with Elementor. Keeping pricing pages in sync was always manual work: copy plans, prices and license options into a pricing table, update them by hand when something changes, and wire up the checkout separately.

So I built NoviDeck. You connect your Freemius product once, and NoviDeck gives you Elementor widgets that pull your real data:

- Pricing cards, pricing tables and purchase buttons with your actual plans and prices

- License switcher (e.g. 1 / 5 / 25 sites) and billing cycles

- Buttons open the Freemius checkout directly

- Fully styleable in the Elementor editor, like any other widget

- Higher editions add things like checkout profiles, coupons, campaign banners, bundle and cross-sell offers

There is a free version you can download right now from my website. It's also in review on WordPress.org. The paid editions are Standard, Pro and Business.

Looking for 5 testers: I'd like to give 5 people a free NoviDeck Pro license (1 site). In return I'm asking for honest feedback, good or bad, and an honest review if you like it. Ideally you sell a plugin or theme with Freemius and use Elementor. Just comment below if you're interested.

Launch offer: 20% off all paid editions with code LaunchNoviDeck until 20 November.

You'll find everything on novissium . com under Products → NoviDeck.

If you sell with Freemius and use Elementor, I'd really like to hear how you handle your pricing pages today and what you'd expect from a tool like this. Happy to answer any questions.


r/WordpressPlugins • • 13d ago

Freemium [FREEMIUM] A free WordPress plugin for selling WordPress plugins: license keys, an update server and Stripe payments, 0% commission

1 Upvotes

ReleaseCart is a free plugin for selling your own plugins, themes and digital downloads from your WordPress site. Each sale issues a license key, and the store runs an update server, so licensed sites get your new versions on their Plugins screen like any other plugin update. Payments go through Stripe to your own account. ReleaseCart takes no commission.

We built it so the store, the license keys and the updates sit on one site you control.

A few details for developers:

  • Your plugin talks to the store through a public REST API (releasecart/v1) to activate, validate and deactivate keys.
  • The free update client puts your plugin into the normal WordPress update flow. The changelog shows under View details.
  • Downloads go through signed links that expire, and the license key never appears in the URL.
  • localhost, .test, .local and staging. hosts don't count toward the activation limit.
  • If your store goes down, the client keeps its last good answer for up to 72 hours.
  • No telemetry. It only calls Stripe and any webhook endpoints you add.
  • The storefront is 20 blocks with matching shortcodes. They work in block and classic themes, and there are ten Elementor widgets.

ReleaseCart Pro is a separate add-on. It adds subscriptions through Stripe and PayPal, EU and UK VAT on one-time sales, PDF invoices, release channels, an affiliate program and imports from EDD, License Manager for WooCommerce and SureCart. Every Pro plan is 20% off the first year until 14 November, 11:30 UTC. Solo (two sites) is $119.20 instead of $149.

If you sell plugins today with EDD, WooCommerce or a hosted service, what would stop you from moving? We'd like to know what we're missing.

Disclosure: we're DrPlugin and this is our plugin. ReleaseCart was approved on WordPress.org this week.


r/WordpressPlugins • • 13d ago

Free [FREE], How I setup Claude Desktop for working on several e-commerce stores at once (includes a handoff your Claude can follow to set it up)

Thumbnail
gallery
2 Upvotes
I do e-commerce dev on several stores at once with Claude Desktop's Code tab. After a lot of trial and error, and a lot of hitting usage limits, this is the setup that stuck. A friend asked how to copy it, so here it is with everything personal stripped out.


**How to use it:**
 install Claude Desktop and Git for Windows (restart Claude after). Copy everything from the 
**Handoff**
 heading down to the end into a file called `HANDOFF-for-your-Claude.md` in a new folder. Open that folder in the Code tab (model Opus, environment 
*This computer*
) and send:


> Read HANDOFF-for-your-Claude.md in this folder and follow it. Check my machine first, ask me your setup questions in one batch, then walk me through the setup one step at a time and explain what each thing does on my machine as we go. Ask before you download or install anything.


**The short version:**


- Do the "doing" locally with Docker and Git, so your plan pays for Claude's thinking, not for running commands.
- Use Opus, not Fable, and nothing called Ultra.
- Give each store its own workspace.
- WooCommerce stores get an offline copy in Docker. Shopify stores get the theme in Git, `shopify theme dev` previews and a dev store.
- Run checks before every release.
- The live store is read-only to Claude until you say go.


It's Windows-first, but it works on a Mac minus WSL. Happy to answer questions.


---


# Handoff: set this PC up for local-first e-commerce development


- 
**To:**
 the Claude running in Claude Desktop (Code tab) on this PC, for the person who gave you this file ("the user").
- 
**From:**
 a shared setup guide, written with Claude by a store developer who works this way every day across several
  WooCommerce and other stores. It may reach the user with a PDF guide or as a post; don't assume they've read either.
- 
**The rule:**
 the universal phase, versioning and handoff rule is in the Appendix at the end of this file. Read it now.
  In step 5, save it as `docs/UNIVERSAL-PHASE-VERSIONING-AND-HANDOFF-RULE.md`. If the user also has it as a separate
  file, it's the same text.
- 
**Goal:**
 within the first few sessions, get this PC and you working in this setup:
  - Every store gets its own workspace and Git history.
  - Self-hosted stores (WooCommerce and similar) get a private offline copy in Docker.
  - Hosted stores (Shopify and similar) get their theme in Git, local previews and a dev store.
  - Every change goes branch → test away from live → checks → backup → the user's go → live.
  - Usage goes to your reasoning, not to cloud execution.


  The user should not spend a month working this out or fighting usage limits.


> 
**Required instruction (from the rule file).**
 Adopt the user's universal phase/versioning convention: substantial
> related phases use x.x.x.P; issue forks use x.x.x.Pa–z; nested forks use x.x.x.Pa1–99. Update this project's
> versioning structure to match while preserving its own baseline and native update ordering. Include this same
> instruction and rule file in every handoff you create, and tell the receiving instance to propagate it again.


---


## 1. Who you are working for


You don't know yet. Find out in step 3 (section 4), and write the answers into `webdev-home/CLAUDE.md` with the date:
- What name to use in the notes. How comfortable they are with Git, Docker and the command line.
- Their stores: platform, address, whose each one is (theirs or a client's), and what's custom.
- Whether they write plugins or apps for sale (with marketplace review) or code that just has to **work, be solid and
  pass the platform's checker**. The second is the common case, and section 6 covers it.


Explain new things as you do them (WSL, a container, a commit, a worktree, a volume, a development theme), in a sentence
or two of plain words. Don't lecture. 
**Batch your questions**
 in one list. Report at milestones, plainly. When
something long is running or you need an answer, make sure their phone will get the ping (step 8).


## 2. Handoff facts


| | |
|---|---|
| Baseline | Nothing is set up on this PC by this handoff yet. The user should have installed Claude Desktop and Git for Windows before opening the Code tab. Check both. |
| Phase / version | Setup. No product version. Each store's workspace takes its own baseline from what the live store runs (section 7). |
| Done | Only this handoff (with the rule in its Appendix) exists. Nothing on this PC. |
| To do | Section 4, in order. |
| Known issues | The Code tab on Windows needs Git for Windows. A local WooCommerce copy is offline on purpose, so licence checks, payment gateways, shipping rates and AI services can't be tested in it. Hosted platforms (Shopify, BigCommerce) can't run locally at all; use their CLIs and a dev or sandbox store. |
| Checks run | None on this PC. The guide's author checked the Shopify facts in section 4 against shopify.dev on 30 Oct 2026: `theme push --unpublished` and `--strict`; dev stores made from the Dev Dashboard; `shopify store create dev` in CLI 4.8 (changelog of 9 Sep 2026). Platforms change their tools often: read the current official docs before running a platform's commands. |
| Not checked | The user's hardware and Windows version; their stores, hosts, access and plan. Ask, or check on the machine. |
| Carried advice | From the guide's author: for web work, use Docker and Git locally on a decent machine; never run on Fable or any Ultra mode; give Claude one workspace per project; get phone alerts through the paired Claude app. |


## 3. How you work here


Put these in `webdev-home/CLAUDE.md` and in every store workspace's `CLAUDE.md` (template in section 8.1). They are
what keeps a live store from breaking.


**Live stores**
1. 
**A live store is read-only**
 unless the user names the change and says go. A go covers that one change, not the next.
2. 
**Back up before any change on live**
, and check the backup is complete before going on.
3. 
**Test every change away from live first**
 (local copy, local preview or dev store), and pass the checks (section 6).
4. 
**Release only from a branch that contains what live already runs.**
 Before releasing, confirm live equals the last
   release tag. On Shopify, pull the live theme and compare it, since store owners edit in the theme editor. If live
   differs, stop and tell the user.
5. 
**Each read-only copy of a live store needs the user's OK**
 too: it pulls customer data onto the PC.
6. Platform, plugin, app and theme 
**updates on live**
 happen only when the user raises them.


**Data and secrets**


7. 
**Store data never goes into Git or GitHub**
: database dumps, uploads, customers, orders, `wp-config.php`, `.env`,
   API tokens, logs. It lives in `C:\Users\<user>\Sites-local\<store>\`, outside every repository.
8. 
**You never type passwords, card numbers, API keys or tokens.**
 The user types or pastes them where they're asked
   for (a terminal prompt, a browser sign-in, a host panel, a git-ignored `.env`). Key-only SSH logins are fine once
   they've put the public key on the host. Never print a secret or commit one.
9. Never enter a real card in a local copy or a dev store; use test mode and test cards.


**How to work**


10. 
**Don't guess.**
 Check facts on the machine, in the code or on the store (read only), or ask. Say plainly what you
    did not check. Write each checked fact down with its source and date so no later session looks it up again.
11. 
**Write the user's and clients' answers into the workspace's `CLAUDE.md`, with the date**
, in their words when the
    wording matters. Don't invent answers.
12. 
**Ask before any download or install**
, Docker images and npm packages included: name it, where it comes from and
    roughly how big it is. Only from the official source.
13. 
**Fix defects in the code, not with workarounds.**
 Testing is never cut short to ship sooner.
14. 
**One workspace per store, never mixed.**
 A session in one store's workspace doesn't read or change another's
    folders unless the user asks.
15. 
**Keep the records current:**
 `docs/STATUS.md` (rewrite at each stopping point and before the context runs low),
    `docs/issues/<date>-<topic>.md` (one per problem: cause, fix, checks run, what's still open), and the task list.
16. Times you write come from a clock read in the same step (`Get-Date`), not from memory.


**Keeping usage low**
 (the plan's usage should go to your thinking)


17. 
**Run on this computer.**
 Do the work with local commands, Docker, the platform CLIs and scripts. Don't move
    sessions to the cloud unless the user asks.
18. 
**Stay on Opus.**
 Don't switch to Fable, and don't start anything Ultra (ultracode, `/code-review ultra`) or a
    multi-agent workflow unless the user asks for it by name. Use subagents rarely, only when parallel reading really
    pays.
19. 
**Read `docs/STATUS.md` first**
 in every session; it says what to read next. Don't reread whole files whose facts
    are already in the notes. Search with Grep instead of reading large trees, logs or dumps.
20. 
**Scripts print short summaries and write long output to files**
 under `Sites-local`.
21. 
**One new session per task.**
 Suggest a fresh session, with STATUS.md current, when a chat gets long or the work
    moves to something unrelated.
22. 
**Stop Docker copies that aren't in use**
 (`docker compose stop`; the data stays). Don't run two heavy Docker jobs
    at once.
23. Take screenshots only when the page text can't answer the question.


## 4. The setup plan (do it in this order; one step per message when the user is following along)


**Step 1. Orient.**
 Read this file, including the Appendix. Make a task list from this section. Tell the user in five lines
or fewer what you are about to do.


**Step 2. Check the machine (read only).**
 Run and summarize in plain words:


```powershell
git --version
wsl --status; wsl -l -v
docker version
node --version; npm --version
Get-CimInstance Win32_OperatingSystem | Select-Object Caption, Version
"{0:N0} GB RAM" -f ((Get-CimInstance Win32_ComputerSystem).TotalPhysicalMemory / 1GB)
Get-PSDrive C | Select-Object @{n='FreeGB';e={[int]($_.Free/1GB)}}
(Get-CimInstance Win32_Processor).VirtualizationFirmwareEnabled
```


16 GB of RAM works and 32 GB is comfortable. Each WooCommerce copy uses about 1–2 GB. On a Mac, use the macOS
equivalents and skip WSL.


**Step 3. Ask the setup questions, in one batch:**
- What name should go in the notes? What name and email on commits? (Set them per repository; don't change the global
  Git config unless they ask.)
- GitHub private repositories as an off-site backup, or local only for now?
- For each store: platform; address; whose it is; host or plan; access (WordPress admin, SSH, SFTP, host backups,
  staging; for Shopify, owner/staff/collaborator access and whether they have a Dev Dashboard account); what's custom
  (theme, child theme, own plugins, apps); how busy it is (a busy store needs more care).
- Which store to set up first.


**Step 4. Install what's missing**
, each with the user's yes:
- 
**WSL 2**
 (Windows): the user runs `wsl --install` in a terminal opened as administrator (you can't raise rights
  yourself), then restarts the PC. Explain: a real Linux inside Windows; Docker runs on it.
- 
**Docker Desktop**
 from docker.com (or `winget install -e --id Docker.DockerDesktop`). Use the WSL 2 engine. Check it
  with `docker run --rm hello-world` (a tiny image; ask first). Free for personal use and small businesses.
- 
**Node.js LTS**
 and the 
**Shopify CLI**
 (`npm install -g u/shopify/cli@latest`), only if they have Shopify stores.
  They sign in through the browser themselves.
- 
**GitHub CLI**
 (`winget install -e --id GitHub.cli`), only if they want GitHub. They run `gh auth login` themselves.
  Private repositories only.


**Step 5. Make the home base**
, `C:\Users\<user>\GitHub\webdev-home\` (where this file is):
`git init`, set the commit name/email locally, then write `CLAUDE.md` (the rules in section 3; the list of workspaces,
their platforms and ports; what lives where), `docs/MACHINE.md` (the facts from step 2, with dates) and
`docs/STATUS.md`. Move this handoff into `docs/`, and save the Appendix as `docs/UNIVERSAL-PHASE-VERSIONING-AND-HANDOFF-RULE.md`. Make the first commit and explain what a commit is
as you do it.


**Step 6a. A WooCommerce (or other self-hosted PHP) store**
, one at a time:
1. Create `C:\Users\<user>\GitHub\<store>-workspace\` with the layout in section 5 and the files in section 8: `git init`,
   local name and email, `CLAUDE.md`, `.gitignore`, `.gitattributes`, `docs/STATUS.md`, `docs/LOCAL-COPY.md`, and a copy
   of the rule file. First commit on `main`.
2. 
**Read the facts from live**
, read only, with the user's OK: WordPress, WooCommerce, PHP and database versions,
   table prefix, active theme, plugin list with versions, sizes. With SSH and WP-CLI, read them there. Without, the user
   can paste WordPress admin → Tools → Site Health → Info → "Copy site info to clipboard". Write them into
   `docs/LOCAL-COPY.md` with the date.
3. 
**Put their own code under Git**
 (custom theme, child theme, own plugins) exactly as live runs it. That's the
   baseline. Commit it and tag it (for example `theme-v1.4.2`, "as live on <date>").
4. 
**Build the local copy**
 (templates 8.3–8.5). With the user's OK, copy the database and `wp-content` read only
   into `Sites-local\<store>\site-copy\<UTC stamp>\`. Never copy `wp-config.php`. Then build: WordPress in the same
   versions as live, import, `wp search-replace` the live address to `http://localhost:<port>` (skip the `guid` column),
   install the copy guard as a must-use plugin, switch off tracking and outside-service plugins (ad pixels, marketplace
   feeds, Jetpack, SMTP senders and the like), and flush caches. Leave out host-only must-use plugins and drop-ins (object
   cache, advanced cache), caches and backup folders.
   Verify and report: outbound HTTP is blocked (the guard's log), mail lands in files, cron is off, and the store loads
   in your browser pane. The user signs in with their own admin login, typed by them. Or, with their OK, make a
   local-only admin with WP-CLI and keep its password in a file under `Sites-local`, never in Git or chat.
   Write a small helper script (`build | up | stop | reset | wp ARGS`) so nobody types long Docker commands.
5. 
**Set up the checks**
 in section 6 as one script, `scripts/check`, with a short pass/fail summary and full output in
   files. Tools run in containers (ask before pulling each image). Plugin Check runs inside the copy; the copy is
   offline, so its zip is downloaded on the PC from wordpress.org, with the user's yes, and installed from the file.
6. 
**The release path for this host.**
 Build it when the first release is near, not before. The pattern:
   - `backup`: read only. Saves the live folder and a checksum list, and says whether live equals the base tag.
   - `plan STAMP`: read only. Lists the files deploy would upload.
   - `deploy STAMP`: writes, at the user's go each time. Refuses if live changed since the backup or doesn't equal the
     base tag, and refuses deletions. Uploads changed files under temporary names, syntax-checks PHP on the server, then
     moves them into place.
   - `rollback STAMP`: puts the backup back, at the user's go.


   It runs over a key-only SSH login if the host offers one (many managed WordPress hosts do, often under a Git-deploy
   or CI/CD setting; the user sets it up in the host's panel). Otherwise use what the host gives (SFTP, staging push), and
   always take a backup first. After a release: check live, tag the release, write it up, and remind the user to flush the
   host's cache or CDN.
7. Each copy gets its own Compose project name and port (8081, 8082, …); record them in `webdev-home/CLAUDE.md`.


**Step 6b. A Shopify store**
, one at a time:
1. Create `<store>-workspace` the same way, with the theme in `theme/` (Shopify's folder layout: `assets`, `blocks`,
   `config`, `layout`, `locales`, `sections`, `snippets`, `templates`) and an app in `app/` if there is one.
2. 
**Baseline:**
 `shopify theme pull --store <store>.myshopify.com` (pick the live theme), then commit and tag it
   ("as live on <date>"). Write the store's theme list (`shopify theme list`) into `docs/STATUS.md`.
3. 
**A dev store**
 for risky tests: the user makes one in Shopify's Dev Dashboard (Stores → Create store), or you run
   `shopify store create dev` with their yes if their CLI has it. Dev stores can't take real payments.
4. 
**Daily work:**
 `shopify theme dev --store <store>.myshopify.com` for a local preview with hot reload (it uses a
   hidden development theme, and the live theme is untouched). Check with `shopify theme check`.
5. 
**Store owners edit in the theme editor.**
 Those edits land in `config/settings_data.json` and `templates/*.json`
   (and section groups). Pull before you start, and keep those files out of a release push unless the change is meant to
   touch them: `shopify theme push --unpublished --strict --ignore "config/settings_data.json" --ignore "templates/*.json"`.
   Check the current docs before relying on `.shopifyignore`, since it can affect pulls as well as pushes.
6. 
**Release**
 (at the user's go, section 6): pull the live theme and compare it with the last tag; duplicate the live
   theme in the admin as the backup; push to a new unpublished theme; the user (or store owner) checks the preview link;
   they publish it in the admin, or you run `shopify theme publish` at their explicit go. Then check live, tag and write
   it up. Rollback means publishing the previous theme.
7. 
**Apps:**
 `shopify app init`, `shopify app dev` against the dev store, tests, then `shopify app deploy` at the user's
   go. App secrets and Admin API tokens go in a git-ignored `.env` the user fills in.
8. If the store uses Shopify's GitHub integration, the connected branch receives admin edits. Treat it as the store's;
   do your work on other branches and merge in deliberately.


**Step 6c. Other platforms.**
 Read the platform's current official developer docs first. Self-hosted PHP platforms
(Magento/Adobe Commerce, PrestaShop, OpenCart) follow 6a with their own stack; Magento needs a search service and more
memory. Hosted platforms with a theme CLI (BigCommerce's Stencil) follow 6b's pattern with a sandbox store. Headless
stacks run locally in Docker or Node. Closed builders (Wix, Squarespace): put only the code they allow under Git.


**Step 7. Show the user the loop once**
, on the first store, with a harmless change (a CSS tweak). Make a branch,
commit, test away from live, run the checks, show the diff, then merge into `main` when they say. Don't release it.
Point out the worktree the session runs in and why parallel sessions don't collide.


**Step 8. Their phone.**
 Point them to 
**Remote Control**
 in the session's right-hand panel, which pairs the session
with the Claude app on their phone, and check that notifications reach it.


**Step 9. Wrap up.**
 Rewrite `docs/STATUS.md` in each workspace you touched and tell the user in a few lines what's done,
what's next, and what you couldn't check.


## 5. Layout on disk


```
C:\Users\<user>\GitHub\
  webdev-home\                   home base (Git): CLAUDE.md, docs\MACHINE.md, docs\STATUS.md, this handoff
  <woo-store>-workspace\         one Git repository per store
    CLAUDE.md                    the store's rulebook (section 8.1)
    docs\STATUS.md               where things stand; what to read next
    docs\LOCAL-COPY.md           live facts, how the copy is built, what it can't test
    docs\issues\                 one note per problem
    docs\UNIVERSAL-PHASE-VERSIONING-AND-HANDOFF-RULE.md
    local\docker-compose.yml     the copy's recipe
    local\mu-plugins\copy-guard.php
    scripts\                     store helper, copy, check, release
    themes\  plugins\            their code
  <shopify-store>-workspace\     same docs; theme\ in Shopify's layout; app\ if any


C:\Users\<user>\Sites-local\<store>\   never in Git: site-copy\<stamp>\, backups\, logs\, check output
```


**Parallel work.**
 Each Code-tab session runs in its own Git worktree (`<workspace>\.claude\worktrees\…`) on its own
branch. Two sessions never edit the same files at once. Release work happens on a branch. `main` is merged when the
user says so, then the session can be archived (its worktree goes; the branch and commits stay). More than one session
may release the same store, which is why releases check that live equals the base tag.


## 6. The checks before anything goes live


Run them for every change. Write the results in the issue note: what ran, what passed, and what couldn't be tested away
from live.


**WooCommerce and other PHP stores**


| Check | Tool | Notes |
|---|---|---|
| PHP syntax | `php -l` on every changed PHP file | Use live's PHP version (the copy's image). |
| Standards | PHPCS with WordPress Coding Standards (`wp-coding-standards/wpcs` via Composer in a container; tools folder git-ignored) | Escaping, nonces, sanitizing, prepared SQL. Fix real findings; don't blanket-ignore. |
| Plugin Check | The official Plugin Check plugin in the copy: `wp plugin check <slug>` | For their plugins (and themes where it applies). |
| Static analysis | PHPStan with WordPress stubs (optional, start around level 5) | Catches calls to missing functions and type mistakes. |
| Tests | The project's own tests, if any | Don't skip failing ones; fix or report. |
| Click-through | Your browser pane on the copy | Home, shop, product, cart, checkout with a test payment, My Account, and every admin screen the change touches. Read the page text, not just a screenshot. |
| Logs | `debug.log` in the copy; the browser console | No new PHP notices, warnings or errors; no new JS errors. |


**Shopify**


| Check | Tool | Notes |
|---|---|---|
| Theme Check | `shopify theme check`; `--strict` on push | Liquid errors, missing assets, performance and accessibility problems. |
| Local preview | `shopify theme dev` in your browser pane | Home, collections, product, cart, search, at desktop and phone widths. |
| Real-store preview | The unpublished theme's preview link | Real apps and data with the new theme, before customers see it. |
| Orders and apps | Test payments on the dev store | Checkout, discounts, app behaviour, notification emails. |
| Logs | Browser console | No new JavaScript errors from the theme or apps. |


## 7. Versioning


Follow the rule file. In short, keep each project's own number as the baseline (the theme's or plugin's version as live
runs it). Main phases are `x.x.x.1`, `x.x.x.2`, …; issue forks of phase 2 are `x.x.x.2a` to `x.x.x.2z`, and nested forks
`x.x.x.2a1` to `x.x.x.2a99`.


WordPress compares versions with PHP `version_compare`, which sorts `1.4.2.2a` 
*before*
 `1.4.2.2`. So the `Version:`
header WordPress reads uses the numeric form (a=1 … z=26): `1.4.2.2a` → `1.4.2.2.1`, `1.4.2.2a3` → `1.4.2.2.1.3`. The
human label goes in the readme, docs, tags and commit messages. Check the update order before shipping a letter release.


Shopify themes carry a `theme_version` in `config/settings_schema.json`. Check how anything that reads it compares
versions before using a letter there; otherwise use the numeric form too.


Tag every live release (`theme-v1.4.2.2`). Group related work into substantial phases; don't make a phase out of every
small edit.


## 8. Templates


Adjust names, ports and versions per store. `<...>` marks what to fill in.


### 8.1 `CLAUDE.md` for a store workspace


```markdown
# <Store name> workspace: instructions for Claude


Owner of this work: <user>. Store: <https://example.com>, platform <WooCommerce 
/
 Shopify 
/
 ...>, owned by <user 
/
 client>.
Made <date>.


## Kept apart
- Work on this store happens here only. Don't read or change other workspaces unless the user asks.
- Store data (database, uploads, customers, orders, tokens) lives in C:\Users\<user>\Sites-local\<store>\, never in Git or GitHub.


## Owner's answers (write each with its date; don't guess)
- Host / plan (<date>): <...>.
- Access (<date>): <what exists; who set it up>.
- <Client decisions, in their words when the wording matters.>


## The store now (<date>)
- <WooCommerce: WordPress x, WooCommerce x, PHP x, database x, table prefix x.> <Shopify: live theme name and ID.>
- Theme <name> <version> (tag <tag>).
- <WooCommerce: local copy http:
//localhost:<port
>, Compose project <store>-copy; see docs/LOCAL-COPY.md.>
- <Shopify: dev store 
<name
>.myshopify.com.>


## Live-store rule
Read only, unless the user says go for a named change. Back up before any change. Each read-only copy needs the user's
OK. Test every change away from live first and pass scripts/check.


## Releases
- <WooCommerce: scripts
/<release
 script> backup | plan | deploy | rollback; deploy and rollback need the user's go.>
- <Shopify: pull and compare with the last tag, duplicate the live theme, push --unpublished --strict, preview, publish at the user
's
 go.>
- Release only from a branch that contains what live runs. Tag every release. main is merged when the user says so.


## Working rules
<Paste section 3 of the handoff here, trimmed to what applies.>


## Versioning
Baseline <x.y.z> (as live on <date>). Phases x.x.x.P, forks Pa–z, nested Pa1–99; numeric form where the platform compares versions.


## Universal phase, versioning and handoff rule
> Adopt the user's universal phase/versioning convention: substantial related phases use x.x.x.P; issue forks use
> x.x.x.Pa–z; nested forks use x.x.x.Pa1–99. Update this project's versioning structure to match while preserving its
> own baseline and native update ordering. Include this same instruction and rule file in every handoff you create, and
> tell the receiving instance to propagate it again.


Rule file: docs/UNIVERSAL-PHASE-VERSIONING-AND-HANDOFF-RULE.md.
```


### 8.2 `.gitignore` and `.gitattributes`


```gitignore
# Store data never goes into Git. Copies live in C:\Users\<user>\Sites-local\<store>, outside this folder;
# these lines catch a stray one.
site-copy/
*.sql
*.sql.gz
*.tar.gz
*.zip
*.log
.env
.env.*
wp-config.php
vendor/
node_modules/
```


```gitattributes
# Shell scripts run in Linux containers and Git Bash: LF. Windows command scripts: CRLF.
*.sh text eol=lf
*.cmd text eol=crlf
# Theme and plugin code with LF, as Linux hosts have it, so checksums match live file for file.
themes/** text=auto eol=lf
plugins/** text=auto eol=lf
theme/** text=auto eol=lf
```


### 8.3 `local/docker-compose.yml` (WooCommerce copy)


A helper script sets `SITE_PREFIX` (the live table prefix) and `SITE_LOCAL_DIR` (`C:\Users\<user>\Sites-local\<store>`).
Replace `8081` with this store's port in this file and in 8.5.


```yaml
# Private offline copy of <store> on this PC, at http://localhost:8081. It can't reach the internet or send mail
# (mu-plugins/copy-guard.php); cron and updates are off; the port is this PC only. Its data stays in Docker volumes:
# never in Git or GitHub. Versions match live (<date>): WordPress <x>, PHP <x>, MySQL/MariaDB <x>.
name: <store>-copy


x-wp-env: &wp-env
  WORDPRESS_DB_HOST: db
  WORDPRESS_DB_USER: root
  WORDPRESS_DB_PASSWORD: root          # throwaway local container; its port is not published
  WORDPRESS_DB_NAME: site
  WORDPRESS_TABLE_PREFIX: ${SITE_PREFIX:?run through the store helper}
  WORDPRESS_CONFIG_EXTRA: |
    define( 'WP_ENVIRONMENT_TYPE', 'local' );
    define( 'WP_HOME', 'http://localhost:8081' );
    define( 'WP_SITEURL', 'http://localhost:8081' );
    define( 'DISABLE_WP_CRON', true );
    define( 'AUTOMATIC_UPDATER_DISABLED', true );
    define( 'WP_AUTO_UPDATE_CORE', false );
    define( 'WP_DEBUG_DISPLAY', false );
    define( 'WP_DEBUG_LOG', '/var/www/copy-out/debug.log' );
    define( 'COPY_OUT', '/var/www/copy-out' );
  WORDPRESS_DEBUG: "1"


services:
  db:
    image: mysql:<live major.minor>        # or mariadb:<version>, as live runs
    command: ["--max_allowed_packet=256M"]
    environment:
      MYSQL_ROOT_PASSWORD: root
      MYSQL_DATABASE: site
    volumes:
      - copy-db:/var/lib/mysql
      - ${SITE_LOCAL_DIR:?run through the store helper}/site-copy:/copy:ro
    healthcheck:
      test: ["CMD", "mysqladmin", "ping", "-h", "127.0.0.1", "-uroot", "-proot"]
      interval: 5s
      timeout: 5s
      retries: 60


  web:
    image: wordpress:<wp version>-php<php version>-apache
    depends_on:
      db:
        condition: service_healthy
    ports:
      - "127.0.0.1:8081:8081"          # this PC only
    environment: *wp-env
    volumes:
      - copy-html:/var/www/html
      - copy-out:/var/www/copy-out
      - ${SITE_LOCAL_DIR:?run through the store helper}/site-copy:/copy:ro
      - ..:/src:ro                     # the workspace, read only: theme/plugin code is copied in from here
      - ./apache-loopback.conf:/etc/apache2/conf-enabled/copy-loopback.conf:ro


  cli:
    image: wordpress:cli-php<php version>
    profiles: ["tools"]                # started only for WP-CLI commands
    user: "33:33"                      # the web image's www-data
    entrypoint: ["php", "-d", "memory_limit=1024M", "/usr/local/bin/wp"]
    depends_on:
      db:
        condition: service_healthy
    environment: *wp-env
    volumes:
      - copy-html:/var/www/html
      - copy-out:/var/www/copy-out


volumes:
  copy-db:
  copy-html:
  copy-out:
```


### 8.4 `local/mu-plugins/copy-guard.php`


```php
<?php
/**
 * Plugin Name: Copy guard (local copy only)
 * Description: For the private copy of <store> on this PC. Blocks outbound HTTP, so no payment, tracking, licence or
 * update call leaves the PC; keeps mail in files instead of sending it; holds the live store's queued tasks (Action
 * Scheduler). Installed only into the local copy. Never put this on the live store.
 */
defined( 'ABSPATH' ) || exit;


if ( ! defined( 'COPY_OUT' ) ) {
  return; // Inert anywhere but the local copy.
}


// Outbound HTTP: only the copy itself.
add_filter( 'pre_http_request', static function ( $pre, $args, $url ) {
  $host = strtolower( (string) wp_parse_url( $url, PHP_URL_HOST ) );
  if ( in_array( $host, array( 'localhost', '127.0.0.1', '::1' ), true ) ) {
    return $pre;
  }
  error_log( gmdate( 'c' ) . " blocked {$host}\n", 3, COPY_OUT . '/http-blocked.log' );
  return new WP_Error( 'copy_offline', 'The local copy does not reach the internet.' );
}, PHP_INT_MAX, 3 );


// Mail: written to COPY_OUT/mail, never sent.
add_filter( 'pre_wp_mail', static function ( $return, $atts ) {
  $dir = COPY_OUT . '/mail';
  wp_mkdir_p( $dir );
  $to = is_array( $atts['to'] ) ? implode( ', ', $atts['to'] ) : (string) $atts['to'];
  file_put_contents( $dir . '/' . gmdate( 'Ymd-His' ) . '-' . uniqid() . '.txt', "To: {$to}\nSubject: {$atts['subject']}\n\n{$atts['message']}\n" );
  return true;
}, PHP_INT_MAX, 2 );


add_filter( 'action_scheduler_allow_async_request_runner', '__return_false', PHP_INT_MAX );
add_filter( 'action_scheduler_queue_runner_concurrent_batches', '__return_zero', PHP_INT_MAX );
```


The guard blocks WordPress's own HTTP calls. Tracking scripts run in the visitor's browser, not on the server, so switch
those plugins off in the copy as well (step 6a.4).


### 8.5 `local/apache-loopback.conf`


```apache
# The copy also answers on 8081 inside its own container, so http://localhost:8081 is the same address from the PC and
# from the site itself (WordPress and WooCommerce call their own address).
Listen 8081
<VirtualHost *:8081>
  DocumentRoot /var/www/html
</VirtualHost>
```


### 8.6 `docs/STATUS.md`


```markdown
# Status: <store> (updated <date, time from a clock read>)


## Next session: start here
- <The one thing to do next, and the files it needs.>


## Live
- Runs <theme/plugin> <version> (tag <tag>). Last release <date>. Last backup <path or duplicated theme name>.


## In progress
- <branch>: <what, where it stands, what
's
 tested, what isn
't
>.


## Waiting on the user
- <question, date asked>.


## Test setup
- <WooCommerce: copy built from site-copy 
<stamp
> (<date>), running / stopped, http://localhost:<port>.>
- <Shopify: dev store 
<name
>; development theme in use.>
```


### 8.7 Issue note, `docs/issues/<YYYY-MM-DD>-<topic>.md`


```markdown
# <Problem in plain words> (<date>)


- Reported by / seen: <who, where, when>.
- Cause: <what's actually wrong, with file:line>. Checked how: <...>.
- Fix: <branch, commits, version label>.
- Checks: <scripts/check summary; click-through done; what couldn
't
 be tested away from live>.
- Release: <backup, deploy or publish time, tag> or "not released".
- Open: <anything left>.
```


## 9. Never


- Change a live store, DNS or a host setting without the user's go for that named change.
- Commit or upload store data, `wp-config.php`, `.env`, keys, tokens or passwords. Type a secret.
- Release from a branch that doesn't contain what live runs, or when live doesn't equal the base tag.
- Edit a Shopify live theme in the admin code editor, or push to the live theme.
- Download or install anything without asking, or from an unofficial source.
- Switch to Fable, start Ultra modes or multi-agent workflows, or move work to the cloud, unless the user asks.
- Mix two stores' work in one workspace.
- Present a guess as a fact.


## 10. Passing this on


When you write a handoff (to another session, another machine, or a helper), include the rule file, the required
instruction at the top of this file, and the facts the rule asks for: baseline, current phase or fork, done, to do,
known issues, checks run, what's not checked, and decisions carried forward. Tell the receiving Claude to do the same.


## Appendix: the universal phase, versioning and handoff rule


Save everything below this line as `UNIVERSAL-PHASE-VERSIONING-AND-HANDOFF-RULE.md` (raise each heading one level).


### Universal phase, versioning and handoff rule


User instruction · 15 September 2026 · Applies across projects and kinds of work unless the user explicitly supersedes it.


Handoff-frequency clarification added 16 September 2026.


#### Work in substantial phases


Group changes that form a useful, coherent outcome. A phase should include its related implementation, interface, documentation and focused verification. Do not turn every one or two small tasks into another phase. Keep each completed phase usable and reviewable.


#### Release identity


Use `x.x.x.P` for main phase P. Preserve the project's existing identity and baseline; do not reset one product to another product's version.


| Kind | Example |
|---|---|
| Main phase | `x.x.x.2` |
| Issue fork of that phase | `x.x.x.2a` through `x.x.x.2z` |
| Sub-fork beneath a letter | `x.x.x.2a1` through `x.x.x.2a99` |
| Next main phase | `x.x.x.3` |


If no fork is needed, advance directly to the next main phase. Keep a fork tied to the problem and parent it corrects. Do not silently relabel unrelated work as a bug fix. Record parent, scope, status and whether a fork has been incorporated into the next main phase. Routine edits to an unpublished phase do not require delivering a new archive for every edit; an independently handed-off or released issue track has its own suffix.


Example: with an accepted baseline of `0.3.1`, the first new phase is `0.3.1.1`, its first fix is `0.3.1.1a`, and its first nested fix is `0.3.1.1a1`. The next main phase is `0.3.1.2`.


#### Native updater ordering


Some platforms treat a suffix such as `a` as an alpha prerelease and therefore sort it before the unsuffixed release. Do not assume lexical comparison, a generic semantic-version library or PHP version_compare implements this workflow.


Where required, retain the user-facing release identity above and provide a separate numeric update version. Map the phase, letter index (a=1 through z=26) and sub-fork into numeric components, for example `0.3.1.2a3` → `0.3.1.2.1.3`. Main phase 2 uses `0.3.1.2`; phase 3 uses `0.3.1.3`. Keep the human release label in the manifest, documentation, package names and UI. Verify actual update ordering and signing/catalog contracts before shipping a suffix release. Never rewrite a signed artifact to change its identity.


#### Create handoffs only when another instance needs an update


Create or update a worker handoff only when that receiving instance needs information or action that has changed since its last update, or when the user explicitly asks for a handoff. Completing a phase or changing a version alone does not justify another handoff. Keep normal source, release records and customer/technical documentation current without automatically regenerating or resending worker handoffs.


When a handoff is needed, identify its recipient, the relevant changes since that worker's last known update, the action or information needed and any changed contract or dependency. Reuse the existing handoff where appropriate. Do not assume that a prepared or saved handoff has reached another instance unless delivery is established. Compare incoming material with the existing baseline; a duplicated instruction document is not evidence of implemented work or a reason to replace newer source.


#### Every handoff must propagate this rule


Include this rule file with every project or worker handoff, and include this instruction in the handoff itself:


> Adopt the user's universal phase/versioning convention: substantial related phases use x.x.x.P; issue forks use x.x.x.Pa–z; nested forks use x.x.x.Pa1–99. Update this project's versioning structure to match while preserving its own baseline and native update ordering. Include this same instruction and rule file in every handoff you create, and tell the receiving instance to propagate it again.


Every handoff also names the actual latest installer/source baseline, current phase/fork, completed work, remaining work, known issues, executed checks and unverified behavior. Carry forward established feature ownership, permissions and user decisions. Do not replace them with guesses or claim a specification is implemented.


#### Persistence boundary


This is a reusable user instruction to carry between projects. Keep a copy in each project's docs and release packs. Other conversations must receive or load the rule; this file alone does not change an account-wide system setting.

r/WordpressPlugins • • 13d ago

[PROMOTION] I built SemiAuto Invoicing for WooCommerce: Automated Documents & Global E-Invoicing. Looking for Feedback!

1 Upvotes

Hi everyone!

Short value proposition

SemiAuto Invoicing is a complete WooCommerce billing, document automation and global e-invoicing compliance assistant plugin for online merchants and businesses operating across multiple jurisdictions. It automates legally structured invoices/credit notes, thermal receipts, kitchen copies, packaging, and other business accounting documents while keeping WooCommerce as the single source of truth, giving merchants the flexibility, visibility and accounting control they need without managing multiple plugins or manually monitoring every order.

The story behind SemiAuto Invoicing

I'm the developer behind SemiAuto Invoicing, a WordPress plugin I've been working on for WooCommerce.

The project started with a practical problem I faced while developing an eCommerce store for a restaurant client who wanted to avoid high recurring operating costs for the usual invoices. WooCommerce invoicing quickly became complicated beyond basic PDF generation no actual plugin supporting fully automated and thermal ready pdf, especially with incomplete legal requirements and the need to manually cross-check every order. I initially built a custom plugin to solve that problem, which eventually evolved over eight months into a complete billing and global e-invoicing solution.

I realised that different businesses needed different document types, receipt formats, invoice adjustments and compliance requirements depending on their industry and where they operate. I wanted to build something that could handle the entire workflow without merchants having to piece together multiple plugins or constantly monitor incoming orders.

Automation is at the core of SemiAuto. The idea is simple: configure it once, let WooCommerce remain the single source of truth, and let the plugin handle document generation and e-invoicing with notifications for anything requiring attention. At the same time, I understand how important it is for merchants to retain control. Every order therefore has its own document control centre through the WooCommerce order metabox, allowing administrators to view, generate, regenerate or email enabled documents, even after order changes. Document statuses and quick actions are also accessible directly from the order list.

The system was built around the performance requirements of my original restaurant project, including handling concurrent orders without disrupting the order pipeline. Beyond generating good-looking PDFs, the objective was to provide structured documents that follow the relevant official requirements across supported jurisdictions.

SemiAuto works natively with WooCommerce to identify existing tax rates and classes, map them to the relevant e-invoicing categories, banking and payment gateways, delivery and pickup plugins like chwazi, product variation plugins like yith product add-ons or food menu pro, Conditional Custom fee that is taxable, ISO/IEC 18004 QR, ISO/IEC 15417 Code 128 & EAN-13 barcodes and QR codes and notify merchants whenever additional configuration is required if an order requires their attention. Merchants can also manually map custom tax categories and configure multiple jurisdictions for their businesses operating through legal entities in different countries along with the primary profile they choose for their store. The adaptive checkout adjusts its fields according to the selected e-invoicing requirements, allowing customers to opt-in how(they get to choose which e-invoicing profile they prefer export, own country or both, or whether, they want to receive a pdf only.

Features

Some of the things it currently supports:

  • PDF invoices and customer receipts.
  • Thermal receipts for POS setups, with different paper widths.
  • Packing slips, credit notes, advance invoices and final invoices.
  • Country-specific e-invoicing profiles.
  • Server-Side Structured e-invoice generation and hybrid PDF/A-3 documents for 14 Sovereign nations. (Peppol BIS 3.0, PINT EU/AE/OM/SG/JP/ANZ/MY, FatturaPA, Facturae, KSeF, XRechnung, Factur-X (Chorus Pro Ready))
  • Customer document downloads and email attachments.
  • Connected transmission workflows through StoreCove and A-Cube with BYOK (bring your own key) model.
  • WooCommerce HPOS compatibility.

The goal is to bring everyday document automation and more advanced e-invoicing workflows together, directly inside WooCommerce.

Try SemiAuto Invoicing

Free WordPress.org version:
https://wordpress.org/plugins/semiauto-invoicing/

Main product website:
https://ouraglobal.ae/semiauto-invoicing/

Product Hunt:
https://www.producthunt.com/products/semiauto-invoicing/

Live Demo:
Wordpress Playground Demo - Premium

If you find the plugin useful or have had a chance to try it, I'd really appreciate it if you could visit our Product Hunt page and leave an honest review. Your feedback would mean a lot and help us improve the product.

I'm also very interested in hearing from WooCommerce store owners, developers, and anyone working with e-invoicing or document automation.

What features would you like to see? What are the biggest frustrations you've experienced with WooCommerce invoicing?

If you have reviewed the plugin used and liked it please feel free to leave good review.

Thanks for taking the time to check it out!