n-seo 0.2.0 → 0.3.0

package/docs/PRD.md

@@ -102,6 +102,10 @@ a fresh checkout runs.
 - 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: each coverage state renders with what it means, what to do
+  about it, and whether Request Indexing helps — true only where Google has
+  formed no judgement on the content (unknown, discovered-never-crawled),
+  false where it fetched and declined (soft 404, crawled-not-indexed).
 - 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
@@ -148,7 +152,9 @@ the config with the current values as defaults.
   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.
+- Acceptance: light and dark themes; no external fonts — the one webfont is
+  served from the app's own origin, so the dashboard renders identically on a
+  host with no outbound internet and leaks no request to a font CDN.
 
 ## Feature: Settings page [shipped]
 
@@ -206,14 +212,22 @@ instead of a CLI, with the key read from `.env`.
   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: an instance is a standalone project. `n-seo init` exits 2
+  without writing anything when the target holds an application marker, or
+  when the directory it would create falls inside a git repository that is
+  not an instance; `--force` overrides, re-running on an existing instance
+  succeeds, and in-place mode in the engine checkout is unaffected.
+- Acceptance: `init` installs the seven instance-facing skills and a
+  `CLAUDE.md` with the operating rules, substituting the real engine and
+  instance paths, and leaves the contributor (`ndx-*`) skills behind.
 - 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]
+## Feature: Publish the engine to npm [shipped]
 
 - 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.
+  site, and includes the instance-facing skills.
 
 ## Feature: Scheduled upgrade with gate [planned]
 
@@ -246,6 +260,10 @@ runs doctor.
   promises (local data, evidence first, briefs-not-acts) and the operating
   rules.
 
-## Feature: Custom domain [planned]
+## Feature: Custom domain [shipped]
 
-`www/CNAME` and URL updates once a domain is chosen.
+`www/CNAME` carries n-seo.dev; analytics are guarded on the hostname so a
+fork's Pages deploy never reports into the project's property.
+
+- Acceptance: typography is self-hosted (latin-subset variable woff2 from the
+  page's own origin), so the site makes no third-party request.

package/docs/SCHEDULING.md

@@ -4,6 +4,10 @@ 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.
 
+> Or say *"schedule the morning run"* in the instance directory — the
+> `n-seo-deploy` skill covers scheduling on each platform, and `n-seo-setup`
+> ends here.
+
 ## macOS (launchd)
 
 The install script fills in the templates under `ops/templates/`, copies them

package/docs/SETUP-GOOGLE.md

@@ -7,6 +7,13 @@ account with a JSON key** — a machine identity you add as a read-only user in
 each console. No gcloud install, no browser login, no token that expires when
 your session does.
 
+> **You can have this done for you.** `n-seo init` installed the
+> `n-seo-setup` skill in your instance. Open the directory in Claude Code and
+> say *"set this up for my sites"*: it works through everything below, runs
+> `n-seo doctor` between steps, and stops at each decision that is yours (the
+> Cloud project, the property ids, whether to grant access). This page is the
+> reference behind it, and what to read when something does not fit.
+
 ## 1. Pick a Google Cloud project
 
 Any project works; a dedicated one keeps it tidy. In the

package/ops/demo_data.py

@@ -522,6 +522,12 @@ def main():
     else:
         print("\nnow run: n-seo start   (then open the dashboard)")
         print("remove with: n-seo demo --clean")
+    # The demo answers "what is this"; the next question is always "how do I
+    # point it at my own sites", and the answer is a sentence, not a doc.
+    if (seo_config.INSTANCE / ".claude" / "skills" / "n-seo-setup" / "SKILL.md").exists():
+        print("\nwhen you want it on your own sites, you can just ask:")
+        print(f"  cd {seo_config.INSTANCE} && claude")
+        print('  "set this up for my sites"   → /n-seo-setup')
     return 0
 
 

package/ops/doctor.py

@@ -273,6 +273,15 @@ def main():
     check_dashboard()
     check_modules(cfg)
     print(f"\n{'all good' if not FAILS else f'{FAILS} problem(s) to fix'}")
+    # Most people should not work through the setup docs by hand. If the
+    # skills are installed, say so exactly when it is useful: after a report
+    # that lists things to fix.
+    if FAILS and (seo_config.INSTANCE / ".claude" / "skills" / "n-seo-setup" / "SKILL.md").exists():
+        print(
+            "\nnot sure what to do with these? this instance ships the fixes as skills.\n"
+            f"  cd {seo_config.INSTANCE} && claude\n"
+            '  "set this up for my sites"   → /n-seo-setup works through every item above'
+        )
     return 1 if FAILS else 0
 
 

package/ops/export_static.py

@@ -106,6 +106,11 @@ def main():
             dest.write_text(html, encoding="utf-8")
 
         (out / "styles.css").write_text(fetch("/styles.css"), encoding="utf-8")
+        # styles.css declares @font-face against /fonts/, so the file has to
+        # travel with it or every heading in the mirror falls back silently.
+        fonts = ROOT / "public" / "fonts"
+        if fonts.is_dir():
+            shutil.copytree(fonts, out / "fonts")
         (out / "favicon.svg").write_text(fetch("/favicon.svg"), encoding="utf-8")
         (out / "robots.txt").write_text("User-agent: *\nDisallow: /\n", encoding="utf-8")
     except BaseException:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "n-seo",
-  "version": "0.2.0",
+  "version": "0.3.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)",
@@ -47,6 +47,14 @@
     "public/",
     "n-seo.config.example.json",
     ".env.example",
+    ".claude/skills/orient/",
+    ".claude/skills/n-seo-setup/",
+    ".claude/skills/n-seo-add-site/",
+    ".claude/skills/n-seo-triage/",
+    ".claude/skills/n-seo-ship/",
+    ".claude/skills/n-seo-review/",
+    ".claude/skills/n-seo-deploy/",
+    "!.claude/skills/README.md",
     "docs/",
     "README.md",
     "LICENSE"
@@ -71,7 +79,7 @@
     "docker:up": "docker compose -f docker/compose.yml up -d"
   },
   "dependencies": {
-    "@hono/node-server": "^1.13.7",
+    "@hono/node-server": "^2.1.1",
     "@modelcontextprotocol/sdk": "^1.30.0",
     "hono": "^4.6.14",
     "tsx": "^4.19.2",

package/public/fonts/OFL.txt

@@ -0,0 +1,105 @@
+The two fonts in this directory are used under the SIL Open Font License 1.1.
+The full license text follows. Both are redistributed unmodified, as the
+latin-subset variable woff2 files Google Fonts serves.
+
+  montserrat-latin-var.woff2
+    Copyright 2024 The Montserrat Project Authors
+    https://github.com/JulietaUla/Montserrat
+
+  merriweather-latin-var.woff2
+    Copyright 2020 The Merriweather Project Authors, with Reserved Font Name
+    "Merriweather". https://github.com/EbenSorkin/Merriweather4
+
+--------------------------------------------------------------------------
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+https://openfontlicense.org
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded, 
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.

package/public/styles.css

@@ -62,6 +62,19 @@
   }
 }
 
+/* Montserrat, self-hosted: one variable file, latin subset, from this origin.
+   Headings and the brand mark only — the tables, chips and numbers stay on the
+   system UI font, which is what a dense data view is designed around. The
+   fallback stack is what renders if the file is missing, so nothing breaks. */
+@font-face {
+  font-family: "Montserrat";
+  src: url("/fonts/montserrat-latin-var.woff2") format("woff2-variations"),
+       url("/fonts/montserrat-latin-var.woff2") format("woff2");
+  font-weight: 100 900;
+  font-style: normal;
+  font-display: swap;
+}
+
 * { box-sizing: border-box; }
 body {
   margin: 0;
@@ -72,7 +85,7 @@ body {
   line-height: 1.55;
 }
 main { max-width: 1480px; margin: 0 auto; padding: 28px 24px 80px; }
-h1, h2, h3 { line-height: 1.2; letter-spacing: -0.01em; }
+h1, h2, h3 { font-family: "Montserrat", system-ui, -apple-system, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif; line-height: 1.2; letter-spacing: -0.01em; }
 h1 { font-size: 1.8rem; font-weight: 800; margin: 0.5em 0; }
 h2 { font-size: 1.05rem; font-weight: 700; margin: 2em 0 0.6em; text-transform: uppercase; letter-spacing: 0.06em; }
 h2 small { font-weight: 500; color: var(--muted); font-size: 0.75rem; text-transform: none; letter-spacing: 0; }
@@ -544,6 +557,10 @@ footer { max-width: 1480px; margin: 0 auto; padding: 16px 24px 40px; color: var(
 .idx-help { color: var(--muted); font-size: 0.82rem; margin-left: 8px; }
 .idx-stale { color: var(--muted); font-size: 0.72rem; font-weight: 700; text-transform: uppercase; letter-spacing: 0.04em; }
 .idx-sitemap { margin: -4px 0 8px; font-size: 0.78rem; color: var(--muted); }
+.idx-fix { margin: 6px 0 2px 8px; font-size: 0.8rem; color: var(--muted); line-height: 1.55; max-width: 96ch; }
+.idx-ri { display: inline-block; font-size: 0.68rem; font-weight: 700; text-transform: uppercase; letter-spacing: 0.04em; border-radius: 4px; padding: 1px 6px; margin-right: 4px; white-space: nowrap; }
+.idx-ri.yes { background: var(--good-soft); color: var(--good); }
+.idx-ri.no { background: var(--bad-soft); color: var(--bad); }
 
 /* ---- settings ---- */
 .settings-grid { display: grid; grid-template-columns: repeat(auto-fill, minmax(320px, 1fr)); gap: 12px; }

package/src/server.tsx

@@ -5,7 +5,7 @@ import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/
 import crypto from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
-import { ROOT, PORT, siteByHost, dotEnv } from "./config.js";
+import { ROOT, INSTANCE, PORT, siteByHost, dotEnv } from "./config.js";
 import { draftBySlug, campaignBySlug } from "./data.js";
 import { allActions } from "./actions.js";
 import { acceptProposal, setWatching, retire } from "./backlog.js";
@@ -94,6 +94,20 @@ app.get("/styles.css", (c) => {
   return c.text(css, 200, { "Content-Type": "text/css; charset=utf-8" });
 });
 
+// The one webfont the dashboard uses, served from this origin. Self-hosting
+// keeps the dashboard free of third-party requests — it renders on machines
+// with no outbound internet, and it never tells Google when someone opens it.
+app.get("/fonts/:file", (c) => {
+  const file = c.req.param("file");
+  if (!/^[\w.-]+\.woff2$/.test(file)) return c.notFound();
+  const abs = path.join(ROOT, "public", "fonts", file);
+  if (!fs.existsSync(abs)) return c.notFound();
+  return c.body(fs.readFileSync(abs), 200, {
+    "Content-Type": "font/woff2",
+    "Cache-Control": "public, max-age=31536000, immutable",
+  });
+});
+
 app.get("/favicon.svg", (c) => {
   const svg = fs.readFileSync(path.join(ROOT, "public", "favicon.svg"), "utf8");
   return c.text(svg, 200, { "Content-Type": "image/svg+xml", "Cache-Control": "public, max-age=86400" });
@@ -257,4 +271,11 @@ app.post("/api/backlog/:id/retire", (c) => {
 const HOST = process.env.SEO_HOST ?? "127.0.0.1";
 serve({ fetch: app.fetch, port: PORT, hostname: HOST }, (info) => {
   console.log(`n-seo → http://${HOST === "0.0.0.0" ? "localhost" : HOST}:${info.port}`);
+  // Printed once per start, and only where it is actionable: an instance that
+  // has the skills installed. A running dashboard says nothing about how to
+  // get the next thing done, and most people should be asking rather than
+  // reading.
+  if (fs.existsSync(path.join(INSTANCE, ".claude", "skills", "n-seo-triage", "SKILL.md"))) {
+    console.log(`      ask it: cd ${INSTANCE} && claude → "what should I work on today?"`);
+  }
 });

package/src/views.tsx

@@ -652,13 +652,60 @@ const COVERAGE_ORDER = [
   "Crawled - currently not indexed",
 ];
 
-const COVERAGE_HELP: Record<string, string> = {
-  "URL is unknown to Google": "Not discovered at all — check the sitemap and internal links.",
-  "Discovered - currently not indexed": "Known but never fetched. Request Indexing (manual, in the Search Console UI) moves these.",
-  "Soft 404": "Serves 200 but Google reads it as an error or empty page.",
-  "Crawled - currently not indexed": "Google fetched it and declined — a content/value judgement.",
+/** What each verdict means and — separately — what to actually do about it.
+ *
+ *  These are not the same action, and treating them as one is the common
+ *  mistake. "Request Indexing" only helps where Google has *not yet judged*
+ *  the page: unknown or discovered-never-crawled. Once Google has fetched a
+ *  URL and declined it (soft 404, crawled-not-indexed), another request
+ *  re-runs the same judgement on the same content and spends a slot of a
+ *  quota that is roughly ten URLs a day. Those need a page change first. */
+const COVERAGE_HELP: Record<string, { means: string; fix: string }> = {
+  "URL is unknown to Google": {
+    means: "Not discovered at all — Google has never seen this URL.",
+    fix: "Discovery problem, not a content one: confirm it is in the sitemap Search Console actually read, and link to it from a page that is already indexed. Then request indexing.",
+  },
+  "Discovered - currently not indexed": {
+    means: "Known but never fetched — it is sitting in the crawl queue.",
+    fix: "Request Indexing (manual, in the Search Console UI) is the right move here and usually works within hours. Spend the daily quota on these first.",
+  },
+  "Soft 404": {
+    means: "Google fetched it, got a 200, and read the response as an error or an empty page.",
+    fix: "Do NOT just request indexing — Google already judged this content and would judge it the same way again. Fetch the URL and find the cause: content rendered only in JavaScript (the crawler sees an empty shell), a genuinely thin page, or an error page returning 200 that should return 404 or 410 and leave the sitemap. Fix it, then request indexing.",
+  },
+  "Crawled - currently not indexed": {
+    means: "Google fetched it and declined to index it — a judgement about value.",
+    fix: "Requesting indexing re-submits the same page for the same verdict. Either make it substantially better and more distinct from your other pages, or accept it as not worth indexing and drop it from the sitemap.",
+  },
+  "Page with redirect": {
+    means: "The URL redirects, so the destination is what gets indexed.",
+    fix: "Expected for an old URL. If it is in your sitemap, remove it — sitemaps should list final URLs only.",
+  },
+  "Alternate page with proper canonical tag": {
+    means: "Correctly pointing at a canonical elsewhere. Not a problem.",
+    fix: "No action. Remove it from the sitemap if you want the report clean.",
+  },
+  "Duplicate without user-selected canonical": {
+    means: "Google picked a different URL as canonical because it reads as a duplicate.",
+    fix: "Set an explicit canonical, or differentiate the content. Requesting indexing does not change a duplicate judgement.",
+  },
+  "Blocked by robots.txt": {
+    means: "Crawling is disallowed, so it cannot be indexed.",
+    fix: "Either remove the Disallow rule, or remove the URL from the sitemap — asking for a URL you block is a contradiction.",
+  },
+  "Excluded by 'noindex' tag": {
+    means: "The page asks not to be indexed and Google is obeying.",
+    fix: "If that is intentional, drop it from the sitemap. If not, remove the noindex tag, then request indexing.",
+  },
 };
 
+/** True where re-submitting the URL is a reasonable use of the daily quota:
+ *  Google has not yet formed a verdict on the content. */
+const REQUEST_INDEXING_HELPS = new Set([
+  "URL is unknown to Google",
+  "Discovered - currently not indexed",
+]);
+
 const STALE_DAYS = 90;
 
 /** A verdict is only as current as the crawl behind it. A URL can read as
@@ -760,7 +807,24 @@ export const IndexingPage: FC = () => {
                           <tr class="idx-group">
                             <td colspan={2}>
                               <strong>{header}</strong>{" "}
-                              <span class="idx-help">{COVERAGE_HELP[header] ?? p.detail ?? ""}</span>
+                              <span class="idx-help">{COVERAGE_HELP[header]?.means ?? p.detail ?? ""}</span>
+                              {COVERAGE_HELP[header] && (
+                                <div class="idx-fix">
+                                  <span
+                                    class={`idx-ri ${REQUEST_INDEXING_HELPS.has(header) ? "yes" : "no"}`}
+                                    title={
+                                      REQUEST_INDEXING_HELPS.has(header)
+                                        ? "Google has not judged this content yet — a request moves it"
+                                        : "Google already fetched and judged this page; re-requesting repeats the same verdict and spends quota"
+                                    }
+                                  >
+                                    {REQUEST_INDEXING_HELPS.has(header)
+                                      ? "Request Indexing helps"
+                                      : "Request Indexing will not fix this"}
+                                  </span>{" "}
+                                  {COVERAGE_HELP[header].fix}
+                                </div>
+                              )}
                             </td>
                           </tr>
                         )}