@typeroll/mcp-server 0.45.100 → 0.45.102

package/skills/tr-redesign-branch.md

@@ -79,6 +79,22 @@ Save the response's `id` — pass it as `version=<id>` on every
 subsequent call. Branches default `robots_blocked: true` so a
 half-finished redesign won't be indexed.
 
+### 2a. Launch basics (ask early)
+
+Ask the user for these once, early in the project. Read `read_site_settings` first and ask only for
+what is missing. Each item is optional. Record a skipped item in
+`decisions.md`, so the launch check in the last step holds no surprises.
+
+- **Default share image.** Ask the user to choose or create the image that
+  social networks and chat apps show when a page has no image of its own:
+  upload one (`create_upload_url` or `upload_media_from_url`), pick an existing
+  one (`list_media`), or create one with `tr-imagegen`. Use a 1200×630 px PNG or
+  JPEG and set it as `default_og_image` with `update_site_settings`. Never
+  generate a title card from the page title instead. The user may skip this.
+- **Organization.** The business name, logo and official profile URLs
+  (LinkedIn, Instagram, GitHub and similar). Set `organization` with `same_as`;
+  it becomes the home page's Organization schema.
+
 ### 2b. Write the design spec (REQUIRED — before you build)
 
 Every redesign branch MUST carry a written design spec. Without it the
@@ -249,7 +265,17 @@ link for your own verification:
 Default: review/iterate on the reused DB-live preview; deploy only for the
 compiled output, the published-address checks in step 6, or merge. Wait for an explicit "looks good, ship it."
 
-### 7. Merge + deploy
+### 7. Launch: merge and deploy (required)
+
+A site is not finished until this step has run. Call `read_site_readiness`
+before the production publication and again after it. For every item with the
+status `warning` or `suggestion`, either fix it with the tool its `fix` names,
+or record in `decisions.md` (or the starter's `qa/` folder) why it stays open.
+Tell the user which items remain. A missing default share image is only a
+suggestion; leave it if the user chose to skip it.
+
+The report warns and never blocks a publication. A clean report is not approval
+to publish: publish only when the user has approved it.
 
 Before asking for sign-off, summarise exactly what will land:
 
@@ -261,6 +287,7 @@ Then, once approved (creating and merging branches need site admin
 permission):
 
 ```
+read_site_readiness                       # on the branch, before the merge
 merge_branch version_id="<branch>"        # branch's diffs land on main
 trigger_deploy
 get_deploy_status job_id=<id>             # poll until succeeded
@@ -275,6 +302,13 @@ delete_branch version_id="<branch>"       # tidy up
 (You can also leave the branch around as a record of the redesign;
 disk cost is tiny.)
 
+Run `read_site_readiness` again after the publication. It reads saved content
+and settings, so confirm the rest on the live site: the AI crawler zone check
+needs the site's website host, and a Search Console property verified by DNS
+is not visible to Typeroll. The
+[launch checklist](https://typeroll.com/docs/guides/launch-checklist/)
+explains every item.
+
 ## Pitfalls
 
 - **Forgetting `version=` on writes.** Every call you make on the

package/skills/tr-seo.md

@@ -1,9 +1,9 @@
 ---
 name: tr-seo
-description: Use when the user asks to improve SEO, fix meta tags, add structured data, check page titles, or audit the site's search visibility. Triggers on "SEO", "meta descriptions", "Google ranking", "structured data", "JSON-LD", "sitemap", "sökoptimering", or "hjälp mig synas på Google".
+description: Use before a site's first launch and whenever the user asks to improve SEO, fix titles or meta descriptions, set a share image, add structured data, check the sitemap or robots.txt, control AI crawlers, or audit search visibility. Triggers on "launch", "go live", "SEO", "meta descriptions", "share image", "Google ranking", "structured data", "JSON-LD", "sitemap", "llms.txt", "AI crawlers", "sökoptimering", or "hjälp mig synas på Google".
 ---
 
-# SEO audit and improvements for a Typeroll site
+# SEO and launch basics for a Typeroll site
 
 > **The buffer model (draft writes).** Every content write in this recipe
 > (pages, blocks and partials) lands in an unsaved per-doc
@@ -12,252 +12,276 @@ description: Use when the user asks to improve SEO, fix meta tags, add structure
 > the task itself), or run `commit_working_copy` per doc before any
 > `trigger_deploy`. Preview your drafts with `include_working_copy: true`.
 
+Run this recipe at launch, from the last step of `tr-new-site`, the migration
+recipes and `tr-redesign-branch`, and whenever the user asks about search
+visibility. Start with `read_site_readiness`: it lists what is missing on the
+whole site, with a fix and a guide link per item. Most of what search engines
+and AI agents need, the platform produces on its own; your work is the content
+and the few settings only the owner can decide.
 
 ## What Typeroll handles automatically
 
-- `<html lang>` from site `language` setting (per-page override via `language` field)
-- `<title>` = `page.seo_title || page.title + settings.default_seo_suffix`
-- `<meta name="description">` from `page.seo_description`
-- `<meta name="robots">` from `page.noindex`
-- `<meta property="og:*">` Open Graph tags from seo_title, seo_description, og_image
-- `<link rel="canonical">` from `page.canonical_url` (falls back to the page's own URL)
-- Article schema from `kind: "article"` + `author` + `date_published`
-- Page schema from `kind: "page"` (default)
-- `robots.txt` from `settings.robots_txt`
-- Sanitized HTML that preserves semantic structure
+Every publication produces these without any tool call. Do not recreate them
+by hand, and do not add a second copy through `json_ld`, `scripts_head` or a
+page.
+
+**Head of every page**
+
+- `<html lang>` from the Page `language`, otherwise the site `language`.
+- `<title>`: `seo_title`, otherwise the Page title, plus
+  `default_seo_suffix` unless the Page sets `append_seo_suffix: false`.
+- `<meta name="description">`: `seo_description`, then
+  `default_meta_description`, then the tagline.
+- `<link rel="canonical">`: the resolved route on the publication's origin, or
+  an explicit `canonical_url`.
+- `<meta name="robots">` from `noindex` and `nofollow`, and from the site-wide
+  and version restrictions.
+- Open Graph and Twitter card tags (`og:title`, `og:description`, `og:image`,
+  `twitter:card`, `twitter:site` from `twitter_handle`). Sharing text uses
+  `og_title` and `og_description` when set.
+- Share image chain: `og_image`, then a public Content type field mapped to
+  `image`, then `default_og_image`, then the logo. An SVG, AVIF or TIFF share
+  image from the site's media library is published as a 1200×630 PNG copy,
+  contained on the theme's background colour; the original stays the page
+  image. `og:image:type`, `og:image:width` and `og:image:height` are emitted.
+- hreflang `<link rel="alternate">` for Pages with `alternates`.
+- A Markdown rendition of each indexable Page at `<page path>index.md`,
+  announced with `<link rel="alternate" type="text/markdown">`.
+- The first content images are never lazy and get `fetchpriority="high"`, and
+  a first section's background image is preloaded; later images are lazy.
+  Logos and small icons do not count as the first images.
+
+**Structured data (JSON-LD)**
+
+- `Organization` and `WebSite` on the home page, from `site_name`, `tagline`,
+  `organization`, `logo`, contact and social settings.
+- `Article` for Pages with `kind: "article"`, with dates and `author`.
+- `BreadcrumbList` on every page below the home page, from resolved routes.
+- Content type schema from `schema_type` and `schema_field_map`.
+- `FAQPage` from an Accordion block (`core/accordion`) when every item's title
+  ends with a question mark (`?`, `？`, `؟`) and has an answer. Nothing is
+  added when the Page's `json_ld` or its Content type schema already declares
+  `FAQPage`, so it is never emitted twice.
+
+**Site files**
+
+- `robots.txt`: your `robots_txt` setting, with the sitemap lines added. The
+  `ai_crawler_policy` setting adds the matching AI crawler groups.
+  A duplicate load of a theme font in custom CSS or `scripts_head` is reported
+  by the readiness item `duplicate_fonts`, not removed.
+- `sitemap.xml`: published, indexable Page routes. With more than 45,000
+  URLs it becomes a sitemap index over numbered `sitemap-<n>.xml` files.
+  Pages with `alternates` carry their hreflang entries.
+- `sitemap-images.xml`: the public images of each indexable Page.
+- `llms.txt`: a Markdown map of the site for AI agents, grouped by Content type
+  and language section, with each Page's description and links to the
+  sitemap and `llms-full.txt`.
+- `llms-full.txt`: the Markdown of the indexable Pages in one file, with a size
+  cap.
+- The `Content-Signal` response header, when `ai_crawler_policy` is not
+  `allow_all`.
+
+Noindex and unlisted Pages, drafts and blocked versions are left out of every
+site file.
 
 ## Recipe
 
-### 1. Audit current state
+### 1. Read the site's state
 
 ```
-list_pages status="all"
+read_site_readiness
 read_site_settings
+list_pages status="all"
 ```
 
-For each page, check:
-- Does the rendered title accurately identify the page, including any suffix?
-- Is the description useful, specific and supported by the page's content?
-  Search snippets may be rewritten or truncated; fixed character counts are
-  not acceptance rules and must not cause padding or lost meaning.
-- Is `og_image` set for the homepage and key landing pages?
-- Does the page have exactly one `<h1>`?
-
-### 2. Fix missing meta descriptions
-
-```
-batch_update_pages updates=[
-  {page_id: "home",     patch: {seo_description: "Acme designar rum..."}},
-  {page_id: "om-oss",   patch: {seo_description: "Vi är ett..."}},
-  {page_id: "tjanster", patch: {seo_description: "Våra tjänster..."}}
-]
-```
-
-Guidelines:
-- Use the length needed for a clear, accurate summary; avoid padding
-- Include the most important keyword naturally
-- Make it a compelling reason to click, not a summary of the page's nav
+`read_site_readiness` returns `items` with `id`, `status` (`ok`,
+`suggestion` or `warning`), `message`, `fix` and `guide`. Work through the
+warnings first. It never blocks a publication, and a clean report is not
+approval to publish.
 
-### 3. Fix page titles
+For each important Page, check:
 
-SEO title = what Google shows in search results.
+- Does the title identify the page, including any suffix?
+- Is the description specific and supported by the page's content? Search
+  engines may rewrite or shorten snippets; never pad text to a length.
+- Does the page have exactly one H1?
 
-If `settings.default_seo_suffix` is set (e.g. " — Acme Studio"), every
-page whose `seo_title` is empty will show `title + suffix`. That's usually
-fine for inner pages; set an explicit `seo_title` only when you want
-something different.
+### 2. Launch basics only the owner can decide
 
-```
-update_site_settings {"default_seo_suffix": " — Acme Studio"}
+Read `read_site_settings` first and ask only for what is missing. Each item is
+optional; record a skipped item in `decisions.md`.
 
-# Set the canonical URL style once per site. Existing sites default to `always`.
-update_site_settings {"trailing_slash": "always"}
+- **Default share image.** Ask the user to choose or create the image shown
+  when a page has none of its own: upload one (`create_upload_url` or
+  `upload_media_from_url`), pick one with `list_media`, or create one with
+  `tr-imagegen`. Use 1200×630 px PNG or JPEG. Never generate a title card
+  from the page title instead.
 
-# A page that must keep its exact campaign/title text can opt out.
-update_page {"page_id": "campaign", "patch": {"append_seo_suffix": false}, "save": true}
+  ```
+  update_site_settings default_og_image="<cdn_url>" twitter_handle="@acmestudio"
+  ```
 
-update_page page_id="home" patch={
-  "seo_title": "Acme Studio — Inredningsdesign i Stockholm"
-}
-```
+- **Organization and profiles.** The business name, logo and official profile
+  URLs:
 
-### 3b. URL and article conventions
+  ```
+  update_site_settings organization={"name":"Acme Studio","logo":"<cdn_url>","same_as":["https://www.linkedin.com/company/acme"]}
+  ```
 
-When creating or moving pages:
+- **Site description and icons.** `default_meta_description` for pages without
+  their own description, and `favicon`, `apple_touch_icon` and `icon_192`
+  (see `tr-brand`).
+- **AI crawlers.** `ai_crawler_policy` is `allow_all` (the default, which writes
+  nothing), `no_training` or `block_all`:
 
-- Slugs are lowercase kebab-case: `our-services`, not `Our_Services`.
-- Reflect hierarchy in the address. A team member lives at `/team/jane-doe`
-  (set `path`, or use a content type whose `route_template` adds the
-  prefix), not at `/jane-doe`. Breadcrumbs and their BreadcrumbList schema
-  follow the resolved route.
-- Blog posts and news get `kind: "article"` and an `author`: that emits
-  Article JSON-LD and `og:type=article`. No author means no author in the
-  rich result.
-- Give shared pages, especially articles, their own `og_image`.
+  ```
+  update_site_settings ai_crawler_policy="no_training"
+  ```
 
-### 4. Add Open Graph images
+  `no_training` disallows training-only crawlers such as GPTBot, ClaudeBot,
+  Google-Extended, Applebot-Extended and CCBot, and states
+  `Content-Signal: search=yes, ai-input=yes, ai-train=no`. It never blocks
+  Googlebot, Bingbot or Applebot. On Cloudflare, the zone's own AI bot policy
+  is enforced at the edge and wins over `robots.txt`; blocking Training there
+  can also block Googlebot, Bingbot and Applebot. The readiness item
+  `ai_crawler_zone_conflict` reports a mismatch. Never change the zone's
+  settings yourself: tell the owner what to change.
+- **Pages a business needs.** Privacy policy, contact and a 404 page. Set the
+  privacy page as `cookie_consent.privacy_policy_url` when the cookie banner is
+  on.
 
-Set `og_image` on pages that get shared on social media. If the site has
-a branded hero image, upload it:
+### 3. Titles and descriptions
 
 ```
-upload_media_from_url url="https://..." alt="Acme Studio — Inredningsdesign"
-# → returns cdn_url
+update_site_settings {"default_seo_suffix": " — Acme Studio", "trailing_slash": "always"}
 
 batch_update_pages updates=[
-  {page_id: "home",     patch: {og_image: "<cdn_url>"}},
-  {page_id: "om-oss",   patch: {og_image: "<cdn_url>"}}
+  {page_id: "home",     patch: {seo_title: "Acme Studio — Interior design in Stockholm", seo_description: "Acme designs..."}},
+  {page_id: "about",    patch: {seo_description: "We are..."}}
 ]
 ```
 
-OG image dimensions: 1200×630px ideal. The platform doesn't resize —
-use a correctly-sized source image.
-
-For pages without their own image, set a site-wide fallback and the X/Twitter
-handle (admin permission, as in the portal Settings form):
-
-```
-update_site_settings default_og_image="<cdn_url>" twitter_handle="@acmestudio"
-```
-
-### 5. Add structured data (JSON-LD)
-
-Typeroll auto-generates Article and Page schema, but you can override or
-extend with custom JSON-LD per page. Example: LocalBusiness on the homepage.
-
-The site-wide Organization schema comes from settings — set it once instead of
-repeating it on every page (`null` clears it):
-
-```
-update_site_settings organization={"name":"Acme Studio","logo":"<cdn_url>","same_as":["https://www.linkedin.com/company/acme"]}
-```
-
-**FAQ, recipe and event pages have tools.** They validate the input, build
-the schema.org JSON-LD and merge it into the page's `json_ld` (a node of the
-same type is replaced, anything else is kept). Use them instead of
-hand-writing JSON-LD, and copy the content from what the page visibly shows:
-
-```
-add_faq_schema page_id="faq" items=[
-  {"question": "Do you deliver on weekends?", "answer": "Yes, Saturdays 9–15."}
-]
-add_recipe_schema page_id="kanelbullar" name="Kanelbullar"
-  ingredients=["500 g vetemjöl", "2 tsk kanel"] instructions=["Blanda degen.", "Grädda i 225 °C."]
-  prep_time="PT1H30M" cook_time="PT10M" recipe_yield="24 bullar" image_url="<cdn_url>"
-add_event_schema page_id="sommarkonsert" name="Sommarkonsert"
-  start_date="2026-06-12T19:00:00+02:00" location_name="Stadshuset"
-  location_address="Storgatan 1, Sundsvall" offers_price=250 offers_currency="SEK"
-```
+- Give the home page an explicit `seo_title`, so the suffix does not repeat
+  the site name.
+- A page that must keep its exact title can set `append_seo_suffix: false`.
+- The readiness report flags duplicate titles and descriptions, missing or
+  repeated H1s and descriptions over 160 characters. Fix them in the content;
+  they are warnings, not rules to pad or trim text mechanically.
 
-Rules they enforce: FAQ needs at least one question with an answer; a recipe
-needs a name, ingredients and steps, durations are ISO 8601 (`PT30M`) and
-URLs absolute; an event needs a name and an ISO 8601 `start_date` (include
-the UTC offset), `end_date` not before it, and a price needs
-`offers_currency`. Read the returned `warnings`: a recipe without an image or
-an event without a location is valid but not eligible for Google's rich
-results. Like other content writes they land in the draft — `save: true` or
-`commit_working_copy` when approved.
+### 4. URLs and articles
 
-FAQ markup only belongs on a page that visibly presents those questions and
-answers; Google penalizes FAQ markup for content the page does not show.
-
-For other types write `json_ld` yourself:
-
-```
-update_page page_id="home" patch={
-  "json_ld": "{\"@context\":\"https://schema.org\",\"@type\":\"LocalBusiness\",\"name\":\"Acme Studio\",\"url\":\"https://acme.se\",\"telephone\":\"+46812345\",\"address\":{\"@type\":\"PostalAddress\",\"streetAddress\":\"Drottninggatan 1\",\"addressLocality\":\"Stockholm\",\"postalCode\":\"111 51\",\"addressCountry\":\"SE\"}}"
-}
-```
-
-**Important:** JSON-LD goes in the `json_ld` field as a JSON *string*
-(not a nested object). The renderer injects it inside
-`<script type="application/ld+json">`. To keep several nodes on one page,
-store them as `{"@context":"https://schema.org","@graph":[…]}` — the
-`add_*_schema` tools do this for you. Read the page first: an update
-replaces the whole `json_ld` value.
-
-Common schemas worth adding:
-- Homepage: `LocalBusiness` or `Organization`
-- About: `AboutPage`
-- Contact: `ContactPage`
-- Blog articles: auto-generated from `kind:"article"` + `author`
-- FAQ, recipe and event pages: the `add_*_schema` tools above
-- Products: `Product` with `offers`
-
-**Instead of the `schema_markup` workflow.** That workflow runs the model with
-the Organization's own AI key; on a Site without that access it fails with
-`failure_code: "ai_not_enabled"`. Don't retry it. Do the same work here: read
-each published page, pick the one type it genuinely represents (or none),
-apply the tool or `json_ld` above, and tell the user you did it yourself.
-
-### 6. robots.txt
-
-The default robots.txt allows all crawlers. Update if needed:
-
-```
-update_site_settings {
-  "robots_txt": "User-agent: *\nAllow: /\nSitemap: https://acme.se/sitemap.xml"
-}
-```
-
-Typeroll doesn't generate a sitemap automatically in phase 1. If the
-customer needs one, create a `/sitemap` page with HTML that lists all
-published pages, or write a static `sitemap.xml` as a page with
-`slug: "sitemap.xml"` and HTML-encoded XML (not recommended for large sites).
-
-### 7. Canonical URLs
-
-Set `canonical_url` when a page has a duplicate (e.g. the same content
-accessible via two slugs after a migration):
-
-```
-update_page page_id="tjansterna" patch={
-  "canonical_url": "https://acme.se/tjanster",
-  "noindex": true
-}
-```
-
-### 8. Language settings
+- Slugs are lowercase kebab-case: `our-services`, not `Our_Services`.
+- Reflect hierarchy in the address: a team member lives at `/team/jane-doe`
+  (set `path`, or use a Content type whose route pattern adds the prefix).
+  Breadcrumbs and their schema follow the resolved route.
+- Blog posts and news get `kind: "article"` and an `author`.
+- Give shared pages, especially articles, their own `og_image`.
+- Link every published page from somewhere. The readiness item `orphan_pages`
+  lists pages that no internal link reaches; `check_internal_links` finds
+  broken saved links.
+
+### 5. Structured data beyond the automatic output
+
+Use structured data only for information the page visibly shows.
+
+- **FAQ:** an Accordion block whose item titles are questions ending in a
+  question mark, each with an answer, produces `FAQPage` automatically. For
+  FAQ content in another block, use `add_faq_schema`.
+- **Recipes and events:** `add_recipe_schema` and `add_event_schema` validate
+  the input, build the JSON-LD and merge it into the Page's `json_ld`:
+
+  ```
+  add_recipe_schema page_id="kanelbullar" name="Kanelbullar"
+    ingredients=["500 g flour", "2 tsp cinnamon"] instructions=["Mix the dough.", "Bake at 225 °C."]
+    prep_time="PT1H30M" cook_time="PT10M" recipe_yield="24 buns" image_url="<cdn_url>"
+  add_event_schema page_id="summer-concert" name="Summer concert"
+    start_date="2026-06-12T19:00:00+02:00" location_name="City Hall"
+    location_address="Main Street 1, Sundsvall" offers_price=250 offers_currency="SEK"
+  ```
+
+  Read the returned `warnings`: a recipe without an image or an event without
+  a location is valid but not eligible for rich results.
+- **Products, software and directories:** set the Content type's `schema_type`
+  (for example `Product` or `SoftwareApplication`) and map its fields with
+  `schema_field_map` in `update_content_type`, rather than writing JSON-LD on
+  each Page.
+- **Other types:** write `json_ld` yourself as a JSON string. Keep several
+  nodes in one `{"@context":"https://schema.org","@graph":[…]}`. An update
+  replaces the whole value, so read the Page first.
+
+  ```
+  update_page page_id="home" patch={
+    "json_ld": "{\"@context\":\"https://schema.org\",\"@type\":\"LocalBusiness\",\"name\":\"Acme Studio\",\"url\":\"https://acme.se\"}"
+  }
+  ```
+
+The readiness item `structured_data` reports JSON-LD that is missing required
+properties or has invalid dates or URLs.
+
+**Instead of the `schema_markup` workflow.** That workflow uses the
+Organization's own AI key; without it, it fails with
+`failure_code: "ai_not_enabled"`. Don't retry it. Read each published page,
+choose the one type it represents (or none), apply the tools above, and tell
+the user you did it yourself.
+
+### 6. robots.txt, indexing and canonicals
+
+- `robots_txt` holds custom crawl rules; the sitemap lines are added for you.
+  Use `ai_crawler_policy` for AI crawlers instead of hand-written groups.
+- To keep a page out of search but crawlable, set `noindex: true`. Blocking a
+  path in `robots.txt` stops crawlers from reading that directive.
+- Set `canonical_url` only when a page deliberately points elsewhere, for
+  example a cross-domain duplicate. Don't combine it with `noindex`.
+- `check_site_indexing` reports the robots policy of the actual address,
+  including response headers.
+
+### 7. Languages
 
 ```
 update_site_settings {"language": "sv"}
-```
-
-Per-page override for multilingual content:
-```
 update_page page_id="about-en" patch={"language": "en"}
 ```
 
-### 9. Heading audit
+For several languages on one site, use `language_sections` and Page
+`alternates`; see the multilingual sites guide.
 
-Use `search_pages` to find structural problems:
+### 8. Search Console
 
-```
-search_pages contains="<h1"      # pages that have at least one H1
-```
+Ask the owner to add the site in Google Search Console. A Domain property
+verified with a DNS TXT record covers every address. For a URL-prefix
+property, put Google's verification `<meta>` tag in `scripts_head` (admin
+permission). Then submit `https://<host>/sitemap.xml`. Record the property in
+`brief/seo.md`. After launch, `import_gsc_performance` reads page clicks and
+impressions into the URL inventory.
 
-Then `read_page` on pages that seem to have none or multiple. Fix via
-`update_page patch={html_content: "<corrected HTML>"}`.
+### 9. Publish and check
 
-### 10. Deploy
+With the user's approval:
 
 ```
+read_site_readiness
 trigger_deploy
 get_deploy_status job_id=<id>
+read_site_readiness
 ```
 
+Run the report again after the publication. It reads saved content and
+settings: the AI crawler zone check needs the site's website host, and a Search
+Console property verified by DNS is not visible to Typeroll, so confirm it in
+Search Console. Fix or record every open item, and save the result under the
+starter's `qa/` folder. In the portal, the site's overview page has the same
+report under **Launch readiness → Check readiness**. It runs on request, not
+after every publication.
+
 ## Pitfalls
 
-- **Don't stuff keywords.** Write descriptions for humans. Google ignores
-  `<meta name="keywords">` (not a field in Typeroll anyway).
-- **JSON-LD is a string, not a nested field.** Pass the entire schema as
-  a JSON-encoded string in `json_ld`. The server escapes `</script` before
-  injection.
-- **OG images need absolute URLs.** The `cdn.typeroll.com` URLs are always
-  absolute — use those.
-- **`canonical_url` + `noindex` together.** If you noindex a page AND set
-  canonical, the canonical is redundant (noindexed pages don't pass equity).
-  Use one or the other.
-- **Default suffix on homepage looks odd.** "Acme Studio — Acme Studio"
-  happens when title="Acme Studio" and suffix=" — Acme Studio". Set an
-  explicit `seo_title` for the homepage.
+- **Don't stuff keywords.** Write descriptions for people. Google ignores
+  `<meta name="keywords">`, and Typeroll has no such field.
+- **JSON-LD is a string.** Pass the whole schema as a JSON-encoded string in
+  `json_ld`. The server escapes `</script` before output.
+- **Share images need absolute URLs.** Media library `cdn_url` values are
+  absolute.
+- **FAQ markup must match visible content.** Search engines penalize FAQ
+  markup for questions the page does not show.
+- **A site file you write by hand loses.** Don't create Pages named
+  `sitemap.xml`, `robots.txt` or `llms.txt`; the publication writes them.

package/skills/tr-starter-design.md

@@ -41,6 +41,19 @@ Verify a primary/surface change in a test Version across header, footer, cards,
 menus and buttons, then restore the test settings. Do not republish automatically.
 
 
+## Express the brand through settings, not CSS
+
+Brand colours belong in `colors`, font families in `fonts`, sizes and spacing
+in the design scales, and recurring looks in named Styles. Editors can see and
+change all of these, and every page follows them. Use `custom_css` only for an
+exception recorded in `decisions.md`, and never to load a font a second time,
+restyle all headings or buttons, or set a hero background image. Run
+`lint_design_tokens` and check the readiness items `duplicate_fonts` and
+`custom_css_overrides` in `read_site_readiness` before launch.
+
+The CSS variables below are for those recorded exceptions, HTML-mode pages and
+template markup.
+
 A reference for the *default* design that ships with new Typeroll sites.
 The customer may have replaced it — always inspect the actual header partial
 (`read_partial partial_id="header"`) and an existing page before assuming any

package/workspace-templates/qa/checklist.md

@@ -28,6 +28,22 @@
 - Check publishing readiness and migration launch report. Passing technical
   validation does not prove visual/editorial completeness or grant launch approval.
 
+## Launch
+
+Run this before the first production publication, again after it, and after
+major changes. The report covers the whole site; it warns and never blocks.
+
+- [ ] Run `read_site_readiness` on the confirmed Site and Version.
+- [ ] Fix each `warning` and `suggestion` with the tool its `fix` names, or
+  record in decisions.md why it stays open. A missing default share image is a
+  suggestion; leave it when the owner chose to skip it.
+- [ ] Save the result as qa/launch-readiness.md: date, Site, Version, deployed
+  revision, each open item with its decision, and the next review date.
+- [ ] After publication, run it again. It reads saved content and settings, so
+  confirm in Search Console itself that the property is verified and the
+  sitemap is submitted, and record the date in brief/seo.md.
+- [ ] Keep `get_migration_launch_report` as the separate gate for migrations.
+
 Commands/dependencies/limits: scripts/README.md. Design: workflows/design.md.
 Follow existing owner authorization; test publication, traffic cutover and
 indexing have distinct effects but do not require repeated approval if covered.

package/workspace-templates/workflows/interview.md

@@ -45,15 +45,24 @@ conversation, not a portal wizard or a new API workflow.
    alone must not change the motif. Save design_intent and asset exceptions in
    brief/migration.md, and the direction in brief/brand.md. A fresh design never
    grants permission to rewrite preserved text.
-5. **Content and behavior** — Page types, shared templates, navigation, forms,
-   downloads, integrations and who will edit them. Identify missing capabilities
-   before scaling up. Save to brief/content-model.md. New websites skip migration
-   preservation choices and establish their brand/content brief here.
+5. **Content and behavior** — Which pages does the business need? Offer the
+   usual set as choices: home, about, services or products, pricing, contact,
+   privacy policy and other legal pages, comparisons with alternatives, and
+   articles. Then page types, shared templates, navigation, forms, downloads,
+   integrations and who will edit them. Write the page plan (title, path,
+   purpose, search intent, status) in brief/content-model.md before any design
+   work starts. Identify missing capabilities before scaling up. New websites
+   skip migration preservation choices and establish their brand/content brief here.
 6. **SEO and continuity** — Markets, search intent, useful topics and existing
    valuable URLs. Record evidence separately from hypotheses in brief/seo.md.
    Confirm metadata policy; text preservation cannot be bypassed as "SEO cleanup".
    Every old public URL must remain or redirect meaningfully regardless of the
    two migration choices. Retiring a URL requires a separate agreed exception.
+   Ask for the launch basics, each optional: a default share image (choose an
+   existing one, upload one or create one with tr-imagegen; never a generated
+   title card), the organization's name, logo and official profile URLs, and
+   who can verify the site in Google Search Console. Save them under
+   "Launch basics" in brief/seo.md, including any the owner skips.
 7. **Owner rules and review** — Non-negotiable copy/design constraints, editing
    roles and who approves prototypes, publication, DNS or messages. Save confirmed
    rules to brief/rules.md. Keep technical access separate from user authorization.