n-seo 0.2.0 → 0.3.0

package/.claude/skills/n-seo-add-site/SKILL.md

@@ -0,0 +1,125 @@
+---
+name: n-seo-add-site
+description: Add one site to an n-seo instance correctly — the Search Console property form, gscHost, the numeric GA4 id, a brand regex, and the two access grants. Use whenever someone wants a new site tracked.
+---
+
+# Add a site
+
+One entry in `n-seo.config.json`. There are no per-script site lists, so this
+is the only edit. `docs/ADDING-A-SITE.md` is the reference; this is the order
+to do it in.
+
+```sh
+E=<engine checkout>/bin/n-seo.mjs
+I=<instance dir>
+```
+
+## 1. Collect four facts
+
+Ask for whatever you cannot see, and do not guess any of them.
+
+**The property, exactly as Search Console shows it.** This is where most
+mistakes happen:
+
+| In Search Console | `gscProperty` |
+|---|---|
+| Domain property `example.com` | `sc-domain:example.com` |
+| URL-prefix property | `https://www.example.com/` — scheme and **trailing slash** included |
+
+**Whether the property covers more than this site.** A `sc-domain:` property
+covers every subdomain and both protocols. So:
+
+- One site on its own domain property → `gscHost` can be omitted.
+- Several sites sharing one domain property → every entry gets the **same**
+  `gscProperty` and a **different** `gscHost`. The pull happens once per
+  property; each site's rows are filtered by `gscHost` when read.
+- The site serves on `www` and the apex redirects → `gscHost` is
+  `www.example.com` even though `host` is `example.com`. Getting this wrong
+  means the probe and the metadata audit look at the wrong hostname and the
+  site silently shows no data.
+
+**The numeric GA4 property id.** GA4 → Admin → Property details → Property
+ID, nine or ten digits. It is **not** the `G-XXXXXXX` measurement id. Leave
+`ga4Property` empty for a site with no analytics; it will still be probed and
+pulled from Search Console.
+
+**A brand regex.** Case-insensitive, matching what people type when they mean
+this site by name, used for the branded/generic split on `/insights`. For
+`example.com` something like `example|exmpl`. Omit it only if the site has no
+brand terms — a site with a `gscProperty` and no `brand` counts **all** of
+its traffic as generic, which quietly skews that split.
+
+## 2. Add the entry
+
+Append to `sites` in `$I/n-seo.config.json`:
+
+```json
+{
+  "host": "docs.example.com",
+  "label": "docs",
+  "gscProperty": "sc-domain:example.com",
+  "gscHost": "docs.example.com",
+  "ga4Property": "987654321",
+  "brand": "example|exmpl",
+  "repo": "../example-docs",
+  "hosting": "GitHub Pages"
+}
+```
+
+`label`, `repo` and `hosting` are display-only. Keep the JSON valid — the
+dashboard falls back to the last good config and logs a parse error otherwise.
+
+## 3. Grant access to the service account
+
+Both consoles, using the service-account email (`node $E doctor --instance
+"$I"` prints it, or read `client_email` from the key file):
+
+- **Search Console** → the new property → Settings → Users and permissions →
+  Add user → **Full**.
+- **GA4** → Admin → Property access management → **Viewer**. If the service
+  account is already Viewer at the *account* level, a new property under that
+  account inherits it and there is nothing to do.
+
+On `metadata` auth the same grants apply to the runtime service account.
+
+If Search Console's Add-user dialog rejects a service-account address on a
+domain property, the fallback is the Site Verification API and a DNS TXT
+record, described in `docs/SETUP-GOOGLE.md`.
+
+## 4. Verify
+
+```sh
+node $E doctor --instance "$I"
+```
+
+The new property must appear under `search console` with a permission level,
+and its GA4 id must resolve. A missing property means the grant has not
+landed yet (give it a few minutes) or the property string does not match.
+
+Then let the next scheduled run pick it up, or run it now:
+
+```sh
+node $E daily --instance "$I"
+```
+
+## 5. Confirm it landed
+
+- The sites strip on `/` lists it.
+- `/site/<host>` exists and the probe pills render.
+- `/trends` shows it — a brand-new site gets a flat "no traffic recorded yet"
+  row rather than being silently absent, so an empty row is a connected site,
+  not a broken one.
+
+Zero rows from Search Console on a new site is correct, not a fault: there is
+no search history yet.
+
+## Optional: watch a page
+
+`watchPages` is a flat list of URLs whose numbers appear in every daily-log
+entry. Add pages you are about to change so the log tracks them.
+
+## Removing a site
+
+Delete the entry. Its `data/` stays until removed. Backlog items for that host
+in `config/backlog.json` still render on `/actions` — retire them with the
+Retire button or via `POST /api/backlog/<id>/retire`.

package/.claude/skills/n-seo-deploy/SKILL.md

@@ -0,0 +1,171 @@
+---
+name: n-seo-deploy
+description: Deploy n-seo to a host that is always on — a VPS, a NAS, or a GCE VM — with the dashboard reachable only through a tunnel and the static mirror behind sign-in. Use when someone wants n-seo off their laptop, running on a schedule, or asks how to host it.
+---
+
+# Deploy n-seo to an always-on host
+
+Read `docs/DEPLOY.md` for the reasoning. This is the procedure.
+
+## Rules you may not break
+
+1. **Never publish the dashboard's port to the internet, and never suggest
+   it.** It has write endpoints, and its Settings page sets the LLM command
+   the daily run executes — reaching it is running code on the host. Access
+   is a tunnel (IAP, `ssh -L`, Tailscale) or a proxy that authenticates
+   first. If the operator asks for a public dashboard, say what it exposes
+   and offer the mirror or the Caddy overlay instead.
+2. **Never print, echo, cat or commit a secret** — API keys, service-account
+   JSON, `.env` contents. Reference paths, not values.
+3. **Do not create paid cloud resources without explicit confirmation.** Run
+   `./setup.sh --dry-run` first and show the operator what it would create.
+4. **Do not invent gcloud flags.** If unsure, `gcloud <group> <cmd> --help`.
+
+## 1. Establish what they have
+
+Ask only what you cannot detect. Detect what you can:
+
+```sh
+command -v docker gcloud git node python3
+gcloud config get-value project 2>/dev/null
+uname -s
+```
+
+You need to know, in this order:
+
+- **Where should it run?** An existing Linux box they can SSH to, a new GCE
+  VM, or something else with Docker.
+- **Is this a fresh instance, or an existing one to move?** If moving, the
+  instance directory comes with them and step 4 becomes a copy, not an
+  `init`.
+- **Is the mirror wanted?** A read-only static copy others can see. Needs a
+  bucket plus something to serve it.
+- **On GCP already?** Decides `auth: "metadata"` (no key file) versus a
+  mounted key.
+
+## 2. Pick the shape
+
+| They said | Do |
+|---|---|
+| "I have a VPS / NAS / server" | `deploy/vm/startup.sh` on that box |
+| "We're on GCP" | `deploy/gcp/setup.sh`, then the VM steps |
+| "Cloud Run" | Explain why the engine cannot: `export_static.py` finishes with an atomic directory rename and GCS FUSE has none. Offer the VM, and Cloud Run for the mirror only. |
+| "Kubernetes" | Not scaffolded. The image and the volume contract are in `docker/README.md`; one Deployment plus one CronJob sharing a PVC is the shape. |
+
+## 3. Run the scaffolding
+
+**Any Linux box** (as root on that box):
+
+```sh
+curl -fsSLO https://raw.githubusercontent.com/en-dash-consulting/n-seo/main/deploy/vm/startup.sh
+sudo bash startup.sh
+```
+
+**GCP** (from a checkout, on their workstation):
+
+```sh
+gcloud config set project THEIR_PROJECT
+cd deploy/gcp
+./setup.sh --dry-run          # show them this output, get a yes
+./setup.sh
+```
+
+`setup.sh` creates the service account with Token Creator on itself, the
+private mirror bucket, a data disk, a VM with no external IP, an IAP-only
+firewall, and the Cloud Run mirror. It prints the manual steps at the end —
+keep them for step 6.
+
+## 4. The instance
+
+Fresh:
+
+```sh
+sudo -u n-seo /opt/n-seo/manage init
+sudo -u n-seo vi /srv/n-seo/instance/n-seo.config.json
+```
+
+Moving an existing one: copy the directory to `/srv/n-seo/instance`
+(excluding `data/`, which regenerates), keep ownership as the `n-seo` user,
+and confirm `n-seo.config.json`, `config/`, `content/` arrived.
+
+Config points to settle, in order of how often they are wrong:
+
+- `sites[]` — `gscProperty` is `sc-domain:example.com` for a domain property
+  or `https://example.com/` for a url-prefix one. `ga4Property` is the
+  numeric id from GA4 Admin → Property details, not the `G-` tag.
+- `google.auth` — `"metadata"` on GCP (no key). Anywhere else,
+  `"service-account-key"` with the key mounted read-only.
+- `modules.llm` — on a headless host the `claude -p` CLI usually is not
+  there. Use the HTTP path with `apiKeyEnv` and put the key in the
+  instance's `.env`, or leave the module off and accept no proposals or
+  briefings.
+- `modules.staticExport` plus an `afterRun` hook if they want the mirror.
+- `port` — leave it. The container publishes to loopback only.
+
+## 5. Verify, in this order
+
+```sh
+sudo -u n-seo /opt/n-seo/manage doctor
+sudo -u n-seo /opt/n-seo/manage daily --only probe    # no credentials needed
+sudo -u n-seo /opt/n-seo/manage daily                 # the real run
+sudo cat /srv/n-seo/instance/data/last-run.json       # failures should be ""
+```
+
+`doctor` failing on Search Console or GA4 before step 6 is expected — the
+console grants have not happened yet. Everything else should pass.
+
+Then confirm the dashboard, through a tunnel and never otherwise:
+
+```sh
+# GCP
+gcloud compute start-iap-tunnel n-seo 4600 --local-host-port=localhost:4600 --zone ZONE
+# anywhere
+ssh -N -L 4600:localhost:4600 user@host
+```
+
+```sh
+curl -s -o /dev/null -w '%{http_code}\n' http://localhost:4600/
+curl -s http://localhost:4600/api/actions | head -c 200
+```
+
+## 6. Hand over what only they can do
+
+These are console steps. List them explicitly; do not pretend they are done.
+
+1. **Search Console** → Settings → Users and permissions → add the service
+   account address with **Full**. If the UI rejects it on a domain property,
+   point them at `docs/SETUP-GOOGLE.md` for the DNS-verification route.
+2. **GA4** → Admin → Property access management → add the same address as
+   **Viewer**.
+3. **IAP members**, if the mirror is deployed:
+   ```sh
+   gcloud beta iap web add-iam-policy-binding \
+     --resource-type=cloud-run --service=n-seo-mirror --region=REGION \
+     --member='user:someone@example.com' \
+     --role='roles/iap.httpsResourceAccessor'
+   ```
+4. **Re-run `manage doctor`** once those land. It should be all green.
+
+## 7. Leave it healthy
+
+- Confirm the scheduler service is up: `sudo -u n-seo /opt/n-seo/manage ps`.
+  The daily time is `N_SEO_DAILY_AT` in `/srv/n-seo/.env` (default 07:00 in
+  the host's `TZ`).
+- Tell them where to look when it breaks: `/logs` on the dashboard,
+  `data/last-run.json`, `manage logs`.
+- Tell them the upgrade command: `sudo -u n-seo /opt/n-seo/manage upgrade`.
+- Recommend the instance live in its own git repo (`docs/INSTANCE.md`) —
+  that is the backup, and `gitAutoCommit` keeps it current.
+- If they want failure alerts on a server, `modules.notifications` is
+  macOS-only; offer the `afterRun` webhook hook in `docs/DEPLOY.md`.
+
+## Troubleshooting
+
+| Symptom | Cause |
+|---|---|
+| `doctor` says the metadata token was rejected | the SA lacks `roles/iam.serviceAccountTokenCreator` **on itself**; `setup.sh` grants it, re-run that binding |
+| Search Console 403 on every property | the SA was never added as a user in the console (step 6.1) |
+| GA4 returns no rows | `ga4Property` is the `G-` tag instead of the numeric property id |
+| Dashboard unreachable through the tunnel | container not up (`manage ps`), or the tunnel points at the wrong port |
+| Scan and digests produce nothing | `modules.llm` is off, or the CLI is missing on a headless host — use the HTTP path |
+| Mirror is empty | `staticExport` off, or the `afterRun` rsync hook missing or failing (check `data/last-run.json`) |

package/.claude/skills/n-seo-review/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: n-seo-review
+description: The weekly n-seo pass — what shipped, what moved, judge each watching item succeeded/failed/still cooking, retire what is done, refresh the insights briefing. Use for a weekly or monthly review.
+---
+
+# Weekly review
+
+The loop only closes here. Shipped work sits in *watching* until someone
+reads the data and says whether it worked.
+
+```sh
+E=<engine checkout>/bin/n-seo.mjs
+I=<instance dir>
+PORT=$(python3 -c "import json;print(json.load(open('$I/n-seo.config.json'))['port'])" 2>/dev/null || echo 4600)
+```
+
+Read the outputs; do not re-run the pipeline to review it.
+
+## 1. Gather
+
+```sh
+cat "$I/data/last-run.json"                       # were the runs healthy this week
+sed -n '/^## /,$p' "$I/docs/daily-log.md" | tail -120   # the week's entries
+curl -s "http://localhost:$PORT/api/actions"      # or MCP list_actions status=watching
+cat "$I/data/opportunity-proposals.json"          # verdicts + proposals
+```
+
+Also useful: MCP `trends_timeseries` for a page-level before/after, and
+`git log --oneline --since='1 week ago'` in each site repo for what actually
+shipped.
+
+## 2. Judge every watching item
+
+For each item with a `watching` note, find its page in the daily-log lines
+across the week and compare against the note's own success criterion — CTR,
+position, impressions, sessions, engagement, whichever the card named.
+
+Assign one of three, and write the evidence next to it:
+
+- **Succeeded** — the criterion is met. Say by how much.
+- **Failed** — the window has passed and the number did not move, or moved the
+  wrong way. Say what the data shows and propose the next move; a failed
+  metadata change is a candidate for a different angle, not a repeat.
+- **Still cooking** — the 28-day window has not closed, or impressions are too
+  thin to read. Leave it and note when to look again.
+
+The scan's own verdicts in `opportunity-proposals.json` are *review triggers*,
+not conclusions. Read them, then judge from the data yourself.
+
+Beware a page whose demand collapsed for reasons unrelated to the change —
+falling query volume in the trends file means the fix can be fine while the
+number still drops. Say that rather than scoring it failed.
+
+## 3. Retire what is done
+
+Only after it is judged succeeded, and only when there is nothing left to
+watch:
+
+```sh
+curl -sX POST "http://localhost:$PORT/api/backlog/<id>/retire"
+```
+
+For a *failed* item, do not retire it. Either update its `watching` note with
+what you learned and the next move, or replace it with a new card carrying
+that evidence.
+
+For rule-derived cards, remove or update the page's entry in `shippedWatch`
+in `$I/config/backlog.json` — dropping the entry lets the card return as
+active work if the underlying gap is still there, which is usually what you
+want after a failure.
+
+## 4. Sweep the rest
+
+- **Proposals** — present each with its evidence; accept the good ones
+  (Accept on `/actions`, or `POST /api/backlog/accept` with `index`) and say
+  plainly which you are ignoring and why. Never accept silently.
+- **Health** — probe regressions and index-coverage problems from the log.
+  Pages Google has never crawled are a different problem from pages nobody
+  searches for; the `/indexing` page separates them.
+- **Freezes expiring** — list pages whose 28-day window closes in the coming
+  week. Those are next week's metadata budget.
+- **Conversions** — if `conversions` is configured, whether events are
+  arriving (`conversions_status`).
+
+## 5. Refresh the briefing if the picture changed
+
+`$I/config/insights.json` is the hand-written narrative on `/insights`:
+`{ "date": "YYYY-MM-DD", "insights": [ { "title", "verdict", "body": [], "move" } ] }`
+with `verdict` one of `opportunity`, `warning`, `momentum`, `deprioritize`.
+
+Rewrite it only when the picture actually changed — a new rising cluster, a
+collapsing one, a bet that paid off. Update `date` when you do. Leave it alone
+in a quiet week rather than churning it.
+
+## 6. Write the summary
+
+Short, for the owner:
+
+- **Shipped this week** — what, and the verdict where the data allows one.
+- **Moved** — the numbers that changed, with the caveat where demand shifted.
+- **Next week** — the top few, with the metadata budget already applied.
+- **Needs you** — proposals to accept, approvals, anything blocked.
+
+Impact numbers order the queue; they are never reported as expected results.
+Recalibrate them against what you just observed if a card's estimate was
+clearly wrong.

package/.claude/skills/n-seo-setup/SKILL.md

@@ -0,0 +1,139 @@
+---
+name: n-seo-setup
+description: Take an n-seo install from a fresh clone to its first real daily run — config, Google service account, both console grants, doctor, first pull. Use when the dashboard is empty, doctor reports problems, or someone says they just cloned this.
+---
+
+# Setup — clone to first real run
+
+Goal: a green `doctor` and one completed `daily` run. Work top to bottom and
+stop at each **ASK** — those are the owner's decisions, not yours.
+
+Throughout, `E` is the engine and `I` is the instance:
+
+```sh
+E=<engine checkout>/bin/n-seo.mjs      # the directory holding src/ and bin/
+I=<instance dir>                        # in-place mode: the same directory
+node $E version --instance "$I"         # prints engine, instance, and mode
+```
+
+If `n-seo` is on PATH (`npm link` in the engine), `n-seo <cmd>` works instead.
+
+## 1. Establish the layout
+
+Run `node $E version --instance "$I"`. It prints `mode: in-place` or
+`mode: instance`.
+
+- **in-place** — the checkout is the instance. Config lives beside `src/`.
+- **instance** — config lives in a separate directory. If that directory is
+  empty, scaffold it: `node $E init "$I"`, which never overwrites.
+
+`docs/INSTANCE.md` in the engine explains the split if the owner asks.
+
+## 2. Offer the demo first when there is no Google access yet
+
+If the owner does not have a service account (or does not want to make one
+right now), do this before anything else so they see the tool working:
+
+```sh
+node $E demo  --instance "$I"      # synthetic dataset for the configured sites
+node $E start --instance "$I"      # dashboard on the configured port
+```
+
+Every page populates. Say plainly that this is synthetic data, that
+`node $E demo --instance "$I" -- --clean` removes it, and that the real setup
+resumes at step 3. **ASK** whether to continue to real data now.
+
+## 3. Write the config
+
+```sh
+cp <engine>/n-seo.config.example.json "$I/n-seo.config.json"
+```
+
+Fill in `sites` first. For each site the owner names, collect:
+
+| Field | Where it comes from |
+|---|---|
+| `host` | the canonical hostname |
+| `gscProperty` | Search Console, **exactly** as shown: `sc-domain:example.com` or `https://www.example.com/` with the trailing slash |
+| `gscHost` | only when the property covers more hosts than this site, or the site serves on `www` |
+| `ga4Property` | GA4 Admin → Property details → the numeric Property ID, not the `G-…` measurement id |
+| `brand` | a case-insensitive regex matching their branded queries |
+
+Use `/n-seo-add-site` for each site if there are several — it covers the
+domain-vs-URL-prefix and shared-property cases properly. Set `port` if 4600
+is taken.
+
+## 4. Service account and the two grants
+
+Full detail is `docs/SETUP-GOOGLE.md`; the shape is:
+
+1. A Google Cloud project with the Search Console API, Google Analytics Data
+   API and Google Analytics Admin API enabled.
+2. A service account with **no project roles**. Create a JSON key and store
+   it outside the repo:
+   ```sh
+   mkdir -p ~/.config/n-seo
+   mv ~/Downloads/<downloaded>.json ~/.config/n-seo/service-account.json
+   chmod 600 ~/.config/n-seo/service-account.json
+   ```
+   Point `google.serviceAccountKey` at that path.
+3. **Search Console** → property → Settings → Users and permissions → Add
+   user → the service-account email → **Full**.
+4. **GA4** → Admin → Property access management → Add users → the same email
+   → **Viewer**. Account-level Viewer covers every property under it.
+
+**ASK** before creating cloud resources or a key on the owner's behalf, and
+never paste a key's contents into the transcript. If the install runs on GCP,
+`google.auth: "metadata"` avoids the key file entirely — see
+`docs/SETUP-GOOGLE.md`.
+
+## 5. Doctor, and fix what it says
+
+```sh
+node $E doctor --instance "$I"
+```
+
+Work its output item by item; it names the fix for each. The common ones:
+
+- *key file not found* — wrong path in `serviceAccountKey`, or the file is
+  not readable by this user.
+- *a configured property is missing from the accessible list* — the grant in
+  step 4 has not landed. It can take a few minutes; if it never lands, the
+  property string does not match Search Console exactly.
+- *`no ga4Property`* — expected for sites you deliberately left without GA4.
+- *dashboard not running* — expected until step 7.
+
+Do not continue while a FAIL remains.
+
+## 6. First run
+
+Start narrow, then go wide:
+
+```sh
+node $E daily --instance "$I" --only probe        # no auth, proves the config's hosts
+node $E daily --instance "$I"                     # the full run
+cat "$I/data/last-run.json"                        # failures should be ""
+tail -20 "$I/docs/daily-log.md"                    # today's entry
+```
+
+The index-coverage sweep dominates the wall time; several minutes is normal.
+
+## 7. Dashboard, then scheduling
+
+```sh
+node $E start --instance "$I"
+```
+
+Open the configured port. Confirm the sites strip lists every configured site
+and the queue has cards.
+
+Then hand off scheduling. On this machine that is `docs/SCHEDULING.md` —
+launchd, cron, systemd, and the installer script under `ops/templates/`. If it
+should run on a server instead of a laptop, use `/n-seo-deploy`.
+
+## Rules
+
+- Never print or commit a key, a token, or a `.env` value.
+- Do not enable publishing modules (`indexNow`, `staticExport`,
+  `gitAutoCommit`) during setup. They belong to a deliberate decision later.
+- Read `docs/OPERATING-RULES.md` before recommending any change to a site.

package/.claude/skills/n-seo-ship/SKILL.md

@@ -0,0 +1,122 @@
+---
+name: n-seo-ship
+description: Implement one card from the n-seo queue in the site's own repo and record it as watching. Use when someone picks an action to do. Enforces the 28-day metadata freeze and the weekly batch limit.
+---
+
+# Ship one queue card
+
+One card, one branch, one PR, then record it. If the owner has not named a
+card, run `/n-seo-triage` first and let them choose.
+
+```sh
+E=<engine checkout>/bin/n-seo.mjs
+I=<instance dir>
+PORT=$(python3 -c "import json;print(json.load(open('$I/n-seo.config.json'))['port'])" 2>/dev/null || echo 4600)
+```
+
+## 1. Read the whole card
+
+```sh
+curl -s "http://localhost:$PORT/api/actions" | python3 -m json.tool
+```
+
+Or MCP `get_action` with a title substring. Use `spec` — it names the page,
+the target queries, the shape of the change and the success criterion. Note
+`id`, `host`, `tag` and whether it is rule-derived or curated (`source`).
+
+## 2. Freeze and batch check — STOP HERE IF EITHER FAILS
+
+Only for cards that change a title or meta description (`tag` of `metadata`
+or `ctr-gap`, or any card whose `how` rewrites metadata):
+
+1. **28-day freeze.** Look up the page in `shippedWatch` and in the dated
+   `watching` notes in `$I/config/backlog.json`. If its metadata changed
+   within 28 days, **stop and ask.** Say when the window opens. Iterating
+   inside it destroys the measurement the last change was making.
+2. **Weekly batch.** Count metadata changes already recorded this week across
+   every site. At roughly eight, **stop and ask** before adding another.
+
+Content additions, internal links, schema, and hygiene fixes are not metadata
+changes and are not limited by either rule — but a page inside its freeze
+still gets no title or description edit while you are in there.
+
+## 3. Work in the site's repo, never in the instance
+
+The site's code is in its own repository (`repo` on the site's page and in
+the config). The instance holds config and content only.
+
+```sh
+cd <site repo>
+git status --porcelain          # if dirty, use a worktree; never touch uncommitted work
+git checkout main && git pull
+git checkout -b seo-<short-slug>
+```
+
+If the checkout is dirty, `git worktree add ../<repo>-seo-<slug> -b seo-<slug>`
+and work there instead.
+
+Make exactly what the spec describes. For the common kinds:
+
+- **Metadata fix / CTR gap** — the `<title>` restates the ranking query as its
+  answer, front-loaded, under about 60 characters. The description is one
+  ~150-character sentence that answers the query directly. Metadata only.
+- **Striking distance ("push to page 1")** — a section that answers the target
+  queries verbatim: an H2 phrased as the query, then a 40–60 word direct
+  answer, then detail. Two or three internal links to the page from related
+  pages using the query as anchor text.
+- **Engagement mismatch** — rewrite the opening so it delivers what the click
+  promised; keep the URL.
+- **Hygiene** — robots.txt, sitemap, `llms.txt`, real 404s, unblocking AI
+  crawlers, server-rendering the shell. Verify with
+  `node $E daily --instance "$I" --only probe` after deploy.
+
+## 4. Verify before opening the PR
+
+Run whatever the site repo uses (build, tests, lint). Check the rendered page
+locally. Confirm the change is actually in the served HTML, not only in
+source — the metadata audit reads the live page.
+
+Push and open a PR whose description carries the card's evidence: the queries,
+the numbers, the success criterion. That description is how the next daily run
+gets attributed. Never push to `main` directly.
+
+## 5. Record it — the step people skip
+
+After it is merged and live:
+
+**Mark the card watching** with a dated note saying what changed and what you
+are waiting for:
+
+```sh
+curl -sX POST "http://localhost:$PORT/api/backlog/<id>/watch" \
+  --data-urlencode "note=title rewritten for the widgets cluster, frozen until <date>, watching CTR"
+```
+
+The endpoint prefixes today's date. Rule-derived cards have no backlog entry
+to write to — for those, add the page to `shippedWatch` in
+`$I/config/backlog.json` instead, with the same dated note, so the card shows
+as watching rather than reappearing as new work:
+
+```json
+"shippedWatch": {
+  "https://example.com/pricing": "2026-05-04: title rewritten, frozen until 2026-06-01, watching CTR"
+}
+```
+
+**Add the page to `watchPages`** in `n-seo.config.json` if it is not there, so
+its numbers appear in every daily-log entry.
+
+Do not delete the card. Shipped work becomes watching; deleting it is how the
+same page gets "fixed" again in six weeks by someone reading the same gap.
+
+## 6. Report
+
+Say what shipped, the PR link, the success criterion, and the date the freeze
+lifts. The next runs decide whether it worked.
+
+## Never
+
+- Never edit `config/backlog.json` except to add a `shippedWatch` entry or via
+  the accept / watch / retire endpoints.
+- Never touch a page inside its freeze window without the owner saying so.
+- Never commit a secret, and never push to a site's `main`.