@typeroll/mcp-server 0.45.20 → 0.45.22

package/skills/tr-migration-evidence.md

@@ -0,0 +1,160 @@
+---
+name: tr-migration-evidence
+description: Source-first design baseline, native capability mapping and evidence gates required before bulk website migration or visual acceptance.
+---
+
+# Migration evidence contract
+
+Use this shared contract with WordPress, Astro, URL and multisite recipes.
+Default to preserving the source appearance and behavior. A redesign requires
+explicit scope. A partly migrated target is not the design reference.
+
+## Gate 1: source baseline, before conversion
+
+Record the authoritative source URL/date, scope, relevant Core version, active
+Page templates and overrides. Inventory home, category/archive, long/short
+articles, downloads, empty related lists and each distinct business surface.
+Capture screenshots and computed geometry at matching actual `innerWidth`
+values (320/390/768/1024/1280/1536 where relevant, plus both sides of actual
+breakpoints). Record loaded font families/weights, color panels, logo/header,
+hero, gutters, article/sidebar widths, card anatomy/grid and footer. Inspect
+loaded images, menus, scrolled TOC, anchor landings and long links.
+Inventory semantic CTA anchors/buttons, downloads and affiliate links before
+copying prose: retain decoded labels, href paths, query parameters, fragments,
+`target` and meaningful `rel` tokens. A source CSS class may identify a CTA
+whose appearance would disappear when copied into prose.
+
+Before removing builder wrappers/classes, preserve the information they carry:
+anchors, lazy/srcset/background images, captions, tables, ordering, downloads,
+embeds and interactions. Content modernization is a separate decision.
+
+## Gate 2: one verified prototype per active recipe, before bulk writes
+
+Call `list_block_types` and `read_block_type` on the deployed runtime. Map each
+source component to exact fields/bindings, defaults, minimum version and expected
+geometry. A registry entry does not prove the capability works. Save and read
+back each prototype, then inspect its preview and an authorized static build.
+
+Example: a 48px heading uses `core/heading.font_size_px: 48` on Core 0.2.25+;
+read the saved block back and measure computed `fontSize` at 1280px. Writing
+`font_size_px` to `core/prose`, which does not declare it, is an unsupported
+mapping even if an API preserves that unknown key. Stop with
+`waiting_for_native_support` when required capability is absent or ignored;
+do not hide the gap with tenant CSS or generic custom blocks.
+
+Validate shared Page references, item order, missing images and empty/unpublished
+references. Keep semantics separate from presentation: category emoji belongs
+to its shared Page field, not copied into every article or card excerpt.
+Validate actual field types, not just key names: number fields use JSON numbers
+(`16`, `1.6`, `1`), not strings (`"16"`, `"1.6"`, `"1"`); booleans use `true`/
+`false`. Check responsive map values too. Read-back retention is not enough:
+measure the resulting font size, line height and paragraph spacing. If an
+incorrect type is accepted but ignored, fix the prototype before bulk writes.
+
+Map standalone CTAs to `core/button` when its declared fields preserve the
+source behavior, rather than leaving class-dependent anchors in prose.
+Core 0.2.25+ `new_tab: true` emits `target="_blank"` and
+`rel="noopener noreferrer"` in static HTML; false/unset keeps the same tab.
+Verify the rendered target/rel, preserved affiliate queries/fragments, keyboard
+activation, actual tab opening and narrow-screen wrapping without requiring
+JavaScript. Do not silently discard source `sponsored`/`nofollow`, download
+behavior or other semantics unsupported by the chosen block: record the gap
+and use a supported composition or stop for native support.
+Do not apply a template to hundreds of Pages until its prototype passes.
+
+## Separate files, addresses and business behavior
+
+Inventory both file bytes and every discovered historical asset URL, including
+PDF/download hrefs, image click targets, srcsets and backgrounds. Verify transfer
+and rendering separately from old-address preservation. Deduplicate by content
+identity, not similar filenames. Preflight expanded redirect artifact bytes and
+provider rule limits. A 200 at an unrelated destination is a failure. A source
+404 is not permission to discard a URL with traffic/backlinks: record a decision.
+Query URLs need explicit routing support at the future host; keeping the old
+server does not preserve them when the same hostname moves.
+
+Classify each CTA: contact form, owned lead workflow, affiliate link, partner
+iframe/script or other runtime. Preserve market, language, destinations and
+attribution. Never clone recipients or partner IDs across markets. Test loading,
+interaction and conversion separately; only use an authorized synthetic mode and
+safe recipient. Unavailable delivery remains UNVERIFIED. No real leads or mail
+to third parties merely to fill a checklist.
+
+## Evidence record (repeat per recipe, viewport and state)
+
+- Source URL/date and target URL; Page/template IDs; exact publication ID.
+- Runtime/Core version and saved content/config revision.
+- Actual viewport `innerWidth` and height; scroll/menu/anchor state.
+- Source and target screenshot paths; measured expected and actual geometry.
+- Capability mapping: block type, field, read-back value and computed result.
+- Separate PASS / FAIL / UNVERIFIED for routing, content, visual, assets,
+  keyboard/interaction and delivery; reviewer and timestamp.
+- Visible deviation, specific user benefit, accepted scope and rationale.
+
+Filled examples:
+
+| Observation | Technical result | Visual decision |
+| --- | --- | --- |
+| Source video overflows a 390px viewport; native video fits and shows the entire frame | Width 390px, original aspect preserved; captures reviewed | PASS: deliberate improvement in mobile usability |
+| Source has four cards and turquoise hero at 1280px; target has three plain cards and no color panel | HTTP 200, no overflow, all content is blocks | FAIL: brand/layout lost; those technical facts cannot attest visual fidelity |
+| Heading round-trip retains 48 but computed size stays 32 | Save succeeds | FAIL: find ignored field/cascade before bulk conversion |
+
+Keep imported, saved, locally checked, hosted-preview checked, published and
+traffic-cut-over distinct. Template/theme changes invalidate affected acceptance;
+never attach old evidence to a new publication. `record_migration_seo_acceptance`
+booleans are reviewer attestations, not automated visual proof. Do not set them
+from HTTP status, native-block count or overflow alone. Report a completed
+pre-cutover scope honestly when DNS or integrations remain out of scope.
+
+## Complete census and visual signoff
+
+The initial route census must combine source sitemaps, internal links, archive
+pagination, CMS inventory and known utility routes. Include homepage, archives,
+404/search behavior and routes outside the sitemap where present. Do not invent
+features absent from the source. Assign every route a recipe, template override,
+composition or documented exception. Inventory the whole shell: content outside
+`main`, header, footer, service navigation and archive heroes are not optional.
+
+Derive required evidence from that census. Pair every in-scope source/target route
+at mobile and desktop; add each unique component, breakpoint and interaction
+state. Inspect page-specific media, lists, tables, embeds, CTAs, anchors and related
+content. One representative article cannot attest every article's content.
+
+A coverage row records route, recipe, component, state, actual viewport dimensions,
+source revision, target content/config/Core/publication revision, paired screenshot
+references, reviewer, review time and result. All rows start `UNVERIFIED`.
+Keep independent results for content, links, list cardinality, full membership,
+sequence, appearance, keyboard behavior and delivery. Screenshots must be inspected;
+image diffs and contact sheets assist review and do not prove aesthetics.
+
+For menus capture source and target closed, open and scrolled states, nested groups
+if present, short landscape, focus order, Escape, link activation and breakpoint
+transitions. For TOCs capture top/middle/bottom and anchor landings. Include tabs,
+accordions and empty/loading/error/success states where applicable. Separate mobile
+and desktop menu compositions require separate evidence; shared links may be reused
+but one variant's screenshots do not attest the other.
+
+Report denominators separately: routes/content, paired visual pages, recipes,
+components and states. Missing an archive, open menu, footer or a unique embed leaves
+coverage incomplete even if all captured screenshots pass. Shared block, theme,
+partial or template changes invalidate every dependent row; content changes
+invalidate that route and dependent listings. An old revision cannot approve a new
+one. Source availability failures remain `UNVERIFIED`, not silently excluded.
+
+Visual signoff requires zero uncovered required surfaces and zero unexplained
+regressions. `FAIL` or `UNVERIFIED` blocks that signoff, even when a separately scoped
+technical publication has approval. An intentional deviation needs exact before/
+after evidence, specific user benefit and accepted scope; “cleaner” is not a reason.
+
+Examples from a moving-services migration:
+
+| Surface | Passing evidence | Separate visual result |
+| --- | --- | --- |
+| Mobile menu | Keyboard focus and Escape work | FAIL: header moves, source service group is missing, open-menu composition differs |
+| Category archive | Every destination URL exists | FAIL: source sequence, card anatomy and columns differ |
+| Article body | All text imported | UNVERIFIED: unique embed and footer were never compared |
+
+Do not report “all design checked” from a viewport or recipe sample. Keep source
+link-order comparisons and paired contact sheets with the report. The same contract
+applies to WordPress, URL, Astro and multisite migration; do not create separate,
+weaker checklists for individual import mechanisms.

package/skills/tr-page-template.md

@@ -81,3 +81,36 @@ headings render as H2 without mutating storage. A Page without a template H1 can
 keep one body H1. The layout itself does not inject an additional title.
 `core/field_list` defaults to a 0.7rem row gap, weight-600 labels and values that
 wrap long URLs. Empty rows and entirely empty groups stay hidden.
+
+### Native precision (Core 0.2.25 candidate)
+
+Read current block schemas before relying on new controls. Heading/Page title
+support responsive `font_size_px`, unitless `line_height` and `color`. Sections
+separate full-width background from `max_width_px`, `padding_x` and
+`content_gap_px`; Containers add `max_width_px`, `gap_px`, `padding_x_px` and
+`padding_y_px`. Two columns add `gap_px` and `right_width_px`. Use numeric values
+or `{mobile, tablet, laptop, desktop, wide}` overrides, not CSS strings.
+Breadcrumbs have `padding_before_px`, `padding_after_px`, `divider`; TOC has
+`padding_px`, `radius_px`, `border`, `shadow`, `link_color: neutral` and
+`list_style: chevron`. Keep TOC generated from headings. Icon box adds native
+card dimensions and `whole_card_link`; map real Page URLs rather than freezing
+customer routes in HTML. Site logo accepts `height_px`. The `system` font family
+uses the device stack without a webfont request. Preserve complete images and
+validate actual mobile/desktop output, including scrolled outlines.
+
+Columns `stack_below` accepts the select strings `"721"` (default), `"768"`,
+`"1024"`, `"1280"`. A direct-slot TOC follows the selected stacked boundary: its
+`mobile_display: "hidden"` releases the otherwise empty slot; `"visible"` keeps
+it in flow. Use `"1024"` for full article width below laptop when justified by
+the source comparison. Do not merely hide the TOC with `hidden_on` while leaving
+a reserved two-column track, or duplicate body content for tablet/desktop.
+
+For a sticky site header, use an outer semantic Container (`tag: "header"`,
+`sticky: true`, optional responsive `sticky_top_px`, 0–240) outside main. Keep
+its background opaque and its containing block tall enough; do not create a
+short header wrapper or clip it with ancestor overflow. Sticky is opt-in.
+Container `padding_top_px`/`padding_bottom_px` override `padding_y_px` per side
+and accept responsive maps. Grid/Repeater and repeater aliases expose responsive
+`gap_px` (0–240). Use these fields for exact source spacing rather than empty
+spacers or corrective CSS. TOC active-section feedback includes document scroll
+padding; remove obsolete duplicated tenant header offsets during migration.