# Handover: [yoursite.com]

Read this first in any new chat before touching the site. It explains how the site is wired, what can and cannot be changed remotely, and where the traps are.

Template by Orit Mutznik. Full walkthrough: https://www.oritmutznik.com/ai-workflows/wordpress-vibe-coding-101-no-mcp-skill

Last updated: [date]

---

## 1. The site

| | |
|---|---|
| URL | [https://www.yoursite.com] (canonicalises to [www / non-www]) |
| Host | [host, web server, caching plugins] |
| WordPress | [version installed] |
| Theme | [theme name], a [block / classic] theme, live v[x.y.z] |
| Front page | [latest posts / static page] |
| Content | [x published posts, y drafts, z pages] |

Plugins that matter: [SEO plugin, security plugin, caching plugin, forms, anything that changes output]

---

## 2. How to get access

Credentials live in `[filename].md` in this folder: WordPress username plus an **application password**, not the real login password.

Use it as HTTP basic auth against the REST API:

```bash
curl -u "USERNAME:APP PASSWORD" "https://www.yoursite.com/wp-json/wp/v2/users/me?context=edit"
```

You want your own name back, with `"roles":["administrator"]`.

If it stops working, generate a new one at **Users, then Profile, then Application Passwords**.

**Gotcha to check first:** Security plugins often disable application passwords. In Wordfence the setting is at **Wordfence, All Options, Brute Force Protection**, then untick "Disable WordPress application passwords". It is not under Login Security, whatever the error message says.

---

## 3. What can be changed remotely, and what cannot

This is the single most important section. Fill it in for your own site.

### Writable over the REST API, takes effect immediately

| Thing | Endpoint |
|---|---|
| Posts, pages, drafts | `/wp/v2/posts`, `/wp/v2/pages` |
| Media uploads | `/wp/v2/media` |
| Templates | `/wp/v2/templates/[theme]//<slug>` |
| Template parts | `/wp/v2/template-parts/[theme]//<slug>` |
| Global styles and custom CSS | `/wp/v2/global-styles/[id]` |
| Navigation menu | `/wp/v2/navigation/[id]` |
| Site title, tagline, reading settings | `/wp/v2/settings` |
| Per-post SEO fields | `meta` on `/wp/v2/posts/<id>` |

POST, not PUT, to the single-item routes to update.

### Not writable, needs a theme zip upload

- Anything in a theme file: `functions.php`, `style.css`, `theme.json`, patterns, and everything in `assets/`
- Favicons in particular. They look like a setting and they are a theme file.

### Not writable, needs the wp-admin UI

- [Global SEO plugin settings, and anything else a plugin keeps to itself]

---

## 4. The two-layer trap

Block themes store changes in two places:

1. **Theme files**, deployed as a zip
2. **Database overrides**, from the Site Editor or the REST API

**Database overrides always win.** A template can look one way in the files and another way live.

Current overrides on this site: [list them, or "none known"]

To clear one: **Site Editor, Templates, the three dots, Reset.**

---

## 5. Deploying a theme change

1. Edit files in `[local theme folder]`
2. Bump `Version:` in `style.css`
3. Zip the theme folder, excluding `.DS_Store`
4. **Appearance, Themes, Add New, Upload Theme,** pick the zip, Install, Replace current with uploaded
5. Purge the cache

Current build, deployed and live: **[filename.zip]**

**Check the installed version before assuming the local folder matches it.**

---

## 6. Traps that have already cost time

Write each one down the first time it costs you an hour. Format: What happened, how it was diagnosed, what fixed it.

- [Trap 1]
- [Trap 2]
- [Trap 3]

Worth checking for on most sites:

- **CSS pseudo-elements are invisible to HTML searches.** If something is visible on the page and absent from the source, check `::before` and `::after` before blaming the cache.
- **Caching plugins disagree with `curl` and with logged-in views.** Verify a saved setting by reading the stored option, rather than the rendered page.
- **Inline block styles beat stylesheet rules.** Edit the block attribute where you can, instead of fighting it with `!important`.

---

## 7. SEO configuration as it stands

- Title templates: [as set]
- Site representation: [Person / Organisation]
- Schema handled outside the plugin UI: [any filters in `functions.php`]
- Sitemap: [which one is live]
- Known gaps: [empty meta descriptions, missing bio, anything outstanding]

---

## 8. Design system

Fonts: [names and where they are hosted]

| Token | Hex |
|---|---|
| [name] | `#000000` |

Layout: content [x]px, wide [y]px.

---

## 9. Known issues worth fixing

- [Issue, with the fix and who has to do it]

---

## 10. House rules

- [Writing style rules, spelling conventions, formatting rules]
- [Anything a new chat should never do without asking]

---

## 11. Where the last session left off

[What was done, what was verified, what is still outstanding. Update this every time.]