n-seo 0.1.1 → 0.3.0

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

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

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

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

package/README.md

@@ -1,4 +1,4 @@
-# n-seo
+# n-seo — En Dash SEO
 
 **An SEO, self-hosted.** Website: https://n-seo.dev/ · From the makers of [n-dx](https://n-dx.dev).
 
@@ -6,33 +6,92 @@
 [![CI](https://github.com/en-dash-consulting/n-seo/actions/workflows/ci.yml/badge.svg)](https://github.com/en-dash-consulting/n-seo/actions/workflows/ci.yml)
 [![license](https://img.shields.io/npm/l/n-seo)](LICENSE)
 
-A local-first control plane for growing organic traffic to your own sites —
-classic search (SEO), answer engines (AEO) and AI assistants that cite sources
-(GEO) — without paying an agency to read Search Console for you.
+An agentic, local-first control plane for growing organic traffic to your own
+sites — classic search (SEO), answer engines (AEO) and AI assistants that cite
+sources (GEO) — without paying an agency to read Search Console for you.
 
 It pulls Search Console and GA4 into local JSON, probes your live sites for the
 things that quietly break (robots, sitemap, soft 404s, blocked AI crawlers,
 JS-only shells), and turns all of it into a **ranked queue of concrete actions**:
 which page to retitle, which query to answer, which page never got crawled.
-It runs on hardware you control, on a schedule, and shows you the result on a dashboard.
-
-- **Your data stays on your own hardware.** Nothing is sent anywhere except the
-  Google APIs you authorize and, optionally, a local LLM command you choose.
-- **It briefs you; it never posts for you.** Community modules find threads
-  and write a briefing. The words are always yours.
-- **It proposes; you ship.** No module edits your site. The queue tells you
-  what to change and why, with the numbers; you make the change in your own
-  repo and the next day's data tells you whether it worked.
+That part is plain deterministic code. Everything that needs judgment is handed
+to **a model you choose**, and everything that changes a site is handed to you.
+
+- **Your model, whichever you pick.** Point the `llm` module at any CLI that
+  reads a prompt on stdin (`claude -p`, `ollama run`, a shell script) or at an
+  HTTP endpoint — Anthropic, or anything OpenAI-compatible. It writes the
+  proposals, the verdicts on shipped work, and the community briefings. No key
+  ships with n-seo. Leave it off and you still get the full data-derived queue.
+- **Your coding agent, on the queue.** A read-only MCP server exposes the same
+  data the dashboard reads, so Claude Code — or any MCP client — can answer
+  "what should I do first this week?" and then go implement it. Seven skills
+  are installed into your instance, so setup, triage and shipping are things
+  you ask for in plain language, with the operating rules enforced rather than
+  merely documented.
+- **It proposes; it never acts.** No module edits a site, sends an email or
+  posts a comment. Machine proposals wait in a holding area until you accept
+  them. Your data stays on your hardware: nothing leaves the host except the
+  Google APIs you authorize and the provider you configured yourself.
 
 ![Overview](docs/screenshots/overview.png)
 
 ## Quickstart (5 minutes, no Google setup)
 
+> **n-seo is its own project — do not install it inside a website's repo.**
+> It reads your sites the way Google sees them, through the Search Console and
+> GA4 APIs, so it never needs a copy of their code. `n-seo init` makes one
+> directory of its own and everything it writes stays there.
+
+**✗ Inside a site's repo** — what people do by accident:
+
+```
+~/code/my-website/
+├── .git/
+├── package.json
+├── src/
+└── my-sites/               ← init ran here
+    ├── n-seo.config.json   committed to your website
+    ├── config/backlog.json committed
+    ├── .env                committed
+    └── data/               rewritten every morning,
+                            committed, then deployed
+```
+
+**✓ Beside it** — one instance, watching every site you own:
+
+```
+~/
+├── code/
+│   ├── my-website/         untouched
+│   └── docs-site/          untouched
+└── my-sites/               ← n-seo init my-sites
+    ├── n-seo.config.json   lists both sites
+    ├── config/backlog.json your action queue
+    ├── content/            drafts, campaigns
+    ├── .claude/skills/     ask, don't read docs
+    └── data/               gitignored, regenerable
+```
+
+`n-seo init` refuses the first layout: it stops when the target holds a
+`package.json`, or when the directory it would create falls inside a git
+repository that is not itself an instance, and prints the command you wanted
+instead. `--force` overrides it.
+
+**What it touches.** Your site repos: never — when you ship a fix it is you,
+in your repo, on a branch. Google's APIs: read-only, through a service account
+you create. Its own directory: everything it writes. Delete that directory and
+nothing else on your machine changes.
+
 ```sh
-npm install -g n-seo
-n-seo init my-sites && cd my-sites
-n-seo demo          # a synthetic dataset for example.com
-n-seo start         # dashboard → http://localhost:4600
+npm install -g n-seo   # the engine, once — a CLI, not a dependency
+
+cd ~                   # stand somewhere that is NOT a site repo
+n-seo init my-sites    # creates ./my-sites: config, queue, content,
+cd my-sites            #   .mcp.json and seven skills
+
+n-seo demo             # synthetic data, so every page has something
+n-seo start            # the dashboard, reading this directory
+                       #   → http://localhost:4600
 ```
 
 Open http://localhost:4600. Every page is populated from the demo data, so you
@@ -41,6 +100,29 @@ removes it.
 
 Prefer not to install globally? `npx n-seo init my-sites` works the same way.
 
+### Then talk to it
+
+`n-seo init` installs seven skills into the new directory, so the rest of the
+setup is a conversation rather than a docs crawl. Open it in Claude Code — or
+any agent that reads `.claude/skills/` — and say what you want:
+
+```
+cd my-sites && claude
+
+  "set this up for my sites"        → /n-seo-setup: config, the Google service
+                                      account, both console grants, first run
+  "add learn-pretext.com"           → /n-seo-add-site
+  "what should I work on today?"    → /n-seo-triage: the queue, with evidence
+  "do the first one"                → /n-seo-ship: a branch and a PR in the
+                                      site's own repo, freeze rules enforced
+  "how did last month go?"          → /n-seo-review
+```
+
+A read-only MCP server is registered in the generated `.mcp.json`, so the agent
+reads the same queue and metrics the dashboard shows. It can propose and
+implement; it cannot publish, post, or change a site behind your back. Details
+in [Agentic by design](#agentic-by-design).
+
 <details>
 <summary>Or run it from a clone, if you want to change the engine itself</summary>
 
@@ -52,10 +134,11 @@ npm run demo
 npm start
 ```
 
-In this mode the config, queue and data live inside the checkout. That is the
-right shape for hacking on n-seo; for running it, the instance layout above
-keeps your files separate from the engine so upgrades are a reinstall rather
-than a merge. See [docs/INSTANCE.md](docs/INSTANCE.md).
+In this mode the config, queue and data live inside the checkout — still a
+standalone project of its own, just one you can edit. That is the right shape
+for hacking on n-seo; for running it, the instance layout above keeps your
+files separate from the engine so upgrades are a reinstall rather than a
+merge. See [docs/INSTANCE.md](docs/INSTANCE.md).
 </details>
 
 ## Connect your real sites
@@ -84,6 +167,87 @@ Adding another site later is one entry in the config —
 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).
 
+## Agentic by design
+
+Two things are agentic here, and they are separate. Inside n-seo, the daily run
+hands its findings to a model you configure. Alongside n-seo, your own coding
+agent reads the queue over MCP and does the work.
+
+### Your model, on your findings
+
+The `llm` module is off by default. Turn it on and point it at a provider, and
+the morning run stops being a report:
+
+- **Proposals** — rising queries nothing in the queue covers become concrete
+  cards: the page to write, the section to add, with the numbers cited.
+- **Verdicts** — shipped work is judged against its own success criterion:
+  succeeded, failed, or still cooking.
+- **Briefings** — for each community thread worth joining, the gist, the
+  debate, and where your genuine experience connects.
+
+Reach it two ways, in `n-seo.config.json`:
+
+```jsonc
+// a CLI — anything that reads a prompt on stdin and prints a reply
+"llm": {
+  "enabled": true,
+  "command": "claude -p --model claude-sonnet-5",   // or `llm -m gpt-4o`, `ollama run llama3`, a script
+  "fastCommand": "claude -p --model haiku"          // optional: cheaper, for the high-volume calls
+}
+
+// or an HTTP endpoint — for containers and servers with no CLI signed in
+"llm": {
+  "enabled": true,
+  "http": {
+    "provider": "anthropic",                 // or "openai" for anything OpenAI-compatible
+    "model": "claude-sonnet-5",
+    "fastModel": "claude-haiku-4-5-20251001",
+    "apiKeyEnv": "ANTHROPIC_API_KEY",        // read from the env or .env; no key ships with n-seo
+    "baseUrl": ""                            // optional: a gateway or a local server
+  }
+}
+```
+
+`provider: "openai"` speaks the OpenAI chat-completions shape, so it also covers
+the many gateways and local servers that emulate it. `http` wins when it is
+configured and its key resolves; otherwise the CLI path runs. Proposals land in
+a holding area on `/actions` marked PROPOSED; accepting one into the queue is a
+click a human makes. Nothing that comes back is applied automatically.
+
+### Your coding agent, on the queue
+
+The repo ships an MCP server over the same data the dashboard reads, so an
+agent can answer "what should I do first this week?" from the actual queue
+instead of scraping pages: 16 tools and 3 doc resources, every one annotated
+read-only. `.mcp.json` registers it for Claude Code automatically; Claude
+Desktop, stdio and authenticated HTTP clients are covered in
+[docs/MCP.md](docs/MCP.md). `CLAUDE.md` holds the operating rules an agent
+working here has to follow.
+
+Skills ship for the work itself, so the rules are enforced rather than
+merely documented. `n-seo init` copies all seven into the instance's
+`.claude/skills/` with this install's real paths substituted in, alongside a
+`CLAUDE.md` carrying the operating rules — so an agent opened in that
+directory is oriented before you type anything:
+
+| Skill | Use it when |
+|---|---|
+| `n-seo-setup` | Fresh clone to first real daily run, including Google access |
+| `n-seo-add-site` | Adding a site: property form, `gscHost`, GA4 id, brand regex, grants |
+| `n-seo-triage` | "What should I work on today" from the queue and the last run |
+| `n-seo-ship` | Implement one queue card in the site's repo, then record it as watching |
+| `n-seo-review` | The weekly pass: judge watching items, retire what is done, refresh insights |
+| `n-seo-deploy` | Moving n-seo off the laptop onto an always-on host, on a schedule |
+| `orient` | First thing in a fresh session — get current in a few reads |
+
+`n-seo-ship` stops rather than crossing the 28-day title freeze or the weekly
+metadata budget. The engine checkout carries a second set of skills (`ndx-*`)
+for developing n-seo itself with [n-dx](https://n-dx.dev); those are not
+copied into an instance. `.claude/skills/README.md` explains the split.
+
+Read-only is the point: an agent can reason over your search data all day and
+still cannot bypass the freeze, the batching, or you.
+
 ## What you get
 
 | Page | What it shows |
@@ -122,7 +286,7 @@ on the Settings page or in `n-seo.config.json`.
 | `indexStatus` | Asks the URL Inspection API whether each sitemap URL is indexed | Search Console access | on |
 | `metadataAudit` | Fetches each ranking page's live title/description and scores them against its queries | nothing extra | on |
 | `opportunityScan` | Refreshes trend analysis; flags rising queries no queue item covers | nothing extra | on |
-| `llm` | Runs a local command (default: the `claude` CLI) for scan proposals and digest briefings | any CLI that reads a prompt on stdin | off |
+| `llm` | Hands the run's findings to the model you choose: scan proposals, verdicts on shipped work, community briefings | a provider you configure: any stdin CLI, or an Anthropic / OpenAI-compatible endpoint | off |
 | `hackerNews` | Finds fresh HN threads in your expertise areas and briefs you | your HN username (optional) | off |
 | `reddit` | The same for subreddits | a free Reddit "script" app's credentials in `.env` | off |
 | `indexNow` | Generates a key and pings Bing/Copilot/Yandex with changed URLs | nothing (does nothing for Google) | off |
@@ -130,30 +294,6 @@ on the Settings page or in `n-seo.config.json`.
 | `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 |
 
-## Working with an AI agent
-
-The repo ships an MCP server over the same data the dashboard reads, so an
-agent can answer "what should I do first this week?" from the actual queue
-instead of scraping pages. `.mcp.json` registers it for Claude Code
-automatically; Claude Desktop and HTTP clients are covered in
-[docs/MCP.md](docs/MCP.md). It is read-only by design, and `CLAUDE.md` holds
-the operating rules an agent working here has to follow.
-
-It also ships skills for the work itself, so the rules are enforced rather
-than merely documented:
-
-| Skill | Use it when |
-|---|---|
-| `orient` | First thing in a fresh session — get current in a few reads |
-| `n-seo-setup` | Fresh clone to first real daily run, including Google access |
-| `n-seo-add-site` | Adding a site: property form, `gscHost`, GA4 id, brand regex, grants |
-| `n-seo-triage` | "What should I work on today" from the queue and the last run |
-| `n-seo-ship` | Implement one queue card in the site's repo, then record it as watching |
-| `n-seo-review` | The weekly pass: judge watching items, retire what is done, refresh insights |
-
-`.claude/skills/README.md` explains which skills operate an instance and which
-are contributor tooling for developing the engine with [n-dx](https://n-dx.dev).
-
 ## Working with n-dx
 
 The repo is wired for [n-dx](https://n-dx.dev): `docs/PRD.md` is the product
@@ -198,9 +338,10 @@ accept; community participation is human. The reasoning is in
 
 ## Requirements
 
-Node 20 or newer, Python 3.10 or newer, `curl`, `openssl`. macOS or Linux.
-Python is stdlib-only (no pip); the TypeScript app runs under `tsx` with no
-build step.
+Node 20 or newer, Python 3.10 or newer, and `curl`. macOS, Linux or Windows
+10+, all three exercised by CI on every commit. Python is stdlib-only (no
+pip); the TypeScript app runs under `tsx` with no build step. Nothing needs
+`openssl`, `gcloud` or a compiler.
 
 ## Contributing and license