@refactco/refact-os 1.5.0

package/templates/overlays/nextjs/agent/skills/setup-nextjs-app/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: setup-nextjs-app
+description: Create or adopt a Next.js app under apps/<name>, preserving existing project choices and documenting local runtime details.
+pattern: procedure
+when_to_use: /refact setup nextjs app | add Next.js app | create a Next.js app | adopt existing Next.js codebase.
+when_not_to_use: Non-Next.js projects, or tasks that only modify an already configured app.
+next_skills:
+  - nextjs-dev
+  - setup-vercel-deploy
+  - setup-netlify-deploy
+sub_agents: []
+---
+
+# Setup Next.js App Reference
+
+Use this reference when the user asks to create a new Next.js application or bring an existing Next.js app into a `refact-os` project.
+
+## Goal
+
+Create a predictable home for runnable Next.js code without turning `refact-os` into a framework starter. The scaffold owns the agent operating system; `create-next-app` or the existing application owns framework code.
+
+## Canonical layout
+
+```txt
+<project-root>/
+├── apps/
+│   └── <app-name>/
+│       ├── AGENTS.md
+│       ├── docs/              # earned once technical docs exist
+│       ├── package.json
+│       └── ... Next.js code
+├── agent/
+└── docs/
+```
+
+Use `apps/web` as the default app name only when the user has not supplied a name. If another app already exists, ask before choosing a name.
+
+## Preflight
+
+1. Confirm `.refact-os.json` has a `stack.nextjs` entry, or that the target codebase has `next.config.*` / a `next` dependency. If not, ask whether to continue as a Next.js project.
+2. Inspect the existing repo shape:
+   - Is there already a Next.js app at the root?
+   - Is there already an app under `apps/<name>/`?
+   - Which package manager is present: `pnpm-lock.yaml`, `yarn.lock`, `package-lock.json`, or `bun.lockb`?
+3. If moving an existing root app into `apps/<name>/` would touch many files, stop and propose the migration before editing. Do not silently restructure a working app.
+4. Do not overwrite an existing `apps/<name>/` directory.
+
+## Flow A — Create a new app
+
+1. Resolve:
+   - `APP_NAME` from the user's request, or `web` by default.
+   - `PACKAGE_MANAGER` from existing lockfiles; if none exist, use `npm`.
+2. Create the app with the official generator, using conservative defaults:
+
+   ```bash
+   npx create-next-app@latest apps/<app-name> --ts --eslint --app --src-dir --import-alias "@/*"
+   ```
+
+   If the repo already uses `pnpm`, `yarn`, or `bun`, use that package manager's equivalent runner. Do not force Tailwind, a package manager, or an experimental option unless the user asks.
+
+3. Add `apps/<app-name>/AGENTS.md`:
+
+   ```md
+   # AGENTS.md
+
+   This is the Next.js app for this project. Root project context lives in ../../agent/AGENTS.md and ../../docs/.
+
+   - Prefer existing components, route structure, package manager, and lint/build scripts.
+   - App technical docs belong in ./docs/ when they are specific to this app.
+   - Run the smallest relevant check after edits: lint, typecheck, tests, or build.
+   - Never commit .env* files with real secrets.
+   ```
+
+4. Add an `apps/<app-name>/docs/README.md` only if there is a concrete technical note to capture now. Otherwise let `docs/` be earned later.
+5. Report the app path, install command used, and available scripts from `apps/<app-name>/package.json`.
+
+## Flow B — Adopt an existing app
+
+1. If the app already lives under `apps/<name>/`, leave it there.
+2. If the app lives at the repo root, ask before moving it. A root-to-`apps/` migration may require updating:
+   - CI workflow paths.
+   - Vercel project root.
+   - Docker files.
+   - TypeScript path aliases.
+   - Import aliases and workspace package references.
+3. Add `AGENTS.md` inside the app if missing, using the template from Flow A.
+4. Record any unresolved migration decision in `docs/decisions.md` or `docs/task/open/` if the user wants to defer it.
+
+## Package manager rules
+
+- Existing lockfile wins. Do not introduce a second package manager.
+- In monorepos, prefer the root workspace manager and add the app to the workspace only if the repo already uses workspaces.
+- If package-manager intent is unclear, ask once before generating.
+
+## Verification
+
+From the app directory, run the smallest useful checks that exist:
+
+```bash
+npm run lint
+npm run build
+```
+
+Use the actual package manager. If a script is missing, report that rather than inventing one.
+
+## Guardrails
+
+- Do not scaffold framework code into the project root by default; use `apps/<app-name>/`.
+- Do not move a root app into `apps/` without user confirmation.
+- Do not add hosting, auth, database, analytics, or UI libraries as part of app setup unless requested.
+- Do not edit generated adapter folders (`.cursor/`, `.claude/`) by hand. Change `agent/` and run `npm run refact:sync`.
+- Do not commit secrets from `.env`, `.env.local`, or provider dashboards.
+
+## When to stop and ask
+
+- Multiple Next.js apps are present and the user did not name a target.
+- The repo already has a root Next.js app and moving it would affect CI/deploy paths.
+- The user asks for a starter choice with lasting consequences: Tailwind, shadcn/ui, database, auth provider, deployment target, or package manager.

package/templates/overlays/nextjs/agent/skills/setup-vercel-deploy/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: setup-vercel-deploy
+description: Link a Next.js app to Vercel and document deployment settings without assuming every Next.js project deploys to Vercel.
+pattern: procedure
+requires_approval: true
+when_to_use: /refact setup vercel deploy | deploy Next.js to Vercel | link this Next.js app to Vercel | configure Vercel for this app.
+when_not_to_use: Non-Vercel hosting, local-only development, or generic Next.js code changes.
+next_skills:
+  - nextjs-dev
+sub_agents: []
+---
+
+# Vercel Deploy Setup Reference
+
+Use this reference when the user explicitly wants a Next.js app linked or configured for Vercel. Do not run this automatically for every Next.js project.
+
+## Goal
+
+Set up deployment metadata and local verification while keeping project-specific hosting choices explicit. This skill may call external services, create project links, and change deployment settings, so it requires user approval before writes.
+
+## Preflight
+
+1. Confirm the target app path. If multiple Next.js apps exist, ask which app to deploy.
+2. Confirm Vercel is the intended hosting provider.
+3. Check whether the Vercel CLI exists:
+
+   ```bash
+   vercel --version
+   ```
+
+   If missing, ask before installing it. Prefer a project-local or `npx vercel` flow over global installation unless the user wants a global CLI.
+
+4. Check authentication:
+
+   ```bash
+   vercel whoami
+   ```
+
+   If unauthenticated, stop and ask the user to log in. Do not attempt to handle credentials in chat.
+
+5. Inspect existing Vercel state:
+   - `.vercel/project.json` means the app or repo is already linked.
+   - `vercel.json` may define framework/build/output settings.
+   - Existing GitHub workflows may already deploy the app.
+
+## Link flow
+
+1. From the target app directory, run:
+
+   ```bash
+   vercel link
+   ```
+
+2. If the repo is a monorepo, make sure the Vercel project root points at the app directory (`apps/<app-name>`), not the repo root, unless the repo intentionally builds from root.
+3. Do not commit `.vercel/` unless the team intentionally tracks Vercel project metadata. If unsure, ask. Many teams keep `.vercel/` local and document the project name instead.
+4. Record hosting (`vercel`) and each environment's `branch` + `url` (production and preview/staging) in `.refact-os.json` › `stack.nextjs` when stable. Keep app-specific build details (deployment owner, project name, app root, build command) in `apps/<app-name>/docs/deploy.md`.
+
+## Environment variables
+
+1. List required variable names from docs, `.env.example`, and code references.
+2. Add or pull variables through Vercel CLI only with explicit user approval:
+
+   ```bash
+   vercel env ls
+   vercel env pull
+   ```
+
+3. Never paste secret values into files, chat, logs, or docs. Document names and purpose only.
+4. Keep local `.env.local` uncommitted.
+
+## Verification
+
+Prefer local production checks before deploying:
+
+```bash
+npm run build
+vercel build
+```
+
+Use the app's actual package manager. If `vercel build` fails because the project is not linked or env vars are missing, surface the missing piece rather than guessing.
+
+For a preview deploy, confirm with the user, then run:
+
+```bash
+vercel deploy
+```
+
+For production promotion, require explicit approval:
+
+```bash
+vercel deploy --prod
+```
+
+## Git integration
+
+If Vercel Git integration is enabled, prefer PR preview deployments over ad-hoc CLI deploys. Document:
+
+- Production branch.
+- Preview branch behavior.
+- Monorepo root directory.
+- Required Vercel project environment variables.
+
+## Guardrails
+
+- Never assume Vercel just because the app is Next.js.
+- Never deploy to production without explicit user approval.
+- Never print, commit, or store secret values.
+- Never change DNS, domains, production branch, or project ownership without confirmation.
+- Never overwrite existing `vercel.json` or CI workflows without reading them and explaining the change.
+
+## When to stop and ask
+
+- The app is already linked to a different Vercel project than the user named.
+- The repo root and Vercel root directory disagree.
+- Required environment variables are unknown or missing.
+- The user asks to promote a preview to production or change domain settings.

package/templates/overlays/wordpress/agent/skills/install-wp-skills/SKILL.md

@@ -0,0 +1,130 @@
+---
+name: install-wp-skills
+description: Vendor the WordPress/Gutenberg agent skills into this project. WordPress projects only.
+pattern: procedure
+when_to_use: /refact install wp skills | add WordPress agent skills | pull Gutenberg/block skills.
+when_not_to_use: Non-WordPress projects.
+next_skills: []
+sub_agents: []
+---
+
+# Install WordPress Agent Skills Reference
+
+Use this reference when the user invokes `/refact install wp skills` (or asks to "add WordPress skills", "pull the WP agent skills", "install Gutenberg/block skills", etc.).
+
+## Goal
+
+Vendor in a curated set of WordPress-specific skills from the upstream [`WordPress/agent-skills`](https://github.com/WordPress/agent-skills) repository into this project's `.cursor/skills/` directory, alongside the `refact` and `code-development` skills.
+
+These skills give the agent expert WordPress knowledge (blocks, block themes, plugin dev, REST API, performance, etc.) without bloating the refact-os scaffolder itself.
+
+## Curated skill list (default)
+
+| Skill | Teaches |
+|---|---|
+| `wp-block-development` | Gutenberg blocks: `block.json`, attributes, rendering, deprecations |
+| `wp-block-themes` | Block themes: `theme.json`, templates, patterns, style variations |
+| `wp-plugin-development` | Plugin architecture, hooks, settings API, security |
+| `wp-rest-api` | REST routes/endpoints, schema, auth, response shaping |
+| `wp-interactivity-api` | Frontend interactivity with `data-wp-*` directives and stores |
+| `wp-abilities-api` | Capability-based permissions and REST API authentication |
+| `wp-wpcli-and-ops` | WP-CLI automation, multisite, search-replace |
+| `wp-performance` | Profiling, caching, DB optimization, Server-Timing |
+| `wp-phpstan` | PHPStan static analysis tuned for WordPress |
+| `wp-playground` | WordPress Playground for instant local environments |
+
+The upstream repo also ships `wordpress-router`, `wp-project-triage`, `wpds`, `wp-plugin-directory-guidelines`, and `blueprint`. They are **not** in the default set — `wordpress-router` and `wp-project-triage` overlap with the `refact` and `code-development` skills; the others are situational. Install them explicitly only if the user asks.
+
+## Step 1 — Preflight
+
+### 1a. Confirm this is a WordPress project
+
+Check `.refact-os.json` for a `stack.wordpress` entry, or look for `wp-content/` / `.wp-env.json`. If the project is **not** WordPress, stop and ask the user to confirm — these skills are WP-specific and have no value in a non-WordPress project.
+
+### 1b. Check prerequisites
+
+```bash
+command -v git
+command -v node
+node --version
+```
+
+`node` must be **18 or newer** (the upstream `skillpack-build.mjs` script uses modern ESM + node:fs features). If it's older, surface the version and stop.
+
+### 1c. Confirm with the user
+
+Print the curated list above and ask the user to confirm before proceeding. Offer them the chance to:
+
+- Accept the default subset.
+- Add to it (e.g. include `wpds` for design system work).
+- Subtract from it (e.g. skip `wp-playground` if they already use Local).
+
+Record the final skill list as `<skills>` for Step 3.
+
+## Step 2 — Clone upstream to a temp dir
+
+Do **not** clone the upstream repo into the project tree — it would pollute git status. Use a temp directory:
+
+```bash
+WP_SKILLS_TMP="$(mktemp -d -t wp-agent-skills.XXXXXX)"
+git clone --depth=1 https://github.com/WordPress/agent-skills.git "$WP_SKILLS_TMP"
+```
+
+If the clone fails (network, rate limit, repo moved), surface the exact error and stop. Do **not** retry by switching protocols or guessing alternate URLs.
+
+## Step 3 — Build and install
+
+From inside the temp clone, build the distribution and install only the chosen skills with `--targets=cursor`:
+
+```bash
+cd "$WP_SKILLS_TMP"
+node shared/scripts/skillpack-build.mjs --clean
+node shared/scripts/skillpack-install.mjs \
+  --dest="<absolute-path-to-this-project>" \
+  --targets=cursor \
+  --skills=<skills>
+```
+
+Notes:
+
+- `<absolute-path-to-this-project>` is the directory where the user invoked `/refact`. Capture it before `cd`-ing into the temp dir (`PROJECT_ROOT="$(pwd)"` before the `cd`).
+- `<skills>` is the comma-separated final list from Step 1c (e.g. `wp-block-development,wp-plugin-development,wp-rest-api,...`).
+- The installer uses `--mode=replace` by default, which only overwrites the specific skill subfolders being installed. `.cursor/skills/refact/` and `.cursor/skills/code-development/` are untouched.
+- Do **not** pass `--global` here — these skills should live in the project, not the user's home, so each engagement controls its own set.
+
+If the install script errors with "Unknown skill: …", correct the name (skills are case-sensitive, kebab-case) and re-run. Don't silently drop the unknown name from the list.
+
+## Step 4 — Clean up
+
+```bash
+rm -rf "$WP_SKILLS_TMP"
+```
+
+If `rm` fails (permissions, the user `cd`-ed into the tmp dir, etc.), surface it but do **not** retry with `sudo` or `-f` flags beyond what's shown.
+
+## Step 5 — Verify and report
+
+```bash
+ls .cursor/skills/
+```
+
+Confirm each requested skill landed as `.cursor/skills/wp-<name>/SKILL.md`. Then report to the user:
+
+- The list of installed skills with one-line descriptions (from the table above).
+- A reminder that these skills are now available alongside `refact` and `code-development`, and will be auto-invoked by the agent when relevant tasks come up (e.g. asking to build a block triggers `wp-block-development`).
+- A note that the skills are vendored copies — to update them later, the user can re-run `/refact install wp skills` and the installer will replace the existing folders.
+
+## Updating later
+
+To pull newer versions of the upstream skills, just re-run this flow. The `--mode=replace` default means each skill folder is rebuilt from the latest upstream contents — local edits to the vendored copies will be lost, so:
+
+- If the user has modified a vendored skill, ask before overwriting.
+- Encourage them to upstream the change to `WordPress/agent-skills` rather than fork locally.
+
+## Guardrails
+
+- **Never** clone the upstream repo into the project tree.
+- **Never** install with `--global` from this flow — global installs belong to the user's home, not a per-project scaffolder.
+- **Never** add `wordpress-router` or `wp-project-triage` to the default set — they overlap with `refact` routing.
+- **Never** silently overwrite a user-modified vendored skill. Ask first.
+- **Never** retry a failed clone or install with elevated permissions or alternative flags without user approval.

package/templates/overlays/wordpress/agent/skills/setup-kinsta-deploy/SKILL.md

@@ -0,0 +1,201 @@
+---
+name: setup-kinsta-deploy
+description: Create the Kinsta auto-deploy GitHub workflows for apps/wordpress. WordPress-on-Kinsta only.
+pattern: procedure
+requires_approval: true
+when_to_use: /refact setup kinsta auto-deploy | add kinsta deploy | create kinsta workflows.
+when_not_to_use: Non-Kinsta hosting.
+next_skills: []
+sub_agents: []
+---
+
+# Kinsta Auto-Deploy Reference
+
+Use this reference when the user invokes any of:
+
+- `/refact setup kinsta auto-deploy`
+- `/refact add kinsta deploy`
+- `/refact enable kinsta auto-deploy`
+- `/refact create kinsta workflows`
+
+This reference both **documents** how the Kinsta auto-deploy works for projects scaffolded by this package, and **drives the agent** to create the GitHub Actions workflow files on demand. The workflow YAMLs are *not* pre-vendored into the project — they are generated by following Step 2 below, because not every engagement deploys to Kinsta.
+
+## TL;DR
+
+```
+push to main  ──▶  .github/workflows/wordpress-deploy-main.yml   ──▶  Kinsta prod
+push to stage ──▶  .github/workflows/wordpress-deploy-stage.yml  ──▶  Kinsta stage
+
+(both path-filtered on apps/wordpress/**; both force-push a fresh single-commit
+ tree to Kinsta's bare SSH repo)
+```
+
+Each workflow:
+
+1. Checks out the monorepo.
+2. `cd apps/wordpress && rm -rf .git && git init -b main` — fresh repo each run.
+3. `git add .` — staging is filtered by `apps/wordpress/.gitignore` (WP core is excluded).
+4. Force-pushes the single-commit tree to Kinsta's bare SSH endpoint.
+5. Kinsta's post-receive hook checks the working tree into the WP install root.
+
+## Step 1 — Preflight
+
+### 1a. Confirm this is a WordPress project
+
+Check `.refact-os.json` for a `stack.wordpress` entry and that `apps/wordpress/` exists. If not:
+
+- No `apps/wordpress/` → stop and tell the user to scaffold the WordPress app first (`/refact add codebase wordpress`).
+- `stack` has no `wordpress` entry → ask the user to confirm; this flow is WordPress-specific.
+
+The **non-secret** deploy routing — each env's `branch`, and its `ssh` `host` / `port` / `path` plus the public `url` — lives in `.refact-os.json` › `stack.wordpress.environments` (`production` and `staging`); read it from there and keep it consistent with the GitHub Actions secrets the workflow consumes (`ENV_IP`, `ENV_NAME`, `ENV_DIRECTORY`, `ENV_*_PORT`). The SSH **private key** (`SSH_PRIV_KEY`) is a secret and lives only in GitHub Actions — never in `.refact-os.json`.
+
+### 1b. Confirm the two `.gitignore` files are in place
+
+| File | Purpose |
+|---|---|
+| `/.gitignore` (repo root) | Excludes other `apps/<name>/` slots from the monorepo. Pattern: `apps/*` + `!apps/wordpress/`. Adding a new tracked app means another carve-out line. |
+| `/apps/wordpress/.gitignore` | Classic WP "ignore core, allow wp-content" filter. **Also** doubles as the filter for what reaches Kinsta — anything ignored here is never committed during the workflow's fresh-init step, so it never lands on Kinsta. |
+
+If `apps/wordpress/.gitignore` is missing, stop. Do not generate one on the fly — the WordPress scaffold owns that file.
+
+### 1c. Confirm with the user
+
+Tell the user what is about to be created:
+
+- `.github/workflows/wordpress-deploy-stage.yml`
+- `.github/workflows/wordpress-deploy-main.yml`
+
+And remind them which GitHub Actions secrets they will need to add **before** the workflows can succeed. List them:
+
+| Secret | Purpose |
+|---|---|
+| `SSH_PRIV_KEY` | Private SSH key matching the public key added in Kinsta's SSH settings |
+| `ENV_IP` | Kinsta server IP (shared between prod and stage) |
+| `ENV_NAME` | Kinsta user / bare repo name |
+| `ENV_DIRECTORY` | Path slug (e.g. `credaily_764`) |
+| `ENV_PROD_PORT` | Kinsta production SSH port |
+| `ENV_STG_PORT` | Kinsta staging SSH port |
+
+Confirm before writing files.
+
+## Step 2 — Create the workflow files
+
+GitHub Actions only reads workflows from the **repo root** `/.github/workflows/`. Never place these under `apps/wordpress/.github/` — GitHub will not run them, and they would pollute Kinsta's checkout.
+
+Each workflow's `branches:` filter must match the branch recorded for that env in `.refact-os.json` › `stack.wordpress.environments` — `staging.branch` drives the stage workflow, `production.branch` the main workflow. The examples below use `stage` and `main`; substitute the project's actual branch names if they differ.
+
+### `/.github/workflows/wordpress-deploy-stage.yml`
+
+```yaml
+name: WordPress staging deploy
+on:
+  push:
+    branches: [stage]
+    paths:
+      - 'apps/wordpress/**'
+  workflow_dispatch:
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Push apps/wordpress to Kinsta (staging)
+        run: |
+          mkdir -p ~/.ssh
+          chmod 700 ~/.ssh
+          eval $(ssh-agent -s)
+          echo "${{ secrets.SSH_PRIV_KEY }}" | tr -d '\r' | ssh-add -
+          ssh-keyscan -p${{ secrets.ENV_STG_PORT }} ${{ secrets.ENV_IP }} >> ~/.ssh/known_hosts
+          chmod 644 ~/.ssh/known_hosts
+
+          cd apps/wordpress
+          rm -rf .git
+          git init -b main
+          git config user.email "deploy@github.actions"
+          git config user.name "GitHub Actions"
+          git add .
+          git commit -m "Deploy ${{ github.sha }} from monorepo"
+          git push ssh://${{ secrets.ENV_NAME }}@${{ secrets.ENV_IP }}:${{ secrets.ENV_STG_PORT }}/www/${{ secrets.ENV_DIRECTORY }}/private/${{ secrets.ENV_NAME }}.git HEAD:main --force
+```
+
+### `/.github/workflows/wordpress-deploy-main.yml`
+
+Identical to the stage file with these substitutions:
+
+- `name:` → `WordPress production deploy`
+- `branches: [stage]` → `branches: [main]`
+- Step name → `Push apps/wordpress to Kinsta (production)`
+- `${{ secrets.ENV_STG_PORT }}` → `${{ secrets.ENV_PROD_PORT }}` (in both the `ssh-keyscan` and `git push` lines)
+
+Everything else — the path filter, the fresh-init logic, the force-push, the destination path `www/<ENV_DIRECTORY>/private/<ENV_NAME>.git` — stays the same.
+
+## Step 3 — Report and hand off
+
+Tell the user:
+
+1. Which files were created.
+2. The list of GitHub Actions secrets they must add at **Settings → Secrets and variables → Actions** before the first push. If any are missing, the workflow fails at the `ssh-add` or `git push` step.
+3. The next step: push to `stage` first, watch the run in the Actions tab, then promote `stage → main` via PR.
+4. That the workflows are **path-filtered** on `apps/wordpress/**`, so edits elsewhere in the monorepo will not trigger a deploy or burn Actions minutes.
+
+## Adding new tracked files under `apps/wordpress/`
+
+The nested `apps/wordpress/.gitignore` is an allow-list. New files in `wp-content/mu-plugins/`, `wp-content/plugins/`, or `wp-content/themes/` need an explicit `!` exception or git won't see them — and if git doesn't see them, neither does Kinsta.
+
+Example for a new mu-plugin:
+
+```gitignore
+# apps/wordpress/.gitignore (excerpt)
+wp-content/mu-plugins/*
+!wp-content/mu-plugins/cre-daily
+!wp-content/mu-plugins/cre-daily.php
+!wp-content/mu-plugins/your-new-plugin.php
+```
+
+Verify it works before committing:
+
+```bash
+git check-ignore -v apps/wordpress/wp-content/mu-plugins/your-new-plugin.php
+# Should print the `!...` rule line, NOT the `wp-content/mu-plugins/*` line.
+```
+
+`git status` showing the file as untracked is the green-light.
+
+## Smoke-testing the auto-deploy
+
+Round-trip test that doesn't touch theme/plugin code:
+
+1. On `stage`, create `apps/wordpress/wp-content/mu-plugins/deploy-test.php`:
+
+   ```php
+   <?php
+   /** Plugin Name: Deploy Test */
+   defined('ABSPATH') || exit;
+   add_action('wp_footer', function () {
+       echo '<div style="position:fixed;bottom:8px;right:8px;background:#222;color:#fff;padding:6px 10px;font:12px monospace;z-index:99999;">deploy ok &middot; ' . esc_html(gmdate('c')) . '</div>';
+   });
+   ```
+
+2. Add `!wp-content/mu-plugins/deploy-test.php` to `apps/wordpress/.gitignore`.
+3. Commit and `git push origin stage`.
+4. Watch `https://github.com/<org>/<repo>/actions` → "WordPress staging deploy" run.
+5. Visit the staging URL — bottom-right badge means the tree reached Kinsta and was checked out.
+6. Revert via a **new commit** (don't amend) — delete the file, remove the gitignore line, push.
+
+## Hard rules
+
+1. **Force-push (`--force`) is required for the Kinsta endpoint and only the Kinsta endpoint.** Kinsta's bare repo can't fast-forward against a fresh-init tree. Never `--force` to GitHub's `main` or `stage`.
+2. **Never delete or aggressively rewrite `apps/wordpress/.gitignore`.** It's load-bearing — without it, the fresh-init would push WordPress core files to Kinsta on every deploy. Kinsta provisions core; we only push wp-content additions.
+3. **Never place workflows under `apps/wordpress/.github/`.** GitHub doesn't run nested workflows. If any exist there, delete them.
+4. **Never push to `main` directly.** Stage gets validated first, then `stage → main` via PR.
+5. **Don't bypass the path filter** (e.g. removing `paths: 'apps/wordpress/**'`). Doing so means every README edit redeploys to Kinsta.
+
+## When to stop and ask the user
+
+- About to add a path under `apps/wordpress/` and unsure if the nested allow-list covers it → run `git check-ignore -v` first; if it points at the wildcard rule, you need a new `!` line.
+- A workflow run fails → diagnose, don't retry blindly. Common causes: missing secret, wrong port (`STG` vs `PROD`), SSH key not in Kinsta's allowlist, Kinsta-side bare repo missing.
+- Stage deploy works but production doesn't pick up → confirm `ENV_PROD_PORT` ≠ `ENV_STG_PORT` and both point at the correct Kinsta env.
+- About to delete, rename, or significantly rewrite `apps/wordpress/.gitignore` → stop.
+- About to change a workflow to push something other than `apps/wordpress/` → that's an architecture change; surface and confirm scope.