n-seo 0.1.0

package/docs/PLAYBOOK.md

@@ -0,0 +1,122 @@
+# Search and answer-engine growth playbook
+
+How to grow organic traffic across one or more sites with this tool: **SEO**
+(classic search), **AEO** (answer engines — featured snippets, People Also
+Ask, AI Overviews) and **GEO** (generative engines — ChatGPT, Claude,
+Perplexity citing or recommending your pages). No paid ads assumed.
+
+## The operating loop: four planes
+
+1. **Awareness (data in).** Pull Search Console and GA4 on a schedule; probe
+   the live sites. Snapshot everything — rankings and AI-crawler behavior only
+   make sense as trends. This is `ops/daily.py`.
+2. **Analysis.** Turn the snapshots into questions with answers: which
+   queries earn impressions but not clicks (title/description problem)? Which
+   pages rank 5–15 (small changes move them to page one)? Which sitemap URLs
+   has Google never fetched? Are AI crawlers allowed in? This is the action
+   engine, the metadata audit, the indexing sweep, and the trend analysis.
+3. **Action.** Ship the change in the site's own repo: a rewritten title, an
+   answer-formatted section, structured data, internal links, an `llms.txt`.
+   Ping IndexNow, resubmit the sitemap, request indexing where it matters.
+4. **Measurement.** The next day's pull scores the last change. Every
+   metadata change is dated so movement can be attributed, and stays in view
+   as *watching* until the data speaks.
+
+The dashboard is the awareness plane; you (optionally with an AI agent reading
+the MCP server) are analysis and action.
+
+## What actually moves each discipline
+
+### SEO — Google and Bing organic
+
+- **Crawlability first.** Correct `robots.txt`, a complete `sitemap.xml` with
+  honest `lastmod`, real 404s (unknown paths return 404, not 200), one
+  canonical host (https, and one of www/apex), canonical tags. The probe
+  checks these daily; regressions are the cheapest thing to fix and the most
+  common way SEO dies on a deploy.
+- **Server-rendered content.** If the raw HTML is a JavaScript shell, Google
+  mostly copes but Bing and every AI crawler see nothing. The probe reports
+  visible text bytes on the homepage; under ~500 bytes usually means a shell.
+  Static or server rendering is the single highest-leverage technical fix for
+  a client-rendered site.
+- **Indexed before ranked.** A page can sit in the sitemap for months as
+  "Discovered — currently not indexed" and look identical to a page nobody
+  searches for (both show zero impressions). The `/indexing` page separates
+  the two. Spend manual "Request Indexing" quota on never-crawled pages that
+  matter; a resubmitted sitemap and internal links move the rest.
+- **Striking distance.** Queries at position 5–15 with real impressions are
+  the best return per hour in SEO: add a section that answers the query
+  verbatim (H2 phrased as the query, then a 40–60 word direct answer), add
+  two or three internal links with the query as anchor text, update the
+  modified date.
+- **Title and description CTR.** High impressions and low CTR at a good
+  position means the snippet is losing the click. Rewrite the title as the
+  answer to the query (front-load the query words, stay under ~60
+  characters); make the description one ~150-character sentence that
+  answers it. Then leave it alone for 28 days.
+- **Internal linking.** Most small sites barely link within themselves or to
+  their sibling sites. Related-content blocks and footer cross-links pass
+  authority from the pages that have it to the ones that need it.
+- **Core Web Vitals.** Matters at the margin. Check occasionally; don't
+  obsess.
+
+### AEO — featured snippets, People Also Ask, AI Overviews
+
+- **Answer-formatted pages.** A question as an H2, a 40–60 word direct
+  answer immediately below it, then elaboration. This is the shape snippets
+  and AI Overviews lift.
+- **Structured data that fits.** `FAQPage`, `HowTo`, `Article`,
+  `SoftwareApplication`, `Dataset` — whichever the page honestly is. The
+  probe lists the JSON-LD types on each homepage.
+- **Tables, ordered lists, definitions.** These get extracted far more often
+  than prose walls. A comparison table between the hero and the body of a
+  "X vs Y" page is a snippet magnet.
+
+### GEO — being cited by ChatGPT, Claude, Perplexity
+
+- **Let AI crawlers in.** `robots.txt` must not block GPTBot, ClaudeBot,
+  Claude-Web, PerplexityBot, Google-Extended, CCBot, Bytespider,
+  OAI-SearchBot — the probe flags any that are. Blocked crawlers cannot cite
+  you.
+- **`llms.txt` and `llms-full.txt`.** A markdown summary of the site with
+  links to the pages that matter (and, in the full version, the content
+  itself). Regenerate on every publish. The probe checks both exist.
+- **Be the canonical explainer for a niche.** Language models cite pages
+  that define or explain a thing plainly, with concrete numbers, code and
+  steps. Generic content does not get cited; firsthand specifics do.
+- **Freshness.** Generative engines over-select recently updated pages. Real
+  content changes that move the modified date compound.
+- **Measure it.** GA4 referral sessions from chatgpt.com, perplexity.ai,
+  claude.ai, copilot.microsoft.com, gemini.google.com — the dashboard shows
+  them per site and per month. This is the GEO scoreboard.
+
+## Data plane
+
+| Source | API | Auth | Gives you |
+|---|---|---|---|
+| Search Console | `searchconsole.googleapis.com` | service account (Full user on the property) | queries, impressions, CTR, position; sitemap state; per-URL index coverage |
+| GA4 | Analytics Data API | service account (Viewer on the property) | sessions, sources (incl. AI referrals), landing-page engagement, conversion events |
+| Live sites | plain HTTP | none | robots / sitemap / llms.txt / meta / SSR-ness / 404 behavior, daily |
+| IndexNow | `api.indexnow.org` | a key you host at `/{key}.txt` | instant Bing/Copilot/Yandex pings on publish (optional module) |
+| Hacker News, Reddit | public APIs | HN: none; Reddit: a free script app | threads where your expertise applies (optional modules; briefings only) |
+
+## Content loops that work
+
+- **Query gap → answer page.** The trend analysis surfaces rising queries no
+  page targets. Draft an answer-formatted page in the site repo, review,
+  ship, ping, watch.
+- **Publish hook.** When a page ships: regenerate sitemap and `llms.txt`,
+  add internal links from related pages, ping IndexNow, request indexing if
+  it is a page that matters.
+- **Regression sentinel.** The daily probe alerts when robots, sitemap,
+  canonical, `llms.txt` or server-rendered content silently breaks. Deploys
+  are where SEO dies; this is the smoke alarm.
+- **Weekly review.** Read the *watching* list against the daily log. Items
+  whose 28 days are up either graduate (data moved: note it, retire it) or
+  become a new action (data didn't: what else could explain it?).
+
+## What this tool will not do
+
+It does not edit your sites, post to communities, send outreach, or promote
+its own proposals into your queue. Those are the steps where judgment and
+authenticity live, and they stay with you.

package/docs/PRD.md

@@ -0,0 +1,249 @@
+# n-seo — Product Requirements
+
+This is the product definition the PRD tree in `.rex/` is generated from and
+kept in sync with. It states what n-seo is for, who it serves, what it
+deliberately does not do, and the capabilities that exist or are planned.
+Each feature lists acceptance criteria in the form a test or a reviewer can
+check. Status markers: **[shipped]**, **[planned]**, **[idea]**.
+
+## Purpose
+
+n-seo is a local-first control plane for organic growth across one or more
+websites: classic search (SEO), answer engines (AEO) and generative engines
+that cite sources (GEO). It replaces the monthly agency read-out with a loop
+that runs every morning on the owner's machine: pull Search Console and GA4,
+probe the live sites, turn the data into a ranked queue of concrete actions
+with evidence attached, and measure yesterday's changes.
+
+## Users
+
+- **A site owner or small team** who wants to hone their own SEO practice
+  without paying an agency: developers, indie makers, consultancies, small
+  businesses with a technical person.
+- **An operator running several sites** (a portfolio, an agency serving its
+  own clients) who needs one queue across all of them.
+- **An AI agent** (Claude Code, Claude Desktop, any MCP client) acting for
+  the owner, which needs the same data in machine-readable form and must not
+  be able to bypass the owner's approval gates.
+
+## 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.
+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.
+3. **Evidence before advice.** Every action shows the numbers behind it,
+   then the move, then a spec and a success criterion.
+4. **Encoded operating rules.** 28-day metadata freeze; ≈8 metadata changes
+   per week; decisions on the trailing 90 days, 16 months for history; impact
+   orders the queue and is never reported as a forecast; shipped work becomes
+   *watching*, never deleted; machine proposals never self-promote.
+5. **Upgradeable.** An instance (config, queue, content, data) is separable
+   from the engine so an upgrade is a pull, not a merge.
+6. **Stdlib Python, no-bundler TypeScript, no pip installs**, so "clone and
+   run" is literally true.
+
+## Non-goals
+
+- Not a rank tracker or keyword-research SaaS; it reads what Google already
+  reports about the owner's own sites.
+- Not an auto-publisher, link builder, or comment bot.
+- Not a hosted product; there is no account and no server-side component
+  beyond an optional static mirror the owner hosts.
+- Windows is not a target (WSL likely works; untested).
+
+---
+
+# Epic: Configuration and Google access [shipped]
+
+## Feature: One config file for every component [shipped]
+
+`n-seo.config.json` (path overridable by `N_SEO_CONFIG`) is read by the
+TypeScript app and every Python script; the example file is the fallback so
+a fresh checkout runs.
+
+- Acceptance: adding a site to `sites[]` makes it appear in every pull,
+  probe, audit, page and export with no other edit.
+- Acceptance: both loaders derive the same `data/gsc/<slug>` from a property
+  (`sc-domain:` and url-prefix forms).
+- Acceptance: unknown keys are preserved when the Settings page saves.
+
+## Feature: Service-account auth without gcloud [shipped]
+
+- Acceptance: with only a service-account JSON key and `openssl` on PATH,
+  `python3 ingest/google_auth.py` mints a token and lists accessible
+  properties.
+- Acceptance: gcloud impersonation and gcloud user modes remain selectable.
+- Acceptance: `ops/doctor.py` reports the exact email to add in Search
+  Console and GA4 and which configured properties are not yet accessible.
+
+# Epic: Ingest [shipped]
+
+## Feature: Search Console pulls [shipped]
+
+- Acceptance: per property, `queries`, `pages`, `query_page`, `dates` for the
+  16-month window and `*_90d` for the trailing 90 days; transient failures
+  retried; a 4xx fails loudly.
+- Acceptance: `gscExtraProperties` are pulled into `data/gsc/<slug>` without
+  appearing in the UI.
+
+## Feature: GA4 pulls [shipped]
+
+- Acceptance: `daily`, `sources`, `landing` per configured property id; a
+  `funnel` report only for `conversions.site`, falling back when the custom
+  dimension is unregistered.
+
+## Feature: Time series, index coverage, metadata audit, trend analysis [shipped]
+
+- Acceptance: date × page series for 180 days from both sources.
+- Acceptance: URL Inspection verdict for every sitemap URL (sitemap indexes
+  followed one level, ≤400 URLs/host), with sitemap submission state.
+- Acceptance: metadata audit flags title/query mismatch, CTR below position
+  expectation, missing/short/duplicate descriptions, long titles.
+- Acceptance: trend file with branded/generic split, rising/falling queries
+  (84d vs prior 84d), monthly trajectory and AI-referral sessions by month.
+
+# Epic: Live-site probe [shipped]
+
+- Acceptance: robots.txt (incl. AI-crawler disallows), sitemap.xml, llms.txt
+  and llms-full.txt, homepage metadata/JSON-LD/visible-text bytes, and a real
+  404 check, per configured host, written as a timestamped snapshot.
+- Acceptance: the daily diff raises an ALERT line on any regression versus
+  the previous snapshot.
+
+# Epic: Action engine [shipped]
+
+- Acceptance: six rules over the 90-day window (metadata findings, CTR
+  gaps, striking distance, probe hygiene, engagement mismatch, traffic drop)
+  produce actions with id, host, title, kind, why, how, spec[], impact,
+  effort, tag, source.
+- Acceptance: ranking is impact / effort weight (S=1, M=2.5, L=5).
+- Acceptance: metadata findings suppress CTR-gap cards on the same page.
+- Acceptance: pages in `shippedWatch` render as *watching*.
+- Acceptance: `config/backlog.json` is merged and hot-reloaded without a
+  restart, and a syntax error keeps the last good queue.
+
+## Feature: Rule thresholds in config [planned]
+
+Move the numeric thresholds (min impressions, position band, engagement
+floor, drop percentage, effort weights) into an optional `rules` block of
+the config with the current values as defaults.
+
+- Acceptance: every threshold has a documented default and a config
+  override; tests cover an override changing a rule's output.
+
+# Epic: Dashboard [shipped]
+
+- Acceptance: routes `/`, `/actions`, `/insights`, `/trends[/N]`,
+  `/content`, `/drafts/:slug`, `/campaigns/:slug`, `/site/:host`,
+  `/indexing`, `/probes`, `/logs`, `/settings`, `/api/actions` all render
+  from demo data with no server error.
+- Acceptance: Today board groups Fix / Approve / Publish / Comment / Ship;
+  Comment appears only when a participation module is enabled.
+- Acceptance: proposals can be accepted into the backlog; backlog items can
+  be marked watching or retired; rule-derived items expose no write buttons.
+- Acceptance: the server binds 127.0.0.1 by default and rejects cross-origin
+  POSTs.
+- Acceptance: light and dark themes; no external fonts.
+
+## Feature: Settings page [shipped]
+
+- Acceptance: toggles every module, edits digest topics, expertise, watch
+  pages and conversions, and writes the config file (creating it from the
+  example on first save); invalid topic lines are rejected with a message.
+
+## Feature: Custom pages and rules in instance mode [idea]
+
+Allow an instance to register extra routes and rules without forking the
+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.
+- Acceptance: the LLM module runs any command that reads a prompt on stdin;
+  when unavailable, the scan records candidates only and digests skip
+  briefings.
+- Acceptance: briefing prompts forbid generating comment text.
+
+## Feature: HTTP LLM adapter [planned]
+
+Optional adapter that calls an OpenAI-compatible or Anthropic HTTP endpoint
+instead of a CLI, with the key read from `.env`.
+
+## Feature: Bing Webmaster ingest [idea]
+
+## Feature: Core Web Vitals via CrUX [idea]
+
+# Epic: Daily run and scheduling [shipped]
+
+- Acceptance: `ops/daily.py` waits for the network, runs the enabled steps
+  in order, retries a failed step once, tees output to `data/daily-ops.log`,
+  writes `data/last-run.json` with per-step timing, honours `--only`,
+  `--skip`, `--list`, `--no-network-wait`, and exits 1 on any failure.
+- Acceptance: hooks (`beforeRun`, `afterRun`, `afterStep`) run in the
+  instance directory and are logged like steps without aborting the run.
+- Acceptance: launchd, cron and systemd templates plus an installer script.
+
+# Epic: MCP server [shipped]
+
+- Acceptance: stdio transport with no secret; HTTP transport that returns
+  503 with no token configured and compares tokens in constant time.
+- Acceptance: every tool is annotated read-only; tools cover the queue, a
+  single action, sites, per-site report, top queries, striking distance, CTR
+  gaps, metadata audit, time series, ops status, daily log, proposals,
+  conversions, campaigns, settings and engine info; docs exposed as
+  resources.
+
+# Epic: Engine and instance [shipped]
+
+- Acceptance: `N_SEO_INSTANCE` relocates every instance-owned path; in-place
+  mode is unchanged when it is unset.
+- Acceptance: `n-seo init|start|dev|daily|doctor|demo|mcp|check|export|
+  upgrade|version` behave as documented in `docs/INSTANCE.md`.
+- Acceptance: `n-seo upgrade` refuses to leave the engine on a commit that
+  fails `npm run check` without printing the rollback command.
+
+## Feature: Publish the engine to npm [planned]
+
+- Acceptance: `npm i n-seo` installs a working engine; `npx n-seo init`
+  scaffolds an instance; the `files` list excludes tests and the marketing
+  site.
+
+## Feature: Scheduled upgrade with gate [planned]
+
+A documented weekly job (`n-seo upgrade`) with notification on failure, so
+instances exercise the upgrade path routinely.
+
+# Epic: Quality [shipped]
+
+- Acceptance: `npm run check` runs typecheck, TypeScript tests (sandboxed
+  copy) and Python tests; CI runs both suites, a demo-data dashboard smoke,
+  `doctor --offline`, and a grep that fails on any private name.
+
+# Epic: Onboarding and docs [shipped]
+
+- Acceptance: `npm run demo` populates every page with synthetic data before
+  any Google setup.
+- Acceptance: README quickstart, SETUP-GOOGLE, SCHEDULING, ADDING-A-SITE,
+  INSTANCE, MCP, OPERATING-RULES, PLAYBOOK, FAQ, CONTRIBUTING, SECURITY,
+  CHANGELOG exist and match the CLI contracts.
+
+## Feature: Interactive setup wizard [idea]
+
+`n-seo init --guided`: asks for hosts, property ids and the key path, then
+runs doctor.
+
+# Epic: Marketing site [shipped]
+
+- Acceptance: `www/` is a single static page deployed by the Pages workflow,
+  with OG image, `llms.txt`, robots and sitemap; copy names the three
+  promises (local data, evidence first, briefs-not-acts) and the operating
+  rules.
+
+## Feature: Custom domain [planned]
+
+`www/CNAME` and URL updates once a domain is chosen.

package/docs/RELEASING.md

@@ -0,0 +1,189 @@
+# Releasing
+
+n-seo publishes to npm as **`n-seo`**, unscoped. The package name and the
+binary name match, which is why `npm i n-seo` gives you `npx n-seo` and not
+something longer.
+
+Releases are driven by tags. Pushing `v<version>` runs
+[`.github/workflows/release.yml`](../.github/workflows/release.yml), which
+refuses rather than guesses at every step: a tag that disagrees with
+`package.json`, or a version with no changelog section, stops the run before
+anything reaches the registry.
+
+## What counts as a breaking change
+
+The public contract is larger than the exported functions, because most people
+never import this package — they run it. Treat these as **major**:
+
+- **`n-seo.config.json`** — removing a key, renaming one, or changing what a
+  value means. Adding an optional key with a safe default is minor.
+- **The instance layout** — where `config/`, `content/`, `data/` and
+  `docs/daily-log.md` live, and which of them an upgrade may touch. Someone's
+  instance is a directory they back up; moving it silently is a breaking
+  change even though no code signature moved.
+- **The CLI verbs** and their arguments (`init`, `start`, `daily`, `doctor`,
+  `demo`, `mcp`, `export`, `check`, `upgrade`, `version`).
+- **The data-file shapes** in `docs/ARCHITECTURE.md`, since instances and
+  outside scripts read them.
+- **The MCP tool names and their inputs**, which agents call.
+
+Minor: new modules, new rules in the action engine, new pages, new data files.
+Patch: fixes that leave all of the above alone.
+
+The engine and an instance are versioned together — an instance pins an engine
+version, so a major bump is the signal to read the changelog before upgrading.
+
+## Pre-flight
+
+```sh
+git switch main && git pull
+git status --porcelain          # must be empty
+npm ci
+npm run check                   # typecheck + TypeScript tests + Python tests
+.github/scripts/pack-smoke.sh   # packs, installs, and drives the tarball
+```
+
+CI must be green on `main`. The `package` job is the one that matters most
+here: it installs the tarball into an empty project and drives the result,
+which is the only place packaging bugs are visible. Two shipped undetected
+before it existed — `tsx` sitting in `devDependencies`, and `tsconfig.json`
+missing from `files` — and a git checkout hides both.
+
+## Cut the release
+
+1. **Write the changelog.** Rename `## [Unreleased]` to
+   `## [<version>] - <YYYY-MM-DD>`, add a fresh empty `## [Unreleased]` above
+   it, and update the link definitions at the bottom of the file.
+
+2. **Bump the version.** `npm version` writes `package.json`, commits, and
+   tags in one step:
+
+   ```sh
+   npm version patch      # or minor, or major
+   ```
+
+   To keep the changelog commit and the version commit together, stage the
+   changelog first and use `npm version --no-git-tag-version`, then commit and
+   tag by hand:
+
+   ```sh
+   npm version 0.2.0 --no-git-tag-version
+   git add package.json package-lock.json CHANGELOG.md
+   git commit -m "Release 0.2.0"
+   git tag v0.2.0
+   ```
+
+3. **Push the tag.**
+
+   ```sh
+   git push origin main
+   git push origin v0.2.0
+   ```
+
+The workflow then checks the tag against `package.json`, checks the changelog
+has that section, runs the full suite, packs and drives the tarball,
+publishes with provenance, and opens a GitHub Release whose body is that
+changelog section.
+
+## The first release is different
+
+Two things are only true once.
+
+**Provenance needs a public repository.** `npm publish --provenance` attaches a
+signed attestation linking the tarball to the workflow run that built it.
+GitHub will not issue the OIDC token for that on a private repo, so the repo
+must be public before the first tag is pushed.
+
+**Trusted publishing cannot be configured until the package exists.** npm
+binds a trusted publisher to a package, and the settings page for it lives on
+the package — which does not exist before the first publish. PyPI allows
+configuring a publisher for a not-yet-existing project; npm does not
+([npm/cli#8544](https://github.com/npm/cli/issues/8544)).
+
+So something has to make version 0.1.0 exist. The best option is **not** a CI
+token: publish the first version by hand, from a machine, with interactive
+2FA. No long-lived credential is created and nothing is ever stored in the
+repository.
+
+1. Make the repository public (provenance requires it).
+2. From a clean checkout at the tagged commit:
+   ```sh
+   npm login                 # interactive, with 2FA
+   npm run check             # the suite
+   .github/scripts/pack-smoke.sh   # install the tarball and drive it
+   npm publish --access public
+   ```
+   Skip `--provenance` here: a local publish has no OIDC token to sign
+   against. Only the workflow can attach provenance.
+3. On npmjs.com, open the package → Settings → Trusted Publisher, and point it
+   at `en-dash-consulting/n-seo` with workflow `.github/workflows/release.yml`.
+4. `npm logout`, so the local session token dies too.
+
+Every release after that is just a tag. The workflow authenticates over OIDC,
+signs with provenance, and no secret exists in the repository at all.
+
+If you would rather automate even the first publish, a **granular access
+token** scoped to publish, with the shortest expiry npm offers, added as
+`NPM_TOKEN` and restored to the publish step as
+`NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}`, will do it. Delete the secret
+immediately afterwards. Prefer the manual route: npm is actively moving away
+from long-lived tokens, and 2FA-bypassing automation tokens for account
+management are being retired.
+
+### Why the workflow upgrades npm
+
+Node 22 ships npm 10, and trusted publishing needs **npm 11.5.1 or later**.
+Without the upgrade step the OIDC exchange never happens and the publish
+fails with a 404 that has nothing to do with the package being missing. The
+workflow also deliberately omits `registry-url` from `setup-node`, because it
+writes an `.npmrc` auth line interpolating `NODE_AUTH_TOKEN`, and an empty
+value there produces the same misleading 404.
+
+## Verify what was published
+
+Do not trust the workflow's own output. Install from the registry, into an
+empty directory, as a stranger would:
+
+```sh
+cd "$(mktemp -d)"
+npm init -y >/dev/null
+npm i n-seo
+npx n-seo version
+npx n-seo init ./inst
+npx n-seo demo --instance ./inst
+npx n-seo start --instance ./inst      # then open the port it prints
+```
+
+Check the npm page shows the provenance badge, the README renders, and
+`repository` and `homepage` resolve.
+
+## When a release is wrong
+
+**Prefer publishing a fix.** A new patch version is almost always better than
+removing one, because anything that already installed the bad version keeps
+working.
+
+Mark a bad version so nobody new installs it:
+
+```sh
+npm deprecate n-seo@0.2.0 "Broken packaging; use 0.2.1 or later."
+```
+
+If `latest` is pointing at the wrong version, move it:
+
+```sh
+npm dist-tag add n-seo@0.1.0 latest
+```
+
+Unpublishing is a last resort and npm's policy limits it to a 72-hour window
+for a version that nothing depends on:
+
+```sh
+npm unpublish n-seo@0.2.0
+```
+
+A version number is never reusable once published, even after unpublishing.
+Bump and move on.
+
+If a secret ever reaches the registry, treat the secret as compromised and
+rotate it first. Removing the tarball does not un-leak it.

package/docs/SCHEDULING.md

@@ -0,0 +1,104 @@
+# Scheduling the daily run and the dashboard
+
+Two things should always be running: the **dashboard** (a long-lived process
+serving the configured port) and the **daily run** (`ops/daily.py`, once a
+morning). Both are plain processes; pick the scheduler your OS already has.
+
+## macOS (launchd)
+
+The install script fills in the templates under `ops/templates/`, copies them
+to `~/Library/LaunchAgents`, and loads them:
+
+```sh
+ops/install-launchd.sh            # installs n-seo.dashboard and n-seo.daily
+ops/install-launchd.sh --uninstall
+```
+
+What it installs:
+
+| Label | Does | Log |
+|---|---|---|
+| `n-seo.dashboard` | `npx tsx src/server.tsx`, KeepAlive, starts at login | `data/dashboard.log` |
+| `n-seo.daily` | `python3 ops/daily.py` at 07:00 local | `data/daily-launchd.log` (launchd), `data/daily-ops.log` (the run itself) |
+
+Manual equivalent: copy the two plists from `ops/templates/`, replace
+`__REPO__`, `__NODE_BIN__` and `__HOME__`, then
+`launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.n-seo.*.plist`.
+
+**Runs on wake.** A `StartCalendarInterval` job that misses its slot because
+the machine was asleep fires as soon as the machine wakes. On wake the network
+is usually not up yet, which is why `ops/daily.py` waits (up to five minutes)
+for connectivity before it starts. A machine that stays shut all day skips
+that day; there is no catch-up.
+
+**After code changes** the dashboard service does not reload itself:
+
+```sh
+launchctl kickstart -k gui/$(id -u)/n-seo.dashboard
+```
+
+For iterative development use `npm run dev` in a terminal — but stop it
+before relying on the service again, since both bind the same port.
+
+## Linux (cron)
+
+```sh
+crontab -e
+```
+
+Paste the line from `ops/templates/n-seo.cron`, adjusting the path:
+
+```
+0 7 * * * cd /path/to/n-seo && /usr/bin/python3 ops/daily.py >> data/daily-cron.log 2>&1
+```
+
+Cron does not run missed jobs; if the machine is off at 07:00 that day is
+skipped. Run the dashboard with the systemd unit below, or with any process
+supervisor you already use.
+
+## Linux (systemd user units)
+
+`ops/templates/` has three units:
+
+| File | Purpose |
+|---|---|
+| `n-seo-dashboard.service` | the dashboard, `Restart=always` |
+| `n-seo-daily.service` | one run of `ops/daily.py` |
+| `n-seo-daily.timer` | `OnCalendar=*-*-* 07:00:00`, `Persistent=true` (runs a missed slot on next boot) |
+
+```sh
+mkdir -p ~/.config/systemd/user
+sed "s|__REPO__|$PWD|g" ops/templates/n-seo-dashboard.service > ~/.config/systemd/user/n-seo-dashboard.service
+sed "s|__REPO__|$PWD|g" ops/templates/n-seo-daily.service     > ~/.config/systemd/user/n-seo-daily.service
+cp ops/templates/n-seo-daily.timer ~/.config/systemd/user/
+systemctl --user daemon-reload
+systemctl --user enable --now n-seo-dashboard.service n-seo-daily.timer
+loginctl enable-linger "$USER"     # keep user units running when you are logged out
+```
+
+Check on them with `systemctl --user status n-seo-dashboard` and
+`journalctl --user -u n-seo-daily`.
+
+## Running by hand
+
+```sh
+python3 ops/daily.py                   # everything
+python3 ops/daily.py --list            # the step names
+python3 ops/daily.py --only gsc,ga4    # a subset
+python3 ops/daily.py --skip index-status
+python3 ops/daily.py --no-network-wait
+```
+
+Each run appends to `data/daily-ops.log`, writes `data/last-run.json` (which
+the dashboard shows as the run status chip), and appends a dated entry to
+`docs/daily-log.md`. Re-running on the same day replaces that day's entry
+rather than stacking a second one.
+
+## Logs, in one place
+
+| File | What |
+|---|---|
+| `data/daily-ops.log` | stdout of every daily run, appended |
+| `data/last-run.json` | timestamp, failed step names, per-step timing |
+| `docs/daily-log.md` | the human-readable daily entry (also on `/logs`) |
+| `data/dashboard.log` | dashboard stdout/stderr under launchd |