@seoagent-official/seoagent 1.125.0 → 1.127.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@seoagent-official/seoagent",
-  "version": "1.125.0",
+  "version": "1.127.0",
   "description": "The persistent AI SEO agent for Claude Code. Audits, keyword strategy, briefs, articles, real product screenshots from your repo, and the autopilot loop (cloud detects → CLI executes → ack closes) — other SEO tools write the prompt, SEOAgent runs it.",
   "type": "module",
   "bin": {

package/skills/references/inbox.md

@@ -19,7 +19,7 @@
 | `cli_technical_fix` | Open technical-SEO issue (meta, schema, canonical, internal linking, …) to fix in a page's source | Safe/reversible |
 | `cli_new_content` | A content brief with no article written yet — write + publish it | Safe (new content) |
 | `cli_content_update` | An existing page flagged for revision (declining GSC clicks, low CTR, stale/thin) | Reversible |
-| `cli_sitemap_update` | GSC can't fetch a sitemap at `/sitemap.xml` — write/refresh the project's sitemap | Safe |
+| `cli_sitemap_update` | The live sitemap is missing, robots.txt does not point at it, or Google refused it — the file's `reasons` say which | Safe |
 | `cli_ai_files_update` | The AI-readable file layer (OKF bundle + `llms.txt`) is missing, unmanaged, or stale | Safe |
 | `cli_new_landing_page` | High-value keyword (`easy_win`/`competitor_gap`) with no page covering it — write a landing page | Safe (new content) |
 | `cli_draft_ready` | The cloud already wrote a complete article and synced it to `.seoagent/content/<slug>.md` — review and place it | Safe (new content) |
@@ -61,6 +61,7 @@ Start by reading `.seoagent/inbox/README.md` (or `seoagent inbox`) to see the li
 - **Read the full brief** under `.seoagent/` (briefs file or `strategy/` entry matching `brief_slug`) for the outline, word-count target, and internal-link plan.
 - Write the article following the skill's content-production protocol (Phase 4), then publish it where this project's content lives (repo `content/` or the connected CMS — you are the publishing engine). Follow the file's go-ahead step: **Standing approval** → publish, commit, ack; otherwise show the user the draft before publishing (interactive sessions can use the visual review loop — `references/draft-review.md`).
 - **If the action body has a "Screenshots to capture" section** (autopilot flagged this as a SaaS product), follow `references/screenshots.md` — capture real product screenshots from this repo's UI for the relevant sections instead of shipping illustration-only.
+- **Make sure the new URL is in the site's sitemap.** A framework sitemap built from the content directory usually lists it by itself — check that it does; a hand-kept `sitemap.xml` needs the URL added.
 - Acknowledge: `seoagent ack <action_id>` (or `--failed --reason "skipped; off-strategy"`).
 
 ### `cli_content_update-<id>.md`
@@ -77,11 +78,12 @@ Start by reading `.seoagent/inbox/README.md` (or `seoagent inbox`) to see the li
 
 ### `cli_sitemap_update-<id>.md`
 
-- `Read` it. The frontmatter has `action_id` + `sitemap_url`; the body lists the URLs SEOAgent knows (crawled + GSC-discovered — this **includes CMS-hosted blog articles your repo doesn't contain**).
-- **Find how the project serves its sitemap** (framework sitemap like Next.js `app/sitemap.ts` / `next-sitemap` / Astro integration, or a static `public/sitemap.xml`, or none yet). Prefer extending the framework sitemap so it stays current.
-- **Union** the repo's own routes (which the framework sitemap usually covers) with the URL list in the file (which adds off-repo CMS articles), dedup, and ensure the result is served at `sitemap_url`. Show the user the diff, or under **Standing approval** commit it. Deploy if needed — GSC fetches the live URL. See `references/sitemaps.md` for the generator-detection table.
-- **Verify with `seoagent sitemap`** once deployed — it should report 200, no private leakage, and the expected URL count.
-- Acknowledge: `seoagent ack <action_id>` (or `--failed --reason "sitemap already served"`). SEOAgent re-submits the sitemap to GSC on its schedule.
+- `Read` it. The frontmatter has `action_id`, `reasons`, `sitemap_url` and `robots_txt_url`. SEOAgent checked the live site before it queued the file, and Search Console is not needed for it. A file without `reasons` comes from an older server and means `missing`.
+- **`missing`** — no working sitemap at a robots.txt `Sitemap:` line, `/sitemap.xml`, `/sitemap-index.xml` or `/sitemap_index.xml`. Find how the project serves its sitemap (framework sitemap like Next.js `app/sitemap.ts` / `next-sitemap` / Astro integration, or a static `public/sitemap.xml`, or none yet); prefer extending the framework sitemap so it stays current. **Union** the repo's routes with the URL list in the file (it adds off-repo CMS articles), dedup, serve it at `sitemap_url`, and add an absolute `Sitemap:` line to robots.txt. See `references/sitemaps.md` for the generator-detection table.
+- **`robots_line`** — the sitemap works, but robots.txt does not point Google at it: no robots.txt, no absolute `Sitemap:` line (a relative `Sitemap: /sitemap.xml` is ignored), or a line naming a file that is gone. Edit robots.txt's **source** (static file or route) and add `Sitemap: <sitemap_url>`. Add no `Disallow` rules as part of this task.
+- **`google`** — Google refused the sitemap on SEOAgent's nightly submit, or counted errors in it; the file quotes Google's answer. Run `seoagent sitemap --url <sitemap_url>`, fix the sitemap's source, and check every `<loc>` is an absolute URL on this domain that answers 200.
+- Show the user the diff, or under **Standing approval** commit it. Deploy — Google reads the live files — then verify with `seoagent sitemap --url <sitemap_url>`.
+- Acknowledge: `seoagent ack <action_id>` (or `--failed --reason "already correct: ..."`). SEOAgent re-checks the live site every autopilot run and withdraws the task by itself once the problem is gone.
 
 ### `cli_ai_files_update-<id>.md`
 
@@ -99,6 +101,7 @@ Start by reading `.seoagent/inbox/README.md` (or `seoagent inbox`) to see the li
 - Write the article following the content-production protocol (Phase 4 — match the article type's quality rules, add internal links from related cluster pages, etc.). Follow the file's go-ahead step: **Standing approval** → publish, commit, ack; otherwise show the user the draft before publishing (interactive sessions can use the visual review loop — `references/draft-review.md`).
 - **If the action body has a "Screenshots to capture" section** (SaaS product), follow `references/screenshots.md` — a landing page for a SaaS product should lead with a real product screenshot in the hero + feature sections, captured from this repo's UI.
 - Publish where this project's content lives (repo `content/` or the connected CMS). Safe (new content). Without **Standing approval**, confirm the user wants this specific page before committing.
+- **Make sure the new URL is in the site's sitemap** (a framework sitemap usually lists it by itself — check; a hand-kept `sitemap.xml` needs it added).
 - Acknowledge: `seoagent ack <action_id>` (or `--failed --reason "already covered by /existing-page"`).
 
 ### `cli_draft_ready-<id>.md`
@@ -106,8 +109,13 @@ Start by reading `.seoagent/inbox/README.md` (or `seoagent inbox`) to see the li
 - `Read` it. The frontmatter has `action_id`, `article_slug`, `path`, `mode`, and (when drafted from a brief) `brief_slug`. The draft itself is at `.seoagent/<path>`.
 - **Believe the task's own delivery line, not the word count.** It says either "pulled in the same sync that delivered this task" or "**NOT delivered by this sync**". The second means the pull kept your local copy and the cloud draft never reached disk: read the local file, then run the `seoagent sync --force <path>` the task prints to take the cloud version for that one file. Never publish a file whose body is a `Tracked record` pointer stub — that is the tracking placeholder, not the article.
 - **Check `mode:` first.** It is the whole contract:
-  - **`mode: new`** — the slug is free. Review the draft (frontmatter carries title, meta description, status), then place it where this project's content renders: repo-native (mdx_sync) → copy/adapt into the repo's content directory and `seoagent content track` it; CMS → create the entry and track it; cloud-hosted → flip frontmatter `status` to `published` and sync.
+  - **`mode: new`** — the slug is free. Review the draft (frontmatter carries title, meta description, status), then place it where this project's content renders: repo-native (mdx_sync) → copy/adapt into the repo's content directory and `seoagent content track` it; CMS → create the entry and track it; cloud-hosted → flip frontmatter `status` to `published` and sync. Then make sure the new URL is in the site's sitemap.
   - **`mode: revision`** — that slug **already renders live on this site** (`replaces_path` names the file). **Do not place it as a new post and do not overwrite the live file.** `diff` the two, fold in only what is genuinely new or better, and keep the live article's URL, frontmatter and dates. If the draft adds nothing, decline — that is a real answer.
+- **AUTHOR RULE (the byline).** The draft's frontmatter carries `author`, `author_title`, `author_url`, `author_same_as` (and `author_key` once known) only when the site owner set a person author. The task file's **Byline** section has the full rule:
+  - **No `author`:** write no author fields and change no template.
+  - **The repo's posts already show a byline:** use that convention (the same frontmatter key, the same authors file or registry; `author_key` is how this repo already names the author). Add a missing author to the authors file once.
+  - **The posts show no byline:** add one to the post template in the same change: the name linked to `author_url` with `rel="author"`, and the author as a `Person` in the page's Article JSON-LD. Say so in one line of the PR or commit message.
+  - Pass `--author-key <the value the post's author field or authors-file entry uses>` to `content track`, so the next draft already knows it. A `mode: revision` draft keeps the live article's byline.
 - **Match the destination's frontmatter contract, not just the draft's.** The cloud draft carries `title`, `meta_description`, and `status`; the repo's content directory may require fields it does not — an `ogImage`, an `excerpt`, a `date`, a tag list — and may enforce them in CI. Read the content directory's `README`/`_README` and one neighbouring post before writing the file. **Drafts arrive with no images**, so when a hero image is required, produce one in the site's existing style and commit it alongside the post; a draft placed exactly as delivered will otherwise turn the build red.
 - **Renaming the slug is encouraged** when the generated one reads as a full sentence; a short slug is the better URL. When you rename, pass `--supersedes <the-delivered-slug>` to `content track`. That is what tells the cloud it is the SAME article under a new name — without it the cloud keeps the original as an unfinished draft and delivers it to you all over again.
 - **A rename has a second half: the draft's own identity fields.** The delivered frontmatter carries the generated `slug:` (and often a `canonical`/`url`), so copying it verbatim into a file you renamed leaves the old slug behind in the body of the post. Loaders commonly resolve identity as `frontmatter.slug || filename` while the **route** resolves from the filename, so the page renders at the new URL and declares a canonical pointing at the old one — a silent self-canonical to a 404, on the page you just chose to publish. Nothing fails loudly. **Drop `slug:` when the destination derives it from the filename**, or update it to the new slug when the destination reads it; do the same for any `canonical`/`url` field. `--supersedes` fixes the cloud's record of the rename, not the repo's.

package/skills/references/listicle-articles.md

@@ -96,7 +96,7 @@ A listicle's defining schema is **`ItemList`** (in addition to `Article`). For t
   {
     "@type": "Article",
     "headline": "{Title}",
-    "author": { "@type": "Person", "name": "{Author}" },
+    "author": { "@type": "Person", "name": "{author}", "jobTitle": "{author_title}", "url": "{author_url}", "sameAs": {author_same_as} },
     "datePublished": "{ISO date}",
     "dateModified": "{ISO date}",
     "image": "https://{domain}/{hero}",
@@ -114,6 +114,8 @@ A listicle's defining schema is **`ItemList`** (in addition to `Article`). For t
 ]
 ```
 
+**Author:** take it from the draft's frontmatter: `author` → `name`, `author_title` → `jobTitle`, `author_url` → `url`, `author_same_as` → `sameAs`; leave out a key the draft does not have. No `author` in the frontmatter → use the publisher Organization as the `author`. Never invent a person. The byline on the page follows the same fields (see the AUTHOR RULE in `references/inbox.md`).
+
 Use `itemListOrder` `…OrderAscending`/`…OrderDescending` for a true ranking; omit it (or use unordered) for an unranked "best of". See `references/schema-markup.md` for the full JSON-LD rules.
 
 ## Quality rules — a listicle is LIGHTER than a guide/pillar

package/skills/references/long-tail-articles.md

@@ -88,7 +88,7 @@ twitter:
   {
     "@type": "Article",
     "headline": "{Title}",
-    "author": { "@type": "Person", "name": "{Author}" },
+    "author": { "@type": "Person", "name": "{author}", "jobTitle": "{author_title}", "url": "{author_url}", "sameAs": {author_same_as} },
     "datePublished": "{ISO date}",
     "dateModified": "{ISO date}",
     "image": "https://{domain}/{hero}",
@@ -97,6 +97,8 @@ twitter:
 ]
 ```
 
+**Author:** take it from the draft's frontmatter: `author` → `name`, `author_title` → `jobTitle`, `author_url` → `url`, `author_same_as` → `sameAs`; leave out a key the draft does not have. No `author` in the frontmatter → use the publisher Organization as the `author`. Never invent a person. The byline on the page follows the same fields (see the AUTHOR RULE in `references/inbox.md`).
+
 For "how to" long_tails, add `HowTo`:
 ```json
 {

package/skills/references/pillar-articles.md

@@ -94,7 +94,7 @@ Pillars almost always need both `Article` and `FAQPage`:
   {
     "@type": "Article",
     "headline": "{Title}",
-    "author": { "@type": "Person", "name": "{Author Name}" },
+    "author": { "@type": "Person", "name": "{author}", "jobTitle": "{author_title}", "url": "{author_url}", "sameAs": {author_same_as} },
     "datePublished": "{ISO date}",
     "dateModified": "{ISO date}",
     "image": "https://{domain}/{hero-image}",
@@ -113,6 +113,8 @@ Pillars almost always need both `Article` and `FAQPage`:
 ]
 ```
 
+**Author:** take it from the draft's frontmatter: `author` → `name`, `author_title` → `jobTitle`, `author_url` → `url`, `author_same_as` → `sameAs`; leave out a key the draft does not have. No `author` in the frontmatter → use the publisher Organization as the `author`. Never invent a person. The byline on the page follows the same fields (see the AUTHOR RULE in `references/inbox.md`).
+
 If the pillar contains step-by-step processes, also add `HowTo` schema. If it contains a glossary section, add `DefinedTermSet`.
 
 ## After Writing

package/skills/references/publishing.md

@@ -29,7 +29,7 @@ Figure out the destination from the codebase first (you usually already know it
 
 The site renders content from files in this repo (Next.js `content/`, Astro `src/content/`, a `_posts/` dir, MDX routes, a static-site generator, etc.).
 
-- **How you publish:** **Read an existing published article first** to learn the exact location, filename convention, and frontmatter shape this site expects. Then write the article **directly into a new file in that same location** (Phase 4 step 7), matching that frontmatter exactly (their field names, their date format, their tags). Inject internal links + image refs. If a route/sitemap entry is needed and missing, add it. **The repo file is the single source of truth for the body** — do NOT also write a full-body copy into `.seoagent/`.
+- **How you publish:** **Read an existing published article first** to learn the exact location, filename convention, and frontmatter shape this site expects. Then write the article **directly into a new file in that same location** (Phase 4 step 7), matching that frontmatter exactly (their field names, their date format, their tags). Inject internal links + image refs. **Byline:** when the draft's frontmatter has `author`, the post carries it the way this repo's posts carry theirs (their author key or authors file); a template with no byline gets one in the same change (the name linked to `author_url` with `rel="author"`, the author `Person` in the Article JSON-LD). No `author` → no author fields. See the AUTHOR RULE in `references/inbox.md`. If a route/sitemap entry is needed and missing, add it. **The repo file is the single source of truth for the body** — do NOT also write a full-body copy into `.seoagent/`.
 - **Register it so the cloud sees it:** after the repo file is written, run `seoagent content track --slug {slug} --url https://{domain}{blog_path}/{slug} --file {path}` (Phase 4 step 7). That's what makes the article appear on the dashboard — `sync` only walks `.seoagent/`, so a repo-only article is otherwise invisible to the cloud. The track record is a pointer, not a duplicate.
 - **First post / just-converted blog (no existing file to copy):** if the content dir is empty — a brand-new blog, or one you're converting from a DB/headless source per the guardrail above — define a simple frontmatter convention yourself (`title`, `description`, `date`, `tags`, `slug`) and, if the route doesn't yet read from files, scaffold the loader + route to read the content dir (this is the one-time setup task in "After the user picks", tracked with `setup_status: pending` until it deploys).
 - **Ship it the way the repo ships:** open a PR (or commit to a branch) so the user's existing CI/CD deploys it. Never push straight to the default branch without asking.
@@ -39,7 +39,7 @@ The site renders content from files in this repo (Next.js `content/`, Astro `src
 
 The site pulls content from a CMS. You don't need a SEOAgent adapter — **read how the repo already talks to the CMS** (the existing fetch/SDK code, the env var names) and mirror it to *create* a post.
 
-- **How you publish:** find the CMS client/credentials the app already uses (`.env*`, an SDK import, an API base). Map the article (`title`, `slug`, body, meta, canonical, JSON-LD) to that CMS's content model and create the entry — print the exact `curl`/SDK call for the user to run, or, with explicit consent, run it yourself using their existing credentials. Confirm the post is a draft vs. published per the user's preference. The CMS holds the body; **then `seoagent content track --slug {slug} --url {live-url}` so the dashboard tracks it** (the cloud can't see your CMS).
+- **How you publish:** find the CMS client/credentials the app already uses (`.env*`, an SDK import, an API base). Map the article (`title`, `slug`, body, meta, canonical, the `author` byline when the draft has one, JSON-LD) to that CMS's content model and create the entry — print the exact `curl`/SDK call for the user to run, or, with explicit consent, run it yourself using their existing credentials. Confirm the post is a draft vs. published per the user's preference. The CMS holds the body; **then `seoagent content track --slug {slug} --url {live-url}` so the dashboard tracks it** (the cloud can't see your CMS).
 - **Mapping starting points:** Strapi → `POST /api/articles` `{data:{…}}`. Sanity → `client.create({_type:'post',…})`. Contentful → Management API `createEntry`. Webflow → `POST /collections/:id/items`. Shopify → `POST /admin/api/.../articles.json`. Ghost → Admin API `posts.add`. WordPress → `POST /wp-json/wp/v2/posts`. For anything unfamiliar, ask the user once how a post gets created, then store the mapping in `project.md` so future articles are one step.
 - **Best for:** teams with an existing CMS — keep it, just get SEOAgent's content into it.
 

package/skills/references/schema-markup.md

@@ -30,7 +30,9 @@ JSON-LD is the recommended format. Embed in `<script type="application/ld+json">
   "author": {
     "@type": "Person",
     "name": "Jane Doe",
-    "url": "https://example.com/authors/jane"
+    "jobTitle": "Founder, Acme",
+    "url": "https://www.linkedin.com/in/janedoe",
+    "sameAs": ["https://www.linkedin.com/in/janedoe", "https://janedoe.com"]
   },
   "datePublished": "2026-04-27",
   "dateModified": "2026-04-27",
@@ -49,6 +51,8 @@ JSON-LD is the recommended format. Embed in `<script type="application/ld+json">
 
 Required: `headline`, `author`, `datePublished`, `dateModified`, `image`, `publisher.logo`. Missing any of these and Google may reject the rich result.
 
+**The author comes from the article's frontmatter**, never from this example: `author` → `name`, `author_title` → `jobTitle`, `author_url` → `url`, `author_same_as` → `sameAs` (SEOAgent's cloud drafts carry these when the site owner added an author). Leave out a key the article does not have. With no `author`, the `author` is the publisher Organization: never invent a person. The visible byline links the name to the same `author_url` with `rel="author"`.
+
 ### FAQPage (add to articles with FAQ sections)
 
 ```json

package/skills/references/schemas.md

@@ -106,6 +106,12 @@ word_count: 3120
 status: drafted
 created_at: 2026-04-27T10:00:00Z
 brief: tech-seo-guide
+# Byline: present only when the site owner added a person author (cloud drafts carry it).
+author: "Jane Doe"
+author_title: "Founder, Acme"
+author_url: "https://www.linkedin.com/in/janedoe"            # the byline link (profile, else website)
+author_same_as: ["https://www.linkedin.com/in/janedoe", "https://janedoe.com"]
+author_key: "jane-doe"         # optional: how this repo names the author (learned from `content track --author-key`)
 images:
   hero:
     alt: "Diagram of the technical SEO audit flow from crawl to indexation"
@@ -123,6 +129,8 @@ json_ld:
 ---
 ```
 
+**Byline fields** (`author`, `author_title`, `author_url`, `author_same_as`, `author_key`): the cloud writes them into a draft only when the site owner set a person author (Site settings → Authors, or the `site.authors.set` chat tool). No `author` means the site has no author or uses the company name: write no author fields. When you place the article, put the byline where the repo's own posts keep theirs and fill the Article JSON-LD's author `Person` from these fields (the AUTHOR RULE in `references/inbox.md`).
+
 ## Audit output — `.seoagent/audit/latest.md`
 
 ```markdown

package/skills/references/sub-pillar-articles.md

@@ -85,7 +85,7 @@ twitter:
   {
     "@type": "Article",
     "headline": "{Title}",
-    "author": { "@type": "Person", "name": "{Author}" },
+    "author": { "@type": "Person", "name": "{author}", "jobTitle": "{author_title}", "url": "{author_url}", "sameAs": {author_same_as} },
     "datePublished": "{ISO date}",
     "dateModified": "{ISO date}",
     "image": "https://{domain}/{hero}",
@@ -98,6 +98,8 @@ twitter:
 ]
 ```
 
+**Author:** take it from the draft's frontmatter: `author` → `name`, `author_title` → `jobTitle`, `author_url` → `url`, `author_same_as` → `sameAs`; leave out a key the draft does not have. No `author` in the frontmatter → use the publisher Organization as the `author`. Never invent a person. The byline on the page follows the same fields (see the AUTHOR RULE in `references/inbox.md`).
+
 Add `HowTo` schema when the article is an action-oriented step-by-step (title starts with "How to..." or has a numbered checklist as the main content).
 
 ## After Writing