@typeroll/mcp-server 0.21.0 → 0.24.0

package/AGENTS.md

@@ -97,10 +97,14 @@ maps to one HTTP endpoint; the actual logic runs in the customer's portal
   - **Third-party** (origin: 'third_party') — imported from .tcblocks
     packages via `import_block_types`.
 
-  `list_block_types` returns ALL of them in one list, with each entry's
-  full schema (field names, types, defaults). Always call this FIRST
-  before working with blocks — never hardcode block ids or field names,
-  the available set is per-site.
+  `list_block_types` returns ALL of them in one list as a lightweight
+  summary: each entry's id, label, category, container/slot info, origin,
+  and full field schema (names, types, defaults) — but NOT the render-time
+  template/styles/script (omitted so the list stays within token budget as
+  the library grows). Use `read_block_type` for one block's markup, or pass
+  `full:true` to inline it for every block. Always call this FIRST before
+  working with blocks — never hardcode block ids or field names, the
+  available set is per-site.
 
   Block-library specifics worth knowing (template_capabilities_version
   0.15.0):
@@ -154,6 +158,15 @@ maps to one HTTP endpoint; the actual logic runs in the customer's portal
     they merge into the `<section>` element itself. On 0.14.x–0.15.2
     they wrapped the section in a `<div>`, which silently disabled
     full-bleed for that section.
+  - **Shaped section transitions** (since template_capabilities_version
+    0.24.0): `core/section` takes `divider_top` / `divider_bottom`
+    (`none | wave | curve | tilt`). The platform paints the divider in the
+    section's OWN `background` and overlaps the neighbour by 1px, so a
+    cream↔colour transition renders seam-free. **Use this for waves/curves —
+    never hand-roll a divider band in `core/html`** (a separate stacked shape
+    seams against the next section as a sub-pixel hairline in Chrome). Put the
+    divider on the section whose colour should "rise/dip" into the neighbour
+    (usually the lower section's `divider_top`).
   - **`core/html`** is the raw-HTML escape hatch for block-mode pages —
     one `html` field rendered verbatim (then sanitized like HTML-mode
     content). Use it for the genuinely unique thing no block covers.
@@ -226,6 +239,18 @@ goes through the MCP:
 You usually want at least #1 + #2 + a sampling from #3 before
 proposing any design change, so you mirror the conventions in use.
 
+**Source of truth = the live site (the API), by default.** The content and
+structure you read back through the MCP (`read_page`, `read_partial`,
+`read_site_settings`, …) is canonical. Local files in the project folder —
+`sources/*.md` copy drafts, briefs, old exports — are PROPOSALS, not truth:
+treat them as authoritative only when the user explicitly says "use the copy
+in `<file>`". When rebuilding or redesigning, derive copy and structure from
+the live page, not from a local draft, unless told otherwise. And if you edit
+copy directly on the live site, sync it back to the corresponding draft file
+in the same pass — otherwise the two diverge and the next agent inherits stale
+text. (This is a real failure mode: a copy draft that had drifted from the live
+page once sent a whole redesign off the approved wording.)
+
 **Don't have a site yet?** With an org-scoped key you can `create_site
 name="Acme"` — it bootstraps settings + a draft Home page + a published
 header/footer and returns the new site id. Use that id as `site_id`
@@ -554,6 +579,19 @@ After any non-trivial change, call `get_preview_link` and ask the user
 (or your own browser tool) to confirm the result before moving on. One
 HTTP call vs. shipping a broken redesign — always worth it.
 
+**A design review covers appearance AND readability — not just structure.**
+If you have a browser tool, screenshot at desktop (~1440px) and mobile (~390px)
+and actually judge the visuals before telling the user it's done: logo fully
+visible (not cut off by a header's overflow:hidden + overlap margin) + legible +
+brand-compliant against its real background — screenshot the header in page
+context, NOT the logo element in isolation (an element shot renders the full SVG
+and hides layout clipping); a light/yellow wordmark must not sit bare on a light
+surface without its plate. Text contrast on every
+band, no horizontal scroll (`scrollWidth === clientWidth` at 360–390px), no
+mid-word breaks, all images rendered, mobile layout actually collapsed. "Copy
+present + no overflow + images 200" is a structural check, NOT a design review —
+never report a design as perfect/approved off structural metrics alone.
+
 Preview shows DB state (drafts included). Live (`get_site → urls.production`)
 shows the most recent deploy. Branch deploys live at
 `get_version → deploy_url` (`{branch}.{project}.pages.dev`).
@@ -594,7 +632,7 @@ stakeholder review.
 
 | Family       | Tools |
 |---|---|
-| **Skills (playbook)** | `list_skills`, `read_skill` — the bundled `tr-*.md` recipes, advertised at runtime. Call `list_skills` first when a task looks like "build / migrate / redesign a site", then `read_skill name=…`. No API key or site context needed. |
+| **Guide + skills (playbook)** | `read_guide` (returns this whole guide — the bridge for hosted clients that can't read it off disk), `list_skills`, `read_skill` — the bundled `tr-*.md` recipes (incl. `tr-responsive` for per-breakpoint layout). Call `list_skills` first when a task looks like "build / migrate / redesign a site", then `read_skill name=…`. No API key or site context needed. |
 | **Discovery** | `get_site`, `create_site` (org-scoped key only — see below), `update_site`, `list_versions`, `read_site_settings` |
 | **Pages — reads** | `list_pages`, `read_page`, `batch_read_pages` |
 | **Pages — writes** | `create_page`, `update_page`, `replace_page`, `batch_update_pages`, `delete_page`, `clone_page` |

package/README.md

@@ -99,14 +99,16 @@ which tool.
 Around 50 tools across these families. See [AGENTS.md](./AGENTS.md) for
 the full reference + concrete operation recipes.
 
-- **Skills (self-describing playbook)** — `list_skills` and
-  `read_skill`. The server advertises its own bundled recipes at runtime,
-  so an agent discovers the platform's playbook (`tr-new-site`,
-  `tr-migrate-wp`, `tr-brand`, …) on connection without any files copied
-  locally. Call `list_skills` early when the user wants to build /
-  migrate / redesign a site, then `read_skill name=tr-new-site` for the
-  full markdown. Pure local reads — no API key or site context needed, so
-  they work identically on the hosted connector and over stdio.
+- **Skills + guide (self-describing playbook)** — `read_guide`,
+  `list_skills`, `read_skill`. The server advertises its own operating
+  guide AND bundled recipes at runtime, so an agent gets the full context
+  on connection without any files copied locally. `read_guide` returns the
+  whole AGENTS.md briefing (data model, conventions, safety, tool families)
+  — the bridge for the hosted connector, which can't read the file off
+  disk. `list_skills` then surfaces the task recipes (`tr-new-site`,
+  `tr-migrate-wp`, `tr-brand`, `tr-responsive`, …); `read_skill name=…`
+  loads one. All pure local reads — no API key or site context — so they
+  work identically on the hosted connector and over stdio.
 - **Discovery** — `get_site`, `create_site` (bootstrap a new site — org-scoped
   key only), `update_site` (name/slug/domain), `list_versions`,
   `read_site_settings`, `update_site_settings`.