@typeroll/mcp-server 0.45.77 → 0.45.80

package/workspace-templates/workflows/migration.md

@@ -33,3 +33,97 @@ Track import, block reconstruction, separate text/design review, candidate
 publication and domain cutover as separate milestones. Import completion is not
 launch approval. All four text/design combinations use the same block hierarchy
 and URL continuity contract. Planning choices are not migration API fields.
+
+## Repeatable reconstruction and acceptance
+
+Read workflows/design.md and scripts/README.md. First check whether public
+WordPress REST + HTML covers the source; use tr-migrate-wp's access decision
+table before asking for a helper plugin. Inventory both Pages and posts plus
+internal links and known old slugs. A sitemap alone is not complete.
+
+Discard HTML comments before extracting text, resolve relative links against
+the source, and keep an explicit old URL map. Do not redirect deleted content
+to the home page merely to get a 200. Preserve/renew text and design separately.
+Use capture_text.cjs + compare_text.py for preserved text with explicit selectors.
+
+Before every authorized test deployment run check_unsaved.py (Pages and partials).
+Deploy saved content to the agreed protected test host, then run check_url_parity.py,
+check_assets.py and shoot_hosted.cjs. Check whole-card targets with
+card-stacking-check.cjs and inspect actual desktop/mobile screenshots. Record a
+QA round and platform findings. Review on the owner's phone when possible.
+Domain preparation/cutover and production indexing follow their own explicit
+approval scope and the platform's current guided flow; do not bypass readiness.
+Do not request a second approval for a step the owner has already authorized.
+
+
+## Native controls and publication checks
+
+On Core 0.2.103 / MCP 0.45.79 or later, discover the actual block schemas first.
+Use column `content_gap_px`, responsive section `padding_y`, heading-role
+`space_before`/`space_after`, hero focal/fit/text-position fields and image
+`never_upscale` instead of one-off CSS. Responsive block keys start at `mobile`,
+not `base`. For vertical-only spacing, do not reset horizontal padding with CSS
+shorthand. Optional `click_to_load` videos need an explicit poster if desired;
+choose a first-party poster to avoid early provider requests.
+
+`import_sitemap` can include public WordPress REST (`include_wordpress: true`)
+and a bounded crawl (`crawl_pages: 10`). Record truncation and access warnings.
+A `matched_draft` URL is accounted for in the CMS but not ready for launch.
+Resolve `unpublished_targets`, redirect loops/chains and actual deployed parity.
+
+A deploy with working copies returns `unsaved_content`; review the targets.
+Save explicitly or obtain approval to publish saved content only using
+`allow_unsaved: true`. Never silently save somebody else's work.
+
+Keep the bound Organization/Site/Version explicit. A site API key cannot switch
+to another Organization: use an authorized OAuth connection or a separate key.
+Read the schema for target envelopes and pagination; do not guess aliases.
+Page/partial block writes update working copies; check `saved` and use
+`commit_working_copy` with `target: {kind: "page"|"partial", id: "..."}`.
+Page templates save immediately and do not have working copies. REST read envelopes and
+MCP tool text are different layers; `call.py` returns the decoded tool result.
+
+## Design token check
+
+Follow workflows/design.md for palette/font roles and named scales. Run
+`lint_design_tokens` before launch and after major design changes. Review exact
+colour replacements with scripts/typeroll/color_tokens.py; record deliberate
+exceptions in decisions.md. Preserve text independently from design changes.
+
+## Source retirement, analytics and domain preparation
+
+Before old hosting is retired, follow workflows/source-media.md: preserve unused
+and print originals in a private archive with independently verified checksums.
+Only approved web assets enter the CMS. Use ICC-aware conversion for CMYK/TIFF.
+
+Enable Analytics through the authorized Typeroll API/MCP (`update_app` or the
+Organization analytics tools), then read back settings and verify the beacon and
+cookies on the actual artifact. Resolve missing provider scopes through the
+normal approval flow. A separately authorized provider-side setup with a supplied
+beacon token is an alternative, not a way to bypass Organization permissions.
+Never expose a provider API token as a public beacon token.
+
+From Core 0.2.106, saving future hosts does not redirect normal publication.
+Keep using `trigger_deploy` to update and review the current/temporary address.
+Read `next_publication` in `read_publishing_domains` for the destination.
+Shortly before DNS changes, deliberately call `prepare_publishing_domain_change`
+with the current revision. It prepares the last successful public snapshot,
+not later unpublished CMS edits. Review its frozen indexing settings and DNS
+requirements, then approve traffic separately. If another normal publication
+succeeds while the candidate waits, prepare again: an outdated snapshot cannot
+replace newer published content. There is no need to clear saved future hosts.
+To correct candidate indexing, save the intended setting, publish normally, and
+prepare again. Temporary-host protection keeps the review address noindex even
+when the published authored setting permits indexing on the future host.
+Keep MX/SPF and unrelated DNS unchanged; review any validation window and obtain
+the already-defined traffic-switch authorization.
+
+## Owner-supplied facts and photos
+
+Record owner statements, source and confirmation date. Preserve approved copy
+under `text: preserve`; do not silently delete dates/prices or rewrite it into
+"timeless" language. Under `text: renew`, propose removing stale details or using
+recurring-event wording only when a source supports recurrence. Flag uncertain
+facts for review or keep new Pages in draft; missing evidence does not prove that
+an event stopped. Link to the actual organiser when relevant. Upload approved
+photos with SHA-256 verification and review focal points at mobile/desktop widths.

package/workspace-templates/workflows/new-site.md

@@ -15,3 +15,10 @@ Do not publish, change DNS or send messages without explicit approval.
 
 The CMS owns current content and settings. The repository owns the brief, rules,
 decisions and evidence. Load recipes when needed, not the whole manual.
+
+## Design token check
+
+Follow workflows/design.md for palette/font roles and named scales. Run
+`lint_design_tokens` before launch and after major design changes. Review exact
+colour replacements with scripts/typeroll/color_tokens.py; record deliberate
+exceptions in decisions.md. Preserve text independently from design changes.

package/workspace-templates/workflows/source-media.md

@@ -0,0 +1,50 @@
+# Preserve source media before retirement
+
+This is a separate owner-approved archive, not an import of every old file into
+the CMS. Do not delete source files or cancel old hosting as part of this routine.
+
+1. Inventory originals and downloads from the source API/export, including files
+   absent from published pages. Include drafts, private records and historical
+   attachments when authorized. A public sitemap or REST response cannot prove
+   the library is complete. Keep the export under ignored `sources/private/`.
+2. Compare with the new site's references, including templates, partials and
+   retained URLs. Record used, unused and uncertain files. "Unused" is not an
+   instruction to delete. Preserve print originals even when a web derivative exists.
+3. Agree a private archive destination, its owning account, retention and access.
+   Verify account/bucket identity and that public bucket/custom-domain access is
+   disabled. Use the owner's credentials through their secret manager; never put
+   credentials in scripts or manifests. Do not provision or expose a bucket silently.
+4. Copy with bounded concurrency and bounded reads, stream large files and use
+   resumable transfers when supported. Preserve a collision-safe key derived from
+   the full source host/path, not just the filename. Never overwrite a different
+   object merely because the basename matches.
+5. Record source URL, destination key, source ID, byte count, SHA-256, media type,
+   title/alt/caption, copy time and verification state in a private manifest.
+   ETag is not universally MD5 (multipart objects and providers differ). Use a
+   documented checksum API or stream the destination back and compare SHA-256
+   and size. Metadata claiming a hash is not proof of the uploaded bytes.
+6. Resume only verified matches; report every unavailable source and hash conflict.
+   Verify a restore from the archive, including a large file. Keep an independent
+   private copy of the manifest. The owner reviews completeness and grants a
+   separate old-host retirement decision. This archive does not preserve old
+   public URLs by itself: keep URL parity/redirect acceptance separate.
+
+## Prepare print images for the web
+
+Use `scripts/typeroll/prepare_image.py` for a reviewed local TIFF or other original.
+Install Pillow with ImageCms in an isolated environment. It applies EXIF
+orientation, converts through the embedded (or explicitly supplied) ICC profile
+to sRGB, embeds the sRGB profile, strips source EXIF metadata and writes a new
+JPEG. It never changes the original, uploads files or edits a Page.
+
+```sh
+python3 scripts/typeroll/prepare_image.py sources/private/original.tif sources/private/web.jpg
+```
+
+CMYK without the correct profile fails; obtain the actual source profile instead
+of guessing. `--source-profile sources/private/original.icc` supplies it.
+Unprofiled RGB/gray requires an explicit `--assume-srgb` decision. Multi-page,
+animated and transparent images require a separate reviewed workflow. Compare
+colour, subject framing and sharpness visually before upload. Upload through the
+normal integrity-checked media flow and choose alt/caption text independently.
+Store the tool's hash report privately; never commit customer images or archives.