n-seo 0.1.0

package/docs/ARCHITECTURE.md

@@ -0,0 +1,213 @@
+# Architecture
+
+n-seo is a local-first control plane for organic growth across one or
+more websites: **SEO** (classic search), **AEO** (answer engines: featured
+snippets, AI Overviews) and **GEO** (being cited by ChatGPT, Claude,
+Perplexity). It runs on a machine you control, keeps all data in local JSON files, and
+turns them into a ranked queue of concrete actions.
+
+```
+                    ┌──────────── daily run (ops/daily.py) ────────────┐
+   Search Console ──┤ ingest/pull_gsc.py         → data/gsc/…          │
+   GA4 ─────────────┤ ingest/pull_ga4.py         → data/ga4/…          │
+   your live sites ─┤ probes/site_probe.py       → data/probes/…       │
+                    │ ingest/pull_timeseries.py  → data/timeseries/…   │
+                    │ ingest/analyze_metadata.py → data/metadata-audit.json
+                    │ ingest/pull_index_status.py→ data/index-status.json
+                    │ ops/opportunity_scan.py    → data/trends-*.json, data/opportunity-proposals.json
+                    │ ops/daily_diff.py          → docs/daily-log.md   │
+                    │ ops/hn_digest.py (opt-in)  → data/hn-digest.json │
+                    │ ops/reddit_digest.py (opt) → data/reddit-digest.json
+                    │ ops/export_static.py (opt) → site/               │
+                    │ ops/publish.py (opt)       → your bucket/host    │
+                    └─────────────────────────────────────────────────┘
+                                          │
+                       dashboard (src/server.tsx, Hono + hono/jsx SSR)
+                       reads data/ + config/ + content/ on every request
+                                          │
+                       MCP server (src/mcp.ts) — the same data for agents
+```
+
+## One config file
+
+`n-seo.config.json` (copy from `n-seo.config.example.json`; path
+overridable with `$N_SEO_CONFIG`) is read by the TypeScript app
+(`src/config.ts`) **and** every Python script (`ingest/seo_config.py`). If
+the file does not exist, both fall back to the example so a fresh checkout
+can run the demo. Nothing else carries a site list.
+
+| Key | Meaning |
+|---|---|
+| `name` | Shown in the dashboard header |
+| `port` | Dashboard port (env `SEO_PORT` overrides) |
+| `google.auth` | `service-account-key` (default) · `gcloud-impersonate` · `gcloud-user` |
+| `google.serviceAccountKey` | Path to the SA JSON key (`~` ok). `$GOOGLE_APPLICATION_CREDENTIALS` also works |
+| `google.impersonate` | SA email for the impersonation mode |
+| `sites[]` | `host`, `label`, `gscProperty` (`sc-domain:x` or `https://x/`), `gscHost` (page-URL host filter; defaults to host), `ga4Property` (numeric id), `brand` (regex for branded queries), `repo`, `hosting` |
+| `watchPages[]` | URLs whose GSC numbers the daily log reports every day |
+| `conversions` | `{ site, events[], sourceDimension }` — GA4 key events that are your real goal (signups, leads). Optional |
+| `participation.expertise` | Who you are / what you know first-hand. The only context the digest briefings get |
+| `modules.<key>.enabled` | See "Modules" |
+
+Derived helpers (identical in both languages): `gscSlug(property)` strips
+`sc-domain:` / the scheme and the trailing slash and maps `/`→`_`;
+`gscDataSlug(property)` is the `data/gsc/<slug>/` directory name — the same,
+plus a `-urlprefix` suffix for url-prefix (`https://…`) properties so they
+never share a directory with the domain property of the same host
+(`sc-domain:example.com` → `example.com`, `https://www.example.com/` →
+`www.example.com-urlprefix`).
+
+## Data files (all under `data/`, gitignored, regenerable)
+
+| Path | Written by | Shape |
+|---|---|---|
+| `gsc/<slug>/{queries,pages,query_page,dates}.json` | pull_gsc.py | `{site, dimensions, startDate, endDate, rowCount, rows:[{keys[], clicks, impressions, ctr, position}]}` — 16-month window |
+| `gsc/<slug>/{queries,pages,query_page}_90d.json` | pull_gsc.py | same, trailing 90 days (**the decision window**) |
+| `ga4/<host>/daily.json` | pull_ga4.py | raw GA4 runReport: dims `[date]`, mets `[sessions,totalUsers]`, 90d |
+| `ga4/<host>/sources.json` | pull_ga4.py | dims `[sessionSource, sessionMedium]`, mets `[sessions,totalUsers]` |
+| `ga4/<host>/landing.json` | pull_ga4.py | dims `[landingPage]`, mets `[sessions, engagementRate]` |
+| `ga4/<host>/funnel.json` | pull_ga4.py (only for `conversions.site`) | dims `[date, eventName, <sourceDimension>]` (falls back to `[date,eventName]`), mets `[eventCount]` |
+| `timeseries/gsc-<slug>.json` | pull_timeseries.py | `{site, startDate, endDate, rows:[{keys:[date,page], clicks, impressions}]}` 180d |
+| `timeseries/ga4-<host>.json` | pull_timeseries.py | `{site, rows:[{date:"YYYYMMDD", page, sessions}]}` 180d |
+| `timeseries/ga4-sources-<host>.json` | pull_timeseries.py | `{site, rows:[{date:"YYYYMMDD", source, medium, sessions}]}` 180d — daily traffic by source, bucketed into six groups (AI assistants, Search, Direct, Referral, Social, Other) by `classifySource` in `src/data.ts` |
+| `probes/probe-YYYYmmdd-HHMMSS.json` | site_probe.py | `{probed_at, sites:[{site:"https://host", robots{status,exists,sitemap_declared,ai_crawlers_blocked[]}, sitemap{status,exists,url_count,newest_lastmod}, "llms.txt"{status,exists,bytes}, "llms-full.txt"{…}, homepage{status,title,meta_description,canonical,og_tags,jsonld_types[],h1_count,lang,visible_text_bytes}, soft_404{status,real_404}}]}` |
+| `metadata-audit.json` | analyze_metadata.py | `{generated, window:"90d", sites:{host:[{page,title,description,imps,clicks,issues[],top_queries[{q,imps,clicks,pos,ctr}],missed_clicks_window}]}}` |
+| `index-status.json` | pull_index_status.py | `{generated, sites:{host:{property, checked, indexed, neverCrawled, sitemap{submitted, entries[{path,lastSubmitted,lastDownloaded,pending,errors,warnings}]}, problems:[{url,coverage,lastCrawl,verdict,robots,canonicalMismatch,googleCanonical,detail}]}}}` |
+| `trends-YYYY-MM-DD.json` | analyze_trends.py | `{generated, sites:{"<gscProperty>":{recent_split, prior_split, rising[], falling[], monthly{}}}, ai_referrals:{host:{ai{ym:n}, total{ym:n}}}}` |
+| `opportunity-proposals.json` | opportunity_scan.py | `{generated, candidates[], proposals[{host,title,kind,why,how,spec[],impact,effort,tag}], verdicts[{title,verdict,evidence}], inference_ran}` |
+| `hn-digest.json` | hn_digest.py | `{generated, stats{user,karma,created,comments}, picks[{id,title,url,story_url,comments,points,why,briefing,commented}]}` |
+| `reddit-digest.json` | reddit_digest.py | `{generated, user, auth, picks[{id,title,url,sub,comments,score,age_days,why,briefing,commented}]}` |
+| `last-run.json` | daily.py | `{ts, failures, steps:[{name, ok, seconds}]}` |
+| `daily-ops.log` | daily.py | appended stdout of each run |
+
+Committed, human-curated inputs:
+
+| Path | Purpose |
+|---|---|
+| `config/backlog.json` | `{actions:[Action…], shippedWatch:{url:note}}` — your strategic queue. `Action` = `{id, host, title, kind, why, how, spec[], impact, effort:"S"\|"M"\|"L", tag, watching?}` |
+| `config/insights.json` | `{date, insights:[{title, verdict, body[], move}]}` — optional narrative briefing |
+| `content/drafts/*.md` | Distribution drafts with front-matter `title, order, action, channel, status, tags, notes` |
+| `content/campaigns/*.json` | `{slug, name, site, summary, voice, targets[{rank,name,category,url,contact,angle,value,likelihood,evidence,status}], templates[{id,audience,subject,body}], plan[{day,action,template,notes}], week2, later, cautions[]}` |
+| `docs/daily-log.md` | Appended by the daily run; one `## YYYY-MM-DD` section per day |
+
+## The action engine (src/actions.ts)
+
+Rules over the 90-day window, each producing `Action`s with an evidence
+string, a concrete move, a spec, an impact estimate (clicks/month, **for
+ordering only**) and an effort size. Score = impact / effort weight
+(S=1, M=2.5, L=5). Rules: metadata-audit findings, CTR gaps, striking
+distance (pos 5–15), probe hygiene, landing-page engagement mismatch, 28-day
+traffic drop. Merged with `config/backlog.json`; any action whose page is in
+`shippedWatch` is shown as *watching* instead of *active*.
+
+The backlog file is hot-reloaded (stat polling) so edits — by hand or via
+the dashboard's accept/watch/retire buttons — show up without a restart.
+
+## Modules (opt-in, `modules.<key>.enabled`)
+
+| Key | Default | What it turns on |
+|---|---|---|
+| `indexStatus` | on | URL Inspection sweep of each sitemap |
+| `metadataAudit` | on | live title/description audit |
+| `opportunityScan` | on | trend refresh + uncovered-riser detection |
+| `llm` | off | local inference command (`command`, `fastCommand`; prompt on stdin, reply on stdout). Enables proposals/verdicts in the scan and briefings in the digests |
+| `hackerNews` | off | HN thread digest (`user`, `topics:[[query, why]]`) |
+| `reddit` | off | Reddit thread digest (`user`, `topics:[[sub, query, why]]`; creds in `.env`) |
+| `indexNow` | off | key generation + pings (`keyFile`) |
+| `staticExport` | off | dashboard → `site/` after each run (`signOutUrl`, `signOutLabel` add a sign-out link to every exported page) |
+| `publish` | off | copy `site/` to `destination` (`target`: `gcs` \| `s3` \| `rsync` \| `command`; `delete`, `dryRun`, `env`) |
+| `gitAutoCommit` | off | commit (+push) log/export after each run |
+| `notifications` | off | macOS notification on step failure |
+
+The dashboard's **Settings** page toggles these and edits the digest topics,
+writing back to `n-seo.config.json`. Nothing in any module posts, sends,
+or publishes on your behalf: digests produce briefings, the scan produces
+proposals, campaigns produce templates. You act.
+
+## Dashboard routes
+
+`/` overview (Today board + portfolio strip) · `/actions` (proposed → active
+→ watching, searchable) · `/insights` · `/trends[/N]` · `/content` (+
+`/drafts/:slug`, `/campaigns/:slug`) · `/site/:host` · `/indexing` ·
+`/probes` · `/logs` · `/settings` · `/api/actions` (JSON) · `/mcp` (HTTP
+MCP, bearer token) · write endpoints: `POST /api/backlog/accept`,
+`POST /api/backlog/:id/watch`, `POST /api/backlog/:id/retire`,
+`POST /settings`.
+
+## Engine and instance
+
+The checkout is the **engine**: code, public assets, engine docs. An
+**instance** is one user's config, queue, content and data. By default they
+are the same directory ("in-place" mode — a plain clone works unchanged).
+Set `N_SEO_INSTANCE=/path/to/instance` (or use the `n-seo` CLI, which sets it
+for you) to keep them apart; upgrading the engine is then a `git pull` or
+`npm update` that never touches instance files.
+
+| Owned by | Paths |
+|---|---|
+| engine (`ROOT`) | `src/`, `ingest/`, `ops/`, `probes/`, `public/`, `bin/`, `tests/`, `n-seo.config.example.json`, `docs/PLAYBOOK.md`, `docs/OPERATING-RULES.md`, `docs/ARCHITECTURE.md` |
+| instance (`INSTANCE`) | `n-seo.config.json` (`N_SEO_CONFIG` still overrides), `.env`, `config/backlog.json`, `config/insights.json`, `content/drafts/`, `content/campaigns/`, `data/`, `site/`, `docs/daily-log.md`, `docs/reports/`, the IndexNow key file (`modules.indexNow.keyFile`, relative to the instance) |
+
+Both loaders expose the split: `src/config.ts` → `ROOT`, `INSTANCE`,
+`engineInfo()`; `ingest/seo_config.py` → `ROOT`, `INSTANCE`, `DATA`,
+`engine_info()`. Engine scripts always run with `cwd=ROOT` and find the
+instance through the environment, never through the working directory.
+Git auto-commit commits in the instance. `engine_info` (MCP), the Engine
+card on `/settings`, `n-seo version` and the first block of `doctor` all
+report version · commit · mode · engine path · instance path.
+
+### Hooks
+
+```json
+"hooks": {
+  "beforeRun": ["python3 my/prep.py"],
+  "afterStep": { "daily-diff": ["python3 my/sync.py"] },
+  "afterRun":  ["rsync -a site/ user@host:/srv/mirror/"]
+}
+```
+
+Each entry is a shell string run by `ops/daily.py` with `cwd=INSTANCE` and
+`N_SEO_ROOT`, `N_SEO_INSTANCE`, `N_SEO_STEP` (afterStep only) in the
+environment. Output is teed to `data/daily-ops.log` like a step and each hook
+is recorded in `last-run.json` as `hook:before:<i>`, `hook:<step>:<i>` or
+`hook:after:<i>`. A failing hook counts as a failure (and notifies) but never
+aborts the run. `afterRun` hooks see a complete `last-run.json`. `--skip hooks`
+runs steps only; `--list` shows hooks in order.
+
+Two things worth knowing before you put something destructive in a hook.
+Hooks are run-level, not step-level: `beforeRun` and `afterRun` fire even
+under `--only`, so a one-step smoke test still runs them (the command prints
+a note when it is about to). And `afterStep` fires whether or not its step
+succeeded, so a hook that publishes something should check the step's own
+output rather than assume it ran.
+
+### `gscExtraProperties`
+
+```json
+"gscExtraProperties": ["https://example.com/"]
+```
+
+Extra Search Console properties (for example a url-prefix property that
+duplicates a domain property) pulled by `pull_gsc.py` and `pull_timeseries.py`
+into `data/gsc/<gscDataSlug>/` with the same windows and datasets (a url-prefix
+property lands in `<host>-urlprefix/`, never colliding with the domain
+property's directory), and checked by `doctor`. They are not sites: nothing in the dashboard, the trend analysis or
+the reports shows them.
+
+### The `n-seo` CLI (`bin/n-seo.mjs`)
+
+| Command | Does |
+|---|---|
+| `n-seo init [dir]` | Scaffold an instance: config from the example, empty `config/`, `content/`, `.env`, `.gitignore`, `.mcp.json` pointing at this engine, README. Never overwrites |
+| `n-seo start` · `dev` · `daily` · `doctor` · `demo` · `mcp` · `check` · `export` | Run the engine's command against the instance (`--instance <path>`, else `$N_SEO_INSTANCE`, else cwd); remaining args pass through |
+| `n-seo upgrade` | Git engine: `git pull --ff-only`, `npm ci` if the lockfile changed, `npm run check`; prints the exact `git reset --hard <sha>` if the check fails. npm engine: says to `npm update n-seo` |
+| `n-seo version` | engine version, commit, engine path, instance path, mode |
+
+## Operating rules the tooling encodes
+
+- Decisions ride the 90-day window; 16-month data is for totals and history.
+- Impact numbers order the queue. They are not forecasts.
+- After changing a page's title/description, freeze that page's metadata for
+  28 days. Stagger metadata changes (≈8/week max across all sites).
+- Shipped work becomes *watching*, never deleted — the data decides next.
+- Community participation is human: the tool briefs, you write.

package/docs/DEPLOY.md

@@ -0,0 +1,300 @@
+# Deploying n-seo somewhere other than your laptop
+
+n-seo is local-first, not laptop-first. "Local" means the data lives on
+infrastructure you control rather than in someone's SaaS; it does not have to
+mean the machine you are typing on. A laptop is a poor host for a daily job:
+it sleeps, it travels, and the run silently skips a day.
+
+This document is about moving it to a box that is always on.
+
+## The shape
+
+One host runs two long-lived things — the dashboard and a scheduler that
+fires the daily run — against one instance directory. That directory is the
+only state.
+
+```
+    ┌─────────────────────── your host ────────────────────────┐
+    │  docker compose                                          │
+    │    dashboard   ──┐                                       │
+    │    scheduler   ──┴──►  /instance   config, queue,        │
+    │      (daily at 07:00)              content, data, logs   │
+    └──────────────────────────────────────────────────────────┘
+              │ tunnel (IAP / SSH / Tailscale)     │ publish step
+              ▼                                    ▼
+        you, on :4600                     a bucket, served read-only
+                                          behind IAP — the mirror
+```
+
+Two audiences, two doors. **You** get the live dashboard, always through a
+tunnel, never over the open internet. **Everyone else** — colleagues, a
+client — gets the static mirror: yesterday's HTML with no application behind
+it, behind whatever sign-in you already have.
+
+## Rules, not suggestions
+
+- **Never publish the dashboard's port.** It has write endpoints, and the
+  Settings page sets the LLM command that the daily run executes. Reaching
+  the dashboard is equivalent to running code on the host. It binds
+  `127.0.0.1` by default and the container publishes to loopback only; keep
+  it that way and tunnel in.
+- **If you must have a hostname, put auth in front.** The Caddy overlay in
+  `docker/` does basic auth and TLS. IAP or Cloudflare Access are better.
+  Nothing goes in front of it means nothing is protecting it.
+- **No secret in the image or in git.** Mount the service-account key
+  read-only, or on GCP use no key at all (see below). `.env` stays out of
+  version control; `n-seo init` already gitignores it.
+- **The mirror is the thing you share.** It is static and read-only by
+  construction. Share that, not the dashboard.
+
+## Pick a host
+
+| | Good when | Notes |
+|---|---|---|
+| **Any Linux box with Docker** | you already have a VPS, a NAS, a home server | `deploy/vm/startup.sh` sets it up. Cheapest path. |
+| **A small GCE VM** | you are already on GCP, want IAP and disk snapshots | `deploy/gcp/setup.sh` builds the whole thing. `e2-small` is plenty. |
+| **Cloud Run for the engine** | — | Don't. See below. |
+
+### Why not Cloud Run for the engine
+
+It is the obvious idea and it does not work, for a specific reason:
+`ops/export_static.py` builds the site into a staging directory and finishes
+with an atomic `Path.rename()`, so a failed export can never publish an empty
+mirror. GCS FUSE — the only way to give Cloud Run persistent storage — has no
+atomic directory rename. You would trade a real guarantee for a scale-to-zero
+you do not need for a job that runs once a day.
+
+Cloud Run is still the right tool for *serving the mirror*, where the bucket
+is mounted read-only and nothing renames anything. That is what
+`deploy/gcp/cloud-run-mirror/` is.
+
+## Any Linux box
+
+```sh
+curl -fsSLO https://raw.githubusercontent.com/en-dash-consulting/n-seo/main/deploy/vm/startup.sh
+sudo bash startup.sh
+
+sudo -u n-seo /opt/n-seo/manage init
+sudo -u n-seo vi /srv/n-seo/instance/n-seo.config.json
+sudo -u n-seo /opt/n-seo/manage doctor
+sudo -u n-seo /opt/n-seo/manage daily
+```
+
+Then tunnel to the dashboard:
+
+```sh
+ssh -N -L 4600:localhost:4600 you@your-host
+```
+
+Details, commands and backup instructions: `deploy/vm/README.md`.
+
+## GCP, end to end
+
+```sh
+gcloud config set project YOUR_PROJECT
+cd deploy/gcp
+
+./setup.sh --dry-run        # read what it will do
+./setup.sh                  # do it
+```
+
+That creates a service account with Token Creator on itself, a private bucket
+for the mirror, a persistent data disk, a VM with the SA attached and **no
+external IP**, a firewall that allows only IAP's SSH range, and the Cloud Run
+mirror behind IAP. Every value at the top of the script is overridable
+(`REGION=europe-west1 ./setup.sh`).
+
+It cannot do four things, and prints them when it finishes:
+
+1. **Search Console** — add the service account as a **Full** user on every
+   property. Domain properties sometimes reject a service-account address in
+   that UI; `docs/SETUP-GOOGLE.md` covers verifying it as an owner instead.
+2. **GA4** — add the same address with the **Viewer** role.
+3. **IAP members** — who may open the mirror.
+4. **Your instance** — the config, the queue, the content. Yours to write.
+
+### Auth with no key file
+
+On GCP, set:
+
+```json
+"google": { "auth": "metadata" }
+```
+
+The engine takes the VM's own identity from the metadata server and exchanges
+it, through IAM Credentials, for a token scoped to Search Console or GA4 —
+the metadata server's default token is `cloud-platform` scoped, which the
+Search Console API rejects. That exchange is why the service account needs
+`roles/iam.serviceAccountTokenCreator` **on itself**, which `setup.sh`
+grants. No key is created, downloaded or stored.
+
+Off GCP, keep a key file mounted read-only and point
+`google.serviceAccountKey` at it.
+
+### Publishing the mirror
+
+`staticExport` builds `site/`; `publish` copies it wherever people read it.
+Both are steps in the daily run, so they are logged, retried once and
+recorded in `last-run.json` like everything else.
+
+```json
+"modules": {
+  "staticExport": { "enabled": true, "signOutUrl": "/_gcp_iap/clear_login_cookie" },
+  "publish": {
+    "enabled": true,
+    "target": "gcs",
+    "destination": "gs://YOUR_PROJECT-n-seo-mirror",
+    "delete": true,
+    "dryRun": false,
+    "env": {}
+  }
+}
+```
+
+The VM's service account already has write access to that bucket, so nothing
+here carries a credential. `deploy/gcp/cloud-run-mirror/README.md` has the
+serving side.
+
+**Four targets.** Each needs its own tool on `PATH`, and the step says so
+plainly when one is missing.
+
+| `target` | Runs | `delete` adds |
+|---|---|---|
+| `gcs` | `gcloud storage rsync site <destination> --recursive` | `--delete-unmatched-destination-objects` |
+| `s3` | `aws s3 sync site <destination>` | `--delete` |
+| `rsync` | `rsync -a site/ <destination>` | `--delete` |
+| `command` | `modules.publish.command`, as a shell string | nothing — your command decides |
+
+`delete` is what makes the mirror match the export instead of accumulating
+pages you have since removed. It also means a broken export would delete a
+working mirror, which is why `ops/export_static.py` builds into a staging
+directory and only swaps it in on success.
+
+**Rehearse first.** Set `dryRun` and the step prints the exact command
+without running it:
+
+```
+publish: env CLOUDSDK_CONFIG
+publish: DRY RUN — would run:
+  gcloud storage rsync /srv/n-seo/site gs://acme-n-seo-mirror --recursive --delete-unmatched-destination-objects
+publish: set modules.publish.dryRun to false to publish for real
+```
+
+Read that line before you clear `dryRun`, especially with `delete` on and a
+bucket that is already serving something.
+
+**Credentials.** `env` is merged into the publish command's environment only,
+so a deployment that keeps its cloud config somewhere specific can point at
+it without exporting that for the whole run:
+
+```json
+"env": { "CLOUDSDK_CONFIG": "~/.config/acme/gcloud" }
+```
+
+`~` and `$VARS` are expanded. Only the key names are ever logged.
+
+### A sign-out link on the mirror
+
+The mirror sits behind an auth proxy, and a proxy needs a way out. Set the
+URL yours uses and every exported page gets a sign-out link in the topbar:
+
+```json
+"staticExport": { "enabled": true, "signOutUrl": "/oauth2/sign_out", "signOutLabel": "Sign out" }
+```
+
+IAP uses `/_gcp_iap/clear_login_cookie`, oauth2-proxy `/oauth2/sign_out`,
+Cloudflare Access `/cdn-cgi/access/logout`. The live dashboard renders
+nothing for it — there is nothing to sign out of on your own machine.
+
+### Reaching the dashboard on GCP
+
+```sh
+gcloud compute start-iap-tunnel n-seo 4600 \
+  --local-host-port=localhost:4600 --zone us-east1-b
+open http://localhost:4600
+```
+
+No public IP, no open port, no password to leak.
+
+## The LLM module on a headless host
+
+`modules.llm` shells out to a local CLI by default (`claude -p`). On a server
+that binary usually is not there and is not signed in, and the opportunity
+scan and the digests quietly fall back to no proposals and no briefings.
+
+Either install and authenticate the CLI in the image, or configure the HTTP
+path so no CLI is needed:
+
+```json
+"modules": {
+  "llm": {
+    "enabled": true,
+    "http": {
+      "provider": "anthropic",
+      "model": "claude-sonnet-5",
+      "fastModel": "claude-haiku-4-5-20251001",
+      "apiKeyEnv": "ANTHROPIC_API_KEY"
+    }
+  }
+}
+```
+
+with `ANTHROPIC_API_KEY` in the instance's `.env` (never in the image).
+`doctor` reports which path it will use.
+
+## Backups
+
+The instance directory is the whole story, and if you keep it in its own git
+repo — which `docs/INSTANCE.md` recommends — most of it is already backed up
+on every daily run when `gitAutoCommit` is on. `data/` is regenerable; the
+next run rewrites it.
+
+```sh
+gcloud compute disks snapshot n-seo-data --zone us-east1-b     # GCE
+
+sudo tar czf n-seo-instance-$(date +%F).tgz \
+  --exclude=data --exclude=site -C /srv/n-seo instance          # anywhere
+```
+
+Restoring is putting the directory back and running `manage daily` once.
+
+## Upgrades
+
+```sh
+sudo -u n-seo /opt/n-seo/manage upgrade
+```
+
+Pulls the engine, rebuilds the image, restarts the stack, re-runs the offline
+checks. The instance directory is never touched by an upgrade — that
+separation is the point of `docs/INSTANCE.md`. Roll back by checking out the
+previous engine commit and running `manage up`.
+
+## Watching it
+
+| Where | What |
+|---|---|
+| `/` (run chip) | green or red for the last run |
+| `/logs` | the daily entries and raw run output |
+| `data/last-run.json` | per-step timing and the names of failed steps |
+| `docs/daily-log.md` | the human-readable entry, one section a day |
+| `manage logs` | container stdout, both services |
+
+`modules.notifications` is macOS-only. On a server, notice failures by
+watching the run chip, or add an `afterRun` hook that posts `last-run.json`
+somewhere you look — Slack, email, a health-check ping. A hook that fires on
+failure is three lines:
+
+```json
+"hooks": {
+  "afterRun": [
+    "grep -q '\"failures\": \"\"' data/last-run.json || curl -fsS -X POST -d @data/last-run.json \"$ALERT_WEBHOOK\""
+  ]
+}
+```
+
+## An agent can do all of this
+
+`.claude/skills/n-seo-deploy/SKILL.md` walks an agent through choosing a
+shape, running the scaffolding, verifying it, and handing you the console
+steps it cannot do. It will not expose the dashboard for you, and it will not
+print a secret.

package/docs/FAQ.md

@@ -0,0 +1,93 @@
+# FAQ
+
+**What does it cost?**
+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.
+
+**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.
+The next daily run tells you whether it worked. The only files the app ever
+writes are its own config, `config/backlog.json` (when you click accept /
+watch / retire), and files under `data/`, `site/` and `docs/`.
+
+**Can it post to Hacker News or Reddit for me?**
+No, by design, and the docs ask any AI agent using the repo not to either.
+The community modules find threads where your experience applies and write a
+briefing — what the piece says, what the thread is debating, where you
+genuinely connect. Generated participation is detectable and gets accounts
+banned; a briefing gets you to the thread quickly and the words stay yours.
+
+**Do I need Claude, or any LLM?**
+No. Every data step and every page works without one. The `llm` module is
+off by default; when on, it runs a shell command that reads a prompt on
+stdin and prints a reply — the `claude` CLI by default, but any CLI with
+that shape works (`llm`, `ollama run …`, your own script). It adds
+proposals and verdicts to the opportunity scan and briefings to the digests.
+Nothing it produces is applied automatically.
+
+**Does it run on Windows?**
+Not supported. The scripts assume `curl`, `openssl`, POSIX paths and one of
+launchd / cron / systemd. WSL2 is likely to work but is untested.
+
+**Where does my data go?**
+Into `data/` on the machine that runs the pipeline, as JSON. The only network
+calls are to the Google APIs you authorized, your own sites (the probe and
+the metadata audit fetch pages like a browser would), and — if you enable
+them — the HN Algolia API, Reddit's API, IndexNow, and your LLM command. The
+static-export module writes HTML to `site/`; where you host that, and behind
+what auth, is up to you. Nothing phones home.
+
+**Can several people use one install?**
+The dashboard is a plain HTTP server on the configured port with no accounts.
+On a shared machine or a tunnel, everyone who can reach the port sees
+everything and can click accept / watch / retire and change Settings. Put it
+behind your own auth (a VPN, an identity-aware proxy, an SSH tunnel) if that
+matters. The MCP HTTP endpoint is the one part with its own gate: a bearer
+token, and it refuses to serve without one.
+
+**How is "impact" estimated?**
+Roughly, and only to order the queue. CTR gaps: impressions × (the CTR the
+position should earn − the CTR it gets), per month. Striking distance: a
+small fraction of impressions assumed to convert to clicks if the page
+reaches the top five. Engagement mismatches: a share of the sessions that
+currently bounce. Backlog items carry whatever estimate you typed. Impact ÷
+effort (S=1, M=2.5, L=5) sorts the list. These are not forecasts and the
+dashboard says so on every page that shows them.
+
+**Why 90 days?**
+Because a page you fixed last week must stop being accused within a season,
+and a query cluster that died in the spring must stop looking alive in the
+fall. Sixteen months is kept for totals and history; every decision uses the
+trailing 90 days.
+
+**Why the 28-day title freeze?**
+Search engines re-evaluate a page after a title change and need weeks of
+impression data to settle. Iterating inside that window destroys the
+measurement, and a stream of title changes reads as manipulation.
+
+**Search Console shows the last three days but the tool doesn't.**
+The pipeline requests finalized data only (`dataState: final`), and Google
+finalizes each day about three days late. The trailing three days always
+fill in on later runs.
+
+**The Trends page says "no traffic recorded yet" for a site.**
+That is a connected site with empty data — new, or not yet ranking. It is
+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.
+
+**A daily step failed. What now?**
+Open `/logs` (or `data/daily-ops.log`), then `python3 ops/doctor.py`. A 401
+or 403 from Google means the service account lost access or the key file
+moved. A run that fails every network step at once was offline; the next run
+will recover. Steps are independent — one failing does not stop the others.
+
+**Can I run it for clients?**
+Yes; one config per install, or several sites in one config. The license is
+MIT.