n-seo 0.2.0 → 0.3.0

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

@@ -0,0 +1,90 @@
+---
+name: n-seo-triage
+description: Answer "what should I work on today" from an n-seo instance — the ranked queue, the last run, and the scan proposals, with the evidence and the operating rules applied. Use for any status or what-next question.
+---
+
+# Triage — what to do today
+
+Read the system's outputs. **Do not re-run pulls, re-crawl sites, or
+recompute trends to answer a status question** — the daily run already
+produced all of it, and a re-run spends quota to reproduce a file that exists.
+
+```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. Trust the data before you use it
+
+```sh
+cat "$I/data/last-run.json"        # ts, failures, per-step timing
+```
+
+Or the MCP `ops_status` tool, which adds dataset staleness and probe results.
+If `failures` is non-empty, **say so first** — the numbers below are stale in
+whatever the failing step feeds. `data/daily-ops.log` has the reason.
+
+## 2. Read the queue
+
+```sh
+curl -s "http://localhost:$PORT/api/actions"
+```
+
+Or MCP `list_actions` (`status: active`, optional `host`, `tag`, `limit`),
+which returns the same ranked list. If the dashboard is not running, start it
+(`node $E start --instance "$I"`) or read `config/backlog.json` plus the
+rule-derived cards from the MCP server.
+
+Each action carries `impact`, `effort`, `why` (the evidence), `how`, `spec`,
+`tag`, and `watching` when it has shipped. Ranking is impact ÷ effort weight.
+
+## 3. Read what happened lately
+
+```sh
+tail -30 "$I/docs/daily-log.md"                 # or MCP daily_log
+cat "$I/data/opportunity-proposals.json"        # or MCP opportunity_proposals
+```
+
+The log gives probe health, the watched pages' numbers, the conversions line
+and cross-referrals. The proposals file gives rising queries no card covers,
+machine proposals awaiting accept, and verdicts on watching items.
+
+## 4. Apply the rules before recommending
+
+- **28-day freeze.** A page whose title or description changed inside 28 days
+  is off limits for another metadata change. Check `shippedWatch` in
+  `config/backlog.json` and the dated `watching` notes for the page.
+- **≈8 metadata changes a week across all sites.** Count what has already
+  shipped this week from the recent `watching` notes before proposing more.
+  If the audit lists twenty, recommend the top few, not the list.
+- **Impact orders, it does not forecast.** Never present an impact number as
+  an expected result. "Ranked highest" not "will earn 60 clicks."
+- **Decisions ride the 90 days.** Cite the 90-day figures the cards use, not
+  16-month totals.
+- **Proposals are not queue items** until accepted.
+
+## 5. Answer
+
+Short, ranked, evidence attached. For each recommendation:
+
+- the move, in one line;
+- the numbers behind it, from the card's `why`;
+- why now (freeze expired, riser, regression, seasonal window);
+- what it costs (`effort`).
+
+Then, separately and briefly:
+
+- **Blocked or broken** — failing steps, probe regressions, index problems.
+- **Waiting on the owner** — scan proposals to accept or ignore, drafts whose
+  status contains `approval`.
+- **Watching** — shipped work whose window is closing, and what the data says
+  so far. Verdicts of *succeeded* or *failed* are review triggers; hand them
+  to `/n-seo-review` rather than acting on them here.
+
+## Stay inside the lines
+
+- Do not write to `config/backlog.json` here. Triage reads.
+- Do not draft comments for Hacker News or Reddit. The digests brief; the
+  human writes. Point at the briefing and stop.
+- Do not enable modules or change settings as part of answering.

package/.claude/skills/orient/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: orient
+description: Fast, cheap orientation for a fresh session on this n-seo install. Use FIRST in any new session here — reads current state from the running system instead of re-deriving it from raw data.
+---
+
+# Orient — get current in ~4 reads, not 40
+
+The system is self-updating; your job is to read its outputs, never to rebuild
+its conclusions. Procedure, in order — stop when you have what the task needs:
+
+1. **The queue is the truth for "what's next"**:
+   `curl -s http://localhost:4600/api/actions` (the port is `port` in
+   `n-seo.config.json`; the MCP `list_actions` tool returns the same).
+   Every active and watching action with evidence and spec.
+2. **What happened lately**: the last entry of `docs/daily-log.md` (probe
+   health, watched-page numbers, conversions line) and `data/last-run.json`
+   (did the last daily run succeed, which steps failed).
+3. **Machine-proposed work awaiting the owner**:
+   `data/opportunity-proposals.json` — proposals and verdicts from the scan.
+4. **Recent human decisions**: `git log --oneline -10` in this repo.
+
+## Do NOT (wastes tokens, re-derives what the batch already did)
+
+- Do not re-run pulls, audits, or trend analysis to answer status questions —
+  `ops/daily.py` refreshes everything on its schedule; its outputs are in
+  `data/` and `docs/daily-log.md`.
+- Do not re-audit sites or re-crawl pages the probe already covers.
+- Do not summarize the architecture from source — `docs/ARCHITECTURE.md` has it.
+- Do not restate history — `docs/daily-log.md` and `git log` hold it.
+
+## Rules live in CLAUDE.md — the ones people forget
+
+Queue edits only through accept/watch/retire or explicit approval · never
+generate comment text · 28-day title freeze + ≤8 metadata changes/week ·
+decisions ride the 90-day window · proposals never self-promote.
+
+## Then hand off to the right skill
+
+`n-seo-triage` for "what should I do today", `n-seo-ship` to implement one
+card, `n-seo-review` for the weekly pass, `n-seo-setup` and `n-seo-add-site`
+for configuration. `.claude/skills/README.md` says which skills are for
+operating an instance and which are for developing the engine.
+
+## If something is broken
+
+- Dashboard down: `npm start` in-place, or
+  `node <engine>/bin/n-seo.mjs start --instance <dir>` in engine+instance
+  mode, or if it runs as a service,
+  `launchctl kickstart -k gui/$(id -u)/n-seo.dashboard`.
+- Daily run failing: the Logs page (`/logs`) or `data/daily-ops.log`, then
+  `python3 ops/doctor.py`. 401/403 from Google means the service account
+  lost access or the key file moved — see `docs/SETUP-GOOGLE.md`.
+- Nothing on the dashboard: no run has happened yet — `python3 ops/daily.py`
+  (or `python3 ops/demo_data.py` to see it populated with synthetic data).

package/README.md

@@ -24,8 +24,10 @@ to **a model you choose**, and everything that changes a site is handed to you.
   ships with n-seo. Leave it off and you still get the full data-derived queue.
 - **Your coding agent, on the queue.** A read-only MCP server exposes the same
   data the dashboard reads, so Claude Code — or any MCP client — can answer
-  "what should I do first this week?" and then go implement it. Six skills ship
-  with it, so the operating rules are enforced rather than merely documented.
+  "what should I do first this week?" and then go implement it. Seven skills
+  are installed into your instance, so setup, triage and shipping are things
+  you ask for in plain language, with the operating rules enforced rather than
+  merely documented.
 - **It proposes; it never acts.** No module edits a site, sends an email or
   posts a comment. Machine proposals wait in a holding area until you accept
   them. Your data stays on your hardware: nothing leaves the host except the
@@ -35,11 +37,61 @@ to **a model you choose**, and everything that changes a site is handed to you.
 
 ## Quickstart (5 minutes, no Google setup)
 
+> **n-seo is its own project — do not install it inside a website's repo.**
+> It reads your sites the way Google sees them, through the Search Console and
+> GA4 APIs, so it never needs a copy of their code. `n-seo init` makes one
+> directory of its own and everything it writes stays there.
+
+**✗ Inside a site's repo** — what people do by accident:
+
+```
+~/code/my-website/
+├── .git/
+├── package.json
+├── src/
+└── my-sites/               ← init ran here
+    ├── n-seo.config.json   committed to your website
+    ├── config/backlog.json committed
+    ├── .env                committed
+    └── data/               rewritten every morning,
+                            committed, then deployed
+```
+
+**✓ Beside it** — one instance, watching every site you own:
+
+```
+~/
+├── code/
+│   ├── my-website/         untouched
+│   └── docs-site/          untouched
+└── my-sites/               ← n-seo init my-sites
+    ├── n-seo.config.json   lists both sites
+    ├── config/backlog.json your action queue
+    ├── content/            drafts, campaigns
+    ├── .claude/skills/     ask, don't read docs
+    └── data/               gitignored, regenerable
+```
+
+`n-seo init` refuses the first layout: it stops when the target holds a
+`package.json`, or when the directory it would create falls inside a git
+repository that is not itself an instance, and prints the command you wanted
+instead. `--force` overrides it.
+
+**What it touches.** Your site repos: never — when you ship a fix it is you,
+in your repo, on a branch. Google's APIs: read-only, through a service account
+you create. Its own directory: everything it writes. Delete that directory and
+nothing else on your machine changes.
+
 ```sh
-npm install -g n-seo
-n-seo init my-sites && cd my-sites
-n-seo demo          # a synthetic dataset for example.com
-n-seo start         # dashboard → http://localhost:4600
+npm install -g n-seo   # the engine, once — a CLI, not a dependency
+
+cd ~                   # stand somewhere that is NOT a site repo
+n-seo init my-sites    # creates ./my-sites: config, queue, content,
+cd my-sites            #   .mcp.json and seven skills
+
+n-seo demo             # synthetic data, so every page has something
+n-seo start            # the dashboard, reading this directory
+                       #   → http://localhost:4600
 ```
 
 Open http://localhost:4600. Every page is populated from the demo data, so you
@@ -48,6 +100,29 @@ removes it.
 
 Prefer not to install globally? `npx n-seo init my-sites` works the same way.
 
+### Then talk to it
+
+`n-seo init` installs seven skills into the new directory, so the rest of the
+setup is a conversation rather than a docs crawl. Open it in Claude Code — or
+any agent that reads `.claude/skills/` — and say what you want:
+
+```
+cd my-sites && claude
+
+  "set this up for my sites"        → /n-seo-setup: config, the Google service
+                                      account, both console grants, first run
+  "add learn-pretext.com"           → /n-seo-add-site
+  "what should I work on today?"    → /n-seo-triage: the queue, with evidence
+  "do the first one"                → /n-seo-ship: a branch and a PR in the
+                                      site's own repo, freeze rules enforced
+  "how did last month go?"          → /n-seo-review
+```
+
+A read-only MCP server is registered in the generated `.mcp.json`, so the agent
+reads the same queue and metrics the dashboard shows. It can propose and
+implement; it cannot publish, post, or change a site behind your back. Details
+in [Agentic by design](#agentic-by-design).
+
 <details>
 <summary>Or run it from a clone, if you want to change the engine itself</summary>
 
@@ -59,10 +134,11 @@ npm run demo
 npm start
 ```
 
-In this mode the config, queue and data live inside the checkout. That is the
-right shape for hacking on n-seo; for running it, the instance layout above
-keeps your files separate from the engine so upgrades are a reinstall rather
-than a merge. See [docs/INSTANCE.md](docs/INSTANCE.md).
+In this mode the config, queue and data live inside the checkout — still a
+standalone project of its own, just one you can edit. That is the right shape
+for hacking on n-seo; for running it, the instance layout above keeps your
+files separate from the engine so upgrades are a reinstall rather than a
+merge. See [docs/INSTANCE.md](docs/INSTANCE.md).
 </details>
 
 ## Connect your real sites
@@ -149,8 +225,10 @@ Desktop, stdio and authenticated HTTP clients are covered in
 working here has to follow.
 
 Skills ship for the work itself, so the rules are enforced rather than
-merely documented — six that operate an instance, plus `orient` to get
-current in a fresh session:
+merely documented. `n-seo init` copies all seven into the instance's
+`.claude/skills/` with this install's real paths substituted in, alongside a
+`CLAUDE.md` carrying the operating rules — so an agent opened in that
+directory is oriented before you type anything:
 
 | Skill | Use it when |
 |---|---|
@@ -163,9 +241,9 @@ current in a fresh session:
 | `orient` | First thing in a fresh session — get current in a few reads |
 
 `n-seo-ship` stops rather than crossing the 28-day title freeze or the weekly
-metadata budget. `.claude/skills/README.md` explains which skills operate an
-instance and which are contributor tooling for developing the engine with
-[n-dx](https://n-dx.dev).
+metadata budget. The engine checkout carries a second set of skills (`ndx-*`)
+for developing n-seo itself with [n-dx](https://n-dx.dev); those are not
+copied into an instance. `.claude/skills/README.md` explains the split.
 
 Read-only is the point: an agent can reason over your search data all day and
 still cannot bypass the freeze, the batching, or you.

package/bin/n-seo.mjs

@@ -28,7 +28,9 @@ const USAGE = `n-seo ${PKG.version} — an SEO on your machine
 
 usage: n-seo <command> [--instance <dir>] [args...]
 
-  init [dir]      scaffold an instance directory (default: cwd); never overwrites
+  init [dir]      scaffold a standalone instance directory (default: cwd); never
+                  overwrites, and refuses to scaffold inside a website's repo
+                  (--force overrides)
   start           run the dashboard for the instance
   dev             dashboard with reload on engine code changes
   daily           the morning run (args pass through: --only, --skip, --list, …)
@@ -142,8 +144,87 @@ function missingDeps(cmd, what) {
 
 /* ---------- init ---------- */
 
-function init(dirArg) {
+/** Files that mean "this directory is an application", not a place to keep
+ *  search-ops files. n-seo is a standalone project: it writes a config, a
+ *  queue, drafts and a data/ tree that the daily run rewrites every morning.
+ *  Dropped into a website's repo those files get committed, deployed, and
+ *  eventually served — and `n-seo upgrade` starts fighting the site's own
+ *  package.json. The instance sits beside the sites it watches, never inside
+ *  one. */
+const APP_MARKERS = [
+  "package.json", "index.html", "next.config.js", "next.config.mjs", "next.config.ts",
+  "vite.config.js", "vite.config.ts", "astro.config.mjs", "nuxt.config.ts",
+  "svelte.config.js", "gatsby-config.js", "remix.config.js", "angular.json",
+  "Gemfile", "go.mod", "Cargo.toml", "pyproject.toml", "composer.json",
+  "hugo.toml", "config.toml", "_config.yml", "wp-config.php", "Dockerfile",
+];
+
+/** The nearest ancestor holding a .git, or null. */
+function gitRootOf(dir) {
+  let cur = path.resolve(dir);
+  for (;;) {
+    if (fs.existsSync(path.join(cur, ".git"))) return cur;
+    const up = path.dirname(cur);
+    if (up === cur) return null;
+    cur = up;
+  }
+}
+
+/** Why this directory is the wrong place for an instance, or null if it is
+ *  fine.
+ *
+ *  `forChild` means the instance will be a NEW directory created inside
+ *  `dir`, which changes one answer: a repository root is a fine place to put
+ *  an instance (it becomes its own repo) but a terrible parent for one (the
+ *  new directory lands inside that repo's working tree).
+ *
+ *  Re-running init on an existing instance is always allowed. */
+function wrongPlaceFor(dir, forChild = false) {
+  if (fs.existsSync(path.join(dir, "n-seo.config.json"))) return null;
+  // In-place mode: the engine checkout is the instance. It has a package.json
+  // and a .git of its own, both of which would otherwise trip every check.
+  if (!forChild && path.resolve(dir) === ROOT) return null;
+  const marker = APP_MARKERS.find((f) => fs.existsSync(path.join(dir, f)));
+  if (marker) {
+    return forChild
+      ? `${dir} contains ${marker} — an instance created here would sit inside an application`
+      : `${dir} contains ${marker} — that is an application, not an n-seo instance`;
+  }
+  const root = gitRootOf(dir);
+  const insideSomeoneElsesRepo = root && (forChild || root !== path.resolve(dir));
+  if (insideSomeoneElsesRepo && !fs.existsSync(path.join(root, "n-seo.config.json"))) {
+    return `${dir} is inside the git repository at ${root} — the instance would be committed to it`;
+  }
+  return null;
+}
+
+function init(dirArg, force = false) {
   const dir = path.resolve(dirArg ?? process.cwd());
+  // A directory that does not exist yet inherits its parent's problem: a new
+  // folder created inside a site repo is still inside that site repo.
+  const wrong = fs.existsSync(dir) ? wrongPlaceFor(dir) : wrongPlaceFor(path.dirname(dir), true);
+  if (wrong && !force) {
+    console.error(`n-seo init: refusing to scaffold here.
+
+  ${wrong}
+
+n-seo is a standalone project, not something you add to a website. It keeps a
+config, an action queue, content drafts and a data/ tree that the daily run
+rewrites every morning; inside a site repo those get committed and deployed.
+The instance watches your sites over the Search Console API — it never needs
+to live in their code.
+
+Do this instead:
+
+  cd ~            # anywhere outside your site repos
+  n-seo init my-sites
+  cd my-sites
+
+Then list the sites you own in my-sites/n-seo.config.json.
+
+If you really mean it here, pass --force.`);
+    return 2;
+  }
   fs.mkdirSync(dir, { recursive: true });
   const name = path.basename(dir);
   const put = (rel, content) => {
@@ -170,6 +251,59 @@ function init(dirArg) {
     const src = path.join(ROOT, rel);
     put(rel, fs.existsSync(src) ? fs.readFileSync(src, "utf8") : `# ${rel}\n`);
   }
+  // The skills are the product's front door: with them in place the instance
+  // is a directory an agent can be pointed at, and setup / triage / shipping
+  // become a conversation instead of a docs-reading exercise. The engine's
+  // own contributor skills (ndx-*) stay behind — they are for working on
+  // n-seo, not with it. Placeholders become this install's real paths so the
+  // commands in them are copy-pasteable.
+  const INSTANCE_SKILLS = ["orient", "n-seo-setup", "n-seo-add-site", "n-seo-triage", "n-seo-ship", "n-seo-review", "n-seo-deploy"];
+  let skillsCopied = 0;
+  for (const skill of INSTANCE_SKILLS) {
+    const src = path.join(ROOT, ".claude", "skills", skill, "SKILL.md");
+    if (!fs.existsSync(src)) continue;
+    const body = fs
+      .readFileSync(src, "utf8")
+      .replaceAll("<engine checkout>/bin/n-seo.mjs", path.join(ROOT, "bin", "n-seo.mjs"))
+      .replaceAll("<instance dir>", dir);
+    put(path.join(".claude", "skills", skill, "SKILL.md"), body);
+    skillsCopied++;
+  }
+
+  put("CLAUDE.md", `# ${name} — an n-seo instance
+
+This directory is an n-seo instance: config, the curated action queue, content
+drafts, and the data the daily run writes. It is **not** a website. The sites
+it watches live in their own repositories and are read over the Search Console
+and GA4 APIs.
+
+Engine (the code): ${ROOT}
+Docs: ${path.join(ROOT, "docs")}
+
+## Working here
+
+Skills in \`.claude/skills/\` cover the routine work — start with
+\`/orient\` in a fresh session, then \`/n-seo-triage\` for what to do today,
+\`/n-seo-ship\` to implement one card, \`/n-seo-review\` for the weekly pass.
+
+## Rules that are not negotiable
+
+- **28-day metadata freeze.** After a page's title or description changes,
+  leave that page's metadata alone for 28 days. Title churn reads as
+  manipulation and resets Google's evaluation.
+- **At most ~8 title/description changes a week** across all sites.
+- **Impact numbers order the queue. They are not forecasts.** Never report
+  one as an expected result.
+- **Decisions ride the trailing 90 days.** The 16-month data is for totals
+  and history only.
+- **Shipped work becomes \`watching\`, never deleted** — that is how the loop
+  closes.
+- **Machine proposals never self-promote.** They wait in the holding area on
+  /actions until a human accepts them.
+- **Site changes ship as branches and pull requests** in the site's own repo,
+  never committed straight to its main branch.
+`);
+
   const envExample = path.join(ROOT, ".env.example");
   put(".env", fs.existsSync(envExample) ? fs.readFileSync(envExample, "utf8") : "");
   put(".gitignore", "data/\nsite/\n.env\n__pycache__/\nnode_modules/\n");
@@ -203,15 +337,38 @@ n-seo upgrade         # update the engine; your files here are untouched
 
 Edit \`n-seo.config.json\` for sites, Google access, modules and hooks.
 Docs: ${path.join(ROOT, "docs")}
+
+## Or just ask
+
+n-seo is built to be driven by an AI agent. Open this directory in Claude Code
+(or any agent that reads \`.claude/skills/\`) and talk to it:
+
+    "set this up for my sites"      → /n-seo-setup
+    "what should I work on today?"  → /n-seo-triage
+    "do the first one"              → /n-seo-ship
+    "how did last month go?"        → /n-seo-review
+
+A read-only MCP server is wired up in \`.mcp.json\`, so the agent reads the
+same queue and metrics the dashboard shows. It can propose and implement;
+it cannot publish, post, or change your sites behind your back.
 `);
   console.log(`
 instance ready at ${dir}
+  a standalone project — your websites stay in their own repos, untouched
 
 next:
   cd ${dir}
-  edit n-seo.config.json      (sites, google.serviceAccountKey — see ${path.join(ROOT, "docs", "SETUP-GOOGLE.md")})
-  n-seo doctor
-  n-seo demo && n-seo start   (or n-seo daily once the key is in place)
+  n-seo demo && n-seo start   see the dashboard working on synthetic data
+  edit n-seo.config.json      your sites + google.serviceAccountKey
+  n-seo doctor                checks the setup and names what is missing
+
+or hand it to an agent — ${skillsCopied} skills are installed in .claude/skills/:
+  cd ${dir} && claude
+  "set this up for my sites"  → /n-seo-setup walks the whole thing, including
+                                the Google service account and both grants
+  later: "what should I work on today?" → /n-seo-triage
+
+setup guide: ${path.join(ROOT, "docs", "SETUP-GOOGLE.md")}
 `);
   return 0;
 }
@@ -264,7 +421,7 @@ let code = 0;
 
 switch (cmd) {
   case "init":
-    code = init(rest[0] ?? flag ?? process.cwd());
+    code = init(rest.find((a) => !a.startsWith("-")) ?? flag ?? process.cwd(), rest.includes("--force"));
     break;
   case "start":
   case "dev":

package/docs/ADDING-A-SITE.md

@@ -3,6 +3,10 @@
 One entry in `n-seo.config.json`. There are no per-script site lists:
 every pull, probe, audit, page and export reads the same `sites` array.
 
+> Or say *"add example.com"* in the instance directory: the `n-seo-add-site`
+> skill picks the right property form, finds the numeric GA4 id, proposes a
+> brand regex, and reminds you about both access grants.
+
 ```json
 {
   "host": "docs.example.com",

package/docs/DEPLOY.md

@@ -7,6 +7,10 @@ it sleeps, it travels, and the run silently skips a day.
 
 This document is about moving it to a box that is always on.
 
+> Or say *"get this off my laptop"* in the instance directory — the
+> `n-seo-deploy` skill runs this procedure, and refuses to expose the
+> dashboard port to the internet whatever you ask it for.
+
 ## The shape
 
 One host runs two long-lived things — the dashboard and a scheduler that

package/docs/FAQ.md

@@ -5,6 +5,25 @@ Nothing. The Search Console and GA4 APIs are free within quotas that ordinary
 use never approaches. The optional LLM module runs whatever local command you
 give it; if that is a paid CLI, that is your cost, not the tool's.
 
+**Can I install it inside my website's repository?**
+No — and `n-seo init` refuses to, so you cannot do it by accident. n-seo is a
+standalone project. It writes a config, an action queue, content drafts and a
+`data/` tree that the daily run rewrites every morning; inside a site repo all
+of that gets committed, and usually deployed. It reads your sites through the
+Search Console and GA4 APIs, so it has no reason to sit in their code. Put the
+instance anywhere else — `~/my-sites` is fine — and list the sites you own in
+its config. One instance can watch as many sites as you like. `--force`
+overrides the check if you have a reason.
+
+**Do I have to read all these docs?**
+No. `n-seo init` installs seven skills into your instance, so setup and daily
+use are a conversation: open the directory in Claude Code (or any agent that
+reads `.claude/skills/`) and say "set this up for my sites", "what should I
+work on today?", "do the first one". The agent reads the queue over a
+read-only MCP server, follows the operating rules in the generated
+`CLAUDE.md`, and cannot publish or change a site on its own. The docs are the
+reference behind the skills, not a prerequisite.
+
 **Does it change my site?**
 No. It reads your data, probes your pages, and produces a queue of actions
 with evidence and specs. You make the change in your own repo and ship it.
@@ -89,9 +108,19 @@ shown flat rather than omitted so you can tell "connected and quiet" from
 "missing from the pipeline."
 
 **The indexing page lists a "Soft 404" for a page that is fine.**
-Check the "last crawled" column. A verdict is only as current as the crawl
-behind it; the page flags verdicts older than 90 days as stale. Request
-indexing and re-check rather than chasing a template bug.
+Check the "last crawled" column first. A verdict is only as current as the
+crawl behind it, and the page flags verdicts older than 90 days as stale — a
+page rewritten since then is being judged on content Google has not seen. For
+a stale verdict, request indexing once and let the recrawl settle it.
+
+For a *fresh* soft 404, requesting indexing is the wrong move: Google already
+fetched the page, got a 200, and decided the content was an error or empty.
+Asking again re-runs the same judgement and spends the daily quota. Fetch the
+URL yourself and pick the real cause — the page renders its content in
+JavaScript and the crawler saw an empty shell, or it is genuinely thin, or it
+is an error page returning 200 and should return 404 or 410 and leave the
+sitemap. Fix that, then request indexing. n-seo's indexing page names the
+check to run for each verdict.
 
 **A daily step failed. What now?**
 Open `/logs` (or `data/daily-ops.log`), then run `n-seo doctor`. A 401

package/docs/INSTANCE.md

@@ -1,5 +1,29 @@
 # Running n-seo as an engine + instance
 
+> **An instance is a standalone project.** It is never a subdirectory of a
+> website you are optimising. n-seo reads your sites through the Search
+> Console and GA4 APIs; it has no reason to live in their code, and living
+> there means committing and deploying its config, its queue and a `data/`
+> tree that is rewritten every morning.
+
+```
+~/
+├── code/
+│   ├── my-website/         a site you own — untouched
+│   └── docs-site/          another one — untouched
+└── my-sites/               the instance
+    ├── n-seo.config.json   both sites listed here
+    ├── config/backlog.json the curated queue
+    ├── content/            drafts, campaigns
+    ├── .claude/skills/     the operating skills
+    ├── CLAUDE.md           the operating rules
+    └── data/               the daily run's output, gitignored
+```
+
+One instance watches as many sites as you own, and `n-seo init` refuses to
+scaffold into an application directory or a git repository it does not own
+(`--force` overrides).
+
 n-seo can run two ways. In the simplest, you clone the repo, put your config
 in the checkout and run it there. In the second, the checkout is an **engine**
 you never edit, and everything that is yours — config, queue, content, data,
@@ -93,6 +117,36 @@ and `content/campaigns/README.md`, `.env` (from `.env.example`), a
 `.gitignore` that excludes `data/`, `site/` and `.env`, a `.mcp.json` that
 spawns the engine's MCP server with `N_SEO_INSTANCE` set, and a short README.
 
+It also makes the instance agent-ready, which is how most people should drive
+it:
+
+- `.claude/skills/` — the seven operating skills (`orient`, `n-seo-setup`,
+  `n-seo-add-site`, `n-seo-triage`, `n-seo-ship`, `n-seo-review`,
+  `n-seo-deploy`), copied from the engine with this install's real engine and
+  instance paths substituted in, so every command in them is copy-pasteable.
+  The engine's contributor skills (`ndx-*`) are not copied — they are for
+  developing n-seo, not operating it.
+- `CLAUDE.md` — the operating rules an agent working in this directory has to
+  follow: the 28-day freeze, the weekly metadata budget, impact-is-not-a-
+  forecast, decisions on the 90-day window, shipped-becomes-watching,
+  proposals never self-promote, site changes ship as pull requests.
+
+With those two files plus `.mcp.json`, opening the instance in Claude Code is
+enough: it can read the queue and the metrics, and it already knows the rules.
+
+```sh
+cd ~/sites/search-ops && claude
+  "set this up for my sites"        → /n-seo-setup
+  "what should I work on today?"    → /n-seo-triage
+  "do the first one"                → /n-seo-ship
+  "how did last month go?"          → /n-seo-review
+```
+
+Both files are yours once written. `n-seo init` never overwrites, so editing
+`CLAUDE.md` to add your own rules survives every re-run and every engine
+upgrade. To pick up improved skills from a newer engine, delete the ones you
+have not customised and re-run `n-seo init`.
+
 To make `n-seo` a command, link the engine once:
 
 ```sh