kaloko 0.17.0 → 0.19.0

package/skills/kaloko/reference/stacks.md

@@ -17,6 +17,15 @@ sorting, thumbnails and CSV export, and each page opens in the lightbox.
   per page, and export the failing ones for the content team.
 - A redesign or migration: walk the old URL list against the new site.
 
+For a weekly SEO and answer-engine monitor of a public site, start with
+`npx kaloko init --seo <site>`: it reads robots.txt and the sitemaps, finds
+the languages and the biggest content families and writes
+`qa/flows/seo-<site>.yml` with one rotating stack per family (`match` per
+language, packs seo and aeo). Read the comment at the top of the file:
+families it paired across languages by size are guesses to check. Then
+`kaloko validate`, `kaloko walk --limit 20`, and
+`kaloko schedule export github`. See help/how-to/seo-monitor.md.
+
 Not for a flow of different screens: those stay separate steps. A stack
 step does not click through anything. It opens each page by URL. Use a
 step script only to prepare each page, for example to dismiss a dialog
@@ -31,10 +40,13 @@ step script only to prepare each page, for example to dismiss a dialog
   purpose: Every article reads well and is findable.
   packs: [seo]                              # health checks of every page (advisory)
   items:
-    sitemap: /sitemap.xml                   # or urls / file / crawl / script (exactly one)
+    sitemap: /sitemap.xml                   # or robots: true / urls / file / crawl / script (exactly one)
     match: '^/clanky/'                      # regex on the path with its query; exclude: '…' drops pages
+                                            # or a map by locale: { default: '^/blog/', fi: '^/fi/blogi/' }
     limit: 800                              # default 500, at most 10000
-    semantic_sample: 20                     # semantic criteria on the first 20 pages only
+    # rotate: week                          # each ISO week the next `limit` pages (run: each run)
+    semantic_sample: 20                     # semantic criteria on 20 pages only
+    # semantic_order: priority              # failing and least recently checked pages first
     # viewports: [desktop]                  # default: the first viewport of the scenario
   fields:                                   # index columns (max 12); default title, h1, words, http
     - { id: title, label: Title, from: title }
@@ -55,12 +67,43 @@ Item sources:
 - `file: qa/data/products.csv` is a list next to the scenario. Accepted
   formats are text with one path per line, CSV (first column), or JSON:
   `["/a"]` or `[{ path, title, key, purpose }]`, where `key` gives a stable id.
-- `sitemap: /sitemap.xml` also follows a sitemap index (up to 50 sitemaps).
+- `sitemap: /sitemap.xml` also follows a sitemap index, two levels deep
+  (up to 50 sitemaps each). Gzipped sitemaps work: a `.gz` URL or gzip
+  bytes behind any URL are unpacked.
+- `sitemap: robots` (or `robots: true`) reads the `Sitemap:` lines of
+  `/robots.txt` on the environment's origin. When their URLs name the
+  walked locale as a segment (`/sitemaps/de/sitemap.xml.gz`,
+  `sitemap-de.xml`; `en_US` finds `en-us`, `en` does not), only that
+  locale's sitemaps are read; otherwise all of them. Use it when a site
+  lists one sitemap per language, so the scenario does not hard-code paths.
 - `crawl: { from: /clanky, links: "a.card", next: "a.next", pages: 20 }`
   collects links from a listing and follows its pagination.
 - `script: qa/steps/items.mjs` uses the default export
-  `({ page, env, locale, url }) => [paths | { path, title, key, purpose }]` for
-  anything else, such as an API or a search.
+  `({ page, env, locale, url, node, params }) => [paths | { path, title, key, purpose }]`
+  for anything else, such as an API or a search. `node` is
+  `{ id, title, lane, lane_title, session }` of the step and `params` is
+  `items.params`, so one script can serve several stacks.
+
+Fix handoff: a script or a JSON list may give each page `edit_url` (the
+page in the CMS, http(s) only) and `content_ref` (its record id for a
+content API). `resolve: steps/resolve.mjs` (default export
+`async (item, { env, locale, node, params, url }) => ({ edit_url, content_ref })`)
+looks them up for the walked pages only, 15 s per page; a page it fails on is walked
+without them and the walk says how many. They show in the page detail
+("Edit in CMS"), the stack CSV, `get_stack_items` and
+`kaloko export findings`.
+
+`match` and `exclude` apply to every source before `limit` (and before
+`rotate`). Either is a regex or a map by locale; the walked locale, then its
+language (`en` for `en_US`), then `default` is used. A `match` map without
+the locale and without `default` is an error.
+
+`rotate: week` (or `rotate: run`) walks a big list in turns: each ISO week
+(or each run) takes the next `limit` pages, wrapping around, so the list is
+covered in `pages ÷ limit` rounds. `run` keeps its count and each page's last
+check in `.cache/stack/` of the output folder, so use `week` on CI with a
+fresh checkout. The stack index gets `rotation` per locale (window, covered,
+never checked) and each page `last_checked` (its previous check, or null).
 
 An item's `purpose` (for example its title and meta description) is what the
 semantic evaluator reads as `screen_purpose` for that page instead of the
@@ -73,11 +116,44 @@ in the wrong language.
 Pages are deduplicated. External URLs are allowed (e.g. an old domain).
 `{locale}` in any source string is replaced by the walked locale. This is
 how one sitemap with every language is split:
-`match: '^/guides/.*lang={locale}'`, or `sitemap: /{locale}/sitemap.xml`.
+`match: '^/guides/.*lang={locale}'`, or `sitemap: /{locale}/sitemap.xml`,
+or `sitemap: /sitemaps/{locale}/sitemap.xml.gz`. One content family per
+stack: the same per-locale sitemap with `match: '/eshop/'` in one step and
+`match: '/(magazin|magazine|revista)/'` in another.
 
 Field sources: `title`, `h1`, `description`, `canonical`, `lang`, `url`,
 `path`, `words` (words in main/article/body), `http` (the navigation
-status), `count:<selector>`, `<selector>` (text) and `<selector>@<attr>`.
+status), `jsonld_types` (the schema.org types of the page's JSON-LD, for
+example `Product, Offer, BreadcrumbList`; `invalid×1` when a block does not
+parse), a meta tag by name (`og:title`, `og:image`, `twitter:card`,
+`meta:robots`), `count:<selector>`, `<selector>` (text) and
+`<selector>@<attr>`.
+
+Structured data is also summarised without a field: every capture records
+`structured_data` (blocks, invalid blocks, types), and `items.json` carries
+`structured_data` per page and, at the top, pages per type, pages without
+structured data and pages with invalid JSON-LD. The `seo` pack checks it
+(HC112 present, HC113 valid); `packs: [aeo]` adds the answer-engine signals
+(HC901–HC905; HC905 `nojs_parity` fetches each page's raw HTML as GPTBot,
+respecting robots.txt, and fails when the title, canonical, H1, JSON-LD or
+most of the text appear only after JavaScript). See
+help/reference/checks-and-packs.md.
+
+With the `seo` pack a stack also compares its pages with each other after the
+walk (HC121–HC126, advisory): shared titles, descriptions and H1s within a
+language, canonicals pointing elsewhere or to error/noindex pages, hreflang
+that the other walked version does not answer, and (sitemap or robots
+sources) listed pages that answer non-200, redirect or say noindex. They are
+health entries of the stack node (`cross_page: true`, `counts` in pages,
+`urls`); `items.json` has them under `cross_page` with the groups, and each
+affected page lists the ids in `cross_fails`. They cannot be adopted.
+`packs: [locale]` (scenarios with `locales`) checks html lang, the own
+hreflang, the text's language and price decimals against the walked locale
+(HC1001–HC1004). `health: { site: true }` on the scenario adds site checks
+once per run (robots.txt, sitemaps, llms.txt, http→https and www redirects;
+HC1101–HC1107, `site.json` in the run, `site` in the manifest). Off the
+`production` environment HC1102 is a warning and HC1103 is skipped;
+`health.site.environments: [production]` runs them there only.
 
 A step `execution.script` still works. It is called with `item` in the
 context, opens `item.url` itself and may call `capture()`. Without a script,
@@ -86,19 +162,28 @@ the walk opens each page and captures it.
 ## Cost and size: choose deliberately
 
 - Deterministic criteria and packs run on every page. They are cheap.
-- Semantic criteria go to the evaluator. On a stack they run only on the
-  first `semantic_sample` pages (default 20). The other pages show the
-  criterion as not evaluated. Raise the sample only when the question
+- Semantic criteria go to the evaluator. On a stack they run only on
+  `semantic_sample` pages (default 20), the first in walk order. With
+  `semantic_order: priority`, or an evaluator budget, pages failing a
+  deterministic acceptance criterion come first, then those never or least
+  recently checked. The other pages show the criterion as not evaluated. `evaluate.budget.calls`
+  caps the calls of a whole evaluation (evaluation.md). Raise the sample only when the question
   really differs between pages, and tell the person what it costs
   (one call per page and viewport).
 - Stacks capture the first screen of each page (fast, small). Set
   `capture: { full_page: true }` when the criteria are about the whole page.
 - Walking takes about 1–2 s per page. For a first look, use
   `kaloko walk --limit 50`. Re-walk chosen pages with
-  `--items clanek-7,clanek-12` (matches the id or the path).
-- A shared run holds at most 20000 files and 300 MB. Each page stores about
-  four files, so a stack of a few thousand first-screen pages fits. Split
-  larger catalogues by section (`match`), one stack per section.
+  `--items clanek-7,clanek-12` (matches the id or the path; picked from
+  every matching page, also outside this week's rotation, and such a
+  partial walk leaves the rotation state alone).
+- A shared run holds at most 20000 files and 300 MB as stored (HTML and JSON
+  travel gzip-compressed, about a tenth of their size on disk). Each page
+  stores about four files, so a stack of a few thousand first-screen pages
+  fits. For SEO crawls where the checks read the page, not the picture, set
+  `capture: { screenshot: thumb }`: only the 640 px thumbnail is kept. Split
+  larger catalogues by section (`match`) or walk a rotating sample
+  (`rotate: week`).
 
 ## Reading the results
 
@@ -118,6 +203,11 @@ the walk opens each page and captures it.
   `get_stack_items {run_id, step, status?, criterion?, query?, offset, limit}`
   lists pages with fields, failing criteria, evidence and screenshot URLs.
   This is the way to hand an agent "fix these 37 articles".
+- `kaloko export findings [--format csv|json] [--locale l] [--step s] [--out file]`
+  writes the fix list of the local run: one row per failing criterion or
+  health check, page and locale, with URL, evidence, `edit_url`,
+  `content_ref` and `recheck` (`kaloko walk --steps s --items <page> --locales l`,
+  which re-walks just that page after the fix).
 
 ## Report