n-seo 0.3.3 → 0.4.0

package/CHANGELOG.md

@@ -0,0 +1,399 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project
+uses [Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+Nothing yet.
+
+## [0.4.0] - 2026-09-12
+
+Upgrading used to be something you found out about by accident. This release
+makes it visible and makes it one command.
+
+### Added
+- **`n-seo upgrade` does the upgrade.** It works out how the engine was
+  installed — a git checkout, a global npm install, a global install under a
+  custom prefix, or a local one — and runs the right thing for that layout.
+  It prints the versions either side, the new release's changelog section,
+  the exact rollback command, and a reminder that the dashboard needs a
+  restart. `--check` reports what is available and changes nothing.
+- **A daily update check, and a notice where you already look.** The new
+  `updateCheck` module asks the registry once per run whether a newer engine
+  shipped, and the Settings page and `n-seo doctor` show it. The dashboard
+  never makes that request itself — it reads `data/update-check.json` — so
+  every page still renders with the machine offline, and an unreachable
+  registry leaves the previous answer in place rather than failing the run.
+- **This is the only module that ships enabled**, so the claim that nothing
+  leaves the host was no longer strictly true. The README, the site and the
+  PRD now say exactly what it sends (nothing about you) and how to switch it
+  off. `CHANGELOG.md` is published with the package so the upgrade can show
+  you what you just got.
+
+### Fixed
+- **`n-seo upgrade` gave advice that silently did nothing.** For any npm
+  engine it printed `npm update n-seo`. That is correct for exactly one
+  layout — a consumer `package.json` with n-seo as a dependency — and wrong
+  for the global install the README recommends: run there it reports "up to
+  date", exits 0, upgrades nothing, and leaves a stray `package-lock.json` in
+  whatever directory you were standing in.
+- The Settings notice compares against the engine running now rather than the
+  version recorded in the file, so upgrading clears it immediately instead of
+  at the next daily run.
+
+## [0.3.3] - 2026-09-11
+
+### Fixed
+- **Every published mirror page claimed the daily run had not happened.**
+  `data/last-run.json` was written once, after all steps finished. But
+  `static-export` is itself a step, so when it stamped each page it read the
+  *previous* run's record — a mirror rebuilt at 07:44 carried a "daily run
+  OK" badge from the night before, which reads exactly like a run that never
+  fired. The record is now written after every step, so a later step sees the
+  run it is part of. It also means the dashboard's status advances during a
+  long run instead of sitting stale for its full duration.
+
+## [0.3.2] - 2026-09-10
+
+### Changed
+- **The dashboard's top bar uses the display face too.** 0.3.1 put Montserrat
+  on headings only, which left the wordmark and the nav in the system UI font
+  and made the top bar look untouched next to a restyled page. Both now use
+  it, matching how the marketing site treats its own chrome. The face is a
+  `--display` token rather than three copies of a fallback stack. The
+  Sites and System dropdowns keep the mono face: they list hostnames, which
+  are easier to scan monospaced. Tables, chips and numbers are unchanged —
+  a dense data view is designed around the system font.
+
+## [0.3.1] - 2026-09-10
+
+### Fixed
+- **`doctor` told a healthy npm install to run `npm install`.** The check
+  looked for a `node_modules` directory inside the engine. npm hoists
+  dependencies to the *consumer's* `node_modules`, so an `npm i n-seo` engine
+  correctly has none of its own, and every install reported a warning whose
+  suggested fix did nothing. It now asks node to resolve `tsx`, `hono` and
+  `@hono/node-server` from the engine — the same resolution the CLI does
+  before it spawns the dashboard — so it passes on both layouts and still
+  fails on an engine that genuinely cannot start. Found by pointing a real
+  instance at the published package instead of a git checkout.
+
+## [0.3.0] - 2026-09-10
+
+### Added
+- **`n-seo init` refuses to scaffold inside a website.** An instance is a
+  standalone project: it writes a config, a queue, drafts and a `data/` tree
+  that the daily run rewrites every morning, and inside a site repo all of
+  that gets committed and usually deployed. `init` now stops when the target
+  directory (or the parent of a directory it is about to create) holds an
+  application marker such as `package.json`, or sits inside a git repository
+  that is not itself an instance. The error names the reason and shows the
+  right command. `--force` overrides; re-running `init` on an existing
+  instance is always allowed, and in-place mode in the engine checkout is
+  unaffected. The README, the marketing site, `docs/INSTANCE.md` and the FAQ
+  say the same thing in words.
+- **The skills ship, and `init` installs them.** `.claude/skills/` was not in
+  the npm `files` list, so an `npm i n-seo` install had none of the operating
+  skills at all. The seven instance-facing ones are now packaged, and `init`
+  copies them into the new instance with this install's real engine and
+  instance paths substituted for the placeholders, alongside a `CLAUDE.md`
+  carrying the operating rules. Opening an instance in Claude Code is now
+  enough to run setup, triage, shipping and the weekly review by asking. The
+  contributor skills (`ndx-*`) stay in the engine checkout.
+- **Command output points at the skills where it is useful.** `n-seo init`
+  ends with the prompts to try, `n-seo demo` names the one that connects real
+  sites, `n-seo start` prints the triage prompt, and `n-seo doctor` suggests
+  `/n-seo-setup` only when it found problems to fix. Each is gated on the
+  skills actually being present.
+
+### Changed
+- **The site shows the setup instead of describing it.** Someone opened their
+  own website's repo and ran `n-seo init` inside it, which is a fair reading
+  of a quickstart that never says where the command should be run. There is
+  now a "Where it goes" section on n-seo.dev with the wrong filesystem layout
+  beside the right one, a breakdown of what each command in the quickstart
+  actually does, and three cards naming what n-seo touches: your repos never,
+  Google's APIs read-only, its own directory for everything it writes. The
+  README and `docs/INSTANCE.md` carry the same trees as text.
+- **Typography, self-hosted.** Montserrat and Merriweather replace DM Sans,
+  DM Mono and the Google Fonts CDN on the marketing site; the dashboard's
+  headings and brand mark move to Montserrat while its tables keep the system
+  UI font. Both families are shipped as latin-subset variable woff2 files
+  served from the same origin, so there is no third-party request, no
+  render-blocking stylesheet on another domain, and the dashboard renders
+  correctly on a host with no outbound internet. Licences are in
+  `www/fonts/OFL.txt` and `public/fonts/OFL.txt`. The static export copies the
+  font alongside `styles.css`.
+- **The indexing page says what to do, per verdict.** Every coverage state now
+  carries a remediation line and a marker saying whether Request Indexing will
+  help. It helps for "URL is unknown to Google" and "Discovered - currently
+  not indexed", where Google has formed no judgement about the content. It
+  does not help for "Soft 404" or "Crawled - currently not indexed": Google
+  fetched the page, judged it, and would judge the same content the same way
+  again, so a re-request spends a slot of a roughly ten-a-day quota for
+  nothing. Redirects, canonicals, duplicates, robots blocks and noindex are
+  covered too. The FAQ answer on stale soft 404s was rewritten for the same
+  reason.
+
+## [0.2.0] - 2026-09-09
+
+### Changed
+- **Says what it is.** n-seo is an agentic tool: your model turns findings
+  into proposals, verdicts and briefings, and your coding agent works the
+  queue over MCP. That was the seventh heading in the README and absent from
+  the npm description; it is now the second section on the site and near the
+  top of the README. "En Dash SEO" appears beside the wordmark, since `n-seo`
+  reads as noise to someone landing cold. The LLM module remains opt-in and
+  nothing posts, publishes or edits a site.
+
+### Fixed
+- The docs claimed 15 MCP tools where the server registers 16 (`engine_info`
+  was missing from the table), the README skills list omitted `n-seo-deploy`,
+  and `llms.txt` still carried the pre-npm clone quickstart.
+- Two MCP error messages told the reader to run a Python script directly
+  rather than the CLI command that works on every platform.
+
+### Added
+- **Windows support.** CI runs the whole check job on `windows-latest` —
+  typecheck, both test suites, every dashboard route, the MCP stdio smoke and
+  a scaffolded instance — alongside Ubuntu on Node 20 and 22. Nothing is
+  gated off for Windows. `ops/templates/n-seo-daily-task.xml` is a Task
+  Scheduler definition for the daily run, with the catch-up behaviour launchd
+  gives on macOS.
+- `ops/py.mjs` resolves the Python interpreter this machine actually has, and
+  the npm scripts and the CLI both go through it. `$PYTHON` still overrides.
+- `tests/py/test_portability.py` enforces the two rules that make the above
+  hold: every text file call names `encoding="utf-8"`, and no shipped code
+  invokes `openssl`.
+
+### Changed
+- The service-account JWT is signed with node's crypto module instead of the
+  `openssl` binary. That removes an external dependency on every platform, and
+  removes the temporary private-key file the old path wrote to disk. The
+  Docker image no longer installs openssl.
+- Dashboard copy names the CLI (`n-seo daily --only probe`) rather than
+  `python3 probes/site_probe.py`, which is not a command on Windows.
+
+### Fixed
+- Python file I/O and stdout used the platform's locale encoding, which is
+  cp1252 on a stock Windows install rather than UTF-8. Non-ASCII Search
+  Console queries would have raised `UnicodeEncodeError` and ended the daily
+  run there. All 85 call sites are explicit now, and `seo_config` forces UTF-8
+  stdio on import.
+- A command configured with an unbalanced quote in Settings raised
+  `ValueError` out of `shlex` and took down the daily run on every platform.
+  It degrades to "no command", and `n-seo doctor` says the command could not
+  be parsed rather than reporting it as unconfigured.
+- `shlex.split` treated backslashes in a configured LLM command as escapes,
+  turning `C:\tools\claude.exe` into `C:toolsclaude.exe`.
+- The TypeScript test sandbox spawned `python3` to seed its dataset, so on
+  Windows every Python-seeded suite would have taken its skip branch and
+  reported a green run that tested none of them.
+
+## [0.1.1] - 2026-09-09
+
+### Changed
+- Install instructions lead with `npm install -g n-seo` now that the package
+  is published; the clone path stays documented for people changing the
+  engine itself. README carries npm, CI and licence badges.
+- The site moves to https://n-seo.dev, and `www/CNAME` ships inside the Pages
+  artifact so a redeploy cannot drop the custom domain.
+
+### Fixed
+- The release smoke script no longer parses `npm pack --json`, whose shape
+  differs between npm 10 and npm 12. The release job upgrades npm before
+  running it, so it saw a different shape than CI did and failed one step
+  before publishing.
+
+### Security
+- Releases are staged rather than published directly. CI submits with
+  `npm stage publish`; a maintainer approves with 2FA before anything is
+  live, so a compromised runner or a stray tag cannot put code on the
+  registry.
+
+## [0.1.0] - 2026-09-09
+
+First public release.
+
+### Security
+- Dashboard binds `127.0.0.1` by default (`SEO_HOST` overrides) and rejects
+  cross-origin `POST`s, since Settings can set the LLM command that the daily
+  run executes.
+- The static export omits `/settings` (local paths and the service-account
+  email do not belong on a mirror).
+
+### Added
+- **Traffic sources over time.** `pull_timeseries.py` also pulls GA4
+  `date × source/medium` for 180 days into
+  `data/timeseries/ga4-sources-<host>.json`, and `classifySource` buckets it
+  into AI assistants, Search, Direct, Referral, Social and Other. Trends and
+  every site page get a stacked "sessions by source" chart, plus a dedicated
+  **AI assistants / day** chart on its own axis — inside the stack AI is a
+  percent or two, so the trend worth watching is invisible there.
+- **Site pages show trends**, with the same window picker `/trends` has
+  (`/site/<host>/<days>`).
+
+- **`modules.publish`**: getting `site/` to wherever people read it is now a
+  pipeline step rather than a hook you write yourself, so it is logged,
+  retried once and recorded in `last-run.json`. Targets: `gcs`
+  (`gcloud storage rsync`), `s3` (`aws s3 sync`), `rsync`, and `command` for
+  anything else. `delete` makes the mirror match the export; `dryRun` prints
+  the exact command without running it, which is how you rehearse a cutover
+  against a bucket that is already serving something; `env` is merged into
+  that command's environment only, with key names logged and values never.
+  It refuses clearly when the destination is empty, the tool is missing from
+  `PATH`, or there is no `site/` to publish.
+- **`modules.staticExport.signOutUrl`** (with `signOutLabel`) adds a sign-out
+  link to every exported page, for a mirror behind IAP, oauth2-proxy,
+  Cloudflare Access or anything else with a sign-out URL. The live dashboard
+  renders nothing for it.
+- **Engine / instance split**: `N_SEO_INSTANCE` points the engine at a separate
+  directory holding your config, queue, content and data, so upgrading the
+  engine is a `git pull` (or `npm update`) that never touches your files.
+  In-place mode (no env var) is unchanged.
+- **`n-seo` CLI** (`bin/n-seo.mjs`): `init` scaffolds an instance;
+  `start`/`dev`/`daily`/`doctor`/`demo`/`mcp`/`check`/`export` run the engine
+  against it; `upgrade` pulls, reinstalls and re-checks the engine with a
+  printed rollback; `version` shows engine + instance.
+- **Hooks** (`hooks.beforeRun` / `hooks.afterStep.<step>` / `hooks.afterRun`):
+  your own shell commands around the daily run, logged and recorded like steps.
+- **`gscExtraProperties`**: extra Search Console properties pulled for their
+  data without appearing as sites.
+- `engine_info` MCP tool; Engine card on Settings; `doctor` engine block.
+- **One config file** (`n-seo.config.json`) read by the dashboard and every
+  Python script: sites, Google auth, watch pages, conversions, module switches.
+  Falls back to the example so a fresh checkout runs.
+- **Google auth without gcloud**: service-account JSON key, JWT signed locally
+  with the `openssl` CLI. gcloud impersonation and user modes remain available.
+- **Ingest**: Search Console (16-month and 90-day windows), GA4 (daily, sources,
+  landing pages, conversion events), per-page time series, URL Inspection
+  index-coverage sweep, live-site probes (robots, sitemap, llms.txt, soft 404s,
+  AI-crawler blocks, JS-shell detection), metadata audit, 84-day trend analysis.
+- **Action engine**: metadata findings, CTR gaps, striking-distance queries,
+  probe hygiene, landing-page engagement mismatch, traffic-drop investigation;
+  ranked by impact per unit of effort and merged with a curated queue in
+  `config/backlog.json` (hot-reloaded). Shipped pages show as *watching*.
+- **Dashboard** (Hono SSR, no bundler): Today board, action queue with
+  accept / mark-watching / retire, Insights, Trends (band charts + heatmap),
+  Content (drafts, campaigns, participation briefings), per-site pages,
+  Indexing, Probes, Logs, and a **Settings** page that toggles modules and
+  writes the config. Light and dark themes.
+- **Opt-in modules**: LLM inference through any stdin CLI, Hacker News and
+  Reddit digests (briefings only, never comment text), IndexNow, static export,
+  git auto-commit, desktop notifications.
+- **MCP server** (stdio and bearer-token HTTP, read-only) exposing the queue,
+  metrics, audit, ops status, proposals, campaigns and settings to agents.
+- **Operations**: `ops/daily.py` orchestrator with network wait and one retry,
+  `ops/doctor.py` setup checker, `ops/demo_data.py` synthetic dataset,
+  launchd / cron / systemd templates and a launchd installer.
+- **Tests and CI**: `node --test` suites for config, backlog writes, action
+  engine invariants and data helpers; `unittest` suites for config parity,
+  HTTP retry classification, JWT signing, daily-diff and demo-data conformance;
+  GitHub Actions running all of it plus a dashboard smoke test and a grep that
+  rejects private names.
+- Docs: README, ARCHITECTURE, SETUP-GOOGLE, SCHEDULING, OPERATING-RULES,
+  PLAYBOOK, MCP, ADDING-A-SITE, FAQ, CONTRIBUTING, SECURITY.
+
+- **Deployment off a laptop**: `google.auth: "metadata"` uses the GCE /
+  Cloud Run / GKE runtime service account, so a hosted install needs no key
+  file at all. The metadata token is `cloud-platform` scoped and Search
+  Console rejects that, so the account mints a correctly scoped token for
+  itself through IAM Credentials; a missing Token Creator binding is
+  reported with the exact `gcloud` command that fixes it.
+- **LLM over HTTP**: `modules.llm.http` calls an Anthropic or
+  OpenAI-compatible endpoint instead of a local CLI, with the key read from
+  the environment or `.env`. Without it the opportunity scan and the digests
+  are silently inert on any machine you did not sign a CLI into. `http` wins
+  when its key resolves, so one config file works on both a laptop and a
+  server.
+
+- **Deployment**: a container image (`Dockerfile`, 328 MB, Node + stdlib
+  Python + curl + openssl) whose entrypoint takes `serve`, `daily`, `doctor`,
+  `demo`, `init` or `cron`, with the instance as a volume at `/instance`.
+  `docker/compose.yml` runs the dashboard and a scheduler on one volume and
+  binds the dashboard to loopback, so a bare `docker compose up` is not an
+  open dashboard; `docker/compose.caddy.yml` adds TLS and basic auth and
+  refuses to start without credentials configured.
+- **GCP scaffolding**: `deploy/gcp/setup.sh` (idempotent, `--dry-run`)
+  provisions a service account with the Token Creator self-binding, a private
+  mirror bucket, a data disk, a VM with no external IP reachable only over
+  IAP, and the Cloud Run mirror; `deploy/vm/startup.sh` brings the same stack
+  up on any Debian or Ubuntu host, so a VPS or a NAS works the same way.
+  `docs/DEPLOY.md` is the narrative and says plainly why the engine does not
+  belong on Cloud Run: the static export finishes with a directory rename,
+  which GCS FUSE cannot do atomically.
+- **`n-seo-deploy` skill** walks an agent through choosing a host, running the
+  scaffolding, verifying with `doctor` and a probe-only run, and handing back
+  the console steps that cannot be scripted.
+
+### Changed
+- **The site page stops wasting the screen.** Query tables and the narrow
+  source lists sit in a 2:1 split instead of every table spanning the full
+  width, and "Do next" caps at six cards with a link to the full queue.
+- **Seven nav items instead of ten.** Indexing, Probes, Logs and Settings
+  fold into one **System** menu.
+
+- The Trends page opens with a portfolio source mix and an AI-assistants
+  chart for every site combined, so "where is the traffic coming from" is
+  answered without expanding a tile.
+
+- `npm i n-seo` produced an install that could not serve a page. The CLI
+  refused to start because it looked for `node_modules` inside the engine,
+  which npm hoists to the consumer instead; and `tsconfig.json` was not in the
+  published files, so tsx fell back to the React JSX transform and every
+  server-rendered route answered 500. Both found by installing the packed
+  tarball and running it, which is now the release check.
+
+### Fixed
+- **Data loss**: a Search Console, GA4 or time-series pull that hit an API
+  error overwrote the previous snapshot with zero rows and still reported the
+  step as successful. The pulls now keep the last good file and fail the step.
+- **Wrong advice**: the metadata audit ignored the HTTP status, so a page that
+  had started 404ing was audited against its error page and produced a
+  top-ranked "rewrite this title" card. It now reports the dead page instead,
+  counting both 200 and 206 as serving because a ranged request returns 206
+  from any server that honours the Range header.
+  Descriptions containing an apostrophe were truncated at it and then flagged
+  as too short, and HTML entities were blanked rather than decoded.
+- **Inverted GEO signal**: the robots.txt check matched across `User-agent`
+  group boundaries, so a crawler the file explicitly allowed could be reported
+  as blocked, with a hygiene action to match.
+- **Queue ordering**: one unrecognised `effort` in `config/backlog.json` made
+  the sort comparator return NaN, leaving the order of every other card
+  undefined. Values are coerced on load and scoring can no longer produce NaN.
+- Two long titles could share a truncated id, so retiring one deleted both.
+- The traffic-drop card measured 28-day sessions but was ranked and rendered
+  as monthly clicks, so it outranked everything else by roughly fifty times.
+- The static export emptied `site/` before fetching, so a failed export
+  published an empty mirror through the `afterRun` rsync hook.
+- `--no-network-wait` was ignored on the retry path, so an offline run waited
+  the full timeout for every failing step.
+- GA4 time series and trend queries were unpaginated and truncated silently;
+  the URL Inspection budget was per host although the quota is per property.
+- The JWT is backdated 60s so a slightly fast clock cannot fail
+  authentication, and `GOOGLE_APPLICATION_CREDENTIALS` is honoured when the
+  configured key path does not exist.
+- The opportunity scan dropped genuine risers whose query appeared as a
+  substring anywhere in the queue's prose.
+- `tsx` moved from devDependencies to dependencies. The engine runs
+  TypeScript directly with no build step, so `npm ci --omit=dev` — and
+  therefore any published `npm i n-seo` — produced an install whose dashboard
+  could not start.
+- The test sandbox now seeds its own demo dataset and neutralizes
+  `N_SEO_INSTANCE` while importing. Previously the action-engine suite was
+  dropped from the run whenever the checkout had no `data/` — which is the
+  normal state of an engine in instance mode, and therefore of every
+  `n-seo upgrade` gate — without changing the reported test counts, and an
+  in-place install ran those assertions against the owner's live data.
+
+[Unreleased]: https://github.com/en-dash-consulting/n-seo/compare/v0.4.0...HEAD
+[0.4.0]: https://github.com/en-dash-consulting/n-seo/compare/v0.3.3...v0.4.0
+[0.3.3]: https://github.com/en-dash-consulting/n-seo/compare/v0.3.2...v0.3.3
+[0.3.2]: https://github.com/en-dash-consulting/n-seo/compare/v0.3.1...v0.3.2
+[0.3.1]: https://github.com/en-dash-consulting/n-seo/compare/v0.3.0...v0.3.1
+[0.3.0]: https://github.com/en-dash-consulting/n-seo/compare/v0.2.0...v0.3.0
+[0.2.0]: https://github.com/en-dash-consulting/n-seo/compare/v0.1.1...v0.2.0
+[0.1.1]: https://github.com/en-dash-consulting/n-seo/compare/v0.1.0...v0.1.1
+[0.1.0]: https://github.com/en-dash-consulting/n-seo/releases/tag/v0.1.0

package/README.md

@@ -31,7 +31,9 @@ to **a model you choose**, and everything that changes a site is handed to you.
 - **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
-  Google APIs you authorize and the provider you configured yourself.
+  Google APIs you authorize, the model provider you configured yourself, and
+  one daily version check against the npm registry that carries nothing about
+  you and turns off with `"updateCheck": {"enabled": false}`.
 
 ![Overview](docs/screenshots/overview.png)
 
@@ -164,6 +166,25 @@ merge. See [docs/INSTANCE.md](docs/INSTANCE.md).
 Adding another site later is one entry in the config —
 [docs/ADDING-A-SITE.md](docs/ADDING-A-SITE.md).
 
+## Upgrading
+
+```sh
+n-seo upgrade --check   # what is available, changes nothing
+n-seo upgrade           # do it
+```
+
+One command, whichever way you installed it: a git checkout, a global npm
+install, or a local one. It works out which, runs the right thing, prints
+what changed and the exact command to roll back, then reminds you to restart
+the dashboard. **Your config, queue, content and data are never touched** —
+that is the whole point of keeping the instance separate from the engine.
+
+You do not have to remember to check. Each daily run asks the registry once
+whether a newer version shipped and notes it on the Settings page and in
+`n-seo doctor`. The dashboard never makes that request itself, so pages still
+render with the machine offline. Turn the whole thing off with
+`"updateCheck": {"enabled": false}` in `n-seo.config.json`.
+
 Running several people's sites, or want upgrades to be a `git pull`? Keep your
 config in its own directory — see [docs/INSTANCE.md](docs/INSTANCE.md).
 
@@ -278,8 +299,8 @@ the data says whether it worked.
 
 ## Modules
 
-Everything below is off by default except the three data steps. Toggle them
-on the Settings page or in `n-seo.config.json`.
+Everything below is off by default except the three data steps and
+`updateCheck`. Toggle them on the Settings page or in `n-seo.config.json`.
 
 | Module | What it does | Needs | Default |
 |---|---|---|---|
@@ -293,6 +314,7 @@ on the Settings page or in `n-seo.config.json`.
 | `staticExport` | Snapshots the dashboard into `site/` as static HTML | nothing | off |
 | `gitAutoCommit` | Commits (and pushes) the daily log and export after each run | a git remote, if you want the push | off |
 | `notifications` | macOS notification when a daily step fails | macOS | off |
+| `updateCheck` | Once per run, asks the registry whether a newer engine shipped, and notes it on Settings and in `doctor` | nothing | **on** |
 
 ## Working with n-dx
 

package/bin/n-seo.mjs

@@ -39,7 +39,8 @@ usage: n-seo <command> [--instance <dir>] [args...]
   mcp             the read-only MCP server on stdio (for .mcp.json)
   export          static export of the dashboard into <instance>/site/
   check           engine self-test: typecheck + unit tests
-  upgrade         update the engine (git pull / npm ci / check) with a rollback hint
+  upgrade         update the engine in place, whatever way it was installed;
+                  --check reports what is available without changing anything
   version         engine version, commit, paths, mode
   help            this text
 
@@ -377,9 +378,133 @@ setup guide: ${path.join(ROOT, "docs", "SETUP-GOOGLE.md")}
 
 const sha256 = (p) => (fs.existsSync(p) ? createHash("sha256").update(fs.readFileSync(p)).digest("hex") : "");
 
-function upgrade(instance) {
-  if (!isGitEngine()) {
-    console.log("engine installed from npm — run: npm update n-seo");
+/** Where this engine came from, and therefore how to upgrade it.
+ *
+ *  This used to print `npm update n-seo` for every npm install. That command
+ *  is right for exactly one layout — a consumer package.json with n-seo as a
+ *  dependency — and silently wrong for the global install the README
+ *  recommends: it reports "up to date", exits 0, upgrades nothing, and drops
+ *  a stray package-lock.json in whatever directory you ran it from. */
+function installKind() {
+  if (isGitEngine()) return { kind: "git", label: "git checkout" };
+
+  const modules = path.dirname(ROOT);              // .../node_modules
+  if (path.basename(modules) !== "node_modules") {
+    return { kind: "unknown", label: "unrecognised layout" };
+  }
+  let globalRoot = null;
+  try {
+    globalRoot = execFileSync(npmBin(), ["root", "-g"], { stdio: ["ignore", "pipe", "ignore"] }).toString().trim();
+  } catch { /* npm not on PATH; fall through to the path-shape checks */ }
+
+  if (globalRoot && path.resolve(globalRoot) === path.resolve(modules)) {
+    return { kind: "npm-global", label: "npm, global", args: ["install", "-g"] };
+  }
+  // A global install under a custom prefix lives in <prefix>/lib/node_modules,
+  // and its bin symlink is in <prefix>/bin — so it has to be upgraded with -g
+  // against that prefix, not as a plain local install.
+  if (path.basename(path.dirname(modules)) === "lib") {
+    const prefix = path.dirname(path.dirname(modules));
+    return { kind: "npm-global", label: `npm, global (prefix ${prefix})`, args: ["install", "-g", "--prefix", prefix] };
+  }
+  const dir = path.dirname(modules);
+  return { kind: "npm-local", label: `npm, in ${dir}`, args: ["install", "--prefix", dir] };
+}
+
+/** The version the registry serves, or null if it cannot be reached.
+ *  `npm view` is used rather than a direct fetch so a private registry,
+ *  proxy or .npmrc scope configuration is honoured. */
+function registryVersion() {
+  try {
+    const out = execFileSync(npmBin(), ["view", `${PKG.name}@latest`, "version"],
+      { stdio: ["ignore", "pipe", "ignore"], timeout: 20_000 }).toString().trim();
+    return /^\d+\.\d+\.\d+/.test(out) ? out : null;
+  } catch {
+    return null;
+  }
+}
+
+const RELEASES = "https://github.com/en-dash-consulting/n-seo/releases/tag/v";
+
+/** One version's section of the engine's own CHANGELOG.md, if it ships one. */
+function changelogSection(version) {
+  const file = path.join(ROOT, "CHANGELOG.md");
+  if (!fs.existsSync(file)) return null;
+  const lines = fs.readFileSync(file, "utf8").split("\n");
+  const start = lines.findIndex((l) => l.startsWith(`## [${version}]`));
+  if (start === -1) return null;
+  let end = lines.length;
+  for (let i = start + 1; i < lines.length; i++) {
+    if (lines[i].startsWith("## ")) { end = i; break; }
+  }
+  const body = lines.slice(start + 1, end)
+    .filter((l) => !/^\[[^\]]+\]:\s/.test(l))
+    .join("\n").trim();
+  return body || null;
+}
+
+function upgradeNpm(install, check) {
+  const current = PKG.version;
+  console.log(`engine     ${PKG.name} ${current}   ${install.label}`);
+  const latest = registryVersion();
+  if (!latest) {
+    console.error("registry   unreachable — check the network, or your registry configuration");
+    return 1;
+  }
+  const upToDate = latest === current;
+  console.log(`registry   ${PKG.name} ${latest}   ${upToDate ? "— up to date" : "— newer"}`);
+
+  if (upToDate) return 0;
+  if (check) {
+    console.log(`\nupgrade with: n-seo upgrade`);
+    console.log(`release notes: ${RELEASES}${latest}`);
+    return 0;
+  }
+
+  const args = [...install.args, `${PKG.name}@${latest}`];
+  console.log(`\nupgrading  ${npmBin()} ${args.join(" ")}\n`);
+  const r = spawnSync(npmBin(), args, { stdio: "inherit" });
+  if (r.status !== 0) {
+    console.error(`\nupgrade failed. The engine is still ${current}; nothing in your instance was touched.`);
+    return r.status ?? 1;
+  }
+
+  console.log(`\n${PKG.name} ${current} → ${latest}`);
+  // Read the changelog from the *new* install: this is "what you just got".
+  const notes = changelogSection(latest);
+  if (notes) {
+    console.log("\nwhat changed\n");
+    for (const line of notes.split("\n")) console.log(`  ${line}`);
+  }
+  console.log(`\nfull notes  ${RELEASES}${latest}`);
+  console.log(`\nrestart the dashboard so it picks this up:`);
+  console.log(`  n-seo start${process.platform === "darwin" ? "   (or, if it runs under launchd: launchctl kickstart -k gui/$(id -u)/<label>)" : ""}`);
+  console.log(`\nroll back with:\n  ${npmBin()} ${[...install.args, `${PKG.name}@${current}`].join(" ")}`);
+  return 0;
+}
+
+function upgrade(instance, check = false) {
+  const install = installKind();
+  if (install.kind === "npm-global" || install.kind === "npm-local") {
+    return upgradeNpm(install, check);
+  }
+  if (install.kind === "unknown") {
+    console.error(`cannot tell how this engine was installed (${ROOT}).`);
+    console.error("upgrade it the way you installed it, then run: n-seo check");
+    return 1;
+  }
+  if (check) {
+    console.log(`engine     ${PKG.name} ${PKG.version}   git checkout at ${ROOT}`);
+    const r = spawnSync("git", ["-C", ROOT, "fetch", "--quiet"], { stdio: "inherit" });
+    if (r.status === 0) {
+      try {
+        const behind = execFileSync("git", ["-C", ROOT, "rev-list", "--count", "HEAD..@{u}"],
+          { stdio: ["ignore", "pipe", "ignore"] }).toString().trim();
+        console.log(behind === "0" ? "remote     up to date" : `remote     ${behind} commit(s) ahead — run: n-seo upgrade`);
+      } catch {
+        console.log("remote     no upstream branch configured");
+      }
+    }
     return 0;
   }
   const before = gitCommit();
@@ -457,7 +582,7 @@ switch (cmd) {
     code = run(py, [path.join(ROOT, "ops", "export_static.py"), ...rest], instance);
     break;
   case "upgrade":
-    code = upgrade(instance);
+    code = upgrade(instance, rest.includes("--check"));
     break;
   case "version": {
     const mode = instance === ROOT ? "in-place" : "instance";

package/docs/ARCHITECTURE.md

@@ -200,7 +200,7 @@ the reports shows them.
 |---|---|
 | `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 upgrade` | Detects the install shape and does the 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 (global, custom prefix, or local): installs the published latest with the right flags for that layout, then prints the new CHANGELOG section and the rollback command. `--check` reports without changing anything |
 | `n-seo version` | engine version, commit, engine path, instance path, mode |
 
 ## Operating rules the tooling encodes

package/docs/INSTANCE.md

@@ -232,16 +232,17 @@ npx n-seo init .
     "daily": "n-seo daily",
     "doctor": "n-seo doctor",
     "export": "n-seo export",
-    "upgrade": "npm update n-seo && n-seo check"
+    "upgrade": "n-seo upgrade && n-seo check"
   },
   "dependencies": { "n-seo": "github:en-dash-consulting/n-seo" }
 }
 ```
 
 The engine lives in `node_modules/n-seo`; the instance is the current
-directory. `n-seo upgrade` recognizes an npm install and tells you to run
-`npm update n-seo` instead of pulling. Pin with a version or a commit
-(`github:en-dash-consulting/n-seo#<sha>`) when you need to.
+directory. `n-seo upgrade` recognizes this layout and installs the published
+latest into it; `n-seo upgrade --check` reports without changing anything.
+Pin with a version or a commit (`github:en-dash-consulting/n-seo#<sha>`) when
+you need to.
 
 Python is still required on the machine — the engine's ingest scripts run
 with `python3` from the package directory.

package/docs/PRD.md

@@ -29,8 +29,13 @@ with evidence attached, and measure yesterday's changes.
 ## Principles (non-negotiable)
 
 1. **Local-first.** All data lives in files on the owner's machine. The only
-   outbound calls are to Google APIs the owner authorized and to a local LLM
-   command the owner configured.
+   outbound calls are to Google APIs the owner authorized, the LLM provider
+   the owner configured, and — once per daily run, from the `updateCheck`
+   module — a public registry query for the engine's own latest version. That
+   last one is the only thing enabled by default that talks to a third party;
+   it sends nothing about the instance and is disabled in one line. The
+   dashboard itself never makes a network request, so every page renders with
+   the machine offline.
 2. **It briefs; it never acts on the owner's behalf.** No module posts,
    sends, publishes, or edits a site. Community modules produce briefings,
    never comment text.
@@ -170,8 +175,12 @@ engine (e.g. `instance/src/extensions.ts`).
 # Epic: Modules (opt-in) [shipped]
 
 - Acceptance: each of indexStatus, metadataAudit, opportunityScan, llm,
-  hackerNews, reddit, indexNow, staticExport, gitAutoCommit, notifications is
-  gated by `modules.<key>.enabled`; a disabled digest exits 0 with a message.
+  hackerNews, reddit, indexNow, staticExport, gitAutoCommit, notifications,
+  updateCheck is gated by `modules.<key>.enabled`; a disabled digest exits 0
+  with a message.
+- Acceptance: `updateCheck` is the only module enabled by default. It writes
+  `data/update-check.json`, exits 0 when the registry is unreachable without
+  disturbing the previous result, and makes no request at all when disabled.
 - Acceptance: the LLM module runs any command that reads a prompt on stdin;
   when unavailable, the scan records candidates only and digests skip
   briefings.
@@ -229,10 +238,19 @@ instead of a CLI, with the key read from `.env`.
   scaffolds an instance; the `files` list excludes tests and the marketing
   site, and includes the instance-facing skills.
 
-## Feature: Scheduled upgrade with gate [planned]
-
-A documented weekly job (`n-seo upgrade`) with notification on failure, so
-instances exercise the upgrade path routinely.
+## Feature: Upgrading is visible and one command [shipped]
+
+- Acceptance: `n-seo upgrade` detects how the engine was installed — git
+  checkout, npm global (including a custom prefix), npm local — and performs
+  the upgrade itself rather than printing advice. It prints the old and new
+  versions, the section of the new CHANGELOG, the rollback command, and a
+  reminder to restart the dashboard.
+- Acceptance: `n-seo upgrade --check` reports what is available and changes
+  nothing.
+- Acceptance: a newer published version is shown on the Settings page and in
+  `doctor`, both read from `data/update-check.json` rather than the network,
+  and both compare against the engine running now — so an upgrade stops the
+  notice immediately rather than at the next daily run.
 
 # Epic: Quality [shipped]
 

package/ingest/seo_config.py

@@ -40,12 +40,18 @@ EXAMPLE_PATH = ROOT / "n-seo.config.example.json"
 MODULE_KEYS = [
     "indexStatus", "metadataAudit", "opportunityScan", "llm", "hackerNews",
     "reddit", "indexNow", "staticExport", "publish", "gitAutoCommit",
-    "notifications",
+    "notifications", "updateCheck",
 ]
 
 # Per-module defaults, so a half-written block cannot make a step guess.
 # Mirrors MODULE_DEFAULTS in src/config.ts.
 MODULE_DEFAULTS = {
+    # The one module that ships on. Everything else here is opt-in, but an
+    # engine that never mentions its own updates leaves people running old
+    # code without knowing it. One public metadata request a day, carrying
+    # nothing about this instance, and `"updateCheck": {"enabled": false}`
+    # stops it for good.
+    "updateCheck": {"enabled": True},
     "staticExport": {"signOutUrl": "", "signOutLabel": "Sign out"},
     "publish": {"target": "gcs", "destination": "", "command": "",
                 "delete": False, "dryRun": False, "env": {}},

package/n-seo.config.example.json

@@ -100,6 +100,9 @@
     },
     "notifications": {
       "enabled": false
+    },
+    "updateCheck": {
+      "enabled": true
     }
   },
   "hooks": {

package/ops/daily.py

@@ -39,6 +39,9 @@ LOG = seo_config.DATA / "daily-ops.log"
 
 # (name, script, module gate or None)
 STEPS = [
+    # First, and cheap: "a newer version exists" belongs at the top of the
+    # log, not buried under forty minutes of pulls.
+    ("update-check",     "ops/update_check.py",           "updateCheck"),
     ("probe",            "probes/site_probe.py",          None),
     ("gsc",              "ingest/pull_gsc.py",            None),
     ("ga4",              "ingest/pull_ga4.py",            None),

package/ops/doctor.py

@@ -35,6 +35,24 @@ def check_engine():
            else "config, queue and data live inside the engine checkout (see docs/INSTANCE.md to split them)")
     report("OK", f"engine: {e['root']}")
     report("OK", f"instance: {e['instance']}")
+    # From the file the daily run writes, never a fresh request: doctor is
+    # something people run when something is already wrong, often offline,
+    # and it should not hang on a registry.
+    try:
+        u = json.loads((seo_config.DATA / "update-check.json").read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        u = None
+    if u and u.get("latest"):
+        def parts(v):
+            bits = str(v).split(".")[:3]
+            return tuple(int(b) for b in bits) if len(bits) == 3 and all(b.isdigit() for b in bits) else None
+        cur, new_ = parts(e["version"]), parts(u["latest"])
+        if cur and new_ and new_ > cur:
+            report("WARN", f"n-seo {u['latest']} is available", "upgrade with: n-seo upgrade")
+        else:
+            report("OK", f"n-seo {e['version']} is current", f"checked {u.get('checked', '?')}")
+    elif seo_config.module("updateCheck").get("enabled"):
+        report("OK", "update check has not run yet", "it runs with the daily run")
 
 
 def check_config():

package/ops/update_check.py

@@ -0,0 +1,113 @@
+#!/usr/bin/env python3
+"""Ask the registry whether a newer engine has been published.
+
+Nothing else in n-seo checks for updates, so before this existed the only way
+to learn that a release had happened was to go and look. That is a poor deal
+for a tool you schedule and then stop thinking about.
+
+Two rules this obeys, because the promise on the tin is that your data stays
+put:
+
+1. **Only this step talks to the registry.** The dashboard never does — it
+   reads the file written here, so opening a page makes no outbound request
+   and works with the network unplugged.
+2. **It is a module, and it can be switched off.** `modules.updateCheck`.
+   The request carries no instance data: it is the same public metadata
+   request `npm view n-seo version` makes from any machine.
+
+Writes data/update-check.json. Pure stdlib; runs unattended from ops/daily.py.
+"""
+
+import json
+import re
+import shutil
+import subprocess
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent / "ingest"))
+import seo_config  # noqa: E402
+
+DATA = seo_config.DATA
+OUT = DATA / "update-check.json"
+PACKAGE = "n-seo"
+RELEASES = "https://github.com/en-dash-consulting/n-seo/releases/tag/v"
+
+SEMVER = re.compile(r"^(\d+)\.(\d+)\.(\d+)")
+
+
+def parts(v: str):
+    """(1, 2, 3) from '1.2.3', or None if it is not a plain release version."""
+    m = SEMVER.match(v or "")
+    return tuple(int(g) for g in m.groups()) if m else None
+
+
+def npm_bin() -> str:
+    return "npm.cmd" if sys.platform == "win32" else "npm"
+
+
+def published_version() -> str | None:
+    """What the registry serves.
+
+    `npm view` rather than a direct fetch, so a private registry, a proxy or
+    an .npmrc setting is honoured — someone running an internal mirror should
+    be told about *their* latest, not npmjs.com's.
+    """
+    npm = shutil.which(npm_bin())
+    if not npm:
+        return None
+    try:
+        out = subprocess.run(
+            [npm, "view", f"{PACKAGE}@latest", "version"],
+            capture_output=True, text=True, timeout=45, encoding="utf-8",
+        )
+    except (subprocess.TimeoutExpired, OSError):
+        return None
+    if out.returncode != 0:
+        return None
+    v = (out.stdout or "").strip()
+    return v if parts(v) else None
+
+
+def main() -> int:
+    m = seo_config.module("updateCheck")
+    if not m.get("enabled"):
+        print("updateCheck module is off — skipping (no registry request made)")
+        return 0
+
+    engine = seo_config.engine_info()
+    current = engine.get("version", "0.0.0")
+    latest = published_version()
+
+    if latest is None:
+        # Never a failure: an offline morning must not fail the daily run over
+        # a version check, and a stale file is better than no file.
+        print("could not reach the registry — leaving the last result in place")
+        return 0
+
+    cur_p, new_p = parts(current), parts(latest)
+    newer = bool(cur_p and new_p and new_p > cur_p)
+    ahead = bool(cur_p and new_p and cur_p > new_p)
+
+    DATA.mkdir(parents=True, exist_ok=True)
+    OUT.write_text(json.dumps({
+        "checked": datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%MZ"),
+        "current": current,
+        "latest": latest,
+        "newer": newer,
+        "notes": f"{RELEASES}{latest}" if newer else "",
+    }, indent=1) + "\n", encoding="utf-8")
+
+    if newer:
+        print(f"n-seo {latest} is available (running {current}) — upgrade with: n-seo upgrade")
+        print(f"  release notes: {RELEASES}{latest}")
+    elif ahead:
+        print(f"running {current}, ahead of the published {latest} — a development build")
+    else:
+        print(f"n-seo {current} is the latest")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "n-seo",
-  "version": "0.3.3",
+  "version": "0.4.0",
   "description": "Agentic, local-first SEO / AEO / GEO control plane: pulls Search Console + GA4, probes your sites, and ranks the next moves. Your LLM writes the proposals; your coding agent works the queue over MCP.",
   "license": "MIT",
   "author": "En Dash Consulting (https://endash.us)",
@@ -57,6 +57,7 @@
     "!.claude/skills/README.md",
     "docs/",
     "README.md",
+    "CHANGELOG.md",
     "LICENSE"
   ],
   "engines": {

package/public/styles.css

@@ -151,6 +151,7 @@ a { color: var(--accent); }
 .chip.ai, .chip.src { background: var(--accent-soft); color: var(--accent); }
 .chip.good { background: var(--good-soft); color: var(--good); }
 .chip.bad { background: var(--bad-soft); color: var(--bad); }
+.chip.warn { background: var(--warn-soft); color: var(--warn); }
 .chip.impact { background: var(--good-soft); color: var(--good); }
 .chip.effort.e-S { background: var(--code-bg); color: var(--muted); }
 .chip.effort.e-M { background: var(--warn-soft); color: var(--warn); }

package/src/config.ts

@@ -107,6 +107,8 @@ export interface Config {
 /** Per-module defaults, so a half-written block cannot make a step guess.
  *  Mirrors MODULE_DEFAULTS in ingest/seo_config.py. */
 export const MODULE_DEFAULTS: Record<string, Record<string, unknown>> = {
+  // The one module that ships on — see the note in ingest/seo_config.py.
+  updateCheck: { enabled: true },
   staticExport: { signOutUrl: "", signOutLabel: "Sign out" },
   publish: { target: "gcs", destination: "", command: "", delete: false, dryRun: false, env: {} },
 };
@@ -123,6 +125,7 @@ export const MODULE_INFO: { key: string; title: string; blurb: string; needs?: s
   { key: "publish", title: "Publish the mirror", blurb: "Copy site/ to a bucket, an object store or a box over ssh after the export — a real pipeline step, so it is logged and retried like the rest. `dryRun` prints the command without running it, which is how you rehearse a cutover.", needs: "gcloud, aws or rsync on PATH, depending on the target" },
   { key: "gitAutoCommit", title: "Git auto-commit", blurb: "Commit the daily log and export after each run (and push if a remote is set)." },
   { key: "notifications", title: "Desktop notifications", blurb: "macOS notification when a daily step fails (osascript)." },
+  { key: "updateCheck", title: "Update check", blurb: "Once a day, during the run, ask the registry whether a newer engine has been published and note it on this page. The only module that is on by default. The dashboard itself never makes the request — it reads the result — so pages still render with no network. Nothing about this instance is sent." },
 ];
 
 function readJson<T>(p: string): T {

package/src/data.ts

@@ -4,7 +4,7 @@
  *  long-lived process (dashboard, MCP server) honest about what is on disk. */
 import fs from "node:fs";
 import path from "node:path";
-import { ROOT, INSTANCE, config, gscDataSlug, type SiteCfg } from "./config.js";
+import { ROOT, INSTANCE, ENGINE_VERSION, config, gscDataSlug, type SiteCfg } from "./config.js";
 import { BACKLOG_PATH } from "./backlog.js";
 
 const DATA = path.join(INSTANCE, "data");
@@ -736,6 +736,32 @@ export function opsLogTail(maxLines = 150): string {
 
 export interface LastRun { ts: string; failures: string; steps?: { name: string; ok: boolean; seconds?: number }[] }
 
+export interface UpdateCheck { checked: string; current: string; latest: string; newer: boolean; notes: string }
+
+/** What ops/update_check.py last learned from the registry.
+ *
+ *  Read-only, from disk. The server makes no network request of its own —
+ *  a dashboard whose pages depend on reaching npmjs.com would be slower, and
+ *  would break the promise that this thing works with the network unplugged. */
+export function updateCheck(): UpdateCheck | null {
+  const r = readJson<Partial<UpdateCheck>>(path.join(DATA, "update-check.json"));
+  if (!r?.latest) return null;
+  // `newer` is recomputed against the engine running right now rather than
+  // trusted from the file. Upgrading does not rewrite it — only the next
+  // daily run does — so the stored flag would keep advertising an update you
+  // have already installed, for up to a day.
+  const parse = (v: string) => /^\d+\.\d+\.\d+/.test(v) ? v.split(".", 3).map(Number) : null;
+  const now = parse(ENGINE_VERSION), latest = parse(r.latest);
+  const newer = !!(now && latest && (latest[0] - now[0] || latest[1] - now[1] || latest[2] - now[2]) > 0);
+  return {
+    checked: r.checked ?? "",
+    current: ENGINE_VERSION,
+    latest: r.latest,
+    newer,
+    notes: r.notes ?? "",
+  };
+}
+
 export function lastRun(): LastRun | null {
   const r = readJson<Partial<LastRun>>(path.join(DATA, "last-run.json"));
   if (!r) return null;

package/src/settings.tsx

@@ -31,6 +31,7 @@ export const SettingsPage: FC<{ saved?: boolean; error?: string }> = ({ saved, e
   const sa = serviceAccountEmail(cfg.google.serviceAccountKey);
   const lr = data.lastRun();
   const eng = engineInfo();
+  const upd = data.updateCheck();
   const hookCount = cfg.hooks.beforeRun.length + cfg.hooks.afterRun.length + Object.values(cfg.hooks.afterStep).reduce((n, l) => n + l.length, 0);
   const str = (v: unknown) => (v == null ? "" : String(v));
   return (
@@ -51,7 +52,11 @@ export const SettingsPage: FC<{ saved?: boolean; error?: string }> = ({ saved, e
       <h2>Engine <small>— what is running, and where</small></h2>
       <div class="settings-grid">
         <div class="s-card">
-          <div class="s-title">n-seo {eng.version}{eng.commit ? ` · ${eng.commit}` : ""}</div>
+          <div class="s-title">
+            n-seo {eng.version}{eng.commit ? ` · ${eng.commit}` : ""}
+            {upd?.newer && <span class="chip warn" title={`checked ${upd.checked}`}> {upd.latest} available</span>}
+            {upd && !upd.newer && <span class="chip good" title={`checked ${upd.checked}`}> latest</span>}
+          </div>
           <p class="sub"><span class={`chip ${eng.mode === "instance" ? "good" : ""}`}>{eng.mode}</span> {eng.mode === "instance"
             ? "the engine and this instance live in separate directories; upgrading the engine does not touch your config, queue or data."
             : "config, queue and data live inside the engine checkout. Fine for one person; see docs/INSTANCE.md to split them."}</p>
@@ -59,7 +64,16 @@ export const SettingsPage: FC<{ saved?: boolean; error?: string }> = ({ saved, e
         <div class="s-card">
           <div class="s-title">Engine path</div>
           <div class="mono">{eng.root}</div>
-          <p class="sub">Upgrade: <code>n-seo upgrade</code> (git engine) or <code>npm update n-seo</code> (npm engine).</p>
+          <p class="sub">
+            Upgrade with <code>n-seo upgrade</code>, whatever way it was installed.
+            {" "}<code>n-seo upgrade --check</code> reports without changing anything.
+          </p>
+          {upd?.newer && (
+            <p class="sub">
+              <b>{upd.latest} is available.</b> Your config, queue and content are untouched by an upgrade.
+              {upd.notes && <> <a href={upd.notes} target="_blank" rel="noopener noreferrer">Release notes →</a></>}
+            </p>
+          )}
         </div>
         <div class="s-card">
           <div class="s-title">Instance path</div>